proteum 2.2.7 → 2.2.9

package/AGENTS.md

@@ -31,11 +31,12 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 cd <worktree path>
 npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 ```
+- After initializing any new framework worktree, immediately boot the required reference app dev servers with the elevated-permissions workflow below. Keep those servers running across subsequent changes and validation until the user explicitly asks to stop them, or until a retry, port change, stale-session cleanup, or conflicting live session requires a controlled stop.
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise browser-visible flows with the browser MCP or use the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
 - When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `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 such as `[http://localhost:3100](http://localhost:3100)`.
 - Do not use `--replace-existing` unless you are 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.
 - When a reference app uses local `file:` connected projects for the affected flow, boot every connected producer app as well, each on its own free port and thread-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or validating the consumer app.
-- Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
+- Before retrying a boot on the same app, changing ports, handling a conflicting live session, or when the user explicitly asks to stop servers, stop the relevant framework-started dev session with `npx proteum dev stop --session-file <path>` or clean stale sessions with `npx proteum dev stop --all --stale`. Do not stop healthy framework-started dev sessions merely because the current task is finished.
 - If the task changed the dev workflow itself, verify the final cleanup path with `npx proteum dev list --json` before finishing.
 - When you have finished your work, summarize in one top-level short (up to 100 characters) sentence ALL the changes you made since the beginning of the WHOLE conversation. Strictly use the Conventional Commits specification:
   ```

package/README.md

@@ -404,7 +404,7 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
-`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.
+`proteum configure agents` embeds the full Proteum project instruction corpus into the managed `# Proteum Instructions` section of each tracked instruction file. Standalone mode writes root documents into the app root; monorepo mode writes shared root documents such as `AGENTS.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root and keeps only app-local instruction files in the Proteum app root. It preserves content outside managed sections and asks before replacing directories or foreign symlinks. If you decline, that path is left untouched.
 
 Every `proteum dev` start runs the same idempotent instruction check. It updates missing or stale managed sections automatically and prompts only when a blocked path would need to be replaced.
 

package/agents/project/AGENTS.md

@@ -63,8 +63,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### Before Finishing
 
 - 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.
-- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.
-- After implementing UI-visible changes, once the required tests or verification pass, use the browser MCP to open the changed routes or states, capture screenshots focused on the changed areas, inspect them for obvious visual defects, and include or reference those screenshots in the final response as proof of the completed UI change.
+- Run the full project `npx proteum check` before finishing each feature or change. Targeted lint, typecheck, diagnose, request, browser, or E2E runs are still useful while iterating, but they do not replace the final full check. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.`
@@ -174,13 +173,12 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface first, then escalate only if the changed surface justifies it.
+- Default: use the cheapest trustworthy verification for the changed surface first, then run the full project `npx proteum check` before finishing.
 - Route additions: boot the app and hit the real URL.
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: use the browser MCP to load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
-- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
-- UI-visible changes: after the required tests or verification, use the browser MCP to screenshot the changed areas and confirm the screenshots match the intended result.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update the relevant end-to-end coverage and finish by running the full Playwright suite plus the full project `npx proteum check`.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: use the browser MCP after request-level verification is insufficient. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - Raw browser execution outside end-to-end suites: use the browser MCP only. Keep Playwright in `npx proteum e2e --port <port>` for targeted/full end-to-end suites.
@@ -203,6 +201,7 @@ Verify at the correct layer:
 - Do not create nested `catalogs/` folders under pages, components, services, tests, or other feature folders.
 - Keep strong TypeScript typings across the project.
 - Do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
+- Do not use `Reflect.get`, bracket access, broad `in` checks, or local loose reader helpers to bypass missing typings for app-owned data; fix the type contract or normalize once with a typed adapter at the boundary.
 - Fix typing issues only on code you wrote.
 - Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 

package/agents/project/CODING_STYLE.md

@@ -8,7 +8,11 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - Write clean, consistent, readable code with a tab size of 4.
 - Keep functions and methods short.
 - Every time possible, create reusable functions and components instead of repeating.
