proteum 2.5.0 → 2.5.2

package/AGENTS.md

@@ -46,8 +46,8 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
   [optional body]
   ```
   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.`
+  When the user asks to push, explain the currently unpushed commits in short, minimalistic bullet points in plain language, like you would do to your grandma. Start each bullet with a verb in the past.
+  When an optional commit body is useful, write it as a short, minimalistic bullet list explaining what changed in this thread in plain language, like you would do to your grandma. Start each bullet with a verb in the past. Do not print a separate prompt asking for that explanation.
 
 ## Core Changes
 

package/README.md

@@ -140,7 +140,7 @@ Use this for linked or workspace-local TypeScript packages that ship source file
 
 ## Example: Server Bootstrap
 
-Proteum app services are declared explicitly through typed config exports plus a concrete `Application` subclass.
+Proteum app services and router plugins are declared explicitly through typed config exports plus a default-exported `defineApplication(...)` definition object.
 
 ```ts
 // server/config/user.ts
@@ -167,27 +167,47 @@ export const routerBaseConfig = {
 
 ```ts
 // server/index.ts
-import { defineApplication } from '@server/app';
+import { defineApplication, type Application } from '@server/app';
 import Router from '@server/services/router';
 import SchemaRouter from '@server/services/schema/router';
 import Users from '@/server/services/Users';
 import * as userConfig from '@/server/config/user';
 
