proteum 2.1.9 → 2.2.1

package/docs/diagnostics.md

@@ -1,12 +1,13 @@
 # Diagnostics and Explainability
 
-Proteum exposes two manifest-backed diagnostics surfaces plus one composite request-diagnosis surface:
+Proteum exposes three manifest-backed orientation and diagnostics surfaces plus one composite request-diagnosis surface:
 
+- `proteum orient`: resolve the likely owner, guidance files, connected boundaries, and next steps before opening code
 - `proteum explain`: inspect the generated app structure
 - `proteum doctor`: inspect manifest diagnostics
 - `proteum diagnose`: combine owner lookup, diagnostics, matching request traces, and buffered server logs for one concrete query or path
 
-These are not separate models for different tools. `explain` and `doctor` share the same generated manifest snapshot, while `diagnose` layers live dev-only request data on top of that same framework view.
+These are not separate models for different tools. `orient`, `explain`, and `doctor` share the same generated manifest snapshot, while `diagnose` layers live dev-only request data on top of that same framework view.
 
 Performance inspection is a sibling surface, not a separate instrumentation stack: `proteum perf` and the profiler `Perf` tab aggregate the same dev-only request traces that back `proteum trace`.
 
@@ -14,8 +15,9 @@ Performance inspection is a sibling surface, not a separate instrumentation stac
 
 The canonical snapshot lives in `./.proteum/manifest.json`.
 
-Proteum uses that same manifest in six places:
+Proteum uses that same manifest in seven places:
 
+- `proteum orient` for owner lookup, guidance resolution, connected-boundary summary, and next-step suggestions
 - `proteum explain` for human-readable and `--json` output
 - `proteum doctor` for human-readable and `--json` output
 - `proteum explain owner <query>` for ownership lookup over the manifest index
@@ -32,6 +34,8 @@ If a command such as `proteum explain`, `proteum doctor`, `proteum diagnose`, or
 Common usage:
 
 ```bash
+proteum orient /api/Auth/CurrentUser
+
 proteum explain
 proteum explain owner /api/Auth/CurrentUser
 proteum explain --routes --controllers --commands
@@ -46,14 +50,34 @@ proteum diagnose /
 proteum diagnose /dashboard --port 3101
 proteum diagnose /api/Auth/CurrentUser --url http://127.0.0.1:3101
 
+proteum verify owner /api/Auth/CurrentUser
+proteum verify request /dashboard --port 3101
+proteum verify browser /dashboard --port 3101 --session-email admin@example.com --session-role ADMIN
+
 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 orient --json` emits:
+
+- `query`
+- `normalizedQuery`
+- `app`
+- `guidance`
+- `owner`
+- `connected`
+- `nextSteps`
+- `warnings`
+
 `proteum explain --json` emits the selected manifest sections as machine-readable JSON.
 
+`proteum explain owner <query> --json` keeps the existing owner ranking shape and adds:
+
+- `scopeLabel`
+- `originHint`
+
 `proteum doctor --json` emits:
 
 - `summary.errors`
@@ -64,6 +88,8 @@ proteum perf memory --since 1h --group-by controller
 `proteum diagnose` emits a composite response with:
 
 - `owner`
+- `orientation`
+- `chain`
 - `doctor`
 - `contracts`
 - `request`
@@ -71,13 +97,31 @@ proteum perf memory --since 1h --group-by controller
 - `suspects`
 - `serverLogs`
 
+`proteum verify owner|request|browser --json` emits:
+
+- `action`
+- `target`
+- `orientation`
+- `introducedFindings`
+- `preExistingFindings`
+- `verificationSteps`
+- `result`
+
 `proteum perf` emits trace-derived performance views:
 
 - `top`: grouped hot paths with avg, p95, CPU, SQL, render, and heap deltas
-- `request`: one traced request waterfall with stage timings, CPU, SQL, render, self time, and payload sizes
+- `request`: one traced request waterfall with stage timings, CPU, SQL, render, self time, payload sizes, chain attribution, and SQL fingerprints
 - `compare`: grouped baseline vs target deltas
 - `memory`: grouped heap and RSS drift summaries
 
+Focused verification defaults to the smallest trustworthy surface first:
+
+- `verify owner`: orient the target, then choose request, command, or local owner-scoped diagnostics
+- `verify request`: hit one real request, collect `diagnose`, and classify introduced vs pre-existing findings
+- `verify browser`: only when browser-visible behavior matters, using an app-local isolated Playwright workspace
+
+Focused verification fails on introduced blocking findings by default and does not fail on unrelated pre-existing blockers unless `--strict-global` is passed.
+
 ## Dev HTTP Endpoints
 
 In `profile: dev`, the running app exposes:
