@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-docs/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: dknet-docs
+description: Generate structured technical documentation and Mermaid architecture diagrams for completed features. Use this when documenting implemented features with README, architecture diagrams, and API references. Invoke as `/dknet-docs <Feature>` to scaffold it for a feature.
+metadata:
+  kind: workflow
+  arguments: "<Feature>"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+Usage: `/dknet-docs <Feature>`
+
+# Skill: Feature Documentation with Diagrams
+
+**Duration**: 30–60 minutes | **Difficulty**: Beginner | **Category**: Documentation & Knowledge Management
+
+---
+
+## Overview
+
+**When to use this skill**: After completing a feature (Domain Modeling → CRUD Operations → API Endpoints). Document it so any developer can understand, maintain, and extend the feature without digging through code.
+
+**What you'll create**: Five structured markdown documents under `docs/features/<feature-name>/`:
+
+| File | Purpose |
+|------|---------|
+| `README.md` | Overview, purpose, usage summary |
+| `architecture.md` | Vertical slice diagram, component responsibilities, data flow |
+| `api-reference.md` | All endpoints with request/response examples and curl commands |
+| `data-model.md` | Entity diagram, properties, constraints, relationships |
+| `events.md` | Domain events catalog with publishers and subscribers |
+
+**Diagram tool**: All diagrams use **Mermaid.js** — rendered natively in GitHub, VS Code Preview, and most wikis. No extra tools required.
+
+**Real examples already in this repo**: this skill is about documenting a *new* feature you just
+built, not about the two worked samples that ship with the template — but those samples
+(`ManualSample/PurchaseOrder` and `AutomatedSample/Product`) are the best current reference for what
+"good enough to hand to another developer" looks like in this codebase. Skim their code before
+writing your own docs — they show the level of detail and the "what does the developer give up"
+framing this repo expects, even though the samples themselves don't ship their own per-feature docs
+in the five-document structure below.
+
+---
+
+## Prerequisites: Do You Know This?
+
+- [ ] Feature is implemented (Domain Entity, CRUD handlers, endpoints)
+- [ ] Comfortable writing markdown
+- [ ] Can read C# class definitions and extract relevant info
+- [ ] Know what API endpoints were created (HTTP method, route, request/response)
+
+---
+
+## Inputs Checklist
+
+Collect this before you start:
+
+- [ ] **Feature name** (e.g., `PurchaseOrder`, `Product`, `Invoices`)
+- [ ] **Purpose**: What business problem does it solve? (1–2 sentences)
+- [ ] **Entity properties**: All fields with types and constraints
+- [ ] **Entity relationships**: Foreign keys and navigation properties
+- [ ] **API endpoints**: HTTP method, route, request/response shape
+- [ ] **Domain events**: Names, publishers, subscribers
+- [ ] **Business rules**: Validation, uniqueness, state transitions
+- [ ] **Status/State model**: Does the entity have status fields? What are the transitions?
+
+---
+
+## Step-by-Step Workflow
+
+### Step 1: Create the Feature Docs Folder
+
+**Convention**: All feature docs must live in `docs/features/<feature-name>/`.
+
+```bash
+mkdir -p docs/features/purchase-orders
+```
+
+**Naming convention**:
+- Folder name: `kebab-case` (e.g., `purchase-orders`, `order-management`)
+- File names: lowercase with hyphens (e.g., `api-reference.md`, `data-model.md`)
+
+---
+
+### Step 2: Write README.md (Overview)
+
+**What you're doing**: A self-contained landing page that answers: *what is this feature, why does it exist, and how do I use it?*
+
+**Target audience**: Any developer new to the feature (including your future self).
+
+Copy `templates/README-template.md` from this skill's folder and fill it in — What Is This?, Why Does It Exist?, Quick Start, Key Concepts, Feature Map, Related Documentation.
+
+Example Quick Start entry (from the `PurchaseOrder` sample):
+
+```http
+POST /v1/purchase-orders
+Content-Type: application/json
+Authorization: Bearer {token}
+X-Idempotency-Key: 6e6f4d3c-1b7e-4c7a-9f1d-8a2b5c6d7e01
+
+{
+  "customerName": "Acme Pte Ltd",
+  "amount": 1250.00
+}
+```
+
+---
+
+### Step 3: Write architecture.md (Diagrams + Data Flow)
+
+**What you're doing**: Show how the feature is structured across layers with a vertical slice diagram. Use Mermaid for all diagrams.
+
+**Five diagrams to include**:
+
+1. **Vertical Slice Overview** — All layers and their responsibilities
+2. **Request Sequence Diagram** — How a POST (create) flows through the system
+3. **Component Diagram** — Classes/files and their relationships
+4. **State Diagram** — Status transitions (if entity has status field)
+5. **Event Flow Diagram** — Domain events and consumers
+
+Copy `templates/architecture-template.md` from this skill's folder and fill it in — Vertical Slice Overview, Sequence Diagram, Component Diagram, Status State Machine, Event Flow, Layer Responsibilities. Document only the transitions actual handler code performs in the State Machine — don't document an enum member as reachable just because it exists.
+
+Example Vertical Slice Overview diagram (from the `PurchaseOrder` sample):
+
+```mermaid
+graph TD
+    Client["Client / Browser"]
+    subgraph API["Minimal.Api"]
+        EP["PurchaseOrderV1Endpoint.cs"]
+    end
+    subgraph AppServices["Minimal.AppServices"]
+        HDL["Command Handlers"]
+    end
+    subgraph Domains["Minimal.Domains"]
+        ENT["PurchaseOrder (AggregateRoot)"]
+    end
+    DB[("PostgreSQL")]
+    Client -->|HTTP| EP --> HDL --> ENT --> DB
+```
+
+---
+
+### Step 4: Write api-reference.md (Endpoint Reference)
+
+**What you're doing**: Full endpoint documentation with curl examples, request/response schemas, and error codes.
+
+Copy `templates/api-reference-template.md` from this skill's folder and fill it in — Endpoints Summary table, one section per endpoint (query params/request body, response, error table, curl example), Common Error Response Format. Note the pagination-defaults gotcha: a hand-written list query's `pageIndex`/`pageSize` defaults differ from the generated `MapGetList` route's contract (`pageNumber`/`pageSize` default 1/1000, configurable ceiling via `DKNet:ListQuery`, plus `fromDate`/`toDate` windowing) — document whichever contract this feature's route actually uses. Also document the standard error format: `result.Response()` (`DKNet.AspCore.Extensions.Responses`) converts a failed `FluentResults` result into `ProblemDetails` with messages under an `errors` array; a `NotFoundError` produces the same shape with `status: 404`.
+
+Example endpoint entry (from the `PurchaseOrder` sample):
+
+```markdown
+## POST /v1/purchase-orders
+
+Creates a new purchase order. **Requires** an idempotency key header.
+
+| Field | Type | Required | Rules |
+|-------|------|----------|-------|
+| `customerName` | string | ✓ | 1–200 characters |
+| `amount` | decimal | ✓ | Must be greater than 0 |
+
+**Response** `201 Created` — a `PurchaseOrderDto` with `status: "Placed"`.
+```
+
+---
+
+### Step 5: Write data-model.md (Entity Diagram)
+
+**What you're doing**: Document the entity schema, constraints, relationships, and EF Core mapping config.
+
+Copy `templates/data-model-template.md` from this skill's folder and fill it in — Entity Relationship Diagram, Properties table, EF Core Mapping Configuration (table/schema, indexes, enum storage, seed data), Validation Rules.
+
+Example ER diagram (from the `PurchaseOrder` sample):
+
+```mermaid
+erDiagram
+    PURCHASE_ORDER {
+        uniqueidentifier Id PK "Auto-generated GUID"
+        nvarchar(200) CustomerName "Not null, indexed"
+        decimal_18_2 Amount "Not null"
+        nvarchar Status "Draft / Placed / Cancelled"
+    }
+```
+
+---
+
+### Step 6: Write events.md (Domain Events Catalog)
+
+**What you're doing**: Catalog all domain events published and consumed by this feature so other teams know how to subscribe.
+
+Copy `templates/events-template.md` from this skill's folder and fill it in — Events Published (per event: publisher, payload, subscribers table, example handler usage), Events Consumed, Event Bus Configuration, Event Flow diagram.
+
+Example event entry (from the `PurchaseOrder` sample):
+
+```csharp
+public sealed record PurchaseOrderCreatedEvent(Guid Id, string CustomerName, decimal Amount);
+```
+
+| Subscriber | Bus | Action |
+|-----------|-----|--------|
+| `PurchaseOrderCreatedEventHandler` | In-Memory | Logs at Information level |
+
+---
+
+## Document Naming Conventions
+
+| Document | File Name | Description |
+|----------|-----------|-------------|
+| Overview + quick start | `README.md` | Always required |
+| Architecture + diagrams | `architecture.md` | Required when using vertical slices |
+| API endpoint reference | `api-reference.md` | Required for any REST-exposed feature |
+| Entity + data model | `data-model.md` | Required for any persisted entity |
+| Domain events | `events.md` | Required when events are published/consumed |
+| Configuration guide | `configuration.md` | Optional — for features with settings/flags |
+| ADR (decision records) | `decisions/adr-001-*.md` | Optional — when major tradeoffs were made |
+
+---
+
+## Mermaid Diagram Types Reference
+
+Use appropriate Mermaid diagram types for different aspects:
+
+| Diagram type | Mermaid keyword | When to use |
+|-------------|-----------------|-------------|
+| Component flow | `graph TD` / `graph LR` | Overview of layers, event flows |
+| Request sequence | `sequenceDiagram` | How a specific API call flows step-by-step |
+| Entity classes | `classDiagram` | Class relationships and properties |
+| Entity-Relation | `erDiagram` | Database table structure |
+| State machine | `stateDiagram-v2` | Status transitions |
+| Timeline | `timeline` | Feature evolution, release history |
+
+**All Mermaid diagrams are fenced code blocks**:
+
+````md
+```mermaid
+graph TD
+    A --> B
+```
+````
+
+They render automatically on GitHub, GitLab, VS Code (Markdown Preview), Docusaurus, and most modern wikis.
+
+---
+
+## Feature Docs Folder Structure
+
+```
+docs/
+└── features/
+    └── purchase-orders/          ← kebab-case folder name
+        ├── README.md             ← Overview (START HERE)
+        ├── architecture.md       ← Diagrams + vertical slice
+        ├── api-reference.md      ← Endpoints + examples + curl
+        ├── data-model.md         ← Entity diagram + constraints
+        ├── events.md             ← Domain events + subscribers
+        └── decisions/            ← Optional ADRs
+            └── adr-001-idempotency-key-strategy.md
+```
+
+---
+
+# Workflow: `/dknet-docs`
+
+The procedure an agent follows when invoked with arguments. The reference sections above are the rules it applies.
+
+You are producing authoritative feature documentation for a vertical slice that is already implemented and tested.
+
+### Required reading
+
+1. The reference sections above
+2. this skill's `templates/` folder` (README, architecture, data-model, events, api-reference templates).
+3. The two shipped sample slices (`ManualSample/PurchaseOrder`, `AutomatedSample/Product`) — document against the code, and use their existing feature docs (if the solution kept them) for shape and voice.
+
+### Steps
+
+1. Inspect the implemented slice to harvest facts: entity properties, mapper indexes, request/response DTOs, validator rules, endpoint routes, event names, test coverage.
+   Determine which flow the slice uses (a `[CrudCreate]` on the entity means the automated flow) and
+   document it explicitly — a reader cannot tell from the route table alone, and the two flows differ
+   in behavior a consumer will hit:
+   - whether the create route is idempotent (`X-Idempotency-Key`),
+   - whether validation is enforced (it is **not** on generated routes — say so plainly rather than
+     listing a `[Range]` as if it returns `400`),
+   - how the acting user is attributed (`[FromClaim]` vs `DataOwnerHook`).
+   For automated slices, read event names off the compiled assembly, not off a guess at the
+   composition rule.
+2. Render the four required artifacts under `docs/features/<feature>/` (or `docs/<feature>/` if the slice is template-internal):
+   - `README.md` (feature overview + quick links)
+   - `architecture.md` (Mermaid diagrams: layer flow, sequence for Create, ER snippet)
+   - `data-model.md`
+   - `api-reference.md`
+3. Cross-link from `docs/features/README.md` (or whichever index file lists features).
+4. Verify all referenced files exist and Mermaid blocks render (no stray fences).
+
+### Constraints
+
+- Do not invent fields, validators, events, or endpoints — only document what's in the code.
+- Use the templates in the skill folder verbatim where they fit; deviations need a one-line note.
+- No hand-wavey language ("flexible", "robust", "scalable") — describe what the code actually does.

