@stjoseph/prumo 0.0.6 → 0.1.0

package/.prumo-templates/api/observability.md

@@ -2,90 +2,64 @@
 
 ## Rule
 
-Expose two health routes with `@nestjs/terminus`. Liveness reports that the process is up and checks
-no dependency. Readiness checks that dependencies answer, the database included. Mark both `@Public()`
-and exclude them from request logging.
+Expose two public health routes in `src/infra/http/controllers/health.controller.ts`. `/api/health/live`
+checks nothing. `/api/health/ready` checks the database with `orm.checkConnection()` and answers 503 when it
+is down.
 
-Connect the ORM explicitly at bootstrap, before the application listens.
+Connect the ORM explicitly in `server.ts`, before the application listens.
 
-Do not install an error-reporting or tracing service by default. A project has structured logs and
-these two routes, and nothing else, until its owner chooses otherwise.
+Do not install an error-reporting or tracing service by default. A project has structured logs and these two
+routes, and nothing else, until its owner chooses otherwise.
 
-When Sentry is chosen, wire it exactly as follows and not otherwise.
+When Sentry is chosen, wire it exactly as follows:
 
-Import `instrument.ts` as the first line of the bootstrap, before `NestFactory` and before every other
-import. Register `SentryModule` in the root module. Add `@SentryExceptionCaptured()` to the existing
-global exception filter's `catch()` method. Do not register `SentryGlobalFilter`.
-
-Send an event for any 5xx response: an unhandled exception and a deliberately thrown 5xx alike. Never
-send one for a 4xx, and never make a `logger.error` call create one by itself.
-
-Attach the request id as a **tag**, and the user's identifier when a session exists. Leave PII sending
-off. Never attach a request body.
+- Install `@sentry/node`. Call `Sentry.init` in `src/infra/observability/instrument.ts`, with
+  `Sentry.fastifyIntegration()` in `integrations`, and import that file as the first line of `server.ts`,
+  before `reflect-metadata`.
+- Give `fastifyIntegration` a `shouldHandleError` that uses the status the error handler resolves, so only a
+  5xx becomes an event. Export that mapping from `error-handler.ts` rather than writing a second one.
+- Do not call `setupFastifyErrorHandler`: in `@sentry/node` 11 it does nothing.
+- Attach the request id as a tag, and the user's id when a session exists. Leave PII sending off. Never
+  attach a request body.
 
 ## Rationale
 
-Liveness and readiness answer opposite questions (*should I restart this process* and *should I send
-it traffic*) and a single endpoint forces one answer to both. The failure that causes is routine: the
-endpoint checks the database, the database wobbles, and the orchestrator restarts a healthy process.
-Restarting does not fix a database, and the wobble becomes an outage.
+Liveness and readiness answer opposite questions, *should I restart this process* and *should I send it
+traffic*, and one endpoint forces one answer to both. The routine failure: the endpoint checks the database,
+the database wobbles, and the orchestrator restarts a healthy process.
 
-**MikroORM 7's `init` no longer connects**, and the readiness check asks whether a connection exists. Without
-the explicit connect, readiness reports the database down until a first query, and an orchestrator sends no
-query to an instance that is not ready. The instance never becomes ready. Connecting at bootstrap also means
-an unreachable database fails the boot instead of a request.
+**MikroORM 7's `init` no longer connects.** Without the explicit connect, readiness reports the database down
+until a first query, and no query reaches an instance that is not ready. Connecting first also means an
+unreachable database fails the boot instead of a request.
 
-Error reporting is not installed because it requires a commercial account. Installing a service that
-needs an account, a DSN and eventually a bill decides something commercial on the owner's behalf,
-inside a project that is theirs. Free tooling can simply be deleted; a SaaS dependency is different in
-kind. So the wiring is written down and ready, and absent until wanted.
+Error reporting is not installed because it requires a commercial account: an account, a DSN and eventually a
+bill is a commercial decision made on the owner's behalf. The wiring is written down and absent until wanted.
 
 `Sentry.init` must run before other modules load, because the instrumentation patches them as they are
