portable-agent-layer 0.34.0 → 0.36.0

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -233,6 +233,7 @@ Brief description.
 │                     │    - Work learning capture
 │                     │    - Failure logging
 │                     │    - Reflect trigger check
+│                     │    - Write context digests (semi-static sources)
 │                     │    - Auto-backup
 │                     │    - Count updates
 │                     │    - Tab reset
@@ -357,34 +358,44 @@ Relationship notes (O/B types)
 
 ## Context Loading Architecture
 
-### Two-Layer Design
+### Three-Tier Design
 
-**Static context** (loaded natively by the agent):
-- CLAUDE.md — identity, modes, context routing table
-- Loaded once at session start, always available
+**Tier 1 — Operational** (loaded natively at agent startup):
+- CLAUDE.md / AGENTS.md — identity, modes, context routing table
+- Loaded once per session, always available, never re-fetched
 
-**Dynamic context** (injected by LoadContext hook):
-- Changes per-session, can't live in a static file
-- Injected as `<system-reminder>` block to stdout
+**Tier 2 — Semi-static** (pre-compiled at previous session stop, loaded natively):
+- Self-model, wisdom, opinions, synthesis, failures, steering rules
+- Written to disk by `writeContextDigests()` at Stop time
+- Loaded natively per-agent: `@imports` in CLAUDE.md (Claude Code), `instructions[]` in opencode config, `.mdc` rules in `~/.cursor/rules/` (Cursor), `.instructions.md` in `~/.copilot/instructions/` (Copilot)
+- Content is global/user-level — safe to pre-compile (not project-scoped)
+
+**Tier 3 — Dynamic** (injected fresh each session by LoadContext hook):
+- Handoff notes, session intelligence, open threads, relationship notes, project history
+- Changes per-session or is project-scoped — can't be pre-compiled
+- Injected as `<system-reminder>` block via stdout
 - Each section independently toggleable in `pal-settings.json → dynamicContext`
 
-### Injection Order
+### Semi-Static Registry
+
+All semi-static sources are defined in `src/hooks/lib/semi-static.ts` via `getSemiStaticSources()`. Adding one entry there propagates automatically to every consumer — no other files need to change.
+
+### Dynamic Injection Order
 
 ```
 LoadContext.ts
   │
   ├─► Regenerate CLAUDE.md if template/telos changed
   │
-  └─► Build system-reminder:
+  └─► Build system-reminder (dynamic sections only):
       1. loadAtStartup files (user-configured)
-      2. Crystallized principles (wisdom frames)
-      3. Tracked opinions (≥85% confidence)
-      4. Recent interaction notes (last 2 days)
-      5. Learning digest (this project + other recent)
-      6. Pattern synthesis recommendations
-      7. Signal trends (today/week/trend)
-      8. Failure patterns (last 5 low-rating contexts)
-      9. Active work summary (sessions + projects)
+      2. Handoff note (in-progress work from last session)
+      3. Session intelligence (rating trend, algorithm performance)
+      4. Open threads (current project only)
+      5. Recent interaction notes (last 2 days)
+      6. Active projects
+      7. Project session history (this project)
+      8. Signal trends (today/week/trend)
 ```
 
 ### On-Demand Context
@@ -436,6 +447,9 @@ src/targets/
 ├── cursor/          # Cursor specific
 │   ├── install.ts   # Register hooks + skills in ~/.cursor/
 │   └── uninstall.ts
