proteum 2.1.0 → 2.1.2

package/agents/project/AGENTS.md

@@ -1,138 +1,84 @@
-# Architecture
-
-This is a full stack monolith project using Typescript, NodeJS, Preact, and Proteum.
-
-`/client`: frontend
-    `/assets`: CSS, images and other frontend assets
-    `/catalogs`: client-only catalogs and registries
-    `/components`: reusable components
-    `/pages`: page route files and page-local UI
-    `/hooks`
-`/common`: shared functions, constants, typings, and cross-runtime catalogs
-`/server`: backend
-    `/catalogs`: server-only catalogs and registries
-    `/config`: service configuration
-    `/services`: backend services and controllers
-    `/routes`: explicit non-controller routes
-    `/lib`: helper functions
-`/tests`
-
-# Coding style
-
-See `CODING_STYLE.md`.
-This file is the source of truth for formatting, section-comment structure, and general coding style.
-
-# Framework contract
-
-For Proteum-wide project scaffolding, routing, SSR, controller, service, generated-code, and maintenance rules, use the
-framework guide in the Proteum repository at `agents/framework/AGENTS.md`.
-From a normal Proteum project install, read it at `./node_modules/proteum/agents/framework/AGENTS.md`.
-
-Start framework inspection with:
-
-- `./.proteum/manifest.json`
-- `npx proteum explain`
-- `npx proteum doctor`
-
-Generated files live under `./.proteum` and should not be edited by hand.
-Project code should use the generated aliases `@generated/client/*`, `@generated/common/*`, and `@generated/server/*`.
-Client context is typically imported from `@/client/context`.
-Prefer type inference from the explicit application class in `./server/index.ts` whenever possible. Treat it as the
-canonical type root for app services, router services, router context, and models instead of duplicating manual type
-declarations.
-
-# Files organization
-
-- Always keep one class / React component per file
-- Prefer a deep tree structure that groups files by business concern instead of long file names
-- The default `*.ts` / `*.tsx` file is the normal implementation; use `*.ssr.ts` / `*.ssr.tsx` only when the project
-needs an SSR-specific variant
-
-## Centralize feature catalogs (Single Source of Truth)
-
-When implementing a feature that relies on a **curated list of items**, keep **one canonical catalog/registry file** and make all other code import it.
-
-- Client-only catalogs live in `/client/catalogs/**`
-- Server-only catalogs live in `/server/catalogs/**`
-- Shared catalogs used by both runtimes live in `/common/catalogs/**`
-- Organize those root catalog trees by business concern (mirror the feature path when useful)
-- Do not create nested `catalogs/` folders inside `/client/pages/**`, `/client/components/**`, `/server/services/**`, or similar feature folders
-
-## Runtime access rules
-
-- `@models/types`: Prisma typings only. Can be imported anywhere.
-- Never use runtime value imports from `@request` or `@models`.
-- Never expose request-scoped state through imports.
-- Keep app services, router services, router context, and model contracts inferred from `./server/index.ts` whenever
-possible instead of recreating parallel type maps.
-
-## Client runtime access
-
-- Page route files use `Router.page(...)`.
-- `Router.page(path, render)` for pages without SSR setup.
-- `Router.page(path, setup, render)` for pages with SSR config/data.
-- `setup` receives the normal page context plus the generated controller tree spread into it.
-- `render` receives the normal page context plus the resolved setup data and the same controller tree spread into it.
-- Components and hooks use the app client context hook, usually imported from `@/client/context`.
-- For UI primitives, prefer the project's shared Shadcn-based components whenever they already exist and fit the need before creating bespoke buttons, inputs, dialogs, or similar building blocks.
-
-## Server runtime access
-
-- Normal business logic lives in `/server/services/**/index.ts` classes that extend `Service`.
-- Route entrypoints live in `/server/controllers/**/*.ts` classes that extend `Controller`.
-- Only controller files are indexed as callable API endpoints.
-- Controller methods validate input with `this.input(schema)` and access request scope through `this.request`.
-- Service classes access other services via `this.services` and prisma models via `this.models`.
-- App service types should be inferred from the explicit application graph rooted at `./server/index.ts`.
-- Router services and request/context values such as `user`, `auth`, and similar request-scoped contracts should come
-from inferred request and app types, not ad hoc casts.
-- Models should be inferred from the app/model registry rooted at `./server/index.ts` and exposed through the generated
-server app shim, not from duplicated manual model maps.
-- Never use request-scoped state directly inside normal service methods.
-- Controllers should resolve auth and request-derived values, then pass plain typed arguments into services.
-- When referencing an app service, a router service, or a model, expose it in the current block scope first by
-destructuring from `this.request`, `this.app`, `this.models`, or the generated app/model accessors where applicable,
-then call methods on that local binding. The service, router value, or model should be the first element of the callee
-chain.
-
-# Agent behavior
-
-**Make sure the code you generate integrates perfectly with the current codebase by avoiding repetition and centralizing each purpose.**
-
-## Typings
-
-- Keep strong, consistent TypeScript typings across the whole project.
+# Project Guide
+
+This file adds project-local rules on top of the canonical Proteum app contract.
+
+Framework contract:
+
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
+
+Coding style source of truth: `./CODING_STYLE.md`.
+
+## Fast Start
+
+- Start with `./.proteum/manifest.json`, `npx proteum explain`, and `npx proteum doctor`.
+- For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand.
+- Use `--dry-run --json` on scaffold commands when an agent needs a machine-readable plan before writing files.
+- For request-time issues in dev, inspect traces before adding logs.
+- If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
+- If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
+
+## 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`
+
+## Local Deltas
+
+- 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`.
+- Use `@generated/client/*`, `@generated/common/*`, and `@generated/server/*` for generated surfaces.
+- Client context is typically imported from `@/client/context`.
+- Prefer type inference from the explicit application class in `./server/index.ts`.
+- Reuse shared Shadcn-based UI primitives when the project already provides them.
+
+## Dependency Selection
+
+- Before implementing a feature or change, first check whether the repo already includes a suitable dependency.
+- If not, search npm before building a new utility, abstraction, component primitive, parser, formatter, or integration from scratch.
+- Prefer the most popular, flexible, maintained packages that fit the project constraints.
+- Only reinvent the wheel when existing packages are clearly inadequate on bundle size, SSR behavior, performance, typing quality, flexibility, licensing, or maintenance risk.
+- 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 the code you wrote.
-- Never cast with `as any` or `as unknown`; fix the type contract or introduce an explicit typed adapter instead. If you find no other solution, tell me in the output.
+- Fix typing issues only on code you wrote.
+- Never cast with `as any` or `as unknown`; fix the contract or add an explicit typed adapter.
 
 ## Workflow
 
-- Every time I input error messages without any instructions, don't implement fixes.
-Instead, investigate the potential causes of the errors, and for each:
-    1. Evaluate / quantify the probabilities
-    2. Give why and
-    3. Suggest how to fix it
-- When you have finished your work, summarize in one top-level short sentence the changes you made since the beginning of the conversation. Output as "Commit message".
+- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+- For request-time behavior in dev, check whether a server is already running on the default port and prefer `npx proteum trace` before reproducing the issue or adding logs.
+- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- End your work with `Commit message`: one short top-level sentence.
 
-## High-impact files
+## High-Impact Files
 
-- Do not edit generated files under `.proteum` by hand.
-- Treat `tsconfig*.json`, `env*.yaml`, Prisma-generated files, and symbolic links as high-impact.
-- Edit them only when the task actually requires it, and keep those changes minimal and explicit.
+Edit these only when required, and keep changes minimal and explicit:
 
-If a high-impact file change is not required for the task, leave it alone.
+- `tsconfig*.json`
+- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- Prisma-generated files
+- symbolic links
 
-## Don't run any of these commands
+## Commands Not To Run
 
-```
-git restore
-git reset
-prisma *
-And any git command in the write mode.
-```
+- `git restore`
+- `git reset`
+- `prisma *`
+- any write-mode git command
 
-# Copy and UX
+## Product And UX Docs
 
-Before making UX/copy decisions, read `docs/PERSONAS.md`, `docs/PRODUCT.md`, `docs/MARKETING.md`.
-When implementing UI, prefer existing Shadcn components or local wrappers around them whenever they can satisfy the requirement cleanly.
+If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist.

package/agents/project/client/AGENTS.md

@@ -1,108 +1,37 @@
 # Frontend
 
-UI components are defined in `/client/pages` and `/client/components`.
-Client-only catalogs and registries live in `/client/catalogs/**`.
+This file adds client-side local rules on top of the canonical framework contract:
+
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
 
 ## Stack
 
-- Typescript strict
+- TypeScript strict
 - Preact with SSR
-- Follow the UI stack already used in the touched area.
-- Many Proteum apps use Tailwind and `@/client/components/Motion`, but those are app conventions, not framework guarantees.
-- When the project already exposes Shadcn components or `client/components/ui/**` primitives derived from them, prefer those components for standard UI instead of rebuilding the same primitives locally.
-
-Don't add `React` imports just for JSX.
-Use `React` only when a React or Preact API is actually needed.
-Don't use `React.useCallback` unless strictly necessary or already common in the touched area.
-
-## Communicate with the server
-
-### Pages
-
-Pages use `Router.page(...)`.
-
-Use `Router.page(path, render)` when there is no SSR setup.
-
-Use `Router.page(path, setup, render)` when the page needs SSR config or SSR data:
-
-```typescript
-Router.page('/dashboard/example', ({ Feature }) => ({
-    _auth: 'USER',
-    dataKey: Feature.loadExample(),
-}), ({ dataKey }) => <Page data={dataKey} />);
-```
-
-- Keep the route registration compact instead of exploding the whole call into a staircase layout.
-- `setup` returns one flat object
-- keys like `_auth`, `_layout`, `_priority` are route config
-- all other keys are SSR data fetchers
-- never use `api.fetch(...)` in page files
-
-### Components and hooks
-
-Components and hooks access controllers through the app client context hook, typically `useContext()` from `@/client/context`:
-
-```typescript
-const { Auth, Domains } = useContext();
-```
+- follow the UI stack already used in the touched area
+- many Proteum apps use Tailwind and `@/client/components/Motion`, but those are app conventions, not framework guarantees
 
-Then call controller methods directly:
+## Local Client Rules
 
-```typescript
-Auth.signUp(data).then((result) => {
-    ...
-});
-```
-
-### Async calls
-
-- Prefer direct controller calls from the context or page render args
-- Follow the controller naming and hierarchy already used in the touched feature instead of inventing a new one
-- The thrown errors will automatically be displayed to the user, so don't silence them
-- Never depend on legacy `@app` imports on the client
-
-## Errors handling
-
-Errors caught from controller calls should never be silenced.
-If a catch is needed, rethrow or surface the failure clearly.
+- Page files follow the page contract in `./pages/AGENTS.md`.
+- Components and hooks access controllers through the app client context hook, usually `useContext()` from `@/client/context`.
+- Prefer direct controller calls from context or page render args.
+- Never depend on legacy `@app` imports on the client.
+- Errors from controller calls should never be silently swallowed. Rethrow or surface them clearly.
 
 ## Design
 
-- Follow the existing design language of the app or feature area.
+- Follow the existing design language of the touched area.
 - Keep layouts responsive and accessible.
 - Add motion only when the area already uses it or when it materially improves UX.
-- Reuse Shadcn-based shared primitives first for common controls like buttons, inputs, dialogs, dropdowns, tabs, tables, and forms when they cover the requirement.
-- Create custom UI primitives only when the existing Shadcn layer cannot express the interaction or visual requirement cleanly.
-
-## Rules
-
-- Don't add `React` imports unless the file actually uses a React or Preact API.
-- Don't use any component from `@client/components` unless the codebase already does in that area, except for established shared primitives such as the project's Shadcn-based `client/components/ui/**` layer
-- To create a link / button, always use the `Link` component when the codebase expects navigation links
-
-## Keep the code organized
-
-- Split big components (more than 1000 lines) into smaller components
-- Always use one component per file
-- Every time possible, load data and define action handlers in the directly concerned component instead of passing everything from the parent
-- Put curated lists, option registries, UI copy catalogs, and similar SSOT data under `/client/catalogs/**`, not inside page or component folders
-
-## Split the page by sections via comments
-
-Use:
-
-```typescript
-/*----------------------------------
-- SECTION NAME
-----------------------------------*/
-```
+- When the project already exposes shared Shadcn-based UI primitives, reuse them before creating custom primitives.
 
-File sections:
-- DEPENDENCIES
-- TYPES
-- COMPONENT / PAGE
+## Code Organization
 
-Component / page sections:
-- INIT
-- ACTIONS
-- RENDER
+- Do not add `React` imports just for JSX.
+- Do not use `React.useCallback` unless it is necessary or already common in the touched area.
+- Keep one component per file.
+- Load data and define handlers in the directly concerned component when that keeps ownership clearer.
+- Keep curated lists, option registries, and UI copy catalogs under `/client/catalogs/**`.
+- Follow the section-comment format from the project-root `CODING_STYLE.md`.

package/agents/project/client/pages/AGENTS.md

@@ -1,35 +1,33 @@
-# Page files
+# Page Files
 
-Page files are located in `/client/pages/**/*.tsx`.
+This file adds page-file local rules on top of the canonical framework contract:
 
-## Router.page contract
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
 
-Use one of these forms:
+## Router.page Usage
 
-```typescript
-Router.page('/path', ({ request, Feature }) => <Page />);
-```
+- Prefer `Router.page(path, setup, render)` for normal SSR pages.
+- Use `Router.page(path, options, setup, render)` when a separate route-options object makes the call clearer.
+- Keep the `Router.page(...)` call compact instead of exploding each outer argument onto its own line.
+- Keep route registration at top level. Do not hide it behind helper abstractions.
 
-```typescript
-Router.page('/path', ({ Feature }) => ({
-    _auth: 'USER',
-    dataKey: Feature.loadData({ param1: 'value' }),
-}), ({ request, dataKey, Feature }) => <Page data={dataKey} />);
-```
+## Setup And Render
 
-- Keep the `Router.page(...)` call itself compact instead of expanding each argument onto its own outer line.
-- `setup` is the second `Router.page` argument
-- `render` is the last `Router.page` argument
-- `setup` receives the page context plus generated controller instances
-- `render` receives the page context, resolved setup data, and generated controller instances
-- Prefer the generated page arguments or the app context hook; do not import `.proteum` files directly.
-- Never use `api.fetch(...)` in page files
-- Never import client service values from `@app`
-- Compose page UI from shared Shadcn-based components when the project already provides them instead of redefining common controls inline in the page file
-- Keep page-local curated copy, option sets, and registries in `/client/catalogs/**`; do not create `catalogs/` folders under `client/pages/**`
+- `setup` returns one flat object.
+- `_`-prefixed keys are route options.
+- every other key is SSR data and should be consumed from `render`
+- if a page needs route data, return it from `setup` and read it in `render`
+
+## Page Rules
+
+- Prefer generated page args or the app context hook. Do not import `.proteum` files directly.
+- Never use `api.fetch(...)` in page files.
+- Never import client service values from `@app`.
+- Keep page-local curated copy, option sets, and registries in `/client/catalogs/**`.
+- When shared Shadcn-based primitives exist, compose the page UI from them instead of redefining common controls inline.
 
 ## Typings
 
-- Treat generated controller method typings as the source of truth
-- Never cast controller methods, their parameters, or their return types
-- If a page needs route data, return it from `setup` and consume it from `render`
+- Treat generated controller method typings as the source of truth.
+- Never cast controller methods, their parameters, or their return types.

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

@@ -1,13 +1,15 @@
-# Server routes
+# Server Routes
 
-Use `/server/routes/**` only for explicit custom routes that should not be generated from controllers.
+This file adds route-area local rules on top of the canonical framework contract:
 
-- Callable app APIs belong in `/server/controllers/**/*.ts`
-- `/server/routes/**` is for manual `Router.get/post/...` routes, redirects, resources, OAuth callbacks, etc.
-- If a route needs a curated list or registry, keep server-only data in `/server/catalogs/**` and shared data in `/common/catalogs/**`
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
 
-## Generate absolute urls
+- Use `/server/routes/**` only for explicit custom HTTP behavior that should not be generated from controllers.
+- If the endpoint is just a normal app API, prefer `/server/controllers/**/*.ts`.
+- Good fits include redirects, resources, OAuth callbacks, webhooks, sitemap-like output, and custom public endpoints.
+- If a route needs a curated registry, keep server-only data in `/server/catalogs/**` and shared data in `/common/catalogs/**`.
 
-The absolute urls are generated via `Router.url()`:
+## Absolute URLs
 
-`const absoluteUrl = Router.url('/relative/path')`
+Use `Router.url('/relative/path')` to generate absolute URLs.

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

@@ -1,170 +1,33 @@
 # Server Services
 
-Stack:
-- Typescript with strict mode
-- NodeJS
-- Prisma 7 ORM
+This file adds service-area local rules on top of the canonical framework contract:
 
-## Catalog placement
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.md`
 
-- Server-only catalogs and registries live in `/server/catalogs/**`
-- Shared cross-runtime catalogs live in `/common/catalogs/**`
-- Do not create nested `catalogs/` folders under `/server/services/**`
-- Services should import curated lists from those root catalog locations instead of redefining them locally
+## Placement
 
-## 1. Create the service file in `/server/services/<service name>/index.ts`
+- Root business services live in `/server/services/<Feature>/index.ts`.
+- Root-service metadata lives in `/server/services/<Feature>/service.json`.
+- Root-service config lives in `/server/config/*.ts` when the service needs config.
+- Companion client-callable entrypoints live in `/server/controllers/**`.
 
-Template:
+## Local Service Rules
 
-```typescript
-/*----------------------------------
-- DEPENDANCE
-----------------------------------*/
+- Keep business logic in services and keep request/auth/input handling in controllers.
+- If a feature grows several coherent domains, split it into explicit subservices.
+- Server-only catalogs live in `/server/catalogs/**`.
+- Shared cross-runtime catalogs live in `/common/catalogs/**`.
+- Do not create nested `catalogs/` folders under `/server/services/**`.
 