@@ -138,14 +182,36 @@ During `proteum dev`, the bottom profiler is the human-facing UI over the same d
 
 Use the profiler when a human needs to browse the same data that an agent or CLI command can already inspect directly.
 
+## Runtime Contract Diagnostics
+
+`proteum doctor --contracts` now emits additive runtime-focused diagnostics for framework-owned failures that are often misdiagnosed as leaf-component bugs:
+
+- `runtime/provider-hook-outside-provider`
+- `runtime/client-only-hook-in-ssr`
+- `runtime/router-context-outside-router`
+- `runtime/connected-boundary-mismatch`
+
+Each diagnostic includes:
+
+- `code`
+- `message`
+- `filepath`
+- `sourceLocation`
+- `fixHint`
+- `relatedFilepaths`
+
+Treat these as framework contract failures first. The fix usually belongs at the provider, router, connected-boundary, or SSR/client split where the contract was broken, not only in the component that happened to throw.
+
 ## Agent Workflow
 
 For AI coding agents or automation:
 
-1. Read `./.proteum/manifest.json` or run `proteum explain --json`.
-2. Run `proteum doctor --json` and `proteum doctor --contracts --json` to inspect framework and generated-artifact diagnostics.
-3. Run `proteum explain owner <query>` when you need to map a route, controller path, or generated artifact back to source.
-4. For concrete request-time behavior, start with `proteum diagnose <path> --port <port>`.
-5. For performance, CPU, SQL, render, or memory questions, use `proteum perf top|request|compare|memory` against the same running dev server.
-6. Use `proteum trace ...` when you need lower-level event detail than `diagnose` or `perf` provides.
-7. Open the profiler only when a human-readable view helps; it should agree with the CLI after refresh.
+1. Start with `proteum orient <query>` when the target might be generated, connected, framework-owned, or multi-repo.
+2. Read `./.proteum/manifest.json` or run `proteum explain --json` only after you know which surface matters.
+3. Run `proteum doctor --json` and `proteum doctor --contracts --json` to inspect framework and generated-artifact diagnostics.
+4. Use `proteum verify owner <query>` or `proteum diagnose <path> --port <port>` for the smallest trustworthy runtime surface before broad checks.
+5. Use `proteum verify browser` for browser-visible verification, and only drop to direct Playwright when request-level verification cannot reproduce the issue. Keep auth sourced from `proteum session`, and reserve browser flows for the final verifier agent unless they are the only trustworthy surface.
+6. For performance, CPU, SQL, render, cache, or connected-boundary questions, use `proteum perf request <requestId|path>` against the same running dev server.
+7. Use `proteum trace ...` when you need lower-level event detail than `diagnose` or `perf` provides.
+8. Run global checks second, not first. Unrelated diagnostics should remain visible but non-blocking during focused verification unless strict global mode is required.
+9. Open the profiler only when a human-readable view helps; it should agree with the CLI after refresh.

package/docs/migrate-from-2.1.3.md

