`, NOT the viewport** — snap/maximize geometry must use `workArea()` (section-relative: `top=GAP`, `bottom=vh-TOPBAR-DOCK_RESERVE`), the drag snap preview must be `position:absolute` (shares the surface), and drag commits must use `offsetLeft/offsetTop`, never viewport `getBoundingClientRect`. - **`window-content.tsx` loads app bundles with `useState`/`useEffect`, NOT `React.lazy`+`Suspense`.** Window opens come from the synchronous external store (`useSyncExternalStore`); a Suspense boundary suspending in that path misses its retry ping — the chunk resolves but the spinner only clears on the next render (a click). A `setState` on import-resolve always re-renders. Don't reintroduce Suspense here. Dock hover warms the chunk (`app.load()`), so it stays instant. - **Dock = macOS behaviour**: clicking a running app focuses its front window (`focusApp`, never spawns); hovering shows its open windows to switch + a "New Window" entry for `multi` apps. Opening surfaces (Launchpad/Spotlight) spawn. - **`ShellCapabilities`** is the injection seam: `useAppearance`, `useCpuPercent`, `useSearch`→`SearchHit[]`, `useSystemStats`, `useChat`, `useServerToggle`. Defaults merged in `CapabilitiesProvider` so optional caps degrade (accessors stay unconditional). Add an app = manifest edit; add a shell feature = new `appshell/features//` + `defineFeature` + add to `DEFAULT_FEATURES`. No surface edits (open/closed). ## Routing — the OS is addressable (keep windowing!) - ONE catch-all route `app/[[...slug]]/page.tsx` (no per-app pages). Windowing is untouched; only the **focused** app + its launch path is mirrored to the URL (`/files/home/user`, `/code`). `appshell` `UrlSync` does it. - **URL writes use the History API, NOT `router.push`.** Opening a window is pure client state — `router.push` triggers a full RSC transition + remount (slow, flashy + breaks the sync). Use `window.history.push/replaceState`; Next 16 syncs `usePathname`. Deep links / ⌘-middle-click `` / back-forward still navigate. - App URL slugs are assigned centrally in `shell.manifest.ts` (`AppDescriptor.slug`, falls back to `id`); app slices stay URL-agnostic. Dock + Launchpad use `` with **`prefetch={false}`** — MANDATORY: left-click is intercepted (never navigates), so default prefetch would fire one RSC render of the dynamic catch-all per link (24 on load) and peg the VPS. The href is only for middle/⌘-click. Never drop it. - The catch-all **must `notFound()` reserved paths** (`slug[0]==="_next"`): otherwise a missing `/_next/static/*` chunk falls through and returns the app HTML with 200 → wrong-MIME refusal, no recovery. 404 lets the client router hard-reload onto the new build. - `next/Image` ONLY where the optimizer helps (browser favicons via the fixed Google s2 host in `next.config` `images.remotePatterns`). Host-fs images + the live Playwright screenshot stream stay raw `` on purpose (dynamic/auth'd bytes). ## Deploy / ops (instance-derived, not source-hardcoded) - `mso.service` normally serves the current installed checkout on :4005. Resolve its actual `WorkingDirectory` from the service unit and its browser origin from `OS_PUBLIC_ORIGIN`; never copy a maintainer home path, hostname, or sibling app domain into portable source. - Optional demo/review runtimes are installation-owned and must remain mock-only, loopback-bound unless explicitly published, and outside the canonical checkout. Discover their actual service unit/worktree instead of assuming a user or path. - **Deploy prod:** use `bun run ship ""`. It regenerates the derived changelog, runs committed pre-push gates/out-of-tree build, pushes the exact SHA, then finalizes the supported service replacement/chunk verification. Through MSO/MCP, finalization runs in `mso-self-update.service`; completion is proven only when the log ends `UPDATE OK`. Operator update/recovery is Settings → Update MSO or `mso update [--rebuild]`. Do not use a bare in-place build merely to verify code. - **Service worker** is served from `app/api/sw/route.ts` with a `beforeFiles` rewrite `/sw.js`→`/api/sw`. It caches only icons+manifest, never chunks/HTML, and bakes `BUILD_ID` into its cache name so browser clients detect a new deployment. - **New routes need a clean build.** On a live production checkout use `mso deploy`; for verification use `mso build`. Never remove/replace a live `.next`. - **`bun run build` is fail-closed on a live checkout.** Use `mso build` for the out-of-tree compile proof and `mso deploy` for a production rebuild. Raw `next build` is an internal deploy primitive only after the supported lifecycle has quiesced the runtime. - **The Browser app powers a systemd USER unit** whose `ExecStart` points at `scripts/camoufox-vnc-service` in this repo. The script discovers the current user-local Camoufox executable unless `CAMOUFOX_BROWSER` explicitly overrides it. - For browser verification, discover an available authenticated/local or mock-only endpoint from the current installation; do not encode an operator hostname or home path into tests. ## Pull request readiness Follow the cross-agent hard gate in [`AGENTS.md`](./AGENTS.md#pull-request-readiness-mandatory-for-all-coding-agents). Use `bun run pr:local` before pushing a committed task branch and `bun run pr:security` for pinned CI scanner parity where Docker is available. If either is missing/failed, keep the PR in **Draft** and explicitly record the blocker. CodeQL and review-thread clearance are GitHub-side gates after PR creation; a local green run cannot supersede them. Never bypass branch rules. ## Rules in force - **One canonical checkout; parallel work only through isolated hidden worktrees.** The canonical `main` checkout is a **release/integration surface, not an agent scratchpad**. Automated source-changing work must happen in a task-owned hidden worktree; if canonical is dirty with another session's work, stop and preserve it rather than stashing, resetting, committing, merging or overwriting on that session's behalf. Only a release/integration step may advance canonical after the candidate and concurrent work are independently preserved and verified. the current `git rev-parse --show-toplevel` checkout on `main` is the canonical release SSOT. Never create task-specific `mso-*` siblings under `~/projects` and never let two sessions share one worktree, `HEAD`, or index. If parallel work is necessary, use one Git worktree per task under `~/.cache/mso-worktrees/mso-`. Never put a development checkout under `~/.mso`: host-file security deliberately treats that entire tree as private state. The older one-checkout rule existed because shared-index sessions repeatedly wiped/bundled each other's work; isolated worktrees solve that collision without creating another source of truth. A worktree is development-only: preserve its tracked/untracked WIP, reconcile every user-deliverable commit into `main`, verify there, and ship through `bun run ship`. Do not call a feature shipped while it exists only in a worktree/feature branch; the installer and updater intentionally deliver only `origin/main`. Never prune a dirty worktree until its intended work is committed/archived and accounted for. - Max 200 lines/file, single responsibility, shadcn primitives only, theme tokens 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. - Autonomous coding agents must use isolated task branches and PR review, never push directly to `main`. Human-owned release integration still uses the verified `bun run ship` path after review. Conventional commits + Claude co-author. - **The gates live in `scripts/gates.sh`, which IS committed.** `.git/hooks/pre-push` is a one-line shim that execs it; reinstall with `bash scripts/gates.sh --install`. They used to live in the untracked hook itself, which meant a fresh clone had NO gates and an sc-git hook reinstall silently dropped the audit + build guards while re-adding a `check-slices.mjs` line for a script deleted on 2026-08-03. Four guards run the repository-owned `bun run verify`, cycle/docs/changelog checks, the local strict high/critical audit, and `scripts/verify-build.sh`. There is no external sc-git runner and no Convex auto-deploy tail. Hook installation resolves Git's hook path, including linked worktrees. Build verification stays out-of-tree; never bypass gates. - **`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. `bun run audit:strict` fails closed on unavailable, malformed or incomplete evidence and is mandatory inside `security:ultimate`. CI also runs the raw fail-closed command: an incomplete audit is never a security pass. - **`bun run test:features` runs test areas separately.** PASS requires executed tests; PARTIAL/SKIPPED evidence exits 2 and is listed explicitly. This is unit/integration coverage, not proof that every UI workflow or third-party integration works. ## MCP server (`/mcp`) — optional, OFF by default An MCP endpoint so ChatGPT / Claude.ai / Cursor can drive the host. `lib/mcp/*` includes OAuth/PKCE/store/scope, read/discovery/learning/power/write tool catalogs, toolset metadata, workflow activity and dispatch; routes live under `/mcp`, `/oauth/*` and `/.well-known/oauth-*`. **`OS_MCP_ENABLED=1` or every one of those routes 404s** — that is the kill switch, and demo mode forces it off. Read `docs/MCP.md`; for ChatGPT setup/diagrams use `docs/CHATGPT-PLUGIN.md`. Implementation changes must also follow `docs/MCP-FEATURE-IMPLEMENTATION.md`; inspect the real runtime and working analogue before changing a tool or skill contract. - **`/mcp` is deliberately NOT under `/api`.** `proxy.ts` blocks mutating `/api` that cannot prove same-origin and an MCP client is cross-origin by definition; the bearer is the control, not the CSRF gate. `proxy.ts` exempts `/mcp`, `/oauth/token`, `/oauth/register` and `/.well-known/oauth-*` from BOTH that gate and the document CSP. `/oauth/authorize` is NOT exempt — it is a real HTML page and needs its nonce. - **Tool execution is transport-neutral.** `lib/capabilities/*` owns scope, required-argument validation, workflow correlation, rate limits, audit/activity and execution semantics. MCP/A2A/agent surfaces are adapters over that kernel. Host operations flow through narrow `lib/host/*-api.ts` facades, which preserve `OS_FS_*_ROOTS`, the credential denylist (including `~/.mso`) and destructive-command guards. Do not reimplement a guarded host operation inside an adapter. - Scope ladder `read < write < exec`, picked per token on the consent page, capped by `OS_MCP_MAX_SCOPE`. The default ceiling is `exec`, and consent preselects the highest permitted tier; set the env to `read` or `write` to opt down. `tools/list` filters by it AND `tools/call` re-checks it — a client can call a name it was never shown. - **Tool names are an MSO public API contract.** Keep global names MSO-owned and generic. Project-owned MCP names are data behind `project_mcp_tools` / `project_mcp_call`; never copy them into the global catalog. The exact full MSO catalog **and** compact ChatGPT profile are source-generated in [`docs/generated/MCP-CATALOG.md`](./docs/generated/MCP-CATALOG.md); `GET /mcp` remains the live version/hash authority. Hidden ChatGPT-profile names are rejected at call time, not merely omitted from `tools/list`. - Store is `~/.mso/mcp.json`, **sha256 only**, same atomic-write + fail-loud-on-corrupt rule as `lib/auth/device-store.ts`. Codes are single-use, 60 s, deleted BEFORE the token is minted. `browser_status` must never return the VNC password — that profile holds a live Google session. - **The capability kernel writes the audit trail, because model-facing tools bypass route-layer audit.** `/api/v1` routes audit at the route layer; capability tools may call guarded host APIs directly, so `lib/capabilities/execute.ts` enforces scope/rate/workflow telemetry and records declared `CapabilityTool.audit` actions once for MCP/A2A/agent adapters. MCP uses `actor: mcp:` and `meta.via = "mcp"`; scope refusals log `mcp.denied`. Reads stay unlogged, same rule the routes follow. `GET /api/v1/sys/audit` reads it (session-gated); there is deliberately **no MCP tool** for it, or a compromised token could check whether it had been noticed. ## Install/update requests from an AI agent When a user points an agent at this repository and asks to install or update MSO, the agent must use `scripts/install.sh` / `mso update`, not hand-roll a competing setup. The installer is also the backward- compatible bridge for old installations that predate `mso update` and Settings → Update MSO: it detects the active service checkout, preserves `.env.local` + `~/.mso`, and updates in place. Never create a second install beside an owned service or reset dirty/diverged source. End with `mso doctor` and health proof. Credential prompts remain hidden/STDIN; tell the user where to create/store a required key, never put it on argv or in an agent transcript. ## 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 (enforced by a test in `bin/mso.test.ts`), plus `doctor`, `completion` and `--base`. `scripts/install.sh` verifies and launches `scripts/install-core.sh`; the core symlinks it to `~/.local/bin/mso` and symlinks `claude-skills/*` into `~/.claude/skills/` (every committed directory under `claude-skills/`, including `/mso-skill-authoring`). `mso -h` lists every verb; `mso api [json]` is the escape hatch for anything without a named verb. - **Every CLI caller must send `Origin: `.** `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`, `device role`, `service`, `build`) can use the private device store/systemd directly where documented, so recovery still works while the service is down. ## Local dev ```bash bun install cp .env.example .env.local # set OS_LOGIN_PASSWORD + OS_SESSION_SECRET bun run typecheck bun run dev # OS desktop at :3000 (mock data by default) node scripts/approve-device.js "my device" --role owner # bootstrap login ``` ## Package manager: bun installs, Node runs (migrated from pnpm 2026-08-03) `bun.lock` is committed; `pnpm-lock.yaml` is gone. **The runtime did NOT migrate** — `.nvmrc`/`engines.node` still pin Node 22 and prod's `ExecStart` is still `/usr/bin/npm run start`. `next`/`tsc`/`eslint`/`vitest` carry `#!/usr/bin/env node` shebangs, which `bun run` honours, so every tool still executes under Node. - **`bun run test`, NEVER `bun test`.** The builtin runner shadows the script, ignores `vitest.config.mts`, and exits 0 having run nothing — `verify` goes green testing zero files. Same trap in `.github/workflows/ci.yml`. - **`node-pty` must stay in `trustedDependencies`.** No Linux prebuild → it compiles at install; bun skips lifecycle scripts for untrusted packages. It loads eagerly through `lib/host/pty.ts` → `lib/host/index.ts`, which every `/api/v1` route imports, so a skipped build breaks the whole host API, not just Terminal. After ANY dependency change: `node -e "require('node-pty')"` before building. - **Never `bunx`/`bun x` in a deploy or CI script** — unlike `pnpm exec` it downloads a missing package and runs it. Call `node_modules/.bin/` directly. - `unrs-resolver`/`protobufjs` postinstalls stay blocked (both work from prebuilt binaries). Don't "fix" the `bun pm untrusted` warning. `sharp` used to be a third entry here; 0.35 dropped its install script, so it no longer appears at all. - `lib/host/cleanup.ts`'s pnpm-store card stays — other repos on this box still use it. ## antislop UI, copy, people, mobile layout, and code-comment work is filtered by antislop before it ships. - Core filter, read first: `antislop` skill - UI and visual: `antislop-ui` - Copy and text: `antislop-copywriting` - People, contrast, keyboard: `antislop-human` - Mobile and responsive: `antislop-layoutmobile` - Code comments: `antislop-code` Hard gates that already apply to this repo, so a review will reject a change that breaks them: - No em dash in user-visible strings. Comments and docs are out of scope. - No fabricated numbers, testimonials, or security claims. - Every interactive element has real behaviour; no dead controls. - Text meets WCAG AA contrast; the repo gate is `node scripts/check-contrast.mjs`. - Both shipped themes must work. Design direction lives in `DESIGN.md`. Read it before any UI work. If it is absent, say so and treat the result as a draft without direction. If a rule and a task conflict, name the rule and ask. Do not silently override either one.