proteum 2.5.23 → 2.5.24

package/common/dev/inspection.ts

@@ -780,14 +780,23 @@ const resolveGuidance = ({
     manifest: TProteumManifest;
     ownerFilepath?: string;
 }) => {
-    // `agentInstructions: false`: the project owns one hand-written CLAUDE.md and deleted the routed
-    // copies, so every guidance slot points at it instead of Proteum's bundled fallbacks.
+    // `agentInstructions: false`: the project owns one hand-written instruction file and deleted the
+    // routed copies, so every guidance slot points at it instead of Proteum's bundled fallbacks.
+    // Claude Code reads CLAUDE.md when it exists and AGENTS.md otherwise; follow the same order.
     if (manifest.app.setup.agentInstructions === false) {
-        const claudeInstructions = resolveGuidanceFile({
+        const claudeFile = resolveGuidanceFile({
             appRoot: manifest.app.root,
-            fallbackFilepath: joinPath(manifest.app.root, 'CLAUDE.md'),
+            fallbackFilepath: '',
             relativePath: 'CLAUDE.md',
-        }).filepath;
+        });
+        const claudeInstructions =
+            claudeFile.warning === undefined
+                ? claudeFile.filepath
+                : resolveGuidanceFile({
+                      appRoot: manifest.app.root,
+                      fallbackFilepath: joinPath(manifest.app.root, 'AGENTS.md'),
+                      relativePath: 'AGENTS.md',
+                  }).filepath;
 
         return {
             guidance: {

package/common/dev/mcpPayloads.ts

@@ -940,12 +940,13 @@ export const resolveInstructionRouting = ({
     const selected = new Map<string, ReturnType<typeof createSelectedInstruction>>();
     const readWhen: Array<{ file?: string; when: string }> = [];
 
-    // `agentInstructions: false`: the routed AGENTS.md copies no longer exist; route to the hand-owned CLAUDE.md.
+    // `agentInstructions: false`: the routed copies no longer exist; route to the hand-owned file the
+    // agent actually loads (Claude Code reads CLAUDE.md when it exists and AGENTS.md otherwise).
     if (!readsProteumManagedInstructions(appRoot)) {
-        const claudeFile = resolveDocumentFile({ appRoot, repoRoot, relativeFilepath: 'CLAUDE.md' });
-        if (claudeFile && fileExists(claudeFile)) {
-            selected.set(claudeFile, createSelectedInstruction(claudeFile, 'Project-owned agent instructions.'));
-        }
+        const ownedFile = ['CLAUDE.md', 'AGENTS.md']
+            .map((relativeFilepath) => resolveDocumentFile({ appRoot, repoRoot, relativeFilepath }))
+            .find((filepath) => filepath !== undefined && fileExists(filepath));
+        if (ownedFile) selected.set(ownedFile, createSelectedInstruction(ownedFile, 'Project-owned agent instructions.'));
         const selectedFiles = [...selected.values()];
         return createMcpPayload({
             summary: `${selectedFiles.length} instruction files selected for ${normalizedQuery || 'current app'}`,

package/docs/agent-routing.md

@@ -141,4 +141,4 @@ The result confirms the intended routing:
 
 ## Hand-Owned Instructions
 
-A project that writes its own agent instructions sets `agentInstructions: false` in each app's `proteum.config.ts`. Proteum then never writes `AGENTS.md`, `CLAUDE.md` or the routed instruction copies for that app: `proteum dev` skips the sync, `proteum configure agents` refuses to run, and a monorepo root is managed only when no app opted out. MCP `workflow_start` and `instructions_resolve` route such apps to their `CLAUDE.md`, and orientation guidance points there instead of Proteum's bundled fallbacks.
+A project that writes its own agent instructions sets `agentInstructions: false` in each app's `proteum.config.ts`. Proteum then never writes `AGENTS.md`, `CLAUDE.md` or the routed instruction copies for that app: `proteum dev` skips the sync, `proteum configure agents` refuses to run, and a monorepo root is managed only when no app opted out. MCP `workflow_start` and `instructions_resolve` route such apps to their hand-owned instruction file (`CLAUDE.md` when it exists, else `AGENTS.md`, the order Claude Code reads them in), and orientation guidance points there instead of Proteum's bundled fallbacks.

package/package.json

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

package/tests/inspection.test.cjs

@@ -6,7 +6,7 @@ process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 require('ts-node/register/transpile-only');
 
-const { explainOwner } = require('../common/dev/inspection.ts');
+const { buildOrientationResponse, explainOwner } = require('../common/dev/inspection.ts');
 
 const createRoute = (routePath, filepath) => ({
     chunkFilepath: filepath,
@@ -64,3 +64,21 @@ test('root owner lookup returns only the literal root route when present', () =>
     assert.equal(matches.length, 1);
     assert.equal(matches[0].label, '/');
 });
+
+test('orientation guidance of an opted-out app points at its hand-owned instruction file', () => {
+    const fs = require('node:fs');
+    const os = require('node:os');
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-owned-guidance-'));
+    fs.mkdirSync(path.join(appRoot, '.git'));
+    fs.writeFileSync(path.join(appRoot, 'AGENTS.md'), '# Owned\n');
+    const manifest = createManifest([]);
+    manifest.app = { coreRoot, root: appRoot, identity: { identifier: 'OwnedApp', name: 'Owned App' }, setup: { agentInstructions: false } };
+
+    const agentsOnly = buildOrientationResponse(manifest, '/').guidance;
+    assert.equal(agentsOnly.agents, path.join(appRoot, 'AGENTS.md'));
+    assert.equal(agentsOnly.documentation, path.join(appRoot, 'AGENTS.md'));
+    assert.deepEqual(agentsOnly.areaAgents, []);
+
+    fs.writeFileSync(path.join(appRoot, 'CLAUDE.md'), '# Owned for Claude\n');
+    assert.equal(buildOrientationResponse(manifest, '/').guidance.agents, path.join(appRoot, 'CLAUDE.md'));
+});

package/tests/mcp.test.cjs

@@ -156,6 +156,23 @@ const writeFreshCopyFixture = (appRoot, manifestOverrides = {}) => {
     writeFile(path.join(appRoot, '.proteum', 'manifest.json'), JSON.stringify(createManifest(appRoot, manifestOverrides), null, 2));
 };
 
+test('instruction routing sends an opted-out app to its hand-owned instruction file', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-owned-'));
+
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default { agentInstructions: false };\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Owned\n');
+    writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Stale routed copy\n');
+
+    const agentsOnly = resolveInstructionRouting({ appRoot, query: 'client/pages/domain.tsx' });
+    assert.deepEqual(agentsOnly.data.selected.map((entry) => path.relative(appRoot, entry.file)), ['AGENTS.md']);
+    assert.deepEqual(agentsOnly.data.readWhen, []);
+
+    // Claude Code reads CLAUDE.md first when both exist, so routing follows it.
+    writeFile(path.join(appRoot, 'CLAUDE.md'), '# Owned for Claude\n');
+    const withClaude = resolveInstructionRouting({ appRoot, query: 'client/pages/domain.tsx' });
+    assert.deepEqual(withClaude.data.selected.map((entry) => path.relative(appRoot, entry.file)), ['CLAUDE.md']);
+});
+
 test('instruction routing returns compact selected files for a page query', () => {
     const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-app-'));