FUNDOCS Navigation Contract

FUNDOCS has one documentation information-architecture policy. Quartz turns that policy and its post-filter content graph into a versioned, navigation-only artifact; FUNDEV and Quartz Explorer render different projections of that same release.

Boundaries

The artifact is published at:

/dev/docs/wiki/static/fundoocs-navigation.v1.json

It has schemaVersion: 1, a release generation, ordered root sections, and shortcuts. Every node is a logical slug, title, folder flag, drawer flag, and recursive children. It contains no article content or untrusted URL/icon values.

Tree and visibility rules

1. Quartz derives the tree from post-filter content, so private or unlisted: true pages are absent.
2. A directory hub is the page at folder/index; its title and optional nav metadata name the folder.
3. nav.order is a finite numeric priority. Remaining nodes sort folders first, then title and slug.
4. A hub may declare nav.drawer: false to remain in Quartz Explorer but stay out of FUNDEV’s compact parent drawer.
5. The parent drawer renders root sections, shortcuts, and only their direct visible folder hubs. The Explorer retains the full recursive tree.
6. FUNDEV validates the exact v1 shape, bounded tree depth/size, logical slugs, text, and a local trusted-icon allowlist before rendering. A bad or unavailable artifact leaves only the stable Docs Overview route.

Release pipeline

flowchart LR
  A[Markdown + Quartz policy] --> B[Quartz staged build]
  B --> C[Navigation and search artifacts]
  C --> D{Validate release}
  D -->|valid| E[Atomic current pointer]
  D -->|invalid| F[Keep prior generation]
  E --> G[Quartz Explorer]
  E --> H[FUNDEV drawer, palette, landing]

npm run build:docs is the production publication command:

cd /home/usr/funday/dev/docs
npm run build:docs

It builds Quartz into an isolated staging directory under .quartz-releases/, generates case-preserving aliases there, validates index.html, contentIndex.json, and the v1 navigation artifact, then atomically replaces .quartz-releases/current. The release server resolves that pointer per request, so a valid docs-only navigation/content release does not require a frontend build or service restart. It retains the current and immediately preceding generation.

Never publish with npx quartz build directly into live output. Never hand-edit generated release artifacts.

Failure behavior and recovery

• A failed build, alias pass, missing artifact, or invalid manifest cannot replace the current generation.
• Before the first atomic publication, the server serves legacy public/ output. After publication begins, a missing current release returns 503 rather than silently serving stale legacy files.
• If an artifact fetch or schema validation fails in FUNDEV, the drawer removes dynamic documentation entries and keeps /dev/docs available.
• To inspect the focused publication guard locally, run npm run test:publication from dev/docs.

Related pages

• FUNDOCS Architecture
• Quartz SSOT Guidelines
• Dev access gating