-imported. Nothing enforces that ordering, which makes it the most fragile line in the project.
-
-The 5xx boundary is the status, not the exception type: a deliberately thrown `ServiceUnavailableException`
-is a real failure somebody must see, and treating it as routine because it was explicit would hide the
-case that matters most. Sending everything instead turns the issue list into a stream of invalid client
-input until somebody mutes the project.
+imported. The status comes from our mapping because a domain error carries a `kind`, not a status: a filter
+reading the error alone would count a 404 as a 500 and fill the issue list with invalid client input.
 
-**What reaches Sentry leaves your perimeter.** A log stays in infrastructure you control; a third-party
-service does not, and is readable by anyone with access to that project. That is why the bar here is
-higher than for logs, and why the body never goes: on an authentication route it is the password, on a
-payment route it is the card. Reproduction is a convenience; a leak into someone else's system is an
-incident.
+**What reaches Sentry leaves your perimeter**, readable by anyone with access to that project. That is why
+the body never goes: on an authentication route it is the password.
 
 ## Applies to
 
-The bootstrap, the health module, and the global exception filter.
+`server.ts`, the health controller, and `src/infra/observability/` once error reporting is installed.
 
 ## Examples
 
-Health routes:
-
-```
-✅  GET /api/health/live    → process is up, checks nothing
-    GET /api/health/ready   → database answers
-❌  GET /api/health         → used for both
 ```
+✅  GET /api/health/live     process is up, checks nothing
+    GET /api/health/ready    database answers
+❌  GET /api/health          used for both
 
-Wiring Sentry into the existing filter:
-
-```
-✅  @Catch()
-    export class ProblemFilter implements ExceptionFilter {
-      @SentryExceptionCaptured()
-      catch(exception: unknown, host: ArgumentsHost) {}
-    }
-
-❌  app.useGlobalFilters(new SentryGlobalFilter(), new ProblemFilter())
+✅  Sentry.fastifyIntegration({ shouldHandleError: (error) => statusOf(error) >= 500 })
+❌  Sentry.setupFastifyErrorHandler(app)
 ```
 
 ## Enforcement
 
-**Boot.** The health routes and the filter are registered once.
-
-**Review only, and this is the weakest line in the project:** that `instrument.ts` stays the first
-import. Reordering imports for tidiness, or a formatter doing it unasked, silently stops the
-instrumentation, and nothing fails.
+**Boot.** The health routes are registered once, and the ORM connects before listening.
 
-Also review: that no event carries a body, and that a 4xx never becomes one.
+**Review only, and this is the weakest line in the project:** that `instrument.ts` stays the first import.
+Reordering imports, or a formatter doing it unasked, silently stops the instrumentation, and nothing fails.

package/.prumo-templates/api/pagination.md

@@ -6,66 +6,51 @@ Paginate every list endpoint by cursor. The UUID v7 primary key is the cursor.
 
 Order by id descending. `after` means *older than this*. Do not accept a sort parameter.
 
-Accept two query parameters, declared on a query DTO: `limit`, defaulting to 20 and carrying
-`@Max(100)`, and `after`.
+Accept two query parameters in the route's `querystring` schema, a `z.strictObject`:
+`limit: z.coerce.number().int().min(1).max(100).default(20)` and `after: z.uuid().optional()`.
 
-Return `{ "data": [...], "nextCursor": "01J..." | null }`. Add nothing else: no `hasMore`, no
-`total`, no nested `meta`.
+Return `{ "data": [...], "nextCursor": "0199..." | null }`. Add nothing else: no `hasMore`, no `total`, no
+nested `meta`.
 
 Set `nextCursor` to the id of the last item on the page, or `null` when the page is the last one.
 
 ## Rationale
 
-Offset pagination fails silently. Under concurrent inserts, page 2 repeats an item from page 1 or
-skips one (no error, just a wrong list) and it degrades at depth, because the database counts and
-discards every skipped row. A cursor is stable at any depth, and UUID v7 being time-ordered means the
-id already is one: no extra sort column, no extra index.
+Offset pagination fails silently. Under concurrent inserts, page 2 repeats an item from page 1 or skips one,
+with no error, and it degrades at depth, because the database counts and discards every skipped row. A cursor
+is stable at any depth, and UUID v7 being time-ordered means the id already is one.
 
