traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/sim/tune.py

@@ -0,0 +1,172 @@
+"""Closed-loop tuning: change a component, rerun the simulator, repeat until a spec is met."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge.sim.circuit import Circuit, SimError, format_value
+from traceforge.sim.engine import SimRun, run_ngspice
+from traceforge.sim.measure import measure
+from traceforge.sim.results import Result
+
+
+@dataclass
+class TuneStep:
+    iteration: int
+    value: float
+    measured: float
+    error_pct: float
+
+
+@dataclass
+class TuneResult:
+    converged: bool
+    parameter: str
+    quantity: str
+    target: float
+    tolerance: float
+    value: float
+    measured: float
+    steps: list[TuneStep] = field(default_factory=list)
+    circuit: Circuit | None = None
+    reason: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "converged": self.converged,
+            "parameter": self.parameter,
+            "quantity": self.quantity,
+            "target": self.target,
+            "tolerance_pct": self.tolerance * 100,
+            "final_value": self.value,
+            "measured": self.measured,
+            "iterations": [
+                {
+                    "n": s.iteration,
+                    "value": s.value,
+                    "measured": s.measured,
+                    "error_pct": round(s.error_pct, 4),
+                }
+                for s in self.steps
+            ],
+            "reason": self.reason,
+        }
+
+
+def parse_target(text: str) -> tuple[str, float]:
+    """``f3db(v(out))=500`` -> (quantity, 500.0); the value accepts SPICE suffixes."""
+    from traceforge.sim.circuit import parse_value
+
+    quantity, sep, goal = text.rpartition("=")
+    if not sep or not quantity.strip():
+        raise SimError("target must look like 'f3db(v(out))=500'")
+    return quantity.strip(), parse_value(goal)
+
+
+def tune(
+    circuit: Circuit,
+    parameter: str,
+    target: float | str,
+    tolerance: float = 0.01,
+    *,
+    quantity: str | None = None,
+    analysis: object = None,
+    bounds: tuple[float, float] | None = None,
+    max_iter: int = 25,
+    workdir: str | Path = ".",
+    meas: list[str] | None = None,
+    runner: Callable[..., SimRun] = run_ngspice,
+) -> TuneResult:
+    """Adjust ``parameter`` (``R1``, a tied group ``R1,R2`` or ``param:NAME``) until
+    ``quantity`` (see ``measure``) equals ``target`` within ``tolerance`` (relative).
+
+    Secant steps in the log domain, falling back to bisection once the target is bracketed.
+    The passed circuit is not changed; the tuned copy is in ``TuneResult.circuit``.
+    """
+    if isinstance(target, str):
+        quantity, target = parse_target(target)
+    if not quantity:
+        raise SimError("tune needs a quantity to measure, e.g. 'f3db(v(out))'")
+    if analysis is None:
+        raise SimError("tune needs an analysis, e.g. '.ac dec 40 10 100k'")
+    work = Path(workdir)
+    first = parameter.split(",")[0].strip()
+    x0 = circuit.number(first)
+    if x0 <= 0:
+        raise SimError(f"{first} must start above zero to be tuned")
+    lo, hi = bounds or (x0 / 1000, x0 * 1000)
+    steps: list[TuneStep] = []
+    best: tuple[float, float, Circuit] | None = None
+
+    def evaluate(x: float) -> tuple[float, Circuit]:
+        trial = circuit.copy()
+        trial.set_value(parameter, x)
+        run = runner(trial, analysis, work / f"iter{len(steps) + 1:02d}", meas=meas)
+        value = measure(Result(run), quantity)
+        err = (value - target) / abs(target) if target else value
+        steps.append(TuneStep(len(steps) + 1, x, value, 100 * err))
+        return value, trial
+
+    def g(v: float) -> float:
+        return math.log(v) if v > 0 and target > 0 else v
+
+    def goal() -> float:
+        return g(target)
+
+    pts: list[tuple[float, float]] = []  # (x, measured)
+    below: tuple[float, float] | None = None
+    above: tuple[float, float] | None = None
+    x = min(max(x0, lo), hi)
+    reason = "iteration limit reached"
+    for _ in range(max_iter):
+        value, trial = evaluate(x)
+        err = abs(value - target) / abs(target) if target else abs(value)
+        if best is None or err < best[0]:
+            best = (err, x, trial)
+        if err <= tolerance:
+            reason = "target met"
+            break
+        pts.append((x, value))
+        if value < target:
+            if below is None or value > below[1]:
+                below = (x, value)
+        elif above is None or value < above[1]:
+            above = (x, value)
+        nxt = None
+        if len(pts) >= 2:
+            (xa, ya), (xb, yb) = pts[-2], pts[-1]
+            if xa != xb and g(ya) != g(yb):
+                slope = (g(yb) - g(ya)) / (math.log(xb) - math.log(xa))
+                nxt = math.exp(math.log(xb) + (goal() - g(yb)) / slope)
+        if below and above:  # bracketed: stay inside it, bisect when the secant leaves it
+            a, b = sorted([below[0], above[0]])
+            if nxt is None or not (a < nxt < b):
+                nxt = math.sqrt(a * b)
+        elif nxt is None or nxt <= 0:
+            nxt = x * 1.25  # first move, or a flat response
+        nxt = min(max(nxt, lo), hi)
+        if len(pts) >= 2 and math.isclose(nxt, x, rel_tol=1e-12):
+            reason = "stopped at the parameter bound"
+            break
+        x = nxt
+    assert best is not None
+    last = steps[-1]
+    converged = reason == "target met"
+    winner = best[2] if not converged else trial
+    return TuneResult(
+        converged,
+        parameter,
+        quantity,
+        target,
+        tolerance,
+        last.value if converged else best[1],
+        last.measured if converged else next(s.measured for s in steps if s.value == best[1]),
+        steps,
+        winner,
+        reason
+        if converged
+        else f"{reason}; best {format_value(best[1])} ({best[0] * 100:.2f} % off)",
+    )

traceforge/skill_commands.py

@@ -0,0 +1,165 @@
+"""Skills: reusable task instructions the user invokes as ``/<name>`` in a session.
+
+A skill is a folder holding a ``SKILL.md``: YAML front matter, then Markdown
+instructions. Project skills live in ``.traceforge/skills/<name>/SKILL.md`` and
+user skills in ``~/.config/traceforge/skills/<name>/SKILL.md`` (a project skill
+wins over a user skill of the same name)::
+
+    ---
+    description: Prepare a JLCPCB order (BOM, CPL, gerbers) and check part stock
+    mode: agent                # optional: agent | plan | ask
+    arguments: "[board variant]"  # optional hint shown in the command list
+    ---
+    # JLCPCB release
+
+    1. Run kicad_drc and stop if it reports errors.
+    2. ...
+
+``/jlcpcb-release rev B`` sends the instructions with "rev B" as the task. Helper
+scripts can sit next to ``SKILL.md``; the agent runs them with its normal tools.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from traceforge.config import config_home
+
+MAX_SKILLS = 64
+MAX_SKILL_BYTES = 64 * 1024
+NAME = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+FRONT_MATTER = re.compile(r"^---\r?\n([\s\S]*?)\r?\n---\r?\n?")
+SKILL_TEMPLATE = """---
+description: {description}
+mode: agent
+arguments: "[what to apply it to]"
+---
+# {title}
+
+Describe the procedure step by step. Name the tools and checks to use, the files to
+produce, and what "done" means, for example:
+
+1. Call kicad_project and read the parts of the design this skill is about.
+2. ...
+3. Run kicad_erc and kicad_drc and fix what they report.
+4. Summarize what changed and what was verified.
+"""
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    instructions: str
+    path: Path
+    source: str  # project | user
+    mode: str | None = None
+    arguments: str = ""
+    title: str = ""
+
+    def prompt(self, task: str) -> str:
+        folder = self.path.parent
+        return (
+            f'<skill name="{self.name}" folder="{folder}">\n{self.instructions.strip()}\n</skill>\n\n'
+            "Follow the skill above. Helper files it mentions are in its folder.\n\n"
+            f"Task: {task.strip() or 'Apply this skill to the current project.'}"
+        )
+
+
+def skill_dirs(workspace: Path) -> list[tuple[str, Path]]:
+    return [
+        ("project", Path(workspace) / ".traceforge" / "skills"),
+        ("user", config_home() / "skills"),
+    ]
+
+
+def _load_one(folder: Path, source: str) -> tuple[Skill | None, str | None]:
+    name = folder.name.lower()
+    file = folder / "SKILL.md"
+    if not NAME.fullmatch(name) or not file.is_file():
+        return (
+            None,
+            f"ignored {source} skill folder {folder.name!r} (needs a valid name and SKILL.md)",
+        )
+    if file.stat().st_size > MAX_SKILL_BYTES:
+        return None, f"ignored {source} skill {name!r}: SKILL.md is over 64 KB"
+    text = file.read_text(encoding="utf-8", errors="replace")
+    meta: dict = {}
+    match = FRONT_MATTER.match(text)
+    if match:
+        try:
+            loaded = yaml.safe_load(match.group(1)) or {}
+        except yaml.YAMLError:
+            return None, f"ignored {source} skill {name!r}: invalid YAML front matter"
+        meta = loaded if isinstance(loaded, dict) else {}
+        body = text[match.end() :].strip()
+    else:
+        body = text.strip()
+    if not body:
+        return None, f"ignored {source} skill {name!r}: no instructions"
+    heading = re.search(r"^#\s+(.+)$", body, re.MULTILINE)
+    description = str(meta.get("description") or "").strip()
+    if not description:
+        paragraph = next(
+            (p.strip() for p in re.split(r"\n\s*\n", body) if p.strip() and not p.startswith("#")),
+            "",
+        )
+        description = re.sub(r"\s+", " ", paragraph)
+    mode = str(meta.get("mode") or "").strip().lower() or None
+    return (
+        Skill(
+            name=name,
+            description=description[:300] or "project skill",
+            instructions=body,
+            path=file,
+            source=source,
+            mode=mode if mode in {"agent", "plan", "ask"} else None,
+            arguments=str(meta.get("arguments") or "")[:80],
+            title=heading.group(1).strip() if heading else name.replace("-", " ").title(),
+        ),
+        None,
+    )
+
+
+def load_skills(workspace: Path, reserved: set[str] | None = None) -> tuple[list[Skill], list[str]]:
+    """All skills for ``workspace`` plus diagnostics about folders that were skipped."""
+    found: dict[str, Skill] = {}
+    problems: list[str] = []
+    for source, root in skill_dirs(workspace):
+        if not root.is_dir():
+            continue
+        for folder in sorted(root.iterdir())[:MAX_SKILLS]:
+            if not folder.is_dir():
+                continue
+            skill, problem = _load_one(folder, source)
+            if problem:
+                problems.append(problem)
+            if skill is None or skill.name in found:
+                continue
+            if reserved and skill.name in reserved:
+                problems.append(f"skill {skill.name!r} has the name of a built-in command; renamed")
+                continue
+            found[skill.name] = skill
+    return sorted(found.values(), key=lambda s: s.name), problems
+
+
+def create_skill(workspace: Path, name: str, description: str, *, user: bool = False) -> Path:
+    name = name.strip().lower()
+    if not NAME.fullmatch(name):
+        raise ValueError("skill names use lowercase letters, digits, - and _")
+    root = (config_home() / "skills") if user else (Path(workspace) / ".traceforge" / "skills")
+    folder = root / name
+    file = folder / "SKILL.md"
+    if file.exists():
+        raise FileExistsError(f"{file} already exists")
+    folder.mkdir(parents=True, exist_ok=True)
+    title = name.replace("-", " ").replace("_", " ").title()
+    file.write_text(
+        SKILL_TEMPLATE.format(description=description or f"{title} procedure", title=title),
+        encoding="utf-8",
+    )
+    return file

