@nikovirtala/adr 0.3.0 → 0.4.0

package/README.md

@@ -32,6 +32,8 @@ Each decision has a canonical id (`k3f9q8a1`). Accepted decisions also get a num
 ```sh
 # Set up: write adr.toml and starter templates; never overwrites a file.
 adr init --template nygard --template madr --commit
+adr init --skill                                     # also the agent skill and an AGENTS.md pointer
+adr init --skill --skill-dir .kiro/skills/adr
 
 # Propose: render a draft from a template, write the body and the proposed event, and stage them.
 adr new "Use Aurora for orders" --section context="We need SQL." --section scope=services/orders
@@ -67,6 +69,10 @@ adr list --since ORIG_HEAD                 # only decisions with events added si
 adr show ADR-0001 --history
 adr list --ref v1.2.0                      # time travel: the log as of any ref
 
+# Search ids, titles, bodies and notes: every word must match; active decisions unless --all.
+adr search orders aurora
+adr search dynamodb --all
+
 # Verify the log: the whole tree, a range, or the staged changes (for a pre-commit hook).
 adr verify
 adr verify --base origin/main --format github
@@ -79,6 +85,9 @@ adr index --check
 # Git hooks: install adr in ledger's shared hook shims, or print the config for a hook manager.
 adr hooks install
 adr hooks print --manager lefthook
+
+# The MCP server for agents, over stdio; start it from an MCP client (see "MCP server").
+adr mcp
 ```
 
 - `new` takes `--template <name>` (default `nygard`; built-ins `nygard`, `madr`, `y-statement`, or your own `<root>/templates/<name>.md`), `--section <id>=<markdown>` (repeatable), `--supersedes <decision>` (repeatable), and `--edit`/`--no-edit`. It opens `$VISUAL` or `$EDITOR` with `--edit`, or by default in an interactive terminal; an editor failure never loses your edits and never commits content you didn't confirm.
@@ -93,6 +102,8 @@ adr hooks print --manager lefthook
 - `list --since <rev>` lists only the decisions with event files added between `<rev>` and HEAD (or `--ref`), each with the new event types, such as `[new: accepted]`; it prints nothing when the log didn't change.
 - In a shallow clone, numbers need history the clone lacks. With a committed index, adr reads them from `index.md` in the commit being read (`--ref`, else HEAD) and notes `numbers come from docs/adr/index.md (shallow clone)`; without one, decisions display by id until you run `git fetch --unshallow`. Nothing is fetched automatically.
 - `hooks install` registers adr in ledger's shims, one per hook and shared with other ark tools: `pre-commit` runs `adr hooks run pre-commit`, `commit-msg` runs `adr hooks trailers` (adds `ADR:` and `ADR-Event:` trailers when event files are staged, unless the message has them or a merge is in progress), `pre-push` runs `adr verify --base @{upstream} --ref HEAD`, which checks the current branch's commits against its upstream whichever refs the push names (without an upstream, against `origin`'s default branch; with no remote, the whole log), and `post-merge` runs `adr list --since ORIG_HEAD`. It never overwrites a foreign hook (it writes the other hooks, exits 2 and names the line to add to that hook) and writes nothing when `core.hooksPath` is set (exit 2, pointing to `adr hooks print --manager lefthook|husky|pre-commit` for the hook manager in use). `hooks uninstall` removes adr from the shims. The pre-commit steps are rename following (`[hooks] scope_follow_renames`), the index (checked, or regenerated and staged with `[hooks] index = "stage"`), then `verify --staged`. The hook stages only into the commit's own index: for `git commit <paths>`, a rename that changes a decision's scope stops the commit and names the command to run. When the staged `index.md` lists decision files that aren't staged, the `index/stale` finding names them; stage them, or move them out of the work tree and run `adr index`.
+- `search <query>…` joins its words and lists the decisions whose id, number, title, body or notes contain every one, case- and accent-insensitively (`Café` finds `cafe`), as substrings (`order` finds `orders`). Only proposed and accepted decisions are listed unless `--all`; a note counts the others that match. Each result has the best matching line of the body or a note. It reads the local log only; with `[[sources]]` configured, a note says so (as `list` and `for` do) until ark's step 4.
+- `init --skill` writes the agent skill to `.claude/skills/adr/SKILL.md`, or to `<dir>/SKILL.md` with `--skill-dir <dir>` (a directory inside the repository), and adds one line pointing at it to `AGENTS.md`, creating the file if needed. It never overwrites a SKILL.md (one that differs is kept, with a note), and a second run changes nothing. An `AGENTS.md` with unstaged changes, or not tracked, gets the line but isn't staged; with `--commit` it is refused (exit 2).
 - `show` leads with a state header. A decision that isn't in force says so and names what to read instead, for example `SUPERSEDED by ADR-0002 (accepted 2026-10-18). Do not apply this decision; read ADR-0002 instead.`
 
 Every command takes `--json`, `--root <dir>` (the log directory) and `--help`; reads also take `--ref <ref>`, and writes refuse it.
@@ -103,7 +114,7 @@ Every command takes `--json`, `--root <dir>` (the log directory) and `--help`; r
 - **1**: failing findings from `verify` (or `index --check`, or a hook), or a write the log's rules forbid (an illegal transition, a draft that fails its template lint, an agent's acceptance, an unaccepted successor). Nothing is written, and the findings are in the output.
 - **2**: the tool can't run: bad usage (unknown command, flag or decision, a missing argument, `--ref` on a write), config, environment or internal errors. Nothing is written, except when git refuses a `--commit` (`commit-failed`): the write is then staged and the error says how to finish the commit.
 