-// Core libs
-import Service from '@server/app/service';
+## Models And Typing
 
-/*----------------------------------
-- TYPES
-----------------------------------*/
+- 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`.
+- Prefer inferred return types such as `Awaited<ReturnType<MyService['methodName']>>` over manual DTO duplication.
 
-export type Config = Record<string, never>;
+## Errors
 
-/*----------------------------------
-- SERVICE
-----------------------------------*/
-
-export default class ServiceName extends Service<Config, {}, AppType, ParentServiceType> {
-
-    public async methodName(data: { param1: string }) {
-        return this.services.OtherService.otherMethod(data);
-    }
-}
-```
-
-Replace `AppType` and `ParentServiceType` with the local app types used by neighboring services.
-If the service receives config from a project config file, replace `Config` with the real config shape and expose a typed
-config export with `Services.config(ServiceName, { ... })` from `server/config/*.ts`.
-
-## 2. Create the controller file in `/server/controllers/...`
-
-Template:
-
-```typescript
-import Controller, { schema } from '@server/app/controller';
-
-const MethodInput = schema.object({
-    param1: schema.string(),
-});
-
-export default class ServiceNameController extends Controller<AppType> {
-
-    public async methodName() {
-        const input = this.input(MethodInput);
-        const currentUser = this.request.auth.check('USER', null);
-
-        return this.services.ServiceName.methodName({
-            ...input,
-            currentUser,
-        });
-    }
-}
-```
-
-Replace `AppType` with the local app type if the surrounding controllers use a generic.
-Place the controller under the path that should drive the public API shape, for example `/server/controllers/ServiceName.ts` or `/server/controllers/ServiceName/subFeature.ts`.
-
-Rules:
-- Only files under `/server/controllers/**/*.ts` are indexed as callable API endpoints
-- Route path is derived from the controller file path and the method name
-- `this.input(schema)` is the only validation entrypoint
-- Call `this.input(...)` at most once per controller method
-- Request-scoped state exists only on `this.request`
-- Keep controllers thin and push business logic into services
-- Extract auth and request-derived values in the controller and pass explicit typed arguments into services
-
-## 3. Create the service metas file in `/server/services/<service name>/service.json`
-
-```json
-{
-    "id": "<AppIdentifier>/ServiceName",
-    "name": "ServiceName",
-    "parent": "app",
-    "dependences": []
-}
-```
-
-Use the same id namespace and naming convention as neighboring services in the project.
-
-## 4. Add a typed config export in `/server/config/*.ts` and instantiate the service in `/server/index.ts`
-
-```typescript
-// server/config/feature.ts
-import { Services } from '@server/app';
-import ServiceName from '@/server/services/ServiceName';
-
-export const serviceNameConfig = Services.config(ServiceName, {});
-```
-
-```typescript
-// server/index.ts
-import { Application } from '@server/app';
-import ServiceName from '@/server/services/ServiceName';
-import * as featureConfig from '@/server/config/feature';
-
-export default class MyApp extends Application {
-    public ServiceName = new ServiceName(this, featureConfig.serviceNameConfig, this);
-}
-```
-
-Match the existing config-grouping and namespace-import convention in the project instead of inventing a new bootstrap shape.
-
-## 5. Keep classes clean
-
-If the class grows too large, split business concerns into subservices.
-
-## 6. Use request-aware features only in controllers
-
-Use:
-
-```typescript
-const { auth, request, user, response } = this.request;
-```
-
-- Never import runtime request state from `@request`
-- Never access request-scoped state inside normal service methods
-- If a service needs user identity, locale, cookies, or another request-derived value, compute it in the controller and pass only that value
-
-## 7. Fetch and return data from the database
-
-Use runtime models through `this.models`:
-
-```typescript
-const users = await this.models.user.findMany({
-    select: {
-        id: true,
-    },
-});
-```
-
-Use prisma typings through `@models/types` only:
-
-```typescript
-import type * as Models from '@models/types';
-```
-
-Rules:
-- Never edit prisma files, except the schema
-- Never use runtime `@models` imports
-- If you need generated runtime Prisma enums or helpers already emitted by Proteum, follow the local `@generated/server/models` import pattern
-- In all queries and joins, always specify what fields to select
-
-## DTO and typing rules
-
-- Prefer inferred return types:
-`export type TResult = Awaited<ReturnType<MyService["MethodName"]>>;`
-- Never create manual DTO types when the exact return type can be inferred
-
-## Errors handling
-
-Never silence caught errors. Throw `Anomaly` with enough detail and the original error when needed.
+- Never silence caught errors.
+- If you need to wrap a failure, preserve enough detail and the original error.

package/agents/project/tests/AGENTS.md

@@ -1,9 +1,12 @@
-# Codex guidance for writing E2E tests
+# E2E Tests
 
-- Understand the typical user flow and the main feature branches
-- Favor as many tests as possible to cover real usage
-- Always locate elements via their `data-testid` attribute
-- Add `data-testid` where needed
-- Keep test files clean, organized and structured
-- Test the current controller/page runtime model, not legacy `@Route` or `api.fetch` behavior
-- Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants inside tests
+This file adds test-area local rules on top of the canonical framework contract:
+
+- framework repo: `agents/framework/AGENTS.md`
+- installed app: `./node_modules/proteum/agents/framework/AGENTS.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.
+- Locate elements with `data-testid`.
+- Add `data-testid` where needed instead of relying on brittle selectors.
+- Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.