traceforge/skill_library/circuit-simulation/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: circuit-simulation
+description: Simulate a KiCad circuit or a SPICE deck with ngspice (DC, AC, transient, noise, operating point), read -3 dB, poles and margins, tune a component to a spec, and export CSV, VCD, SVG or LTspice files.
+---
+
+# Circuit simulation
+
+Use this when the user wants to check or tune analogue behaviour: a filter cutoff, an LED
+current, a step response, a rectifier, a regulator's output, noise.
+
+1. Build and run with `kicad_simulate`. For a schematic it takes connectivity from KiCad
+   and values from the symbols. Parts with `Sim.*` fields use them; LEDs, diodes,
+   op-amps, LDOs, MOSFETs and BJTs without a model get a generic stand-in that is listed in
+   `generic_models`. Parts with no model (connectors, MCUs) are listed in `skipped_parts`:
+   say so, because anything they drive is floating. A schematic has no power source, so
+   pass `sources` (for example `{"pos": "VBUS", "dc": 5}`). Ground nets (GND, GNDA, ...) map to 0.
+2. Pick the analysis: `.op` (currents and voltages; ask for `i(R5)` in `probes`), `.ac dec 40 10 100k`
+   (Bode, -3 dB, poles, second-order f0/Q), `.tran 10u 20m`, `.noise`, `.dc`. Add `.meas` lines
+   for numbers you need. For phase and gain margin give `loop_gain` (an AC signal that is the
+   loop gain); the poles-based phase margin is only an equivalent for a second-order system.
+3. To meet a spec use `sim_tune`: `parameter` "R1,R2" (tied) or "param:NAME", `target`
+   "f3db(v(out))=500", an AC analysis. It reports every iteration. Apply the result to the
+   schematic with `kicad_set_field`, then simulate again. Round to the nearest standard value
+   and re-simulate: the E-series value changes the answer.
+4. `export` gives csv, vcd (transient or DC) and svg; `sim_plot` re-plots a rawfile.
+5. `engine: "ltspice"` only writes a netlist and `.asc` for LTspice. LTspice does not run
+   here, and the `.asc` is untested in LTspice. ngspice cannot run LTspice-only models.
+
+Report what is generic and what was skipped. Never present a result from a generic model as
+the behaviour of the real part.

