# AGENTS.md — Fusible Agent Guide
> **The fuse for your firmware.** Fusible is an electronic linter and tscircuit project manager written in Rust. It reads the Circuit JSON generated by [tscircuit](https://tscircuit.com), checks physical and electrical design rules, and enforces a strict contract: **when a rule fails, the fuse blows (exit code 1)** — halting artifact exports and firmware code generation before defective designs can reach fabrication.
---
## 1. Project Philosophy & Invariants
1. **The Fuse Contract (Exit Codes)**:
- `0` — **Fuse intact**: circuit is electrically sound, rules pass, command succeeded.
- `1` — **Fuse blown**: one or more electrical violations detected (`unconnected_net`, `ghost_net`, `malformed_element`, future DRC/pin-mux). Artifact exports and codegen are blocked.
- `2` — **Tool error**: IO failure, unreadable/malformed JSON, runner missing, or CLI syntax error.
2. **Fail-Closed Rule Design**: If a net or component cannot be definitively proven connected, report it. Never assume floating traces or unlinked ports are valid without explicit net aliases.
3. **Rust Core / External Toolchain Separation**:
- The core parser (`src/parser/`), netlist IR (`src/netlist/`), and rules engine (`src/linter/`) are 100% pure Rust with zero C-system dependencies.
- External EDA converters (Gerber, SVG, STEP, KiCad) and the dev server are orchestrated through `src/tscircuit/` via local `tsci`, `bun`, `npx`, or `npm`.
- If `tscircuit` is not installed on the host machine, Fusible continues to function gracefully by leveraging existing `circuit.json` or providing `fusible doctor`.
---
## 2. Directory Structure
```
Fusible/
├── Cargo.toml # Rust package manifest (version, dependencies)
├── CHANGELOG.md # Keep a Changelog (Added, Changed, Fixed, Removed)
├── facile.toml # Facile Studio suite catalog discovery
├── mise.toml # mise toolchain config (lefthook, bun)
├── lefthook.yml # Conventional commit hooks
├── README.md # User-facing documentation & quickstart
├── ROADMAP.md # Feature phases (1: MVP, 1.1: Manifest/CLI, 2: MCU/Embassy)
├── GLOSSARY.md # Domain terminology (Circuit JSON, Netlist, Fuse, etc.)
├── examples/ # Sample Circuit JSON files for testing
├── tests/ # Integration test suites (exit codes, subcommands)
└── src/
├── main.rs # CLI entry point & exit code translation
├── cli.rs # Clap command definitions (check, dev, build, export, init, doctor)
├── linter.rs # Linter engine, Rule trait, FuseBlown diagnostic
├── parser.rs # Serde Circuit JSON parser & span tracking
├── commands/ # Subcommand execution pipelines
│ ├── check.rs # Electrical check + TSX on-the-fly compilation & fallback
│ ├── dev.rs # Live interactive viewer (tsci dev)
│ ├── export.rs # Fuse-gated export subsystem (presets: fab, cad, docs, all)
│ ├── build.rs # Full build pipeline
│ ├── doctor.rs # Toolchain health inspection & runner auto-setup
│ ├── init.rs # fusible.yml scaffolding
│ └── target.rs # Path resolution from manifest & conventions
├── config/ # fusible.yml manifest parser & discovery
├── linter/ # Rules implementation
│ ├── diagnostics.rs # miette diagnostics for violations
│ └── rules/ # Individual rules (unconnected_net, ghost_net, malformed_element)
├── netlist/ # Bipartite graph IR of nets, components, ports, and traces
└── tscircuit/ # Runner discovery (Local, Global, Bun, Npx, Npm) & process control
```
---
## 3. Standard Development Workflow
Before submitting any change, run:
```sh
# 1. Format check
cargo fmt --all -- --check
# 2. Clippy lint (zero warnings permitted)
cargo clippy --all-targets -- -D warnings
# 3. Test suite
cargo test --locked
# 4. Suite quality check (if filet is installed)
filet check .
```
Commit messages MUST adhere to [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` new feature or CLI command
- `fix:` bug fix or rule correction
- `chore:` release, dependencies, toolchain updates
- `docs:` documentation or comments
---
## 4. Fusible CLI Commands Reference
- `fusible check [FILE] [--mcu <MCU>]`: Runs the electrical linter on Circuit JSON or TSX file. Falls back to cached `dist/circuit.json` if runner is absent.
- `fusible dev [FILE] [-p <PORT>]`: Launches interactive hot-reloading webview.
- `fusible export [FILE] [--preset <PRESET>] [-f <FORMAT>] [-o <PATH>]`:
- **Fuse-gated**: Validates rules before creating any files.
- `--preset fab`: Exports `gerbers.zip` and `circuit.json` into `dist/fab/`.
- `--preset cad`: Exports `kicad.zip` and `board.step` into `dist/cad/`.
- `--preset docs`: Exports `schematic.svg`, `pcb.svg`, and `schematic.pdf` into `dist/docs/`.
- `--preset all`: Runs all three presets.
- `-f <FORMAT>`: Direct export (`gerbers`, `pcb-svg`, `step`, `glb`, `kicad_zip`, etc.).
- `--skip-lint`: Bypasses electrical rule checking (for drafts only).
- `fusible doctor [--install]`: Inspects bun/node/npm/tsci toolchains and optionally provisions `tscircuit`.
- `fusible init [--name <NAME>]`: Generates a clean `fusible.yml` project manifest.