proteum 2.1.9 → 2.2.0

package/.codex/environments/environment.toml

@@ -0,0 +1,11 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "core"
+
+[setup]
+script = ""
+
+[[actions]]
+name = "Run"
+icon = "run"
+command = "npm login && npm publish"

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Proteum Core
 
-This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md`.
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md` for the standalone app-root contract, or split between `agents/project/root/AGENTS.md` and `agents/project/app-root/AGENTS.md` in a monorepo.
 Role: keep only framework-repo instructions here.
 Keep here: core-repo priorities, framework change workflow, reference-app validation, and framework-specific constraints.
 Do not put here: downstream app implementation contracts, area-specific app rules, or repeated content that belongs in `agents/project/**`.
@@ -19,22 +19,33 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 - Keep `server/index.ts` as the canonical type root for services, router context, request context, and models.
 - Keep generated code deterministic, auditable, and easy to map back to source.
 - Prefer typed traces, perf rollups, and manifest-backed diagnostics over ad hoc logging.
+- For Prisma-backed apps, declare database structure changes in the app's `schema.prisma` only. Never create or edit migration files manually, and never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, or `DROP TABLE`.
 - Follow `agents/project/optimizations.md` when choosing packages, helpers, runtimes, plugins, or build infrastructure.
 - Delete obsolete compatibility layers, helper indirection, and unused packages when safe.
 
 ## Workflow
 
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+- If you changed any app `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
+```
+cd <worktree path>
+npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
+```
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
-- When starting a long-lived reference app dev server for framework work, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
+- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- Do not use `--replace-existing` unless you are restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
+- When a reference app uses local `file:` connected projects for the affected flow, boot every connected producer app as well, each on its own free port and thread-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or validating the consumer app.
 - Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
 - If the task changed the dev workflow itself, verify the final cleanup path with `npx proteum dev list --json` before finishing.
-- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
-```
-Commit message: <type>[optional scope]: <description>
+- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence ALL the changes you made since the beginning of the WHOLE conversation. Strictly use the Conventional Commits specification:
+  ```
+  Commit message: <type>[optional scope]: <description>
 
-[optional body]
-```
+  [optional body]
+  ```
+  If the user replies exactly `commit`, use that Conventional Commit message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, then create the commit by running `git commit`.
+  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 Changes
 
@@ -44,9 +55,9 @@ Commit message: <type>[optional scope]: <description>
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/product`
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
-- Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
-- Keep core changes aligned with the explicit controller/page architecture in `agents/project/AGENTS.md`.
+- Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
+- Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.
 - Remove dead docs, flags, helper files, and compatibility branches in the same pass when safe.
@@ -64,13 +75,16 @@ Commit message: <type>[optional scope]: <description>
 
 Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
 
-- Run `npx proteum dev --no-cache --replace-existing --session-file var/run/proteum/dev/framework-<app>.json --port 3xxx` in both reference apps on explicit ports.
+- Run `npx proteum dev --no-cache --session-file var/run/proteum/dev/framework-<app>.json --port <free-3xxx-port>` in both reference apps on explicit free ports and with elevated permissions outside the sandbox.
+- If either reference app uses local `file:` connected projects for the affected flow, run those producer apps too on their own free ports before exercising the consumer.
 - When validating a concrete route, controller path, or failing page on a running dev server, prefer `proteum diagnose <path> --port <port>` first. Use raw `proteum trace ...` output when you need lower-level event detail beyond the diagnose summary.
 - When the issue is latency, CPU, SQL cost, render cost, or memory drift, inspect `proteum perf top`, `proteum perf request`, `proteum perf compare`, or `proteum perf memory` against the running dev server before adding custom instrumentation.
 - When a framework change can affect shipped client code size, run `proteum build --prod --analyze` for static bundle artifacts or `proteum build --prod --analyze --analyze-serve --analyze-port auto` when you need a local analyzer URL.
 - For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` to mint a dev auth cookie instead of automating the login UI. Use the login UI only when login itself is the feature under test.
+- When a task needs browser execution instead of the higher-level verifier, prefer `npx proteum verify browser <path>` or direct Playwright with a disposable profile. Keep auth sourced from `npx proteum session`, not UI login or shared browser state.
 - For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
 - When the framework-facing workflow itself changed, verify the CLI surface too with `proteum verify framework-change --crosspath-port <port> --product-port <port> --website-port <port>`.
+- Only the final verifier agent should usually run browser flows. Other agents should stay on `orient`, `verify owner`, `verify request`, and command-level checks unless browser execution is the only trustworthy surface.
 - Open the real pages with Playwright.
 - Inspect browser console errors and warnings.
 - Inspect server startup and runtime errors.

package/README.md

@@ -4,6 +4,8 @@ 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)
+
 ## Why Proteum
 
 Most full-stack frameworks optimize first for human convenience.
@@ -24,7 +26,7 @@ Proteum combines:
 
 ## Core Principles
 
-- **Server-first by default.** Put data loading in the page setup function and keep client code focused on UI.
+- **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)`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
@@ -69,7 +71,7 @@ Important files:
 - `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(...)`
