create-zudo-circuit-doc 0.1.0

package/dist/scaffold.js

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+// Files carrying these extensions are copied byte-for-byte: they are either
+// binary (previews, 3D models, fonts) or, in the case of .svg, listed
+// explicitly by the spec as skipped even though it is text (spec #6).
+const BINARY_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".svg",
+    ".wrl",
+    ".step",
+    ".stp",
+    ".pdf",
+    ".zip",
+    ".gz",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+]);
+const PLACEHOLDER_TOKENS = [
+    "__PROJECT_NAME__",
+    "__SITE_TITLE__",
+    "__LIBRARY_NAME__",
+];
+export function placeholdersFromPlan(plan) {
+    return {
+        __PROJECT_NAME__: plan.name,
+        __SITE_TITLE__: plan.title,
+        __LIBRARY_NAME__: plan.library,
+    };
+}
+/** Throws a CliError, unchanged, if the destination exists and is not empty (spec #4). There is no force flag. */
+export function checkDestinationCollision(destinationPath) {
+    let stat;
+    try {
+        stat = fs.statSync(destinationPath);
+    }
+    catch {
+        return; // Missing destination is fine.
+    }
+    if (!stat.isDirectory()) {
+        throw new CliError(`Cannot create project: "${destinationPath}" already exists and is not a directory.`);
+    }
+    const entries = fs.readdirSync(destinationPath);
+    if (entries.length > 0) {
+        throw new CliError(`Cannot create project: "${destinationPath}" already exists and is not empty.`);
+    }
+}
+function resolveTemplateDirPath(templateDir) {
+    return typeof templateDir === "string" ? templateDir : fileURLToPath(templateDir);
+}
+function substitutePlaceholders(text, values) {
+    let result = text;
+    for (const token of PLACEHOLDER_TOKENS) {
+        result = result.replaceAll(token, values[token]);
+    }
+    return result;
+}
+function copyTemplateTree(sourceDir, targetDir, values, beforeCopyFile, relPath) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+        const entryRelPath = relPath ? `${relPath}/${entry.name}` : entry.name;
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
+        const targetPath = path.join(targetDir, targetName);
+        if (entry.isDirectory()) {
+            copyTemplateTree(sourcePath, targetPath, values, beforeCopyFile, entryRelPath);
+            continue;
+        }
+        if (!entry.isFile()) {
+            throw new Error(`Unsupported template entry (not a file or directory): ${entryRelPath}`);
+        }
+        beforeCopyFile?.(entryRelPath);
+        const stat = fs.statSync(sourcePath);
+        const ext = path.extname(entry.name).toLowerCase();
+        if (BINARY_EXTENSIONS.has(ext)) {
+            fs.copyFileSync(sourcePath, targetPath);
+        }
+        else {
+            const contents = fs.readFileSync(sourcePath, "utf8");
+            fs.writeFileSync(targetPath, substitutePlaceholders(contents, values), "utf8");
+        }
+        fs.chmodSync(targetPath, stat.mode);
+    }
+}
+function assertNoPlaceholdersRemain(dir, relPath = "") {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryRelPath = relPath ? `${relPath}/${entry.name}` : entry.name;
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            assertNoPlaceholdersRemain(entryPath, entryRelPath);
+            continue;
+        }
+        const ext = path.extname(entry.name).toLowerCase();
+        if (BINARY_EXTENSIONS.has(ext))
+            continue;
+        const contents = fs.readFileSync(entryPath, "utf8");
+        for (const token of PLACEHOLDER_TOKENS) {
+            if (contents.includes(token)) {
+                throw new Error(`Placeholder ${token} was not replaced in generated file: ${entryRelPath}`);
+            }
+        }
+    }
+}
+const RUNTIME_PACKAGE_NAME = "@takazudo/zudo-circuit-doc";
+const RUNTIME_SPEC_MANIFESTS = ["package.json", "doc/package.json"];
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies"];
+/**
+ * Overwrites the `@takazudo/zudo-circuit-doc` dependency spec in both
+ * manifests with `runtimeSpec` (spec #58's `--runtime-spec`). Both manifests
+ * are required to already declare the dependency — every shipped template
+ * does — so a missing one is a template bug, not a user error.
+ */
+function applyRuntimeSpec(stagingDir, runtimeSpec) {
+    for (const relPath of RUNTIME_SPEC_MANIFESTS) {
+        const manifestPath = path.join(stagingDir, ...relPath.split("/"));
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        let found = false;
+        for (const field of DEPENDENCY_FIELDS) {
+            const dependencies = manifest[field];
+            if (dependencies && typeof dependencies === "object" && RUNTIME_PACKAGE_NAME in dependencies) {
+                dependencies[RUNTIME_PACKAGE_NAME] = runtimeSpec;
+                found = true;
+            }
+        }
+        if (!found) {
+            throw new Error(`${relPath} has no "${RUNTIME_PACKAGE_NAME}" dependency to apply --runtime-spec to.`);
+        }
+        fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    }
+}
+/** claude removes AGENTS.md, codex removes CLAUDE.md, none removes both, both removes neither (spec #6). `.claude/skills/**` is never touched here, so it always stays. */
+function applyAgentFilter(dir, agent) {
+    const removeIfExists = (name) => {
+        const target = path.join(dir, name);
+        if (fs.existsSync(target))
+            fs.rmSync(target, { force: true });
+    };
+    if (agent === "claude")
+        removeIfExists("AGENTS.md");
+    else if (agent === "codex")
+        removeIfExists("CLAUDE.md");
+    else if (agent === "none") {
+        removeIfExists("AGENTS.md");
+        removeIfExists("CLAUDE.md");
+    }
+}
+/**
+ * Composes the project into a sibling staging directory, then renames it
+ * onto the destination in one atomic step (spec #6). On any failure the
+ * staging directory is removed and the destination is left untouched.
+ */
+export function composeProject(params) {
+    const { plan, templateDir, randomSuffix, beforeCopyFile } = params;
+    const sourceDir = resolveTemplateDirPath(templateDir);
+    // An existing (empty) destination is filled in place: renaming over it would
+    // swap the directory inode out from under a shell whose cwd is that directory.
+    const destinationExists = fs.existsSync(plan.destinationPath);
+    const stagingDir = path.join(destinationExists ? plan.destinationPath : path.dirname(plan.destinationPath), `.create-zudo-circuit-doc-staging-${randomSuffix()}`);
+    try {
+        copyTemplateTree(sourceDir, stagingDir, placeholdersFromPlan(plan), beforeCopyFile, "");
+        assertNoPlaceholdersRemain(stagingDir);
+        applyAgentFilter(stagingDir, plan.agent);
+        if (plan.runtimeSpec !== undefined)
+            applyRuntimeSpec(stagingDir, plan.runtimeSpec);
+        if (destinationExists) {
+            for (const entry of fs.readdirSync(stagingDir)) {
+                fs.renameSync(path.join(stagingDir, entry), path.join(plan.destinationPath, entry));
+            }
+            fs.rmdirSync(stagingDir);
+        }
+        else {
+            fs.renameSync(stagingDir, plan.destinationPath);
+        }
+    }
+    catch (error) {
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+        throw new CliError(`Failed to create project at "${plan.destinationPath}": ${error.message}`);
+    }
+}