-That choice fixes the order. `WHERE id < :cursor ORDER BY id DESC` only works over one ordering, so a
-sort parameter would break the cursor without erroring. Descending, because that is what a list screen
-shows.
+That fixes the order: `WHERE id < :cursor ORDER BY id DESC` only works over one ordering, so a sort parameter
+would break the cursor without erroring.
 
-`hasMore` is omitted because a null `nextCursor` already says it, and a field derived from another
-field can disagree with it. `total` is omitted because it costs a `COUNT` on every request: the most
-expensive part of an otherwise cheap endpoint, paid whether or not anyone reads it. Adding it to one
-route later breaks no client.
+`hasMore` is omitted because a null `nextCursor` already says it. `total` is omitted because it costs a
+`COUNT` on every request, paid whether or not anyone reads it; adding it to one route later breaks no client.
 
-The parameters are an ordinary query DTO, so validation already covers them and the maximum is a
-decorator rather than clamping logic. Clamping would return 100 rows to a client that asked for 500
-without saying so, and the client would advance as though it had consumed 500.
+The maximum lives in the schema rather than in clamping logic. Clamping would return 100 rows to a client
+that asked for 500 without saying so.
 
 ## Applies to
 
-Every endpoint returning a collection. Filtering is not covered here: a filter is a query DTO field
-like any other, and it composes with the cursor without special handling.
+Every endpoint returning a collection. A filter is another field of the same query schema and composes with
+the cursor.
 
 ## Examples
 
-The response:
-
 ```
-✅  { "data": [ ... ], "nextCursor": "01JQ8Z..." }
+✅  { "data": [ ... ], "nextCursor": "0199..." }
 ❌  { "data": [ ... ], "meta": { "page": 2, "total": 3204, "hasMore": true } }
-```
 
-The query DTO:
+✅  limit: z.coerce.number().int().min(1).max(100).default(20)
+❌  limit: z.coerce.number().default(20)          no maximum: ?limit=1000000
 
-```
-✅  @Max(100) limit: number = 20
-❌  limit: number = 20        // no maximum; ?limit=1000000 is a denial of service
-```
-
-Ordering:
-
-```
-✅  GET /api/v1/orders?limit=20&after=01JQ8Z...
+✅  GET /api/v1/orders?limit=20&after=0199...
 ❌  GET /api/v1/orders?sort=total&page=3
 ```
 
 ## Enforcement
 
-**Validation.** `limit`'s bounds are enforced by the pipe, and an unknown parameter (`page`, `sort`,
-`offset`) is already rejected because unknown properties are forbidden.
+**Validation.** `limit`'s bounds are enforced by the schema, and an unknown parameter (`page`, `sort`,
+`offset`) is rejected by `z.strictObject`.
 
-**Review only.** That `nextCursor` is the last item's id and is null on the final page, and that a new
-list endpoint paginates at all rather than returning an unbounded array.
+**Review only.** That `nextCursor` is the last item's id and is null on the final page, and that a new list
+endpoint paginates at all.

package/.prumo-templates/api/routes.md

@@ -2,88 +2,107 @@
 
 ## Rule
 
-Set a global prefix of `api` and enable `VersioningType.URI`. Every route is reachable at
-`/api/v<n>/<resource>`.
+Serve every route at `/api/v<n>/<resource>`: register each controller with
+`prefix: '/api/v<n>/<resource>'`. Better Auth's `/api/auth/*`, `/api/health/*` and `/api/docs` are the only
+routes outside a version.
 
-Name resources in the plural, kebab-case for compound words. Use REST verbs and Nest's default status
-codes.
+Name resources in the plural, kebab-case for compound words. Use REST verbs. A `POST` answers `201`
+through `reply.code(201)`; every other method answers `200`.
 
