Ownership and upgrades

What belongs to the package, the project, or the generator; why there is no update command; and how to refresh the scaffold by hand.

Who owns what

Generated MDX is never hand-edited: change the evidence or the selection, then regenerate. A hand-edited generated file is reported as drift by pnpm check; one with its generated-page marker removed entirely is reported as an ownership conflict — the emitter refuses to overwrite a marker-less target, and never partially writes on any conflict.

Create-only: there is no update command

create-zudo-circuit-doc scaffolds a project once. There is deliberately no zudo-circuit-doc update or create-zudo-circuit-doc upgrade command — a generated project's authored content (brief, architecture, decisions, evidence) is yours from the moment it's created, and an automatic in-place rewrite of project files is exactly the kind of silent mutation this project's evidence model is built to avoid elsewhere. Two things do get newer over time without an update command:

• The runtime package (@takazudo/zudo-circuit-doc) — an ordinary pnpm update bumps it like any other dependency, because the CLI, validator and MDX renderer are code your project depends on, not files copied into your project.

• The scaffold (the zudo-doc host glue under doc/, package.json, pnpm-workspace.yaml) — these files are copied at creation time, and upgrading them is a manual, reviewable scaffold-refresh, described next.

The scaffold-refresh procedure

The initializer's doc/ host glue is synced from a pinned create-zudo-doc release, with a few project-specific lines layered on top (the chrome-bindings import, the islands seed import, the package's styles.css import). ZUDO_DEPS_PINS.md, generated into every new project, records exactly which files came from where, at which pinned commit, and which lines were added on top of the vendored scaffold:

## create-zudo-doc
- pinned: <commit> (v5.27.0)
- files: doc/pages/docs/[[...slug]].tsx, doc/pages/index.tsx, doc/tsconfig.json,
  doc/src/styles/global.css, doc/scripts/check-links.js
- notes: doc/pages/docs/[[...slug]].tsx carries one added import beyond the upstream stub;
  doc/src/styles/global.css has one added @import line. Re-apply both after any re-copy.

To refresh a project's scaffold by hand after a new create-zudo-doc release:

1. Run the pinned (or newer) create-zudo-doc into a scratch directory and diff its app/ output against the files ZUDO_DEPS_PINS.md lists.

2. Apply the upstream diff to your project's copies.

3. Re-apply the project-specific lines ZUDO_DEPS_PINS.md's notes call out (they are not part of the upstream scaffold, and a plain re-copy would silently drop them).

4. Update ZUDO_DEPS_PINS.md's pinned:/updated: fields.

Adding an authored section

A new top-level section (a sibling of project/, architecture/, research/, decisions/, verification/) needs three things, all in doc/zfb.config.ts, which is project-owned:

1. A content directory. doc/src/content/docs/<section>/ with its own index.mdx.

2. A headerNav entry whose categoryMatch matches that directory name exactly. categoryMatch is how zudo-doc decides which sidebar to render for a given page — a section with no matching categoryMatch gets an empty sidebar, silently, with no build error. Copy an existing entry's shape rather than writing one from scratch:

   { label: "My Section", path: "/docs/my-section", categoryMatch: "my-section" }

3. A slot in the 6-item header nav cap. The scaffold's default headerNav already uses 6 items (Project, Architecture, Research, Decisions, Verification, Components) — the same number the generated site's own What you get page counts. Adding a 7th top-level entry means either removing one, or nesting the new section as a children entry under an existing one (see headerNav[].children — the scaffold's own Components entry nests "Catalog & Records" and "Raw agent resources" this way):

   {
     label: "Components",
     path: "/docs/components",
     categoryMatch: "components",
     children: [
       { label: "Catalog & Records", path: "/docs/components", categoryMatch: "components" },
       { label: "My Section", path: "/docs/my-section", categoryMatch: "my-section" },
     ],
   }

The project/ entry is required by the shared workflow entry: every workflow starts by reading the brief and next actions there, so removing or renaming it breaks the workflow text's own instructions, not just navigation. The other four scaffold sections (architecture, research, decisions, verification) are conventional, not load-bearing — rename or drop them if your project structures its authored docs differently, as long as project/ stays.