+├── copilot/         # GitHub Copilot specific
+│   ├── install.ts   # Write instruction files + update VS Code settings
+│   └── uninstall.ts
 └── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
 ```
 
@@ -452,6 +466,7 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
 | Cursor config | `~/.cursor` | `PAL_CURSOR_DIR` |
+| Copilot config | `~/.copilot` | `PAL_COPILOT_DIR` |
 | Codex config | `~/.codex` | `PAL_CODEX_DIR` |
 | Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
 

package/assets/templates/PAL/WORK_TRACKING.md

@@ -4,4 +4,4 @@ PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captu
 
 ## Projects
 
-Projects are managed in `telos/PROJECTS.md` and force-loaded at session startup via `pal-settings.json → loadAtStartup.files`.
+Projects are managed via the `/projects` skill. State lives in `~/.pal/memory/state/progress/{slug}.json`, one file per project. Inspect with `bun ~/.pal/tools/project.ts list`; manage via `~/.pal/docs/PROJECT_LIFECYCLE.md`.

package/assets/templates/pal-settings.json

@@ -13,9 +13,7 @@
   },
   "loadAtStartup": {
     "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
-    "files": [
-      "~/.pal/docs/STEERING_RULES.md"
-    ]
+    "files": []
   },
   "dynamicContext": {
     "_docs": "Dynamic context sections injected at session start. Set to false to disable.",

package/assets/templates/settings.claude.json

@@ -97,5 +97,6 @@
         ]
       }
     ]
-  }
+  },
+  "autoMemoryEnabled": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/setup-telos.ts

@@ -7,72 +7,9 @@
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import * as clack from "@clack/prompts";
-import { upsertProject } from "../../assets/skills/telos/tools/update-projects";
 import { palHome } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 
-function toKebabCase(name: string): string {
-  return name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
-async function promptProjectsLoop(): Promise<void> {
-  const addFirst = await clack.confirm({
-    message: "Do you want to add any projects now?",
-    initialValue: true,
-  });
-  if (clack.isCancel(addFirst) || !addFirst) return;
-
-  let addMore = true;
-  while (addMore) {
-    const name = await clack.text({
-      message: "Project name?",
-      placeholder: "e.g. PAL, My SaaS, Work Dashboard",
-    });
-    if (clack.isCancel(name)) return;
-
-    const status = await clack.select({
-      message: "Status?",
-      options: [
-        { value: "Active", label: "Active" },
-        { value: "Planning", label: "Planning" },
-        { value: "Paused", label: "Paused" },
-        { value: "Complete", label: "Complete" },
-      ],
-    });
-    if (clack.isCancel(status)) return;
-
-    const priority = await clack.select({
-      message: "Priority?",
-      options: [
-        { value: "High", label: "High" },
-        { value: "Medium", label: "Medium" },
-        { value: "Low", label: "Low" },
-      ],
-    });
-    if (clack.isCancel(priority)) return;
-
-    const notes = await clack.text({
-      message: "Notes? (optional — leave blank to skip)",
-      placeholder: "e.g. Building the v2 API, blocked on design review",
-    });
-    if (clack.isCancel(notes)) return;
-
-    const id = toKebabCase(name as string);
-    const row = `| ${id} | ${name} | ${status} | ${priority} | ${notes || ""} |`;
-    upsertProject(id, row, `Added ${name} during PAL setup`);
-    clack.log.success(`Added: ${name}`);
-
-    const again = await clack.confirm({
-      message: "Add another project?",
-      initialValue: false,
-    });
-    if (clack.isCancel(again) || !again) addMore = false;
-  }
-}
-
 /** Prompt for missing TELOS context. Skips any step whose file already has real content. */
 export async function promptTelos(): Promise<void> {
   // Skip interactive prompts in non-TTY environments (tests, CI)
@@ -95,25 +32,21 @@ export async function promptTelos(): Promise<void> {
   );
 
   for (const key of pending) {
-    if (key === "projects") {
-      await promptProjectsLoop();
-    } else {
-      const step = SETUP_STEPS[key];
-      const title = key.charAt(0).toUpperCase() + key.slice(1);
-
-      const answer = await clack.text({
-        message: step.question,
-        placeholder: step.hint,
-      });
+    const step = SETUP_STEPS[key];
+    const title = key.charAt(0).toUpperCase() + key.slice(1);
 
-      if (clack.isCancel(answer)) {
-        clack.cancel("Setup cancelled");
-        return;
-      }
+    const answer = await clack.text({
+      message: step.question,
+      placeholder: step.hint,
+    });
 
-      const filePath = resolve(home, step.file);
-      writeFileSync(filePath, `# ${title}\n\n${answer}\n`, "utf-8");
+    if (clack.isCancel(answer)) {
+      clack.cancel("Setup cancelled");
+      return;
     }