@@ -0,0 +1,388 @@
+# Migrating from Proteum 2.1.3
+
+This guide covers the breaking changes between `proteum@2.1.3` and the current framework code in this repository.
+
+The important conclusion is that the breaking surface is mostly at the app root and tooling contract level, not in day-to-day page, controller, or service authoring. In the repo diff from `2.1.3` to the current `2.1.9` line, I did not find a mandatory rewrite of `Router.page(...)`, controller methods, or normal service method bodies. The required migration is mainly about config files, env, service metadata discovery, and connected-app setup.
+
+## Breaking Changes Summary
+
+### 1. `identity.yaml` is no longer supported
+
+`2.1.3` expected a YAML file at the app root:
+
+- `identity.yaml`
+
+Current Proteum requires a typed TypeScript config:
+
+- `identity.config.ts`
+
+The file must default-export `Application.identity(...)` from `proteum/config`.
+
+### 2. `proteum.config.ts` is now required
+
+`2.1.3` had no app-level setup file for compiler or connected-project config.
+
+Current Proteum requires:
+
+- `proteum.config.ts`
+
+The file must default-export `Application.setup(...)` from `proteum/config`.
+
+This is where app-level framework config now lives, especially:
+
+- `transpile`
+- `connect`
+
+### 3. `URL_INTERNAL` is now a required env var
+
+`2.1.3` required:
+
+- `ENV_NAME`
+- `ENV_PROFILE`
+- `PORT`
+- `URL`
+
+Current Proteum also requires:
+
+- `URL_INTERNAL`
+
+The router and SSR runtime now treat the internal base URL as a first-class contract instead of reusing `URL` implicitly.
+
+### 4. `server/services/**/service.json` is no longer part of the contract
+
+In `2.1.3`, Proteum still read service metadata from `server/services/**/service.json`.
+
+Current Proteum reads the service graph from:
+
+- `server/index.ts`
+- typed config exports under `server/config/*.ts`
+
+If you still have `service.json` files from a `2.1.3` app, they are obsolete and should be removed.
+
+If you used `priority` there, move that value into the typed service config export with `Services.config(...)`.
+
+### 5. Connected apps must be declared explicitly
+
+Current Proteum adds an explicit connected-project contract in `proteum.config.ts`.
+
+If your app consumes controllers from another Proteum app, you now need:
+
+- `connect.<Namespace>.source`
+- `connect.<Namespace>.urlInternal`
+
+There is no namespace-based inference. The producer app must also already be on the new contract because Proteum now expects the producer app root to contain:
+
+- `identity.config.ts`
+- `proteum.config.ts`
+- generated connected contract files
+
+### 6. `proteum dev` is stricter when connected apps are configured
+
+If `connect` is configured, current `proteum dev` verifies the producer app health endpoint before it declares the server ready.
+
+That means broken or stale connected-app config is now a startup failure, not just a latent runtime problem.
+
+### 7. Human-facing CLI output changed
+
+Current Proteum prints a welcome banner only for the bare `proteum build` and bare `proteum dev` commands, and `proteum dev` now has tracked session files plus `list` and `stop` subcommands.
+
+This is not an app-code migration, but it can break scripts that parse mixed stdout/stderr loosely. Prefer `--json` for automation.
+
+## Migration Checklist
+
+### 1. Upgrade the package
+
+Update the app dependency to the current Proteum version, then reinstall.
+
+### 2. Replace `identity.yaml` with `identity.config.ts`
+
+Create a new root file:
+
+```ts
+import { Application } from 'proteum/config';
+
+export default Application.identity({
+    name: 'My App',
+    identifier: 'MyApp',
+    description: 'My Proteum app',
+    author: {
+        name: 'My Team',
+        url: 'https://example.com',
+        email: 'team@example.com',
+    },
+    social: {},
+    language: 'en',
+    locale: 'en-US',
+    maincolor: 'white',
+    iconsPack: 'light',
+    web: {
+        title: 'My App',
+        titleSuffix: 'My App',
+        fullTitle: 'My App',
+        description: 'My Proteum app',
+        version: '0.0.1',
+    },
+});
+```
+
+Mapping from the old YAML shape is mostly direct:
+
+- `name` stays `name`
+- `identifier` stays `identifier`
+- `description` stays `description`
+- `author.*` stays `author.*`
+- `language`, `locale`, `maincolor`, `iconsPack` keep the same meaning
+- `web.*` keeps the same meaning
+
+Then remove the old file:
+
+- `identity.yaml`
+
+### 3. Add `proteum.config.ts`
+
+Create a new root file:
+
+```ts
+import { Application } from 'proteum/config';
+
+export default Application.setup({
+    transpile: [],
+    connect: {},
+});
+```
+
+If your app does not consume another Proteum app and does not need package transpilation, this empty config is enough.
+
+If your app compiles workspace or source-distributed packages through Proteum, put them in `transpile`.
+
+Example:
+
+```ts
+import { Application } from 'proteum/config';
+
+export default Application.setup({
+    transpile: ['@acme/components'],
+    connect: {},
+});
+```
+
+### 4. Add `URL_INTERNAL` to `.env`
+
+At minimum, a migrated app now needs:
+
+```dotenv
+ENV_NAME=local
+ENV_PROFILE=dev
+PORT=3010
+URL=http://localhost:3010
+URL_INTERNAL=http://localhost:3010
+```
+
+For many local apps, `URL_INTERNAL` can initially match `URL`.
+
+Use a different internal URL only when the app is reached differently from server-side code than from a browser.
+
+### 5. Remove `service.json` and move metadata into typed config
+
+Delete any legacy files such as:
+
+- `server/services/Foo/service.json`
+
+Current Proteum derives the root service graph from `server/index.ts`, so the real source of truth is now the code that instantiates root services there.
+
+If the old `service.json` carried priority metadata, move it into the typed config export.
+
+Old pattern:
+
+```json
+{
+    "priority": 5
+}
+```
+
+New pattern:
+
+```ts
+import { Services } from '@server/app';
+import MetricsRouter from '@/server/services/utils/Metrics/router';
+
+export const routerMetricsConfig = Services.config(MetricsRouter, {
+    priority: 5,
+});
+```
+
+Then make sure `server/index.ts` instantiates the service explicitly:
+
+```ts
+public Router = new Router(this, {
+    ...userConfig.routerBaseConfig,
+    plugins: {
+        metrics: new MetricsRouter(userConfig.routerMetricsConfig, this),
+    },
+}, this);
+```
+
+### 6. Keep `server/index.ts` explicit
+
+Current Proteum expects the installed root services and router plugins to be visible directly in `server/index.ts`.
+
+The migration target is:
+
+- root services are instantiated as class properties on the `Application` subclass
+- router plugins are instantiated inside the `Router` config
+- typed config values come from `server/config/*.ts`
+
+If your `2.1.3` app relied on legacy discovery metadata, replace that with explicit code.
+
+## Connected-App Migration
+
+This section applies only if one Proteum app consumes controllers from another Proteum app.
+
+### 1. Upgrade the producer app too
+
+A current consumer app expects a producer app root that already has:
+
+- `identity.config.ts`
+- `proteum.config.ts`
+
+So a `file:` connected source pointing at an untouched `2.1.3` producer will fail.
+
+### 2. Declare `connect` explicitly in `proteum.config.ts`
+
+Example:
+
+```ts
+import { Application } from 'proteum/config';
+
+export default Application.setup({
+    connect: {
+        Product: {
+            source: process.env.PRODUCT_CONNECTED_SOURCE,
+            urlInternal: process.env.PRODUCT_URL_INTERNAL,
+        },
+    },
+});
+```
+
+### 3. Add the new env vars used by that config
+
+Example:
+
+```dotenv
+PRODUCT_CONNECTED_SOURCE=file:../product
+PRODUCT_URL_INTERNAL=http://localhost:3020
+```
+
+Supported source styles in the current contract are:
+
+- `file:../relative-producer-app`
+- `github:owner/repo?ref=<ref>&path=proteum.connected.json`
+
+### 4. Expect stricter startup behavior
+
+When `connect` is configured, `proteum dev` now checks the producer health endpoint before it reports ready.
+
+If startup fails, validate in this order:
+
+1. The producer app has already been migrated.
+2. `connect.<Namespace>.source` points at the right producer app root.
+3. `connect.<Namespace>.urlInternal` points at the producer dev server.
+4. The producer app is running.
+5. `npx proteum connect --strict` passes in the consumer app.
+
+## Monorepo and Workspace Notes
+
+Current Proteum is better at resolving hoisted and workspace installs than `2.1.3`, but old app tsconfig files often still hardcode shallow `node_modules` paths.
+
+If your app lives inside a monorepo and TypeScript path resolution starts failing after the upgrade, align `client/tsconfig.json` and `server/tsconfig.json` with the current scaffold shape:
+
+- include `../identity.config.ts` and `../proteum.config.ts` in the server tsconfig
+- make sure the `extends` path points to the real visible `proteum/tsconfig.common.json`
+- make sure the `@client/*`, `@common/*`, and `@server/*` aliases point to the real visible Proteum install
+- make sure Preact compat aliases include `react-dom/client` when your app imports it
+
+This is usually only needed for workspace or hoisted installs. Standalone apps with a local `node_modules/proteum` often keep working after the config-file migration alone.
+
+## CLI and Workflow Changes
+
+These are worth updating even though they are not core app-code migrations.
+
+### Use `--json` for automation
+
+Only bare `proteum build` and bare `proteum dev` runs print a banner. For scripts, CI helpers, or editor tooling, prefer:
+
+- `npx proteum explain --json`
+- `npx proteum doctor --json`
+- `npx proteum connect --json`
+
+### Use tracked dev sessions
+
+Current `proteum dev` supports tracked session management:
+
+- `npx proteum dev --session-file var/run/proteum/dev/app.json --replace-existing`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file var/run/proteum/dev/app.json`
+
+If your local workflow starts multiple dev servers, this is the current supported model.
+
+### New diagnostics are available
+
+These are new capabilities, not migration requirements, but they are the fastest way to validate the upgrade:
+
+- `npx proteum connect --strict`
+- `npx proteum explain --connected --controllers`
+- `npx proteum diagnose / --port <port>`
+- `npx proteum perf top --port <port>`
+- `npx proteum trace latest --port <port>`
+
+## Recommended Migration Order
+
+1. Upgrade the package.
+2. Convert `identity.yaml` to `identity.config.ts`.
+3. Add `proteum.config.ts`.
+4. Add `URL_INTERNAL`.
+5. Delete all legacy `service.json` files.
+6. Move any legacy service metadata, especially `priority`, into `Services.config(...)`.
+7. Confirm `server/index.ts` explicitly instantiates every root service and router plugin.
+8. If the app is connected to another app, migrate the producer app and then add explicit `connect` config.
+9. If the app is inside a workspace, align tsconfig paths with the actual Proteum install location.
+10. Run `npx proteum refresh`, then validate with the commands below.
+
+## Validation After Migration
+
+Run these from the migrated app:
+
+```bash
+npx proteum refresh
+npx proteum explain --env
+npx proteum doctor --contracts --strict
+npx proteum check
+```
+
+If the app uses connected projects, also run:
+
+```bash
+npx proteum connect --strict
+npx proteum explain --connected --controllers
+```
+
+Then boot the app and verify the live runtime:
+
+```bash
+npx proteum dev --port 3010
+npx proteum diagnose / --port 3010
+npx proteum trace latest --port 3010
+```
+
+## Short Version
+
+If you want the shortest possible migration plan:
+
+1. Replace `identity.yaml` with `identity.config.ts`.
+2. Add `proteum.config.ts`.
+3. Add `URL_INTERNAL`.
+4. Delete `server/services/**/service.json`.
+5. Move any service `priority` into `Services.config(...)`.
+6. If you connect apps together, declare `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` explicitly.
+
+That is the minimum needed to move a real `2.1.3` app onto the current Proteum contract.

package/docs/request-tracing.md

@@ -1,13 +1,18 @@
 # Request Tracing
 
-Proteum ships with a dev-only in-memory request trace buffer so routing, controller execution, SSR, API, Prisma SQL, render behavior, and request-time performance can be inspected without attaching a debugger or scattering temporary logs through the runtime.
+Proteum ships with one request-instrumentation system with two runtime shapes:
+
+- retained dev traces for `proteum trace`, `proteum perf`, the dev-only HTTP endpoints, and the bottom profiler
+- reduced request-local profiling for `request.profiling` and the router `request.finished` hook
+
+The same API and SQL instrumentation feeds both shapes. Dev trace keeps the in-memory buffer and event timeline. Reduced profiling keeps only the finalized request/API/SQL snapshot and releases it after the `request.finished` hook runs.
 
 ## Scope
 
-- tracing is available only when the app runs with `profile: dev`
+- retained dev tracing is available only when the app runs with `profile: dev`
 - traces are exposed through `proteum trace`, `proteum perf`, and the dev-only `__proteum/trace` and `__proteum/perf` HTTP endpoints
 - `proteum diagnose` is a separate composite surface that reads the same framework diagnostics plus one matching request trace and buffered server logs; see [diagnostics.md](diagnostics.md)
-- production requests are not traced by this feature
+- `ENABLE_PROFILER=true` enables reduced request-local profiling in any environment, including production
 
 ## Main Commands
 
@@ -34,9 +39,9 @@ Before reproducing a bug or starting a new test pass:
 Typical debugging flow:
 
 ```bash
