dld-kit 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -36,7 +36,7 @@ This writes:
 
 - `dld.config.yaml`, `decisions/records/` and `decisions/INDEX.md`
 - the `dld-*` skills for each selected agent: `.claude/skills/` for Claude Code, `.agents/skills/` for the others
-- the always-on rule: `.claude/rules/dld-workflow.md` for Claude Code, `.agents/rules/dld-workflow.md` for Antigravity, and a block between `<!-- dld-kit:start -->` and `<!-- dld-kit:end -->` in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi
+- the always-on rule, once per agent: a block between `<!-- dld-kit:start -->` and `<!-- dld-kit:end -->` in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi, `.agents/rules/dld-workflow.md` for Antigravity, and `.claude/rules/dld-workflow.md` for Claude Code unless Claude Code already reads the block (see [Agents](#agents)). When the block goes into `AGENTS.md` and the project has no `CLAUDE.md` or `.claude/CLAUDE.md`, it writes `.claude/CLAUDE.md` instead, which imports `AGENTS.md` for Claude Code
 
 `init` detects the agents from files in the project (`.claude/`, `.codex/`, `.cursor/`, `opencode.json`, `.pi/`, `AGENTS.md` and so on) and asks you to confirm the list. Options:
 
@@ -114,18 +114,31 @@ Channels can be combined. These combinations need care:
 
 | Agent | Skills (`dld init`) | Always-on rule (`dld init`, `/dld-init`) | Run a skill |
 |---|---|---|---|
-| Claude Code | `.claude/skills/` | `.claude/rules/dld-workflow.md` | `/dld-plan` |
+| Claude Code | `.claude/skills/` | `.claude/rules/dld-workflow.md`, or the block in `CLAUDE.md`, or in `AGENTS.md` imported from a CLAUDE file (`@AGENTS.md`) | `/dld-plan` |
 | Antigravity | `.agents/skills/` | `.agents/rules/dld-workflow.md` | Ask for the dld-plan skill |
 | Codex | `.agents/skills/` | Block in `AGENTS.md` | Ask for the dld-plan skill |
-| Cursor | `.agents/skills/` | Block in `AGENTS.md` | Ask for the dld-plan skill |
-| OpenCode | `.agents/skills/` | Block in `AGENTS.md`, or `CLAUDE.md` if there is no `AGENTS.md` | Ask for the dld-plan skill |
+| Cursor | `.agents/skills/` | Block in `AGENTS.md` or `CLAUDE.md` (Cursor reads both) | Ask for the dld-plan skill |
+| OpenCode | `.agents/skills/` | Block in `AGENTS.md` (OpenCode 2.x reads no `CLAUDE.md`) | Ask for the dld-plan skill |
 | Pi | `.agents/skills/` | Block in `AGENTS.md`, or `CLAUDE.md` if there is no `AGENTS.md` | `/skill:dld-plan` |
 | Copilot CLI | Plugin only | Block in `AGENTS.md` (installed as for Codex) | Ask for the dld-plan skill |
 
-A new block goes into `AGENTS.md` if it exists, else into `CLAUDE.md` if that exists, else into a new `AGENTS.md`. Codex and Cursor read only `AGENTS.md`: when the block ends up in `CLAUDE.md`, `dld install-rule` warns and says how to move it.
+A new block goes into `AGENTS.md` if it exists. Otherwise it goes into an existing `CLAUDE.md` only when every selected agent that takes the block (Codex, Cursor, OpenCode, Pi) reads that file, which Cursor and Pi do, and into a new `AGENTS.md` in all other cases. Pi reads `CLAUDE.md` only while there is no `AGENTS.md`, so when `dld` creates `AGENTS.md` next to a `CLAUDE.md` for Pi, it warns you to move anything Pi needs. A block already in `CLAUDE.md` stays there; `dld install-rule` warns about agents that cannot see it (Codex, OpenCode) and says how to move it.
+
+Each agent gets the rule once. Claude Code reads `AGENTS.md` by itself only when the project has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`, so adding one of those (even an uncommitted `CLAUDE.local.md`) would stop it. When the block is in `AGENTS.md` and the project has no `CLAUDE.md` or `.claude/CLAUDE.md`, `init` writes `.claude/CLAUDE.md` with the line `@../AGENTS.md`. Claude Code then loads `AGENTS.md` through that import, once, whichever CLAUDE files are added later. If a `CLAUDE.md` of yours already imports `@AGENTS.md`, the block there is Claude Code's rule and no other file is written.
 
 The examples below use Claude Code's `/dld-plan` form. In other agents, name the skill instead, e.g. "use the dld-plan skill to plan the retry feature".
 
+### Upgrading from 0.x
+
+Before 1.0, the skills were copied by hand or installed with Tessl, each skill carried `scripts/*.sh`, and `/dld-init` appended a `## DLD (Decision-Linked Development)` section to `CLAUDE.md`.
+
+- **Your data carries over unchanged:** `dld.config.yaml`, `decisions/records/`, `decisions/INDEX.md` and `decisions/.dld-state.yaml`. 1.0 reads them as 0.x wrote them.
+- **Skills copied into `.claude/skills/` or `.agents/skills/`:** in the project, run `npx dld-kit@latest update --agent <names>` (e.g. `--agent claude,codex`). It rewrites the `dld-*` skills, deletes their old `scripts/*.sh`, and installs the always-on rule. Commit the result.
+- **Skills copied anywhere else** (e.g. `.cursor/skills/`, `.codex/skills/`): delete those `dld-*` directories, then run the same `update`.
+- **Tessl installs:** remove the `dld-kit/dld` tile with Tessl, and delete any DLD rule text Tessl added. Then run `update`. The Tessl tile gets no new versions.
+- **The old `CLAUDE.md` section:** once the rule is installed, delete the `## DLD (Decision-Linked Development)` section yourself. Until then Claude Code and Cursor read the rule twice. `update` warns while the section is there, and never edits it.
+- **To use the plugin or `npx skills` instead:** delete the copied `dld-*` directories and the old `CLAUDE.md` section first, then install through that channel.
+
 ## Get started
 
 ### New feature or change
@@ -367,10 +380,12 @@ The `dld` command comes with the npm package (`npx dld-kit <command>`, or `npm i
 | `dld update` | Rewrites the installed skills and rule with this version; `--agent` adds agents |
 | `dld install-rule --agent <names>` | Installs or refreshes only the always-on rule |
 | `dld session-context --agent <name>` | Prints the rule for a session hook, unless the agent loads it already (used by the Claude Code plugin) |
-| `dld --help` | Lists every command; the rest are the operations the skills run |
+| `dld --help` | Lists the setup commands above, then the commands the skills run |
 
 `init` and `update` refuse to overwrite files from a newer dld-kit unless given `--force`.
 
+Semantic versioning covers the four commands above, their flags, exit codes and documented output, and `--help` and `--version`. The other commands (`next-id`, `create-decision`, `regenerate-index` and so on) are internal: the skills run them from their own bundled copy of the CLI, and their names, arguments and output can change in a minor release. Don't script against them.
+
 ## Development
 
 ```bash
@@ -411,7 +426,7 @@ DLD is under active development. Feature requests and ideas are welcome — [ope
 
 ## Manual rule setup
 
-The always-on rule tells the agent to read a decision before changing code annotated with it. `/dld-init` installs it with `dld install-rule --agent <harness>`, which picks the file the harness loads: `.claude/rules/dld-workflow.md` for Claude Code, `.agents/rules/dld-workflow.md` for Antigravity, or a marked block in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi.
+The always-on rule tells the agent to read a decision before changing code annotated with it. `/dld-init` installs it with `dld install-rule --agent <harness>`, which picks the file the harness loads: `.claude/rules/dld-workflow.md` for Claude Code (unless it reads the block in `AGENTS.md`, directly or through a `.claude/CLAUDE.md` import), `.agents/rules/dld-workflow.md` for Antigravity, or a marked block in `AGENTS.md` (or `CLAUDE.md`) for Codex, Cursor, OpenCode and Pi.
 
 To add it by hand instead, copy [`templates/rules/dld-workflow.md`](templates/rules/dld-workflow.md) into one of those files.
 

package/dist/dld.mjs

@@ -7372,7 +7372,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 // package.json
-var version = "1.0.0-rc.1";
+var version = "1.0.0-rc.3";
 
 // src/core/errors.ts
 var EXIT_ERROR = 1;
@@ -7944,6 +7944,7 @@ function updateSnapshotState(ctx, project, customArtifacts) {
 var collectActiveDecisionsCommand = {
   name: "collect-active-decisions",
   summary: "Print every accepted decision record",
+  internal: true,
   usage: "Usage: dld collect-active-decisions\n\nPrint each accepted record in ID order, separated by ===DLD_DECISION_BOUNDARY=== lines.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8326,6 +8327,7 @@ function skippedNotice(reason) {
 var commitReindexCommand = {
   name: "commit-reindex",
   summary: "Squash the branch into one reindex commit",
+  internal: true,
   usage: `Usage: dld commit-reindex --base <ref> < plan
 
 Read a rename plan on standard input and squash the branch's commits since the merge-base
@@ -8386,6 +8388,7 @@ function createDirectories(ctx, { config, paths }) {
 var createConfigCommand = {
   name: "create-config",
   summary: "Create dld.config.yaml at the project root",
+  internal: true,
   usage: "Usage: dld create-config <flat|namespaced> [namespace ...]\n\nCreate dld.config.yaml. Namespaced mode needs at least one namespace.\n",
   run(args, io, ctx) {
     const { positionals } = parseCommandArgs({
@@ -8443,6 +8446,7 @@ function isSafeDirName(name) {
 var createDecisionCommand = {
   name: "create-decision",
   summary: "Create a proposed decision record",
+  internal: true,
   usage: `Usage: dld create-decision --id <DL-NNN> --title <title> [options]
 
 Create a decision record with status proposed and print its path.
@@ -8494,6 +8498,7 @@ Options:
 var createDirectoriesCommand = {
   name: "create-directories",
   summary: "Create the decisions directory structure from the config",
+  internal: true,
   usage: "Usage: dld create-directories\n\nCreate the decisions and records directories, and one per namespace.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8562,6 +8567,7 @@ function writeIndex(ctx, paths, content) {
 var createEmptyIndexCommand = {
   name: "create-empty-index",
   summary: "Write an INDEX.md with no decisions",
+  internal: true,
   usage: "Usage: dld create-empty-index\n\nWrite INDEX.md in the decisions directory with only the table header.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8577,6 +8583,7 @@ var createEmptyIndexCommand = {
 var detectSnapshotChangesCommand = {
   name: "detect-snapshot-changes",
   summary: "Report what changed since the last snapshot",
+  internal: true,
   usage: "Usage: dld detect-snapshot-changes\n\nPrint mode (full or incremental), new_decisions, modified_decisions and commit_range.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8589,7 +8596,14 @@ var detectSnapshotChangesCommand = {
 import { join as join11, relative as relative6, sep as sep3 } from "node:path";
 var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git",
+  // Agent configuration directories, which hold installed skills.
   ".claude",
+  ".agents",
+  ".agent",
+  ".codex",
+  ".cursor",
+  ".opencode",
+  ".pi",
   ".tessl",
   "node_modules",
   "vendor",
@@ -8668,6 +8682,7 @@ function formatAnnotation({ file, line, id }) {
 var findAnnotationsCommand = {
   name: "find-annotations",
   summary: "List every annotation in the codebase",
+  internal: true,
   usage: "Usage: dld find-annotations\n\nPrint <file>:<line>:<DL-NNN> for every annotation, one per line.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8683,6 +8698,7 @@ var findAnnotationsCommand = {
 var findCollisionsCommand = {
   name: "find-collisions",
   summary: "List locally added decisions whose IDs are taken",
+  internal: true,
   usage: `Usage: dld find-collisions [--base <ref>]
 
 Print <path>\\t<DL-NNN> for each decision added on this branch whose ID is taken on the base
@@ -8749,6 +8765,7 @@ function updateAuditState(ctx, { paths }) {
 var findMissingAmendsCommand = {
   name: "find-missing-amends",
   summary: "List decision IDs mentioned in a body but not declared",
+  internal: true,
   usage: `Usage: dld find-missing-amends [--all]
 
 Print <source-id>:<referenced-id> for each decision ID a record's body mentions without
@@ -8859,6 +8876,7 @@ function formatStaleMention({ file, line, oldId, newId, text }) {
 var findStaleMentionsCommand = {
   name: "find-stale-mentions",
   summary: "List remaining mentions of renamed decision IDs",
+  internal: true,
   usage: `Usage: dld find-stale-mentions --base <ref> < plan
 
 Read a rename plan (<path>\\t<DL-OLD>\\t<DL-NEW> per line) on standard input and print
@@ -9040,7 +9058,6 @@ var AGENTS_LAYOUT = {
   dir: ".agents/skills"
 };
 var LAYOUTS = [CLAUDE_LAYOUT, AGENTS_LAYOUT];
-var AGENTS_FIRST = ["AGENTS.md", "CLAUDE.md"];
 var HARNESSES = [
   {
     name: "claude",
@@ -9048,7 +9065,8 @@ var HARNESSES = [
     layout: CLAUDE_LAYOUT,
     rule: "claude-file",
     markers: [".claude", "CLAUDE.md"],
-    instructions: ["CLAUDE.md", "AGENTS.md"]
+    // @decision(DL-054) @decision(DL-055)
+    instructions: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]
   },
   {
     name: "antigravity",
@@ -9072,7 +9090,9 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".cursor"],
-    instructions: ["AGENTS.md"]
+    // @decision(DL-061)
+    instructions: ["AGENTS.md", "CLAUDE.md"],
+    readsAll: true
   },
   {
     name: "opencode",
@@ -9080,7 +9100,8 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".opencode", "opencode.json", "opencode.jsonc"],
-    instructions: AGENTS_FIRST
+    // @decision(DL-061) OpenCode 2.x; 1.x also fell back to CLAUDE.md.
+    instructions: ["AGENTS.md"]
   },
   {
     name: "pi",
@@ -9088,7 +9109,7 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".pi"],
-    instructions: AGENTS_FIRST
+    instructions: ["AGENTS.md", "CLAUDE.md"]
   }
 ];
 var GENERIC_MARKERS = ["AGENTS.md", ".agents/skills"];
@@ -9255,7 +9276,7 @@ function removeEmptyParents(ctx, dir, paths) {
 }
 
 // src/generate/rule.ts
-import { dirname as dirname3, join as join15 } from "node:path";
+import { dirname as dirname3, join as join15, posix as posix4 } from "node:path";
 
 // templates/rules/dld-workflow.md
 var dld_workflow_default = "# DLD (Decision-Linked Development)\n\nThis project uses Decision-Linked Development. Decision records (DL-*.md) live in the `records/` subdirectory of the decisions directory set in `dld.config.yaml` (`decisions/` by default). High-level docs (INDEX.md, OVERVIEW.md, SNAPSHOT.md) live in the decisions directory.\n\n## Rules\n\n- When you encounter `@decision(DL-XXX)` annotations in code, read the referenced decision with the dld-lookup skill BEFORE modifying the annotated code.\n- ALWAYS look up and verify related decisions before modifying annotated code. Do not skip this step.\n- NEVER modify code in a way that contradicts an existing decision without first confirming with the user. If the change requires breaking a previous decision, a new decision must be recorded (with the dld-decide skill) that explicitly supersedes the old one. If it only partially modifies a previous decision, record it as an amendment instead.\n\n## Skills\n\n- dld-decide: record a new decision\n- dld-plan: break down a feature into multiple grouped decisions\n- dld-implement: implement proposed decisions\n- dld-lookup: query decisions by ID, tag, or code path\n- dld-adjust: adjust or update existing decisions\n- dld-audit: scan for drift between decisions and code\n- dld-snapshot: regenerate SNAPSHOT.md and OVERVIEW.md from the decision log\n- dld-status: a quick overview of the decision log state\n- dld-retrofit: generate decisions from an existing codebase\n- dld-reindex: resolve decision-ID collisions with the base branch (and open PRs) before rebasing\n";
@@ -9265,10 +9286,13 @@ var RULE_TEXT = dld_workflow_default;
 var RULE_SOURCE = "templates/rules/dld-workflow.md";
 var CLAUDE_RULE_FILE = ".claude/rules/dld-workflow.md";
 var AGENTS_RULE_FILE = ".agents/rules/dld-workflow.md";
+var CLAUDE_IMPORT_FILE = ".claude/CLAUDE.md";
 var BLOCK_START = "<!-- dld-kit:start -->";
 var BLOCK_END = "<!-- dld-kit:end -->";
 var AGENTS_MD = "AGENTS.md";
 var CLAUDE_MD = "CLAUDE.md";
+var CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE, "CLAUDE.local.md"];
+var SHARED_CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE];
 var RULE_FILES = {
   "claude-file": CLAUDE_RULE_FILE,
   "agents-file": AGENTS_RULE_FILE
@@ -9286,6 +9310,16 @@ function renderRuleFile(channel, text, version2) {
 
 ${text}`;
 }
+function renderImportFile(version2) {
+  return `<!-- Generated by dld-kit ${version2} for Claude Code: it loads AGENTS.md, which holds the DLD rule, through the import below. Do not edit: updating the rule overwrites this file. -->
+
+@../AGENTS.md
+`;
+}
+var IMPORT_STAMP = /^<!-- Generated by dld-kit (\S+) for Claude Code:/;
+function importFileVersion(content) {
+  return IMPORT_STAMP.exec(content)?.[1];
+}
 function renderBlock(text, version2) {
   const body = text.endsWith("\n") ? text.slice(0, -1) : text;
   return [BLOCK_START, notice(version2, "block"), "", ...body.split("\n"), BLOCK_END];
@@ -9334,25 +9368,53 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   let blockFiles = [AGENTS_MD, CLAUDE_MD].filter(
     (file) => regular(file) && findBlock(read(file), file) !== void 0
   );
-  if (blockFiles.length === 0 && channels.has("block")) blockFiles = [blockPlacement(ctx, root)];
+  if (blockFiles.length === 0 && channels.has("block")) {
+    const targets = harnesses.filter((h) => h.rule === "block");
+    const file = blockPlacement(ctx, root, targets);
+    blockFiles = [file];
+    plan.warnings.push(...switchWarnings(ctx, root, file, targets));
+  }
+  const pending = /* @__PURE__ */ new Map();
   for (const file of blockFiles) {
     const content = read(file);
     const updated = upsertBlock(content, renderBlock(text, version2), file);
+    pending.set(file, updated);
     if (updated !== content) plan.writes.push({ path: file, content: updated });
   }
+  const linkedDir = symlinkedPart(ctx, root, dirname3(CLAUDE_IMPORT_FILE));
+  const ownsImport = linkedDir === void 0 && importFileVersion(read(CLAUDE_IMPORT_FILE)) !== void 0;
+  const wantsImport = channels.has("claude-file") && blockFiles.includes(AGENTS_MD) && !SHARED_CLAUDE_FILES.some((file) => ctx.fs.lexists(join15(root, file)));
+  if (ownsImport || wantsImport && linkedDir === void 0) {
+    const content = renderImportFile(version2);
+    pending.set(CLAUDE_IMPORT_FILE, content);
+    if (read(CLAUDE_IMPORT_FILE) !== content) {
+      plan.writes.push({ path: CLAUDE_IMPORT_FILE, content });
+    }
+  } else if (wantsImport) {
+    plan.warnings.push(
+      `${linkedDir} is a symlink, so dld-kit does not write ${CLAUDE_IMPORT_FILE}, which would import AGENTS.md for Claude Code. Claude Code reads the rule block in AGENTS.md by itself only while the project has no CLAUDE.md, ${CLAUDE_IMPORT_FILE} or CLAUDE.local.md.`
+    );
+  }
   const withBlock = new Set(blockFiles.map(resolved));
-  const loads = (file) => withBlock.has(resolved(file));
-  const readsBlock = (harness) => loads(instructionFile(ctx, root, harness));
+  const current = projectView(ctx, root);
+  const view = {
+    exists: (file) => pending.has(file) || current.exists(file),
+    read: (file) => pending.get(file) ?? current.read(file)
+  };
+  const reads = (harness) => instructionFiles(harness, view)[0];
+  const readsBlock = (harness) => instructionFiles(harness, view).some((file) => withBlock.has(resolved(file)));
   const ownerOf = (channel) => HARNESSES.find((h) => h.rule === channel);
   const loadsBlock = (channel) => {
     const owner = ownerOf(channel);
     return owner !== void 0 && readsBlock(owner);
   };
-  const blind = harnesses.filter((h) => h.rule === "block" && !readsBlock(h));
-  if (blockFiles.length > 0 && blind.length > 0) {
-    const names = blind.map((h) => h.title).join(" and ");
+  if (blockFiles.length > 0) {
     plan.warnings.push(
-      `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${blind.length === 1 ? "reads" : "read"} ${AGENTS_MD}. To cover ${blind.length === 1 ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${AGENTS_MD}, then run dld install-rule.`
+      ...blindWarnings(
+        blockFiles,
+        harnesses.filter((h) => h.rule === "block" && !readsBlock(h)),
+        reads
+      )
     );
   }
   for (const channel of ["claude-file", "agents-file"]) {
@@ -9369,21 +9431,82 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   plan.warnings.push(...legacyBlockWarnings(read(CLAUDE_MD), ruleInstalled));
   return plan;
 }
-function instructionFile(ctx, root, harness) {
-  const { instructions } = harness;
-  return instructions.find((file) => ctx.fs.exists(join15(root, file))) ?? instructions.at(-1) ?? AGENTS_MD;
+function projectView(ctx, root) {
+  const exists = (file) => ctx.fs.exists(join15(root, file));
+  return {
+    exists,
+    read: (file) => exists(file) && !ctx.fs.isDirectory(join15(root, file)) ? ctx.fs.readFile(join15(root, file)) : ""
+  };
 }
-function blockPlacement(ctx, root) {
-  for (const file of [AGENTS_MD, CLAUDE_MD]) {
-    if (ctx.fs.isRegularFile(join15(root, file))) return file;
+function instructionFiles(harness, view) {
+  if (harness.name !== "claude") {
+    if (harness.readsAll) return harness.instructions.filter((f) => view.exists(f));
+    const file = harness.instructions.find((f) => view.exists(f));
+    return file === void 0 ? [] : [file];
+  }
+  const files = CLAUDE_FILES.filter((file) => view.exists(file));
+  if (files.length === 0) return view.exists(AGENTS_MD) ? [AGENTS_MD] : [];
+  const imported = files.some((file) => importsAgentsMd(view.read(file), file));
+  return imported && view.exists(AGENTS_MD) ? [...files, AGENTS_MD] : files;
+}
+var FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function importsAgentsMd(content, file) {
+  const dir = posix4.dirname(file);
+  let fence;
+  for (const line of content.split(/\r?\n/)) {
+    const marker = FENCE.exec(line)?.[1];
+    if (marker !== void 0) {
+      if (fence === void 0) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length) fence = void 0;
+      continue;
+    }
+    if (fence !== void 0) continue;
+    const prose = line.replace(/`[^`]*`/g, "");
+    for (const match of prose.matchAll(/(?:^|\s)@(\S+)/g)) {
+      const target = match[1];
+      if (target !== void 0 && posix4.normalize(posix4.join(dir, target)) === AGENTS_MD) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function blindWarnings(blockFiles, blind, reads) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const harness of blind) {
+    const file = reads(harness) ?? harness.instructions[0] ?? AGENTS_MD;
+    byFile.set(file, [...byFile.get(file) ?? [], harness]);
   }
-  if (ctx.fs.lexists(join15(root, AGENTS_MD))) {
+  return [...byFile].map(([file, harnesses]) => {
+    const names = harnesses.map((h) => h.title).join(" and ");
+    const one = harnesses.length === 1;
+    return `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${one ? "reads" : "read"} ${file}. To cover ${one ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${file}, then run dld install-rule.`;
+  });
+}
+function blockPlacement(ctx, root, targets) {
+  if (ctx.fs.isRegularFile(join15(root, AGENTS_MD))) return AGENTS_MD;
+  const agentsLinked = ctx.fs.lexists(join15(root, AGENTS_MD));
+  if (ctx.fs.isRegularFile(join15(root, CLAUDE_MD)) && (agentsLinked || targets.every((h) => h.instructions.includes(CLAUDE_MD)))) {
+    return CLAUDE_MD;
+  }
+  if (agentsLinked) {
     throw new DldError(
       `${AGENTS_MD} is not a regular file (a symlink?); dld-kit does not edit through it. Point it at a regular file or add the dld-kit block by hand.`
     );
   }
   return AGENTS_MD;
 }
+function switchWarnings(ctx, root, file, targets) {
+  if (file !== AGENTS_MD || ctx.fs.lexists(join15(root, AGENTS_MD))) return [];
+  const claudeMd = join15(root, CLAUDE_MD);
+  if (!ctx.fs.exists(claudeMd) || ctx.fs.isDirectory(claudeMd)) return [];
+  const switching = targets.filter((h) => !h.readsAll && h.instructions.includes(CLAUDE_MD));
+  if (switching.length === 0) return [];
+  const names = switching.map((h) => h.title).join(" and ");
+  return [
+    `dld-kit puts the rule block in a new AGENTS.md. ${names} will read AGENTS.md instead of CLAUDE.md from now on, so move anything ${switching.length === 1 ? "it needs" : "they need"} from CLAUDE.md into AGENTS.md.`
+  ];
+}
 var LEGACY_HEADING = /^## DLD \(Decision-Linked Development\)\s*$/;
 function legacyBlockWarnings(claudeMd, ruleInstalled) {
   const span = findBlock(claudeMd, CLAUDE_MD);
@@ -9398,32 +9521,43 @@ function loadsRule(ctx, root, harness) {
   if (harness.rule !== "block" && ctx.fs.exists(join15(root, RULE_FILES[harness.rule]))) {
     return true;
   }
-  const file = instructionFile(ctx, root, harness);
-  if (!ctx.fs.exists(join15(root, file))) return false;
-  return ctx.fs.readFile(join15(root, file)).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line));
+  const view = projectView(ctx, root);
+  return instructionFiles(harness, view).some(
+    (file) => view.read(file).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line))
+  );
 }
 function sessionContext(ctx, root, harness, text = RULE_TEXT) {
   if (!ctx.fs.exists(join15(root, CONFIG_FILE))) return void 0;
   return loadsRule(ctx, root, harness) ? void 0 : text;
 }
-function refuseSymlinkedDir(ctx, root, dir) {
+function symlinkedPart(ctx, root, dir) {
   let current = "";
   for (const part of dir.split("/")) {
     current = current === "" ? part : `${current}/${part}`;
     const full = join15(root, current);
-    if (!ctx.fs.lexists(full)) return;
+    if (!ctx.fs.lexists(full)) return void 0;
     if (!ctx.fs.exists(full) || ctx.fs.realPath(full) !== join15(ctx.fs.realPath(root), current)) {
-      throw new DldError(
-        `${current} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
-      );
+      return current;
     }
   }
+  return void 0;
+}
+function refuseSymlinkedDir(ctx, root, dir) {
+  const linked = symlinkedPart(ctx, root, dir);
+  if (linked !== void 0) {
+    throw new DldError(
+      `${linked} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
+    );
+  }
 }
 function installedRuleChannels(ctx, root) {
   const channels = /* @__PURE__ */ new Set();
   for (const channel of ["claude-file", "agents-file"]) {
     if (ctx.fs.lexists(join15(root, RULE_FILES[channel]))) channels.add(channel);
   }
+  if (importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE)) !== void 0) {
+    channels.add("claude-file");
+  }
   for (const file of [AGENTS_MD, CLAUDE_MD]) {
     const path = join15(root, file);
     if (ctx.fs.isRegularFile(path) && findBlock(ctx.fs.readFile(path), file) !== void 0) {
@@ -9438,6 +9572,8 @@ function installedRuleStamps(ctx, root) {
   for (const file of [CLAUDE_RULE_FILE, AGENTS_RULE_FILE].filter(regular)) {
     stamps.push({ path: file, version: ruleVersion(ctx.fs.readFile(join15(root, file))) });
   }
+  const imported = importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE));
+  if (imported !== void 0) stamps.push({ path: CLAUDE_IMPORT_FILE, version: imported });
   for (const file of [AGENTS_MD, CLAUDE_MD].filter(regular)) {
     const content = ctx.fs.readFile(join15(root, file));
     const span = findBlock(content, file);
@@ -9680,8 +9816,13 @@ function printReport(io, report2) {
     io.stdout(`${dir}: ${written} written, ${removed} removed, ${unchanged} unchanged
 `);
   }
-  for (const path of report2.ruleWritten) io.stdout(`Wrote the DLD rule to ${path}
-`);
+  for (const path of report2.ruleWritten) {
+    io.stdout(
+      path === CLAUDE_IMPORT_FILE ? `Wrote ${path} (imports AGENTS.md for Claude Code)
+` : `Wrote the DLD rule to ${path}
+`
+    );
+  }
   for (const path of report2.ruleRemoved) io.stdout(`Removed ${path} (the rule is in the block)
 `);
   for (const warning of report2.warnings) io.stderr(`Warning: ${warning}
@@ -9810,6 +9951,7 @@ ${AGENT_HELP}
 var listTakenIdsCommand = {
   name: "list-taken-ids",
   summary: "List decision IDs taken on the base branch and in open PRs",
+  internal: true,
   usage: `Usage: dld list-taken-ids [--base <ref>]
 
 Print the decision IDs on the base branch and in records touched by open pull requests
@@ -9833,6 +9975,7 @@ Options:
 var nextIdCommand = {
   name: "next-id",
   summary: "Print the next sequential decision ID",
+  internal: true,
   usage: "Usage: dld next-id\n\nPrint the next decision ID, e.g. DL-004.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -9847,6 +9990,7 @@ var nextIdCommand = {
 var planRenamesCommand = {
   name: "plan-renames",
   summary: "Plan renames that resolve decision ID collisions",
+  internal: true,
   usage: `Usage: dld plan-renames [--base <ref>]
 
 Print <path>\\t<DL-OLD>\\t<DL-NEW> for each colliding local decision, assigning the next free
@@ -9870,6 +10014,7 @@ Options:
 var regenerateIndexCommand = {
   name: "regenerate-index",
   summary: "Rebuild INDEX.md from the decision records",
+  internal: true,
   usage: `Usage: dld regenerate-index [--include-base <ref>]
 
 Rebuild INDEX.md from every decision record.
@@ -9897,6 +10042,7 @@ Options:
 var renameDecisionCommand = {
   name: "rename-decision",
   summary: "Rename a local decision and rewrite its references",
+  internal: true,
   usage: `Usage: dld rename-decision --old <DL-OLD> --new <DL-NEW> --path <path> [--base <ref>]
 
 Rename a locally added decision with git mv, rewrite its id and references in changed
@@ -9932,6 +10078,7 @@ Options:
 var resolveBaseCommand = {
   name: "resolve-base",
   summary: "Print the base ref to check decision IDs against",
+  internal: true,
   usage: `Usage: dld resolve-base
 
 Print the current branch's upstream when it tracks a differently named branch, otherwise
@@ -10043,6 +10190,7 @@ ${AGENT_HELP}
 var updateAuditStateCommand = {
   name: "update-audit-state",
   summary: "Record the audit run in .dld-state.yaml",
+  internal: true,
   usage: "Usage: dld update-audit-state\n\nRecord the current time and HEAD commit as the last audit.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -10057,6 +10205,7 @@ var updateAuditStateCommand = {
 var updateSnapshotStateCommand = {
   name: "update-snapshot-state",
   summary: "Record the snapshot run in .dld-state.yaml",
+  internal: true,
   usage: `Usage: dld update-snapshot-state [artifact ...]
 
 Record the snapshot time, HEAD commit and highest accepted decision, with timestamps for
@@ -10079,6 +10228,7 @@ SNAPSHOT.md, OVERVIEW.md and any custom artifacts named.
 var updateStatusCommand = {
   name: "update-status",
   summary: "Set a decision's status",
+  internal: true,
   usage: `Usage: dld update-status <DL-NNN> <${STATUSES.join("|")}>
 
 Change only the status line of a decision record.
@@ -10110,6 +10260,7 @@ var EXIT_MISSING = 1;
 var verifyAnnotationsCommand = {
   name: "verify-annotations",
   summary: "Check that decisions have annotations in the code",
+  internal: true,
   usage: "Usage: dld verify-annotations <DL-NNN> [DL-NNN ...]\n\nExit 0 if every decision has at least one annotation, 1 if any are missing.\n",
   run(args, io, ctx) {
     const { positionals: ids } = parseCommandArgs({
@@ -10163,11 +10314,19 @@ var COMMANDS = [
   findStaleMentionsCommand,
   commitReindexCommand
 ];
+var INTERNAL_HEADING = "Commands the skills run (internal; may change in minor releases)";
+var INTERNAL_NOTE = "Internal: the dld-kit skills run this command. Its name, arguments and output may change in a minor release.\n";
 function usage(commands) {
+  const list = (group) => group.map((c) => `  ${c.name.padEnd(25)} ${c.summary}`).join("\n");
+  const setup = commands.filter((c) => !c.internal);
+  const internal = commands.filter((c) => c.internal);
+  const sections = [`Setup commands:
+${list(setup)}`];
+  if (internal.length > 0) sections.push(`${INTERNAL_HEADING}:
+${list(internal)}`);
   return `Usage: dld <command> [options]
 
-Commands:
-${commands.map((c) => `  ${c.name.padEnd(20)} ${c.summary}`).join("\n")}
+${sections.join("\n\n")}
 
 Options:
   -h, --help     Show this help, or a command's help after its name
@@ -10206,7 +10365,8 @@ ${usage(commands)}`);
 }
 function report(error, command, io) {
   if (error instanceof HelpRequested) {
-    io.stdout(command.usage);
+    io.stdout(command.internal ? `${command.usage}
+${INTERNAL_NOTE}` : command.usage);
     return EXIT_OK;
   }
   if (error instanceof UsageError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dld-kit",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "description": "Decision-Linked Development: record, link, and audit development decisions alongside code",
   "license": "MIT",
   "author": {

package/skills/dld-adjust/SKILL.md

@@ -3,7 +3,7 @@ name: dld-adjust
 description: Adjust or update existing decision records. Handles permission gating for accepted decisions and correctly interprets adjustment requests.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-adjust/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-audit/SKILL.md

@@ -3,7 +3,7 @@ name: dld-audit
 description: Scan for drift between decisions and code. Finds orphaned annotations, stale references, and undocumented changes.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-audit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-audit-auto/SKILL.md

@@ -3,7 +3,7 @@ name: dld-audit-auto
 description: Autonomous audit — detects drift, fixes issues, and opens a PR. Designed for scheduled/CI execution without human interaction.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-audit-auto/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-common/SKILL.md

@@ -3,7 +3,7 @@ name: dld-common
 description: The dld CLI shared by the DLD skills. Not intended for direct invocation — the other DLD skills run it.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-common/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-common/scripts/dld.mjs

@@ -7372,7 +7372,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 // package.json
-var version = "1.0.0-rc.1";
+var version = "1.0.0-rc.3";
 
 // src/core/errors.ts
 var EXIT_ERROR = 1;
@@ -7944,6 +7944,7 @@ function updateSnapshotState(ctx, project, customArtifacts) {
 var collectActiveDecisionsCommand = {
   name: "collect-active-decisions",
   summary: "Print every accepted decision record",
+  internal: true,
   usage: "Usage: dld collect-active-decisions\n\nPrint each accepted record in ID order, separated by ===DLD_DECISION_BOUNDARY=== lines.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8326,6 +8327,7 @@ function skippedNotice(reason) {
 var commitReindexCommand = {
   name: "commit-reindex",
   summary: "Squash the branch into one reindex commit",
+  internal: true,
   usage: `Usage: dld commit-reindex --base <ref> < plan
 
 Read a rename plan on standard input and squash the branch's commits since the merge-base
@@ -8386,6 +8388,7 @@ function createDirectories(ctx, { config, paths }) {
 var createConfigCommand = {
   name: "create-config",
   summary: "Create dld.config.yaml at the project root",
+  internal: true,
   usage: "Usage: dld create-config <flat|namespaced> [namespace ...]\n\nCreate dld.config.yaml. Namespaced mode needs at least one namespace.\n",
   run(args, io, ctx) {
     const { positionals } = parseCommandArgs({
@@ -8443,6 +8446,7 @@ function isSafeDirName(name) {
 var createDecisionCommand = {
   name: "create-decision",
   summary: "Create a proposed decision record",
+  internal: true,
   usage: `Usage: dld create-decision --id <DL-NNN> --title <title> [options]
 
 Create a decision record with status proposed and print its path.
@@ -8494,6 +8498,7 @@ Options:
 var createDirectoriesCommand = {
   name: "create-directories",
   summary: "Create the decisions directory structure from the config",
+  internal: true,
   usage: "Usage: dld create-directories\n\nCreate the decisions and records directories, and one per namespace.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8562,6 +8567,7 @@ function writeIndex(ctx, paths, content) {
 var createEmptyIndexCommand = {
   name: "create-empty-index",
   summary: "Write an INDEX.md with no decisions",
+  internal: true,
   usage: "Usage: dld create-empty-index\n\nWrite INDEX.md in the decisions directory with only the table header.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8577,6 +8583,7 @@ var createEmptyIndexCommand = {
 var detectSnapshotChangesCommand = {
   name: "detect-snapshot-changes",
   summary: "Report what changed since the last snapshot",
+  internal: true,
   usage: "Usage: dld detect-snapshot-changes\n\nPrint mode (full or incremental), new_decisions, modified_decisions and commit_range.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8589,7 +8596,14 @@ var detectSnapshotChangesCommand = {
 import { join as join11, relative as relative6, sep as sep3 } from "node:path";
 var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git",
+  // Agent configuration directories, which hold installed skills.
   ".claude",
+  ".agents",
+  ".agent",
+  ".codex",
+  ".cursor",
+  ".opencode",
+  ".pi",
   ".tessl",
   "node_modules",
   "vendor",
@@ -8668,6 +8682,7 @@ function formatAnnotation({ file, line, id }) {
 var findAnnotationsCommand = {
   name: "find-annotations",
   summary: "List every annotation in the codebase",
+  internal: true,
   usage: "Usage: dld find-annotations\n\nPrint <file>:<line>:<DL-NNN> for every annotation, one per line.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -8683,6 +8698,7 @@ var findAnnotationsCommand = {
 var findCollisionsCommand = {
   name: "find-collisions",
   summary: "List locally added decisions whose IDs are taken",
+  internal: true,
   usage: `Usage: dld find-collisions [--base <ref>]
 
 Print <path>\\t<DL-NNN> for each decision added on this branch whose ID is taken on the base
@@ -8749,6 +8765,7 @@ function updateAuditState(ctx, { paths }) {
 var findMissingAmendsCommand = {
   name: "find-missing-amends",
   summary: "List decision IDs mentioned in a body but not declared",
+  internal: true,
   usage: `Usage: dld find-missing-amends [--all]
 
 Print <source-id>:<referenced-id> for each decision ID a record's body mentions without
@@ -8859,6 +8876,7 @@ function formatStaleMention({ file, line, oldId, newId, text }) {
 var findStaleMentionsCommand = {
   name: "find-stale-mentions",
   summary: "List remaining mentions of renamed decision IDs",
+  internal: true,
   usage: `Usage: dld find-stale-mentions --base <ref> < plan
 
 Read a rename plan (<path>\\t<DL-OLD>\\t<DL-NEW> per line) on standard input and print
@@ -9040,7 +9058,6 @@ var AGENTS_LAYOUT = {
   dir: ".agents/skills"
 };
 var LAYOUTS = [CLAUDE_LAYOUT, AGENTS_LAYOUT];
-var AGENTS_FIRST = ["AGENTS.md", "CLAUDE.md"];
 var HARNESSES = [
   {
     name: "claude",
@@ -9048,7 +9065,8 @@ var HARNESSES = [
     layout: CLAUDE_LAYOUT,
     rule: "claude-file",
     markers: [".claude", "CLAUDE.md"],
-    instructions: ["CLAUDE.md", "AGENTS.md"]
+    // @decision(DL-054) @decision(DL-055)
+    instructions: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]
   },
   {
     name: "antigravity",
@@ -9072,7 +9090,9 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".cursor"],
-    instructions: ["AGENTS.md"]
+    // @decision(DL-061)
+    instructions: ["AGENTS.md", "CLAUDE.md"],
+    readsAll: true
   },
   {
     name: "opencode",
@@ -9080,7 +9100,8 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".opencode", "opencode.json", "opencode.jsonc"],
-    instructions: AGENTS_FIRST
+    // @decision(DL-061) OpenCode 2.x; 1.x also fell back to CLAUDE.md.
+    instructions: ["AGENTS.md"]
   },
   {
     name: "pi",
@@ -9088,7 +9109,7 @@ var HARNESSES = [
     layout: AGENTS_LAYOUT,
     rule: "block",
     markers: [".pi"],
-    instructions: AGENTS_FIRST
+    instructions: ["AGENTS.md", "CLAUDE.md"]
   }
 ];
 var GENERIC_MARKERS = ["AGENTS.md", ".agents/skills"];
@@ -9255,7 +9276,7 @@ function removeEmptyParents(ctx, dir, paths) {
 }
 
 // src/generate/rule.ts
-import { dirname as dirname3, join as join15 } from "node:path";
+import { dirname as dirname3, join as join15, posix as posix4 } from "node:path";
 
 // templates/rules/dld-workflow.md
 var dld_workflow_default = "# DLD (Decision-Linked Development)\n\nThis project uses Decision-Linked Development. Decision records (DL-*.md) live in the `records/` subdirectory of the decisions directory set in `dld.config.yaml` (`decisions/` by default). High-level docs (INDEX.md, OVERVIEW.md, SNAPSHOT.md) live in the decisions directory.\n\n## Rules\n\n- When you encounter `@decision(DL-XXX)` annotations in code, read the referenced decision with the dld-lookup skill BEFORE modifying the annotated code.\n- ALWAYS look up and verify related decisions before modifying annotated code. Do not skip this step.\n- NEVER modify code in a way that contradicts an existing decision without first confirming with the user. If the change requires breaking a previous decision, a new decision must be recorded (with the dld-decide skill) that explicitly supersedes the old one. If it only partially modifies a previous decision, record it as an amendment instead.\n\n## Skills\n\n- dld-decide: record a new decision\n- dld-plan: break down a feature into multiple grouped decisions\n- dld-implement: implement proposed decisions\n- dld-lookup: query decisions by ID, tag, or code path\n- dld-adjust: adjust or update existing decisions\n- dld-audit: scan for drift between decisions and code\n- dld-snapshot: regenerate SNAPSHOT.md and OVERVIEW.md from the decision log\n- dld-status: a quick overview of the decision log state\n- dld-retrofit: generate decisions from an existing codebase\n- dld-reindex: resolve decision-ID collisions with the base branch (and open PRs) before rebasing\n";
@@ -9265,10 +9286,13 @@ var RULE_TEXT = dld_workflow_default;
 var RULE_SOURCE = "templates/rules/dld-workflow.md";
 var CLAUDE_RULE_FILE = ".claude/rules/dld-workflow.md";
 var AGENTS_RULE_FILE = ".agents/rules/dld-workflow.md";
+var CLAUDE_IMPORT_FILE = ".claude/CLAUDE.md";
 var BLOCK_START = "<!-- dld-kit:start -->";
 var BLOCK_END = "<!-- dld-kit:end -->";
 var AGENTS_MD = "AGENTS.md";
 var CLAUDE_MD = "CLAUDE.md";
+var CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE, "CLAUDE.local.md"];
+var SHARED_CLAUDE_FILES = [CLAUDE_MD, CLAUDE_IMPORT_FILE];
 var RULE_FILES = {
   "claude-file": CLAUDE_RULE_FILE,
   "agents-file": AGENTS_RULE_FILE
@@ -9286,6 +9310,16 @@ function renderRuleFile(channel, text, version2) {
 
 ${text}`;
 }
+function renderImportFile(version2) {
+  return `<!-- Generated by dld-kit ${version2} for Claude Code: it loads AGENTS.md, which holds the DLD rule, through the import below. Do not edit: updating the rule overwrites this file. -->
+
+@../AGENTS.md
+`;
+}
+var IMPORT_STAMP = /^<!-- Generated by dld-kit (\S+) for Claude Code:/;
+function importFileVersion(content) {
+  return IMPORT_STAMP.exec(content)?.[1];
+}
 function renderBlock(text, version2) {
   const body = text.endsWith("\n") ? text.slice(0, -1) : text;
   return [BLOCK_START, notice(version2, "block"), "", ...body.split("\n"), BLOCK_END];
@@ -9334,25 +9368,53 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   let blockFiles = [AGENTS_MD, CLAUDE_MD].filter(
     (file) => regular(file) && findBlock(read(file), file) !== void 0
   );
-  if (blockFiles.length === 0 && channels.has("block")) blockFiles = [blockPlacement(ctx, root)];
+  if (blockFiles.length === 0 && channels.has("block")) {
+    const targets = harnesses.filter((h) => h.rule === "block");
+    const file = blockPlacement(ctx, root, targets);
+    blockFiles = [file];
+    plan.warnings.push(...switchWarnings(ctx, root, file, targets));
+  }
+  const pending = /* @__PURE__ */ new Map();
   for (const file of blockFiles) {
     const content = read(file);
     const updated = upsertBlock(content, renderBlock(text, version2), file);
+    pending.set(file, updated);
     if (updated !== content) plan.writes.push({ path: file, content: updated });
   }
+  const linkedDir = symlinkedPart(ctx, root, dirname3(CLAUDE_IMPORT_FILE));
+  const ownsImport = linkedDir === void 0 && importFileVersion(read(CLAUDE_IMPORT_FILE)) !== void 0;
+  const wantsImport = channels.has("claude-file") && blockFiles.includes(AGENTS_MD) && !SHARED_CLAUDE_FILES.some((file) => ctx.fs.lexists(join15(root, file)));
+  if (ownsImport || wantsImport && linkedDir === void 0) {
+    const content = renderImportFile(version2);
+    pending.set(CLAUDE_IMPORT_FILE, content);
+    if (read(CLAUDE_IMPORT_FILE) !== content) {
+      plan.writes.push({ path: CLAUDE_IMPORT_FILE, content });
+    }
+  } else if (wantsImport) {
+    plan.warnings.push(
+      `${linkedDir} is a symlink, so dld-kit does not write ${CLAUDE_IMPORT_FILE}, which would import AGENTS.md for Claude Code. Claude Code reads the rule block in AGENTS.md by itself only while the project has no CLAUDE.md, ${CLAUDE_IMPORT_FILE} or CLAUDE.local.md.`
+    );
+  }
   const withBlock = new Set(blockFiles.map(resolved));
-  const loads = (file) => withBlock.has(resolved(file));
-  const readsBlock = (harness) => loads(instructionFile(ctx, root, harness));
+  const current = projectView(ctx, root);
+  const view = {
+    exists: (file) => pending.has(file) || current.exists(file),
+    read: (file) => pending.get(file) ?? current.read(file)
+  };
+  const reads = (harness) => instructionFiles(harness, view)[0];
+  const readsBlock = (harness) => instructionFiles(harness, view).some((file) => withBlock.has(resolved(file)));
   const ownerOf = (channel) => HARNESSES.find((h) => h.rule === channel);
   const loadsBlock = (channel) => {
     const owner = ownerOf(channel);
     return owner !== void 0 && readsBlock(owner);
   };
-  const blind = harnesses.filter((h) => h.rule === "block" && !readsBlock(h));
-  if (blockFiles.length > 0 && blind.length > 0) {
-    const names = blind.map((h) => h.title).join(" and ");
+  if (blockFiles.length > 0) {
     plan.warnings.push(
-      `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${blind.length === 1 ? "reads" : "read"} ${AGENTS_MD}. To cover ${blind.length === 1 ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${AGENTS_MD}, then run dld install-rule.`
+      ...blindWarnings(
+        blockFiles,
+        harnesses.filter((h) => h.rule === "block" && !readsBlock(h)),
+        reads
+      )
     );
   }
   for (const channel of ["claude-file", "agents-file"]) {
@@ -9369,21 +9431,82 @@ function planRule(ctx, root, channels, version2, { harnesses = [] } = {}, text =
   plan.warnings.push(...legacyBlockWarnings(read(CLAUDE_MD), ruleInstalled));
   return plan;
 }
-function instructionFile(ctx, root, harness) {
-  const { instructions } = harness;
-  return instructions.find((file) => ctx.fs.exists(join15(root, file))) ?? instructions.at(-1) ?? AGENTS_MD;
+function projectView(ctx, root) {
+  const exists = (file) => ctx.fs.exists(join15(root, file));
+  return {
+    exists,
+    read: (file) => exists(file) && !ctx.fs.isDirectory(join15(root, file)) ? ctx.fs.readFile(join15(root, file)) : ""
+  };
 }
-function blockPlacement(ctx, root) {
-  for (const file of [AGENTS_MD, CLAUDE_MD]) {
-    if (ctx.fs.isRegularFile(join15(root, file))) return file;
+function instructionFiles(harness, view) {
+  if (harness.name !== "claude") {
+    if (harness.readsAll) return harness.instructions.filter((f) => view.exists(f));
+    const file = harness.instructions.find((f) => view.exists(f));
+    return file === void 0 ? [] : [file];
+  }
+  const files = CLAUDE_FILES.filter((file) => view.exists(file));
+  if (files.length === 0) return view.exists(AGENTS_MD) ? [AGENTS_MD] : [];
+  const imported = files.some((file) => importsAgentsMd(view.read(file), file));
+  return imported && view.exists(AGENTS_MD) ? [...files, AGENTS_MD] : files;
+}
+var FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function importsAgentsMd(content, file) {
+  const dir = posix4.dirname(file);
+  let fence;
+  for (const line of content.split(/\r?\n/)) {
+    const marker = FENCE.exec(line)?.[1];
+    if (marker !== void 0) {
+      if (fence === void 0) fence = marker;
+      else if (marker[0] === fence[0] && marker.length >= fence.length) fence = void 0;
+      continue;
+    }
+    if (fence !== void 0) continue;
+    const prose = line.replace(/`[^`]*`/g, "");
+    for (const match of prose.matchAll(/(?:^|\s)@(\S+)/g)) {
+      const target = match[1];
+      if (target !== void 0 && posix4.normalize(posix4.join(dir, target)) === AGENTS_MD) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function blindWarnings(blockFiles, blind, reads) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const harness of blind) {
+    const file = reads(harness) ?? harness.instructions[0] ?? AGENTS_MD;
+    byFile.set(file, [...byFile.get(file) ?? [], harness]);
   }
-  if (ctx.fs.lexists(join15(root, AGENTS_MD))) {
+  return [...byFile].map(([file, harnesses]) => {
+    const names = harnesses.map((h) => h.title).join(" and ");
+    const one = harnesses.length === 1;
+    return `The dld-kit rule block is in ${blockFiles.join(" and ")}, but ${names} ${one ? "reads" : "read"} ${file}. To cover ${one ? "it" : "them"}, move the block (the dld-kit:start line through the dld-kit:end line) into ${file}, then run dld install-rule.`;
+  });
+}
+function blockPlacement(ctx, root, targets) {
+  if (ctx.fs.isRegularFile(join15(root, AGENTS_MD))) return AGENTS_MD;
+  const agentsLinked = ctx.fs.lexists(join15(root, AGENTS_MD));
+  if (ctx.fs.isRegularFile(join15(root, CLAUDE_MD)) && (agentsLinked || targets.every((h) => h.instructions.includes(CLAUDE_MD)))) {
+    return CLAUDE_MD;
+  }
+  if (agentsLinked) {
     throw new DldError(
       `${AGENTS_MD} is not a regular file (a symlink?); dld-kit does not edit through it. Point it at a regular file or add the dld-kit block by hand.`
     );
   }
   return AGENTS_MD;
 }
+function switchWarnings(ctx, root, file, targets) {
+  if (file !== AGENTS_MD || ctx.fs.lexists(join15(root, AGENTS_MD))) return [];
+  const claudeMd = join15(root, CLAUDE_MD);
+  if (!ctx.fs.exists(claudeMd) || ctx.fs.isDirectory(claudeMd)) return [];
+  const switching = targets.filter((h) => !h.readsAll && h.instructions.includes(CLAUDE_MD));
+  if (switching.length === 0) return [];
+  const names = switching.map((h) => h.title).join(" and ");
+  return [
+    `dld-kit puts the rule block in a new AGENTS.md. ${names} will read AGENTS.md instead of CLAUDE.md from now on, so move anything ${switching.length === 1 ? "it needs" : "they need"} from CLAUDE.md into AGENTS.md.`
+  ];
+}
 var LEGACY_HEADING = /^## DLD \(Decision-Linked Development\)\s*$/;
 function legacyBlockWarnings(claudeMd, ruleInstalled) {
   const span = findBlock(claudeMd, CLAUDE_MD);
@@ -9398,32 +9521,43 @@ function loadsRule(ctx, root, harness) {
   if (harness.rule !== "block" && ctx.fs.exists(join15(root, RULE_FILES[harness.rule]))) {
     return true;
   }
-  const file = instructionFile(ctx, root, harness);
-  if (!ctx.fs.exists(join15(root, file))) return false;
-  return ctx.fs.readFile(join15(root, file)).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line));
+  const view = projectView(ctx, root);
+  return instructionFiles(harness, view).some(
+    (file) => view.read(file).split(/\r?\n/).some((line) => line === BLOCK_START || LEGACY_HEADING.test(line))
+  );
 }
 function sessionContext(ctx, root, harness, text = RULE_TEXT) {
   if (!ctx.fs.exists(join15(root, CONFIG_FILE))) return void 0;
   return loadsRule(ctx, root, harness) ? void 0 : text;
 }
-function refuseSymlinkedDir(ctx, root, dir) {
+function symlinkedPart(ctx, root, dir) {
   let current = "";
   for (const part of dir.split("/")) {
     current = current === "" ? part : `${current}/${part}`;
     const full = join15(root, current);
-    if (!ctx.fs.lexists(full)) return;
+    if (!ctx.fs.lexists(full)) return void 0;
     if (!ctx.fs.exists(full) || ctx.fs.realPath(full) !== join15(ctx.fs.realPath(root), current)) {
-      throw new DldError(
-        `${current} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
-      );
+      return current;
     }
   }
+  return void 0;
+}
+function refuseSymlinkedDir(ctx, root, dir) {
+  const linked = symlinkedPart(ctx, root, dir);
+  if (linked !== void 0) {
+    throw new DldError(
+      `${linked} is a symlink; dld-kit does not install through symlinks. Replace it with a directory (dld-kit keeps each agent's copy separate).`
+    );
+  }
 }
 function installedRuleChannels(ctx, root) {
   const channels = /* @__PURE__ */ new Set();
   for (const channel of ["claude-file", "agents-file"]) {
     if (ctx.fs.lexists(join15(root, RULE_FILES[channel]))) channels.add(channel);
   }
+  if (importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE)) !== void 0) {
+    channels.add("claude-file");
+  }
   for (const file of [AGENTS_MD, CLAUDE_MD]) {
     const path = join15(root, file);
     if (ctx.fs.isRegularFile(path) && findBlock(ctx.fs.readFile(path), file) !== void 0) {
@@ -9438,6 +9572,8 @@ function installedRuleStamps(ctx, root) {
   for (const file of [CLAUDE_RULE_FILE, AGENTS_RULE_FILE].filter(regular)) {
     stamps.push({ path: file, version: ruleVersion(ctx.fs.readFile(join15(root, file))) });
   }
+  const imported = importFileVersion(projectView(ctx, root).read(CLAUDE_IMPORT_FILE));
+  if (imported !== void 0) stamps.push({ path: CLAUDE_IMPORT_FILE, version: imported });
   for (const file of [AGENTS_MD, CLAUDE_MD].filter(regular)) {
     const content = ctx.fs.readFile(join15(root, file));
     const span = findBlock(content, file);
@@ -9680,8 +9816,13 @@ function printReport(io, report2) {
     io.stdout(`${dir}: ${written} written, ${removed} removed, ${unchanged} unchanged
 `);
   }
-  for (const path of report2.ruleWritten) io.stdout(`Wrote the DLD rule to ${path}
-`);
+  for (const path of report2.ruleWritten) {
+    io.stdout(
+      path === CLAUDE_IMPORT_FILE ? `Wrote ${path} (imports AGENTS.md for Claude Code)
+` : `Wrote the DLD rule to ${path}
+`
+    );
+  }
   for (const path of report2.ruleRemoved) io.stdout(`Removed ${path} (the rule is in the block)
 `);
   for (const warning of report2.warnings) io.stderr(`Warning: ${warning}
@@ -9810,6 +9951,7 @@ ${AGENT_HELP}
 var listTakenIdsCommand = {
   name: "list-taken-ids",
   summary: "List decision IDs taken on the base branch and in open PRs",
+  internal: true,
   usage: `Usage: dld list-taken-ids [--base <ref>]
 
 Print the decision IDs on the base branch and in records touched by open pull requests
@@ -9833,6 +9975,7 @@ Options:
 var nextIdCommand = {
   name: "next-id",
   summary: "Print the next sequential decision ID",
+  internal: true,
   usage: "Usage: dld next-id\n\nPrint the next decision ID, e.g. DL-004.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -9847,6 +9990,7 @@ var nextIdCommand = {
 var planRenamesCommand = {
   name: "plan-renames",
   summary: "Plan renames that resolve decision ID collisions",
+  internal: true,
   usage: `Usage: dld plan-renames [--base <ref>]
 
 Print <path>\\t<DL-OLD>\\t<DL-NEW> for each colliding local decision, assigning the next free
@@ -9870,6 +10014,7 @@ Options:
 var regenerateIndexCommand = {
   name: "regenerate-index",
   summary: "Rebuild INDEX.md from the decision records",
+  internal: true,
   usage: `Usage: dld regenerate-index [--include-base <ref>]
 
 Rebuild INDEX.md from every decision record.
@@ -9897,6 +10042,7 @@ Options:
 var renameDecisionCommand = {
   name: "rename-decision",
   summary: "Rename a local decision and rewrite its references",
+  internal: true,
   usage: `Usage: dld rename-decision --old <DL-OLD> --new <DL-NEW> --path <path> [--base <ref>]
 
 Rename a locally added decision with git mv, rewrite its id and references in changed
@@ -9932,6 +10078,7 @@ Options:
 var resolveBaseCommand = {
   name: "resolve-base",
   summary: "Print the base ref to check decision IDs against",
+  internal: true,
   usage: `Usage: dld resolve-base
 
 Print the current branch's upstream when it tracks a differently named branch, otherwise
@@ -10043,6 +10190,7 @@ ${AGENT_HELP}
 var updateAuditStateCommand = {
   name: "update-audit-state",
   summary: "Record the audit run in .dld-state.yaml",
+  internal: true,
   usage: "Usage: dld update-audit-state\n\nRecord the current time and HEAD commit as the last audit.\n",
   run(args, io, ctx) {
     parseCommandArgs({ args: [...args], options: {} });
@@ -10057,6 +10205,7 @@ var updateAuditStateCommand = {
 var updateSnapshotStateCommand = {
   name: "update-snapshot-state",
   summary: "Record the snapshot run in .dld-state.yaml",
+  internal: true,
   usage: `Usage: dld update-snapshot-state [artifact ...]
 
 Record the snapshot time, HEAD commit and highest accepted decision, with timestamps for
@@ -10079,6 +10228,7 @@ SNAPSHOT.md, OVERVIEW.md and any custom artifacts named.
 var updateStatusCommand = {
   name: "update-status",
   summary: "Set a decision's status",
+  internal: true,
   usage: `Usage: dld update-status <DL-NNN> <${STATUSES.join("|")}>
 
 Change only the status line of a decision record.
@@ -10110,6 +10260,7 @@ var EXIT_MISSING = 1;
 var verifyAnnotationsCommand = {
   name: "verify-annotations",
   summary: "Check that decisions have annotations in the code",
+  internal: true,
   usage: "Usage: dld verify-annotations <DL-NNN> [DL-NNN ...]\n\nExit 0 if every decision has at least one annotation, 1 if any are missing.\n",
   run(args, io, ctx) {
     const { positionals: ids } = parseCommandArgs({
@@ -10163,11 +10314,19 @@ var COMMANDS = [
   findStaleMentionsCommand,
   commitReindexCommand
 ];
+var INTERNAL_HEADING = "Commands the skills run (internal; may change in minor releases)";
+var INTERNAL_NOTE = "Internal: the dld-kit skills run this command. Its name, arguments and output may change in a minor release.\n";
 function usage(commands) {
+  const list = (group) => group.map((c) => `  ${c.name.padEnd(25)} ${c.summary}`).join("\n");
+  const setup = commands.filter((c) => !c.internal);
+  const internal = commands.filter((c) => c.internal);
+  const sections = [`Setup commands:
+${list(setup)}`];
+  if (internal.length > 0) sections.push(`${INTERNAL_HEADING}:
+${list(internal)}`);
   return `Usage: dld <command> [options]
 
-Commands:
-${commands.map((c) => `  ${c.name.padEnd(20)} ${c.summary}`).join("\n")}
+${sections.join("\n\n")}
 
 Options:
   -h, --help     Show this help, or a command's help after its name
@@ -10206,7 +10365,8 @@ ${usage(commands)}`);
 }
 function report(error, command, io) {
   if (error instanceof HelpRequested) {
-    io.stdout(command.usage);
+    io.stdout(command.internal ? `${command.usage}
+${INTERNAL_NOTE}` : command.usage);
     return EXIT_OK;
   }
   if (error instanceof UsageError) {

package/skills/dld-decide/SKILL.md

@@ -3,7 +3,7 @@ name: dld-decide
 description: Record a single development decision as a markdown file with YAML frontmatter. Collects context, rationale, and code references interactively.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-decide/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-implement/SKILL.md

@@ -3,7 +3,7 @@ name: dld-implement
 description: Implement one or more proposed decisions. Makes code changes, adds `@decision` annotations, and updates decision status.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-implement/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-init/SKILL.md

@@ -3,7 +3,7 @@ name: dld-init
 description: Bootstrap DLD (Decision-Linked Development) in a repository. Creates dld.config.yaml, the decisions/ directory, and INDEX.md. Run once per project.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-init/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-lookup/SKILL.md

@@ -3,7 +3,7 @@ name: dld-lookup
 description: Look up decisions by ID, tag, code path, or keyword. IMPORTANT — use this proactively whenever you encounter `@decision` annotations in code you are about to read or modify.
 compatibility: No external dependencies.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-lookup/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-plan/SKILL.md

@@ -3,7 +3,7 @@ name: dld-plan
 description: Break down a feature into multiple decisions interactively. Creates a set of decision records grouped by a shared tag.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-plan/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-reindex/SKILL.md

@@ -3,7 +3,7 @@ name: dld-reindex
 description: Resolve decision ID collisions between a local branch and the base branch (and open PRs) before rebasing. Renames colliding local decisions with git mv, rewrites cross-references and annotations, then squashes branch commits into a single rebase-clean reindex commit.
 compatibility: Requires Node.js 20+ and git. Open-PR scanning additionally needs the `gh` CLI authenticated against a GitHub remote — the skill falls back gracefully when unavailable.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-reindex/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-retrofit/SKILL.md

@@ -3,7 +3,7 @@ name: dld-retrofit
 description: Bootstrap DLD decisions from an existing codebase. Analyzes code to infer rationale, generates decision records, and adds `@decision` annotations.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-retrofit/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-snapshot/SKILL.md

@@ -3,7 +3,7 @@ name: dld-snapshot
 description: Generate SNAPSHOT.md (detailed decision reference) and OVERVIEW.md (narrative synthesis with diagrams) from the decision log.
 compatibility: Requires Node.js 20+ and git.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-snapshot/SKILL.md. Do not edit: updating the skills overwrites this file. -->
 

package/skills/dld-status/SKILL.md

@@ -3,7 +3,7 @@ name: dld-status
 description: Quick overview of the decision log state — counts by status, recent decisions, and run tracking info.
 compatibility: No external dependencies.
 metadata:
-  dld-kit-version: "1.0.0-rc.1"
+  dld-kit-version: "1.0.0-rc.3"
 ---
 <!-- Generated by dld-kit from templates/skills/dld-status/SKILL.md. Do not edit: updating the skills overwrites this file. -->