proteum 2.5.5 → 2.5.7

package/agents/project/AGENTS.md

@@ -81,7 +81,6 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
 - Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
-- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 

package/agents/project/root/AGENTS.md

@@ -67,7 +67,6 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
 - For production changes, always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every ordinary change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; downstream app commit-only workflows run `proteum refresh`, then targeted lint, typecheck, and test commands in parallel unless the user explicitly requests more, while framework-repo commits skip this downstream app verification. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
 - Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
-- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 

package/cli/commands/configure.ts

@@ -14,10 +14,12 @@ import { renderRows } from '../presentation/layout';
 import { isLikelyProteumAppRoot } from '../presentation/commands';
 import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
 import {
+    configureMonorepoProjectAgentInstructions,
     configureProjectAgentInstructions,
     findLikelyRepoRoot,
     isInsideDirectory,
     resolveCanonicalPath,
+    type TConfigureMonorepoProjectAgentInstructionsResult,
     type TConfigureProjectAgentInstructionsResult,
 } from '../utils/agents';
 
@@ -68,20 +70,22 @@ const promptMonorepoRoot = async ({
     return resolveCanonicalPath(String(response.value || defaultRoot || ''));
 };
 
-const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
-    if (blockedPaths.length === 0) return [];
+export const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
+    const uniqueBlockedPaths = [...new Set(blockedPaths)];
+
+    if (uniqueBlockedPaths.length === 0) return [];
 
     console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
             'Choose whether to overwrite each path with a Proteum-managed instruction path:',
-            ...blockedPaths.map((entry) => `- ${entry}`),
+            ...uniqueBlockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
 
     const overwriteBlockedPaths: string[] = [];
 
-    for (const blockedPath of blockedPaths) {
+    for (const blockedPath of uniqueBlockedPaths) {
         const response = await prompts(
             {
                 type: 'confirm',
@@ -133,6 +137,12 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentInstruction
     return sections;
 };
 
+const renderConfigureMonorepoResultSections = (result: TConfigureMonorepoProjectAgentInstructionsResult) =>
+    renderConfigureResultSections({
+        ...result,
+        appRoot: result.monorepoRoot,
+    });
+
 /*----------------------------------
 - COMMAND
 ----------------------------------*/
@@ -218,3 +228,52 @@ export const runConfigureAgentsWizard = async ({
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };
+
+export const runConfigureAgentsMonorepoWizard = async ({
+    appRoots,
+    coreRoot = cli.paths.core.root,
+    monorepoRoot,
+}: {
+    appRoots: string[];
+    coreRoot?: string;
+    monorepoRoot: string;
+}) => {
+    if (appRoots.length === 0) throw new UsageError(`No Proteum app roots were found under ${monorepoRoot}.`);
+    for (const appRoot of appRoots) assertProteumAppRoot(appRoot);
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
+    }
+
+    console.info(
+        [
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure monorepo Proteum instruction files and Claude aliases.'),
+            renderRows([
+                { label: 'monorepo root', value: monorepoRoot === process.cwd() ? '.' : monorepoRoot },
+                { label: 'apps', value: String(appRoots.length) },
+            ]),
+        ].join('\n\n'),
+    );
+
+    const preview = configureMonorepoProjectAgentInstructions({
+        appRoots,
+        coreRoot,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedOverwritePaths(preview.blocked);
+
+    console.info(await renderStep('[1/1]', 'Writing monorepo root and app instruction files and Claude aliases.'));
+
+    const result = configureMonorepoProjectAgentInstructions({
+        appRoots,
+        coreRoot,
+        monorepoRoot,
+        overwriteBlockedPaths,
+    });
+    const sections = renderConfigureMonorepoResultSections(result);
+
+    console.info(await renderSuccess('Proteum-managed monorepo instruction files and Claude aliases are configured.'));
+
+    if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
+};

package/cli/index.ts

@@ -9,6 +9,7 @@ import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from '
 import { renderCliWelcomeBanner } from './presentation/welcome';
 import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
 import { createCli, registeredCommands } from './runtime/commands';
+import { isMonorepoFanoutChild, maybeRunMonorepoCommand } from './runtime/monorepoCommands';
 
 const formatInvocation = (argv: string[]) => ['proteum', ...argv].join(' ').trim();
 
@@ -21,6 +22,7 @@ const shouldRenderSharedWelcomeBanner = ({
     argv: string[];
     helpRequestKind: 'none' | 'overview' | 'command';
 }) => {
+    if (isMonorepoFanoutChild()) return false;
     if (helpRequestKind !== 'none') return false;
     if (argv.length !== 1) return false;
 
@@ -32,27 +34,9 @@ const shouldRenderSharedWelcomeBanner = ({
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
     const version = String(cli.packageJson.version || '');
-    const proteumInstall = resolveFrameworkInstallInfo({
-        appRoot: cli.paths.appRoot,
-        framework: cli.paths.framework,
-    });
     const clipanion = createCli(version);
     const initAvailable = true;
     const helpRequest = resolveCustomHelpRequest(normalizedArgv);
-    const shouldRenderWelcomeBanner = shouldRenderSharedWelcomeBanner({
-        argv: normalizedArgv,
-        helpRequestKind: helpRequest.kind,
-    });
-
-    if (shouldRenderWelcomeBanner) {
-        process.stderr.write(
-            `${await renderCliWelcomeBanner({
-                command: formatInvocation(normalizedArgv),
-                installSummary: proteumInstall.summary,
-                version,
-            })}\n\n`,
-        );
-    }
 
     if (helpRequest.kind === 'overview') {
         process.stdout.write(
@@ -77,6 +61,28 @@ export const runCli = async (argv: string[] = process.argv.slice(2)) => {
         return;
     }
 
+    if (await maybeRunMonorepoCommand(normalizedArgv)) return;
+
+    const shouldRenderWelcomeBanner = shouldRenderSharedWelcomeBanner({
+        argv: normalizedArgv,
+        helpRequestKind: helpRequest.kind,
+    });
+
+    if (shouldRenderWelcomeBanner) {
+        const proteumInstall = resolveFrameworkInstallInfo({
+            appRoot: cli.paths.appRoot,
+            framework: cli.paths.framework,
+        });
+
+        process.stderr.write(
+            `${await renderCliWelcomeBanner({
+                command: formatInvocation(normalizedArgv),
+                installSummary: proteumInstall.summary,
+                version,
+            })}\n\n`,
+        );
+    }
+
     await clipanion.runExit(normalizedArgv, Cli.defaultContext);
 };
 

package/cli/presentation/commands.ts

@@ -130,6 +130,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             '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 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.',
+            'When run from a monorepo wrapper root that contains Proteum apps, configure writes the shared root documents once and app-root instruction files for every discovered app.',
             '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.',
@@ -167,6 +168,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             'Bootstrap writes `.proteum/worktree-bootstrap.json` with hashes, step timestamps, dependency status, runtime status, and Proteum version.',
             'When `.env` is missing, `--source` is required and must point to an app root with a readable `.env`.',
             'For monorepos with root tooling, bootstrap also ensures the workspace-root `.env` exists from the source root or source app env.',
+            'When `worktree init` runs from a monorepo wrapper root, Proteum bootstraps every discovered app, matches source apps by relative path, and deduplicates dependency install by shared package-lock root.',
+            'When `worktree create` runs from a source monorepo wrapper root, Proteum creates the Git worktree once and then bootstraps every matching target app.',
             'Guarded commands block inside `/.codex/worktrees/` until bootstrap is complete or explicitly bypassed with `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1`.',
             '`worktree create` preserves the source app root path relative to the source repository root, so monorepo app roots are bootstrapped in the matching target location.',
         ],
@@ -207,13 +210,14 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
-            'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
+            'From a monorepo wrapper root, eligible app-scoped commands run for every discovered Proteum app. Use an app root or `--cwd` when supported to target exactly one app.',
+            'From a monorepo wrapper root, bare `proteum dev` supervises all discovered apps with app-local session files and unique router/HMR port pairs; `dev list` and `dev stop` aggregate every app.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
             'Before registering a new session, Proteum removes stale same-worktree session files and fails fast if another live tracked session remains.',
             'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
             'Use `--replace-existing` only when retrying the exact requested session file.',
-            '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
-            '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',
+            '`proteum dev list` inspects tracked sessions for the current app root, or every discovered app from a monorepo wrapper root. Add `--stale` to show only orphaned or dead sessions.',
+            '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root, or run from a monorepo wrapper root to apply the stop command to every app.',
             '`proteum dev` clears the interactive terminal once at startup, then shows `CTRL+R` reload and `CTRL+C` shutdown hotkeys in the session banner.',
             'Legacy single-dash long options remain supported, for example `proteum dev -port 3001`.',
         ],
@@ -229,7 +233,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         examples: [
             { description: 'Refresh generated contracts after source edits', command: 'proteum refresh' },
         ],
-        notes: ['Use this when you need deterministic regeneration without starting the full dev loop.'],
+        notes: ['Use this when you need deterministic regeneration without starting the full dev loop.', 'From a monorepo wrapper root, refresh runs once per discovered Proteum app.'],
         status: 'stable',
     },
     build: {
@@ -257,6 +261,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             '`--analyze-serve` switches the analyzer to HTTP server mode and keeps the process open until you stop it.',
             '`--analyze-host` and `--analyze-port` require `--analyze-serve`; use `auto` to let the OS assign a free port.',
             'Use `--strict` when the build must refresh generated typings and fail on any TypeScript error before compilation starts.',
+            'From a monorepo wrapper root, build runs once per discovered Proteum app. `--analyze-serve` must be run from one app root because the analyzer server stays open.',
             'The production output is emitted under `bin/`.',
         ],
         status: 'stable',
@@ -270,7 +275,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         examples: [
             { description: 'Typecheck every discovered client and server app tsconfig', command: 'proteum typecheck' },
         ],
-        notes: ['Proteum refreshes generated typings before running TypeScript.'],
+        notes: ['Proteum refreshes generated typings before running TypeScript.', 'From a monorepo wrapper root, typecheck runs once per discovered Proteum app.'],
         status: 'stable',
     },
     lint: {
@@ -283,7 +288,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Run ESLint in check mode', command: 'proteum lint' },
             { description: 'Apply fixable lint changes', command: 'proteum lint --fix' },
         ],
-        notes: ['Legacy positional usage such as `proteum lint fix` remains supported.'],
+        notes: ['Legacy positional usage such as `proteum lint fix` remains supported.', 'From a monorepo wrapper root, lint runs once per discovered Proteum app.'],
         status: 'stable',
     },
     check: {
@@ -293,7 +298,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         usage: 'proteum check',
         bestFor: 'One command before commits, pushes, or CI when you want the standard local validation path.',
         examples: [{ description: 'Run the full default validation pipeline', command: 'proteum check' }],
-        notes: ['This command executes refresh, typecheck, then lint in that order.'],
+        notes: ['This command executes refresh, typecheck, then lint in that order.', 'From a monorepo wrapper root, check runs once per discovered Proteum app.'],
         status: 'stable',
     },
     e2e: {