-proteum trace arm --capture deep --port 3103
-# reproduce the failing request once
-proteum trace requests --port 3103
+proteum orient /dashboard
+proteum diagnose /dashboard --hit /dashboard --port 3103
+proteum perf request /dashboard --port 3103
 proteum trace show <requestId> --port 3103
 ```
 
@@ -44,14 +49,16 @@ Use `--url http://host:port` when the dev server is reachable on a non-standard
 
 If the request under test is protected and login UX is not the feature under test, mint an auth cookie with `proteum session <email> --role <role>` before reproducing the request. This keeps the trace focused on the protected behavior instead of the login flow.
 
-If you already know the failing path and want a one-shot suspect list before reading raw events, start with `proteum diagnose <path> --port <port>` and drop into `proteum trace show <requestId>` only when the lower-level event stream is still needed.
+If you already know the failing path and want a one-shot suspect list before reading raw events, start with `proteum diagnose <path> --port <port>` and `proteum perf request <path> --port <port>` first, then drop into `proteum trace show <requestId>` only when the lower-level event stream is still needed.
 
-Trace summaries include `sql=<count>`. Detailed trace output includes both a `Calls` section for API/fetcher activity and a `SQL` section for captured Prisma queries.
+Use ad hoc database queries or one-off scripts only after `orient`, `diagnose`, `perf request`, and `trace show` still leave the request chain unclear.
+
+Trace summaries include `sql=<count>`. Detailed trace output includes both a `Calls` section for API, cache, or fetcher activity and a `SQL` section for captured Prisma queries.
 
 `proteum perf` is a grouped view over the same trace store:
 
 - `top` ranks routes, concrete paths, or controllers by avg, p95, CPU, SQL, render, self time, and heap delta
