create-zudo-circuit-doc 0.1.0

package/templates/default/circuit/templates/cad-asset-receipt.json

@@ -0,0 +1,58 @@
+{
+  "receipt_version": 1,
+  "identity": {
+    "asset_id": null,
+    "record_id": null,
+    "manufacturer": null,
+    "mpn": null,
+    "package": null,
+    "variant_notes": null
+  },
+  "acquisition": {
+    "provider": null,
+    "library_release_tag": null,
+    "source_url": null,
+    "acquired_on": null,
+    "original_filenames": [],
+    "sha256": {}
+  },
+  "representation": {
+    "files": [],
+    "formats": [],
+    "units": null,
+    "original_paths": []
+  },
+  "fidelity": {
+    "class": null,
+    "reason": null,
+    "evidence": []
+  },
+  "derivation": {
+    "derived": false,
+    "input_sha256": {},
+    "tool": null,
+    "tool_version": null,
+    "parameters": {},
+    "output_sha256": {}
+  },
+  "cad_use": {
+    "symbol": null,
+    "footprint": null,
+    "model_path": null,
+    "transform": {
+      "offset": null,
+      "rotation": null,
+      "scale": null
+    },
+    "seating_plane": null
+  },
+  "checks": {
+    "performed": [],
+    "remaining_physical_checks": []
+  },
+  "publication": {
+    "preview_selected": false,
+    "download_published": false,
+    "permitted_scope": null
+  }
+}

package/templates/default/circuit/templates/cad-asset-receipt.md

@@ -0,0 +1,33 @@
+# CAD asset receipt
+
+A receipt records what an acquired symbol, footprint or 3D model actually is, where it came from and what has been checked. It is a sidecar next to the v1 evidence: it does not change the owner bundle's schema, and the validator does not read it.
+
+Write one receipt per acquired asset set as `circuit/cad-receipts/ASSET_ID.receipt.json`, starting from [cad-asset-receipt.json](./cad-asset-receipt.json). Copy this Markdown form beside it only when the JSON needs a longer explanation. Leave a field `null` until you know it; never fill a field with a guess.
+
+## Field groups
+
+| Group | Fields | What to enter |
+| --- | --- | --- |
+| Identity | `asset_id`, `record_id`, `manufacturer`, `mpn`, `package`, `variant_notes` | The exact orderable variant the asset is meant to represent, and the owner record ID |
+| Acquisition | `provider`, `library_release_tag`, `source_url`, `acquired_on`, `original_filenames`, `sha256` | Where the files came from, the pinned library release tag (for KiCad official libraries), the date, the unmodified filenames and one SHA-256 per file |
+| Representation | `files`, `formats`, `units`, `original_paths` | The formats kept (symbol, footprint, STEP, WRL, other), their units and where the originals are kept |
+| Fidelity | `class`, `reason`, `evidence` | One of `exact-vendor`, `family`, `derived`, `unavailable`, with the reason and the evidence that supports the label |
+| Derivation | `derived`, `input_sha256`, `tool`, `tool_version`, `parameters`, `output_sha256` | Only for a derived asset: the inputs, the deterministic transformation and the outputs |
+| CAD use | `symbol`, `footprint`, `model_path`, `transform`, `seating_plane` | How the footprint references the model, and the offset, rotation and scale applied |
+| Checks | `performed`, `remaining_physical_checks` | Each check actually done with its method and evidence (pin/pad numbering, pitch, body envelope, pin 1), and what still needs physical verification |
+| Publication | `preview_selected`, `download_published`, `permitted_scope` | Whether a preview is selected in `circuit/publication/selection.json`, whether a file is listed in `circuit/publication/assets.json`, and the redistribution scope |
+
+## Fidelity classes
+
+| Class | Use it when |
+| --- | --- |
+| `exact-vendor` | The manufacturer published the asset for this exact orderable variant |
+| `family` | The asset represents the package or series and is not proven for this variant |
+| `derived` | The asset was produced from an original by a recorded transformation |
+| `unavailable` | No usable asset exists; the state is documented and nothing is fabricated |
+
+## Limits to state in every receipt
+
+- A rendered preview is not dimensional proof.
+- A footprint that imports cleanly does not prove pin correspondence.
+- Model geometry does not prove physical seating, clearance or solderability; list those as remaining physical checks until they are observed.

