proteum 2.1.9 → 2.2.1

package/agents/project/root/AGENTS.md

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

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

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

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

@@ -5,8 +5,8 @@ Role: keep only service-layer rules here.
 Keep here: service placement, service responsibilities, model access, query-shaping, return-type guidance, and service error-handling rules.
 Do not put here: request parsing, page/render rules, controller transport details, or broad project workflow already defined in higher-level AGENTS files.
 
-Optimization source of truth: project-root `optimizations.md`.
-Diagnostics source of truth: project-root `diagnostics.md`.
+Optimization source of truth: root-level `optimizations.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
 
 ## Placement
 
@@ -29,6 +29,8 @@ Diagnostics source of truth: project-root `diagnostics.md`.
 - Use runtime models through `this.models` or the app model accessors.
 - Use Prisma typings through `@models/types` only.
 - In database queries, prefer explicit `select` or narrow `include`.
+- For database structure changes, edit the app's `schema.prisma` only. Never create or edit migration files manually.
+- Never use raw SQL DDL or other schema-mutating SQL to change database structure.
 - Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
 ## Errors

package/agents/project/tests/AGENTS.md

@@ -5,14 +5,21 @@ Role: keep only test-area rules here.
 Keep here: runtime verification guidance, selector strategy, test-specific reuse rules, and authenticated test-flow expectations.
 Do not put here: production implementation rules, page/service architecture contracts, or duplicated project workflow that belongs in broader AGENTS files.
 
-Diagnostics source of truth: project-root `diagnostics.md`.
+Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
-- After implementing a browser-visible feature or change, run targeted Playwright coverage or a real browser repro against a running app before finishing; this verification is required, not optional cleanup.
+- After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Use a real browser repro against a running app during iteration when it is the fastest trustworthy loop.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
+- Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
+- Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.
+- Put page objects and reusable UI surface wrappers in `tests/e2e/pages/**`.
+- Put reusable multi-step user flows in `tests/e2e/workflows/**`.
+- Put test data builders in `tests/e2e/factories/**` and generic helpers in `tests/e2e/utils/**`.
+- Keep helpers out of spec files when they are reusable, and do not create ad hoc flat test files or duplicate support abstractions when an existing page, workflow, factory, or utility already fits.
 - Locate elements with `data-testid`.
 - Add `data-testid` where needed instead of relying on brittle selectors.
+- Keep end-to-end tests clean, well organized, and non-redundant. Prefer extending or reshaping the most relevant existing scenario over duplicating coverage, and remove or consolidate overlap when the suite becomes repetitive.
 - Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.
 - For protected dev flows, prefer `npx proteum session <email> --role <role>` over automating login unless the login flow itself is under test.

package/cli/app/index.ts

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

package/cli/commands/configure.ts

@@ -0,0 +1,226 @@
+/*----------------------------------
+- DEPENDANCES
+----------------------------------*/
+
+// Npm
+import fs from 'fs';
+import path from 'path';
+import prompts from 'prompts';
+import { UsageError } from 'clipanion';
+
+// Configs
+import cli from '..';
+import { renderRows } from '../presentation/layout';
+import { isLikelyProteumAppRoot } from '../presentation/commands';
+import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
+import { configureProjectAgentSymlinks, type TConfigureProjectAgentSymlinksResult } from '../utils/agents';
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const findLikelyRepoRoot = (startPath: string) => {
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        if (fs.existsSync(path.join(currentPath, '.git'))) return currentPath;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+};
+
+const resolveCanonicalPath = (inputPath: string) => {
+    const resolvedPath = path.resolve(inputPath);
+
+    try {
+        return fs.realpathSync(resolvedPath);
+    } catch {
+        return resolvedPath;
+    }
+};
+
+const isInsideDirectory = ({ child, parent }: { child: string; parent: string }) => {
+    const relativePath = path.relative(parent, child);
+    return relativePath !== '' && !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+};
+
+const assertProteumAppRoot = (appRoot: string) => {
+    if (isLikelyProteumAppRoot(appRoot)) return;
+
+    throw new UsageError(
+        `This command expects a Proteum app root. Missing one or more required entries in ${appRoot}.`,
+    );
+};
+
+const promptMonorepoRoot = async ({
+    appRoot,
+    defaultRoot,
+}: {
+    appRoot: string;
+    defaultRoot?: string;
+}) => {
+    const response = await prompts(
+        {
+            type: 'text',
+            name: 'value',
+            message: 'Monorepo root path',
+            initial: defaultRoot,
+            validate: (input) => {
+                const resolvedRoot = resolveCanonicalPath(String(input || defaultRoot || ''));
+
+                if (!input && !defaultRoot) return 'A monorepo root path is required.';
+                if (!fs.existsSync(resolvedRoot) || !fs.statSync(resolvedRoot).isDirectory())
+                    return `Directory not found: ${resolvedRoot}`;
+                if (!isInsideDirectory({ child: appRoot, parent: resolvedRoot }))
+                    return `The Proteum app root must be inside the monorepo root: ${resolvedRoot}`;
+
+                return true;
+            },
+        },
+        {
+            onCancel: () => {
+                throw new UsageError('Cancelled `proteum configure agents`.');
+            },
+        },
+    );
+
+    return resolveCanonicalPath(String(response.value || defaultRoot || ''));
+};
+
+const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
+    if (blockedPaths.length === 0) return [];
+
+    console.info(await renderWarning('Proteum found existing non-managed instruction paths.'));
+    console.info(['Choose whether to overwrite each path with a Proteum-managed symlink:', ...blockedPaths.map((entry) => `- ${entry}`)].join('\n'));
+
+    const overwriteBlockedPaths: string[] = [];
+
+    for (const blockedPath of blockedPaths) {
+        const response = await prompts(
+            {
+                type: 'confirm',
+                name: 'value',
+                message: `Overwrite ${blockedPath}?`,
+                initial: false,
+            },
+            {
+                onCancel: () => {
+                    throw new UsageError('Cancelled `proteum configure agents`.');
+                },
+            },
+        );
+
+        if (response.value === true) overwriteBlockedPaths.push(blockedPath);
+    }
+
+    return overwriteBlockedPaths;
+};
+
+const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksResult) => {
+    const sections: string[] = [];
+
+    sections.push(
+        renderRows(
+            [
+                { label: 'mode', value: result.mode },
+                ...(result.monorepoRoot ? [{ label: 'monorepo root', value: result.monorepoRoot }] : []),
+            ],
+            { minLabelWidth: 16, maxLabelWidth: 16 },
+        ),
+    );
+
+    if (result.created.length > 0) sections.push(['Created:', ...result.created.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updated.length > 0) sections.push(['Updated:', ...result.updated.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.overwritten.length > 0)
+        sections.push(['Overwritten:', ...result.overwritten.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updatedGitignores.length > 0)
+        sections.push(['Updated .gitignore:', ...result.updatedGitignores.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.blocked.length > 0)
+        sections.push(
+            [
+                'Skipped existing non-managed paths:',
+                ...result.blocked.map((entry) => `- ${entry}`),
+            ].join('\n'),
+        );
+
+    return sections;
+};
+
+/*----------------------------------
+- COMMAND
+----------------------------------*/
+
+export const run = async (): Promise<void> => {
+    if (cli.args.action !== 'agents') throw new UsageError('Usage: `proteum configure agents`');
+
+    const appRoot = resolveCanonicalPath(cli.paths.appRoot);
+    assertProteumAppRoot(appRoot);
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
+    }
+
+    const likelyRepoRoot = findLikelyRepoRoot(appRoot);
+    const defaultMonorepoRoot =
+        likelyRepoRoot && likelyRepoRoot !== appRoot && isInsideDirectory({ child: appRoot, parent: likelyRepoRoot })
+            ? likelyRepoRoot
+            : undefined;
+    console.info(
+        [
+            await renderTitle('PROTEUM CONFIGURE AGENTS', 'Configure Proteum-managed instruction symlinks.'),
+            renderRows([{ label: 'app', value: appRoot === process.cwd() ? '.' : appRoot }]),
+        ].join('\n\n'),
+    );
+
+    const monorepoResponse = await prompts(
+        {
+            type: 'confirm',
+            name: 'value',
+            message: 'Is this Proteum app part of a monorepo?',
+            initial: defaultMonorepoRoot !== undefined,
+        },
+        {
+            onCancel: () => {
+                throw new UsageError('Cancelled `proteum configure agents`.');
+            },
+        },
+    );
+    const isMonorepo = monorepoResponse.value === true;
+    const monorepoRoot = isMonorepo
+        ? await promptMonorepoRoot({
+              appRoot,
+              defaultRoot: defaultMonorepoRoot,
+          })
+        : undefined;
+
+    const preview = configureProjectAgentSymlinks({
+        appRoot,
+        coreRoot: cli.paths.core.root,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedOverwritePaths(preview.blocked);
+
+    console.info(
+        await renderStep(
+            '[1/1]',
+            isMonorepo
+                ? `Writing monorepo-aware instruction symlinks using ${monorepoRoot}.`
+                : 'Writing standalone instruction symlinks.',
+        ),
+    );
+
+    const result = configureProjectAgentSymlinks({
+        appRoot,
+        coreRoot: cli.paths.core.root,
+        monorepoRoot,
+        overwriteBlockedPaths,
+    });
+    const sections = renderConfigureResultSections(result);
+
+    console.info(await renderSuccess('Proteum-managed instruction symlinks are configured.'));
+
+    if (sections.length > 0) console.info(`\n${sections.join('\n\n')}`);
+};