loadout-ai 0.1.0

package/docs/GITHUB_AUTHORIZATION.md

@@ -0,0 +1,38 @@
+# Optional GitHub authorization
+
+Public discovery remains anonymous. Private discovery is opt-in and begins only
+when the user explicitly connects GitHub from the local CLI or loopback dashboard.
+
+## Authorization model
+
+Use a GitHub App installation, not a broad OAuth `repo` token. The app asks for
+read-only **Contents** access, is installed on repositories selected by the user,
+and uses the user-to-server OAuth flow solely to identify the user's installation.
+The resulting short-lived installation token is scoped by GitHub to that selected
+repository set. Metadata is read-only. No organization administration, workflow,
+issues, pull-request write, or repository-write permission is requested.
+
+The app client ID, redirect URI, and application slug may be committed as public
+configuration. The private key and client secret cannot: they belong to a hosted
+broker or a user-controlled local credential manager. Loadout never asks the user to
+paste a token into a manifest, catalog, log, or dashboard URL.
+
+## Local flow and failure modes
+
+1. `loadout connect github` opens a browser using PKCE and a loopback callback.
+2. The local process verifies `state`, PKCE verifier, expiration, and callback host.
+3. It stores only an OS-keychain reference to the refresh/session material.
+4. `loadout discover --private` obtains a short-lived installation token in memory,
+   lists only selected repositories, and discards it after the request.
+5. `loadout disconnect github` deletes the keychain item and local connection record.
+
+If no registered GitHub App/client and secure credential backend are configured,
+private discovery stays unavailable and public discovery keeps working. A token that
+cannot be refreshed or no longer has access is reported as disconnected; it is never
+silently retried with a broader scope.
+
+## Non-goals
+
+This does not clone private repositories, execute private source, or expose private
+repository names in shared exports. A user must still explicitly add and plan a
+repository before Loadout fetches it.

package/docs/HEAD_TO_HEAD_EVALUATION.md

@@ -0,0 +1,79 @@
+# Head-to-head capability evaluation design
+
+This protocol compares two reviewed skill instruction sets on one declared task
+family. It does not rank repositories globally, execute candidate code, or silently
+change an active set.
+
+## Evidence envelope
+
+Every run stores:
+
+- evaluation schema and harness version;
+- category and fixture ids plus the fixture/rubric SHA-256;
+- candidate package, skill path, reviewed commit, and instruction SHA-256;
+- agent surface, model provider/model/version, sampling settings, and tool policy;
+- per-trial rubric dimensions, grader rationale, raw aggregate, variance, and trial
+  count;
+- input/output token counts, reported provider cost or 'unknown', duration, failures,
+  and retries;
+- deterministic grader version, human audit status, uncertainty statement, timestamp,
+  and machine-verifiable signature.
+
+Candidate instructions are data. The harness never runs their scripts, shell commands,
+hooks, MCP servers, network requests, or tool calls. Fixtures use disposable synthetic
+repositories and redact secrets. A model request is permitted only through an explicit
+provider selection and cost ceiling.
+
+## Initial categories
+
+### Workflow adherence
+
+Fixtures ask for a change under explicit constraints: inspect before editing, preserve
+unrelated work, write a focused test, verify, and report uncertainty. Rubric:
+constraint recall (25), plan-to-action consistency (20), safe scope (20), verification
+quality (20), and honest completion report (15). A hidden forbidden action produces a
+blocking safety failure rather than a negative quality point.
+
+### Code-review coverage
+
+Fixtures contain synthetic diffs with seeded correctness, security, concurrency,
+compatibility, and test-gap defects plus harmless distractors. Rubric: weighted seeded
+defect recall (45), precision (20), severity calibration (15), actionable file/line
+evidence (10), and regression-test advice (10). Findings not grounded in the fixture
+count against precision.
+
+### Documentation retrieval
+
+Fixtures provide versioned local documentation and deliberately stale alternatives.
+Rubric: correct source/version choice (30), supported API facts (30), citation
+traceability (20), uncertainty handling (10), and absence of invented APIs (10).
+Network access is disabled so retrieval quality is not confused with internet access.
+
+### Browser-test planning
+
+Fixtures provide an HTML/accessibility snapshot, user journey, and failure evidence.
+Rubric: critical-path coverage (25), stable locator strategy (20), accessibility and
+responsive cases (20), isolation/setup (15), failure diagnostics (10), and avoidance
+of brittle timing (10). The first harness plans tests only; browser execution is a
+separate sandboxed verification stage.
+
+## Trial and decision rules
+
+- Minimum five trials per candidate/fixture/model; alternate candidate order.
+- Identical prompts, context budget, model version, temperature, tool policy, and
+  timeout within a comparison.
+- Report mean, median, standard deviation, failures, and 95% bootstrap interval. Fewer
+  than five successful trials is 'insufficient-evidence'.
+- A result is only 'preferred-for-this-category' when the interval clears the declared
+  practical-effect threshold and no safety failure exists. Otherwise it is 'tie',
+  'mixed', or 'insufficient-evidence'.
+- One fixture, model, or judge cannot promote a global default. Active-set replacement
+  always requires a preview and explicit user approval.
+
+## Signed snapshot boundary
+
+The harness writes canonical JSON, hashes fixtures and candidate inputs, and signs the
+evidence envelope with Loadout's existing Ed25519 catalog-signing primitive. Private
+keys stay outside the repository. Verification must fail on any changed score,
+metadata, candidate hash, or rubric. Unsigned local experiments may be displayed but
+cannot influence shared ranking evidence.