package/templates/default/circuit/templates/project-docs/architecture/interfaces.mdx

@@ -0,0 +1,52 @@
+---
+title: "Interfaces and connections"
+description: "Explicit boundaries between circuit blocks, external devices, firmware, and mechanical parts."
+sidebar_position: 20
+---
+
+This page explains interface contracts for the [architecture](./overview.mdx). Populate only interfaces that exist or are actively proposed. It is not a generated pin catalog.
+
+## Interface inventory
+
+| Interface ID | Endpoint A | Endpoint B | Purpose | Intended representation | Current status |
+|---|---|---|---|---|---|
+| Not entered | Not entered | Not entered | Not entered | Schematic, cable drawing, firmware API, or mechanical drawing | Unspecified |
+
+Identify whether each connection is internal, external, removable, accessible during service, or part of a test fixture. State its direction from a named endpoint so “input” and “output” are unambiguous.
+
+## Electrical and configuration contract
+
+For each interface, describe the following in a small section or a linked canonical integration record:
+
+| Question | Project answer | Evidence or design reference |
+|---|---|---|
+| What carries energy, signal, reference, or shielding? | Not entered | Not entered |
+| Which side supplies power or drives each signal? | Not entered | Not entered |
+| Which operating conditions must both endpoints tolerate? | Not entered | Not entered |
+| What happens if only one endpoint is powered? | Not entered | Not entered |
+| What are the startup, reset, and disconnected states? | Not entered | Not entered |
+| Are external pulls, termination, or configuration required? | Not entered | Not entered |
+| Does programming or service equipment create another power path? | Not entered | Not entered |
+| Which conditions remain unproven? | Not entered | Not entered |
+
+Write project-specific requirements here and link exact pin functions, thresholds, defaults, and ratings to the component evidence bundle. If a circuit condition combines several components, link the integration calculation or rule that covers those components together.
+
+## Connector and cable mapping
+
+| Mapping subject | What must be recorded |
+|---|---|
+| Physical identification | Exact connector and mating-part records, keying, orientation and pin-1 reference |
+| View convention | Mating face, cable side, component top, or board side; include a drawing when needed |
+| Electrical mapping | Connector terminal, schematic pin, footprint pad, and intended net reference |
+| Cable construction | Endpoint-to-endpoint mapping, conductor identification and assembly revision |
+| Verification | Continuity or orientation report for the actual assembly, when performed |
+
+A model that visually mates and a footprint that imports successfully do not establish numeric pin correspondence. Keep visual fit, numeric mapping, electrical compatibility, and observed continuity as separately traceable checks.
+
+## Mechanical and firmware boundaries
+
+Record the project constraints that cross disciplines: component height, mounting datum, actuator travel, insertion direction, finger clearance, enclosure opening, sensor location, firmware pin assignment, initialization order, and any persistent configuration. Do not copy a full mechanical drawing into prose; link the asset and its dimensional audit.
+
+## Change triggers
+
+Name changes that require revisiting this contract. Common examples are a new package variant, different mating connector, board-side mounting change, changed signal direction, different default configuration, or an altered service connection. Use a [change-impact note](../project/change-impact.mdx) when applying one of these changes.

package/templates/default/circuit/templates/project-docs/architecture/overview.mdx

