@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -7,6 +7,47 @@ release.
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-09-19
+
+### Changed
+
+- **BREAKING: `install`, `status`, `plan` and `uninstall` print a human
+  summary, not JSON.** Typing `install` and getting several hundred lines of
+  JSON made success unreadable; the result object is now rendered for a
+  person on stdout — what changed, grouped by coding agent, and the restart
+  each one needs. A run with nothing to do is one line. Conflicts, drift and
+  manual steps are never collapsed: each names its file and its remedy, and
+  an agent this project has not installed is never named at all. Pass
+  `--json` for the previous object, unchanged apart from the key rename
+  below, and `--verbose` for the per-file detail alongside the summary.
+  **Every skill, script or agent parsing this output must add `--json`.**
+- **BREAKING: `--host` is now `--agent`, with no alias.** `--host` is
+  rejected as an unknown option (exit 2, with runnable `--agent` help), the
+  `hosts` key in every result body is now `agents`, and the lock file records
+  `agents`. A lock written by an earlier version under `hosts` is still read
+  and is rewritten as `agents` on the next run, so an existing install keeps
+  its recorded selection. Consistent with the earlier
+  `--no-companions` -> `--no-extra-components` break.
+  **WARNING — the lock migration is one-way:** writing `agents` drops the
+  legacy `hosts` key, so after any run of this version an older pinned CLI
+  (`npx …@0.1.6`) exits 2 in that repository with "no --host given, this
+  repository has no recorded install". Verified against the published 0.1.6
+  tarball.
+- `install` invoked with a bad flag now reports `install`, not `apply`, in
+  its usage help.
+
+### Fixed
+
+- `status` no longer labels a conflict as "edited since install". Its
+  `drift[]` entries now carry the action's `state`, and the human renderer
+  titles conflicts as conflicts.
+
+## [0.1.6] - 2026-09-18
+
+### Changed
+
+- `README.md` only (commit subject: "Test"). No code change.
+
 ## [0.1.5] - 2026-09-17
 
 ### Fixed

package/CONTRIBUTING.md

@@ -15,7 +15,7 @@ npm run gen:check                # generated adapters match their sources
 node scripts/check-pack.mjs      # the tarball matches the files allow-list
 ```
 
-If you edited an agent or a skill, regenerate the host adapters first and
+If you edited an agent or a skill, regenerate the per-agent adapters first and
 commit the result:
 
 ```bash
@@ -29,14 +29,23 @@ npm run gen
   `scripts/gen-copilot-agents.mjs`. Never hand-edit them — run `npm run gen`
   and commit the output. `npm run gen:check` fails the build on drift.
 - **Every `SKILL.md` stays under 8192 bytes**, Codex's effective cap and the
-  smallest of the four hosts'. A test enforces it. When a skill grows past the
-  cap, move material into `reference/*.md` beside it — that is
+  smallest of the four coding agents'. A test enforces it. When a skill grows
+  past the cap, move material into `reference/*.md` beside it — that is
   **reorganisation, never compression**. Audit the split against the
   pre-split file line by line; do not drop meaning to make the number work.
-- **Skills stay host-neutral.** No `${CLAUDE_SKILL_DIR}`, no `$ARGUMENTS`, no
+- **Skills stay agent-neutral.** No `${CLAUDE_SKILL_DIR}`, no `$ARGUMENTS`, no
   `SendMessage` or `subagent_type`, no literal `.claude/…` path. Any prose that
   asks the user a question names both Claude Code's and Codex's question
   tools, not just one.
+- **The result object is the model; `lib/render.mjs` is only a view.** Every
+  command builds one body, `--json` prints it verbatim and the human summary
+  is rendered from that same body — never assembled beside it. The renderer is
+  pure `body -> string` with no I/O, so it is unit-tested in
+  `test/render.test.mjs` without a terminal. Human text goes to stdout (it is
+  the result); only the interactive picker and warnings go to stderr.
+- **Test suites pass `--json`.** `test/helpers.mjs`'s `run()` appends it for
+  every call; only a suite that is about the human output opts out with
+  `{ json: false }`.
 - **The installer never prompts, never fetches, and writes atomically.**
   Every file is written to a temporary path and renamed. A change that breaks
   any of those three properties is a change to the contract this package