-- Before finishing a feature or change, review touched files against this document and run the smallest relevant project lint or check command when available; coding-style regressions are defects, not optional cleanup.
+- Before finishing a feature or change, review touched files against this document and run the full project `npx proteum check`; coding-style regressions are defects, not optional cleanup.
+
+## Type safety
+
+- Do not use `Reflect.get`, bracket access, broad `in` checks, or local loose reader helpers to bypass missing typings for app-owned data; fix the type contract or normalize once with a typed adapter at the boundary.
 
 ## Formatting
 

package/agents/project/client/AGENTS.md

@@ -24,6 +24,8 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Prefer generated app surfaces over direct `.proteum` implementation imports.
 - Never depend on legacy `@app` imports on the client.
 - Errors from controller calls should never be silently swallowed. Rethrow or surface them clearly.
+- Caught frontend errors must always preserve the original failure. Never write `catch {}`, `.catch(() => ...)`, or a catch handler that only shows a generic toast/state without using the caught error.
+- Valid frontend error handling includes rethrowing the error, passing it to `Router.app.handleError(error)`, logging/reporting it with the original error, or surfacing original detail such as `error.message` in user-visible feedback.
 
 ## Design
 

package/agents/project/diagnostics.md

@@ -50,17 +50,16 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Verification And Testing
 
 - Use the cheapest trustworthy verification that matches the failing layer.
-- After implementing a change, verify only at the smallest trustworthy layer required by the changed surface. Do not default to a running app, browser MCP, project-wide typecheck, `npx proteum check`, or Playwright when a narrower static or request-level verification is enough.
+- After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, then run the full project `npx proteum check` before finishing. Do not default to a running app, browser MCP, or Playwright while iterating when a narrower static or request-level verification is enough.
 - For compile-time or type-safety issues, start with the relevant targeted typecheck or build command. Do not run them by default for unrelated runtime, copy, docs, or local refactor changes.
 - For request/runtime issues, verify through the real page, route, generated controller call, or command on a running app.
 - Start the smallest trustworthy runtime surface first: `npx proteum orient <query>`, then the relevant real URL, generated controller call, command, or `npx proteum diagnose <path> --port <port>`. Use browser MCP validation only when request-level verification is insufficient or the change is browser-visible.
 - When automated browser assertions or suite coverage are required, use `npx proteum e2e --port <port>` for targeted or full Playwright suites. Do not use direct Playwright for browser validation outside the E2E wrapper, and do not launch raw browser automation against a shared persistent profile.
 - Focused verification should treat unrelated global diagnostics as visible but non-blocking by default. Use `--strict-global` only when the task explicitly requires broad clean-room validation.
 - For browser regressions, prefer a browser MCP repro first and add targeted Playwright E2E coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when browser MCP verification is insufficient.
-- For UI-visible fixes, after the required tests or verification pass, use the browser MCP to capture focused screenshots of the changed areas and inspect them before finalizing.
 - Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, `diagnose`, and command-level checks unless browser execution is the only trustworthy reproducer.
 - Treat server startup failures, runtime errors, browser console errors or warnings, and Playwright failures as blocking unless they are clearly unrelated to the change.
-- When the touched surface can affect coding-style enforcement, run the smallest relevant static check. Do not default to `npx proteum check`; prefer a narrower lint or type check only when the changed surface or an observed issue calls for it.
+- When the touched surface can affect coding-style enforcement, run the full project `npx proteum check` before finishing. Narrower lint or type checks are useful while iterating, but they do not replace the final full check.
 - If the task started any long-lived `proteum dev` server, stop it explicitly with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`, then confirm the remaining tracked sessions with `npx proteum dev list --json`.
 - Add `data-testid` when stable selectors are missing instead of relying on brittle text or DOM-shape selectors.
 - If an isolated test misses prerequisite state, run the smallest broader scope that reproduces the real setup.

package/agents/project/root/AGENTS.md

@@ -53,8 +53,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### Before Finishing
 
 - 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.
-- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.
-- After implementing UI-visible changes, once the required tests or verification pass, use the browser MCP to open the changed routes or states, capture screenshots focused on the changed areas, inspect them for obvious visual defects, and include or reference those screenshots in the final response as proof of the completed UI change.
+- Run the full project `npx proteum check` before finishing each feature or change. Targeted lint, typecheck, diagnose, request, browser, or E2E runs are still useful while iterating, but they do not replace the final full check. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-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.`
@@ -164,13 +163,12 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface first, then escalate only if the changed surface justifies it.
+- Default: use the cheapest trustworthy verification for the changed surface first, then run the full project `npx proteum check` before finishing.
 - Route additions: boot the app and hit the real URL.
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: use the browser MCP to load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
-- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
-- UI-visible changes: after the required tests or verification, use the browser MCP to screenshot the changed areas and confirm the screenshots match the intended result.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update the relevant end-to-end coverage and finish by running the full Playwright suite plus the full project `npx proteum check`.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: use the browser MCP after request-level verification is insufficient. Use `npx proteum e2e --port <port> ...` only when automated end-to-end coverage or a Playwright suite is required.
 - Raw browser execution outside end-to-end suites: use the browser MCP only. Keep Playwright in `npx proteum e2e --port <port>` for targeted/full end-to-end suites.
