From 7b4b23fc4ffdd7e6be8af9da6b2026067acbd35e Mon Sep 17 00:00:00 2001
From: Citali <git@fellies.email>
Date: Wed, 11 Feb 2026 12:10:28 +0100
Subject: [PATCH] docs(crud): add implementation examples and complete docs
 task

---
 TODO.md                                   |  2 +-
 docs/.vitepress/config.mts                |  1 +
 docs/product-engineering/crud-baseline.md |  1 +
 docs/product-engineering/crud-examples.md | 69 +++++++++++++++++++++++
 docs/product-engineering/index.md         |  1 +
 5 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/product-engineering/crud-examples.md

diff --git a/TODO.md b/TODO.md
index e9f14f8..4aac56f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -74,7 +74,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] Docs tool baseline added (`docs/` via VitePress)
 - [x] [P1] RBAC and permission model documentation in docs site
 - [x] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
-- [~] [P1] CRUD base patterns documentation and examples
+- [x] [P1] CRUD base patterns documentation and examples
 - [ ] [P1] Environment and deployment runbook docs (dev/staging/production)
 - [ ] [P2] API and domain glossary pages
 - [ ] [P2] Architecture Decision Records (ADR) structure and first ADRs
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index c2f06f8..b9bf739 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -21,6 +21,7 @@ export default defineConfig({
           { text: "Architecture", link: "/architecture" },
           { text: "Better Auth Baseline", link: "/product-engineering/auth-baseline" },
           { text: "CRUD Baseline", link: "/product-engineering/crud-baseline" },
+          { text: "CRUD Examples", link: "/product-engineering/crud-examples" },
           { text: "i18n Baseline", link: "/product-engineering/i18n-baseline" },
           { text: "i18n Conventions", link: "/product-engineering/i18n-conventions" },
           { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" },
diff --git a/docs/product-engineering/crud-baseline.md b/docs/product-engineering/crud-baseline.md
index aff07ab..84f1a29 100644
--- a/docs/product-engineering/crud-baseline.md
+++ b/docs/product-engineering/crud-baseline.md
@@ -38,3 +38,4 @@ The admin dashboard currently includes a temporary posts CRUD sandbox to validat
 
 - This is the base layer for future entities (pages, navigation, media, users, commissions).
 - Audit hook persistence/transport is intentionally left for later implementation work.
+- Implementation examples are documented in `crud-examples.md`.
diff --git a/docs/product-engineering/crud-examples.md b/docs/product-engineering/crud-examples.md
new file mode 100644
index 0000000..69f9c12
--- /dev/null
+++ b/docs/product-engineering/crud-examples.md
@@ -0,0 +1,69 @@
+# CRUD Examples
+
+## Goal
+
+Provide concrete implementation patterns for new entities adopting `@cms/crud`.
+
+## Example: Service Factory Wiring
+
+```ts
+import { createCrudService } from "@cms/crud"
+import { createPageInputSchema, updatePageInputSchema } from "@cms/content"
+
+const pageCrudService = createCrudService({
+  resource: "page",
+  repository: pageRepository,
+  schemas: {
+    create: createPageInputSchema,
+    update: updatePageInputSchema,
+  },
+  auditHooks: pageAuditHooks,
+})
+```
+
+## Example: Repository Contract
+
+```ts
+const pageRepository = {
+  list: () => db.page.findMany({ orderBy: { updatedAt: "desc" } }),
+  findById: (id: string) => db.page.findUnique({ where: { id } }),
+  create: (input: CreatePageInput) => db.page.create({ data: input }),
+  update: (id: string, input: UpdatePageInput) =>
+    db.page.update({
+      where: { id },
+      data: input,
+    }),
+  delete: (id: string) => db.page.delete({ where: { id } }),
+}
+```
+
+## Example: Action Usage
+
+```ts
+export async function createPage(input: unknown, context?: CrudMutationContext) {
+  return pageCrudService.create(input, context)
+}
+
+export async function updatePage(id: string, input: unknown, context?: CrudMutationContext) {
+  return pageCrudService.update(id, input, context)
+}
+
+export async function deletePage(id: string, context?: CrudMutationContext) {
+  return pageCrudService.delete(id, context)
+}
+```
+
+## Testing Expectations
+
+- validation failure returns `CrudValidationError`
+- missing IDs return `CrudNotFoundError`
+- repository methods are called in expected order
+- audit hooks receive `actor`, `metadata`, `before`, `after`
+
+## Adoption Checklist
+
+1. Add entity schemas in `@cms/content`
+2. Add repository + service in `@cms/db`
+3. Add unit tests for contract + validation
+4. Wire route/action permission checks before mutations
+5. Add docs links and TODO updates
diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md
index 69ebda1..9251b54 100644
--- a/docs/product-engineering/index.md
+++ b/docs/product-engineering/index.md
@@ -9,6 +9,7 @@ This section covers platform and implementation documentation for engineers and
 - [Better Auth Baseline](/product-engineering/auth-baseline)
 - [RBAC And Permissions](/product-engineering/rbac-permission-model)
 - [i18n Conventions](/product-engineering/i18n-conventions)
+- [CRUD Examples](/product-engineering/crud-examples)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
 - [Workflow](/workflow)