+
+    const filePath = resolve(home, step.file);
+    writeFileSync(filePath, `# ${title}\n\n${answer}\n`, "utf-8");
   }
 
   clack.outro("Personal context saved ✓");

package/src/hooks/LoadContext.ts

@@ -9,10 +9,10 @@
  * context directly to ~/.copilot/copilot-instructions.md so it is picked up on load.
  */
 
-import { existsSync, lstatSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
-import { buildSystemReminder } from "./lib/context";
+import { type AgentTarget, buildSystemReminder } from "./lib/context";
 import { logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 
@@ -36,21 +36,33 @@ try {
 
 // --- Context to stdout (or file for Copilot) ---
 try {
-  const reminder = buildSystemReminder();
+  // Determine agent target — controls which sections are skipped (loaded natively instead).
+  let agent: AgentTarget = "claude";
+  if (process.env.PAL_AGENT === "copilot") agent = "copilot";
+  else if (process.env.CURSOR_VERSION) agent = "cursor";
+  const reminder = buildSystemReminder({ agent });
   if (!reminder) process.exit(0);
 
   if (process.env.PAL_AGENT === "copilot") {
-    // Copilot: sessionStart output is ignored — write merged context to copilot-instructions.md
-    const instructionsPath = resolve(platform.copilotDir(), "copilot-instructions.md");
+    // Copilot: semi-static in ~/.copilot/instructions/pal-*.instructions.md (written at stop).
+    // Write AGENTS.md + dynamic context to pal-session.instructions.md on each session start.
+    const instructionsDir = resolve(platform.copilotDir(), "instructions");
+    mkdirSync(instructionsDir, { recursive: true });
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
-    if (existsSync(instructionsPath) && lstatSync(instructionsPath).isSymbolicLink()) {
-      unlinkSync(instructionsPath);
+    if (context) {
+      writeFileSync(
+        resolve(instructionsDir, "pal-session.instructions.md"),
+        `---\napplyTo: "**"\n---\n\n${context}`,
+        "utf-8"
+      );
     }
-    writeFileSync(instructionsPath, context, "utf-8");
-    logDebug("LoadContext", `Copilot instructions written: ${context.length} chars`);
+    logDebug(
+      "LoadContext",
+      `Copilot session instructions written: ${context.length} chars`
+    );
   } else if (process.env.CURSOR_VERSION) {
-    // Cursor: no native user-level rules — inject AGENTS.md + dynamic context
+    // Cursor: semi-static in ~/.cursor/rules/pal-context.mdc; inject AGENTS.md + dynamic here
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
     process.stdout.write(JSON.stringify({ additional_context: context }));

package/src/hooks/handlers/context-digests.ts

@@ -0,0 +1,74 @@
+/**
+ * Handler: write pre-compiled context digest files for @import / instructions[].
+ *
+ * Runs at session stop so that CLAUDE.md can @import these files natively
+ * at the next session start, keeping hook stdout small.
+ *
+ * Sources are defined in src/hooks/lib/semi-static.ts — add one entry there
+ * to extend coverage to all consumers (CLAUDE.md, opencode, Cursor, Copilot).
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { ensureDir, platform } from "../lib/paths";
+import {
+  copilotFilename,
+  cursorFilename,
+  getSemiStaticSources,
+} from "../lib/semi-static";
+
+export function writeContextDigests(): void {
+  const sources = getSemiStaticSources();
+
+  // Resolve Cursor/Copilot destination dirs once (null if agent not installed)
+  let rulesDir: string | null = null;
+  let instructionsDir: string | null = null;
+
+  try {
+    const cursorDir = platform.cursorDir();
+    if (existsSync(cursorDir)) {
+      rulesDir = ensureDir(resolve(cursorDir, "rules"));
+    }
+  } catch {
+    /* non-fatal */
+  }
+
+  try {
+    const copilotDir = platform.copilotDir();
+    if (existsSync(copilotDir)) {
+      instructionsDir = ensureDir(resolve(copilotDir, "instructions"));
+    }
+  } catch {
+    /* non-fatal */
+  }
+
+  for (const src of sources) {
+    try {
+      const content = src.load();
+      if (!content) continue;
+
+      if (src.writesDigest) {
+        ensureDir(dirname(src.path));
+        writeFileSync(src.path, content, "utf-8");
+      }
+
+      if (rulesDir) {
+        writeFileSync(
+          resolve(rulesDir, cursorFilename(src)),
+          `---\ndescription: ${src.description}\nalwaysApply: true\n---\n\n${content}`,
+          "utf-8"
+        );
+      }
+
+      if (instructionsDir) {
+        writeFileSync(
+          resolve(instructionsDir, copilotFilename(src)),
+          `---\napplyTo: "**"\n---\n\n${content}`,
+          "utf-8"
+        );
+      }
+    } catch {
+      /* non-fatal */
+    }
+  }
+}

package/src/hooks/handlers/session-intelligence.ts

@@ -1,11 +1,13 @@
 /**
  * Stop handler: unified session intelligence capture.
  *
- * Merges work-learning + relationship + handoff into a single Haiku call.
- * Produces: title, summary, insights, handoff, relationship observations.
- * Writes: session learning file, project history, relationship notes, last-handoff.
+ * Produces: title, summary, insights via Haiku.
+ * Writes: session learning file, project history.
  *
- * Replaces: work-learning.ts + relationship.ts (both still exist but are bypassed).
+ * Relationship notes → written in ALGORITHM LEARN phase via relationship-note.ts
+ * Handoff notes     → written in ALGORITHM LEARN phase via handoff-note.ts
+ *
+ * Replaces: work-learning.ts (still exists but is bypassed).
  */
 
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
@@ -15,7 +17,6 @@ import { inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
-import { appendNotes, hasSessionNotes, type RelationshipNote } from "../lib/relationship";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -110,25 +111,8 @@ const INTELLIGENCE_SCHEMA = {
       description:
         "If status is in-progress: what remains to be done, key decisions made, blockers. If completed: empty string.",
     },
-    observations: {
-      type: "array" as const,
-      items: {
-        type: "object" as const,
-        additionalProperties: false,
-        properties: {
-          type: {
-            type: "string" as const,
-            enum: ["O", "W", "B"],
-            description: "O=preference, W=world fact, B=what AI did",
-          },
-          text: { type: "string" as const },
-          confidence: { type: "number" as const },
-        },
-        required: ["type", "text", "confidence"] as const,
-      },
-    },
   },
-  required: ["title", "summary", "insights", "handoff", "observations"] as const,
+  required: ["title", "summary", "insights", "handoff"] as const,
 };
 
 interface IntelligenceOutput {
@@ -136,7 +120,6 @@ interface IntelligenceOutput {
   summary: string;
   insights: string;
   handoff: string;
-  observations: Array<{ type: "O" | "W" | "B"; text: string; confidence: number }>;
 }
 
 // ── Main handler ──
@@ -160,9 +143,6 @@ export async function captureSessionIntelligence(
     return;
   }
 
-  // Relationship dedup — skip relationship capture if already done for this session
-  const skipRelationship = sessionId ? hasSessionNotes(sessionId) : false;
-
   // Extract transcript windows
   const userMessages = messages
     .filter((m) => m.role === "user")
@@ -174,8 +154,7 @@ export async function captureSessionIntelligence(
   const lastUser = extractLastUser(messages);
   const status = detectStatus(lastAssistantText);
 
-  // Wider window: 15 user msgs at 200 chars (relationship needs more context)
-  const userWindow = userMessages.slice(-15).map((t) => t.slice(0, 200));
+  const userWindow = userMessages.slice(-10).map((t) => t.slice(0, 200));
   const assistantWindow = lastAssistantText.slice(0, 600);
 
   if (userWindow.length < 3) return;
@@ -195,12 +174,9 @@ export async function captureSessionIntelligence(
         status === "in-progress"
           ? "4. handoff: what remains unfinished — decisions made so far, next steps, blockers (2-4 sentences)"
           : "4. handoff: empty string (session completed)",
-        skipRelationship
-          ? "5. observations: empty array (already captured)"
-          : "5. observations: 0-3 relationship observations. O=preference/opinion, W=world fact, B=what AI did this session (first-person). Be concise.",
       ].join("\n"),
       user: `User messages:\n${userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n\nLast AI response:\n${assistantWindow}`,
-      maxTokens: 500,
+      maxTokens: 350,
       timeout: 15000,
       jsonSchema: INTELLIGENCE_SCHEMA,
     });
@@ -218,8 +194,6 @@ export async function captureSessionIntelligence(
   const title = output?.title || extractContent(lastUser).slice(0, 80) || "session";
   const summary = output?.summary || lastAssistantText.slice(0, 600);
   const insights = output?.insights || "";
-  const handoff = output?.handoff || "";
-
   // ── Write session learning file ──
 
   const category = categorizeLearning(title, summary);
@@ -241,7 +215,6 @@ export async function captureSessionIntelligence(
     "",
     "## Insights",
     insights || "*No insights captured.*",
-    ...(handoff ? ["", "## Handoff", handoff] : []),
   ].join("\n");
 
   const content = stringify(meta, body);
@@ -271,54 +244,4 @@ export async function captureSessionIntelligence(
 
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
   logDebug("session-intelligence", `Learning captured: ${title}`);
-
-  // ── Write relationship notes ──
-
-  if (!skipRelationship && output?.observations && output.observations.length > 0) {
-    try {
-      const notes: RelationshipNote[] = output.observations.map((o) => ({
-        type: o.type,
-        text: o.text,
-        confidence: o.confidence,
-      }));
-      appendNotes(notes, sessionId);
-      logDebug(
-        "session-intelligence",
-        `${notes.length} relationship observations captured`
-      );
-    } catch (err) {
-      logError("session-intelligence:relationship", err);
-    }
-  }
-
-  // ── Write handoff state ──
-
-  if (handoff && status === "in-progress") {
-    try {
-      const handoffPath = resolve(ensureDir(paths.state()), "last-handoff.json");
-      let handoffs: Record<string, unknown> = {};
-      if (existsSync(handoffPath)) {
-        try {
-          handoffs = JSON.parse(readFileSync(handoffPath, "utf-8"));
-        } catch {
-          /* fresh */
-        }
-      }
-      handoffs[process.cwd()] = {
-        timestamp: new Date().toISOString(),
-        sessionId,
-        title,
-        status,
-        handoff,
-        artifacts: [],
-      };
-      // Keep last 20 projects
-      const entries = Object.entries(handoffs);
-      if (entries.length > 20) handoffs = Object.fromEntries(entries.slice(-20));
-      writeFileSync(handoffPath, JSON.stringify(handoffs, null, 2), "utf-8");
-      logDebug("session-intelligence", "Handoff state written");
-    } catch (err) {
-      logError("session-intelligence:handoff", err);
-    }
-  }
 }

package/src/hooks/lib/claude-md.ts

@@ -1,9 +1,10 @@
 /**
- * Dynamic AGENTS.md generation.
+ * Dynamic AGENTS.md / CLAUDE.md generation.
  *
- * AGENTS.md is regenerated when setup.json or any telos file is newer than
- * the existing AGENTS.md. The template lives at AGENTS.md.template.
- * CLAUDE.md is kept as a symlink pointing to AGENTS.md.
+ * AGENTS.md (opencode, codex, copilot) is regenerated when setup.json or any
+ * telos file is newer. CLAUDE.md (Claude Code) is a real file — not a symlink —
+ * and prepends an @import for the self-model so that large static context loads
+ * natively rather than through the hook's stdout.
  */
 
 import {
@@ -19,6 +20,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assets, ensureDir, paths, platform } from "./paths";
+import { getSemiStaticSources } from "./semi-static";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
 
@@ -70,16 +72,12 @@ function ensureOneSymlink(linkPath: string, targetPath: string): void {
   }
 }
 
-/** Ensure all agent symlinks point to the canonical AGENTS.md */
+/** Ensure codex symlink points to the canonical AGENTS.md.
+ *  CLAUDE.md for Claude Code is a real file written by ensureClaudeCodeMd().
+ *  Copilot uses ~/.copilot/instructions/*.instructions.md — no symlink needed. */
 function ensureSymlinks(): void {
-  const { outputPath, symlinkPath } = getOutputPaths();
-  ensureOneSymlink(symlinkPath, outputPath);
+  const { outputPath } = getOutputPaths();
   ensureOneSymlink(resolve(platform.codexDir(), "AGENTS.md"), outputPath);
-  // Copilot instructions — only create if ~/.copilot/ already exists (i.e. Copilot is installed)
-  const copilotDir = platform.copilotDir();
-  if (existsSync(copilotDir)) {
-    ensureOneSymlink(resolve(copilotDir, "copilot-instructions.md"), outputPath);
-  }
 }
 
 /** Returns true if AGENTS.md needs to be regenerated */
@@ -89,11 +87,12 @@ export function needsRebuild(): boolean {
 
   const outputMtime = statSync(outputPath).mtimeMs;
 
-  // Collect source files: template + setup.json + identity + PAL docs
+  // Collect source files: template + setup.json + identity + PAL docs + @import candidates
   const sources: string[] = [
     TEMPLATE_PATH,
     resolve(paths.state(), "setup.json"),
     resolve(paths.memory(), "pal-settings.json"),
+    ...getSemiStaticSources().map((s) => s.path),
   ];
 
   // Track PAL doc sources for rebuild detection
@@ -124,15 +123,71 @@ export function buildClaudeMd(): string {
     .replaceAll("{{PRINCIPAL_NAME}}", id.principal.name);
 }
 
-/** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
+/** Build @import header lines for CLAUDE.md — one line per semi-static file that exists. */
+function buildClaudeCodeImports(): string {
+  const claudeDir = platform.claudeDir();
+
+  const lines = getSemiStaticSources()
+    .map((s) => s.path)
+    .filter((p) => existsSync(p))
+    .map((p) => `@${relative(claudeDir, p).replaceAll("\\", "/")}`);
+
+  return lines.length > 0 ? `${lines.join("\n")}\n\n` : "";
+}
+
+/** Build CLAUDE.md content for Claude Code — prepends @import for self-model. */
+export function buildClaudeCodeMd(): string {
+  return buildClaudeCodeImports() + buildClaudeMd();
+}
+
+/** Write ~/.claude/CLAUDE.md as a real file (upgrading from symlink if needed).
+ *  Also rewrites if the @import header has changed (new digest files appeared). */
+function ensureClaudeCodeMd(): void {
+  const claudeDir = platform.claudeDir();
+  if (!claudeDir) return;
+  const claudeMdPath = resolve(claudeDir, "CLAUDE.md");
+  const expected = buildClaudeCodeMd();
+  try {
+    if (existsSync(claudeMdPath) && !lstatSync(claudeMdPath).isSymbolicLink()) {
+      const current = readFileSync(claudeMdPath, "utf-8");
+      if (current === expected) return; // no change needed
+      // @imports changed — rewrite
+    } else if (existsSync(claudeMdPath)) {
+      unlinkSync(claudeMdPath); // remove symlink
+    }
+  } catch {
+    /* fall through */
+  }
+  try {
+    ensureDir(claudeDir);
+    writeFileSync(claudeMdPath, expected, "utf-8");
+  } catch {
+    /* ignore write errors — non-fatal */
+  }
+}
+
+/** Regenerate AGENTS.md if any source file is newer, write real CLAUDE.md, ensure other symlinks. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   if (!needsRebuild()) {
     ensureSymlinks();
+    ensureClaudeCodeMd();
     return false;
   }
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
+  // Write Claude Code's CLAUDE.md as a real file (removing any existing symlink)
+  const claudeDir = platform.claudeDir();
+  if (claudeDir) {
+    const claudeMdPath = resolve(claudeDir, "CLAUDE.md");
+    try {
+      if (existsSync(claudeMdPath)) unlinkSync(claudeMdPath);
+      ensureDir(claudeDir);
+      writeFileSync(claudeMdPath, buildClaudeCodeMd(), "utf-8");
+    } catch {
+      /* ignore — CLAUDE.md write failure is non-fatal */
+    }
+  }
   ensureSymlinks();
   return true;
 }