Skip to main content

Maintaining This Handbook

The handbook is only useful if it stays true. Two rules.

1. Single source of truth​

The deep engineering docs are synced, not copied by hand. They live in the repo (docs/claude/*.md, CLAUDE.md, and selected root specs) and are pulled into Canonical Reference by docs/scripts/sync-handbook.mjs on every build (prestart / prebuild). The generated handbook/reference/ folder is git-ignored.

  • To change a reference doc: edit the source in the repo, rebuild. Never edit the copy — it's overwritten.
  • To add a source to the sync: drop a .md in docs/claude/, or add it to ROOT_SPECS in the sync script.
  • The narrative pages (this section, Product, Engineering, etc.) are hand-authored and committed — edit them directly.

This mirrors the knowledge-base thesis: meet the data where it lives, ingest into one view. The handbook is connector #1.

2. No superficial pages​

A page that reads "done" but is empty is worse than no page — it hides the gap. So:

  • State what is real and sourced. Link the source.
  • Flag gaps with a :::warning Gap block that says what's missing and what would fill it.
  • Never invent numbers, testimonials, or client stories.

Running it locally​

cd /Users/G/basis/docs
npm install          # first time only
npm start            # runs sync-handbook then serves on http://localhost:3000

npm run build produces the static site (also runs the sync first). npm run sync-handbook refreshes just the reference view.

Structure​

docs/
├─ docusaurus.config.ts     # site config (two docs instances: docs + handbook)
├─ sidebars.ts              # Product Docs (customer-facing) sidebar
├─ sidebarsHandbook.ts      # Handbook (internal) sidebar
├─ scripts/sync-handbook.mjs# pulls repo docs → handbook/reference/ (generated)
├─ handbook/                # THIS handbook (narrative pages, committed)
│  └─ reference/            # generated, git-ignored
└─ docs/                    # customer-facing Product Docs