+- `client/pages/**`: SSR page entrypoints registered through `Router.page(path, options, data, render)`
 - `server/controllers/**`: request handlers that extend `Controller`
 - `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
@@ -192,9 +194,11 @@ import Router from '@/client/router';
 
 Router.page(
   '/',
+  {
+    auth: false,
+    layout: false,
+  },
   ({ Plans, Stats }) => ({
-    _auth: false,
-    _layout: false,
     plans: Plans.getPlans(),
     stats: Stats.general(),
   }),
@@ -207,9 +211,10 @@ Router.page(
 What happens here:
 
 - the first argument is the route path
-- the optional setup function runs on the server for SSR data loading
-- keys prefixed with `_` become route options such as `_auth`, `_layout`, `_static`, or `_redirectLogged`
-- every other returned key becomes page data
+- the second argument is the explicit route-options object
+- the third argument is the page data function or `null`
+- 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
 
 ## Example: Controller
@@ -334,6 +339,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
 | `proteum verify` | Validate framework-facing workflows across one or more running dev apps; `framework-change` is the built-in cross-reference-app check |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
+| `proteum configure agents` | Interactively configure Proteum-managed instruction symlinks and confirm overwrites for standalone or monorepo apps |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
 Recommended daily workflow:
@@ -347,7 +353,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
+Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
 
 Useful inspection commands:
 
@@ -383,11 +389,14 @@ Useful scaffolding commands:
 ```bash
 proteum init my-app --name "My App"
 proteum init my-app --name "My App" --dry-run --json
+proteum configure agents
 proteum create page marketing/faq --route /faq
 proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
