Andersseen · Andersseen · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,7 +2,8 @@ name: CI
 
 # Single pipeline for the whole monorepo:
 #   quality -> e2e
-#           -> deploy (Cloudflare Pages, main only)
+#           -> deploy web (Cloudflare Pages, main only)
+#           -> deploy docs (Cloudflare Pages, main only)
 #
 # Cloudflare is the one and only deploy target. See docs/DEPLOYMENT.md.
 
@@ -22,10 +23,12 @@ permissions:
 
 env:
   BUN_VERSION: "1.3.11"
-  # Keep in sync with the `wrangler` devDependency in apps/web/package.json.
-  WRANGLER_VERSION: "3.114.17"
+  # Keep in sync with the root `wrangler` devDependency.
+  WRANGLER_VERSION: "4.114.0"
   CF_PAGES_PROJECT: vertex-web
+  CF_DOCS_PAGES_PROJECT: vertex-docs
   PRODUCTION_URL: https://vertex.andersseen.dev
+  DOCS_PRODUCTION_URL: https://vertex-docs.pages.dev
 
 jobs:
   quality:
@@ -41,12 +44,26 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      - name: Package boundaries
+        run: bun run check:boundaries
+
       - name: Typecheck
         run: bun run check-types
 
       - name: Unit tests
         run: bun test
 
+      - name: Build documentation
+        run: bun run docs:build
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: vertex-docs-dist
+          path: apps/docs/dist
+          retention-days: 1
+          if-no-files-found: error
+
   e2e:
     name: E2E · Playwright
     needs: quality
@@ -137,3 +154,53 @@ jobs:
           } >> "$GITHUB_STEP_SUMMARY"
         env:
           DEPLOYMENT_URL: ${{ steps.cloudflare.outputs.deployment-url }}
+
+  deploy-docs:
+    name: Deploy docs · Cloudflare Pages
+    needs: quality
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    environment:
+      name: documentation
+      url: https://vertex-docs.pages.dev
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Download tested documentation
+        uses: actions/download-artifact@v4
+        with:
+          name: vertex-docs-dist
+          path: apps/docs/dist
+
+      - name: Publish documentation to Cloudflare Pages
+        id: cloudflare-docs
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          wranglerVersion: ${{ env.WRANGLER_VERSION }}
+          packageManager: bun
+          workingDirectory: apps/docs
+          command: pages deploy dist --project-name=${{ env.CF_DOCS_PAGES_PROJECT }} --branch=main
+
+      - name: Documentation deployment summary
+        run: |
+          {
+            echo "### 📚 Documentation deployed to Cloudflare Pages"
+            echo ""
+            echo "| | |"
+            echo "| --- | --- |"
+            echo "| Production | ${DOCS_PRODUCTION_URL} |"
+            echo "| Build alias | ${DEPLOYMENT_URL:-—} |"
+            echo "| Project | \`${CF_DOCS_PAGES_PROJECT}\` |"
+            echo "| Commit | \`${GITHUB_SHA}\` |"
+          } >> "$GITHUB_STEP_SUMMARY"
+        env:
+          DEPLOYMENT_URL: ${{ steps.cloudflare-docs.outputs.deployment-url }}
diff --git a/.gitignore b/.gitignore
@@ -96,3 +96,6 @@ yarn-error.log*
 # Playwright
 playwright-report/
 test-results/
+
+# Generated docs assets
+apps/docs/public/vendor/
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,11 +11,13 @@ apps/
   web/          → Angular 21 + Analog.js + Vite main app (→ localhost:5173)
   desktop/      → Tauri + Rust
   web-editor-demo/ → standalone web component demo
+  docs/         → Astro Starlight public documentation
 packages/
   frontend/
     ide-ui/     → @vertex/ide-ui — IDE components (headless + CSS custom props)
     ui/         → @vertex/ui — layouts, CodeMirror editor, sidebar
     runtime/    → @vertex/runtime — VirtualFS + GitClient + Build + Preview + Deploy (browser)
+    editor-core/→ @vertex/editor-core — framework-free CodeMirror configuration + language profiles
     core/       → @vertex/core — Angular services (RuntimeService, PreferencesService, Dexie DB)
     types/      → @vertex/types — shared types
     web-editor/ → @vertex/web-editor — Angular Element standalone (publishable web component)
