proteum 2.5.2 → 2.5.3

package/AGENTS.md

@@ -65,7 +65,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
 - Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.

package/README.md

@@ -403,7 +403,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum e2e` | Run Playwright with Proteum-managed `E2E_*` values instead of shell-leading env assignments |
 | `proteum verify` | Validate targeted changed-file checks, focused owner/request/browser workflows, or the full framework reference-app pass |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
-| `proteum configure agents` | Interactively configure tracked Proteum instruction files for standalone or monorepo apps |
+| `proteum configure agents` | Interactively configure tracked Proteum instruction files and Claude aliases |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 | `proteum worktree` | Create or initialize Codex worktrees with a machine-readable bootstrap marker |
 
@@ -419,7 +419,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner. Every `proteum dev` start ensures tracked Proteum instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner. Every `proteum dev` start ensures tracked Proteum instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 Useful inspection commands:
 
@@ -467,7 +467,7 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
-`proteum configure agents` writes a compact managed `# Proteum Instructions` router plus the task-specific instruction files that router points to. Standalone mode writes root documents into the app root; monorepo mode writes shared root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root and keeps only app-local instruction files in the Proteum app root. It preserves content outside managed sections and asks before replacing directories or foreign symlinks. If you decline, that path is left untouched.
+`proteum configure agents` writes a compact managed `# Proteum Instructions` router plus the task-specific instruction files that router points to. Standalone mode writes root documents into the app root; monorepo mode writes shared root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root and keeps only app-local instruction files in the Proteum app root. For each generated `AGENTS.md`, it creates a sibling `CLAUDE.md` symlink pointing to `AGENTS.md`. It preserves content outside managed sections and asks before replacing directories, foreign symlinks, or unrelated files. If you decline, that path is left untouched.
 
 Every `proteum dev` start runs the same idempotent instruction check. It updates missing or stale managed sections automatically and prompts only when a blocked path would need to be replaced.
 

package/agents/project/AGENTS.md

@@ -74,7 +74,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 ### Before Finishing
 

package/agents/project/diagnostics.md

@@ -18,7 +18,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 - For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum runtime status` first, then use its exact next action so occupied router/HMR ports and untracked same-app runtimes are handled without page-body probes. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
-- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 - During `npx proteum dev`, the running app exposes the read-only Proteum MCP transport at `/__proteum/mcp`. Use it for runtime-adjacent agent reads instead of repeatedly spawning equivalent CLI diagnostics.
 - If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root. If no live session exists, use the exact MCP offline or runtime-status next action so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - For ownership or repo discovery questions, start with MCP `workflow_start`; use MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, and MCP `explain_summary { projectId, query }` only when the bootstrap owner summary is insufficient. Use `npx proteum orient <query>` or `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required.

package/agents/project/root/AGENTS.md

@@ -59,7 +59,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
 - For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
 
 ### Before Finishing
 

package/cli/commands/configure.ts

@@ -74,7 +74,7 @@ const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Choose whether to overwrite each path with a tracked Proteum instruction file:',
+            'Choose whether to overwrite each path with a Proteum-managed instruction path:',
             ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
