cadet-agent 0.24.0 → 0.27.0

package/README.md

@@ -2,14 +2,14 @@
 
 Cadet-Agent is an **opinionated** cross-IDE agent framework for game-development workflows. It is built on foundational software engineering practices and real-world game-development experience, with the goal of **guiding you through the entire development process** — from requirements and technical design through TDD, implementation, and review.
 
-Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, and Claude Code.
+Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished game from a single prompt. Instead, it walks you through each phase methodically: calibrating the learner model, scoping work into epics and stories, planning architecture, writing tests first, and iterating on feedback. The shared framework core integrates with GitHub Copilot, Cursor, Continue, Claude Code, and Deep Code.
 
 ## Repository Layout
 - `.cadet/agent/core/` contains the shared Cadet-Agent framework documents.
   - `cadet-agent.md` is the thin global directive: identity, non-negotiable rules, workflow routing, hard-gate protocol, and skill dispatch.
   - `Harness.md` is the canonical harness contract: budgets, evidence-backed gates, retries, context tiers, tool routing, privacy, and escalation.
   - `harness.schema.json` and `state.schema.json` are the machine-readable schemas for harness records and session state.
-  - `skills/` contains scoped workflow-phase skills (Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
+  - `skills/` contains scoped workflow-phase skills (PlanningReview, Requirements, Architecture, Spike, StoryBreakdown, TDD, Debugging, CodeReview, Resume, MCPSetup, AgentReviewer).
   - `templates/` contains runtime templates for planning artifacts.
 - `.cadet/harness.json` holds repository-local budget/policy overrides (preserved by sync).
 - `.cadet/runs/` holds sanitized run ledgers (preserved by sync; no secrets or raw prompts by default).
@@ -20,31 +20,34 @@ Cadet-Agent is **not a one-shot code generator**. It won't spit out a finished g
 - `.cursor/` contains Cursor-specific authored files.
 - `.continue/` contains Continue-specific authored files.
 - `.claude/` contains Claude Code-specific authored files.
+- `.agents/skills/` contains Deep Code (and cross-client) skill adapters.
 - These IDE folders hold thin integration shims; the core framework logic still lives in `.cadet/agent/core/`.
 - `package-agent.ps1` builds the distributable `cadet-agent.zip` package.
-- `publish-npm.ps1` publishes the CLI to npm using a token from `~/.npm_token`.
+- `bump-version.ps1` bumps the version, updates version-bearing files, commits, tags, and pushes. It runs `npm run lint` first and refuses to release if the link check fails.
+- `npm run lint` checks all markdown links (the same offline check CI runs); `npm run verify` runs tests + lint.
 
 ## Cross-IDE Support
 
-Cadet-Agent provides full workflow parity across four IDEs. The same 9 skills + reviewer are available in each:
-
-| Feature | GitHub Copilot | Cursor | Continue | Claude Code |
-|---|---|---|---|---|
-| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill |
-| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills |
-| Requirements | ✅ | ✅ | ✅ | ✅ |
-| Architecture | ✅ | ✅ | ✅ | ✅ |
-| Spike | ✅ | ✅ | ✅ | ✅ |
-| Story Breakdown | ✅ | ✅ | ✅ | ✅ |
-| TDD | ✅ | ✅ | ✅ | ✅ |
-| Debugging | ✅ | ✅ | ✅ | ✅ |
-| Code Review | ✅ | ✅ | ✅ | ✅ |
-| Resume | ✅ | ✅ | ✅ | ✅ |
-| MCP Setup | ✅ | ✅ | ✅ | ✅ |
-| Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` |
-| Git guard | PreToolUse hook | Manual | Manual | Manual |
-
-All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory.
+Cadet-Agent provides full workflow parity across five IDEs. The same 10 skills + reviewer are available in each:
+
+| Feature | GitHub Copilot | Cursor | Continue | Claude Code | Deep Code |
+|---|---|---|---|---|---|
+| Auto-load rules | Agent definition | `alwaysApply` rule | Project rule | Project skill | Project skill (`.agents/skills/`) |
+| Skill dispatch | `/cadet-<skill>` prompts | Natural language | `/cadet-<skill>` commands | `/cadet-<skill>` skills | `/skills` menu (`/`) |
+| Planning Review | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Requirements | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Architecture | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Spike | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Story Breakdown | ✅ | ✅ | ✅ | ✅ | ✅ |
+| TDD | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Debugging | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Code Review | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Resume | ✅ | ✅ | ✅ | ✅ | ✅ |
+| MCP Setup | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reviewer mode | Agent picker | Rule toggle | `/cadet-agent-reviewer` | `/cadet-agent-reviewer` | `cadet-agent-reviewer` skill |
+| Git guard | PreToolUse hook | Manual | Manual | Manual | `permissions.ask` (`mutate-git-log`) |
+
+All adapters delegate to the canonical files under `.cadet/agent/core/` — no duplicated rules or skills. See `ADAPTERS.md` for the full inventory and `docs/guidance/DeepCode.md` for Deep Code setup.
 
 ## Quick Install
 
@@ -72,6 +75,20 @@ To sync a specific directory:
 npx cadet-agent@latest sync --target ./my-unity-project
 ```
 
+#### AGENTS.md is create-only
+
+Cadet ships a repository-root `AGENTS.md` (a thin pointer to `.cadet/agent/core/cadet-agent.md`). If your repo already has one, Cadet **never overwrites it**:
+
+- In a terminal, `init`/`sync` ask whether to keep, overwrite, or merge (default: keep).
+- Non-interactive installs (CI, `--yes`, piped output) always **keep** and print a tag-pinned link to Cadet's copy.
+- Control it explicitly with `--agents-md keep|overwrite|merge`.
+- `merge` inserts Cadet's text between `<!-- cadet-agent:begin -->` / `<!-- cadet-agent:end -->` markers and leaves the rest of your file untouched.
+
+```bash
+npx cadet-agent@latest sync --agents-md keep       # never touch an existing AGENTS.md
+npx cadet-agent@latest sync --yes                  # non-interactive; keeps existing files
+```
+
 ## Manual Install (fallback)
 
 If you prefer to install from a packaged release artifact, download `cadet-agent.zip` from [GitHub Releases](https://github.com/naishtech/cadet-agent/releases) and extract it into your Unity project root:
@@ -96,6 +113,7 @@ flowchart TD
     REPORT["Report current phase,<br/>epics, stories & gates"]
     CR["🔍 Context Resolution<br/>classify change size,<br/>calibrate learner,<br/>detect policy"]
     REQ["📋 Requirements<br/>Given/When/Then criteria<br/>assumption audit"]
+    PLANREV["🧩 Planning Review<br/>interview one question<br/>at a time · decision tree"]
     ARCH["🏗️ Architecture<br/>technical design,<br/>ADR decisions"]
     SPIKE["🧪 Spikes<br/>resolve unverified<br/>assumptions"]
     BREAKDOWN["📐 Story Breakdown<br/>epics → testable stories"]
@@ -110,8 +128,11 @@ flowchart TD
     RESUME -->|"yes"| REPORT --> CR
 
     CR -->|"large change"| REQ
+    CR -->|"plan fuzzy or contested"| PLANREV
     CR -->|"small / no_test_required"| IMPL
 
+    PLANREV -->|"shared understanding reached"| REQ
+
     REQ --> ARCH
     ARCH -->|"unverified assumptions"| SPIKE
     ARCH -->|"all assumptions resolved"| BREAKDOWN
@@ -128,6 +149,7 @@ flowchart TD
     style START fill:#4a9,stroke:#333,color:#fff
     style CLOSED fill:#4a9,stroke:#333,color:#fff
     style RESUME fill:#e8a840,stroke:#333,color:#000
+    style PLANREV fill:#8a7ae8,stroke:#333,color:#fff
     style REVIEW fill:#e87440,stroke:#333,color:#fff
     style VALIDATE fill:#e87440,stroke:#333,color:#fff
 ```
@@ -191,6 +213,11 @@ Cadet Agent will classify the change, check `.cadet/state.json` for blocking gat
 
 **Skill mode:** For a specific workflow phase, use the matching slash command so the skill becomes the primary instruction context:
 
+```text
+/cadet-planning-review
+clarify the plan for a co-op loot system before I write the design
+```
+
 ```text
 /cadet-requirements
 create a requirements doc for a kart handling prototype
@@ -227,6 +254,26 @@ Create a requirements outline for a single-player time-trial mode with ghost rep
 
 The Continue rule in `.continue/rules/cadet-agent.md` should steer the response back through the shared Cadet framework.
 
+### Deep Code request
+With [Deep Code](https://deepcode.vegamo.cn/) installed (`npm install -g @vegamo/deepcode-cli`), run `deepcode` in the repository and use `/skills` to confirm the `cadet-*` skills are discovered from `.agents/skills/`. Then pick a phase skill from the `/` menu (there is no `/cadet-<skill>` command — select it by name, or ask for the phase in plain language):
+
+```text
+Run the TDD skill for the ghost-replay story.
+```
+
+Because Deep Code has no PreToolUse hook, enforce the commit/push approval gate in `.deepcode/settings.json`:
+
+```json
+{
+  "permissions": {
+    "ask": ["mutate-git-log", "network"],
+    "defaultMode": "askAll"
+  }
+}
+```
+
+See `docs/guidance/DeepCode.md` for the full setup, MCP wiring, and configuration reference.
+
 ### Repository policy example
 If a specific game repository needs local conventions, add a policy file under `.cadet/agent/policies` using `.cadet/agent/core/Templates/PolicyTemplate.md`. For example, a repository policy could define:
 - where project plans should live

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "cadet-agent",
-  "version": "0.24.0",
+  "version": "0.27.0",
   "description": "Cross-IDE agent framework for Unity/C# game-development — one-command install",
   "type": "module",
   "bin": {
     "cadet-agent": "bin/cli.mjs"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "lint": "lychee --offline --include-fragments \"**/*.md\"",
+    "verify": "npm test && npm run lint"
   },
   "files": [
     "bin/",

package/src/cli.mjs

@@ -51,6 +51,8 @@ function showHelp() {
     --gate         Gate name (harness verify)
     --command      Command override (harness verify)
     --files        Comma-separated relevant files to bind evidence to (harness verify)
+    --agents-md    keep|overwrite|merge for an existing AGENTS.md (init/sync)
+    --yes, -y      Never prompt; keep existing files (non-interactive installs)
     --help, -h    Show this help
     --version, -v Show version number
 `);
@@ -77,6 +79,8 @@ function parseArgs(argv) {
       case '--evidence-status': opts.evidenceStatus = argv[++i]; break;
       case '--files': opts.files = (argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean); break;
       case '--older-than-ms': opts.olderThanMs = Number(argv[++i]); break;
+      case '--agents-md': opts.agentsMd = argv[++i]; break;
+      case '--yes': case '-y': opts.yes = true; break;
       default: opts.rest.push(a);
     }
   }
@@ -381,13 +385,25 @@ export async function run(argv) {
   const command = argv[2];
   const opts = parseArgs(argv);
 
+  // Validate the create-only policy flag early so a typo fails loudly.
+  const AGENTS_MD_MODES = ['keep', 'overwrite', 'merge'];
+  if (opts.agentsMd !== undefined && !AGENTS_MD_MODES.includes(opts.agentsMd)) {
+    console.error(`Invalid --agents-md value "${opts.agentsMd}" (expected: ${AGENTS_MD_MODES.join('|')})`);
+    process.exit(1);
+  }
+  const installOpts = {
+    sourceUrl: opts.sourceUrl,
+    yes: opts.yes === true,
+    createOnlyPolicy: opts.agentsMd ? { 'AGENTS.md': opts.agentsMd } : undefined,
+  };
+
   try {
     switch (command) {
       case 'init':
-        await install(opts.targetDir, { sourceUrl: opts.sourceUrl });
+        await install(opts.targetDir, installOpts);
         break;
       case 'sync':
-        await sync(opts.targetDir, { sourceUrl: opts.sourceUrl });
+        await sync(opts.targetDir, installOpts);
         break;
       case 'state':
         await cmdState(opts);

package/src/install.mjs

@@ -1,5 +1,6 @@
-import { readFileSync, unlinkSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, unlinkSync, existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { createInterface } from 'node:readline';
 import { runUpgrades } from './upgrades.mjs';
 import {
   extractArchive, readArchiveEntry, findEocd,
@@ -61,10 +62,99 @@ const ARCHIVE_LIMITS = DEFAULT_ARCHIVE_LIMITS;
 
 export { ArchiveError, findEocd };
 
-/** Extract every file entry into targetDir, returning the written paths. */
-export async function extractZip(buf, targetDir) {
-  const { extracted } = extractArchive(buf, targetDir, { limits: ARCHIVE_LIMITS });
-  return extracted;
+// ── Create-only paths (never overwrite an existing consumer file) ─────────────
+//
+// Some packaged files are advisory conveniences that a consumer repository may
+// already own (currently root `AGENTS.md`). These are listed in the manifest as
+// `createOnlyPaths`: written when absent, and never overwritten when present.
+// The canonical copy always remains available at the repository URL below.
+
+const REPO_URL = 'https://github.com/naishtech/cadet-agent';
+
+/** Tag-pinned URL for a create-only file, so the link cannot drift. */
+export function createOnlyUrl(relPath, version) {
+  const tag = version && version !== 'unknown' ? `v${normalizeVersion(version)}` : 'main';
+  return `${REPO_URL}/blob/${tag}/${relPath}`;
+}
+
+function normalizeRel(p) {
+  return p.replace(/^\.?\//, '').replace(/\\/g, '/');
+}
+
+/** Does an absolute-or-relative entry match a create-only path (exact file)? */
+function matchesCreateOnly(entryName, createOnlyPaths) {
+  const n = normalizeRel(entryName);
+  return (createOnlyPaths || []).some((c) => normalizeRel(c) === n);
+}
+
+/**
+ * Decide how to handle a create-only path that already exists on disk.
+ * Returns 'keep' | 'overwrite' | 'merge'.
+ *
+ * Non-interactive (no TTY, --yes, or an explicit policy) always resolves to the
+ * safe 'keep' — a scripted/CI install must never clobber a consumer file.
+ */
+async function resolveExistingCreateOnly({ relPath, mode, interactive }) {
+  if (mode) return mode; // explicit --agents-md=keep|overwrite|merge
+  if (!interactive) return 'keep';
+
+  const answer = await promptLine(
+    `\n⚠️  ${relPath} already exists in this repository.\n` +
+    `   [k] Keep mine (leave it untouched)   [o] Overwrite with Cadet's   [m] Merge Cadet's block\n` +
+    `   Keep yours? (K/o/m): `
+  );
+  const a = (answer || '').trim().toLowerCase();
+  if (a === 'o' || a === 'overwrite') return 'overwrite';
+  if (a === 'm' || a === 'merge') return 'merge';
+  return 'keep';
+}
+
+/** Read one line from stdin. Resolves to '' if stdin ends without an answer. */
+function promptLine(question) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => { if (!settled) { settled = true; resolve(value); } };
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      done(answer);
+      rl.close();
+    });
+    // Only fall back to '' if the stream closes with no answer (EOF/piped input).
+    rl.on('close', () => done(''));
+  });
+}
+
+/** True when we may prompt: an interactive TTY and not disabled by --yes. */
+export function canPrompt(opts = {}) {
+  if (opts.yes === true) return false;
+  if (opts.interactive === false) return false;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+// Marker block used by the 'merge' resolution. Content between the markers is
+// Cadet-owned and replaced on each sync; everything outside is the consumer's.
+export const AGENTS_MARKER_BEGIN = '<!-- cadet-agent:begin -->';
+export const AGENTS_MARKER_END = '<!-- cadet-agent:end -->';
+
+/** Wrap a body in the Cadet marker block. */
+export function wrapWithMarkers(body) {
+  return `${AGENTS_MARKER_BEGIN}\n${body.trim()}\n${AGENTS_MARKER_END}`;
+}
+
+/**
+ * Merge Cadet's marked block into an existing file's text:
+ * replace the block if present, otherwise append it. Content outside the
+ * markers is preserved verbatim.
+ */
+export function mergeMarkerBlock(existing, cadetBody) {
+  const block = wrapWithMarkers(cadetBody);
+  const begin = existing.indexOf(AGENTS_MARKER_BEGIN);
+  const end = existing.indexOf(AGENTS_MARKER_END);
+  if (begin !== -1 && end !== -1 && end > begin) {
+    return existing.slice(0, begin) + block + existing.slice(end + AGENTS_MARKER_END.length);
+  }
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${sep}${block}\n`;
 }
 
 // ── GitHub release download ─────────────────────────────────────────────────
@@ -174,9 +264,16 @@ export async function install(targetDir, opts = {}) {
   const zipBuf = await downloadZip(asset.browser_download_url);
   console.log(`   Downloaded ${(zipBuf.length / 1024).toFixed(0)} KB\n`);
 
-  // 4. Extract
+  // 4. Extract. Create-only paths (e.g. AGENTS.md) must never overwrite an
+  // existing consumer file; if one is skipped, point the user at the source.
   console.log('📂 Extracting...');
-  const extracted = await extractZip(zipBuf, targetDir);
+  const createOnly = readCreateOnlyPathsFromZip(zipBuf);
+  const extracted = await extractZip(zipBuf, targetDir, {
+    ...opts,
+    createOnlyPaths: createOnly,
+    interactive: canPrompt(opts),
+  });
+  reportCreateOnlySkips(createOnly, targetDir, releaseVersion, opts);
 
   // 5. Report
   console.log(`\n✅ Cadet-Agent v${releaseVersion} installed! Extracted ${extracted.length} files.\n`);
@@ -205,6 +302,12 @@ export async function install(targetDir, opts = {}) {
   console.log('      /cadet-breakdown, /cadet-tdd, /cadet-debug, /cadet-review, /cadet-resume');
   console.log('    Reviewer: /cadet-agent-reviewer');
   console.log('    Git guard: manual — see .claude\\skills\\cadet-agent\\SKILL.md for instructions');
+  console.log('  Deep Code:');
+  console.log('    Already active — .agents\\skills\\cadet-agent\\SKILL.md is discovered as a project skill');
+  console.log('    List skills with /skills, then pick a cadet-* skill from the / menu');
+  console.log('    Reviewer: the cadet-agent-reviewer skill');
+  console.log('    Git guard: no hook — approve via .deepcode\\settings.json permissions.ask (mutate-git-log)');
+  console.log('    Docs: https://deepcode.vegamo.cn/');
   console.log('');
 }
 
@@ -282,12 +385,91 @@ function deleteObsoleteManagedFiles(targetDir, managedPaths, zipFilenames) {
   return deleted;
 }
 
-export async function extractZipWithManifest(buf, targetDir, { preserved, managed, limits = ARCHIVE_LIMITS }) {
+/**
+ * Resolve create-only paths against the target directory before extraction.
+ * Returns:
+ *   - skip:    set of normalized paths whose existing copy must be left alone
+ *   - merge:   map of normalized path -> existing text (to merge Cadet's block)
+ *   - created: normalized paths that do not yet exist (write normally)
+ *   - kept:    human-readable list of paths left untouched
+ */
+async function planCreateOnly(createOnlyPaths, targetDir, opts = {}) {
+  const skip = new Set();
+  const merge = new Map();
+  const created = [];
+  const kept = [];
+
+  for (const rel of createOnlyPaths || []) {
+    const n = normalizeRel(rel);
+    const full = join(targetDir, rel.replace(/^\.?\//, ''));
+    if (!existsSync(full)) {
+      created.push(n);
+      continue;
+    }
+    const resolution = await resolveExistingCreateOnly({
+      relPath: n,
+      mode: opts.createOnlyPolicy && opts.createOnlyPolicy[n],
+      interactive: canPrompt(opts),
+    });
+    if (resolution === 'overwrite') continue;             // fall through and write
+    if (resolution === 'merge') {
+      // Remember the consumer's current text; the Cadet body is read from the
+      // archive after extraction (never written over the consumer's file).
+      merge.set(n, readFileSync(full, 'utf-8'));
+      skip.add(n);
+    } else {
+      skip.add(n);
+    }
+    kept.push(n);
+  }
+  return { skip, merge, created, kept };
+}
+
+/** Extract every file entry into targetDir, returning the written paths. */
+export async function extractZip(buf, targetDir, opts = {}) {
+  const createOnlyPaths = opts.createOnlyPaths || [];
+  const plan = await planCreateOnly(createOnlyPaths, targetDir, opts);
+
+  const { extracted } = extractArchive(buf, targetDir, {
+    limits: ARCHIVE_LIMITS,
+    filter: (entry) => {
+      if (plan.skip.has(normalizeRel(entry.filename))) return { skip: true };
+      return true;
+    },
+  });
+
+  applyMerges(plan, targetDir, buf);
+  return extracted;
+}
+
+/**
+ * Merge Cadet's marker block into the existing file for every planned merge.
+ * Cadet's body is read from the archive (its entry was skipped, so the
+ * consumer's file on disk was never touched). Content outside the markers is
+ * preserved.
+ */
+function applyMerges(plan, targetDir, buf) {
+  for (const [rel, existingText] of plan.merge) {
+    const full = join(targetDir, rel);
+    const data = readArchiveEntry(buf, rel, ARCHIVE_LIMITS);
+    if (!data) continue; // archive lacks the file — leave the consumer's text alone
+    const cadetBody = data.toString('utf-8');
+    writeFileSync(full, mergeMarkerBlock(existingText, cadetBody), 'utf-8');
+    plan.merged = plan.merged || [];
+    plan.merged.push(full);
+  }
+}
+
+export async function extractZipWithManifest(buf, targetDir, { preserved, managed, createOnly = [], limits = ARCHIVE_LIMITS, ...opts }) {
   const updated = [];
   const preserved_list = [];
   const added = [];
+  const kept = [];
   const zipFilenames = [];
 
+  const plan = await planCreateOnly(createOnly, targetDir, opts);
+  kept.push(...plan.kept);
+
   const { extracted } = extractArchive(buf, targetDir, {
     limits,
     filter: (entry) => {
@@ -296,10 +478,15 @@ export async function extractZipWithManifest(buf, targetDir, { preserved, manage
         preserved_list.push(entry.filename);
         return { skip: true };
       }
+      if (plan.skip.has(normalizeRel(entry.filename))) {
+        return { skip: true };
+      }
       return true;
     },
   });
 
+  applyMerges(plan, targetDir, buf);
+
   // `extractArchive` skips directory entries; classify the extracted files.
   for (const outPath of extracted) {
     const rel = outPath.replace(/\\/g, '/');
@@ -313,7 +500,7 @@ export async function extractZipWithManifest(buf, targetDir, { preserved, manage
   // Delete obsolete managed files no longer in the zip (renamed/removed managed paths)
   const deleted = deleteObsoleteManagedFiles(targetDir, managed, zipFilenames);
 
-  return { updated, preserved: preserved_list, added, deleted, zipFilenames };
+  return { updated, preserved: preserved_list, added, deleted, kept, zipFilenames };
 }
 
 // ── Removed-managed-path cleanup ─────────────────────────────────────────────
@@ -330,6 +517,37 @@ export function findManagedPathsInZip(buf) {
   return [];
 }
 
+/** Read `createOnlyPaths` from the manifest inside the zip. */
+export function readCreateOnlyPathsFromZip(buf) {
+  try {
+    const data = readArchiveEntry(buf, '.cadet/agent/core/FrameworkManifest.json', ARCHIVE_LIMITS);
+    if (!data) return [];
+    const manifest = JSON.parse(data.toString('utf-8'));
+    return manifest.createOnlyPaths || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Print a note for each create-only path that was left untouched, including a
+ * tag-pinned URL so the user can copy the canonical version if they want it.
+ */
+export function reportCreateOnlySkips(createOnlyPaths, targetDir, version, opts = {}) {
+  const skipped = (createOnlyPaths || []).filter((rel) => {
+    const full = join(targetDir, rel.replace(/^\.?\//, ''));
+    return existsSync(full);
+  });
+  for (const rel of skipped) {
+    const n = normalizeRel(rel);
+    const resolution = opts.createOnlyPolicy && opts.createOnlyPolicy[n];
+    if (resolution === 'overwrite') continue; // the user chose to replace it
+    console.log(`   Kept:     ${n} (existing file left untouched)`);
+    console.log(`             Cadet's version: ${createOnlyUrl(n, version)}`);
+  }
+  return skipped;
+}
+
 export function deleteRemovedManagedPaths(targetDir, oldManaged, newManaged) {
   const newSet = new Set(newManaged.map(p => p.replace(/^\.\//, '').replace(/\\/g, '/')));
   const deleted = [];
@@ -388,11 +606,16 @@ export async function sync(targetDir, opts = {}) {
   const zipBuf = await downloadZip(asset.browser_download_url);
   console.log(`   Downloaded ${(zipBuf.length / 1024).toFixed(0)} KB\n`);
 
-  // 4. Extract with manifest awareness
+  // 4. Extract with manifest awareness. Create-only paths (e.g. AGENTS.md) are
+  // never overwritten when the consumer already has them.
   console.log('📂 Extracting (preserving local policies and plans)...');
+  const createOnly = readCreateOnlyPathsFromZip(zipBuf);
   const result = await extractZipWithManifest(zipBuf, targetDir, {
     preserved: existingManifest.preservedPaths || [],
     managed: existingManifest.managedPaths || [],
+    createOnly,
+    ...opts,
+    interactive: canPrompt(opts),
   });
 
   // 4b. Find new managed paths from the zip and delete any old paths that were removed
@@ -425,6 +648,7 @@ export async function sync(targetDir, opts = {}) {
   if (result.deleted.length > 0) {
     console.log(`   Removed:  ${result.deleted.length} files (no longer managed)`);
   }
+  reportCreateOnlySkips(createOnly, targetDir, newVersion, opts);
   console.log('');
 
   // Print per-IDE next steps