-- `request` shows one traced request waterfall with stage timings plus the hottest calls and SQL
+- `request` shows one traced request waterfall with stage timings plus the hottest calls, SQL, chain attribution, connected boundary, and SQL fingerprints
 - `compare` shows baseline-vs-target regressions between trace windows such as `yesterday` and `today`
 - `memory` shows grouped heap and RSS drift trends
 
@@ -65,6 +72,7 @@ Depending on capture mode, traces can include:
 - route resolution start, match, and deep-mode skip reasons
 - controller start and result shape
 - synchronous SSR fetcher calls, API batch fetchers, and async request traces
+- cache hits and cache writes observed during request handling
 - Prisma SQL queries with caller method/path, optional fetcher attribution, SQL text, params, kind, operation, and timing
 - created router/context keys
 - setup output keys and page data summaries
@@ -72,6 +80,14 @@ Depending on capture mode, traces can include:
 - render start/end timings and document output sizes
 - per-request CPU usage deltas plus heap and RSS snapshots before and after the request
 - normalized request errors
+- additive owner, service, cache, and connected-boundary metadata propagated from route/controller resolution into downstream calls and SQL
+
+Reduced request-local profiling keeps the finalized request summary plus API and SQL rows only:
+
+- `request.profiling` exists before the router `request` hook runs
+- `request.profiling.apiCalls` and `request.profiling.sqlQueries` start empty and are populated during request handling
+- the router `request.finished` hook receives that same object after status, duration, API calls, and SQL queries are finalized
+- when only reduced profiling is enabled, finished requests are released immediately after `request.finished` instead of being retained in the global trace buffer
 
 ## SQL Tracing
 
