proteum 2.5.9 → 2.5.11

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` for the standalone app-root contract, or split between `agents/project/root/AGENTS.md` and `agents/project/app-root/AGENTS.md` in a monorepo.
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md`; it is the single canonical project contract, and `proteum configure agents` deploys it through the generated root router in both standalone and monorepo modes.
 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/**`.
@@ -45,7 +45,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
   [optional body]
   ```
-  If the user replies exactly `commit`, treat it as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation. In each affected repository or worktree, stage all conversation-related changed files with `git add` while still excluding unrelated pre-existing user changes or incidental untracked files, then create one `git commit`. Do not run downstream project commit-time verification such as `proteum refresh`, targeted lint, typecheck, or test commands when committing this framework repository itself unless the user explicitly asks for those checks. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work.
+  If the user replies exactly `commit`, treat it as conversation-wide and cross-project, not task-scoped. Identify every affected git repository or worktree touched since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation. In each affected repository or worktree, stage all conversation-related changed files with `git add` while still excluding unrelated pre-existing user changes or incidental untracked files, then create one `git commit` — or several when the changes span clearly separable concerns (independent features, an unrelated fix, a refactor separable from a behavior change), each commit staging only the files that belong to its concern and carrying its own message. Do not run downstream project commit-time verification such as `proteum refresh`, targeted lint, typecheck, or test commands when committing this framework repository itself unless the user explicitly asks for those checks. Do not omit linked local dependencies, framework repos, connected projects, or producer apps when they were changed to make the delivered behavior actually work.
   When the user asks to push, explain the currently unpushed commits in short, minimalistic bullet points in plain language, like you would do to your grandma. Start each bullet with a verb in the past.
   When an optional commit body is useful, write it as a short, minimalistic bullet list explaining what changed in this thread in plain language, like you would do to your grandma. Start each bullet with a verb in the past. Do not print a separate prompt asking for that explanation.
 
@@ -62,11 +62,11 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
     - `/Users/gaetan/Desktop/Projets/klair.work/apps/api`
     - `/Users/gaetan/Desktop/Projets/klair.work/apps/worker`
 - Inspect how the relevant reference 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/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.
+- 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.
 - Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
 - 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.
-- 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`.
+- Keep core changes aligned with the explicit controller/page architecture 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.

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,64 @@ 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.
+```
+
+## Doc anchors
+
+A why-comment explains one decision. A doc anchor connects the file to the durable documentation that governs it, so an agent that opens the file finds the feature pack, the decision record and the invariant without searching the corpus first.
+
+Write anchors in a leading block comment:
+
+```typescript
+/**
+ * @docs docs/features/search
+ * @adr  ADR-0004
+ * @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+ * @rule Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.
+ */
+```
+
+- `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
+- `@adr` and `@fix` point at the decision record and fix note that constrain the file. Add them where the decision or the bug actually lives, not on every file in the area.
+- `@rule` states the invariant inline, in full. It is the one anchor that carries content rather than a pointer, because the rule is what an agent needs at the moment of editing. A `@rule` that only says `todo` or repeats the linked title is a defect.
+- Anchors are not a substitute for the documents. Narrative, alternatives, benchmarks and acceptance stay under `docs/**`; the anchor carries the pointer and the single-sentence rule.
+
+Two ESLint rules enforce this. `proteum/require-doc-anchor` reports definition files with no `@docs`, and warns by default so an adopting project sees its backlog without a failing build; pass `docAnchors: 'error'` to `createProteumEslintConfig` once the backfill is done. `proteum/valid-doc-anchor` always errors, because an anchor pointing at a deleted document is worse than no anchor.
+
+The read-only MCP owner payloads return these anchors alongside `explain_summary`, `orient`, `route_candidates`, `diagnose`, and `workflow_start`, so the documentation reaches the agent in the same response that identifies the owner.
+
+`proteum docs check` verifies the whole corpus in both directions: it fails on an anchor that no longer resolves, and reports as a backlog every fix note carrying an `Agent warning` that no code anchors, plus every feature pack nothing points at. `proteum verify changed` selects it automatically whenever `docs/**` or a source file changes, so a renamed document cannot silently orphan an anchor.
+
+## 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.
+- Every touched definition file carries a `@docs` anchor, and any fix or decision applied in this pass left a `@rule` anchor at the code site it constrains.
+- 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/DOCUMENTATION.md

@@ -37,6 +37,8 @@ Do not code from assumptions when a source-of-truth document exists.
 
 Do not duplicate rules across documents. Link to the source of truth when needed.
 
+Documentation must be reachable from the code it governs. Every document written under these rules names the code it affects; the code must point back with a doc anchor, so the next agent finds the governing document by opening the file rather than by searching the corpus. Anchors carry pointers plus the single-sentence invariant, never the narrative. The format and the lint rules that enforce it are in `CODING_STYLE.md`.
+
 ---
 
 # 2. Always read these first
@@ -86,6 +88,7 @@ docs/features/<feature>/acceptance.md
 docs/testing/regression-tests.md              if a regression test was added
 docs/decisions/                               if a major decision changed
 docs/fixes/                                   if a bug or regression was fixed
+@docs anchor on each definition file the feature owns
 ```
 
 ---
@@ -108,6 +111,7 @@ After fixing the bug, update:
 docs/fixes/YYYY-MM-DD-short-bug-name.md
 docs/testing/regression-tests.md
 affected feature edge-cases.md if a new edge case was discovered
+@rule and @fix anchors at the code site that regressed
 ```
 
 A bug fix is incomplete if:
@@ -117,6 +121,7 @@ the root cause is not documented
 the implemented solution is not documented
 the regression test is not linked
 future agents cannot tell what pattern must not return
+the invariant lives only in the fix note and not at the code site that regressed
 ```
 
 ---
@@ -847,12 +852,18 @@ tests/regression/<area>/<bug-name>.test.ts
 
 ## New rule added
 
-What should future agents follow?
+What should future agents follow? Both sections below are mandatory, and each one must also be mirrored to a `@rule` doc anchor at the code site it constrains. A rule that lives only in this note reaches no agent editing that file.
 
 ## Agent warning
 
 What pattern must not be reintroduced?
 
+## Code anchor
+
+```txt
+path/to/file        the @rule and @fix anchors added there
+```
+
 ## Related docs
 
 - docs/features/<feature>/
@@ -1004,11 +1015,17 @@ tests/performance/<benchmark>.test.ts
 
 ## New rule added
 
-What should future agents follow?
+What should future agents follow? Both sections below are mandatory, and each one must also be mirrored to a `@rule` doc anchor at the code site it constrains. A rule that lives only in this note reaches no agent editing that file.
 
 ## Agent warning
 
 What pattern must not be reintroduced?
+
+## Code anchor
+
+```txt
+path/to/file        the @rule and @fix anchors added there
+```
 ````
 
 ---

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