loadout-ai 0.7.0 → 0.9.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./docs/assets/loadout-workflow.png" alt="Loadout discovers skills, tools, and MCP servers, keeps them in a screened library, matches an active set to each project, and manages them across AI coding agents." width="960">
+  <img src="./docs/assets/loadout-discover-activate.webp" alt="Loadout discovers agent skills, tools, and MCP servers; screens and pins them; activates the right set for a repository; and lets users preview or roll back every change." width="960">
 </p>
 
 <h1 align="center">Loadout</h1>
@@ -8,8 +8,9 @@
 
 <p align="center">
   <strong>The package manager for your AI coding setup.</strong><br>
-  Install skills across 12 agents. Route each task to the right model.<br>
-  Hand work between Claude Code and Codex. Undo any of it.
+  Find skills worth having, activate the right ones per project,<br>
+  install them across 12 agents, hand work from Claude Code to Codex,<br>
+  and undo any of it.
 </p>
 
 <p align="center">
@@ -25,43 +26,52 @@
   <a href="#what-it-looks-like">See it</a> ·
   <a href="#install">Install</a> ·
   <a href="#use-it-from-inside-your-agent">Use it in your agent</a> ·
-  <a href="#working-across-two-agents">Two agents</a> ·
+  <a href="#passing-work-between-two-agents">Two agents</a> ·
   <a href="#why-loadout">Why</a> ·
-  <a href="#trust-and-limits">Trust</a> ·
   <a href="#command-reference">Commands</a>
 </p>
 
 ## What it looks like
 
 ```console
-$ loadout status
-Loadout — grade A: Healthy and up to date
-
-✓ Claude Code
-  ~/.claude/skills
-  582 items | supports: skill, command, agent, mcp, plugin, root
-✓ Codex
-  ~/.agents/skills
-  83 items | supports: skill, command, agent, mcp, plugin, root
-
-$ loadout route implement the payment webhook handler
-Phase:    implement
-Tier:     Standard (balanced)
-Models:   Claude Sonnet 5 ($3/$15)
-          GPT-5.6 Terra ($2/$12)
-Agents:   claude-code, codex
-Why:      Implementation is high-volume; standard models score within 5% of frontier
-
-Conserve: drop to fast tier (GPT-5.6 Luna at $0.2/$1.2)
-          May need more iterations on complex logic; fine for CRUD and boilerplate
-
-Hand off:
-  loadout handoff send codex 'implement the payment webhook handler'
+$ loadout doctor
+loadout doctor — HEALTHY
+
+Platform:   darwin
+State:      ~/.loadout ✓ writable
+Agents:     3 detected, 9 available
+
+DETECTED AGENTS
+  ✓ Claude Code
+    ~/.claude/skills
+    43 skills | supports: skill, command, agent, mcp, plugin, root
+  ✓ Codex
+    ~/.agents/skills
+    30 skills | supports: skill, command, agent, mcp, plugin, root
+
+$ loadout recommend --project .
+Project: checkout-service
+Detected: TypeScript, Zod, Vitest, next.js, react
+
+Rule-based project suggestions:
+  superpowers [high, skill library] — Useful engineering planning, testing, and review workflows.
+  context7 [high, skill library] — Current library documentation helps agents avoid outdated APIs.
+  ui-ux-pro-max [high, skill library] — Frontend framework detected: next.js, react.
+  playwright-mcp [medium, MCP/runtime setup] — Browser verification may help test the detected frontend.
 ```
 
