proteum 2.4.4 → 2.5.1

package/agents/project/client/pages/AGENTS.md

@@ -2,27 +2,39 @@
 
 This is the canonical page-file contract for Proteum-based projects.
 Role: keep only page-file rules here.
-Keep here: `Router.page(...)` registration, SSR `data` and `render` contracts, page payload shape, and page-local typing rules.
+Keep here: `definePageRoute(...)` and `defineErrorRoute(...)`, SSR `data` and `render` contracts, page payload shape, and page-local typing rules.
 Do not put here: generic component rules, server/service implementation details, or app-wide workflow already covered by broader AGENTS files.
 
 Optimization source of truth: root-level `optimizations.md`.
 Diagnostics source of truth: root-level `diagnostics.md`.
 Coding style source of truth: root-level `CODING_STYLE.md`.
 
-## Router.page Usage
+## Page Definition Usage
 
-- 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 page files default-export `definePageRoute({ path, options, data, render })` or `defineErrorRoute({ code, options, render })`.
+- File path controls chunk identity and layout discovery; route URL comes from the explicit `path` value.
 - `options` is always required and must be an object.
-- `data` is the only nullable argument. Pass `null` when the page does not need SSR data.
-- Keep the `Router.page(...)` call compact instead of exploding each outer argument onto its own line.
-- Keep route registration at top level. Do not hide it behind helper abstractions.
+- `data` is the only nullable route field. Pass `null` when the page does not need SSR data.
+- Keep route metadata static and serializable. Runtime app/client references belong only inside `data` and `render`.
+- Do not import `@app`, `@/client/router`, or `@client/router` in page files.
+
+```tsx
+import { definePageRoute } from '@common/router/definitions';
+
+export default definePageRoute({
+    path: '/dashboard',
+    options: { auth: true },
+    data: ({ AccountController }) => ({
+        account: AccountController.accountPage(),
+    }),
+    render: ({ account }) => <Dashboard account={account} />,
+});
+```
 
 ## Data And Render
 
 - Route behavior belongs in the explicit `options` object, not in page data.
-- `data` returns one flat object or `null` is passed as the third argument when no page data is needed.
+- `data` returns one flat object, or the route definition sets `data: null` when no page data is needed.
 - Returning route-option keys such as `auth`, `layout`, `static`, `redirectLogged`, or their `_`-prefixed variants from `data` is a contract error.
 - Controller fetchers and promises returned from `data` resolve before render.
 - If a page needs route data, return it from `data` and read it in `render`.

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, 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.
+- 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.
 - 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.
@@ -64,7 +64,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - 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.
 - 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 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.
+- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. Run the repository's non-coverage commit gate before committing, and run the full `npm run check` gate before pushing or when explicitly requested.
 - 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/optimizations.md

@@ -23,7 +23,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 
 ## SSR And Page Size
 
-- SSR page data belongs in the explicit `Router.page(path, options, data, render)` `data` function, not in `api.fetch(...)`.
+- SSR page data belongs in the explicit `definePageRoute({ path, options, data, render })` `data` function, not in `api.fetch(...)`.
 - `options` carries route behavior. `data` returns one flat object or is `null` when the page has no SSR data loader.
 - Route-option keys and `_`-prefixed route-option aliases are forbidden in page data and must live in `options`.
 - If a page needs route data, return it from `data` and read it in `render`.

package/agents/project/root/AGENTS.md

@@ -21,6 +21,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 needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
@@ -63,21 +64,22 @@ 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.
-- For production changes, 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. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions, and do not claim the project has full unit coverage when an exception remains.
-- 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.
+- 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.
 - 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.
@@ -90,14 +92,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`.
@@ -109,6 +112,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 } }`.
@@ -120,13 +168,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`.
@@ -139,25 +201,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`.
@@ -167,19 +251,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.
@@ -217,7 +300,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

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

@@ -11,8 +11,37 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Use `server/routes/**` only for explicit HTTP behavior that should not be generated from controllers.
 - If the endpoint is a normal app API, prefer `server/controllers/**/*.ts`.
 - Good fits include redirects, resources, OAuth callbacks, webhooks, sitemap-like output, and custom public endpoints.
+- Route files default-export `defineServerRoute({ method, path, options, handler })` or `defineServerRoutes([...])`.
+- Keep `method`, `path`, and `options` static. Runtime services are received through the route factory or handler context.
+- Do not import `@app` in route files. Use `defineServerRoutes((app) => [...])` when routes need app services.
+- Use `expressHandler(...)` only when a route needs raw Express `req`, `res`, or `next`.
 - If a route needs a curated registry, keep server-only data in `/server/catalogs/**` and shared data in `/common/catalogs/**`.
 