-Put input DTOs in `dto/`, named as the generator names them: `CreateUserDto`, `UpdateUserDto`.
+Write one controller per module, `src/infra/http/controllers/<module>.controller.ts`, as a Fastify plugin
+declared with `function`. Its handler reads the request, resolves one use case from the container, calls
+`execute()` and returns the result. Nothing else happens in a handler.
 
-Configure the global `ValidationPipe` with `whitelist: true`, `forbidNonWhitelisted: true` and
-`transform: true`. Leave `enableImplicitConversion` off; convert a field that needs it with `@Type()`.
+Declare every route's schemas from the module's `dto/`: `body`, `querystring` and `params` for what enters,
+`response` for what leaves, keyed by status. Write input schemas with `z.strictObject`, output schemas with
+`z.object`. Convert a query or path value that is not a string with `z.coerce`, in the schema.
 
-Return the entity. Serialize it with `ClassSerializerInterceptor`, marking with `@Exclude` every
-property that must not leave. Where the value arrives as a plain object, add
-`@SerializeOptions({ type: Entity })`. Do not write a response DTO per route.
+Write one output schema per shape the API exposes, named after the entity: `profile-response.dto.ts`. Every
+route and every MCP tool returning that shape uses it. Write another only when the shape differs, and name
+the difference: `profile-summary-response.dto.ts`. Declare dates in an output schema as `z.date()`.
 
-A controller receives the request, calls the service and returns. Everything else on it is a
-decorator.
-
-Enable the `@nestjs/swagger` CLI plugin. Decorate by hand only what it cannot infer: error responses,
-non-obvious status codes, route descriptions.
+Tag every route with its module. Describe by hand only what a schema cannot say: a non-obvious status, an
+error a route answers on purpose.
 
 Serve the documentation UI outside production only.
 
 ## Rationale
 
-The global prefix makes Better Auth's `/api/auth/*` fall out of the ordinary convention instead of
-becoming the one route with an exception in its path.
+The prefix makes Better Auth's `/api/auth/*` fall out of the ordinary convention instead of becoming the
+one route with an exception in its path.
+
+Versioning costs five characters today and a coordinated migration of every consumer later, including a
+published mobile app that does not update when you want it to. It goes in the URI rather than a header
+because a version in the URL appears in logs, caches, a `curl` line and an error report: exactly where you
+look when v1 breaks.
 
-Versioning costs five characters today and a coordinated migration of every consumer later, including
-a published mobile app that does not update when you want it to. It goes in the URI rather than a
-header because a version in the URL appears in logs, caches, a `curl` line and a Sentry report:
-exactly where you look when v1 breaks.
+`z.strictObject` is what makes an unexpected property visible. Stripping it silently returns 200 to a
+client that sent `role: "admin"`, which looks like success and hides the honest bug and the malicious
+attempt equally.
 
-`forbidNonWhitelisted` is what makes an unexpected property visible. Stripping it silently returns 200
-to a client that sent `role: "admin"`, which looks like success and hides the honest bug and the
-malicious attempt equally.
+On the way out the opposite is wanted, and `z.object` gives it: Fastify serializes through the response
+schema and drops every field it does not list. The schema is therefore the list of what may leave. It is
+written once per shape, because three schemas over one entity would each have to remember to leave out
+`tenant_id`, and so would the fourth someone adds later. A route with no response schema would fall back
+to `JSON.stringify` and publish every column, which is why the application refuses to start with one.
 
-Serialization is declared once on the entity rather than repeated in every response DTO that touches
-it. Three DTOs over one entity would each have to remember to omit `tenant_id`, and so would the
-fourth someone adds later.
+A date is `z.date()` because the entity holds a `Date` and Fastify writes it as ISO 8601. `z.iso.datetime()`
+and `.transform()` both fail at runtime on a `Date`, with a 500.
 
