proteum 2.4.4 → 2.5.1

package/README.md

@@ -4,8 +4,6 @@ Proteum is an LLM-first SSR / SEO / TypeScript framework for full-stack web appl
 
 It is built for teams that want explicit server contracts, server-first rendering, deterministic generated artifacts, and a codebase that an AI agent can inspect without reverse-engineering hidden runtime magic.
 
-Migration guide for older apps: [docs/migrate-from-2.1.3.md](docs/migrate-from-2.1.3.md)
-
 ## Sponsor
 
 Proteum is sponsored by [Unique Domains](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor).
@@ -33,8 +31,8 @@ Proteum combines:
 ## Core Principles
 
 - **Server-first by default.** Put data loading in the page data function and keep client code focused on UI.
-- **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
-- **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
+- **Explicit request entrypoints.** Routes and controllers are exported definition objects.
+- **Local validation.** Declare controller input on `defineAction({ input, handler })`; handlers receive parsed `input`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
 - **Explainability matters.** `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` expose the framework view of your app and its live requests, and the profiler renders the same diagnostics and perf surfaces for humans in dev.
 - **SEO is not an afterthought.** Identity, routes, layouts, and SSR data are part of the app contract.
@@ -76,9 +74,9 @@ Important files:
 - `proteum.config.ts`: typed Proteum compiler and connection settings such as `transpile` and `connect` via `Application.setup({ ... })`
 - `process.env` / optional `.env`: `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen variables referenced by `proteum.config.ts`, and `TRACE_*` environment variables loaded by the app
 - `server/config/*.ts`: plain typed config exports consumed by the explicit app bootstrap
-- `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
-- `client/pages/**`: SSR page entrypoints registered through `Router.page(path, options, data, render)`
-- `server/controllers/**`: request handlers that extend `Controller`
+- `server/index.ts`: default-exported `defineApplication({ services, router, models, commands })` application graph
+- `client/pages/**`: SSR page entrypoints that default-export `definePageRoute({ path, options, data, render })`
+- `server/controllers/**`: generated API definitions that default-export `defineController({ path, actions })`
 - `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
 - `.proteum/**`: framework-owned generated contracts and manifests
@@ -142,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
@@ -169,25 +167,45 @@ export const routerBaseConfig = {
 
 ```ts
 // server/index.ts
-import { Application } 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 class MyApp extends Application {
-  public Users = new Users(this, userConfig.usersConfig, this);
-  public Router = new Router(
-    this,
+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({}, this),
+        schema: new SchemaRouter({}, app),
       },
     },
-    this
+    app
   );
-}
+
+const MyApplication = defineApplication<MyAppServices, MyRouter>({
+  services: (app) => ({
+    Users: new Users(app, userConfig.usersConfig, app),
+  }),
+  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,60 +251,59 @@ Default public asset validators depend on the environment: dev disables `ETag` a
 Proteum pages are explicit SSR entrypoints.
 
 ```tsx
-import Router from '@/client/router';
+import { definePageRoute } from '@common/router/definitions';
 
-Router.page(
-  '/',
-  {
+export default definePageRoute({
+  path: '/',
+  options: {
     auth: false,
     layout: false,
   },
-  ({ Plans, Stats }) => ({
+  data: ({ Plans, Stats }) => ({
     plans: Plans.getPlans(),
     stats: Stats.general(),
   }),
-  ({ plans, stats }) => {
+  render: ({ plans, stats }) => {
     return <LandingPage plans={plans} stats={stats} />;
-  }
-);
+  },
+});
 ```
 
 What happens here:
 
-- the first argument is the route path
-- the second argument is the explicit route-options object
-- the third argument is the page data function or `null`
+- `path`, `options`, and error `code` metadata are static and compiler-readable
 - route behavior such as `auth`, `layout`, `static`, or `redirectLogged` lives in the options object
-- every key returned from the data function becomes page data
-- the renderer receives the resolved data and the generated controller/service context
+- every key returned from `data` becomes page data
+- runtime app/client references are allowed only inside `data` and `render`
 
 ## Example: Controller
 
 Proteum controllers are explicit request entrypoints.
 
 ```ts
-import Controller, { schema } from '@server/app/controller';
+import { defineAction, defineController, schema } from '@server/app/controller';
 
-export default class AuthController extends Controller<MyApp> {
-  public async loginWithPassword() {
-    const { Auth } = this.services;
-    const data = this.input(
-      schema.object({
+export default defineController({
+  path: 'Auth',
+  actions: {
+    loginWithPassword: defineAction({
+      input: schema.object({
         email: schema.string().email(),
         password: schema.string().min(8),
-      })
-    );
-
-    return Auth.loginWithPassword(data, this.request);
-  }
-}
+      }),
+      handler: ({ input, services, request }) => {
+        return services.Auth.loginWithPassword(input, request);
+      },
+    }),
+  },
+});
 ```
 
 Controller rules:
 
-- read request-scoped values from `this.request`
-- validate once with `this.input(schema)`
-- call business logic through `this.services`, `this.models`, or `this.app`
+- read request-scoped values from action context
+- declare validation once with `defineAction({ input, handler })`
+- call business logic through `services`, `models`, or `app`
 - return explicit values instead of relying on ambient globals
 
 ## Example: Command
@@ -386,6 +403,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `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 |
+| `proteum worktree` | Create or initialize Codex worktrees with a machine-readable bootstrap marker |
 
 Recommended daily workflow:
 
@@ -439,6 +457,8 @@ Useful scaffolding commands:
 proteum init my-app --name "My App"
 proteum init my-app --name "My App" --dry-run --json
 proteum configure agents
+proteum worktree init --source /path/to/main-app
+proteum worktree create /path/to/.codex/worktrees/feature --source /path/to/main-app --branch feature/name
 proteum create page marketing/faq --route /faq
 proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
@@ -448,6 +468,8 @@ proteum create service Conversion/Plans
 
 Every `proteum dev` start runs the same idempotent instruction check. It updates missing or stale managed sections automatically and prompts only when a blocked path would need to be replaced.
 
+`proteum worktree init` writes `.proteum/worktree-bootstrap.json` for app roots under `/.codex/worktrees/`. The marker records `.env` copy status, refresh and dependency results, runtime status, key file hashes, and the active Proteum version. `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` block inside Codex worktrees until the marker is fresh. Run `npx proteum worktree init --source <source-app-root>` for a new worktree, or add `--refresh` when stale state is reported. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor, and MCP output.
+
 `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. `proteum runtime status` also inspects the configured router/HMR ports and returns an exact Start Dev action, so agents do not need to `curl` page routes to identify port owners. `proteum dev` exposes the app-root MCP contract at `/__proteum/mcp` and ensures one managed machine MCP daemon is running; `proteum mcp` is the machine-scope router agents register once. Agents should start with MCP `workflow_start`, use offline candidates to choose the correct app root when no dev server is live, then route repeated reads by the returned live `projectId`. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md), [docs/mcp.md](docs/mcp.md), and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands
@@ -573,13 +595,14 @@ If you are an LLM or automation agent, start here:
 
 1. Use `proteum mcp` as the one registered MCP server; `proteum dev` ensures the managed machine daemon is running.
 2. Call MCP `workflow_start` with `cwd` or a known `projectId`; if it is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, choose the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.
-3. Use the returned live `projectId` with MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` before CLI equivalents for repeated read-only app state.
-4. Treat returned instruction previews as the allowed scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when compact previews are insufficient.
-5. Use compact CLI commands for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final reproducible terminal evidence.
-6. Use `proteum diagnose`, `proteum perf`, and compact `proteum trace` for reproducible command evidence when MCP is unavailable or the terminal output itself is needed.
-7. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact MCP offline or runtime-status next action. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again and retry `workflow_start`. Do not run diagnose, trace, or perf reads while runtime health is unreachable, and do not `curl` normal page routes to identify port ownership.
-8. Inspect `server/index.ts`, controllers, services, or pages only after the routing/diagnostic surfaces identify the relevant owner. Do not run broad owner searches after MCP already returned the route/page/controller owner.
-9. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum e2e --session-email <email> --session-role <role>` for Playwright suites or `proteum session <email> --role <role>` before direct HTTP calls.
+3. If the app root is inside `/.codex/worktrees/` and `workflow_start` or a guarded CLI command reports missing/stale bootstrap, run the returned `npx proteum worktree init --source <source-app-root>` command before runtime reads.
+4. Use the returned live `projectId` with MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` before CLI equivalents for repeated read-only app state.
+5. Treat returned instruction previews as the allowed scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when compact previews are insufficient.
+6. Use compact CLI commands for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final reproducible terminal evidence.
+7. Use `proteum diagnose`, `proteum perf`, and compact `proteum trace` for reproducible command evidence when MCP is unavailable or the terminal output itself is needed.
+8. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact MCP offline or runtime-status next action. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again and retry `workflow_start`. Do not run diagnose, trace, or perf reads while runtime health is unreachable, and do not `curl` normal page routes to identify port ownership.
+9. Inspect `server/index.ts`, controllers, services, or pages only after the routing/diagnostic surfaces identify the relevant owner. Do not run broad owner searches after MCP already returned the route/page/controller owner.
+10. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum e2e --session-email <email> --session-role <role>` for Playwright suites or `proteum session <email> --role <role>` before direct HTTP calls.
 
 For implementation rules in a real Proteum app, treat the routed local `AGENTS.md` files plus `proteum orient`, compact CLI diagnostics, and MCP repeated-read surfaces as the task contract. This README is the framework overview, not the project-local instruction layer.
 
@@ -648,6 +671,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:
@@ -656,7 +685,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

@@ -16,16 +16,14 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 ## Fast Triggers
 
 - If `cwd` is inside `/.codex/worktrees/`, run Worktree Preflight before implementation:
-  - Copy `.env` from the main worktree when missing.
-  - Run `npx proteum refresh`.
-  - Run `npm i` when dependencies are missing or stale.
+  - Run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing.
+  - Run `npx proteum worktree init --source <source-app-root> --refresh` when Proteum reports stale bootstrap state.
+  - Use `--skip-deps --reason "..."` only when dependency installation is intentionally skipped.
   - Run `npx proteum runtime status`.
   - For runtime-visible work, start or reuse one tracked `npx proteum dev` session using the Task Lifecycle launch workflow.
 - If you are working in a newly created Proteum worktree, before following the rest of these instructions:
-  - Copy `.env` from the main worktree.
-  - Run `npx proteum refresh`.
+  - Run `npx proteum worktree init --source <source-app-root>`.
   - Read and acknowledge the applicable `AGENTS.md` files.
-  - Run `npm i`.
   - Run the dev server with the task-safe elevated-permissions launch workflow from `Task Lifecycle`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link.
 - If the user pastes raw errors without asking for a fix, do not implement changes yet. First run the task-safe local reproduction path: identify the likely app, route, command, or request from the error, boot or reuse the relevant dev server with the elevated-permissions workflow in `Task Lifecycle`, reproduce the failing surface locally, and inspect server output, browser console output, diagnostics, traces, or the smallest relevant command result. If the error does not identify enough context to reproduce, say what is missing and use the available local evidence before guessing. Then list likely causes and, for each one, give probability, why, and how to fix it. After this, every time you implement a fix:
     - test, re-run analysis and give a comparison table of before and after
@@ -36,6 +34,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - When a Proteum MCP client is available, first call MCP `workflow_start` with `cwd` or a known `projectId`. If it is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start exactly one dev server from that app root when needed, then retry `workflow_start`. Pass the returned live `projectId` to every follow-up app-bound MCP tool. `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Prefer MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime/status/orientation/owner/route/trace/perf/log/database reads. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after MCP returns the owner. Use CLI commands when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 - MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
+- For bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes, load and follow root-level `DOCUMENTATION.md` before coding so the relevant fix note, regression-test docs, ADR, or explicit skip reason is handled in the same change.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
 - If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
@@ -54,7 +53,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
   [optional body]
   ```
-  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.
+  Then treat `commit` as conversation-wide and cross-project, not task-scoped. Before staging or committing, run the repository's non-coverage commit gate when it defines one, such as `npm run check:commit`; otherwise run targeted lint, typecheck, and test commands. Report any blocker instead of committing through a failed commit gate. 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.`
 
@@ -80,20 +79,21 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 ### 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.
-- 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 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.
 - 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.`
 
 ## Core Contracts
 
-- Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)`.
-- Page URLs come from the explicit `Router.page('/path', ...)` call, not from the file path.
-- Callable app APIs live only in `server/controllers/**/*.ts` files that extend `Controller`.
+- Client pages live in `client/pages/**` and default-export `definePageRoute(...)` or `defineErrorRoute(...)`.
+- Page URLs come from the explicit route definition `path`, not from the file path.
+- Callable app APIs live only in `server/controllers/**/*.ts` files that default-export `defineController(...)`.
 - Dev-only internal execution lives only in `commands/**/*.ts` files that extend `Commands`.
 - Manual HTTP endpoints live only in `server/routes/**`.
-- Controllers call `this.input(schema)` inside the method body, at most once per method.
-- Request-scoped state lives only on `this.request` and manual-route/router context objects.
+- Controllers declare input on `defineAction({ input, handler })`; handlers receive parsed `input` in context.
+- Request-scoped state lives only on action handler context and manual-route handler context objects.
 - Keep one class or one React/Preact component per file.
 - Prefer a deep tree grouped by business concern instead of long file names.
 - Use the default `*.ts` or `*.tsx` file unless an `*.ssr.ts` or `*.ssr.tsx` variant is truly required.
@@ -106,14 +106,15 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Do not import runtime values from `@models`.
 - Do not use `@request` runtime globals.
 - Do not use `@app` on the client.
+- Do not import `@app` in route, page, or controller files. Runtime app/services/router access belongs in typed callback parameters.
 - Prefer type inference rooted in the explicit application graph in `server/index.ts`.
 
 ## Surface Contracts
 
 ### App Bootstrap And Services
 
-- `server/index.ts` default-exports the app `Application` subclass and is the canonical type root.
-- Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
+- `server/index.ts` default-exports `defineApplication({ services, router, models, commands })` and is the canonical type root.
+- Root services are declared in the explicit `services` graph and instantiated with `new ServiceClass(app, config, app)`.
 - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
 - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
 - Router plugins can subscribe to `request` and `request.finished`; `request.profiling` exists before `request` runs and carries the finalized request/API/SQL snapshot by `request.finished`.
@@ -125,6 +126,51 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Companion client-callable entrypoints live in `server/controllers/**`.
 - `proteum create service ...` scaffolds the service file, a typed config export under `server/config/*.ts`, and the root registration in `server/index.ts`; review and adapt the generated names before committing.
 
+Example app root shape; replace names with the project app type and service names:
+
+```ts
+import { defineApplication, type Application } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+import BillingService from '@/server/services/Billing';
+
+import * as appConfig from '@/server/config/app';
+
+type ProjectServices = {
+    Billing: BillingService;
+};
+
+type ProjectRouterPlugins = {
+    schema: SchemaRouter;
+};
+
+export type ProjectRouter = Router<ProjectApp, ProjectRouterPlugins>;
+export interface ProjectApp extends Application, ProjectServices {
+    Router: ProjectRouter;
+}
+
+const createProjectRouter = (app: ProjectApp): ProjectRouter =>
+    new Router<ProjectApp, ProjectRouterPlugins>(
+        app,
+        {
+            ...appConfig.routerBaseConfig,
+            plugins: {
+                schema: new SchemaRouter({}, app),
+            },
+        },
+        app,
+    );
+
+const ProjectApplication = defineApplication<ProjectServices, ProjectRouter>({
+    services: (app) => ({
+        Billing: new BillingService(app, {}, app),
+    }),
+    router: createProjectRouter,
+});
+
+export default ProjectApplication;
+```
+
 ### Connected Projects
 
 - Declare connected namespaces in `proteum.config.ts` with explicit values such as `connect: { Product: { source: PRODUCT_CONNECTED_SOURCE, urlInternal: PRODUCT_URL_INTERNAL } }`.
@@ -136,13 +182,27 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 ### Controllers
 
-- Files live under `server/controllers/**/*.ts` and default-export a class extending `Controller`.
-- Methods with bodies become generated client-callable endpoints.
-- Route path comes from the controller file path plus the method name.
-- `export const controllerPath = 'Custom/path'` can override the base path.
+- Files live under `server/controllers/**/*.ts` and default-export `defineController({ path, actions })`.
+- Actions declared with `defineAction(...)` become generated client-callable endpoints.
+- Route path comes from the controller `path` plus the action name.
+- Set `path: 'Custom/path'` on `defineController(...)` to override the base path.
 - Generated client calls use `POST`.
 - 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';
+
+export default defineController({
+    path: 'Billing',
+    actions: {
+        read: defineAction({
+            input: schema.object({ accountId: schema.string() }),
+            handler: ({ input }) => ({ accountId: input.accountId }),
+        }),
+    },
+});
+```
+
 ### Commands
 
 - Files live under `commands/**/*.ts` and default-export a class extending `Commands` from `@server/app/commands`.