+Example route file; replace `ProjectApp` with the concrete app type exported from `server/index.ts`.
+
+```ts
+import { defineServerRoute, defineServerRoutes, expressHandler } from '@common/router/definitions';
+import type { ProjectApp } from '@/server/index';
+
+export default defineServerRoutes((app: ProjectApp) => [
+    defineServerRoute({
+        method: 'GET',
+        path: '/health',
+        options: {},
+        handler: ({ response }) => response.json({ ok: true }),
+    }),
+    defineServerRoute({
+        method: 'POST',
+        path: '/webhook',
+        options: {},
+        handler: expressHandler((request, response) => {
+            app.Webhooks.handle(request.body);
+            response.status(204).send('');
+        }),
+    }),
+]);
+```
+
 ## Absolute URLs
 
-Use `Router.url('/relative/path')` to generate absolute URLs.
+Use `context.Router.url('/relative/path')` inside handlers, or `app.Router.url('/relative/path')` inside `defineServerRoutes((app) => ...)`, to generate absolute URLs.

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 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. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions, and do not claim the project has full unit coverage when an exception remains.
+- 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.
 - 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/doctor.ts

@@ -1,9 +1,15 @@
 import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
+import {
+    createWorktreeBootstrapDiagnostics,
+    getWorktreeBootstrapStatus,
+    type TWorktreeBootstrapDiagnostic,
+} from '../runtime/worktreeBootstrap';
 import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
-import { buildDoctorResponse, renderDoctorHuman, renderDoctorResponseHuman } from '@common/dev/diagnostics';
+import { buildDoctorResponse, renderDoctorResponseHuman } from '@common/dev/diagnostics';
 import { compactList, printAgentResponse, printJson, truncateForAgent } from '../utils/agentOutput';
+import type { TDoctorResponse } from '@common/dev/diagnostics';
 
 const allowedDoctorArgs = new Set(['contracts', 'full', 'human', 'json', 'strict']);
 
@@ -30,6 +36,31 @@ const compactDiagnostic = (diagnostic: ReturnType<typeof buildDoctorResponse>['d
     fixHint: diagnostic.fixHint ? truncateForAgent(diagnostic.fixHint) : undefined,
 });
 
