harmoniqs · aarontrowbridge · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/README.md b/README.md
@@ -1,63 +1,108 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="packages/extension/media/amico-tab-dark.svg">
-  <img alt="Amicode" src="packages/extension/media/amico-tab-light.svg" width="96">
+  <source media="(prefers-color-scheme: dark)" srcset="packages/extension/media/amico-face-dark.svg">
+  <img alt="Amicode" src="packages/extension/media/amico-face-light.svg" width="96">
 </picture>
 
 # Amicode
 
-### Quantum optimal control, driven by conversation.
+### Open autonomous research, starting with quantum control.
 
-Describe the gate you want in plain language. Amicode designs the pulse, runs the
-solve, and shows you the result — without leaving your editor.
+Your vaults, your fleet, your devices, your pulses — composed by conversation.
 
 <sub>A VS Code extension · built on [Piccolo.jl](https://github.com/harmoniqs/Piccolo.jl) · chat harness vendored from [opencode](https://github.com/sst/opencode)</sub>
 
 </div>
 
 ---
 
-Amicode turns a natural-language description of a control problem into an
-LLM-authored Julia optimization, runs it, and streams the result back into native
-editor panels. The physics, the solver idioms, and your lab's accumulated
-knowledge all ride along as context — so the script it writes is correct by
-construction, not by luck.
+Amicode is an **open autonomous research studio** that lives in your editor.
 
-**This repo is the whole product**: the VS Code extension (`packages/extension`),
-the `amico` / `amico-run` CLI (`packages/amico-run`), and the public skill
-library (`packages/extension/skills/`) — skills are product content, versioned
-with the extension and bundled into every vsix. Additional skills load from your
-own Armonia vault mounts (they are never shipped), and package skills ride their
-Julia repos behind entitlements. (The old `amico-plugin` repo is retired; the
-skill library lives here now.)
+Describe what you want in plain language — a gate, a state preparation, a calibration sweep — and Amicode designs the pulse, runs the solve, and shows you the result. Every run is captured, every pulse versioned for warm-start, and every session distilled into durable knowledge. The loop gets smarter as you use it.
 
-## What it does
+We start with **quantum control** because it is the hardest physical system to prove the loop on. If the studio works here — arbitrary Hamiltonians, hard constraints, hardware in the loop — it generalizes to any physical system you can model. Bring your own Hamiltonian; the loop is the same. That's **physical intelligence**: not one device or platform, but a composable way to do experimental science.
 
-**Conversational solves.** Ask for a gate or a state preparation; Amicode writes a
-self-contained Piccolo script, runs the Ipopt solve, and captures the result. No
-boilerplate, no parameter-guessing.
+**This repo is the whole product:** the VS Code extension (`packages/extension`), the `amico` / `amico-run` CLI (`packages/amico-run`), and the public skill library (`packages/extension/skills/`) — skills are product content, versioned with the extension and bundled into every vsix. Additional skills load from your own vault mounts (never shipped), and package skills ride their Julia repos behind entitlements. (The old `amico-plugin` repo is retired; the skill library lives here now.)
 
-**Physics that ships with the tool.** Platform references for neutral-atom Rydberg,
-transmon, fluxonium, trapped-ion, and bosonic systems load on demand — the
-Hamiltonians, drive conventions, and construction patterns are inlined into each
-script so it stands on its own.
+## The studio
 
-**Your knowledge, mounted.** Amicode reads your **Armonia** — the stack of vaults
-you mount (personal, team, public). Notes, specs, experiment history, and your
-pulse catalog become first-class context the assistant plans against.
+**The workspace is what you edit. `~/.amico` is what the system manages. Amicode is the lens.**
 
-**A live run inspector.** Watch a solve converge in real time: overlaid pulse
-plots, fidelity and constraint-violation traces, per-run metrics. Every run is
-captured and revisitable.
+Most of what used to clutter the workspace is not working material but state — visible only because a raw file tree was the only lens. Amicode replaces the tree with native surfaces:
 
-**A pulse catalog.** A versioned, warm-startable library of your best pulses —
-retrieve the incumbent for a `(platform, gate)`, warm-start from it, and promote a
-new best when you beat it.
+| What the system manages | Where you see it |
+|---|---|
+| Vaults (`~/.amico/vaults/`) — notes, specs, experiment history | Vault tree + Armonia view |
+| Runs (`~/.amico/runs/`) — per-solve capture | Run Inspector |
+| Pulse catalog — versioned warm-start memory | Catalog view |
+| Devices + calibration (`~/.amico/amicode/devices/`) | Device Inspector |
+| Fleet + sessions — sync, locks, traces | Healthcheck, status bar, Learn |
 
-**Straight to hardware.** Drive real RFSoC devices through the QICK backend, or run
-the *entire* closed loop against a pure-Julia mock with zero hardware for
-development and CI.
+The extension renders managed state semantically instead of exposing it as folders. The underlying files stay on disk and stay yours.
+
+## What you get
+
+### Open autonomous research
+
+Amico, your research copilot, turns plain language into a self-contained Julia optimization, runs it, and streams the result back into native panels. Physics, solver idioms, and your lab's accumulated knowledge ride along as context — so the script it writes is correct by construction, not by luck. A short guided exchange settles anything it needs (levels, drive bounds, constraints) before committing to code. Every run is captured to disk and revisitable; when you beat a previous best, the catalog promotes and the next solve warm-starts from your last good answer.
+
+### Open quantum intelligence
+
+The physics ships with the tool. Platform references for **neutral-atom Rydberg**, **transmon**, **fluxonium**, **trapped-ion**, and **bosonic** systems load on demand — Hamiltonians, drive conventions, and construction patterns are inlined into each script so it stands alone. You never hand the assistant a Hamiltonian; naming the platform is enough. Searched papers, ingested notes, and your own experiment history plan alongside the physics.
+
+### Vaults — your knowledge, mounted
+
+Amicode reads your **vaults** — the stack you mount under `~/.amico/vaults/` (personal, team, project). Notes, specs, experiment history, and your pulse catalog become first-class context the assistant plans against. Armonia is one vault in that set — your personal research memory. Vaults layer by scope and by `visibility` (`local` → `team` → `public`); dream-promotion carries provenance so every insight traces to its source.
+
+### Fleet management — one logical studio across machines
+
+Your machines form one logical studio. Vault mounts sync via `armonia-sync-once` (launchd, every 15 min); the chat database stays canonical via an SSH mesh; WIP follows you between hosts with `leave`/`arrive`. No second writer ever touches the same SQLite file, no live `.git` is file-synced — the invariants are enforced, not assumed. Check it with `/fleet`; the skill is the playbook. Solo still works fully offline — the fleet simply means you never have to choose which machine holds the truth.
+
+### Open system management — from pulse to device
+
+The extension manages the system around the solve, not just the solve itself. Lab profiles (`lab.toml`), device calibration graphs, and run capture are all rendered natively instead of buried in config files. You see system state where you act on it.
+
+### Straight to hardware
+
+Drive real RFSoC devices through the QICK backend, or run the *entire* closed loop against a pure-Julia mock with zero hardware for development and CI.
+
+## How it scales
+
+```
+solo ──────────► team ──────────► fleet
+
+personal vault   + team / project    + SSH mesh, canonical DB,
+local runs        vault mounts         WIP-sync, device locks
+catalog           shared catalog       shared catalog, warm-starts
+                  visibility-gated     every run feeds the next
+                  dream-promotion
+```
+
+**Solo** — personal vault, local runs, versioned catalog. Works fully offline.
+
+**Team** — mount team and project vaults alongside your personal one. Vaults layer with `local | team | public` visibility; promotion to the team vault is a PR with provenance, not a copy-paste. Two researchers never clobber: one-file-per-note, a computed catalog index, per-session result files, and device locks make concurrent work safe by construction.
+
+**Fleet** — the mesh above. One canonical chat database, vault sync on a timer, WIP-sync across hosts. The same invariants that make team-safe make fleet-safe. Every run — whoever ran it, wherever — feeds the same knowledge base, so new work starts from the best prior answer.
+
+## Skills are the product
+
+Skills are not configuration — they are the capability surface. The **37 public skills** in `packages/extension/skills/` ship in the vsix, versioned with the product. Additional skills load from your own vault mounts and from co-located Julia packages behind entitlements.
+
+| Surface | What it covers |
+|---|---|
+| Physics | `transmon`, `fluxonium`, `atoms` (Rydberg), `bosonic`, `ions` — Hamiltonians, drives, construction patterns |
+| Lab + catalog + vault | `amico-lab`, `amico-catalog`, `amico-vault`, `amico-strategy`, `amico-schema-check` |
+| Analysis + synthesis | `analyze`, `structural-analysis`, `hypothesis-review`, `dream-reflect` |
+| System | `fleet`, `setup`, `solve`, `simulate`, `warm-start`, `constraints`, `objectives` |
+| Delivery | `demo`, `pasqal`, `plot`, `compose`, `multistart` |
+| Engineering | `debugging`, `tdd`, `verification`, `brainstorming`, `deliberate`, `grill-me`, `report-a-bug` |
+
+The extension stages the union of the public bundle and your vault mounts at startup; mount presence is the eligibility proof.
+
+## Physical intelligence
+
+Quantum control is the first domain, not the ceiling. The studio's loop — *describe → author a self-contained optimization → run → capture → distill → warm-start the next run* — does not care what the Hamiltonian is, only that you can write it down. If you can model the system, the same vault, the same catalog, the same fleet carries the work. That's why we lead with the hardest physical system: if the loop is trustworthy here, it composes outward.
 
 ## Hardware — QICK / RFSoC
 
@@ -103,6 +148,8 @@ Open the Amicode panel and paste:
 > leakage to |2⟩). Then run the optimized pulse through the IntonatoQICK mock
 > backend, read out the populations, and plot both the pulse and the readout.
 