-export default defineApplication({
-  services: (app) => ({
-    Users: new Users(app, userConfig.usersConfig, app),
-    Router: new Router(
-      app,
-      {
-        ...userConfig.routerBaseConfig,
-        plugins: {
-          schema: new SchemaRouter({}, app),
-        },
+type MyAppServices = {
+  Users: Users;
+};
+
+type MyRouterPlugins = {
+  schema: SchemaRouter;
+};
+
+export type MyRouter = Router<MyApp, MyRouterPlugins>;
+export interface MyApp extends Application, MyAppServices {
+  Router: MyRouter;
+}
+
+const createRouter = (app: MyApp): MyRouter =>
+  new Router<MyApp, MyRouterPlugins>(
+    app,
+    {
+      ...userConfig.routerBaseConfig,
+      plugins: {
+        schema: new SchemaRouter({}, app),
       },
-      app
-    ),
-  }),
+    },
+    app
+  );
+
+const createServices = (app: MyApp): MyAppServices => ({
+  Users: new Users(app, userConfig.usersConfig, app),
+});
+
+const MyApplication = defineApplication({
+  services: createServices,
+  router: createRouter,
 });
+
+export default MyApplication;
 ```
 
 Proteum reads `server/index.ts` as the source of truth for installed root services and router plugins, and reads `server/config/*.ts` `Services.config(...)` exports for typed config such as service priority overrides.
@@ -233,7 +253,7 @@ Default public asset validators depend on the environment: dev disables `ETag` a
 Proteum pages are explicit SSR entrypoints.
 
 ```tsx
-import { definePageRoute } from '@common/router';
+import { definePageRoute } from '@common/router/definitions';
 
 export default definePageRoute({
   path: '/',
@@ -263,7 +283,7 @@ What happens here:
 Proteum controllers are explicit request entrypoints.
 
 ```ts
-import { defineAction, defineController, schema } from '@server/app/controller';
+import { defineAction, defineController, schema } from '@generated/server/controller';
 
 export default defineController({
   path: 'Auth',
@@ -381,7 +401,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum command` | Run a dev-only internal command locally or against a running dev server |
 | `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
 | `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 verify` | Validate targeted changed-file checks, focused owner/request/browser workflows, or the full framework reference-app pass |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
 | `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 |
@@ -393,6 +413,7 @@ Recommended daily workflow:
 proteum dev
 proteum refresh
 proteum check
+proteum verify changed --dry-run
 proteum build --prod
 proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
@@ -653,6 +674,12 @@ npx proteum check
 npx proteum build --prod
 ```
 
+## Migrating To 2.5
+
+Proteum 2.5 removes the old contextual route/controller magic. Apps migrate by replacing ambient `@app` imports, top-level `Router.*(...)` route calls, controller classes, and `Application` subclasses with explicit definition objects and typed runtime callback parameters.
+
+Use [the 2.5 migration guide](docs/migration-2.5.md) for the full checklist.
+
 ## Repository Structure
 
 This repository is organized around the same explicit framework surface it exposes:
@@ -661,7 +688,7 @@ This repository is organized around the same explicit framework surface it expos
 - `client/`: client runtime, page registration, islands, and router behavior
 - `server/`: controller base classes, services, runtime, and SSR server behavior
 - `common/`: shared router contracts, models, request/response types, and utilities
-- `doc/`: focused design notes and internal documentation
+- `docs/`: focused design notes and internal documentation
 - `agents/`: agent-specific conventions and scaffolding used in Proteum-based projects
 
 ## Status

package/agents/project/AGENTS.md

@@ -80,7 +80,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
-- Run targeted tests and checks that match the changed surface before finishing each feature or change. Continue running tests after changes, but do not run coverage by default. Reserve the non-coverage commit gate for commit workflows, and reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
+- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Reserve the non-coverage commit gate for commit workflows, and reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -161,10 +161,12 @@ const createProjectRouter = (app: ProjectApp): ProjectRouter =>
         app,
     );
 
-const ProjectApplication = defineApplication<ProjectServices, ProjectRouter>({
-    services: (app) => ({
-        Billing: new BillingService(app, {}, app),
-    }),
+const createProjectServices = (app: ProjectApp): ProjectServices => ({
+    Billing: new BillingService(app, {}, app),
+});
+
+const ProjectApplication = defineApplication({
+    services: createProjectServices,
     router: createProjectRouter,
 });
 
@@ -190,7 +192,7 @@ export default ProjectApplication;
 - Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
 
 ```ts
-import { defineAction, defineController, schema } from '@server/app/controller';
+import { defineAction, defineController, schema } from '@generated/server/controller';
 
 export default defineController({
     path: 'Billing',
@@ -271,7 +273,7 @@ export default defineServerRoute({
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface, including targeted tests for changed behavior. Do not run coverage by default during ordinary change closeout.
+- Default: use the cheapest trustworthy verification for the changed surface, including targeted tests for changed behavior. When `proteum.verify.config.ts` exists, start with `npx proteum verify changed`. Do not run coverage by default during ordinary change closeout.
 - 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.

package/agents/project/CODING_STYLE.md

@@ -8,7 +8,7 @@ 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 targeted lint/typecheck/tests for the changed surface. Do not run coverage by default after ordinary changes. Run the repository's non-coverage commit gate before committing, and run the full `npm run check` gate before pushing or when the user explicitly asks for it; coding-style regressions are defects, not optional cleanup.
+- Before finishing a feature or change, review touched files against this document and run targeted lint/typecheck/tests for the changed surface. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass. Do not run coverage by default after ordinary changes. Run the repository's non-coverage commit gate before committing, and run the full `npm run check` gate before pushing or when the user explicitly asks for it; coding-style regressions are defects, not optional cleanup.
 
 ## Type safety
 

package/agents/project/client/AGENTS.md

@@ -25,7 +25,11 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - 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 `useContext().app.handleError(error)` or `context.app.handleError(error)`, logging/reporting it with the original error, or surfacing original detail such as `error.message` in user-visible feedback.
+- Valid terminal frontend error handling is `throw error`, `useContext().app.handleError(error)`, or `context.app.handleError(error)`.
+- Do not normalize caught values in app code before calling `handleError`; the app handles `unknown` values and returns a displayable message.
+- If the app customizes `handleError`, keep the signature `handleError(error: unknown, fallbackMessage?: string): string`.
+- Toasts and form errors are local feedback only; use `setError(context.app.handleError(error, fallbackMessage))` or rethrow the caught error.
+- `console.*(error)` is not error handling and must not be the last stop for a caught error.
 
 ## Design
 

package/agents/project/diagnostics.md

@@ -55,7 +55,7 @@ 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 at the smallest trustworthy layer required by the changed surface first, including targeted tests when behavior changed. Do not run coverage by default, and do not default to a running app, browser MCP, or Playwright while iterating 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, including targeted tests when behavior changed. When the project defines `proteum.verify.config.ts`, prefer `npx proteum verify changed` for the first post-edit verification plan. Do not run coverage by default, and 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: MCP `workflow_start`, then MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, or MCP `explain_summary { projectId, query }` only when more owner detail is needed. If runtime health is unreachable, repair/start dev before any diagnose, trace, or perf read. Once runtime is reachable, use the relevant real URL, generated controller call, command, or MCP `diagnose { projectId, path }`. Use CLI equivalents only when MCP is unavailable or terminal evidence is required. Use browser MCP validation only when request-level verification is insufficient or the change is browser-visible.

package/agents/project/root/AGENTS.md

@@ -66,7 +66,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Before finishing a production code change, re-check root-level `DOCUMENTATION.md` update rules. If behavior changed, a bug was fixed, a decision changed, or an important route, auth/OAuth, or integration issue was addressed, update the relevant docs before committing or explicitly explain why no docs update was needed.
 - For production changes, always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Do not run coverage after every ordinary change by default. Reserve whole-project coverage for the repository's full `npm run check` gate during push workflows or when the user explicitly requests it; do not run coverage for commit-only workflows by default. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
-- Run targeted tests and checks that match the changed surface before finishing each feature or change. Continue running tests after changes, but do not run coverage by default. Reserve the non-coverage commit gate for commit workflows, and reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
+- Run targeted tests and checks that match the changed surface before finishing each feature or change. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Reserve the non-coverage commit gate for commit workflows, and reserve the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate. After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage and run the cheapest trustworthy Playwright or browser verification for that behavior before finishing. For docs-only, wording-only, type-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -147,10 +147,12 @@ const createProjectRouter = (app: ProjectApp): ProjectRouter =>
         app,
     );
 
-const ProjectApplication = defineApplication<ProjectServices, ProjectRouter>({
-    services: (app) => ({
-        Billing: new BillingService(app, {}, app),
-    }),
+const createProjectServices = (app: ProjectApp): ProjectServices => ({
+    Billing: new BillingService(app, {}, app),
+});
+
+const ProjectApplication = defineApplication({
+    services: createProjectServices,
     router: createProjectRouter,
 });
 
@@ -176,7 +178,7 @@ export default ProjectApplication;
 - Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
 
 ```ts
-import { defineAction, defineController, schema } from '@server/app/controller';
+import { defineAction, defineController, schema } from '@generated/server/controller';
 
 export default defineController({
     path: 'Billing',
@@ -257,7 +259,7 @@ export default defineServerRoute({
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface, including targeted tests for changed behavior. Do not run coverage by default during ordinary change closeout.
+- Default: use the cheapest trustworthy verification for the changed surface, including targeted tests for changed behavior. When `proteum.verify.config.ts` exists, start with `npx proteum verify changed`. Do not run coverage by default during ordinary change closeout.
 - 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.

package/agents/project/server/services/AGENTS.md

@@ -38,3 +38,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Never silence caught errors.
 - If you need to wrap a failure, preserve enough detail and the original error.
+- Prefer `throw error` when the current request or job should fail.
+- For catch-and-continue server work, detached promises, custom Express responses, or background jobs, call `await this.app.reportError(error, request)` when a request is available, or `await this.app.reportError(error)` without one.
+- Do not call `app.runHook('error', ...)` directly from app code; route caught errors through `app.reportError(...)` so HTTP-specific error hooks stay centralized.
+- `console.*(error)` is not error handling and must not be the last stop for a caught error.

package/agents/project/tests/AGENTS.md

@@ -9,7 +9,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
-- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. Do not run whole-project coverage after every ordinary change by default. Use the repository's non-coverage commit gate before commit, and use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
+- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Do not run whole-project coverage after every ordinary change by default. Use the repository's non-coverage commit gate before commit, and use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
 - 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.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.

package/cli/commands/verify.ts

@@ -5,7 +5,6 @@ import path from 'path';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
-import Compiler from '../compiler';
 import Paths from '../paths';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
@@ -14,6 +13,13 @@ import { buildOrientationResponse, type TDiagnoseChainItem, type TDiagnoseRespon
 import type { TProteumManifest, TProteumManifestDiagnostic } from '@common/dev/proteumManifest';
 import type { TDevCommandRunResponse } from '@common/dev/commands';
 import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '@common/dev/session';
+import {
+    renderChangedVerificationPlan,
+    runChangedVerification,
+    type TChangedVerificationCheck,
+    type TChangedVerificationExecution,
+    type TChangedVerificationSkippedCheck,
+} from '../verification/changed';
 
 type TVerifySeverity = 'error' | 'warning';
 type TVerifyStepStatus = 'failed' | 'info' | 'passed';
@@ -23,7 +29,7 @@ type TVerifyFinding = {
     blocking: boolean;
     code: string;
     message: string;
-    source: 'browser' | 'contracts' | 'doctor' | 'framework-change' | 'request' | 'command';
+    source: 'browser' | 'changed' | 'contracts' | 'doctor' | 'framework-change' | 'request' | 'command';
     filepath?: string;
     sourceLocation?: { line?: number; column?: number };
     relatedFilepaths?: string[];
@@ -51,12 +57,20 @@ type TVerifyResult = {
     action: string;
     target?: string;
     orientation?: TOrientResponse;
+    changedFiles?: string[];
+    configFilepath?: string;
+    dryRun?: boolean;
+    executions?: TChangedVerificationExecution[];
     introducedFindings: TVerifyFinding[];
     preExistingFindings: TVerifyFinding[];
+    selectedChecks?: TChangedVerificationCheck[];
+    skippedChecks?: TChangedVerificationSkippedCheck[];
     verificationSteps: TVerifyStep[];
     result: {
         ok: boolean;
         strictGlobal: boolean;
+        failedChecks?: number;
+        selectedChecks?: number;
         introducedBlockingFindings: number;
         preExistingBlockingFindings: number;
         blockingFindings: number;
@@ -267,6 +281,7 @@ const ensureServer = async ({
 };
 
 const resolveLocalManifest = async () => {
+    const { default: Compiler } = await import('../compiler');
     const compiler = new Compiler('dev');
     await compiler.refreshGeneratedTypings();
     return readProteumManifest(cli.paths.appRoot);
@@ -365,9 +380,16 @@ const classifyDiagnostics = ({
 const finalizeResult = ({
     action,
     apps,
+    changedFiles,
+    configFilepath,
+    dryRun,
+    executions,
     introducedFindings,
     orientation,
     preExistingFindings,
+    selectedChecks,
+    skippedChecks,
+    changedResult,
     strictGlobal,
     target,
     verificationSteps,
@@ -375,9 +397,16 @@ const finalizeResult = ({
     action: string;
     target?: string;
     orientation?: TOrientResponse;
+    changedFiles?: string[];
+    configFilepath?: string;
+    dryRun?: boolean;
+    executions?: TChangedVerificationExecution[];
     apps?: TVerifyAppResult[];
     introducedFindings: TVerifyFinding[];
     preExistingFindings: TVerifyFinding[];
+    selectedChecks?: TChangedVerificationCheck[];
+    skippedChecks?: TChangedVerificationSkippedCheck[];
+    changedResult?: { failedChecks: number; selectedChecks: number };
     verificationSteps: TVerifyStep[];
     strictGlobal: boolean;
 }): TVerifyResult => {
@@ -389,13 +418,20 @@ const finalizeResult = ({
         action,
         ...(target ? { target } : {}),
         ...(orientation ? { orientation } : {}),
+        ...(changedFiles ? { changedFiles } : {}),
+        ...(configFilepath ? { configFilepath } : {}),
+        ...(dryRun !== undefined ? { dryRun } : {}),
+        ...(executions ? { executions } : {}),
         ...(apps ? { apps } : {}),
         introducedFindings,
         preExistingFindings,
+        ...(selectedChecks ? { selectedChecks } : {}),
+        ...(skippedChecks ? { skippedChecks } : {}),
         verificationSteps,
         result: {
             ok,
             strictGlobal,
+            ...(changedResult ? { failedChecks: changedResult.failedChecks, selectedChecks: changedResult.selectedChecks } : {}),
             introducedBlockingFindings,
             preExistingBlockingFindings,
             blockingFindings: introducedBlockingFindings + preExistingBlockingFindings,
@@ -437,6 +473,24 @@ const renderFrameworkApps = (apps: TVerifyAppResult[]) =>
         ])
         .join('\n');
 
+const renderChangedChecks = (result: TVerifyResult) => {
+    if (!result.changedFiles || !result.selectedChecks || !result.skippedChecks) return '';
+
+    return [
+        'Changed Verification',
+        `- config=${result.configFilepath || 'none'}`,
+        `- dryRun=${result.dryRun === true}`,
+        `- changedFiles=${result.changedFiles.length}`,
+        `- selectedChecks=${result.selectedChecks.length}`,
+        `- skippedChecks=${result.skippedChecks.length}`,
+        ...result.selectedChecks.map(
+            (check) =>
+                `- [${check.scope}] ${check.id} cwd=${check.cwd} command=${check.command} reason=${check.reasons.join('; ')}`,
+        ),
+        ...result.skippedChecks.map((check) => `- [skipped] ${check.id} reason=${check.reason}`),
+    ].join('\n');
+};
+
 const renderHuman = (result: TVerifyResult) =>
     [
         `Proteum verify ${result.action}${result.target ? ` ${result.target}` : ''}`,
@@ -448,6 +502,7 @@ const renderHuman = (result: TVerifyResult) =>
               ]
             : []),
         ...(result.apps ? [renderFrameworkApps(result.apps)] : []),
+        ...(result.changedFiles ? ['', renderChangedChecks(result)] : []),
         '',
         renderSteps(result.verificationSteps),
         '',
@@ -1075,6 +1130,62 @@ const collectAppResult = async ({
     };
 };
 
+const runChangedVerify = async () => {
+    const base = typeof cli.args.base === 'string' && cli.args.base.trim() ? cli.args.base.trim() : undefined;
+    const changed = await runChangedVerification({
+        base,
+        cwd: String(cli.args.workdir || process.cwd()),
+        dryRun: cli.args.dryRun === true,
+        onPlan: (plan) => {
+            if (cli.args.json !== true) console.log(renderChangedVerificationPlan(plan));
+        },
+        staged: cli.args.staged === true,
+    });
+    const introducedFindings: TVerifyFinding[] = changed.executions
+        .filter((execution) => execution.status === 'failed')
+        .map((execution) => ({
+            severity: 'error',
+            blocking: true,
+            code: 'changed/check-failed',
+            message: `Verification check "${execution.checkId}" failed with exit code ${execution.exitCode ?? 'unknown'}.`,
+            source: 'changed',
+            details: [`command=${execution.command}`, `cwd=${execution.cwd}`, `durationMs=${execution.durationMs}`],
+        }));
+
+    return finalizeResult({
+        action: 'changed',
+        changedFiles: changed.changedFiles,
+        configFilepath: changed.configFilepath,
+        dryRun: changed.dryRun,
+        executions: changed.executions,
+        introducedFindings,
+        preExistingFindings: [],
+        selectedChecks: changed.selectedChecks,
+        skippedChecks: changed.skippedChecks,
+        changedResult: changed.result,
+        strictGlobal: false,
+        verificationSteps: [
+            {
+                label: 'Discover Changed Files',
+                status: 'passed',
+                details: [`files=${changed.changedFiles.length}`, `gitRoot=${changed.gitRoot}`],
+            },
+            {
+                label: 'Plan Targeted Checks',
+                status: 'passed',
+                details: [`selected=${changed.selectedChecks.length}`, `skipped=${changed.skippedChecks.length}`],
+            },
+            {
+                label: changed.dryRun ? 'Skip Execution' : 'Run Targeted Checks',
+                status: changed.result.ok ? 'passed' : 'failed',
+                details: changed.dryRun
+                    ? ['dryRun=true']
+                    : [`executions=${changed.executions.length}`, `failed=${changed.result.failedChecks}`],
+            },
+        ],
+    });
+};
+
 const runFrameworkChangeVerify = async () => {
     const websiteRoute = typeof cli.args.route === 'string' && cli.args.route ? cli.args.route : '/';
     const apps = {
@@ -1208,7 +1319,9 @@ export const run = async () => {
     const target = typeof cli.args.target === 'string' ? cli.args.target.trim() : '';
     let result: TVerifyResult;
 
-    if (action === 'framework-change') {
+    if (action === 'changed') {
+        result = await runChangedVerify();
+    } else if (action === 'framework-change') {
         result = await runFrameworkChangeVerify();
     } else if (action === 'owner') {
         if (!target) throw new UsageError('`proteum verify owner` requires a query.');
@@ -1220,7 +1333,7 @@ export const run = async () => {
         if (!target) throw new UsageError('`proteum verify browser` requires a path or absolute URL.');
         result = await runBrowserVerify(target);
     } else {
-        throw new UsageError(`Unsupported verify action "${action}". Expected framework-change, owner, request, or browser.`);
+        throw new UsageError(`Unsupported verify action "${action}". Expected changed, framework-change, owner, request, or browser.`);
     }
 
     if (cli.args.json === true) {

package/cli/compiler/artifacts/controllerHelper.ts

@@ -0,0 +1,66 @@
+export const createTypedControllerHelperContent = (appIdentifier: string) => `/*----------------------------------
+- GENERATED FILE
+----------------------------------*/
+
+// This file is generated by Proteum from server/index.ts.
+// Do not edit it manually.
+
+import {
+    defineAction as defineBaseAction,
+    defineController,
+    schema,
+} from '@server/app/controller';
+import type {
+    TControllerActionContext,
+    TControllerActionDefinition,
+    TControllerActionInput,
+    TControllerActionResult,
+    TControllerDefinition,
+    TValidationSchema,
+    TValidationShape,
+    z,
+} from '@server/app/controller';
+
+export { defineController, schema };
+export type {
+    TControllerActionDefinition,
+    TControllerActionInput,
+    TControllerActionResult,
+    TControllerDefinition,
+    TValidationSchema,
+    TValidationShape,
+    z,
+};
+
+export type TApplication = import('@/server/index').${appIdentifier};
+export type TControllerRequestServices = import('@/server/index').TControllerRequestServices;
+export type TTypedControllerActionContext<TInput = undefined> = TControllerActionContext<
+    TInput,
+    TApplication,
+    TControllerRequestServices
+>;
+
+export function defineAction<TSchema extends TValidationSchema, TResult>(
+    definition: {
+        input: TSchema;
+        handler: (context: TTypedControllerActionContext<z.output<TSchema>>) => TResult;
+    },
+): TControllerActionDefinition<z.output<TSchema>, TResult, TApplication, TControllerRequestServices>;
+export function defineAction<TShape extends TValidationShape, TResult>(
+    definition: {
+        input: TShape;
+        handler: (context: TTypedControllerActionContext<z.output<z.ZodObject<TShape>>>) => TResult;
+    },
+): TControllerActionDefinition<z.output<z.ZodObject<TShape>>, TResult, TApplication, TControllerRequestServices>;
+export function defineAction<TResult>(
+    definition: {
+        handler: (context: TTypedControllerActionContext<undefined>) => TResult;
+    },
+): TControllerActionDefinition<undefined, TResult, TApplication, TControllerRequestServices>;
+export function defineAction(definition: {
+    input?: TValidationSchema | TValidationShape;
+    handler: (context: TTypedControllerActionContext<any>) => unknown;
+}) {
+    return defineBaseAction(definition as any);
+}
+`;

package/cli/compiler/artifacts/controllers.ts

@@ -5,6 +5,7 @@ import cli from '../..';
 import { indexControllers, printControllerTree, type TControllerFileMeta } from '../common/controllers';
 import { TProteumManifestController } from '../common/proteumManifest';
 import writeIfChanged from '../writeIfChanged';
+import { createTypedControllerHelperContent } from './controllerHelper';
 import { resolveConnectedProjectContracts, writeConnectedProjectContract } from './connectedProjects';
 import { normalizeAbsolutePath } from './shared';
 
@@ -319,6 +320,8 @@ export default controllers;
 `,
     );
 
+    writeIfChanged(path.join(app.paths.server.generated, 'controller.ts'), createTypedControllerHelperContent(app.identity.identifier));
+
     return {
         connectedProjects: connectedProjectContracts,
         controllers: [...manifestControllers, ...connectedManifestControllers],