@@ -193,6 +191,7 @@ Verify at the correct layer:
 - Do not create nested `catalogs/` folders under pages, components, services, tests, or other feature folders.
 - Keep strong TypeScript typings across the project.
 - Do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
+- Do not use `Reflect.get`, bracket access, broad `in` checks, or local loose reader helpers to bypass missing typings for app-owned data; fix the type contract or normalize once with a typed adapter at the boundary.
 - Fix typing issues only on code you wrote.
 - Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 

package/agents/project/tests/AGENTS.md

@@ -11,7 +11,6 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
 - After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Prefer `npx proteum e2e --port <port>` for Playwright runs so base URLs and auth tokens are passed through Proteum-managed child env instead of shell-leading environment assignments. Use a browser MCP repro against a running app during iteration when it is the fastest trustworthy loop.
-- For UI-visible feature changes, after the required Playwright run passes, use the browser MCP to capture focused screenshots of the changed areas and inspect them for visual correctness before finishing.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
 - Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
 - Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.

package/cli/commands/check.ts

@@ -19,19 +19,37 @@ export const run = async (): Promise<void> => {
 
     console.info(
         [
-            await renderTitle('PROTEUM CHECK', 'Refreshing contracts, running TypeScript, then running ESLint.'),
+            await renderTitle('PROTEUM CHECK', 'Refreshing contracts, then running TypeScript and ESLint.'),
             renderRows([{ label: 'app', value: cli.paths.appRoot === process.cwd() ? '.' : cli.paths.appRoot }]),
         ].join('\n\n'),
     );
+
     if (hasAppConfig()) {
         console.info(await renderStep('[1/3]', 'Refreshing generated typings.'));
         await refreshGeneratedTypings();
     } else {
         console.info(await renderStep('[1/3]', 'Skipping generated typings: no Proteum app config found.'));
     }
+
+    const failures: Error[] = [];
+
     console.info(await renderStep('[2/3]', 'Running TypeScript typechecking.'));
-    await runAppTypecheck();
+    try {
+        await runAppTypecheck();
+    } catch (error) {
+        failures.push(error instanceof Error ? error : new Error(String(error)));
+    }
+
     console.info(await renderStep('[3/3]', 'Running ESLint.'));
-    await runAppLint();
+    try {
+        await runAppLint();
+    } catch (error) {
+        failures.push(error instanceof Error ? error : new Error(String(error)));
+    }
+
+    if (failures.length > 0) {
+        throw new AggregateError(failures, 'Proteum check failed. See TypeScript and ESLint output above.');
+    }
+
     console.info(await renderSuccess('All checks passed.'));
 };

package/cli/commands/configure.ts

