proteum 2.1.9-2 → 2.1.9-5

package/.codex/environments/environment.toml

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

package/AGENTS.md

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

package/README.md

@@ -4,6 +4,8 @@ Proteum is an LLM-first SSR / SEO / TypeScript framework for full-stack web appl
 
 It is built for teams that want explicit server contracts, server-first rendering, deterministic generated artifacts, and a codebase that an AI agent can inspect without reverse-engineering hidden runtime magic.
 
+Migration guide for older apps: [docs/migrate-from-2.1.3.md](docs/migrate-from-2.1.3.md)
+
 ## Why Proteum
 
 Most full-stack frameworks optimize first for human convenience.
@@ -347,7 +349,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
+Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
 
 Useful inspection commands:
 

package/agents/project/AGENTS.md

@@ -9,37 +9,52 @@ Optimization source of truth: project-root `optimizations.md`.
 Diagnostics source of truth: project-root `diagnostics.md`.
 Coding style source of truth: project-root `CODING_STYLE.md`.
 
-## Workflow
+## Fast Triggers
 
-- At the beginning of every task, acknowledge the applicable optimization, diagnostics, and coding-style sources before analyzing or editing code: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
-- Follow project-root `diagnostics.md` for diagnosis, runtime reproduction, temporary instrumentation, error-solving workflow, and verification method selection.
-- For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
+- If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
+- If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow project-root `diagnostics.md`.
+- If the task touches client-side files, especially `client/**` and page files, load and apply project-root `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+- If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
+- If you changed `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
+  ```
+  cd <worktree path>
+  npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
+  ```
+- If you encounter `runtime/provider-hook-outside-provider`, `runtime/client-only-hook-in-ssr`, `runtime/router-context-outside-router`, or `runtime/connected-boundary-mismatch`, treat it as a framework contract failure first. Fix the provider, SSR/client, router, or connected boundary before assuming a local leaf-component bug.
+- If the change is runtime-visible, request-time, router, SSR, browser-visible, or controller-behavior, use running-app verification.
+- If the change is docs-only, wording-only, type-only, test-only, generated-output cleanup, or a clearly local non-runtime refactor, use static verification only unless the user explicitly asks for runtime verification or the agent finds a real issue.
+- If the user replies exactly `commit`, generate one top-level short (up to 100 characters) sentence covering all changes made since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation, strictly using the Conventional Commits specification:
+  ```
+  <type>[optional scope]: <description>
+
+  [optional body]
+  ```
+  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+
+## Task Lifecycle
+
+### Before Editing
+
+- Before changing any file, load project-root `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.
 - When starting a long-lived dev server for an agent task, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
 - Do not start a second `proteum dev` server for the same app and port until the earlier tracked session has been stopped or replaced.
-- When framework work changes Proteum CLI commands, profiler panels/features, or the `proteum dev` banners, keep this file, project-root `diagnostics.md`, and any narrower area `AGENTS.md` that mentions the same workflow aligned with the live framework behavior in the same pass.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
-- Before finishing, double-check the touched files and generated output against the applicable optimization, diagnostics, and coding-style sources: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
-- After implementing any feature or behavior change, always verify it on a running app before finishing: start the server, exercise the affected flow with Playwright or the smallest real runtime or `npx proteum` surface, run the relevant diagnostics or perf commands, and confirm there is no meaningful regression in behavior, performance, bundle/load size, SEO output, or coding style.
-- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
-- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
-```
-Commit message: <type>[optional scope]: <description>
-
-[optional body]
-```
+- For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
 
-## Project Shape
-
-This is a TypeScript, Node.js, Preact, Proteum monolith:
+### Before Finishing
 
-- `/client`: assets, catalogs, components, hooks, pages
-- `/common`: shared functions, constants, types, and catalogs
-- `/server`: catalogs, config, services, routes, lib
-- `/tests`
+- Before finishing, re-check touched files against project-root `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against project-root `optimizations.md` only for touched client-side files. Re-check against project-root `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
+- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
+- When you have finished your work, ask the user whether they want a commit message.
 
-## Non-Negotiable Rules
+## Core Contracts
 
 - Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)`.
 - Page URLs come from the explicit `Router.page('/path', ...)` call, not from the file path.
@@ -48,11 +63,12 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - Manual HTTP endpoints live only in `server/routes/**`.
 - Controllers call `this.input(schema)` inside the method body, at most once per method.
 - Request-scoped state lives only on `this.request` and manual-route/router context objects.