-With `--json`, stdout carries exactly one JSON document: `adr-list/v1` (with `since`, `null` without `--since`), `adr-show/v1`, `adr-write/v1` (for every write command), `adr-for/v1`, `adr-init/v1`, `adr-index/v1`, `adr-hooks/v1`, ledger's `ledger-findings/v1` for `verify`, or `ark-error/v1` (`{ "format": "ark-error/v1", "error": { "code", "message" } }`) when the command exits 2; a `commit-failed` error also has the write's `notes`. Every key is always present, with `null` where a value is unknown. A `numbering` object's `reason` is `"index"` when a shallow clone's numbers come from `index.md`. In a shallow clone with a committed index, `adr-write/v1`'s `decision.number` comes from the index in HEAD, which on a branch is the number the acceptance will get once the branch merges. Warnings and notes go to stderr.
+With `--json`, stdout carries exactly one JSON document: `adr-list/v1` (with `since`, `null` without `--since`), `adr-show/v1`, `adr-search/v1`, `adr-write/v1` (for every write command), `adr-for/v1`, `adr-init/v1`, `adr-index/v1`, `adr-hooks/v1`, ledger's `ledger-findings/v1` for `verify`, or `ark-error/v1` (`{ "format": "ark-error/v1", "error": { "code", "message" } }`) when the command exits 2; a `commit-failed` error also has the write's `notes`. Every key is always present, with `null` where a value is unknown. A `numbering` object's `reason` is `"index"` when a shallow clone's numbers come from `index.md`. In a shallow clone with a committed index, `adr-write/v1`'s `decision.number` comes from the index in HEAD, which on a branch is the number the acceptance will get once the branch merges. Warnings and notes go to stderr.
 
 ## Config (`adr.toml`)
 
@@ -119,7 +130,7 @@ index = "none"                  # or "committed": adr index, fresh on every writ
 [policy]
 accept_requires_human = true    # refuse acceptances by an agent
 auto_commit = false             # commit writes without --commit
-mcp_can_decide = false          # validated now, used in phase 3
+mcp_can_decide = false          # agents propose, humans decide; true adds adr_accept, adr_reject, adr_deprecate and adr_supersede to adr mcp
 
 [verify]
 fail_on = "error"               # or "warning"
