proteum 2.1.9 → 2.2.0

package/agents/project/client/AGENTS.md

@@ -3,11 +3,11 @@
 This is the canonical client-area contract for Proteum-based projects.
 Role: keep only client-area rules here.
 Keep here: client component, hook, design-system, accessibility, and client-context usage rules that apply beyond a single page.
-Do not put here: page `setup` and route-registration details, server/service rules, or generic project workflow already covered by the project-root `AGENTS.md`.
+Do not put here: page `data` and route-registration details, server/service rules, or generic project workflow already covered by broader ancestor `AGENTS.md` files.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
-Coding style source of truth: project-root `CODING_STYLE.md`.
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
+Coding style source of truth: root-level `CODING_STYLE.md`.
 
 ## Stack
 
@@ -39,4 +39,4 @@ Coding style source of truth: project-root `CODING_STYLE.md`.
 - 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 project-root `CODING_STYLE.md`.
+- Follow the section-comment format from the root-level `CODING_STYLE.md`.

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

@@ -2,30 +2,30 @@
 
 This is the canonical page-file contract for Proteum-based projects.
 Role: keep only page-file rules here.
-Keep here: `Router.page(...)` registration, SSR `setup` and `render` contracts, page payload shape, and page-local typing rules.
+Keep here: `Router.page(...)` registration, SSR `data` and `render` contracts, page payload shape, and page-local typing rules.
 Do not put here: generic component rules, server/service implementation details, or app-wide workflow already covered by broader AGENTS files.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
-Coding style source of truth: project-root `CODING_STYLE.md`.
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
+Coding style source of truth: root-level `CODING_STYLE.md`.
 
 ## Router.page Usage
 
 - Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
 - File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- Prefer `Router.page(path, setup, render)` for normal SSR pages.
-- Use `Router.page(path, options, setup, render)` when a separate route-options object makes the call clearer.
+- The only supported page signature is `Router.page(path, options, data, render)`.
+- `options` is always required and must be an object.
+- `data` is the only nullable argument. Pass `null` when the page does not need SSR data.
 - Keep the `Router.page(...)` call compact instead of exploding each outer argument onto its own line.
 - Keep route registration at top level. Do not hide it behind helper abstractions.
 
-## Setup And Render
+## Data And Render
 