@@ -36,7 +38,7 @@ bun dev:all                          # web + terminal sidecar + rust sidecar in
 bun desktop:dev                      # Tauri desktop (requires Rust + Cargo)
 
 # Build
-bun build                            # full build via Turbo (respects dependencies)
+bun run build                        # full build via Turbo (respects dependencies)
 bun web:build                        # Analog/Vite web app only
 bun web-editor:build                 # web component (esbuild bundle → dist/web-editor.min.js)
 
@@ -57,16 +59,23 @@ bun web:deploy                       # vite build + wrangler pages deploy → Cl
 
 # Web editor demo
 bun web-editor-demo:start            # build web-component + serve demo
+
+# Documentation
+bun docs:dev                         # build editor bundles + start Starlight
+bun docs:build                       # production documentation build
+bun docs:deploy                      # build + deploy to Cloudflare Pages vertex-docs
 ```
 
 ---
 
 ## CI/CD
 
 One pipeline, one platform. `.github/workflows/ci.yml` runs `quality` (lint → types → unit),
-then `e2e` (Playwright, non-blocking) and `deploy` in parallel. `deploy` only runs for pushes to
-`main`, targets the GitHub `production` environment, and publishes `apps/web/dist/client` to the
-Cloudflare Pages project `vertex-web`. Shared setup lives in `.github/actions/setup`.
+then `e2e` (Playwright, non-blocking), `deploy`, and `deploy-docs` in parallel.
+Production deploys only run for pushes to `main`. The web job publishes
+`apps/web/dist/client` to `vertex-web`; the docs job publishes the tested
+`apps/docs/dist` artifact to `vertex-docs`. Shared setup lives in
+`.github/actions/setup`.
 
 `.github/workflows/release-web-editor.yml` publishes the web-component bundles to the rolling
 `web-editor-latest` GitHub Release when `packages/frontend/web-editor/**` changes.
@@ -124,6 +133,9 @@ To add Dexie tables: `db.version(2).stores({...})` in `packages/frontend/core/sr
 apps/web (Angular app)
   └── uses @vertex/core, @vertex/ide-ui, @vertex/runtime, @vertex/ui
 
+@vertex/editor-core
+  └── shared CodeMirror engine primitives; no Angular, runtime, Git, preview, or workbench dependencies
+
 @vertex/core
   ├── db/vertex.db.ts         → VertexDatabase (Dexie), SessionRecord, PreferenceRecord
   ├── services/               → WorkspaceService, PreferencesService, ConfigService
@@ -149,6 +161,10 @@ apps/web (Angular app)
   └── web-editor-lite.component.ts → display-only, ~500KB vs ~1.6MB
 ```
 
+Product boundaries and allowed dependency direction are defined in
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md). Run `bun run check:boundaries`
+after changing package imports.
+
 The terminal uses **dependency injection** via `TERMINAL_BACKEND_ADAPTER`. In web: `VirtualTerminalService`; in desktop: can connect to node-pty or WebContainers.
 
 ---

diff --git a/README.md b/README.md
@@ -11,9 +11,11 @@
 
 ### Clone any GitHub repo, edit it, build it, preview it, ship it — **without installing anything.**
 
-**Vertex is an open-source IDE that runs entirely inside a browser tab.**
-Real git, a real filesystem, a real bundler, a real Node runtime — all client-side.
-The same codebase also ships as a **Tauri desktop app** and as a **drop-in `<vertex-editor>` web component**.
+**Vertex is an open-source family of code-editing products.** The browser
+workbench combines Git, a virtual filesystem, build, and a Node-compatible
+runtime client-side. The Tauri app adds installed-platform adapters, while the
+drop-in `<vertex-editor>` remains a focused editor with no IDE/runtime
+dependency.
 
 <br/>
 
@@ -32,7 +34,7 @@ The same codebase also ships as a **Tauri desktop app** and as a **drop-in `<ver
 
 <br/>
 
-[**🚀 Try it live**](https://vertex.andersseen.dev) · [**⚡ Quick start**](#-quick-start) · [**🧩 Features**](#-what-you-get) · [**🏗️ Architecture**](#️-architecture) · [**📦 Web component**](#-embed-the-editor-anywhere) · [**☁️ Deployment**](docs/DEPLOYMENT.md) · [**🤝 Contributing**](CONTRIBUTING.md)
+[**🚀 Try it live**](https://vertex.andersseen.dev) · [**⚡ Quick start**](#-quick-start) · [**🧩 Products**](#-product-surfaces) · [**🏗️ Architecture**](#️-architecture) · [**📦 Web component**](#-embed-the-editor-anywhere) · [**📚 Docs source**](apps/docs/README.md) · [**🤝 Contributing**](CONTRIBUTING.md)
 
 </div>
 
@@ -48,9 +50,26 @@ Cloud IDEs put your code on someone else's machine. Local IDEs need an install,
                               isomorphic-git          CodeMirror 6   esbuild-wasm   WebContainers   Cloudflare
 ```
 
-There is no Vertex backend. The web app is static files on Cloudflare Pages; your repository is
-cloned straight from GitHub into your browser's **OPFS** and stays there. No account, no upload,
-no telemetry — because there is nowhere for it to go.
+The hosted browser workbench does not require a Vertex application backend. It
+is static output on Cloudflare Pages; repositories are cloned into browser
+storage rather than uploaded to a Vertex server. Optional local sidecars exist
+for installed/native development workflows.
+
+---
+
+## 🧭 Product surfaces
+
+Vertex is not one application stretched across every environment:
+
+| Surface | Job | Owns |
+| :-- | :-- | :-- |
+| `apps/web` | Complete browser workbench | OPFS, browser Git, build, WebContainer preview, deploy |
+| `apps/desktop` | Installed Tauri workbench | Native filesystem/process/terminal adapters and lifecycle |
+| `<vertex-editor>` | Editor embedded in another product | Editing API, language loading, themes, events |
+| `<vertex-editor-lite>` | Read-only code display | Small native custom element and syntax highlighting |
+
+The custom elements do not include filesystems, Git, terminals, preview, or
+deployment. Preview is a workbench capability, not an editor capability.
 
 ---
 
@@ -139,7 +158,7 @@ Signals everywhere, `OnPush` everywhere, no Zone.js, no Tailwind, no component f
 
 ## ⚡ Quick start
 
-> **Requirements** — [Bun](https://bun.sh) `1.3.11+`, Node.js `18+`, and a Rust toolchain *(desktop only)*.
+> **Requirements** — [Bun](https://bun.sh) `1.3.11+`, Node.js `22.12+`, and a Rust toolchain *(desktop only)*.
 
 ```bash
 git clone https://github.com/Andersseen/vertex.git
@@ -165,6 +184,7 @@ bun web:dev            # → http://localhost:5173
 | 🎭 | `bun test:e2e` | Playwright end-to-end suite |
 | 📦 | `bun web-editor:build` | Bundle the `<vertex-editor>` web component |
 | 🎬 | `bun web-editor-demo:start` | Build the component and serve its demo app |
+| 📚 | `bun docs:dev` · `bun docs:build` · `bun docs:deploy` | Develop, build, or publish the Starlight documentation |
 | ☁️ | `bun run deploy` | Build + publish to Cloudflare Pages |
 
 </details>
@@ -175,14 +195,16 @@ bun web:dev            # → http://localhost:5173
 
 ```mermaid
 flowchart TB
-  subgraph SURFACES["🖼️ Surfaces — one codebase, three shells"]
+  subgraph SURFACES["🖼️ Products — shared editor, separate responsibilities"]
     direction LR
     W["🌐 apps/web<br/>Angular 21 · Analog.js"]
     D["🖥️ apps/desktop<br/>Tauri 2 · Rust"]
-    E["🧩 @vertex/web-editor<br/>&lt;vertex-editor&gt;"]
+    E["🧩 @vertex/web-editor<br/>&lt;vertex-editor&gt; · editor only"]
   end
 
-  subgraph ANGULAR["🅰️ Angular layer"]
+  EDITOR["@vertex/editor-core<br/>CodeMirror engine · language profiles"]
+
+  subgraph ANGULAR["🅰️ Workbench layer"]
     direction LR
     UI["@vertex/ui<br/>layouts · editor · sidebar"]
     IDEUI["@vertex/ide-ui<br/>21 headless components"]
@@ -196,7 +218,8 @@ flowchart TB
 
   W --> ANGULAR
   D --> ANGULAR
-  E --> IDEUI
+  E --> EDITOR
+  UI --> EDITOR
   ANGULAR --> RUNTIME
   RUNTIME --> STORE[("💾 OPFS + IndexedDB<br/>your files never leave the browser")]
 ```
@@ -211,9 +234,11 @@ apps/
   web/                  🌐 Angular 21 + Analog.js + Vite — the main IDE
   desktop/              🖥️ Tauri 2 shell around the same app
   web-editor-demo/      🎬 Playground for the standalone web component
+  docs/                 📚 Starlight documentation for every product surface
 packages/
   frontend/
     core/               🧠 Angular services, Dexie DB, terminal adapter token
+    editor-core/        ✏️ Framework-free CodeMirror engine and language profiles
     ide-ui/             🧩 @vertex/ide-ui — headless IDE components (CSS custom props)
     runtime/            ⚙️ VirtualFS · GitClient · Bundler · Preview · Deploy
     types/              📐 Shared TypeScript contracts
@@ -224,11 +249,16 @@ packages/
     terminal/           📟 Node.js + node-pty terminal sidecar
     core/               🧪 Experimental shared terminal types
 scripts/                🔧 Install & release helpers
-docs/                   📚 Deployment, preview-WC design notes
+docs/                   🧭 Repository architecture, deployment, and design notes
 ```
 
 </details>
 
+The products intentionally have different scopes. See
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for dependency rules and product
+boundaries, and [`docs/EDITOR_FOUNDATION.md`](docs/EDITOR_FOUNDATION.md) for the
+stability checklist.
+
 <details>
 <summary><b>Where state lives</b></summary>
 
@@ -272,16 +302,21 @@ curl -fsSL https://raw.githubusercontent.com/Andersseen/vertex/main/scripts/inst
 
 ## 🗺️ Status
 
-Vertex is in **active development**. Phase 2 — *run code in the browser* — is where the work is.
+Vertex is in active development. The current target is a dependable editor and
+browser/tablet MVP, not VS Code feature parity.
 
-| Phase | Capability | State |
-| :-- | :-- | :-- |
-| 1 | Virtual filesystem · in-browser git · editor · terminal | ✅ Done |
-| 2A | Bundling with `esbuild-wasm` | ✅ Done |
-| 2B | Live preview via WebContainers | ✅ Done |
-| 2C | Full Node.js runtime (headless WebContainer runner) | 🔄 In progress |
-| 2D | Deploy to Cloudflare Pages / Workers from the IDE | ✅ Done |
-| 3 | Language server protocol, richer intellisense | 🧭 Planned |
+| Priority | Current state |
+| :-- | :-- |
+| Shared editor core, language profiles, package boundaries | ✅ Established |
+| Full and lite custom elements with enforced bundle budgets | ✅ Established |
+| Public docs and canonical custom-element API | 🔄 In progress |
+| Capability fallback, recovery UX, blocking persistence E2E | 🧭 Next |
+| Project search, command palette, Git status/diff | 🧭 MVP |
+| Physical tablet keyboard/touch/lifecycle validation | 🧭 MVP |
+| Broad VS Code extension compatibility | 🔭 Later research |
+
+See the [foundation checklist](docs/EDITOR_FOUNDATION.md) and the
+[public roadmap source](apps/docs/src/content/docs/project/roadmap.md).
 
 ---
 
@@ -331,6 +366,9 @@ with Angular and Analog specifics in [ANGULAR_USAGE.md](ANGULAR_USAGE.md) and
 | Doc | About |
 | :-- | :-- |
 | [AGENTS.md](AGENTS.md) | Architecture, conventions, commands — the authoritative guide |
+| [apps/docs](apps/docs/README.md) | Public Starlight documentation application |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Product ownership and package boundaries |
+| [docs/EDITOR_FOUNDATION.md](docs/EDITOR_FOUNDATION.md) | Stability checklist and MVP gaps |
 | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Cloudflare pipeline, secrets, environments |
 | [apps/web/README.md](apps/web/README.md) | Web application |
 | [apps/desktop/README.md](apps/desktop/README.md) | Tauri desktop application |