@@ -149,9 +160,41 @@ An agent using the CLI sets `ARK_AGENT=<agent-id>`, and `ARK_ON_BEHALF_OF=<email
 
 The git identity is git's author identity (`git var GIT_AUTHOR_IDENT` with `user.useConfigOnly`): `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` when set, else `user.name` and `user.email`; it is never guessed. Setting `GIT_AUTHOR_*` also changes the author of `--commit` commits, which is why agents should use `ARK_ON_BEHALF_OF` instead. `--commit` also needs a committer identity, and exits 2 before writing without one.
 
+Agents with an MCP client use `adr mcp` instead (below), and `adr init --skill` gives them the skill: when to check the decisions, how to read them, and that they propose and a human accepts.
+
+## MCP server
+
+`adr mcp` serves the decision log to agents over stdio, in the repository it starts in (`--root` works as for every command). Add it to your MCP client's server config:
+
+```json
+{
+  "mcpServers": {
+    "adr": {
+      "command": "npx",
+      "args": ["-y", "@nikovirtala/adr", "mcp"],
+      "env": { "ARK_ON_BEHALF_OF": "you@example.com" }
+    }
+  }
+}
+```
+
+Set `ARK_ON_BEHALF_OF` in that `env`: stdio clients pass only a few environment variables (`HOME`, `PATH` and the like) to the server, so a value exported in your shell doesn't reach it. Writes are recorded as an agent named by the MCP client (`actor.agent`), on behalf of `ARK_ON_BEHALF_OF`, or of the git user, with a note. An invalid `ARK_ON_BEHALF_OF` makes `adr mcp` exit 2 before serving.
+
+| Tools | Listed |
+| --- | --- |
+| `adr_search`, `adr_get`, `adr_list`, `adr_templates`, `adr_for_path` (reads) | always |
+| `adr_propose`, `adr_update_draft`, `adr_note`, `adr_link`, `adr_scope`, `adr_withdraw` (writes) | always |
+| `adr_accept`, `adr_reject`, `adr_deprecate`, `adr_supersede` | with `[policy] mcp_can_decide = true` |
+
+- Every tool returns the JSON document its CLI command prints under `--json` (`adr-search/v1`, `adr-show/v1`, `adr-list/v1`, `adr-for/v1`, `adr-write/v1`, and `adr-templates/v1` for `adr_templates`) as `structuredContent`, with a readable text whose state headers come first and point at `adr://decision/<number>`. Errors are `isError` results with `ark-error/v1`; a write the log or the MCP policy refuses is a document with `ok: false` and the findings.
+- Resources: `adr://index` (the index table) and `adr://decision/{id}`, one decision's state header and body, where `{id}` is the id, the number or `ADR-NNNN`. The prompt `adr_draft_from_discussion` (optional `title`, `template`, `supersedes`) walks an agent from a conversation to a proposal.
+- `adr_propose` takes a `sections` map (section id to markdown); template lint findings come back as data, and `adr_update_draft` replaces sections of a draft in place, writing only if nobody changed the file meanwhile. With `auto_commit`, an incomplete draft is refused instead of committed.
+- Without `mcp_can_decide`, an agent may update, scope and withdraw only proposals made on behalf of the same person, and never rescope an accepted or deprecated decision (`decision/mcp-cannot-decide`). `accept_requires_human` still refuses an agent's `adr_accept`.
+- MCP writes stage their files and commit only with `[policy] auto_commit`; there is no commit input. Each call reads the log again, but the tool list is fixed at startup: restart `adr mcp` after changing `mcp_can_decide`.
+
 ## Library
 
-The CLI is a thin layer over the library, and phase 3's MCP server uses the same functions and returns the same JSON documents.
+The CLI is a thin layer over the library, and the MCP server uses the same functions and returns the same JSON documents.
 
 ```ts
 import { listDecisions, openDecisionLog, readDecisions, showDecision, verifyDecisions } from "@nikovirtala/adr";
@@ -162,7 +205,7 @@ const { decisions } = listDecisions(read, { status: ["accepted"] });
 const findings = await verifyDecisions(log, { type: "full" });
 ```
 