-- `setup` returns one flat object.
-- `_`-prefixed keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options.
-- Every other key is SSR data and should be consumed from `render`.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- If a page needs route data, return it from `setup` and read it in `render`.
+- Route behavior belongs in the explicit `options` object, not in page data.
+- `data` returns one flat object or `null` is passed as the third argument when no page data is needed.
+- Returning route-option keys such as `auth`, `layout`, `static`, `redirectLogged`, or their `_`-prefixed variants from `data` is a contract error.
+- Controller fetchers and promises returned from `data` resolve before render.
+- If a page needs route data, return it from `data` and read it in `render`.
 
 ## Page Rules
 

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`.
@@ -12,23 +12,28 @@ 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.
+- For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
+- 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.
+- When diagnosing a consumer app that depends on local `file:` connected projects, boot every connected producer app too, each on its own free port and task-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before reproducing the consumer issue.
 - 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 +41,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 +49,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/optimizations.md

@@ -22,12 +22,11 @@ When tradeoffs exist inside optimization work, optimize in this order:
 
 ## SSR And Page Size
 
-- SSR page data belongs in page `setup`, not in `api.fetch(...)`.
-- Prefer `Router.page(path, setup, render)` for normal SSR pages.
-- `setup` returns one flat object.
-- `_`-prefixed keys are route options. Every other key is SSR data and should be consumed from `render`.
-- If a page needs route data, return it from `setup` and read it in `render`.
-- Controller fetchers and promises returned from `setup` resolve before render.
+- SSR page data belongs in the explicit `Router.page(path, options, data, render)` `data` function, not in `api.fetch(...)`.
+- `options` carries route behavior. `data` returns one flat object or is `null` when the page has no SSR data loader.
+- Route-option keys and `_`-prefixed route-option aliases are forbidden in page data and must live in `options`.
+- If a page needs route data, return it from `data` and read it in `render`.
+- Controller fetchers and promises returned from `data` resolve before render.
 - Never use `api.fetch(...)` in page files for SSR loading.
 - Synchronous or SSR data calls must return only the strictly necessary data for the current render path to minimize SSR payload size.
 - If an existing controller or data method returns a broader shape than the SSR path needs, create a dedicated proxy controller method with a narrower typed contract instead of reusing the oversized payload.

package/agents/project/root/AGENTS.md

@@ -0,0 +1,295 @@
+# Proteum Root Contract
+
+This is the reusable Proteum-wide contract that is safe to place at the root of a monorepo above one or more Proteum apps.
+Pair this file with an app-root `AGENTS.md` inside each Proteum app when local workflow or product-context instructions depend on the current directory being the app root.
+Role: keep only reusable Proteum workflow, architecture contracts, shared typing rules, and cross-surface verification rules here.
+Do not put here: app-root bootstrap steps, local product-doc reading rules, detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `diagnostics.md`, `optimizations.md`, `CODING_STYLE.md`, `client/AGENTS.md`, `client/pages/AGENTS.md`, `server/routes/AGENTS.md`, `server/services/AGENTS.md`, or `tests/AGENTS.md`.
+
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
+Coding style source of truth: root-level `CODING_STYLE.md`.
+
+## Fast Triggers
+
+- 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 the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
+- If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
+- If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
+- If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
+- If you changed `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
+  ```
+  cd <worktree path>
+  npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
+  ```
+- If you encounter `runtime/provider-hook-outside-provider`, `runtime/client-only-hook-in-ssr`, `runtime/router-context-outside-router`, or `runtime/connected-boundary-mismatch`, treat it as a framework contract failure first. Fix the provider, SSR/client, router, or connected boundary before assuming a local leaf-component bug.
+- If the change is runtime-visible, request-time, router, SSR, browser-visible, or controller-behavior, use running-app verification.
+- If the change is docs-only, wording-only, type-only, test-only, generated-output cleanup, or a clearly local non-runtime refactor, use static verification only unless the user explicitly asks for runtime verification or the agent finds a real issue.
+- If the user replies exactly `commit`, generate one top-level short (up to 100 characters) sentence covering all changes made since the last `commit` and, if there has been no prior `commit`, since the beginning of the whole conversation, strictly using the Conventional Commits specification:
+  ```
+  <type>[optional scope]: <description>
+
+  [optional body]
+  ```
+  Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
+
+## Task Lifecycle
+
+### Before Editing
+
+- Before changing any file, load root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applies to the touched files. Do not spend response space explicitly acknowledging those reads unless the user asks.
+
+### During Implementation
+
+- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
+- If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
+- For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
+
+### 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.
+- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
+- When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
+
+## Core Contracts
+
+- Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)`.
+- Page URLs come from the explicit `Router.page('/path', ...)` call, not from the file path.
+- Callable app APIs live only in `server/controllers/**/*.ts` files that extend `Controller`.
+- Dev-only internal execution lives only in `commands/**/*.ts` files that extend `Commands`.
+- Manual HTTP endpoints live only in `server/routes/**`.
+- Controllers call `this.input(schema)` inside the method body, at most once per method.
+- Request-scoped state lives only on `this.request` and manual-route/router context objects.
+- 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.
+- Do not import runtime values from `@models`.
+- Do not use `@request` runtime globals.
+- Do not use `@app` on the client.
+- Prefer type inference rooted in the explicit application graph in `server/index.ts`.
+
+## Surface Contracts
+
+### App Bootstrap And Services
+
+- `server/index.ts` default-exports the app `Application` subclass and is the canonical type root.
+- Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
+- Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
+- Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
+- Root business services live in `server/services/<Feature>/index.ts`.
+- Root-service config lives in `server/config/*.ts` when the service needs config.
+- Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
+- Keep auth, input parsing, locale, cookies, and request-derived values in controllers, then pass explicit typed arguments into services.
+- Split growing features into explicit subservices.
+- Companion client-callable entrypoints live in `server/controllers/**`.
+- `proteum create service ...` scaffolds the service file, a typed config export under `server/config/*.ts`, and the root registration in `server/index.ts`; review and adapt the generated names before committing.
+
+### Connected Projects
+
+- Declare connected namespaces in `proteum.config.ts` with explicit values such as `connect: { Product: { source: PRODUCT_CONNECTED_SOURCE, urlInternal: PRODUCT_URL_INTERNAL } }`.
+- Proteum does not infer connected env key names from the namespace. The source and internal URL must be provided explicitly in `proteum.config.ts`.
+- Use `npx proteum connect` to inspect configured connect values, cached contract state, and imported controllers for the current app.
+- Before launching a consumer app that depends on local `file:` connected sources, launch every connected producer app too, assign each one a free port, run each `proteum dev` outside the sandbox with elevated permissions, and make sure `connect.<Namespace>.urlInternal` resolves to those live producer URLs.
+- `file:` connected sources point at another Proteum app root and keep strong connected typings.
+- Non-local connected sources provide runtime helper generation but are intentionally typed loosely.
+
+### Controllers
+
+- Files live under `server/controllers/**/*.ts` and default-export a class extending `Controller`.
+- Methods with bodies become generated client-callable endpoints.
+- Route path comes from the controller file path plus the method name.
+- `export const controllerPath = 'Custom/path'` can override the base path.
+- Generated client calls use `POST`.
+- Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
+
+### Commands
+
+- Files live under `commands/**/*.ts` and default-export a class extending `Commands` from `@server/app/commands`.
+- Methods with bodies become generated dev commands.
+- Command path comes from the file path plus the method name.
+- `export const commandPath = 'Custom/path'` can override the base path.
+- Commands are for dev-only internal execution through `proteum command ...` or the profiler `Commands` tab.
+- Keep command logic internal; do not turn it into a normal controller unless it is a real app API.
+- Prefer `proteum create command ...` for new command boilerplate.
+
+### Client Pages
+
+- Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
+- File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
+- The only supported page signature is `Router.page(path, options, data, render)`.
+- `options` is always required. `data` is the only nullable argument and must be `null` when the page has no SSR data loader.
+- `data` returns one flat object. Route-option keys such as `auth`, `layout`, `static`, and `_static` are forbidden in page data and must live in `options`.
+- Controller fetchers and promises returned from `data` resolve before render.
+- `render` consumes resolved page data and uses generated controller methods from render args or `@/client/context`.
+- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page data state.
+- Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path, options object, and data payload.
+
+### Manual Routes
+
+- Use `server/routes/**` only for explicit HTTP behavior that should not be a generated controller action.
+- Good fits include redirects, sitemap or RSS output, OAuth callbacks, webhooks, and public resources with custom semantics.
+- Import server-side app services from `@app` and use route handler context for `request`, `response`, router plugins, and custom router context.
+- If the route is a normal app API, prefer a controller.
+- Prefer `proteum create route ...` for new manual-route boilerplate.
+
+### Models And Aliases
+
+- Use Prisma typings from `@models/types`.
+- Use runtime models through `this.models` or `this.app.Models.client`.
+- Keep Prisma runtime access inside services when possible and prefer explicit `select` or narrow `include`.
+- Do not import runtime values from `@models` or edit generated Prisma client files.
+- Aliases:
+  - `@/client/...`, `@/server/...`, `@/common/...`: app code
+  - `@client/...`, `@server/...`, `@common/...`: Proteum core modules
+  - `@app`: server-side application services for manual routes only
+  - `@generated/*`: generated app surfaces
+
+## Verification Matrix
+
+Verify at the correct layer:
+
+- Default: use the cheapest trustworthy verification for the changed surface first, then escalate only if the changed surface justifies it.
+- Route additions: boot the app and hit the real URL.
+- Controller changes: exercise the generated client call or generated `/api/...` endpoint.
+- SSR changes: load the real page and inspect rendered HTML plus browser console.
+- Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
+- Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
+- Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
+- Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
+- For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow root-level `diagnostics.md`.
+
+## Implementation Rules
+
+### Dependency Selection
+
+- Before implementing a feature or change, first check whether the repo already includes a suitable dependency.
+- If not, search npm before building a new utility, abstraction, component primitive, parser, formatter, or integration from scratch.
+- Prefer the most popular, flexible, maintained packages that fit the project constraints.
+- 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
+
+- 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.
+- 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
+
+- Prefer explicit `server/index.ts` bootstrap over hidden registration.
+- Prefer controller-backed app APIs over ad hoc manual `/api/...` routes.
+- Prefer service classes over server helpers with hidden dependencies.
+- 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
+
+- request-scoped state inside normal service methods
+- hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
+- editing `.proteum` directly
+
+## Hard Stops
+
+- 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.
+
+## 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/*`
+
+Project code should consume:
+
+- `@generated/client/*`
+- `@generated/common/*`
+- `@generated/server/*`
+- `@/client/context` as the generated client context entrypoint
+
+### Useful Commands
+
+Prefer structured CLI surfaces over re-deriving framework facts from source:
+
+- `npx proteum connect --json`
+- `npx proteum connect --controllers --strict`
+- `npx proteum orient <query>`
+- `npx proteum explain --json`
+- `npx proteum explain --connected --controllers`
+- `npx proteum explain owner <query>`
+- `npx proteum doctor --json`
+- `npx proteum doctor --contracts --json`
+- `npx proteum diagnose <path> --port <port>`
+- `npx proteum verify owner <query>`
+- `npx proteum verify request <path>`
+- `npx proteum verify browser <path>`
+- `npx proteum perf ...`
+- `npx proteum trace ...`
+- `npx proteum command ...`
+- `npx proteum session ...`
+- `npx proteum create ... --dry-run --json`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file <path>`
+
+Prefer scaffold commands before hand-writing boilerplate:
+
+- `npx proteum init <directory> --name <name>`
+- `npx proteum init ... --dry-run --json`
+- `npx proteum create page|controller|command|route|service <target>`
+- `npx proteum create ... --dry-run --json`
+
+### High-Impact Files
+
+Edit these only when required, and keep changes minimal and explicit:
+
+- `tsconfig*.json`
+- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- Prisma-generated files
+- symbolic links

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

@@ -5,8 +5,8 @@ Role: keep only manual-route rules here.
 Keep here: explicit HTTP route guidance, public/crawlable endpoint rules, absolute URL generation, and route-specific catalog placement.
 Do not put here: controller contracts, service-layer business logic, page SSR rules, or broad project workflow already defined elsewhere.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Use `server/routes/**` only for explicit HTTP behavior that should not be generated from controllers.
 - If the endpoint is a normal app API, prefer `server/controllers/**/*.ts`.

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

@@ -5,8 +5,8 @@ Role: keep only service-layer rules here.
 Keep here: service placement, service responsibilities, model access, query-shaping, return-type guidance, and service error-handling rules.
 Do not put here: request parsing, page/render rules, controller transport details, or broad project workflow already defined in higher-level AGENTS files.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
 
 ## Placement
 
@@ -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

@@ -5,12 +5,12 @@ Role: keep only test-area rules here.
 Keep here: runtime verification guidance, selector strategy, test-specific reuse rules, and authenticated test-flow expectations.
 Do not put here: production implementation rules, page/service architecture contracts, or duplicated project workflow that belongs in broader AGENTS files.
 
-Diagnostics source of truth: project-root `diagnostics.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
 - 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/app/index.ts

@@ -38,20 +38,34 @@ const normalizeModulePath = (value: string) => value.replace(/\\/g, '/').replace
 
 const resolveTranspileModuleDirectories = ({
     moduleNames,
-    nodeModulesRoots,
+    resolvePackageRoot,
+    getVisiblePackageInstallRoots,
 }: {
     moduleNames: string[];
-    nodeModulesRoots: string[];
+    resolvePackageRoot: (moduleName: string) => string;
+    getVisiblePackageInstallRoots: (moduleName: string) => string[];
 }) => {
     const directories = new Set<string>();
 
     for (const moduleName of moduleNames) {
-        for (const nodeModulesRoot of nodeModulesRoots) {
-            const candidate = normalizeModulePath(path.join(nodeModulesRoot, moduleName));
+        const candidates = new Set<string>();
+
+        try {
+            candidates.add(normalizeModulePath(resolvePackageRoot(moduleName)));
+        } catch {}
+
+        for (const visibleInstallRoot of getVisiblePackageInstallRoots(moduleName)) {
+            candidates.add(normalizeModulePath(visibleInstallRoot));
+        }
+
+        for (const candidate of candidates) {
             if (!fs.existsSync(candidate)) continue;
 
             directories.add(candidate);
-            directories.add(normalizeModulePath(fs.realpathSync(candidate)));
+
+            try {
+                directories.add(normalizeModulePath(fs.realpathSync(candidate)));
+            } catch {}
         }
     }
 
@@ -136,15 +150,25 @@ export class App {
     public get transpileModuleDirectories() {
         return resolveTranspileModuleDirectories({
             moduleNames: this.transpile,
-            nodeModulesRoots: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
+            resolvePackageRoot: (moduleName) => cli.paths.resolvePackageRoot(moduleName),
+            getVisiblePackageInstallRoots: (moduleName) => cli.paths.getVisiblePackageInstallRoots(moduleName),
         });
     }
 
     public isTranspileModuleFile(filepath: string) {
         const normalizedFilepath = normalizeModulePath(path.resolve(filepath));
+        let normalizedRealFilepath: string | undefined;
+
+        try {
+            normalizedRealFilepath = normalizeModulePath(fs.realpathSync(filepath));
+        } catch {}
 
         return this.transpileModuleDirectories.some(
-            (directory) => normalizedFilepath === directory || normalizedFilepath.startsWith(directory + '/'),
+            (directory) =>
+                normalizedFilepath === directory ||
+                normalizedFilepath.startsWith(directory + '/') ||
+                normalizedRealFilepath === directory ||
+                normalizedRealFilepath?.startsWith(directory + '/') === true,
         );
     }