package/skills/dknet-docs/checklist.md

@@ -0,0 +1,58 @@
+# Quick Validation Checklist: Feature Documentation
+
+## Folder Structure
+- [ ] Feature docs folder created at `docs/features/<feature-name>/` (kebab-case)
+- [ ] All 5 required documents are present
+
+## README.md (Overview)
+- [ ] Explains **what** the feature does (1-2 sentences)
+- [ ] Explains **why** it exists (business value, problem solved)
+- [ ] Contains quick-start code example (at minimum one HTTP example)
+- [ ] Lists all key concepts in a table
+- [ ] Contains a **Feature Map** table linking to source files across layers
+- [ ] Links to all other docs (architecture, api-reference, data-model, events)
+
+## architecture.md (Diagrams)
+- [ ] **Vertical Slice Diagram** (`graph TD`) shows all layers (Api → AppServices → Domains → Infra)
+- [ ] **Sequence Diagram** shows the full request flow for at least one write operation (e.g., Create)
+- [ ] **Component Diagram** (`classDiagram`) shows key classes and their relationships
+- [ ] **State Diagram** (`stateDiagram-v2`) present if entity has status/state (e.g. `PurchaseOrder`'s `Draft`/`Placed`/`Cancelled`)
+- [ ] **Event Flow Diagram** shows publishers and subscribers
+- [ ] All diagrams use Mermaid (render in GitHub natively)
+- [ ] Layer responsibilities table lists each layer's role in this specific feature
+
+## api-reference.md (Endpoint Reference)
+- [ ] Summary table lists ALL endpoints (Method / Path / Description / Auth)
+- [ ] Each endpoint has: description, request body or params, response body example (JSON)
+- [ ] Request field tables show: field name, type, required flag, validation rules
+- [ ] Each endpoint has at least one `curl` example that can be copy-pasted
+- [ ] Error response table lists all possible error status codes and reasons
+- [ ] Common `ProblemDetails` error format documented at end
+- [ ] Custom action endpoints beyond plain CRUD (e.g. `PurchaseOrder`'s `POST {id}/cancel`) documented
+- [ ] GET list endpoint documents all query parameters (pagination, sorting, filtering)
+
+## data-model.md (Data Model)
+- [ ] `erDiagram` (Mermaid ER diagram) shows all columns with types and constraints
+- [ ] Properties table lists every field with C# type, DB column name, and constraints
+- [ ] Unique indexes documented
+- [ ] EF Core mapping notes (table name, schema, global query filters)
+- [ ] Validation rules table (field → rule → enforcement mechanism)
+- [ ] Related entities shown if any foreign key relationships exist
+
+## events.md (Domain Events)
+- [ ] Each published event documented with: name, publisher, payload (record definition)
+- [ ] Payload property table (name, type, description)
+- [ ] Known subscribers table (handler class name, bus type, action description)
+- [ ] Code example showing how to subscribe to the event
+- [ ] "Events Consumed" section present (or explicitly states "none")
+- [ ] Event bus configuration documented (In-Memory vs Azure Service Bus conditions)
+- [ ] Mermaid event flow diagram showing publish and subscribe flow
+
+## Quality Standards
+- [ ] All file names are lowercase with hyphens (`api-reference.md`, not `ApiReference.md`)
+- [ ] Folder name uses kebab-case (`purchase-orders`, not `PurchaseOrders`)
+- [ ] All internal links work (relative links between docs)
+- [ ] No broken Mermaid diagrams (test by opening in VS Code Preview or GitHub)
+- [ ] JSON examples are valid (check with a formatter)
+- [ ] All source file paths in the Feature Map table are correct and files exist
+- [ ] No placeholder text left (e.g., `{todo}`, `replace this`, etc.)

package/skills/dknet-docs/templates/README-template.md

@@ -0,0 +1,68 @@
+# {FeatureName}
+
+> {One sentence: what this feature manages/does.}
+
+## What Is This?
+
+{2–4 sentences describing the feature. What entity does it manage? What lifecycle does it support?
+What key behaviors does it provide? Who are the consumers of this feature?}
+
+## Why Does It Exist?
+
+{The business problem this feature solves. List 2–4 bullet points explaining:
+- What it enables
+- What compliance or workflow it supports
+- How it relates to other features}
+
+## Quick Start
+
+### {Most common operation, e.g., Create a {Entity}}
+
+```http
+POST /api/v1/{feature-route}
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "field1": "value",
+  "field2": "value"
+}
+```
+
+### Get a {Entity}
+
+```http
+GET /api/v1/{feature-route}/{id}
+Authorization: Bearer {token}
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **{ConceptName}** | {Brief explanation of what it is and why it matters} |
+| **{ConceptName}** | {Brief explanation} |
+| **Status** | Lifecycle state: `{State1} → {State2} / {State3}` |
+| **Soft Delete** | Records are never hard-deleted; `IsDeleted = true` marks them inactive |
+
+## Feature Map
+
+> Source files for this feature across all layers.
+
+| Layer | Path |
+|-------|------|
+| Domain Entity | `ApiEndpoints/Minimal.Domains/Features/{EntityFolder}/Entities/{EntityName}.cs` |
+| EF Core Mapper | `ApiEndpoints/Minimal.Infra/Features/{EntityFolder}/Mappers/{EntityName}Mapper.cs` |
+| Create Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Create.cs` |
+| Update Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Update.cs` |
+| Delete Handler | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Actions/Delete.cs` |
+| Domain Events | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Events/` |
+| Query Specs | `ApiEndpoints/Minimal.AppServices/{FeatureFolder}/V1/Specs/` |
+| API Endpoints | `ApiEndpoints/Minimal.Api/ApiEndpoints/{EntityName}V1Endpoints.cs` |
+
+## Related Documentation
+
+- [Architecture](./architecture.md)
+- [API Reference](./api-reference.md)
+- [Data Model](./data-model.md)
+- [Domain Events](./events.md)

package/skills/dknet-docs/templates/api-reference-template.md

@@ -0,0 +1,275 @@
+# {FeatureName} — API Reference
+
+**Base Path**: `/api/v1/{feature-route}`
+**Auth**: Bearer token required on all endpoints
+**Content-Type**: `application/json`
+
+---
+
+## Endpoints Summary
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| `GET` | `/` | List {entities} (paginated) | ✓ |
+| `GET` | `/{id}` | Get {entity} by ID | ✓ |
+| `POST` | `/` | Create new {entity} | ✓ |
+| `PUT` | `/{id}` | Update {entity} | ✓ |
+| `DELETE` | `/{id}` | Soft-delete {entity} | ✓ |
+| `PATCH` | `/{id}/approve` | Approve pending {entity} | ✓ Admin |
+| `PATCH` | `/{id}/reject` | Reject pending {entity} | ✓ Admin |
+
+> Remove rows that don't apply. Add custom actions as needed.
+
+---
+
+## GET /api/v1/{feature-route}
+
+Returns a paginated list of {entities}.
+
+**Query Parameters**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pageNumber` | int | 1 | Page number (1-based) |
+| `pageSize` | int | 1000 | Items per page (max 1000, clamped not rejected) |
+| `search` | string | — | Filter by name or key fields |
+| `sortBy` | string | `CreatedAt` | Field to sort by |
+| `sortDirection` | string | `desc` | `asc` or `desc` |
+| `fromDate` | ISO-8601 | — | Inclusive lower bound on when a record was last active |
+| `toDate` | ISO-8601 | — | Inclusive upper bound on when a record was last active. Naming neither bound windows an audited listing to the last three months, not all history |
+
+> The paging values above are the built-in defaults of `DKNet.AspCore.Extensions`' `MapGetList`, and a
+> host can override them through `ListQueryOptions` (section `DKNet:ListQuery`). Check them against
+> what your project configures. The full contract is in the `dknet-queries-specs` skill.
+
+**Response** `200 OK`
+
+```json
+{
+  "items": [
+    {
+      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+      "field1": "value",
+      "field2": "value",
+      "status": "Pending",
+      "createdAt": "2025-01-15T10:30:00Z",
+      "updatedAt": "2025-01-20T14:00:00Z"
+    }
+  ],
+  "pageNumber": 1,
+  "pageSize": 10,
+  "totalCount": 100,
+  "totalPages": 10
+}
+```
+
+**curl Example**
+
+```bash
+curl -X GET "https://api.example.com/api/v1/{feature-route}?pageSize=10" \
+  -H "Authorization: Bearer {token}"
+```
+
+---
+
+## GET /api/v1/{feature-route}/{id}
+
+Returns a single {entity} by ID.
+
+**Route Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | `Guid` | The {entity} unique identifier |
+
+**Response** `200 OK`
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "field1": "value",
+  "field2": "value",
+  "status": "Pending",
+  "createdAt": "2025-01-15T10:30:00Z",
+  "updatedAt": "2025-01-20T14:00:00Z"
+}
+```
+
+**Error Responses**
+
+| Status | Reason |
+|--------|--------|
+| `404 Not Found` | No {entity} with this ID |
+
+---
+
+## POST /api/v1/{feature-route}
+
+Creates a new {entity}.
+
+**Request Body**
+
+```json
+{
+  "field1": "value",
+  "field2": "value"
+}
+```
+
+| Field | Type | Required | Rules |
+|-------|------|----------|-------|
+| `field1` | string | ✓ | {constraints, e.g., 2–150 characters} |
+| `field2` | string | ✓ | {constraints, e.g., valid email, unique} |
+| `field3` | string | — | {optional field rules} |
+
+**Response** `201 Created`
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "field1": "value",
+  "field2": "value",
+  "status": "Pending",
+  "createdAt": "2025-01-15T10:30:00Z",
+  "updatedAt": "2025-01-15T10:30:00Z"
+}
+```
+
+**Error Responses**
+
+| Status | Reason |
+|--------|--------|
+| `400 Bad Request` | Validation failure |
+| `409 Conflict` | Duplicate value in unique field |
+
+**curl Example**
+
+```bash
+curl -X POST "https://api.example.com/api/v1/{feature-route}" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{"field1":"value","field2":"value"}'
+```
+
+---
+
+## PUT /api/v1/{feature-route}/{id}
+
+Updates an existing {entity}. All fields are optional — only non-null fields are updated.
+
+**Request Body**
+
+```json
+{
+  "field1": "updated value"
+}
+```
+
+| Field | Type | Required | Rules |
+|-------|------|----------|-------|
+| `field1` | string | — | {constraints}; if null, current value preserved |
+| `field2` | string | — | {constraints}; if null, current value preserved |
+
+**Response** `200 OK` — Returns updated `{EntityName}Dto`.
+
+**Error Responses**
+
+| Status | Reason |
+|--------|--------|
+| `400 Bad Request` | All fields null (nothing to update) |
+| `404 Not Found` | {Entity} not found |
+
+---
+
+## DELETE /api/v1/{feature-route}/{id}
+
+Soft-deletes the {entity}. The record is preserved with `IsDeleted = true`.
+
+**Response** `204 No Content`
+
+**Error Responses**
+
+| Status | Reason |
+|--------|--------|
+| `404 Not Found` | {Entity} not found |
+
+---
+
+## PATCH /api/v1/{feature-route}/{id}/approve
+
+Approves a pending {entity}. Updates status to `Approved`.
+
+> Remove this section if there is no approval workflow.
+
+**Request Body**
+
+```json
+{
+  "reason": "Manually verified"
+}
+```
+
+| Field | Type | Required | Rules |
+|-------|------|----------|-------|
+| `reason` | string | — | Optional audit comment; max 500 chars |
+
+**Response** `200 OK` — Returns updated `{EntityName}Dto`.
+
+**Error Responses**
+
+| Status | Reason |
+|--------|--------|
+| `400 Bad Request` | {Entity} is not in Pending state |
+| `404 Not Found` | {Entity} not found |
+| `403 Forbidden` | User does not have Admin role |
+
+---
+
+## PATCH /api/v1/{feature-route}/{id}/reject
+
+Rejects a pending {entity}. Reason is **required** for audit trail.
+
+> Remove this section if there is no rejection workflow.
+
+**Request Body**
+
+```json
+{
+  "reason": "Identity documents not provided"
+}
+```
+
+| Field | Type | Required | Rules |
+|-------|------|----------|-------|
+| `reason` | string | ✓ | Required; 1–500 characters |
+
+**Response** `200 OK` — Returns updated `{EntityName}Dto`.
+
+---
+
+## Common Error Response Format
+
+All errors return `ProblemDetails`:
+
+```json
+{
+  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "One or more validation errors occurred.",
+  "errors": {
+    "field1": ["Field1 is required"],
+    "field2": ["Field2 format is invalid"]
+  }
+}
+```
+
+| Status | Meaning |
+|--------|---------|
+| `400` | Validation or business rule failure |
+| `401` | Missing or invalid Bearer token |
+| `403` | Insufficient permissions (role missing) |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate unique field) |
+| `429` | Rate limit exceeded |
+| `500` | Internal server error |