proteum 2.1.9 → 2.2.1

package/.codex/environments/environment.toml

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

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Proteum Core
 
-This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md`.
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/project/AGENTS.md` for the standalone app-root contract, or split between `agents/project/root/AGENTS.md` and `agents/project/app-root/AGENTS.md` in a monorepo.
 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/**`.
@@ -19,34 +19,47 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 - Keep `server/index.ts` as the canonical type root for services, router context, request context, and models.
 - Keep generated code deterministic, auditable, and easy to map back to source.
 - Prefer typed traces, perf rollups, and manifest-backed diagnostics over ad hoc logging.
+- For Prisma-backed apps, declare database structure changes in the app's `schema.prisma` only. Never create or edit migration files manually, and never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, or `DROP TABLE`.
 - Follow `agents/project/optimizations.md` when choosing packages, helpers, runtimes, plugins, or build infrastructure.
 - Delete obsolete compatibility layers, helper indirection, and unused packages when safe.
 
 ## Workflow
 
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+- If you changed any app `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
+```
+cd <worktree path>
+npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
+```
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
-- When starting a long-lived reference app dev server for framework work, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
+- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link such as `[http://localhost:3100](http://localhost:3100)`.
+- Do not use `--replace-existing` unless you are 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.
+- When a reference app uses local `file:` connected projects for the affected flow, boot every connected producer app as well, each on its own free port and thread-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or validating the consumer app.
 - Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
 - If the task changed the dev workflow itself, verify the final cleanup path with `npx proteum dev list --json` before finishing.
-- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
-```
-Commit message: <type>[optional scope]: <description>
+- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence ALL the changes you made since the beginning of the WHOLE conversation. Strictly use the Conventional Commits specification:
+  ```
+  Commit message: <type>[optional scope]: <description>
 
-[optional body]
-```
+  [optional body]
+  ```
+  If the user replies exactly `commit`, use that Conventional Commit message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, then create the commit by running `git commit`.
+  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 Changes
 
 - Validate framework changes against the reference apps:
   - `/Users/gaetan/Desktop/Projets/crosspath/platform`: Standalone app
+  - `/Users/gaetan/Desktop/Projets/crosspath/website`: Standalone app
   - `/Users/gaetan/Desktop/Projets/unique.domains/platform`: Monorepo including the following apps:
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/product`
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
-- Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
-- Keep core changes aligned with the explicit controller/page architecture in `agents/project/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/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
+- Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
+- Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.
 - Remove dead docs, flags, helper files, and compatibility branches in the same pass when safe.
@@ -64,13 +77,16 @@ Commit message: <type>[optional scope]: <description>
 
 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 --replace-existing --session-file var/run/proteum/dev/framework-<app>.json --port 3xxx` in both reference apps on explicit ports.
+- Run `npx proteum dev --no-cache --session-file var/run/proteum/dev/framework-<app>.json --port <free-3xxx-port>` in both reference apps on explicit free ports and with elevated permissions outside the sandbox.
+- If either reference app uses local `file:` connected projects for the affected flow, run those producer apps too on their own free ports before exercising the consumer.
 - 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.
 - When a framework change can affect shipped client code size, run `proteum build --prod --analyze` for static bundle artifacts or `proteum build --prod --analyze --analyze-serve --analyze-port auto` when you need a local analyzer URL.
 - For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` to mint a dev auth cookie instead of automating the login UI. Use the login UI only when login itself is the feature under test.
+- When a task needs browser execution instead of the higher-level verifier, prefer `npx proteum verify browser <path>` or direct Playwright with a disposable profile. Keep auth sourced from `npx proteum session`, not UI login or shared browser state.
 - For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
 - When the framework-facing workflow itself changed, verify the CLI surface too with `proteum verify framework-change --crosspath-port <port> --product-port <port> --website-port <port>`.
+- Only the final verifier agent should usually run browser flows. Other agents should stay on `orient`, `verify owner`, `verify request`, and command-level checks unless browser execution is the only trustworthy surface.
 - Open the real pages with Playwright.
 - Inspect browser console errors and warnings.
 - Inspect server startup and runtime errors.

package/README.md

@@ -4,6 +4,14 @@ Proteum is an LLM-first SSR / SEO / TypeScript framework for full-stack web appl
 
 It is built for teams that want explicit server contracts, server-first rendering, deterministic generated artifacts, and a codebase that an AI agent can inspect without reverse-engineering hidden runtime magic.
 
+Migration guide for older apps: [docs/migrate-from-2.1.3.md](docs/migrate-from-2.1.3.md)
+
+## Sponsor
+
+Proteum is sponsored by [Unique Domains](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor).
+
+[![Unique Domains](docs/assets/unique-domains-chip.png)](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor)
+
 ## Why Proteum
 
 Most full-stack frameworks optimize first for human convenience.
@@ -24,7 +32,7 @@ Proteum combines:
 
 ## Core Principles
 
-- **Server-first by default.** Put data loading in the page setup function and keep client code focused on UI.
+- **Server-first by default.** Put data loading in the page data function and keep client code focused on UI.
 - **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.
@@ -69,7 +77,7 @@ Important files:
 - `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(...)`
+- `client/pages/**`: SSR page entrypoints registered through `Router.page(path, options, data, render)`
 - `server/controllers/**`: request handlers that extend `Controller`
 - `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
@@ -99,6 +107,7 @@ Optional trace env vars:
 - `TRACE_EVENTS_LIMIT`
 - `TRACE_CAPTURE`
 - `TRACE_PERSIST_ON_ERROR`
+- `ENABLE_PROFILER`
 
 Optional `proteum.config.ts` fields:
 
@@ -192,9 +201,11 @@ import Router from '@/client/router';
 
 Router.page(
   '/',
+  {
+    auth: false,
+    layout: false,
+  },
   ({ Plans, Stats }) => ({
-    _auth: false,
-    _layout: false,
     plans: Plans.getPlans(),
     stats: Stats.general(),
   }),
@@ -207,9 +218,10 @@ Router.page(
 What happens here:
 
 - the first argument is the route path
-- the optional setup function runs on the server for SSR data loading
-- keys prefixed with `_` become route options such as `_auth`, `_layout`, `_static`, or `_redirectLogged`
-- every other returned key becomes page data
+- the second argument is the explicit route-options object
+- the third argument is the page data function or `null`
+- route behavior such as `auth`, `layout`, `static`, or `redirectLogged` lives in the options object
+- every key returned from the data function becomes page data
 - the renderer receives the resolved data and the generated controller/service context
 
 ## Example: Controller
@@ -334,6 +346,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `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 configure agents` | Interactively configure Proteum-managed instruction symlinks and confirm overwrites for standalone or monorepo apps |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
 Recommended daily workflow:
@@ -347,7 +360,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
+Only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
 
 Useful inspection commands:
 
@@ -383,11 +396,14 @@ Useful scaffolding commands:
 ```bash
 proteum init my-app --name "My App"
 proteum init my-app --name "My App" --dry-run --json
+proteum configure agents
 proteum create page marketing/faq --route /faq
 proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
+`proteum configure agents` asks before replacing any existing non-managed instruction file or foreign symlink. If you decline, that path is left untouched.
+
 `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
@@ -455,6 +471,7 @@ Default behavior:
 - 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
+- `ENABLE_PROFILER=true` reuses the same instrumentation path to populate `request.profiling` and the router `request.finished` hook with a reduced request/API/SQL snapshot in any environment, without retaining finished requests in the global trace buffer unless dev trace is also enabled
 
 Trace env example:
 
@@ -464,6 +481,7 @@ export TRACE_REQUESTS_LIMIT=200
 export TRACE_EVENTS_LIMIT=800
 export TRACE_CAPTURE=resolve
 export TRACE_PERSIST_ON_ERROR=true
+export ENABLE_PROFILER=true
 ```
 
 Capture modes:
@@ -491,7 +509,7 @@ Proteum answers those questions with explicit artifacts:
 
 - `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
+- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, `TRACE_*`, and `ENABLE_PROFILER` 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
@@ -507,12 +525,12 @@ Proteum answers those questions with explicit artifacts:
 If you are an LLM or automation agent, start here:
 
 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`.
+2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, plus `TRACE_*` and `ENABLE_PROFILER`, 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.
+7. Inspect `client/pages/**` for SSR routes and page data 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`, `proteum diagnose`, `proteum perf`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
@@ -576,6 +594,7 @@ Then use the normal workflow:
 
 ```bash
 npm install
+npx proteum configure agents
 npx proteum dev
 npx proteum check
 npx proteum build --prod