Nava Docs

The official Nava documentation site, built with Vocs.

Sections

• 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.

Setup and local development

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.

corepack enable
corepack prepare pnpm@10.33.3 --activate
pnpm install --frozen-lockfile
pnpm dev

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

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

Install Playwright's pinned Chromium before the visual gate on a new machine:

pnpm exec playwright install chromium

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.

Project layout

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

Contributing

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.

Release-status and product-boundary claims must be verified against the current product contract. Prefer short, scannable prose and stable root-relative links.