traceforge/skill_library/compliance-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: compliance-review
+description: Compliance-oriented review aids - IPC-2221 conductor width and spacing, creepage and clearance by voltage class, and a DO-160 test category checklist. Guides and checklists, not certification.
+---
+
+# Compliance review
+
+These are review aids. They do not certify anything; the applicable standard and a test lab decide.
+
+## IPC-2221 (deterministic)
+Declare currents and voltages in `.traceforge/electrical.yaml`:
+
+    delta_t: 10
+    copper_oz: {outer: 1, inner: 0.5}
+    coating: uncoated        # uncoated | coated | conformal
+    nets:
+      VBUS: {current_a: 10, voltage_v: 5}
+      "MAINS_*": {voltage_v: 230}
+
+or name net classes `Power_10A`, `HV_230V`. Run `kicad_ipc2221` (or the `pcb.ipc2221` validate check) to
+find tracks narrower than IPC-2221 requires (I = k dT^0.44 A^0.725; 10 A, 10 K, 1 oz external needs about
+7.2 mm) and conductors closer than Table 6-1 allows for the voltage between them.
+`kicad_ipc2221 width_for_a=3` and `voltage_v=230` answer lookups.
+
+## Creepage and clearance (IEC 60664-1 style guide, pollution degree 2)
+Creepage by working voltage (rms), FR-4 (material group III, CTI 175-400): 50 V 1.2 mm, 100 V 1.4, 250 V 2.5,
+400 V 4.0, 630 V 6.3, 1000 V 10.0. Basic-insulation clearance, overvoltage category II: 150 V 0.5 mm, 300 V
+1.5, 600 V 3.0, 1000 V 5.5. Reinforced insulation doubles clearance; pollution degree 3 or altitude over
+2000 m needs the standard's multipliers. Use `kicad_ipc2221 voltage_v=...` for the numbers, and add slots
+under mains-to-SELV barriers. Measure on the board (DRC clearance and a creepage path by hand); the tool
+checks copper-to-copper distance only.
+
+## DO-160 test category checklist (airborne equipment part class)
+For each section decide the category with the customer, record it, and note the design response. This is a
+checklist, not certification: only an accredited test per the current DO-160 revision shows compliance.
+- 4 Temperature and altitude: operating range, ground survival, short-time operating; part ratings, derating, thermal review.
+- 5 Temperature variation: solder joints, large BGAs, conformal coat cracking.
+- 6 Humidity: coating, creepage after moisture, connector sealing.
+- 7 Operational shocks and crash safety: heavy parts retained, connector retention.
+- 8 Vibration: mass and mounting, tall capacitors and magnetics bonded, crystal and relay placement.
+- 9 Explosive atmosphere, 10 Waterproofness, 11 Fluids: enclosure and finish decisions.
+- 12 Sand and dust, 13 Fungus, 14 Salt fog: coating and finish.
+- 15 Magnetic effect: compass-safe distance.
+- 16 Power input: voltage ranges, transients, brownout and interrupt behaviour; input protection, hold-up.
+- 17 Voltage spike: TVS and clamp ratings on every power input.
+- 18 Audio frequency conducted susceptibility: filter and regulator PSRR.
+- 19 Induced signal susceptibility, 20 and 21 RF susceptibility and emissions: shielding, filtering, ground strategy, clock and switcher layout.
+- 22 Lightning induced transients: protection on external lines, isolation.
+- 23 Lightning direct effects, 24 Icing, 25 ESD (connectors and user-touch points, TVS at connectors).
+- 26 Fire and flammability: PCB laminate and plastics ratings.
+Record each category as "level required / design response / evidence (file, test)" in the review notes.