@@ -155,25 +215,47 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 
 ### Client Pages
 
-- Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
-- File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- The only supported page signature is `Router.page(path, options, data, render)`.
+- Proteum scans page files for default-exported `definePageRoute(...)` and `defineErrorRoute(...)` definitions.
+- File path controls chunk identity and layout discovery; route path comes from the explicit definition `path` value.
+- The supported page shape is `definePageRoute({ path, options, data, render })`.
 - `options` is always required. `data` is the only nullable argument and must be `null` when the page has no SSR data loader.
 - `data` returns one flat object. Route-option keys such as `auth`, `layout`, `static`, and `_static` are forbidden in page data and must live in `options`.
 - Controller fetchers and promises returned from `data` resolve before render.
 - `render` consumes resolved page data and uses generated controller methods from render args or `@/client/context`.
 - Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page data state.
-- Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
+- Error pages use `defineErrorRoute({ code, options, render })` in `client/pages/_messages/**`.
 - Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
 
+```tsx
+import { definePageRoute } from '@common/router/definitions';
+
+export default definePageRoute({
+    path: '/billing',
+    options: { auth: true },
+    data: ({ BillingController }) => ({ billing: BillingController.read({ accountId: 'current' }) }),
+    render: ({ billing }) => <BillingPage billing={billing} />,
+});
+```
+
 ### Manual Routes
 
 - Use `server/routes/**` only for explicit HTTP behavior that should not be a generated controller action.
 - Good fits include redirects, sitemap or RSS output, OAuth callbacks, webhooks, and public resources with custom semantics.