package/README.md

@@ -4,6 +4,8 @@ The `sw-*` skills and sub-agents for Shopware 6 projects: they turn a briefing
 into a PRD, a PRD into a technical spec, a spec into tested code, and tested
 code into a project wiki page.
 
+New line
+
 It ships as **one npm package carrying an installer**. The installer copies the
 skills and agents into whichever coding agents your repository uses and
 registers the MCP servers and permission rules they depend on. Nothing is
@@ -49,26 +51,39 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 
 | Command | What it does |
 | --- | --- |
-| `install` | installs into the resolved host(s) (see Flags below); the same as `apply --yes` |
+| `install` | installs into the resolved coding agent(s) (see Flags below); the same as `apply --yes` |
 | `status` | read-only; what is installed, what drifted, which optional extra components are present |
 | `plan` | the exact changes, written as a diff; writes nothing |
 | `apply --yes` | performs them |
 | `uninstall --yes` | removes what the lock file records |
 | `guide` | the install protocol, the single source of truth |
 
-Flags: `--host claude-code|codex|copilot|cursor` (repeatable), `--scope
+Flags: `--agent claude-code|codex|copilot|cursor` (repeatable), `--scope
 project|user` (default `project`), `--root <path>` (default the current
 directory), `--yes` (required by `apply` and `uninstall` — `install` implies
-it), and `--no-extra-components` (skip detection of the optional editor
-packages).
-
-`install`/`apply` resolve which host(s) to write into, in order: `--host` if
-given; else the hosts a lock file already records (a re-run needs no
-question); else, with a terminal attached, an interactive picker; else exit 2
-with the four `install --host <h>` commands as `help` — it never guesses and
-never hangs. `status` and `uninstall` are unaffected by this and keep
-covering every host by default; `plan` writes nothing, so with no `--host` and
-no lock it previews all four and says so.
+it), `--no-extra-components` (skip detection of the optional editor
+packages), `--json` and `--verbose` (see Output below).
+
+`install`/`apply` resolve which coding agent(s) to write into, in order:
+`--agent` if given; else the agents a lock file already records (a re-run
+needs no question); else, with a terminal attached, an interactive picker;
+else exit 2 with the four `install --agent <a>` commands as `help` — it never
+guesses and never hangs. `status` and `uninstall` are unaffected by this and
+keep covering every agent by default; `plan` writes nothing, so with no
+`--agent` and no lock it previews all four and says so.
+
+### Output
+
+`install`, `status`, `plan` and `uninstall` print a short human summary on
+stdout — what changed, grouped by coding agent, and the restart each one
+needs. When nothing changed, that is a single line. Conflicts, drift and
+manual steps are always shown in full, with the file and the remedy, because
+those are the only things you have to act on.
+
+`--json` prints the result object instead: the same body, with the per-file
+detail, a `next_step` on every success and a `help` array of runnable commands
+on every error. **Anything parsing this output must pass `--json`.**
+`--verbose` keeps the human summary but adds the per-file detail.
 
 ## Install
 
@@ -84,9 +99,9 @@ The command's output tells you which ones and how.
 
 `apply` refuses without `--yes`. Neither `apply` nor `install` prompts for
 consent — typing the verb, or passing `--yes`, is the consent — but with no
-`--host`, no existing lock and no terminal (Codex's question tool does not
+`--agent`, no existing lock and no terminal (Codex's question tool does not
 block outside Plan mode, and CI has no terminal either), it exits 2 rather
-than guess. Add `--host claude-code` (repeatable) to install into one agent,
+than guess. Add `--agent claude-code` (repeatable) to install into one agent,
 and `--scope user` to install into your home directory instead of this
 repository. The default scope is the project — nothing is written under `~`
 unless you ask.
@@ -127,10 +142,11 @@ keeps anything you hand-edited, and tells you what it kept.
 
 ### From a skill
 
-`sw-setup` is a stub: it runs `status`, renders the table, asks once, and runs
-`apply --yes`. It deliberately restates none of the protocol, because an
-installed skill file goes stale and the CLI does not. Anything that needs the
-protocol runs:
+`sw-setup` is a stub: it runs `status --json`, renders the table, asks once,
+and runs `apply --yes --json`. A skill always passes `--json`; the bare
+commands print the human summary. It deliberately restates none of the
+protocol, because an installed skill file goes stale and the CLI does not.
+Anything that needs the protocol runs:
 
 ```bash
 npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