traceforge/skill_library/design-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: design-review
+description: Structured pre-fabrication review of a KiCad project, with one read-only subagent per subsystem or part group and a findings list rated P0-P3 with evidence.
+---
+
+# Design review
+
+Use this when the user asks for a review, an audit or "is this ready to order?".
+
+## 1. Establish the facts first
+
+1. `kicad_project`, then `kicad_components` and `kicad_board`.
+2. Run the deterministic checks yourself: `kicad_erc`, `kicad_drc` (with parity) and,
+   where useful, `kicad_netlist`. Record what could not run and why.
+3. Read `TRACEFORGE.md` and `.traceforge/notes/` for the stated requirements.
+4. Write a todo list with `write_todos`: one item per stage below.
+
+## 2. Fan out the part-level checks
+
+Group the parts by subsystem (power input and protection, regulators, MCU and its
+support parts, each interface connector, indicators). Start one `task` call per group
+with `subagent_type: explore`, all in the same response so they run in parallel. Give
+each subagent:
+
+- the references in its group, the schematic and board paths,
+- what to verify: symbol pin mapping against the footprint pads (`kicad_symbol_pins`,
+  `kicad_footprint_pads`), footprint against the part number's package, values against
+  datasheet equations (show the arithmetic), ratings (voltage, current, power,
+  temperature), decoupling and pull-ups, and placement of the group on the board
+  (`kicad_board`, `kicad_netlist` for pin-level nets),
+- the report format: one line per finding, `P0..P3 | reference | problem | evidence`,
+  then "no issues" lines for what was checked and found correct.
+
+## 3. Cross-cutting checks (yourself)
+
+Power tree and sequencing, connector protection (ESD, reverse polarity, fuses),
+schematic/board parity, routing of power and return paths, fab limits for the chosen
+fab, silkscreen (reference designators visible, polarity marks), fiducials and
+assembly data (part numbers on every placed part), and the release package.
+
+## 4. Report
+
+Merge the subagent reports with your own findings, remove duplicates, and sort by
+severity. Every finding needs evidence: file and location, a check result, a datasheet
+section or a calculation. End with a verdict (ready / ready after fixes / not ready)
+and the list of what was not verified. Save a short version with `save_note`
+(name `review_<date>`), and update `design_summary` if you learned something durable.

