proteum 2.5.8 → 2.5.10

package/agents/project/AGENTS.md

@@ -1,87 +1,116 @@
 # Proteum Project Contract
 
-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.
+This is the canonical project 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: cross-cutting project workflow, architecture contracts, and rules that apply across client, server, pages, and tests.
 Do not put here: documentation-driven coding workflow, detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `DOCUMENTATION.md`, `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`.
+Every rule has exactly one canonical home. When another section or file needs a rule defined elsewhere, it points to the canonical home instead of restating it.
 
 Documentation source of truth: root-level `DOCUMENTATION.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`.
+Coding style source of truth: root-level `CODING_STYLE.md` (style, formatting, file organization, typing, comments).
 
 Managed compact root routers must use trigger -> canonical instruction file references, not copied summaries of this contract. If a trigger points here, load this full file before acting and keep the source rule here.
 
 ## Fast Triggers
 
-- If `cwd` is inside `/.codex/worktrees/`, run Worktree Preflight before implementation:
-  - 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:
-  - Run `npx proteum worktree init --source <source-app-root>`.
-  - Read and acknowledge the applicable `AGENTS.md` files.
-  - 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
-    - re-print the complete list of suggested fixes, but strike the ones we already implemented or not necessary anymore
+- If `cwd` is inside `/.codex/worktrees/` or you are working in a newly created Proteum worktree, run the `Worktree Preflight` in `Task Lifecycle` before implementation.
+- If the user pastes raw errors without asking for a fix, do not implement changes yet. Reproduce locally first using the `Initial Triage` workflow in root-level `diagnostics.md`, 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 the analysis, and give a comparison table of before and after
+  - re-print the complete list of suggested fixes, but strike the ones already implemented or no longer necessary
 - If the user asks to implement a feature, first inspect the relevant existing surface and state any implementation problem, pain point, attention point, inconsistency, missing information, or question you see. If anything needs clarification or a decision, pause before editing, ask the user what decision to take, and resume only after the user answers.
-- If the task is ambiguous, generated, connected, or multi-repo, start with MCP `workflow_start` and then MCP `orient { projectId, query }` only if the bootstrap did not return a sufficient owner or next action; use `npx proteum orient <query>` only when MCP is unavailable or terminal evidence is required.
-- Treat Proteum CLI and MCP output as the workflow router. Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
-- 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, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, 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.
+- If the task is ambiguous, generated, connected, or multi-repo, follow `MCP Orientation`.
 - 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 user reports an issue, or you encounter 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.
 - 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 changed `schema.prisma`, stop before testing or validation and follow the migration rule in `Hard Stops`.
 - 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>
+- If the change is runtime-visible, request-time, router, SSR, browser-visible, or controller-behavior, use running-app verification per the `Verification Matrix`.
+- If a new feature is visible in the UI or browser, run the mandatory browser MCP pass defined in the `Verification Policy` before finishing.
+- 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 you find a real issue.
+- If the user replies exactly `commit`, follow `Commit Workflow`.
 
-  [optional body]
-  ```
-  Then treat `commit` as conversation-wide and cross-project, not task-scoped. For downstream Proteum apps, before staging or committing, run only this commit-time verification: `proteum refresh`, then the targeted lint, typecheck, and test commands that match the conversation changes in parallel. Skip this downstream app verification when the affected repository is the Proteum framework repository itself; use the framework repo `AGENTS.md` commit workflow there. Do not run coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or any other check unless the user explicitly asks for it in the same request. Report any blocker instead of committing through failed commit-time verification. 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.`
+## MCP Orientation
+
+Treat Proteum CLI and MCP output as the workflow router.
+
+- When a Proteum MCP client is available, call MCP `workflow_start` first, with `cwd` or a known `projectId`.
+- If `workflow_start` is ambiguous or returns offline app candidates: call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, 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.
+- 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, and 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.
+- Treat instruction previews returned by MCP `workflow_start` or `instructions_resolve { projectId }` as the allowed instruction scope for read-only discovery and diagnostics. Read full file contents only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the compact preview is insufficient. Do not read broad instruction folders or every managed instruction file up front.
+- MCP payloads are compact single-line `proteum-mcp-v1` JSON with capped and paginated detail. Do not expand MCP output for human readability.
+- During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands.
+- For route/page/controller ownership, prefer `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
+- `npx proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon.
+- Use CLI commands such as `npx proteum orient <query>` when MCP is unavailable, when terminal evidence is required, or when you need reproducible terminal validation, dev/build/check workflows, fallback repair, or output to share with a human.
 
 ## Task Lifecycle
 
