proteum 2.1.0-5 → 2.1.1

package/AGENTS.md

@@ -1,71 +1,59 @@
 # Proteum Core
 
-This file governs work in the Proteum framework repository itself.
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/framework/AGENTS.md`.
 
-For the canonical Proteum app contract used by downstream projects, use `agents/framework/AGENTS.md`.
+## Priorities
 
-## Vision
-
-Proteum aims to become the first SSR / SEO / TypeScript framework built primarily for non-human developers and AI agents.
-
-When tradeoffs exist, prioritize framework decisions in this order:
+When tradeoffs exist, optimize in this order:
 
 1. Reduce shipped client bundle size and unnecessary runtime code.
-2. Increase build-time, server-time, and browser-time performance.
-3. Improve SEO output and LLM-friendly, crawlable, semantic HTML.
+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.
 
-When working on Proteum itself:
+## Core Rules
 
-- prefer explicit, typed, machine-readable contracts over runtime magic or hidden conventions
-- keep `server/index.ts` as the canonical type root for app services, router services, request context, and models
-- keep generated code deterministic, auditable, and easy to map back to source files
-- prefer typed request traces and manifest-backed diagnostics over ad hoc runtime logging
-- prefer deleting obsolete compatibility layers, helper indirection, and unused packages over preserving dead paths
+- 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.
+- Delete obsolete compatibility layers, helper indirection, and unused packages when safe.
 
 ## Workflow
 
-- Every time I input error messages without any instructions, do not implement fixes. Instead, investigate the potential causes and, for each one:
-  1. evaluate or quantify the probability
-  2. explain why
-  3. suggest how to fix it
-- When you have finished your work, summarize in one top-level short sentence all the changes you made since the beginning of the conversation. Output as `Commit message`. Max 90 characters.
-
-## Framework Change 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.
+- End your work with `Commit message`: one short top-level sentence, max 90 characters.
 
-When changing Proteum itself:
+## Core Changes
 
-- validate the change against these two reference apps:
+- Validate framework changes against both reference apps:
   - `/Users/gaetan/Desktop/Projets/crosspath/platform`
   - `/Users/gaetan/Desktop/Projets/unique.domains/website`
-- inspect how both apps currently use the feature, runtime, API, compiler behavior, or generated files before proposing or implementing a core change
-- prefer removing framework magic when the same result can be expressed with explicit runtime contracts, generated code, or typed context
-- if a webpack plugin, Babel plugin, alias, helper, runtime service, or npm package is not meaningfully used by both apps, challenge its existence
-- keep core changes aligned with the explicit controller/page architecture described in `agents/framework/AGENTS.md`
-- remove related dead docs, config flags, helper files, and compatibility branches in the same pass when safe
-
-## Proposal Rules
-
-When proposing a core change:
-
-- start from the concrete mismatch or risk seen in the reference apps
-- show the target API with real client and server usage examples that match current Proteum conventions
-- distinguish the ideal end-state API from any transitional migration rule
-- explain which source files drive generated artifacts when generation changes
-- explicitly name removed behavior and why it is obsolete
+- 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`.
+- 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.
+- Remove dead docs, flags, helper files, and compatibility branches in the same pass when safe.
 
-## Validation
+## Proposals
 
-Do not stop at static analysis when the change affects runtime behavior.
+- Start from the concrete mismatch or risk visible in the reference apps.
+- Name the npm packages or package categories evaluated first when adding capability or infrastructure.
+- Show the target API with real Proteum-style client and server usage.
+- Separate the ideal end state from any migration rule.
+- Name the source files that drive generated artifacts when generation changes.
+- Explicitly name removed behavior and why it is obsolete.
 
-If a change touches routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets:
+## Runtime Validation
 
-- run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports
-- use `proteum trace arm --capture deep`, reproduce the request once, then inspect `proteum trace latest` or `proteum trace show <requestId>` when the issue is request-time behavior
-- open the real pages with Playwright
-- inspect browser console errors and warnings
-- inspect server startup and runtime errors
+Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
 
