docs: add VitePress site with GitHub Pages deploy workflow

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build VitePress site
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install root dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -8,6 +8,8 @@ client/dist/
 packages/inspector-agent/.build/
 packages/inspector-agent/.swiftpm/
 packages/nativescript-inspector/dist/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 
 # Package manager installs and caches
 node_modules/

.prettierignore

@@ -7,3 +7,5 @@ packages/inspector-agent/.build
 packages/nativescript-inspector/dist
 node_modules
 server/target
+docs/.vitepress/dist
+docs/.vitepress/cache

AGENTS.md

@@ -8,6 +8,7 @@ This repository is a local-first simulator control plane. The product goal is a
 - `client/` is the browser UI.
 - `skills/xcode-canvas-web/SKILL.md` is the operator guide for using the tool from Codex.
 - `scripts/` holds repeatable build entrypoints.
+- `docs/` is the public VitePress documentation site (deployed to GitHub Pages by `.github/workflows/docs.yml`).
 
 The native side should own anything that depends on macOS frameworks, `xcrun simctl`, or private CoreSimulator/SimulatorKit APIs. The web client should stay thin and consume the CLI API.
 
@@ -113,6 +114,7 @@ Useful direct commands:
 
 - If you add an API route, add the matching client affordance or document why it stays CLI-only.
 - If you change the CLI invocation shape, update `README.md` and `skills/xcode-canvas-web/SKILL.md` in the same pass.
+- If you change a CLI flag, REST route, packet format, or inspector method, update the matching page under `docs/` in the same pass.
 - If you expand the private framework bridge, document the Xcode/runtime assumptions here.
 - If a feature depends on a booted simulator, fail with a clear JSON error instead of silently returning an empty asset.
 - Do not reintroduce legacy `/stream.h264` handling. The supported live path is Rust-managed WebTransport.

README.md

@@ -36,6 +36,10 @@ npm install -g .
 
 After a global install, use the `xcode-canvas-web` command directly. From a local checkout, you can also run `./build/xcode-canvas-web`.
 
+## Documentation
+
+Full documentation lives at [djdeveloperr.github.io/xcode-canvas-web](https://djdeveloperr.github.io/xcode-canvas-web/), with guides, the CLI reference, the REST API, the WebTransport video pipeline, and the inspector protocols. The source for the site lives in [`docs/`](docs/) — preview it locally with `npm run docs:dev`.
+
 ## Run
 
 ```sh

docs/.vitepress/config.mts

@@ -0,0 +1,179 @@
+import { defineConfig } from "vitepress";
+
+const repoName = "xcode-canvas-web";
+const githubUrl = `https://github.com/DjDeveloperr/${repoName}`;
+
+export default defineConfig({
+  title: "SimDeck",
+  description:
+    "A local-first iOS Simulator control plane with a browser UI, REST API, and WebTransport video.",
+  lang: "en-US",
+  cleanUrls: true,
+  lastUpdated: true,
+  base: `/${repoName}/`,
+
+  head: [
+    ["meta", { name: "theme-color", content: "#0a84ff" }],
+    ["meta", { property: "og:type", content: "website" }],
+    ["meta", { property: "og:title", content: "SimDeck" }],
+    [
+      "meta",
+      {
+        property: "og:description",
+        content:
+          "A local iOS Simulator control plane with a browser UI, REST API, and WebTransport video.",
+      },
+    ],
+    [
+      "meta",
+      {
+        property: "og:url",
+        content: `https://djdeveloperr.github.io/${repoName}/`,
+      },
+    ],
+  ],
+
+  themeConfig: {
+    siteTitle: "SimDeck",
+
+    nav: [
+      { text: "Guide", link: "/guide/", activeMatch: "/guide/" },
+      { text: "CLI", link: "/cli/", activeMatch: "/cli/" },
+      { text: "API", link: "/api/rest", activeMatch: "/api/" },
+      {
+        text: "Inspector",
+        link: "/inspector/",
+        activeMatch: "/inspector/",
+      },
+      {
+        text: "Extensions",
+        link: "/extensions/vscode",
+        activeMatch: "/extensions/",
+      },
+      {
+        text: "0.1.0",
+        items: [
+          {
+            text: "Changelog",
+            link: `${githubUrl}/releases`,
+          },
+          {
+            text: "Contributing",
+            link: "/contributing",
+          },
+        ],
+      },
+    ],
+
+    sidebar: {
+      "/guide/": [
+        {
+          text: "Getting Started",
+          items: [
+            { text: "Introduction", link: "/guide/" },
+            { text: "Installation", link: "/guide/installation" },
+            { text: "Quick Start", link: "/guide/quick-start" },
+          ],
+        },
+        {
+          text: "Concepts",
+          items: [
+            { text: "Architecture", link: "/guide/architecture" },
+            { text: "Video Pipeline", link: "/guide/video" },
+            { text: "LAN Access", link: "/guide/lan-access" },
+            { text: "Background Service", link: "/guide/service" },
+          ],
+        },
+        {
+          text: "Operating SimDeck",
+          items: [
+            { text: "Troubleshooting", link: "/guide/troubleshooting" },
+            { text: "Contributing", link: "/contributing" },
+          ],
+        },
+      ],
+
+      "/cli/": [
+        {
+          text: "CLI",
+          items: [
+            { text: "Overview", link: "/cli/" },
+            { text: "Command Reference", link: "/cli/commands" },
+            { text: "Flags & Options", link: "/cli/flags" },
+          ],
+        },
+      ],
+
+      "/api/": [
+        {
+          text: "HTTP API",
+          items: [
+            { text: "REST Endpoints", link: "/api/rest" },
+            { text: "Health & Metrics", link: "/api/health" },
+          ],
+        },
+        {
+          text: "Live Video",
+          items: [
+            { text: "WebTransport", link: "/api/webtransport" },
+            { text: "Packet Format", link: "/api/packet-format" },
+          ],
+        },
+        {
+          text: "Inspectors",
+          items: [
+            { text: "Inspector Protocol", link: "/api/inspector-protocol" },
+          ],
+        },
+      ],
+
+      "/inspector/": [
+        {
+          text: "Inspector",
+          items: [
+            { text: "Overview", link: "/inspector/" },
+            { text: "Accessibility (AXe)", link: "/inspector/accessibility" },
+            {
+              text: "Swift In-App Agent",
+              link: "/inspector/swift",
+            },
+            {
+              text: "NativeScript Runtime",
+              link: "/inspector/nativescript",
+            },
+          ],
+        },
+      ],
+
+      "/extensions/": [
+        {
+          text: "Extensions",
+          items: [
+            { text: "VS Code", link: "/extensions/vscode" },
+            { text: "Browser Client", link: "/extensions/browser-client" },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [{ icon: "github", link: githubUrl }],
+
+    editLink: {
+      pattern: `${githubUrl}/edit/main/docs/:path`,
+      text: "Edit this page on GitHub",
+    },
+
+    search: {
+      provider: "local",
+    },
+
+    footer: {
+      message: "Released under the Apache-2.0 License.",
+      copyright: `Copyright © 2026 SimDeck contributors.`,
+    },
+
+    outline: {
+      level: [2, 3],
+    },
+  },
+});