-- Follow project-root `optimizations.md` for bundle size, performance, SEO, and SSR page-size rules.
 - Keep one class or one React/Preact component per file.
 - Prefer a deep tree grouped by business concern instead of long file names.
 - Use the default `*.ts` or `*.tsx` file unless an `*.ssr.ts` or `*.ssr.tsx` variant is truly required.
 - Never edit generated files under `.proteum`.
+- When a task changes database structure, edit the app's `schema.prisma` only.
+- Never create or edit migration files manually.
 - Use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
 - Client context is typically imported from `@/client/context`.
 - Normal service methods do not read request state directly.
@@ -61,63 +77,7 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - Do not use `@app` on the client.
 - Prefer type inference rooted in the explicit application graph in `server/index.ts`.
 
-## Source Of Truth
-
-Proteum reads:
-
-- `package.json`
-- `identity.config.ts` for app identity via `Application.identity({ ... })`
-- `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
-- `server/config/*.ts`
-- `server/index.ts`
-- `commands/**/*.ts`
-- `server/controllers/**/*.ts`
-- `server/routes/**/*.ts`
-- `client/pages/**/*.ts(x)`
-- `client/pages/**/_layout/index.tsx`
-- `public/**`
-
-Proteum owns:
-
-- `.proteum/manifest.json`
-- `.proteum/client/*`
-- `.proteum/common/*`
-- `.proteum/server/*`
-
-Project code should consume:
-
-- `@generated/client/*`
-- `@generated/common/*`
-- `@generated/server/*`
-- `@/client/context` as the generated client context entrypoint
-
-Prefer structured CLI surfaces over re-deriving framework facts from source:
-
-- `npx proteum connect --json`
-- `npx proteum connect --controllers --strict`
-- `npx proteum explain --json`
-- `npx proteum explain --connected --controllers`
-- `npx proteum explain owner <query>`
-- `npx proteum doctor --json`
-- `npx proteum doctor --contracts --json`
-- `npx proteum diagnose <path> --port <port>`
-- `npx proteum perf ...`
-- `npx proteum trace ...`
-- `npx proteum command ...`
-- `npx proteum session ...`
-- `npx proteum create ... --dry-run --json`
-- `npx proteum dev list --json`
-- `npx proteum dev stop --session-file <path>`
-
-Prefer scaffold commands before hand-writing boilerplate:
-
-- Use `npx proteum init <directory> --name <name>` for new apps.
-- Use `npx proteum init ... --dry-run --json` when an agent needs a machine-readable app plan before writing files.
-- Use `npx proteum create page|controller|command|route|service <target>` for new app artifacts before creating the files manually.
-- Use `npx proteum create ... --dry-run --json` when an agent needs a machine-readable artifact plan before writing files.
-
-## File Contracts
+## Surface Contracts
 
 ### App Bootstrap And Services
 
@@ -193,15 +153,31 @@ Prefer scaffold commands before hand-writing boilerplate:
   - `@app`: server-side application services for manual routes only
   - `@generated/*`: generated app surfaces
 
-## Dependency Selection
+## Verification Matrix
+
+Verify at the correct layer:
+
+- Default: use the cheapest trustworthy verification for the changed surface first, then escalate only if the changed surface justifies it.
+- Route additions: boot the app and hit the real URL.
+- Controller changes: exercise the generated client call or generated `/api/...` endpoint.
+- SSR changes: load the real page and inspect rendered HTML plus browser console.
+- Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
+- Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
+- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
+- Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
+- For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow project-root `diagnostics.md`.
+
+## Implementation Rules
+
+### Dependency Selection
 
 - Before implementing a feature or change, first check whether the repo already includes a suitable dependency.
 - If not, search npm before building a new utility, abstraction, component primitive, parser, formatter, or integration from scratch.
 - Prefer the most popular, flexible, maintained packages that fit the project constraints.
-- Follow project-root `optimizations.md` when deciding whether custom infrastructure is justified over an existing package.
+- When the task explicitly involves client-side optimization work, use project-root `optimizations.md` to decide whether custom infrastructure is justified over an existing package.
 - When you choose custom over a package, explain the reason briefly.
 
-## Catalogs And Typing
+### Catalogs And Typing
 
 - Keep one canonical catalog or registry file and import it everywhere else.
 - Client-only catalogs live in `/client/catalogs/**`, server-only catalogs in `/server/catalogs/**`, and shared catalogs in `/common/catalogs/**`.
@@ -211,7 +187,7 @@ Prefer scaffold commands before hand-writing boilerplate:
 - Fix typing issues only on code you wrote.
 - Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 
-## Design Rules
+### Design Rules
 
 - Prefer explicit `server/index.ts` bootstrap over hidden registration.
 - Prefer controller-backed app APIs over ad hoc manual `/api/...` routes.
@@ -219,25 +195,93 @@ Prefer scaffold commands before hand-writing boilerplate:
 - Keep one canonical source of truth for catalogs, registries, and shared types.
 - Reuse shared Shadcn-based UI primitives when the project already provides them.
 
-## Discouraged Patterns
+### Discouraged Patterns
 
 - request-scoped state inside normal service methods
 - hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
 - editing `.proteum` directly
 
-## Verification
+## Hard Stops
 
-Verify at the correct layer:
+- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX` to change database structure.
+- Do not run `prisma *` yourself. If a schema change requires migration, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue`.
+- Do not run `git restore` or `git reset`.
+- Do not run write-mode git commands by default. The built-in exception is an exact `commit` reply, which allows only task-scoped `git add` and `git commit`. Any other write-mode git action requires an explicit user request.
 
-- route additions: boot the app and hit the real URL
-- controller changes: exercise the generated client call or generated `/api/...` endpoint
-- SSR changes: load the real page and inspect rendered HTML plus browser console
-- router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
-- For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow project-root `diagnostics.md`.
+## Appendix
+
+### Project Shape
+
+This is a TypeScript, Node.js, Preact, Proteum monolith:
+
+- `/client`: assets, catalogs, components, hooks, pages
+- `/common`: shared functions, constants, types, and catalogs
+- `/server`: catalogs, config, services, routes, lib
+- `/tests`
+
+### Source Of Truth
+
+Proteum reads:
+
+- `package.json`
+- `identity.config.ts` for app identity via `Application.identity({ ... })`
+- `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `server/config/*.ts`
+- `server/index.ts`
+- `commands/**/*.ts`
+- `server/controllers/**/*.ts`
+- `server/routes/**/*.ts`
+- `client/pages/**/*.ts(x)`
+- `client/pages/**/_layout/index.tsx`
+- `public/**`
+
+Proteum owns:
+
+- `.proteum/manifest.json`
+- `.proteum/client/*`
+- `.proteum/common/*`
+- `.proteum/server/*`
 
-Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `proteum dev list --json`, `proteum dev stop --session-file <path>`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum build --prod --analyze`, `npx proteum build --prod --analyze --analyze-serve --analyze-port auto`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
+Project code should consume:
 
-## High-Impact Files
+- `@generated/client/*`
+- `@generated/common/*`
+- `@generated/server/*`
+- `@/client/context` as the generated client context entrypoint
+
+### Useful Commands
+
+Prefer structured CLI surfaces over re-deriving framework facts from source:
+
+- `npx proteum connect --json`
+- `npx proteum connect --controllers --strict`
+- `npx proteum orient <query>`
+- `npx proteum explain --json`
+- `npx proteum explain --connected --controllers`
+- `npx proteum explain owner <query>`
+- `npx proteum doctor --json`
+- `npx proteum doctor --contracts --json`
+- `npx proteum diagnose <path> --port <port>`
+- `npx proteum verify owner <query>`
+- `npx proteum verify request <path>`
+- `npx proteum verify browser <path>`
+- `npx proteum perf ...`
+- `npx proteum trace ...`
+- `npx proteum command ...`
+- `npx proteum session ...`
+- `npx proteum create ... --dry-run --json`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file <path>`
+
+Prefer scaffold commands before hand-writing boilerplate:
+
+- `npx proteum init <directory> --name <name>`
+- `npx proteum init ... --dry-run --json`
+- `npx proteum create page|controller|command|route|service <target>`
+- `npx proteum create ... --dry-run --json`
+
+### High-Impact Files
 
 Edit these only when required, and keep changes minimal and explicit:
 
@@ -245,14 +289,3 @@ Edit these only when required, and keep changes minimal and explicit:
 - `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
 - Prisma-generated files
 - symbolic links
-
-## Commands Not To Run
-
-- `git restore`
-- `git reset`
-- `prisma *`
-- any write-mode git command
-
-## Product And UX Docs
-
-If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist.

package/agents/project/diagnostics.md

@@ -4,7 +4,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Initial Triage
 
-- Start with machine-readable app state before reading large parts of the codebase: `./.proteum/manifest.json`, `npx proteum connect --json`, `npx proteum explain --json`, `npx proteum doctor --json`, and `npx proteum doctor --contracts --json` when generated artifacts or manifest-owned files may be stale.
+- Start with machine-readable app state before reading large parts of the codebase: `npx proteum orient <query>`, `./.proteum/manifest.json`, `npx proteum connect --json`, `npx proteum explain --json`, `npx proteum doctor --json`, and `npx proteum doctor --contracts --json` when generated artifacts or manifest-owned files may be stale.
 - When one app depends on another app's generated controllers, inspect `npx proteum connect --controllers`, `npx proteum explain --connected --controllers`, the producer `proteum.connected.json`, the consumer `proteum.config.ts` connected `source` value, and the producer `./.proteum/proteum.connected.d.ts` before assuming the contract is local.
 - Use `rg -n` first to narrow the exact code path, then read only the relevant files.
 - Inspect `./server/index.ts`, `./server/config/*.ts`, and the touched files under `./commands`, `./server/controllers`, `./server/services`, `./server/routes`, `./client/pages`, and `./tests`.
@@ -13,22 +13,25 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Runtime Diagnostics
 
 - For long-lived dev reproductions, start the app with `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically after the repro.
-- Human-facing Proteum CLI runs now print the welcome banner and include the active Proteum installation method, but 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.
+- 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 banner. 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.
+- For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
+- Prefer focused verification before global checks: `npx proteum verify owner <query>`, `npx proteum verify request <path>`, and only then `npx proteum verify browser <path>` or targeted Playwright when the bug is browser-visible.
 - For connected-project failures, confirm the consumer app resolves the expected `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` values, the producer app exposes `GET /api/__proteum/connected/ping`, and the imported controller entries show `scope=connected` in `proteum explain`.
 - Use `npx proteum explain owner <query>` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code.
-- For performance issues or regressions in dev, use `npx proteum perf top --since <window>` to rank hot paths, `npx proteum perf request <requestId|path>` for one request waterfall, `npx proteum perf compare --baseline <window> --target <window>` for regressions, and `npx proteum perf memory --since <window>` for heap or RSS drift.
+- For performance issues or regressions in dev, use `npx proteum perf top --since <window>` to rank hot paths, `npx proteum perf request <requestId|path>` for one request waterfall plus chain attribution and SQL fingerprints, `npx proteum perf compare --baseline <window> --target <window>` for regressions, and `npx proteum perf memory --since <window>` for heap or RSS drift.
 - For bundle-size inspection, use `npx proteum build --prod --analyze` to emit `bin/bundle-analysis/client.html` and `client-stats.json`, or add `--analyze-serve --analyze-port auto` when you want a local analyzer URL instead of a static HTML file.
 - For request-time issues in dev, inspect traces before adding logs when the diagnose surface is still too coarse.
 - If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request with `npx proteum trace latest` or `npx proteum trace show <requestId>`.
 - 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. Use the login UI only when auth UX itself is under test.
+- For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` over driving the login UI. Feed that auth into `npx proteum verify browser ...` or direct Playwright. Use the login UI only when auth UX itself is under test.
 
 ## Temporary Instrumentation
 
 - When manifest inspection, trace data, browser console output, and server errors are still insufficient, add temporary targeted logs in the code to confirm control flow, payload shape, query shape, or branch selection.
+- If SQL is needed during diagnosis, keep it read-only. Never use SQL to change database structure or execute schema-mutating DDL.
 - Keep temporary logs narrow, contextual, and easy to remove. Do not leave broad debug noise in shared execution paths.
 - Re-run only the smallest relevant repro, request, or test after adding temporary instrumentation.
 - Temporary logs added in the code for diagnosis must be cleaned at the end of tests or the repro cycle and must never be committed.
@@ -36,6 +39,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Error Solving
 
 - Fix the contract boundary, not only the downstream symptom.
+- Treat provider, SSR/client-only hook, router-context, and connected-boundary failures as contract mistakes first. The likely fix is where the boundary was crossed incorrectly, not only where the throw surfaced.
 - Prefer explicit typed schemas, adapters, query `select`s, and narrow response shapes over casts, broad payloads, or hidden fallbacks.
 - Keep patches narrow, then verify immediately at the failing layer before broadening the test surface.
 - Review the resulting diff to confirm the fix removed the cause instead of masking it.
@@ -43,13 +47,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 feature or behavior change, always verify it on a running app instead of stopping at static analysis or code review.
-- For compile-time or type-safety issues, start with the relevant typecheck or build command.
+- After implementing a change, verify only at the smallest trustworthy layer required by the changed surface. Do not default to a running app, project-wide typecheck, `npx proteum check`, or Playwright 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: boot the server, run the relevant real URL, generated controller call, command, or `npx proteum diagnose <path> --port <port>`, then add targeted Playwright coverage when the change is browser-visible.
-- For browser regressions, prefer targeted Playwright coverage and inspect failure artifacts such as screenshots, videos, `error-context.md`, and Playwright traces.
+- Start the smallest trustworthy runtime surface first: `npx proteum orient <query>`, then the relevant real URL, generated controller call, command, or `npx proteum diagnose <path> --port <port>`. Add targeted Playwright coverage only when request-level verification is insufficient or the change is browser-visible.
+- Proteum does not provide a dedicated raw browser-runtime CLI. When `npx proteum verify browser` is insufficient, use direct Playwright with a disposable profile. 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 real browser repro first and add targeted Playwright coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when manual/browser 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 smallest relevant project check such as `npx proteum lint` or `npx proteum check` before finishing.
+- When the touched surface can affect coding-style enforcement, run the smallest relevant static check. Do not default to `npx proteum check`; prefer a narrower lint or type check only when the changed surface or an observed issue calls for it.
 - 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/server/services/AGENTS.md

@@ -29,6 +29,8 @@ Diagnostics source of truth: project-root `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.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

package/agents/project/tests/AGENTS.md

@@ -10,7 +10,7 @@ Diagnostics source of truth: project-root `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.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
-- After implementing a browser-visible feature or change, run targeted Playwright coverage or a real browser repro against a running app before finishing; this verification is required, not optional cleanup.
+- After implementing a browser-visible feature or change, prefer a real browser repro against a running app first. Add targeted Playwright coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when manual/browser verification is insufficient.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
 - Locate elements with `data-testid`.
 - Add `data-testid` where needed instead of relying on brittle selectors.

package/cli/commands/diagnose.ts

@@ -163,7 +163,35 @@ const renderOwners = (matches: TExplainOwnerMatch[]) =>
         ? ['Owner matches', '- none'].join('\n')
         : [
               'Owner matches',
-              ...matches.map((match) => `- [${match.kind}] ${match.label} score=${match.score} source=${formatSource(match)}`),
+              ...matches.map(
+                  (match) =>
+                      `- [${match.kind}] ${match.label} score=${match.score} scope=${match.scopeLabel} origin=${match.originHint} source=${formatSource(match)}`,
+              ),
+          ].join('\n');
+
+const renderChain = (response: TDiagnoseResponse) =>
+    !response.chain || response.chain.length === 0
+        ? ['Chain', '- none'].join('\n')
+        : [
+              'Chain',
+              ...response.chain.map(
+                  (item) =>
+                      `- [${item.kind}] ${item.label}${item.source?.filepath ? ` source=${item.source.filepath}${item.source.line ? `:${item.source.line}` : ''}${item.source.column ? `:${item.source.column}` : ''}` : ''}${item.details.length > 0 ? ` details=${item.details.join(', ')}` : ''}`,
+              ),
+          ].join('\n');
+
+const renderOrientation = (response: TDiagnoseResponse) =>
+    !response.orientation
+        ? ['Orientation', '- none'].join('\n')
+        : [
+              'Orientation',
+              `- agents=${response.orientation.guidance.agents}`,
+              `- diagnostics=${response.orientation.guidance.diagnostics}`,
+              `- optimizations=${response.orientation.guidance.optimizations}`,
+              `- codingStyle=${response.orientation.guidance.codingStyle}`,
+              `- areaAgents=${response.orientation.guidance.areaAgents.join(', ') || 'none'}`,
+              `- connected imports=${response.orientation.connected.imports.length} producers=${response.orientation.connected.producers.length}`,
+              ...response.orientation.nextSteps.map((step) => `- next=${step.command} (${step.reason})`),
           ].join('\n');
 
 const renderSuspects = (response: TDiagnoseResponse) =>
@@ -188,6 +216,10 @@ const renderHuman = (manifest: ReturnType<typeof readProteumManifest>, response:
         '',
         renderOwners(response.owner.matches.slice(0, 6)),
         '',
+        renderChain(response),
+        '',
+        renderOrientation(response),
+        '',
         renderDoctorResponseHuman({
             emptyMessage: 'No manifest diagnostics were found.',
             manifest,

package/cli/commands/explain.ts

@@ -55,7 +55,7 @@ export const run = async (): Promise<void> => {
                     ? ['- No matching manifest owners were found.']
                     : response.matches.map(
                           (match) =>
-                              `- [${match.kind}] ${match.label} score=${match.score} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
+                              `- [${match.kind}] ${match.label} score=${match.score} scope=${match.scopeLabel} origin=${match.originHint} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
                       )),
             ].join('\n'),
         );