@@ -0,0 +1,55 @@
+---
+title: "Architecture overview"
+description: "Functional blocks, operating states, design boundaries, and unresolved architecture questions."
+sidebar_position: 10
+---
+
+This page describes an architecture proposal. No topology, component, board split, power source, or operating limit has been chosen by this template.
+
+## Intended behavior
+
+Summarize the user-visible behavior from the [project brief](../project/index.mdx). Explain which physical or electrical functions are required to produce it.
+
+## Functional blocks
+
+| Block ID | Responsibility | Receives | Produces | Current design basis |
+|---|---|---|---|---|
+| Not entered | Not entered | Not entered | Not entered | Requirement, proposed approach, or decision reference |
+
+Start with responsibilities rather than IC names. Introduce selected components only after the relevant evidence and decision exist. If a diagram adds clarity, derive it from these same blocks and their interfaces; do not let a diagram silently introduce another net name or voltage domain.
+
+## Physical partitioning
+
+Describe the proposed physical arrangement: boards, external modules, cables, enclosure, mounting surfaces, and any user-accessible conductors. State why each boundary exists and whether it is fixed or still a candidate.
+
+| Boundary | Reason for separating it | Consequence for assembly or testing | Decision reference |
+|---|---|---|---|
+| Not entered | Not entered | Not entered | Not entered |
+
+Do not assume that a visually convenient board split is electrically or mechanically neutral. Record the interface work it creates in the [interface page](./interfaces.mdx).
+
+## Operating states and transitions
+
+| State | How it is entered | Required outputs or behavior | Defaults and stored configuration | Evidence or test still needed |
+|---|---|---|---|---|
+| State not yet defined | Not entered | Not entered | Not entered | Not entered |
+
+Consider only states that apply to this project. Possibilities include unpowered, initial connection, reset, normal operation, deliberate shutdown, service/programming, and recovery from interrupted power. Delete inapplicable cases after recording why they do not apply.
+
+Defaults deserve explicit evidence. Separate manufacturer-documented defaults, intended programming, actual readback, firmware initialization, and observed hardware behavior.
+
+## Project envelopes and calculations
+
+| Analysis question | Related blocks | Required inputs | Evidence or calculation reference | Current limitation |
+|---|---|---|---|---|
+| Not entered | Not entered | Not entered | Not entered | Not entered |
+
+Keep exact component limits in the component evidence bundle. Link any cross-component calculation with its input facts, units, conditions, and current design revision. An operating target, a recommended range, a typical value, an absolute maximum, a simulated result, and a measured result are different kinds of information.
+
+If an analysis uses an assumed source impedance, load, thermal condition, tolerance, or configuration, state it next to the conclusion. A calculation cannot close a hardware question it did not model.
+
+## Architecture choices still open
+
+List choices that could change the block structure, interfaces, layout, firmware, or procurement. Link each to [next actions](../project/next-actions.mdx) and name the evidence or owner decision needed to close it.
+
+When a choice is made, capture the alternatives and conditions in a [decision record](../decisions/decision.mdx). Keep the architecture page current and preserve the historical reasoning in the decision.

package/templates/default/circuit/templates/project-docs/decisions/decision.mdx