@@ -163,12 +179,13 @@ npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
 
 Re-run `install` afterwards so the new skill lands in each host. `status`'s
 `extra_components[]` array reports the pinned `version` and the exact `install`
-command for whichever one is missing.
+command for whichever one is missing (`status --json`).
 
 Re-running `install` is safe at any time: it rewrites only what it owns,
 leaves anything you hand-edited alone (reported as drift), and records the new
-version in the lock file. Restart your coding agent afterwards — every host
-reads its configuration at startup.
+version in the lock file. It prints one line when there was nothing to change.
+Restart your coding agent afterwards — every host reads its configuration at
+startup.
 
 `@latest` matters. Without it, `npx` can reuse a copy already in its cache or
 in this project's `node_modules`, so you would silently keep running the
@@ -332,7 +349,7 @@ repository is development-only.**
 
 ### Every `SKILL.md` is capped at 8 KB
 
-Codex's effective skill-body limit is the smallest of the four hosts', so it is
+Codex's effective skill-body limit is the smallest of the four coding agents', so it is
 the budget every skill is written to. Overflow lives in `reference/*.md` beside
 each `SKILL.md`, loaded on demand. A test enforces the cap, so the gate is
 mechanical rather than a review habit.
@@ -341,7 +358,7 @@ mechanical rather than a review habit.
 
 | Symptom | What it means | What to do |
 | --- | --- | --- |
-| `state: "conflict"` | A file we did not install already sits at that path. It is never overwritten. | Move or delete the existing file, or `--host`-scope the run away from it, then re-run `apply`. |
+| `state: "conflict"` | A file we did not install already sits at that path. It is never overwritten. | Move or delete the existing file, or `--agent`-scope the run away from it, then re-run `apply`. |
 | `state: "drift"` | You (or something else) edited a file this installer wrote. It is left alone on every later run. | Nothing to fix — this is by design. Re-run `status` to confirm it is the only thing reported. |
 | A manual step for `.vscode/mcp.json` | That file is JSONC (comments or trailing commas). Rewriting it would destroy your notes, so it is never touched automatically. | Add the printed snippet to `.vscode/mcp.json` yourself, under the `servers` key. |
 | `.codex/` reported read-only | Codex's default workspace-write sandbox makes `.codex/` and `.agents/` read-only from inside a Codex session. | Run the installer from a plain shell, not from inside Codex. |

package/bin/cli.mjs

