@intentius/chant 0.45.0 → 0.49.0

package/src/cli/handlers/lifecycle.ts

@@ -18,6 +18,8 @@ import {
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
+import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
+import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
 import {
   formatUnobserved,
   mergeObservations,
@@ -30,7 +32,9 @@ import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 import { affectedStacks } from "../../lifecycle/affected";
 import { rollbackToRevision } from "../../lifecycle/rollback";
-import { loadChantConfig, environmentNames } from "../../config";
+import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, resolveOwnershipStack } from "../../config";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env";
+import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -109,7 +113,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const declaredParams = await commandBuildParams(config.buildParams, args);
   if (!declaredParams) return 1;
   const declaredEnvNames = environmentNames(config.environments);
-  if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
+  if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
       message: `Unknown environment "${environment}"`,
       hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
@@ -356,6 +360,10 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   // committed set. Absent is the normal state (nothing accepted yet).
   const baseline = args.live ? await readObservationBaseline(environment) : null;
   const accepted: Record<string, DeviationToAccept[]> = {};
+  // Effect receipts across every target's build (#1833) — `--update-baseline`
+  // refuses to accept drift on them (the effect step is their only writer),
+  // and recognition is marker-based so materialized lexicon rows are caught.
+  const receiptEntities = new Set<string>();
 
   // #1166 — an environment can declare its own endpoint (a local emulator like
   // Floci), so `--live` is self-sufficient even when the ambient shell never
@@ -428,6 +436,9 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
         for (const [lexicon, deviations] of Object.entries(r.toAccept)) {
           (accepted[lexicon] ??= []).push(...deviations);
         }
+        if (args.updateBaseline) {
+          for (const name of collectEffectReceipts(buildResult.entities).keys()) receiptEntities.add(name);
+        }
         if (json) {
           if (target.stack) perStackJson[target.stack] = r.byLexicon;
           else combinedLexiconsJson = r.byLexicon;
@@ -441,7 +452,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
     // accepted, so it stops re-alerting. Runs before the summary lines so the
     // "no drift" verdict below still describes the run that produced it.
     if (args.live && args.updateBaseline) {
-      await recordAcceptedBaseline(environment, baseline, accepted, json);
+      await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities);
     }
 
     if (args.live) {
@@ -493,6 +504,7 @@ async function recordAcceptedBaseline(
   existing: ObservationBaseline | null,
   accepted: Record<string, DeviationToAccept[]>,
   json: boolean,
+  receipts?: ReadonlySet<string>,
 ): Promise<void> {
   const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
   if (total === 0) {
@@ -503,11 +515,14 @@ async function recordAcceptedBaseline(
     }
     return;
   }
-  let next = existing ?? emptyBaseline(environment);
-  for (const [lexicon, deviations] of Object.entries(accepted)) {
-    next = acceptDeviations(next, lexicon, deviations);
-  }
   try {
+    // `acceptDeviations` throws on an effect-receipt deviation (#1833) —
+    // inside the try so the refusal reaches the operator as a formatted
+    // error, with no baseline written at all.
+    let next = existing ?? emptyBaseline(environment);
+    for (const [lexicon, deviations] of Object.entries(accepted)) {
+      next = acceptDeviations(next, lexicon, deviations, { receipts });
+    }
     await writeObservationBaseline(next);
     const pushed = await pushLifecycle();
     if (!json) {
@@ -518,7 +533,7 @@ async function recordAcceptedBaseline(
     }
   } catch (err) {
     console.error(formatError({
-      message: `--update-baseline: could not write the baseline — ${err instanceof Error ? err.message : String(err)}`,
+      message: `--update-baseline: baseline not updated — ${err instanceof Error ? err.message : String(err)}`,
     }));
   }
 }
@@ -1124,6 +1139,15 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   const merged: ChangeSet = { env: environment, entries: [] };
   let checked = 0;
 
+  // Effect receipts (#1832): declared, diffed, and observed like any resource,
+  // but observe-only to the generic apply path — the plan compares live value
+  // to resolved expectation and proposes the fire, never a create/update.
+  const receipts = collectEffectReceipts(buildResult.entities);
+  const receiptReadings = new Map<string, ReceiptReading>();
+  // Every lexicon's observed resources merged, for resolving a receipt's
+  // reference inputs against observed values / stack outputs at plan time.
+  const allObservedResources: Record<string, ResourceMetadata> = {};
+
   // #1166 — same self-sufficiency as `chant graph --live`: an environment can
   // declare its own endpoint, applied here unless the ambient shell already
   // set it. `chant lifecycle plan` is always a live read (no `--live` flag of
@@ -1154,11 +1178,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
       const declared = new Set<string>();
       const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
       for (const [name, entity] of buildResult.entities) {
-        if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
+        // A receipt has no `props` payload of its own but is declared, diffed,
+        // and observed like any resource (#1832) — it joins the declared axis
+        // so its lexicon's observation can confirm presence or absence.
+        if (entity.lexicon === lexiconName && (isResourceDeclarable(entity) || isEffectReceipt(entity))) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (isResourceDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }
@@ -1183,6 +1210,37 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         ...(args.namespace ? { namespace: args.namespace } : {}),
       });
 
+      Object.assign(allObservedResources, observed.resources);
+      for (const [receiptName, receipt] of receipts) {
+        if (receipt.lexicon !== lexiconName) continue;
+        const live = observed.resources[receiptName];
+        const hole = observed.unobserved[receiptName];
+        if (live) {
+          receiptReadings.set(receiptName, {
+            observed: true,
+            present: true,
+            value: readReceiptValue(live.attributes),
+            type: live.type,
+            ...(live.physicalId ? { physicalId: live.physicalId } : {}),
+            lexicon: lexiconName,
+          });
+        } else if (hole) {
+          receiptReadings.set(receiptName, {
+            observed: false,
+            present: false,
+            lexicon: lexiconName,
+            ...(hole.type ? { type: hole.type } : {}),
+            unobservedReason: hole.reason,
+            ...(hole.detail ? { unobservedDetail: hole.detail } : {}),
+          });
+        } else {
+          // Neither returned nor named unobserved: the lexicon looked and
+          // confirmed the receipt absent — the same claim the change set
+          // reads off a bare observation (#1089).
+          receiptReadings.set(receiptName, { observed: true, present: false, lexicon: lexiconName });
+        }
+      }
+
       const content = await readSnapshot(environment, lexiconName);
       const observedThen = content ? (JSON.parse(content) as LifecycleSnapshot).resources : undefined;
 
@@ -1212,6 +1270,16 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // Receipt classification (#1832): live value vs resolved expectation.
+  // Absent/stale proposes the fire; unobservable is a loud hole; whatever the
+  // generic classification proposed for a receipt (a create, a delete) is
+  // replaced — the effect step is the sole writer, and a receipt is never a
+  // prune candidate.
+  if (receipts.size > 0) {
+    const receiptEntries = planReceipts(receipts, receiptReadings, observedValueResolver(allObservedResources));
+    mergeReceiptEntries(merged, receipts, receiptEntries);
+  }
+
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
@@ -1240,6 +1308,227 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * chant lifecycle teardown <environment> (#1222).
+ *
+ * Enumerates what deleting the environment would remove: every live resource
+ * carrying this project's ownership marker (managed-by + `ownership.stack`)
+ * with the requested env identity. Stateless — live markers only, no build, no
+ * snapshot. Without `--yes` nothing is deleted; with it the planned set is
+ * executed per lexicon with one bounded retry pass over failures, and every
+ * candidate's outcome is reported (deleted / failed / not-prunable / retained / skipped —
+ * never silence). A production-like environment name additionally requires an
+ * interactive confirmation, or `--confirm-prod` non-interactively.
+ */
+export async function runLifecycleTeardown(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle teardown <environment>" }));
+    return 1;
+  }
+
+  const { config } = await loadChantConfig(resolve("."));
+
+  // Refuse an env the project does not declare — a typo here is the difference
+  // between tearing down `dev` and tearing down `prod`. Literal `environments`
+  // entries only (#1221's pattern entries would extend this same check).
+  const envErr = unknownEnvError(environment, config.environments);
+  if (envErr) {
+    console.error(formatError({ message: envErr }));
+    return 1;
+  }
+
+  // Teardown selects on the ownership marker; a project that stamps none has
+  // nothing to key on, and "delete what looks like mine" is not a fallback.
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) {
+    console.error(formatError({
+      message: "This project declares no ownership.stack — teardown is marker-scoped and has nothing to select on",
+      hint: 'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.',
+    }));
+    return 1;
+  }
+
+  // The prod guard (#1222): a production-like name never falls to `--yes`
+  // alone. Interactive runs re-type the environment name; non-interactive
+  // runs say `--confirm-prod` explicitly. Checked before any live read so a
+  // refused teardown touches nothing at all.
+  if (args.yes && isProdLikeEnvironment(environment) && !args.confirmProd) {
+    if (!process.stdin.isTTY) {
+      console.error(formatError({
+        message: `"${environment}" looks like a production environment — --yes alone is not enough`,
+        hint: "Re-run with --yes --confirm-prod to tear it down non-interactively.",
+      }));
+      return 1;
+    }
+    const confirmed = await promptProdTeardown(environment);
+    if (!confirmed) {
+      console.error(formatError({ message: "Confirmation did not match — nothing was deleted." }));
+      return 1;
+    }
+  }
+
+  // #1166 — teardown is always a live read (and with --yes, a live write), so
+  // an environment's declared endpoint applies here too, unless the ambient
+  // shell already set it.
+  const readingPlugins = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+  const endpointResult = applyLiveEndpoint(config.environments, environment, readingPlugins);
+  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+  let plan: TeardownPlan;
+  let report: TeardownReport | undefined;
+  try {
+    // A multi-stack project's declared stacks, for stack-shaped teardowns
+    // (aws enumerates and deletes whole CloudFormation stacks). A single-stack
+    // project passes nothing and the env-named default convention applies.
+    const deployedStacks = (config.stacks ?? []).map((s) => ({
+      name: s.name,
+      ...(s.region ? { region: s.region } : {}),
+    }));
+    plan = await planTeardown({
+      environment,
+      stack,
+      plugins,
+      ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+    });
+    if (args.yes) {
+      report = await executeTeardown({
+        environment,
+        stack,
+        plugins,
+        plan,
+        ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+      });
+    }
+  } finally {
+    endpointResult.restore();
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report ?? plan, null, 2));
+    return report && report.outcomes.some((o) => o.outcome === "failed") ? 1 : 0;
+  }
+
+  console.log(formatBold(
+    args.yes
+      ? `Teardown — environment: ${environment}, stack: ${stack}`
+      : `Teardown plan — environment: ${environment}, stack: ${stack} (plan only — nothing is deleted)`,
+  ));
+
+  if (plan.entries.length === 0) {
+    console.error(formatWarning({
+      message: `No live resources carry the marker stack "${stack}" + env "${environment}" — nothing would be deleted.` +
+        (plan.holes.length > 0
+          ? " But this plan has holes (below) — parts of the estate could not be read, so \"nothing\" is a claim about what was readable, not about the environment."
+          : " If this environment is deployed, check that its resources were stamped (ownership marking on, and the env identity resolved at build time)."),
+    }));
+  } else {
+    console.log(`\n${plan.entries.length} resource(s) would be deleted:`);
+    console.log("RESOURCE".padEnd(28) + "TYPE".padEnd(32) + "MARKER".padEnd(24) + "LEXICON");
+    console.log("-".repeat(96));
+    for (const entry of plan.entries) {
+      console.log(
+        entry.name.padEnd(28) +
+        entry.type.padEnd(32) +
+        `${entry.marker.stack}/${entry.marker.env}`.padEnd(24) +
+        entry.lexicon,
+      );
+    }
+  }
+
+  // Holes are loud (#1089): an unreadable kind is unknown, not absent, and the
+  // execution half must not treat this plan as the whole delete set.
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: `${plan.holes.length} hole(s) — resources chant may own but could not read. This plan is incomplete, not clean.`,
+    }));
+    console.log(formatBold("\nHOLES (stamped kinds the read could not cover):"));
+    for (const hole of plan.holes) {
+      console.log(`  ? ${hole.lexicon}: ${hole.name}${hole.type ? ` (${hole.type})` : ""} — ${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}`);
+    }
+  }
+
+  if (plan.skipped.length > 0) {
+    console.error(formatWarning({
+      message: `Skipped (no teardown enumeration and no describeResources): ${plan.skipped.join(", ")} — those lexicons' resources are not in this plan.`,
+    }));
+  }
+
+  if (!report) {
+    console.error(formatWarning({ message: "Plan only — re-run with --yes to execute." }));
+    return 0;
+  }
+
+  if (report.outcomes.length > 0) {
+    console.log(formatBold("\nOutcomes:"));
+    console.log("RESOURCE".padEnd(28) + "OUTCOME".padEnd(14) + "LEXICON".padEnd(12) + "DETAIL");
+    console.log("-".repeat(96));
+    for (const o of report.outcomes) {
+      console.log(
+        o.name.padEnd(28) +
+        o.outcome.padEnd(14) +
+        o.lexicon.padEnd(12) +
+        (o.detail ?? "") +
+        (o.retried ? " (after retry)" : ""),
+      );
+    }
+  }
+
+  const counts = { deleted: 0, failed: 0, "not-prunable": 0, retained: 0, skipped: 0 };
+  for (const o of report.outcomes) counts[o.outcome]++;
+  console.log(
+    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ` +
+    `${counts.retained} retained, ${counts.skipped} skipped`,
+  );
+
+  if (report.unimplemented.length > 0) {
+    console.error(formatWarning({
+      message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
+    }));
+  }
+  if (counts.retained > 0) {
+    console.error(formatWarning({
+      message: `${counts.retained} resource(s) retained — owned by this env but deliberately kept (generated-once secrets are never swept). ` +
+        `The environment is NOT clean while they exist; delete them explicitly (e.g. kubectl delete) if you mean to.`,
+    }));
+  }
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",
+    }));
+  }
+  if (counts.failed > 0) {
+    console.error(formatError({
+      message: `${counts.failed} candidate(s) failed to delete after the retry pass — see the outcomes above.`,
+    }));
+    return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * The interactive half of the prod guard: the operator re-types the
+ * environment name. Anything else — including EOF — refuses.
+ */
+async function promptProdTeardown(environment: string): Promise<boolean> {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolvePrompt) => {
+    rl.question(
+      `"${environment}" looks like a production environment. Type the environment name to confirm teardown: `,
+      (answer) => {
+        resolvePrompt(answer.trim() === environment);
+        rl.close();
+      },
+    );
+    // EOF (Ctrl-D) closes the interface without answering — that is a refusal.
+    rl.on("close", () => resolvePrompt(false));
+  });
+}
+
 /**
  * chant lifecycle log [environment]
  */
@@ -1268,7 +1557,7 @@ export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
 export async function runLifecycleUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle teardown, chant lifecycle log",
   }));
   return 1;
 }

package/src/cli/handlers/search.ts

@@ -9,7 +9,7 @@ import { discover } from "../../discovery/index";
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
 import type { LiveObservation } from "../../graph-ir";
-import { loadChantConfig } from "../../config";
+import { loadChantConfig, matchesDeclaredEnvironment } from "../../config";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatError, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
@@ -89,7 +89,10 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       }));
       return 1;
     }
-    if (config.environments && !config.environments.includes(environment)) {
+    // Membership via matchesDeclaredEnvironment (#1221): handles `{ name,
+    // endpoint }` entries (#1166) — a plain `.includes` never matched those —
+    // and glob-pattern entries like `"pr-*"`.
+    if (config.environments && config.environments.length > 0 && !matchesDeclaredEnvironment(config.environments, environment)) {
       console.error(formatError({ message: `Unknown environment "${environment}"` }));
       return 1;
     }

package/src/cli/main.ts

@@ -23,7 +23,7 @@ import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
 import { runCarveEmit } from "./handlers/carve-emit";
 import { runCarveBridge } from "./handlers/carve-bridge";
 import { runCarveApply } from "./handlers/carve-apply";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
@@ -78,6 +78,8 @@ const BOOLEAN_FLAGS = new Set([
   "--fold",
   "--no-fold",
   "--sandbox",
+  "--yes",
+  "--confirm-prod",
 ]);
 
 /**
@@ -228,6 +230,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.emit = args[++i];
     } else if (arg === "--dry-run") {
       result.dryRun = true;
+    } else if (arg === "--yes") {
+      result.yes = true;
+    } else if (arg === "--confirm-prod") {
+      result.confirmProd = true;
     } else if (arg === "--strict") {
       result.strict = true;
     } else if (arg === "--validate") {
@@ -484,6 +490,10 @@ Lifecycle (alias: lc):
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle teardown <env>  Plan what deleting the environment would remove —
+                            marker-scoped (this project's stack + env); --yes
+                            executes the plan (production-like names also need
+                            --confirm-prod, or an interactive confirmation)
   lifecycle log [env]       History of lifecycle snapshots
 
 Component release ledger + status:
@@ -780,6 +790,7 @@ const registry: CommandDef[] = [
   { name: "lifecycle rollback", handler: runLifecycleRollback },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+  { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
 
   // Component release ledger + status surface (#568, epic #551)

package/src/cli/mcp/resource-handlers.ts

@@ -1,10 +1,13 @@
-import { resolve } from "node:path";
+import { resolve, join, dirname } from "node:path";
+import { readFile } from "node:fs/promises";
 import type { ResourceDefinition } from "./types";
 import { getContext } from "./resources/context";
 import { readSnapshot, readEnvironmentSnapshots } from "../../lifecycle/git";
 import { discoverOps } from "../../op/discover";
 import { makeTemporalClient } from "../handlers/run";
 import { resolveWorkflowId } from "../handlers/run-client";
+import { loadOkfBundle } from "../../okf-read";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../config";
 
 type PluginResourceEntry = { definition: ResourceDefinition; handler: () => Promise<string> };
 
@@ -42,6 +45,12 @@ export const coreResourceDefinitions: ResourceDefinition[] = [
     description: "Latest run state for a named Op",
     mimeType: "application/json",
   },
+  {
+    uri: "chant://knowledge",
+    name: "Knowledge bundle",
+    description: "The project's OKF knowledge bundle (#1864, #1059): index.md and every authored concept, empty when no bundle exists",
+    mimeType: "application/json",
+  },
   {
     uri: "chant://state/{environment}",
     name: "State (all lexicons)",
@@ -122,6 +131,34 @@ export async function handleResourcesRead(
     };
   }
 
+  // Authored knowledge (#1867, #1864, design #1059): same bundle the CLI's
+  // `chant explain` reads, over MCP — the resource path has no local
+  // filesystem, so this is the only way an MCP client sees the `knowledge/`
+  // directory's contents at all. Resolved from cwd, matching every other
+  // path-less resource here (`chant://ops`, `chant://state/...`). A missing
+  // bundle is not an error — `loadOkfBundle` already treats it as empty, and
+  // a missing `index.md` reads as `index: null` rather than throwing.
+  if (uri === "chant://knowledge") {
+    const cwd = resolve(".");
+    const loaded = await loadChantConfigUpward(cwd);
+    const projectRoot = loaded.configPath ? dirname(loaded.configPath) : cwd;
+    const dir = resolveKnowledgeDir(loaded.config, projectRoot);
+    const bundle = await loadOkfBundle(dir);
+    let index: string | null = null;
+    try {
+      index = await readFile(join(dir, "index.md"), "utf8");
+    } catch {
+      index = null;
+    }
+    return {
+      contents: [{
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify({ dir, index, concepts: bundle.concepts }, null, 2),
+      }],
+    };
+  }
+
   // Op resources
   if (uri === "chant://ops") {
     const { ops } = await discoverOps();

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

@@ -590,6 +590,7 @@ describe("McpServer", () => {
       expect(uris).toContain("chant://ops");
       expect(uris).toContain("chant://ops/{name}/runs");
       expect(uris).toContain("chant://ops/{name}/runs/latest");
+      expect(uris).toContain("chant://knowledge");
 
       // Each resource has required fields
       for (const resource of result.resources) {
@@ -735,6 +736,62 @@ describe("McpServer", () => {
         expect(data.error).toBeDefined();
       });
     });
+
+    describe("chant://knowledge", () => {
+      test("empty gracefully when no bundle exists", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string; mimeType: string }> };
+          expect(result.contents[0].mimeType).toBe("application/json");
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBeNull();
+          expect(data.concepts).toEqual([]);
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+
+      test("serves the bundle index and concepts when present", async () => {
+        const originalCwd = process.cwd();
+        process.chdir(testDir);
+        try {
+          await mkdir(join(testDir, "knowledge", "decisions"), { recursive: true });
+          await writeFile(join(testDir, "knowledge", "index.md"), "# Knowledge index\n");
+          await writeFile(
+            join(testDir, "knowledge", "decisions", "public-assets.md"),
+            "---\ntype: decision\ntitle: Public assets\nbinds: bucket\n---\nBody text.\n",
+          );
+
+          const response = await server.handleRequest({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "resources/read",
+            params: { uri: "chant://knowledge" },
+          });
+          expect(response.error).toBeUndefined();
+          const result = response.result as { contents: Array<{ text: string }> };
+          const data = JSON.parse(result.contents[0].text);
+          expect(data.index).toBe("# Knowledge index\n");
+          expect(data.concepts).toHaveLength(1);
+          expect(data.concepts[0]).toMatchObject({
+            path: "decisions/public-assets.md",
+            type: "decision",
+            title: "Public assets",
+            binds: ["bucket"],
+          });
+        } finally {
+          process.chdir(originalCwd);
+        }
+      });
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -1157,7 +1214,7 @@ describe("McpServer", () => {
 
       const resourcesRes = await s.handleRequest({ jsonrpc: "2.0", id: 3, method: "resources/list" });
       const resources = (resourcesRes.result as { resources: Array<{ uri: string }> }).resources;
-      expect(resources).toHaveLength(7);
+      expect(resources).toHaveLength(8);
     });
 
     test("server with empty plugins array works", async () => {