-- Import server-side app services from `@app` and use route handler context for `request`, `response`, router plugins, and custom router context.
+- Receive app services through `defineServerRoutes((app) => [...])` and use handler context for `request`, `response`, router plugins, and custom router context.
 - If the route is a normal app API, prefer a controller.
 - Prefer `proteum create route ...` for new manual-route boilerplate.
 
+```ts
+import { defineServerRoute } from '@common/router/definitions';
+
+export default defineServerRoute({
+    method: 'GET',
+    path: '/health',
+    options: {},
+    handler: ({ response }) => response.json({ ok: true }),
+});
+```
+
 ### Models And Aliases
 
 - Use Prisma typings from `@models/types`.
@@ -183,19 +265,18 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Aliases:
   - `@/client/...`, `@/server/...`, `@/common/...`: app code
   - `@client/...`, `@server/...`, `@common/...`: Proteum core modules
-  - `@app`: server-side application services for manual routes only
   - `@generated/*`: generated app surfaces
 
 ## Verification Matrix
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface first, then run the full project `npx proteum check` before finishing.
+- 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.
 - 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 plus the full project `npx proteum check`.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, use the browser MCP for browser-visible validation, then update and run the relevant end-to-end coverage. Save the non-coverage commit gate for commit workflows and the full `npm run check` gate for push workflows unless the user or project-local instructions explicitly ask for the full gate earlier.
 - Generated, connected, or ownership-ambiguous changes: start with MCP `workflow_start`, then `orient { projectId, query }` and `explain_summary { projectId, query }` only when more detail is needed; use `npx proteum orient <query>` and `npx proteum verify owner <query>` when MCP is unavailable or terminal evidence is required.
 - 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.