package/dist/shell-quote.d.ts

@@ -0,0 +1,2 @@
+/** Quotes `value` for a POSIX shell only when it contains characters that would need it. */
+export declare function shellQuote(value: string): string;

package/dist/shell-quote.js

@@ -0,0 +1,7 @@
+const SAFE_UNQUOTED_RE = /^[A-Za-z0-9_.\-/]+$/;
+/** Quotes `value` for a POSIX shell only when it contains characters that would need it. */
+export function shellQuote(value) {
+    if (SAFE_UNQUOTED_RE.test(value))
+        return value;
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/validate.d.ts

@@ -0,0 +1,18 @@
+/** Throws a CliUsageError if `name` does not satisfy the npm package-name grammar (spec #3). */
+export declare function validateName(name: string): void;
+/** Throws a CliUsageError if `title` is not 1-80 printable characters excluding quoting-sensitive symbols (spec #3). */
+export declare function validateTitle(title: string): void;
+/** Throws a CliUsageError if `library` does not match the KiCad library-name grammar (spec #3). */
+export declare function validateLibrary(library: string): void;
+/**
+ * Throws a CliUsageError if `spec` is not usable as the
+ * `@takazudo/zudo-circuit-doc` dependency spec (spec #58). Accepts a semver
+ * range/dist-tag, or a `file:` spec whose path is absolute. A relative
+ * `file:` path is rejected rather than rebased: `doc/package.json` sits one
+ * directory deeper than `package.json`, so one relative string cannot be
+ * correct in both places without silently pointing `doc/` at the wrong
+ * ancestor — pass an absolute path instead.
+ */
+export declare function validateRuntimeSpec(spec: string): void;
+/** "my-thing" -> "My Thing". Used as the default --title derived from --name. */
+export declare function titleCaseFromName(name: string): string;

package/dist/validate.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { CliUsageError } from "./errors.js";
+const UNSCOPED_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const SCOPED_NAME_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+/** Throws a CliUsageError if `name` does not satisfy the npm package-name grammar (spec #3). */
+export function validateName(name) {
+    if (name.length < 1 || name.length > 214) {
+        throw new CliUsageError(`Invalid --name "${name}": must be 1-214 characters long.`);
+    }
+    if (name === "node_modules" || name.includes("node_modules")) {
+        throw new CliUsageError(`Invalid --name "${name}": must not be or contain "node_modules".`);
+    }
+    if (!UNSCOPED_NAME_RE.test(name) && !SCOPED_NAME_RE.test(name)) {
+        throw new CliUsageError(`Invalid --name "${name}": must match the npm package-name grammar (lowercase, optionally scoped).`);
+    }
+}
+// Excluded because the title is substituted verbatim into TS string literals
+// and MDX frontmatter — these characters would break that quoting.
+const TITLE_FORBIDDEN_RE = /["'`\\$<>{}]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+/** Throws a CliUsageError if `title` is not 1-80 printable characters excluding quoting-sensitive symbols (spec #3). */
+export function validateTitle(title) {
+    if (title.length < 1 || title.length > 80) {
+        throw new CliUsageError(`Invalid --title "${title}": must be 1-80 characters long.`);
+    }
+    if (CONTROL_CHAR_RE.test(title)) {
+        throw new CliUsageError(`Invalid --title "${title}": must not contain control characters.`);
+    }
+    if (TITLE_FORBIDDEN_RE.test(title)) {
+        throw new CliUsageError(`Invalid --title "${title}": must not contain any of " ' \` \\ $ < > { }.`);
+    }
+}
+const LIBRARY_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** Throws a CliUsageError if `library` does not match the KiCad library-name grammar (spec #3). */
+export function validateLibrary(library) {
+    if (!LIBRARY_RE.test(library)) {
+        throw new CliUsageError(`Invalid --library "${library}": must match ${LIBRARY_RE.source}.`);
+    }
+}
+// eslint-disable-next-line no-control-regex
+const RUNTIME_SPEC_CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+// Permissive semver-range grammar (npm dist-tags like "latest"/"next" also
+// match): digits, dots, the usual range operators, hyphen ranges and OR.
+// This is deliberately not a full semver-range parser — it only rejects
+// values that could not possibly be a range or a "file:" spec.
+const SEMVER_RANGE_RE = /^[0-9A-Za-z.\-+^~*<>=|\s]+$/;
+/**
+ * Throws a CliUsageError if `spec` is not usable as the
+ * `@takazudo/zudo-circuit-doc` dependency spec (spec #58). Accepts a semver
+ * range/dist-tag, or a `file:` spec whose path is absolute. A relative
+ * `file:` path is rejected rather than rebased: `doc/package.json` sits one
+ * directory deeper than `package.json`, so one relative string cannot be
+ * correct in both places without silently pointing `doc/` at the wrong
+ * ancestor — pass an absolute path instead.
+ */
+export function validateRuntimeSpec(spec) {
+    // 1024, not 200 like the other options: a "file:" spec carries a full
+    // absolute path (e.g. verify-pack's tmpdir tarball path), which can run
+    // considerably longer than a semver range on some platforms/CI runners.
+    if (spec.length < 1 || spec.length > 1024) {
+        throw new CliUsageError(`Invalid --runtime-spec "${spec}": must be 1-1024 characters long.`);
+    }
+    if (RUNTIME_SPEC_CONTROL_CHAR_RE.test(spec)) {
+        throw new CliUsageError(`Invalid --runtime-spec "${spec}": must not contain control characters.`);
+    }
+    if (spec.startsWith("file:")) {
+        const filePath = spec.slice("file:".length);
+        if (filePath.length === 0 || !path.isAbsolute(filePath)) {
+            throw new CliUsageError(`Invalid --runtime-spec "${spec}": a "file:" spec must use an absolute path (relative "file:" paths are not supported, since doc/package.json sits one directory deeper than package.json).`);
+        }
+        return;
+    }
+    if (!SEMVER_RANGE_RE.test(spec)) {
+        throw new CliUsageError(`Invalid --runtime-spec "${spec}": must be a semver range/dist-tag or a "file:" spec with an absolute path.`);
+    }
+}
+/** "my-thing" -> "My Thing". Used as the default --title derived from --name. */
+export function titleCaseFromName(name) {
+    return name
+        .split(/[-_]+/)
+        .filter((word) => word.length > 0)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads the package version from package.json at runtime, resolved relative
+ * to `baseUrl` (pass `import.meta.url` from src or dist — both sit one
+ * directory below the package root, spec #9).
+ */
+export declare function readPackageVersion(baseUrl: string | URL): string;

package/dist/version.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Reads the package version from package.json at runtime, resolved relative
+ * to `baseUrl` (pass `import.meta.url` from src or dist — both sit one
+ * directory below the package root, spec #9).
+ */
+export function readPackageVersion(baseUrl) {
+    const packageJsonUrl = new URL("../package.json", baseUrl);
+    const contents = readFileSync(fileURLToPath(packageJsonUrl), "utf8");
+    const pkg = JSON.parse(contents);
+    return pkg.version;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "create-zudo-circuit-doc",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Create a new zudo-circuit-doc project.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Takazudo/zudo-circuit-doc.git",
+    "directory": "packages/create-zudo-circuit-doc"
+  },
+  "bugs": {
+    "url": "https://github.com/Takazudo/zudo-circuit-doc/issues"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "circuit",
+    "zudo-circuit-doc",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-zudo-circuit-doc": "./bin/create-zudo-circuit-doc.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "!dist/**/*.test.*"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test \"test/**/*.test.ts\""
+  }
+}

package/templates/default/.claude/skills/circuit-spec-integration/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: circuit-spec-integration
+description: Audit behavior that spans more than one exact component, such as shared supplies, signal boundaries, startup and reset states, protection, sensing, thermal coupling, firmware assumptions and as-built state. Use whenever a question, substitution or design change involves several component records or a stage beyond a single datasheet.
+---
+
+# Circuit specification integration
+
+Individually valid components do not prove the whole circuit. This skill handles the cross-component rules in `references/rules.json`. The canonical workflow is [circuit/WORKFLOW.md](../../../circuit/WORKFLOW.md).
+
+1. Run `pnpm exec zudo-circuit-doc validate` (or `pnpm circuit:check`) and note pre-existing failures.
+2. Read `references/rules.json` and load every exact owner bundle named by each matching rule, through the component-spec-audit skill. Resolve manufacturer, MPN and order codes independently; reject conflicts, same-name wrong-vendor parts and ambiguous bare names. Load subordinate records directly.
+3. Use the listed fact IDs with their exact conditions and locators. An `UNSOURCED` fact cannot close a domain, and design connectivity cannot prove programmed, assembled or measured state.
+4. For a substitution or design change, report the affected rule, the raw facts, recalculated margins with their dependencies, the evidence stages still missing, and one honest verdict. Do not change design files silently.
+5. Recompute conditioned calculations from their inputs. The validator checks the arithmetic, not the units or the reading of the source table; check those yourself.
+
+## Adding a rule
+
+The rule list may be empty; `{ "schema_version": 1, "rules": [] }` is valid. Add a rule **only when a real interaction exists** between exact components. A rule names its `rule_id`, `domain`, `record_ids`, `fact_ids` (owned by those records), `conditions`, `verdict`, `refusal` text and any `conditioned_calculations`.
+
+An evidence chain lists stages in order, from the official source and the conditioned requirement through the netlist, symbol and footprint, PCB orientation, BOM and placement, as-built and programmed state, to bench results. Every stage stays `OPEN` with empty `fact_ids` until real evidence exists. A completed early stage never implies a later one, and a generated netlist is never `CONFIRMED`.
+
+After editing rules, update the integration count lock `expect.integrationRules` in `circuit/publication/selection.json`, then run `pnpm circuit:generate` and `pnpm check`.

package/templates/default/.claude/skills/circuit-spec-integration/references/rules.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "rules": []
+}

package/templates/default/.claude/skills/component-spec-audit/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: component-spec-audit
+description: Audit exact electronic-component identities and evidence, and run the end-to-end workflow for adding or replacing a component. Use whenever circuit, schematic, PCB, BOM, firmware, bring-up, substitution or documentation work could depend on a component rating, pin, package, source, CAD asset, publication or interaction.
+---
+
+# Component spec audit
+
+Protect the design from plausible-looking but wrong component claims. Manufacturer documents are the authority for component behavior; the inventory is the list of orderable identities; each owner bundle is the evidence for one exact component. The canonical workflow is [circuit/WORKFLOW.md](../../../circuit/WORKFLOW.md); this skill is its entry for component work.
+
+## Audit existing components
+
+1. Run the validator before relying on any record:
+
+   ```sh
+   pnpm exec zudo-circuit-doc validate
+   ```
+
+   (`pnpm circuit:check` runs the same command.) Note pre-existing failures before editing, and read the `SCOPE:` line: with the manual inventory provider, placements are declared, not bound to a schematic.
+2. Resolve the component through `references/inventory.json` by exact manufacturer and complete MPN, supplier order code, function or placement, then load the owner bundle named by the line's `owner_skill`. A bare base name is not an identity. Load subordinate records directly; never answer a subordinate query from its parent.
+3. Read the owner's `manifest.json`, `sources.json`, `facts.json`, `coverage.json`, `routing.json`, `interactions.json` and `pin-map.json`. Standalone and subordinate records get the same rigor.
+4. Keep the contract's distinctions: source authority versus availability, fact class, provenance, conditions, calculation dependencies and the six verdicts, spelled exactly. The frozen prose is the package's [contract.md](../../../node_modules/@takazudo/zudo-circuit-doc/contract/contract.md).
+5. Cross-check claims against the pin map and the current design state. For effects that span components, also load [circuit-spec-integration](../circuit-spec-integration/SKILL.md).
+6. If an authoritative source cannot be retrieved, or its retained extract does not support the claim, report `SOURCE UNAVAILABLE` and `UNSOURCED`. Never reconstruct a fact from memory or from a same-name or family part.
+7. Report exact fact IDs, source IDs, locators, conditions, calculations and one allowed verdict. Keep proposed design changes separate from the audit result.
+
+## Add or replace a component
+
+Follow [the new-component workflow](references/new-component-workflow.md) in order. It covers identity, the owner bundle, the manual inventory profile, optional CAD, the publication selection, regeneration and checks, and it is the only onboarding procedure; do not create a separate catalog-update skill.
+
+Start a new owner bundle with:
+
+```sh
+pnpm exec zudo-circuit-doc new-component SUFFIX
+```
+
+Replace every placeholder value the template contains; the validator fails on any that remain. Keep downloads in the ignored `.circuit-cache/sources/` directory, retain short normalized extracts in `sources.json`, and use `pnpm exec zudo-circuit-doc validate --online` or `--refresh-source SOURCE_ID` only for an explicit source refresh.

package/templates/default/.claude/skills/component-spec-audit/references/contract.md

@@ -0,0 +1,21 @@
+# Frozen component-spec contract (version 1)
+
+The central inventory is generated-spec identity truth; an owner record is evidence truth. One inventory line represents one nonblank LCSC/orderable identity and may have many placements. Bare-copper pogo and test pads remain explicit exclusions.
+
+Every standalone or subordinate record uses the same files and schema. Subordinates receive their own record, source, fact, interaction, routing, coverage, and pin-map IDs; parentage changes organization, never rigor.
+
+A subordinate's `parent_record_id` resolves to a standalone record in the same bundle. Each record lists exactly all and only its assigned source, fact, and interaction IDs, has direct positive/negative routing plus coverage and pin-map data, and owns no unexplained orphan data. Each open domain is a named entry matched one-for-one by `OPEN` coverage with an explicit reason.
+
+Every coverage entry also carries a machine-readable `blocking_fact_ids` array. For an `OPEN` entry it names the exact same-record facts whose non-PASS verdicts keep the domain open; each member must carry a verdict of `UNSOURCED` or `NEEDS BENCH`, or cite a `SOURCE UNAVAILABLE` source. The converse is enforced too: whenever any fact listed in `fact_ids` meets that same blocking test, `blocking_fact_ids` must name at least one of them. It may be empty only when no listed fact addresses the domain in that sense — a `NOT APPLICABLE` fact never blocks, so an `OPEN` entry whose only evidence is `NOT APPLICABLE` correctly keeps the array empty. Independently, a reason whose text claims evidence is unavailable, lower-authority, or `UNSOURCED` must cite those facts through `blocking_fact_ids` rather than leave the claim unverifiable.
+
+## Evidence retention
+
+A source lock records document title/number, revision/date, primary and optional alternate authoritative URLs, retrieval date, authority class, SHA-256, physical PDF page index, printed label, and exact section/table/figure/row locator. Retain a normalized, minimal evidence extract beside the locator so a reviewer can audit a critical claim without redistributing a PDF. An inaccessible source is `SOURCE UNAVAILABLE`; its SHA-256 is always the all-zero sentinel. Its extract may remain for audit history but cannot promote a new claim or invite a memory-based fallback.
+
+Fact classes are `ABSOLUTE_MAXIMUM`, `RECOMMENDED_OPERATION`, `GUARANTEED_ELECTRICAL`, `TYPICAL_CURVE`, `TRANSIENT`, `PROTECTION_STANDOFF`, `PROTECTION_BREAKDOWN`, `PROTECTION_CLAMP`, `THERMAL_SOA`, and `PROJECT_STATE`. Provenance is `PRIMARY-SPEC`, narrowly scoped `DISTRIBUTOR-IDENTITY`, `REFERENCE-DESIGN`, `CALCULATED`, `PROJECT-CHOICE`, `BENCH-OBSERVED`, or `UNVERIFIED`. Every quantitative fact carries an explicit unit and conditions; textual facts use unit `NONE`. Calculated facts list raw fact IDs and an evaluable arithmetic expression. Cycles are invalid.
+
+Only these verdicts are valid: `PASS - primary-source confirmed`, `CONFIRMED - distributor identity only`, `BLOCKER - deterministic spec violation`, `NEEDS BENCH`, `UNSOURCED`, and `NOT APPLICABLE`. Distributor identity confirmation is valid only for an `AVAILABLE` `DISTRIBUTOR_IDENTITY` source and a `PROJECT_STATE` identity fact; it cannot support electrical/thermal limits, calculations, primary PASS, or deterministic BLOCKER.
+
+`PRIMARY-SPEC` may receive a PASS only from an `AVAILABLE` `MANUFACTURER_PRIMARY` source. A calculated PASS is trusted only when every raw leaf in its dependency closure is such a primary-source PASS. Its expression names exactly the transformed fact IDs in `depends_on`; undeclared, unused, self, missing, or cyclic dependencies fail.
+
+Unknown identity, source, open harness/mechanical domains, unavailable URLs, and unexplained coverage gaps stay explicit. Generic-family, distributor, or same-name cross-vendor data never silently stands in for the exact orderable.

package/templates/default/.claude/skills/component-spec-audit/references/direct-routing.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "contract": "For each line, the validator constructs literal positive queries for exact MPN, exact LCSC, manufacturer plus MPN, and function plus MPN; every query must resolve directly and uniquely. The negative query must resolve no line.",
+  "cases": []
+}

package/templates/default/.claude/skills/component-spec-audit/references/external-vendor-qualifiers.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "vendor_names": []
+}

package/templates/default/.claude/skills/component-spec-audit/references/inventory.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "generator_specs": [],
+  "assertions": {
+    "orderable_lines": 0,
+    "fitted_lines": 0,
+    "dnp_or_hand_fit_lines": 0
+  },
+  "exclusions": [],
+  "lines": []
+}

package/templates/default/.claude/skills/component-spec-audit/references/new-component-workflow.md

@@ -0,0 +1,113 @@
+# New component workflow
+
+Run these steps from the project root, in order. This checklist owns a new or replacement component from its exact identity through the committed, published reference. It is the detailed form of Workflow B in [circuit/WORKFLOW.md](../../../../circuit/WORKFLOW.md). It does not authorize an unresolved electrical or firmware design change.
+
+## Preconditions
+
+Resolve before editing:
+
+- manufacturer, complete MPN (suffix and package variant), supplier order codes;
+- intended function, placements (board and reference designator) and population (fitted, not fitted, hand-fitted, external);
+- the source that will establish identity and behavior;
+- whether the part needs CAD assets on a board, and whether its page and previews will be published.
+
+Do not invent a reference designator, pin, fact, order code or document kind to make the workflow progress. Stop and record the missing design or review decision in next actions instead.
+
+Run `pnpm circuit:check` first and note what already fails.
+
+## 1. Lock the identity
+
+The configured inventory provider (`inventoryProvider` in `circuit.config.ts`) decides how identity is locked.
+
+### Manual provider (the default)
+
+Edit `.claude/skills/component-spec-audit/references/inventory.json`:
+
+1. Add one line per orderable identity, with the same keys as existing lines (`line_id`, `mpn`, `manufacturer`, `lcsc`, `package`, `dnp`, `owner_skill`, `identity_state`, `source_state`, `function`, `placements`; `mounting` defaults to `pcb`). The validator names any key that is missing.
+2. Identity is a unique `line_id` plus a unique (manufacturer, complete MPN) pair. Two manufacturers may share an MPN; each line then resolves only with its manufacturer qualifier.
+3. `lcsc` must be present. Use `""` unless you read a C-number from the supplier's listing for this exact part. Never fabricate, guess or reuse a C-number from a similar part.
+4. Optional `suppliers: [{ "supplier": "...", "order_code": "..." }]` records other order codes. They are display-only and create no routing aliases.
+5. `placements` may be `[]`. Placements are **declared, not verified**: the manual provider does not bind them to a schematic, and the `SCOPE:` line printed by the validator says so. Repeat that limit in your report.
+6. `identity_state` is `VERIFIED` or `UNRESOLVED`; `source_state` is `AVAILABLE` or `SOURCE UNAVAILABLE`. Keep them consistent with the owner bundle; the validator warns when the summary lags the evidence.
+7. Update the reviewed `assertions` counts (`orderable_lines`, `fitted_lines`, `dnp_or_hand_fit_lines`) by hand. Do not change a count only to make a check pass.
+
+### Generator provider (optional)
+
+When the project configures a generator-based provider, the generator specification is the identity lock: add the exact part to the configured spec, regenerate the schematic with the project's generator, commit the spec and its output together, and then reconcile the inventory line against it. Do not hand-edit an inventory line to disagree with its generator.
+
+## 2. Build the evidence owner
+
+1. Create the bundle from the package template:
+
+   ```sh
+   pnpm exec zudo-circuit-doc new-component SUFFIX
+   ```
+
+   This creates `.claude/skills/component-SUFFIX/` and refuses an existing directory. Use a suffix derived from the exact part.
+2. Replace **every** placeholder in all eight files. Fill `manifest.json`, `sources.json`, `facts.json`, `coverage.json`, `routing.json`, `interactions.json` and `pin-map.json` from audited sources (Workflow C for acquisition). Record units, conditions, provenance, verdicts, calculation dependencies, open domains with their `blocking_fact_ids`, routing cases and the real pin map. Retain short normalized extracts, not whole documents.
+3. Keep the bundle `SKILL.md` frontmatter valid: `name` equals the directory name, and `description` is at least 80 characters and says when to use it.
+4. The record's `mpn`, `manufacturer`, `lcsc` and `package` must equal the inventory line; `owner_skill` on the line names this bundle.
+5. Add the line's positive and negative cases to `.claude/skills/component-spec-audit/references/direct-routing.json`. Add a vendor qualifier to `external-vendor-qualifiers.json` only when routing needs one.
+6. When the part affects another component or domain, add or update a rule in `.claude/skills/circuit-spec-integration/references/rules.json` (see the circuit-spec-integration skill). Evidence-chain stages stay `OPEN` until real evidence exists.
+
+Run `pnpm circuit:check` now; fix every failure the new bundle introduced.
+
+## 3. CAD assets (optional)
+
+Only when the part goes on a board and `cad.enabled` is `true` in `circuit.config.ts`. With CAD disabled, the pin-asset check is reported as SKIPPED; say so in the report rather than implying pins were checked.
+
+1. Acquire the symbol, footprint and model (Workflow D): a pinned KiCad library release tag, the manufacturer, or `easyeda2kicad` for an LCSC-listed part. Import into `.circuit-cache/cad/` first, never straight into the libraries.
+2. Merge only this part's symbol into the configured symbol library. Never overwrite a shared multi-symbol library with importer output.
+3. Place the footprint in the configured footprint roots. If the config names both a master root and a library root, keep the two `.kicad_mod` copies byte-identical (`cmp -s`).
+4. Place the WRL model in the configured model root — it is required and is what gets published. A STEP file is optional; if you add one, it must share the WRL's basename (a mismatched pair fails the check). Review the footprint's model reference and its offset, rotation and scale. The web viewer renders WRL only; if no WRL exists for the pinned library release, record the model as unavailable rather than converting one.
+5. The pin map's `symbol` and `footprint` must exist in the configured libraries, and symbol pin numbers, footprint pad numbers and pin-map pins must be identical sets. Check them against the datasheet yourself; the validator checks only agreement.
+6. Write the receipt `circuit/cad-receipts/ASSET_ID.receipt.json` from `circuit/templates/cad-asset-receipt.json`, with the fidelity class (`exact-vendor`, `family`, `derived`, `unavailable`) and the evidence for it.
+
+## 4. Choose what becomes public
+
+Edit `circuit/publication/selection.json` in the same change. Nothing is published unless it is listed.
+
+1. Add the record to `recordIds`, every public source to `sourceIds`, and every approved outbound URL to `linkableSourceIds`.
+2. Add exactly one entry to `documentSelections` for the record, with its audited document source and a truthful `documentKind` (`datasheet`, `specification` or `drawing`). Inspect the retrieved content first: a product page or HTML denial is not a datasheet because its URL ends in `.pdf`. The bytes must start with `%PDF-`, and the title and part list must cover the exact MPN.
+3. Update the reviewed `expect` locks: `records`, `sources`, `integrationRules` and `packages` (the number of selected footprint/model packages; `0` is valid). Keep them explicit; never infer them.
+4. A file deliberately published under `doc/public/` (for example a redistributable drawing) needs an entry in `circuit/publication/assets.json` with its path and reason. Raw sources and CAD files otherwise stay out of `doc/public/`.
+
+## 5. Regenerate, review, commit
+
+1. If CAD previews were selected, regenerate and check them:
+
+   ```sh
+   pnpm previews:generate
+   pnpm exec zudo-circuit-doc footprints check
+   pnpm exec zudo-circuit-doc models
+   pnpm exec zudo-circuit-doc models --check
+   ```
+
+   Restart a running dev server after adding public assets.
+2. Regenerate and check:
+
+   ```sh
+   pnpm circuit:generate
+   pnpm circuit:check
+   pnpm check
+   ```
+
+3. Build and run the post-build checks:
+
+   ```sh
+   pnpm build
+   pnpm check:site
+   ```
+
+4. Commit the evidence, inventory, routing, selection, receipts, generated pages, `circuit/generated/preflight.json` and previews together. Never hand-edit generated files. Review the generated diff with:
+
+   ```sh
+   git add --intent-to-add -A -- doc/src/content/docs/components circuit/generated doc/public/assets/component-previews
+   git diff -- doc/src/content/docs/components circuit/generated doc/public/assets/component-previews
+   ```
+
+5. Open the new record page in the built site or dev server. A passing link check proves the route exists, not that it reads correctly.
+
+## External (off-board) components
+
+A purchased, hand-wired component that is not soldered to a PCB (a panel switch, a connector on a cable) is not a board part. Set inventory `mounting: external`, keep its footprint empty, and record its physical terminal numbers in the pin map's `footprint_pad`. Do not fabricate PCB pads or model geometry for it. Verify system wiring and its absence from the PCB assembly separately; both remain explicit checks.

package/templates/default/AGENTS.md

@@ -0,0 +1,7 @@
+# Agent instructions
+
+Read [circuit/WORKFLOW.md](circuit/WORKFLOW.md) first. It is the canonical workflow for this circuit project; this file only points to it.
+
+- Exact-component evidence lives in the owner bundles under `.claude/skills/component-*/`, indexed by `.claude/skills/component-spec-audit/references/inventory.json`. Cross-component rules live in `.claude/skills/circuit-spec-integration/references/rules.json`.
+- Run `pnpm circuit:check` before editing and again after.
+- Never hand-edit the generated pages under `doc/src/content/docs/components/`; change the evidence and run `pnpm circuit:generate`.

package/templates/default/CLAUDE.md

@@ -0,0 +1,7 @@
+# Agent instructions
+
+Read [circuit/WORKFLOW.md](circuit/WORKFLOW.md) first. It is the canonical workflow for this circuit project; this file only points to it.
+
+- Exact-component evidence lives in the owner bundles under `.claude/skills/component-*/`, indexed by `.claude/skills/component-spec-audit/references/inventory.json`. Cross-component rules live in `.claude/skills/circuit-spec-integration/references/rules.json`.
+- Run `pnpm circuit:check` before editing and again after.
+- Never hand-edit the generated pages under `doc/src/content/docs/components/`; change the evidence and run `pnpm circuit:generate`.