traceforge/skill_library/errata-hunt/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: errata-hunt
+description: Find silicon errata, datasheet warnings and known design gotchas for the parts in a KiCad project before bring-up, and check the design against each one.
+---
+
+# Errata hunt
+
+Use this when the user asks about errata, known issues, "gotchas", or wants a part-level
+risk check before ordering boards.
+
+1. `kicad_components` to list the parts. Skip passives and connectors unless the user
+   asks; focus on ICs, regulators, crystals/oscillators, modules and protection parts.
+2. Start with `errata_hunt` (part=MPN): it fetches the datasheet and errata documents, extracts
+   candidate items with page/section citations and severity, merges duplicates and ranks them.
+   Items with `verified: false` had no retrievable source; report them as unverified, never as fact.
+   Then, for each part (fan out with read-only subagents when there are more than five):
+   - `part_lookup` for the exact MPN and its datasheet URL; `datasheet_fetch` the
+     datasheet and look for "Errata", "Application information", "Layout guidelines",
+     absolute maximum ratings and footnotes.
+   - `web_search` for "<MPN> errata", "<MPN> silicon revision", "<MPN> known issues"
+     and the manufacturer's errata sheet; `web_fetch` the ones that match the part's
+     revision/date code where stated.
+3. Check each finding against the design: `kicad_symbol_pins`, `kicad_netlist`,
+   `kicad_board` (e.g. a required pull-up present, a forbidden pin state avoided, the
+   decoupling and layout rule followed, the affected silicon revision actually used).
+4. Report a table: part, issue, source (URL + section), affects this design (yes/no/
+   unknown with the evidence), fix. Rate each P0-P3. Save it with `save_note`.
+
+Never claim an erratum without a source; say "no errata found" only after checking the
+manufacturer's site.

