proteum 2.2.6 → 2.2.7

package/AGENTS.md

@@ -58,7 +58,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - 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.
 - 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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 banner. 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.
 - 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

@@ -347,7 +347,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 framework-facing workflows across one or more running dev apps; `framework-change` is the built-in cross-reference-app check |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
-| `proteum configure agents` | Interactively configure Proteum-managed instruction symlinks and confirm overwrites for standalone or monorepo apps |
+| `proteum configure agents` | Interactively configure tracked Proteum instruction files for standalone or monorepo apps |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
 Recommended daily workflow:
@@ -361,7 +361,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. When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` 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 before the dev loop begins.
 
 Useful inspection commands:
 
@@ -404,9 +404,9 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
-`proteum configure agents` asks before replacing any existing non-managed instruction file or foreign symlink. If you decline, that path is left untouched.
+`proteum configure agents` embeds the full Proteum project instruction corpus into the managed `# Proteum Instructions` section of each tracked instruction file. It preserves content outside that section and asks before replacing directories or foreign symlinks. If you decline, that path is left untouched.
 
-Bare interactive `proteum dev` reuses that same wizard when the app root is missing `AGENTS.md`; declining the prompt continues the dev start without writing files.
+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.
 
 `proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md) and [docs/request-tracing.md](docs/request-tracing.md).
 

package/agents/project/AGENTS.md

@@ -21,6 +21,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - If the user pastes raw errors without asking for a fix, do not implement changes yet. First run the task-safe local reproduction path: identify the likely app, route, command, or request from the error, boot or reuse the relevant dev server with the elevated-permissions workflow in `Task Lifecycle`, reproduce the failing surface locally, and inspect server output, browser console output, diagnostics, traces, or the smallest relevant command result. If the error does not identify enough context to reproduce, say what is missing and use the available local evidence before guessing. Then list likely causes and, for each one, give probability, why, and how to fix it. After this, every time you implement a fix:
     - test, re-run analysis and give a comparison table of before and after
     - re-print the complete list of suggested fixes, but strike the ones we already implemented or not necessary anymore
+- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
 - If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
@@ -57,7 +58,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - 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.
 - 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.
 - 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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 banner. 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.
 
 ### Before Finishing
 

package/agents/project/app-root/AGENTS.md

@@ -12,5 +12,5 @@ Do not put here: reusable Proteum architecture contracts, shared verification ru
   - Run `npx proteum refresh`.
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If the bare interactive `proteum dev` start offers to launch `proteum configure agents`, finish that wizard before continuing.
+  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If `proteum dev` reports blocked instruction paths, resolve them before continuing.
 - If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.

package/agents/project/diagnostics.md

@@ -15,7 +15,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 dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `npx proteum dev` start offers to launch `npx proteum configure agents` 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 banner. 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.
 - For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
 - Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then browser MCP validation when the bug is browser-visible. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.

package/agents/project/root/AGENTS.md

@@ -12,6 +12,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ## Fast Triggers
 
 - If the user pastes raw errors without asking for a fix, do not implement changes yet. First run the task-safe local reproduction path: identify the likely app, route, command, or request from the error, boot or reuse the relevant dev server with the elevated-permissions workflow in `Task Lifecycle`, reproduce the failing surface locally, and inspect server output, browser console output, diagnostics, traces, or the smallest relevant command result. If the error does not identify enough context to reproduce, say what is missing and use the available local evidence before guessing. Then list likely causes and, for each one, give probability, why, and how to fix it.
+- If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, or question you see. If a concern is blocking, or it can materially change product behavior, API shape, architecture, data model, cost, privacy, security, or UX, ask before editing; otherwise state the assumption and continue implementing.
 - If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
@@ -47,7 +48,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - 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.
 - 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.
 - 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 banner. 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. When the app root is missing `AGENTS.md`, the bare interactive `proteum dev` start offers to launch `proteum configure agents` 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 banner. 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.
 
 ### Before Finishing
 

package/cli/commands/configure.ts

@@ -13,39 +13,18 @@ import cli from '..';
 import { renderRows } from '../presentation/layout';
 import { isLikelyProteumAppRoot } from '../presentation/commands';
 import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
-import { configureProjectAgentInstructions, type TConfigureProjectAgentInstructionsResult } from '../utils/agents';
+import {
+    configureProjectAgentInstructions,
+    findLikelyRepoRoot,
+    isInsideDirectory,
+    resolveCanonicalPath,
+    type TConfigureProjectAgentInstructionsResult,
+} from '../utils/agents';
 
 /*----------------------------------
 - HELPERS
 ----------------------------------*/
 
-const findLikelyRepoRoot = (startPath: string) => {
-    let currentPath = path.resolve(startPath);
-
-    while (true) {
-        if (fs.existsSync(path.join(currentPath, '.git'))) return currentPath;
-
-        const parentPath = path.dirname(currentPath);
-        if (parentPath === currentPath) return undefined;
-        currentPath = parentPath;
-    }
-};
-
-const resolveCanonicalPath = (inputPath: string) => {
-    const resolvedPath = path.resolve(inputPath);
-
-    try {
-        return fs.realpathSync(resolvedPath);
-    } catch {
-        return resolvedPath;
-    }
-};
-
-const isInsideDirectory = ({ child, parent }: { child: string; parent: string }) => {
-    const relativePath = path.relative(parent, child);
-    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
-};
-
 const assertProteumAppRoot = (appRoot: string) => {
     if (isLikelyProteumAppRoot(appRoot)) return;
 
@@ -92,10 +71,10 @@ const promptMonorepoRoot = async ({
 const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
     if (blockedPaths.length === 0) return [];
 
-    console.info(await renderWarning('Proteum found existing non-managed instruction paths.'));
+    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 stub:',
+            'Choose whether to overwrite each path with a tracked Proteum instruction file:',
             ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
@@ -145,7 +124,7 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentInstruction
     if (result.blocked.length > 0)
         sections.push(
             [
-                'Skipped existing non-managed paths:',
+                'Skipped blocked paths:',
                 ...result.blocked.map((entry) => `- ${entry}`),
             ].join('\n'),
         );
@@ -183,7 +162,7 @@ export const runConfigureAgentsWizard = async ({
             : undefined;
     console.info(
         [
-            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure Proteum-managed instruction stubs.'),
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure tracked Proteum instruction files.'),
             renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
         ].join('\n\n'),
     );
@@ -221,8 +200,8 @@ export const runConfigureAgentsWizard = async ({
         await renderStep(
             '[1/1]',
             isMonorepo
-                ? `Writing monorepo-aware instruction stubs using ${monorepoRoot}.`
-                : 'Writing standalone instruction stubs.',
+                ? `Writing monorepo-aware instruction files using ${monorepoRoot}.`
+                : 'Writing standalone instruction files.',
         ),
     );
 
@@ -234,7 +213,7 @@ export const runConfigureAgentsWizard = async ({
     });
     const sections = renderConfigureResultSections(result);
 
-    console.info(await renderSuccess('Proteum-managed instruction stubs are configured.'));
+    console.info(await renderSuccess('Proteum-managed instruction files are configured.'));
 
     if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
 };

package/cli/commands/dev.ts

@@ -22,7 +22,6 @@ import {
 
 // Configs
 import Compiler from '../compiler';
-import { regex } from '../compiler/common';
 import { createDevEventServer } from './devEvents';
 import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { clearInteractiveConsole } from '../presentation/welcome';
@@ -41,8 +40,7 @@ import {
 } from '../runtime/devSessions';
 import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
-import { inspectProjectAgentFiles } from '../utils/agents';
-import { runConfigureAgentsWizard } from './configure';
+import { configureProjectAgentInstructions, resolveProjectAgentMonorepoRoot } from '../utils/agents';
 
 // Core
 import { app, App } from '../app';
@@ -61,6 +59,7 @@ const hotReloadableServerPathPatterns = [
     /^server\/services\/.+\.controller\.[jt]sx?$/,
 ];
 const hotReloadableRoots = [() => app.paths.root, () => cli.paths.core.root];
+const transpileSourceWatchPattern = /\.(ts|tsx|js|jsx|css|less|scss)$/;
 
 /*----------------------------------
 - STATE
@@ -144,43 +143,74 @@ const createIgnoredWatchMatcher = (outputPaths: string[]) => (watchPath: string)
     return ignoredWatchPathPatterns.test(normalizedWatchPath);
 };
 
-const promptToConfigureAgentsIfMissing = async () => {
-    if (cli.args.json === true) return;
-    if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-
-    const inspection = inspectProjectAgentFiles({ appRoot: app.paths.root });
-    if (!inspection.missing.includes('AGENTS.md')) return;
+const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) => {
+    if (blockedPaths.length === 0) return [];
+    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:',
+                ...blockedPaths.map((entry) => `- ${entry}`),
+                'Run `proteum configure agents` in an interactive terminal to choose which paths can be replaced.',
+            ].join('\n'),
+        );
+    }
 
-    console.info(await renderWarning('Proteum could not find the app-root `AGENTS.md` instruction file.'));
+    console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Missing standard AGENTS files:',
-            ...inspection.missing.map((entry) => `- ${entry}`),
-            '',
-            'Run `proteum configure agents` now before starting the dev server?',
+            'Choose whether to overwrite each blocked path with a tracked Proteum instruction file:',
+            ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
 
-    const response = await prompts(
-        {
-            type: 'confirm',
-            name: 'value',
-            message: 'Run the configure-agents wizard now?',
-            initial: true,
-        },
-        {
-            onCancel: () => {
-                throw new UsageError('Cancelled `proteum dev`.');
+    const overwriteBlockedPaths: string[] = [];
+
+    for (const blockedPath of blockedPaths) {
+        const response = await prompts(
+            {
+                type: 'confirm',
+                name: 'value',
+                message: `Overwrite ${blockedPath}?`,
+                initial: false,
             },
-        },
-    );
+            {
+                onCancel: () => {
+                    throw new UsageError('Cancelled `proteum dev`.');
+                },
+            },
+        );
+
+        if (response.value === true) overwriteBlockedPaths.push(blockedPath);
+    }
 
-    if (response.value !== true) return;
+    return overwriteBlockedPaths;
+};
+
+const ensureProjectAgentInstructions = async () => {
+    const monorepoRoot = resolveProjectAgentMonorepoRoot(app.paths.root);
+    const preview = configureProjectAgentInstructions({
+        appRoot: app.paths.root,
+        coreRoot: cli.paths.core.root,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedAgentInstructionOverwrites(preview.blocked);
 
-    await runConfigureAgentsWizard({
+    const result = configureProjectAgentInstructions({
         appRoot: app.paths.root,
         coreRoot: cli.paths.core.root,
+        monorepoRoot,
+        overwriteBlockedPaths,
     });
+
+    if (result.blocked.length === 0) return;
+
+    throw new UsageError(
+        [
+            'Proteum could not update all managed instruction files because these paths were left blocked:',
+            ...result.blocked.map((entry) => `- ${entry}`),
+        ].join('\n'),
+    );
 };
 
 const getDevAppName = (app: App) =>
@@ -530,11 +560,11 @@ type TIndexedSourceWatchEvent = 'change' | 'rename';
 type TIndexedSourceWatchCompilerName = 'server' | 'client';
 type TIndexedSourceWatchInvalidateTarget = 'all' | TIndexedSourceWatchCompilerName;
 type TIndexedSourceWatchRule = {
-    compilerName: TIndexedSourceWatchCompilerName;
+    compilerNames: TIndexedSourceWatchCompilerName[];
     rootPath: string;
     relativePathPattern: RegExp;
     eventTypes: TIndexedSourceWatchEvent[];
-    invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+    invalidateTargets: TIndexedSourceWatchInvalidateTarget[];
 };
 type TNamedWatching = { compiler: { name?: string }; invalidate: () => void };
 type TMultiWatchingLike = TDevWatching & { watchings?: TNamedWatching[] };
@@ -553,26 +583,26 @@ const resolveIndexedSourceWatchRules = (): TIndexedSourceWatchRule[] => {
 
     return [
         {
-            compilerName: 'server',
+            compilerNames: ['server'],
             rootPath: app.paths.root,
             relativePathPattern: /^commands(?:\/|$)/,
             eventTypes: ['rename'],
-            invalidateTarget: 'all',
+            invalidateTargets: ['all'],
         },
         {
-            compilerName: 'server',
+            compilerNames: ['server'],
             rootPath: cli.paths.core.root,
             relativePathPattern: /^commands(?:\/|$)/,
             eventTypes: ['rename'],
-            invalidateTarget: 'all',
+            invalidateTargets: ['all'],
         },
         ...transpileWatchRoots.map(
             (rootPath): TIndexedSourceWatchRule => ({
-                compilerName: 'server',
+                compilerNames: ['client', 'server'],
                 rootPath,
-                relativePathPattern: regex.scripts,
+                relativePathPattern: transpileSourceWatchPattern,
                 eventTypes: ['change', 'rename'],
-                invalidateTarget: 'server',
+                invalidateTargets: ['client', 'server'],
             }),
         ),
     ];
@@ -587,6 +617,12 @@ const findCompilerWatching = (
     return childWatchings?.find((childWatching) => childWatching.compiler.name === compilerName);
 };
 
+const formatInvalidateTargets = (invalidateTargets: TIndexedSourceWatchCompilerName[]) => {
+    if (invalidateTargets.length === 1) return invalidateTargets[0];
+    if (invalidateTargets.length === 2) return `${invalidateTargets[0]} and ${invalidateTargets[1]}`;
+    return `${invalidateTargets.slice(0, -1).join(', ')}, and ${invalidateTargets[invalidateTargets.length - 1]}`;
+};
+
 const closeFsWatcher = async (watcher: FSWatcher) => {
     await new Promise<void>((resolve) => {
         watcher.once('close', () => resolve());
@@ -618,7 +654,7 @@ const createIndexedSourceWatching = ({
 
         if (pendingInvalidateTargets.has('all')) {
             pendingInvalidateTargets.clear();
-            logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+            logVerbose('Indexed source files changed. Invalidating all dev compilers to refresh generated artifacts.');
             watching.invalidate();
             return;
         }
@@ -630,40 +666,57 @@ const createIndexedSourceWatching = ({
 
         if (invalidateTargets.length === 0) return;
 
-        logVerbose('Transpiled source files changed. Invalidating the server compiler to refresh mutable package code.');
+        const compilerWatchings: TNamedWatching[] = [];
+
         for (const invalidateTarget of invalidateTargets) {
             const compilerWatching = findCompilerWatching(watching, invalidateTarget);
 
             if (!compilerWatching) {
+                logVerbose('Transpiled source files changed. Invalidating all dev compilers to refresh mutable package code.');
                 watching.invalidate();
                 return;
             }
 
+            compilerWatchings.push(compilerWatching);
+        }
+
+        logVerbose(
+            `Transpiled source files changed. Invalidating ${formatInvalidateTargets(
+                invalidateTargets,
+            )} compilers to refresh mutable package code.`,
+        );
+        for (const compilerWatching of compilerWatchings) {
             compilerWatching.invalidate();
         }
     };
 
     const queueInvalidate = ({
-        compilerName,
+        compilerNames,
         filepath,
-        invalidateTarget,
+        invalidateTargets,
     }: {
-        compilerName: TIndexedSourceWatchCompilerName;
+        compilerNames: TIndexedSourceWatchCompilerName[];
         filepath: string;
-        invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+        invalidateTargets: TIndexedSourceWatchInvalidateTarget[];
     }) => {
         const normalizedFilepath = normalizeWatchPath(filepath);
-        const queueKey = `${invalidateTarget}:${compilerName}:${normalizedFilepath}`;
+        const queueKey = `${invalidateTargets.join(',')}:${compilerNames.join(',')}:${normalizedFilepath}`;
         const queuedAt = recentQueuedChanges.get(queueKey);
 
         if (queuedAt !== undefined && Date.now() - queuedAt < 250) return;
 
         recentQueuedChanges.set(queueKey, Date.now());
-        const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
 
-        changedFiles.add(normalizedFilepath);
-        pendingChanges.set(compilerName, changedFiles);
-        pendingInvalidateTargets.add(invalidateTarget);
+        for (const compilerName of compilerNames) {
+            const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
+
+            changedFiles.add(normalizedFilepath);
+            pendingChanges.set(compilerName, changedFiles);
+        }
+
+        for (const invalidateTarget of invalidateTargets) {
+            pendingInvalidateTargets.add(invalidateTarget);
+        }
 
         if (invalidateTimer) return;
         invalidateTimer = setTimeout(flushInvalidate, 40);
@@ -682,9 +735,9 @@ const createIndexedSourceWatching = ({
                 if (!watchRule.eventTypes.includes(normalizedEventType) && relativePath) return;
 
                 queueInvalidate({
-                    compilerName: watchRule.compilerName,
+                    compilerNames: watchRule.compilerNames,
                     filepath: relativePath ? path.join(rootPath, relativePath) : rootPath,
-                    invalidateTarget: watchRule.invalidateTarget,
+                    invalidateTargets: watchRule.invalidateTargets,
                 });
             }),
         );
@@ -755,7 +808,7 @@ const runDevLoop = async () => {
             // - Node modules except 5HTP core (framework dev mode)
             // - Generated files during runtime (cause infinite loop. Ex: models.d.ts)
             // - Webpack output folders (`./dev`, legacy `./bin`)
-            ignored: ignoredWatchMatcher,
+            ignored: ignoredWatchMatcher as never,
 
             //aggregateTimeout: 1000,
         },
@@ -880,6 +933,6 @@ export const run = async () => {
         return;
     }
 
-    await promptToConfigureAgentsIfMissing();
+    await ensureProjectAgentInstructions();
     await runDevLoop();
 };

package/cli/compiler/artifacts/manifest.ts

@@ -5,7 +5,6 @@ import app from '../../app';
 import cli from '../..';
 import { inspectProteumEnv } from '../../../common/env/proteumEnv';
 import { reservedRouteOptionKeys, routeOptionKeys } from '../../../common/router/pageData';
-import { getProjectInstructionGitignoreEntries } from '../../utils/agents';
 import {
     TProteumManifest,
     TProteumManifestCommand,
@@ -40,10 +39,7 @@ const collectManifestDiagnostics = ({
     routes: TProteumManifest['routes'];
 }) => {
     const diagnostics: TProteumManifestDiagnostic[] = [];
-    const expectedGitignoreEntries = [
-        ...requiredGitignoreEntries,
-        ...getProjectInstructionGitignoreEntries({ coreRoot: cli.paths.core.root }),
-    ];
+    const expectedGitignoreEntries = [...requiredGitignoreEntries];
 
     const pushDiagnostic = (diagnostic: TProteumManifestDiagnostic) => {
         diagnostics.push(diagnostic);

package/cli/presentation/commands.ts

@@ -113,22 +113,22 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure Proteum-managed instruction stubs for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
         usage: 'proteum configure agents',
         bestFor:
-            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write instruction files implicitly.',
+            'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
         examples: [
             {
-                description: 'Configure instruction stubs for the current standalone app',
+                description: 'Configure instruction files for the current standalone app',
                 command: 'proteum configure agents',
             },
         ],
         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 `AGENTS.md` stub.',
-            'Standalone mode writes the full app-root instruction set into the current Proteum app root.',
-            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and switches the current app root `AGENTS.md` to the app-root addendum.',
-            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed stub.',
-            'Declined non-managed paths are left untouched; Proteum still creates missing stubs and updates stubs or symlinks it already manages.',
+            '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 `AGENTS.md` file.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and the app-root instruction files into the current Proteum app root.',
+            '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.',
         ],
         status: 'experimental',
     },
@@ -191,7 +191,7 @@ 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.',
             '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 the interactive dev loop starts, Proteum offers to launch `proteum configure agents` when the app root is missing `AGENTS.md`.',
+            'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
             'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
             '`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.',

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/scaffold/index.ts

