test(admin): cover pages and navigation form components

TODO.md

@@ -187,7 +187,7 @@ This file is the single source of truth for roadmap and delivery progress.
 ### Testing
 
 - [x] [P1] Unit tests for content schemas and service logic
-- [~] [P1] Component tests for admin forms (pages/media/navigation)
+- [x] [P1] Component tests for admin forms (pages/media/navigation)
 - [x] [P1] Integration tests for owner invariant and hidden support-user protection
 - [x] [P1] Integration tests for registration allow/deny behavior
 - [ ] [P1] Integration tests for translated content CRUD and locale-specific validation
@@ -197,11 +197,11 @@ This file is the single source of truth for roadmap and delivery progress.
 
 ### Code Documentation And Handover
 
-- [ ] [P1] Create architecture map per package/app (`what exists`, `why`, `how to extend`) for `@cms/db`, `@cms/content`, `@cms/crud`, `@cms/ui`, `apps/admin`, `apps/web`
+- [x] [P1] Create architecture map per package/app (`what exists`, `why`, `how to extend`) for `@cms/db`, `@cms/content`, `@cms/crud`, `@cms/ui`, `apps/admin`, `apps/web`
-- [ ] [P1] Add module-level ownership docs for auth, media, pages/navigation, commissions, announcements/news flows
+- [x] [P1] Add module-level ownership docs for auth, media, pages/navigation, commissions, announcements/news flows
-- [ ] [P1] Document critical invariants (single owner rule, protected support user, registration policy gates, media storage key contract)
+- [x] [P1] Document critical invariants (single owner rule, protected support user, registration policy gates, media storage key contract)
-- [ ] [P1] Add “request lifecycle” docs for key flows (auth sign-in/up, media upload, page publish, commission status change)
+- [x] [P1] Add “request lifecycle” docs for key flows (auth sign-in/up, media upload, page publish, commission status change)
-- [ ] [P1] Add coding handover playbook: local setup, migration workflow, test strategy, branch/release process, common failure recovery
+- [x] [P1] Add coding handover playbook: local setup, migration workflow, test strategy, branch/release process, common failure recovery
 - [ ] [P2] Add code-level diagrams (Mermaid) for service boundaries and data relationships
 - [ ] [P2] Add route/action inventory for admin and public apps with linked source files
 
@@ -319,6 +319,8 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-12] Admin settings now manage public header banner (enabled/message/CTA), backed by `system_setting` and consumed by public layout rendering.
 - [2026-02-12] Added owner/support invariant integration tests for auth guards (`apps/admin/src/lib/auth/server.test.ts`), covering protected-user deletion blocking and one-owner repair/promotion rules.
 - [2026-02-12] Started admin form component tests with media upload behavior coverage (`apps/admin/src/components/media/media-upload-form.test.tsx`).
+- [2026-02-12] Added code handover documentation baseline: architecture map, critical invariants, request lifecycles, and onboarding playbook under `docs/product-engineering/`.
+- [2026-02-12] Completed admin form component coverage for pages/navigation/media using isolated form components and tests.
 
 ## How We Use This File
 

apps/admin/src/app/navigation/page.tsx

@@ -11,6 +11,8 @@ import { revalidatePath } from "next/cache"
 import { redirect } from "next/navigation"
 
 import { AdminShell } from "@/components/admin-shell"
+import { CreateMenuForm } from "@/components/navigation/create-menu-form"
+import { CreateNavigationItemForm } from "@/components/navigation/create-navigation-item-form"
 import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
