Agent guide — ZCode

You are working on ZCode, a dual-mode VS Code OSS browser IDE (repo may still be named code-server).

Read first

PLAN.md — architecture diagrams, done / in progress / remaining, next queue, invariants
RESUME.md — paste-ready agent handoff / resume prompt
README.md — how to run
docs/design-dual-mode-vscode-ide.md — full design RFC

Brand: ZCode · CLI: zcode · not affiliated with coder/code-server
UI always in the browser; dual-mode = remoteAuthority / EH / providers, not a custom editor RPC
Browser git needs stateless /git-proxy (CORS); not a control plane
Primary IDE: / (VS Code Web). Debug SPA /debug/ = dogfood only (off when NODE_ENV=production).

pnpm dev

Full bootstrap in one shot: pnpm install (if needed) → fetch vscode-web/themes → turbo build → serve (ZCODE_COI=1).

Product IDE: http://127.0.0.1:5000/
Debug SPA: http://127.0.0.1:5000/debug/ (DEV only)
Shells: Command Palette → ZCode: Open Browser Shell / WebContainer / Pyodide REPL
Fast restart: pnpm dev:fast · force re-fetch assets: pnpm dev:refresh

See PLAN.md §5. M0d–M2, R2c/R6, H3 runbook, SA0–SA2 (server-agnostic ADRs) done on this path.

Repo: https://github.com/spinupdev/zcode
North star: IDE without required server (same-origin remote optional; WASM Run in browser)
Next: WB1 Pyodide runtime · RA1/RA2 zcode-remote Tier 1 attach · finish RA0 spike · WB2 Node WASM
(ops: CI PTY hard-fail, CF domain, OPFS dual-open, H5 — parallel)
ADRs: docs/adr/0001-server-agnostic-ide.md, docs/adr/0002-browser-remote-workspace-sync.md
Rebuild owned assets: Node 24 + GITHUB_TOKEN + ./scripts/build-web.sh --package / ./scripts/build-server.sh
R6: pnpm e2e:reh · STRICT: ZCODE_E2E_REH_STRICT=1 pnpm e2e:reh · PTY hard-fail: ZCODE_E2E_REH_PTY_REQUIRED=1
Docker: pnpm docker:build · Hosting: pnpm hosting:dry-run · Deploy: pnpm deploy:cloudflare

pnpm test
pnpm e2e:browser
pnpm e2e:playwright   # needs Chromium: pnpm --filter @zcode/e2e install-browsers