{"id":"b2e9887a-f14b-44bb-9cab-59f6dadd1288","slug":"vibread","kind":"mcp","name":"ViBread","summary":"","owner":"BarryTheShen","repoUrl":"https://github.com/BarryTheShen/ViBread","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-26T03:17:53.000Z","addedAt":"2026-10-21T21:59:07.233Z","logoUrl":"https://avatars.githubusercontent.com/u/125682613?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T00:13:13.336Z","sample":false,"url":"https://conduits.dev/tools/vibread","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ViBread — Mission Control for your breadboard\n\nViBread helps non-technical makers go from \"a lamp that turns on when it's dark\" to a working Arduino breadboard. You\ndescribe what the circuit should do; ViBread's agent designs it (parts from your kit, netlist, Arduino sketch), a\n**Go/No-Go poll** of independent checkers verifies it, LEGO-style numbered steps show how to build it on laptop and\nphone, and a **self-test over USB** checks the real build and says *where* it is wrong (\"Houston, we have a problem: D2\nreads LOW even with the button released — its leg shares row 17 with the GND jumper\").\n\n**New here? Read [HOW-IT-WORKS.md](HOW-IT-WORKS.md)** — what the app does, step by step, in plain words.\n\n**Try it without installing: [barrytheshen.github.io/ViBread](https://barrytheshen.github.io/ViBread/)**, a read-only\ndemo of one recorded project (Moon-Phase Lamp): the design chat, schematic, tests, checks and build steps, and Try it\nrunning the real sketch in your browser. No Arduino or sign-in needed. It is built with `npm run build:demo -w\n@vibread/web` from recorded server responses (`scripts/capture-demo.mjs` → `apps/web/public/demo-data/`).\n\n**Screenshots:** every main screen, from the brief to phone Build Mode, is in [docs/screenshots](docs/screenshots/README.md).\n\n![Try it: the real sketch running on a simulated Arduino; the room is dark, so the lamp shows a full moon](docs/screenshots/07-try-it.png)\n\nBuilt for the HackWashU Fall Build Challenge (Sep 25–27, 2026; theme \"Fly Me to the Moon\"). The full plan is in\n[PLAN.md](PLAN.md); research and hands-on library audits are in [research/](research/).\n\n## What's in the box\n\n| Console | What it checks | Built on |\n|---|---|---|\n| **EECOM** electrical | Typed ERC + Uno rule table (current per pin/total, LED resistor, floating button, PWM/I²C/SPI/serial pins, shorts, KiCad-style pin-type conflicts) at worst-case corners; ngspice cross-check | json-rules-engine, ngspice |\n| **GUIDO** firmware | The sketch compiles for the chosen board; flash/RAM budget; pin modes observed in simulation match the design | arduino-cli, avr8js |\n| **FIDO** simulation | An independent test author's scenarios pass against the exact binary, with lenient timing (open-ended windows plus 150 ms before / 300 ms after grace). Every intent clause must be tested; other coverage gaps (an output never asserted, an input never exercised, no power-on test) only warn, and failures the test review doesn't confirm are set aside | avr8js |\n| **FAO** assembly | A deterministic breadboard layout fits, and LVS proves the layout's nets equal the design's nets | our allocator + LVS |\n| **RETRO** review | A separate agent compares brief, design, sketch and results and votes GO/NO-GO | Claude |\n\nThen: numbered build steps with the USB plug state on every step (phone Build Mode polls the server), safe firmware\nbefore any wiring, a rail checkpoint, and a read-before-drive self-test whose telemetry is diagnosed against the design\n(rule table + a simulated single-fault dictionary). A \"Try it\" tab runs the real compiled sketch live in the browser.\nPhoto check (Claude vision) is advisory only.\n\nDerived results (layout, build steps and their pictures, schematic, check reports) carry the version of the code that made\nthem. When an update changes that code, the server re-derives existing missions' current and released revisions in the\nbackground after it starts (the old results stay on screen until the new ones are saved). The design, tests and chat are\nnever touched; a build in progress keeps its placement and wire colours, gets new steps drawn from that placement, and\ncontinues where it was (timeline note). The version is a fingerprint of golden outputs, so most pipeline changes are\npicked up without a manual bump; raise `DERIVATION_VERSION` in `packages/tools/src/pipeline.ts` for changes it can't see.\n\n### Export and import a project\n\nUse the mission’s ⋯ menu or the panel download menu to choose **Project file (.vibread)**. The single portable file keeps the mission brief, every design revision, chat history, build progress, wire-colour choices, inventory and hardware snapshot, plus any photos you attached or checked. Derived drawings, pictures and firmware are intentionally left out; when the file is opened on another ViBread server, the current design is checked again and older revisions are checked in the background.\n\nChoose **Import project** below **New mission** in the sidebar and select the `.vibread` file (you can also drop it anywhere in the window). Import creates a new mission owned by the signed-in user; it never transfers credentials, tokens, pairing links or account identifiers. The import screen stays busy while the current revision is checked, then opens the new mission.\n\n\nThe same mission is reachable from **iMessage** (\"CAPCOM\", via Photon Spectrum) and from **Claude Code** over MCP. There\nare no design permission modes: Claude can edit the design directly. **GO for build** is human-only (the web button or an\niMessage `GO`). Physical actions (flash, self-test, rewiring) still wait for a click at the bench; remote agents can only\nrequest them.\n\n## Install\n\n### Option A — Desktop app (recommended)\n\nDownload, double-click, done: no Node.js, npm or terminal, and no browser choice (the app has Chromium built in, so the\nUSB bench works the same on every OS). How it works inside: [HOW-IT-WORKS.md](HOW-IT-WORKS.md).\n\nEvery successful build of `main` is published as a new, numbered release (**ViBread desktop 0.1.N**); download the\nnewest from **[Releases → Latest](https://github.com/BarryTheShen/ViBread/releases/latest)**. Pushes build Linux and\nWindows; the macOS apps are built on request (Actions → *Desktop app* → *Run workflow* → tick *macOS*), and every\nrelease's notes link the newest macOS build.\n\n| OS | File in the latest release | First launch if unsigned-app warnings appear |\n|---|---|---|\n| Linux x64 | `ViBread-<version>-linux-amd64.deb` (recommended on Ubuntu/Debian, required for the full sandbox on Ubuntu 24.04+) or `ViBread-<version>-linux-x86_64.AppImage` (any distro) | Deb: `sudo apt install ./ViBread-*.deb`, then *ViBread* in the app menu. AppImage: `chmod +x ViBread-*.AppImage` then run it (needs FUSE's `fusermount3`, present on desktop distros; without FUSE run it with `APPIMAGE_EXTRACT_AND_RUN=1`) |\n| Windows 10/11 x64 | `ViBread-<version>-win-x64.exe` (installer) | SmartScreen: **More info → Run anyway** |\n| macOS (Apple silicon / Intel) | `ViBread-<version>-mac-arm64.dmg` / `ViBread-<version>-mac-x64.dmg` (in the newest release that has them — see the release notes) | Drag to Applications, open once, then **System Settings → Privacy & Security → Open Anyway** (or `xattr -dr com.apple.quarantine /Applications/ViBread.app`) |\n\n- **First launch** shows a setup window: it downloads the Arduino toolchain (arduino-cli 1.5.1 + AVR core 1.8.8 +\n  ArduinoJson 7.4.2, SHA-256 checked, ~150 MB) and builds the example missions — about 2–3 minutes, internet needed\n  once. Later launches start in ~10 s. The download is ~160–200 MB; installed size ~600 MB plus the toolchain.\n- **Upgrading on Windows:** run the new installer over the old version; it closes a running ViBread first. An upgrade\n  used to stop with *\"Failed to uninstall old application files\"* when another program (for example an antivirus\n  scan) held one of the ~16,000 old files; from 0.1.105 the installer installs over the old files instead. If an\n  upgrade still fails, uninstall ViBread in *Settings → Apps* (your missions and the toolchain in `%APPDATA%\\ViBread`\n  are kept), then install again.\n- **Chromium sandbox on Linux:** Ubuntu 23.10+ blocks unprivileged user namespaces (AppArmor), which Electron's\n  sandbox normally uses. The `.deb` installs the setuid `chrome-sandbox` helper, so the sandbox keeps working there. The\n  AppImage can't ship a setuid helper: its launcher tests `unshare -Ur true` and, when namespaces are blocked, starts\n  with `--no-sandbox` by itself, so it opens instead of failing with \"No usable sandbox\" (the window only ever loads\n  ViBread's own local server). For the full Chromium sandbox on Ubuntu 24.04+, use the `.deb`.\n- **USB on Linux:** add yourself to the serial group once and log out/in: `sudo usermod -aG dialout $USER` (Arch:\n  `uucp`). Then the bench's *Choose filtered USB port* picks the Arduino automatically (or asks when several are plugged in).\n- **Phones:** menu **ViBread → Show phone link / QR** (same Wi-Fi). Phones pair by scanning the QR code; other devices\n  on the Wi-Fi can't open your ViBread. Allow ViBread through the firewall when your OS asks (Windows/macOS prompt on\n  first phone connection; private networks only).\n- **AI agents:** the primary route is **Settings → Connect your Claude account**: ViBread runs pi-ai's Anthropic OAuth in\n  the server. Paste the code Claude shows, `code#state`, or the whole `localhost:53692/callback…` address; this also works\n  when the browser is on another computer. The other route is **Settings → Claude → Use an API key instead**. ViBread\n  checks that key with Anthropic before saving it, and stores either credential per user in the server database. No helper\n  program or `HOME`/`USERPROFILE` credential file is used. In the desktop menu, **ViBread → Set Anthropic API key…** sets\n  the server's fallback key in the OS credential store.\n- **Your data** lives in `~/.config/ViBread` (Linux), `%APPDATA%\\ViBread` (Windows), `~/Library/Application Support/ViBread`\n  (macOS): `data/` (missions), `toolchain/`, `logs/server.log`, `logs/setup.log`. Menu: *Open data folder*, *Open logs*,\n  *Reset example missions*.\n- **SPICE cross-check** needs [ngspice](https://ngspice.sourceforge.io/) installed (`sudo apt install ngspice` /\n  `brew install ngspice` / Windows: add `ngspice.exe` to `PATH`); without it EECOM reports SPICE as unavailable.\n\n### Option B — From source (developers)\n\nTested from a clean clone of this repository (install → toolchain → build → seed → `npm test` → app) on Linux x86_64.\n\n### 1. What you need\n\n| | Version | Check with | Notes |\n|---|---|---|---|\n| OS | macOS (Intel or Apple silicon), Linux x86_64/arm64, or Windows 10/11 x64 | — | The Arduino compiler is downloaded for your platform |\n| Node.js | **22.12 or newer** | `node -v` | https://nodejs.org or `nvm install 22` |\n| npm | **10 or newer** | `npm -v` | Upgrade with `npm install -g npm@11` |\n| git, tar | any | — | Preinstalled on macOS/Linux and Windows 10+ |\n| Browser | Chrome or Edge | — | Needed for the bench (Web Serial talks to the Arduino). Other screens work in any modern browser |\n| Disk / network | ~1.5 GB, internet for the first install | — | node_modules + Arduino toolchain |\n\nOptional: **ngspice** for the SPICE cross-check (`brew install ngspice` / `sudo apt install ngspice`), **Claude Code** to\ndrive ViBread over MCP.\n\n### 2. Install and run\n\n```bash\ngit clone https://github.com/BarryTheShen/ViBread.git\ncd ViBread\nnpm install               # runs postinstall for the isolated schematic runtime (packages/assembly/schematic-runtime);\n                         # rerun after git pull so new runtime dependencies such as elkjs are installed\nnpm run setup:toolchain   # ~1 min; arduino-cli 1.5.1 (SHA-256 pinned) + Arduino AVR core 1.8.8 + ArduinoJson 7.4.2 → .toolchain/ (any OS)\nnpm run build             # builds the web app into apps/web/dist (the server serves it)\nnpm run seed              # optional: the example missions (Moon-Phase Lamp, Knob Night-Light, Launch Control) plus one recorded real Claude run\ncp .env.example .env      # optional: add ANTHROPIC_API_KEY etc. (see Configuration)\nnpm start                 # → http://localhost:8787\n```\n\nOpen **http://localhost:8787**. Without a Claude credential, everything works except live Claude calls (the chat says Claude\nisn't connected): set the server fallback `ANTHROPIC_API_KEY`, or use Settings → **Claude** to connect your account or save\nyour own Anthropic API key.\n\nCheck the install: `npm test` (~30 s; compiles firmware, runs the simulator, the checks and the server tests) and\n`npm run typecheck`.\n\n### 3. Other devices and the bench\n\n- **Phone (Build Mode):** the server finds the first non-internal Wi-Fi IPv4 address when `PUBLIC_URL` is left unset; scan the QR\n  code in the workspace's Steps tab. Set `VIBREAD_PHONE_URL=http://<laptop-ip>:8787` if automatic discovery is not right.\n- **Bench (Arduino over USB):** open the bench on the laptop the board is plugged into, at `http://localhost:8787` (Web\n  Serial needs localhost or HTTPS). On a remote server, forward the port: `ssh -L 8787:<server>:8787 <host>`.\n- **Development mode** (hot reload): `npm run dev:server` (port 8787) and `npm run dev:web` (http://localhost:5173, proxies\n  the API to 8787).\n\n### 4. Troubleshooting\n\n| Problem | Fix |\n|---|---|\n| `npm install` complains about the engine or lockfile | Upgrade Node to 22.12+ and npm to 10+ |\n| Port 8787 is busy | `PORT=8788 npm start` |\n| \"Claude is not connected\" in the chat | Expected without a credential — set the server fallback `ANTHROPIC_API_KEY`, or connect an account or API key in Settings → **Claude** |\n| Schematic tab says the drawing isn't ready | Re-run `npm install` (its postinstall installs `packages/assembly/schematic-runtime`, including elkjs) |\n| Compile errors mentioning `arduino-cli` / missing core | Re-run `npm run setup:toolchain` |\n| Bench can't see the board | Use Chrome/Edge on `localhost`; try another USB cable (charge-only cables have no data); close the Arduino IDE serial monitor; on Linux add yourself to the `dialout` group |\n| Flashing from the browser fails | When the browser runs on the computer the board is plugged into (the desktop app, or `npm start` there), the bench's Step 2 offers **Flash with ViBread's uploader (avrdude)**: pick the port and the server uploads with its bundled arduino-cli, the same avrdude upload the Arduino IDE does. The uploader's lines go to Settings → Diagnostics. Otherwise copy the command under *Laptop fallback*, e.g. `.toolchain/bin/arduino-cli --config-file .toolchain/arduino/arduino-cli.yaml upload --fqbn arduino:avr:uno --port <port> --input-file <hex>` |\n| Start over with fresh demo data | Stop the server, `rm -rf data`, `npm run seed`, `npm start` |\n\n## Inventory, interface, and diagnostics\n\n- **Inventory:** type a list of parts or scan from the laptop camera, a phone, or an upload. The typed parser handles\n  parentheses, `N each`, `A & B`, and units. Scans have explicit upload and analysis failure states with **Retry**, and\n  Settings lets you edit part types.\n- **Chat:** the mission chat uses assistant-ui with MUI styling. Tool calls fold into grouped rows, Claude's questions are\n  answerable cards, and the chat supports stop/resume.\n- **Theme:** the light and dark palettes follow the system setting and use space cadet, cool gray, anti-flash white, and\n  red tokens.\n- **Debug logs:** the server writes redacted JSONL to `data/logs/server.jsonl` and `data/logs/missions/<missionId>.jsonl`.\n  Settings → **Diagnostics** shows the server or a selected mission log with area/level filters; browser errors are sent to\n  the server. Follow a log from the repository root with `node scripts/debug-log.mjs [missionId] --follow`.\n\n### Configuration (`.env` in the repo root, all optional)\n\n| Variable | Meaning |\n|---|---|\n| `PORT`, `HOST`, `PUBLIC_URL` | Listen address (default `0.0.0.0:8787`) and the public origin used in links, QR codes, OAuth metadata and the `claude mcp add` command |\n| `VIBREAD_PHONE_URL` | Phone/QR origin override; when unset, an HTTP localhost `PUBLIC_URL` uses the first non-internal LAN IPv4 address |\n| `VIBREAD_LAN_PAIRING=off` | Disable the single-operator LAN pairing guard (only on a trusted network) |\n| Tunnels (cloudflared/ngrok) | Treated as remote devices; `ssh -R`-style raw forwarding looks like the laptop itself, so use multi-user sign-in for any public tunnel |\n| `DATA_DIR` | SQLite database, artifacts and generated secrets (default `./data`, relative to the repo root) |\n| `ANTHROPIC_API_KEY` | Optional server fallback key for design, test author, RETRO, photo check, and scan calls. A user can instead connect a Claude account or save an API key in Settings → Claude. Without both a user credential and this fallback, live Claude calls are unavailable |\n| `ANTHROPIC_BASE_URL` | Anthropic API origin for every Claude call (a proxy or local bridge; default `https://api.anthropic.com`) |\n| `VIBREAD_MODEL`, `VIBREAD_FAST_MODEL` | Default `claude-opus-5-5`, `claude-sonnet-5` |\n| `VIBREAD_CLAUDE_PROTOCOL` | `managed` (default: pi-ai's per-model request protocol — for claude-opus-5-5 adaptive thinking, mid-conversation system messages and their beta headers) or `plain`. If Claude answers 400 to a managed feature, ViBread retries that request plain and stays plain for that model (logged in Diagnostics) |\n| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Google sign-in (callback `${PUBLIC_URL}/api/auth/callback/google`) |\n| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | GitHub sign-in (callback `${PUBLIC_URL}/api/auth/callback/github`). With Google or GitHub configured, single-operator mode (no sign-in) is turned off |\n| `BETTER_AUTH_SECRET`, `VIBREAD_APPROVAL_SECRET` | Generated and stored in `DATA_DIR` when unset |\n| `CAPCOM_PROVIDER` | `off` (default), `terminal` (local test chat), or `cloud` (iMessage) with `PHOTON_PROJECT_ID`, `PHOTON_PROJECT_SECRET`, `CAPCOM_NUMBER`. On the ViBread computer, Settings → iMessage can save the Photon project instead (it starts CAPCOM at once; the secret is never sent back to the browser) |\n| `VIBREAD_ARDUINO_CLI`, `VIBREAD_ARDUINO_CONFIG`, `VIBREAD_COMPILE_TIMEOUT_MS` | Override the toolchain location / compile timeout |\n| `VIBREAD_NO_STATIC=1` | Don't serve `apps/web/dist` |\n\n## Using it\n\n1. **Home** — describe the circuit and tap the parts you own.\n2. **Mission workspace** — Claude edits the design directly; grouped tool rows show its work, and question cards let you\n   answer clarifications. Stop/resume is available while a run is active. The side panel's **Show** menu lists its views\n   by stage, in build order: **1 Design** (Parts, Schematic, Code) · **2 Simulate** (Try it, Tests with each scenario's\n   replay, Checks) · **3 Build** (Build steps, Bench, Photo checks) · **4 Debug** (Bench results: the latest diagnosis\n   and everything the board reported). The view and design version are kept in the address (`?panel=…&rev=…`). The status\n   dots show EECOM · GUIDO · FIDO · FAO · RETRO. **GO for build** (you are the Flight Director) is a human action from the\n   web button or iMessage `GO`.\n   From the sidebar or the mission header's ⋯ menu, rename, duplicate, export, or delete a mission.\n3. **Build Mode on the phone** — scan the QR code in Build steps (`/b/<mission>`): one step at a time, focused picture,\n   exact holes, the USB plug state (the step where it changes says \"Plug the USB cable in now\" / \"Unplug the USB cable\n   now\"), tap the picture to zoom, **Done**, \"Check with camera\". A checkpoint's **Done** unlocks when its checks pass\n   on the laptop's Bench; **Skip checks and continue** moves on without them. After the inventory and the board-orientation steps comes\n   a bare-board check: plug in just the Arduino, connect, flash the safe firmware and check its power before anything\n   goes on the breadboard.\n4. **Bench** (the panel's Bench view, `/m/<mission>?panel=bench`; Chrome/Edge) — connect the board, flash safe\n   firmware, power checkpoint, self-test with on-screen prompts, diagnosis with the suspect holes highlighted, then flash\n   the app firmware with the light-sensor calibration. A build step's checkpoint opens it scoped to that step's tests;\n   the old `/m/<mission>/bench` address redirects here. \"Try without a board\" runs the same firmware in a simulated board,\n   with injectable wiring faults. Physical actions always wait for the click in this view.\n\nIf you have tested a design or board yourself and a safety gate still blocks progress, the web UI offers an explicit red\n**Override — I know what I'm doing** action for simulation-test, release, bench, and completion gates. It lists exactly\nwhich check will be bypassed, asks you to confirm that ViBread will not check it for you, and accepts an optional reason\n(up to 200 characters). Overrides never change the underlying verdicts: each release, bench acceptance, and completion\noverride is recorded in the mission timeline and shown as an override rather than a clean GO.\n\n### Connect your Claude account\n\nSettings → **Connect your Claude account** is the primary way to let your own Claude account power missions instead of\nViBread's key. ViBread runs the Claude sign-in itself (pi-ai's Anthropic OAuth, no helper program): open the claude.ai\nlink, approve, then paste the code Claude shows, `code#state`, or the address of the page that fails to load\n(`localhost:53692/callback?code=…`) into ViBread; that works when your browser is on a different machine than the\nserver. If your browser runs on the server machine, the sign-in finishes by itself (unless another program holds port\n53692 — then paste as well; the server log says so). You can connect an Anthropic API key\ninstead (`POST /api/connections/claude/key`). The credential is stored in ViBread's database for your user only (pi-ai\nrefreshes the sign-in when it expires); Disconnect removes it. When your credential can't be used, ViBread falls back to\nits server key. Note: Anthropic's terms restrict using Claude.ai login in third-party apps — see PLAN.md §9.\n\n### Claude Code (MCP) and other agents (A2A)\n\nSettings → **Connect Claude Code** mints a short-lived token and shows the command, e.g.\n\n```bash\nclaude mcp add --transport http vibread https://<public-host>/mcp --header \"Authorization: Bearer vb_…\"\n```\n\nScopes: `circuits:read`, `circuits:write`, `bench:request`. Without a header, Claude Code can also use OAuth 2.1 (Better\nAuth authorization server with protected-resource metadata, PKCE and client ID metadata documents). Tools include every\nViBread tool (checks, compile, simulation, layout, diagnosis…) plus `vibread_list_missions`, `vibread_create_mission`,\n`vibread_say`, `vibread_status`, `vibread_continue_task`. An A2A agent card is served at\n`/.well-known/agent-card.json` (endpoint `/a2a`, bearer auth).\n\n### iMessage (Photon Spectrum)\n\nSettings → **iMessage (CAPCOM)** shows a one-time code; text it to your CAPCOM number (with `CAPCOM_PROVIDER=terminal`, type it\nin the server's terminal chat). Once linked, CAPCOM texts you about **all** your missions, wherever they were started:\nClaude's questions (text + a poll of its choices; pick one or reply with your own answer — the first answer, laptop or phone,\nwins), design ready / NO-GO / a ViBread limit / a failed run, bench self-test results and fault alerts. The mission a text is\nabout becomes the one your replies go to (`mission` lists and switches). You can also text a brief, `status`, `GO` to start\nbuilding, and GO / NO-GO to bench approval polls. Settings has a test message, a switch per kind of notification, and opt-in\nquiet hours in your own time zone: notifications are held, never dropped, and arrive as one digest when they end; replies to\nyour texts always go through.\n\n## Supported circuits\n\nArduino Uno R3 or Nano (ATmega328P, 5 V, USB power), one breadboard (30 or 63 rows), ≤ 20 parts, ≤ 20 signal nets. Module\nlibrary: LED, resistor, push button, photoresistor, potentiometer, active and passive buzzer; other parts can be added as\ngeneric digital/analog modules (simulated with basic logic only, always labeled unverified). The simulator runs the exact\nbinary that gets flashed at instruction level with protocol-level part models: it validates logic, timing and pin\nconfiguration, not current, noise, brown-out or contact quality — the physical self-test covers those.\n\n## Repository layout\n\n```\napps/server        Express 5: auth, REST, UI-message chat stream, MCP /mcp, A2A /a2a, CAPCOM, mission machine, bench-request broker\napps/web           React 19 + Vite + Material UI + assistant-ui: workspace, Build Mode, bench (Web Serial), Try it, settings\npackages/core      Contracts: circuit IR (vibread.circuit/0.1), boards, breadboards, modules, scenarios, telemetry, results, services\npackages/tools     Tool registry + pi AgentTool/MCP adapters + physical bench-request gate\npackages/checks    EECOM + GUIDO rules and the ngspice cross-check\npackages/firmware  arduino-cli service, bench self-test firmware template (Eta + ArduinoJson), calibration injection\npackages/sim       avr8js ATmega328P simulator, device models, scenario runner, coverage (Node workers + browser)\npackages/assembly  Breadboard allocator, LVS, steps, SVG/PNG rendering; schematic via elkjs layout + a geometry check (isolated runtime)\npackages/bench     Self-test plan, NDJSON decoding, telemetry evaluation, diagnosis rules, fault catalog + fault dictionary\nfixtures           Golden designs with test suites and pre-built HEX\nscripts            Toolchain setup, golden seeding, debug-log CLI\n```\n\n## Libraries and licenses\n\nViBread's own code is MIT (see [LICENSE](LICENSE)). Main dependencies: pi-agent-core + pi-ai (MIT; in-process Claude\nagents and structured calls), AI SDK (`ai`, `@ai-sdk/react`, Apache-2.0; the web UI-message stream format), assistant-ui\n(MIT; chat rendering), Material UI (MIT), Better Auth and its MCP/OAuth plugins (MIT), Model Context Protocol SDK (MIT),\nA2A JS SDK (Apache-2.0), Photon `spectrum-ts` (MIT), Express (MIT), XState (MIT), Drizzle ORM (Apache-2.0),\nbetter-sqlite3 (MIT), elkjs (EPL-2.0, schematic layout; isolated in `packages/assembly/schematic-runtime`), json-rules-engine\n(ISC), avr8js (MIT), webserial-flasher (MIT), Eta (MIT), ArduinoJson (MIT, compiled into the bench firmware), yaml (ISC),\nzod (MIT), sharp (Apache-2.0).\n\nNotices: `@resvg/resvg-js` is MPL-2.0 and `elkjs` is EPL-2.0 (both used unmodified as libraries; elkjs sources:\nhttps://github.com/kieler/elkjs). `heif2jpeg` is MIT but statically bundles libheif and\nlibde265 (LGPL-3.0); their sources are available from their upstream projects. arduino-cli (GPL-3.0) and ngspice\n(BSD-3-Clause) are external tools invoked as separate programs and not redistributed in this repository; the Arduino AVR\ncore (LGPL) is installed by `setup:toolchain` and linked into sketches as Arduino libraries normally are.\n\n## Data and privacy\n\nMissions, designs, chat history and bench telemetry are stored in SQLite under `DATA_DIR`. Agent calls send the brief,\nthe design and (for the photo check) the uploaded photo to Anthropic's API; see Anthropic's commercial data-retention\nterms. Photos are resized server-side and stored with the mission. Nothing is sent anywhere else, except iMessage traffic\nthrough Photon when CAPCOM is enabled.\n\n## How this was built\n\nEverything in this repository was written during the event (Sep 25–27, 2026). Planning, research and code were produced\nwith AI coding agents under the team's direction: Claude Opus 5.5 (planning, integration, review, and the agent,\nserver-core and web-workspace slices) and GPT-5.6 Luna (research and the remaining package slices). The runtime design\nagent runs on pi inside the server; no external sign-in helper is needed. Tester GitHub issues #1–#14 drove an issue-by-issue QA\nloop before the final docs pass. Libraries are used through their public APIs; no code was copied from other projects.\n"}