traceforge/skill_library/firmware/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: firmware
+description: Firmware that matches the hardware - pin map from the schematic nets, pin headers, project scaffolds (Arduino, PlatformIO, ESP-IDF, STM32, AVR), I2C/SPI driver snippets, and compiling with the real toolchain.
+---
+
+# Firmware from the schematic
+
+Use this when the user wants code for the board: pin definitions, a starter project, a
+driver for a sensor, or a compile check.
+
+1. `firmware_pins` on the design (`.yaml`, `.kicad_sch` or `.net`). Read the warnings first:
+   strapping pins, flash/PSRAM pins, USB pins, RESET used as I/O, a net named like I2C on a
+   pin that has no I2C. Report them before writing code; fix the schematic if a pin is wrong.
+2. Check the pin table is for the same package/module as the design (the data cites its
+   datasheet table). If the MCU is not in the table, say so and ask for the pin names.
+3. `firmware_scaffold` with the target the user names (arduino, platformio, esp-idf, stm32,
+   avr). Pass `drivers` for the sensors on the board; use `firmware_driver` with no `part` to
+   list them. Drivers include the part's address; confirm address straps (SDO, ADDR, A0-A2)
+   against the schematic nets and pass `address` when they differ.
+4. `firmware_toolchain` shows what is installed. `firmware_build` compiles for real and
+   returns parsed errors and flash/RAM use. Never claim a build passed unless the tool did;
+   if the toolchain is missing, give the install line it returns and say what was not run.
+5. `firmware_flash` always asks the user. Use `dry_run` to show the command first.
+
+The pin header is generated: regenerate it after a schematic change, do not edit it.
+Raw sensor reads (BME280) need the datasheet's compensation to become units; say so.

traceforge/skill_library/power-budget/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: power-budget
+description: Power budget for a KiCad design - current per rail and operating mode, regulator headroom and dissipation, and battery sizing and runtime.
+---
+
+# Power budget
+
+Use this when the user asks for a power budget, battery life, regulator sizing or
+thermal headroom.
+
+1. Map the power tree: `kicad_netlist` and `kicad_components` give the rails, the
+   regulators feeding them and the loads on each rail. Confirm unclear rails with the user.
+2. Ask for (or propose) the operating modes: e.g. active, radio TX, idle, sleep, and the
+   duty cycle of each. Write them down before computing.
+3. For each load and mode take the current from the datasheet (`part_lookup`,
+   `datasheet_fetch`): typical and maximum, with the table/figure cited.
+4. Per rail and mode: sum the loads, add regulator quiescent current, and compute input
+   current (LDO: same current; switcher: P_out / (efficiency x V_in), efficiency from the
+   datasheet curve at that load). Check each regulator's rated current with 20-30 %
+   margin and its dissipation (LDO: (V_in - V_out) x I) against package thermal
+   resistance and the maximum ambient temperature.
+5. Battery: average current from the duty cycles, capacity derated for temperature,
+   cut-off voltage and ageing (assume 80 % usable unless the user says otherwise);
+   runtime = usable capacity / average current. Propose cells if none is chosen.
+6. Present one table per mode (rail, loads, current, regulator, margin, dissipation),
+   the battery result, and the risks (P0-P3). Save the tables with `save_note`. Use
+   `execute` with Python for the arithmetic, not mental math.