-The swagger plugin reads the class-validator decorators that already exist. Declaring the same field a
-third time by hand produces the copy nobody updates, and API documentation that lies is worse than
-none, because consumers trust it.
+The OpenAPI document is generated from the same schemas the routes validate with. A description written by
+hand beside them is the copy nobody updates, and documentation that lies is worse than none, because
+consumers trust it.
+
+`201` on `POST` is the status code clients already receive: the rule was Nest's default before, and is
+written down now that no framework supplies it.
 
 ## Applies to
 
-Every controller under `src/`, and the application bootstrap where the prefix, versioning, pipe and
-documentation are configured.
+Every controller under `src/infra/http/controllers/`, every schema under `src/domain/<module>/dto/`, and
+`src/infra/http/app.ts`, where the prefixes, the compilers and the documentation are registered.
 
 ## Examples
 
 Resource naming and versioning:
 
 ```
-✅  @Controller({ path: 'billing-accounts', version: '1' })
-❌  @Controller('billingAccount')
+✅  app.register(billingAccountsController, { prefix: '/api/v1/billing-accounts' })
+❌  app.register(billingAccountsController, { prefix: '/billingAccount' })
+```
+
+What enters and what leaves:
+
+```
+✅  body: updateProfileSchema          z.strictObject({ … })
+    response: { 200: profileResponseSchema }
+❌  body: z.object({ … })               an unknown field passes, silently dropped
+❌  { schema: { body: … } }             no response: every column leaves
 ```
 
-Keeping a property out of a response:
+A value from the query string:
 
 ```
-✅  @Exclude() tenantId!: string
-❌  tenantId!: string
+✅  page: z.coerce.number().int().min(1)
+❌  page: z.number()                    always a string on the wire, always a 400
 ```
 
-A controller that delegates:
+A handler that delegates:
 
 ```
-✅  findOne(@Param('id') id: string) { return this.users.findById(id) }
-❌  findOne(@Param('id') id: string) {
-      const u = await this.users.findById(id)
-      if (u.plan === 'trial' && u.createdAt < cutoff) u.plan = 'expired'
-      return u
+✅  async (request) => app.container.resolve(FindProfileUseCase).execute(currentUser(request).id)
+❌  async (request) => {
+      const profile = await app.container.resolve(FindProfileUseCase).execute(id)
+      if (profile.plan === 'trial' && profile.createdAt < cutoff) profile.plan = 'expired'
+      return profile
     }
 ```
 
 ## Enforcement
 
-**Boot.** The prefix, versioning, `ValidationPipe` and serializer are configured once at bootstrap, so
-a route cannot opt out of them by accident.
+**Boot.** `src/infra/http/app.ts` refuses to start when a route under `/api/v` declares no response
+schema, and names it. The compilers, the prefix and the documentation are registered once there, so a
+route cannot opt out of them by accident.
 
-**Review only.** Resource naming, controller thinness, and (most importantly) whether a new
-sensitive column carries `@Exclude`. Nothing checks that, and a column added without it is published
-to every client of that route.
+**Review only.** Resource naming, the thinness of a handler, `201` on `POST`, `z.strictObject` on input,
+and (most importantly) whether a new sensitive column has stayed out of the output schema. The schema
+lists what leaves, so a field is only published when somebody adds it to that list.

package/.prumo-templates/api/structure.md

