docs: restore Starlight site + refresh for v1 + agent-friendly USAGE section

.github/workflows/ci.yml

@@ -29,8 +29,11 @@ jobs:
       - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151  # v4
       - run: pnpm install --frozen-lockfile --ignore-scripts
       - name: Build workspace .d.ts so cross-package types resolve
-        run: pnpm -r build
-      - run: pnpm -r exec tsc --noEmit
+        # Skip @opencodehub/docs — its build runs astro + rehype-mermaid +
+        # playwright (heavy headless-Chromium dep) and is exercised on the
+        # dedicated `pages.yml` workflow with --with-deps installed.
+        run: pnpm --filter '!@opencodehub/docs' -r build
+      - run: pnpm --filter '!@opencodehub/docs' -r exec tsc --noEmit
 
   test:
     # Node 22 = native-opt-in path (OCH_NATIVE_PARSER=1); Node 24 = WASM default
@@ -60,7 +63,7 @@ jobs:
       - name: Install deps (Node 24, ignore-scripts)
         if: matrix.node-version == 24
         run: pnpm install --frozen-lockfile --ignore-scripts
-      - run: pnpm -r test
+      - run: pnpm --filter '!@opencodehub/docs' -r test
         env:
           OCH_NATIVE_PARSER: ${{ matrix.node-version == 22 && '1' || '' }}
 

.github/workflows/och-self-scan.yml

@@ -34,7 +34,10 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build workspace
-        run: pnpm -r build
+        # Skip @opencodehub/docs — its build runs astro + playwright; the
+        # self-scan job only needs the OCH workspace built. Pages.yml owns
+        # the docs build.
+        run: pnpm --filter '!@opencodehub/docs' -r build
 
       - name: Analyze repository
         run: pnpm exec node packages/cli/dist/index.js analyze .

.github/workflows/pages.yml

@@ -0,0 +1,62 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "packages/docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac  # v2.4.4
+      # NOTE: --ignore-scripts removed so sharp's native binary download
+      # and Playwright's chromium install (via rehype-mermaid) are allowed.
+      - run: pnpm install --frozen-lockfile
+      # rehype-mermaid renders ```mermaid fences to inline SVG at build
+      # time using Playwright chromium. --with-deps installs the apt
+      # libraries Playwright needs on ubuntu-latest. Do not use --with-deps
+      # on dev machines.
+      - run: pnpm --filter @opencodehub/docs exec playwright install chromium --with-deps
+      # mise-action@v4 writes NODE_ENV=development to $GITHUB_ENV, which
+      # takes precedence over job-level env. Override at the step level
+      # (step env beats $GITHUB_ENV) to force Astro into production mode
+      # so Starlight wires Pagefind instead of shipping the dev stub
+      # ("Search is only available in production builds").
+      # mise-action@v4 writes NODE_ENV=development to $GITHUB_ENV at setup
+      # time. Inline `env VAR=val` and step-level env: don't reach astro's
+      # Vite compilation reliably — Vite resolves `import.meta.env.DEV` at
+      # bundle time from process.env.NODE_ENV that the Vite module sees.
+      # Override $GITHUB_ENV directly so every subsequent step (including
+      # the Node process spawned by pnpm → astro) inherits production.
+      - run: echo "NODE_ENV=production" >> "$GITHUB_ENV"
+      - run: pnpm -F @opencodehub/docs build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
+        with:
+          path: packages/docs/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5

.github/workflows/release.yml

@@ -126,7 +126,10 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build workspace
-        run: pnpm -r build
+        # Skip @opencodehub/docs — its build runs astro + playwright. The
+        # release flow only needs the OCH workspace TS packages built; the
+        # docs build runs on the dedicated `pages.yml` workflow.
+        run: pnpm --filter '!@opencodehub/docs' -r build
 
       - name: Analyze repository (OCH self-index)
         run: pnpm exec node packages/cli/dist/index.js analyze .
@@ -346,6 +349,6 @@ jobs:
           persist-credentials: false
       - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac  # v2.4.4
       - run: pnpm install --frozen-lockfile
-      - run: pnpm -r build
+      - run: pnpm --filter '!@opencodehub/docs' -r build
       - name: Publish (dry-run)
-        run: pnpm -r publish --provenance --access public --no-git-checks --dry-run
+        run: pnpm --filter '!@opencodehub/docs' -r publish --provenance --access public --no-git-checks --dry-run

.gitignore

@@ -3,6 +3,10 @@ dist/
 .tsbuildinfo
 *.tsbuildinfo
 
+# Astro / Starlight build artifacts (packages/docs/)
+.astro/
+packages/docs/dist/
+
 # Python (eval package)
 .venv/
 __pycache__/

packages/docs/README.md

