proteum 2.2.1 → 2.2.2

package/AGENTS.md

@@ -43,7 +43,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
   [optional body]
   ```
-  If the user replies exactly `commit`, use that Conventional Commit message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, then create the commit by running `git commit`.
+  If the user replies exactly `commit`, treat it as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation. In each affected repository or worktree, stage all conversation-related changed files with `git add` while still excluding unrelated pre-existing user changes or incidental untracked files, then create one `git commit`. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work.
   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.`
 
@@ -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.
+- 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.
 - 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

@@ -360,7 +360,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.
+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.
 
 Useful inspection commands:
 
@@ -404,6 +404,8 @@ 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.
 
+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.
+
 `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).
 
 ## Dev Commands

package/agents/project/AGENTS.md

@@ -40,7 +40,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
   [optional body]
   ```
-  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  Then treat `commit` as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the 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.`
 
@@ -57,7 +57,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 raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
-- 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.
+- 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.
 
 ### Before Finishing
 
@@ -222,7 +222,7 @@ Verify at the correct layer:
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
-- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows only task-scoped `git add` and `git commit`. Any other write-mode git action requires an explicit user request.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.
 
 ## Appendix
 

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.
+  - 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.
 - 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

@@ -14,7 +14,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.
+- 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.
 - 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 `npx proteum verify browser <path>` or targeted Playwright when the bug is browser-visible.

package/agents/project/root/AGENTS.md

@@ -30,7 +30,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
   [optional body]
   ```
-  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  Then treat `commit` as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched during that span, stage all conversation-related changed files in each affected repository or worktree with `git add` while still avoiding unrelated pre-existing user changes or incidental untracked files, and create one `git commit` per affected repository or worktree. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work. Do not stop at only suggesting the 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.`
 
@@ -47,7 +47,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 raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
-- 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.
+- 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.
 
 ### Before Finishing
 
@@ -212,7 +212,7 @@ Verify at the correct layer:
 - Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
 - Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
 - Do not run `git restore` or `git reset`.
-- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows only task-scoped `git add` and `git commit`. Any other write-mode git action requires an explicit user request.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows `git add` and `git commit` in every affected repository or worktree touched during the whole conversation. Any other write-mode git action requires an explicit user request.
 
 ## Appendix
 

package/cli/commands/configure.ts

@@ -155,7 +155,16 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksRes
 export const run = async (): Promise<void> => {
     if (cli.args.action !== 'agents') throw new UsageError('Usage: `proteum configure agents`');
 
-    const appRoot = resolveCanonicalPath(cli.paths.appRoot);
+    await runConfigureAgentsWizard();
+};
+
+export const runConfigureAgentsWizard = async ({
+    appRoot = resolveCanonicalPath(cli.paths.appRoot),
+    coreRoot = cli.paths.core.root,
+}: {
+    appRoot?: string;
+    coreRoot?: string;
+} = {}) => {
     assertProteumAppRoot(appRoot);
 
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -197,7 +206,7 @@ export const run = async (): Promise<void> => {
 
     const preview = configureProjectAgentSymlinks({
         appRoot,
-        coreRoot: cli.paths.core.root,
+        coreRoot,
         dryRun: true,
         monorepoRoot,
     });
@@ -214,7 +223,7 @@ export const run = async (): Promise<void> => {
 
     const result = configureProjectAgentSymlinks({
         appRoot,
-        coreRoot: cli.paths.core.root,
+        coreRoot,
         monorepoRoot,
         overwriteBlockedPaths,
     });

package/cli/commands/dev.ts

@@ -7,6 +7,8 @@ import path from 'path';
 import { spawn, ChildProcess } from 'child_process';
 import fs from 'fs-extra';
 import type { FSWatcher } from 'fs';
+import prompts from 'prompts';
+import { UsageError } from 'clipanion';
 
 // Cor elibs
 import cli from '..';
@@ -20,9 +22,11 @@ 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';
+import { renderWarning } from '../presentation/ink';
 import {
     createDevSessionRecord,
     inspectDevSessionFile,
@@ -37,6 +41,8 @@ import {
 } from '../runtime/devSessions';
 import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
+import { inspectProjectAgentFiles } from '../utils/agents';
+import { runConfigureAgentsWizard } from './configure';
 
 // Core
 import { app, App } from '../app';
@@ -138,6 +144,45 @@ 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;
+
+    console.info(await renderWarning('Proteum could not find the app-root `AGENTS.md` instruction file.'));
+    console.info(
+        [
+            'Missing standard AGENTS files:',
+            ...inspection.missing.map((entry) => `- ${entry}`),
+            '',
+            'Run `proteum configure agents` now before starting the dev server?',
+        ].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`.');
+            },
+        },
+    );
+
+    if (response.value !== true) return;
+
+    await runConfigureAgentsWizard({
+        appRoot: app.paths.root,
+        coreRoot: cli.paths.core.root,
+    });
+};
+
 const getDevAppName = (app: App) =>
     app.identity.web?.fullTitle || app.identity.web?.title || app.identity.name || app.packageJson.name || app.paths.root;
 