@@ -28,23 +28,23 @@ const COMMANDS = {
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
-  install    [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  status     [--host <h>] [--scope project|user] [--root <path>]
-  plan       [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  uninstall  --yes [--host <h>] [--scope project|user] [--root <path>]
+  install    [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
+  status     [--agent <a>] [--scope project|user] [--root <path>]
+  plan       [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
+  apply      --yes [--agent <a>] [--scope project|user] [--root <path>] [--no-extra-components]
+  uninstall  --yes [--agent <a>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
   install is apply --yes under a friendlier name: the whole install in one
   command, no --yes needed — typing the verb is the consent for that write;
-  it can still ask which host(s), see below.
+  it can still ask which coding agent(s), see below.
 
-  <h> is one of: claude-code, codex, copilot, cursor. Repeat --host to select
-  several. install/apply resolve which host(s) to use, in order: --host if
-  given; else the hosts already recorded in the lock file, if one exists;
+  <a> is one of: claude-code, codex, copilot, cursor. Repeat --agent to select
+  several. install/apply resolve which agent(s) to use, in order: --agent if
+  given; else the agents already recorded in the lock file, if one exists;
   else, with a terminal attached, an interactive picker; else exit 2 with
-  the four "... install --host <h>" commands as help. status and uninstall
-  keep covering every host by default.
+  the four "... install --agent <a>" commands as help. status and uninstall
+  keep covering every agent by default.
 
   --scope defaults to project: nothing is written under your home directory
   unless you ask for it. --root defaults to the current directory.
@@ -52,8 +52,12 @@ const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
   --no-extra-components skips the two optional extra-component skills (Specs
   Editor, Tender Discovery Tool) even when the package is present locally.
 
-Every command prints one JSON object on stdout carrying a next_step. Run
-\`sw-ecosystem-agentic-harness guide\` first — it is the install protocol.`;
+  --json      print the result object instead of the human summary
+  --verbose   include the per-file detail --json carries
+
+install, status, plan and uninstall print a short human summary on stdout.
+Add --json for the machine-readable object, which always carries a next_step.
+Run \`sw-ecosystem-agentic-harness guide\` first — it is the install protocol.`;
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];

package/lib/commands.mjs

@@ -1,8 +1,8 @@
 // status / plan / apply / uninstall.
 //
-// Error aggregation lives here: each host is planned and applied inside its
-// own try, failures accumulate, and the process fails only after every host
-// has been attempted. One unwritable host must not abort the others.
+// Error aggregation lives here: each agent is planned and applied inside its
+// own try, failures accumulate, and the process fails only after every agent
+// has been attempted. One unwritable agent must not abort the others.
 
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
@@ -11,11 +11,12 @@ import {
   CONTENT_VERSION, LOCK_FILE, PKG_NAME, PKG_VERSION, agents, skills,
 } from './content.mjs';
 import { exists, isWritable, abs } from './fsx.mjs';
-import { HOSTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
+import { AGENTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
 import * as lockfile from './lock.mjs';
 import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
 import { probeAll } from './extra-components.mjs';
-import { askHosts } from './prompt.mjs';
+import { askAgents } from './prompt.mjs';
+import { RESTART } from './render.mjs';
 
 const RUN = 'sw-ecosystem-agentic-harness';
 
@@ -25,24 +26,28 @@ class UsageError extends Error {
 
 /** Parse the flags every command shares. */
 export function buildContext(argv, command) {
-  const hosts = [];
+  const agents = [];
   let scope = 'project';
   let root = process.cwd();
   let yes = false;
   let projectWiki;
   let extraComponents = true;
+  let asJson = false;
+  let verbose = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') { yes = true; continue; }
     if (arg === '--no-extra-components') { extraComponents = false; continue; }
-    if (arg === '--host') {
+    if (arg === '--json') { asJson = true; continue; }
+    if (arg === '--verbose') { verbose = true; continue; }
+    if (arg === '--agent') {
       const value = argv[++i];
-      if (!HOSTS.includes(value)) {
-        throw new UsageError(`unknown --host ${value ?? '(missing)'}`,
-          HOSTS.map((h) => `${RUN} ${command} --host ${h}`));
+      if (!AGENTS.includes(value)) {
+        throw new UsageError(`unknown --agent ${value ?? '(missing)'}`,
+          AGENTS.map((a) => `${RUN} ${command} --agent ${a}`));
       }
-      hosts.push(value);
+      agents.push(value);
       continue;
     }
     if (arg === '--scope') {
@@ -59,17 +64,20 @@ export function buildContext(argv, command) {
     throw new UsageError(`unknown option ${arg}`, [`${RUN} guide`, `${RUN} ${command}`]);
   }
 
+  out.setFormat(asJson ? 'json' : 'human');
+  out.setVerbose(verbose);
+
   // User scope writes under $HOME; project scope stays in the repository.
   if (scope === 'user') root = homedir();
   root = resolve(root);
   if (!exists(root)) throw new UsageError(`--root does not exist: ${root}`, [`${RUN} ${command} --root .`]);
 
   return {
-    root, scope, yes, projectWiki, extraComponents,
-    // Empty means "nothing chosen yet" — resolveHosts() applies the
+    root, scope, yes, projectWiki, extraComponents, json: asJson, verbose,
+    // Empty means "nothing chosen yet" — resolveAgents() applies the
     // per-command fallback once the lock (and, for apply/install, a TTY)
     // is available to consult.
-    hosts: [...new Set(hosts)],
+    agents: [...new Set(agents)],
     platform: process.platform,
     version: PKG_VERSION,
     lock: null,
@@ -77,35 +85,36 @@ export function buildContext(argv, command) {
 }
 
 /**
- * The host-resolution chain every write command shares:
- *   1. `--host` given → use exactly those. No question.
- *   2. else a lock already records hosts → reuse them. This is an update;
- *      the choice was already made. No question.
+ * The agent-resolution chain every write command shares:
+ *   1. `--agent` given → use exactly those. No question.
+ *   2. else a lock already records agents → reuse them. This is an update;
+ *      the choice was already made. No question. A lock written before the
+ *      rename records them under `hosts`; lib/lock.mjs reads either.
  *   3. else a TTY is attached (apply/install only) → ask, via lib/prompt.mjs.
  *   4. else → UsageError, exit 2, `help` lists the four runnable commands.
  *
- * `status` and `uninstall` keep their old, ungated default of every host —
+ * `status` and `uninstall` keep their old, ungated default of every agent —
  * reporting and removal are not consent points. `plan` writes nothing, so it
  * never reaches step 3: steps 1-2, then it previews all four and says so.
  *
  * Call after `loadLock(ctx)` so `ctx.lock` is populated for step 2.
  */
-async function resolveHosts(ctx, command) {
-  if (ctx.hosts.length) return { hosts: [...new Set(ctx.hosts)], chosen: true };
-  if (command === 'status' || command === 'uninstall') return { hosts: [...HOSTS], chosen: true };
+async function resolveAgents(ctx, command) {
+  if (ctx.agents.length) return { agents: [...new Set(ctx.agents)], chosen: true };
+  if (command === 'status' || command === 'uninstall') return { agents: [...AGENTS], chosen: true };
 
-  const lockHosts = ctx.lock?.hosts ? Object.keys(ctx.lock.hosts) : [];
-  if (lockHosts.length) return { hosts: lockHosts, chosen: true };
+  const recorded = ctx.lock?.agents ? Object.keys(ctx.lock.agents) : [];
+  if (recorded.length) return { agents: recorded, chosen: true };
 
-  if (command === 'plan') return { hosts: [...HOSTS], chosen: false };
+  if (command === 'plan') return { agents: [...AGENTS], chosen: false };
 
   if (process.stdin.isTTY) {
-    const chosen = await askHosts(HOSTS);
-    if (chosen) return { hosts: chosen, chosen: true };
+    const chosen = await askAgents(AGENTS);
+    if (chosen) return { agents: chosen, chosen: true };
   }
   throw new UsageError(
-    'no --host given, this repository has no recorded install, and there is no terminal to ask which host(s) to use',
-    HOSTS.map((h) => `${RUN} ${command} --host ${h}`),
+    'no --agent given, this repository has no recorded install, and there is no terminal to ask which coding agent(s) to use',
+    AGENTS.map((a) => `${RUN} ${command} --agent ${a}`),
   );
 }
 
@@ -121,13 +130,13 @@ function loadLock(ctx) {
   return ctx.lock;
 }
 
-/** Preview every action for the selected hosts, aggregating per-host failures. */
+/** Preview every action for the selected agents, aggregating per-agent failures. */
 function previewAll(ctx) {
   const errors = [];
   const actions = [];
-  for (const host of ctx.hosts) {
+  for (const host of ctx.agents) {
     try {
-      const forHost = dedupe(buildPlan({ ...ctx, hosts: [host], selectedHosts: ctx.hosts }));
+      const forHost = dedupe(buildPlan({ ...ctx, agents: [host], selectedAgents: ctx.agents }));
       for (const action of forHost) {
         try {
           actions.push(preview(action, ctx));
@@ -175,13 +184,13 @@ export async function status(argv) {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, 'status'));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, 'status'));
 
   const detections = await detectAll(ctx);
   const { actions, errors } = previewAll(ctx);
   const byHost = new Map(detections.map((d) => [d.id, d]));
 
-  const hosts = detections.map((d) => {
+  const agentStates = detections.map((d) => {
     const mine = actions.filter((a) => a.host === d.id || a.host === 'shared');
     let state = 'absent';
     if (d.detected) {
@@ -189,7 +198,7 @@ export async function status(argv) {
       const bad = mine.filter((a) => a.state === 'conflict' || a.state === 'drift');
       if (bad.length) state = bad.some((a) => a.state === 'conflict') ? 'conflict' : 'drift';
       else if (pending.length === 0) state = 'ok';
-      else state = lock?.hosts?.[d.id] ? 'drift' : 'not-installed';
+      else state = lock?.agents?.[d.id] ? 'drift' : 'not-installed';
     }
     return {
       id: d.id, detected: d.detected, marker: d.marker, writable: d.writable,
@@ -197,14 +206,16 @@ export async function status(argv) {
     };
   });
 
+  // `drift[]` carries conflicts too; `state` says which, so a file someone
+  // else wrote is not reported back to the user as their own edit.
   const drift = actions.filter((a) => a.state === 'drift' || a.state === 'conflict').map((a) => ({
-    target: a.target, expected: a.hash ?? null, actual: a.prior ?? null,
+    target: a.target, state: a.state, expected: a.hash ?? null, actual: a.prior ?? null,
     reason: a.reason, remedy: a.remedy,
   }));
 
   const pending = actions.filter((a) => isWritableState(a.state)).length;
   const worst = ['conflict', 'drift', 'not-installed', 'ok', 'absent']
-    .find((s) => hosts.some((h) => h.state === s)) ?? 'absent';
+    .find((s) => agentStates.some((a) => a.state === s)) ?? 'absent';
 
   const extraComponents = ctx.extraComponents === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
     id: p.id, package: p.pkg, version: p.version, label: p.label,
@@ -231,7 +242,7 @@ export async function status(argv) {
     next_step: next,
     help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
     inventory: { skills: skills().length, agents: agents().length },
-    hosts, extra_components: extraComponents, drift,
+    agents: agentStates, extra_components: extraComponents, drift,
     declined: lock?.declined ?? [],
     manual: lock?.manual ?? [],
     errors,
@@ -251,13 +262,13 @@ export async function plan(argv) {
     }
     throw e;
   }
-  const { hosts, chosen } = await resolveHosts(ctx, 'plan');
-  ctx.hosts = hosts;
+  const { agents: chosenAgents, chosen } = await resolveAgents(ctx, 'plan');
+  ctx.agents = chosenAgents;
   const { actions, errors } = previewAll(ctx);
   const summary = summarise(actions);
   const changes = summary.create + summary.update;
 
-  let next = chosen ? '' : 'No --host given and no existing install found, so this previews all four hosts. ';
+  let next = chosen ? '' : 'No --agent given and no existing install found, so this previews all four agents. ';
   next += changes
     ? `Nothing was written. Run \`${RUN} apply --yes\` to perform the ${changes} change(s).`
       + (summary.conflict || summary.manual
@@ -271,7 +282,7 @@ export async function plan(argv) {
 
   return out.ok('plan', head(ctx, {
     summary, next_step: next,
-    help: [`${RUN} apply --yes`, ...ctx.hosts.map((h) => `${RUN} apply --yes --host ${h}`)],
+    help: [`${RUN} apply --yes`, ...ctx.agents.map((a) => `${RUN} apply --yes --agent ${a}`)],
     actions: actions.map(publicAction),
     errors,
   }));
@@ -279,15 +290,8 @@ export async function plan(argv) {
 
 // ------------------------------------------------------------------- apply
 
-const RESTART_HELP = {
-  'claude-code': 'Restart Claude Code, or run `/mcp` in the running session',
-  codex: 'Restart `codex` — .codex/config.toml is read once at startup',
-  copilot: 'Reload the VS Code window (Developer: Reload Window) for .vscode/mcp.json',
-  cursor: 'Restart Cursor so it re-reads .cursor/mcp.json',
-};
-
 export async function apply(argv, label = 'apply') {
-  const ctx = buildContext(argv, 'apply');
+  const ctx = buildContext(argv, label);
   if (!ctx.yes) {
     return out.usage(label, 'apply refuses to write without --yes',
       [`${RUN} plan`, `${RUN} apply --yes`]);
@@ -303,7 +307,7 @@ export async function apply(argv, label = 'apply') {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, label));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, label));
 
   // An apply we cannot record is an apply we cannot undo. Refuse up front
   // rather than leave the user with files and no way back.
@@ -316,11 +320,11 @@ export async function apply(argv, label = 'apply') {
 
   const { actions, errors } = previewAll(ctx);
   const results = [];
-  const perHost = new Map(ctx.hosts.map((h) => [h, { id: h, created: 0, updated: 0, unchanged: 0, failed: 0 }]));
+  const perAgent = new Map(ctx.agents.map((a) => [a, { id: a, created: 0, updated: 0, unchanged: 0, failed: 0 }]));
   const manual = [];
 
   for (const action of actions) {
-    const bucket = perHost.get(action.host) ?? perHost.get(ctx.hosts[0]);
+    const bucket = perAgent.get(action.host) ?? perAgent.get(ctx.agents[0]);
     if (action.state === 'manual') {
       manual.push({ target: action.target, reason: action.reason, remedy: action.remedy });
       results.push({ ...publicAction(action), state: 'manual' });
@@ -333,7 +337,7 @@ export async function apply(argv, label = 'apply') {
     }
     try {
       const entry = execute(action, ctx);
-      lock = lockfile.record(lock, [entry], { host: action.host === 'shared' ? undefined : action.host });
+      lock = lockfile.record(lock, [entry], { agent: action.host === 'shared' ? undefined : action.host });
       if (bucket) bucket[action.state === 'create' ? 'created' : 'updated'] += 1;
       results.push({ ...publicAction(action), state: action.state === 'create' ? 'created' : 'updated' });
     } catch (e) {
@@ -355,8 +359,8 @@ export async function apply(argv, label = 'apply') {
   for (const entry of manual) {
     lock = lockfile.record(lock, [{ kind: 'manual', target: entry.target, remedy: entry.remedy }]);
   }
-  for (const host of ctx.hosts) {
-    lock = { ...lock, hosts: { ...lock.hosts, [host]: { installed_at: new Date().toISOString(), version: PKG_VERSION } } };
+  for (const agent of ctx.agents) {
+    lock = { ...lock, agents: { ...lock.agents, [agent]: { installed_at: new Date().toISOString(), version: PKG_VERSION } } };
   }
   lockfile.write(ctx.root, lock);
 
@@ -371,12 +375,12 @@ export async function apply(argv, label = 'apply') {
     failed: results.filter((r) => r.state === 'failed').length,
   };
 
-  const help = ctx.hosts.map((h) => RESTART_HELP[h]).filter(Boolean);
+  const help = ctx.agents.map((a) => RESTART[a]).filter(Boolean);
   help.push(`${RUN} status`);
 
   let next = summary.failed
     ? `${summary.failed} change(s) failed — see \`errors\`. Fix those, then re-run \`${RUN} apply --yes\`.`
-    : `Restart the hosts listed in \`help\` so they pick up the new skills, agents and MCP servers.`
+    : `Restart the coding agents listed in \`help\` so they pick up the new skills, sub-agents and MCP servers.`
       + (manual.length ? ` Then finish the ${manual.length} manual step(s) in \`manual\`.` : '');
   const installs = skippedInstalls(results);
   if (installs.length) {
@@ -385,7 +389,7 @@ export async function apply(argv, label = 'apply') {
 
   const body = head(ctx, {
     summary, lock_file: LOCK_FILE, next_step: next, help,
-    hosts: [...perHost.values()], actions: results, manual, errors,
+    agents: [...perAgent.values()], actions: results, manual, errors,
   });
   return summary.failed ? out.failure(label, `${summary.failed} change(s) failed`, body) : out.ok(label, body);
 }
@@ -412,7 +416,7 @@ export async function uninstall(argv) {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, 'uninstall'));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, 'uninstall'));
 
   if (!lock) {
     // No record means no evidence of what we own. Guessing here would delete
@@ -425,7 +429,7 @@ export async function uninstall(argv) {
     }));
   }
 
-  const selected = new Set(ctx.hosts);
+  const selected = new Set(ctx.agents);
   const all = lockfile.entries(lock);
   const mine = all.filter((e) => !e.host || selected.has(e.host) || e.host === 'shared');
 
@@ -452,7 +456,7 @@ export async function uninstall(argv) {
   const prunedDirs = pruneDirs(lock.dirs ?? [], ctx);
   const failed = errors.length;
 
-  if (failed === 0 && survivors.length === 0 && selected.size === HOSTS.length) {
+  if (failed === 0 && survivors.length === 0 && selected.size === AGENTS.length) {
     // Everything we recorded is gone; the lock has nothing left to describe.
     const { removeFile } = await import('./fsx.mjs');
     removeFile(lockfile.lockPath(ctx.root));
@@ -466,8 +470,8 @@ export async function uninstall(argv) {
     summary: { removed, reverted, kept: kept.length, missing: missing.length, failed },
     next_step: failed
       ? `${failed} item(s) could not be removed — see \`errors\`.`
-      : `Restart your hosts.` + (kept.length ? ` ${kept.length} file(s) were left in place because you edited them — they are listed under \`kept\`.` : ''),
-    help: [...ctx.hosts.map((h) => RESTART_HELP[h]).filter(Boolean), `${RUN} status`],
+      : `Restart your coding agent(s).` + (kept.length ? ` ${kept.length} file(s) were left in place because you edited them — they are listed under \`kept\`.` : ''),
+    help: [...ctx.agents.map((a) => RESTART[a]).filter(Boolean), `${RUN} status`],
     kept, missing, pruned_dirs: prunedDirs, errors,
   });
   return failed ? out.failure('uninstall', `${failed} item(s) could not be removed`, body) : out.ok('uninstall', body);
@@ -484,9 +488,9 @@ function rebuild(lock, survivors, selected) {
     else if (entry.kind === 'json-merge') json_pointers.push(entry);
     else fences.push(entry);
   }
-  const hosts = { ...lock.hosts };
-  for (const host of selected) delete hosts[host];
-  return { ...lock, files, json_pointers, rules, fences, hosts };
+  const agents = { ...lock.agents };
+  for (const agent of selected) delete agents[agent];
+  return { ...lock, files, json_pointers, rules, fences, agents };
 }
 
 export { UsageError };