-Build-only checks are supplements, not final proof.
+- Run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports.
+- For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
+- Open the real pages with Playwright.
+- Inspect browser console errors and warnings.
+- Inspect server startup and runtime errors.
 
-Keep iterating until both apps boot and the browser console shows no new framework regressions. Treat unrelated environment warnings separately and call them out clearly.
+Build-only checks are supplementary. Iterate until both apps boot and show no new framework regressions, and call unrelated environment warnings out separately.

package/README.md

@@ -38,6 +38,7 @@ my-app/
   identity.yaml
   .env               # optional file for required local env vars
   package.json
+  commands/
   client/
     pages/
       _layout/
@@ -68,6 +69,7 @@ Important files:
 - `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
 - `client/pages/**`: SSR page entrypoints registered through `Router.page(...)`
 - `server/controllers/**`: request handlers that extend `Controller`
+- `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
 - `.proteum/**`: framework-owned generated contracts and manifests
 
@@ -200,6 +202,35 @@ Controller rules:
 - call business logic through `this.services`, `this.models`, or `this.app`
 - return explicit values instead of relying on ambient globals
 
+## Example: Command
+
+Proteum commands are explicit dev-only internal entrypoints.
+
+```ts
+import { Commands } from '@server/app/commands';
+
+export default class DiagnosticsCommands extends Commands {
+  public async ping() {
+    const { Stats } = this.services;
+
+    return {
+      app: this.app.identity.identifier,
+      domains: await Stats.general(),
+    };
+  }
+}
+```
+
+Command rules:
+
+- files live under `commands/**/*.ts`
+- each file default-exports 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 when needed
+- `commands/tsconfig.json` and `.proteum/server/commands.d.ts` give `/commands` its own dev-only alias and app typing surface
+- commands run only in dev contexts: `proteum command ...`, the dev profiler, or dev-only `__proteum/commands` endpoints
+
 ## Example: Service
 
 Proteum services keep business logic out of request handlers.
@@ -234,6 +265,7 @@ Typical generated artifacts:
 - `.proteum/client/controllers.ts`
 - `.proteum/client/layouts.ts`
 - `.proteum/common/controllers.ts`
+- `.proteum/server/commands.ts`
 - `.proteum/server/routes.ts`
 - `.proteum/server/controllers.ts`
 
@@ -256,6 +288,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum doctor` | Inspect manifest diagnostics |
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
 | `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 init` | Experimental project scaffolding when scaffold assets are installed |
 
 Recommended daily workflow:
@@ -273,13 +306,29 @@ Useful inspection commands:
 proteum doctor
 proteum doctor --json
 proteum explain
-proteum explain --routes --controllers
+proteum explain --routes --controllers --commands
 proteum explain --all --json
+proteum command proteum/diagnostics/ping
+proteum command proteum/diagnostics/ping --port 3101
 proteum trace requests
 proteum trace arm --capture deep
 proteum trace latest
 ```
 
+## Dev Commands
+
+Proteum includes a dev-only command surface for internal testing, debugging, and one-off execution that should not become a normal controller or route.
+
+- commands live under `./commands/**/*.ts`
+- each file default-exports a class extending `Commands` from `@server/app/commands`
+- each method is addressed by `file/path/methodName`
+- Proteum creates `commands/tsconfig.json` when the folder exists so command files inherit the server alias/type project
+- `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
+
+Proteum itself also ships a small built-in diagnostic command at `proteum/diagnostics/ping`, so the command surface is never empty in dev.
+
 ## Request Tracing
 
 Proteum includes a dev-only in-memory request trace buffer for routing, controller, context, SSR, and render debugging.
@@ -299,6 +348,7 @@ Default behavior:
 - traces live in memory and are bounded by `TRACE_REQUESTS_LIMIT` and `TRACE_EVENTS_LIMIT`
 - payloads are summarized, long strings are truncated, and sensitive fields such as cookies, passwords, and tokens are redacted
 - `TRACE_PERSIST_ON_ERROR` can export crashing requests under `var/traces/`