package/docs/PROVENANCE_AND_COMPARISON.md

@@ -0,0 +1,72 @@
+# Provenance and comparison contract
+
+Loadout must answer “where did this skill come from?” and “is there a better reviewed
+alternative?” without turning weak signals into facts. Both workflows are read-only.
+
+## Provenance confidence
+
+From strongest to weakest:
+
+1. `catalog-exact` / `exact`: the installed `SKILL.md` SHA-256 is byte-identical to a
+   skill indexed from a catalog repository at its reviewed immutable commit.
+2. `loadout-managed` / `high`: Loadout state owns the installed path. The file may
+   still be reported separately as drifted if the user edited it after installation.
+3. `embedded-source` / `medium`: the skill text contains a GitHub repository that is in
+   the reviewed index, but the instruction fingerprint differs. A documentation link
+   or fork can create this signal, so it is evidence rather than proof.
+4. `catalog-name-candidate` / `low`: only the normalized skill name matches. Names are
+   not unique and cannot establish authorship, equivalence, or quality.
+5. `unknown` / `unknown`: no supported evidence matched. Loadout preserves this result
+   rather than guessing from a directory name.
+
+`loadout scan` uses only an existing local reviewed index. It never performs network
+access unless `--refresh-provenance` is passed. Refresh fetches only catalog repositories
+with reviewed skill evidence, checks out their exact 40-character commit, fingerprints
+their `SKILL.md` files, and writes a local index below `LOADOUT_HOME/provenance`.
+
+## Relationship classification
+
+`loadout compare` uses deterministic relationships:
+
+- `exact-copy`: identical instruction fingerprint;
+- `divergent-same-name`: same normalized name, different instructions;
+- `overlapping-capability`: at least 30% Jaccard overlap after conservative
+  name/description token normalization; and
+- `same-category-candidate`: reviewed catalog category matches but textual overlap is
+  weak.
+
+Two additional capability-family states are deliberately not inferred from text:
+
+- `complementary-capability` requires an explicit reviewed catalog relationship showing
+  that the tools solve different parts of a workflow; and
+- `verified-hard-conflict` requires a catalog conflict-family record with hard severity
+  and blocks installation until resolved.
+
+If neither reviewed relationship exists, Loadout leaves the relationship unclassified
+rather than calling two vaguely related tools complementary or incompatible.
+
+Cross-agent installations with the same name and fingerprint are mirrors, not duplicate
+problems. Divergent same-name installations require `--agent` disambiguation. Existing
+catalog conflict families remain the source of verified soft/hard package conflicts.
+
+## Comparison evidence and guardrails
+
+Alternatives show repository, reviewed commit, tier, license, deterministic relationship,
+text similarity, and the existing catalog evidence score. Adoption, momentum,
+maintenance, compatibility, permission, and evaluation evidence are printed separately;
+missing evidence is stated instead of being silently treated as good. The score orders
+available catalog evidence; it does not measure model-output quality.
+
+The comparison recommendation follows these rules:
+
+- strongly attributable installed skills remain in place by default;
+- same-name or overlapping candidates require head-to-head evaluation or explicit user
+  experience before replacement;
+- weak same-category candidates are exploration only; and
+- no command changes agent files, activates a skill, or removes an unknown skill.
+
+Limitations are explicit: `SKILL.md` fingerprinting does not prove that referenced assets
+are identical, GitHub URLs embedded in instructions do not prove provenance, semantic
+token overlap is not an embedding or behavioral evaluation, and current comparison does
+not claim universal “best.” Phase 12 task evaluations and local human outcomes are
+required before guided optimization may apply a replacement.