@@ -0,0 +1,66 @@
+---
+title: "Decision record"
+description: "The context, alternatives, evidence, tradeoffs, and validity conditions of one consequential choice."
+sidebar_position: 10
+---
+
+Duplicate this page for one consequential choice. This is an unfilled decision template; it records no accepted design or component selection.
+
+## Record
+
+| Field | Entry |
+|---|---|
+| Decision ID | Not assigned |
+| Topic | Not entered |
+| State | Draft; no decision recorded |
+| Decision date | Not entered |
+| Decision maker | Not entered |
+| Applicable project revision | Not entered |
+| Replaces or is replaced by | Not entered |
+
+Use a visible state such as proposed, accepted, rejected, or superseded when the actual decision exists. These are decision lifecycle terms, not assertions that the underlying hardware has passed verification.
+
+## Context
+
+Describe the concrete problem and why it needs a decision now. Link the relevant requirements, research notes, canonical component evidence, and integration calculations. State any constraint supplied by the project owner that materially changes the choice.
+
+## Alternatives considered
+
+| Alternative | Why it could work | Decisive tradeoff | Evidence still needed | Disposition |
+|---|---|---|---|---|
+| No alternative entered | Not entered | Not entered | Not entered | Unreviewed |
+
+An alternative can be a component, topology, control behavior, board partition, assembly method, or a decision to defer work. “Not selected” should explain which criterion mattered; it should not imply that the alternative is generally unsuitable.
+
+## Decision
+
+State exactly what is adopted and what scope it covers. If conditional, name each condition. Link the selected exact component record rather than relying on a family name, short description, or package label.
+
+For a design change, identify the intended authoritative representation to update, such as a circuit specification or schematic. A recorded decision and an implemented design are separate states.
+
+## Reasoning
+
+Explain the most important tradeoff first. Include the relevant uncertainty and the strongest reason another option could have been chosen. Numeric claims should link to canonical facts or calculations with their qualifiers and conditions preserved.
+
+## Consequences and follow-up
+
+| Consequence | Required update or verification | Owner or next-action reference |
+|---|---|---|
+| Not entered | Not entered | Not entered |
+
+Consider affected architecture, interfaces, firmware, mechanical fit, documentation, sourcing, and verification. A part substitution may require more than replacing a row in a BOM. Link a [change-impact note](../project/change-impact.mdx) if downstream effects are material.
+
+## What could reopen this decision
+
+Record observable triggers: a contradicted fact, unavailable exact part, changed operating envelope, package mismatch, failed test, changed requirement, or revised cost assumption. Where the basis is a dated stock observation, give the recheck event.
+
+When superseding a decision, keep the old rationale and add a link to the new record. Update current architecture and next actions so the historical choice is no longer presented as current.
+
+## Implementation and verification references
+
+| Item | Reference and present state |
+|---|---|
+| Intended change | Not entered |
+| Implemented revision | Not entered |
+| Evidence refresh | Not entered |
+| Verification report | Not entered |

package/templates/default/circuit/templates/project-docs/decisions/sourcing.mdx

@@ -0,0 +1,57 @@
+---
+title: "BOM and sourcing decisions"
+description: "Population policy, assembly choices, dated supply observations, and procurement rationale."
+sidebar_position: 20
+---
+
+This page explains procurement and population choices. It is not a manually maintained replacement for the canonical component inventory or a generated assembly BOM. No order, quote, stock check, or assembly plan exists by virtue of this template.
+
+## Intended build
+
+| Field | Entry |
+|---|---|
+| Build or prototype ID | Not assigned |
+| Design revision being considered | Not entered |
+| Quantity and purpose | Not entered |
+| Assembly method or provider | Not entered |
+| Required delivery date, if any | Not entered |
+| Applicable generated BOM and placement outputs | Not generated or not entered |
+| Quote reference and observation date | Not obtained or not entered |
+
+## Population policy
+
+Describe how this project distinguishes fitted assembly parts, hand-fitted parts, intentionally unpopulated positions, test-only features, and geometry with no purchased part. Record population per placement in the inventory (`dnp`, `mounting`) and explain the reasoning here.
+
+| Design feature or placement reference | Intended population | Reason | Design or decision reference |
+|---|---|---|---|
+| Not entered | Not decided | Not entered | Not entered |
+
+Population belongs to a particular design revision or build variant. The same component may be fitted in one build and omitted in another. Do not encode the project's selection by modifying a shared generic footprint's supplier identity.
+
+## Sourcing observations
+
+| Component record | Supplier observation reference | Checked at | Quantity or assembly assumption | Recheck trigger |
+|---|---|---|---|---|
+| No component entered | Not obtained | Not entered | Not entered | Not entered |
+
+Store exact part mapping, observed stock, pricing, tier, currency, and source provenance in the component evidence bundle (inventory `suppliers` entries are display-only order codes). This page explains why those observations matter to the build. A dated observation does not reserve parts or establish that the assembler supports the intended process.
+
+## Cost reasoning
+
+Explain which costs drive the decision: parts, setup charges, minimum quantities, board runs, tooling, manual assembly, shipping, or rework. Link a dated estimate or quote and identify the quantity and assumptions behind it.
+
+If changing the build arrangement is expected to reduce cost, describe the new constraints it creates. Preserve the difference between a rough estimate, a supplier quotation, and a completed purchase.
+
+## Alternate parts and unavailable items
+
+| Affected component | Procurement problem | Candidate alternative record | Compatibility work required | Decision reference |
+|---|---|---|---|---|
+| Not entered | Not entered | Not researched | Not assessed | Not entered |
+
+A similar label, package, or catalog number is a candidate for investigation. Evaluate exact identity, pin mapping, ratings under applicable conditions, behavior, mechanical fit, firmware implications, and assembly compatibility before treating it as a replacement.
+
+## Build reconciliation
+
+Before an order or handoff is prepared, record which source revision produced the BOM and placement data, how population exclusions were handled, and whether the exported identities match the intended placements. If orientation or assembler conventions apply, link their explicit review rather than assuming the preview proves all fields.
+
+Save each order or manufacturing handoff against its own revision. Changes after ordering belong in a new change note, not in a silently revised description of the ordered assembly.

