@@ -40,8 +40,9 @@ extensions/levelcode-hackability/ user init script + Atom/NPP keymap presets + p
 extensions/levelcode-sync/       'levelcode' auth provider that lights up the built-in Settings Sync (LevelCode Sync, S0)
 extensions/levelcode-updater/    notify-only update checker (polls the update feed; never auto-applies)
 patches/levelcode-core.patch     our core source edits, applied on bootstrap
-scripts/                    bootstrap.sh, apply-branding.mjs, run-dev.sh, editor-identity.mjs, build-macos.sh, make-dmg.sh, make-icon.sh; atom (CLI launcher) + install-level.sh
+scripts/                    bootstrap.sh, apply-branding.mjs, run-dev.sh, editor-identity.mjs, build-macos.sh, make-dmg.sh, make-icon.sh, build-web.mjs; atom (CLI launcher) + install-level.sh
 tools/                      dependency-free reference servers: sync-server (/v1 Settings-Sync), update-server (/api/update feed)
+web/                        LevelCode in a browser tab: page entry + callback, scratch-workspace extension, browser build of levelcode-ai, dev server, tests (docs/WEB.md)
 vscode/                     GITIGNORED upstream Code-OSS checkout (generated)
 ```
 
@@ -82,6 +83,30 @@ To macOS a run from source and the installed LevelCode used to be ONE app — sa
 - A LaunchServices handler must live outside temp folders — a bundle under `/tmp` is registered but
   never chosen. Tests therefore run on fixtures and do not register anything (`test/editorIdentity.test.js`).
 
+## LevelCode in a tab (`web/`) — read `docs/WEB.md` first
+
+The same `extensions/levelcode-ai` source runs in a browser tab (web-worker extension host). Rules that keep
+the desktop app exactly as it was:
+
+- **A workspace read or write goes through `extensions/levelcode-ai/host.js`**, never `fs` on a workspace path:
+  in a tab the workspace is whatever the editor's file-system provider says, and every read is asynchronous.
+  On the desktop each `host` function does what the call site did before, behind `await`.
+- **Nothing outside `host.js` asks "am I in a browser?"** — a call site asks for a capability (`host.caps.shell`,
+  `.mcpStdio`, `.ripgrep`) or calls a function that already knows. A new tool that needs a shell/disk/process is
+  listed in `NEEDS_SHELL` (agent.js) so the browser neither offers it nor promises it.
+- The browser build is `web/ai-extension/` (esbuild + shims for `fs`/`path`/`os`/`crypto`/`child_process`).
+  Strings that are true on a Mac and false in a tab are rewritten by `web/ai-extension/copy.js`, which fails the
+  build when the desktop text it expects is gone — change both together. `manifest.js` drops the commands and
+  settings a tab cannot honour.
+- `web/main.js` is a plain ES module with a **top-level `await`**: a `const` declared lower in the file is not
+  initialised until that await finishes (this cleared a saved session once). Declare constants above the
+  `try`, and use function declarations for helpers it calls.
+- The session store (`createSecretStorage`) belongs to every tab: no cache, one-key read-modify-write under a
+  Web Lock. The refresh token is rotated on use; do not reintroduce a start-up snapshot.
+- Build: `node scripts/build-web.mjs --account <origin>` → `dist-web/`; serve with `node web/serve.mjs --dist dist-web`.
+  Tests: the unit gate (`scripts/test-extensions.sh` includes `web/test/unit/*.test.js`) and the end-to-end checks in
+  `web/test/e2e*.mjs` (headless Chrome, stand-in backend; Node 22+). What was not run is listed in `docs/WEB.md`.
+
 ## Toolchain (hard requirements — these bit us)
 
 - **Node = `vscode/.nvmrc` (currently 24.15.0)**. Older majors fail to compile native modules.
@@ -213,7 +238,7 @@ big-file mode badge. Files: extension.js + fileOps/lineOps/columnOps/encodingEol
   is not in the editor until you load it: `./scripts/run-dev.sh --extensionDevelopmentPath=<worktree>/extensions/levelcode-ai`
   (from the main checkout; the dev extension replaces the built-in one). Uncommitted work is not "on the branch" —
   checking the branch out somewhere else gets none of it. Run it in the editor before telling anyone to try it.
-- Commit `extensions/`, `patches/`, `branding/`, `scripts/`, `docs/`, `PLAN.md`, `CLAUDE.md`. Never commit `vscode/`.
+- Commit `extensions/`, `patches/`, `branding/`, `scripts/`, `web/`, `docs/`, `PLAN.md`, `CLAUDE.md`. Never commit `vscode/` or `dist-web/`.
 - `extensions/levelcode-ai/diagram/` modules listed in `bundle.FILES` are pasted INTO a script block in `chat.html`.
   They must never contain the text of a script tag or an HTML comment opener — not even in a comment — or the block
   ends early; `bundle.js` refuses to build if one does. Keep them dependency-free and free of `require('vscode')`/`fs`.
 
@@ -35,7 +35,8 @@ LevelCode is a **clean overlay on top of Code-OSS**, not a vendored copy of the
 - `extensions/` — the first-party extensions (native AI, Notepad++ pack, themes, hackability, sync, updater), plain JS with no build step.
 - `branding/` — the LevelCode identity (`product.overlay.json`) + icons, deep-merged onto upstream `product.json`; the extension gallery wired to **Open VSX**.
 - `patches/` — the small set of core source patches (each tagged `// [LevelCode]`).
-- `scripts/` — bootstrap / run-dev / build / dmg / icon.
+- `scripts/` — bootstrap / run-dev / build / dmg / icon, and `build-web.mjs` (LevelCode in a browser tab).
+- `web/` — LevelCode in your browser: the same workbench and AI extension as a static site you can host; sign in with a LevelCode account or use your own key. See [`docs/WEB.md`](docs/WEB.md).
 - `tools/` — dependency-free reference servers (Settings-Sync feed, update feed).
 - `PLAN.md`, `docs/`, `CLAUDE.md` — the vision, roadmap, and repo map.