create-m5kdev 0.41.0 → 0.43.0

package/templates/minimal-app/.cursor/rules/module-service-guide.mdc

@@ -1,367 +1,367 @@
----
-globs: apps/**/server/src/modules/**/*.service.ts
-alwaysApply: false
----
-
-# Module Service File Style Guide
-
-Conventions for service classes in app modules. Services consume the module
-DTO object (`postSchemas`) — they do not import hand-written request/response
-types. Input and output schemas are attached to each procedure.
-
-## File Location
-
-```
-apps/<app>/server/src/modules/<module>/<module>.service.ts
-```
-
-## Conventions
-
-- Always extend `BasePermissionService<Repositories, Services>`.
-- Declare repository and service dependencies as explicit named maps in generics.
-- Instantiate service classes in `apps/*/server/src/service.ts` (composition root), not inside module files.
-- Keep orchestration/business logic in service; repositories handle persistence only.
-- Implement service methods as `readonly` procedures using `this.procedure("name")` builder chains.
-- Propagate `ServerResultAsync` consistently and use `err(...)`/`ok(...)` composition.
-- Prefer helper methods for repeated workflows (prompt prep, query assembly, enrichment).
-- Define grants in `<module>.grants.ts` and wire them when composing the service.
-- **Strongly prefer repository built-ins** (`queryList`, `queryFind`, `findById`, `create`, `update`, `deleteById`, …) over custom repository methods.
-
-## Prefer Repository Built-ins
-
-Call `BaseTableRepository` helpers from the service. Do **not** invent repository wrappers for ordinary CRUD, lists, or lookups.
-
-- **Reads**: use `queryList` / `queryFind` with `filters` (and `addContextFilter` when org/member scoped). Usually no custom `list*` / `get*` / `findBy*` repository methods.
-- **Creates**: `create` is permissive — stamp defaults and actor fields in the service (`memberId`, `organizationId`, `status: "draft"`, …) and pass the full row payload. No custom `create*` repo method for defaults.
-- **Updates**: `update` accepts partial fields — only pass columns that should change. No custom `update*` repo method to omit fields or merge patches.
-- Add a custom repository method only for joins, CTEs, multi-table writes, transactions, or predicates that cannot be expressed with filters / `TableConditionBuilder`.
-
-```typescript
-// Preferred: built-in + filters / stamped defaults in the service
-readonly listPublished = this.procedure("listPublished")
-  .input(postSchemas.input.list)
-  .output(postSchemas.output.list)
-  .requireAuth("organization")
-  .addContextFilter(["organization"])
-  .addFilters(() => [
-    {
-      columnId: "status",
-      type: "enum",
-      method: "equals",
-      value: "published",
-    },
-  ])
-  .access({ action: "read" })
-  .handle(({ input }) =>
-    this.repository.posts.queryList(input, {
-      globalSearchColumns: ["title", "excerpt", "content"],
-    })
-  );
-
-readonly create = this.procedure("create")
-  .input(postSchemas.input.create)
-  .output(postSchemas.output.single)
-  .requireAuth("organization")
-  .access({ action: "write" })
-  .handle(async ({ input, ctx }) => {
-    return this.repository.posts.create({
-      ...input,
-      memberId: ctx.actor.memberId,
-      organizationId: ctx.session.activeOrganizationId,
-      status: "draft",
-    });
-  });
-
-readonly update = this.procedure("update")
-  .input(postSchemas.input.update)
-  .output(postSchemas.output.single)
-  .requireAuth("organization")
-  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
-  .access({ action: "write", entityStep: "post" })
-  .handle(async ({ input }) => {
-    // Partial update — only fields present on input are written
-    return this.repository.posts.update(input);
-  });
-```
-
-## Avoid Trivial Service Delegation
-
-- Do not add a service method whose only behavior is calling another service.
-- Call the owning service directly when no business rule, authorization, validation, orchestration, transaction boundary, or meaningful domain translation is added.
-- Renaming the dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a wrapper.
-- A delegating method is justified only when the current service genuinely owns the use case and adds behavior or protects a boundary callers must not bypass.
-- If removing the method and calling the dependency directly would lose nothing, do not add the method.
-
-## Procedure Builder
-
-Each procedure declares its schemas from the DTO, then auth, resource loading,
-access control, and the handler:
-
-1. `.input(schema)` -- Accepts a Zod schema; infers `TInput` so you don't need `this.procedure<Type>(...)`. No runtime validation by default; pass `true` as second arg to enable it.
-2. `.output(schema)` -- Accepts a Zod schema; constrains the handler return type so you don't need explicit return annotations. No runtime validation by default; pass `true` as second arg to enable it.
-3. `.requireAuth(scope?)` -- Enforces authentication. Scope can be `"user"` (default), `"organization" (recommended)`, `"team"`, or `"admin"`.
-4. `.loadResource(name, loader)` -- Loads a value and stores it in `state`; returns `NOT_FOUND` if falsy.
-5. `.use(name, step)` -- Runs an arbitrary step and stores the result in `state`.
-6. `.addContextFilter(scopes?)` -- Applies context-based query filtering (requires auth).
-7. `.addFilters(resolve)` -- Appends query filters to the current input (`({ input, ctx, state, ... }) => QueryFilter | QueryFilter[]`).
-8. `.access(config)` -- Permission check via grants. Arrays are soft-filtered to allowed rows (empty OK); single entities return `FORBIDDEN` when denied. Filtered arrays are written back to `entityStep` state.
-9. `.handle(handler)` -- Terminal method; runs the handler with `{ input, ctx, state, repository, service, logger }`.
-
-### Input / Output Typing
-
-Prefer `.input(schema)` with Zod schemas from the module's `.dto.ts`:
-
-```typescript
-// Preferred: schema-driven
-readonly create = this.procedure("create")
-  .input(postSchemas.input.create)
-  .output(postSchemas.output.single)
-  .requireAuth("organization")
-  .access({ action: "write" })
-  .handle(async ({ input, ctx }) => {
-    return this.repository.posts.create({
-      ...input,
-      userId: ctx.actor.userId,
-      memberId: ctx.actor.memberId,
-    });
-  });
-
-// Acceptable for simple primitives with no matching schema
-readonly getCount = this.procedure("getCount")
-  .requireAuth("organization")
-  .access({ action: "read" })
-  .handle(async ({ ctx }): ServerResultAsync<number> => {
-    return this.repository.posts.countByUser(ctx.actor.userId);
-  });
-```
-
-When no Zod schema exists (simple primitives, inline objects), you can still use the generic: `this.procedure<string>("name")`.
-
-## Procedure Patterns
-
-### Simple CRUD
-
-```typescript
-readonly list = this.procedure("list")
-  .input(postSchemas.input.list)
-  .output(postSchemas.output.list)
-  .requireAuth("organization")
-  .addContextFilter(["organization"])
-  .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
-  .access({
-    action: "read",
-    entityStep: "posts",
-  })
-  .handle(({ state }) => state.posts);
-
-readonly create = this.procedure("create")
-  .input(postSchemas.input.create)
-  .output(postSchemas.output.single)
-  .requireAuth("organization")
-  .access({ action: "write" })
-  .handle(async ({ input, ctx }) => {
-    return this.repository.posts.create({
-      ...input,
-      userId: ctx.actor.userId,
-      memberId: ctx.actor.memberId,
-    });
-  });
-```
-
-### With Resource Loading and Access Control (recommended)
-
-```typescript
-readonly update = this.procedure("update")
-  .input(postSchemas.input.update)
-  .output(postSchemas.output.single)
-  .requireAuth("organization")
-  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
-  .access({
-    action: "write",
-    entityStep: "post",
-  })
-  .handle(async ({ input }) => {
-    return this.repository.posts.update(input);
-  });
-```
-
-Use grants with `"org"` (org admin/owner) or `"own"` (member) so `findById` cannot update cross-org rows. Do not use `"all"` for organization-scoped roles.
-
-### Org-scoped list with access soft-filter
-
-```typescript
-readonly list = this.procedure("list")
-  .input(postSchemas.input.list)
-  .output(postSchemas.output.list)
-  .requireAuth("organization")
-  .addContextFilter(["organization"])
-  .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
-  .access({
-    action: "read",
-    entityStep: "posts",
-  })
-  .handle(({ state }) => state.posts);
-```
-
-- Default list scoping: `addContextFilter(["organization"])`.
-- When grants are member-own only, prefer `addContextFilter(["member", "organization"])` so the query is already narrowed.
-- `.access` on an **array** soft-filters to allowed rows (may be `[]`); it does not 403 the whole list.
-- Filtered results are written back to `state[entityStep]` (here `state.posts`).
-
-### With Context Filter (Query-Based Lists)
-
-```typescript
-readonly list = this.procedure("list")
-  .output(postSchemas.output.list)
-  .requireAuth("organization")
-  .addContextFilter(["member", "organization"])
-  .access({ action: "read" })
-  .handle(({ input }) => {
-    return this.repository.posts.queryList(input, {
-      globalSearchColumns: ["title", "excerpt", "content"],
-    });
-  });
-```
-
-### Create with business logic
-
-```typescript
-readonly create = this.procedure("create")
-  .requireAuth("organization")
-  .input(postSchemas.input.create)
-  .output(postSchemas.output.single)
-  .access({ action: "write" })
-  .handle(async ({ input, ctx }) => {
-    const uniqueSlug = await this.repository.posts.resolveUniqueSlug({
-      candidate: slugify(input.slug ?? input.title),
-    });
-    if (uniqueSlug.isErr()) return err(uniqueSlug.error);
-
-    return this.repository.posts.create({
-      // Org-scoped assets: stamp memberId (+ organizationId). Personal resources: stamp userId.
-      memberId: ctx.actor.memberId,
-      organizationId: ctx.actor.organizationId,
-      title: input.title.trim(),
-      slug: uniqueSlug.value,
-      content: input.content.trim(),
-      status: "draft",
-    });
-  });
-```
-
-### Soft delete
-
-```typescript
-readonly softDelete = this.procedure("softDelete")
-  .input(postSchemas.input.delete)
-  .output(postSchemas.output.uuid)
-  .requireAuth("organization")
-  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
-  .access({ action: "delete", entityStep: "post" })
-  .handle(async ({ input }) => {
-    const updated = await this.repository.posts.update({
-      id: input.id,
-      deletedAt: new Date(),
-    });
-    if (updated.isErr()) return err(updated.error);
-    return ok({ id: updated.value.id });
-  });
-```
-
-### Public (No Auth)
-
-```typescript
-readonly validateCode = this.procedure("validateCode")
-  .input(postSchemas.input.validate)
-  .output(postSchemas.output.status)
-  .handle(async ({ input }) => {
-    return this.repository.posts.validateCode(input);
-  });
-```
-
-## Permission and Grants
-
-- Keep all guarded action names aligned with grants (`read`, `write`, `delete`, `publish`, etc.).
-- Do not use undeclared action aliases (e.g., guard `"update"` when grants only define `"write"`).
-- Prefer `.access({ action, entityStep? })` over ad-hoc ownership checks in `.use`.
-- For org-scoped assets, stamp and authorize with `memberId` (`ctx.actor.memberId`). Keep `userId` for authentication and personal resources (billing, devices, OAuth). Prefer the column name `memberId` over aliases like `authorMemberId`.
-- Access modes: `"all"` (global), `"org"` (same organization), `"own"` (ownership), `"none"` (explicit deny). Prefer `"org"` for org owner/admin grants.
-
-## Access Control Modes
-
-- **`entityStep`** — references a value stored by `.loadResource()`/`.use()`;
-  the entity's `userId`, `memberId`, `organizationId`, and `teamId` are read automatically.
-  Arrays are soft-filtered; singles return `FORBIDDEN` when denied. Filtered arrays are written back to the step state.
-- **`entities`** — inline function returning `{ userId?, memberId?, organizationId?, teamId? }`
-  when the entity is not loaded into state.
-
-## Example Skeleton
-
-```typescript
-import { BasePermissionService } from "@m5kdev/backend/base/base.service";
-import { postSchemas } from "./posts.dto";
-import type { PostsRepository } from "./posts.repository";
-
-export class PostsService extends BasePermissionService<
-  { posts: PostsRepository },
-  Record<string, never>
-> {
-  readonly list = this.procedure("list")
-    .input(postSchemas.input.list)
-    .output(postSchemas.output.list)
-    .requireAuth("organization")
-    .addContextFilter(["organization"])
-    .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
-    .access({
-      action: "read",
-      entityStep: "posts",
-    })
-    .handle(({ state }) => state.posts);
-
-  readonly create = this.procedure("create")
-    .input(postSchemas.input.create)
-    .output(postSchemas.output.single)
-    .requireAuth("organization")
-    .access({ action: "write" })
-    .handle(async ({ input, ctx }) => {
-      return this.repository.posts.create({
-        ...input,
-        userId: ctx.actor.userId,
-        memberId: ctx.actor.memberId,
-      });
-    });
-
-  readonly update = this.procedure("update")
-    .input(postSchemas.input.update)
-    .output(postSchemas.output.single)
-    .requireAuth("organization")
-    .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
-    .access({
-      action: "write",
-      entityStep: "post",
-    })
-    .handle(async ({ input }) => {
-      return this.repository.posts.update(input);
-    });
-
-  readonly delete = this.procedure("delete")
-    .input(postSchemas.input.delete)
-    .requireAuth("organization")
-    .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
-    .access({
-      action: "delete",
-      entityStep: "post",
-    })
-    .handle(async ({ input }) => {
-      return this.repository.posts.deleteById(input.id);
-    });
-}
-```
-
-## Best Practices
-
-1. Keep procedures as `readonly` class properties.
-2. `.loadResource()` before `.access({ entityStep })` — it 404s on missing rows for free.
-3. Return `this.error("NOT_FOUND")` / `this.error("FORBIDDEN")` for expected failures; reserve 5xx codes for server faults (they report to Sentry).
-4. Keep pure helpers (slugify, excerpt) in `<module>.utils.ts`.
-5. Propagate `err(...)` from repository results rather than throwing.
+---
+globs: apps/**/server/src/modules/**/*.service.ts
+alwaysApply: false
+---
+
+# Module Service File Style Guide
+
+Conventions for service classes in app modules. Services consume the module
+DTO object (`postSchemas`) — they do not import hand-written request/response
+types. Input and output schemas are attached to each procedure.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.service.ts
+```
+
+## Conventions
+
+- Always extend `BasePermissionService<Repositories, Services>`.
+- Declare repository and service dependencies as explicit named maps in generics.
+- Instantiate service classes in `apps/*/server/src/service.ts` (composition root), not inside module files.
+- Keep orchestration/business logic in service; repositories handle persistence only.
+- Implement service methods as `readonly` procedures using `this.procedure("name")` builder chains.
+- Propagate `ServerResultAsync` consistently and use `err(...)`/`ok(...)` composition.
+- Prefer helper methods for repeated workflows (prompt prep, query assembly, enrichment).
+- Define grants in `<module>.grants.ts` and wire them when composing the service.
+- **Strongly prefer repository built-ins** (`queryList`, `queryFind`, `findById`, `create`, `update`, `deleteById`, …) over custom repository methods.
+
+## Prefer Repository Built-ins
+
+Call `BaseTableRepository` helpers from the service. Do **not** invent repository wrappers for ordinary CRUD, lists, or lookups.
+
+- **Reads**: use `queryList` / `queryFind` with `filters` (and `addContextFilter` when org/member scoped). Usually no custom `list*` / `get*` / `findBy*` repository methods.
+- **Creates**: `create` is permissive — stamp defaults and actor fields in the service (`memberId`, `organizationId`, `status: "draft"`, …) and pass the full row payload. No custom `create*` repo method for defaults.
+- **Updates**: `update` accepts partial fields — only pass columns that should change. No custom `update*` repo method to omit fields or merge patches.
+- Add a custom repository method only for joins, CTEs, multi-table writes, transactions, or predicates that cannot be expressed with filters / `TableConditionBuilder`.
+
+```typescript
+// Preferred: built-in + filters / stamped defaults in the service
+readonly listPublished = this.procedure("listPublished")
+  .input(postSchemas.input.list)
+  .output(postSchemas.output.list)
+  .requireAuth("organization")
+  .addContextFilter(["organization"])
+  .addFilters(() => [
+    {
+      columnId: "status",
+      type: "enum",
+      method: "equals",
+      value: "published",
+    },
+  ])
+  .access({ action: "read" })
+  .handle(({ input }) =>
+    this.repository.posts.queryList(input, {
+      globalSearchColumns: ["title", "excerpt", "content"],
+    })
+  );
+
+readonly create = this.procedure("create")
+  .input(postSchemas.input.create)
+  .output(postSchemas.output.single)
+  .requireAuth("organization")
+  .access({ action: "write" })
+  .handle(async ({ input, ctx }) => {
+    return this.repository.posts.create({
+      ...input,
+      memberId: ctx.actor.memberId,
+      organizationId: ctx.session.activeOrganizationId,
+      status: "draft",
+    });
+  });
+
+readonly update = this.procedure("update")
+  .input(postSchemas.input.update)
+  .output(postSchemas.output.single)
+  .requireAuth("organization")
+  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+  .access({ action: "write", entityStep: "post" })
+  .handle(async ({ input }) => {
+    // Partial update — only fields present on input are written
+    return this.repository.posts.update(input);
+  });
+```
+
+## Avoid Trivial Service Delegation
+
+- Do not add a service method whose only behavior is calling another service.
+- Call the owning service directly when no business rule, authorization, validation, orchestration, transaction boundary, or meaningful domain translation is added.
+- Renaming the dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a wrapper.
+- A delegating method is justified only when the current service genuinely owns the use case and adds behavior or protects a boundary callers must not bypass.
+- If removing the method and calling the dependency directly would lose nothing, do not add the method.
+
+## Procedure Builder
+
+Each procedure declares its schemas from the DTO, then auth, resource loading,
+access control, and the handler:
+
+1. `.input(schema)` -- Accepts a Zod schema; infers `TInput` so you don't need `this.procedure<Type>(...)`. No runtime validation by default; pass `true` as second arg to enable it.
+2. `.output(schema)` -- Accepts a Zod schema; constrains the handler return type so you don't need explicit return annotations. No runtime validation by default; pass `true` as second arg to enable it.
+3. `.requireAuth(scope?)` -- Enforces authentication. Scope can be `"user"` (default), `"organization" (recommended)`, `"team"`, or `"admin"`.
+4. `.loadResource(name, loader)` -- Loads a value and stores it in `state`; returns `NOT_FOUND` if falsy.
+5. `.use(name, step)` -- Runs an arbitrary step and stores the result in `state`.
+6. `.addContextFilter(scopes?)` -- Applies context-based query filtering (requires auth).
+7. `.addFilters(resolve)` -- Appends query filters to the current input (`({ input, ctx, state, ... }) => QueryFilter | QueryFilter[]`).
+8. `.access(config)` -- Permission check via grants. Arrays are soft-filtered to allowed rows (empty OK); single entities return `FORBIDDEN` when denied. Filtered arrays are written back to `entityStep` state.
+9. `.handle(handler)` -- Terminal method; runs the handler with `{ input, ctx, state, repository, service, logger }`.
+
+### Input / Output Typing
+
+Prefer `.input(schema)` with Zod schemas from the module's `.dto.ts`:
+
+```typescript
+// Preferred: schema-driven
+readonly create = this.procedure("create")
+  .input(postSchemas.input.create)
+  .output(postSchemas.output.single)
+  .requireAuth("organization")
+  .access({ action: "write" })
+  .handle(async ({ input, ctx }) => {
+    return this.repository.posts.create({
+      ...input,
+      userId: ctx.actor.userId,
+      memberId: ctx.actor.memberId,
+    });
+  });
+
+// Acceptable for simple primitives with no matching schema
+readonly getCount = this.procedure("getCount")
+  .requireAuth("organization")
+  .access({ action: "read" })
+  .handle(async ({ ctx }): ServerResultAsync<number> => {
+    return this.repository.posts.countByUser(ctx.actor.userId);
+  });
+```
+
+When no Zod schema exists (simple primitives, inline objects), you can still use the generic: `this.procedure<string>("name")`.
+
+## Procedure Patterns
+
+### Simple CRUD
+
+```typescript
+readonly list = this.procedure("list")
+  .input(postSchemas.input.list)
+  .output(postSchemas.output.list)
+  .requireAuth("organization")
+  .addContextFilter(["organization"])
+  .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
+  .access({
+    action: "read",
+    entityStep: "posts",
+  })
+  .handle(({ state }) => state.posts);
+
+readonly create = this.procedure("create")
+  .input(postSchemas.input.create)
+  .output(postSchemas.output.single)
+  .requireAuth("organization")
+  .access({ action: "write" })
+  .handle(async ({ input, ctx }) => {
+    return this.repository.posts.create({
+      ...input,
+      userId: ctx.actor.userId,
+      memberId: ctx.actor.memberId,
+    });
+  });
+```
+
+### With Resource Loading and Access Control (recommended)
+
+```typescript
+readonly update = this.procedure("update")
+  .input(postSchemas.input.update)
+  .output(postSchemas.output.single)
+  .requireAuth("organization")
+  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+  .access({
+    action: "write",
+    entityStep: "post",
+  })
+  .handle(async ({ input }) => {
+    return this.repository.posts.update(input);
+  });
+```
+
+Use grants with `"org"` (org admin/owner) or `"own"` (member) so `findById` cannot update cross-org rows. Do not use `"all"` for organization-scoped roles.
+
+### Org-scoped list with access soft-filter
+
+```typescript
+readonly list = this.procedure("list")
+  .input(postSchemas.input.list)
+  .output(postSchemas.output.list)
+  .requireAuth("organization")
+  .addContextFilter(["organization"])
+  .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
+  .access({
+    action: "read",
+    entityStep: "posts",
+  })
+  .handle(({ state }) => state.posts);
+```
+
+- Default list scoping: `addContextFilter(["organization"])`.
+- When grants are member-own only, prefer `addContextFilter(["member", "organization"])` so the query is already narrowed.
+- `.access` on an **array** soft-filters to allowed rows (may be `[]`); it does not 403 the whole list.
+- Filtered results are written back to `state[entityStep]` (here `state.posts`).
+
+### With Context Filter (Query-Based Lists)
+
+```typescript
+readonly list = this.procedure("list")
+  .output(postSchemas.output.list)
+  .requireAuth("organization")
+  .addContextFilter(["member", "organization"])
+  .access({ action: "read" })
+  .handle(({ input }) => {
+    return this.repository.posts.queryList(input, {
+      globalSearchColumns: ["title", "excerpt", "content"],
+    });
+  });
+```
+
+### Create with business logic
+
+```typescript
+readonly create = this.procedure("create")
+  .requireAuth("organization")
+  .input(postSchemas.input.create)
+  .output(postSchemas.output.single)
+  .access({ action: "write" })
+  .handle(async ({ input, ctx }) => {
+    const uniqueSlug = await this.repository.posts.resolveUniqueSlug({
+      candidate: slugify(input.slug ?? input.title),
+    });
+    if (uniqueSlug.isErr()) return err(uniqueSlug.error);
+
+    return this.repository.posts.create({
+      // Org-scoped assets: stamp memberId (+ organizationId). Personal resources: stamp userId.
+      memberId: ctx.actor.memberId,
+      organizationId: ctx.actor.organizationId,
+      title: input.title.trim(),
+      slug: uniqueSlug.value,
+      content: input.content.trim(),
+      status: "draft",
+    });
+  });
+```
+
+### Soft delete
+
+```typescript
+readonly softDelete = this.procedure("softDelete")
+  .input(postSchemas.input.delete)
+  .output(postSchemas.output.uuid)
+  .requireAuth("organization")
+  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+  .access({ action: "delete", entityStep: "post" })
+  .handle(async ({ input }) => {
+    const updated = await this.repository.posts.update({
+      id: input.id,
+      deletedAt: new Date(),
+    });
+    if (updated.isErr()) return err(updated.error);
+    return ok({ id: updated.value.id });
+  });
+```
+
+### Public (No Auth)
+
+```typescript
+readonly validateCode = this.procedure("validateCode")
+  .input(postSchemas.input.validate)
+  .output(postSchemas.output.status)
+  .handle(async ({ input }) => {
+    return this.repository.posts.validateCode(input);
+  });
+```
+
+## Permission and Grants
+
+- Keep all guarded action names aligned with grants (`read`, `write`, `delete`, `publish`, etc.).
+- Do not use undeclared action aliases (e.g., guard `"update"` when grants only define `"write"`).
+- Prefer `.access({ action, entityStep? })` over ad-hoc ownership checks in `.use`.
+- For org-scoped assets, stamp and authorize with `memberId` (`ctx.actor.memberId`). Keep `userId` for authentication and personal resources (billing, devices, OAuth). Prefer the column name `memberId` over aliases like `authorMemberId`.
+- Access modes: `"all"` (global), `"org"` (same organization), `"own"` (ownership), `"none"` (explicit deny). Prefer `"org"` for org owner/admin grants.
+
+## Access Control Modes
+
+- **`entityStep`** — references a value stored by `.loadResource()`/`.use()`;
+  the entity's `userId`, `memberId`, `organizationId`, and `teamId` are read automatically.
+  Arrays are soft-filtered; singles return `FORBIDDEN` when denied. Filtered arrays are written back to the step state.
+- **`entities`** — inline function returning `{ userId?, memberId?, organizationId?, teamId? }`
+  when the entity is not loaded into state.
+
+## Example Skeleton
+
+```typescript
+import { BasePermissionService } from "@m5kdev/backend/base/base.service";
+import { postSchemas } from "./posts.dto";
+import type { PostsRepository } from "./posts.repository";
+
+export class PostsService extends BasePermissionService<
+  { posts: PostsRepository },
+  Record<string, never>
+> {
+  readonly list = this.procedure("list")
+    .input(postSchemas.input.list)
+    .output(postSchemas.output.list)
+    .requireAuth("organization")
+    .addContextFilter(["organization"])
+    .loadResource("posts", ({ input }) => this.repository.posts.queryList(input))
+    .access({
+      action: "read",
+      entityStep: "posts",
+    })
+    .handle(({ state }) => state.posts);
+
+  readonly create = this.procedure("create")
+    .input(postSchemas.input.create)
+    .output(postSchemas.output.single)
+    .requireAuth("organization")
+    .access({ action: "write" })
+    .handle(async ({ input, ctx }) => {
+      return this.repository.posts.create({
+        ...input,
+        userId: ctx.actor.userId,
+        memberId: ctx.actor.memberId,
+      });
+    });
+
+  readonly update = this.procedure("update")
+    .input(postSchemas.input.update)
+    .output(postSchemas.output.single)
+    .requireAuth("organization")
+    .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+    .access({
+      action: "write",
+      entityStep: "post",
+    })
+    .handle(async ({ input }) => {
+      return this.repository.posts.update(input);
+    });
+
+  readonly delete = this.procedure("delete")
+    .input(postSchemas.input.delete)
+    .requireAuth("organization")
+    .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+    .access({
+      action: "delete",
+      entityStep: "post",
+    })
+    .handle(async ({ input }) => {
+      return this.repository.posts.deleteById(input.id);
+    });
+}
+```
+
+## Best Practices
+
+1. Keep procedures as `readonly` class properties.
+2. `.loadResource()` before `.access({ entityStep })` — it 404s on missing rows for free.
+3. Return `this.error("NOT_FOUND")` / `this.error("FORBIDDEN")` for expected failures; reserve 5xx codes for server faults (they report to Sentry).
+4. Keep pure helpers (slugify, excerpt) in `<module>.utils.ts`.
+5. Propagate `err(...)` from repository results rather than throwing.