package/templates/default/circuit/templates/project-docs/project/change-impact.mdx

@@ -0,0 +1,61 @@
+---
+title: "Change-impact note"
+description: "The intended scope, dependencies, evidence changes, and verification of one proposed design update."
+sidebar_position: 20
+---
+
+Use this note when a change may invalidate evidence, derived files, or prior test results. It starts as an unfilled proposal. The note itself does not imply that the change has been applied.
+
+## Change identity
+
+| Field | Entry |
+|---|---|
+| Change ID | Not assigned |
+| Requested outcome | Not entered |
+| Reason for the change | Not entered |
+| Baseline revision | Not entered |
+| Scope already requested by the owner | Not entered |
+| Present state | Proposal not yet specified |
+| Related decision | Not entered |
+
+Describe the resulting behavior, not just a file edit. For a component replacement, identify both exact component records and every affected placement. For a footprint change, distinguish corrected geometry from a new physical part.
+
+## Impact map
+
+| Area | Relevant object or record | Expected effect | Required follow-up | Present state |
+|---|---|---|---|---|
+| Component identity and facts | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Cross-component calculations and interfaces | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Schematic or circuit specification | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Footprint, model and mechanical fit | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Firmware or stored configuration | Not assessed | Not assessed | Not assessed | Unreviewed |
+| BOM, placement and assembly outputs | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Generated catalog and previews | Not assessed | Not assessed | Not assessed | Unreviewed |
+| Authored rationale and prior verification | Not assessed | Not assessed | Not assessed | Unreviewed |
+
+Mark an area unaffected only after considering the actual dependency. A same-package substitution can still change behavior or limits; a source correction can change a conclusion without changing the physical circuit.
+
+## Evidence that becomes stale
+
+Identify source records, project-state hashes, derived assets, calculations, or measurements tied to the baseline. State which remain valid, which require regeneration, and which need another test. Preserve the old evidence with its old revision instead of relabeling it as current.
+
+If a claim was previously presented as settled, explicitly state why the change reopens it. Update the current narrative wherever it still relies on the old conclusion.
+
+## Implementation sequence
+
+Describe the source edits and dependent regeneration in order. Use only the commands listed in `circuit/WORKFLOW.md`. Name the authoritative input before its generated outputs.
+
+Record any required local validation, preview review, or hardware verification along with the result it is meant to establish. An asset can render successfully while its dimensions or pin mapping remain unverified.
+
+## Completion record
+
+| Item | Reference and outcome |
+|---|---|
+| Applied source revision | Not applied or not entered |
+| Updated evidence records | Not entered |
+| Regenerated outputs | Not generated or not entered |
+| Validation or review results | Not run |
+| Hardware verification | Not run |
+| Remaining open questions | Not entered |
+
+If the work reveals a materially different design choice, record the new choice and the information needed to decide it. Continue work already within the requested scope; do not turn routine documentation updates into repeated permission requests.

package/templates/default/circuit/templates/project-docs/project/index.mdx