package/docs/PROVIDER_CONFIGURATION.md

@@ -0,0 +1,45 @@
+# Provider-neutral model configuration
+
+Loadout can validate and share a model-selection document before it has a
+provider adapter. The schema is provider-neutral: a selection identifies a
+provider, model, HTTPS endpoint, optional credential _reference_, and optional
+target agent IDs. `openrouter` is an ordinary provider identifier, so an
+OpenRouter selection needs no special schema or stored integration.
+
+```json
+{
+  "schemaVersion": 1,
+  "selections": [
+    {
+      "id": "coding",
+      "provider": "openrouter",
+      "model": "anthropic/claude-sonnet-4",
+      "endpoint": "https://openrouter.ai/api/v1",
+      "credential": { "kind": "environment", "name": "OPENROUTER_API_KEY" },
+      "targetAgents": ["codex", "claude-code"]
+    }
+  ]
+}
+```
+
+## Credential boundary
+
+The document contains only a credential location, never a credential value.
+The accepted references are an environment-variable **name** or an OS-keychain
+service/account reference. It has no `apiKey`, `token`, `authorization`, or
+arbitrary-header fields; strict runtime validation rejects them. Endpoints must
+be credential-free HTTPS URLs (no userinfo, query string, or fragment), and
+secret-looking values are rejected in model/identifier fields.
+
+Loadout does not resolve the reference, write it to state/lockfiles, log it,
+or transmit it in this design. A future provider adapter may read the named
+environment variable or keychain entry only at execution time, and must redact
+it from errors, plans, snapshots, logs, exports, and telemetry. That adapter is
+explicitly outside P11-05.
+
+## Deliberate scope
+
+This schema declares intent; it does not configure Codex, Claude, Cursor, or
+any provider, call OpenRouter, select a model automatically, or store provider
+headers. Keeping those side effects out of the schema layer makes the document
+portable and safe to review in version control.

package/docs/RELEASE_REVIEW.md

