@intentius/chant 0.88.0 → 0.90.0

package/dist/workspace/source-block.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A record's stored source block (#2708): where a proposal came from.
+ *
+ * chant's provenance (`trust/provenance.ts`) is computed from git: who
+ * committed a record, and with which key. It says nothing about the harness,
+ * model and session a decision was proposed in, or the conversation behind it.
+ * A record kind that declares `source: { field }` opts in to a stored block
+ * holding that, next to whatever else its source field says (a decision's
+ * issue row or workspace member, a work item's finding):
+ *
+ * - `via`: how the record reached the workspace, `cli`, `mcp` or `harvest`;
+ * - `client`: the MCP client's `clientInfo` (`name`, `version`), or the CLI;
+ * - `harness`: the harness's id, such as `claude-code` or `codex`;
+ * - `model`: the model id the harness reports;
+ * - `session`: the harness's session or conversation id, as a string, or as
+ *   `{ id, record }` with the chant session record it was held in (#2697);
+ * - `turns`: the turn range the decision was made in, `{ from, to }`;
+ * - `transcript`: `{ path | uri, sha256 }`, pinning a transcript by hash and
+ *   never copying it, the way evidence pins a file.
+ *
+ * Every field is optional, and the block is data about the proposal, not
+ * trust: nothing here raises or lowers a record's standing. The rules are
+ * three. The fields that are present must have these shapes
+ * (`record-schema-invalid` otherwise, beside the kind's own schema). A record
+ * written with `via: "harvest"` must open in the kind's first state, since a
+ * harvest proposes and a person decides (`source-harvest-not-proposed`, a
+ * write refusal). And `records` warns `source-transcript-drift` when the
+ * pinned transcript can be read here and its bytes hash to something else.
+ */
+import { z } from "zod";
+/** How a record reached the workspace. Closed. */
+export declare const SOURCE_VIAS: readonly ["cli", "mcp", "harvest"];
+export type SourceVia = (typeof SOURCE_VIAS)[number];
+/** The proposal fields of a source block. Other fields of the block are the kind's, and left to its schema. */
+export declare const sourceBlockSchema: z.ZodObject<{
+    via: z.ZodOptional<z.ZodEnum<{
+        cli: "cli";
+        mcp: "mcp";
+        harvest: "harvest";
+    }>>;
+    client: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    harness: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    session: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        record: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    turns: z.ZodOptional<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strict>>;
+    transcript: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        uri: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>]>>;
+}, z.core.$strip>;
+export type SourceBlock = z.infer<typeof sourceBlockSchema>;
+/** The source block of `data`, when `field` holds an object. */
+export declare function sourceBlock(data: Record<string, unknown> | null, field: string): Record<string, unknown> | undefined;
+/** What is wrong with the proposal fields of `block`, as `<path> <message>` lines. Empty when nothing is. */
+export declare function sourceBlockProblems(block: Record<string, unknown>, field: string): string[];
+/**
+ * The file a transcript pin names, when it can be read here: a `path`
+ * (absolute, `~/` from the home directory, or else from the workspace root)
+ * or a `file:` URI. Any other URI is not fetched, so it is never reachable.
+ */
+export declare function transcriptFile(transcript: {
+    path?: string;
+    uri?: string;
+}, workspaceDir: string): string | undefined;
+/**
+ * The `source-transcript-drift` message for `block`, or undefined: when its
+ * transcript pin is well formed, the file it names can be read here, and its
+ * bytes hash to something other than the pin. A transcript that can't be
+ * read says nothing either way.
+ */
+export declare function transcriptDrift(block: Record<string, unknown>, field: string, workspaceDir: string): string | undefined;
+//# sourceMappingURL=source-block.d.ts.map

package/dist/workspace/source-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-block.d.ts","sourceRoot":"","sources":["../../src/workspace/source-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,kDAAkD;AAClD,eAAO,MAAM,WAAW,oCAAqC,CAAC;AAC9D,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAKrD,+GAA+G;AAC/G,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuB5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGpH;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAI3F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpH;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBvH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.88.0",
+  "version": "0.90.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/serve.ts

@@ -11,7 +11,17 @@ export async function runServeLsp(ctx: CommandContext): Promise<number> {
 
 export async function runServeMcp(ctx: CommandContext): Promise<number> {
   const { McpServer } = await import("../mcp/server");
-  const server = new McpServer(ctx.plugins);
+  // #2700 — main() hands over no plugins only at a workspace root with no
+  // lexicon of its own (anywhere else it refuses first). There the lexicons
+  // are the chant members', and the server says which loaded.
+  let plugins = ctx.plugins;
+  let instructions: string | undefined;
+  if (plugins.length === 0) {
+    const { loadWorkspacePlugins } = await import("../mcp/workspace-plugins");
+    ({ plugins, instructions } = await loadWorkspacePlugins(process.cwd()));
+  }
+  // #2707 — at or inside a declared workspace, the workspace tools are served too.
+  const server = new McpServer(plugins, { instructions, workspace: { cwd: process.cwd() } });
   await server.start();
   await new Promise(() => {});
   return 0; // unreachable

package/src/cli/main.test.ts

@@ -71,6 +71,13 @@ describe("parseArgs", () => {
     expect(result.help).toBe(true);
   });
 
+  test("parses --version and -V (#2701)", () => {
+    expect(parseArgs(["--version"]).version).toBe(true);
+    expect(parseArgs(["-V"]).version).toBe(true);
+    expect(parseArgs(["build"]).version).toBeUndefined();
+    expect(() => parseArgs(["--version=1"])).toThrow();
+  });
+
   test("parses --output with value", () => {
     const result = parseArgs(["build", "--output", "stack.json"]);
     expect(result.output).toBe("stack.json");

package/src/cli/main.ts

@@ -7,6 +7,8 @@ import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 import { loadChantConfigUpward } from "../config";
 import { findProjectRoot, findWorkspaceRoot } from "../project-root";
+import { isNoLexiconDetected } from "../detectLexicon";
+import { CHANT_VERSION } from "./version";
 import { validateLexiconConfig, formatLexiconConfigProblems } from "../lexicon-config";
 import { armSandboxConfigEvaluation } from "../config-sandbox";
 import { armSandboxPolicyExecution } from "../lint/policy-import";
@@ -52,6 +54,7 @@ import type { LexiconPlugin } from "../lexicon";
  */
 const BOOLEAN_FLAGS = new Set([
   "--help",
+  "--version",
   "--agents",
   "--agent",
   "--all-projects",
@@ -167,6 +170,8 @@ export function parseArgs(args: string[]): ParsedArgs {
 
     if (arg === "--help" || arg === "-h") {
       result.help = true;
+    } else if (arg === "--version" || arg === "-V") {
+      result.version = true;
     } else if (arg === "--output" || arg === "-o") {
       result.output = args[++i];
     } else if (arg === "--format" || arg === "-f") {
@@ -971,6 +976,7 @@ Options:
                         resolved build parameter and per-file fold decision
                         instead of the one-line summaries
   -h, --help            Show this help message
+  -V, --version         Print the installed chant's version
   --on <lexicon>        Which runtime hosts the run: a configured lexicon with
                         an opRuntime, or the built-in local runtime when
                         omitted (every run subcommand; #2121)
@@ -1183,6 +1189,28 @@ async function loadPluginsOrExit(path: string): Promise<import("../lexicon").Lex
   return plugins;
 }
 
+/**
+ * #2700 — whether `path` is the root of a declared workspace and holds no
+ * lexicon of its own: no `lexicons` in a root config, and no lexicon import in
+ * the root's source, which leaves the members' directories out (#2527). A
+ * generated chud repo is this shape: its lexicons are all in `delivery/`.
+ * `chant serve mcp` starts there instead of refusing with "No lexicon
+ * detected", and serves core with the chant members' lexicons.
+ *
+ * A directory with no workspace declaration costs only `findWorkspaceRoot`'s
+ * existence checks, so a level-0 project reaches `loadPluginsOrExit` as before.
+ */
+async function isLexiconlessWorkspaceRoot(path: string): Promise<boolean> {
+  const target = resolve(path);
+  if (findWorkspaceRoot(target)?.dir !== target) return false;
+  try {
+    await resolveProjectLexicons(target);
+    return false;
+  } catch (error) {
+    return isNoLexiconDetected(error);
+  }
+}
+
 /** Whether `def` must run without evaluating the project's `chant.config.ts` (chant#2591). */
 function commandRunsNoConfig(def: CommandDef, args: ParsedArgs): boolean {
   return typeof def.runsNoConfig === "function" ? def.runsNoConfig(args) : def.runsNoConfig === true;
@@ -1388,6 +1416,15 @@ async function main(): Promise<void> {
     throw err;
   }
 
+  // #2701 — `chant --version` / `-V` prints the installed chant's version, the
+  // one the MCP server reports (./version.ts). With a command word it answers
+  // only for one of core's own commands; a lexicon-mounted verb keeps the flag.
+  if (args.version && (!args.command || resolveCommand(args, commandRegistry))) {
+    console.log(CHANT_VERSION);
+    await flushAndExit(0);
+    return;
+  }
+
   if (args.help || !args.command) {
     const groups = await loadPluginsBestEffort().then(collectCommandGroups).catch(() => []);
     printHelp(groups);
@@ -1515,7 +1552,9 @@ async function main(): Promise<void> {
   const plugins = match.def.requiresPlugins
     ? isGenerateComponents || isComponentsStatus || isEmulator || isFanOutFromFile
       ? await loadPlugins(await resolveProjectLexicons(resolve(projectPath)).catch(() => [])).catch(() => [])
-      : await loadPluginsOrExit(projectPath)
+      : match.def.name === "serve mcp" && (await isLexiconlessWorkspaceRoot(projectPath))
+        ? [] // #2700 — runServeMcp loads the chant members' lexicons itself.
+        : await loadPluginsOrExit(projectPath)
     : [];
   const serializers = plugins.map((p) => p.serializer);
   const ctx = { args, plugins, serializers };

package/src/cli/mcp/docs-parity.test.ts

@@ -39,8 +39,9 @@ const guideDoc = readFileSync(join(repoRoot, GUIDE_DOC), "utf8");
 const serverSrc = readFileSync(join(repoRoot, SERVER_SRC), "utf8");
 
 /** What a client is told when it asks, built from a server with no plugins loaded. */
-async function servedListing(method: "tools/list" | "resources/list"): Promise<string[]> {
-  const response = await new McpServer().handleRequest({ jsonrpc: "2.0", id: 1, method });
+async function servedListing(method: "tools/list" | "resources/list", inWorkspace = false): Promise<string[]> {
+  const server = inWorkspace ? new McpServer([], { workspace: { cwd: repoRoot } }) : new McpServer();
+  const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method });
   const result = response.result as { tools?: ToolDefinition[]; resources?: ResourceDefinition[] };
   const names = result.tools?.map((t) => t.name) ?? result.resources?.map((r) => r.uri);
   if (!names || names.length === 0) {
@@ -82,6 +83,23 @@ describe("the MCP docs describe the server that ships (#2385)", () => {
     ).toEqual(sorted(registered));
   });
 
+  test("cli/mcp.mdx's Workspace tools table lists exactly the tools a server inside a workspace adds (#2707)", async () => {
+    const core = await servedListing("tools/list");
+    // This repository declares a workspace, so a server started in it has them.
+    const registered = (await servedListing("tools/list", true)).filter((n) => !core.includes(n));
+    expect(registered.length).toBeGreaterThan(0);
+    const listed = firstColumnCells(section(mcpDoc, "## Workspace tools", MCP_DOC));
+    expect(sorted(listed), `${MCP_DOC}'s "Workspace tools" table and the workspace tools disagree`).toEqual(sorted(registered));
+  });
+
+  test("guide/agent-integration.mdx lists exactly the workspace tools (#2707)", async () => {
+    const core = await servedListing("tools/list");
+    const registered = (await servedListing("tools/list", true)).filter((n) => !core.includes(n));
+    expect(registered.length).toBeGreaterThan(0);
+    const listed = firstColumnCells(section(guideDoc, "### Workspace Tools", GUIDE_DOC));
+    expect(sorted(listed), `${GUIDE_DOC}'s "Workspace Tools" table and the workspace tools a server inside a workspace registers disagree`).toEqual(sorted(registered));
+  });
+
   test("guide/agent-integration.mdx lists exactly the tools the server registers", async () => {
     const registered = await servedListing("tools/list");
     const listed = firstColumnCells(section(guideDoc, "### Available Tools", GUIDE_DOC));

package/src/cli/mcp/server.ts

@@ -8,7 +8,9 @@ import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import { compositesTool, createCompositesHandler } from "./tools/composites";
 import type { LexiconPlugin } from "../../lexicon";
-import type { McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import type { McpClientInfo, McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
+import { findWorkspaceRoot } from "../../project-root";
+import { createWorkspaceTools, type WorkspaceToolsOptions } from "./workspace-tools";
 import { createSnapshotTool, createDiffTool } from "./lifecycle-tools";
 import { setGateOrigin } from "../../lifecycle/gate-origin";
 import { createOpListTool, createOpRunTool, createOpStatusTool, createOpApproveTool, createOpReportTool } from "./op-tools";
@@ -47,14 +49,14 @@ export function negotiateProtocolVersion(requested: string | undefined): string
  * sends on `initialize`. Read-side only — the server holds no handshake
  * state to update (#1194).
  */
-export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: { name: string; version?: string } } {
+export function parseMeta(params: Record<string, unknown>): { protocolVersion?: string; clientInfo?: McpClientInfo } {
   const meta = (params._meta ?? {}) as McpRequestMeta;
   const protocolVersion =
     (typeof meta.protocolVersion === "string" ? meta.protocolVersion : undefined) ??
     (typeof params.protocolVersion === "string" ? params.protocolVersion : undefined);
   const clientInfo =
     meta["io.modelcontextprotocol/clientInfo"] ??
-    (params.clientInfo as { name: string; version?: string } | undefined);
+    (params.clientInfo as McpClientInfo | undefined);
   return { protocolVersion, clientInfo };
 }
 
@@ -93,9 +95,23 @@ export class McpServer {
   private toolHandlers: Map<string, ToolHandler> = new Map();
   private pluginResources: Map<string, { definition: ResourceDefinition; handler: () => Promise<string> }> = new Map();
   private plugins: LexiconPlugin[];
+  private instructions: string | undefined;
+  /** The `clientInfo` the client gave on `initialize`, for a request that carries none in `_meta` (#2707). */
+  private clientInfo: McpClientInfo | undefined;
 
-  constructor(plugins?: LexiconPlugin[]) {
+  /**
+   * `options.instructions` is sent as the `initialize` result's
+   * `instructions`, the text a client may give its model about this server.
+   * Only a workspace root with no lexicon of its own sets it (#2700), to say
+   * which members' lexicons were loaded.
+   *
+   * `options.workspace` names the directory the server serves (#2707). When
+   * it is at or inside a declared workspace, the workspace read-contract and
+   * record-write tools are served too.
+   */
+  constructor(plugins?: LexiconPlugin[], options: { instructions?: string; workspace?: WorkspaceToolsOptions } = {}) {
     this.plugins = plugins ?? [];
+    this.instructions = options.instructions;
     // Register core tools
     this.registerTool(buildTool, handleBuild);
     this.registerTool(lintTool, handleLint);
@@ -118,6 +134,11 @@ export class McpServer {
       this.registerTool(t.definition, t.handler);
     }
 
+    // Workspace reads and record writes (#2707), inside a declared workspace only.
+    if (options.workspace && findWorkspaceRoot(options.workspace.cwd)) {
+      for (const t of createWorkspaceTools(options.workspace)) this.registerTool(t.definition, t.handler);
+    }
+
     // Register plugin contributions
     if (plugins) {
       for (const plugin of plugins) {
@@ -226,6 +247,7 @@ export class McpServer {
       capabilities: { tools: {}, resources: {} },
       // The installed chant's version, so a client can tell which chant it talks to (#2689).
       serverInfo: { name: "chant", version: CHANT_VERSION },
+      ...(this.instructions ? { instructions: this.instructions } : {}),
     };
   }
 
@@ -235,6 +257,8 @@ export class McpServer {
   private async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
     switch (method) {
       case "initialize":
+        // Kept for a write's source block (#2707): a prior-revision client names itself only here.
+        this.clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
         // Answered for prior-revision clients too — negotiated, not hard-coded (#1194).
         return this.buildInitializeResult(params);
 
@@ -281,7 +305,9 @@ export class McpServer {
     }
 
     try {
-      const result = await handler(toolParams);
+      // The client, from this request's _meta (2026-07-28) or else from initialize.
+      const clientInfo = parseMeta(params).clientInfo ?? this.clientInfo;
+      const result = await handler(toolParams, clientInfo ? { clientInfo } : {});
       const isStructured = typeof result === "object" && result !== null;
       return {
         content: [
@@ -365,6 +391,6 @@ export async function startMcpServer(): Promise<void> {
     // Start without plugins if resolution fails
   }
 
-  const server = new McpServer(plugins);
+  const server = new McpServer(plugins, { workspace: { cwd: process.cwd() } });
   server.start();
 }

package/src/cli/mcp/types.ts

@@ -32,7 +32,7 @@ export interface McpResponse {
  */
 export interface McpRequestMeta {
   protocolVersion?: string;
-  "io.modelcontextprotocol/clientInfo"?: { name: string; version?: string };
+  "io.modelcontextprotocol/clientInfo"?: McpClientInfo;
 }
 
 /**
@@ -68,4 +68,17 @@ export interface ResourceDefinition {
   mimeType?: string;
 }
 
-export type ToolHandler = (params: Record<string, unknown>) => Promise<unknown>;
+/** The MCP client's `clientInfo`, as it gave it on `initialize` or in a request's `_meta`. */
+export interface McpClientInfo {
+  name: string;
+  version?: string;
+  title?: string;
+}
+
+/** What a handler knows about the call beyond its arguments (#2707). */
+export interface ToolContext {
+  /** The client that made the call, when it said. */
+  clientInfo?: McpClientInfo;
+}
+
+export type ToolHandler = (params: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;

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

@@ -0,0 +1,123 @@
+/**
+ * #2700 — the lexicons `chant serve mcp` loads at the root of a declared
+ * workspace that has no lexicon of its own.
+ *
+ * Such a root (a generated chud repo, say, whose lexicons are all in
+ * `delivery/`) used to refuse with "No lexicon detected", so an agent started
+ * there got none of chant's tools. The server now starts with core's tools and
+ * resources, and with the lexicons of the workspace's members of kind chant,
+ * each read from that member's own config the way `chant build` in the
+ * member's directory reads it.
+ *
+ * Loading is best effort, one member and one lexicon at a time: a member whose
+ * config does not load, or a lexicon this chant cannot import, is left out and
+ * named in the server's `instructions`, and the rest are served. Nothing here
+ * fails the server; with nothing loaded it serves core alone and says so.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { LexiconPlugin } from "../../lexicon";
+
+/** One member of kind chant, and what came of reading its lexicons. */
+export interface MemberLexicons {
+  member: string;
+  dir: string;
+  /** The lexicon names its config declares or its source imports, or null when they could not be read. */
+  lexicons: string[] | null;
+  /** Why they could not be read. */
+  error?: string;
+}
+
+export interface WorkspacePlugins {
+  plugins: LexiconPlugin[];
+  members: MemberLexicons[];
+  /** Lexicons named by a member that did not load, with the reason. */
+  failed: { lexicon: string; error: string }[];
+  /** The text the MCP server gives as its `instructions`. */
+  instructions: string;
+}
+
+function message(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.split("\n")[0];
+}
+
+/** Load the lexicons of the chant members of the workspace declared at `root`. */
+export async function loadWorkspacePlugins(root: string): Promise<WorkspacePlugins> {
+  const [{ readDeclaration }, { workingTree }, { resolveProjectLexicons, loadPlugins }] = await Promise.all([
+    import("../../workspace/declaration"),
+    import("../../workspace/tree"),
+    import("../plugins"),
+  ]);
+
+  const members: MemberLexicons[] = [];
+  let workspaceName: string | undefined;
+  let declarationError: string | undefined;
+  try {
+    const declaration = readDeclaration(workingTree(root));
+    workspaceName = declaration.name;
+    for (const m of declaration.members) {
+      // The root member is the directory this server already found no lexicon in.
+      if (m.kind !== "chant" || m.dir === ".") continue;
+      const abs = join(root, m.dir);
+      if (!existsSync(abs)) {
+        members.push({ member: m.name, dir: m.dir, lexicons: null, error: "its directory does not exist" });
+        continue;
+      }
+      try {
+        members.push({ member: m.name, dir: m.dir, lexicons: await resolveProjectLexicons(abs) });
+      } catch (error) {
+        members.push({ member: m.name, dir: m.dir, lexicons: null, error: message(error) });
+      }
+    }
+  } catch (error) {
+    declarationError = message(error);
+  }
+
+  const plugins: LexiconPlugin[] = [];
+  const failed: { lexicon: string; error: string }[] = [];
+  const seen = new Set<string>();
+  for (const m of members) {
+    for (const name of m.lexicons ?? []) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      try {
+        plugins.push(...(await loadPlugins([name])));
+      } catch (error) {
+        failed.push({ lexicon: name, error: message(error) });
+      }
+    }
+  }
+
+  return { plugins, members, failed, instructions: describe(workspaceName, members, plugins, failed, declarationError) };
+}
+
+function describe(
+  name: string | undefined,
+  members: MemberLexicons[],
+  plugins: LexiconPlugin[],
+  failed: { lexicon: string; error: string }[],
+  declarationError: string | undefined,
+): string {
+  const lines: string[] = [];
+  lines.push(
+    `This chant MCP server runs at the root of the workspace ${name ? `"${name}" ` : ""}(chant.workspace.json), which has no lexicon of its own. ` +
+      "Core tools and resources are served as in any project. The tools that take a path (build, lint, explain) work on a project directory, so pass a member's directory.",
+  );
+  if (declarationError) lines.push(`The workspace declaration could not be read: ${declarationError}.`);
+  for (const m of members) {
+    lines.push(
+      m.lexicons
+        ? `Member ${m.member} (${m.dir}/) declares ${m.lexicons.length ? m.lexicons.join(", ") : "no lexicon"}.`
+        : `Member ${m.member} (${m.dir}/) was not read: ${m.error}.`,
+    );
+  }
+  for (const f of failed) lines.push(`Lexicon ${f.lexicon} did not load: ${f.error}.`);
+  lines.push(
+    plugins.length > 0
+      ? `Lexicon tools and resources served: ${plugins.map((p) => p.name).join(", ")}.`
+      : "No member lexicon loaded, so only chant's core tools and resources are served.",
+  );
+  return lines.join("\n");
+}