-`initDecisionLog`, `proposeDecision`, `acceptDecision`, `rejectDecision`, `withdrawDecision`, `deprecateDecision`, `supersedeDecision`, `noteDecision`, `linkDecision`, `scopeDecision` and `followScopeRenames` write, `decisionsFor` answers `adr for`, `resolveDecision` turns an id or number into an id, and `stateHeader` gives the header `show` prints. `indexDecisionLog` and `renderDecisionIndex` regenerate or render the index, and `installDecisionHooks`, `uninstallDecisionHooks`, `printDecisionHooks`, `runPreCommitHook` and `addHookTrailers` are the hook commands.
+`initDecisionLog`, `proposeDecision`, `acceptDecision`, `rejectDecision`, `withdrawDecision`, `deprecateDecision`, `supersedeDecision`, `noteDecision`, `linkDecision`, `scopeDecision` and `followScopeRenames` write, `decisionsFor` answers `adr for`, `resolveDecision` turns an id or number into an id, and `stateHeader` gives the header `show` prints. `searchDecisions` answers `adr search`, `listTemplates` lists the usable templates (`adr-templates/v1`), `updateDraft` replaces sections of a proposed draft, `sourcesNote` gives the local-only note, and `SKILL_MD` is the agent skill. `indexDecisionLog` and `renderDecisionIndex` regenerate or render the index, and `installDecisionHooks`, `uninstallDecisionHooks`, `printDecisionHooks`, `runPreCommitHook` and `addHookTrailers` are the hook commands.
 
 `@nikovirtala/adr/kind` exports only the decision kind (`adrKind`, made with ledger's `defineKind`) and its types, without any CLI code, for tools that fold decision logs themselves, such as issues linking to decisions:
 
@@ -173,5 +216,5 @@ import { adrKind } from "@nikovirtala/adr/kind";
 ## Not yet included
 
 - **Reference checks are local.** `verify` checks that `supersedes`, `superseded.by` and `linked.to` name decisions in the same log. Qualified references to other logs (`<source>:<id>`, written by `adr link`) and qualified anchors are skipped until ark's step 4.
-- **Phase 3:** an MCP server, a SKILL.md for agents, and search.
-- **ark's step 4, with issues:** cross-log reference checks at the pinned ref and listing across sources; until then `link` stores a qualified target unchecked.
+- **Search limits.** `adr search` matches substrings without stemming (`orders` doesn't find `order`) and without phrases, and folds accents but not `ß` (`strasse` doesn't find `Straße`).
+- **ark's step 4, with issues:** cross-log reference checks at the pinned ref, and listing and searching across sources; until then `link` stores a qualified target unchecked.

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { A as openDecisionLog, C as adrChecks, D as runDecisionIndex, N as resolveDecision, O as changedSince, S as withdrawDecision, _ as proposeDecision, a as initDecisionLog, c as installDecisionHooks, d as uninstallDecisionHooks, f as acceptDecision, g as noteDecision, h as linkDecision, j as readDecisions, k as numberingNote, l as printDecisionHooks, m as followScopeRenames, n as listDecisions, o as addHookTrailers, p as deprecateDecision, r as showDecision, t as decisionsFor, u as runPreCommitHook, v as rejectDecision, x as supersedeDecision, y as scopeDecision } from "./scope-CLqH-q1y.js";
+import { A as changedSince, I as resolveDecision, M as numberingNote, N as openDecisionLog, O as runDecisionIndex, P as readDecisions, _ as withdrawDecision, c as followScopeRenames, d as proposeDecision, f as rejectDecision, h as supersedeDecision, i as showDecision, l as linkDecision, n as decisionsFor, o as acceptDecision, p as scopeDecision, r as listDecisions, s as deprecateDecision, t as searchDecisions, u as noteDecision } from "./search-CwIPlNGd.js";
 import { n as DECISION_STATUSES, t as adrKind } from "./kind-DjvA3dyA.js";
+import { a as installDecisionHooks, c as uninstallDecisionHooks, l as adrChecks, o as printDecisionHooks, r as addHookTrailers, s as runPreCommitHook, t as initDecisionLog } from "./init-YgW7g9Fx.js";
 import { createRequire } from "node:module";
 import { UsageError, exitCode, findingsReport, formatText, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
-import { resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
 import { spawn } from "node:child_process";
 // src/cli/open.ts
@@ -176,7 +178,8 @@ const VERBS = {
 	deprecate: "deprecated",
 	note: "noted",
 	link: "linked",
-	scope: "scoped"
+	scope: "scoped",
+	update: "updated"
 };
 /**
 * The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
@@ -243,6 +246,9 @@ function writeText(doc, display, o) {
 				recorded
 			].join("\n");
 		}
+		case "update":
+			if (doc.written.length === 0) return `Draft of ${named(v.id, display)} unchanged`;
+			return [`Updated the draft of ${named(v.id, display)}: ${v.title}`, recorded].join("\n");
 	}
 }
 /**
@@ -298,15 +304,39 @@ function forText(doc, display, keyword) {
 	}
 	return lines.join("\n");
 }
+/**
+* `adr search`: one padded row per result with its excerpt (or which field matched) under it, and
+* an inactive result's warning; then the count.
+*/
+function searchText(doc) {
+	const quoted = JSON.stringify(doc.query);
+	if (doc.results.length === 0) return `No ${doc.include_inactive ? "" : "active "}decisions match ${quoted}.`;
+	const rows = columns(doc.results.map((r) => [
+		r.decision.number === null ? r.decision.id : `${r.decision.display} (${r.decision.id})`,
+		r.decision.status,
+		r.decision.title
+	])).split("\n");
+	const lines = [];
+	doc.results.forEach((r, i) => {
+		lines.push(rows[i] ?? "");
+		if (r.header.warning !== null) lines.push(`  ${r.header.warning}`);
+		const where = r.matched.filter((f) => f === "id" || f === "title").join(" and ");
+		lines.push(r.excerpt === null ? `  (${where} match)` : `  ${r.excerpt}`);
+	});
+	const n = doc.total;
+	lines.push(`${n === 1 ? "1 decision matches" : `${n} decisions match`} ${quoted}.`);
+	return lines.join("\n");
+}
 /** `adr init`: what was written and kept, then the next step; or that nothing was needed. */
 function initText(doc) {
 	if (doc.written.length === 0) return `Already initialized: ${doc.root} (kept ${doc.kept.join(", ")})`;
+	const skill = doc.skill !== null && doc.written.includes(doc.skill);
 	return [
-		`Initialized ${doc.root}`,
+		doc.written.every((p) => p === doc.skill || p === "AGENTS.md") ? "Set up the adr agent skill" : `Initialized ${doc.root}`,
 		...doc.written.map((p) => `  ${p}`),
 		...doc.kept.map((p) => `Kept ${p}`),
 		...doc.commit === null ? [] : [`Committed ${short$1(doc.commit)}.`],
-		"Next: adr new \"<title>\""
+		skill ? "Next: adr mcp, from your MCP client's config" : "Next: adr new \"<title>\""
 	].join("\n");
 }
 // src/cli/accept.ts
@@ -594,39 +624,68 @@ const indexCommand = {
 	}
 };
 // src/cli/init.ts
-/** `adr init [--template <name>]… [--commit | --no-commit] [-m <message>]` (design §6.2). */
-const initCommand = {
-	name: "init",
-	summary: "set up a decision log: a config file and starter templates",
-	usage: "init [--template <name>]… [--commit | --no-commit] [-m <message>]",
-	options: {
-		template: {
-			type: "string",
-			multiple: true
+const DEFAULT_SKILL_DIR = ".claude/skills/adr";
+const MAX_DIR = 1024;
+/** `--skill-dir` as a repo-relative directory inside the work tree and outside `.git`. */
+async function skillDir(root, cwd, given) {
+	const dir = given.trim();
+	const bad = () => new UsageError("--skill-dir must be a directory inside the repository");
+	if (dir === "" || dir.length > MAX_DIR || dir.includes("\0")) throw bad();
+	const base = await realpath(cwd).catch(() => cwd);
+	const rel = relative(root, resolve(base, dir));
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw bad();
+	const segments = rel.split(sep).filter((s) => s !== "");
+	if (segments[0] === ".git") throw bad();
+	return segments.join("/");
+}
+/**
+* `adr init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit]
+* [-m <message>]` (design §6.2, phase 3 §9).
+*/
+function initCommand(version) {
+	return {
+		name: "init",
+		summary: "set up a decision log: a config file and starter templates",
+		usage: "init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit] [-m <message>]",
+		options: {
+			template: {
+				type: "string",
+				multiple: true
+			},
+			skill: { type: "boolean" },
+			"skill-dir": { type: "string" },
+			...COMMIT_OPTIONS
 		},
-		...COMMIT_OPTIONS
-	},
-	positionals: {
-		min: 0,
-		max: 0,
-		names: []
-	},
-	ref: "reject",
-	async run({ io, flags, values }) {
-		const templates = Array.isArray(values.template) ? values.template : void 0;
-		const log = await openForCli(io, flags);
-		const doc = await initDecisionLog(log, {
-			...templates === void 0 ? {} : { templates },
-			...commitChoice(values, { autoCommit: log.adr.autoCommit })
-		});
-		return {
-			exit: 0,
-			json: doc,
-			text: initText(doc),
-			notes: doc.notes
-		};
-	}
-};
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags, values }) {
+			const templates = Array.isArray(values.template) ? values.template : void 0;
+			const given = typeof values["skill-dir"] === "string" ? values["skill-dir"] : null;
+			if (given !== null && values.skill !== true) throw new UsageError("--skill-dir needs --skill");
+			const log = await openForCli(io, flags);
+			const root = log.git.root ?? io.cwd;
+			const dir = values.skill !== true ? null : given === null ? DEFAULT_SKILL_DIR : await skillDir(root, io.cwd, given);
+			const doc = await initDecisionLog(log, {
+				...templates === void 0 ? {} : { templates },
+				...dir === null ? {} : { skill: {
+					dir,
+					version
+				} },
+				...commitChoice(values, { autoCommit: log.adr.autoCommit })
+			});
+			return {
+				exit: 0,
+				json: doc,
+				text: initText(doc),
+				notes: doc.notes
+			};
+		}
+	};
+}
 // src/cli/link.ts
 /** `adr link <decision> <target> [--rel <rel>]` (design §6.7): a typed link, in any state. */
 const linkCommand = {
@@ -728,6 +787,42 @@ const listCommand = {
 		};
 	}
 };