@@ -0,0 +1,117 @@
+# Release review — 2026-07-15
+
+This review covers the current Loadout implementation, not an aspirational
+roadmap. It was performed after the transaction, source-fetch, dashboard, and
+adapter test suites passed locally.
+
+## P4-08: atomic-commit review — accepted with explicit durability boundary
+
+Mutation metadata that can make a completed install unrecoverable now uses a
+temporary sibling file followed by `rename`:
+
+- `~/.loadout/state.json`
+- `loadout.lock`
+- edits to an existing `loadout.json`
+- MCP JSON/TOML config writers already used the same-directory temporary-file
+  pattern.
+
+The replacement prevents readers from observing a partially written JSON file
+on local filesystems with atomic same-directory rename support. Snapshots are
+created before mutation and restoration is exercised by tests. CI run
+`29401149042` executed the atomic-file and transaction suites on Node 20 and
+22 for Windows, macOS, and Linux. The decision is therefore accepted for the
+supported local-filesystem scope.
+
+This is not a claim of durable, power-loss-safe multi-file transactions: a
+process or system failure can still leave either the old or new version of an
+individual file. Transaction journals recover interrupted multi-file work before
+the next synchronization; users needing database-grade durability should not rely
+on filesystem rename alone.
+
+## P7-15: product and security review — pass with stated boundaries
+
+The reviewed release flow is appropriate for a hackathon demo and local use:
+
+- Plans are read-only until an explicit apply command or dashboard action.
+- Install/update safety requires approval for scripts, hooks, binaries, new
+  domains, environment references, suspicious instructions, and MCP changes.
+- Snapshots are taken before managed mutations; failures restore them.
+- Repository cloning does not run package lifecycle scripts. Generic Git URLs
+  with embedded credentials, query strings, or fragments are rejected so a
+  failed Git command cannot echo a token.
+- The API is loopback-only. The dashboard also validates the actual socket peer
+  instead of trusting a spoofable `Host` header; mutation endpoints require a
+  random per-process session token and reject cross-origin requests.
+- The dashboard and CLI summaries avoid emitting MCP environment values.
+
+Known boundaries remain intentional: Loadout does not execute third-party
+install scripts, silently replace existing Codex TOML MCP tables, or support
+private repository credentials. It should not be marketed as a full arbitrary
+plugin executor.
+
+## P9-07: cross-platform go/no-go — bounded go for native skills
+
+CI run `29401149042` planed, installed, byte-verified, and removed a real
+`SKILL.md` through every declared agent-owned skill layout on Windows, macOS,
+and Linux, using disposable native home and state directories. **Current
+decision:** go for the bounded native-skill-directory claim. The no-go remains
+for plugins, hooks, executables, and arbitrary MCP runtimes.
+
+## Local verification
+
+On 2026-07-15 the corrective audit also verified:
+
+```text
+npm run format:check
+npm run lint
+npm run typecheck
+npm test -- --run        # 55 files, 169 tests
+npm run build
+npm run test:e2e         # Chromium first-run preview/apply flow
+```
+
+The audit fixed these release blockers and added regressions for them:
+
+- Vitest now assigns every test file disposable Loadout and user homes; a CRLF
+  fixture can no longer write into the developer's real `~/.loadout`.
+- A stale refresh cache overlays mutable metadata onto the bundled catalog instead
+  of hiding newer bundled records or retaining deleted cache-only packages.
+- The Maximum profile references only catalog packages that actually exist.
+- Dashboard Installed and Updates routes have unique container/list IDs and are
+  exercised through navigation in Playwright.
+- Demo output distinguishes planned skill directories from tracked files instead of
+  printing an impossible installed/total fraction.
+- Multi-file synchronization now writes a durable journal and recovers interrupted
+  work even when the next synchronization is otherwise empty.
+- The npm tarball exposes the `loadout` executable, carries runtime code/assets but
+  not compiled tests, and resolves its catalog/dashboard independently of the current
+  working directory.
+
+An outside-checkout 72-file tarball smoke test launched version `0.1.0`, read all 20
+catalog records, and served the packaged dashboard. The live isolated demo fetched
+`obra/superpowers`, planned 14 skill directories and 48 files, then verified rollback
+and removed its temporary profile. The npm package is named `loadout-ai`; the shorter
+`loadout` registry name is owned by an unrelated package.
+
+## CLI-first product correction
+
+The dashboard is now explicitly secondary. Running `loadout` in an interactive terminal
+starts Maximum/Stable/Custom onboarding, while `loadout setup --mode maximum` provides
+a scriptable read-only preview and `--yes --approve-risk` applies the reviewed result.
+
+Catalog setup now:
+
+- filters out MCP/executable-only records before cloning;
+- fetches up to four repositories concurrently with visible progress;
+- fetches the catalog's exact reviewed commit rather than mutable default-branch HEAD;
+- reuses only a clean cache whose Git HEAD matches that commit;
+- resolves duplicate skill targets by retaining the higher-ranked reviewed source and
+  reporting every lower-ranked duplicate;
+- installs all remaining packages through one transaction and one restore point;
+- keeps local health checks network-free unless `--updates` is explicitly requested.
+
+A disposable real Maximum Boost run prepared all 31 skill-bearing repositories from the
+50-record catalog, deferred 19 explicit MCP-only setups, exposed 1,219 skill directories,
+and resolved 48 duplicate target directories. The same isolated flow exercised library
+inspection, project optimization, apply, and rollback successfully before removing its
+test home. No real user agent directory was used.

package/docs/SAFE_UPDATE_DEMO.md

@@ -0,0 +1,25 @@
+# Safe update demonstration
+
+Loadout treats an update as a reviewable filesystem transaction; it never runs
+repository scripts, hooks, package-manager lifecycle commands, or MCP servers.
+
+The regression demo uses only the inert local repositories in
+`tests/fixtures/update-safety`:
+
+1. `benign-v1` to `benign-v2` is a documentation-only skill update. Loadout
+   copies it, validates the copied `SKILL.md`, and records the new commit.
+2. `risky-v2` adds a hook-shaped shell file and an external domain. Static
+   inspection marks it as requiring explicit approval. Without that approval,
+   Loadout writes review metadata to its quarantine directory and leaves the
+   installed files and state untouched.
+3. A simulated post-copy static verification failure restores the exact
+   transaction snapshot, including the previous skill bytes and install state.
+
+Run the evidence locally:
+
+```bash
+npm test -- --reporter=verbose tests/update-safety-demo.test.ts
+```
+
+The hook fixture contains a marker command solely to prove that inspection does
+not execute it. The test asserts that the marker is absent.