@@ -481,10 +526,66 @@ function normalizeWatchPath(watchPath: string) {
     return path.resolve(watchPath).replace(/\\/g, '/').replace(/\/$/, '');
 }
 
-const indexedSourceWatchRules: { compilerName: 'server'; root: () => string; relativePathPattern: RegExp }[] = [
-    { compilerName: 'server', root: () => app.paths.root, relativePathPattern: /^commands(?:\/|$)/ },
-    { compilerName: 'server', root: () => cli.paths.core.root, relativePathPattern: /^commands(?:\/|$)/ },
-];
+type TIndexedSourceWatchEvent = 'change' | 'rename';
+type TIndexedSourceWatchCompilerName = 'server' | 'client';
+type TIndexedSourceWatchInvalidateTarget = 'all' | TIndexedSourceWatchCompilerName;
+type TIndexedSourceWatchRule = {
+    compilerName: TIndexedSourceWatchCompilerName;
+    rootPath: string;
+    relativePathPattern: RegExp;
+    eventTypes: TIndexedSourceWatchEvent[];
+    invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+};
+type TNamedWatching = { compiler: { name?: string }; invalidate: () => void };
+type TMultiWatchingLike = TDevWatching & { watchings?: TNamedWatching[] };
+
+const resolveIndexedSourceWatchRules = (): TIndexedSourceWatchRule[] => {
+    const transpileWatchRoots = app.transpileModuleDirectories
+        .map((rootPath) => {
+            try {
+                return fs.realpathSync(rootPath);
+            } catch {
+                return rootPath;
+            }
+        })
+        .map(normalizeWatchPath)
+        .filter((rootPath, index, list) => list.indexOf(rootPath) === index);
+
+    return [
+        {
+            compilerName: 'server',
+            rootPath: app.paths.root,
+            relativePathPattern: /^commands(?:\/|$)/,
+            eventTypes: ['rename'],
+            invalidateTarget: 'all',
+        },
+        {
+            compilerName: 'server',
+            rootPath: cli.paths.core.root,
+            relativePathPattern: /^commands(?:\/|$)/,
+            eventTypes: ['rename'],
+            invalidateTarget: 'all',
+        },
+        ...transpileWatchRoots.map(
+            (rootPath): TIndexedSourceWatchRule => ({
+                compilerName: 'server',
+                rootPath,
+                relativePathPattern: regex.scripts,
+                eventTypes: ['change', 'rename'],
+                invalidateTarget: 'server',
+            }),
+        ),
+    ];
+};
+
+const findCompilerWatching = (
+    watching: TDevWatching,
+    compilerName: TIndexedSourceWatchCompilerName,
+): TNamedWatching | undefined => {
+    const childWatchings = (watching as TMultiWatchingLike).watchings;
+
+    return childWatchings?.find((childWatching) => childWatching.compiler.name === compilerName);
+};
 
 const closeFsWatcher = async (watcher: FSWatcher) => {
     await new Promise<void>((resolve) => {
@@ -501,7 +602,9 @@ const createIndexedSourceWatching = ({
     watching: TDevWatching;
 }): TIndexedSourceWatching => {
     const watchers: FSWatcher[] = [];
-    const pendingChanges = new Map<'server', Set<string>>();
+    const pendingChanges = new Map<TIndexedSourceWatchCompilerName, Set<string>>();
+    const pendingInvalidateTargets = new Set<TIndexedSourceWatchInvalidateTarget>();
+    const recentQueuedChanges = new Map<string, number>();
     let invalidateTimer: NodeJS.Timeout | undefined;
 
     const flushInvalidate = () => {
@@ -512,31 +615,77 @@ const createIndexedSourceWatching = ({
         }
 
         pendingChanges.clear();
-        logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
-        watching.invalidate();
+
+        if (pendingInvalidateTargets.has('all')) {
+            pendingInvalidateTargets.clear();
+            logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+            watching.invalidate();
+            return;
+        }
+
+        const invalidateTargets = [...pendingInvalidateTargets].filter(
+            (invalidateTarget): invalidateTarget is TIndexedSourceWatchCompilerName => invalidateTarget !== 'all',
+        );
+        pendingInvalidateTargets.clear();
+
+        if (invalidateTargets.length === 0) return;
+
+        logVerbose('Transpiled source files changed. Invalidating the server compiler to refresh mutable package code.');
+        for (const invalidateTarget of invalidateTargets) {
+            const compilerWatching = findCompilerWatching(watching, invalidateTarget);
+
+            if (!compilerWatching) {
+                watching.invalidate();
+                return;
+            }
+
+            compilerWatching.invalidate();
+        }
     };
 
-    const queueInvalidate = (compilerName: 'server', filepath: string) => {
+    const queueInvalidate = ({
+        compilerName,
+        filepath,
+        invalidateTarget,
+    }: {
+        compilerName: TIndexedSourceWatchCompilerName;
+        filepath: string;
+        invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+    }) => {
         const normalizedFilepath = normalizeWatchPath(filepath);
+        const queueKey = `${invalidateTarget}:${compilerName}:${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);
 
         if (invalidateTimer) return;
         invalidateTimer = setTimeout(flushInvalidate, 40);
     };
 
-    for (const watchRule of indexedSourceWatchRules) {
-        const rootPath = watchRule.root();
+    for (const watchRule of resolveIndexedSourceWatchRules()) {
+        const rootPath = watchRule.rootPath;
+        if (!fs.existsSync(rootPath)) continue;
 
         watchers.push(
             fs.watch(rootPath, { recursive: true }, (eventType, filename) => {
                 const relativePath = typeof filename === 'string' ? filename.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+                const normalizedEventType: TIndexedSourceWatchEvent = eventType === 'change' ? 'change' : 'rename';
+
                 if (relativePath && !watchRule.relativePathPattern.test(relativePath)) return;
-                if (eventType !== 'rename' && relativePath) return;
+                if (!watchRule.eventTypes.includes(normalizedEventType) && relativePath) return;
 
-                queueInvalidate(watchRule.compilerName, relativePath ? path.join(rootPath, relativePath) : rootPath);
+                queueInvalidate({
+                    compilerName: watchRule.compilerName,
+                    filepath: relativePath ? path.join(rootPath, relativePath) : rootPath,
+                    invalidateTarget: watchRule.invalidateTarget,
+                });
             }),
         );
     }
@@ -731,5 +880,6 @@ export const run = async () => {
         return;
     }
 
+    await promptToConfigureAgentsIfMissing();
     await runDevLoop();
 };

package/cli/compiler/common/index.ts

@@ -45,6 +45,15 @@ export default function createCommonConfig(
 ): Configuration {
     const dev = mode === 'dev';
     const enableFilesystemCache = dev ? cli.args.cache !== false : cli.args.cache === true;
+    const transpileModuleDirectories = app.transpileModuleDirectories;
+    const transpileModuleSnapshot =
+        dev && transpileModuleDirectories.length > 0
+            ? {
+                  // Transpiled local packages can resolve through node_modules symlinks,
+                  // but they still need live invalidation like mutable app sources in dev.
+                  unmanagedPaths: transpileModuleDirectories,
+              }
+            : undefined;
     const frameworkPackageRoots = [cli.paths.framework.installedRoot, cli.paths.framework.activeRoot].filter(
         (rootPath, index, list): rootPath is string => typeof rootPath === 'string' && list.indexOf(rootPath) === index,
     );
@@ -109,6 +118,8 @@ export default function createCommonConfig(
             ]*/
         },
 
+        ...(transpileModuleSnapshot ? { snapshot: transpileModuleSnapshot } : {}),
+
         // Turn off performance processing because we utilize
         // our own hints via the FileSizeReporter
         performance: false,
@@ -123,6 +134,11 @@ export default function createCommonConfig(
                   cacheDirectory: path.join(app.paths.cache, 'rspack', side, mode),
                   compression: false,
                   buildDependencies: { config: [__filename] },
+                  ...(transpileModuleSnapshot
+                      ? {
+                            snapshot: transpileModuleSnapshot,
+                        }
+                      : {}),
               }
             : false,
 

package/cli/presentation/commands.ts

@@ -190,6 +190,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`.',
             '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,6 +139,10 @@ 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.', {
+                    indent: '  ',
+                    nextIndent: '  ',
+                }),
                 wrapText('Legacy single-dash flags and positional booleans remain accepted for older app scripts, but new docs should prefer modern long flags.', {
                     indent: '  ',
                     nextIndent: '  ',

package/cli/utils/agents.ts

@@ -42,6 +42,11 @@ export type TConfigureProjectAgentSymlinksResult = {
     updatedGitignores: string[];
 };
 
+export type TProjectAgentFileInspection = {
+    existing: string[];
+    missing: string[];
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -147,6 +152,37 @@ export function renderProjectInstructionGitignoreBlock({ coreRoot }: TProjectIns
     return renderInstructionGitignoreBlock({ linkDefinitions: getAppAgentLinkDefinitions({ coreRoot, mode: 'standalone' }) });
 }
 
+export function inspectProjectAgentFiles({ appRoot }: { appRoot: string }): TProjectAgentFileInspection {
+    const normalizedAppRoot = path.resolve(appRoot);
+    const expectedAgentPaths = Array.from(
+        new Set(
+            standaloneAppAgentLinkDefinitions
+                .map((linkDefinition) => linkDefinition.projectPath)
+                .filter((projectPath) => projectPath.endsWith('AGENTS.md')),
+        ),
+    );
+    const result: TProjectAgentFileInspection = {
+        existing: [],
+        missing: [],
+    };
+
+    for (const projectPath of expectedAgentPaths) {
+        const absolutePath = path.join(normalizedAppRoot, projectPath);
+        const parentPath = path.dirname(absolutePath);
+
+        if (projectPath !== 'AGENTS.md' && !fs.existsSync(parentPath)) continue;
+
+        if (fs.existsSync(absolutePath)) {
+            result.existing.push(projectPath);
+            continue;
+        }
+
+        result.missing.push(projectPath);
+    }
+
+    return result;
+}
+
 /*----------------------------------
 - HELPERS
 ----------------------------------*/

package/package.json

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