breadkit 0.1.0 → 0.2.0

data/docs/CLI.md

@@ -0,0 +1,108 @@
+# CLI reference
+
+`breadkit` accepts Ruby circuit files (`.bk.rb`), declarative YAML
+(`.bk.yml`, `.bk.yaml`) and TOML (`.bk.toml`) circuit files, and JSON IR files
+where a circuit input is required. Ruby circuit files execute code; load only
+files you trust. YAML and TOML circuit files are parsed as data. Ordinary `.yml`
+part definitions are not circuit inputs.
+
+| Command | Purpose |
+| --- | --- |
+| `breadkit new --template led\|555\|arduino [FILE]` | Create a runnable circuit file. The default name is `<template>.bk.rb`; an existing file is never overwritten. |
+| `breadkit parts [FILE]` | List built-in parts and definitions loaded by `use_parts` in `FILE`. |
+| `breadkit parts show PART [FILE]` | Print a part definition as JSON. |
+| `breadkit check-part PART.yml` | Validate one YAML part definition. |
+| `breadkit where HOLE FILE` | Show the hole's conductive strip, net, pins, and wire ends. |
+| `breadkit explain REF FILE` | Show a component's pins, resolved nets, and constrained potentials. |
+| `breadkit bom FILE` | Count parts by type and value, plus jumper wires. |
+| `breadkit diff OLD NEW` | List changed board, supplies, labels, components, and wires. |
+| `breadkit export --format FORMAT FILE` | Export `kicad`, `spice`, `wokwi`, `pins`, or `fritzing` data. |
+| `breadkit fmt FILE` | Print a normalized declarative YAML or TOML circuit file. |
+| `breadkit lock FILE` | Record the local part and board definition files used by a circuit in `breadkit.lock`. |
+| `breadkit suggest FILE` | Print JSON candidates for unmet connection intent between placed pins. Each candidate names two free board holes; nothing is changed. |
+| `breadkit kit --inventory KIT.yml FILE` | Allocate candidate jumpers from a measured YAML or JSON inventory. See [Jumper kits](JUMPER_KIT.md). |
+| `breadkit patterns FILE` | Print recognized circuit patterns as JSON. An empty array means no supported pattern matched. |
+| `breadkit console FILE` | Open IRB with the loaded `circuit` variable. |
+| `breadkit doctor` | Check the Ruby version and availability of the optional linter and renderer commands. |
+
+`nets`, `where`, and `explain` accept `--state SWITCH` for a closed switch state.
+Their default is the all-open state. A regular switch uses its reference, such
+as `SW1`. The C&K BD04 has four independent positions: `SW1.1` through
+`SW1.4`. Separate selected positions with commas, for example
+`breadkit nets --state SW1.1,SW1.4 circuit.bk.rb`. The position names are
+Breadkit logical names, not a claim about the manufacturer's terminal numbers.
+`explain` uses DC operating-point analysis for
+voltage sources, resistors, LEDs, and diodes. It reports the fixed-drop diode
+assumptions and labels ungrounded voltages as relative. Unsupported parts or
+indeterminate circuits leave currents unknown. `bom` reports quantities, not
+supplier part numbers or prices. `diff` compares resolved circuit content and
+ignores source locations.
+
+`nets`, `where`, `explain`, and `bom` print error diagnostics to standard error
+and stop before printing inspection results when the circuit is invalid.
+`suggest` follows the same rule. It skips state-specific expectations,
+offboard or unplaced pins, occupied holes, holes under component bodies, and
+connections that would merge nets with different known voltages.
+An empty JSON list means no safe candidate was found; it does not prove the
+intent is satisfied. Inspect each candidate before adding a `wire` declaration.
+
+Use `breadkit ir --force FILE` to export a circuit with diagnostics. Supplies
+can be marked `isolated: true`, and an inclusive voltage range such as
+`3.0..4.2` can describe a battery whose voltage varies. Component values may
+also include tolerance or ratings, such as `4.7k 5%`, `330 1/4W`, and
+`10u 16V`.
+
+## Circuit patterns
+
+`breadkit patterns FILE` identifies an unloaded two-resistor voltage divider
+when exactly one fixed-voltage standalone supply and two resistors form a
+series path between its terminals. It uses the DC analysis result for the
+nominal midpoint voltage and reports that voltage relative to the supply's
+negative terminal. The output names the top and bottom resistors and the
+midpoint net:
+
+```sh
+breadkit patterns divider.bk.rb
+```
+
+The command also recognizes the exact, source-backed NE555 astable wiring used
+by [the blinker example](../examples/02_555_blinker.bk.rb): a fixed supply
+within the modeled NE555 range; RESET and VCC tied to supply positive; GND tied
+to supply negative; TRIG and THR joined; a resistor from VCC to DIS; another
+from DIS to TRIG/THR; a correctly polarized timing electrolytic to ground;
+control and supply bypass capacitors; and an LED with its series resistor on
+OUT. The pin relationships follow the [TI NE555 astable circuit](https://www.ti.com/lit/ds/symlink/ne555.pdf).
+The result is labeled `ne555_astable_wiring`: it identifies a connection
+pattern, not measured oscillation. No frequency or duty cycle is estimated.
+Modified timing, reset, control, or output connections are not classified.
+
+The command prints `[]` when a valid circuit matches neither supported
+pattern. Invalid circuits report diagnostics and exit with an error. `[]` does
+not mean the circuit is safe or has no useful topology.
+
+## Export formats
+
+| Format | Supported output |
+| --- | --- |
+| `kicad` | [KiCad XML netlist](https://docs.kicad.org/9.0/en/eeschema/eeschema.html) with resolved component pin numbers and nets. It does not create a schematic or assign PCB footprints. |
+| `spice` | [ngspice](https://ngspice.sourceforge.io/docs/ngspice-46-manual.pdf) operating-point netlist for fixed voltage supplies, resistors, and capacitors. Part references must begin with `R` or `C`. Other components and ranged supplies are rejected. |
+| `wokwi` | [diagram.json](https://docs.wokwi.com/diagram-format) for Arduino Uno, resistors, and LEDs. Breadboard connections are flattened into wires between part pins. Standalone supplies and unsupported parts are rejected. Add a sketch to simulate it. |
+| `pins` | Arduino C header constants for a connected Uno, or MicroPython constants for a connected Pico W / RP2040 board. Label nets to give constants stable signal names. |
+| `fritzing` | Native, uncompressed Fritzing `.fz` sketch for the exact built-in 830-hole `full` breadboard, straight electrical jumpers, resistors, red 5 mm LEDs, and 4-pin tact switches. The 50-hole power rails must be unsplit. Resistor and LED leads must share a row; resistor pin 1 must be left of pin 2. Other parts, standalone supplies, net labels, boards, and styled wires are rejected with an error. |
+
+Export stops when the circuit has error diagnostics. `kicad` preserves physical
+pin numbers but leaves library and footprint assignment to the KiCad project.
+
+For a supported full-board circuit, run `breadkit export --format fritzing
+board.bk.rb > board.fz` and open `board.fz` in Fritzing. The exporter uses
+Fritzing's bundled 830-hole breadboard, resistor, red LED, 4-pin pushbutton,
+and wire parts. It does not generate a `.fzz` archive or import custom
+Fritzing parts. The Fritzing export is available only for the documented
+subset; use the renderer for a Breadkit diagram of other circuits. Resistor
+values must be plain numbers with an optional engineering suffix (for example,
+`330` or `1k`); values with a tolerance, power rating, or `Ω` suffix are
+rejected because those properties are not yet preserved in this export.
+
+See the [declarative circuit guide](DECLARATIVE.md) for complete YAML and TOML
+examples. The same commands work with any supported circuit input format.
+See [locking local definitions](LOCK.md) for the lockfile format and verification behavior.

data/docs/COMPATIBILITY.md

@@ -0,0 +1,60 @@
+# Compatibility and versioning
+
+Breadkit, breadkit-lint, and breadkit-render are separate gems. Each gem has its
+own version and release schedule. The lint and render gemspecs declare the core
+versions they support; no shared release number is required.
+
+Breadkit is currently a 0.x project. Until 1.0, a minor release may change the
+Ruby DSL, CLI, or analysis behavior. Patch releases preserve their documented
+inputs and output contracts. After 1.0, incompatible DSL or Ruby API changes
+require a new major gem version.
+
+JSON interfaces have their own `schema_version`, independent of gem versions:
+
+| Interface | Current schema | Compatibility rule |
+| --- | --- | --- |
+| Circuit IR | [v1](https://breadkit.github.io/breadkit/schema/ir-v1.json) for one unnamed board; [v2](https://breadkit.github.io/breadkit/schema/ir-v2.json) for named boards | A reader accepts supported versions explicitly. A breaking field or meaning change requires a new schema version. |
+| Part YAML | [v1](https://breadkit.github.io/breadkit/schema/part-v1.json) | New optional fields may be added. Existing fields keep their meaning within v1. |
+| Board YAML | [v1](https://breadkit.github.io/breadkit/schema/board-v1.json) | New optional fields may be added. Existing fields keep their meaning within v1. |
+
+The JSON IR writer selects v1 for a single unnamed board and v2 for named
+boards. Consumers should check `schema_version` before reading an IR file and
+ignore unknown optional fields. They should not infer the IR version from the
+gem version. The linter publishes its own [result schema](https://breadkit.github.io/breadkit-lint/schemas/lint-v1.json).
+
+## Editor schema associations
+
+Part and board files can use any YAML filename when referenced by `use_parts`
+or `use_boards`. The optional `.bkpart.yml` and `.bkboard.yml` endings make
+editor associations unambiguous. In VS Code with the YAML extension, use a
+modeline at the start of an individual file:
+
+```yaml
+# yaml-language-server: $schema=https://breadkit.github.io/breadkit/schema/part-v1.json
+id: custom_part
+pins:
+  - {num: 1, name: SIGNAL}
+```
+
+For a whole workspace, add this to `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://breadkit.github.io/breadkit/schema/part-v1.json": "*.bkpart.yml",
+    "https://breadkit.github.io/breadkit/schema/board-v1.json": "*.bkboard.yml"
+  },
+  "json.schemas": [
+    { "fileMatch": ["*.bkir.json"], "url": "https://breadkit.github.io/breadkit/schema/ir-v1.json" },
+    { "fileMatch": ["*.bkir-v2.json"], "url": "https://breadkit.github.io/breadkit/schema/ir-v2.json" }
+  ]
+}
+```
+
+Use `ir-v2.json` for named-board IR. `.bkir.json` and `.bkir-v2.json` are
+optional filenames; `Breadkit.load` accepts any `.json` circuit IR file.
+
+Before a 1.0 release, changes to a public schema or documented DSL form need
+round-trip coverage and an entry in the relevant gem's changelog. The published
+schema files are versioned artifacts; changing a v1 schema to reinterpret
+existing fields is a breaking change and requires v2 instead.

data/docs/DECLARATIVE.md

@@ -0,0 +1,138 @@
+# YAML and TOML circuit files
+
+Use `.bk.yml` or `.bk.yaml` for YAML and `.bk.toml` for TOML. Breadkit parses
+these files as data and passes their declarations through the same builder and
+resolver used by the Ruby DSL. Ordinary `.yml` files remain part definitions.
+
+Try the complete [YAML](../examples/06_declarative_led.bk.yml) and
+[TOML](../examples/07_declarative_led.bk.toml) LED examples:
+
+```sh
+breadkit nets examples/06_declarative_led.bk.yml
+breadkit ir examples/07_declarative_led.bk.toml > circuit.json
+breadkit fmt examples/06_declarative_led.bk.yml > formatted.bk.yml
+```
+
+The YAML example describes a USB supply, resistor, LED, jumper wire, and three
+expected connections:
+
+```yaml
+title: LED circuit
+board: mini
+supplies:
+  - {name: USB, voltage: 5, plus: a1, minus: a2}
+labels:
+  - {name: VCC, at: a1}
+  - {name: GND, at: a2}
+parts:
+  - {ref: R1, type: resistor, value: "330", pins: [b1, b3]}
+  - {ref: D1, type: led, pins: {anode: c3, cathode: c4}, attrs: {color: red}}
+wires:
+  - {from: d4, to: b2, color: black}
+expectations:
+  - connected: [[VCC, R1.1], [R1.2, D1.anode], [D1.cathode, GND]]
+```
+
+## Fields
+
+| Field | Shape | Meaning |
+| --- | --- | --- |
+| `title` | text | Circuit title. |
+| `board` | text or mapping | Board type, optionally `{type: full, split_rails: true}`. |
+| `boards` | list of mappings | Named boards with `name`, `type`, and optional `split_rails`; use instead of `board`. Qualify holes as `B1.a1`. |
+| `use_parts`, `use_boards` | path or list of paths | Load definitions relative to the circuit file. Globs are accepted. |
+| `supplies` | list of mappings | Either `name`, `voltage`, `plus`, `minus` for a standalone source, or `from`, `plus`, `minus` to route a defined offboard output. Standalone sources also accept `isolated` and numeric `current_limit`. |
+| `labels` | list of mappings | `name` and `at` for a named net. |
+| `parts` | list of mappings | `ref`, `type`; optional `value`, `pins`, `at`, `attrs`, `unused`. |
+| `offboard` | list of mappings | `ref`, `type`; optional `side`, `at`, `attrs`, `unused`. `offboard: true` also works in a `parts` entry. |
+| `wires` | list of mappings | `from`, `to`; optional `color`, `id`, `route`, `layer`, `electrical`, `dashed`. |
+| `connections` | list of mappings | Intent assertions with `from`, `to`, and optional `when` switch state. They do not place wires. |
+| `expectations` | list of mappings | Optional `strict`, `when`, and connection, isolation, net, voltage, or current checks. |
+| `lint_disables` | list of mappings | `rule`; optional `on` and `reason`. |
+
+Quote `"on"` when using that key in YAML, because YAML parsers may interpret
+an unquoted `on` as a boolean.
+
+Use a list for positional part pins (`pins: [b1, b3]`) or a mapping for named
+pins (`pins: {anode: c3, cathode: c4}`). `attrs` holds part-specific options,
+such as `color`, `rotate`, or `mirror`. Supply voltage can be a number, a value
+string such as `3.3V`, or an inclusive range string such as `3.0..4.2`. Part
+values accept the same notation as the Ruby DSL, including `4.7k 5%`,
+`330 1/4W`, and `10u 16V`.
+
+Declare expected connectivity separately from physical wiring:
+
+```yaml
+connections:
+  - {from: R1.1, to: D1.anode}
+wires:
+  - {from: b1, to: a5}
+```
+
+The connection records the same IR expectation as Ruby `connect`; only the
+wire changes connectivity. Run `bklint` to report a mismatch or an unknown
+reference. Run `breadkit suggest FILE` for free-hole candidates when both pins
+are physically placed. TOML uses `[[connections]]` with `from` and `to` fields.
+
+An expectation can contain `connected` or `isolated` as lists of reference
+lists, `nets` as a list of `{name, refs}` mappings, and `voltage` or `current`
+as lists of `{ref, range}` mappings. Measurement ranges use inclusive strings
+such as `"3.0..3.6"`. `when` names a switch state. Example:
+
+```yaml
+expectations:
+  - strict: true
+    connected: [[VCC, R1.1]]
+    isolated: [[VCC, GND]]
+    nets: [{name: VCC, refs: [R1.1]}]
+    voltage: [{ref: VCC, range: "4.8..5.2"}]
+```
+
+For TOML, use a `[[section]]` array of tables for each list entry. The
+[complete TOML example](../examples/07_declarative_led.bk.toml) shows this
+structure. For a custom offboard module, define its part in YAML and load it
+with `use_parts`:
+
+```yaml
+board: mini
+use_parts: [sensor.yml]
+offboard:
+  - {ref: SENSOR, type: sensor, side: left}
+wires:
+  - {from: SENSOR.SIG, to: a1}
+```
+
+YAML object tags and aliases are rejected. Unknown fields and invalid field
+types produce input errors. Diagnostics from declarative files currently point
+to the file's first line rather than the individual field.
+
+For multiple boards, use `boards` instead of `board`:
+
+```yaml
+boards:
+  - {name: B1, type: half}
+  - {name: B2, type: mini}
+wires:
+  - {from: B1.a1, to: B2.j1}
+```
+
+This produces version 2 IR. See the [DSL reference](dsl.md#multiple-boards)
+for board identity and connection rules.
+
+An offboard output can feed rails without declaring a duplicate voltage source:
+
+```yaml
+board: half
+offboard:
+  - {ref: UNO, type: arduino_uno}
+supplies:
+  - {from: UNO.5V, plus: T+, minus: T-}
+```
+
+The output voltage and return pin come from the part's `provides` definition.
+Both rail destinations are required, and the resolved IR contains two wires.
+
+`breadkit fmt FILE` prints canonical YAML or TOML without modifying the input.
+It validates the circuit fields first and keeps the original format. Formatting
+discards comments, so review the output before replacing a commented source
+file. Ruby DSL files are not supported by this formatter.

data/docs/IR.md

@@ -0,0 +1,42 @@
+# JSON circuit IR
+
+Breadkit IR is a resolved circuit in JSON. Generate it from a circuit file to
+pass the same circuit to Breadkit, breadkit-render, breadkit-lint, or another
+tool. JSON input is data-only; Ruby DSL input executes code.
+
+```sh
+breadkit ir examples/06_declarative_led.bk.yml > circuit.json
+breadkit nets circuit.json
+```
+
+Here is a compact, valid v1 IR input for a circuit using built-in definitions:
+
+```json
+{
+  "schema_version": 1,
+  "title": "LED circuit",
+  "board": { "type": "mini", "options": { "split_rails": false } },
+  "supplies": [
+    { "name": "USB", "voltage": 5, "plus": "a1", "minus": "a2", "source": null }
+  ],
+  "labels": [],
+  "components": [
+    { "ref": "R1", "part": "resistor", "value": "330", "attrs": {},
+      "pins": { "1": "b1", "2": "b3" }, "unused": [], "source": null },
+    { "ref": "D1", "part": "led", "value": null, "attrs": { "color": "red" },
+      "pins": { "anode": "c3", "cathode": "c4" }, "unused": [], "source": null }
+  ],
+  "wires": [
+    { "id": "W1", "from": "d4", "to": "b2", "color": null,
+      "route": "straight", "source": null }
+  ],
+  "expectations": []
+}
+```
+
+`breadkit ir` writes additional resolved details, including the board
+definition, any custom part definitions, source locations, and `analysis.nets`.
+The reader recalculates `analysis` when loading IR. Use
+[IR v1](../schema/ir-v1.json) for one unnamed board and
+[IR v2](../schema/ir-v2.json) for named boards. See the
+[compatibility policy](COMPATIBILITY.md) before consuming IR in another tool.

data/docs/JUMPER_KIT.md

@@ -0,0 +1,45 @@
+# Jumper kit allocation
+
+Record the usable span of the jumpers you own, measured between the hole
+centers they can reach after insertion. Use millimeters and count each color
+and size separately:
+
+```yaml
+wires:
+  - {color: red, usable_span_mm: 12, count: 4}
+  - {color: black, usable_span_mm: 20, count: 3}
+measured_routes:
+  W3: 18
+```
+
+Run `breadkit kit --inventory kit.yml circuit.bk.yml`. JSON inventories with
+the same structure are accepted. The command prints JSON with `assignments`,
+`unassigned`, and `skipped` arrays. Each assignment includes a wire ID, color,
+chosen usable span, required span, and its source (`board_geometry` or
+`measured`). For a measured route without board geometry, `minimum_span_mm` is
+null. Inventory counts
+are never reused. A wire with an explicit color only matches the same color;
+an uncolored wire can use any inventory color. Color names are compared without
+case. The command leaves the circuit and inventory unchanged.
+
+The allocator uses the 2.54 mm terminal-hole geometry of the packaged mini,
+half, full, and double-full breadboards. Without a `measured_routes` entry, it
+considers only electrical, straight wires between terminal holes on the same
+board. It skips rail and offboard endpoints, solder boards, custom boards
+without verified pitch, cross-board wires, and curved or edge routes with a
+reason in `skipped`. Board spacing in a multi-board diagram is for display and
+cannot determine a real cable length.
+
+Use `measured_routes` when you have measured the required usable cable span for
+a specific wire, including bends, rise, and the chosen physical route. This
+allows a rail, offboard, curved, or cross-board wire to use the kit without
+pretending its diagram coordinates are physical measurements. Wire IDs must
+exist in the circuit; give such wires explicit `id:` values if declarations
+may be reordered. A measured span for a terminal wire cannot be shorter than
+the modeled endpoint span. Visual-only wires cannot receive a measured route.
+
+The modeled endpoint span is a lower bound. Routing around components, wire rise,
+connector shape, and how the board is mounted can require more length. Measure
+`usable_span_mm` with those allowances and inspect each proposed assignment
+before building. An `unassigned` entry means the inventory cannot cover an
+eligible wire under these constraints; it does not change the circuit.

data/docs/LOCK.md

@@ -0,0 +1,75 @@
+# Locking local definitions
+
+Circuit files can load local YAML part and board definitions with `use_parts`
+and `use_boards`. Patterns may match different files after a project changes.
+Run `breadkit lock FILE` to record the exact matched paths and their SHA-256
+checksums:
+
+```yaml
+# logger.bk.yml
+board: mini
+use_parts: [parts/*.yml]
+offboard:
+  - {ref: SENSOR, type: custom_sensor}
+```
+
+```sh
+breadkit lock logger.bk.yml
+breadkit nets logger.bk.yml
+```
+
+The command writes `breadkit.lock` beside the circuit. Commit the lockfile
+with the circuit and definitions. Each entry records a circuit filename, the
+Breadkit version, and relative paths and checksums for its local part and
+board YAML files. Multiple circuit files in one directory have separate
+entries in the same lockfile. Running `breadkit lock FILE` again updates only
+that circuit's entry.
+
+When a lockfile exists, Breadkit checks the entry before resolving a Ruby,
+YAML, or TOML circuit. A changed definition, a new or removed glob match, a
+different Breadkit version, or a missing circuit entry stops loading with an
+error. Run `breadkit lock FILE` again after intentionally changing local
+definitions. This check also applies to the MCP and LSP servers when they
+resolve supported circuit inputs. JSON IR files are self-contained and do not
+use the lockfile.
+
+The lockfile pins only local YAML definitions loaded by `use_parts` and
+`use_boards`, plus the Breadkit version. It does not hash the circuit source,
+Ruby DSL files loaded with `include`, other gems, or external tools. Ruby DSL
+files are executable and should only be loaded when trusted. Declarative YAML
+and TOML circuit files remain data-only.
+
+## Vendored part packs
+
+To share a versioned pack today, keep its YAML files under your project, for
+example as a Git submodule pinned to a commit under `vendor/parts/`. Point
+`use_parts` at those local files and commit both the Git revision and
+`breadkit.lock`. The lock checks the exact YAML bytes even if a submodule or
+checkout changes unexpectedly:
+
+```yaml
+board: mini
+use_parts: [vendor/parts/*.yml]
+```
+
+Breadkit does not download packs, resolve remote versions, or authenticate a
+Git source. Those steps remain with your existing Git or package manager
+workflow. Avoid loading unpinned remote files directly into a circuit.
+
+For a shared Git pack, pin the submodule to a reviewed commit and commit the
+submodule pointer, circuit, and generated lockfile together. In CI, check out
+submodules before running Breadkit. A pack repository can validate each
+definition with `breadkit check-part`; editors can use the public
+[`part-v1` schema](https://breadkit.github.io/breadkit/schema/part-v1.json):
+
+```sh
+for file in parts/*.yml; do
+  breadkit check-part "$file"
+done
+```
+
+Consumers should run `breadkit nets FILE` or `breadkit ir FILE` in CI after
+the submodule checkout. That verifies the recorded SHA-256 bytes and the
+exact set of matched definitions before a diagram or report is produced.
+The Git commit pins the pack version; `breadkit.lock` catches changed YAML
+bytes or newly matched files even when the checkout differs from that commit.

data/docs/LSP.md

@@ -0,0 +1,59 @@
+# Language server and VS Code extension
+
+`breadkit-lsp` is a stdio Language Server Protocol 3.18 server. It provides:
+
+- Full-document diagnostics as a YAML or TOML circuit is edited.
+- Completion for board holes, rail holes, component pins, and net labels.
+- Hover with the resolved net name and potential. Unconstrained potentials are
+  shown as unknown.
+
+The server accepts `.bk.yml`, `.bk.yaml`, `.bk.toml`, and `.bk.rb` documents.
+YAML and TOML buffers use safe data parsers and do not execute Ruby. Ruby DSL
+files receive hole completion without evaluation by default. To enable full
+Ruby diagnostics, component pin completion, and net hover, start the server
+with both `--root DIRECTORY` and `--trusted-ruby`. This evaluates Ruby source,
+including unsaved edits, with the permissions of the server process. Use it
+only for code you trust. `--root` limits data-only circuit files and declared
+part or board files to that directory. It is not a sandbox for Ruby code.
+
+```sh
+breadkit-lsp --root /path/to/project
+```
+
+The server uses standard LSP framing on stdin/stdout. It supports `initialize`,
+`shutdown`, `exit`, full `didOpen`/`didChange`/`didClose` synchronization,
+`textDocument/completion`, `textDocument/hover`, and push diagnostics. Run it
+from an LSP client; stdout is reserved for protocol messages.
+
+## VS Code
+
+The source for the minimal desktop extension is in [`vscode/`](../vscode/).
+It needs VS Code 1.100 or newer and the `breadkit` gem installed in the Ruby
+environment used by VS Code. Preview also needs the separately installed
+`breadkit-render` gem (`bkrender` command).
+
+To make a local VSIX with the [VS Code extension packaging tool](https://code.visualstudio.com/api/working-with-extensions/publishing-extension):
+
+```sh
+cd vscode
+npx --yes @vscode/vsce@4.0.0 package --no-dependencies
+code --install-extension breadkit-0.1.0.vsix
+```
+
+Open a `.bk.yml`, `.bk.yaml`, `.bk.toml`, or `.bk.rb` file. The extension starts
+the server when a Breadkit file is opened. Run **Breadkit: Preview Circuit**
+from the Command Palette to render the saved file as a static, dark SVG in a
+side panel. Save edits before previewing. Preview runs only in a trusted
+workspace. For Ruby files, set `breadkit.evaluateRubyDsl` to `true` as well.
+The setting also enables Ruby analysis after the extension host restarts.
+
+Set `breadkit.serverCommand` or `breadkit.renderCommand` if the commands are
+not on VS Code's `PATH`. The extension uses direct process execution without
+a shell. With one workspace folder, it passes that folder as `--root`. In a
+multi-folder window, data-only files work but Ruby evaluation remains disabled.
+
+Diagnostics from declarative files currently point to the first line of the
+file because the shared data loader does not preserve field locations.
+Completion is prefix-based; source with a parse error may have fewer
+suggestions. Hover reports resolved supply potential only and does not imply
+current or a simulated operating point.

data/docs/MB102_POWER.md

@@ -0,0 +1,11 @@
+# ShillehTek MB102 four-pin power module
+
+`shillehtek_mb102_4pin` models the [ShillehTek MB102 3.3 V/5 V module](https://shillehtek.com/blogs/shillehtek-product-manuals/mb102-breadboard-power-supply-3-3v-5v) described as having four underside contacts and independent left and right 5 V / OFF / 3.3 V jumpers. It also models the master power switch. This is a named variant, not a pinout for every board sold as “MB102.” For example, the [Rajguru MB102 circuit diagram](https://www.rajguruelectronics.com/Product/1240/111225145243.pdf) depicts four two-contact connectors (J2–J5) on a different revision.
+
+The four contacts are logical names: `LEFT_POS`, `LEFT_GND`, `RIGHT_POS`, and `RIGHT_GND`. The catalog assigns no contact numbers, mounting row offsets, or fixed footprint. Match each contact on **your** module to its rail hole and enter all four hole IDs. The resolver rejects missing pins, duplicate holes, terminal-strip holes, and holes on a rail of the wrong polarity. It cannot confirm that the chosen holes match the physical spacing of a particular module; check the fit before powering it.
+
+The [source template](../examples/templates/shillehtek_mb102_4pin.bk.rb) reads four verified hole IDs from environment variables. For a board you have measured, set `MB102_LEFT_POS`, `MB102_LEFT_GND`, `MB102_RIGHT_POS`, and `MB102_RIGHT_GND`, then run `breadkit nets examples/templates/shillehtek_mb102_4pin.bk.rb`. The template selects 3.3 V on the left and 5 V on the right; change `left:` and `right:` to `:v5`, `:v3_3`, or `:off` to match the physical jumpers. Set `master: :off` when the switch is off. All three settings are required so an omitted jumper position cannot silently energize a rail.
+
+With `master: :on`, each selected side contributes its own voltage source between that side's positive and ground contacts. `:off` contributes no source to that positive rail. The ground contacts remain connected internally, including when either output or the master switch is off. If the breadboard has split rails, bridge each intended segment explicitly; the module energizes only the segment that holds its contact.
+
+The built-in drawing is a logical marker, not a to-scale body or a claim that the module fits over any four chosen holes. The ShillehTek manual lists 6.5–12 V for the center-positive barrel input and 5 V for USB input, with a claimed maximum of 700 mA per rail. The circuit model assumes the selected output voltage is available; it does not simulate regulator dropout, heat, USB supply limits, or simultaneous input selection. Verify the power source and load against the actual board and adapter before assembly.

data/docs/MCP.md

@@ -0,0 +1,44 @@
+# MCP server
+
+`breadkit-mcp` exposes read-only circuit inspection over the Model Context
+Protocol (MCP) stdio transport. It uses the [official Ruby MCP SDK](https://ruby.sdk.modelcontextprotocol.io/server/transports/).
+
+Start the server from a project directory:
+
+```sh
+breadkit-mcp
+```
+
+The current directory is the file root. Set it explicitly when your MCP client
+starts the server elsewhere:
+
+```sh
+breadkit-mcp --root /absolute/path/to/project
+```
+
+A client configuration that accepts `command` and `args` can use:
+
+```json
+{
+  "command": "breadkit-mcp",
+  "args": ["--root", "/absolute/path/to/project"]
+}
+```
+
+The server offers three tools:
+
+| Tool | Input | Result |
+| --- | --- | --- |
+| `breadkit_resolve` | `path` | Board and component summary, validity, and diagnostics. |
+| `breadkit_nets` | `path`, optional `state` | Electrical nets, members, holes, and constrained potentials. Use `state: "base"` for the default switch state. |
+| `breadkit_ir` | `path` | The resolved JSON IR. Requires a circuit without error diagnostics. |
+
+All project paths must remain inside the configured root, including symlink
+targets and referenced part or board definition files. Accepted circuit inputs are
+`.bk.yml`, `.bk.yaml`, `.bk.toml`, and `.json` IR. Ruby DSL files are not
+evaluated by this server. Tool failures return MCP `isError` results, and
+standard output contains only protocol messages.
+
+See the [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+for the tool protocol and the [stdio transport specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio)
+for message framing.

data/docs/RAKE.md

@@ -0,0 +1,19 @@
+# Check circuits with Rake
+
+Install Rake for your project and add an opt-in task to its `Rakefile`:
+
+```ruby
+require "breadkit/rake_task"
+
+Breadkit::RakeTask.new(:circuits, files: Dir["circuits/*.{bk.yml,bk.toml}"])
+task default: :circuits
+```
+
+Run `bundle exec rake circuits`. The task loads each listed file, verifies
+`breadkit.lock` when present, and fails on core resolution errors. It reports
+the first failing file and its diagnostics. The task does not run lint rules;
+run `bklint` separately when you need electrical and layout checks.
+
+Only files passed in `files:` are loaded. Ruby `.bk.rb` circuits execute Ruby
+code, so include them only when you trust their contents. YAML and TOML
+circuit files are parsed as data.