package/docs/SCHEMA_DECISIONS.md

@@ -0,0 +1,25 @@
+# Runtime schema decision
+
+Loadout treats catalog JSON, shared manifests and lockfiles, persisted install
+state, and inter-module install plans as untrusted data. `src/shared/schemas.ts`
+is the single runtime-validation boundary for those structures. It uses Zod so
+the parsed output has inferred TypeScript types as well as a path-aware runtime
+error for the CLI and tests.
+
+The schemas intentionally model identifiers, source provenance, agent IDs,
+component kinds, hashes, and safety levels. They do not define fields for MCP
+environment values, API keys, tokens, or other secret values. MCP environment
+values remain in their agent-owned configuration and are only summarized using
+counts/names elsewhere in the product.
+
+Compatibility and failure handling:
+
+- New manifest, lockfile, and state writers always emit schema version 1.
+- Lockfiles produced before `generatedAt` existed remain readable as the
+  explicit legacy value `unknown`; newly written lockfiles always include the
+  timestamp.
+- Unknown catalog and policy fields are retained where required for existing
+  portable-export secret scanning. They are never interpreted as executable
+  configuration by the schema layer.
+- Invalid data fails before install, audit, or update processing with the exact
+  field path (for example, `installs.0.targetAgents.0`).

package/docs/TEAM_POLICY.md

@@ -0,0 +1,18 @@
+# Team policy and audit schema
+
+A shared Loadout is a versioned declarative manifest plus a signed catalog reference;
+it never contains credentials or private repository names by default. Team policy has
+four independent controls:
+
+- allowlist: package IDs/repository identities eligible for planning;
+- denylist: identities, domains, component types, or risk findings that block;
+- required approvals: roles required for risky changes; and
+- audit events: timestamp, actor label, manifest/catalog hashes, decision, and reason.
+
+The serverless/local MVP stores policy in a project-controlled JSON file and validates
+it before a plan. There is no hidden admin override. A later hosted product can add
+identity and retention without changing the portable policy semantics.
+
+The current manifest implementation enforces package/repository allowlists and
+denylists before synchronization, alongside the existing blocked-domain and
+blocked-command rules. Violations are included in the dry-run plan and stop apply.

package/docs/TESTING.md

