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.
mso (product name: MSO)
Mobile-first web cockpit for a headless VPS, from any browser. Desktop-style UI
metaphor over a vertical-slice stack; value is utility (terminal/files/monitor/
browser), not an OS. Repo/service/domain keep the mso slug; "MSO" is the
UI brand. Self-contained: a single Next.js app, no database, no external
agent — it runs AS a host process and controls its own machine.
- Stack: Next 16 (App Router) · React 19 · Tailwind 4 · shadcn/ui · TypeScript.
No
middleware.ts—proxy.ts(Next 16 rename). - Auth: password + device approval → HMAC signed-cookie session plus live
Viewer/Operator/Owner role (
lib/auth/). No Convex, no Clerk; roles are device-scoped over one Unix service account, not named-user SSO. - Host access:
lib/host/does fs/exec/sys directly (Nodefs+child_process), bounded byOS_FS_READ_ROOTS/OS_FS_WRITE_ROOTS. - Layout:
app/+frontend/slices/<slug>/; barrel-only cross-slice imports (@/features/<slug>).
Read first
docs/PROGRESS.md— source of truth for historical WHY, newest entry first. Current code and the current-reference documents classified bydocs/README.mddefine what exists now; dated audits/plans may intentionally preserve obsolete details.README.md— what it is, features, security model, quickstart..env.example— every var you can actually set. Reconciled againstprocess.envin code on 2026-08-03 (Camoufox, memory/threads paths,NEXT_DEPLOYMENT_ID,NEXT_PUBLIC_COMMIT_SHAwere 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 bynext.config), systemd's (NOTIFY_SOCKET,WATCHDOG_USEC), the OS's (PATH,SHELL), test-only ones (E2E_BASE_URL,OPENCLAW_HOME), andOS_BROWSER_*, which belong to the retiredos-browser/sidecar and not to this app. Still grepprocess.envbefore adding a new one.- The code wins over any doc.
docs/README.mdclassifies the doc set. Current reference docs (includingdocs/ARCHITECTURE.md) must trackmain; dated audits/plans are explicitly historical and may preserve obsolete implementation details only inside that historical context. docs/FRONTEND-CONTRACT.md— required for every frontend, state and responsive change, including native DOM surfaces; shell → feature → UI-kit ownership, action semantics, accessibility, state lifetimes and per-feature evidence.frontend/slices/assistant/CONTRACT.md— current, and authoritative for what an Agent / Tool / Skill / Playbook is and what reaches the model.docs/MCP-FEATURE-IMPLEMENTATION.md— stepwise observe/map/bound/reverse-engineer/ verify playbook for MCP tools, trusted skills and project capabilities.
The doc set, and the one rule. docs/README.md is the map. docs/PROGRESS.md is
the SSOT for historical WHY; current reference docs describe today's contracts; dated
plans/audits are historical. Append to PROGRESS when you ship — do not start a second
HAND-WRITTEN log. (docs/CHANGELOG.md was exactly that once and was merged
back in; the root progress.md is gitignored local scratch and claims authority it
does not have.) docs/CHANGELOG.md exists again as of 2026-08-11 but is generated
from git subjects by scripts/gen-changelog.mjs and gated stale-by-gates.sh, so
there is nothing to keep in sync and no way for it to disagree with history. PROGRESS
is the WHY; CHANGELOG is the WHAT, and it is what Settings → Account → About renders as
"What's new" so a shipped change is visible in the running app.
Comparison is generated policy, not hand-written marketing. Edit only
docs/comparison-data.json, then run node scripts/gen-comparison.mjs. The generator owns the
short README reference and full docs/COMPARISON.md, requires an existing repo evidence path for each MSO cell,
restricts competitor sources to reviewed official hosts, requires the SEO-readable words Strong,
Partial, and Not offered rather than icon-only status legends, and expires review after 90 days.
Do not raise a rating because a feature is planned; implementation evidence must land first.
Service Center never becomes a shell-shaped button collection. Inventory is Viewer, bounded
journal is Operator, and lifecycle is Operator plus an exact OS_SERVICE_CONTROL_UNITS match. Unit
names/actions are fixed argv and wildcards are rejected. Package visibility is cache-only and has no
apply action. New network/storage/user/firewall modules need their own typed policy and tests.
New workflow skills use bun run skill:new, then bun run skill:check. The source template is templates/mso-skill-flow/SKILL.md.template; do not hand-copy an untrusted skill into the official root.
Systematic implementation is the default. Resolve the canonical source and running target;
reproduce before editing; map the end-to-end pattern and every relevant limit; compare a working
analogue; run one discriminating experiment at a time; make the smallest reversible change; then
verify targeted contract, build, runtime and browser/client state. Do not repeatedly retry the same
failed operation, edit temporary/generated copies, or claim completion from a zero exit code. For
MCP features use docs/MCP-FEATURE-IMPLEMENTATION.md and the
mso-mcp-feature-engineering skill; tool name/schema/scope/audit/parity/toolset/client refresh and
skill trust/routing are one release contract.
Shipping is bun run ship "<conventional commit>", not git push. Prod is
systemd with NO webhook, so a pushed commit changes nothing the owner can see until
someone rebuilds. The script does changelog → commit+push (gates run) → build →
restart → and then verifies the served CSS chunk actually resolves. When invoked
through MSO/MCP, it automatically hands build/restart/verification to the owner
mso-self-update.service transient user unit after the gated push: replacing
mso.service kills every process in its cgroup, including nohup children and the
MCP call itself. Poll systemctl --user is-active mso-self-update.service and
~/.mso/self-update.log; do not treat the handoff call returning as deployment
completion. An SSH invocation remains synchronous. Order is load-bearing: the
changelog is derived, so regenerating it AFTER the commit leaves it one commit behind
forever; and build-then-restart, never the reverse.
Deleted 2026-07-28 as dead: SHELL-INTEGRATION-PLAN.md and SYNC-PLAN.md (both target
sibling repos that do not exist on this machine), browser-agent-plan.md (the retired
Playwright sidecar), SIXFIX-PLAN.md (a finished dated fix list). Nothing linked to any
of them. Deleted 2026-07-30 in the same spirit: PLAN.md (the "master plan" — every
section contradicted by shipped code, and its one unique asset, a legacy-dashboard-vs-MSO
table, is descriptive rather than decision-carrying) and MULTISHELL-PLAN.md (its sibling
repo is gone, all six phases are checked off, and PROGRESS.md:574 reverses its one unique
decision). Both recoverable with git show bccd0b1:docs/<name>. Deleted 2026-08-10
(git show 421ab7f:docs/<name>): IOS-PARITY-REFACTOR-PLAN.md (every phase ✅, and the
mock-os/ tree it refactored toward no longer exists), DESIGN-RECONCILE.md (self-labelled
ARCHIVE, same missing tree), MOBILE-RESPONSIVE-PLAN.md (phases 1–4 shipped; phase 5 is the
Playwright verification chore already described below), SHELL-LAYOUT-KIT.md (documented
AppHeader/AppInspector, both deleted the same day), and AUDIT-2026-06-14.md +
SCORECARD-2026-06-14.md (every row shipped or gone stale — one cites an /api/v1/browser
route that does not exist and a coverage install that already happened). AUDIT-2026-06-11.md
STAYS — five source comments cite its findings by number. SHELL-FIDELITY-PLAN.md and
DRAWER-MENU-BYOK-PLAN.md also stay: both look finished and are not, each carrying an
unstarted tail (phases D–F, and providers D2–D4). PROGRESS.md's pre-2026-06-15 tail (34
entries) was trimmed the same day; it is one git show away.
Architecture
browser ──https──> mso (Next.js :4005) ──── lib/host → Node fs/child_process (host)
signed-cookie auth (lib/auth)
The Browser app is Camoufox — a real anti-fingerprinting Firefox on a headless
X display on this host, streamed over noVNC from the reserved split-origin host
camoufox.<managed-app-domain>. proxy.ts requires a live Operator/Owner device role,
strips cockpit credentials before loopback noVNC, and permanently 404s the retired
same-origin /camoufox-vnc/* path. It replaced BOTH the old Playwright sidecar
(os-browser, :4002, retired) and the sandboxed-iframe browser that briefly followed it—an
iframe cannot render most of the web because X-Frame-Options refuses framing on many sites.
os-browser/ stays in-repo only as dev tooling (scripts/e2e use its Playwright
install). See the Browser/camoufox note further down for the systemd user unit.
/api/v1/*= the host API (fs/exec/sys/term/apps/camoufox/managed-apps), every route resolves the live device role first. Only explicitly listed reads are Viewer; every unclassified route fails up to Owner. Operator exceptions must be explicit and bounded. There is no/api/v1/browser. Client picks mock (default) vs live in Settings → Server./api/auth/*= login/logout/me/devices./api/config= BYOK AI key.- Persistence is local: window layout + app registry in localStorage; device
allowlist + config in
~/.mso/*.json.
AppShell framework (the shell is generic + rr-liftable)
The shell is NOT one slice. It is split so the whole desktop+mobile shell can lift
to resources/ (rr) and drive any project from one manifest:
frontend/slices/appshell/— the generic, brand-free framework: window runtime- desktop/mobile surfaces, app/feature/brand registries,
<Slot region>,ResponsiveProvider/useResponsive+ the 4 DRY primitives, the pub/sub buses (toast/activity/inspector), and<AppShell manifest>(the one entry point). It imports NO brand/feature and NO mso@/lib/*— only the universal@/lib/utils(cn). Everything project-specific arrives viamanifest.capabilities.
- desktop/mobile surfaces, app/feature/brand registries,
appshell/features/currently contains 10 directories:clipboard,control-center,desktop-icons,force-quit,inspector,lock-screen,notifications,search,shortcut-help,widgets.desktop-iconsandforce-quitare shell infrastructure rather than normal slot features. Keepdocs/SLICE-CATALOG.mdand the machine-checked count in sync with the directory tree. (shell-settingsstays a flat UI-primitives slice — not an AppShell feature directory.)os-shell— the thin mso consumer:shell.manifest.ts(MSO brand + app list + slugs + features) +capabilities.ts(adapts@/lib/appearance+os-api+ai/streamtoShellCapabilities) + a re-export barrel (@/features/os-shellre-exports appshell verbatim, so all app slices stay unedited).- Windowing (
appshell/lib/store.ts):openWindow(app,title,size,payload,{multi}). Default = single instance per app (reuse/focus);AppDescriptor.multi(e.g. Files) spawns a fresh window each open.focusApp(id)reveals the front-most existing window without spawning — used byUrlSyncso deep-links/back-forward don't duplicate a multi app. Window coords (win.x/y) are relative to the desktop<section top-[30px]>, NOT the viewport — snap/maximize geometry must useworkArea()(section-relative:top=GAP,bottom=vh-TOPBAR-DOCK_RESERVE), the drag snap preview must beposition:absolute(shares the surface), and drag commits must useoffsetLeft/offsetTop, never viewportgetBoundingClientRect. window-content.tsxloads app bundles withuseState/useEffect, NOTReact.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). AsetStateon 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 formultiapps. Opening surfaces (Launchpad/Spotlight) spawn. ShellCapabilitiesis the injection seam:useAppearance,useCpuPercent,useSearch→SearchHit[],useSystemStats,useChat,useServerToggle. Defaults merged inCapabilitiesProviderso optional caps degrade (accessors stay unconditional). Add an app = manifest edit; add a shell feature = newappshell/features/<feat>/+defineFeature+ add toDEFAULT_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).appshellUrlSyncdoes it. - URL writes use the History API, NOT
router.push. Opening a window is pure client state —router.pushtriggers a full RSC transition + remount (slow, flashy- breaks the sync). Use
window.history.push/replaceState; Next 16 syncsusePathname. Deep links / ⌘-middle-click<Link>/ back-forward still navigate.
- breaks the sync). Use
- App URL slugs are assigned centrally in
shell.manifest.ts(AppDescriptor.slug, falls back toid); app slices stay URL-agnostic. Dock + Launchpad use<Link href>withprefetch={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/ImageONLY where the optimizer helps (browser favicons via the fixed Google s2 host innext.configimages.remotePatterns). Host-fs images + the live Playwright screenshot stream stay raw<img>on purpose (dynamic/auth'd bytes).
Deploy / ops (instance-derived, not source-hardcoded)
mso.servicenormally serves the current installed checkout on :4005. Resolve its actualWorkingDirectoryfrom the service unit and its browser origin fromOS_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 "<conventional commit>". 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 inmso-self-update.service; completion is proven only when the log endsUPDATE OK. Operator update/recovery is Settings → Update MSO ormso update [--rebuild]. Do not use a bare in-place build merely to verify code. - Service worker is served from
app/api/sw/route.tswith abeforeFilesrewrite/sw.js→/api/sw. It caches only icons+manifest, never chunks/HTML, and bakesBUILD_IDinto 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 usemso build. Never remove/replace a live.next. bun run buildis fail-closed on a live checkout. Usemso buildfor the out-of-tree compile proof andmso deployfor a production rebuild. Rawnext buildis an internal deploy primitive only after the supported lifecycle has quiesced the runtime.- The Browser app powers a systemd USER unit whose
ExecStartpoints atscripts/camoufox-vnc-servicein this repo. The script discovers the current user-local Camoufox executable unlessCAMOUFOX_BROWSERexplicitly 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.
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
maincheckout 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 currentgit rev-parse --show-toplevelcheckout onmainis the canonical release SSOT. Never create task-specificmso-*siblings under~/projectsand 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-<task>. 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 intomain, verify there, and ship throughbun run ship. Do not call a feature shipped while it exists only in a worktree/feature branch; the installer and updater intentionally deliver onlyorigin/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/v1host ops go throughlib/host(bounds + realpath checks) — never callfs/child_processstraight 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 verifiedbun run shippath after review. Conventional commits + Claude co-author. - The gates live in
scripts/gates.sh, which IS committed..git/hooks/pre-pushis a one-line shim that execs it; reinstall withbash 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 acheck-slices.mjsline for a script deleted on 2026-08-03. Four guards run the repository-ownedbun run verify, cycle/docs/changelog checks, the local strict high/critical audit, andscripts/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 isscripts/audit.mjs, which wrapsbun audit --jsonbecause rawbun auditfails 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 anIGNOREmap (keyed by GHSA, with a reason and a date) for advisories with no upstream fix.--jsonignores--audit-level/--ignore, so the filtering is done in the script.bun run audit:strictfails closed on unavailable, malformed or incomplete evidence and is mandatory insidesecurity:ultimate. CI also runs the raw fail-closed command: an incomplete audit is never a security pass.bun run test:featuresruns 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.
/mcpis deliberately NOT under/api.proxy.tsblocks mutating/apithat cannot prove same-origin and an MCP client is cross-origin by definition; the bearer is the control, not the CSRF gate.proxy.tsexempts/mcp,/oauth/token,/oauth/registerand/.well-known/oauth-*from BOTH that gate and the document CSP./oauth/authorizeis 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 narrowlib/host/*-api.tsfacades, which preserveOS_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 byOS_MCP_MAX_SCOPE. The default ceiling isexec, and consent preselects the highest permitted tier; set the env toreadorwriteto opt down.tools/listfilters by it ANDtools/callre-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 indocs/generated/MCP-CATALOG.md;GET /mcpremains the live version/hash authority. Hidden ChatGPT-profile names are rejected at call time, not merely omitted fromtools/list. - Store is
~/.mso/mcp.json, sha256 only, same atomic-write + fail-loud-on-corrupt rule aslib/auth/device-store.ts. Codes are single-use, 60 s, deleted BEFORE the token is minted.browser_statusmust 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/v1routes audit at the route layer; capability tools may call guarded host APIs directly, solib/capabilities/execute.tsenforces scope/rate/workflow telemetry and records declaredCapabilityTool.auditactions once for MCP/A2A/agent adapters. MCP usesactor: mcp:<id>andmeta.via = "mcp"; scope refusals logmcp.denied. Reads stay unlogged, same rule the routes follow.GET /api/v1/sys/auditreads 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 <METHOD> <path> [json] is
the escape hatch for anything without a named verb.
- Every CLI caller must send
Origin: <base>.proxy.tsblocks mutating/apithat cannot prove same-origin; a browser proves it withSec-Fetch-Site, and the documented fallback is anOriginwhose host matchesHost. Without it login itself 403scross_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 withmso approve $(cat ~/.mso/cli.device.id)).audit.jsandimage-editor.shread 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
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 <deviceId> "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, NEVERbun test. The builtin runner shadows the script, ignoresvitest.config.mts, and exits 0 having run nothing —verifygoes green testing zero files. Same trap in.github/workflows/ci.yml.node-ptymust stay intrustedDependencies. No Linux prebuild → it compiles at install; bun skips lifecycle scripts for untrusted packages. It loads eagerly throughlib/host/pty.ts→lib/host/index.ts, which every/api/v1route 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 xin a deploy or CI script — unlikepnpm execit downloads a missing package and runs it. Callnode_modules/.bin/<tool>directly. unrs-resolver/protobufjspostinstalls stay blocked (both work from prebuilt binaries). Don't "fix" thebun pm untrustedwarning.sharpused 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:
antislopskill - 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.