navalabs-dev · vmichalik · Jul 21, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,6 @@
+# Optional server-side page feedback destination.
+SLACK_FEEDBACK_WEBHOOK=
+
+# Optional server-side semantic retrieval. Both values are required to enable it.
+DOCS_ENABLE_AI_SEARCH=false
+OPENAI_API_KEY=
diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml
@@ -0,0 +1,47 @@
+name: Docs quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-quality:
+    runs-on: windows-2025
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.33.3
+          run_install: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24.14.0
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Install Playwright Chromium
+        run: pnpm exec playwright install chromium
+      - name: Test claim checker
+        run: pnpm test:claims
+      - name: Audit documentation claims
+        run: pnpm check:claims
+      - name: Test Vocs contracts
+        run: pnpm test:vocs
+      - name: Test executable examples
+        run: pnpm test:examples
+      - name: Test interactive documentation models
+        run: pnpm test:interactive
+      - name: Typecheck project sources
+        run: pnpm typecheck
+      - name: Test development runtime
+        run: pnpm test:dev
+      - name: Build production docs
+        run: pnpm build
+      - name: Test visual baselines
+        run: pnpm test:visual
diff --git a/.gitignore b/.gitignore
@@ -1,12 +1,19 @@
 # Dependencies
 node_modules/
 
-# Production
+# Vocs production output
 build/
+dist/
+.vocs/
+.netlify/
+netlify-functions/
+src/pages.gen.ts
+.superpowers/
 
-# Generated files
-.docusaurus/
-.cache-loader
+# Playwright transient output (keep tests/**-snapshots tracked)
+test-results/
+playwright-report/
+blob-report/
 
 # Misc
 .DS_Store

diff --git a/README.md b/README.md
@@ -1,49 +1,90 @@
 # Nava Docs
 