@@ -119,6 +119,7 @@ const renderConfigureResultSections = (result: TConfigureProjectAgentInstruction
     if (result.updated.length > 0) sections.push(['Updated:', ...result.updated.map((entry) => `- ${entry}`)].join('\n'));
     if (result.overwritten.length > 0)
         sections.push(['Overwritten:', ...result.overwritten.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.removed.length > 0) sections.push(['Removed:', ...result.removed.map((entry) => `- ${entry}`)].join('\n'));
     if (result.updatedGitignores.length > 0)
         sections.push(['Updated .gitignore:', ...result.updatedGitignores.map((entry) => `- ${entry}`)].join('\n'));
     if (result.blocked.length > 0)

package/cli/compiler/artifacts/controllers.ts

@@ -120,12 +120,14 @@ export const generateControllerArtifacts = async () => {
     const connectedManifestControllers: TProteumManifestController[] = [];
 
     connectedProjectContracts.forEach(({ namespace, cachedContractFilepath, contract, sourceKind, sourceValue, typeImportModuleSpecifier, typingMode }) => {
+        let connectedTypeName: string | null = null;
+
         if (typingMode === 'local-typed' && typeImportModuleSpecifier) {
-            const typeName = `ConnectedControllers_${namespace.replace(/[^A-Za-z0-9_$]+/g, '_')}`;
+            connectedTypeName = `ConnectedControllers_${namespace.replace(/[^A-Za-z0-9_$]+/g, '_')}`;
             connectedControllerTypeImports.push(
-                `import type { TConnectedControllers as ${typeName} } from ${JSON.stringify(typeImportModuleSpecifier)};`,
+                `import type { TConnectedControllers as ${connectedTypeName} } from ${JSON.stringify(typeImportModuleSpecifier)};`,
             );
-            typeTree[namespace] = JSON.stringify({ rawType: typeName });
+            typeTree[namespace] = JSON.stringify({ rawType: connectedTypeName });
         } else {
             typeTree[namespace] = JSON.stringify({ runtimeOnly: true });
         }
@@ -164,7 +166,9 @@ export const generateControllerArtifacts = async () => {
                     hasInput: controller.hasInput,
                     httpPath: controller.httpPath,
                     methodName: controller.methodName,
-                    resultType: 'unknown',
+                    resultType: connectedTypeName
+                        ? `TConnectedControllerResult<${connectedTypeName}, ${JSON.stringify(controller.clientAccessor)}>`
+                        : 'unknown',
                 }),
             );
         });
@@ -228,6 +232,28 @@ type TControllerResult<TController, TMethod extends keyof TController> =
 
 type TControllerFetcher<TController, TMethod extends keyof TController> = TFetcher<TControllerResult<TController, TMethod>>;
 
+type TConnectedFallbackValue =
+    | string
+    | number
+    | boolean
+    | null
+    | TConnectedFallbackValue[]
+    | { [key: string]: TConnectedFallbackValue | undefined };
+
+type TConnectedControllerLeaf<TControllerTree, TAccessor extends string> =
+    TAccessor extends \`${'${infer THead}.${infer TTail}'}\`
+        ? THead extends keyof TControllerTree
+            ? TConnectedControllerLeaf<TControllerTree[THead], TTail>
+            : undefined
+        : TAccessor extends keyof TControllerTree
+            ? TControllerTree[TAccessor]
+            : undefined;
+
+type TConnectedControllerResult<TControllerTree, TAccessor extends string> =
+    TConnectedControllerLeaf<TControllerTree, TAccessor> extends (...args: infer TArgs) => TFetcher<infer TResult>
+        ? Awaited<TResult>
+        : TConnectedFallbackValue;
+
 export type TControllers = ${printControllerTree(typeTree, typeLeaf)};
 
 export const createControllers = (

package/cli/compiler/artifacts/services.ts

@@ -711,6 +711,68 @@ ${classMembers.join('\n')}
     };
 };
 
+const isNamespaceImportDeclaration = (statement: ts.ImportDeclaration) =>
+    statement.importClause?.namedBindings !== undefined && ts.isNamespaceImport(statement.importClause.namedBindings);
+
+const isClientServerStubSupportStatement = (statement: ts.Statement, appClassIdentifier: string) => {
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return !new Set([
+            `${appClassIdentifier}Disks`,
+            `${appClassIdentifier}Router`,
+            `${appClassIdentifier}RouterPlugins`,
+        ]).has(statement.name.text);
+    }
+
+    return ts.isInterfaceDeclaration(statement) || ts.isModuleDeclaration(statement);
+};
+
+const createClientServerIndexDeclaration = (rootServices: TParsedService[]) => {
+    const sourceFile = createSourceFile(getAppServerEntryFilepath());
+    const appClass = getDefaultExportClassDeclaration(sourceFile);
+    const serviceTypesByRegisteredName = new Map(
+        rootServices.map((service) => [service.registeredName, `import("${service.importPath}").default`] as const),
+    );
+
+    const imports = sourceFile.statements
+        .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
+        .filter((statement) => !isNamespaceImportDeclaration(statement))
+        .map((statement) => statement.getText(sourceFile));
+    const supportStatements = sourceFile.statements
+        .slice(0, sourceFile.statements.indexOf(appClass))
+        .filter((statement) => isClientServerStubSupportStatement(statement, app.identity.identifier))
+        .map((statement) => statement.getText(sourceFile));
+    const heritageClauses = appClass.heritageClauses?.map((clause) => clause.getText(sourceFile)).join(' ');
+    const properties = appClass.members
+        .filter((member): member is ts.PropertyDeclaration => ts.isPropertyDeclaration(member))
+        .filter((member) => !isPrivateOrProtectedInstanceMember(member))
+        .map((property) => {
+            const propertyName = getPropertyNameText(property.name);
+            if (!propertyName) return undefined;
+
+            const propertyType =
+                propertyName === 'Disks'
+                    ? 'object'
+                    : propertyName === 'Router'
+                      ? `${app.identity.identifier}Router`
+                      : property.type?.getText(sourceFile) || serviceTypesByRegisteredName.get(propertyName);
+            if (!propertyType) return undefined;
+
+            return `    public ${propertyName}: ${propertyType};`;
+        })
+        .filter((property): property is string => property !== undefined);
+
+    return `${imports.join('\n')}
+
+${supportStatements.join('\n\n')}
+
+type ${app.identity.identifier}Router = Router<${app.identity.identifier}>;
+
+export default class ${app.identity.identifier}${heritageClauses ? ` ${heritageClauses}` : ''} {
+${properties.join('\n')}
+}
+`;
+};
+
 const resolveManifestService = (service: TParsedService, parent: string): TProteumManifestService => ({
     kind: 'service',
     registeredName: service.registeredName,
@@ -730,6 +792,11 @@ export const generateServiceArtifacts = () => {
     const routerPluginServices = routerPlugins.map((service) => resolveManifestService(service, 'Router.plugins'));
     const commandServiceStubs = createCommandServiceStubDeclarations(rootServices);
 
+    writeIfChanged(
+        path.join(app.paths.client.generated, 'server-index.d.ts'),
+        createClientServerIndexDeclaration(rootServices),
+    );
+
     writeIfChanged(
         path.join(app.paths.client.generated, 'services.d.ts'),
         `declare type ${appClassIdentifier} = import("@/server/index").default;
@@ -737,18 +804,9 @@ export const generateServiceArtifacts = () => {
 declare module "@app" {
 
     import { ${appClassIdentifier} as ${appClassIdentifier}Client } from "@/client";
-    import ${appClassIdentifier}Server from "@/server/index";
   
     export const Router: ${appClassIdentifier}Client['Router'];
 
-    ${rootServices
-        .map((service) =>
-            service.registeredName !== 'Router'
-                ? `export const ${service.registeredName}: ${appClassIdentifier}Server["${service.registeredName}"];`
-                : '',
-        )
-        .join('\n')}
-
 }
     
 declare module '@models/types' {
@@ -894,26 +952,6 @@ declare module "@app" {
     export = ServerServices
 }
 
-declare module '@server/app' {
-
-    import { Application } from "@server/app";
-    import { Environment } from "@server/app";
-    import { ServicesContainer } from "@server/app/service/container";
-
-    abstract class ApplicationWithServices extends Application<
-        ServicesContainer<InstalledServices>
-    > {}
-
-    export interface Exported {
-        Application: typeof ApplicationWithServices,
-        Environment: Environment,
-    }
-
-    const foo: Exported;
-
-    export = foo;
-}
-
 declare module '@common/errors' {
         
     export * from '@common/errors/index';

package/cli/presentation/commands.ts

@@ -124,9 +124,9 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
-            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` file.',
+            '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.',
-            '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.',
+            'Monorepo mode writes reusable root documents such as `AGENTS.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],

package/cli/scaffold/templates.ts

@@ -191,6 +191,7 @@ export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
             "@server/*": [${JSON.stringify(paths.frameworkServer)}],
 
             "@/client/context": ["./.proteum/client/context.ts"],
+            "@/server/index": ["./.proteum/client/server-index.d.ts"],
             "@generated/client/*": ["./.proteum/client/*"],
             "@generated/common/*": ["./.proteum/common/*"],
             "@generated/server/*": ["./.proteum/server/*"],
@@ -207,8 +208,7 @@ export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
         ".",
         "../var/typings",
         ${JSON.stringify(paths.frameworkTypesGlobal)},
-        "../.proteum/client/services.d.ts",
-        "../server/index.ts"
+        "../.proteum/client/services.d.ts"
     ]
 }
 `;
@@ -228,7 +228,6 @@ export const createServerTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
             "@common/*": [${JSON.stringify(paths.frameworkCommon)}],
             "@server/*": [${JSON.stringify(paths.frameworkServer)}],
 
-            "@/client/context": ["./.proteum/client/context.ts"],
             "@generated/client/*": ["./.proteum/client/*"],
             "@generated/common/*": ["./.proteum/common/*"],
             "@generated/server/*": ["./.proteum/server/*"],

package/cli/utils/agents.ts

@@ -29,6 +29,7 @@ type TEnsureInstructionFilesResult = {
     blocked: string[];
     created: string[];
     overwritten: string[];
+    removed: string[];
     skipped: string[];
     updated: string[];
 };
@@ -40,6 +41,7 @@ export type TConfigureProjectAgentInstructionsResult = {
     monorepoRoot?: string;
     mode: 'monorepo' | 'standalone';
     overwritten: string[];
+    removed: string[];
     skipped: string[];
     updated: string[];
     updatedGitignores: string[];
@@ -57,10 +59,13 @@ const managedInstructionSectionStart = '<!-- proteum-instructions:start -->';
 const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
 
-const sharedAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'CODING_STYLE.md' },
     { projectPath: 'diagnostics.md' },
     { projectPath: 'optimizations.md' },
+];
+
+const sharedAreaAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: path.join('client', 'AGENTS.md') },
     { projectPath: path.join('client', 'pages', 'AGENTS.md') },
     { projectPath: path.join('server', 'services', 'AGENTS.md') },
@@ -70,16 +75,18 @@ const sharedAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
 
 const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md' },
-    ...sharedAppAgentInstructionDefinitions,
+    ...sharedRootDocumentInstructionDefinitions,
+    ...sharedAreaAgentInstructionDefinitions,
 ];
 
 const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md' },
-    ...sharedAppAgentInstructionDefinitions,
+    ...sharedAreaAgentInstructionDefinitions,
 ];
 
 const monorepoRootAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md' },
+    ...sharedRootDocumentInstructionDefinitions,
 ];
 
 const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
@@ -111,6 +118,7 @@ export function configureProjectAgentInstructions({
         created: [],
         mode,
         overwritten: [],
+        removed: [],
         skipped: [],
         updated: [],
         updatedGitignores: [],
@@ -152,7 +160,29 @@ export function configureProjectAgentInstructions({
     );
     mergeInstructionResults(result, appFiles, normalizedAppRoot);
 
-    if (!dryRun && removeInstructionGitignoreEntries({ rootDir: normalizedAppRoot, instructionDefinitions: appInstructions }))
+    if (mode === 'monorepo') {
+        const retiredAppRootFiles = removeManagedInstructionFiles(
+            normalizedAppRoot,
+            sharedRootDocumentInstructionDefinitions,
+            '[agents]',
+            path.join(coreRoot, 'agents', 'project'),
+            {
+                dryRun,
+            },
+        );
+        mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
+    }
+
+    const appGitignoreCleanupInstructions =
+        mode === 'monorepo' ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions] : appInstructions;
+
+    if (
+        !dryRun &&
+        removeInstructionGitignoreEntries({
+            rootDir: normalizedAppRoot,
+            instructionDefinitions: appGitignoreCleanupInstructions,
+        })
+    )
         result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
 
     return result;
@@ -253,6 +283,7 @@ function ensureInstructionFiles(
         blocked: [],
         created: [],
         overwritten: [],
+        removed: [],
         skipped: [],
         updated: [],
     };
@@ -320,6 +351,74 @@ function ensureInstructionFiles(
     return result;
 }
 
+function removeManagedInstructionFiles(
+    rootDir: string,
+    instructionDefinitions: TAgentInstructionDefinition[],
+    logPrefix: string,
+    managedSourceRoot: string,
+    {
+        dryRun,
+    }: {
+        dryRun: boolean;
+    },
+): TEnsureInstructionFilesResult {
+    const result: TEnsureInstructionFilesResult = {
+        blocked: [],
+        created: [],
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+    };
+
+    for (const instructionDefinition of instructionDefinitions) {
+        const projectFilepath = path.join(rootDir, instructionDefinition.projectPath);
+        const projectParentDir = path.dirname(projectFilepath);
+        const relativeProjectPath = path.relative(rootDir, projectFilepath) || '.';
+
+        if (!fs.existsSync(projectParentDir)) continue;
+
+        const existingState = inspectExistingPath({
+            managedSourceRoot,
+            projectFilepath,
+        });
+
+        if (existingState.kind === 'missing') continue;
+
+        if (existingState.kind === 'managed-different') {
+            if (!dryRun) fs.removeSync(projectFilepath);
+            result.removed.push(relativeProjectPath);
+            logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+            continue;
+        }
+
+        if (existingState.kind === 'file') {
+            const retainedContent = removeManagedInstructionContent(existingState.content);
+
+            if (retainedContent === undefined) {
+                result.skipped.push(relativeProjectPath);
+                continue;
+            }
+
+            if (retainedContent.trim() === '') {
+                if (!dryRun) fs.removeSync(projectFilepath);
+                result.removed.push(relativeProjectPath);
+                logVerbose(`${logPrefix} Removed retired app-root ${relativeProjectPath}`);
+                continue;
+            }
+
+            if (!dryRun) fs.writeFileSync(projectFilepath, retainedContent);
+            result.updated.push(relativeProjectPath);
+            logVerbose(`${logPrefix} Removed retired managed section from ${relativeProjectPath}`);
+            continue;
+        }
+
+        result.skipped.push(relativeProjectPath);
+    }
+
+    return result;
+}
+
 function inspectExistingPath({
     managedSourceRoot,
     projectFilepath,
@@ -377,6 +476,7 @@ function mergeInstructionResults(
 ) {
     result.created.push(...next.created.map((entry) => formatResultPath(rootDir, entry)));
     result.overwritten.push(...next.overwritten.map((entry) => formatResultPath(rootDir, entry)));
+    result.removed.push(...next.removed.map((entry) => formatResultPath(rootDir, entry)));
     result.updated.push(...next.updated.map((entry) => formatResultPath(rootDir, entry)));
     result.skipped.push(...next.skipped.map((entry) => formatResultPath(rootDir, entry)));
     result.blocked.push(...next.blocked.map((entry) => formatResultPath(rootDir, entry)));
@@ -472,6 +572,16 @@ function upsertManagedInstructionSection(content: string, managedSectionContent:
     return joinMarkdownSections([before, managedSectionContent, after]);
 }
 
+function removeManagedInstructionContent(content: string) {
+    const managedRange = findManagedInstructionSectionRange(content) || findLegacyManagedInstructionStubRange(content);
+    if (!managedRange) return undefined;
+
+    const before = content.slice(0, managedRange.start);
+    const after = content.slice(managedRange.end);
+
+    return joinMarkdownSections([before, after]);
+}
+
 function findManagedInstructionSectionRange(content: string) {
     const markerStartIndex = content.indexOf(managedInstructionSectionStart);
     if (markerStartIndex === -1) return undefined;