+// src/cli/mcp.ts
+/**
+* `adr mcp` (design §7.1): the MCP server over stdio. Loaded with a dynamic import, so no other
+* command loads the MCP SDK.
+*/
+function mcpCommand(version) {
+	return {
+		name: "mcp",
+		summary: "start the MCP server over stdio",
+		usage: "mcp",
+		options: {},
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags }) {
+			if (flags.json) throw new UsageError("adr mcp speaks JSON-RPC on stdout; it takes no --json");
+			if (io.interactive) io.stderr.write("adr: adr mcp speaks MCP on stdin and stdout; start it from an MCP client\n");
+			const { serveAdrMcp } = await import("./server-CXCO5zfp.js");
+			await serveAdrMcp({
+				cwd: io.cwd,
+				root: flags.root,
+				env: io.env,
+				version,
+				stderr: io.stderr
+			});
+			return {
+				exit: 0,
+				json: null,
+				text: ""
+			};
+		}
+	};
+}
 // src/cli/editor.ts
 /**
 * The user's editor as an `edit` callback (design §5.7), or `null` when neither `VISUAL` nor
@@ -1066,6 +1161,38 @@ const scopeCommand = {
 		};
 	}
 };
+// src/cli/search.ts
+/** `adr search <query>… [--all]` (design §8.2): words are joined, and every one must match. */
+const searchCommand = {
+	name: "search",
+	summary: "search decisions' ids, titles, bodies and notes",
+	usage: "search <query>… [--all]",
+	options: { all: { type: "boolean" } },
+	positionals: {
+		min: 1,
+		max: 20,
+		names: ["query"]
+	},
+	ref: "read",
+	async run({ io, flags, values, positionals }) {
+		const read = await readDecisions(await openForCli(io, flags));
+		const doc = searchDecisions(read, {
+			query: positionals.join(" "),
+			includeInactive: values.all === true
+		});
+		const notes = [...notesWith(doc.notes, numberingNote(read, { unavailable: false }))];
+		if (doc.inactive_omitted > 0) {
+			const k = doc.inactive_omitted;
+			notes.push(`${k === 1 ? "1 inactive decision also matches" : `${k} inactive decisions also match`}; add --all to see them`);
+		}
+		return {
+			exit: 0,
+			json: doc,
+			text: searchText(doc),
+			notes
+		};
+	}
+};
 // src/cli/show.ts
 /** `adr show <decision> [--history]` (design §5.6). */
 const showCommand = {
@@ -1203,7 +1330,7 @@ function adrCli(version) {
 		version,
 		summary: "Architecture decision records kept as event logs in git.",
 		commands: [
-			initCommand,
+			initCommand(version),
 			newCommand,
 			acceptCommand,
 			rejectCommand,
@@ -1218,7 +1345,9 @@ function adrCli(version) {
 			forCommand,
 			listCommand,
 			showCommand,
-			verify
+			searchCommand,
+			verify,
+			mcpCommand(version)
 		]
 	};
 }