@@ -0,0 +1,77 @@
+# @opencodehub/docs
+
+Astro + Starlight documentation site for OpenCodeHub. Deployed to
+GitHub Pages at https://theagenticguy.github.io/opencodehub/.
+
+## Local development
+
+```bash
+pnpm install
+pnpm -F @opencodehub/docs dev       # http://localhost:4321/opencodehub
+pnpm -F @opencodehub/docs build     # writes to packages/docs/dist
+pnpm -F @opencodehub/docs preview   # serves dist/ locally
+```
+
+Prefer the mise tasks from the repo root:
+
+```bash
+mise run docs:dev
+mise run docs:build
+mise run docs:preview
+```
+
+## Site IA
+
+Top-level sections under `src/content/docs/`:
+
+- `start-here/` — install, quick-start, first query.
+- `guides/` — editor integrations and task-oriented walkthroughs.
+- `mcp/` — server overview, tool catalog, resources, prompts.
+- `reference/` — CLI, error codes, language matrix, configuration.
+- `architecture/` — monorepo map, determinism, supply chain, ADR index.
+- `skills/` — Claude Code skill references.
+- `contributing/` — dev loop, testing, release process.
+
+## ADRs
+
+Architecture decision records live at `/docs/adr/` at the repo root — 10
+files, numbered `0001-*.md` through `0010-*.md`. The Starlight site
+surfaces them through an index page at
+`src/content/docs/architecture/adrs.md`, so readers get both the canonical
+source and a browsable index.
+
+## Starlight plugins
+
+Configured in `astro.config.mjs`:
+
+- `starlight-llms-txt` — emits `/llms.txt`, `/llms-full.txt`, and
+  `/llms-small.txt` at build time for LLM-crawlable bundles.
+- `starlight-page-actions` — per-page "Copy as Markdown", "Open in ChatGPT",
+  "Open in Claude", and Share actions.
+- `starlight-links-validator` — build-time broken-link check so shipped
+  bundles never carry dead links.
+
+## Authoring
+
+Pages live under `src/content/docs/`. Starlight picks up any
+`.md` or `.mdx` file automatically; the sidebar auto-generates
+per top-level directory.
+
+Frontmatter fields we use:
+
+```yaml
+---
+title: Page title
+description: One-sentence SEO/summary
+sidebar:
+  order: 1        # lower first; ties break alphabetically
+  label: Short    # optional override
+---
+```
+
+## Deploy
+
+`.github/workflows/pages.yml` runs on pushes to `main` that touch
+`packages/docs/**` or the workflow itself. It builds with
+`withastro/action@v6` pinned to Node 22 and deploys with
+`actions/deploy-pages@v5`.

packages/docs/astro.config.mjs

