@intentius/chant 0.124.45 → 0.124.48

package/src/cli/main.test.ts

@@ -208,9 +208,33 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["build", "--unknown=value"])).toThrow(/Unknown flag: --unknown/);
   });
 
-  test("unknown short flags are still silently ignored (unchanged; out of #1127 scope)", () => {
-    const result = parseArgs(["build", "-x", "value"]);
-    expect(result.command).toBe("build");
+  test("an unknown short flag is refused like an unknown long one (#4369)", () => {
+    // Was "unknown short flags are still silently ignored": `-x` vanished and
+    // the next token became the path. #4369 refuses it with the #1127 message.
+    expect(() => parseArgs(["build", "-x", "value"])).toThrow(/Unknown flag: -x\nRun "chant --help"/);
+    expect(() => parseArgs(["search", "kind:X", "-q"])).toThrow(/Unknown flag: -q/);
+  });
+
+  test("a search query that opens with -> is the positional, not a dropped flag (#4369)", () => {
+    expect(parseArgs(["search", "->kind:Bucket"]).path).toBe("->kind:Bucket");
+    const explained = parseArgs(["search", "->kind:Bucket", "--explain"]);
+    expect(explained.path).toBe("->kind:Bucket");
+    expect(explained.explain).toBe(true);
+    expect(parseArgs(["search", "--explain", "->*[via=subnet_id]kind:aws_vpc"]).path).toBe("->*[via=subnet_id]kind:aws_vpc");
+    // Unchanged: the in-edge spelling and a leading space always worked.
+    expect(parseArgs(["search", "<-kind:Bucket"]).path).toBe("<-kind:Bucket");
+    expect(parseArgs(["search", " ->kind:Bucket"]).path).toBe(" ->kind:Bucket");
+    // A known short flag still parses as one.
+    expect(parseArgs(["search", "->kind:Bucket", "-v"]).verbose).toBe(true);
+  });
+
+  test("-- ends flag parsing: what follows is positional, unsplit (#4369)", () => {
+    const r = parseArgs(["search", "--json", "--", "-kind:X", "--explain"]);
+    expect(r.path).toBe("-kind:X");
+    expect(r.extraPositional).toBe("--explain");
+    expect(r.explain).toBeUndefined();
+    expect(r.json).toBe(true);
+    expect(parseArgs(["search", "--", "--x=y"]).path).toBe("--x=y");
   });
 
   test("parses --watch flag", () => {
@@ -845,9 +869,12 @@ describe("workspace init and ls (#2534)", () => {
       "workspace pin",
       "workspace points",
       "workspace records",
+      "workspace run",
       "workspace runs",
+      "workspace search",
       "workspace signers",
       "workspace status",
+      "workspace train",
       "workspace trust",
       "workspace upgrade",
       "workspace verify",
@@ -857,6 +884,19 @@ describe("workspace init and ls (#2534)", () => {
     ]);
   });
 
+  test("run and train take their targets and flags (#2554)", () => {
+    const run = parseArgs(["workspace", "run", "api/deploy", "web/deploy", "--gate", "release", "--env", "prod"]);
+    expect(run).toMatchObject({ command: "workspace", path: "run", positionals: ["run", "api/deploy", "web/deploy"], gate: "release", env: "prod" });
+    expect(resolveCommand(run, commandRegistry)?.def.name).toBe("workspace run");
+    expect(parseArgs(["workspace", "run", "--dependents-of", "network", "--op", "deploy"])).toMatchObject({ dependentsOf: "network", op: "deploy" });
+    expect(() => parseArgs(["workspace", "run", "--dependents-of"])).toThrow(/--dependents-of needs a member/);
+    const train = parseArgs(["workspace", "train", "prod", "--pin", "api=v2", "--pin", "web=v1"]);
+    expect(train).toMatchObject({ positionals: ["train", "prod"], pins: ["api=v2", "web=v1"] });
+    expect(resolveCommand(train, commandRegistry)?.def.name).toBe("workspace train");
+    expect(() => parseArgs(["workspace", "train", "prod", "--pin", "api"])).toThrow(/--pin needs a member and a release/);
+    expect(parseArgs(["workspace", "lint", "--cross-root", "--format", "json"])).toMatchObject({ path: "lint", crossRoot: true, format: "json" });
+  });
+
   test("adopt-lineage, hash-index, versions and upgrade --source take their flags (#2551)", () => {
     const adopt = parseArgs(["workspace", "adopt-lineage", "app", "--from", "acme/starter#svc", "--tags", "v*", "--index", "i.json", "--param", "name=x", "--dry-run"]);
     expect(adopt).toMatchObject({ command: "workspace", path: "adopt-lineage", extraPositional: "app", migrateFrom: "acme/starter#svc", tags: "v*", index: "i.json", param: ["name=x"], dryRun: true });

package/src/cli/main.ts

@@ -170,14 +170,27 @@ Commands:
                         bundle tree, otherwise JSON path→content on stdout)
   search "<query>"      Answer an estate question with a few matching rows
                         instead of a graph dump (kind:, tag:, attr:, ->/<- edge
-                        terms; --live or --at <ref> with --env <name> reads the
-                        estate or a recorded snapshot; --show <attr>,
-                        --check-live, --check-snapshot, --fail-on-drift)
+                        terms, ->* / ->{1,3} for depth, ->[via=attr] / [to=attr]
+                        by attribute; --live or --snapshot <ref> (also --at
+                        <ref>) with --env <name> reads the estate or a
+                        recorded snapshot; --show <attr>,
+                        --count-by kind|module|attr:<name>, --explain prints
+                        paths, --json, --check-live,
+                        --check-snapshot, --fail-on-drift; cap:<name> and
+                        ->[cap=<name>] ask with a capability, and
+                        --capabilities prints the catalog)
   query "<sql>" [dir]   Run one read-only SQL statement over chant/lifecycle:
                         the resources and snapshots each lexicon observed, Op
                         runs, gates, deploys, releases and cuts, loaded into
                         node:sqlite (schema v1, listed in chant_schema).
-                        --member <name> keeps members; --json prints rows
+                        --member <name> keeps members; --json prints rows.
+                        For a read contract, use chant ledger
+  ledger <table> [dir]  One ledger's rows from chant/lifecycle as a read
+                        contract (resources, snapshots, runs, gates, deploys,
+                        releases, cuts; the columns chant query loads).
+                        --where <field><op><value> (= != < <= > >= ~,
+                        repeatable), --since <time|7d>, --at <rev> of
+                        chant/lifecycle, --member <name>, --json
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -580,6 +593,9 @@ Ops:
                         --layout-engine graphviz to use dot instead;
                         --detail 0..3: stacks|composites|declarables|attributes;
                         --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
+                        --format ir --capability-view: add the lexicon-neutral
+                        view capability rules read, as this project's lexicons
+                        map it, to the IR as capabilityView (#4378)
                         --components --format ir --projection gitlab|github|forgejo:
                         add the CI/pipeline projection (stages/jobs/needs) to
                         the component-graph IR, from the same generator
@@ -617,7 +633,7 @@ Workspace (level 1, #2524):
                         restore, from the deploy records, releases and ci
                         revoked tags. Eight weeks back by default. Read only;
                         never fetches. --json prints the read-contract document
-  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--where <field><op><value>]... [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -630,7 +646,9 @@ Workspace (level 1, #2524):
                         asset-drift or asset-missing. In the working tree,
                         each record says whether it is committed, modified
                         or new against HEAD, with the branch and base;
-                        --uncommitted lists only the modified and new ones
+                        --uncommitted lists only the modified and new ones;
+                        --where keeps the records a typed filter matches
+                        (id, path, state, valid, data.<key>, ...)
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -700,14 +718,16 @@ Workspace (level 1, #2524):
                         a url or a path pinned by hash) is appended to the
                         item's pins through records amend. Prints the
                         work-evidence document and never commits
-  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--where <field><op><value>]... [--follow-squash] [--json]
                         The agent runs in the run ledger on chant/lifecycle, each
                         with its model, tokens, cost and the commits it made,
                         and totals per work item, decision and principal; a run
                         that reports no cost is listed as unpriced, never zero.
                         Read-only, never fetches; --follow-squash joins each
                         squash merge to its pull request's runs, fetching a
-                        missing refs/pull/<n>/head from origin
+                        missing refs/pull/<n>/head from origin; --where keeps
+                        the runs a typed filter matches (state, model,
+                        startedAt, cost.amount, ...) before the totals
   workspace runs start --from <file|->
                         Record that an agent run started: who it worked for,
                         its harness, model, work item and lease. Prints the run
@@ -879,7 +899,7 @@ Workspace (level 1, #2524):
   workspace admit <return id> [--note <text>] [--dry-run] [--json]
                         Admit the signers of a return in .chant/trust.json, so
                         its signed work reads as attested once merged
-  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>] [--forge-repos <file>]
                         Fail on an unreadable lineage lock or an open manual
                         step, and, in a declared workspace, on a WSP check of
                         the declaration, member ledgers, pipelines or
@@ -891,7 +911,10 @@ Workspace (level 1, #2524):
                         resolves each declared member link against the live
                         graph of <env> (each chant member runs chant graph
                         --live, which reaches the account) and reports
-                        WSP141 and WSP142
+                        WSP141 and WSP142. --forge-repos reads a forge's
+                        repository list from a file and reports repos an
+                        org workspace lacks (WSP014) or names that the
+                        forge no longer has (WSP015)
   workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
                         Map each path the diff changes to the current records
                         whose constrains cover it: change-uncovered when none
@@ -919,9 +942,12 @@ Workspace (level 1, #2524):
                         its own chant, one process per toolchain. -o <dir>
                         writes <dir>/<member>.json; --member narrows the run;
                         --dry-run prints which chant runs which project
-  workspace lint [dir] [--format stylish|json|sarif] [--member <name>]
+  workspace lint [dir] [--format stylish|json|sarif] [--member <name>] [--cross-root]
                         Lint every chant member and example project with its
-                        own chant; sarif writes one run per member
+                        own chant; sarif writes one run per member.
+                        --cross-root adds the disagreement lint (LNK001 and
+                        the lexicons' cross-root checks) over every member's
+                        graph, where declared links and the graphs disagree
   workspace audit [dir] [--json] [--member <name>]
                         Audit each chant member with its own .chant-audit.json;
                         every finding carries a member field
@@ -934,6 +960,15 @@ Workspace (level 1, #2524):
                         source and toolchain are unchanged is served from
                         the cache in $CHANT_CACHE_DIR or ~/.cache/chant;
                         --no-cache reads every member
+                        --capability-view: each member's chant adds its
+                        capability view, mapped by its own lexicons
+  workspace search "<query>" [--member <name>] [--env <name>] [--snapshot <ref> | --live] [--at <rev>] [--explain] [--count-by ...] [--json]
+                        chant search in every chant member, each under its own
+                        chant, as one read-contract document: ids are
+                        <member>/<id> as workspace graph prints them, each
+                        member is searched alone, and a member that can't be
+                        searched has a reason code. --at <rev> is the git
+                        revision; --snapshot <ref> replays a recorded snapshot
   workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
@@ -949,6 +984,29 @@ Workspace (level 1, #2524):
                         One decision's intent walk over every path: and member:
                         entry it constrains: the commits in its window, each
                         own, worked, within-other or unexplained, with counts
+  workspace run <member>/<op>... [--env <env>] [--gate <name>] [--on <lexicon>] [--dry-run] [--json]
+                        Run Ops that span members (#2554): each target's chant
+                        run <op> in the member's directory, under its own
+                        chant, producers before the members that link to them.
+                        OPS019 checks every target against the composed graph
+                        first. Member run records cite the workspace run,
+                        whose record goes under _members/_workspace/<env>/.
+                        Exits 3 when a step stops at a gate
+  workspace run --dependents-of <member> --op <op> [--env <env>] [--gate <name>] [--dry-run] [--json]
+                        Run <op> in every member that links to <member>,
+                        directly or not, nearest first; members without the
+                        Op are listed as skipped
+  workspace run approve <gate> [--plan <digest>] [--approver <principal>]
+                        Approve a workspace gate's pending fact. It stands in
+                        for a member gate only when it covers that member's
+                        plan and the member sets acceptWorkspaceGates at base
+  workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json]
+                        Record a release train: one cut release of every
+                        chant member (the newest, unless --pin picks one),
+                        under _members/_workspace/<env>/trains.jsonl. Refuses
+                        when a member has no release
+  workspace train list <env> [--json]
+                        The release trains recorded for <env>, oldest first
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
@@ -1022,7 +1080,9 @@ Component release ledger + status:
                             from the report pr-plan --no-status wrote
                             (--pr <n> --head <sha> --env <env> --forge
                             <kind>), in a job that runs none of the
-                            change's code (#4295)
+                            change's code (#4295); --open posts every
+                            open merge request's from a GitLab pipeline
+                            of the target branch (#4328)
   components pr-record     On merge (#4168): plan the same members again,
                             store the change set and write the merge record
                             _merges/<commit>.json; applies and refuses
@@ -1180,12 +1240,16 @@ Options:
                         JSON (lifecycle plan)
                         OR '--report markdown': emit a reviewer-facing markdown
                         render, holes and disruption included (lifecycle plan)
-  --from <name>         Source lexicon for migrate (default: github)
-  --to <name>           Target lexicon for migrate (default: gitlab)
-  --emit <fmt>          Migration output format: yaml (default) or ts
+  --from <name>         Source for migrate: a lexicon, or lexicon/dialect such
+                        as sql/postgres (default: github)
+  --to <name>           Target for migrate, same form, such as sql/clickhouse
+                        (default: gitlab)
+  --emit <fmt>          Migration output format: yaml (default), ts, or sql;
+                        sql/clickhouse defaults to ts
   --strict              Escalate needs-review/validation to errors (migrate);
                         exit nonzero on an unresolved identity (lifecycle whoami)
-  --validate            Run external validator (glci/glab) after migrate
+  --validate            Run external validator after migrate: glci/glab, or the
+                        ClickHouse emulator for sql/clickhouse
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
                         lexicon resources (list, describe, graph, build, run)
@@ -1480,6 +1544,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "search", handler: runSearch },
   // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
   { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
+  { name: "ledger", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/ledger")).runLedgerCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1610,6 +1675,12 @@ export const commandRegistry: CommandDef[] = [
   // chant#2618 — audit runs no project code, at the workspace level too.
   { name: "workspace audit", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "audit") },
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
+  // #4374 — chant search in every member, under its own chant, composed with workspace graph's ids: the search document.
+  // #2554 — Ops that span members, as <member>/<op> targets, each run under its member's own chant.
+  { name: "workspace run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/workspace-run")).runWorkspaceRun(ctx) },
+  // #2554 — a release train: one release of every chant member, pinned in the workspace ledger.
+  { name: "workspace train", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-train")).runWorkspaceTrain(ctx) },
+  { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli")).runWorkspaceSearch(ctx) },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
   // #3308 — a box's listing, written through chant so a tool never edits the declaration itself (ws-074).

package/src/cli/mcp/server.test.ts

@@ -1630,9 +1630,9 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(14);
+      expect(tools).toHaveLength(15);
       expect(tools.map((t) => t.name).sort()).toEqual([
-        "build", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
+        "build", "capabilities", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
         "op-approve", "op-list", "op-report", "op-run", "op-status",
         "scaffold", "search",
       ]);
@@ -1646,7 +1646,7 @@ describe("McpServer", () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(14);
+      expect(tools).toHaveLength(15);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -7,6 +7,7 @@ import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import { compositesTool, createCompositesHandler } from "./tools/composites";
+import { capabilitiesTool, createCapabilitiesHandler } from "./tools/capabilities";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpClientInfo, McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { findWorkspaceRoot } from "../../project-root";
@@ -126,6 +127,8 @@ export class McpServer {
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
     this.registerTool(compositesTool, createCompositesHandler(plugins ?? []));
+    // The capability catalog (#4375), the read contract's capabilities document.
+    this.registerTool(capabilitiesTool, createCapabilitiesHandler(options.workspace?.cwd ?? process.cwd(), options.workspace?.chantCommand));
 
     // Register state tools
     const snapshot = createSnapshotTool(plugins ?? []);

package/src/cli/mcp/tools/capabilities.ts

@@ -0,0 +1,32 @@
+/**
+ * The `capabilities` tool of `chant serve mcp` (#4375): the capability
+ * catalog `chant search` answers `cap:` terms with, as the read contract's
+ * `capabilities` document (capabilities.schema.json).
+ *
+ * Like the workspace reads, it runs the command and returns the document it
+ * printed, unchanged: `chant workspace search --capabilities --json` inside a
+ * declared workspace, where the workspace's chant runs the rules, and `chant
+ * search --capabilities --json` anywhere else. It is served everywhere, since
+ * a plain project's agent asks the same questions.
+ */
+import { findWorkspaceRoot } from "../../../project-root";
+import type { ToolDefinition, ToolHandler } from "../types";
+import { ownChantCommand, runRead, type ChantCommand } from "../workspace-tools";
+
+export const capabilitiesTool: ToolDefinition = {
+  name: "capabilities",
+  description:
+    "The capability catalog for chant search (capabilities.schema.json, #4375): each capability's name, meaning, parameters, the search term that asks for it (cap:<name> for a set, ->[cap=<name>] for an edge), the questions it answers, whether each lexicon can supply it, what it does not evaluate, and its rule. " +
+    "Read it once per session, then ask estate questions with those terms, such as cap:internet-reachable(22) or cap:stores-data <-[cap=reaches]<role>. Not the resource-type catalog: that is the search tool. " +
+    "Returns the document chant search --capabilities --json prints (chant workspace search --capabilities --json inside a declared workspace), unchanged.",
+  inputSchema: { type: "object", properties: {} },
+};
+
+/** The argv the tool runs in `cwd`: the workspace form inside a declared workspace. */
+export function capabilitiesArgv(cwd: string): string[] {
+  return findWorkspaceRoot(cwd) ? ["workspace", "search", "--capabilities", "--json"] : ["search", "--capabilities", "--json"];
+}
+
+export function createCapabilitiesHandler(cwd: string, command: ChantCommand = ownChantCommand()): ToolHandler {
+  return async () => runRead(command, capabilitiesArgv(cwd), cwd);
+}

package/src/cli/mcp/workspace-tools.e2e.test.ts

@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract", "points-withdraw"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-search", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract", "points-withdraw"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -159,7 +159,27 @@ describe("reads", () => {
     expect(flag.content[0].text).toMatch(/at may not start with -/);
   }, 120_000);
 
+  test("workspace-search returns exactly the document chant workspace search --json prints (#4374)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-search", { query: "app" });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "search", "app", "--json"]));
+    expect(res.structuredContent).toMatchObject({ contract: 1, query: "app", at: null, source: { kind: "declared" } });
+    // A query that opens with an edge term is passed after --, and a refusal is a document.
+    const edge = await call(s, "workspace-search", { query: "->kind:Nothing", countBy: "kind" });
+    expect(edge.structuredContent).toEqual(cli(["workspace", "search", "--count-by", "kind", "--json", "--", "->kind:Nothing"]));
+    const refused = await call(s, "workspace-search", { query: "app", at: "latest" });
+    expect(refused.structuredContent).toMatchObject({ error: { code: "revision-unknown", hint: expect.stringContaining("--snapshot latest") } });
+  }, 240_000);
+
   test("the conformance suite's argv maps to the tool that answers it", () => {
+    expect(mcpToolCall(["workspace", "search", "app", "--member", "delivery", "--snapshot", "latest", "--env", "dev", "--json"])).toEqual({
+      name: "workspace-search",
+      arguments: { query: "app", member: ["delivery"], snapshot: "latest", env: "dev" },
+    });
+    expect(readArgv("workspace-search", { query: "->kind:X", member: ["delivery"], snapshot: "latest", env: "dev" })).toEqual([
+      "workspace", "search", "--member", "delivery", "--env", "dev", "--snapshot", "latest", "--json", "--", "->kind:X",
+    ]);
     expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
     expect(mcpToolCall(["workspace", "records", "--uncommitted", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { uncommitted: true, kind: KIND } });
     expect(readArgv("workspace-records", { kind: KIND, uncommitted: true })).toEqual(["workspace", "records", "--kind", KIND, "--uncommitted", "--json"]);

package/src/cli/mcp/workspace-tools.ts

@@ -5,7 +5,7 @@
  * Served when the server starts at or inside a declared workspace. Each tool
  * is a thin call into the code the CLI runs:
  *
- * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
+ * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`, `workspace-search`,
  *   `workspace-changes`, `workspace-records`, `workspace-points`,
  *   `workspace-work-history`, `workspace-runs`) run `chant workspace <command>
  *   ... --json` with the chant this server runs as, in the server's
@@ -123,6 +123,27 @@ export const workspaceReadTools: ToolDefinition[] = [
       },
     },
   },
+  {
+    name: "workspace-search",
+    description:
+      "Answer an estate question over every chant member of the workspace with a few rows instead of the whole graph: chant workspace search <query> --json (search.schema.json, #4374). Returns that document unchanged. Each member is searched under its own chant and alone, ids are <member>/<id> as workspace-graph names the same nodes, and a member that can't be searched is listed with a reason code, never as zero matches. " +
+      "The query is space-separated terms that must all match: a bare word (substring of id, kind or attributes), kind:<substr> (a Terraform resource matches its type, kind:aws_instance), attr:<name>=<value>, tag:<key>=<value>, and edge terms ->X (this node references a node matching X) and <-X (referenced by one); ->*X is any depth, ->{2}X or ->{1,3}X a number of hops, ->[via=attr]X and ->[to=attr]X pick the edge by attribute, and !term negates. " +
+      "at is the git revision of the source; snapshot (with env) answers from a recorded lifecycle snapshot such as latest. They are two different times, and at refuses a snapshot ref.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The search terms. May start with -> or <-." },
+        member: { type: "array", items: { type: "string" }, description: "Only these members (--member)." },
+        env: { type: "string", description: "The environment a snapshot was recorded for (--env)." },
+        snapshot: { type: "string", description: "Answer from this recorded lifecycle snapshot, such as latest (--snapshot). Needs env." },
+        countBy: { type: "string", description: "Group the matches: kind, module or attr:<name> (--count-by). The query may then be empty." },
+        show: { type: "string", description: "Comma-separated attributes to carry on each row (--show)." },
+        explain: { type: "boolean", description: "Add each member's universe and near misses (--explain)." },
+        at: atProp,
+      },
+      required: ["query"],
+    },
+  },
   {
     name: "workspace-changes",
     description:
@@ -417,6 +438,30 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
         "--json",
       ];
     }
+    case "workspace-search": {
+      // The query is one argument after `--`, so one that opens with -> stays a query.
+      const query = params.query;
+      if (typeof query !== "string") throw new ToolInputError("query must be a string");
+      const members = params.member === undefined || params.member === null ? [] : Array.isArray(params.member) ? params.member : [params.member];
+      const memberArgs = members.flatMap((m, i) => ["--member", str({ [`member[${i}]`]: m }, `member[${i}]`, true)!]);
+      const flags = (["env", "snapshot", "show"] as const).flatMap((f) => {
+        const v = str(params, f);
+        return v !== undefined ? [`--${f}`, v] : [];
+      });
+      const countBy = str(params, "countBy");
+      return [
+        "workspace",
+        "search",
+        ...memberArgs,
+        ...flags,
+        ...(countBy !== undefined ? ["--count-by", countBy] : []),
+        ...(bool(params, "explain") ? ["--explain"] : []),
+        ...atArgs,
+        "--json",
+        "--",
+        query,
+      ];
+    }
     case "workspace-agent": {
       const name = str(params, "name", true)!;
       return ["workspace", "agent", name, "--json"];
@@ -458,7 +503,7 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
 }
 
 /** Run chant and parse the one JSON document it printed. The exit code does not matter: an error document is a document. */
-function runRead(command: ChantCommand, argv: string[], cwd: string): Promise<unknown> {
+export function runRead(command: ChantCommand, argv: string[], cwd: string): Promise<unknown> {
   return new Promise((settle, fail) => {
     const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";