+const mergeBootstrapDiagnostics = ({
+    bootstrapDiagnostics,
+    response,
+    strict,
+}: {
+    bootstrapDiagnostics: TWorktreeBootstrapDiagnostic[];
+    response: TDoctorResponse;
+    strict: boolean;
+}): TDoctorResponse => {
+    if (bootstrapDiagnostics.length === 0) return response;
+
+    const diagnostics = [...response.diagnostics, ...bootstrapDiagnostics];
+    const errors = diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+
+    return {
+        diagnostics,
+        summary: {
+            errors,
+            strictFailed: response.summary.strictFailed || (strict && diagnostics.length > 0),
+            warnings,
+        },
+    };
+};
+
 export const run = async (): Promise<void> => {
     validateDoctorArgs();
 
@@ -37,10 +68,25 @@ export const run = async (): Promise<void> => {
     await compiler.refreshGeneratedTypings();
 
     const manifest = readProteumManifest(cli.paths.appRoot);
-    const response =
+    const rawResponse =
         cli.args.contracts === true
             ? buildContractsDoctorResponse(manifest, cli.args.strict === true)
             : buildDoctorResponse(manifest, cli.args.strict === true);
+    const bootstrapStatus = getWorktreeBootstrapStatus({
+        appRoot: cli.paths.appRoot,
+        proteumVersion: String(cli.packageJson.version || ''),
+    });
+    const response =
+        cli.args.contracts === true
+            ? rawResponse
+            : mergeBootstrapDiagnostics({
+                  bootstrapDiagnostics: createWorktreeBootstrapDiagnostics({
+                      appRoot: cli.paths.appRoot,
+                      status: bootstrapStatus,
+                  }),
+                  response: rawResponse,
+                  strict: cli.args.strict === true,
+              });
 
     if (cli.args.full === true) {
         printJson(response);
@@ -53,7 +99,12 @@ export const run = async (): Promise<void> => {
                       response,
                       title: 'Proteum doctor contracts',
                   })
-                : renderDoctorHuman(manifest, cli.args.strict === true),
+                : renderDoctorResponseHuman({
+                      emptyMessage: 'No diagnostics were found.',
+                      manifest,
+                      response,
+                      title: 'Proteum doctor',
+                  }),
         );
     } else {
         printAgentResponse({

package/cli/commands/runtime.ts

@@ -7,6 +7,7 @@ import cli from '..';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { listDevSessionInspections, writeMachineDevSessionRecord, type TDevSessionInspection } from '../runtime/devSessions';
 import { inspectDevPort, type TDevPortInspection } from '../runtime/ports';
+import { compactWorktreeBootstrapStatus, getWorktreeBootstrapStatus } from '../runtime/worktreeBootstrap';
 import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 import type { TDoctorResponse } from '@common/dev/diagnostics';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
@@ -193,6 +194,10 @@ export const run = async () => {
               port: manifest.env.resolved.routerPort,
           })
         : undefined;
+    const worktreeBootstrap = getWorktreeBootstrapStatus({
+        appRoot: cli.paths.appRoot,
+        proteumVersion: String(cli.packageJson.version || ''),
+    });
 
     const payload = {
         appRoot: cli.paths.appRoot,
@@ -216,6 +221,7 @@ export const run = async () => {
         sessions: sessions.map(compactSession),
         health,
         configuredDevPort,
+        worktreeBootstrap: compactWorktreeBootstrapStatus(worktreeBootstrap),
     };
 
     if (cli.args.full === true) {

package/cli/commands/worktree.ts

@@ -0,0 +1,116 @@
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import {
+    compactWorktreeBootstrapStatus,
+    getWorktreeBootstrapStatus,
+    runWorktreeBootstrapCreate,
+    runWorktreeBootstrapInit,
+} from '../runtime/worktreeBootstrap';
+import { printAgentResponse, printJson } from '../utils/agentOutput';
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' ? cli.args.action : '';
+    if (action === 'init' || action === 'create') return action;
+
+    throw new UsageError('Usage: `proteum worktree init` or `proteum worktree create <target-repo-root>`.');
+};
+
+const getStringArg = (name: string) => {
+    const value = cli.args[name];
+    return typeof value === 'string' ? value.trim() : '';
+};
+
+const getBooleanArg = (name: string) => cli.args[name] === true;
+
+const printResult = ({
+    data,
+    json,
+    summary,
+}: {
+    data: object;
+    json: boolean;
+    summary: string;
+}) => {
+    if (json) {
+        printJson({ ok: true, format: 'proteum-agent-v1', summary, data });
+        return;
+    }
+
+    printAgentResponse({ summary, data });
+};
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+
+export const run = async (): Promise<void> => {
+    const action = getAction();
+    const json = getBooleanArg('json');
+    const source = getStringArg('source') || undefined;
+    const skipDeps = getBooleanArg('skipDeps');
+    const reason = getStringArg('reason') || undefined;
+
+    if (action === 'init') {
+        const result = await runWorktreeBootstrapInit({
+            appRoot: cli.paths.appRoot,
+            coreRoot: cli.paths.core.root,
+            json,
+            proteumVersion: String(cli.packageJson.version || ''),
+            reason,
+            refresh: getBooleanArg('refresh'),
+            skipDeps,
+            source,
+        });
+
+        printResult({
+            data: {
+                appRoot: result.appRoot,
+                markerFilepath: result.markerFilepath,
+                worktreeBootstrap: compactWorktreeBootstrapStatus(result.status),
+            },
+            json,
+            summary: 'Proteum worktree bootstrap completed.',
+        });
+        return;
+    }
+
+    const targetRepoRoot = getStringArg('target');
+    const branch = getStringArg('branch');
+    if (!source) throw new UsageError('worktree create requires --source <source-app-root>.');
+
+    const result = await runWorktreeBootstrapCreate({
+        appRoot: source,
+        base: getStringArg('base') || undefined,
+        branch,
+        coreRoot: cli.paths.core.root,
+        json,
+        proteumVersion: String(cli.packageJson.version || ''),
+        reason,
+        refresh: true,
+        skipDeps,
+        source,
+        targetRepoRoot,
+    });
+    const status = getWorktreeBootstrapStatus({
+        appRoot: result.targetAppRoot,
+        proteumVersion: String(cli.packageJson.version || ''),
+    });
+
+    printResult({
+        data: {
+            branch: result.branch,
+            sourceAppRoot: result.sourceAppRoot,
+            sourceRepoRoot: result.sourceRepoRoot,
+            targetAppRoot: result.targetAppRoot,
+            targetRepoRoot: result.targetRepoRoot,
+            worktreeBootstrap: compactWorktreeBootstrapStatus(status),
+        },
+        json,
+        summary: `Created Proteum worktree at ${result.targetRepoRoot}.`,
+    });
+};