@@ -0,0 +1,159 @@
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import starlightLinksValidator from "starlight-links-validator";
+import starlightLlmsTxt from "starlight-llms-txt";
+import starlightPageActions from "starlight-page-actions";
+import rehypeMermaid from "rehype-mermaid";
+
+// https://astro.build/config
+export default defineConfig({
+  site: "https://theagenticguy.github.io",
+  base: "/opencodehub",
+  // Mermaid: render ```mermaid ``` fences to inline SVG at build time.
+  // excludeLangs is critical — without it, Shiki grabs the mermaid fence
+  // first and rehype-mermaid never sees it.
+  markdown: {
+    syntaxHighlight: { type: "shiki", excludeLangs: ["mermaid"] },
+    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
+  },
+  integrations: [
+    starlight({
+      title: "OpenCodeHub",
+      description:
+        "Apache-2.0 code intelligence graph + MCP server for AI coding agents. 29 tools, 15 GA languages, LadybugDB-default, WASM-default parsing, deterministic, offline-capable.",
+      logo: {
+        src: "./src/assets/logo.svg",
+        replacesTitle: false,
+      },
+      favicon: "/favicon.svg",
+      social: [
+        {
+          icon: "github",
+          label: "GitHub",
+          href: "https://github.com/theagenticguy/opencodehub",
+        },
+      ],
+      editLink: {
+        baseUrl:
+          "https://github.com/theagenticguy/opencodehub/edit/main/packages/docs/",
+      },
+      lastUpdated: true,
+      credits: true,
+      plugins: [
+        // 1) LLM-crawlable bundles. Emits /llms.txt, /llms-full.txt,
+        //    /llms-small.txt at build time. Must run first so page-actions
+        //    sees it already registered.
+        starlightLlmsTxt({
+          projectName: "OpenCodeHub",
+          description:
+            "Apache-2.0 code intelligence graph + MCP server for AI coding agents. Gives agents callers, callees, processes, and blast radius in one MCP tool call — local, offline-capable, deterministic.",
+          details:
+            "OpenCodeHub indexes a repository into a hybrid structural + semantic knowledge graph and exposes it over the Model Context Protocol (MCP) to AI coding agents. The MCP server registers 29 tools across five families — exploration (list_repos, query, context, impact, detect_changes, rename, sql), group / federation (group_list, group_query, group_status, group_contracts, group_cross_repo_links, group_sync), scan / findings / verdict (scan, list_findings, list_findings_delta, list_dead_code, remove_dead_code, license_audit, verdict, risk_trends), HTTP / routing (route_map, api_impact, shape_check, tool_map), and meta (project_profile, dependencies, owners, pack_codebase). The CLI binary is `codehub`. Runtime: Node 22 or 24, pnpm 10, LadybugDB graph store + DuckDB temporal sibling by default (legacy single-file DuckDB layout opt-in via CODEHUB_STORE=duck), web-tree-sitter (WASM) parse runtime by default with native opt-in via OCH_NATIVE_PARSER=1, 15 GA languages, SCIP indexers for TypeScript / TSX / JavaScript / Python / Go / Rust / Java / C# / C / C++ / Kotlin / Ruby. 20-scanner inventory. Apache-2.0 end to end. Repos are first-class graph nodes (`repo_uri`); the cross-repo `group_*` family fans out over named groups; AMBIGUOUS_REPO error envelope returns `choices[]` so a caller can retry deterministically.",
+          promote: [
+            "start-here/**",
+            "agents/**",
+            "guides/**",
+            "mcp/**",
+          ],
+          demote: [
+            "architecture/**",
+            "contributing/**",
+          ],
+          // Keep llms-small.txt tight by dropping internals-y prose.
+          exclude: [],
+          minify: {
+            note: true,
+            tip: true,
+            details: true,
+            whitespace: true,
+            caution: false,
+            danger: false,
+          },
+          customSets: [
+            {
+              label: "user-guide",
+              paths: ["start-here/**", "guides/**"],
+              description:
+                "User-facing pages only: install, quick-start, editor integration guides, group + migration guides.",
+            },
+            {
+              label: "agents",
+              paths: ["agents/**", "mcp/**"],
+              description:
+                "Agent-side reference: per-editor MCP setup, the 29-tool catalog, tool decision matrix, idiomatic prompts.",
+            },
+            {
+              label: "mcp",
+              paths: ["mcp/**", "reference/**"],
+              description:
+                "MCP surface: server tools, resources, CLI reference, error codes, language matrix, .docmeta.json schema.",
+            },
+            {
+              label: "contributing",
+              paths: ["contributing/**", "architecture/**"],
+              description:
+                "Developer and architecture docs: dev loop, release flow, ADRs, determinism, supply-chain, storage backend, cross-repo federation.",
+            },
+          ],
+        }),
+
+        // 2) Per-page "Copy as Markdown" + "Open in ChatGPT" + "Open in
+        //    Claude" + Share. IMPORTANT: do NOT set `baseUrl`, or this
+        //    plugin will try to own /llms.txt too and collide with
+        //    starlight-llms-txt. Leave llms generation to plugin #1.
+        starlightPageActions({
+          actions: {
+            markdown: true,
+            chatgpt: true,
+            claude: true,
+            t3chat: false,
+            v0: false,
+          },
+          share: true,
+        }),
+
+        // 3) Build-time broken-link check. Runs after content is built
+        //    but before deploy, so llms-full.txt never ships dead links.
+        starlightLinksValidator({
+          errorOnFallbackPages: false,
+          errorOnInconsistentLocale: false,
+        }),
+      ],
+      sidebar: [
+        {
+          label: "Start here",
+          autogenerate: { directory: "start-here" },
+        },
+        {
+          label: "Agents",
+          autogenerate: { directory: "agents" },
+        },
+        {
+          label: "MCP",
+          autogenerate: { directory: "mcp" },
+        },
+        {
+          label: "Reference",
+          autogenerate: { directory: "reference" },
+        },
+        {
+          label: "Guides",
+          autogenerate: { directory: "guides" },
+        },
+        {
+          label: "Architecture",
+          autogenerate: { directory: "architecture" },
+        },
+        {
+          label: "Skills",
+          autogenerate: { directory: "skills" },
+        },
+        {
+          label: "Contributing",
+          autogenerate: { directory: "contributing" },
+        },
+      ],
+      customCss: ["./src/styles/custom.css"],
+    }),
+  ],
+});

packages/docs/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@opencodehub/docs",
+  "version": "0.0.0",
+  "private": true,
+  "description": "OpenCodeHub documentation site (Astro + Starlight)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "NODE_ENV=production astro build && node scripts/inject-llm-nav.mjs",
+    "preview": "astro preview",
+    "check": "astro check",
+    "clean": "rm -rf dist .astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.38.4",
+    "astro": "^6.2.1",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "playwright": "^1.59.1",
+    "rehype-mermaid": "^3.0.0",
+    "starlight-links-validator": "^0.24.0",
+    "starlight-llms-txt": "^0.8.1",
+    "starlight-page-actions": "^0.6.0"
+  }
+}