@@ -163,7 +163,7 @@ export const runConfigureAgentsWizard = async ({
             : undefined;
     console.info(
         [
-            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure tracked Proteum instruction files.'),
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure tracked Proteum instruction files and Claude aliases.'),
             renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
         ].join('\n\n'),
     );
@@ -201,8 +201,8 @@ export const runConfigureAgentsWizard = async ({
         await renderStep(
             '[1/1]',
             isMonorepo
-                ? `Writing monorepo-aware instruction files using ${monorepoRoot}.`
-                : 'Writing standalone instruction files.',
+                ? `Writing monorepo-aware instruction files and Claude aliases using ${monorepoRoot}.`
+                : 'Writing standalone instruction files and Claude aliases.',
         ),
     );
 
@@ -214,7 +214,7 @@ export const runConfigureAgentsWizard = async ({
     });
     const sections = renderConfigureResultSections(result);
 
-    console.info(await renderSuccess('Proteum-managed instruction files are configured.'));
+    console.info(await renderSuccess('Proteum-managed instruction files and Claude aliases are configured.'));
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };

package/cli/commands/dev.ts

@@ -153,7 +153,7 @@ const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) =
     if (cli.args.json === true || !process.stdin.isTTY || !process.stdout.isTTY) {
         throw new UsageError(
             [
-                'Proteum could not update managed instruction files because existing paths are blocked:',
+                'Proteum could not update managed instruction paths because existing paths are blocked:',
                 ...blockedPaths.map((entry) => `- ${entry}`),
                 'Run `proteum configure agents` in an interactive terminal to choose which paths can be replaced.',
             ].join('\n'),
@@ -163,7 +163,7 @@ const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) =
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Choose whether to overwrite each blocked path with a tracked Proteum instruction file:',
+            'Choose whether to overwrite each blocked path with a Proteum-managed instruction path:',
             ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
@@ -212,7 +212,7 @@ const ensureProjectAgentInstructions = async () => {
 
     throw new UsageError(
         [
-            'Proteum could not update all managed instruction files because these paths were left blocked:',
+            'Proteum could not update all managed instruction paths because these paths were left blocked:',
             ...result.blocked.map((entry) => `- ${entry}`),
         ].join('\n'),
     );

package/cli/presentation/commands.ts

@@ -116,7 +116,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files and Claude aliases for an app.',
         usage: 'proteum configure agents',
         bestFor:
             'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
@@ -128,8 +128,9 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root instruction files.',
-            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root and creates `CLAUDE.md` symlinks beside each `AGENTS.md`.',
             'Monorepo mode writes reusable root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
+            'Every generated `CLAUDE.md` is a sibling symlink pointing to `AGENTS.md`.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/utils/agents.ts

@@ -60,6 +60,9 @@ const managedInstructionSectionHeader = '# Proteum Instructions';
 const managedInstructionSectionStart = '<!-- proteum-instructions:start -->';
 const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
+const agentInstructionFilename = 'AGENTS.md';
+const claudeInstructionFilename = 'CLAUDE.md';
+const claudeInstructionPointerContent = `@${agentInstructionFilename}`;
 
 const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'DOCUMENTATION.md', content: 'source' },
@@ -243,6 +246,45 @@ function getRootAgentInstructionDefinitions() {
     return monorepoRootAgentInstructionDefinitions.map((instructionDefinition) => ({ ...instructionDefinition }));
 }
 
+function createEmptyInstructionResult(): TEnsureInstructionFilesResult {
+    return {
+        blocked: [],
+        created: [],
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+    };
+}
+
+function mergeEnsureInstructionResults(result: TEnsureInstructionFilesResult, next: TEnsureInstructionFilesResult) {
+    result.created.push(...next.created);
+    result.overwritten.push(...next.overwritten);
+    result.removed.push(...next.removed);
+    result.updated.push(...next.updated);
+    result.skipped.push(...next.skipped);
+    result.blocked.push(...next.blocked);
+}
+
+function getManagedInstructionProjectPaths(instructionDefinitions: TAgentInstructionDefinition[]) {
+    const projectPaths: string[] = [];
+
+    for (const instructionDefinition of instructionDefinitions) {
+        projectPaths.push(instructionDefinition.projectPath);
+
+        const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+        if (claudeProjectPath) projectPaths.push(claudeProjectPath);
+    }
+
+    return projectPaths;
+}
+
+function getClaudeCompanionProjectPath(projectPath: string) {
+    if (path.basename(projectPath).toLowerCase() !== agentInstructionFilename.toLowerCase()) return undefined;
+
+    return path.join(path.dirname(projectPath), claudeInstructionFilename);
+}
+
 function removeInstructionGitignoreEntries({
     rootDir,
     instructionDefinitions,
@@ -254,7 +296,7 @@ function removeInstructionGitignoreEntries({
     if (!pathEntryExists(gitignoreFilepath)) return false;
 
     const managedEntries = new Set(
-        instructionDefinitions.map((instructionDefinition) => normalizeGitignoreEntry(instructionDefinition.projectPath)),
+        getManagedInstructionProjectPaths(instructionDefinitions).map((projectPath) => normalizeGitignoreEntry(projectPath)),
     );
     const lines = fs.readFileSync(gitignoreFilepath, 'utf8').split(/\r?\n/);
     const filteredLines: string[] = [];
@@ -341,12 +383,28 @@ function ensureInstructionFiles(
                     : upsertManagedInstructionSection(existingState.content, instructionContent);
             if (nextContent === existingState.content) {
                 result.skipped.push(relativeProjectPath);
+                ensureClaudeCompanionIfNeeded({
+                    dryRun,
+                    instructionDefinition,
+                    logPrefix,
+                    overwriteBlockedPaths,
+                    result,
+                    rootDir,
+                });
                 continue;
             }
 
             if (!dryRun) fs.writeFileSync(projectFilepath, nextContent);
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -357,6 +415,14 @@ function ensureInstructionFiles(
             }
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -373,12 +439,28 @@ function ensureInstructionFiles(
             }
             result.overwritten.push(relativeProjectPath);
             logVerbose(`${logPrefix} Replaced ${relativeProjectPath}`);
+            ensureClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                overwriteBlockedPaths,
+                result,
+                rootDir,
+            });
             continue;
         }
 
         if (!dryRun) fs.writeFileSync(projectFilepath, instructionContent);
         result.created.push(relativeProjectPath);
         logVerbose(`${logPrefix} Created ${relativeProjectPath}`);
+        ensureClaudeCompanionIfNeeded({
+            dryRun,
+            instructionDefinition,
+            logPrefix,
+            overwriteBlockedPaths,
+            result,
+            rootDir,
+        });
     }
 
     return result;
@@ -422,6 +504,13 @@ function removeManagedInstructionFiles(
             if (!dryRun) fs.removeSync(projectFilepath);
             result.removed.push(relativeProjectPath);
             logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+            removeClaudeCompanionIfNeeded({
+                dryRun,
+                instructionDefinition,
+                logPrefix,
+                result,
+                rootDir,
+            });
             continue;
         }
 
@@ -437,6 +526,13 @@ function removeManagedInstructionFiles(
                 if (!dryRun) fs.removeSync(projectFilepath);
                 result.removed.push(relativeProjectPath);
                 logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+                removeClaudeCompanionIfNeeded({
+                    dryRun,
+                    instructionDefinition,
+                    logPrefix,
+                    result,
+                    rootDir,
+                });
                 continue;
             }
 
@@ -452,6 +548,179 @@ function removeManagedInstructionFiles(
     return result;
 }
 
+function ensureClaudeCompanionIfNeeded({
+    dryRun,
+    instructionDefinition,
+    logPrefix,
+    overwriteBlockedPaths,
+    result,
+    rootDir,
+}: {
+    dryRun: boolean;
+    instructionDefinition: TAgentInstructionDefinition;
+    logPrefix: string;
+    overwriteBlockedPaths: Set<string>;
+    result: TEnsureInstructionFilesResult;
+    rootDir: string;
+}) {
+    const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+    if (!claudeProjectPath) return;
+
+    mergeEnsureInstructionResults(
+        result,
+        ensureClaudeInstructionSymlink({
+            claudeProjectPath,
+            dryRun,
+            logPrefix,
+            overwriteBlockedPaths,
+            rootDir,
+        }),
+    );
+}
+
+function ensureClaudeInstructionSymlink({
+    claudeProjectPath,
+    dryRun,
+    logPrefix,
+    overwriteBlockedPaths,
+    rootDir,
+}: {
+    claudeProjectPath: string;
+    dryRun: boolean;
+    logPrefix: string;
+    overwriteBlockedPaths: Set<string>;
+    rootDir: string;
+}): TEnsureInstructionFilesResult {
+    const result = createEmptyInstructionResult();
+    const claudeFilepath = path.join(rootDir, claudeProjectPath);
+    const claudeParentDir = path.dirname(claudeFilepath);
+    const relativeClaudePath = path.relative(rootDir, claudeFilepath) || '.';
+
+    if (!fs.existsSync(claudeParentDir)) {
+        result.skipped.push(relativeClaudePath);
+        return result;
+    }
+
+    const existingState = inspectExistingClaudePath(claudeFilepath);
+
+    if (existingState.kind === 'correct') {
+        result.skipped.push(relativeClaudePath);
+        return result;
+    }
+
+    if (existingState.kind === 'missing') {
+        if (!dryRun) fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+        result.created.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Created ${relativeClaudePath}`);
+        return result;
+    }
+
+    if (existingState.kind === 'managed-different') {
+        if (!dryRun) {
+            fs.removeSync(claudeFilepath);
+            fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+        }
+        result.updated.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Updated ${relativeClaudePath}`);
+        return result;
+    }
+
+    const normalizedClaudeFilepath = normalizeAbsolutePath(claudeFilepath);
+    if (!overwriteBlockedPaths.has(normalizedClaudeFilepath)) {
+        result.blocked.push(relativeClaudePath);
+        return result;
+    }
+
+    if (!dryRun) {
+        fs.removeSync(claudeFilepath);
+        fs.symlinkSync(agentInstructionFilename, claudeFilepath);
+    }
+    result.overwritten.push(relativeClaudePath);
+    logVerbose(`${logPrefix} Replaced ${relativeClaudePath}`);
+
+    return result;
+}
+
+function removeClaudeCompanionIfNeeded({
+    dryRun,
+    instructionDefinition,
+    logPrefix,
+    result,
+    rootDir,
+}: {
+    dryRun: boolean;
+    instructionDefinition: TAgentInstructionDefinition;
+    logPrefix: string;
+    result: TEnsureInstructionFilesResult;
+    rootDir: string;
+}) {
+    const claudeProjectPath = getClaudeCompanionProjectPath(instructionDefinition.projectPath);
+    if (!claudeProjectPath) return;
+
+    mergeEnsureInstructionResults(
+        result,
+        removeClaudeInstructionSymlink({
+            claudeProjectPath,
+            dryRun,
+            logPrefix,
+            rootDir,
+        }),
+    );
+}
+
+function removeClaudeInstructionSymlink({
+    claudeProjectPath,
+    dryRun,
+    logPrefix,
+    rootDir,
+}: {
+    claudeProjectPath: string;
+    dryRun: boolean;
+    logPrefix: string;
+    rootDir: string;
+}): TEnsureInstructionFilesResult {
+    const result = createEmptyInstructionResult();
+    const claudeFilepath = path.join(rootDir, claudeProjectPath);
+    const relativeClaudePath = path.relative(rootDir, claudeFilepath) || '.';
+
+    if (!pathEntryExists(claudeFilepath)) return result;
+
+    const existingState = inspectExistingClaudePath(claudeFilepath);
+    if (existingState.kind === 'correct' || existingState.kind === 'managed-different') {
+        if (!dryRun) fs.removeSync(claudeFilepath);
+        result.removed.push(relativeClaudePath);
+        logVerbose(`${logPrefix} Removed retired app-root ${relativeClaudePath}`);
+        return result;
+    }
+
+    if (existingState.kind === 'blocked') result.skipped.push(relativeClaudePath);
+
+    return result;
+}
+
+function inspectExistingClaudePath(claudeFilepath: string) {
+    if (!pathEntryExists(claudeFilepath)) return { kind: 'missing' as const };
+
+    const stats = fs.lstatSync(claudeFilepath);
+    const claudeParentDir = path.dirname(claudeFilepath);
+    const agentFilepath = path.join(claudeParentDir, agentInstructionFilename);
+
+    if (stats.isSymbolicLink()) {
+        const rawTarget = fs.readlinkSync(claudeFilepath);
+        const resolvedTarget = path.resolve(claudeParentDir, rawTarget);
+        if (normalizeAbsolutePath(resolvedTarget) !== normalizeAbsolutePath(agentFilepath)) return { kind: 'blocked' as const };
+
+        return rawTarget === agentInstructionFilename ? { kind: 'correct' as const } : { kind: 'managed-different' as const };
+    }
+
+    if (!stats.isFile()) return { kind: 'blocked' as const };
+
+    const content = fs.readFileSync(claudeFilepath, 'utf8');
+    if (content.trim() === claudeInstructionPointerContent) return { kind: 'managed-different' as const };
+
+    return { kind: 'blocked' as const };
+}
+
 function inspectExistingPath({
     managedSourceRoot,
     projectFilepath,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.2",
+	"version": "2.5.3",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/agents-utils.test.cjs

@@ -15,6 +15,23 @@ const writeFile = (filepath, content) => {
     fs.writeFileSync(filepath, content);
 };
 
+const assertClaudeSymlink = (root, relativeDir = '') => {
+    const linkPath = path.join(root, relativeDir, 'CLAUDE.md');
+    const stats = fs.lstatSync(linkPath);
+
+    assert.equal(stats.isSymbolicLink(), true, `${linkPath} should be a symlink`);
+    assert.equal(fs.readlinkSync(linkPath), 'AGENTS.md');
+};
+
+const pathEntryExists = (filepath) => {
+    try {
+        fs.lstatSync(filepath);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
 const makeTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-agents-'));
 
 const createCoreFixture = () => {
@@ -53,6 +70,7 @@ const createAppFixture = () => {
             'node_modules',
             '# Proteum-managed instruction files',
             '/AGENTS.md',
+            '/CLAUDE.md',
             '/CODING_STYLE.md',
             '/DOCUMENTATION.md',
             '# End Proteum-managed instruction files',
@@ -137,9 +155,17 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md')), true);
     assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /Journey rule/);
     assert.doesNotMatch(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assertClaudeSymlink(appRoot);
+    assertClaudeSymlink(appRoot, 'client');
+    assertClaudeSymlink(appRoot, 'client/pages');
+    assertClaudeSymlink(appRoot, 'server/routes');
+    assertClaudeSymlink(appRoot, 'server/services');
+    assertClaudeSymlink(appRoot, 'tests');
+    assertClaudeSymlink(appRoot, 'tests/e2e');
     assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
     assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
     assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
+    assert.doesNotMatch(gitignoreContent, /^\/CLAUDE\.md$/m);
     assert.doesNotMatch(gitignoreContent, /^\/DOCUMENTATION\.md$/m);
 });
 
@@ -255,13 +281,20 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'AGENTS.md'), 'utf8'), /## Source: tests\/e2e\/AGENTS\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: tests\/e2e\/REAL_WORLD_JOURNEY_TESTS\.md/);
     assert.doesNotMatch(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assertClaudeSymlink(monorepoRoot);
+    assertClaudeSymlink(monorepoRoot, 'tests');
+    assertClaudeSymlink(monorepoRoot, 'tests/e2e');
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'AGENTS.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), false);
+    assert.equal(pathEntryExists(path.join(appRoot, 'tests', 'CLAUDE.md')), false);
+    assert.equal(pathEntryExists(path.join(appRoot, 'tests', 'e2e', 'CLAUDE.md')), false);
     const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     assert.match(appAgentsContent, /## Agent Routing Contract/);
     assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
     assert.doesNotMatch(appAgentsContent, /Do not start `npx proteum dev` from this root/);
     assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
+    assertClaudeSymlink(appRoot);
+    assertClaudeSymlink(appRoot, 'client');
     assert.equal(fs.existsSync(path.join(appRoot, 'CODING_STYLE.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'DOCUMENTATION.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'diagnostics.md')), false);
@@ -331,6 +364,45 @@ test('configure migrates legacy managed symlinks to tracked files', () => {
     assert.equal(result.updated.some((entry) => entry.endsWith('/AGENTS.md')), true);
     assert.equal(stats.isSymbolicLink(), false);
     assert.match(content, /# Proteum Instructions/);
+    assertClaudeSymlink(appRoot);
+});
+
+test('configure migrates one-line Claude pointer files to symlinks', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const linkPath = path.join(appRoot, 'CLAUDE.md');
+
+    writeFile(linkPath, '@AGENTS.md\n');
+
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+
+    assert.equal(result.updated.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assertClaudeSymlink(appRoot);
+});
+
+test('configure reports blocked Claude companion paths unless overwrite is allowed', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = createAppFixture();
+    const blockedPath = path.join(appRoot, 'CLAUDE.md');
+
+    writeFile(blockedPath, '# Local Claude Notes\n\n- Keep this local rule.\n');
+
+    const preview = configureProjectAgentInstructions({ appRoot, coreRoot, dryRun: true });
+    assert.equal(preview.blocked.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+
+    const blockedResult = configureProjectAgentInstructions({ appRoot, coreRoot });
+    assert.equal(blockedResult.blocked.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assert.equal(fs.lstatSync(blockedPath).isFile(), true);
+    assert.match(fs.readFileSync(blockedPath, 'utf8'), /Keep this local rule/);
+
+    const result = configureProjectAgentInstructions({
+        appRoot,
+        coreRoot,
+        overwriteBlockedPaths: [blockedPath],
+    });
+
+    assert.equal(result.overwritten.some((entry) => entry.endsWith('/CLAUDE.md')), true);
+    assertClaudeSymlink(appRoot);
 });
 
 test('configure reports blocked paths unless overwrite is allowed', () => {