+`proteum configure agents` asks before replacing any existing non-managed instruction file or foreign symlink. If you decline, that path is left untouched.
+
 `proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md) and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands
@@ -512,7 +521,7 @@ If you are an LLM or automation agent, start here:
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.
 6. Inspect `server/services/**` for business logic.
-7. Inspect `client/pages/**` for SSR routes and page setup contracts.
+7. Inspect `client/pages/**` for SSR routes and page data contracts.
 8. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum session <email> --role <role>` before Playwright or direct HTTP calls.
 
 For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
@@ -576,6 +585,7 @@ Then use the normal workflow:
 
 ```bash
 npm install
+npx proteum configure agents
 npx proteum dev
 npx proteum check
 npx proteum build --prod

package/agents/project/AGENTS.md

@@ -1,45 +1,71 @@
 # Proteum Project Contract
 
-This is the canonical contract for Proteum-based projects shipped with Proteum. Narrower `AGENTS.md` files in this folder add area-specific rules on top of this file.
-Role: keep only project-wide app rules here.
+This is the canonical standalone-app contract for Proteum-based projects shipped with Proteum. Narrower `AGENTS.md` files in this folder add area-specific rules on top of this file.
+When splitting instructions across a monorepo, put the Proteum-wide rules in the monorepo-root `AGENTS.md` and keep only app-root-specific additions in each Proteum app root `AGENTS.md`.
+Role: keep only project-wide app rules here when one root `AGENTS.md` must carry both the reusable Proteum contract and the app-root addendum.
 Keep here: cross-cutting project workflow, architecture contracts, shared typing rules, and rules that apply across client, server, pages, and tests.
 Do not put here: detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `diagnostics.md`, `optimizations.md`, `CODING_STYLE.md`, `client/AGENTS.md`, `client/pages/AGENTS.md`, `server/routes/AGENTS.md`, `server/services/AGENTS.md`, or `tests/AGENTS.md`.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
-Coding style source of truth: project-root `CODING_STYLE.md`.
+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`.
 
-## Workflow
+## Fast Triggers
 
-- At the beginning of every task, acknowledge the applicable optimization, diagnostics, and coding-style sources before analyzing or editing code: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
+- 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`.
+  - 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`, and keep it running so user can see the results by himself.
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
-- Follow project-root `diagnostics.md` for diagnosis, runtime reproduction, temporary instrumentation, error-solving workflow, and verification method selection.
-- For 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.
-- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- When starting a long-lived dev server for an agent task, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
-- Do not start a second `proteum dev` server for the same app and port until the earlier tracked session has been stopped or replaced.
-- When framework work changes Proteum CLI commands, profiler panels/features, or the `proteum dev` banners, keep this file, project-root `diagnostics.md`, and any narrower area `AGENTS.md` that mentions the same workflow aligned with the live framework behavior in the same pass.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
-- Before finishing, double-check the touched files and generated output against the applicable optimization, diagnostics, and coding-style sources: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
-- After implementing any feature or behavior change, always verify it on a running app before finishing: start the server, exercise the affected flow with Playwright or the smallest real runtime or `npx proteum` surface, run the relevant diagnostics or perf commands, and confirm there is no meaningful regression in behavior, performance, bundle/load size, SEO output, or coding style.
-- 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, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
-```
-Commit message: <type>[optional scope]: <description>
-
-[optional body]
-```
+- If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
+- 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, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+- 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.
+- If you changed `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
+  ```
+  cd <worktree path>
+  npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
+  ```
+- If you encounter `runtime/provider-hook-outside-provider`, `runtime/client-only-hook-in-ssr`, `runtime/router-context-outside-router`, or `runtime/connected-boundary-mismatch`, treat it as a framework contract failure first. Fix the provider, SSR/client, router, or connected boundary before assuming a local leaf-component bug.
+- If the change is runtime-visible, request-time, router, SSR, browser-visible, or controller-behavior, use running-app verification.
+- If the change is docs-only, wording-only, type-only, test-only, generated-output cleanup, or a clearly local non-runtime refactor, use static verification only unless the user explicitly asks for runtime verification or the agent finds a real issue.
+- If the user replies exactly `commit`, generate one top-level short (up to 100 characters) sentence covering all changes made since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation, strictly using the Conventional Commits specification:
+  ```
+  <type>[optional scope]: <description>
+
+  [optional body]
+  ```
+  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  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.`
+
+## Task Lifecycle
+
+### Before Editing
+
+- Before changing any file, load root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applies to the touched files. Do not spend response space explicitly acknowledging those reads unless the user asks.
+
+### During Implementation
 
-## Project Shape
+- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
+- If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
+- For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
 
-This is a TypeScript, Node.js, Preact, Proteum monolith:
+### Before Finishing
 
-- `/client`: assets, catalogs, components, hooks, pages
-- `/common`: shared functions, constants, types, and catalogs
-- `/server`: catalogs, config, services, routes, lib
-- `/tests`
+- Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
+- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- 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.`
 
-## Non-Negotiable Rules
+## 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.
@@ -48,11 +74,12 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - 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.
-- Follow project-root `optimizations.md` for bundle size, performance, SEO, and SSR page-size rules.
 - 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.
 - Never edit generated files under `.proteum`.
+- When a task changes database structure, edit the app's `schema.prisma` only.
+- Never create or edit migration files manually.
 - Use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
 - Client context is typically imported from `@/client/context`.
 - Normal service methods do not read request state directly.
@@ -61,63 +88,7 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - Do not use `@app` on the client.
 - Prefer type inference rooted in the explicit application graph in `server/index.ts`.
 
-## Source Of Truth
-
-Proteum reads:
-
-- `package.json`
-- `identity.config.ts` for app identity via `Application.identity({ ... })`
-- `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
-- `server/config/*.ts`
-- `server/index.ts`
-- `commands/**/*.ts`
-- `server/controllers/**/*.ts`
-- `server/routes/**/*.ts`
-- `client/pages/**/*.ts(x)`
-- `client/pages/**/_layout/index.tsx`
-- `public/**`
-
-Proteum owns:
-
-- `.proteum/manifest.json`
-- `.proteum/client/*`
-- `.proteum/common/*`
-- `.proteum/server/*`
-
-Project code should consume:
-
-- `@generated/client/*`
-- `@generated/common/*`
-- `@generated/server/*`
-- `@/client/context` as the generated client context entrypoint
-
-Prefer structured CLI surfaces over re-deriving framework facts from source:
-
-- `npx proteum connect --json`
-- `npx proteum connect --controllers --strict`
-- `npx proteum explain --json`
-- `npx proteum explain --connected --controllers`
-- `npx proteum explain owner <query>`
-- `npx proteum doctor --json`
-- `npx proteum doctor --contracts --json`
-- `npx proteum diagnose <path> --port <port>`
-- `npx proteum perf ...`
-- `npx proteum trace ...`
-- `npx proteum command ...`
-- `npx proteum session ...`
-- `npx proteum create ... --dry-run --json`
-- `npx proteum dev list --json`
-- `npx proteum dev stop --session-file <path>`
-
-Prefer scaffold commands before hand-writing boilerplate:
-
-- Use `npx proteum init <directory> --name <name>` for new apps.
-- Use `npx proteum init ... --dry-run --json` when an agent needs a machine-readable app plan before writing files.
-- Use `npx proteum create page|controller|command|route|service <target>` for new app artifacts before creating the files manually.
-- Use `npx proteum create ... --dry-run --json` when an agent needs a machine-readable artifact plan before writing files.
-
-## File Contracts
+## Surface Contracts
 
 ### App Bootstrap And Services
 
@@ -138,6 +109,7 @@ Prefer scaffold commands before hand-writing boilerplate:
 - Declare connected namespaces in `proteum.config.ts` with explicit values such as `connect: { Product: { source: PRODUCT_CONNECTED_SOURCE, urlInternal: PRODUCT_URL_INTERNAL } }`.
 - Proteum does not infer connected env key names from the namespace. The source and internal URL must be provided explicitly in `proteum.config.ts`.
 - Use `npx proteum connect` to inspect configured connect values, cached contract state, and imported controllers for the current app.
+- Before launching a consumer app that depends on local `file:` connected sources, launch every connected producer app too, assign each one a free port, run each `proteum dev` outside the sandbox with elevated permissions, and make sure `connect.<Namespace>.urlInternal` resolves to those live producer URLs.
 - `file:` connected sources point at another Proteum app root and keep strong connected typings.
 - Non-local connected sources provide runtime helper generation but are intentionally typed loosely.
 
@@ -164,14 +136,14 @@ Prefer scaffold commands before hand-writing boilerplate:
 
 - 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.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
-- `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
-- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
+- The only supported page signature is `Router.page(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/**`.
-- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
 
 ### Manual Routes
 
@@ -193,15 +165,31 @@ Prefer scaffold commands before hand-writing boilerplate:
   - `@app`: server-side application services for manual routes only
   - `@generated/*`: generated app surfaces
 
-## Dependency Selection
+## Verification Matrix
+
+Verify at the correct layer:
+
+- Default: use the cheapest trustworthy verification for the changed surface first, then escalate only if the changed surface justifies it.
+- Route additions: boot the app and hit the real URL.
+- Controller changes: exercise the generated client call or generated `/api/...` endpoint.
+- SSR changes: 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.
+- Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
+- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
+- Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
+- For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
+
+## Implementation Rules
+
+### Dependency Selection
 
 - Before implementing a feature or change, first check whether the repo already includes a suitable dependency.
 - If not, search npm before building a new utility, abstraction, component primitive, parser, formatter, or integration from scratch.
 - Prefer the most popular, flexible, maintained packages that fit the project constraints.
-- Follow project-root `optimizations.md` when deciding whether custom infrastructure is justified over an existing package.
+- When the task explicitly involves client-side optimization work, use root-level `optimizations.md` to decide whether custom infrastructure is justified over an existing package.
 - When you choose custom over a package, explain the reason briefly.
 
-## Catalogs And Typing
+### Catalogs And Typing
 
 - Keep one canonical catalog or registry file and import it everywhere else.
 - Client-only catalogs live in `/client/catalogs/**`, server-only catalogs in `/server/catalogs/**`, and shared catalogs in `/common/catalogs/**`.
@@ -211,7 +199,7 @@ Prefer scaffold commands before hand-writing boilerplate:
 - Fix typing issues only on code you wrote.
 - Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 
-## Design Rules
+### Design Rules
 
 - Prefer explicit `server/index.ts` bootstrap over hidden registration.
 - Prefer controller-backed app APIs over ad hoc manual `/api/...` routes.
@@ -219,25 +207,93 @@ Prefer scaffold commands before hand-writing boilerplate:
 - Keep one canonical source of truth for catalogs, registries, and shared types.
 - Reuse shared Shadcn-based UI primitives when the project already provides them.
 
-## Discouraged Patterns
+### Discouraged Patterns
 
 - request-scoped state inside normal service methods
 - hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
 - editing `.proteum` directly
 
-## Verification
+## Hard Stops
 
-Verify at the correct layer:
+- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
+- Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
+- Do not run `git restore` or `git reset`.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows only task-scoped `git add` and `git commit`. Any other write-mode git action requires an explicit user request.
 
-- route additions: boot the app and hit the real URL
-- controller changes: exercise the generated client call or generated `/api/...` endpoint
-- SSR changes: 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
-- For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow project-root `diagnostics.md`.
+## Appendix
 
-Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `proteum dev list --json`, `proteum dev stop --session-file <path>`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum build --prod --analyze`, `npx proteum build --prod --analyze --analyze-serve --analyze-port auto`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
+### Project Shape
 
-## High-Impact Files
+This is a TypeScript, Node.js, Preact, Proteum monolith:
+
+- `/client`: assets, catalogs, components, hooks, pages
+- `/common`: shared functions, constants, types, and catalogs
+- `/server`: catalogs, config, services, routes, lib
+- `/tests`
+
+### Source Of Truth
+
+Proteum reads:
+
+- `package.json`
+- `identity.config.ts` for app identity via `Application.identity({ ... })`
+- `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `server/config/*.ts`
+- `server/index.ts`
+- `commands/**/*.ts`
+- `server/controllers/**/*.ts`
+- `server/routes/**/*.ts`
+- `client/pages/**/*.ts(x)`
+- `client/pages/**/_layout/index.tsx`
+- `public/**`
+
+Proteum owns:
+
+- `.proteum/manifest.json`
+- `.proteum/client/*`
+- `.proteum/common/*`
+- `.proteum/server/*`
+
+Project code should consume:
+
+- `@generated/client/*`
+- `@generated/common/*`
+- `@generated/server/*`
+- `@/client/context` as the generated client context entrypoint
+
+### Useful Commands
+
+Prefer structured CLI surfaces over re-deriving framework facts from source:
+
+- `npx proteum connect --json`
+- `npx proteum connect --controllers --strict`
+- `npx proteum orient <query>`
+- `npx proteum explain --json`
+- `npx proteum explain --connected --controllers`
+- `npx proteum explain owner <query>`
+- `npx proteum doctor --json`
+- `npx proteum doctor --contracts --json`
+- `npx proteum diagnose <path> --port <port>`
+- `npx proteum verify owner <query>`
+- `npx proteum verify request <path>`
+- `npx proteum verify browser <path>`
+- `npx proteum perf ...`
+- `npx proteum trace ...`
+- `npx proteum command ...`
+- `npx proteum session ...`
+- `npx proteum create ... --dry-run --json`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file <path>`
+
+Prefer scaffold commands before hand-writing boilerplate:
+
+- `npx proteum init <directory> --name <name>`
+- `npx proteum init ... --dry-run --json`
+- `npx proteum create page|controller|command|route|service <target>`
+- `npx proteum create ... --dry-run --json`
+
+### High-Impact Files
 
 Edit these only when required, and keep changes minimal and explicit:
 
@@ -245,14 +301,3 @@ Edit these only when required, and keep changes minimal and explicit:
 - `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
 - Prisma-generated files
 - symbolic links
-
-## Commands Not To Run
-
-- `git restore`
-- `git reset`
-- `prisma *`
-- any write-mode git command
-
-## Product And UX Docs
-
-If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist.

package/agents/project/CODING_STYLE.md

@@ -17,7 +17,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', setup, render);`.
+- Keep `Router.page(...)` and `Router.error(...)` registrations in the compact inline-call shape when possible, for example `Router.page('/path', {}, null, render);`.
 
 ## File organization
 

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

@@ -0,0 +1,16 @@
+# Proteum App-Root Addendum
+
+This file is the app-root-only addendum for a Proteum app that lives inside a larger monorepo.
+Keep the reusable Proteum contract in the nearest ancestor root `AGENTS.md`, and keep this file only for instructions that depend on the current directory being the Proteum app root.
+Role: keep only app-root workflow and local project-semantic rules here.
+Do not put here: reusable Proteum architecture contracts, shared verification rules, diagnostics workflow, optimization checklists, coding-style details, or area-specific rules already covered by broader `AGENTS.md` files or the root-level `diagnostics.md`, `optimizations.md`, and `CODING_STYLE.md`.
+
+## 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`.
+  - 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`, and keep it running so user can see the results by himself.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.