+This one prompt exercises the whole studio: it names a platform, a target, a constraint, and a hardware step — chat to physics skill to solve to mock readout to plot — without you writing the Piccolo API, the Hamiltonian, or the QICK verbs. Swap `transmon` for your own system and the loop is the same.
+
 ## Open core
 
 The extension and its platform skills are open. **Entitled builds** add

diff --git a/packages/extension/README.md b/packages/extension/README.md
@@ -1,34 +1,36 @@
 # Amicode
 
-### Quantum optimal control, driven by conversation.
+### Open autonomous research, starting with quantum control.
 
-Describe the gate you want in plain language. Amicode designs the pulse, runs the
-solve, and shows you the result — without leaving your editor.
+Your vaults, your fleet, your devices, your pulses — composed by conversation.
 
-Amicode turns a natural-language description of a control problem into an
-LLM-authored [Piccolo.jl](https://github.com/harmoniqs/Piccolo.jl) (Julia)
-optimization, runs it, and streams the result back into native VS Code panels.
-The physics, the solver idioms, and your lab's accumulated knowledge ride along
-as context — so the script it writes is correct by construction, not by luck.
+Amicode is an **open autonomous research studio** in VS Code. Describe what you want — a gate, a state preparation, a calibration sweep — and it designs the pulse, runs the solve, and shows you the result. Every run is captured, every pulse versioned for warm-start, and every session distilled into durable knowledge. We start with quantum control — the hardest physical system to prove the loop on — and generalize to any physical system you can model.
 
 ## What you get
 
-- **Chat-driven pulse design** — an in-editor copilot (Amico) that authors and
-  runs the Julia optimization for the gate or state you describe.
-- **Live Run Inspector** — watch the solve converge in a native panel: objective,
-  constraints, and the resulting pulse.
-- **Managed Julia toolchain** — first run offers to install Julia (via juliaup),
-  pin the right version, and provision the Piccolo environment for you.
-- **A personal vault** — your systems, pulses, and problems are remembered across
-  sessions, stored locally under `~/.amico`.
+- **Open autonomous research** — Amico, your copilot, authors a self-contained [Piccolo.jl](https://github.com/harmoniqs/Piccolo.jl) optimization from plain language, runs it, and streams the result to native panels. A short guided exchange settles parameters before code is committed. You can stop a solve in flight with **Amicode: Stop current solve**.
+- **Open system management, not just a chat panel** — the workspace is what you edit; `~/.amico` is what the system manages (vaults, runs, catalog, devices). Amicode is the lens: Vault tree, Run Inspector, Catalog, and Device Inspector render managed state semantically instead of as file trees.
+- **Vaults — your knowledge, mounted** — personal + team + project vaults stacked under `~/.amico/vaults/` (your notes, specs, experiment history, pulse catalog) become first-class context the assistant plans against. Works fully offline; scales to a team via vault mounts with `local | team | public` visibility and PR-based promotion.
+- **Fleet management — one logical studio across machines** — vault sync, canonical chat DB, and WIP that follows you between hosts over an SSH mesh. Solo, team, and fleet share the same invariants: one-file-per-note, a computed catalog index, per-session captures, and device locks.
+- **Live execution + versioned memory** — the **Run Inspector** overlays pulse plots and traces fidelity and constraint violation as they fall; the **pulse catalog** keeps a warm-startable, versioned library of your best pulses and promotes when you beat the incumbent.
+- **Straight to hardware** — drive real RFSoC boards via [IntonatoQICK.jl](https://github.com/harmoniqs/IntonatoQICK.jl) over a coarse three-verb boundary (`upload_pulse!` / `trigger!` / `readout`), or run the *entire* closed loop against a pure-Julia mock with zero hardware for dev and CI. Same script, mock or metal.
+- **Physics that ships with the tool** — platform references for **Rydberg**, **transmon**, **fluxonium**, **trapped-ion**, and **bosonic** systems inline the Hamiltonians and drive conventions into each script so it stands alone.
+- **Skills are the product** — 37 public skills ship in the vsix, versioned with the product; your own vault mounts and Julia-package skills layer on top behind entitlements.
+
+<sub>Full studio tour, hardware docs, and the skill index → [github.com/harmoniqs/amicode](https://github.com/harmoniqs/amicode)</sub>
+
+## Try it
+
+Open the Amicode panel and paste:
+
+> Design a minimum-time single-qubit X gate for a transmon (3 levels, penalize leakage to |2⟩). Then run the optimized pulse through the IntonatoQICK mock backend, read out the populations, and plot both the pulse and the readout.
 
 ## Requirements
 
 - An LLM provider configured for the chat engine.
 - Julia — Amicode manages the install on first run; nothing to set up by hand.
 
-Run **Amicode: Healthcheck** from the Command Palette any time to verify your
-setup (Julia environment, chat server, and provider).
+Run **Amicode: Healthcheck** from the Command Palette any time to verify your setup (Julia environment, chat server, and provider).
 
 ---
 

diff --git a/packages/extension/media/amico-face-dark.svg b/packages/extension/media/amico-face-dark.svg