traceforge/skill_library/release-package/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: release-package
+description: Produce and verify a complete fabrication and assembly release (Gerbers, drill, BOM, CPL, schematic PDF, README) for JLCPCB or another fab.
+---
+
+# Release package
+
+Use this when the user asks for fabrication files, "outputs", or to get a board ready
+to order.
+
+1. Gate on the checks. Run `kicad_drc` (zones refilled, parity on) and `kicad_erc`.
+   Do not release while DRC has errors or unconnected items; fix them first or stop
+   and tell the user exactly what blocks the release.
+2. Check assembly data: every part that will be assembled has an LCSC (or MPN) field,
+   values match the schematic, and DNP parts are marked. List any gaps.
+3. Write the outputs with `kicad_export` (kinds: gerbers, bom, cpl, netlist, svg) into
+   `outputs/` (or the folder the user names).
+4. Verify what was written:
+   - Gerbers include every copper layer, both masks, both silkscreens, paste and the
+     edge cuts, plus the drill file; zip them for upload with `execute`.
+   - The CPL has one row per placed SMD part, with rotations; spot-check polarised
+     parts (diodes, LEDs, ICs) against their footprint orientation.
+   - The BOM groups identical parts and its quantities add up to the placed parts.
+5. Render the board (`kicad_export` svg, then `read_file` with `as_image: true`) and
+   look at it: silkscreen legible, reference designators visible, connectors on edges.
+6. Write `outputs/README.md`: board size, layer count, thickness, finish, fab settings,
+   programming or bring-up notes, and the check results with the date.
+7. Report the file list with sizes and anything the user must still decide (finish,
+   colour, assembly side, quantity).

traceforge/skill_library/sourcing-brief/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: sourcing-brief
+description: Sourcing brief for a design's BOM - availability and price breaks by distributor, alternates, lifecycle risk, HS codes and landed-cost notes for the target volume.
+---
+
+# Sourcing brief
+
+Use this when the user asks to source parts, compare suppliers, check stock/lifecycle,
+or prepare a BOM for purchasing.
+
+1. Ask for the build volume(s) and the destination country if not given.
+2. `kicad_components` (or the BOM from `kicad_export`) for the line items. Group
+   identical parts.
+3. For each line: `part_search` / `part_lookup` for stock, price breaks at the target
+   volume, MOQ, lifecycle status and the LCSC/MPN; `web_search` for other distributors
+   when the user wants more than one source. Mark single-source and NRND/EOL parts.
+4. Propose drop-in alternates for risky lines (same package and pinout, ratings checked
+   with `parts_check`) and say what must be verified before swapping.
+5. Add HS codes for the main part classes and note duties or landed-cost factors only
+   when the destination is known; say clearly that duty rates must be confirmed with
+   the forwarder.
+6. Deliver a table (line, refs, MPN, qty, best source, unit and extended price at volume,
+   stock, lifecycle, risk, alternate) with the date of the lookup, plus totals and the
+   top risks. Write it to a CSV in the workspace when the user wants a file.

traceforge/skill_library/thermal-review/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: thermal-review
+description: Estimate dissipation, copper area and junction temperature per part, list hotspots and suggest mitigation (thermal vias, copper).
+---
+
+# Thermal review
+
+1. `kicad_components` and `kicad_netlist` to find regulators, power resistors, LEDs and MOSFETs.
+2. Establish the load: ask the user or read the datasheets of the ICs on each rail, then call
+   `kicad_thermal` with `loads_ma` (ref -> mA) or `rail_current_ma` (net -> mA) and the real `ambient_c`
+   (enclosure air, not room temperature). Give `theta_ja` from the datasheet when you have it, and
+   `iq_ma` for linear regulators with significant quiescent current.
+3. Read the hotspots: parts with a Tj margin under 25 K get P2, over the limit P1. Apply the advice
+   (copper on the tab/pad net, thermal vias, lower input-output drop or a switching stage).
+4. Always repeat the tool's `limits` statement in the report: it is a screening estimate, not a simulation.