+### Worktree Preflight
+
+- Run `npx proteum worktree init --source <source-app-root>` when the bootstrap marker is missing, or add `--refresh` when Proteum reports stale bootstrap state.
+- Use `--skip-deps --reason "..."` only when dependency installation is intentionally skipped.
+- Read and acknowledge the applicable `AGENTS.md` files.
+- Run `npx proteum runtime status`.
+- For runtime-visible work, start or reuse one tracked `npx proteum dev` session using the launch workflow in `During Implementation`, keep it running so the user can see the results, and print the live server URL as a clickable Markdown link.
+
 ### Before Editing
 
-- Before editing in a `.codex/worktrees` worktree, complete Worktree Preflight from Fast Triggers.
+- Complete `Worktree Preflight` when working inside a `.codex/worktrees` worktree.
 - 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
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
 - If any inconsistency, ambiguity, conflicting source, missing information, or implementation detail needing clarification appears while coding, stop editing immediately, ask the user what decision to take, and resume only after the user answers. Do not silently choose a default or keep implementing under a guessed assumption.
-- 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 runtime status` first, then use its exact Start Dev next action so occupied router/HMR ports are avoided. Do not `curl` normal page routes to identify a port owner; use Proteum runtime status or dev-only `/__proteum/*` endpoints. After the server is ready, print the live server URL as a clickable Markdown link.
+- 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 runtime status` first, then use its exact Start Dev next action so occupied router/HMR ports are avoided.
+  - Do not `curl` normal page routes to identify a port owner; use Proteum runtime status or dev-only `/__proteum/*` endpoints.
+  - After the server is ready, print the live server URL as a clickable Markdown link.
 - 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.
-- Do not start a second `npx proteum dev` server in the same worktree, and do not start a second managed MCP daemon. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root; if no live session exists, use the exact MCP offline or runtime-status next action instead of assuming the manifest default port. 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. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
+- Do not start a second `npx proteum dev` server in the same worktree. If MCP routing fails, the runtime is unreachable, or an untracked runtime already answers on the configured port, follow the `Runtime Diagnostics` repair workflow in root-level `diagnostics.md` instead of starting another server.
 - 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.
-- During `npx proteum dev`, the app exposes the read-only Proteum MCP runtime endpoint at `/__proteum/mcp`; use it for repeated agent reads instead of spawning equivalent diagnostics commands. For route/page/controller ownership, prefer MCP `workflow_start`, `route_candidates { projectId, query }`, or `explain_summary { projectId, query }` over broad `npx proteum explain --routes --controllers --full` dumps.
-- For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Bootstrap protected browser MCP state with `npx proteum session`; bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
-- 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 welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. 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. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
+- For browser validation, use the browser MCP against the running app. Keep Playwright inside `npx proteum e2e --port <port>` for targeted/full end-to-end suites. Before every browser MCP pass, bootstrap the browser with the project instructions' admin account via `npx proteum session <admin-email> --role GOD` or its `browserLoginUrl`, unless the task is explicitly testing auth, login, anonymous, or non-admin behavior. If the project instructions do not declare an admin email for local validation, stop and ask before running the browser pass. Bootstrap protected E2E runs with `npx proteum e2e --session-email <email> --session-role <role>`.
 
 ### 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.
+- Re-check touched files against root-level `CODING_STYLE.md`, including its self-check list, and any narrower area `AGENTS.md` that applied to the edit. Re-check root-level `optimizations.md` only for touched client-side files. Re-check root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
+- Scan the final diff for missing decision comments: every non-obvious choice, workaround, magic value, and bug fix must carry a why-comment per the `Decision and context comments` section of `CODING_STYLE.md`. A missing why-comment is a defect to fix before finishing, not optional polish.
 - 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. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient. Continue running tests after changes, but do not run coverage by default. Downstream app commit workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. 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.
-- 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:
+- Apply the `Verification Policy` to the changed surface.
+- When you have finished your work, ask the user whether they want a commit message, then follow `Commit Workflow`.
+
+## Commit Workflow
+
+This is the canonical git workflow. It applies when the user replies exactly `commit`, and after any commit message you provide.
+
+- Scope: conversation-wide and cross-project, not task-scoped. Cover all changes made since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation.
+- Splitting: default to one commit per affected repository or worktree. When the covered changes span clearly separable concerns — independent features, an unrelated fix, a refactor separable from a behavior change — create one commit per concern in that repository, each staging only the files that belong to it. Do not split when the changes only make sense together.
+- Message: one top-level short sentence (up to 100 characters) per commit, covering that commit's changes, strictly using the Conventional Commits specification:
+  ```
+  <type>[optional scope]: <description>
+
+  [optional body]
+  ```
+- Commit-time verification, before staging or committing:
+  - Downstream Proteum apps: run only `proteum refresh`, then the targeted lint, typecheck, and test commands that match the conversation changes, in parallel.
+  - The Proteum framework repository itself: skip the downstream verification above and use the framework repo `AGENTS.md` commit workflow.
+  - Do not run coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or any other check unless the user explicitly asks for it in the same request.
+  - Report any blocker instead of committing through failed commit-time verification.
+- Staging and committing:
+  - 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 avoiding unrelated pre-existing user changes and incidental untracked files.
+  - Create one `git commit` per affected repository or worktree, or several per repository when the splitting rule above applies.
+  - 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.`
 
 ## Core Contracts
@@ -93,9 +122,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - Manual HTTP endpoints live only in `server/routes/**`.
 - 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.
+- File organization, typing, formatting, and commenting rules live in root-level `CODING_STYLE.md`.
 - 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.
@@ -268,17 +295,31 @@ export default defineServerRoute({
   - `@client/...`, `@server/...`, `@common/...`: Proteum core modules
   - `@generated/*`: generated app surfaces
 
-## Verification Matrix
+## Verification
+
+### Verification Policy
+
+This is the canonical post-change verification policy. Other instruction files point here instead of restating it.
+
+- Use the cheapest trustworthy verification that matches the changed surface, including targeted tests for changed behavior.
+- When the repository defines `proteum.verify.config.ts`, run `npx proteum verify changed` as the first post-change verification pass and expand only when the selected plan is insufficient.
+- Applicable production changes must always add or update focused unit tests and run the targeted unit or integration tests that match the changed behavior. Document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions in the completion note.
+- After implementing a new feature that is visible in the UI or browser, run a browser MCP pass against the real page before finishing. This is mandatory even when `npx proteum verify changed`, request diagnostics, lint, or typecheck pass; inspect the rendered page, the primary interaction or state, browser console output, and relevant server output for blocking errors.
+- After implementing a new feature or changing existing feature behavior, update the relevant end-to-end coverage. Run targeted `npx proteum e2e --port <port> ...` when the behavior needs automated browser assertions or journey coverage.
+- For docs-only, wording-only, type-only, test-only, generated-output cleanup, or clearly local non-runtime refactors, use static verification only and skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
+- Do not run coverage by default after ordinary changes. Reserve whole-project coverage and the full `npm run check` gate for push workflows, explicit user requests, or when project-local instructions require the full gate.
+- Commit-time verification is defined in `Commit Workflow`.
+
+### Verification Matrix
 
 Verify at the correct layer:
 
-- Default: use the cheapest trustworthy verification for the changed surface, including targeted tests for changed behavior. When `proteum.verify.config.ts` exists, start with `npx proteum verify changed`. Do not run coverage by default during ordinary change closeout.
 - Route additions: boot the app and hit the real URL.
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
+- New UI-visible features: run the mandatory browser MCP pass against the real page before finishing, using the project instructions' admin account through `npx proteum session <admin-email> --role GOD` or the emitted `browserLoginUrl` before opening the page unless the scenario is explicitly auth, anonymous, or non-admin.
 - 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 and run the relevant end-to-end coverage. During downstream app commit workflows, run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; skip this verification for framework-repo commits and reserve 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.
+- Generated, connected, or ownership-ambiguous changes: follow `MCP Orientation`; 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.
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
@@ -293,16 +334,12 @@ Verify at the correct layer:
 - 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
 
 - 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/**`.
 - Do not create nested `catalogs/` folders under pages, components, services, tests, or other feature folders.
-- Keep strong TypeScript typings across the project.
-- Do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
-- Do not use `Reflect.get`, bracket access, broad `in` checks, or local loose reader helpers to bypass missing typings for app-owned data; fix the type contract or normalize once with a typed adapter at the boundary.
-- Fix typing issues only on code you wrote.
-- Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
+- Typing rules, including the ban on `any`, `unknown`, and loose casts, live in root-level `CODING_STYLE.md`.
 
 ### Design Rules
 
@@ -322,9 +359,41 @@ 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.
 - 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 `prisma *` yourself. 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>
+  ```
 - 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 after the applicable commit-time verification succeeds. For downstream apps, commit-time verification is limited to `proteum refresh`, then targeted lint, typecheck, and test commands in parallel. For the Proteum framework repository itself, skip this downstream app verification and use the framework repo `AGENTS.md` commit workflow. This exception does not allow coverage, full `npm run check`, repository `check:commit`, unrelated broad suites, or other checks unless the user explicitly requests them in the same message. 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.
+- Do not run write-mode git commands by default. The only built-in exception is the exact `commit` reply handled by `Commit Workflow`, which allows `git add` and `git commit` after its commit-time verification succeeds. 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.
+
+## Delivery Workflow
+
+Agents working in generated Proteum projects must use this delivery workflow for production code changes:
+
+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, recording non-obvious decisions as why-comments per `CODING_STYLE.md` while the reasoning is still in context.
+4. Targeted validation: refresh generated framework contracts after route, page, controller, service, command, or config changes, then apply the `Verification Policy` to the changed surface.
+5. Validate unit + E2E: run the relevant unit tests and real-world journey E2E checks before calling the work complete.
+
+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.
+
+Recommended validation sequence:
+
+```bash
+npm run refresh
+npm run typecheck
+npm run lint
+npm run test
+npm run test:integration
+npx proteum check
+npx proteum doctor --contracts --strict
+npx proteum e2e --port <port>
+```
+
+When bundling, SSR, server startup, routing, or build-time behavior changes, also run the project build command before finishing.
 
 ## Appendix
 
@@ -411,32 +480,3 @@ Edit these only when required, and keep changes minimal and explicit:
 - `PORT`, `ENV_*`, `URL`, `TRACE_*`, and `ENABLE_PROFILER` env setup
 - Prisma-generated files
 - symbolic links
-
-## Delivery Workflow
-
-Agents working in generated Proteum projects must use this delivery workflow for production code changes:
-
-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. 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 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; downstream app commit-only workflows run `proteum refresh`, then targeted lint, typecheck, and test commands in parallel unless the user explicitly requests more, while framework-repo commits skip this downstream app verification. 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.
-
-Recommended validation sequence:
-
-```bash
-npm run refresh
-npm run typecheck
-npm run lint
-npm run test
-npm run test:integration
-npx proteum check
-npx proteum doctor --contracts --strict
-npx proteum e2e --port <port>
-```
-
-When bundling, SSR, server startup, routing, or build-time behavior changes, also run the project build command before finishing.

package/agents/project/CODING_STYLE.md

@@ -1,18 +1,21 @@
 # Coding style
 
-This file is the source of truth for codex coding style instructions in Proteum-based projects.
+This file is the canonical coding-style contract for Proteum-based projects. It is loaded before editing any implementation file and re-checked before finishing. Keep workflow, verification, and architecture rules in `AGENTS.md`; keep only style, typing, formatting, and commenting rules here.
 
 ## Baseline
 
-- **The code should be at the highest level of industry, as the product will be used by GAFAMs and will be maintained by a team of 10 developers.**
+- Write code so the next reader — human or agent, with none of the current conversation's context — can recover every decision from the code and its comments.
 - Write clean, consistent, readable code with a tab size of 4.
-- Keep functions and methods short.
-- Every time possible, create reusable functions and components instead of repeating.
-- Before finishing a feature or change, review touched files against this document and run targeted lint/typecheck/tests for the changed surface. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` as the first post-change verification pass. Do not run coverage by default after ordinary changes. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. 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.
+- Keep functions and methods short; extract a helper once a block needs its own explanation.
+- Create reusable functions and components instead of repeating logic.
+- Coding-style regressions are defects, not optional cleanup.
 
 ## Type safety
 
+- Keep strong TypeScript typings; do not introduce `any` or `unknown`, including through casts, helper aliases, or fallback generic defaults.
+- Never cast with `as any` or `as unknown`; fix the contract or add one explicit typed adapter at the boundary.
 - Do not use `Reflect.get`, bracket access, broad `in` checks, or local loose reader helpers to bypass missing typings for app-owned data; fix the type contract or normalize once with a typed adapter at the boundary.
+- Fix typing issues only on code you wrote.
 
 ## Formatting
 
@@ -30,7 +33,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - The default `*.ts` / `*.tsx` file is the browser implementation; use `*.ssr.ts` / `*.ssr.tsx` only for SSR-safe fallbacks.
 - When implementing a feature that relies on a curated list of items, keep one canonical catalog or registry file and make all other code import it.
 
-## Section comments and simple comments
+## Section comments
 
 - Organize files with explicit banner comments:
 
@@ -40,38 +43,37 @@ This file is the source of truth for codex coding style instructions in Proteum-
 ----------------------------------*/
 ```
 
-- Reuse project-native section names when possible, especially:
-  - `DEPENDANCES`
-  - `TYPES`
-  - `HELPERS`
-  - `CONSTANTS`
-  - `COMPONENT`
-  - `SERVICE`
-  - `CONTROLEUR`
-  - `ROUTES`
-  - `PAGE`
-  - `CONFIG`
-  - `PUBLIC API`
-  - `API`
-  - `HOOKS`
-  - `LAYOUT`
-  - `CLASS`
-  - `MODULE`
-  - `STATE`
-  - `CONTEXT`
-  - `QUERIES`
-  - `SCHEMA`
-  - `SCHEMAS`
-  - `ROUTING`
-  - `RENDER`
-  - `EXPORTS`
-  - `UTILS`
-  - `CONTENT`
-  - `FILTERS`
-  - `STATS`
-  - `BUILDERS`
-  - `CATALOG`
-  - `CATALOG (SSOT)`
+- Reuse the section names already used in the touched file or area first. Common project-native names include `DEPENDANCES`, `TYPES`, `CONSTANTS`, `HELPERS`, `SERVICE`, `CONTROLEUR`, `COMPONENT`, `HOOKS`, `STATE`, `CONFIG`, `ROUTES`, `RENDER`, `PUBLIC API`, `EXPORTS`, and `CATALOG (SSOT)`.
 - File-specific section names are allowed when they improve navigation, for example `ROUTE: ...`, `COMPONENT: ...`, or `VIEW: ...`.
-- Add short, useful comments that explain grouping, intent, lifecycle, or why a block exists.
-- Do not add noisy comments that simply restate obvious code.
+
+## Decision and context comments
+
+Comments are the project's in-place memory: they carry decisions and constraints to the next agent or developer, who will have none of the current context. The code says what; comments say why.
+
+- Comment every non-obvious implementation choice at the decision site: why this approach, which constraint forced it, and which alternative was rejected and why when a real alternative was considered.
+- When fixing a bug, comment the invariant that must not regress next to the fixed code, and reference the fix note under `docs/fixes/**` when one exists.
+- A workaround must name what it works around (dependency and version, upstream issue, browser or runtime quirk) and the condition under which it can be removed.
+- Comment magic values, ordering requirements, timing assumptions, and intentional deviations from this document where they occur.
+- When refactoring, move existing why-comments with the code they explain; delete one only when its reason no longer exists.
+- Do not add noisy comments that restate obvious code; a comment that paraphrases the next line is a defect.
+
+```typescript
+// Bad: restates the code, carries no decision
+// increment the retry counter
+retries++;
+
+// Good: records the constraint and the decision
+// Stripe webhooks can arrive out of order; process by event.created, not arrival time.
+// Decision: sort in memory instead of queueing — volume stays under ~100 events/min.
+// See docs/fixes/2026-06-02-stripe-replay.md.
+```
+
+## Self-check before finishing
+
+Re-scan every touched file against this list before declaring the work done:
+
+- No `any`, `unknown`, or casts introduced; contracts fixed at the boundary.
+- New code sits under the right banner section, and section names still match their content.
+- Every non-obvious decision, workaround, magic value, and bug fix has a why-comment at the site.
+- No comments that restate code; no leftover debug logs or commented-out code.
+- Repeated logic extracted; one class or component per file; catalogs stay canonical.

package/agents/project/client/AGENTS.md

@@ -42,7 +42,6 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 
 - Do not add `React` imports just for JSX.
 - Do not use `React.useCallback` unless it is necessary or already common in the touched area.
-- Keep one component per file.
 - Load data and define handlers in the directly concerned component when that keeps ownership clearer.
 - Keep curated lists, option registries, and UI copy catalogs under `/client/catalogs/**`.
 - Follow the section-comment format from the root-level `CODING_STYLE.md`.

package/agents/project/diagnostics.md

@@ -18,7 +18,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 - For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum runtime status` first, then use its exact next action so occupied router/HMR ports and untracked same-app runtimes are handled without page-body probes. After the server is ready, print the live server URL as a clickable Markdown link.
 - 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.
-- Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `npx proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis. Every `npx proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
+- When capturing or comparing command logs: only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner; any extra argument or option skips it. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in its ready banner.
 - During `npx proteum dev`, the running app exposes the read-only Proteum MCP transport at `/__proteum/mcp`. Use it for runtime-adjacent agent reads instead of repeatedly spawning equivalent CLI diagnostics.
 - If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status` from the intended app root. If no live session exists, use the exact MCP offline or runtime-status next action so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Then retry MCP `workflow_start` and use the returned `projectId`.
 - For ownership or repo discovery questions, start with MCP `workflow_start`; use MCP `route_candidates { projectId, query }`, MCP `orient { projectId, query }`, and MCP `explain_summary { projectId, query }` only when the bootstrap owner summary is insufficient. Use `npx proteum orient <query>` or `npx proteum explain owner <query>` only when MCP is unavailable or terminal evidence is required.
@@ -34,7 +34,8 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request with compact `npx proteum trace latest`; use `npx proteum trace show <requestId> --events` only when raw event detail is still required.
 - Use the browser MCP to inspect browser console errors and warnings for frontend, SSR, hydration, and controller-call issues.
 - Inspect server startup and runtime errors.
-- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI, then use that session for browser MCP validation. Use `npx proteum e2e --session-email <email> --session-role <role>` only when Playwright end-to-end suites need the auth token through the child process environment. Use the login UI only when auth UX itself is under test.
+- Before every browser MCP validation pass in dev, create an admin session from the project instructions with `npx proteum session <admin-email> --role GOD` and use its `browserLoginUrl` or emitted cookie state before opening the target page. Skip this only when the task is explicitly testing auth, login, anonymous, or non-admin behavior; if no admin email is declared in the project instructions, stop and ask before browser validation.
+- For protected API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI, then use that session for browser MCP validation. Use `npx proteum e2e --session-email <email> --session-role <role>` only when Playwright end-to-end suites need the auth token through the child process environment. Use the login UI only when auth UX itself is under test.
 
 ## Temporary Instrumentation
 
@@ -55,16 +56,16 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Verification And Testing
 
 - Use the cheapest trustworthy verification that matches the failing layer.
-- After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, including targeted tests when behavior changed. When the project defines `proteum.verify.config.ts`, prefer `npx proteum verify changed` for the first post-edit verification plan. Do not run coverage by default, and do not default to a running app, browser MCP, or Playwright while iterating when a narrower static or request-level verification is enough.
+- After implementing a change, verify at the smallest trustworthy layer required by the changed surface first, following the root contract `Verification Policy`. 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.
+- 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 when request-level verification is insufficient, when the change is browser-visible, or when the root `Verification Policy` requires the mandatory browser pass for a new UI-visible feature.
 - When automated browser assertions or suite coverage are required, use `npx proteum e2e --port <port>` for targeted or full Playwright suites. Do not use direct Playwright for browser validation outside the E2E wrapper, and do not launch raw browser automation against a shared persistent profile.
 - Focused verification should treat unrelated global diagnostics as visible but non-blocking by default. Use `--strict-global` only when the task explicitly requires broad clean-room validation.
 - For browser regressions, prefer a browser MCP repro first and add targeted Playwright E2E coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when browser MCP verification is insufficient.
 - 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 targeted lint or typecheck command for that surface before finishing. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Run the full `npm run check` gate before pushing or when explicitly requested.
+- When the touched surface can affect coding-style enforcement, run the targeted lint or typecheck command for that surface before finishing. Commit-time and push-time gates follow the root contract `Verification Policy` and `Commit Workflow`.
 - 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,12 +23,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 
 ## SSR And Page Size
 
-- 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`.
-- Controller fetchers and promises returned from `data` resolve before render.
-- Never use `api.fetch(...)` in page files for SSR loading.
+- The page `data` / `options` / `render` contract is defined in `client/pages/AGENTS.md`; SSR page data belongs in the route definition `data` function, never in `api.fetch(...)`.
 - Synchronous or SSR data calls must return only the strictly necessary data for the current render path to minimize SSR payload size.
 - If an existing controller or data method returns a broader shape than the SSR path needs, create a dedicated proxy controller method with a narrower typed contract instead of reusing the oversized payload.
 - Keep Prisma runtime access inside services when possible and prefer explicit `select` or narrow `include` in database queries.
@@ -46,4 +41,3 @@ When tradeoffs exist inside optimization work, optimize in this order:
 - For browser or SSR changes, use the browser MCP to load the real page, inspect the rendered HTML, and confirm the change does not ship unnecessary client code or oversized SSR payloads.
 - Treat clearly worse bundle size, runtime cost, or crawlable HTML quality as regressions to fix or justify explicitly, not as optional follow-up cleanup.
 - Build-only checks are supplementary.
-- For SSR changes, use the browser MCP to load the real page and inspect the rendered HTML plus browser console.

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

@@ -29,9 +29,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Use runtime models through `this.models` or the app model accessors.
 - Use Prisma typings through `@models/types` only.
 - In database queries, prefer explicit `select` or narrow `include`.
-- For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually.
-- Never use raw SQL DDL or other schema-mutating SQL to change database structure.
-- 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.
+- For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually; the full database safety rules live in the root contract `Hard Stops`.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

package/agents/project/tests/AGENTS.md

@@ -9,9 +9,9 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
-- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Do not run whole-project coverage after every ordinary change by default. Downstream app commit-only workflows run only `proteum refresh`, then targeted lint, typecheck, and test commands in parallel; framework-repo commit workflows skip this downstream app verification. Use `npm run check` as the full gate before push or when the user explicitly asks for it, and document any generated files, migrations, framework shims, unreachable defensive branches, or changes that cannot reasonably be unit-tested as explicit exceptions.
+- For every production change, add or update focused unit tests and run the targeted test command that matches the changed behavior. When the repository defines `proteum.verify.config.ts`, use `npx proteum verify changed` first so changed test files, related source tests, and project-specific suites are selected consistently. Coverage, commit-time, and push-time gates follow the root contract `Verification Policy` and `Commit Workflow`.
 - 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.
+- After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the targeted Playwright scenarios that cover it before finishing; reserve the full suite for push workflows or explicit requests per the root contract `Verification Policy`. 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. For new UI-visible features, the root `Verification Policy` still requires a browser MCP pass against the real page before finishing.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
 - Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
 - Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.
@@ -23,7 +23,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Add `data-testid` where needed instead of relying on brittle selectors.
 - Keep end-to-end tests clean, well organized, and non-redundant. Prefer extending or reshaping the most relevant existing scenario over duplicating coverage, and remove or consolidate overlap when the suite becomes repetitive.
 - Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.
-- For protected dev flows, prefer `npx proteum e2e --session-email <email> --session-role <role>` or `npx proteum session <email> --role <role>` over automating login unless the login flow itself is under test.
+- For browser MCP validation in dev, start from the project instructions' admin account with `npx proteum session <admin-email> --role GOD` or its `browserLoginUrl` unless the scenario intentionally covers auth, anonymous, or non-admin behavior. For protected E2E dev flows, prefer `npx proteum e2e --session-email <email> --session-role <role>` over automating login unless the login flow itself is under test.
 
 ### Real-World Journey E2E