@@ -0,0 +1,62 @@
+---
+title: "Project brief"
+description: "Purpose, intended behavior, constraints, and the current state of this circuit project."
+sidebar_position: 1
+---
+
+This page is an unfilled project brief. Describe the intended object and the experience of using it before selecting parts. Replace the prompts with project-specific statements as they become known.
+
+## Purpose
+
+| Field | Project statement |
+|---|---|
+| Project name | Not entered |
+| Intended user and setting | Not entered |
+| What the object does | Not entered |
+| Why this project exists | Not entered |
+| What a successful first prototype demonstrates | Not entered |
+| Current owner or maintainer | Not entered |
+
+Write one short scenario: what the user connects, touches, or observes; what the object does in response; and how the session ends. State which behavior is essential and which is a later experiment.
+
+## Scope and constraints
+
+| Topic | Requirement or preference | Basis | Still unknown |
+|---|---|---|---|
+| Power source and operating environment | Not entered | Owner request or evidence reference | Not entered |
+| Inputs, outputs and controls | Not entered | Owner request or evidence reference | Not entered |
+| Physical size, mounting and appearance | Not entered | Owner request or evidence reference | Not entered |
+| Assembly, sourcing and repair | Not entered | Owner request or evidence reference | Not entered |
+| Budget and prototype quantity | Not entered | Owner request or dated estimate | Not entered |
+| Firmware and development tools | Not entered | Owner preference or project decision | Not entered |
+
+A desired behavior is a requirement; an assumed component capability is a claim that still needs evidence. Keep that distinction visible. Mark preferences separately from constraints that would make a design unacceptable.
+
+## Current design state
+
+| Item | Current reference |
+|---|---|
+| Documentation revision reviewed | Not entered |
+| Schematic or circuit specification revision | Not entered |
+| PCB revision | Not entered |
+| Firmware revision, if applicable | Not entered |
+| Physical prototype or assembly ID | Not entered |
+| Latest relevant verification report | Not entered |
+
+Do not describe a schematic, PCB, firmware image, download, or physical prototype as present until it exists. When some representations are ahead of others, say which one describes the intended design and which one describes the built hardware.
+
+## How to read this project
+
+- [Architecture](../architecture/overview.mdx) explains the functional blocks and operating states.
+- [Interfaces](../architecture/interfaces.mdx) defines the boundaries those blocks must agree on.
+- [Component research](../research/component-candidate.mdx) records candidate reasoning and links to the component evidence bundle.
+- [Decisions](../decisions/decision.mdx) records consequential choices and their conditions.
+- [Sourcing](../decisions/sourcing.mdx) explains population and procurement choices.
+- [Verification](../verification/bring-up.mdx) records what was planned, what was performed, and what was observed.
+- [Next actions](./next-actions.mdx) is the entry point for continuing work.
+
+Exact component identity, sourced facts, asset provenance, and generated catalog entries belong to the component evidence bundle. This page describes project intent and current state.
+
+## Immediate next result
+
+Describe one concrete result needed next, the uncertainty it resolves, and the artifact that will preserve the answer. Link the corresponding entry in next actions instead of maintaining two independent task lists.

package/templates/default/circuit/templates/project-docs/project/next-actions.mdx

