Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(cli): add `mso` CLI + agent skills so the web UI is one frontend, not the product

Rahman4e4b0a48d121
diff --git a/CLAUDE.md b/CLAUDE.md
index 1d364182..f5888f59 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -204,6 +204,23 @@ to `resources/` (rr) and drive any project from one manifest:
- Solo-dev: push direct to `main` once `pnpm typecheck` + `pnpm build` are green.
Conventional commits + Claude co-author.
+## CLI (`bin/mso`) — the web UI is only one frontend
+`bin/mso` reaches the same `/api` surface from a shell; `scripts/install.sh` symlinks
+it to `~/.local/bin/mso` and symlinks `claude-skills/*` into `~/.claude/skills/`
+(`/mso`, `/mso-camoufox`, `/mso-apps`, `/mso-list`, `/mso-image-editor`,
+`/mso-browser-list`). `mso -h` lists every verb; `mso api <METHOD> <path> [json]` is
+the escape hatch for anything without a named verb.
+- **Every CLI caller must send `Origin: <base>`.** `proxy.ts` blocks mutating `/api`
+ that cannot prove same-origin; a browser proves it with `Sec-Fetch-Site`, and the
+ documented fallback is an `Origin` whose host matches `Host`. Without it login
+ itself 403s `cross_origin_blocked` — before any device check, so the error looks
+ like an approval problem and is not.
+- One shared CLI device id lives in `~/.mso/cli.device.id` (auto-created, approve
+ once with `mso approve $(cat ~/.mso/cli.device.id)`). `audit.js` and
+ `image-editor.sh` read the same file — do not reintroduce per-script hardcoded ids.
+- Local verbs (`-h`, `approve`, `devices`, `service`, `build`) never log in, so they
+ still work while the service is down.
+
## Local dev
```bash
pnpm install
diff --git a/README.md b/README.md
index f1c256cd..1b601dc4 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,29 @@ curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install
Full production setup, TLS/VPN notes, filesystem roots, updates, and rollback steps live in [docs/INSTALL.md](./docs/INSTALL.md).
+## CLI
+
+The browser UI is one frontend, not the product. The installer also puts `mso` on your
+`PATH`, and it drives the same API:
+
+```bash
+mso -h # every verb
+mso devices # who can log in
+mso approve <deviceId> "my phone"
+mso ls ~/projects # files
+mso exec "df -h" # host shell
+mso stats # cpu / mem / disk
+mso camoufox start # power the anti-detection browser
+mso mapp list # managed apps (hermes, openclaw…)
+mso service restart # systemd
+mso api GET /api/v1/sys/stats # escape hatch — any endpoint
+```
+
+Local verbs (`-h`, `approve`, `devices`, `service`) work even while the service is
+down. If you use [Claude Code](https://claude.com/claude-code), the installer also
+links the agent skills in `claude-skills/` into `~/.claude/skills/` — `/mso`,
+`/mso-camoufox`, `/mso-apps`, `/mso-list`, `/mso-image-editor`, `/mso-browser-list`.
+
## Security warning
An authenticated MSO session can read allowed files and run commands as the user that owns the process. Treat it like SSH in a browser.
diff --git a/bin/mso b/bin/mso
new file mode 100755
index 00000000..d8d7de8d
--- /dev/null
+++ b/bin/mso
@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# mso — drive the whole Manef Shell OS from the shell.
+#
+# mso.rahmanef.com is only ONE frontend. Everything it can do is a call to the
+# same /api/v1 surface, so this CLI reaches every feature without a browser.
+# Auth = signed session cookie (password + approved device), cached in a jar.
+#
+# FILES ls [path] · cat <p> · write <p> <text> · mkdir <p> · rm <p>
+# mv <a> <b> · cp <a> <b> · usage [path] · search <q> [root]
+# HOST exec <cmd…> · stats · ps · cleanup [--run] · health
+# BROWSER camoufox status|start|stop|session
+# APPS apps · mapp list|show <id>|logs <id>|install <id>|update <id>
+# mapp backups <id>|jobs <id>
+# TERMINAL term open [cwd] · term input <id> <text> · term close <id>
+# AI ai <prompt…> · threads [id] · memory
+# CONFIG config · prefs · models · skills
+# DEVICES devices · approve <id> [label] · revoke <id> (local, no login)
+# whoami · login (this CLI's own device id + session)
+# SERVICE service status|start|stop|restart|logs [n] · build · deploy
+# EDITOR crud list|get|set|del|cmds (see `mso crud`)
+# ESCAPE api <METHOD> <path> [json] — any endpoint, e.g.
+# mso api GET /api/v1/sys/stats
+#
+# READ = OS_FS_READ_ROOTS; WRITE = home + ~/projects; exec = full host power.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"
+B="${MSO_BASE:-${OS_BASE:-http://127.0.0.1:4005}}"
+ENVF="${MSO_ENV:-${OS_ENV:-$ROOT/.env.local}}"
+# shellcheck disable=SC1090
+set -a; . "$ENVF" 2>/dev/null || true; set +a
+
+die() { echo "mso: $*" >&2; exit 1; }
+need() { command -v "$1" >/dev/null || die "missing dependency: $1"; }
+need curl; need jq
+
+# ── local ops (no HTTP, no login) ───────────────────────────────────────────
+dev_script() { node "$ROOT/scripts/approve-device.js" "$@"; }
+
+# ── auth ────────────────────────────────────────────────────────────────────
+PASS="${MSO_PASSWORD:-${OS_PASSWORD:-${OS_LOGIN_PASSWORD:-}}}"
+DEV="${MSO_DEVICE:-${OS_DEVICE:-}}"
+# A stable per-host CLI device id, so `mso approve` only ever has to run once.
+DEVF="${MSO_DEVICE_FILE:-$HOME/.mso/cli.device.id}"
+cli_device() {
+ [ -n "$DEV" ] && { printf '%s' "$DEV"; return; }
+ [ -s "$DEVF" ] || { mkdir -p "$(dirname "$DEVF")"; head -c16 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$DEVF"; chmod 600 "$DEVF"; }
+ cat "$DEVF"
+}
+
+JAR="${MSO_JAR:-${TMPDIR:-/tmp}/mso-$(id -u).jar}"
+
+# proxy.ts blocks mutating /api requests that can't prove same-origin. A browser
+# proves it with Sec-Fetch-Site; the documented fallback for non-browser clients
+# is an Origin whose host matches the Host header — which is exactly what $B is.
+# Sent on every call so `login` works before any session cookie exists.
+ORIGIN=(-H "origin: $B")
+
+login() {
+ local d code; d=$(cli_device)
+ [ -n "$PASS" ] || die "no OS_LOGIN_PASSWORD in $ENVF (or export MSO_PASSWORD)"
+ code=$(curl -sS -o /dev/null -w '%{http_code}' -c "$JAR" -X POST "$B/api/auth/login" \
+ "${ORIGIN[@]}" -H 'content-type: application/json' \
+ -d "$(jq -n --arg p "$PASS" --arg d "$d" '{password:$p,deviceId:$d,deviceLabel:"mso cli"}')" || true)
+ [ "$code" = "200" ] || die "login failed ($code) — approve this CLI device:
+ mso approve $d \"mso cli\""
+}
+# Request with the cached cookie; on 401/403 (expired) log in once and retry.
+# Login is lazy on purpose: `mso -h`, `mso approve` and `mso service …` are
+# local-only and must keep working while the service is down or unapproved.
+req() {
+ local out code body
+ [ -f "$JAR" ] || login
+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)
+ code="${out##*$'\n'}"; body="${out%$'\n'*}"
+ if [ "$code" = "401" ] || [ "$code" = "403" ]; then
+ login
+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)
+ code="${out##*$'\n'}"; body="${out%$'\n'*}"
+ fi
+ case "$code" in 2*) printf '%s' "$body" ;; *) die "request failed ($code): $body" ;; esac
+}
+enc() { jq -rn --arg v "$1" '$v|@uri'; }
+jget() { req "$B$1"; }
+jpost() { req -H 'content-type: application/json' -d "${2:-{\}}" "$B$1"; }
+jdel() { req -X DELETE -H 'content-type: application/json' -d "${2:-{\}}" "$B$1"; }
+# Build a JSON object from k=v pairs (numbers + booleans coerced).
+kv_args() { local j='{}' kv k v; for kv in "$@"; do k="${kv%%=*}"; v="${kv#*=}"
+ if [[ "$v" =~ ^-?[0-9]+([.][0-9]+)?$ || "$v" == "true" || "$v" == "false" ]]; then
+ j=$(jq -c --arg k "$k" --argjson v "$v" '.+{($k):$v}' <<<"$j")
+ else j=$(jq -c --arg k "$k" --arg v "$v" '.+{($k):$v}' <<<"$j"); fi; done; printf '%s' "$j"; }
+
+# Print the header block verbatim — stops at the first non-comment line, so the
+# help can never drift out of sync with the comment above.
+usage() { awk 'NR>1 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "$0"; }
+
+cmd="${1:-help}"; shift || true
+case "$cmd" in
+ # ── files ────────────────────────────────────────────────────────────────
+ ls) jget "/api/v1/fs/list?path=$(enc "${1:-~}")" ;;
+ cat) jget "/api/v1/fs/read?path=$(enc "${1:?path}")" | jq -r . ;;
+ usage) jget "/api/v1/fs/usage?path=$(enc "${1:-~}")" ;;
+ search) jget "/api/v1/fs/search?q=$(enc "${1:?query}")${2:+&root=$(enc "$2")}" ;;
+ write) jpost "/api/v1/fs/write" "$(jq -n --arg p "${1:?path}" --arg c "${2-}" '{path:$p,content:$c}')" ;;
+ mkdir) jpost "/api/v1/fs/mkdir" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;
+ rm) jdel "/api/v1/fs/delete" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;
+ mv) jpost "/api/v1/fs/move" "$(jq -n --arg f "${1:?from}" --arg t "${2:?to}" '{from:$f,to:$t}')" ;;
+ cp) jpost "/api/v1/fs/copy" "$(jq -n --arg f "${1:?from}" --arg t "${2:?to}" '{from:$f,to:$t}')" ;;
+
+ # ── host ─────────────────────────────────────────────────────────────────
+ exec) jpost "/api/v1/exec/run" "$(jq -n --arg c "$*" '{cmd:$c}')" ;;
+ stats) jget "/api/v1/sys/stats" ;;
+ ps) jget "/api/v1/sys/processes" ;;
+ cleanup) if [ "${1-}" = "--run" ]; then jpost "/api/v1/sys/cleanup"; else jget "/api/v1/sys/cleanup"; fi ;;
+ health) jget "/api/auth/me" ;;
+
+ # ── camoufox (the real browser the Browser app drives) ────────────────────
+ camoufox)
+ case "${1:-status}" in
+ status) jget "/api/v1/camoufox/service" ;;
+ start) jpost "/api/v1/camoufox/service" '{"action":"start"}' ;;
+ stop) jpost "/api/v1/camoufox/service" '{"action":"stop"}' ;;
+ session) jget "/api/v1/camoufox/session" ;;
+ *) die "camoufox: status|start|stop|session" ;;
+ esac ;;
+
+ # ── managed apps (hermes, openclaw…) ─────────────────────────────────────
+ apps) jget "/api/v1/apps" ;;
+ mapp)
+ sub="${1:-list}"; shift || true
+ case "$sub" in
+ list) jget "/api/v1/managed-apps" ;;
+ show) jget "/api/v1/managed-apps/$(enc "${1:?id}")" ;;
+ logs) jget "/api/v1/managed-apps/$(enc "${1:?id}")/logs" ;;
+ backups) jget "/api/v1/managed-apps/$(enc "${1:?id}")/backups" ;;
+ jobs) jget "/api/v1/managed-apps/$(enc "${1:?id}")/jobs" ;;
+ install) jpost "/api/v1/managed-apps/$(enc "${1:?id}")/install" "$(kv_args "${@:2}")" ;;
+ update) jpost "/api/v1/managed-apps/$(enc "${1:?id}")/update" "$(kv_args "${@:2}")" ;;
+ *) die "mapp: list|show <id>|logs <id>|backups <id>|jobs <id>|install <id>|update <id>" ;;
+ esac ;;
+
+ # ── terminal ─────────────────────────────────────────────────────────────
+ term)
+ sub="${1:-open}"; shift || true
+ case "$sub" in
+ open) jpost "/api/v1/term/open" "$(jq -n --arg c "${1-}" '{cwd:$c}')" ;;
+ input) jpost "/api/v1/term/input" "$(jq -n --arg i "${1:?id}" --arg d "${2:?text}" '{id:$i,data:$d}')" ;;
+ close) jpost "/api/v1/term/close" "$(jq -n --arg i "${1:?id}" '{id:$i}')" ;;
+ *) die "term: open [cwd]|input <id> <text>|close <id>" ;;
+ esac ;;
+
+ # ── assistant / state ────────────────────────────────────────────────────
+ ai) jpost "/api/assistant" "$(jq -n --arg m "$*" '{messages:[{role:"user",content:$m}]}')" ;;
+ threads) if [ -n "${1-}" ]; then jget "/api/threads?id=$(enc "$1")"; else jget "/api/threads"; fi ;;
+ memory) jget "/api/memory" ;;
+ config) jget "/api/config" ;;
+ prefs) jget "/api/prefs" ;;
+ models) jget "/api/models" ;;
+ skills) jget "/api/skills" ;;
+
+ # ── devices (local file, works even when the service is down) ────────────
+ devices) dev_script --list ;;
+ approve) dev_script "${1:?deviceId}" "${@:2}" ;;
+ revoke) dev_script --revoke "${1:?deviceId}" ;;
+ whoami) echo "cli device: $(cli_device)"; jget "/api/auth/me" ;;
+ login) rm -f "$JAR"; login; echo "logged in as device $(cli_device)" ;;
+
+ # ── service (local systemd) ──────────────────────────────────────────────
+ service)
+ case "${1:-status}" in
+ status) systemctl status --no-pager mso.service ;;
+ start) sudo systemctl start mso.service ;;
+ stop) sudo systemctl stop mso.service ;;
+ restart) sudo systemctl restart mso.service ;;
+ logs) journalctl -u mso.service -n "${2:-50}" --no-pager ;;
+ *) die "service: status|start|stop|restart|logs [n]" ;;
+ esac ;;
+ build) (cd "$ROOT" && npm run build) ;;
+ deploy) (cd "$ROOT" && npm run build) && sudo systemctl restart mso.service && echo "deployed → $B" ;;
+
+ # ── editor-document CRUD (one pattern, all editor features) ──────────────
+ crud)
+ sub="${1:-help}"; shift || true
+ case "$sub" in
+ list) jget "/api/v1/fs/list?path=$(enc "${1:?path}")" ;;
+ get) jget "/api/v1/fs/read?path=$(enc "${1:?path}")" | jq -r . ;;
+ del) jdel "/api/v1/fs/delete" "$(jq -n --arg p "${1:?path}" '{path:$p}')" ;;
+ cmds) jget "/api/v1/editor/exec" | jq -r '.tools[] | " \(.name)\t\(.description)"' ;;
+ set)
+ path="${1:?path}"; shift; op="${1:?command-or-content}"; shift || true
+ if [[ "$op" =~ ^[a-z]+\.[a-zA-Z]+$ ]]; then
+ # Editor-doc command → ONE atomic server op: the route reads the doc
+ # (or seeds it), applies the command, and writes it back in place.
+ a=$(kv_args "$@")
+ resp=$(jpost "/api/v1/editor/exec" "$(jq -n --arg p "$path" --arg n "$op" --argjson a "$a" '{path:$p,commands:[{name:$n,args:$a}]}')")
+ jq -e '.dimsFallback' >/dev/null 2>&1 <<<"$resp" && echo " ! image dims unknown → defaulted (AVIF/HEIC/TIFF not probed)" >&2
+ jq -r '.results[]? | " \(.name) \(if .ok then "ok" else "ERR" end) — \(.result)"' <<<"$resp"
+ else
+ jpost "/api/v1/fs/write" "$(jq -n --arg p "$path" --arg c "$op${*:+ $*}" '{path:$p,content:$c}')"
+ fi ;;
+ *) die "crud: list <dir> | get <path> | set <path> <cmd k=v…|text> | del <path> | cmds" ;;
+ esac ;;
+
+ # ── escape hatch: any endpoint at all ────────────────────────────────────
+ api)
+ m="${1:?METHOD}"; p="${2:?/api/...}"; body="${3-}"
+ if [ -n "$body" ]; then req -X "$m" -H 'content-type: application/json' -d "$body" "$B$p"
+ else req -X "$m" "$B$p"; fi ;;
+
+ help|-h|--help) usage; exit 0 ;;
+ *) usage; exit 1 ;;
+esac
+echo
diff --git a/bin/mso.test.ts b/bin/mso.test.ts
new file mode 100644
index 00000000..4b9845af
--- /dev/null
+++ b/bin/mso.test.ts
@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+// The CLI's dispatch table and its help are the same comment block, so a verb
+// that exists in one and not the other is a real bug. These run WITHOUT a server:
+// help and unknown-command are the two paths that must never need auth, because
+// they are what you reach for when the service is down.
+const CLI = path.join(__dirname, "mso");
+const run = (...args: string[]) =>
+ execFileSync(CLI, args, { encoding: "utf8", env: { ...process.env, MSO_ENV: "/dev/null" } });
+
+describe("bin/mso", () => {
+ it("prints help without logging in", () => {
+ const out = run("-h");
+ expect(out).toContain("drive the whole Manef Shell OS");
+ for (const verb of ["camoufox", "approve", "service", "api", "exec"]) {
+ expect(out).toContain(verb);
+ }
+ });
+
+ it("documents every verb the dispatch table implements", () => {
+ const src = require("node:fs").readFileSync(CLI, "utf8") as string;
+ const body = src.slice(src.indexOf('cmd="${1:-help}"'));
+ // Case arms look like ` ls)` / ` camoufox)` / ` help|-h|--help)`.
+ const verbs = [...body.matchAll(/^ {2}([a-z][a-z-]*)\)/gm)].map((m) => m[1]);
+ expect(verbs.length).toBeGreaterThan(20);
+ const help = run("-h");
+ const undocumented = verbs.filter((v) => v !== "help" && !help.includes(v));
+ expect(undocumented).toEqual([]);
+ });
+
+ it("exits non-zero on an unknown command", () => {
+ expect(() => run("definitely-not-a-verb")).toThrow();
+ });
+});
diff --git a/claude-skills/mso-apps/SKILL.md b/claude-skills/mso-apps/SKILL.md
new file mode 100644
index 00000000..32c4a5f5
--- /dev/null
+++ b/claude-skills/mso-apps/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: mso-apps
+description: Drive ANY mso app from the CLI — one app→function→command matrix for Files, Code Editor, Terminal, System Monitor, Browser, Media Viewer, Media Studio, Reel Editor, Settings, Assistant, App Store. Trigger on /mso-apps, "drive an os app", "os files / terminal / code editor / system monitor / settings from cli", "what os app does X", "operate mso feature".
+---
+
+# /mso-apps — every mso app from the CLI
+
+One reference for operating each app. Everything routes through three transports
+([/mso] owns them): `mso` (host fs/exec/sys + generic `crud`), `browser.sh`
+(real Chromium), `image-editor.sh` (editor-document CRUD). Deep dives:
+[/mso] (control + crud), [/mso-image-editor] (editor docs), [/mso-list] (LIVE audit
+of every function), [/mso-browser-list] (browser internals).
+
+```bash
+OS=mso
+BR=/home/rahman/.claude/skills/mso/browser.sh
+IE=/home/rahman/.claude/skills/mso-image-editor/image-editor.sh
+```
+
+## App → function → CLI
+
+| App | Functions | Drive it with |
+|---|---|---|
+| **Files** | list/open/new/rename/move/copy/delete, usage | `$OS ls\|cat\|write\|mkdir\|mv\|cp\|rm\|usage` · `$OS crud {list,get,set,del}` |
+| **Code Editor** | tree, open, edit, save, new file | `$OS cat <f>` / `$OS write <f> <content>` (or edit directly — this box IS the VPS) |
+| **Terminal** | fs builtins + host shell passthrough | `$OS exec "<cmd>"` · `$OS ps` |
+| **System Monitor** | CPU/mem/disk gauges, process table | `$OS stats` · `$OS ps` (read-only) |
+| **Browser** | navigate, back/fwd/reload, click/type/scroll, read | `$BR go\|back\|reload\|click\|type\|key\|scroll\|content\|shot` |
+| **Media Viewer** | view image/video/audio, download | `$OS cat`/copy → **Read** the image here; `$OS exec "ffprobe <f>"` for AV |
+| **Media Studio** | layers/text/shapes/adjust/style canvas | `$IE …` (it's the image editor) — see [/mso-image-editor] |
+| **Image Editor** | full editor-document CRUD + render | `$IE open\|new\|run\|inspect\|save\|view` · `$OS crud set <doc.json> <cmd>` |
+| **Reel Editor** | timeline/clips/keyframes, render→.webm | asset prep `$OS exec "ffmpeg …"`; timeline + render = browser ([/os-browser]) |
+| **Settings** | devices, AI key (BYOK), server mock/live, theme | `node ~/projects/mso/scripts/approve-device.js <id>`; key → `~/.mso/config.json`; theme/server = UI |
+| **Assistant (Alfa)** | streaming chat + editor tool-calling | `POST /api/assistant` (needs BYOK key); for editing prefer deterministic `$IE`/`crud` |
+| **App Store / Create-App** | install/uninstall, runtime apps | built-ins = `shell.manifest.ts` (+redeploy); runtime cmd app == `$OS exec`; install = UI |
+
+## Notes
+
+- **Generic CRUD** is the spine: `mso crud {list|get|set|del}` works on any host
+ resource; `set <x.doc.json> <editor-cmd>` edits an editor document atomically
+ (one server op). Files/code/terminal/monitor are fully CLI-driven; Studio/Reel
+ **render** in the real app (open in the browser) — there is no headless renderer.
+- **What CRUD reaches (honest scope):** host files + editor docs + `~/.mso/*.json`
+ (config/devices). It does NOT reach browser-local state — theme, server mock/live
+ toggle, window layout, the installed-app registry all live in localStorage
+ (per-browser); set those in the UI. System stats are read-only.
+- **Raster ops are browser-only by design:** brush/paint pixels, layer masks, and
+ background removal need the live editor (no headless canvas). The CLI works at
+ the document level (layers/text/shape/adjust/style/transform); paint there, save,
+ and it round-trips back to the file.
+- **Stateless edits:** each `crud set` is independent — no persistent undo/redo or
+ tool/brush state across calls; selection defaults to the last layer (target any
+ other with `layerName=`/`layerId=`). Keep file backups for "undo".
+- **"Working" = the live probe passes.** Run `node ~/.claude/skills/mso-list/audit.js`
+ for the authoritative per-function pass/fail (this matrix is the map; the audit
+ is the truth). AI features (Alfa, Inspector) need a BYOK Anthropic key.
+- Direct action is often best: this box IS the VPS, so Bash + the native file
+ tools beat round-tripping through `mso` for heavy/local work. Use `mso` to
+ reproduce exactly what an app does or to honour its bounded fs semantics.
diff --git a/claude-skills/mso-browser-list/SKILL.md b/claude-skills/mso-browser-list/SKILL.md
new file mode 100644
index 00000000..5bfe8ecd
--- /dev/null
+++ b/claude-skills/mso-browser-list/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: mso-browser-list
+description: Status of the mso Browser — a REAL headless Chromium (Playwright) on the VPS. List its functions, check the service renders real sites, and how to drive it from CLI. Trigger on /mso-browser-list, "browser functions", "why doesn't the browser work", "check the os browser", "browser status", "test the browser", "screenshot the browser".
+---
+
+# /mso-browser-list — Browser app deep check
+
+The Browser is a **real headless Chromium** (Playwright) running on the host as
+systemd `os-browser` (loopback :4002, persistent context = cookies/cache/session
+on disk). The mso app shows live screenshots + sends clicks/keys; the CLI drives
+the SAME session. Renders ANY site — no X-Frame-Options/CSP problem. Companion to
+[/mso] and [/mso-list].
+
+## 1. Live check (run first)
+
+```bash
+node ~/.claude/skills/mso-browser-list/browser-check.js
+```
+Navigates several sites via the service and reports title + screenshot bytes +
+text length. If the service is DOWN: `sudo systemctl status os-browser`.
+
+## 2. Drive it from CLI (you can SEE the page)
+
+```bash
+SH=/home/rahman/.claude/skills/mso/browser.sh
+$SH go <url> ; $SH shot /tmp/b.png # then Read /tmp/b.png to view
+$SH content ; $SH click X Y ; $SH type "…" ; $SH key Enter ; $SH scroll 600
+```
+
+## 3. Browser functions
+
+| Function | How | Status |
+|---|---|---|
+| Navigate (omnibar) | POST `/api/v1/browser/navigate` → service `goto` | works (any site) |
+| Render | live screenshot `<img>` from `/api/v1/browser/screenshot` | works |
+| Click / type / key / scroll | mouse/keyboard mapped to 1280×800 viewport | works |
+| Back / Forward / Reload | service history | works |
+| Bookmarks / history | localStorage | works |
+| Persistent session/cache | Playwright `launchPersistentContext(~/.mso/chrome-profile)` | works — logins stick |
+| AI Inspector (browser) | url/title + actions + scoped chat | works (chat needs key) |
+| CLI access (screenshot/content/drive) | `browser.sh` + the service API | works |
+
+## 4. Architecture
+
+```
+mso Browser app ──Bearer──▶ /api/v1/browser/* ──secret──▶ 172.18.0.1:4002
+CLI (browser.sh) ──secret──▶ 127.0.0.1:4002 (systemd os-browser)
+ └ Playwright Chromium, 1 persistent context (shared session)
+```
+Env (Dokploy mso): `OS_BROWSER_URL=http://172.18.0.1:4002`, `OS_BROWSER_SECRET`.
+Service secret: `/home/rahman/projects/os-browser/.env`. Code: `…/os-browser/server.mjs`.
+
+## 5. Known limits
+
+- **One shared page** (single context) — the web app + CLI share ONE browser tab.
+ Multi-tab would need multiple pages/contexts (future).
+- Screenshot view is interactive via click-mapping, not native scrolling — use the
+ scroll action. Video/canvas update only on screenshot refresh.
+- Heavy/slow pages: increase the refresh poll if a load is still settling.
+
+## 6. If blank / not working
+
+1. `node ~/.claude/skills/mso-browser-list/browser-check.js` — is the service up + rendering?
+2. Service down → `sudo systemctl restart os-browser` (check chromium/deps).
+3. Web app blank but service OK → `OS_BROWSER_URL`/`OS_BROWSER_SECRET` not set in the
+ Dokploy env, or container can't reach `172.18.0.1:4002` (ufw on docker_gwbridge).
+4. "Establishing session…" → not signed in / token expired.
diff --git a/claude-skills/mso-browser-list/browser-check.js b/claude-skills/mso-browser-list/browser-check.js
new file mode 100644
index 00000000..523da44d
--- /dev/null
+++ b/claude-skills/mso-browser-list/browser-check.js
@@ -0,0 +1,39 @@
+// os-browser-list — checks the REAL browser service (Playwright Chromium, systemd
+// os-browser). Navigates several sites and reports title + screenshot bytes +
+// content length, proving any site renders (no X-Frame-Options problem). Runs on
+// the host (loopback). Usage: node ~/.claude/skills/mso-browser-list/browser-check.js
+const fs = require("fs");
+
+const ENVF = process.env.OS_BROWSER_ENV || "/home/rahman/projects/os-browser/.env";
+const BASE = process.env.OS_BROWSER_BASE || "http://127.0.0.1:4002";
+let SECRET = process.env.OS_BROWSER_SECRET || "";
+try {
+ if (!SECRET) {
+ const m = fs.readFileSync(ENVF, "utf8").match(/^OS_BROWSER_SECRET=(.+)$/m);
+ if (m) SECRET = m[1].trim();
+ }
+} catch {}
+const H = { "x-os-browser-secret": SECRET, "content-type": "application/json" };
+
+const SITES = ["https://example.com", "https://news.ycombinator.com", "https://www.google.com", "https://github.com"];
+
+(async () => {
+ try {
+ const h = await fetch(`${BASE}/health`).then((r) => r.json());
+ console.log(`os-browser service: ${h.ok ? "UP" : "DOWN"} @ ${BASE}\n`);
+ } catch (e) {
+ console.log(`os-browser DOWN @ ${BASE}: ${e.message}\n(sudo systemctl status os-browser)`);
+ process.exit(1);
+ }
+ for (const url of SITES) {
+ try {
+ const nav = await fetch(`${BASE}/navigate`, { method: "POST", headers: H, body: JSON.stringify({ url }) }).then((r) => r.json());
+ const png = await fetch(`${BASE}/screenshot`, { headers: H }).then((r) => r.arrayBuffer());
+ const c = await fetch(`${BASE}/content`, { headers: H }).then((r) => r.json());
+ console.log(`OK "${(nav.title || "").slice(0, 30)}" shot=${png.byteLength}b text=${(c.text || "").length} ${url}`);
+ } catch (e) {
+ console.log(`ERR ${url} ${e.message}`);
+ }
+ }
+ console.log("\nWeb path: /api/v1/browser/* (Convex-auth) → 172.18.0.1:4002. CLI: ~/.claude/skills/mso/browser.sh");
+})();
diff --git a/claude-skills/mso-camoufox/SKILL.md b/claude-skills/mso-camoufox/SKILL.md
new file mode 100644
index 00000000..0eebb936
--- /dev/null
+++ b/claude-skills/mso-camoufox/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: mso-camoufox
+description: Drive the Camoufox anti-detection browser that MSO hosts — power the VNC session on/off, get the noVNC URL and one-time password, restore/snapshot the logged-in profile, and reach sites that block headless automation. Trigger on /mso-camoufox, "camoufox", "anti-detection browser", "real firefox on the vps", "the browser that beats cloudflare", "vnc browser", "novnc session".
+---
+
+# /mso-camoufox — the real-Firefox browser MSO hosts
+
+Camoufox is a hardened Firefox build with anti-fingerprinting patches. MSO runs it
+on a headless X display and exposes the live screen over noVNC, so it is a browser
+you *watch and click*, not a headless scraper. Use it when a site blocks the plain
+headless browser (Cloudflare, DataDome, LinkedIn, anything that fingerprints).
+
+**Camoufox IS the Browser app.** It replaced both the Playwright sidecar
+(`os-browser`, `:4002` — retired, kept only as dev tooling for `scripts/e2e`) and the
+sandboxed-iframe browser that briefly followed it, because X-Frame-Options makes an
+iframe unable to render most of the real web.
+
+## Power it from the CLI
+
+```bash
+mso camoufox status # {installed, running, enabled}
+mso camoufox start # systemctl --user start camoufox-vnc.service
+mso camoufox stop
+mso camoufox session # {password: "…"} — the one-time noVNC password
+```
+
+`start`/`stop` go through `/api/v1/camoufox/service`, which shells
+`systemctl --user` — no sudo, no polkit rule. `installed:false` means the unit
+file is missing, not that the browser is off.
+
+## Watch / drive the screen
+
+Once running, the live screen is proxied by MSO itself:
+
+```
+https://mso.rahmanef.com/camoufox-vnc/#password=<from `mso camoufox session`>
+```
+
+`proxy.ts` rewrites `/camoufox-vnc/*` to the local websockify on `127.0.0.1:6080`
+(loopback-checked) behind the SAME verified-session check that guards
+`/api/v1/exec`. Nothing about camoufox is exposed on a public port.
+
+**The password goes in the URL fragment, never the query string** — a fragment is
+not sent to the server and does not land in access logs or `Referer`.
+
+Inside MSO the same thing is the **Browser** app's Camoufox tab.
+
+## What the unit actually starts
+
+`scripts/camoufox-vnc-service` (a *user* unit, `~/.config/systemd/user/camoufox-vnc.service`):
+
+| piece | default | env override |
+|---|---|---|
+| X display | `:92` @ `1440x920x24` | `CAMOUFOX_DISPLAY_NUM`, `CAMOUFOX_GEOMETRY` |
+| VNC / noVNC ports | `5902` / `6080` | `CAMOUFOX_VNC_PORT`, `CAMOUFOX_NOVNC_PORT` |
+| profile | `~/.local/share/camoufox/profiles/linkedin` (chmod 700) | `CAMOUFOX_PROFILE` |
+| browser binary | `~/.cache/camoufox/browsers/official/…/camoufox` | `CAMOUFOX_BROWSER` |
+| start URL | none (restores last session) | `CAMOUFOX_START_URL` |
+| VNC password file | `~/.vnc/passwd` | `CAMOUFOX_VNC_PASSWD` |
+
+Also runs `matchbox-window-manager` so windows have no titlebar and fill the display.
+
+## The profile is the valuable part — and the crown jewels
+
+The profile holds a **live Google session** (`SID`, `__Secure-1PSID`, `SAPISID`) and
+LinkedIn's `li_at`. Stealing those cookies is account takeover with no password and no
+2FA prompt. So the unit re-`chmod 700`s the profile on every start (Firefox writes
+`cookies.sqlite` 0644) and snapshots `cookies.sqlite*`, `key4.db`, `cert9.db` into
+`~/.local/state/camoufox/session-backup/` — 3 generations, 0700.
+
+Never `mso cat` or paste the profile contents anywhere.
+
+To restore a broken session:
+
+```bash
+mso camoufox stop
+mso exec 'cp -p ~/.local/state/camoufox/session-backup/1/* ~/.local/share/camoufox/profiles/linkedin/'
+mso camoufox start
+```
+
+Use a separate profile per identity (`CAMOUFOX_PROFILE=…`) rather than logging one
+profile in and out — the anti-detection value comes from a profile that looks aged.
+
+## Gotchas
+
+- **`enabled:false` is REQUIRED, not an accident.** The unit ships `disabled` with
+ `Restart=no` + `RuntimeMaxSec=2h`. Power is plain `start`/`stop` — never
+ `enable --now`, or every click re-arms boot autostart (that is how it once ran 26h
+ with zero viewers). And a 2h lease under `Restart=always` is a 2-hourly reboot loop:
+ ship `Restart=no` and the lease together or neither.
+- **`CAMOUFOX_PROFILE` must point at `~/.local/share/…`, not `~/.cache/…`.** A wrong
+ path makes `mkdir -p` create an empty profile with no error — you get a
+ logged-out browser and no clue why.
+- **The unit exists only on the host.** There is no copy or installer for it in the
+ repo beyond `scripts/camoufox-vnc-service`; `loginctl enable-linger rahman` and the
+ `user-bus.conf` drop-in have to be set up by hand.
+- **Needs a user bus.** MSO reaches `systemctl --user` only because
+ `mso.service.d/user-bus.conf` sets `XDG_RUNTIME_DIR=/run/user/1001` and rahman has
+ `loginctl enable-linger`. If start fails with "Failed to connect to bus", that
+ drop-in or the linger is gone — not a camoufox problem.
+- **It is heavy.** Xvfb + Firefox + websockify. Check `mso stats` before starting it
+ on a loaded box, and stop it when you are done.
+- **Authorized use only.** Anti-detection browsing is for sites you have a right to
+ access — your own accounts, your own tenants. Do not use it to evade a block that
+ is telling you no.
+
+## Related
+
+- `/mso` — the CLI and everything else on the host
+- `/mso-browser-list` — the retired Playwright sidecar (`:4002`), still used by
+ `scripts/e2e` for screenshots
+- `skills/camoufox-browse` (bundled in MSO's own catalog) — the scripting-level
+ Camoufox skill for the in-app assistant, from ClawHub
diff --git a/claude-skills/mso-image-editor/SKILL.md b/claude-skills/mso-image-editor/SKILL.md
new file mode 100644
index 00000000..dda18252
--- /dev/null
+++ b/claude-skills/mso-image-editor/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: mso-image-editor
+description: Edit images from the CLI by CRUD-ing an mso editor DOCUMENT (JSON) — open an image, run any editor op (layers, text, shapes, adjustments, blend/shadow/glow/stroke, transform, crop, resize), save it, then render by opening in the REAL mso editor. No bespoke renderer. Trigger on /mso-image-editor, "edit this image", "add text to image", "make a thumbnail/story", "resize/crop image", "adjust brightness/contrast", "drive the image editor from cli".
+---
+
+# /mso-image-editor — edit images via document CRUD
+
+Edit images from here using the SAME command registry the in-browser editor's AI
+panel uses. The CLI is **data-level**: it builds/updates an editor **document**
+(JSON) via `POST /api/v1/editor/exec` (a React-free reducer — pure data, no
+browser). To SEE the result, **open the doc in the real mso editor** ("render
+= the actual editor"). This is just editor-document CRUD — see the generic
+`mso crud` in [/mso]; this skill is the editor-doc-specialized front end.
+
+```bash
+SH=/home/rahman/.claude/skills/mso-image-editor/image-editor.sh
+$SH open ~/pic.jpg # → 1:1 doc (image layer; dims via header probe)
+$SH run adjust.set brightness=0.15 contrast=20
+$SH run layer.add kind=text text="SALE 50%" fontSize=160 fill=#ff3366
+$SH run transform.set x=120 y=200
+$SH run style.shadow enabled=true distance=12 size=20 opacity=0.6
+$SH inspect # layer stack + canvas state
+$SH save ~/pic.doc.json # persist the doc to a host file
+$SH view ~/pic.doc.json # → URL; open it to RENDER in the real editor
+```
+
+Other verbs: `new [WxH]` (blank doc), `tools` (every command + schema), `doc`
+(raw session JSON). `k=v` values coerce: `12`/`1.5` → number, `true/false` →
+bool, else string. Hex (`#ff3366`) is fine unquoted.
+
+## Model (no parallel renderer)
+
+- **Session** = a working Doc JSON (`$TMPDIR/mso-image-editor.session.json`). Each
+ verb sends it + one command and saves the returned doc. `open`/`new` reset it;
+ `save <path>` writes it to a real host file (what the editor opens).
+- **CRUD mapping**: `new`/`open` = Create · `inspect`/`doc` = Read · `run` =
+ Update · (delete the file via `mso crud del`). The generic equivalent:
+ `mso crud set <path.json> <cmd k=v…>`.
+- **Render = the REAL editor.** `save` to a `.doc.json`, then open
+ `https://mso.rahmanef.com/studio/<abs-path>` (what `view` prints) — media-studio
+ loads it into the actual Konva editor (`ImageEditor projectSrc`). Pixel-exact,
+ zero duplicate engine. (There is no server-side PNG render anymore.)
+- **Auth**: persistent cookie jar (`$TMPDIR/mso-image-editor.jar`), login only on
+ 401 — same device-approval model as [/mso].
+
+## Commands (32) — `$SH tools` for the full schema
+
+| Domain | Commands |
+|---|---|
+| document | `doc.inspect` `doc.resize w h` `doc.aspect preset` `doc.crop x y w h` |
+| layer | `layer.add kind=…` `layer.remove` `layer.duplicate` `layer.select` `layer.order move=raise\|lower\|front\|back` `layer.visibility visible=` `layer.lock locked=` `layer.rename name=` `layer.opacity opacity=` |
+| transform | `transform.set x= y= width= height= rotation= scaleX= scaleY=` `transform.flip horizontal= vertical=` `text.edit text= fontSize= fill= …` `shape.edit shape= fillColor=` |
+| adjust | `adjust.set brightness= contrast= saturation= hue= blur= grayscale= invert= sepia=` `adjust.reset` `adjust.addLayer` |
+| style | `style.blend blend= clipBelow=` `style.shadow enabled= …` `style.glow enabled= …` `style.stroke enabled= color= width=` |
+| tool | `tool.select tool=` `brush.set` `color.set fg= bg=` `color.swap` `mask.add` `mask.remove` `edit.undo` `edit.redo` |
+
+Target a layer with `layerId=`/`layerName=`; omit → the selected layer (the last
+added). `doc.aspect` presets: `Square 1:1`, `Portrait 4:5`, `Story 9:16`,
+`Landscape 16:9`, `Wide 1.91:1`.
+
+## Recipe
+
+```bash
+# Instagram story from a photo + title, rendered in the real editor
+$SH open ~/photo.jpg
+$SH run doc.aspect preset="Story 9:16"
+$SH run layer.add kind=text text="NEW DROP" fontSize=140 fill=#ffffff fontStyle=bold
+$SH run transform.set x=90 y=1500
+$SH save ~/story.doc.json
+$SH view ~/story.doc.json # open the printed URL → Konva renders it exactly
+```
+
+## Notes
+
+- `set`/`run` only edit DATA; brush pixels are painted in the real editor (the
+ doc carries layers/styles, not brush strokes). `image.removeBackground` is a
+ browser-only op (run it in the editor's AI panel, not headless).
+- Code: route `app/api/v1/editor/exec/route.ts`; engine
+ `frontend/slices/image-editor/lib/headless/{editor-core,run,image-size}.ts`;
+ server barrel `…/image-editor/server.ts`; render bridge `media-studio/app.tsx`
+ + `image-editor.tsx` (`projectSrc`/`ProjectLoader`).
+- Adding a command (a `commands/*.commands.ts` entry) exposes it to this CLI, the
+ generic `mso crud`, AND the in-browser AI panel at once.
diff --git a/claude-skills/mso-image-editor/image-editor.sh b/claude-skills/mso-image-editor/image-editor.sh
new file mode 100755
index 00000000..fdeedab1
--- /dev/null
+++ b/claude-skills/mso-image-editor/image-editor.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# image-editor.sh — drive the mso image editor HEADLESS from the CLI. Hits
+# POST/GET /api/v1/editor/exec (the same command registry the in-browser AI uses)
+# against a React-free Doc reducer + a skia renderer. No browser. The "session"
+# (current Doc) lives in a temp JSON file; each verb sends it and saves the result.
+#
+# image-editor.sh new [WxH] fresh blank doc (default 1080x1080)
+# image-editor.sh open <img> load an image file → 1:1 doc (image layer)
+# image-editor.sh run <cmd> [k=v...] run one command (e.g. adjust.set brightness=0.2)
+# image-editor.sh inspect print the layer stack / canvas state
+# image-editor.sh tools list every command + description
+# image-editor.sh doc print the raw session Doc JSON
+# image-editor.sh save <path.json> write the doc to a host file (CRUD persist)
+# image-editor.sh view <path.json> [--shot [out.png]]
+# URL to open in the REAL editor (+ auto-screenshot)
+#
+# k=v values coerce: 12 / 1.5 → number, true/false → bool, else string.
+# Session file: $OS_EDITOR_SESSION (default $TMPDIR/mso-image-editor.session.json).
+set -euo pipefail
+
+B="${OS_BASE:-http://127.0.0.1:4005}"
+ENVF="${OS_ENV:-/home/rahman/projects/mso/.env.local}"
+# shellcheck disable=SC1090
+set -a; . "$ENVF" 2>/dev/null || true; set +a
+PASS="${OS_PASSWORD:-${OS_LOGIN_PASSWORD:-}}"
+# Share the one CLI device `mso` created + you approved, so this script never
+# needs its own approval round.
+DEV="${OS_DEVICE:-$(cat "$HOME/.mso/cli.device.id" 2>/dev/null || echo 46e72d1e9b22372eb6bdd6b76b11192b)}"
+# proxy.ts blocks mutating /api without same-origin proof; Origin==Host is the
+# documented non-browser path.
+ORIGIN=(-H "origin: $B")
+SESS="${OS_EDITOR_SESSION:-${TMPDIR:-/tmp}/mso-image-editor.session.json}"
+[ -n "$PASS" ] || { echo "no OS_LOGIN_PASSWORD in $ENVF (set OS_PASSWORD)" >&2; exit 1; }
+
+# Persistent cookie jar reused across invocations — log in only when the session
+# is missing/expired (avoids the login rate-limiter on multi-command sequences).
+JAR="${OS_EDITOR_JAR:-${TMPDIR:-/tmp}/mso-image-editor.jar}"
+EXEC="$B/api/v1/editor/exec"
+
+login() {
+ local code
+ code=$(curl -sS -o /dev/null -w '%{http_code}' -c "$JAR" "${ORIGIN[@]}" -X POST "$B/api/auth/login" \
+ -H 'content-type: application/json' \
+ -d "$(jq -n --arg p "$PASS" --arg d "$DEV" '{password:$p,deviceId:$d,deviceLabel:"os-image-editor cli"}')" || true)
+ [ "$code" = "200" ] || { echo "login failed ($code). approve device? → node ~/projects/mso/scripts/approve-device.js $DEV" >&2; exit 1; }
+}
+[ -f "$JAR" ] || login
+
+# Run a request with the cached cookie; on 401 (expired) log in once + retry.
+req() {
+ local out code body
+ out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)
+ code="${out##*$'\n'}"; body="${out%$'\n'*}"
+ if [ "$code" = "401" ] || [ "$code" = "403" ]; then
+ login; out=$(curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' "$@" || true)
+ code="${out##*$'\n'}"; body="${out%$'\n'*}"
+ fi
+ [ "$code" = "200" ] || { echo "request failed ($code): $body" >&2; exit 1; }
+ printf '%s' "$body"
+}
+post() { local p; p=$(cat); req -H 'content-type: application/json' -d "$p" "$EXEC"; }
+have_session() { [ -f "$SESS" ] || { echo "no session — run 'open <img>' or 'new' first" >&2; exit 1; }; }
+save_doc() { jq -e '.doc' >/dev/null <<<"$1" && jq '.doc' <<<"$1" >"$SESS"; }
+show_results() { jq -r '.results[]? | " \(.name) \(if .ok then "ok" else "ERR" end) — \(.result)"' <<<"$1"; }
+
+# Build a JSON args object from k=v pairs, coercing numbers + booleans.
+build_args() {
+ local j='{}' kv k v
+ for kv in "$@"; do
+ k="${kv%%=*}"; v="${kv#*=}"
+ if [[ "$v" =~ ^-?[0-9]+([.][0-9]+)?$ || "$v" == "true" || "$v" == "false" ]]; then
+ j=$(jq -c --arg k "$k" --argjson v "$v" '. + {($k):$v}' <<<"$j")
+ else
+ j=$(jq -c --arg k "$k" --arg v "$v" '. + {($k):$v}' <<<"$j")
+ fi
+ done
+ printf '%s' "$j"
+}
+
+cmd="${1:-help}"; shift || true
+case "$cmd" in
+ new)
+ resp=$(echo '{"commands":[]}' | post); save_doc "$resp"
+ if [ -n "${1:-}" ] && [[ "$1" =~ ^([0-9]+)x([0-9]+)$ ]]; then
+ a=$(build_args "width=${BASH_REMATCH[1]}" "height=${BASH_REMATCH[2]}")
+ resp=$(jq -n --slurpfile d "$SESS" --argjson a "$a" '{doc:$d[0],commands:[{name:"doc.resize",args:$a}]}' | post)
+ save_doc "$resp"
+ fi
+ echo "new session → $SESS"; jq -r '" \(.width)x\(.height), \(.layers|length) layer(s)"' "$SESS" ;;
+ open)
+ f="${1:?image path}"; [ -f "$f" ] || { echo "no such file: $f" >&2; exit 1; }
+ f=$(realpath "$f"); name=$(basename "$f")
+ # Send the host PATH (not bytes) — the route probes dims from the file header
+ # and stores a light same-origin path-URL src, so the doc carries no base64.
+ resp=$(jq -n --arg p "$f" --arg n "$name" '{imagePath:$p,open:true,name:$n}' | post)
+ save_doc "$resp"; echo "opened $f → $SESS"; jq -r '" \(.width)x\(.height), \(.layers|length) layer(s)"' "$SESS" ;;
+ run)
+ have_session; name="${1:?command name}"; shift || true
+ a=$(build_args "$@")
+ resp=$(jq -n --slurpfile d "$SESS" --arg n "$name" --argjson a "$a" '{doc:$d[0],commands:[{name:$n,args:$a}]}' | post)
+ save_doc "$resp"; show_results "$resp" ;;
+ inspect)
+ have_session
+ resp=$(jq -n --slurpfile d "$SESS" '{doc:$d[0],commands:[{name:"doc.inspect"}]}' | post)
+ jq -r '.results[0].result' <<<"$resp" ;;
+ tools)
+ req "$EXEC" | jq -r '.tools[] | " \(.name)\t\(.description)"' ;;
+ doc) have_session; cat "$SESS"; echo ;;
+ save)
+ have_session; out="${1:?dest path, e.g. ~/x.doc.json}"
+ req -H 'content-type: application/json' \
+ -d "$(jq -n --arg p "$out" --arg c "$(jq -c . "$SESS")" '{path:$p,content:$c}')" \
+ "$B/api/v1/fs/write" >/dev/null
+ echo "saved doc → $out (render: $0 view $out)" ;;
+ view)
+ p="${1:?path}"; shift || true
+ base="${OS_PUBLIC_BASE:-https://mso.rahmanef.com}"
+ case "$p" in /*) ;; *) p="/$p" ;; esac
+ url="$base/studio$p"; echo "$url"
+ if [ "${1:-}" = "--shot" ]; then
+ out="${2:-/tmp/studio-view.png}"
+ BR="${OS_BROWSER_SH:-/home/rahman/.claude/skills/mso/browser.sh}"
+ "$BR" go "$url" >/dev/null 2>&1; sleep 7; "$BR" shot "$out" # needs a logged-in browser
+ else
+ echo "# open that URL (logged-in browser) — Konva renders the doc; add --shot [out.png] to auto-screenshot"
+ fi ;;
+ *) sed -n '2,20p' "$0" ;;
+esac
diff --git a/claude-skills/mso-list/SKILL.md b/claude-skills/mso-list/SKILL.md
new file mode 100644
index 00000000..e8cba72b
--- /dev/null
+++ b/claude-skills/mso-list/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: mso-list
+description: List every mso app + its functions and check they actually work end-to-end (live probe of all /api/v1 calls). Trigger on /mso-list, "list os features", "check all os functions", "audit os apps", "what works in the os", "are the os functions working".
+---
+
+# /mso-list — audit all OS apps + functions
+
+Enumerate every mso app, its user-facing functions / AI-Inspector actions, and
+verify the backing calls work against the live host. Pairs with [/mso] (control)
+and [/mso-browser-list] (browser deep-dive).
+
+## 1. Live probe (run this first)
+
+```bash
+cd /home/rahman/projects/mso && node ~/.claude/skills/mso-list/audit.js
+```
+Signs in (device-password, password + approved device from env or defaults) and
+hits every `/api/v1` endpoint, printing a pass/fail table. Override with env
+`OS_BASE`, `OS_CONVEX`, `OS_PASSWORD`, `OS_DEVICE`. Needs the `convex` dep (run
+from the repo). A function is "working" only if its endpoint returns 2xx here.
+
+## 2. App → function matrix
+
+| App | Functions | Backing call | Notes |
+|---|---|---|---|
+| **shell** | open/close/min/max/snap, dock, launchpad, Spotlight ⌘K, AI Inspector ⌘I, menu File/Edit/View | local store | no host call |
+| **files-manager** | navigate, breadcrumb/back/fwd, favorites (real roots), live tree, new folder/file, rename, move (drag), copy/cut/paste, trash*, upload, details | `fs.list/mkdir/write/move/copy/remove/usage` | trash to /.Trash fails on live (outside write root) |
+| **code-editor** | live tree, open (fs.read), edit, save (fs.write), new file, tabs | `fs.read/write/list` | |
+| **terminal** | ls/cat/cd (+13 builtins), mkdir/rm/mv/cp/touch (live fs), unknown cmd → host shell | `fs.*`, `exec.run` | live passthrough |
+| **browser** | omnibar nav, back/fwd/reload, bookmarks, history, in-page link/form click-through | `/api/v1/proxy` | see [/mso-browser-list] |
+| **system-monitor** | gauges, sparklines, process table, refresh | `sys.stats/processes` | |
+| **reel-editor** | timeline, clips, keyframes, render→.webm, Inspector "Render" | client canvas | render is client-side |
+| **media-studio** | layers, tools, filters, export, Inspector add/export/undo | client | |
+| **media-viewer** | image/video/audio view, download, open-in-editor | `fs.read` | |
+| **app-store / create-app** | install/uninstall, create runtime app | Convex `features/apps` | |
+| **runtime-app** | html→iframe, command runtime→Run console | `exec.run` | |
+| **os-settings** | theme/accent/device, server mock/live, AI key, devices approve | Convex + local | |
+| **assistant (Alfa)** | streaming chat, agents/skills/automations | `/api/assistant` | needs ANTHROPIC_API_KEY |
+| **AI Inspector** (every app) | Properties (live state) + scoped AI chat | `usePublishInspector` + `/api/assistant` | AI tab needs ANTHROPIC_API_KEY |
+
+## 3. Caveats that make a function "look broken"
+
+- **AI tab / Alfa**: blank/"no key" until `ANTHROPIC_API_KEY` is set in the Dokploy
+ mso env (or Settings → AI). Backend route is fine; it just has no key.
+- **Live mode**: file/exec/sys functions only hit the VPS when Settings → Server →
+ **Live**. In Mock they use the in-browser sim. Token must be present.
+- **Trash on live**: `/.Trash` is outside the write root → move fails. Known gap.
+- **Browser in-page nav**: works via the injected click-through; heavy SPAs / login
+ flows still constrained — see [/mso-browser-list].
+
+Report = the probe table + which apps are fully green vs gated (AI key / live mode).
diff --git a/claude-skills/mso-list/audit.js b/claude-skills/mso-list/audit.js
new file mode 100644
index 00000000..c975fcfb
--- /dev/null
+++ b/claude-skills/mso-list/audit.js
@@ -0,0 +1,90 @@
+// os-list audit — logs in (password + approved device → signed cookie) and
+// probes every mso /api/v1 function end-to-end, printing a pass/fail table.
+// No Convex (removed 2026-05-30) — auth is the session cookie.
+// node ~/.claude/skills/mso-list/audit.js
+const fs = require("fs");
+// Read a key from mso/.env.local — so the password is sourced, never hardcoded.
+function fromEnvFile(key) {
+ try {
+ const t = fs.readFileSync(process.env.OS_ENV || "/home/rahman/projects/mso/.env.local", "utf8");
+ const m = t.match(new RegExp("^" + key + "=(.*)$", "m"));
+ return m ? m[1].trim().replace(/^['"]|['"]$/g, "") : "";
+ } catch {
+ return "";
+ }
+}
+const BASE = process.env.OS_BASE || "https://mso.rahmanef.com";
+const PASS = process.env.OS_PASSWORD || fromEnvFile("OS_LOGIN_PASSWORD");
+const DEV =
+ process.env.OS_DEVICE ||
+ (() => { try { return require("fs").readFileSync(require("os").homedir() + "/.mso/cli.device.id", "utf8").trim(); } catch { return "46e72d1e9b22372eb6bdd6b76b11192b"; } })();
+// proxy.ts blocks mutating /api without same-origin proof; Origin==Host is the
+// documented non-browser path.
+const ORIGIN = { origin: BASE };
+if (!PASS) {
+ console.error("no password — set OS_PASSWORD or OS_LOGIN_PASSWORD in mso/.env.local");
+ process.exit(1);
+}
+
+(async () => {
+ // 1) login → capture the session cookie.
+ let cookie;
+ try {
+ const r = await fetch(BASE + "/api/auth/login", {
+ method: "POST",
+ headers: { "content-type": "application/json", ...ORIGIN },
+ body: JSON.stringify({ password: PASS, deviceId: DEV, deviceLabel: "os-list audit" }),
+ });
+ if (r.status === 403) {
+ console.error("device_pending — approve it: node ~/projects/mso/scripts/approve-device.js " + DEV);
+ process.exit(1);
+ }
+ if (!r.ok) {
+ console.error("login failed:", r.status, (await r.json().catch(() => ({}))).error);
+ process.exit(1);
+ }
+ const sc = r.headers.get("set-cookie") || "";
+ cookie = (sc.match(/session=[^;]+/) || [])[0];
+ } catch (e) {
+ console.error("login error:", e.message);
+ process.exit(1);
+ }
+ if (!cookie) {
+ console.error("no session cookie returned");
+ process.exit(1);
+ }
+ const H = { cookie, "content-type": "application/json" };
+
+ const probes = [
+ ["GET", "/api/v1/sys/stats", null, "system-monitor: live CPU/mem/disk"],
+ ["GET", "/api/v1/sys/processes", null, "system-monitor: process table"],
+ ["GET", "/api/v1/fs/list?path=~", null, "files/code/tree: list dir"],
+ ["GET", "/api/v1/fs/usage?path=~", null, "files: storage gauge"],
+ ["GET", "/api/v1/apps", null, "app-store: runtime apps"],
+ ["POST", "/api/v1/exec/run", { cmd: "echo ok" }, "terminal/runtime-app: exec"],
+ ["POST", "/api/v1/fs/mkdir", { path: "~/.os-audit" }, "files/tree: new folder"],
+ ["POST", "/api/v1/fs/write", { path: "~/.os-audit/a", content: "x" }, "files/tree/editor: write/save"],
+ // Reads back what the write probe just made: any path under $HOME is inside
+ // OS_FS_READ_ROOTS on every install, unlike the /etc/hostname this used to
+ // probe (that only passed while the roots were the wide-open "/").
+ ["GET", "/api/v1/fs/read?path=~/.os-audit/a", null, "code/viewer: read file"],
+ ["POST", "/api/v1/fs/move", { from: "~/.os-audit/a", to: "~/.os-audit/b" }, "files: move/rename"],
+ ["POST", "/api/v1/fs/copy", { from: "~/.os-audit/b", to: "~/.os-audit/c" }, "files: copy"],
+ ["DELETE", "/api/v1/fs/delete", { path: "~/.os-audit" }, "files: delete/trash"],
+ // The Browser app is Camoufox now; /api/v1/browser was retired with the
+ // Playwright sidecar and 404s.
+ ["GET", "/api/v1/camoufox/service", null, "browser: camoufox VNC service state"],
+ ];
+ console.log(`OS function audit @ ${BASE} (cookie auth)\n`);
+ let ok = 0;
+ for (const [m, p, b, label] of probes) {
+ try {
+ const r = await fetch(BASE + p, { method: m, headers: { ...H, ...ORIGIN }, body: b ? JSON.stringify(b) : undefined });
+ console.log(`${r.ok ? "OK " : "FAIL"} ${r.status} ${m.padEnd(6)} ${p.split("?")[0].padEnd(24)} ${label}`);
+ if (r.ok) ok++;
+ } catch (e) {
+ console.log(`ERR ${m.padEnd(6)} ${p.split("?")[0].padEnd(24)} ${e.message}`);
+ }
+ }
+ console.log(`\n${ok}/${probes.length} endpoints OK`);
+})();
diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.md
new file mode 100644
index 00000000..b20123df
--- /dev/null
+++ b/claude-skills/mso/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: mso
+description: Control the mso web OS + its VPS host from here. Drive the live OS at mso.rahmanef.com — browse/read/write files anywhere on the VPS, run shell commands, manage apps, check system status, deploy. Trigger on /mso, "control the os", "control my vps", "drive mso", "open the OS", "run on the vps", "browse the vps files".
+---
+
+# /mso — control the VPS OS
+
+Operate **mso** (live web OS at https://mso.rahmanef.com) and its VPS host.
+mso is **self-contained**: it runs AS a host process (systemd, :4005) and does
+fs/exec/sys itself — NO Control Room agent, NO Convex. This box (`srv614914`) IS
+the VPS, so you can also act directly via Bash.
+
+## Two ways to act
+
+1. **Direct (you run AS rahman on this box)** — just use Bash. Fastest for local work.
+2. **Through mso** (`mso`) — drives the host the SAME `/api/v1` the web OS
+ uses, so behaviour matches what the user sees. Use to reproduce/debug the OS or
+ get its bounded fs semantics.
+
+```bash
+SH=mso
+$SH health # session ok?
+$SH ls ~/projects # list (READ = whole filesystem)
+$SH cat ~/projects/mso/README.md
+$SH exec "df -h && uptime" # run anything (full shell)
+$SH write ~/scratch/note.txt "hi" # WRITE bounded to home + ~/projects
+$SH mkdir ~/scratch/new ; $SH mv ~/a.txt ~/projects/a.txt
+$SH stats ; $SH ps # telemetry + processes
+```
+
+### Generic resource CRUD (`crud`)
+
+One pattern for every host resource (`mso crud`):
+
+```bash
+$SH crud list ~/projects # → fs.list
+$SH crud get ~/notes/a.md # → fs.read
+$SH crud set ~/notes/a.md "plain text" # write a file
+$SH crud set ~/x.doc.json layer.add kind=text text=Hi # edit an editor DOC (atomic, 1 call)
+$SH crud del ~/notes/a.md ; $SH crud cmds # delete ; list editor commands
+```
+
+`crud set <path.json> <editor-cmd k=v…>` is a SINGLE atomic server op (route reads
+the doc file → applies the command → writes it back in place; missing file is
+seeded, an existing non-doc file is REFUSED, not clobbered). Truly CRUD-able =
+host files + editor docs + the `~/.mso/*.json` config/device files. NOT
+crud-able (live in the browser): theme/server toggle, window layout, the app
+registry (localStorage); sys stats are read-only. To VIEW an edited doc, open it
+in the real editor (see [/mso-image-editor] `view`). Raster ops (brush pixels,
+masks, background removal) are browser-only by design — there is no headless
+renderer.
+
+`mso` needs `jq`. It logs in (POST `/api/auth/login`) with `OS_LOGIN_PASSWORD`
+from `/home/rahman/projects/mso/.env.local` + an approved device id (default
+`46e72…`), keeps the session cookie in a temp jar. Override base with `OS_BASE`.
+If login 403s → device pending → `node ~/projects/mso/scripts/approve-device.js <id>`.
+
+## mso endpoints (cookie-auth, what the OS calls)
+
+All under `/api/v1`, gated by the signed session cookie (sent automatically).
+
+| Method | Path | Body / query | Notes |
+|---|---|---|---|
+| GET | `/fs/list?path=` | — | `{path,parent,roots,entries[]}`; READ = whole fs; hidden incl |
+| GET | `/fs/read?path=` | — | raw utf8 string (≤5 MiB) |
+| GET | `/fs/usage?path=` | — | `{used,total}` |
+| POST | `/fs/write` | `{path,content}` | atomic; **home+~/projects only** |
+| POST | `/fs/mkdir` | `{path}` | bounded |
+| DELETE | `/fs/delete` | `{path}` | recursive; bounded |
+| POST | `/fs/move` / `/fs/copy` | `{from,to}` | bounded |
+| POST | `/exec/run` | `{cmd,cwd?}` | one-shot `/bin/bash`, 30s, 1 MiB out, cwd bounded |
+| GET | `/sys/stats` / `/sys/processes` | — | telemetry / `ps` |
+| GET | `/api/auth/me` | — | session check |
+
+**Bounds env** (in `mso/.env.local`): `OS_FS_READ_ROOTS` (default `/` here →
+browse anywhere), `OS_FS_WRITE_ROOTS` (default home+projects). Logic in
+`mso/lib/host/`. Change → `sudo systemctl restart mso`.
+
+## Real browser (Playwright, you can drive + see it)
+
+Real headless Chromium runs as systemd `os-browser` (Playwright, loopback :4002,
+secret in `/home/rahman/projects/mso/os-browser/.env`). ONE persistent context
+(`~/.mso/chrome-profile`) → cookies/cache/session on disk, SHARED between the
+Browser app and the CLI. Renders any site (no X-Frame-Options).
+
+```bash
+SH=/home/rahman/.claude/skills/mso/browser.sh
+$SH go github.com # navigate (bare words → google search)
+$SH shot /tmp/b.png # screenshot → Read it to SEE the page
+$SH content # innerText
+$SH click 640 380 ; $SH type "hello" ; $SH key Enter ; $SH scroll 600
+$SH state ; $SH back ; $SH reload
+```
+Web OS reaches it via `/api/v1/browser/*` (cookie-auth → 127.0.0.1:4002).
+Restart: `sudo systemctl restart os-browser`. Code: `mso/os-browser/server.mjs`.
+
+## The web OS (mso)
+
+- Repo `/home/rahman/projects/mso` (`[email protected]:rahmanef63/mso.git`).
+- Live `mso.rahmanef.com`. **Auth = password + device approval** (signed cookie, no
+ Convex). New device → "pending" → approve in Settings → Devices, or CLI.
+- **Settings → Server → Live** routes file/exec/sys through `/api/v1` (host ops are
+ internal now). Mock is the default (demo with no host access).
+- **AI Inspector** (⌘I): per-app props + scoped Alfa chat. Alfa needs a key —
+ Settings → AI (BYOK, `~/.mso/config.json`) or `ANTHROPIC_API_KEY` env.
+- Persistence is local: window layout + installed apps in localStorage; devices +
+ config in `~/.mso/*.json`.
+
+## Operate / deploy
+
+- **Off Dokploy.** Prod = the local working dir served by systemd `mso.service`
+ (`next start` :4005). Editing + rebuilding the repo IS deploying.
+- **Deploy a change**: edit → `cd ~/projects/mso && pnpm typecheck && pnpm build`
+ → `sudo systemctl restart mso` → verify. `git push` is version-control only.
+- **Status**: `mso exec "systemctl is-active mso os-browser"`; site 200 check.
+- Audit everything: `node ~/.claude/skills/mso-list/audit.js` (13 endpoints).
+
+## Safety
+
+- Restarting `mso` / `os-browser` is fine (task targets). Do NOT restart
+ `vps-control-room-*` without warning the user — separate live product.
+- `exec` is full shell as `rahman`. Confirm destructive commands (rm -rf, service
+ changes) with the user first.
+- Never echo `.env.local`, the session secret, the login password, or device store.
diff --git a/claude-skills/mso/browser.sh b/claude-skills/mso/browser.sh
new file mode 100755
index 00000000..6864a801
--- /dev/null
+++ b/claude-skills/mso/browser.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# browser.sh — drive the REAL headless browser (Playwright Chromium) the mso
+# Browser app uses. Same persistent session/cache, so logged-in state is shared.
+# Screenshots land in /tmp so they can be Read (viewed) directly.
+#
+# browser.sh go <url> navigate (bare words → google search)
+# browser.sh shot [file] screenshot → /tmp/os-browser.png (or file); prints path
+# browser.sh content page innerText (read what's on screen)
+# browser.sh state current url + title
+# browser.sh click <x> <y> click viewport px (1280x800)
+# browser.sh type <text> type text
+# browser.sh key <Key> press a key (Enter, Backspace, Tab, ArrowDown…)
+# browser.sh scroll <dy> wheel by dy px
+# browser.sh back|forward|reload
+# browser.sh health
+set -euo pipefail
+
+ENVF="${OS_BROWSER_ENV:-/home/rahman/projects/mso/os-browser/.env}"
+# shellcheck disable=SC1090
+set -a; . "$ENVF" 2>/dev/null || true; set +a
+SEC="${OS_BROWSER_SECRET:-}"
+B="${OS_BROWSER_BASE:-http://127.0.0.1:4002}"
+[ -n "$SEC" ] || { echo "no OS_BROWSER_SECRET in $ENVF" >&2; exit 1; }
+H=(-H "x-os-browser-secret: $SEC")
+J=(-H 'content-type: application/json')
+
+cmd="${1:-help}"; shift || true
+case "$cmd" in
+ go|navigate) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg u "${1:?url}" '{url:$u}')" "$B/navigate"; echo ;;
+ shot|screenshot) f="${1:-/tmp/os-browser.png}"; curl -fsS "${H[@]}" "$B/screenshot" -o "$f"; echo "saved $f ($(stat -c%s "$f") bytes) — Read it to view" ;;
+ content) curl -fsS "${H[@]}" "$B/content" ;;
+ state) curl -fsS "${H[@]}" "$B/state"; echo ;;
+ click) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --argjson x "${1:?x}" --argjson y "${2:?y}" '{x:$x,y:$y}')" "$B/click"; echo ;;
+ type) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg t "${*:?text}" '{text:$t}')" "$B/type"; echo ;;
+ key) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --arg k "${1:?key}" '{key:$k}')" "$B/key"; echo ;;
+ scroll) curl -fsS "${H[@]}" "${J[@]}" -d "$(jq -n --argjson d "${1:?dy}" '{dy:$d}')" "$B/scroll"; echo ;;
+ back|forward|reload) curl -fsS "${H[@]}" "${J[@]}" -d '{}' "$B/$cmd"; echo ;;
+ health) curl -fsS "$B/health"; echo ;;
+ *) sed -n '2,20p' "$0" ;;
+esac
diff --git a/scripts/install.sh b/scripts/install.sh
index bf3f7a0f..75d5e4a3 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -243,6 +243,33 @@ else
[ "$DO_SERVICE" -eq 1 ] && warn "no systemctl here — skipping service. Run manually: PORT=$PORT pnpm start"
fi
+# ---- CLI on PATH ----
+# The web UI is one frontend; bin/mso reaches the same /api surface from a shell.
+BIN_DIR="${MSO_BIN_DIR:-$HOME/.local/bin}"
+mkdir -p "$BIN_DIR"
+ln -sfn "$DIR/bin/mso" "$BIN_DIR/mso"
+ok "cli → $BIN_DIR/mso"
+case ":$PATH:" in
+ *":$BIN_DIR:"*) ;;
+ *) warn "$BIN_DIR is not on PATH — add: export PATH=\"\$PATH:$BIN_DIR\"" ;;
+esac
+
+# ---- agent skills (symlinked, so a git pull updates them too) ----
+# Skipped silently when Claude Code isn't installed — mso does not depend on it.
+SKILL_DIR="${MSO_SKILL_DIR:-$HOME/.claude/skills}"
+if [ -d "$DIR/claude-skills" ] && [ -d "$(dirname "$SKILL_DIR")" ]; then
+ mkdir -p "$SKILL_DIR"
+ for s in "$DIR"/claude-skills/*/; do
+ name="$(basename "$s")"
+ if [ -e "$SKILL_DIR/$name" ] && [ ! -L "$SKILL_DIR/$name" ]; then
+ warn "skill $name exists and is not a symlink — left alone"
+ continue
+ fi
+ ln -sfn "${s%/}" "$SKILL_DIR/$name"
+ done
+ ok "skills → $SKILL_DIR (/mso, /mso-camoufox, /mso-apps, /mso-list, …)"
+fi
+
# ---- next steps ----
ok "mso installed at $DIR"
cat <<EOF
diff --git a/vitest.config.mts b/vitest.config.mts
index c6599e7b..12af9814 100644
--- a/vitest.config.mts
+++ b/vitest.config.mts
@@ -22,6 +22,7 @@ export default defineConfig({
"app/**/*.test.{ts,tsx}",
"frontend/slices/**/*.test.{ts,tsx}",
"lib/**/*.test.{ts,tsx}",
+ "bin/**/*.test.{ts,tsx}",
"scripts/e2e/**/*.test.{ts,tsx}",
"instrumentation.test.ts",
// Root-level modules Next requires by name (middleware is `proxy.ts` in 16),