create-zudo-circuit-doc 0.1.0

package/templates/default/circuit/templates/project-docs/verification/bring-up.mdx

@@ -0,0 +1,55 @@
+---
+title: "Verification and bring-up report"
+description: "A revision-specific test plan and execution record with evidence, results, and remaining limits."
+sidebar_position: 10
+---
+
+Duplicate this page for a bounded verification or a specific hardware run. The initial state is **plan only; no procedure has been performed**. A new project must define its own sequence, operating limits, and acceptance criteria.
+
+## Test identity
+
+| Field | Entry |
+|---|---|
+| Report ID | Not assigned |
+| Question or behavior being tested | Not entered |
+| Plan or execution state | Plan only; not run |
+| Date, operator and location | Not entered |
+| Physical unit or specimen ID | Not entered |
+| Schematic and PCB revision | Not entered |
+| Firmware and stored configuration | Not entered |
+| Assembly deviations or rework | Not entered |
+| Related requirements and open questions | Not entered |
+
+If no hardware is available, record the work as a proposed procedure, document review, simulation, or other appropriate activity. Do not report a calculated prediction as a measurement.
+
+## Scope and prerequisites
+
+State what this activity can establish and what it cannot. Identify the actual setup, instruments, source, loads, fixtures, connection mapping, and relevant environmental conditions. Record instrument mode and measurement method where they change the meaning of a result.
+
+List prerequisites in the order needed for this project. Link the evidence that defines initial configuration and allowable conditions. Identify any unresolved prerequisite before execution; limits and sequences from another project or a reference design are not defaults for this circuit.
+
+## Acceptance criteria and observations
+
+| Check ID | Setup and action | Expected criterion and basis | Observation or raw evidence | Outcome |
+|---|---|---|---|---|
+| Not assigned | Not planned | Not defined | Not recorded | Not run |
+
+Define each criterion before evaluating the result. A useful outcome distinguishes pass, fail, inconclusive, blocked, and not run, keeping it separate from the evidence verdicts listed in `circuit/WORKFLOW.md`. A check can pass within its scope while a broader design question remains open.
+
+Where a staged sequence is necessary, state which result permits the next stage, why that dependency exists, and what action follows an unexpected result. Select the actual limits from this project's evidence and engineering review.
+
+## Captured evidence
+
+| Evidence reference | What it contains | Capture conditions | Revision or configuration association |
+|---|---|---|---|
+| None recorded | Not entered | Not entered | Not entered |
+
+Examples include meter readings, scope captures, logs, photographs, configuration readback, or dimensional measurements. Preserve raw observations and link them from the component evidence bundle or verification records. A filename alone does not establish what setup produced it.
+
+## Result and interpretation
+
+No result is recorded. Once executed, write what was directly observed, what was inferred, and what remains unresolved. Describe any unexpected behavior before proposing its cause. If a test changes the setup or the hardware partway through, preserve that transition and identify which observations belong to which state.
+
+## Follow-up and affected claims
+
+List claims, calculations, decisions, or next actions that this result supports or reopens. Update the canonical evidence coverage only for the scope actually demonstrated. Link a separate report for a repeated test or another physical revision.

package/templates/default/circuit.config.ts

@@ -0,0 +1,36 @@
+import type { CircuitConfig } from "@takazudo/zudo-circuit-doc/config";
+
+export default {
+  configVersion: 1,
+  project: {
+    name: "__PROJECT_NAME__",
+    title: "__SITE_TITLE__",
+  },
+  docs: {
+    root: "doc",
+    generatedContent: "doc/src/content/docs/components",
+    preflight: "circuit/generated/preflight.json",
+    publicRoot: "doc/public",
+    dist: "doc/dist",
+    agentResources: true,
+  },
+  evidence: {
+    contractVersion: 1,
+    bundlesRoot: ".claude/skills",
+    ownerPrefix: "component-",
+    auditSkill: "component-spec-audit",
+    integrationSkill: "circuit-spec-integration",
+    inventory: ".claude/skills/component-spec-audit/references/inventory.json",
+    integrationRules: ".claude/skills/circuit-spec-integration/references/rules.json",
+    directRouting: ".claude/skills/component-spec-audit/references/direct-routing.json",
+    vendorQualifiers: ".claude/skills/component-spec-audit/references/external-vendor-qualifiers.json",
+    sourceCache: ".circuit-cache/sources",
+  },
+  inventoryProvider: { kind: "manual" },
+  publication: {
+    selection: "circuit/publication/selection.json",
+    assets: "circuit/publication/assets.json",
+  },
+  cad: { enabled: false, libraryName: "__LIBRARY_NAME__" },
+  validation: {},
+} satisfies CircuitConfig;

