Migrating an existing in-repo component-docs project
Moving a project with its own component-evidence tooling onto the packaged runtime and initializer.
If your project already has its own component-evidence pipeline, it may include a custom generator under doc/component-docs/, hand-written CLI scripts and a project-specific package.json script graph. This page walks through moving evidence validation and publication to @takazudo/zudo-circuit-doc and circuit.config.ts, while retaining project-specific records and commands where needed.
This is a reviewed migration, not a find-and-replace. Check each step against the files and behavior your project currently uses.
1. Move the instance selection
If the old generator keeps its publication selection in a TypeScript module, map its InstanceSelection fields (recordIds, sourceIds, linkableSourceIds, documentSelections, expect) to the package's JSON selection file. The runtime reads this schema-validated file at circuit/ — see Reference → Publication schemas for its exact shape. Keep any separate document-verification history as a project-owned record if you still need it; it has no equivalent field in the config contract and is not consumed during generation.
2. Move the direct-routing fixture
Place the direct-routing fixture at . and set evidence.directRouting in circuit.config.ts to that path (see Reference → circuit.config.ts). The fixture's JSON shape stays the same.
3. Choose an inventory provider
If the existing inventory comes from board-generator scripts, set inventoryProvider.kind to "led-generator-v1" and list those scripts in inventoryProvider.specs. The inventory JSON's generator_specs field must match the configured paths exactly.
Otherwise, use the generic { kind: "manual" } profile. Under this profile, the inventory JSON's generator_specs field must be [] — not omitted or filled with stale paths from a generator that no longer runs. See Concepts → Inventory profiles.
4. Move project validation policy
If the old validator has project-specific gates, represent them in a policy JSON file and point validation.policy at it:
validation: {
policy: "circuit/policy.json",
},See Reference → Publication schemas → validation.policy for the available check types and options. Move each existing assertion deliberately and compare the new policy's results with the old validator before relying on it.
5. Write the publication assets allowlist
A project without a formal doc/public/ review may already serve files that a fresh scan flags. Run zudo-circuit-doc scan early, then either move each flagged file out of publicRoot or add it to circuit/ with a reason. See Concepts → Publication for restricted extensions and the preview files exempt by default.
6. Pick browser-smoke representatives
check-browser can derive up to three representatives once records are published, so browserSmoke.representatives is optional. Set it in Reference → circuit.config.ts → browserSmoke when you want specific component pages tested. Choose pages that represent different component types and availability states; the configured list stays stable as records are added.
What cannot be ported
Deploy configuration. The initializer and runtime do not configure deployment. Keep or write your host's deployment workflow so it publishes the built
doc/dist/output.Custom pre-build steps. The generated root
buildscript runs the runtime's model and page generation followed by the site build. Add any project-specific preparation to the rootpackage.jsonscripts.buildentry before those commands, for example:"build":. Root scripts are project-owned; see Concepts → Ownership and upgrades."node tools/ prepare- docs. mjs & & zudo- circuit- doc models & & zudo- circuit- doc generate & & pnpm - - dir doc build"