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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
docs: reconcile every live doc against what the box actually does
Rahmanbf7b94a38d04
diff --git a/.env.example b/.env.exampleindex bf768422..be9baf6f 100644--- a/.env.example+++ b/.env.example@@ -135,6 +135,32 @@ OS_SESSION_SECRET=# OS_DEVICE_STORE=~/.mso/auth-devices.json # approved-device allowlist# OS_CONFIG_STORE=~/.mso/config.json # BYOK key + model# OS_PREFS_PATH=~/.mso/prefs.json # synced UI prefs (theme, layout)+# OS_MEMORY_STORE=~/.mso/memory.json # assistant long-term memory+# OS_THREADS_DIR=~/.mso/threads # assistant chat threads (one file each)++# --- Camoufox browser (the Browser app) ---+# The noVNC/websockify endpoint proxy.ts rewrites /camoufox-vnc/* to, behind the same+# verified-session check that guards /api/v1/exec. It MUST stay loopback: the rewrite+# leaves this server, so a value pointing off-box turns the cockpit into an open relay,+# and proxy.ts 404s any non-loopback hostname rather than trusting it.+# CAMOUFOX_NOVNC_URL=http://127.0.0.1:6080+#+# Plaintext copy of the VNC password, written beside x11vnc's own passwd blob (which is+# not meant to be read back) by scripts/camoufox-vnc-service. 0600, never committed.+# The API hands it to the viewer in the URL FRAGMENT, never the query string.+# CAMOUFOX_VNC_PASSWD_TEXT=~/.vnc/passwd.txt++# --- Build metadata (optional) ---+# Shown in Settings → About. Set at BUILD time (NEXT_PUBLIC_ is inlined into the+# client bundle), e.g. NEXT_PUBLIC_COMMIT_SHA=$(git rev-parse --short HEAD) bun run build+# NEXT_PUBLIC_COMMIT_SHA=+#+# The ONLY way to emit a ?dpl= query on static chunk URLs. Leave UNSET unless you are+# running skew protection: next.config.mjs used to fall back to Date.now() here, and+# because the config is evaluated twice (build, then `next start` boot) that produced+# two different values for the same chunk and every cold load downloaded ~160 KB gzip+# of entry chunks TWICE. Chunks are content-hashed, so unset is correct.+# NEXT_DEPLOYMENT_ID=# --- Public demo build (optional, BUILD-TIME flag) ---# Build with =1 for a safe public showcase: no login, no host access, no /apidiff --git a/CLAUDE.md b/CLAUDE.mdindex 1bd9545d..3b8d870d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,8 +20,14 @@ agent — it runs AS a host process and controls its own machine.read the top few and you know the current state. Everything else in `docs/` ishistory or a plan, and history goes stale.- `README.md` — what it is, features, security model, quickstart.-- `.env.example` — most env vars. NOT all: it is missing several that only appear in- `.env.local` and in code, so grep `process.env` before assuming one does not exist.+- `.env.example` — every var you can actually set. Reconciled against `process.env`+ in code on 2026-08-03 (Camoufox, memory/threads paths, `NEXT_DEPLOYMENT_ID`,+ `NEXT_PUBLIC_COMMIT_SHA` were all missing and were added). What is still deliberately+ absent is what you never set by hand: framework vars (`NEXT_RUNTIME`,+ `NEXT_PUBLIC_BUILD_ID` — injected by `next.config`), systemd's (`NOTIFY_SOCKET`,+ `WATCHDOG_USEC`), the OS's (`PATH`, `SHELL`), test-only ones (`E2E_BASE_URL`,+ `OPENCLAW_HOME`), and `OS_BROWSER_*`, which belong to the retired `os-browser/`+ sidecar and not to this app. Still grep `process.env` before adding a new one.- **The code wins over any doc.** `docs/ARCHITECTURE.md` is HISTORY, not current — itstill describes a retired Playwright browser sidecar, a managed-app "single-originmode" that was removed for security, and workspace modes that were reversed. It is@@ -129,10 +135,14 @@ to `resources/` (rr) and drive any project from one manifest:host in `next.config` `images.remotePatterns`). Host-fs images + the live Playwrightscreenshot stream stay raw `<img>` on purpose (dynamic/auth'd bytes).-## Deploy / ops (prod :4005 + demo :4006 are systemd, not Dokploy)+## Deploy / ops (prod :4005 is systemd, not Dokploy)- `mso.service` (:4005, WorkingDir `/home/rahman/projects/mso`) serves- mso.rahmanef.com via `next start`. Demo `mso-demo.service` (:4006, WorkingDir- `/home/rahman/projects/mso-demo`, `NEXT_PUBLIC_OS_DEMO=1` → no auth, mock data).+ mso.rahmanef.com via `next start`.+- **The demo does NOT exist on this host** (checked 2026-08-03): no `mso-demo.service`+ unit, no `/home/rahman/projects/mso-demo` checkout. The `NEXT_PUBLIC_OS_DEMO=1`+ build flag is still real and still works — what is gone is the second checkout and+ the :4006 unit that used to serve it. Anything below describing "the demo" is a+ recipe to re-create it, not a description of something running.- **Deploy prod:** `bun run build` **THEN** `sudo systemctl restart mso.service`. ALWAYSbuild-then-restart, never the reverse, and never rebuild again after restartingwithout restarting once more — `next start` loads the build manifest at boot, so if@@ -152,9 +162,18 @@ to `resources/` (rr) and drive any project from one manifest:- **`git add` aborts on a bad pathspec** and stages NOTHING new — after a`git rm`, don't re-list the removed file in `git add`; prefer `git add -A` andcheck `git status --short` before committing (a broken commit shipped once this way).-- **Deploy demo:** from `/home/rahman/projects/mso-demo`: `git fetch origin -q &&- git reset --hard origin/main -q && bun run build && sudo systemctl restart- mso-demo.service`. Mind the cwd — running the sync from the prod dir is a classic slip.+- **Deploy demo (only if you re-create it — see above, it is not running):** from+ `/home/rahman/projects/mso-demo`: `git fetch origin -q && git reset --hard+ origin/main -q && bun run build && sudo systemctl restart mso-demo.service`.+ Mind the cwd — running the sync from the prod dir is a classic slip.+- **Never `bun run build` in this checkout just to CHECK a change** — it is+ `mso.service`'s WorkingDirectory, and `next build` deletes `distDir` before it+ compiles, so the live site 404s every chunk until a restart. Worse, repeat builds+ rename every chunk and mint a new `BUILD_ID`, so already-served HTML stays broken+ afterwards. Use `bash scripts/verify-build.sh`, which builds a throwaway copy of+ `HEAD` in a temp dir (node_modules is COPIED, not symlinked — Turbopack hard-fails+ on a symlink pointing outside the filesystem root). A real deploy still builds in+ place, which is fine because a restart immediately follows.- **The Browser app powers a systemd USER unit**, `camoufox-vnc.service` in`~/.config/systemd/user/`, whose `ExecStart` points at **`scripts/camoufox-vnc-service`in THIS repo** (it used to live untracked under `~/.openclaw/workspace/`, so a fresh@@ -183,11 +202,15 @@ to `resources/` (rr) and drive any project from one manifest:(3 generations, 0700). Restore after an accidental wipe: stop the unit,`cp -p ~/.local/state/camoufox/session-backup/1/* <profile>/`, start. Roll back to `2`or `3` if generation `1` already captured the logged-out state.-- Verify shell behaviour on the demo (no auth): desktop via os-browser at 1280, mobile- via Playwright (`os-browser/node_modules/playwright`, CommonJS) at 390. Drive Spotlight- with Meta+k; click the dock by the BOTTOM-most `a[href="/<slug>"]` (the centre ones are- the hidden Launchpad). `X-Content-Type-Options: nosniff` is set on all routes, so wrong- MIME is fatal — keep static Content-Types correct.+- Verify shell behaviour with **Playwright directly** — `os-browser/node_modules/playwright`+ (CommonJS) is the repo's only install — at 1280 for desktop and 390 for mobile. (This+ used to say "on the demo, via os-browser"; both are gone. There is no demo instance on+ this host, and the `os-browser` SERVICE is stopped + disabled — only its Playwright+ install is still used. Point Playwright at :4005 and log in, or build a throwaway with+ `NEXT_PUBLIC_OS_DEMO=1` on another port.) Drive Spotlight with Meta+k; click the dock by+ the BOTTOM-most `a[href="/<slug>"]` (the centre ones are the hidden Launchpad).+ `X-Content-Type-Options: nosniff` is set on all routes, so wrong MIME is fatal — keep+ static Content-Types correct.## Rules in force- **Only ONE session edits mso at a time.** One checkout, one `HEAD`, one index.@@ -201,8 +224,26 @@ to `resources/` (rr) and drive any project from one manifest:not hex, mobile-first. Barrel-only cross-slice imports.- `/api/v1` host ops go through `lib/host` (bounds + realpath checks) — never call`fs`/`child_process` straight from a route.-- Solo-dev: push direct to `main` once `bun run typecheck` + `bun run build` are green.- Conventional commits + Claude co-author.+- Solo-dev: push direct to `main` once `bun run verify` is green (typecheck + lint ++ test + check + audit). Conventional commits + Claude co-author.+- **The gates live in an UNTRACKED `.git/hooks/pre-push`**, so no commit can carry+ them and an sc-git hook reinstall silently drops them. Four guards run, ~70 s per+ push: sc-git `ci.js --skip build` (typecheck/lint/test, Guard 1), `check-cycles.mjs`+ (1b), `scripts/audit.mjs` (1c), `scripts/verify-build.sh` (1d). A fifth, Guard 2, is+ a self-hosted-Convex auto-deploy that is a silent no-op here — there is no `convex/`+ dir — so don't be surprised to find it in the file. A healthy push prints+ `audit: clean at high/critical.` and `build: HEAD compiles (out-of-tree).` — **if+ those two lines are missing, the wiring is gone.** The `--skip build` is deliberate+ safety, not laziness (see Deploy/ops). A reinstall also re-adds a+ `scripts/check-slices.mjs` line; that script was deleted, so it blocks every push.+- **`bun run audit` ≠ `bun audit`.** The script is `scripts/audit.mjs`, which wraps+ `bun audit --json` because raw `bun audit` fails CLOSED — offline it exits 1, the+ same code as a real advisory, which would turn every network blip into a fake+ security failure. It skips when the registry is unreachable, applies a high/critical+ floor, and keeps an `IGNORE` map (keyed by GHSA, with a reason and a date) for+ advisories with no upstream fix. `--json` ignores `--audit-level`/`--ignore`, so the+ filtering is done in the script. `ci.yml` runs the raw fail-closed command on+ purpose: a release gate must not pass an audit it could not perform.## CLI (`bin/mso`) — the web UI is only one frontend`bin/mso` reaches the same `/api` surface from a shell — every route has a named verbdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5397b8d1..90859219 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -15,20 +15,30 @@ without a VPS or any credentials.## Before you open a PR-A `pre-push` hook runs typecheck + lint + test + the slice/cycle checks and blocks-the push if any fail, so this checklist is mostly a description of what already-happens. `.github/workflows/ci.yml` is **manual** (`gh workflow run CI`) — run it+A `pre-push` hook blocks the push on failure, so this checklist mostly describes what+already happens. It runs four guards: typecheck + lint + test (via sc-git's `ci.js`),+`check-cycles.mjs`, `scripts/audit.mjs`, and `scripts/verify-build.sh`. Budget ~70 s+per push. `.github/workflows/ci.yml` is **manual** (`gh workflow run CI`) — run itbefore cutting a release or after touching `package.json`, `bun.lock` or`scripts/install.sh`, because a clean-checkout `bun install --frozen-lockfile` isthe one thing the local hook cannot reproduce.-- [ ] `bun run typecheck`-- [ ] `bun run lint`-- [ ] `bun run test` — vitest unit + integration (280+ tests)+Two things about that hook are easy to get wrong:++- **The hook is UNTRACKED** (`.git/hooks/pre-push`), so nothing in this repo can carry+ it. Re-running an sc-git hook installer overwrites it and silently drops the audit+ and build guards. A healthy push prints `audit: clean at high/critical.` and+ `build: HEAD compiles (out-of-tree).` — if those two lines are missing, it is gone.+- **`ci.js` is invoked with `--skip build`, on purpose.** It would run the build in+ the current directory, which on the VPS *is* `mso.service`'s WorkingDirectory, and+ `next build` deletes `distDir` before it compiles. `scripts/verify-build.sh` builds+ a throwaway copy of `HEAD` in a temp dir instead. Do not "fix" the skip.++- [ ] `bun run verify` — typecheck + lint + test + check + audit, in one command- [ ] `bun run build`-- [ ] (optional) `node scripts/check-cycles.mjs` — no value-level import cycles-- [ ] (optional) `node scripts/check-slices.mjs` — no slice-boundary violations-- [ ] (optional) `bun run smoke` — e2e smoke against a local `bun run start`+- [ ] (optional) `bash scripts/verify-build.sh` — build `HEAD` out-of-tree; safe to+ run against the prod checkout, unlike a bare `bun run build`+- [ ] (optional) `bun run smoke` — e2e smoke against a running server## Conventions (the short version)diff --git a/README.md b/README.mdindex e1c1e3fc..95bbb1d6 100644--- a/README.md+++ b/README.md@@ -215,11 +215,9 @@ bun run devQuality gates:```bash-bun run typecheck-bun run lint-bun run test-bun run check+bun run verify # typecheck + lint + test + check + auditbun run build+bash scripts/verify-build.sh # build HEAD out-of-tree — safe on the prod checkoutbash -n scripts/install.sh```diff --git a/claude-skills/mso-browser-list/SKILL.md b/claude-skills/mso-browser-list/SKILL.mdindex 5bfe8ecd..507b21f3 100644--- a/claude-skills/mso-browser-list/SKILL.md+++ b/claude-skills/mso-browser-list/SKILL.md@@ -1,15 +1,29 @@---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".+description: The RETIRED os-browser Playwright sidecar, kept only as dev tooling for e2e/desktop verification — its systemd unit is stopped and disabled, and the mso Browser app does NOT use it. For the actual Browser app use /mso-camoufox. Trigger on /mso-browser-list, "os-browser sidecar", "playwright install for e2e", "start the headless chromium service". Do NOT trigger on "why doesn't the browser work" or "browser status" — those mean Camoufox.----# /mso-browser-list — Browser app deep check+# /mso-browser-list — os-browser sidecar 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].+> ## ⚠️ This is NOT the Browser app any more+>+> The **Browser app is Camoufox** — a real anti-fingerprinting Firefox on a headless+> X display, streamed in over noVNC. Use **[/mso-camoufox]** for it.+>+> The `os-browser` Playwright sidecar described below was **retired**, and on+> **2026-08-03 its systemd unit was stopped and `disable`d** — it no longer starts at+> boot and nothing in the mso app calls it (the only remaining mentions in the code+> are comments saying it was removed). Do **not** `systemctl restart os-browser` to+> "fix the Browser"; that starts a service the app does not use.+>+> The `os-browser/` directory stays in the repo on purpose as **dev tooling** — it+> holds the repo's only Playwright install, which `scripts/e2e` and desktop/mobile+> verification use. This skill is still valid for driving THAT, if you start the+> service by hand (`sudo systemctl start os-browser`). It is not a user-facing feature.++The sidecar is a **real headless Chromium** (Playwright) on the host as systemd+`os-browser` (loopback :4002, persistent context = cookies/cache/session on disk).+Renders ANY site — no X-Frame-Options/CSP problem. Companion to [/mso] and [/mso-list].## 1. Live check (run first)@@ -17,51 +31,57 @@ the SAME session. Renders ANY site — no X-Frame-Options/CSP problem. Companionnode ~/.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`.+text length. If the service is DOWN that is now the DEFAULT (see the banner) — `sudo systemctl start os-browser` to run these checks, and stop it again after.++## 2. Drive it from CLI-## 2. Drive it from CLI (you can SEE the page)+`~/.claude/skills/mso/browser.sh` still exists, but it talks to `/api/v1/browser/*`,+and **those routes were deleted with the sidecar** — `app/api/v1/` today is+`apps camoufox editor exec fs managed-apps stock sys term`. So the CLI path below is+DEAD until/unless someone re-adds the routes. Talk to the service directly instead:```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+sudo systemctl start os-browser # it is disabled; start by hand+curl -s -H "x-os-browser-secret: $(grep -oP '(?<=^OS_BROWSER_SECRET=).*' \+ /home/rahman/projects/mso/os-browser/.env)" \+ -X POST 127.0.0.1:4002/goto -d '{"url":"https://example.com"}'+sudo systemctl stop os-browser # leave it off```-## 3. Browser functions+## 3. What still works, and what does not-| 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 |+| | Status |+|---|---|+| The service itself (Playwright Chromium, loopback :4002, secret-gated) | works when started by hand |+| `os-browser/node_modules/playwright` — the repo's ONLY Playwright | works; this is why the dir is kept |+| `scripts/e2e` + desktop/mobile verification | works (uses the Playwright install, not the service) |+| mso Browser app rendering through it | **gone** — the app is Camoufox now |+| `/api/v1/browser/*` routes | **deleted** |+| `OS_BROWSER_URL` / `OS_BROWSER_SECRET` wired into the app | **gone** — the only mention left in app code is a comment in `lib/agent/server.ts` saying it was retired |+| Bookmarks / AI Inspector / omnibar for it | **gone** with the app integration |-## 4. Architecture+## 4. Architecture (what is left)```-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)+you ──secret──▶ 127.0.0.1:4002 (systemd os-browser, DISABLED — start by hand)+ └ Playwright Chromium, one persistent context```-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`.+Service secret: `/home/rahman/projects/mso/os-browser/.env`.+Code: `/home/rahman/projects/mso/os-browser/server.mjs`.+Prod is **systemd on this box, not Dokploy** — ignore any `172.18.0.1` /+docker-bridge address in older notes; that was the Dokploy era.## 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.+- One shared page (single context) — no multi-tab.+- Chromium only. It is exactly what could NOT render sites that block automation,+ which is why the Browser app moved to Camoufox.-## 6. If blank / not working+## 6. If something is "broken"-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.+1. **Is this even the right skill?** If the user means the Browser app in mso, it is+ Camoufox → use [/mso-camoufox]. This skill cannot help with that.+2. Service not running → expected, it is `disable`d. `sudo systemctl start os-browser`+ for a one-off. **Never `enable` it** — that re-arms boot autostart.+3. e2e/Playwright failing → check `os-browser/node_modules/playwright` exists; the+ service does not need to be running for that.diff --git a/claude-skills/mso-browser-list/browser-check.js b/claude-skills/mso-browser-list/browser-check.jsindex 523da44d..6d09fe90 100644--- a/claude-skills/mso-browser-list/browser-check.js+++ b/claude-skills/mso-browser-list/browser-check.js@@ -35,5 +35,5 @@ const SITES = ["https://example.com", "https://news.ycombinator.com", "https://wconsole.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");+ console.log("\nNOTE: this service is RETIRED and its unit is disabled. The mso Browser app is Camoufox (/mso-camoufox); /api/v1/browser/* no longer exists. This dir is kept for its Playwright install, used by scripts/e2e.");})();diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.mdindex 2faa5889..0a8f5562 100644--- a/docs/DEVELOPMENT.md+++ b/docs/DEVELOPMENT.md@@ -26,8 +26,17 @@ Every feature is a self-contained **vertical slice** under `frontend/slices/<slubun run verify # typecheck + lint + test + check + audit (high/critical only)```-A **pre-push hook** runs the same CI locally and blocks the push on failure. None of-these touch `.next`, so they're safe to run against the prod checkout.+A **pre-push hook** blocks the push on failure. Four guards, ~70 s: sc-git's `ci.js`+(typecheck + lint + test), `check-cycles.mjs`, `scripts/audit.mjs`, and+`scripts/verify-build.sh`. None of them touch this checkout's `.next` — the build+guard compiles a throwaway copy of `HEAD` in a temp dir — so all of it is safe to run+against the prod checkout. A healthy push prints `audit: clean at high/critical.` and+`build: HEAD compiles (out-of-tree).`++The hook is **untracked**, so nothing in this repo can carry it: re-running an sc-git+hook installer overwrites the file and silently drops the audit and build guards (and+re-adds a `check-slices.mjs` line for a script that no longer exists, which blocks+every push). If those two lines stop appearing, the wiring is gone.## Deploy — and the build hazard ⚠️diff --git a/docs/FAQ.md b/docs/FAQ.mdindex 20293507..597c2ee7 100644--- a/docs/FAQ.md+++ b/docs/FAQ.md@@ -92,8 +92,11 @@ adds the usual browser footprint — skip it on tiny boxes.Two passes by the maintainer: `docs/AUDIT-2026-06-11.md` (initial cross-cuttingsweep — security, perf, a11y, slice boundaries) and `docs/AUDIT-2026-06-14.md`(follow-up after the first round of fixes). The score trajectory across both-passes lives in `docs/SCORECARD-2026-06-14.md`. Quality gates (typecheck, lint,-280+ vitest tests, build) run on every push via the pre-push hook.+passes lives in `docs/SCORECARD-2026-06-14.md`. A third pass on 2026-08-03 ran five+adversarially-verified lenses (over-engineering, security, Next 16/React 19,+package-manager migration, repo health) — see the top of `docs/PROGRESS.md`. Quality+gates run on every push via the pre-push hook: typecheck, lint, 1100+ vitest tests,+import-cycle check, a high/critical dependency audit, and an out-of-tree build.### Phone support?diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 5c587b44..1d00fcbf 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -8,6 +8,47 @@ Running log of what shipped each phase. Newest at top.> Read those phases as history. **This file is the source of truth for what exists** —> `ARCHITECTURE.md` is no longer maintained and carries a stale-warning banner.+## 2026-08-03 (docs) — reconciling every live doc against what the box actually does (DONE)++A sweep for claims that had quietly become false. History files (`AUDIT-*`,+`SCORECARD-*`, dated plans, this log's older entries) were left alone on purpose —+they describe what was true then. Only *live instructional* docs were touched.++What was actually wrong:++- **`.env.example` was missing 6 settable vars.** Reconciled against `process.env` in+ code: `CAMOUFOX_NOVNC_URL`, `CAMOUFOX_VNC_PASSWD_TEXT`, `OS_MEMORY_STORE`,+ `OS_THREADS_DIR`, `NEXT_PUBLIC_COMMIT_SHA`, `NEXT_DEPLOYMENT_ID`. CLAUDE.md's+ standing caveat ("it is missing several… grep `process.env`") is now a precise list+ of what stays out and why: framework-injected (`NEXT_RUNTIME`,+ `NEXT_PUBLIC_BUILD_ID`), systemd's (`NOTIFY_SOCKET`, `WATCHDOG_USEC`), the OS's+ (`PATH`, `SHELL`), test-only (`E2E_BASE_URL`, `OPENCLAW_HOME`), and `OS_BROWSER_*`,+ which belong to the retired sidecar rather than this app.+- **`CONTRIBUTING.md` told contributors to run `scripts/check-slices.mjs`** — deleted+ earlier the same day — and claimed "280+ tests" (1136). Its checklist now matches the+ four guards that really run, and warns that the hook is untracked and that+ `--skip build` is deliberate.+- **The `/mso-browser-list` skill was the worst offender.** It described `os-browser` as+ *the* Browser app, triggered on "why doesn't the browser work" and "browser status",+ and told the reader to `systemctl restart os-browser`. All false: the Browser app is+ Camoufox, the unit is stopped + `disable`d, `/api/v1/browser/*` was deleted, the+ `OS_BROWSER_URL`/`172.18.0.1` wiring is Dokploy-era (prod is systemd), and its `.env`+ path pointed at `~/projects/os-browser` instead of `~/projects/mso/os-browser`.+ Rewritten, and its `description` now explicitly routes those trigger phrases to+ `/mso-camoufox`. `browser-check.js` printed the same dead architecture line; fixed.+- **`CLAUDE.md` documented a demo that does not exist** — no `mso-demo.service`, no+ `/home/rahman/projects/mso-demo`. The `NEXT_PUBLIC_OS_DEMO=1` flag is still real; the+ second checkout and :4006 unit are not. Its verification recipe also said to drive the+ demo "via os-browser", which is doubly gone — now points at Playwright directly.+- **`docs/SLICE-CATALOG.md` listed 20 slices; there are 21** (`docs` was missing).+- `docs/FAQ.md` still advertised "280+ vitest tests" and only two audit passes.+- `os-browser/README.md` opened "headless Chromium service for the Browser app".++Every claim written in this pass was checked against the box rather than assumed —+including one of my own: I wrote "four guards" and the hook has five `# Guard` lines.+Four run; the fifth is a Convex auto-deploy that no-ops here because there is no+`convex/` dir. Said so rather than rounding.+## 2026-08-03 (later) — the two open items closed, and the health lens finds a silent way to lose the device allowlist (DONE)Clearing both items the entry below left open.diff --git a/docs/SLICE-CATALOG.md b/docs/SLICE-CATALOG.mdindex a47585c6..d63082f5 100644--- a/docs/SLICE-CATALOG.md+++ b/docs/SLICE-CATALOG.md@@ -9,7 +9,7 @@ Every OS app is a vertical slice. Slices are authored lift-ready (props-driven,hardcoded consumer URLs/env/roles). Slices read the host through the `lib/os-api`contract, served by `lib/host` (fs/exec/sys) or `MockAdapter`.-## Slices (20)+## Slices (21)| Slug | Kind | Category | Purpose ||---|---|---|---|@@ -20,6 +20,7 @@ contract, served by `lib/host` (fs/exec/sys) or `MockAdapter`.| `camoufox-browser` | full | ui | Browser — real Firefox over VNC || `code-editor` | full | ui | Code — overlay syntax editor || `create-app` | frontend | ui | Create App — author an os-rr app from a manifest |+| `docs` | frontend | ui | Docs — in-app documentation browser || `files-manager` | full | infra | Files — VPS file manager || `image-editor` | frontend | ui | Image Editor — layered raster editor || `image-picker` | ui | ui | Image Picker — one-button image/wallpaper chooser (gallery · upload · link · Unsplash · reposition) |diff --git a/os-browser/README.md b/os-browser/README.mdindex 2aeaeecc..4fbfc2e8 100644--- a/os-browser/README.md+++ b/os-browser/README.md@@ -1,12 +1,25 @@-# os-browser — headless Chromium service for the Browser app--A tiny HTTP wrapper around a REAL Playwright Chromium running on the VPS.-The mso Browser app proxies to it server-to-server, so any site renders-(no `X-Frame-Options` problem — it's a browser, not an iframe). One+# os-browser — RETIRED sidecar, kept for its Playwright install++> **This is no longer the Browser app.** The Browser app is **Camoufox** — a real+> anti-fingerprinting Firefox on a headless X display, streamed in over noVNC and+> gated in `proxy.ts` by the same verified-session check that guards `/api/v1/exec`.+> Chromium-behind-a-screenshot could not get past sites that block automation, which+> is exactly why it was replaced.+>+> What that means concretely, as of **2026-08-03**:+> - The `os-browser` systemd unit is **stopped and `disable`d** — it does not start at boot.+> - The `/api/v1/browser/*` routes it proxied through **no longer exist**.+> - No app code calls it; the only mention left is a comment in `lib/agent/server.ts`+> recording that the bridge was retired.+>+> **This directory is kept on purpose anyway**: `os-browser/node_modules` holds the+> repo's ONLY Playwright install, which `scripts/e2e` and desktop/mobile verification+> use. Deleting it breaks those until reinstalled. The service below still runs if you+> start it by hand — just never `enable` it.++A tiny HTTP wrapper around a REAL Playwright Chromium running on the VPS. Onepersistent profile (`~/.mso/chrome-profile`) keeps logins across restarts.-Optional: without it, every other mso app still works.-## Run```bash