package/templates/default/doc/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "__PROJECT_NAME__-doc",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "dev": "zudo-circuit-doc generate --config ../circuit.config.ts && run-parallel dev:zfb dev:history dev:circuit",
+    "build": "zfb build",
+    "preview": "zfb preview",
+    "check": "zfb check",
+    "check:links": "node scripts/check-links.js",
+    "dev:zfb": "zfb dev",
+    "dev:zfb:network": "zfb dev --host 0.0.0.0",
+    "dev:network": "run-parallel dev:zfb:network dev:history",
+    "dev:history": "doc-history-server --port 4322 --content-dir src/content/docs",
+    "dev:circuit": "zudo-circuit-doc generate --watch --config ../circuit.config.ts"
+  },
+  "dependencies": {
+    "@takazudo/zfb": "2.21.0",
+    "@takazudo/zfb-runtime": "2.21.0",
+    "@takazudo/zfb-md-wasm": "2.21.0",
+    "@takazudo/zudo-doc": "5.27.0",
+    "@takazudo/zudo-doc-history-server": "5.27.0",
+    "@takazudo/zudo-circuit-doc": "^0.1.0",
+    "zod": "^4.3.6",
+    "preact": "^10.29.1",
+    "preact-render-to-string": "^6.6.6",
+    "diff": "^8.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/templates/default/doc/pages/docs/[[...slug]].tsx

@@ -0,0 +1,68 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locked manifest (#2653 Decision 4): a SELF-CONTAINED doc-route stub retained
+// for explicit host route ownership. zfb 2.13.1 also serves injected dynamic
+// routes in dev. This stub reconstructs the doc route from scratch using ONLY the
+// sanctioned package entrypoints — no `pages/lib`, no `@/config`:
+//   1. the `virtual:zudo-doc-route-context` virtual module (serializable
+//      settings/translations/tagVocabulary/colorSchemes payload),
+//   2. `@takazudo/zudo-doc/route-context` (`createRouteContext`),
+//   3. `@takazudo/zudo-doc/chrome` (`createChrome`), and
+//   4. `virtual:zudo-doc-chrome-bindings` (the host-callables channel).
+// The bindings import is unconditional: the routes plugin supplies an empty
+// object when `chromeBindingsModule` is unset, while configured projects get
+// their MDX/chrome bindings without editing this stub.
+// Makes `/docs/getting-started/` return 200 in BOTH `zfb dev` and `zfb build`.
+// The route-injection build test covers the corresponding package-owned route;
+// this kept file remains the explicit host-owned seam.
+//
+// docHistory note: when the docHistory feature is selected, the generator
+// patches this file to statically import DocHistory from
+// "@takazudo/zudo-doc/doc-history" and merge it over chromeBindings in
+// createChrome's hostBindings (second) argument —
+// DocHistory's chrome-derive default is a no-op stub (unlike
+// DesignTokenPanelBootstrap, which the package auto-defaults), so without
+// that patch the doc-history button never hydrates on this route.
+
+import type { JSX } from "preact";
+import { routeContext } from "virtual:zudo-doc-route-context";
+import {
+  createRouteContext,
+  type RouteContextPayload,
+} from "@takazudo/zudo-doc/route-context";
+import { createChrome } from "@takazudo/zudo-doc/chrome";
+import { DocHistory } from "@takazudo/zudo-doc/doc-history";
+import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
+import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
+import "../lib/_circuit-doc-islands";
+
+const ctx = routeContext as unknown as RouteContextPayload;
+const routeCtx = createRouteContext(ctx);
+const { renderDocPage } = createChrome(routeCtx, {
+  ...chromeBindings,
+  ...defineChromeBindings({ DocHistory }),
+});
+
+export const frontmatter = { title: "Docs" };
+
+export function paths(): Array<{ params: { slug: string[] }; props: unknown }> {
+  const locale = routeCtx.defaultLocale;
+  const source = routeCtx.resolveNavSource(locale, undefined);
+  return routeCtx.buildDocRouteEntries({
+    source,
+    locale,
+    routeSig: `docs;${locale}`,
+  }).map((item) => ({
+    params: { slug: item.slugParams },
+    props: item.props,
+  }));
+}
+
+type PageArgs = { params: { slug: string[] } } & Record<string, unknown>;
+
+export default function DocsPage(props: PageArgs): JSX.Element {
+  return renderDocPage(props as never, {
+    locale: routeCtx.defaultLocale,
+    docHistoryContentDir: routeCtx.settings.docsDir,
+  });
+}

package/templates/default/doc/pages/index.tsx

@@ -0,0 +1,6 @@
+// Locked manifest (epic zudolab/zudo-doc#2651, Decision 4 on #2653): the home
+// route is a 1-line re-export of the package-owned STATIC index route.
+// Verified by the #2652 spike (Q2) to build, dev-render, and hydrate — a
+// dynamic route (see pages/docs/[[...slug]].tsx) cannot use this form because
+// `paths()` static-AST-extraction requires source, not compiled `dist/` JS.
+export { default } from "@takazudo/zudo-doc/routes/index";

package/templates/default/doc/pages/lib/_circuit-doc-islands.ts

@@ -0,0 +1,4 @@
+// ADR-016 seam: the package-owned island seed module. Importing it from the
+// docs route (side-effect only) registers the footprint/WRL preview islands
+// so they hydrate without this host forking a route stub of its own.
+import "@takazudo/zudo-circuit-doc/islands";

package/templates/default/doc/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#7c3aed"/>
+  <text x="16" y="23" font-family="system-ui,sans-serif" font-size="20" font-weight="700" fill="white" text-anchor="middle">Z</text>
+</svg>