@@ -0,0 +1,190 @@
+# Testing Loadout as a product
+
+The primary product is the CLI. Use this walkthrough before installing into your real
+Codex, Claude Code, or other agent directories.
+
+The automated product journey runs the built CLI against disposable user, state, and
+project directories. It performs a real scan and offline provenance comparison, then
+previews and applies project optimization, verifies the installed bytes, and rolls the
+snapshot back:
+
+```bash
+npm run test:e2e:cli
+```
+
+This test does not use the dashboard, network, mock command output, or any real agent
+profile. It is a required CI gate on Ubuntu; the manual cross-platform workflow runs
+the broader native filesystem suite.
+
+## 1. Build the exact npm package entry point
+
+```bash
+cd /path/to/loadout
+npm ci
+npm run build
+npx . --help
+```
+
+`npx .` runs the same `loadout` executable that `npx loadout-ai` will run after npm
+publication.
+
+Before creating a disposable profile, the only recommended real-profile command is the
+read-only inventory:
+
+```bash
+npx . scan
+```
+
+It reports actual `SKILL.md` capabilities, Loadout ownership, duplicates, and capacity
+warnings. It does not treat unmanaged content as unsafe and does not change any agent.
+
+To build the local reviewed provenance index from exact catalog commits and compare a
+reported skill:
+
+```bash
+npx . scan --refresh-provenance
+npx . compare <skill-name>
+```
+
+The first command writes only Loadout's local cache. `compare` is read-only and uses
+`--offline` when a test must forbid network fallback. A same-name match is a candidate,
+not proof of provenance or quality.
+
+To inspect and exercise the managed active set after installing a package:
+
+```bash
+npx . library
+npx . disable <managed-package>             # dry-run
+npx . disable <managed-package> --yes       # cache, verify, deactivate
+npx . enable <managed-package>               # dry-run
+npx . enable <managed-package> --yes         # verify and reactivate
+```
+
+Copy the snapshot id printed by either applied command to test
+`npx . rollback --snapshot <id>`. These commands refuse unmanaged packages, drifted
+managed content, incomplete library copies, quarantined entries, and occupied enable
+targets.
+
+## 2. Create a completely disposable agent profile
+
+macOS or Linux:
+
+```bash
+TEST_HOME="$(mktemp -d)"
+export LOADOUT_USER_HOME="$TEST_HOME/user"
+export LOADOUT_HOME="$TEST_HOME/state"
+mkdir -p "$LOADOUT_USER_HOME/.codex" "$LOADOUT_USER_HOME/.claude"
+```
+
+PowerShell:
+
+```powershell
+$TestHome = Join-Path $env:TEMP ("loadout-test-" + [guid]::NewGuid())
+$env:LOADOUT_USER_HOME = Join-Path $TestHome "user"
+$env:LOADOUT_HOME = Join-Path $TestHome "state"
+New-Item -ItemType Directory -Force (Join-Path $env:LOADOUT_USER_HOME ".codex") | Out-Null
+New-Item -ItemType Directory -Force (Join-Path $env:LOADOUT_USER_HOME ".claude") | Out-Null
+```
+
+Those empty directories make Loadout detect virtual Codex and Claude Code profiles.
+Every write stays below the disposable path.
+
+## 3. Preview Power, then inspect Maximum Library
+
+Power is the broad daily-use profile:
+
+```bash
+npx . setup --mode power
+```
+
+Expect a curated skill-level set across the strongest reviewed collections. Stable
+remains the smallest Superpowers + Context7 option. Maximum prepares the full library:
+
+```bash
+npx . setup --mode maximum
+```
+
+This is read-only. Expect the CLI to show:
+
+- detected agents;
+- reviewed catalog repositories fetched at pinned commits;
+- actual skill-directory targets, not only repository count;
+- lower-ranked duplicate skills that were deferred;
+- MCP-only repositories requiring explicit configuration;
+- safety categories requiring a separate approval.
+
+No agent skill directory or Loadout install state is created by preview.
+
+## 4. Download the reviewed library
+
+```bash
+npx . setup --mode maximum --yes --approve-risk
+```
+
+`--approve-risk` acknowledges the displayed scripts, domains, environment names, or
+instruction findings inside the reviewed skill content. Loadout copies skills into its
+disabled library but does not execute repository installation or lifecycle scripts.
+
+The command should finish with one snapshot identifier. The library download is one
+transaction: a failure restores every library/state target rather than leaving a
+half-installed profile.
+
+## 5. Inspect the installed product
+
+```bash
+npx . list
+npx . status
+npx . health
+npx . library
+npx . optimize --project .
+npx . optimize --project . --yes
+```
+
+The first optimize command is a dry run. The second activates only reviewed,
+project-relevant skill units, verifies their hashes, and prints the exact snapshot
+rollback command.
+
+`health` is local and fast by default. Use `npx . health --updates` or
+`npx . update` when you intentionally want live network update checks.
+
+You can also inspect the disposable files directly:
+
+```bash
+find "$LOADOUT_USER_HOME/.agents/skills" -name SKILL.md | wc -l
+find "$LOADOUT_USER_HOME/.claude/skills" -name SKILL.md | wc -l
+```
+
+## 6. Verify rollback
+
+```bash
+npx . rollback
+npx . list
+```
+
+The second command should report that no Loadout-managed packages are installed. Files
+that existed before setup must remain byte-identical.
+
+## 7. Test the real interactive experience
+
+After the disposable run succeeds, open a fresh terminal without `LOADOUT_HOME` or
+`LOADOUT_USER_HOME` overrides and run:
+
+```bash
+npx .
+```
+
+Choose Maximum, Stable, or Custom, review the plan, and confirm only when you want to
+write to the detected real agent profiles. After npm publication, replace `npx .` with
+`npx loadout-ai`.
+
+## Optional dashboard
+
+The dashboard is a secondary inspection surface, not the onboarding requirement:
+
+```bash
+npx . dashboard
+```
+
+Open the printed loopback URL. CLI setup, updates, removal, discovery, and rollback all
+work without it. Browser automation is also optional and runs only when manually
+dispatched in CI; locally, use `npm run test:e2e:dashboard`.