@@ -0,0 +1,58 @@
+---
+title: "Open questions and next actions"
+description: "A concise handoff of current uncertainties, dependencies, and the next concrete work."
+sidebar_position: 10
+---
+
+This is the continuation point for the project. Keep it short enough that a new session can identify what to do next without rereading the whole archive. This template contains no completed work or resolved questions.
+
+## Current snapshot
+
+| Field | Entry |
+|---|---|
+| Snapshot date | Not entered |
+| Current project goal | Not entered |
+| Design revision considered current | Not entered |
+| Latest completed result and its evidence | Not entered |
+| Most consequential remaining uncertainty | Not entered |
+| Next result to produce | Not entered |
+
+Link the [project brief](./index.mdx) for requirements and the authoritative design files for the actual implementation state. Avoid duplicating full specifications here.
+
+## Open questions
+
+| Question ID | Exact question | Why the answer matters | Evidence needed | Owner or next task |
+|---|---|---|---|---|
+| Not assigned | Not entered | Not entered | Not entered | Not entered |
+
+Classify the needed work in plain language: source research, identity resolution, calculation, design choice, asset audit, supplier information, or physical measurement. This makes it clear whether another web lookup can answer the question or a bench test is required.
+
+## Next actions
+
+| Priority | Bounded action | Depends on | Concrete output | Completion condition |
+|---|---|---|---|---|
+| Not assigned | Not entered | Not entered | Not entered | Not entered |
+
+Prefer actions with a visible result, such as retaining an exact document, mapping one connector, checking a model dimension, or producing one test report. “Investigate everything” gives the next agent no stopping point.
+
+## Blocked work
+
+| Blocked task | Missing prerequisite | Work that can continue meanwhile | Revisit when |
+|---|---|---|---|
+| No task entered | Not entered | Not entered | Not entered |
+
+Record the actual blocker. A failed download, missing hardware, unconfirmed identity, undecided requirement, and unavailable tool are different problems and require different follow-up.
+
+## Recently resolved or reopened
+
+| Question or action | New state | Evidence or decision reference | Pages or records updated |
+|---|---|---|---|
+| No entry | Not entered | Not entered | Not entered |
+
+Move a question here only with its supporting reference. A newer analysis can reopen a previously settled point; preserve both the earlier basis and the reason it no longer closes the question. Do not leave “resolved” elsewhere if the canonical evidence remains missing or conditional.
+
+## Handoff to the next session
+
+Write a short paragraph containing the current goal, the minimum references to read, the exact next task, and the artifact expected at completion. Use the [task-request template](./task-request.mdx) for a larger delegation.
+
+When updating this page, remove stale imperative tasks that are already completed, keep historical work in its original decision or verification record, and carry forward only unresolved dependencies.

package/templates/default/circuit/templates/project-docs/project/task-request.mdx

@@ -0,0 +1,56 @@
+---
+title: "Agent task request"
+description: "A reusable brief for a bounded component, documentation, asset, or verification task."
+sidebar_position: 30
+---
+
+Copy the useful sections of this page into a request to a local AI agent. Fill exact references before execution. This is a task brief template, not an installed skill or active repository instruction file.
+
+## Request
+
+| Field | Entry |
+|---|---|
+| Task title | Not entered |
+| Desired result | Not entered |
+| Why this result matters now | Not entered |
+| Exact component, interface, or revision in scope | Not entered |
+| Work already authorized by this request | Not entered |
+| Deliverables | Not entered |
+
+Ask for the result in ordinary language. Examples include obtaining the exact datasheet, finding and auditing a 3D model, verifying a specific claim, or assessing the impact of a proposed replacement.
+
+## Minimum context to read
+
+List the project brief, current task or question, exact component evidence records, relevant integration records, and design files needed for this task. Point to the narrow records that matter; do not ask the agent to rediscover the entire repository without a reason.
+
+## Research or implementation scope
+
+State which exact question to answer and how broad the search should be. Identify the operating conditions or revision if they affect the answer. If the question is ambiguous, ask the agent to first report the concrete ambiguity with the useful work already completed.
+
+When the task is component research, specify whether a recommendation is wanted. When the task changes the design, state the desired behavior and any selection decisions already made. Do not require extra permission for routine work already covered by the request.
+
+## Evidence to retain
+
+Describe the evidence needed for the requested conclusion. Typical fields are the exact source and revision, URL, access date, local file and checksum when acquired, precise page or section, claim type and conditions, and the link from the claim to the exact component.
+
+For an asset, include its origin, exact or family-level applicability, transformations, dimensional checks, numeric mapping where relevant, and the limitation of any preview. If a resource cannot be obtained or validated, report the attempt and the remaining gap without inventing a completed download or verified state.
+
+## Output locations and generated content
+
+Use the locations defined in `circuit/WORKFLOW.md`. Update exact facts in the component evidence bundle (`.claude/skills/component-*/`) and write explanatory rationale in authored documentation. Regenerate derived catalogs and previews with the project commands (`pnpm circuit:generate`, `pnpm previews:generate`), never by editing generated pages.
+
+State which files were created or updated and why. Keep the final answer readable enough that the owner can review the conclusion without opening every raw source.
+
+## Definition of done
+
+| Required result | Evidence of completion |
+|---|---|
+| The exact research question is answered within available evidence | Supported conclusion or explicitly bounded unresolved result |
+| Sources or assets are retained as requested | Actual file and provenance records, or a concrete retrieval failure |
+| Relevant project implications are described | Affected decisions, interfaces, calculations, or follow-up tasks |
+| Requested records and authored pages agree | Updated references and no unsupported promotion of status |
+| Checks are reported accurately | Commands and outcomes actually observed; unperformed checks identified |
+
+## Suggested final response
+
+Ask the agent to return: the conclusion; files changed; evidence supporting the conclusion; what remains uncertain; and the one next action that would materially improve confidence. A failed retrieval can still be a completed bounded research task if the result and next step are documented honestly.