@@ -5,7 +5,6 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
-import { renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -656,9 +655,7 @@ const createInitFilePlans = ({ appRoot, config }: { appRoot: string; config: TSc
     },
     {
         relativePath: '.gitignore',
-        content: createGitignoreTemplate({
-            projectInstructionGitignoreBlock: renderProjectInstructionGitignoreBlock({ coreRoot: cli.paths.core.root }),
-        }),
+        content: createGitignoreTemplate(),
     },
     {
         relativePath: 'eslint.config.mjs',
@@ -727,7 +724,7 @@ export const runInitScaffold = async () => {
               ? 'Run `npm run dev` in the new app directory.'
               : 'Run `npm install`, then `npm run dev` in the new app directory.',
     );
-    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction stubs.');
+    result.nextSteps.push('Run `proteum configure agents` when you want tracked Proteum instruction files.');
     result.nextSteps.push('Use `proteum create page|controller|command|route|service ...` to add app artifacts.');
 
     printResult(result, createInitSummary(result, config));

package/cli/scaffold/templates.ts

@@ -253,11 +253,7 @@ export const createServerTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
 }
 `;
 
-export const createGitignoreTemplate = ({
-    projectInstructionGitignoreBlock,
-}: {
-    projectInstructionGitignoreBlock: string;
-}) => `node_modules
+export const createGitignoreTemplate = () => `node_modules
 /.proteum
 /.cache
 /bin
@@ -265,8 +261,6 @@ export const createGitignoreTemplate = ({
 /var
 /proteum.connected.json
 .env
-
-${projectInstructionGitignoreBlock}
 `;
 
 export const createEnvTemplate = ({ port, url }: { port: number; url: string }) => `ENV_NAME=local