\n\n**Discover anywhere. Install everywhere.**\n\n`agent-harness` is a reviewable supply chain for reusable AI-agent assets: discover trusted sources, rank workspace-specific recommendations, mirror pinned bundles, stage local files, activate host views, and wire everything into the agent host you already use. ARD 1.0-compatible as both publisher and consumer.\n\n**Proof points**\n\n- **Published CLI:** [`@ar27111994/agent-harness` on npm](https://www.npmjs.com/package/@ar27111994/agent-harness), with release artifacts on [GitHub Releases](https://github.com/ar27111994/agent-harness/releases).\n- **Quality-gated:** every release path is backed by the [quality workflow](https://github.com/ar27111994/agent-harness/actions/workflows/quality.yml).\n- **Discoverable:** listed through [GitHub Explore topic visibility](https://github.com/github/explore/pull/5175) as topic metadata, not an endorsement.\n- **Cross-host today:** VS Code/GitHub Copilot, OpenCode, Cursor, Zed, Claude Code, Pi, and OpenAI Codex.\n\n**▶️ Watch the demo:**\n\n\n\n[](https://youtu.be/u1OmcS97iOg)\n\n**Sound-on walkthrough:** [youtu.be/u1OmcS97iOg](https://youtu.be/u1OmcS97iOg)\n\n- **Video source:** [`agent-harness-demo-video`](https://github.com/ar27111994/agent-harness-demo-video), rendered with Remotion and kept outside this package so npm tarballs stay lean.\n- **Terminal source:** [`docs/demo/workspace-opencode-demo.mjs`](https://github.com/ar27111994/agent-harness/blob/main/docs/demo/workspace-opencode-demo.mjs), which records the public-safe OpenCode quick-start transcript and generated-output tree.\n- **Walkthrough notes:** [`docs/demo/v2-opencode-walkthrough.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/demo/v2-opencode-walkthrough.md), covering the full v2 before/after flow.\n\nThe core model is deliberately boring in the best way: one command surface, a host-adapter boundary, preview-first writes, and explicit native-install steps. The lifecycle stays consistent across hosts while each adapter owns the files, settings, apply/reset behavior, and safety boundaries required by that host.\n\n## Table of contents\n\n- [What this project does](#what-this-project-does)\n- [Lifecycle model](#lifecycle-model)\n- [Supported hosts](#supported-hosts)\n- [Where it fits](#where-it-fits)\n- [What it produces](#what-it-produces)\n- [Quick start](#quick-start)\n- [Usage examples](#usage-examples)\n- [Key playbooks](#key-playbooks)\n- [Command reference](#command-reference)\n- [Host wire-in details](#host-wire-in-details)\n- [Discovery and recommendations](#discovery-and-recommendations)\n- [Environment variables](#environment-variables)\n- [Generated and managed files](#generated-and-managed-files)\n- [Repository structure](#repository-structure)\n- [Development and validation](#development-and-validation)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n- [Security and trust center](#security-and-trust-center)\n- [Current boundaries](#current-boundaries)\n- [Related documentation](#related-documentation)\n- [Sponsor](#sponsor)\n- [License](#license)\n\n## Key Playbooks\n\n- [Documentation index](https://github.com/ar27111994/agent-harness/blob/main/docs/README.md) — hub for per-host references, playbooks, and guides\n- [Agent setup playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AGENT-SETUP-PLAYBOOK.md)\n- [Discovery breadth playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md)\n- [Demand detection playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DEMAND-DETECTION-PLAYBOOK.md)\n- [Demand detection coverage](https://github.com/ar27111994/agent-harness/blob/main/docs/reference/DEMAND-DETECTION-COVERAGE.md)\n- [Source coverage playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/SOURCE-COVERAGE-PLAYBOOK.md)\n- [Catalog breadth guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/CATALOG-BREADTH.md)\n- [Semantic scoring guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/SEMANTIC-SCORING.md)\n- [Source pack seeder guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/SOURCE-PACK-SEEDER.md)\n- [AI enrichment playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AI-ENRICHMENT-PLAYBOOK.md)\n- [Asset update playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/ASSET-UPDATE-PLAYBOOK.md)\n- [Logging strategy](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/LOGGING-STRATEGY.md)\n- [Troubleshooting guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/TROUBLESHOOTING.md)\n- [Recommendation policy playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/RECOMMENDATION-POLICY-PLAYBOOK.md)\n- [Workspace evolution control-loop playbook](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/WORKSPACE-EVOLUTION-PLAYBOOK.md)\n- [End-user harness maintenance guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/HARNESS-MAINTENANCE-GUIDE.md)\n- [Security and trust center](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/TRUST-CENTER.md)\n- [v2 safe defaults](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/SAFE-DEFAULTS.md)\n- [v2 CLI and report contract](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V2-CONTRACT.md)\n- [v1 to v2 upgrade guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V1-TO-V2-UPGRADE.md)\n- [Scheduled maintenance workflow](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/MAINTENANCE-WORKFLOW.md)\n- [Release process](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/RELEASE-PROCESS.md)\n- [Adapter development guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/ADAPTER-DEVELOPMENT.md) — creating new host adapters\n- [CLI cheat sheet](https://github.com/ar27111994/agent-harness/blob/main/docs/cheatsheet.md) — quick reference for common workflows\n\n## What this project does\n\n`agent-harness` automates the lifecycle of reusable agent assets:\n\n1. Scans a target workspace to infer demand signals.\n2. Loads configured and generated discovery sources.\n3. Harvests candidate agent assets from local sources, source packs, documentation sources, package registries, and marketplace references.\n4. Recomputes ranked recommendations from selected catalog entries.\n5. Mirrors the bounded selected asset set into reproducible local artifacts.\n6. Stages mirrored bundle assets into lifecycle-host package stores.\n7. Executes explicit host-native install/verify/remove operations where an adapter supports them.\n8. Activates ranked assets into host runtime views.\n9. Wires the activated assets into a target workspace through a selected host adapter.\n\nThe goal is to make high-quality reusable agent context portable across tools without hardcoding one workstation, one operating system, or one AI host.\n\n## Lifecycle model\n\nThe project intentionally separates these stages:\n\n| Stage | Purpose | Typical output |\n| ----------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |\n| `discover` | Build demand profiles, source indexes, catalogs, selections, and source-utilization reports. | `discover/output/`, `discover/catalog.assets.jsonl` |\n| `recommend` | Rank assets per recommendation host using policy, demand signals, trust, cost, diversity, and caps. | `state/recommendations.json` |\n| `mirror` | Build mirror plans, bundle locks, raw artifact caches, quarantine data, and audit records. | `mirror/` |\n| `stage` | Stage mirrored bundle assets, reconcile generations, and explicitly run supported host-native installs. | `install/`, `state/install/` |\n| `activate` | Materialize active runtime views for lifecycle hosts from staged packages and recommendations. | `activate/` |\n| `wire` | Preview by default, or explicitly apply/reset host-specific workspace integration. | host-specific files plus wire plans |\n| `workspace` | Run the end-to-end lifecycle for a selected host and then apply wire-in. | full pipeline output |\n\n`stage` is the clearer mental model for this phase: the harness stages a bounded mirrored bundle subset into its managed lifecycle store. The CLI still accepts `install` as an alias because host-native install/verify/remove operations also live in that command group.\n\nTwo host concepts are important:\n\n- **Lifecycle host**: the stage/activation package layout used to materialize assets.\n- **Recommendation host**: the host-specific policy used for ranking and budgets.\n\nSome adapters intentionally reuse another lifecycle host while keeping their own recommendation host. For example, Cursor reuses the Copilot-compatible lifecycle host but ranks through the `cursor` policy.\n\n`wire ` is intentionally non-mutating unless you pass `--apply` or `--reset`; use the default preview mode to inspect target paths and planned writes before changing host files.\n\n## Supported hosts\n\n`agent-harness` currently registers seven host adapters in `src/host-adapters/registry.ts`.\n\n| CLI target | Aliases | Lifecycle host | Recommendation host | Default bundles | Wire style |\n| ------------- | --------------------------- | ---------------- | ------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| `vscode` | `copilot` | `copilot-vscode` | `copilot-vscode` | `copilot-core`, `community-stable`, `shared-mcp` | VS Code user settings plus workspace instructions |\n| `opencode` | `open-code` | `opencode` | `opencode` | `opencode-global`, `community-stable`, `shared-mcp` | project-local `.opencode` overlay and managed links |\n| `cursor` | - | `copilot-vscode` | `cursor` | `copilot-core`, `community-stable`, `shared-mcp` | project-local Cursor rules and managed assets |\n| `zed` | - | `opencode` | `zed` | `opencode-global`, `community-stable`, `shared-mcp` | project-local `.rules`, `.zed/settings.json`, and managed assets |\n| `claude-code` | `claude`, `claudecode` | `opencode` | `claude-code` | `opencode-global`, `community-stable`, `shared-mcp` | project-local Claude context, rules, skills, and commands |\n| `pi` | `pi-coding-agent` | `opencode` | `pi` | `opencode-global`, `community-stable` | project-local Pi agent/system context, skills, prompts, and settings |\n| `codex` | `openai-codex`, `codex-app` | `opencode` | `codex` | `opencode-global`, `community-stable`, `shared-mcp` | project-local AGENTS.md, .agents/skills, plugins/agent-harness, and .codex references |\n\nUse `setup hosts` to print the registered adapters from the local build:\n\n```bash\nagent-harness setup hosts\n```\n\n## Where it fits\n\n`agent-harness` is the supply-chain layer that decides what reusable agent assets enter a workspace and how they are staged, activated, reviewed, and wired. It does **not** run agents. It prepares inspectable inputs for the host or harness you already use.\n\n| Tool or category | What it does | Boundary |\n| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| Curated skill/plugin libraries | Help you find and install assets from one ecosystem or curated catalog. | Usually focused on acquisition, not cross-host lifecycle state, pinned mirrors, quarantine, and resettable wire plans. |\n| MCP/server lists | Help you discover servers and integration ideas. | Lists are references; they do not decide what enters a workspace, stage reproducible artifacts, or manage host-specific wiring. |\n| Agent runtime harnesses | Run agents, tasks, models, tools, and sessions. | `agent-harness` is not the runtime. It manages reusable assets before they enter one. |\n| **agent-harness** | **Discovers sources, ranks recommendations, mirrors pinned bundles, stages/activates assets, quarantines risky inputs, and wires selected assets into supported hosts with preview/apply/reset semantics.** | **Supply-chain and workspace integration layer for reusable AI-agent assets.** |\n\nThe practical lifecycle is: `discover -> recommend -> mirror -> stage -> activate -> wire`. Official and verified sources are preferred over popularity-only signals, official-first-party sources are demoted when owner/publisher evidence fails verification, mirrored generations are pinned for review, risky candidates route through quarantine, and native/global host installs remain explicit instead of hidden inside `workspace `.\n\n## ARD interoperability\n\n
\n \n
\n\n**Tagline:** _Discover anywhere. Install everywhere._\n\n`agent-harness` is both an **ARD publisher** and an **ARD consumer**, implementing the [Agentic Resource Discovery](https://agenticresourcediscovery.org/spec) 1.0 specification (backed by Google, Microsoft, Hugging Face, GitHub, NVIDIA, and others).\n\n### Publisher — `.well-known/ai-catalog.json`\n\nEvery `discover select` or `discover full` run builds a selected asset catalog. Export it as an ARD-compliant catalog so registries can discover agent-harness-curated assets:\n\n```bash\nagent-harness discover ard-export\n# → /.well-known/ai-catalog.json\n```\n\nARD registries crawl `/.well-known/ai-catalog.json` at your domain to index agent-harness assets alongside assets from other publishers. The export maps every `AssetCatalogEntry` to an ARD entry with:\n\n- **URN identifier** (`urn:air:::`) — domain-backed identity\n- **Media type** (`application/mcp-server+json`, `application/ai-skill`, etc.) from AssetKind\n- **Trust manifest** — OMS signatures, publisher verification, compliance attestations\n- **Representative queries** — synthetic natural-language queries for semantic discovery\n\nThe export path is relative to the active state root (`--state-root `); by default that is the repository root when running inside the repo (repository-local development), or `/.agent-harness` for an installed CLI run from another workspace, so `discover ard-export` writes `/.well-known/ai-catalog.json`. Entries whose update timestamp is unknown (harvester epoch sentinel) omit `updatedAt` rather than publishing `1970-01-01` (#449).\n\n### Consumer — ARD registry adapter\n\n`agent-harness` can consume ARD-compliant registries as discovery sources via `POST /search`. The registry adapter maps ARD results back to `AssetCatalogEntry` for the full mirror/stage/activate/wire pipeline. See `discover sync` and the `ard-registry` source kind (#327).\n\n### Architecture\n\n```mermaid\ngraph LR\n A[agent-harness Publisher] -->|ai-catalog.json| B[ARD Registries GitHub Agent Finder HuggingFace Discover]\n B -->|POST /search| C[agent-harness Consumer]\n C -->|mirror → stage → activate → wire| D[Host IDEs VS Code, Cursor, Zed, Claude Code, OpenCode, Pi, Codex]\n B -->|index| E[End Users Agent Discovery]\n```\n\nARD defines **discovery** (catalogs and registries). `agent-harness` handles the **distribution** phase that ARD §3.6 explicitly delegates to backend implementation — mirroring, staging, activation, and host-specific wiring.\n\n**See:** [#325](https://github.com/ar27111994/agent-harness/issues/325) (catalog export), [#327](https://github.com/ar27111994/agent-harness/issues/327) (registry consumer), [#328](https://github.com/ar27111994/agent-harness/issues/328) (trust signals), [#326](https://github.com/ar27111994/agent-harness/issues/326) (community submission).\n\n## What it produces\n\nWhen you run the installed CLI from a workspace, mutable lifecycle state is written under `.agent-harness/` by default. Repository-local development keeps the same layout at the repository root so npm scripts and checked-in policy assets continue to work.\n\n| Phase | Inspectable outputs |\n| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Demand detection | `.agent-harness/discover/output/demand-profile.json`, `.agent-harness/discover/output/unknown-signals.json` |\n| Source selection | `.agent-harness/discover/output/source-index.json`, `.agent-harness/discover/output/selection-report.json`, `.agent-harness/discover/output/source-utilization.json`, `.agent-harness/discover/output/source-health.json`, `.agent-harness/discover/output/source-drift.json`, `.agent-harness/discover/output/catalog-maintenance-candidates.json` |\n| Catalog and recommendations | `.agent-harness/discover/catalog.assets.jsonl`, `.agent-harness/discover/output/asset-fingerprints.json`, `.agent-harness/state/recommendations.json` |\n| Mirror locks and quarantine | `.agent-harness/mirror/bundles/*.lock.json`, `.agent-harness/mirror/quarantine/**`, `.agent-harness/mirror/audit/**` |\n| Staged generations | `.agent-harness/install/generations//current.json`, `.agent-harness/install//packages/*/install-manifest.json` |\n| Activation | `.agent-harness/activate//activation-manifest.json`, `.agent-harness/activate//-overlay-plan.json` when the adapter emits an overlay plan |\n| Wire preview/apply | `.agent-harness/activate//wire-preview-.json`, `.agent-harness/activate//wire-plan.json`, plus host-specific managed files such as `.opencode/...`, `.cursor/...`, `.zed/settings.json`, `.claude/...`, `.pi/...`, `.agents/...`, `.codex/...`, `AGENTS.md`, or `.github/copilot-instructions.md` |\n\nPreview mode writes reviewable wire plans without touching host files. Apply mode writes only the selected adapter's managed project files/settings, while native/global host installs remain explicit `install native` operations where supported. See [Host wire-in details](#host-wire-in-details) for the per-host paths and reset behavior.\n\n## Quick start\n\n### Try it in one command\n\n```bash\nnpm install -g @ar27111994/agent-harness\nagent-harness workspace opencode --intent general\n```\n\nRun the command from the workspace you want to inspect. By default, the installed CLI writes lifecycle state under `.agent-harness/`, applies only the selected adapter's managed project-local wire-in, and leaves native/global host installs, MCP authentication, marketplace extensions, and executable integrations as explicit follow-up operations. Review [What it produces](#what-it-produces) for the generated files and [Host wire-in details](#host-wire-in-details) for the exact OpenCode boundaries.\n\n### Requirements\n\n- Node.js `>=23` (the coverage gate runs the test runner with `--test-isolation=none`, which shipped with Node 23)\n- npm\n- Git\n- Optional GitHub token for higher GitHub API throughput:\n - `GITHUB_PERSONAL_ACCESS_TOKEN`\n - or `GITHUB_TOKEN`\n\n### Install the CLI package\n\n```bash\nnpm install -g @ar27111994/agent-harness\n```\n\nFor local development from this repository, install dependencies instead:\n\n```bash\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n> **Windows git-bash (MSYS) users:** MSYS-style paths (`/c/Projects/...`) are now\n> automatically normalised to native Windows paths (`C:\\Projects\\...`) for all CLI\n> arguments including `--state-root`. If you encounter path issues with Node's module\n> resolver, use native Windows paths or `node \"$(cygpath -w /c/Projects/agent-harness/dist/cli.js)\"`.\n> For persistent use, add the project to your `PATH` via native Windows syntax or use\n> `npx @ar27111994/agent-harness` from the npm global install. See\n> [Troubleshooting](docs/guides/TROUBLESHOOTING.md) for more Windows-specific guidance.\n\n### Optional local environment\n\nRuntime configuration is centralized in `src/config/runtime.ts`. `.env.example` documents supported variables. The CLI automatically loads a `.env` file from the current working directory before dispatching commands, without overriding variables that are already exported by your shell. Use `--no-dotenv` for hermetic CI/smoke runs.\n\n```bash\ncp .env.example .env\n```\n\nUse `.env` for local machine values such as GitHub tokens, batch sizes, scan budgets, and optional state-root overrides. Keep real secrets out of git.\n\n### Inspect host readiness\n\n```bash\nagent-harness setup hosts\nagent-harness setup doctor\nagent-harness setup doctor --host vscode\nagent-harness setup doctor --host opencode\nagent-harness setup doctor --host cursor\nagent-harness setup doctor --host zed\nagent-harness setup doctor --host claude-code\nagent-harness setup doctor --host pi\nagent-harness setup doctor --host codex\n```\n\n`setup doctor` prints each adapter's lifecycle host, recommendation host, default bundles, runtime executable, advertised capabilities, lifecycle preflight diagnostics, adapter-specific CLI readiness diagnostics, and activated asset prerequisite guidance. Missing optional host CLIs are reported as warnings unless the selected operation requires a writable host-native path or native installer runtime.\n\n### Run a full workspace pipeline\n\nFrom the target workspace directory, run one of:\n\n```bash\nagent-harness workspace vscode --intent frontend\nagent-harness workspace opencode --intent devops\nagent-harness workspace cursor --intent frontend\nagent-harness workspace cursor --intent frontend --ai-enrich\nagent-harness workspace zed --intent design\nagent-harness workspace claude-code --intent research\nagent-harness workspace pi --intent product\nagent-harness workspace codex --intent research\n```\n\nFrom this repository, equivalent npm scripts are available:\n\n```bash\nnpm run workspace:vscode -- --intent frontend\nnpm run workspace:opencode -- --intent devops\nnpm run workspace:cursor -- --intent frontend\nnpm run workspace:zed -- --intent design\nnpm run workspace:claude-code -- --intent research\nnpm run workspace:pi -- --intent product\nnpm run workspace:codex -- --intent research\n```\n\nUse the adapter-driven `agent-harness workspace ` command for end-to-end host setup. For a new user, this is the straightforward default path: it runs the broad discovery/recommendation pipeline, stages and activates assets, and then performs the selected host's final wire-in.\n\n**After the first wire-in:** copy the [end-user harness maintenance guide](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/HARNESS-MAINTENANCE-GUIDE.md) to your AI coding agent and run the weekly safe-refresh loop from there. Add `--ai-enrich` when you want the bounded enrichment sidecar as part of the same run, or configure `AGENT_HARNESS_AI_ENRICHMENT_MODE` for conservative automatic behavior.\n\nSupported canonical intents are `general`, `frontend`, `backend`, `mobile`, `devops`, `security`, `docs`, `testing`, `research`, `data`, `design`, `product`, and `marketing`. Common aliases are normalized automatically, for example `documentation` → `docs`, `ci-cd` / `infra` → `devops`, `branding` → `design`, and `ba` / `planning` / `product-research` → `product`. `--intent` accepts repeated values for additive multi-intent runs, for example `--intent frontend --intent docs`. The first provided intent remains the primary intent for backward-compatible activation/manifests. If you want to compare isolated task shapes instead of combining them, rerun the command once per intent.\n\n### Mutable state root\n\nA packaged CLI keeps checked-in discovery and mirror policy assets read-only and writes mutable lifecycle state elsewhere:\n\n- When you run from this repository root, the development default remains the repository root so existing npm scripts continue to work.\n- When you run the installed package from another workspace, the default mutable state root is `.agent-harness/` in that workspace.\n- Override the state location with `--state-root ` or `AGENT_HARNESS_STATE_ROOT`.\n- Long-running operations (recommend, discover catalog) respect `--timeout-seconds ` (clamped 10–3,600) or `AGENT_HARNESS_TIMEOUT_SECONDS`.\n\n### Building a comprehensive catalog\n\nThe default `discover full` builds a demand-driven catalog — fast for per-workspace use but limited in breadth (~11,500+ entries from 39 enabled asset-producing sources). The shipped `discover/sources.json` configures 50 sources, but the 8 `docs`-kind entries are metadata-only provenance references (disabled before enabled-source, health, and breadth counts are computed) and swift-package-index, github-agent-finder, and huggingface-discover are disabled, so breadth counts only the 39 enabled asset-producing sources. To build a truly comprehensive catalog across millions of available assets, use the two-phase offline index workflow:\n\n**Phase 1 (offline, one-time or CI):** Build the full index across all sources.\n\n```bash\n# Run the offline index build — fully paginates all indexed sources\nagent-harness discover index\n\n# For unlimited pagination (build the complete index):\nAGENT_HARNESS_SOURCE_SYNC_MAX_PAGES_FOR_INDEX_BUILD=0 agent-harness discover index\n\n# Run on a schedule (daily/weekly CI job recommended)\n```\n\nThe `discover index` command paginates 500 pages per source by default (vs 10 for `discover sync`). Set `AGENT_HARNESS_SOURCE_SYNC_MAX_PAGES_FOR_INDEX_BUILD=0` for unlimited. The index is stored as `discover/output/catalog-index.jsonl` and stays fresh for 7 days (`AGENT_HARNESS_DISCOVERY_INDEX_MAX_AGE_DAYS`).\n\n**Phase 2 (per-workspace):** Demand-rank against the local index — zero API calls.\n\n```bash\n# Uses the pre-built index if fresh, falls back to live harvest if stale\nagent-harness discover select\nagent-harness recommend report --intent frontend\n```\n\n**Production-scale config:** Override conservative defaults for comprehensive coverage:\n\n| Env var | Default | Production | Effect |\n| --------------------------------------------------------- | ------- | --------------------- | --------------------------------- |\n| `AGENT_HARNESS_SOURCE_SYNC_MAX_PAGES_FOR_INDEX_BUILD` | 500 | 0 (unlimited) | Pages per source in index build |\n| `AGENT_HARNESS_VSCODE_MARKETPLACE_POPULARITY_SWEEP_PAGES` | 50 | 200+ | Popularity-sorted VS Code pages |\n| `AGENT_HARNESS_VSCODE_MARKETPLACE_MAX_QUERIES` | 4 | 20 | Demand-driven queries |\n| `AGENT_HARNESS_TIMEOUT_SECONDS` | (none) | 600 | Deadline for long ops (10–3,600) |\n| `GITHUB_TOKEN` | (none) | Personal access token | 5,000 req/h vs 60 unauthenticated |\n\n**Scope:** A full index build with `GITHUB_TOKEN` and unlimited pagination can catalog tens of thousands of assets from VS Code Marketplace (60,000+ extensions), npm (2M+ packages), MCP registry, package registries, GitHub awesome-lists, and community source packs. The per-workspace selection then ranks from this comprehensive pool rather than a limited demand-driven harvest. See `docs/guides/CATALOG-BREADTH.md` for the full guide.\n\nExamples:\n\n```bash\nagent-harness --state-root .agent-harness workspace cursor --intent frontend\nAGENT_HARNESS_STATE_ROOT=.agent-harness agent-harness wire zed --preview\n```\n\n## Usage examples\n\n### Preview before touching a workspace\n\nUse `wire` or `wire --preview` when you want to inspect planned host targets without mutating workspace files:\n\n```bash\nagent-harness wire cursor\nagent-harness wire zed --preview\nagent-harness wire claude-code --preview\n```\n\nPreview output is written under `activate//` and can be reviewed before `--apply`. Omitting a mode flag is equivalent to `--preview`.\n\n### Use an AI agent as a dry-run setup operator\n\nWhen you want another agent to operate `agent-harness` for you, start with a dry run before any apply/install step. This keeps workspace mutation, extension installation, and MCP/tool authentication separate from discovery and recommendation review.\n\nFor the full playbook, reusable prompts, classification rules, and decision tree, see [`AGENT-SETUP-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AGENT-SETUP-PLAYBOOK.md).\n\nAvailable playbooks:\n\n- [`AGENT-SETUP-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AGENT-SETUP-PLAYBOOK.md) - dry-run setup workflow, decision tree, and reusable agent prompts for workspace/host asset setup\n\n- [`DISCOVERY-BREADTH-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md) - maximize the practical candidate pool before judging recommendation quality\n\n- [`DEMAND-DETECTION-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DEMAND-DETECTION-PLAYBOOK.md) - debug false negatives, false positives, and weak evidence in `discover/output/demand-profile.json`\n\n- [`DEMAND-DETECTION-COVERAGE.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/reference/DEMAND-DETECTION-COVERAGE.md) - audited project-type matrix for stack/vertical detection coverage\n\n- [`SOURCE-COVERAGE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/SOURCE-COVERAGE-PLAYBOOK.md) - widen discovery sources cleanly when the workspace is understood but the source universe is too narrow\n\n- [`AI-ENRICHMENT-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AI-ENRICHMENT-PLAYBOOK.md) - choose enrichment modes, bounded AI review, and operator workflows\n\n- [`ASSET-UPDATE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/ASSET-UPDATE-PLAYBOOK.md) - refresh staged assets safely with report-only, due-only, and apply-safe flows\n\n- [`RECOMMENDATION-POLICY-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/RECOMMENDATION-POLICY-PLAYBOOK.md) - inspect and tune ranking only after recall looks healthy\n\nShort version:\n\n- new user default: run `agent-harness workspace ` for the full end-to-end host flow\n- run `agent-harness setup doctor --host ` first when you want a dry-run/operator-guided setup review\n- use `agent-harness discover breadth` first when your main question is candidate-pool breadth rather than end-to-end setup\n- run `agent-harness wire --preview` only when lifecycle outputs already exist and you want to inspect/apply host-specific wire behavior\n- separate staged/wired assets from native installs and manual runtime follow-up\n- only run mutating install/apply commands after the dry run looks correct\n\nIf your main question is \"how do I give recommendations the widest sensible candidate pool first?\", use [`DISCOVERY-BREADTH-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md) before changing recommendation policy. If breadth looks wrong because stack detection is weak, continue with [`DEMAND-DETECTION-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DEMAND-DETECTION-PLAYBOOK.md); if the stack looks right but the discovery universe is still too small, continue with [`SOURCE-COVERAGE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/SOURCE-COVERAGE-PLAYBOOK.md).\n\n### Default workspace diagnostic ladder\n\nWhen `agent-harness workspace ` gives surprising output, diagnose in this order instead of jumping straight to bigger limits or host-policy edits:\n\n1. **Did the workspace command complete?** If not, inspect preflight/runtime/install/wire logs and host readiness with `agent-harness setup doctor --host `.\n2. **Is `discover/output/demand-profile.json` wrong or weak?** If yes, use [`DEMAND-DETECTION-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DEMAND-DETECTION-PLAYBOOK.md) and the matrix in [`DEMAND-DETECTION-COVERAGE.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/reference/DEMAND-DETECTION-COVERAGE.md).\n3. **Is source utilization or selected-candidate breadth starved?** Inspect `discover/output/source-index.json`, `discover/output/source-utilization.json`, and `discover/output/selection-report.json`, then use [`SOURCE-COVERAGE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/SOURCE-COVERAGE-PLAYBOOK.md) / [`DISCOVERY-BREADTH-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md).\n4. **Are relevant assets selected but buried?** Inspect `state/recommendations.json`, `recommend policy:print --host `, and `recommend explain --host --asset `, then use [`RECOMMENDATION-POLICY-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/RECOMMENDATION-POLICY-PLAYBOOK.md).\n5. **Is the problem host-specific?** Validate the host policy with recommendation fixtures before changing defaults.\n6. **Is narrative judgment needed after deterministic output is sane?** Use bounded AI review/enrichment as an audit layer, not as a replacement for detection/source/ranking fixes.\n\nEvery detection, source, or policy change should cite fixture output, explain output, a selected-catalog miss, a source-utilization miss, or a demand-profile false negative/positive. Avoid changes based only on vibes.\n\n### Apply and reset one host\n\n```bash\nagent-harness wire cursor --apply\nagent-harness wire cursor --reset\n```\n\nUse this when activation outputs already exist and you only want to test the host adapter behavior.\n\n### Run the full pipeline for a documentation-heavy repo\n\n```bash\nagent-harness workspace zed --intent docs\n```\n\nThis scans the current workspace, ranks assets with the `zed` recommendation policy, activates the OpenCode-compatible lifecycle view, and writes Zed project-local files.\n\n### Run the full pipeline for a frontend repo in Cursor\n\n```bash\nagent-harness workspace cursor --intent frontend\nagent-harness workspace cursor --intent frontend --ai-enrich\n```\n\nCursor reuses the Copilot-compatible lifecycle host but applies Cursor-specific recommendation policy, project-local `.cursor` rules, prompt-pack command coverage, MCP references, and managed Cursor plugin-compatible assets. Adding `--ai-enrich` writes the bounded enrichment sidecar after the deterministic workspace flow completes.\n\n### Inspect why an asset was recommended\n\n```bash\nagent-harness recommend explain --host claude-code --asset \n```\n\nUse this to inspect scoring reasons, matched demand signals, coverage tags, and score breakdowns.\n\n### Run bounded AI review for a host\n\n```bash\nagent-harness recommend ai-review --host vscode --apply\n```\n\nThis writes bounded AI-review input/output artifacts under `recommend/output/` and, with `--apply`, folds validated suppressions and reranks back into the recommendation report.\n\n### Print the effective policy for one host\n\n```bash\nagent-harness recommend policy:print --host pi\n```\n\nThis is useful when tuning host policy overrides or investigating why a host selected different assets than another host.\n\n### Rebuild from repository state\n\n```bash\nnpm run rebuild:full\nnpm run recommend:report\nnpm run activate:host\n```\n\nUse this sequence after changing source definitions, recommendation policy, mirror bundles, or install behavior.\n\n## Command reference\n\n### Command style convention\n\n- Use `agent-harness ...` for installed package usage and copy-pasteable user commands.\n- Use `npm run ...` for repository-development shortcuts after `npm install`.\n- Use `node ./dist/cli.js ...` only when intentionally testing the built local entrypoint from this repository.\n\n### Managed wire-in vs native/global install\n\n`workspace ` applies the complete managed lifecycle and final host wire-in. It stages and activates selected harness assets, then writes the host-specific project/user files owned by the adapter.\n\nIt does not silently perform separate native or global installation steps. Marketplace extension installs, MCP authentication, global host package/plugin registration, executable hook/tool setup, and host logins remain explicit or manual unless an asset provides structured host-native config for a documented surface. Use `agent-harness install native --host --operation ` for supported native extension flows.\n\n### Build and validation\n\n```bash\nnpm run build\nnpm run typecheck\nnpm run lint\nnpm run format\nnpm run format:check\nnpm run validate\nnpm test\nnpm run smoke:cli\nnpm run benchmark:scan\nnpm run quality:detection\nnpm run quality:policy\nnpm run validate:recommendations\n```\n\n### Discover\n\n```bash\nnpm run discover:demand\nnpm run discover:sources\nagent-harness discover sync\nnpm run discover:catalog\nnpm run discover:select\nnpm run discover:full\nagent-harness discover breadth\nnpm run discover:stats\nnpm run discover:enrich\n```\n\nEquivalent direct CLI examples:\n\n```bash\nagent-harness discover demand-profile\nagent-harness discover sources\nagent-harness discover sync\nagent-harness discover catalog\nagent-harness discover select --ai-enrich\nagent-harness discover full --ai-enrich\nagent-harness discover breadth\nagent-harness discover recall\nagent-harness discover candidate-pool\nagent-harness discover stats\nagent-harness discover enrich --force\nagent-harness discover diff --baseline \nagent-harness discover inspect --source \nagent-harness discover inspect --id \nagent-harness discover environment-index\n```\n\n### Reducing source health noise\n\n`discover full` produces source health warnings for every configured source. With 50 configured sources, most warnings are expected — e.g. \"entries produced but none survived selection\" for registries irrelevant to your workspace. Three flags help manage output and performance:\n\n- **`--quiet`**: suppress expected warnings; only severe/error conditions are shown\n- **`--summary`**: print aggregate warning counts grouped by reason instead of per-source lines\n- **`--sync-all`**: sync every enabled source (bypass demand-based filtering); useful when your project spans ecosystems not detected by demand signals, or for building a comprehensive catalog\n\n```bash\nagent-harness discover full --quiet # only errors, warnings suppressed\nagent-harness discover full --summary # aggregate breakdown by reason\nagent-harness discover full --sync-all # full sync of all configured sources\n```\n\nDemand-based filtering (#419) automatically narrows source sync to only ecosystem-relevant sources. After demand detection, `discover full` prints a summary like `[discover full] Detected TypeScript project. Syncing 12/50 demand-relevant sources (38 skipped). Use --sync-all for full sync or --no-sync to skip entirely.` This reduces first-run sync time from 5+ minutes to under 60 seconds for typical single-stack projects. Use `--sync-all` for the legacy full-sync behaviour, or `--no-sync` to skip sync entirely.\n\n`discover sync` now provides persistent indexed harvesting for the built-in marketplace and registry sources that expose trustworthy official feeds, sitemaps, or paginated APIs. That includes the VS Code and Cursor marketplaces, Zed and Pi package galleries, skills.sh, ClawHub's server-rendered plugin catalog, the official MCP registry, and the supported package registries (npm change feed, PyPI, crates.io, Go index, Maven Central, NuGet, RubyGems, Packagist, Hex.pm, ConanCenter, and pub.dev).\n\nCoverage modes remain explicit instead of silently pretending everything is equivalent:\n\n- **direct**: single-pass sources harvested during catalog generation (for example docs and local sources)\n- **rotating**: batch-rotated remote repo sources\n- **indexed**: sources with persistent resumable sync support\n- **sampled**: an honesty label kept only for sources that still lack a trustworthy exhaustive upstream surface in the current implementation\n\nIn the checked-in built-in source registry, the goal is for `sampled` to disappear over time; after the indexed-source expansion it should only show up for newly added or still-unsupported custom sources, not for the main built-in registry families.\n\nThe discovery configuration is assembled from multiple checked-in inputs on purpose:\n\n- `discover/sources.json` = first-class source definitions\n- `discover/source-packs/*.json` = repo-source expansions merged into the registry\n- `discover/official-skills-indexes.json` + `discover/official-upstreams.json` = official index seeds and owner allowlists used during catalog harvest\n\n`discover sources` now records those assembled configuration inputs in `discover/output/source-index.json` so the effective discovery universe is inspectable instead of implicit.\n\nIf you want the widest practical candidate pool before judging recommendation quality, start with `agent-harness discover breadth`. That first-class command runs the full breadth-oriented discovery pass and prints whether the bottleneck currently looks like demand detection, source coverage, selection filtering, or ranking. For the step-by-step workflow and agent-operated version, use [`DISCOVERY-BREADTH-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/DISCOVERY-BREADTH-PLAYBOOK.md).\n\n`discover breadth` is a full discovery pass: it **replaces** the catalog and selection outputs in the state root. Recommendations, mirror bundle locks, install generations, and activation manifests built from the previous catalog are then stale — the command prints a warning naming the affected artifacts (with the previous catalog size vs the new one in its summary), and you must re-run `recommend report` and the affected mirror/install/activate commands afterwards.\n\nEvery command group accepts `--help` or `-h` and exits before preparing lifecycle state. Examples:\n\n```bash\nagent-harness discover --help\nagent-harness wire vscode --help\nagent-harness recommend explain --help\n```\n\n### Detection breadth and vendor signatures\n\nDemand detection is deterministic by default. It does not require an external AI/ML service or API key for normal operation. The scanner combines:\n\n- file-family detector signatures for docs, notebooks, datasets, BI dashboards, finance/trading, media/design, audio/music/video/VFX, CAD/hardware, embedded/firmware, games, mobile, robotics/simulation, DevOps/platform, security/networking, blockchain/smart contracts, business analysis, 3D printing/slicer profiles, marketing/content/CMS/SEO, and research artifacts;\n- ecosystem dependency signatures for npm, PyPI, Dart `pubspec.yaml`, Cargo, Go modules, Maven/Gradle, NuGet, RubyGems, Packagist, SwiftPM, CocoaPods, and related native mobile manifests;\n- vendor/platform signatures for common third-party stacks such as Node, React, Flutter/Dart, Swift, Objective-C, Kotlin, Java Android, C#/.NET MAUI/Xamarin, Java/.NET/Go/Rust/Ruby/PHP backends, Azure, AWS, GCP, Firebase, Supabase, Apify, MCP, AI/ML/DL/RL/MLOps/RAG/vector-search libraries, robotics/simulation, blockchain/security, DevOps/Kubernetes/Helm/Ansible/Pulumi, network automation, finance/trading, BI/reporting, CAD/embedded/3D printing, creative media, and marketing/SEO/content packages;\n- generic language, package-manager, infrastructure, and API markers.\n\nThese signatures live under `src/domains/discovery/` alongside focused demand-profile, source-registry, source-index, source-utilization, catalog-selection, package/reference/local/GitHub/official-index harvester, and catalog utility modules. Support for additional domains or vendors can be added as data-driven detector entries or focused harvester modules instead of one-off project-specific logic. Optional AI-assisted enrichment is available through `discover enrich`, but normal discovery intentionally stays reproducible and offline-capable by default.\n\n### AI-assisted enrichment\n\nAI-assisted enrichment is optional and disabled by default. When configured, it writes a bounded request artifact to `discover/output/ai-enrichment-input.json` and an outcome artifact to `discover/output/ai-enrichment.json` using an OpenAI-compatible chat-completions endpoint. Loopback, private-network, and non-public origins are still rejected before any API key is sent. By default the runtime allows a built-in set of public provider origins, automatically allows the configured endpoint origin when it is valid `https`, and can be extended with `AGENT_HARNESS_AI_ENRICHMENT_ALLOWED_ORIGINS` for compatible gateways or proxies.\n\nThe same guarded endpoint configuration is also reused by `recommend ai-review` and `recommend report --ai-review`. Enrichment remains a sidecar summary; AI review is the bounded stage that can actually suppress or rerank recommendation entries after the deterministic report is built.\n\nSupported enrichment modes are:\n\n- `manual` (default): only run `discover enrich` or explicit `--ai-enrich` wrapper flags\n- `after-select`: automatically evaluate enrichment after selection completes\n- `after-workspace`: automatically evaluate enrichment after a workspace flow finishes\n- `on-ambiguity`: automatically run only when deterministic selection looks uncertain\n- `on-input-change`: automatically run only when the bounded enrichment input changed\n- `ci-only`: automatically evaluate enrichment only in CI/headless contexts\n- `off`: disable automatic enrichment entirely\n\nWhen enrichment runs, the outcome artifact uses explicit statuses such as `disabled`, `skipped`, `completed`, `reused`, and `failed`. Unchanged successful inputs reuse cached results unless you pass `--force`, and CI/headless flows can opt into fail-open or require-enrichment behavior.\n\n```bash\nAGENT_HARNESS_AI_ENRICHMENT_URL=https://api.openai.com/v1/chat/completions\nAGENT_HARNESS_AI_ENRICHMENT_API_KEY=\nAGENT_HARNESS_AI_ENRICHMENT_MODE=manual\nAGENT_HARNESS_AI_ENRICHMENT_MODEL=gpt-4o-mini\n# Optional comma-separated extra allowlist entries for compatible public gateways.\nAGENT_HARNESS_AI_ENRICHMENT_ALLOWED_ORIGINS=https://gateway.example.com\nagent-harness discover enrich\nagent-harness discover full --ai-enrich\nagent-harness workspace cursor --intent frontend --ai-enrich\n```\n\nUse `setup login --provider ai` for configuration guidance. For scenario-based operator guidance, see [`AI-ENRICHMENT-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/AI-ENRICHMENT-PLAYBOOK.md).\n\n### Discover diff\n\nCompare discovery outputs against a baseline state root. Useful for validating that an updated source registry or selection policy changed the expected set of catalog entries.\n\n```bash\nagent-harness discover diff --baseline ../agent-harness-v1\nagent-harness discover diff --baseline ../agent-harness-v1 --json\n```\n\nKey flags:\n\n- **`--baseline `** (required) — State root to compare against\n- **`--json`** — Print the diff report as JSON instead of a human-readable summary\n\nThe report is written to `discover/output/diff-report.json`.\n\n### Discover inspect\n\nPrint catalog entries filtered by `--source` or `--id`. This is a non-mutating lookup into the built catalog.\n\n```bash\nagent-harness discover inspect --source vscode-marketplace\nagent-harness discover inspect --id github/copilot-skills\nagent-harness discover inspect --source npm --limit 10\n```\n\nKey flags:\n\n- **`--source `** — Filter entries by source identifier\n- **`--id `** — Filter entries by asset ID\n- **`--limit `** — Maximum results to display (default: 20)\n\n### Discover environment-index\n\nWrite an experimental read-only query metadata index for selected catalog assets. This index is designed for future query/retrieval flows and does not change mirror, install, activation, or wire behavior.\n\n```bash\nagent-harness discover environment-index\nagent-harness discover environment-index --json\n```\n\nOutput is written to `discover/output/environment-index.json`. The `--json` flag also prints the report to stdout.\n\n### Recommend\n\n```bash\nnpm run recommend:report\nagent-harness recommend\nagent-harness recommend report --ai-review\nagent-harness recommend ai-review --apply\nnpm run recommend:evaluate\nnpm run recommend:update\n```\n\nOmitting the recommendation subcommand defaults to `report`.\n`recommend evaluate` now ends with an aggregate summary so you can spot whether a fixture suite is being carried by exact-stack wins, weak-only generic matches, or broad fallback behavior.\n\n`recommend ai-review` writes `recommend/output/ai-review-input.json` and `recommend/output/ai-review.json`. Use `--host ` to review a single host shortlist and `--apply` to write validated reranks/suppressions back into `recommend/output/report.json`. `recommend report --ai-review` is the one-shot version that rebuilds the deterministic report first and then applies the same bounded AI review stage.\n\nExplain a specific recommendation:\n\n```bash\nagent-harness recommend explain --host vscode --asset \n```\n\nEvaluate golden recommendation fixtures against the current discovery and policy state:\n\n```bash\nagent-harness recommend evaluate\nnpm run recommend:evaluate\n```\n\n`recommend evaluate` runs golden recommendation fixtures and prints an aggregate summary with quality signals including top-rank reason mix, top-rank confidence mix, broad-fallback frequency, and local-availability frequency. Use it to spot whether a fixture suite is being carried by exact-stack wins, weak-only generic matches, or broad fallback behavior.\n\nPrint the merged effective policy for a host:\n\n```bash\nagent-harness recommend policy:print --host shared\n```\n\nIf the selected candidate pool already looks healthy but the final ranking still feels wrong, use [`RECOMMENDATION-POLICY-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/RECOMMENDATION-POLICY-PLAYBOOK.md). For recurring post-wire-in repository drift, use [`WORKSPACE-EVOLUTION-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/WORKSPACE-EVOLUTION-PLAYBOOK.md).\n\n### Mirror\n\n```bash\nnpm run mirror:plan\nnpm run mirror:locks\nnpm run mirror:acquire\nagent-harness mirror plan\nagent-harness mirror locks\nagent-harness mirror acquire\nagent-harness mirror diff\nagent-harness mirror explain --asset \nagent-harness mirror explain --mirror \n```\n\n**`mirror plan`** builds a mirror readiness plan from current discovery outputs. It summarizes the mirror-eligible candidate pool, applies mirror policy, and writes recommendations to `mirror/audit/mirror-plan.json`.\n\n```bash\nagent-harness mirror plan\n```\n\nThe plan includes candidate breakdowns by host and asset kind, the effective mirror policies, and next-action suggestions.\n\n**`mirror locks`** generates initial bundle lock files from selected catalog entries. Each lock file (`mirror/bundles/.lock.json`) defines which assets belong to a mirror bundle before acquisition begins.\n\n```bash\nagent-harness mirror locks\n```\n\n**`mirror acquire`** acquires raw mirror artifacts, writes the mirror index file (`mirror/index.jsonl`), and resolves bundle locks by downloading or verifying each asset referenced in the lock files. High-risk community assets are routed into quarantine.\n\n```bash\nagent-harness mirror acquire\n```\n\n**`mirror diff`** compares the current mirror index file (`mirror/index.jsonl`) against the previous index snapshot, printing added, removed, and changed assets.\n\n```bash\nagent-harness mirror diff\n```\n\nPrevious index state is read from `mirror/index.jsonl.snapshot`; the current index is `mirror/index.jsonl`.\n\n**`mirror explain`** prints the full mirror index entry (`mirror/index.jsonl`), raw content preview, and any available manifest for a specific mirrored artifact. Use `--asset` or `--mirror` to identify the target.\n\n```bash\nagent-harness mirror explain --asset my-asset-id\nagent-harness mirror explain --mirror mirror-abc123\n```\n\nOutput includes the mirror index entry (from `mirror/index.jsonl`), raw artifact root path, optional manifest, and a 4000-character content preview.\n\n### Bundle\n\nBundle commands inspect and explain why assets are present in bundle locks. The `bundle` CLI domain is an alias for `mirror bundle-explain`.\n\n```bash\nagent-harness bundle explain \nagent-harness bundle explain --bundle \n```\n\n**`bundle explain`** explains why assets are present in a given bundle lock. For each asset in the bundle, it shows whether the asset was selected or rejected during catalog selection, its asset kind, compatibility mode, source authority tier, mirror status, and the specific reason for its bundle inclusion.\n\n```bash\nagent-harness bundle explain copilot-vscode-default\nagent-harness bundle explain --bundle opencode-default --json\n```\n\nKey flags:\n\n- **`--bundle `** (or pass the bundle ID as a positional argument) — Bundle lock to explain\n- **`--json`** — Output the full explanation as JSON\n\nThe explanation draws on the catalog selection report, the mirror index file (`mirror/index.jsonl`), and the rejection log to explain each asset's presence in the bundle.\n\n### Quarantine review\n\n```bash\nagent-harness quarantine list\nagent-harness quarantine inspect --asset \nagent-harness quarantine report\nagent-harness quarantine approve --asset --reason \"reviewed source and content\"\nagent-harness quarantine reject --asset --reason \"unsafe prompt or executable behavior\"\nagent-harness quarantine pin --asset --reason \"await ownership proof\"\n```\n\nMirror acquisition routes high-risk or prompt-injection-like community assets into quarantine. Install and activation skip quarantined assets until an explicit review approves them as `approved-with-warning`. `quarantine report` writes `state/quarantine/quarantine-state.json` with current state, reason, first seen, last reviewed, suggested action, and transition evidence. See [`QUARANTINE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/QUARANTINE-PLAYBOOK.md) for review flow.\n\n### Stage / install\n\n```bash\nnpm run install:bundle\nagent-harness install bundle\nagent-harness install native --host vscode\nagent-harness install native --host vscode --operation verify\nagent-harness install native --host vscode --operation install --apply\nagent-harness install native --host vscode --operation remove --apply\nagent-harness install native --host cursor\nagent-harness install native --host cursor --operation verify\nagent-harness install refresh --host copilot-vscode\nagent-harness install refresh --host copilot-vscode --apply\nagent-harness install refresh --host copilot-vscode --due-only\nagent-harness install diff\nagent-harness install diff --host copilot-vscode\nagent-harness install explain --asset \nagent-harness install generations list\nagent-harness install generations list --host opencode\nagent-harness install generations pin --host copilot-vscode --generation --reason \"stable\"\nagent-harness install generations unpin --host copilot-vscode --generation \nagent-harness install generations prune\nagent-harness install reset\nnpm","readmeFilename":"README.md"}
![\"License:](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"TypeScript](\"https://img.shields.io/badge/TypeScript-6.0.3-3178C6?logo=typescript&logoColor=white\"){kind=icon}
\n ![\"Quality](\"https://github.com/ar27111994/agent-harness/actions/workflows/quality.yml/badge.svg\"){kind=icon}
\n ![\"Latest](\"https://img.shields.io/github/v/release/ar27111994/agent-harness?display_name=tag\")
\n ![\"npm](\"https://img.shields.io/npm/v/%40ar27111994%2Fagent-harness?logo=npm&color=CB3837\")
\n ![\"npm](\"https://img.shields.io/npm/dm/%40ar27111994%2Fagent-harness?logo=npm&color=CB3837\")
\n ![\"Sponsor\"](\"https://img.shields.io/badge/Sponsor-support-ff69b4?logo=githubsponsors&logoColor=white\"){kind=icon}
\n ![\"Ask](\"https://deepwiki.com/badge.svg\"){kind=icon}
\n![\"VS](\"https://img.shields.io/badge/VS%20Code%20%2B%20Copilot-007ACC?logo=githubcopilot&logoColor=white\"){kind=icon}
![\"OpenCode\"](\"https://img.shields.io/badge/OpenCode-111827?logo=data:image/svg%2Bxml;base64,PHN2ZyBmaWxsPSJ3aGl0ZSIgcm9sZT0iaW1nIiB2aWV3Qm94PSIwIDAgMjQgMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHRpdGxlPk9wZW5Db2RlPC90aXRsZT48cGF0aCBkPSJNMjIgMjRIMlYwaDIwek0xNyA0LjhIN3YxNC40aDEweiIvPjwvc3ZnPg==\"){kind=icon}
![\"Cursor\"](\"https://img.shields.io/badge/Cursor-000000?logo=cursor&logoColor=white\"){kind=icon}
![\"Zed\"](\"https://img.shields.io/badge/Zed-084CCF?logo=zedindustries&logoColor=white\"){kind=icon}
![\"Claude](\"https://img.shields.io/badge/Claude%20Code-D97757?logo=claude&logoColor=white\"){kind=icon}
![\"Pi\"](\"https://img.shields.io/badge/Pi-FF4F8B?logo=data:image/svg%2Bxml;base64,PHN2ZyBmaWxsPSJ3aGl0ZSIgcm9sZT0iaW1nIiB2aWV3Qm94PSIwIDAgMjQgMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHRpdGxlPlBpPC90aXRsZT48cGF0aCBkPSJNMCAwdjI0aDZ2LTZoNnYtNkg2VjZoNnY2aDZWMFptMTggMTJ2MTJoNlYxMloiLz48L3N2Zz4=\"){kind=icon}
![\"OpenAI](\"https://img.shields.io/badge/OpenAI%20Codex-412991?logo=data:image/svg%2Bxml;base64,PHN2ZyBmaWxsPSJ3aGl0ZSIgdmlld0JveD0iMCAwIDI0IDI0IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik05LjA2NCAzLjM0NGE0LjU3OCA0LjU3OCAwIDAxMi4yODUtLjMxMmMxIC4xMTUgMS44OTEuNTQgMi42NzMgMS4yNzUuMDEuMDEuMDI0LjAxNy4wMzcuMDIxYS4wOS4wOSAwIDAwLjA0MyAwIDQuNTUgNC41NSAwIDAxMy4wNDYuMjc1bC4wNDcuMDIyLjExNi4wNTdhNC41ODEgNC41ODEgMCAwMTIuMTg4IDIuMzk5Yy4yMDkuNTEuMzEzIDEuMDQxLjMxNSAxLjU5NWE0LjI0IDQuMjQgMCAwMS0uMTM0IDEuMjIzLjEyMy4xMjMgMCAwMC4wMy4xMTVjLjU5NC42MDcuOTg4IDEuMzMgMS4xODMgMi4xNy4yODkgMS40MjUtLjAwNyAyLjcxLS44ODcgMy44NTRsLS4xMzYuMTY2YTQuNTQ4IDQuNTQ4IDAgMDEtMi4yMDEgMS4zODguMTIzLjEyMyAwIDAwLS4wODEuMDc2Yy0uMTkxLjU1MS0uMzgzIDEuMDIzLS43NCAxLjQ5NC0uOSAxLjE4Ny0yLjIyMiAxLjg0Ni0zLjcxMSAxLjgzOC0xLjE4Ny0uMDA2LTIuMjM5LS40NC0zLjE1Ny0xLjMwMmEuMTA3LjEwNyAwIDAwLS4xMDUtLjAyNGMtLjM4OC4xMjUtLjc4LjE0My0xLjIwNC4xMzhhNC40NDEgNC40NDEgMCAwMS0xLjk0NS0uNDY2IDQuNTQ0IDQuNTQ0IDAgMDEtMS42MS0xLjMzNWMtLjE1Mi0uMjAyLS4zMDMtLjM5Mi0uNDE0LS42MTdhNS44MSA1LjgxIDAgMDEtLjM3LS45NjEgNC41ODIgNC41ODIgMCAwMS0uMDE0LTIuMjk4LjEyNC4xMjQgMCAwMC4wMDYtLjA1Ni4wODUuMDg1IDAgMDAtLjAyNy0uMDQ4IDQuNDY3IDQuNDY3IDAgMDEtMS4wMzQtMS42NTEgMy44OTYgMy44OTYgMCAwMS0uMjUxLTEuMTkyIDUuMTg5IDUuMTg5IDAgMDEuMTQxLTEuNmMuMzM3LTEuMTEyLjk4Mi0xLjk4NSAxLjkzMy0yLjYxOC4yMTItLjE0MS40MTMtLjI1MS42MDEtLjMzLjIxNS0uMDg5LjQzLS4xNjQuNjQ2LS4yMjdhLjA5OC4wOTggMCAwMC4wNjUtLjA2NiA0LjUxIDQuNTEgMCAwMS44MjktMS42MTUgNC41MzUgNC41MzUgMCAwMTEuODM3LTEuMzg4em0zLjQ4MiAxMC41NjVhLjYzNy42MzcgMCAwMDAgMS4yNzJoMy42MzZhLjYzNy42MzcgMCAxMDAtMS4yNzJoLTMuNjM2ek04LjQ2MiA5LjIzYS42MzcuNjM3IDAgMDAtMS4xMDYuNjMxbDEuMjcyIDIuMjI0LTEuMjY2IDIuMTM2YS42MzYuNjM2IDAgMTAxLjA5NS42NDlsMS40NTQtMi40NTVhLjYzNi42MzYgMCAwMC4wMDUtLjY0TDguNDYyIDkuMjN6Ii8+PC9zdmc+\"){kind=icon}
![\"skills\"](\"https://img.shields.io/badge/skills-5B8DEF?logo=codecademy&logoColor=white\"){kind=icon}
![\"agents\"](\"https://img.shields.io/badge/agents-7C3AED?logo=probot&logoColor=white\"){kind=icon}
![\"instructions\"](\"https://img.shields.io/badge/instructions-0F766E?logo=markdown&logoColor=white\"){kind=icon}
![\"workflows\"](\"https://img.shields.io/badge/workflows-F59E0B?logo=githubactions&logoColor=white\"){kind=icon}
![\"prompt](\"https://img.shields.io/badge/prompt%20packs-DB2777?logo=huggingface&logoColor=white\"){kind=icon}
![\"MCP](\"https://img.shields.io/badge/MCP%20servers-2563EB?logo=docker&logoColor=white\"){kind=icon}
![\"plugins\"](\"https://img.shields.io/badge/plugins-16A34A?logo=gradle&logoColor=white\"){kind=icon}
![\"hooks\"](\"https://img.shields.io/badge/hooks-DC2626?logo=zap&logoColor=white\"){kind=icon}
![\"extensions\"](\"https://img.shields.io/badge/extensions-0891B2?logo=vscodium&logoColor=white\"){kind=icon}
![\"reference](\"https://img.shields.io/badge/reference%20packs-64748B?logo=gitbook&logoColor=white\"){kind=icon}
![\"ARD](\"https://img.shields.io/badge/ARD-v1.0-6366F1?logo=data:image/svg%2Bxml;base64,PHN2ZyBmaWxsPSJ3aGl0ZSIgdmlld0JveD0iMCAwIDI0IDI0IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0xMiAyTDIgN3YxMGwxMCA1IDEwLTVWN0wxMiAyem0wIDIuMTY0bDcgMy41djcuNjcybC03IDMuNS03LTMuNVY3LjY2NGw3LTMuNXoiLz48L3N2Zz4=\"){kind=icon}