package/templates/default/circuit/templates/project-docs/research/component-candidate.mdx

@@ -0,0 +1,60 @@
+---
+title: "Component candidate research"
+description: "A bounded component research question, comparison criteria, evidence links, and unresolved gaps."
+sidebar_position: 10
+---
+
+Duplicate this page for a real research topic. It records rationale and suitability questions; the component evidence bundle owns exact identity, sources, facts, asset provenance, and coverage.
+
+## Research question
+
+| Field | Entry |
+|---|---|
+| Research ID | Not assigned |
+| Function or problem being solved | Not entered |
+| Relevant project requirements | Not entered |
+| Intended use and operating conditions | Not entered |
+| Research date and scope | Not entered |
+| Decision this research will inform | Not entered |
+
+Write the question narrowly enough that an agent can return a useful answer. For example, ask whether candidates satisfy the documented interface and sourcing constraints; do not request “find the best part” without criteria.
+
+## Comparison criteria
+
+| Criterion | Required, preferred, or exploratory | How it will be evaluated | Reference |
+|---|---|---|---|
+| Not entered | Not classified | Not entered | Requirement or analysis reference |
+
+Criteria may include behavior, operating conditions, startup defaults, package geometry, documented pin mapping, tool support, assembly capability, availability, or cost. Include only criteria relevant to the project and give them a clear priority.
+
+## Candidate register
+
+| Candidate record | Exact identity confirmed? | Why it is being considered | Material evidence gap | Current disposition |
+|---|---|---|---|---|
+| No candidate entered | Not assessed | Not entered | Not entered | Unreviewed |
+
+An orderable identity includes the manufacturer and full MPN, including applicable suffixes and package variants. A distributor number is an additional mapping that needs evidence; a family name or generic footprint name does not resolve the exact part.
+
+## What the evidence establishes
+
+For each candidate, link the relevant canonical records and explain their bearing on the research question. Do not recreate all the source facts in this page.
+
+| Research issue | Evidence reference | Interpretation for this use | Limitation |
+|---|---|---|---|
+| Not entered | Record, fact, calculation, or asset ID | Not entered | Not entered |
+
+If two sources disagree, identify the disputed field and record the disagreement. Preserve whether a statement is a manufacturer guarantee, a typical characteristic, a distributor listing, an inferred calculation, or a project observation. A missing source or unreadable datasheet remains a gap.
+
+## Datasheet and CAD needs
+
+State which documents or assets the next task should obtain and what they are needed to prove. Possible requests include a manufacturer datasheet for one package suffix, a dimensioned drawing for a mounting feature, or a model audit against the exact part.
+
+Record attempted retrievals and failures in the component evidence bundle. A URL is a reference; a locally retained file with recorded origin is an acquired asset. An imported or family-level model should remain identified as such until the required checks are completed.
+
+## Recommendation and alternatives
+
+No candidate is recommended by this template. When the research supports a recommendation, explain its strongest reason, the conditions under which it holds, and the uncertainty that could change it. Link a [decision record](../decisions/decision.mdx) if the owner adopts it.
+
+## Next action
+
+Name the smallest follow-up that would change the decision: another source, package check, conditioned calculation, supplier response, or bench observation. Add it to [next actions](../project/next-actions.mdx).