-Three things most agent tools do not do: it knows which agents you actually have,
-it prices the tradeoff before you spend the tokens, and every mutating command
-previews first and snapshots before it writes.
+It reads your repository rather than a config file, knows which agents you
+actually have, and previews and snapshots every write before it touches them.
+
+### Demo
+
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=opNqJKX7xMw">
+    <img src="https://img.youtube.com/vi/opNqJKX7xMw/maxresdefault.jpg" alt="Watch the 72-second Loadout demo" width="880">
+  </a>
+</p>
+
+**[Watch the 72-second Loadout demo on YouTube](https://www.youtube.com/watch?v=opNqJKX7xMw).**
 
 ## Install
 
@@ -76,45 +86,85 @@ The second command detects your agents and previews the 30-skill Stable loadout.
 Nothing changes until you approve it. If anything goes wrong, start with the
 [user test guide](./docs/USER_TEST_GUIDE.md).
 
-For a reproducible install, pin the release: `npm install --global loadout-ai@0.7.0`.
+For a reproducible install, pin the release: `npm install --global loadout-ai@0.9.0`.
 
 ## Use it from inside your agent
 
-A CLI you have to leave your agent to run is a context switch. Loadout ships its
-own skill so you do not have to:
+A CLI you have to leave your agent to run is a context switch. Loadout ships two
+skills so you do not have to: one for agent handoffs and one for choosing a
+focused skill set for the current repository.
 
 ```bash
-loadout skills install loadout-router --yes
+loadout skills install loadout-handoff --yes
+loadout skills install loadout-curator --yes
 ```
 
 Start a new agent session and just ask, in the conversation you are already in:
 
-> _"Which model should I use to refactor this auth module?"_
-> _"I'm running low on usage — what should I switch to?"_
 > _"Hand the test writing to Codex."_
+> _"What did Codex leave for me?"_
+> _"Which skills should be active for this repo?"_
 
-The skill teaches your agent to call `loadout route` and `loadout handoff` and act
-on the results. It wraps the CLI rather than embedding a copy of the model table,
-so pricing and model coverage update when Loadout updates instead of going stale
-in a markdown file.
+The skills teach your agent to call `loadout` and act on the results, so it
+checks its own inbox at the start of a session and can pass work to your other
+agent without you relaying it by hand.
 
 `loadout skills list` shows what ships with Loadout and what is already installed.
 
-## Working across two agents
+## Passing work between two agents
+
+<p align="center">
+  <img src="./docs/assets/loadout-handoff-coordinate.webp" alt="Claude Code and Codex use Loadout in two ways: durable task handoffs between sessions, and structured coordination for contracts, file ownership, decisions, acknowledgements, and an audit trail." width="960">
+</p>
 
 If you pay for both Claude and a ChatGPT plan, the two agents cannot see each
 other. Loadout gives them a shared, append-only task log:
 
 ```bash
-loadout handoff init
-loadout handoff send codex "write unit tests for auth" --context "see src/auth.ts"
-loadout handoff pickup --yes
+loadout handoff codex "write unit tests for auth" --context "see src/auth.ts"
+```
+
+That is the whole thing. The first send creates the log and adds a short managed
+block to `CLAUDE.md` and `AGENTS.md` telling each agent to check its inbox at the
+start of a session. Only the text between the `loadout:handoff` markers is
+managed; the rest of your file is left alone.
+
+```bash
+loadout handoff codex      # what is waiting for codex
+loadout handoff            # everything pending, both directions
+loadout handoff --done 4f2a1c
+```
+
+### Make Claude Code and Codex coordinate live (beta)
+
+Live coordination adds file ownership, versioned contracts, decisions, and
+acknowledgements over a shared project event stream — not a merged context
+window. See the [live coordination guide](./docs/LIVE_COLLABORATION.md).
+
+```bash
+loadout coord own claude-code src/api
+loadout coord contract checkout-api --agent claude-code \
+  --body "POST /api/checkout -> 201 { id: string }"
+loadout coord snapshot codex            # what codex needs to know
+loadout coord replay                    # full timeline as a story
 ```
 
-`pickup` writes a small managed block into `CLAUDE.md` and `AGENTS.md` telling each
-agent to check `loadout handoff inbox <agent>` at the start of a session. Only the
-text between the `loadout:handoff` markers is managed; the rest of your file is left
-alone, and re-running replaces that block instead of duplicating it.
+`loadout serve` exposes the same operations as MCP tools for both hosts.
+The optional provider bridge (`loadout coord agents bridge`) resumes sessions
+and delivers events at safe turn boundaries — never mid-turn.
+
+Start a bounded design discussion to have both agents challenge an approach
+before either writes code. Two rounds plus synthesis = five provider turns:
+
+```bash
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --agents claude-code,codex --rounds 2 --max-turns 5
+```
+
+Each response is explicitly public, linked to the previous response, and saved
+in the project audit trail. The discussion prompt forbids edits and tool use;
+review the final decision, then choose whether to implement it. Existing
+sessions work with `--sessions claude-code:<id> codex:<id>`.
 
 ## How it works
 
@@ -146,13 +196,10 @@ Loadout installed 4 repositories for 3 agent(s). Snapshot: <snapshot-id>
 $ loadout rollback
 Restored snapshot <snapshot-id>
 
-$ loadout route design the authentication system
-Phase:    plan
-Tier:     Frontier (deep reasoning)
-Models:   Claude Opus 5 ($5/$25)
-          GPT-5.6 Sol ($5/$30)
-Agents:   claude-code
-Why:      Architecture and decomposition need deep reasoning to avoid costly rework
+$ loadout handoff codex "write tests for the auth module" --context "zod schemas exist"
+  created .handoff/
+  told codex to check its inbox
+Sent to codex: write tests for the auth module
 
 $ loadout doctor
 loadout doctor — HEALTHY
@@ -180,11 +227,15 @@ coding agents without making you rebuild the setup for every agent and every pro
 Most extension tools begin with a repo you already know. Loadout begins one step
 earlier: **what is actually worth knowing?** It stays with you after installation.
 
+Some tools distribute agent configuration. Others share memory or coordinate
+running agents. Loadout connects the whole lifecycle: discover and inspect what is
+worth using, activate it reversibly across agents, then hand work off or coordinate
+structured project facts when Claude Code and Codex work together.
+
 Everything on this page is enforced. `docs/evidence/readme-claims.json` records
 each material claim with the code or command that proves it, and CI fails the
 build when the README and the implementation disagree — including the pinned
-version in the install line above. A README that cannot drift is a strange thing
-to build, and it is the reason the rest of this page is worth believing.
+version in the install line above.
 
 Loadout watches a much wider catalog than it activates. You can keep thousands of
 technically screened skill copies in the disabled Maximum library, discover new projects as
@@ -204,84 +255,26 @@ Loadout is local, open source, and preview-first. It does not need an LLM API ke
 to manage skills. MCP servers and executable tools stay behind their own explicit
 setup and permission steps.
 
-### Demo
-
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=opNqJKX7xMw">
-    <img src="https://img.youtube.com/vi/opNqJKX7xMw/maxresdefault.jpg" alt="Watch the 72-second Loadout demo" width="880">
-  </a>
-</p>
-
-**[Watch the 72-second Loadout demo on YouTube](https://www.youtube.com/watch?v=opNqJKX7xMw).**
-It shows the real CLI product, including profiles, project-aware selection,
-discovery, explicit integrations, and snapshot-backed rollback. The exact
-[recording and voiceover script](./docs/DEMO_SCRIPT.md) is public.
-
-The [end-to-end acceptance guide](./docs/USER_TEST_GUIDE.md) contains the commands
-you can run yourself.
-
 ## Stable workflow
 
 ### Stable: install the essentials and start building
 
 Stable is the recommended daily driver: **30 selected skill directories from four
-pinned public sources**, installed into each agent you choose. It covers planning,
-implementation, debugging, testing, documentation, code review, frontend work,
-performance, Git, shipping, and more without turning every discovered skill on.
-
-| Included source                                                        | What Stable takes from it                                     | GitHub                                                                                                                                            |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Superpowers](https://github.com/obra/superpowers)                     | Planning, execution, testing, review, verification            | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)               |
-| [Context7](https://github.com/upstash/context7)                        | Current documentation and MCP workflows                       | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)               |
-| [Addy Osmani Agent Skills](https://github.com/addyosmani/agent-skills) | Engineering, frontend, debugging, performance, docs, shipping | [![GitHub stars](https://img.shields.io/github/stars/addyosmani/agent-skills?style=flat&label=stars)](https://github.com/addyosmani/agent-skills) |
-| [Agent Skills Marketplace](https://github.com/wshobson/agents)         | Architecture, review, error handling, JavaScript, Python      | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                 |
-
-Every row links directly to the upstream project. Loadout does not claim ownership
-or endorsement; it pins, credits, screens, and selects from their public work.
+pinned public sources**, installed into each agent you choose.
 
 ```bash
-# Preview for detected agents
 loadout setup --mode stable
-
-# Recompute from current state and apply after reviewing the preview
 loadout setup --mode stable --yes
-
-# Inspect managed state, then undo the install if needed
 loadout status
 loadout scan
 loadout rollback
 ```
 
 Stable is Loadout's strongest general starting point, not a claim that one setup is
-best for every person or project. Run `loadout profiles stable --json` when you want
-the machine-readable selection.
-
-## Manage skills you already have
-
-Already have skills? Loadout can compare them with exact catalog copies and manage
-the ones it can identify confidently:
-
-```bash
-# Read-only inventory and source/update comparison
-loadout scan
-loadout reconcile --refresh
-
-# Record ownership only for exact byte-for-byte matches; files are not rewritten
-loadout reconcile --yes
-
-# Preview old copies that have one unambiguous reviewed source
-loadout reconcile --replace-outdated
-```
-
-Unknown or ambiguous copies stay untouched. Replacing an old copy is a separate,
-previewed transaction with its own rollback snapshot. Managed copies can then be
-checked by `loadout update` without moving them to a different agent path.
+best for every person or project.
 
 ## Profiles
 
-Loadout is opinionated when you want it to be and precise when you do not. The
-modes differ in one thing: how much of the reviewed catalog they install.
-
 | Mode      | Sources               | Skills | Active by default                |
 | --------- | --------------------- | ------ | -------------------------------- |
 | `stable`  | 4                     | 30     | yes — recommended starting point |
@@ -289,150 +282,23 @@ modes differ in one thing: how much of the reviewed catalog they install.
 | `maximum` | all reviewed          | all    | **no — downloaded but disabled** |
 | `custom`  | your `--package` list | varies | yes                              |
 
-**Maximum is the one worth understanding.** It downloads the entire reviewed
-library and leaves every skill _disabled_. Nothing reaches an agent prompt until
-a project activates what it needs:
-
-```bash
-loadout setup --mode maximum --yes
-cd ~/code/my-app
-loadout optimize --project .   # scans the repo, proposes an active set
-loadout activate               # enable just those here
-```
-
-That trade is deliberate: disk is cheap and context is not. A large disabled
-library plus a small active set beats installing everything into every prompt.
-
-### Power: a larger cross-project toolkit
-
-Power draws a skill-level allowlist from eight major collections. The prepared set
-is deduplicated and invalid units are quarantined, so the final count can be lower
-than the raw allowlist. In current acceptance testing it prepared about 50 active
-skills per agent.
-
-| Included source                                                          | Focus                                                     | GitHub                                                                                                                                                                      |
-| ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Anthropic Skills](https://github.com/anthropics/skills)                 | Documents, frontend, MCP building, web testing            | [![GitHub stars](https://img.shields.io/github/stars/anthropics/skills?style=flat&label=stars)](https://github.com/anthropics/skills)                                       |
-| [OpenAI Skills](https://github.com/openai/skills)                        | CLI, docs, browser work, images, security                 | [![GitHub stars](https://img.shields.io/github/stars/openai/skills?style=flat&label=stars)](https://github.com/openai/skills)                                               |
-| [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)       | React, web design, composition, deployment                | [![GitHub stars](https://img.shields.io/github/stars/vercel-labs/agent-skills?style=flat&label=stars)](https://github.com/vercel-labs/agent-skills)                         |
-| [Superpowers](https://github.com/obra/superpowers)                       | Planning, debugging, testing, collaboration               | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)                                         |
-| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UI systems, slides, styling, product design               | [![GitHub stars](https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat&label=stars)](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
-| [Context7](https://github.com/upstash/context7)                          | Current documentation and MCP workflows                   | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)                                         |
-| [Agent Skills Marketplace](https://github.com/wshobson/agents)           | Architecture, testing, APIs, TypeScript, Python           | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                                           |
-| [Awesome Copilot](https://github.com/github/awesome-copilot)             | Codebase knowledge, plans, browser and security workflows | [![GitHub stars](https://img.shields.io/github/stars/github/awesome-copilot?style=flat&label=stars)](https://github.com/github/awesome-copilot)                             |
-
-```bash
-loadout setup --mode power
-```
-
-### Maximum Library: download broadly, activate intelligently
-
-Maximum is for explorers. It downloads every non-archived, technically screened
-skill component in the catalog into Loadout's **disabled local library**. Disabled
-means cached and available, not injected into agent context. Then let the current
-project choose a focused active set:
+**Maximum** downloads the entire reviewed library and leaves every skill _disabled_.
+Nothing reaches an agent prompt until a project activates what it needs.
 
-```bash
-loadout setup --mode maximum
-loadout recommend --project .
-loadout optimize --project . --limit 30
-loadout optimize --project . --limit 30 --yes
-```
-
-This is the difference between “install everything” and “have everything ready.”
-The first overloads agents; the second gives you a large library with a small,
-relevant active loadout.
-
-### Custom: take exact control
-
-Use `setup` when the listed packages should become the complete managed profile for
-the selected agents. Packages from the previous managed profile that are not listed
-will be retired, and the preview names every retirement:
-
-```bash
-loadout setup --mode custom --package superpowers --package context7
-```
-
-Use `install` when you only want to add a package without replacing the current
-managed profile:
-
-```bash
-
-# Install the reviewed Humanizer writing skill
-loadout install --mode custom --package humanizer
-
-# Install the reviewed Obsidian skills for specific agents
-loadout install --mode custom --package obsidian-skills --agents claude-code,cursor
-```
-
-Run `loadout profiles` to compare every mode. MCP servers always use a separate
-approval step. Obsidian skills are also proposed automatically when `recommend` or
-`optimize` detects an Obsidian vault; they are not added to the universal Stable set.
-
-## MCP integrations
-
-Profiles never start MCP servers silently. First list the available recipes and see
-which ones need credentials:
-
-```bash
-loadout mcp-recipe
-loadout mcp-recipe --credential-free
-```
-
-Preview and configure one for the host you use:
-
-```bash
-loadout mcp-recipe playwright --agent claude-code
-loadout mcp-recipe playwright --agent claude-code --yes
-loadout mcp-recipe playwright --agent claude-code --verify
-```
-
-Configuration alone does not start the server. Test a real connection separately
-with `--connect --approve-risk`. Loadout can reference credentials from environment
-variables or the OS keychain without printing their values.
-
-## Optional runtime tools
-
-[Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
-tool. It installs both a command and an agent skill, so Loadout keeps it separate from
-the normal profiles. It does not require an LLM API key:
-
-```bash
-loadout tool graphify
-loadout tool graphify --yes --approve-risk
-loadout tool graphify --remove --yes --approve-risk
-```
-
-Executable tools remain an explicit choice instead of hiding inside a profile.
+For detailed profile tables, source lists, and custom configuration, see the
+**[full reference](./docs/REFERENCE.md)**.
 
 ## Catalog and discovery
 
-### GitHub moves every day. Your loadout should not stand still.
-
-The catalog is not a frozen “top 50” list. Loadout separates **discovery** from
+The catalog is not a frozen list. Loadout separates **discovery** from
 **installation** so a viral repo can be noticed quickly without being trusted
-blindly. Candidates enter a review queue; catalog entries are pinned and inspected;
-only the bounded Stable policy gets the strongest automatic recommendation.
+blindly.
 
 ```bash
-# Find candidates across configured discovery sources
 loadout discover --source all --queue
-
-# Inspect the queue and one candidate before promotion
 loadout review-queue
 loadout candidate inspect owner/repository
-
-# Check whether managed active or disabled-library sources changed
 loadout update
-loadout health --updates
-```
-
-Daily checks are opt-in and read-only. They tell you what changed; they do not
-silently rewrite your agents:
-
-```bash
-loadout autopilot --yes
-loadout autopilot --status
 ```
 
 <!-- loadout:catalog-coverage:start -->
@@ -443,39 +309,30 @@ The bundled catalog currently contains **53 credited public repositories** acros
 
 <!-- loadout:evidence-stages:start -->
 
-Catalog maturity: **53 sourced**, **53 technically inspected**, and **4 selected for Stable**. Independent human-review attestations are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
+Catalog maturity: **53 sourced**, **53 technically inspected**, and **4 selected for Stable**. Independent human-review attestations and signed comparative benchmarks are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
 
 <!-- loadout:evidence-stages:end -->
 
-Loadout does not claim there is one universally “best” configuration. Recommendations are bounded, rule-based proposals; stars and discovery results are signals for review, not quality proof.
-
 <!-- loadout:daily-discovery:start -->
 
-**Discovery snapshot (generated 2026-08-31):** [238 repositories observed](./docs/DISCOVERED.md), including 219 uncataloged review candidates and 19 repositories already in the inspected catalog.
+**Discovery snapshot (generated 2026-09-04):** [239 repositories observed](./docs/DISCOVERED.md), including 222 uncataloged review candidates and 17 repositories already in the inspected catalog.
 <!-- loadout:daily-discovery:end -->
 
-The checked-in discovery report proves only its dated snapshot, not the success of every scheduled run. Use `loadout discover --source all --queue`, `loadout review-queue`, and `loadout candidate inspect owner/repository` to inspect candidates before catalog promotion.
-
 ## Trust and limits
 
 - A pinned commit identifies source bytes; it does not prove safety, correct licensing, usefulness, or future compatibility.
 - Static inspection reports scripts, hooks, binaries, domains, credential references, and unsupported components. It is not a security audit.
-- No bundled source is called proven until human review and recorded local outcomes support it; static inspection alone never earns that label.
+- No bundled source is called proven until human review and recorded local outcomes support it.
 - Project recommendations read bounded local metadata. The documented local flow does not upload project source.
-- Catalog fetches, discovery, update checks, and optional live checks use the network where stated.
-- MCP servers and executable tools have separate preview and approval paths because they can use credentials, start processes, or contact services.
+- MCP servers and executable tools have separate preview and approval paths.
 - Shared manifests hold environment-variable or OS-keychain references, not secret values.
 
 <!-- loadout:current-limits:start -->
 
-- **4 catalog records** currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
+- All catalog records have identified SPDX licenses. See the [recorded license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md) for the source-by-source record.
 
 <!-- loadout:current-limits:end -->
 
-The four records have an explicit public-release decision rather than an assumed
-license. Read [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md) for
-the source-by-source record and the boundary applied to Power, Maximum, and Custom.
-
 Read the [security policy](./SECURITY.md), [catalog policy](./docs/CATALOG_POLICY.md), and [credential and update policy](./docs/CREDENTIAL_AND_UPDATE_POLICY.md) before trusting third-party content.
 
 ## Agent support
@@ -494,50 +351,40 @@ Configured CI platforms describe a manually triggered workflow, not evidence tha
 
 <!-- loadout:support-summary:end -->
 
-Configured paths and disposable filesystem lifecycle tests do not prove that native applications recognize or execute installed skills. Use `loadout capabilities --inspect` for the local component matrix.
-
 ## Command reference
 
-Start at the top and stop whenever Loadout does everything you need.
-
-| Priority | What it does                                                    | Command                                                      |
-| -------: | --------------------------------------------------------------- | ------------------------------------------------------------ |
-|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                              |
-|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                |
-|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                 |
-|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                               |
-|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                          |
-|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                               |
-|        7 | Explains what fits the current repository                       | `loadout recommend --project .`                              |
-|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                    |
-|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                |
-|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                             |
-|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                      |
-|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                       |
-|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free` |
-|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent claude-code`          |
-|       15 | Installs Loadout's own skill into your agents                   | `loadout skills install loadout-router --yes`                |
-|       16 | Recommends the right model and agent for a task                 | `loadout route design the auth system`                       |
-|       17 | Shows the full model catalog with pricing                       | `loadout route --models`; `loadout route --cost`             |
-|       18 | Sends a task to another agent via file-based handoff            | `loadout handoff send codex "write tests for auth"`          |
-|       19 | Checks agent health, permissions, and setup                     | `loadout doctor`; `loadout doctor --verbose`                 |
-|       20 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify`                      |
-|       21 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                |
-|       22 | Previews removal of one managed package                         | `loadout remove <package-id>`                                |
-|       23 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                          |
-|       24 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                    |
-|       25 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                         |
-
-Most mutating commands are dry runs first. After reading the preview, add `--yes` to
-apply. Commands with executable or connection risk require the additional approval
-shown in their output.
-
-## Built with Claude
-
-Loadout was designed and built by [Viraj Mishra](https://github.com/VirajMishra1) with Claude Code.
-
-Loadout itself does **not** call any LLM API and does not require an LLM API key
-to manage skills. Claude helped build the tool; it is not a hidden runtime dependency.
+| What it does                            | Command                                        |
+| --------------------------------------- | ---------------------------------------------- |
+| Beginner-friendly guided path           | `loadout guide`                                |
+| Preview the 30-skill Stable setup       | `loadout setup --mode stable`                  |
+| Apply after reviewing the preview       | `loadout setup --mode stable --yes`            |
+| Show managed packages and active skills | `loadout status` · `loadout library`           |
+| What fits this repository               | `loadout recommend --project .`                |
+| Project-specific active set             | `loadout optimize --project . --limit 30`      |
+| Scan existing skills across agents      | `loadout scan`                                 |
+| Check for source updates                | `loadout update`                               |
+| Find newly launched candidates          | `loadout discover --source all --queue`        |
+| Install Loadout's own skill             | `loadout skills install loadout-handoff --yes` |
+| Send a task to another agent            | `loadout handoff codex "write tests"`          |
+| Inspect shared agent state              | `loadout coord snapshot codex`                 |
+| Detect live provider runtimes           | `loadout coord agents detect`                  |
+| Debate one design with both providers   | `loadout coord discuss start "<topic>" ...`    |
+| Start the coordination MCP server       | `loadout serve`                                |
+| Agent health check                      | `loadout doctor`                               |
+| Rollback the latest managed change      | `loadout rollback`                             |
+| Preview complete removal                | `loadout uninstall`                            |
+| Full CLI reference                      | `loadout --help` · `loadout advanced`          |
+
+Most mutating commands are dry runs first. Add `--yes` to apply.
+
+## Built with Claude and Codex
+
+Loadout was designed and built by [Viraj Mishra](https://github.com/VirajMishra1) with Claude Code and Codex.
+
+Loadout's core skill management does **not** call an LLM API or require an LLM API
+key. The opt-in provider bridge and design room do invoke your configured
+Claude/Codex sessions and spend their quota; neither is a hidden requirement for
+discovering, installing, or rolling back extensions.
 
 ## Development
 
@@ -549,28 +396,26 @@ npm run verify:full
 
 <!-- loadout:verification-summary:start -->
 
-`verify` invokes `format:check`, `lint`, `typecheck`, `check:evidence`, `test`, `test:e2e:cli`, `test:e2e:readme`, `test:package`, `test:performance` in that order. `npm run verify:full` is an alias for the same complete CLI release gate.
+`verify` invokes `format:check`, `lint`, `typecheck`, `check:audit`, `check:evidence`, `test`, `test:e2e:cli`, `test:e2e:readme`, `test:package`, `test:performance` in that order. `verify:full` runs that gate and the coverage suite.
 
 <!-- loadout:verification-summary:end -->
 
-The repository's mixed README product-flow test uses an isolated build, disposable state, an offline fixture, direct core calls, and CLI subprocesses. It does not prove live-network availability or behavior inside native agent applications. The [testing guide](./docs/TESTING.md) documents the exact checks and their boundaries.
+The [testing guide](./docs/TESTING.md) documents the exact checks and their boundaries.
 
 ## Documentation
 
+- [Full reference (profiles, MCP, discovery, tools)](./docs/REFERENCE.md)
 - [Catalog and upstream credits](./docs/CATALOG.md)
 - [Catalog evidence policy](./docs/CATALOG_POLICY.md)
 - [Feature and evidence matrix](./docs/FEATURE_TEST_MATRIX.md)
 - [Testing contract](./docs/TESTING.md)
-- [User test and troubleshooting guide](./docs/USER_TEST_GUIDE.md)
-- [Daily discovery snapshot](./docs/DISCOVERED.md)
-- [Candidate inspection and promotion](./docs/CANDIDATE_INTELLIGENCE.md)
-- [Credential and update policy](./docs/CREDENTIAL_AND_UPDATE_POLICY.md)
-- [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md)
+- [User test guide](./docs/USER_TEST_GUIDE.md)
+- [Live Codex ↔ Claude collaboration design](./docs/LIVE_COLLABORATION.md)
 - [Changelog](./CHANGELOG.md)
 
 ## Contributing, security, and attribution
 
-Keep changes scoped, add regression coverage for behavior changes, and run `npm run verify:full`. Report vulnerabilities through [SECURITY.md](./SECURITY.md), without credentials, private source, or unredacted state. General bugs and proposals belong in the [issue tracker](https://github.com/VirajMishra1/loadout/issues).
+See [CONTRIBUTING.md](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · Report vulnerabilities through [SECURITY.md](./SECURITY.md), without credentials, private source, or unredacted state. General bugs and proposals belong in the [issue tracker](https://github.com/VirajMishra1/loadout/issues).
 
 The catalog contains 53 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.