@@ -0,0 +1,130 @@
+# Structure
+
+## Rule
+
+Split `src/` into two layers. `src/domain` holds what the product is: entities, ports, use cases, DTOs and
+errors. `src/infra` holds how it runs: configuration, auth, the database adapters, the HTTP edge and the
+dependency container.
+
+Import nothing from `src/infra`, from the ORM or from the HTTP framework inside `src/domain`. The domain
+imports `zod` for its DTOs and `tsyringe` for its decorators, and nothing else outside itself, except by
+name: an entity declaring a relation imports `Ref`, `ref` and `Collection` from `@mikro-orm/core`, and
+nothing more.
+
+Create one module per resource under `src/domain`: `users`, `orders`, `invoices`. A module holds only these
+folders, each created with its first file:
+
+| Folder | Holds | File |
+|---|---|---|
+| `entities/` | A plain class with the data and the behaviour of one entity | `<name>.entity.ts` |
+| `repositories/` | The port: an interface and its `Symbol` token, in one file | `<name>.repository.ts` |
+| `use-cases/` | One class per use case, with one `execute()` method | `<verb>-<noun>.use-case.ts` |
+| `dto/` | Zod schemas and their inferred types, input and output | `<name>.dto.ts` |
+| `errors/` | Classes extending `DomainError` | `<name>.error.ts` |
+| `services/` | A pure function spanning several entities of the module | `<name>.service.ts` |
+
+Put logic about one entity in a method of that entity. Put logic spanning several in an exported function
+under `services/`. A pure function is imported directly and never registered in the container.
+
+For every port, write its adapter under `src/infra` and register it in `src/infra/di/<module>.di.ts`, which
+`src/infra/di/index.ts` calls.
+
+Name every file with its role suffix, including where the folder already says it.
+
+Reach another module only through its use cases: inject the use case class. A module's ports are its own;
+no other module injects them.
+
+Two modules never depend on each other in both directions, and neither do two use cases. When they appear
+to, move the common part into a third module named for what it does. Do not use tsyringe's `delay()`.
+
+Do not write barrel files. An `index.ts` that holds code of its own, as `src/infra/di/index.ts` does, is not
+one.
+
+Put in `src/domain/shared/` only a primitive every module uses or a second module has come to need, in a
+folder named for its role: `errors/`, `transactions/`. A capability with a name of its own, such as
+`notifications`, `pdf` or `storage`, is a module, not a shared file.
+
+## Rationale
+
+The layers exist so the rules can be read and tested without a database or a server. A use case receives
+its ports through the constructor, so its test hands it an in-memory fake; nothing about Postgres or
+Fastify is needed to prove a rule of the product. The rule is kept by convention rather than by a checker,
+a choice made knowingly: the one checker considered was measured once producing a useless file to satisfy
+itself.
+
+One class per use case keeps each constructor to what that case needs. A service per module accumulates
+the dependencies of every case in one constructor and grows without a limit.
+
+The suffix is always written because the same name lives in several layers. `update-profile` is both a
+DTO and a use case; `profile` is an entity, a schema, a port and an adapter. Without the suffix, an editor
+shows four tabs named `profile.ts` and a file search cannot tell them apart. A rule of *suffix where it
+collides* would need judging at every new file and would rename old files when a new one arrived.
+
+Reaching another module through its use cases means the module that owns an entity is the only one that
+writes it, so its rules cannot be bypassed from outside. A cycle is refused because tsyringe's answer to
+one, `delay()`, is presented in its own documentation as the way out of an `undefined constructor` error:
+a patch over a design already in a loop. Barrel files are refused because they are how an invisible cycle
+forms: a file imports the index that imports it back.
+
+A folder exists only with its first file because Git does not keep an empty one, and a folder waiting to
+be filled is filled for its own sake. `domain/shared/` has an admission test because a shared folder
+without one only grows; requiring a role for each folder forces the question *what is this*.
+
+**What this costs:** a module that is large and still one thing gets many files, one per use case. And
+nothing but review keeps the domain free of the infrastructure.
+
+## Applies to
+
+Every file under `src/` of the API. The rules about reaching across modules apply wherever one module's
+code refers to another's.
+
+## Examples
+
+The layers:
+
+```
+✅  src/domain/orders/use-cases/create-order.use-case.ts   imports @/domain/…
+❌  src/domain/orders/use-cases/create-order.use-case.ts   imports @mikro-orm/core
+```
+
+A module:
+
+```
+✅  domain/users/entities/profile.entity.ts
+    domain/users/repositories/profile.repository.ts        interface + PROFILE_REPOSITORY
+    domain/users/use-cases/update-profile.use-case.ts
+    domain/users/dto/update-profile.dto.ts
+❌  domain/users/users.service.ts                           every case in one class
+❌  domain/users/profile.ts                                 no role suffix
+```
+
+Reaching another module:
+
+```
+✅  constructor(private readonly findProfile: FindProfileUseCase) {}
+❌  constructor(@inject(PROFILE_REPOSITORY) private readonly profiles: ProfileRepository) {}   from orders
+❌  constructor(@inject(delay(() => CreateOrderUseCase)) …)
+```
+
+Where logic goes:
+
+```
+✅  profile.update(changes)                      one entity
+✅  domain/orders/services/order-total.service.ts   several entities
+❌  a private function copied into two use cases
+```
+
+Importing:
+
+```
+✅  import { FindProfileUseCase } from '@/domain/users/use-cases/find-profile.use-case'
+❌  import { FindProfileUseCase } from '@/domain/users'
+```
+
+## Enforcement
+
+**Lint.** Biome's `noBarrelFile`, enabled in the API's `biome.jsonc`, refuses a file that re-exports.
+
+**Review only.** Everything else. Nothing checks that the domain imports no infrastructure, that a module
+maps to a resource, that another module is reached through its use cases, that no cycle has formed, or
+that `domain/shared/` admits only primitives; a reviewer does.