@@ -233,7 +314,7 @@ Verify at the correct layer:
 ### Discouraged Patterns
 
 - request-scoped state inside normal service methods
-- hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
+- hiding route definitions behind abstractions that remove the default-exported `definePageRoute(...)` or `defineServerRoute(...)` contract
 - editing `.proteum` directly
 
 ## Hard Stops
@@ -242,7 +323,7 @@ Verify at the correct layer:
 - For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.
 - 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 `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.
+- 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 after the repository's non-coverage commit gate passes when it defines one, such as `npm run check:commit`. Any other write-mode git action requires an explicit user request. Before any explicit push, run `npm run check` in every affected repository or worktree that defines it and report any blocker instead of pushing through a failed check.
 
 ## Appendix
 
@@ -337,10 +418,10 @@ Agents working in generated Proteum projects must use this delivery workflow for
 1. BDD / ATDD: translate the requested behavior into acceptance scenarios before changing implementation code.
 2. TDD: write or update the smallest failing unit/integration test that proves the next behavior.
 3. Implementation: make the narrowest production change that satisfies the failing test while preserving Proteum boundaries.
-4. Proteum check: refresh and validate generated framework contracts after route, page, controller, service, command, or config changes.
+4. Targeted validation: refresh generated framework contracts after route, page, controller, service, command, or config changes, then run the targeted tests/checks that match the changed surface.
 5. Validate unit + E2E: run the relevant unit tests and real-world journey E2E checks before calling the work complete.
 
-Unit test expectation: production changes must always add or update focused unit tests and maintain 100% whole-project Vitest unit coverage. Before claiming implementation work complete, run `npx vitest run --coverage` from the repository root and make sure global statements, branches, functions, and lines all meet the configured 100% thresholds. MCP endpoint-reference coverage, touched-path-only coverage, and focused test passes are not substitutes for whole-project Vitest coverage. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note, and agents must not claim the project has full unit coverage when an exception remains.
+Unit test expectation: production changes must 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 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. Any excluded generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested must be documented in the completion note.
 
 E2E expectation: real-world journeys must follow the project-local instructions in `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`. These tests should model complete user workflows, role transitions, permissions, state changes, and cross-view consistency rather than isolated happy paths.
 

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 the full project `npx proteum check`; 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. 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
 
@@ -21,7 +21,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - Keep short arrow functions and short returned object literals compact when they are easy to scan.
 - Keep JSX multiline only when it is clearly more readable; otherwise keep short JSX compact.
 - Avoid staircase formatting and unnecessary blank lines inside short callbacks.
-- Keep `Router.page(...)` and `Router.error(...)` registrations in the compact inline-call shape when possible, for example `Router.page('/path', {}, null, render);`.
+- Keep route definition metadata compact when possible, for example `definePageRoute({ path: '/path', options: {}, data: null, render });`.
 
 ## File organization
 

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

@@ -8,9 +8,7 @@ Do not put here: reusable Proteum architecture contracts, shared verification ru
 ## App-Root Triggers
 
 - If you are working in a newly created Proteum worktree, before following the rest of these instructions:
-  - Copy `.env` from the main worktree.
-  - Run `npx proteum refresh`.
+  - Run `npx proteum worktree init --source <source-app-root>`.
   - Read and acknowledge the applicable `AGENTS.md` files.
-  - Run `npm i`.
   - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If `proteum dev` reports blocked instruction paths, resolve them before continuing.
 - If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.

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 `Router.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