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.

docs: reconcile every live doc against what the box actually does

Rahmanbf7b94a38d04
diff --git a/.env.example b/.env.example
index 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 /api
diff --git a/CLAUDE.md b/CLAUDE.md
index 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/` is
history 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 — it
still describes a retired Playwright browser sidecar, a managed-app "single-origin
mode" 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 Playwright
screenshot 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`. ALWAYS
build-then-restart, never the reverse, and never rebuild again after restarting
without 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` and
check `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 verb
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 it
before cutting a release or after touching `package.json`, `bun.lock` or
`scripts/install.sh`, because a clean-checkout `bun install --frozen-lockfile` is
the 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.md
index e1c1e3fc..95bbb1d6 100644
--- a/README.md
+++ b/README.md
@@ -215,11 +215,9 @@ bun run dev
Quality gates:
```bash
-bun run typecheck
-bun run lint
-bun run test
-bun run check
+bun run verify # typecheck + lint + test + check + audit
bun run build
+bash scripts/verify-build.sh # build HEAD out-of-tree — safe on the prod checkout
bash -n scripts/install.sh
```
diff --git a/claude-skills/mso-browser-list/SKILL.md b/claude-skills/mso-browser-list/SKILL.md
index 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. Companion
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`.
+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.js
index 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://w
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");
+ 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.md
index 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/<slu
bun 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.md
index 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-cutting
sweep — 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.md
index 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.md
index 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.md
index 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. One
persistent profile (`~/.mso/chrome-profile`) keeps logins across restarts.
-Optional: without it, every other mso app still works.
-
## Run
```bash