package/.prumo-templates/client/data.md

@@ -38,9 +38,10 @@ API renames a field, the client keeps compiling against its own copy, and the fa
 `undefined` on a screen.
 
 **Importing the entity type from the API package looks like the obvious fix and is unsound.** Responses
-are entities passed through `ClassSerializerInterceptor`, so every `@Exclude`d property is missing from the
-JSON while remaining on the entity type. The shared type would promise `tenantId` on a payload that never
-carries it: a type that lies, which is worse than the duplication it removes.
+pass through the route's output schema, which drops every field it does not list, so a property can remain
+on the entity type while missing from the JSON; and a `Date` on the entity arrives as an ISO string. The
+shared type would promise `tenantId` on a payload that never carries it: a type that lies, which is worse
+than the duplication it removes.
 
 **The contract lives in one directory, not beside each feature, so that one template serves both
 architectures.** The monorepo form moves `api-contract/` whole into `packages/api-contract` and changes one

package/.prumo-templates/core/conventions.md

@@ -2,8 +2,9 @@
 
 ## Rule
 
-Name every source file in kebab-case, with the role suffix the generator uses: `users.service.ts`,
-`users.controller.ts`, `create-user.dto.ts`, `button.tsx`.
+Name every source file in kebab-case. In `api`, add the role suffix, always: `profile.entity.ts`,
+`update-profile.use-case.ts`, `update-profile.dto.ts`, `users.controller.ts`. A component is
+`button.tsx`.
 
 Write a comment only when it carries a fact the code cannot carry about itself. Before writing one, ask
 whether a careful reader could recover it anyway. If they could, delete it.
@@ -19,9 +20,11 @@ tag or a change log; git holds all three.
 
 ## Rationale
 
-kebab-case is what `nest g resource` and shadcn's CLI both emit, so anything else adds a rename step after
-every generation, and a correction after generation is what people forget. It also never touches a problem
-PascalCase lives with: macOS and Windows are case-insensitive, so renaming `OrderList.tsx` to
+kebab-case is what shadcn's CLI emits, so anything else adds a rename step after every generation, and a
+correction after generation is what people forget. The suffix is always written because in `api` the same
+name lives in several layers: `update-profile` is a DTO and a use case, `profile` an entity, a schema, a port
+and an adapter, and without it an editor shows four tabs called `profile.ts`. kebab-case also never touches
+a problem PascalCase lives with: macOS and Windows are case-insensitive, so renaming `OrderList.tsx` to
 `orderList.tsx` does not register as a change in git, and the file ends up cased differently in the
 repository and on a Linux clone.
 
@@ -44,8 +47,8 @@ Every source file, in every type.
 Naming:
 
 ```
-✅  create-user.dto.ts      users.service.ts      order-list.tsx
-❌  CreateUserDto.ts        UsersService.ts       OrderList.tsx
+✅  create-user.dto.ts      create-user.use-case.ts      order-list.tsx
+❌  CreateUserDto.ts        create-user.ts               OrderList.tsx
 ```
 
 A comment that earns its place: