proteum 2.1.3-1 → 2.1.7

package/AGENTS.md

@@ -1,40 +1,44 @@
 # Proteum Core
 
-This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/framework/AGENTS.md`.
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md`.
+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/**`.
+Downstream app optimization source of truth: `agents/project/optimizations.md`.
+Downstream app diagnostics source of truth: `agents/project/diagnostics.md`.
+Downstream app coding style source of truth: `agents/project/CODING_STYLE.md`.
 
 ## Priorities
 
-When tradeoffs exist, optimize in this order:
-
-1. Reduce shipped client bundle size and unnecessary runtime code.
-2. Improve build-time, server-time, and browser-time performance.
-3. Improve SEO output and crawlable, semantic HTML.
-4. Preserve explicit, typed, machine-readable contracts for agents.
+Optimization priorities and rules live in `agents/project/optimizations.md`.
+After those optimization concerns, preserve explicit, typed, machine-readable contracts for agents.
 
 ## Core Rules
 
 - Prefer explicit typed contracts over runtime magic or hidden conventions.
 - 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 and manifest-backed diagnostics over ad hoc logging.
-- Check existing repo dependencies and npm before inventing a new helper, runtime, plugin, or abstraction.
-- Prefer established, flexible, well-typed packages; build custom only when packages fail on bundle size, performance, SSR behavior, typing, flexibility, or maintenance risk.
+- Prefer typed traces, perf rollups, and manifest-backed diagnostics over ad hoc logging.
+- 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.
-- End your work with `Commit message`: one short top-level sentence, max 90 characters.
+- 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 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. Output as "Commit message".
 
 ## Core Changes
 
-- Validate framework changes against both reference apps:
+- Validate framework changes against the reference apps:
   - `/Users/gaetan/Desktop/Projets/crosspath/platform`
+  - `/Users/gaetan/Desktop/Projets/unique.domains/product`
   - `/Users/gaetan/Desktop/Projets/unique.domains/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
-- Keep core changes aligned with the explicit controller/page architecture in `agents/framework/AGENTS.md`.
+- Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
+- 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.
-- Challenge any webpack plugin, Babel plugin, alias, helper, runtime service, or npm package that is not meaningfully used by both apps.
+- 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.
 
 ## Proposals
@@ -51,7 +55,11 @@ When tradeoffs exist, optimize in this order:
 Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
 
 - Run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports.
+- When validating a concrete route, controller path, or failing page on a running dev server, prefer `proteum diagnose <path> --port <port>` first. Use raw `proteum trace ...` output when you need lower-level event detail beyond the diagnose summary.
+- When the issue is latency, CPU, SQL cost, render cost, or memory drift, inspect `proteum perf top`, `proteum perf request`, `proteum perf compare`, or `proteum perf memory` against the running dev server before adding custom instrumentation.
+- 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.
 - 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>`.
 - Open the real pages with Playwright.
 - Inspect browser console errors and warnings.
 - Inspect server startup and runtime errors.

package/README.md

@@ -28,14 +28,15 @@ Proteum combines:
 - **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
 - **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
-- **Explainability matters.** `proteum explain`, `proteum doctor`, and `proteum trace` expose the framework view of your app and its live requests, and the profiler renders the same diagnostics surfaces for humans in dev.
+- **Explainability matters.** `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` expose the framework view of your app and its live requests, and the profiler renders the same diagnostics and perf surfaces for humans in dev.
 - **SEO is not an afterthought.** Identity, routes, layouts, and SSR data are part of the app contract.
 
 ## What a Proteum App Looks Like
 
 ```text
 my-app/
-  identity.yaml
+  identity.config.ts
+  proteum.config.ts
   .env               # optional file for required local env vars
   package.json
   commands/
@@ -63,8 +64,9 @@ my-app/
 
 Important files:
 
-- `identity.yaml`: app identity, naming, locale, and SEO-facing metadata defaults
-- `process.env` / optional `.env`: `PORT`, `ENV_*`, `URL`, and `TRACE_*` environment variables loaded by the app
+- `identity.config.ts`: typed app identity, naming, locale, and SEO-facing metadata defaults via `Application.identity({ ... })`
+- `proteum.config.ts`: typed Proteum compiler and connection settings such as `transpile` and `connect` via `Application.setup({ ... })`
+- `process.env` / optional `.env`: `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen variables referenced by `proteum.config.ts`, and `TRACE_*` environment variables loaded by the app
 - `server/config/*.ts`: plain typed config exports consumed by the explicit app bootstrap
 - `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
 - `client/pages/**`: SSR page entrypoints registered through `Router.page(...)`
@@ -79,6 +81,12 @@ Required Proteum env vars:
 - `ENV_PROFILE`: `dev`, `testing`, or `prod`
 - `PORT`: default router port
 - `URL`: canonical absolute base URL for `Router.url(..., true)`
+- `URL_INTERNAL`: internal absolute base URL used by SSR and connected-project server calls
+
+If `proteum.config.ts` declares `connect`, Proteum also requires:
+
+- one explicit `connect.<Namespace>.source` value in `proteum.config.ts`
+- one explicit `connect.<Namespace>.urlInternal` value in `proteum.config.ts`
 
 Proteum does not provide defaults for required env vars. They must be defined explicitly in `process.env` or `.env`.
 
@@ -92,6 +100,37 @@ Optional trace env vars:
 - `TRACE_CAPTURE`
 - `TRACE_PERSIST_ON_ERROR`
 
+Optional `proteum.config.ts` fields:
+
+- `transpile`: array of package names that Proteum should compile from `node_modules/` instead of treating as prebuilt vendor code
+- `connect`: connected project namespaces that should be merged into generated controller helpers
+
+Example:
+
+```ts
+import { Application } from 'proteum/config';
+
+const PRODUCT_CONNECTED_SOURCE = process.env.PRODUCT_CONNECTED_SOURCE;
+const PRODUCT_URL_INTERNAL = process.env.PRODUCT_URL_INTERNAL;
+
+export default Application.setup({
+  transpile: ['@acme/components'],
+  connect: {
+    Product: {
+      source: PRODUCT_CONNECTED_SOURCE,
+      urlInternal: PRODUCT_URL_INTERNAL,
+    },
+  },
+});
+```
+
+Connected contract sources are provided explicitly through `proteum.config.ts` instead of being inferred from the namespace:
+
+- local typed source value: `file:../product`
+- remote runtime-only source value: `github:owner/repo?ref=<sha-or-branch>&path=proteum.connected.json`
+
+Use this for linked or workspace-local TypeScript packages that ship source files and must flow through Proteum's alias and SSR compilation pipeline.
+
 ## Example: Server Bootstrap
 
 Proteum app services are declared explicitly through typed config exports plus a concrete `Application` subclass.
@@ -142,7 +181,7 @@ export default class MyApp extends Application {
 }
 ```
 
-Proteum reads `server/index.ts` plus `server/services/**/service.json` to derive the installed service graph and generated type contracts.
+Proteum reads `server/index.ts` as the source of truth for installed root services and router plugins, and reads `server/config/*.ts` `Services.config(...)` exports for typed config such as service priority overrides.
 
 ## Example: Page
 
@@ -285,11 +324,15 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum lint` | Run ESLint for the current app |
 | `proteum check` | Refresh, typecheck, and lint in one command |
 | `proteum build --prod` | Produce the production server and client bundles into `bin/` |
+| `proteum connect` | Inspect connected-project sources, env, cached contracts, and imported controllers |
 | `proteum doctor` | Inspect manifest diagnostics |
-| `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
+| `proteum explain` | Explain routes, controllers, services, layouts, conventions, env, and connected projects |
+| `proteum diagnose` | Combine owner lookup, diagnostics, trace data, and server logs for one concrete route or request target |
+| `proteum perf` | Aggregate request-trace performance into hot paths, one-request waterfalls, regressions, and memory drift views |
 | `proteum trace` | Inspect live dev-only request traces from the running SSR server |
 | `proteum command` | Run a dev-only internal command locally or against a running dev server |
 | `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
+| `proteum verify` | Validate framework-facing workflows across one or more running dev apps; `framework-change` is the built-in cross-reference-app check |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
@@ -306,10 +349,22 @@ Useful inspection commands:
 
 ```bash
 proteum doctor
+proteum doctor --contracts
 proteum doctor --json
+proteum connect
+proteum connect --controllers
+proteum connect --strict
 proteum explain
+proteum explain owner /api/Auth/CurrentUser
 proteum explain --routes --controllers --commands
+proteum explain --connected --controllers
 proteum explain --all --json
+proteum diagnose /
+proteum diagnose /dashboard --port 3101
+proteum perf top --since today
+proteum perf request /dashboard --port 3101
+proteum perf compare --baseline yesterday --target today --group-by route
+proteum perf memory --since 1h --group-by controller
 proteum command proteum/diagnostics/ping
 proteum command proteum/diagnostics/ping --port 3101
 proteum session admin@example.com --role ADMIN --port 3101
@@ -329,7 +384,7 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
-`proteum explain` and `proteum doctor` share the same manifest-backed diagnostics contract as the profiler `Explain` and `Doctor` tabs. For the full dev diagnostics model, see [docs/diagnostics.md](docs/diagnostics.md).
+`proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md) and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands
 
@@ -342,15 +397,36 @@ Proteum includes a dev-only command surface for internal testing, debugging, and
 - `proteum command foo/bar` refreshes generated artifacts, builds the dev output, starts a temporary local dev server, runs the command, prints the result, and exits
 - `proteum command foo/bar --port 3101` runs the same command against an existing `proteum dev` instance
 - the dev profiler exposes the same command list and run action through the `Commands` tab
-- the same profiler also exposes `Explain` and `Doctor` tabs backed by the same manifest diagnostics contract as the CLI
+- the same profiler also exposes `Explain`, `Doctor`, and `Diagnose` tabs backed by the same diagnostics contract as the CLI
 
 Proteum itself also ships a small built-in diagnostic command at `proteum/diagnostics/ping`, so the command surface is never empty in dev.
 
+## Dev Sessions
+
+Proteum includes a dev-only auth bootstrap command for browser automation, API probes, and protected-route debugging without driving the login UI.
+
+- `proteum session <email>` mints a session for a known user
+- `--role <role>` asserts that the resolved user has the expected role before returning the session
+- `--port <port>` or `--url <baseUrl>` targets an existing `proteum dev` server
+- without `--port` or `--url`, Proteum starts a temporary local dev server, creates the session, prints the payload, and exits
+- output includes the raw token, a `Cookie:` header, and a Playwright-ready `cookies` payload
+- prefer this command when an LLM or test runner needs an authenticated dev context
+- do not use it when the login flow itself is what you are testing
+
+Typical usage:
+
+```bash
+proteum session admin@example.com --role ADMIN --port 3101
+proteum session god@example.com --role GOD --json
+```
+
+The CLI talks to the running app over the dev-only `__proteum/session/start` endpoint and uses the auth service registered on the current app router. For the full guide, see [docs/dev-sessions.md](docs/dev-sessions.md).
+
 ## Request Tracing
 
-Proteum includes a dev-only in-memory request trace buffer for auth, routing, controller, context, SSR, and render debugging.
+Proteum includes a dev-only in-memory request trace buffer for auth, routing, controller, context, SSR, API, Prisma SQL, and render debugging.
 
-This is separate from `proteum explain` and `proteum doctor`: tracing is live request-time data, while explain/doctor are manifest-backed structure and diagnostics.
+This is separate from `proteum explain` and `proteum doctor`: tracing is live request-time data, while explain/doctor are manifest-backed structure and diagnostics. `proteum perf` aggregates the same trace buffer into hot-path, waterfall, compare, and memory views. When you already know the failing path and want the fastest suspect list, start with `proteum diagnose`; when the issue is performance, start with `proteum perf`; then drop into raw trace output only if needed.
 
 When diagnosing or testing against an app, first read the default port from `PORT` or `./.proteum/manifest.json` and check whether a server is already running there. If it is, inspect the existing traces before reproducing the issue so you can collect past errors and their context.
 
@@ -360,6 +436,13 @@ When diagnosing or testing against an app, first read the default port from `POR
 - `proteum trace arm --capture deep`: force the next request into deep capture mode
 - `proteum trace export <requestId>`: write one trace to disk
 - `proteum trace latest --url http://127.0.0.1:3010`: target a non-standard dev base URL directly
+- `proteum diagnose /dashboard --port 3101`: combine owner lookup, diagnostics, trace summary, and buffered logs for one concrete path
+- `proteum perf top --since today`: rank the hottest traced paths in the selected window
+- `proteum perf request /dashboard --port 3101`: inspect one traced request with stage timings, CPU, SQL, render, and memory deltas
+- `proteum perf compare --baseline yesterday --target today --group-by route`: compare regression deltas between two windows
+- `proteum perf memory --since 1h --group-by controller`: rank recent heap and RSS drift
+
+Trace summaries include `sql=<count>`. Detailed trace output includes `Calls` and `SQL` sections so API/fetcher activity and Prisma queries can be inspected together.
 
 Default behavior:
 
@@ -385,7 +468,9 @@ Capture modes:
 - `resolve`: adds auth, route resolution, and controller/context steps
 - `deep`: adds route skip reasons and deeper payload summaries for one request investigation
 
-The trace CLI talks to the running dev server over the dev-only `__proteum/trace` HTTP endpoints. Use `--port` for a different local port or `--url` when the host itself is non-standard. For the full guide, see [docs/request-tracing.md](docs/request-tracing.md).
+In the dev profiler, the request-trace tabs are now visual as well as textual: `Summary`, `Auth`, `Routing`, `Controller`, `SSR`, `API`, `SQL`, `Errors`, `Diagnose`, `Explain`, `Doctor`, `Commands`, and `Cron` all add focused charts over the same live contracts, while `Perf` remains the aggregated hot-path, breakdown, regression, and memory surface exposed by `proteum perf`.
+
+The trace and perf CLIs talk to the running dev server over the dev-only `__proteum/trace` and `__proteum/perf` HTTP endpoints. Use `--port` for a different local port or `--url` when the host itself is non-standard. For the full guide, see [docs/request-tracing.md](docs/request-tracing.md).
 
 ## LLM-Friendly By Design
 
@@ -400,26 +485,33 @@ Proteum is built so an agent can answer these questions quickly and reliably:
 
 Proteum answers those questions with explicit artifacts:
 
-- `identity.yaml` for app identity
-- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env vars for the environment surface
+- `identity.config.ts` for app identity
+- `proteum.config.ts` for compiler and connected-project setup
+- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, and `TRACE_*` env vars for the environment surface
 - `server/index.ts` for the explicit root service graph
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
 - `proteum doctor --json` for structured diagnostics
-- the profiler `Explain` and `Doctor` tabs for a human-readable view over the same manifest-backed contract
+- `proteum doctor --contracts --json` for generated-artifact and manifest-owned file checks
+- `proteum explain owner <query>` for fast ownership lookup over routes, controllers, files, and generated artifacts
+- `proteum diagnose <path>` for a one-shot request diagnosis surface
+- `proteum perf top|request|compare|memory` for request-trace performance rollups
+- the profiler `Explain`, `Doctor`, `Diagnose`, and `Perf` tabs for a human-readable view over the same diagnostics and trace-derived perf contracts
 - `proteum command ...` plus the profiler `Commands` tab for dev-only internal execution
+- `proteum session ...` for explicit authenticated dev browser or API bootstrapping without login UI automation
 
 If you are an LLM or automation agent, start here:
 
-1. Read `identity.yaml`.
-2. Read `PORT`, the relevant `ENV_*`, `URL`, and `TRACE_*` env vars, or run `proteum explain env`.
+1. Read `identity.config.ts` and `proteum.config.ts`.
+2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, and `TRACE_*` env vars, or run `proteum explain env`.
 3. Inspect `server/index.ts` and `server/config/*.ts` for the explicit app bootstrap.
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.
 6. Inspect `server/services/**` for business logic.
 7. Inspect `client/pages/**` for SSR routes and page setup contracts.
+8. If the task touches a protected route or controller in dev and login UX is not the feature under test, use `proteum session <email> --role <role>` before Playwright or direct HTTP calls.
 
-For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
+For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, `proteum diagnose`, `proteum perf`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
 
 ## What Proteum Avoids
 

package/agents/project/AGENTS.md

@@ -1,22 +1,25 @@
-# Project Guide
+# Proteum Project Contract
 
-This file adds project-local rules on top of the canonical Proteum app contract.
+This is the canonical contract for Proteum-based projects shipped with Proteum. Narrower `AGENTS.md` files in this folder add area-specific rules on top of this file.
+Role: keep only project-wide app rules here.
+Keep here: cross-cutting project workflow, architecture contracts, shared typing rules, and rules that apply across client, server, pages, and tests.
+Do not put here: detailed diagnostics workflow, optimization checklists, coding-style details, or narrow area-specific instructions that belong in `diagnostics.md`, `optimizations.md`, `CODING_STYLE.md`, `client/AGENTS.md`, `client/pages/AGENTS.md`, `server/routes/AGENTS.md`, `server/services/AGENTS.md`, or `tests/AGENTS.md`.
 
-Framework contract:
+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`.
 
-- framework repo: `agents/framework/AGENTS.md`
-- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
-
-Coding style source of truth: `./CODING_STYLE.md`.
-
-## Fast Start
+## Workflow
 
-- Start with `./.proteum/manifest.json`, `npx proteum explain`, and `npx proteum doctor`.
-- For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand.
-- Use `--dry-run --json` on scaffold commands when an agent needs a machine-readable plan before writing files.
-- For request-time issues in dev, inspect traces before adding logs.
-- 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.
+- 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.
+- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- 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.
+- 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.
+- 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. Output as "Commit message".
 
 ## Project Shape
 
@@ -27,23 +30,164 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - `/server`: catalogs, config, services, routes, lib
 - `/tests`
 
-## Local Deltas
+## Non-Negotiable Rules
 
+- 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.
+- 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`.
+- Never edit generated files under `.proteum`.
 - Use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
 - Client context is typically imported from `@/client/context`.
-- Prefer type inference from the explicit application class in `./server/index.ts`.
-- Reuse shared Shadcn-based UI primitives when the project already provides them.
+- 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`.
+
+## 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`
+
+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
+
+### 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.
+- `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.
+- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
+- For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
+- `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
+- Controller fetchers and promises returned from `setup` resolve before render.
+- `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
+- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
+- Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
+
+### 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
 
 ## 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.
-- Only reinvent the wheel when existing packages are clearly inadequate on bundle size, SSR behavior, performance, typing quality, flexibility, licensing, or maintenance risk.
+- Follow project-root `optimizations.md` when deciding whether custom infrastructure is justified over an existing package.
 - When you choose custom over a package, explain the reason briefly.
 
 ## Catalogs And Typing
@@ -56,12 +200,31 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 - 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.
 
-## Workflow
+## Design Rules
 
-- 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.
-- For request-time behavior in dev, check whether a server is already running on the default port and prefer `npx proteum trace` before reproducing the issue or adding logs.
-- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- End your work with `Commit message`: one short top-level sentence.
+- 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
+
+## Verification
+
+Verify at the correct layer:
+
+- 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`.
+
+Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `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>`.
 
 ## High-Impact Files
 

package/agents/project/CODING_STYLE.md

@@ -8,6 +8,7 @@ This file is the source of truth for codex coding style instructions in Proteum-
 - 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 the smallest relevant project lint or check command when available; coding-style regressions are defects, not optional cleanup.
 
 ## Formatting
 

package/agents/project/client/AGENTS.md

@@ -1,22 +1,27 @@
-# Frontend
+# Frontend Contract
 
-This file adds client-side local rules on top of the canonical framework contract:
+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`.
 
-- framework repo: `agents/framework/AGENTS.md`
-- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
+Optimization source of truth: project-root `optimizations.md`.
+Diagnostics source of truth: project-root `diagnostics.md`.
+Coding style source of truth: project-root `CODING_STYLE.md`.
 
 ## Stack
 
 - TypeScript strict
 - Preact with SSR
-- follow the UI stack already used in the touched area
-- many Proteum apps use Tailwind and `@/client/components/Motion`, but those are app conventions, not framework guarantees
+- Follow the UI stack already used in the touched area.
+- Many Proteum apps use Tailwind and `@/client/components/Motion`, but those are app conventions, not framework guarantees.
 
-## Local Client Rules
+## Client Rules
 
 - Page files follow the page contract in `./pages/AGENTS.md`.
-- Components and hooks access controllers through the app client context hook, usually `useContext()` from `@/client/context`.
+- Components and hooks should reach server APIs through generated controller calls from page render args or the app client context, usually `useContext()` from `@/client/context`.
 - Prefer direct controller calls from context or page render args.
+- Prefer generated app surfaces over direct `.proteum` implementation imports.
 - Never depend on legacy `@app` imports on the client.
 - Errors from controller calls should never be silently swallowed. Rethrow or surface them clearly.