-The official documentation site for Nava, built with [Docusaurus](https://docusaurus.io/).
+The official Nava documentation site, built with [Vocs](https://vocs.dev/).
 
 ## Sections
 
-The docs are organized by topic under [`docs/`](./docs):
+- **Introduction** - Nava and the Developer Preview policy architecture.
+- **Nava Guardian** - **Developer Preview** Agent Operator and developer guidance, policy handling, execution safety, and the canonical API reference.
+- **Nava Gateway** - developer-only **Developer Preview** guidance; there is no Gateway Agent Operator workflow.
+- **NavaClaw** - a first-class **Developer Preview** section for the Nava-powered agent harness.
 
-- **Introduction** — what Nava is, architecture overview, and core concepts (Guardian, Navachain, execution escrow).
-- **Guides** — practical walkthroughs: quickstart, authentication, SDK integration, MCP server, skills, and Nava Claw.
-- **Guardian** — deep dive on the Guardian: overview, validation API, and extension points.
-- **Network** — on-chain contracts, Navachain details, and public endpoints.
-- **API Reference** — authentication, account management, transactions, and environment variables.
+## Setup and local development
 
-## Running locally
-
-Requires Node.js 18+ and [pnpm](https://pnpm.io/).
+Use Node.js 22.15+, 24, or 26 and the repository-pinned pnpm 10.33.3. Corepack can activate the exact package manager from `package.json`.
 
 ```bash
-pnpm install      # install dependencies
-pnpm start        # run the dev server with hot reload
-pnpm build        # build a production bundle into ./build
-pnpm serve        # serve the production build locally
+corepack enable
+corepack prepare pnpm@10.33.3 --activate
+pnpm install --frozen-lockfile
+pnpm dev
 ```
 
-## Project layout
+The development server uses Vocs hot reload. Do not treat a successful dev render as the production gate; run the checks below before contributing.
+
+## Advanced documentation features
+
+- Generated OpenAPI references under `/api/guardian` and `/api/gateway` provide searchable schemas and request playgrounds.
+- The docs-only MCP server is available at `/api/mcp`. It exposes public documentation navigation and deliberately has no source-repository adapters.
+- Page feedback can be enabled by setting the server-side `SLACK_FEEDBACK_WEBHOOK` environment variable.
+- Semantic retrieval is opt-in: set `DOCS_ENABLE_AI_SEARCH=true` and a server-side `OPENAI_API_KEY`. It remains disabled when either value is absent, so local and CI builds do not create embedding requests by default.
+- Public changes to the documentation are recorded at `/changelog`; page share cards are generated by the Vocs OG endpoint.
+
+Copy `.env.example` to the environment used by the Vocs server. Never expose the Slack webhook or OpenAI key through client-side variables or commit their values.
+
+## Project-owned Vocs boundaries
+
+The repository uses public Vocs extension points rather than patching installed packages:
+
+- `src/pages/_mdx-wrapper.tsx` wraps MDX content with the public Vocs layout.
+- `src/recma-normalize-windows-imports.ts` narrowly normalizes the generated Windows import for that wrapper.
+- `src/components/DocsFooter.tsx` adds public changelog and API affordances through the project-owned MDX layout.
+- `src/styles.css` owns the documentation theme through semantic and project-owned selectors.
+- `src/navigation.ts` discovers page files and generates the sidebar and top navigation consumed by `vocs.config.ts`.
+- `scripts/check-deploy-output.mjs` compares deployable page HTML with the source page tree while ignoring Waku `.d` transport assets.
+
+## Verification
 
+```bash
+pnpm test:claims        # test the documentation claim checker
+pnpm check:claims       # audit public documentation claims
+pnpm test:vocs          # route, navigation, build-contract, and harness tests
+pnpm test:examples      # exercise the copyable Guardian integration example
+pnpm test:interactive   # pure behavior tests for the documentation explorers
+pnpm typecheck          # typecheck all project-owned TypeScript and TSX
+pnpm test:dev           # verify development console, preloads, and Mermaid rendering
+pnpm build              # production build plus deployable-route validation
+pnpm test:visual        # build a fresh preview on 127.0.0.1:4175 and compare screenshots
 ```
-docs/           Markdown content, organized by section
-src/            Custom React components and page overrides
-static/         Static assets (images, favicons, etc.)
-sidebars.ts     Sidebar configuration
-docusaurus.config.ts   Site-wide Docusaurus config
+
+Install Playwright's pinned Chromium before the visual gate on a new machine:
+
+```bash
+pnpm exec playwright install chromium
 ```
 
-## Contributing
+The Windows CI workflow uses `pnpm install --frozen-lockfile`, installs Chromium, and runs the complete documentation quality gate. Visual baselines are generated on that pinned Windows runner.
 
-Contributions to docs are welcome — typo fixes, clarifications, new guides, or restructuring.
+## Project layout
+
+```text
+src/pages/          Vocs MDX pages organized by public route
+openapi/            Nava Guardian and Nava Gateway OpenAPI source contracts
+src/components/     Client-side, no-network documentation explorers
+src/lib/            Pure models shared by the explorers and tests
+src/navigation.ts   Generated sidebar and top-navigation model
+src/styles.css      Project-owned documentation styling
+public/             Static images, fonts, and favicons
+tests/visual/       Playwright semantic checks and neutral-named baselines
+vocs.config.ts      Site-wide Vocs configuration
+```
 
-1. **Fork** the repo and create a branch off `main` (e.g. `docs/fix-quickstart-typo`).
-2. **Edit or add** Markdown files under the relevant section in [`docs/`](./docs). New pages are picked up automatically; if you need to reorder or rename, update [`sidebars.ts`](./sidebars.ts).
-3. **Preview locally** with `pnpm start` and make sure `pnpm build` passes without broken links or warnings.
-4. **Open a pull request** with a short description of what changed and why. Screenshots help for visual changes.
+## Contributing
 
-### Style notes
+1. Fork the repository and branch from `main`.
+2. Run the frozen setup commands above.
+3. Edit or add MDX under `src/pages/`. Navigation is generated; change `src/navigation.ts` only when classification or ordering rules must change.
+4. Run every verification command listed above. Use `pnpm test:visual -- --update-snapshots` only for intentional, reviewed visual changes on the pinned Windows environment.
+5. Open a pull request describing the documentation and evidence changes. Include screenshots when visual output changes.
 
-- Prefer short, scannable sentences and code examples over long prose.
-- Use relative links between doc pages so they survive restructuring.
-- Put images in `static/img/` and reference them with `/img/your-image.png`.
+Release-status and product-boundary claims must be verified against the current product contract. Prefer short, scannable prose and stable root-relative links.
diff --git a/docs/1-introduction/architecture-overview.md b/docs/1-introduction/architecture-overview.md
diff --git a/docs/1-introduction/execution-escrow.md b/docs/1-introduction/execution-escrow.md
diff --git a/docs/1-introduction/guardian.md b/docs/1-introduction/guardian.md