@@ -87,6 +103,21 @@ Prisma query tracing covers both ORM operations and raw queries.
 
 This currently covers SQL issued through Proteum's Prisma service, including raw helpers that flow through the same Prisma client.
 
+Each traced SQL entry can now include:
+
+- `fingerprint`: stable normalized SQL shape for repeated-query comparison
+- `ownerLabel` and `ownerFilepath`: route/controller ownership propagated from the request
+- `serviceLabel`: the inferred service boundary when available
+- `connectedNamespace`: the connected producer namespace when the request crossed an app boundary
+
+`proteum diagnose` and `proteum perf request` collapse those lower-level records into a compact request chain:
+
+- route or controller
+- service
+- cache branch when used
+- connected app boundary when used
+- SQL fingerprints
+
 ## Capture Modes
 
 - `summary`: smallest capture, focused on request lifecycle and high-signal events
@@ -121,6 +152,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
 ```
 
 Notes:
@@ -131,6 +163,7 @@ Notes:
 - `eventsLimit` defaults to `800`
 - `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
 - explicit `proteum trace export` files under `var/traces/exports/` are left in place
+- `ENABLE_PROFILER` reuses the same request instrumentation path but skips the retained global buffer and event timeline when dev trace is otherwise off
 
 ## Memory Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.9",
+	"version": "2.2.1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -16,6 +16,10 @@
 		"proteum": "cli/bin.js"
 	},
 	"dependencies": {
+		"@babel/generator": "^7.29.0",
+		"@babel/parser": "^7.29.0",
+		"@babel/traverse": "^7.29.0",
+		"@babel/types": "^7.29.0",
 		"@inkjs/ui": "^2.0.0",
 		"@prisma/adapter-mariadb": "7.2.0",
 		"@prisma/client": "7.2.0",
@@ -69,6 +73,7 @@
 		"preact": "^10.27.1",
 		"preact-render-to-string": "^6.6.1",
 		"prompts": "^2.4.2",
+		"react": "^19.2.0",
 		"react-apexcharts": "^2.1.0",
 		"replace-once": "^1.0.0",
 		"responsive-loader": "^3.1.2",