+- `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
 
 Trace env example:
 
@@ -337,6 +387,7 @@ Proteum answers those questions with explicit artifacts:
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
 - `proteum doctor --json` for structured diagnostics
+- `proteum command ...` plus the profiler `Commands` tab for dev-only internal execution
 
 If you are an LLM or automation agent, start here:
 

package/agents/framework/AGENTS.md

@@ -1,30 +1,27 @@
 # Proteum App Contract
 
-This is the canonical framework contract for Proteum-based projects.
+This is the canonical contract for Proteum-based projects. Local project `AGENTS.md` files should add deltas only, not restate these rules.
 
-Local project `AGENTS.md` files should only add project-specific deltas. They should not restate the framework contract.
+## First Pass
 
-## Fast Start
-
-When you enter a Proteum app, inspect it in this order:
+Inspect apps in this order:
 
 1. Run `npx proteum explain --json` or read `./.proteum/manifest.json`.
-2. Inspect `./server/index.ts` and `./server/config/*.ts`.
-3. Inspect the touched `./server/controllers/**/*.ts`, `./server/services/**`, `./server/routes/**`, and `./client/pages/**` files.
-4. Run `npx proteum doctor` if routing or generation looks suspicious.
-5. If you need to diagnose or test against a running app, check the default port in `PORT` or `./.proteum/manifest.json` first.
-6. If a server is already running on that port, use `npx proteum trace` to inspect past requests, errors, and their context before reproducing the issue or adding temporary logs.
+2. Inspect `./server/index.ts`, `./server/config/*.ts`, and the touched files under `./commands`, `./server/controllers`, `./server/services`, `./server/routes`, and `./client/pages`.
+3. Run `npx proteum doctor` if routing or generation looks suspicious.
+4. For request-time issues in dev, read the default port from `PORT` or `./.proteum/manifest.json`; if a server is already running there, inspect `npx proteum trace` output before reproducing the issue or adding logs.
+5. If existing traces are insufficient, run `npx proteum trace arm --capture deep`, reproduce once, then inspect the captured request.
 
 ## Non-Negotiable Rules
 
-- Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)` calls.
+- 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`.
-- Manual HTTP endpoints live in `server/routes/**`.
-- Controllers validate input with `this.input(schema)` inside the method body.
-- Call `this.input(...)` at most once per controller method.
-- Request-scoped state exists only on `this.request` and router/manual-route context objects.
-- SSR page data belongs in the page `setup` return object, not in `api.fetch(...)`.
+- 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.
+- SSR page data belongs in page `setup`, not in `api.fetch(...)`.
 - Normal service methods do not read request state directly.
 - Do not import runtime values from `@models`.
 - Do not use `@request` runtime globals.
@@ -34,233 +31,115 @@ When you enter a Proteum app, inspect it in this order:
 
 ## Source Of Truth
 
-Proteum reads these source files directly:
+Proteum reads:
 
 - `package.json`
 - `identity.yaml`
-- `process.env` via the `PORT`, `ENV_*`, `URL`, and `TRACE_*` env contract
+- `process.env` via `PORT`, `ENV_*`, `URL`, and `TRACE_*`
 - `server/config/*.ts`
 - `server/index.ts`
 - `server/services/**/service.json`
+- `commands/**/*.ts`
 - `server/controllers/**/*.ts`
 - `server/routes/**/*.ts`
 - `client/pages/**/*.ts(x)`
 - `client/pages/**/_layout/index.tsx`
 - `public/**`
 
-Proteum generates and owns:
+Proteum owns:
 
 - `.proteum/manifest.json`
 - `.proteum/client/*`
 - `.proteum/common/*`
 - `.proteum/server/*`
 
-Project code should use:
+Project code should consume:
 
 - `@generated/client/*`
 - `@generated/common/*`
 - `@generated/server/*`
-- `@/client/context` for the generated client context entrypoint
-
-Use the structured CLI surfaces instead of re-deriving framework facts from source whenever possible:
-
-- `npx proteum explain --json`: app structure, services, controllers, routes, layouts, diagnostics
-- `npx proteum doctor --json`: manifest-backed diagnostics
-- `npx proteum trace ...`: live dev-only request traces
-
-## App Bootstrap And Services
-
-`server/index.ts` is the canonical type root and the explicit application graph.
-
-Rules:
-
-- `server/index.ts` must default-export the app `Application` subclass
-- 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
-- `server/services/**/service.json` plus `server/index.ts` drive generated service typings and manifest service entries
-
-Service rules:
-
-- business logic lives in classes that extend `Service`
-- 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
-- use subservices when a feature has multiple coherent domains and the root class is growing
-
-## Controllers
-
-Controller rules:
-
-- files live under `server/controllers/**/*.ts`
-- each file default-exports 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 when needed
-- generated client calls use `POST`
-
-Controller workflow:
-
-1. destructure the service or router helper you need
-2. validate once with `this.input(schema)`
-3. resolve auth and other request-derived values from `this.request`
-4. pass explicit typed values into a service method
-
-## Client Pages
-
-Compiler rules:
-
-- Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls
-- the file path controls chunk identity and layout discovery
-- the route path comes from the explicit string in `Router.page(...)`
-
-Supported signatures:
-
-```ts
-Router.page('/path', render);
-Router.page('/path', setup, render);
-Router.page('/path', options, render);
-Router.page('/path', options, setup, render);
-```
-
-For new work, prefer:
-
-```ts
-Router.page('/path', setup, render);
-Router.page('/path', options, setup, render);
-```
-
-`setup` rules:
-
-- return one flat object
-- keys like `_auth`, `_layout`, `_static`, `_redirectLogged`, and other reserved setup keys are route options
-- every other key is SSR data
-- controller fetchers and promises are resolved before render
-- plain values may also be returned
-
-`render` rules:
-
-- consume resolved setup data there
-- use generated controller methods from the 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/**`
-
-## Client Context And Controller Calls
-
-Use the generated client context entrypoint:
-
-```ts
-import useContext from '@/client/context';
-```
-
-Then call generated controllers directly:
-
-```ts
-const { Founder } = useContext();
-await Founder.projects.updateProject(payload);
-```
-
-Use direct controller calls for interactions. Do not recreate fake runtime imports or client-side `@app` access.
-
-## Manual Server Routes
-
-Use `server/routes/**` only for explicit HTTP behavior that should not be a generated controller action.
-
-Good fits:
-
-- redirects
-- sitemap or RSS
-- OAuth callbacks
-- webhooks
-- public resources with custom semantics
-
-Rules:
-
-- import server-side app services from `@app`
-- use route handler context for `request`, `response`, router plugins, and custom router context
-- if the route is just a normal app API, prefer a controller instead
-
-## Models And Aliases
-
-Use Prisma typings from:
-
-```ts
-import type * as Models from '@models/types';
-```
-
-Use runtime models through:
-
-- `this.models`
-- `this.app.Models.client`
-
-Rules:
-
-- do not import runtime values from `@models`
-- keep Prisma runtime access inside services when possible
-- prefer explicit `select` or narrow `include`
-- do not edit generated Prisma client files
-
-Relevant 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
-
-## Task Playbooks
-
-### Add A New App API
-
-1. Add or extend a root service under `server/services/<Feature>/index.ts`.
-2. Add or update `server/services/<Feature>/service.json`.
-3. Add a controller under `server/controllers/**`.
-4. Validate once with `this.input(schema)`.
-5. Resolve auth and request-derived values in the controller.
-6. Call the service from the client through the generated controller tree.
-
-### Add A New SSR Page
-
-1. Create or update `client/pages/.../index.tsx`.
-2. Register `Router.page('/real-url', setup, render)`.
-3. Return `_auth`, `_layout`, and SSR data from `setup`.
-4. Read resolved data in `render`.
-5. Use `@/client/context` or render args only for interactive follow-up actions.
-
-### Add A New Manual Route
-
-1. Create `server/routes/...`.
-2. Import `Router` and needed app services from `@app`.
-3. Register `Router.get/post/put/patch/delete(...)`.
-4. Return response helpers or raw serializable data.
-
-### Diagnose A Runtime Issue
-
-1. Run `npx proteum explain --json`.
-2. Run `npx proteum doctor`.
-3. Read the default port from `PORT` or `./.proteum/manifest.json` and check whether a server is already running there.
-4. If a server is already running on that default port, inspect existing traces first:
-   - `npx proteum trace requests --port <envPort>`
-   - `npx proteum trace latest --port <envPort>`
-   - `npx proteum trace show <requestId> --port <envPort>` when you need the full context for a past error
-5. If the issue is request-time behavior in dev and the existing traces are not enough, run:
-   - `npx proteum trace arm --capture deep --port <envPort>`
-   - reproduce the failing request once
-   - `npx proteum trace latest --port <envPort>` or `npx proteum trace show <requestId> --port <envPort>`
-6. Inspect the touched controller, service, route, or page source.
-7. Only add temporary logging if the trace is insufficient.
-
-For the full trace reference, see `node_modules/proteum/docs/request-tracing.md` in installed apps or `docs/request-tracing.md` in the framework repository.
-
-## Preferred Patterns
-
-- explicit `server/index.ts` bootstrap over hidden registration
-- `Router.page(path, setup, render)` over page-local fetch hacks
-- controller-backed app APIs over ad hoc manual `/api/...` route files
-- service classes over random server helpers with hidden dependencies
-- one canonical source of truth for catalogs, registries, and shared types
-- project-local Shadcn-based UI primitives when the app already provides them
+- `@/client/context` as the generated client context entrypoint
+
+Prefer structured CLI surfaces over re-deriving framework facts from source:
+
+- `npx proteum explain --json`
+- `npx proteum doctor --json`
+- `npx proteum trace ...`
+- `npx proteum command ...`
+
+## 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.
+- `server/services/**/service.json` plus `server/index.ts` drive generated service typings and manifest entries.
+- 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.
+
+### 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`.
+
+### 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.
+
+### 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/**`.
+
+### 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.
+
+### 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
+
+## 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 project-local Shadcn-based UI primitives when the app already provides them.
+- Before inventing a helper, primitive, parser, formatter, SDK wrapper, or build-time tool, first check whether the repo already depends on a suitable package.
+- If it does not, search npm before writing a custom implementation.
+- Prefer widely adopted, actively maintained, flexible, well-typed packages.
+- Only build custom infrastructure when packages would clearly hurt bundle size, SSR behavior, performance, explicit contracts, or long-term maintainability.
+- If you choose custom over a package, state briefly why.
 
 ## Discouraged Patterns
 
@@ -276,21 +155,10 @@ For the full trace reference, see `node_modules/proteum/docs/request-tracing.md`
 Verify at the correct layer:
 
 - route additions: boot the app and hit the real URL
-- controller changes: exercise the generated client call or the generated `/api/...` endpoint
+- 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/plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
-
-When you need to diagnose or test against an app that may already be running:
-
-- read the default port from `PORT` or `./.proteum/manifest.json`
-- check whether a server is already running on that port
-- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue
+- router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
 
-Useful app commands:
+When an app may already be running, check the default port from `PORT` or `./.proteum/manifest.json` and inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue. If those traces are not enough, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
 
-- `proteum dev`
-- `npx proteum refresh`
-- `npx proteum typecheck`
-- `npx proteum lint`
-- `npx proteum check`
-- `npx proteum build prod`
+Useful commands: `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum command <path>`.