@@ -206,123 +208,12 @@ export default async function NavigationManagementPage({
       <section className="grid gap-4 lg:grid-cols-2">
         <article className="rounded-xl border border-neutral-200 p-6">
           <h2 className="text-xl font-medium">Create Menu</h2>
-          <form action={createMenuAction} className="mt-4 space-y-3">
+          <CreateMenuForm action={createMenuAction} />
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Name</span>
-              <input
-                name="name"
-                required
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Slug</span>
-              <input
-                name="slug"
-                required
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Location</span>
-              <input
-                name="location"
-                defaultValue="primary"
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <label className="inline-flex items-center gap-2 text-sm text-neutral-700">
-              <input
-                name="isVisible"
-                type="checkbox"
-                value="true"
-                defaultChecked
-                className="size-4"
-              />
-              Visible
-            </label>
-            <Button type="submit">Create menu</Button>
-          </form>
         </article>
 
         <article className="rounded-xl border border-neutral-200 p-6">
           <h2 className="text-xl font-medium">Create Navigation Item</h2>
-          <form action={createItemAction} className="mt-4 space-y-3">
+          <CreateNavigationItemForm action={createItemAction} menus={menus} pages={pages} />
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Menu</span>
-              <select
-                name="menuId"
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              >
-                {menus.map((menu) => (
-                  <option key={menu.id} value={menu.id}>
-                    {menu.name} ({menu.location})
-                  </option>
-                ))}
-              </select>
-            </label>
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Label</span>
-              <input
-                name="label"
-                required
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <div className="grid gap-3 md:grid-cols-2">
-              <label className="space-y-1">
-                <span className="text-xs text-neutral-600">Custom href</span>
-                <input
-                  name="href"
-                  className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-                />
-              </label>
-              <label className="space-y-1">
-                <span className="text-xs text-neutral-600">Linked page</span>
-                <select
-                  name="pageId"
-                  className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-                >
-                  <option value="">(none)</option>
-                  {pages.map((page) => (
-                    <option key={page.id} value={page.id}>
-                      {page.title} (/{page.slug})
-                    </option>
-                  ))}
-                </select>
-              </label>
-            </div>
-            <div className="grid gap-3 md:grid-cols-2">
-              <label className="space-y-1">
-                <span className="text-xs text-neutral-600">Parent item id</span>
-                <input
-                  name="parentId"
-                  className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-                />
-              </label>
-              <label className="space-y-1">
-                <span className="text-xs text-neutral-600">Sort order</span>
-                <input
-                  name="sortOrder"
-                  defaultValue="0"
-                  type="number"
-                  min={0}
-                  className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-                />
-              </label>
-            </div>
-            <label className="inline-flex items-center gap-2 text-sm text-neutral-700">
-              <input
-                name="isVisible"
-                type="checkbox"
-                value="true"
-                defaultChecked
-                className="size-4"
-              />
-              Visible
-            </label>
-            <Button type="submit">Create item</Button>
-          </form>
         </article>
       </section>
 

apps/admin/src/app/pages/page.tsx

@@ -1,10 +1,10 @@
 import { createPage, listPages } from "@cms/db"
-import { Button } from "@cms/ui/button"
 import { revalidatePath } from "next/cache"
 import Link from "next/link"
 import { redirect } from "next/navigation"
 
 import { AdminShell } from "@/components/admin-shell"
+import { CreatePageForm } from "@/components/pages/create-page-form"
 import { requirePermissionForRoute } from "@/lib/route-guards"
 
 export const dynamic = "force-dynamic"
@@ -110,75 +110,7 @@ export default async function PagesManagementPage({
 
       <section className="rounded-xl border border-neutral-200 p-6">
         <h2 className="text-xl font-medium">Create Page</h2>
-        <form action={createPageAction} className="mt-4 space-y-3">
+        <CreatePageForm action={createPageAction} />
-          <div className="grid gap-3 md:grid-cols-3">
-            <label className="space-y-1 md:col-span-2">
-              <span className="text-xs text-neutral-600">Title</span>
-              <input
-                name="title"
-                required
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">Status</span>
-              <select
-                name="status"
-                defaultValue="draft"
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              >
-                <option value="draft">draft</option>
-                <option value="published">published</option>
-              </select>
-            </label>
-          </div>
-
-          <label className="space-y-1">
-            <span className="text-xs text-neutral-600">Slug</span>
-            <input
-              name="slug"
-              required
-              className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-            />
-          </label>
-
-          <label className="space-y-1">
-            <span className="text-xs text-neutral-600">Summary</span>
-            <input
-              name="summary"
-              className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-            />
-          </label>
-
-          <label className="space-y-1">
-            <span className="text-xs text-neutral-600">Content</span>
-            <textarea
-              name="content"
-              rows={6}
-              required
-              className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-            />
-          </label>
-
-          <div className="grid gap-3 md:grid-cols-2">
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">SEO title</span>
-              <input
-                name="seoTitle"
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-            <label className="space-y-1">
-              <span className="text-xs text-neutral-600">SEO description</span>
-              <input
-                name="seoDescription"
-                className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
-              />
-            </label>
-          </div>
-
-          <Button type="submit">Create page</Button>
-        </form>
       </section>
 
       <section className="rounded-xl border border-neutral-200 p-6">

apps/admin/src/components/navigation/create-menu-form.test.tsx

@@ -0,0 +1,20 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+
+import { CreateMenuForm } from "./create-menu-form"
+
+describe("CreateMenuForm", () => {
+  it("renders defaults for location and visibility", () => {
+    render(<CreateMenuForm action={vi.fn()} />)
+
+    const location = screen.getByLabelText("Location") as HTMLInputElement
+    expect(location.value).toBe("primary")
+
+    const visible = screen.getByLabelText("Visible") as HTMLInputElement
+    expect(visible.checked).toBe(true)
+
+    expect(screen.getByRole("button", { name: "Create menu" })).not.toBeNull()
+  })
+})

apps/admin/src/components/navigation/create-menu-form.tsx

@@ -0,0 +1,41 @@
+import { Button } from "@cms/ui/button"
+
+type CreateMenuFormProps = {
+  action: (formData: FormData) => void | Promise<void>
+}
+
+export function CreateMenuForm({ action }: CreateMenuFormProps) {
+  return (
+    <form action={action} className="mt-4 space-y-3">
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Name</span>
+        <input
+          name="name"
+          required
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Slug</span>
+        <input
+          name="slug"
+          required
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Location</span>
+        <input
+          name="location"
+          defaultValue="primary"
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+      <label className="inline-flex items-center gap-2 text-sm text-neutral-700">
+        <input name="isVisible" type="checkbox" value="true" defaultChecked className="size-4" />
+        Visible
+      </label>
+      <Button type="submit">Create menu</Button>
+    </form>
+  )
+}

apps/admin/src/components/navigation/create-navigation-item-form.test.tsx

@@ -0,0 +1,32 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+
+import { CreateNavigationItemForm } from "./create-navigation-item-form"
+
+describe("CreateNavigationItemForm", () => {
+  it("renders menu/page options and defaults", () => {
+    render(
+      <CreateNavigationItemForm
+        action={vi.fn()}
+        menus={[{ id: "menu-1", name: "Primary", location: "header" }]}
+        pages={[{ id: "page-1", title: "Home", slug: "home" }]}
+      />,
+    )
+
+    const menu = screen.getByLabelText("Menu") as HTMLSelectElement
+    expect(menu.options.length).toBe(1)
+    expect(menu.value).toBe("menu-1")
+
+    const page = screen.getByLabelText("Linked page") as HTMLSelectElement
+    expect(page.options.length).toBe(2)
+    expect(page.options[0]?.value).toBe("")
+
+    const sortOrder = screen.getByLabelText("Sort order") as HTMLInputElement
+    expect(sortOrder.value).toBe("0")
+
+    const visible = screen.getByLabelText("Visible") as HTMLInputElement
+    expect(visible.checked).toBe(true)
+  })
+})

apps/admin/src/components/navigation/create-navigation-item-form.tsx

@@ -0,0 +1,94 @@
+import { Button } from "@cms/ui/button"
+
+type MenuOption = {
+  id: string
+  name: string
+  location: string
+}
+
+type PageOption = {
+  id: string
+  title: string
+  slug: string
+}
+
+type CreateNavigationItemFormProps = {
+  action: (formData: FormData) => void | Promise<void>
+  menus: MenuOption[]
+  pages: PageOption[]
+}
+
+export function CreateNavigationItemForm({ action, menus, pages }: CreateNavigationItemFormProps) {
+  return (
+    <form action={action} className="mt-4 space-y-3">
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Menu</span>
+        <select
+          name="menuId"
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        >
+          {menus.map((menu) => (
+            <option key={menu.id} value={menu.id}>
+              {menu.name} ({menu.location})
+            </option>
+          ))}
+        </select>
+      </label>
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Label</span>
+        <input
+          name="label"
+          required
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+      <div className="grid gap-3 md:grid-cols-2">
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">Custom href</span>
+          <input
+            name="href"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">Linked page</span>
+          <select
+            name="pageId"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          >
+            <option value="">(none)</option>
+            {pages.map((page) => (
+              <option key={page.id} value={page.id}>
+                {page.title} (/{page.slug})
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+      <div className="grid gap-3 md:grid-cols-2">
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">Parent item id</span>
+          <input
+            name="parentId"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">Sort order</span>
+          <input
+            name="sortOrder"
+            defaultValue="0"
+            type="number"
+            min={0}
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+      </div>
+      <label className="inline-flex items-center gap-2 text-sm text-neutral-700">
+        <input name="isVisible" type="checkbox" value="true" defaultChecked className="size-4" />
+        Visible
+      </label>
+      <Button type="submit">Create item</Button>
+    </form>
+  )
+}

apps/admin/src/components/pages/create-page-form.test.tsx

@@ -0,0 +1,21 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+
+import { CreatePageForm } from "./create-page-form"
+
+describe("CreatePageForm", () => {
+  it("renders required fields and draft default status", () => {
+    render(<CreatePageForm action={vi.fn()} />)
+
+    expect((screen.getByLabelText("Title") as HTMLInputElement).name).toBe("title")
+    expect((screen.getByLabelText("Slug") as HTMLInputElement).name).toBe("slug")
+    expect((screen.getByLabelText("Content") as HTMLTextAreaElement).name).toBe("content")
+
+    const status = screen.getByLabelText("Status") as HTMLSelectElement
+    expect(status.value).toBe("draft")
+
+    expect(screen.getByRole("button", { name: "Create page" })).not.toBeNull()
+  })
+})

apps/admin/src/components/pages/create-page-form.tsx

@@ -0,0 +1,79 @@
+import { Button } from "@cms/ui/button"
+
+type CreatePageFormProps = {
+  action: (formData: FormData) => void | Promise<void>
+}
+
+export function CreatePageForm({ action }: CreatePageFormProps) {
+  return (
+    <form action={action} className="mt-4 space-y-3">
+      <div className="grid gap-3 md:grid-cols-3">
+        <label className="space-y-1 md:col-span-2">
+          <span className="text-xs text-neutral-600">Title</span>
+          <input
+            name="title"
+            required
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">Status</span>
+          <select
+            name="status"
+            defaultValue="draft"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          >
+            <option value="draft">draft</option>
+            <option value="published">published</option>
+          </select>
+        </label>
+      </div>
+
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Slug</span>
+        <input
+          name="slug"
+          required
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Summary</span>
+        <input
+          name="summary"
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+
+      <label className="space-y-1">
+        <span className="text-xs text-neutral-600">Content</span>
+        <textarea
+          name="content"
+          rows={6}
+          required
+          className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+        />
+      </label>
+
+      <div className="grid gap-3 md:grid-cols-2">
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">SEO title</span>
+          <input
+            name="seoTitle"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+        <label className="space-y-1">
+          <span className="text-xs text-neutral-600">SEO description</span>
+          <input
+            name="seoDescription"
+            className="w-full rounded border border-neutral-300 px-3 py-2 text-sm"
+          />
+        </label>
+      </div>
+
+      <Button type="submit">Create page</Button>
+    </form>
+  )
+}

docs/.vitepress/config.mts

@@ -25,6 +25,10 @@ export default defineConfig({
           { 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" },
+          { text: "Code Architecture Map", link: "/product-engineering/code-architecture-map" },
+          { text: "Critical Invariants", link: "/product-engineering/critical-invariants" },
+          { text: "Request Lifecycle Flows", link: "/product-engineering/request-lifecycle-flows" },
+          { text: "Code Handover Playbook", link: "/product-engineering/code-handover-playbook" },
           { text: "Domain Glossary", link: "/product-engineering/domain-glossary" },
           { text: "Environment Runbook", link: "/product-engineering/environment-runbook" },
           { text: "Delivery Pipeline", link: "/product-engineering/delivery-pipeline" },

docs/product-engineering/code-architecture-map.md

@@ -0,0 +1,53 @@
+# Code Architecture Map
+
+This page is the fast handover map for engineers taking over the codebase.
+
+## Repository Structure
+
+- `apps/admin`:
+  Next.js admin panel. Owns auth UI, CMS management screens, and protected workflows.
+- `apps/web`:
+  Next.js public site. Renders CMS-managed content and public-facing routes.
+- `packages/db`:
+  Prisma schema, generated client usage, and data access services.
+- `packages/content`:
+  Domain-level Zod schemas and shared contracts.
+- `packages/crud`:
+  Shared CRUD service pattern (validation, not-found behavior, audit hook contracts).
+- `packages/ui`:
+  Shared UI primitives used by admin/public apps.
+- `packages/i18n`:
+  Shared locale helpers.
+
+## Runtime Boundaries
+
+- Admin app:
+  writes content and settings, enforces RBAC, runs Better Auth route handlers.
+- Public app:
+  reads published content and settings; no public auth coupling.
+- DB package:
+  only data access and business-persistence rules.
+- Content package:
+  only validation and domain typing; no DB or framework runtime coupling.
+
+## Core Feature Modules
+
+- Auth and user guards:
+  `apps/admin/src/lib/auth/server.ts`, `apps/admin/src/app/api/auth/[...all]/route.ts`
+- Access and route permissions:
+  `apps/admin/src/lib/access.ts`, `apps/admin/src/lib/route-guards.ts`
+- Media domain + storage:
+  `packages/db/src/media-foundation.ts`, `apps/admin/src/lib/media/storage.ts`
+- Pages and navigation:
+  `packages/db/src/pages-navigation.ts`, `apps/admin/src/app/pages/*`, `apps/admin/src/app/navigation/*`
+- Commissions and customers:
+  `packages/db/src/commissions.ts`, `apps/admin/src/app/commissions/page.tsx`
+- Announcements and news:
+  `packages/db/src/announcements.ts`, `apps/admin/src/app/announcements/page.tsx`, `apps/admin/src/app/news/page.tsx`
+
+## Extension Rules
+
+- Add/adjust schema first in `packages/content`.
+- Implement persistence in `packages/db`.
+- Wire usage in app route/actions after schema/service are in place.
+- Add tests at service and app-boundary levels before marking TODO items done.

docs/product-engineering/code-handover-playbook.md

@@ -0,0 +1,62 @@
+# Code Handover Playbook
+
+This is the minimum runbook for a new engineer to continue delivery safely.
+
+## Local Setup
+
+1. Install Bun matching repo policy.
+2. Copy `.env.example` to `.env` and fill required values.
+3. Generate Prisma client:
+   `bun run db:generate`
+4. Apply migrations:
+   `bun run db:migrate:deploy` (or local named migration flow)
+5. Seed data:
+   `bun run db:seed`
+6. Start apps:
+   `bun run dev`
+
+## Daily Development Loop
+
+1. Create branch by task type:
+   `todo/*`, `refactor/*`, `code/*`.
+2. Implement smallest vertical slice for one TODO item.
+3. Run quality gates:
+   `bun run check`
+   `bun run typecheck`
+   `bun run test`
+4. Update `TODO.md` status and discovery log.
+5. Commit with Conventional Commit message and GPG signing.
+
+## Database Workflow
+
+- Schema source is:
+  `packages/db/prisma/schema.prisma`
+- Use named dev migrations for schema changes.
+- Avoid manual SQL unless migration tooling is blocked.
+- Always regenerate client after schema change.
+
+## Testing Strategy
+
+- Unit/service tests:
+  `packages/*` and logic helpers.
+- App-boundary integration tests:
+  auth flow and route-level behavior.
+- E2E tests:
+  full admin/public happy paths through Playwright.
+
+## Common Failure Recovery
+
+- `DATABASE_URL not set`:
+  ensure root `.env` is loaded for Bun/Prisma scripts.
+- Prisma client import errors:
+  run `bun run db:generate`.
+- Migration drift:
+  run deploy/reset flow in dev and reseed.
+- Playwright host deps missing:
+  install browser dependencies on host before running e2e.
+
+## Ownership Expectations
+
+- Keep invariants explicit and tested before changing auth/media pipelines.
+- Treat `TODO.md` as delivery source of truth.
+- If changing branch/release workflow, update docs in same branch.

docs/product-engineering/critical-invariants.md

@@ -0,0 +1,57 @@
+# Critical Invariants
+
+These rules must stay true across refactors and feature work.
+
+## Auth and User Invariants
+
+- Exactly one owner user must exist.
+- The canonical owner must remain protected and not banned.
+- Support user is system-owned and protected.
+- Protected users cannot be deleted through auth endpoints.
+- First owner bootstrap closes open owner-registration window.
+
+Primary implementation:
+- `apps/admin/src/lib/auth/server.ts`
+- `apps/admin/src/app/api/auth/[...all]/route.ts`
+
+Primary tests:
+- `apps/admin/src/lib/auth/server.test.ts`
+- `apps/admin/src/app/register/page.test.tsx`
+- `apps/admin/src/app/welcome/page.test.tsx`
+- `apps/admin/src/app/login/page.test.tsx`
+
+## Registration Policy Invariants
+
+- If no owner exists:
+  `welcome` flow is open for first owner bootstrap.
+- If owner exists:
+  self-registration depends on persisted policy in `system_setting`.
+- Register route must never silently create users when policy is disabled.
+
+Primary implementation:
+- `packages/db/src/settings.ts`
+- `apps/admin/src/app/settings/page.tsx`
+- `apps/admin/src/app/register/page.tsx`
+
+## Media Storage Contract
+
+- Storage provider is selected by `CMS_MEDIA_STORAGE_PROVIDER`.
+- S3 is primary; local is explicit fallback.
+- Each media asset stores a stable `storageKey`.
+- Deleting a media asset must also attempt storage object deletion.
+
+Primary implementation:
+- `apps/admin/src/lib/media/storage.ts`
+- `apps/admin/src/lib/media/storage-key.ts`
+- `apps/admin/src/app/media/[id]/page.tsx`
+
+## Public Rendering Contract
+
+- Public pages must render only published CMS pages.
+- Public navigation must be built from managed menu items.
+- Header banner and announcements must be optional and fail-safe.
+
+Primary implementation:
+- `apps/web/src/app/[locale]/layout.tsx`
+- `apps/web/src/app/[locale]/page.tsx`
+- `apps/web/src/app/[locale]/[slug]/page.tsx`

docs/product-engineering/index.md

@@ -11,6 +11,10 @@ This section covers platform and implementation documentation for engineers and
 - [i18n Conventions](/product-engineering/i18n-conventions)
 - [CRUD Examples](/product-engineering/crud-examples)
 - [Package Catalog And Decision Notes](/product-engineering/package-catalog)
+- [Code Architecture Map](/product-engineering/code-architecture-map)
+- [Critical Invariants](/product-engineering/critical-invariants)
+- [Request Lifecycle Flows](/product-engineering/request-lifecycle-flows)
+- [Code Handover Playbook](/product-engineering/code-handover-playbook)
 - [User Personas And Use-Case Topics](/product-engineering/user-personas-and-use-cases)
 - [CMS Feature Topics (Domain-Centric)](/product-engineering/cms-feature-topics)
 - [Domain Glossary](/product-engineering/domain-glossary)

docs/product-engineering/request-lifecycle-flows.md

@@ -0,0 +1,61 @@
+# Request Lifecycle Flows
+
+## 1. Auth Sign-In (Admin)
+
+1. Browser posts to `/api/auth/sign-in/email`.
+2. Route resolves `identifier` (email or username) to canonical email.
+3. Better Auth credential sign-in executes.
+4. Session cookie is set and user is redirected.
+
+Key files:
+- `apps/admin/src/app/login/login-form.tsx`
+- `apps/admin/src/app/api/auth/[...all]/route.ts`
+- `apps/admin/src/lib/auth/server.ts`
+
+## 2. Initial Owner Registration
+
+1. If no owner exists, `/welcome` renders owner sign-up mode.
+2. Sign-up request goes through auth route handler.
+3. New user is promoted to owner in transactional guard.
+4. Owner invariant is re-validated to enforce single owner.
+
+Key files:
+- `apps/admin/src/app/welcome/page.tsx`
+- `apps/admin/src/app/api/auth/[...all]/route.ts`
+- `apps/admin/src/lib/auth/server.ts`
+
+## 3. Media Upload
+
+1. Admin form posts multipart data to `/api/media/upload`.
+2. Metadata is validated and file is stored through selected provider.
+3. Media asset record is persisted with storage metadata.
+4. UI redirects back to media list with flash status query.
+
+Key files:
+- `apps/admin/src/components/media/media-upload-form.tsx`
+- `apps/admin/src/app/api/media/upload/route.ts`
+- `apps/admin/src/lib/media/storage.ts`
+- `packages/db/src/media-foundation.ts`
+
+## 4. Page Publish
+
+1. Admin submit on `/pages` calls server action.
+2. Page schema validates payload and persists.
+3. `published` status sets publication fields.
+4. Public app resolves slug and renders page if published.
+
+Key files:
+- `apps/admin/src/app/pages/page.tsx`
+- `packages/db/src/pages-navigation.ts`
+- `apps/web/src/app/[locale]/[slug]/page.tsx`
+
+## 5. Commission Status Transition
+
+1. Admin updates status from commission card form.
+2. Server action validates transition payload.
+3. DB update persists new status.
+4. Kanban view re-renders with updated column placement.
+
+Key files:
+- `apps/admin/src/app/commissions/page.tsx`
+- `packages/db/src/commissions.ts`