docs(crud): add implementation examples and complete docs task

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

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" },

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`.

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

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)