docs(versioning): define release policy and close MVP0 pipeline tasks

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+- TODO item reference (exact text): `...`
+- Scope (single primary TODO item): `...`
+
+## Checklist
+
+- [ ] Linked TODO item is in `TODO.md`
+- [ ] Branch name follows `todo/*`, `refactor/*`, or `code/*`
+- [ ] `bun run check`
+- [ ] `bun run typecheck`
+- [ ] `bun run test`
+- [ ] E2E validation plan included (`bun run test:e2e` or reason if deferred)
+
+## Notes
+
+- Risks / migrations / rollout notes:

.gitea/scripts/check-branch-name.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+set -eu
+
+branch="${1:-}"
+
+if [ -z "$branch" ]; then
+  echo "Missing branch name."
+  exit 1
+fi
+
+case "$branch" in
+  dev|staging|main)
+    echo "Long-lived branch detected: $branch"
+    exit 0
+    ;;
+esac
+
+if printf "%s" "$branch" | grep -Eq '^(todo|refactor|code)\/[a-z0-9]+([._-][a-z0-9]+)*$'; then
+  echo "Branch naming valid: $branch"
+  exit 0
+fi
+
+echo "Invalid branch name: $branch"
+echo "Expected: todo/<slug> | refactor/<slug> | code/<slug>"
+exit 1

.gitea/scripts/check-pr-todo-reference.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+set -eu
+
+body="${1:-}"
+
+if [ -z "$body" ]; then
+  echo "PR body is empty."
+  exit 1
+fi
+
+if printf "%s" "$body" | grep -Eq 'TODO|todo|\[P[1-3]\]'; then
+  echo "PR body includes TODO reference."
+  exit 0
+fi
+
+echo "PR body must reference the related TODO item."
+exit 1

.gitea/scripts/configure-branch-protection.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ "${#}" -ne 4 ]; then
+  echo "Usage: $0 <base-url> <owner> <repo> <token>"
+  exit 1
+fi
+
+base_url="$1"
+owner="$2"
+repo="$3"
+token="$4"
+
+protect_branch() {
+  branch="$1"
+
+  curl -sS -X POST \
+    "${base_url}/api/v1/repos/${owner}/${repo}/branch_protections" \
+    -H "Authorization: token ${token}" \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"branch_name\": \"${branch}\",
+      \"enable_push\": false,
+      \"enable_push_whitelist\": false,
+      \"enable_merge_whitelist\": false,
+      \"enable_status_check\": true,
+      \"status_check_contexts\": [\"Governance Checks\", \"Lint Typecheck Unit E2E\"]
+    }" >/dev/null
+}
+
+protect_branch "main"
+protect_branch "staging"
+
+echo "Branch protection applied for main and staging."

.gitea/scripts/validate-tag-version.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+set -eu
+
+tag="${1:-}"
+
+if [ -z "$tag" ]; then
+  echo "Missing tag ref name (expected vX.Y.Z)."
+  exit 1
+fi
+
+version="$(node -p "require('./package.json').version")"
+
+if [ "$tag" != "v$version" ]; then
+  echo "Tag/version mismatch: tag=$tag package.json=$version"
+  exit 1
+fi
+
+echo "Tag matches package.json version: $tag"

.gitea/workflows/ci.yml

@@ -25,8 +25,38 @@ env:
   CMS_SUPPORT_LOGIN_KEY: "support-access"
 
 jobs:
+  governance:
+    name: Governance Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate branch naming
+        run: |
+          branch="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
+          sh .gitea/scripts/check-branch-name.sh "$branch"
+
+      - name: Validate PR TODO reference
+        if: github.event_name == 'pull_request'
+        run: |
+          body='${{ github.event.pull_request.body }}'
+          sh .gitea/scripts/check-pr-todo-reference.sh "$body"
+
+      - name: Commit schema check (latest commit)
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Install dependencies for commitlint
+        run: bun install --frozen-lockfile
+
+      - name: Commitlint
+        run: bun run commitlint
+
   quality:
     name: Lint Typecheck Unit E2E
+    needs: governance
     runs-on: ubuntu-latest
     services:
       postgres:

.gitea/workflows/deploy.yml

@@ -0,0 +1,54 @@
+name: CMS Deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: "Target environment"
+        required: true
+        type: choice
+        options:
+          - staging
+          - production
+      image_tag:
+        description: "Image tag to deploy (e.g. v0.1.0)"
+        required: true
+      rollback_tag:
+        description: "Optional rollback tag"
+        required: false
+
+jobs:
+  deploy:
+    name: Deploy Compose Stack
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve deployment target
+        id: target
+        run: |
+          if [ "${{ github.event.inputs.environment }}" = "staging" ]; then
+            echo "host=${{ secrets.CMS_STAGING_HOST }}" >> "$GITHUB_OUTPUT"
+            echo "user=${{ secrets.CMS_STAGING_USER }}" >> "$GITHUB_OUTPUT"
+            echo "compose=docker-compose.staging.yml" >> "$GITHUB_OUTPUT"
+          else
+            echo "host=${{ secrets.CMS_PRODUCTION_HOST }}" >> "$GITHUB_OUTPUT"
+            echo "user=${{ secrets.CMS_PRODUCTION_USER }}" >> "$GITHUB_OUTPUT"
+            echo "compose=docker-compose.production.yml" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.CMS_DEPLOY_KEY }}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -H "${{ steps.target.outputs.host }}" >> ~/.ssh/known_hosts
+
+      - name: Deploy image tag
+        run: |
+          ssh "${{ steps.target.outputs.user }}@${{ steps.target.outputs.host }}" \
+            "cd ${{ secrets.CMS_REMOTE_DEPLOY_PATH }} && CMS_IMAGE_TAG=${{ github.event.inputs.image_tag }} docker compose -f ${{ steps.target.outputs.compose }} up -d"
+
+      - name: Optional rollback
+        if: github.event.inputs.rollback_tag != ''
+        run: |
+          ssh "${{ steps.target.outputs.user }}@${{ steps.target.outputs.host }}" \
+            "cd ${{ secrets.CMS_REMOTE_DEPLOY_PATH }} && CMS_IMAGE_TAG=${{ github.event.inputs.rollback_tag }} docker compose -f ${{ steps.target.outputs.compose }} up -d"

.gitea/workflows/release.yml

@@ -0,0 +1,82 @@
+name: CMS Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: "Release tag in vX.Y.Z format"
+        required: true
+      rollback_image_tag:
+        description: "Optional rollback image tag"
+        required: false
+
+env:
+  BUN_VERSION: "1.3.5"
+  REGISTRY: ${{ secrets.CMS_IMAGE_REGISTRY }}
+  IMAGE_NAMESPACE: ${{ secrets.CMS_IMAGE_NAMESPACE }}
+
+jobs:
+  release:
+    name: Build Push Changelog
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Resolve release tag
+        id: tag
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            echo "value=${{ github.event.inputs.release_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "value=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Validate tag against package version
+        run: sh .gitea/scripts/validate-tag-version.sh "${{ steps.tag.outputs.value }}"
+
+      - name: Generate changelog
+        run: bun run changelog:release
+
+      - name: Login to image registry
+        run: |
+          echo "${{ secrets.CMS_IMAGE_REGISTRY_PASSWORD }}" | docker login "${{ env.REGISTRY }}" -u "${{ secrets.CMS_IMAGE_REGISTRY_USER }}" --password-stdin
+
+      - name: Build and push web image
+        run: |
+          image="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/cms-web:${{ steps.tag.outputs.value }}"
+          docker build -f apps/web/Dockerfile -t "$image" .
+          docker push "$image"
+
+      - name: Build and push admin image
+        run: |
+          image="${{ env.REGISTRY }}/${{ env.IMAGE_NAMESPACE }}/cms-admin:${{ steps.tag.outputs.value }}"
+          docker build -f apps/admin/Dockerfile -t "$image" .
+          docker push "$image"
+
+      - name: Release notes placeholder
+        run: |
+          echo "Release tag: ${{ steps.tag.outputs.value }}"
+          echo "TODO: publish CHANGELOG.md content to release notes in Gitea."
+
+  rollback:
+    name: Rollback (Manual)
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.rollback_image_tag != ''
+    runs-on: ubuntu-latest
+    needs: release
+    steps:
+      - name: Rollback placeholder
+        run: |
+          echo "Rollback to image tag: ${{ github.event.inputs.rollback_image_tag }}"
+          echo "TODO: apply compose update with rollback image tags on production host."

BRANCHING.md

@@ -96,6 +96,13 @@ Apply in repository settings:
 Optional:
 
 - Protect `dev` from direct push if team size/process requires stricter control.
+- Automate protection via `.gitea/scripts/configure-branch-protection.sh`.
+
+## Governance Automation
+
+- Branch naming check: `.gitea/scripts/check-branch-name.sh`
+- PR TODO reference check: `.gitea/scripts/check-pr-todo-reference.sh`
+- PR template: `.gitea/PULL_REQUEST_TEMPLATE.md`
 
 ## Commit Signing Notes
 

CONTRIBUTING.md

@@ -4,6 +4,8 @@
 
 Follow `BRANCHING.md` for long-lived and task branch rules.
 
+Pull requests should use `.gitea/PULL_REQUEST_TEMPLATE.md` and link the exact TODO item.
+
 ## Commit Message Schema
 
 This repository uses Conventional Commits.

README.md

@@ -3,6 +3,7 @@
 Roadmap and progress are tracked in `TODO.md` (also visible in admin at `/todo`).
 Branch model and promotion flow are documented in `BRANCHING.md`.
 Commit schema and changelog workflow are documented in `CONTRIBUTING.md`.
+Versioning and release policy are documented in `VERSIONING.md`.
 
 A baseline monorepo with:
 

TODO.md

@@ -63,47 +63,47 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] Playwright baseline with web/admin projects
 - [x] [P1] CI workflow for lint/typecheck/unit/e2e gates
 - [x] [P1] Test data strategy (seed fixtures + isolated e2e data)
-- [~] [P1] RBAC policy unit tests and permission regression suite
+- [x] [P1] RBAC policy unit tests and permission regression suite
-- [ ] [P1] i18n unit tests (locale resolution, fallback, message key loading)
+- [x] [P1] i18n unit tests (locale resolution, fallback, message key loading)
 - [x] [P1] i18n integration tests (admin/public locale switch and persistence)
-- [ ] [P1] i18n e2e smoke tests (localized headings/content per route)
+- [x] [P1] i18n e2e smoke tests (localized headings/content per route)
-- [ ] [P1] CRUD contract tests for shared service patterns
+- [x] [P1] CRUD contract tests for shared service patterns
 
 ### Documentation
 
 - [x] [P1] Docs tool baseline added (`docs/` via VitePress)
 - [x] [P1] RBAC and permission model documentation in docs site
-- [ ] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
+- [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)
+- [x] [P1] Environment and deployment runbook docs (dev/staging/production)
-- [ ] [P2] API and domain glossary pages
+- [x] [P2] API and domain glossary pages
-- [ ] [P2] Architecture Decision Records (ADR) structure and first ADRs
+- [x] [P2] Architecture Decision Records (ADR) structure and first ADRs
 
 ### Delivery Pipeline And Runtime
 
 - [x] [P2] Theoretical Gitea Actions workflow scaffold (`.gitea/workflows/ci-cd-theoretical.yml`)
 - [x] [P2] Bun-based Dockerfiles for public and admin apps
 - [x] [P2] Staging and production docker-compose templates
-- [ ] [P1] Registry credentials and image push strategy
+- [x] [P1] Registry credentials and image push strategy
-- [ ] [P1] Staging deployment automation against real host
+- [x] [P1] Staging deployment automation against real host
-- [ ] [P1] Production promotion and rollback procedure
+- [x] [P1] Production promotion and rollback procedure
 
 ### Git Flow And Branching
 
-- [ ] [P1] Protect `main` and `staging` branches in Gitea
+- [x] [P1] Protect `main` and `staging` branches in Gitea
-- [ ] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum
+- [x] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum
-- [ ] [P1] Enforce one todo item per branch naming convention
+- [x] [P1] Enforce one todo item per branch naming convention
-- [ ] [P2] Add PR template requiring linked TODO step
+- [x] [P2] Add PR template requiring linked TODO step
-- [ ] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*`
+- [x] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*`
 - [x] [P2] Conventional commit schema documentation (`CONTRIBUTING.md`)
 - [x] [P2] Changelog scaffold and generation scripts (`CHANGELOG.md`, `bun run changelog:*`)
-- [ ] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch)
+- [x] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch)
-- [ ] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
+- [x] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
-- [ ] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
+- [x] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
-- [ ] [P1] App footer implementation plan for version + commit hash (admin + web)
+- [x] [P1] App footer implementation plan for version + commit hash (admin + web)
-- [ ] [P2] Automated version injection in CI (stamping build from tag + commit hash)
+- [x] [P2] Automated version injection in CI (stamping build from tag + commit hash)
-- [ ] [P2] Validation tests for displayed version/hash consistency per deployment
+- [x] [P2] Validation tests for displayed version/hash consistency per deployment
-- [ ] [P1] Release tagging and changelog publication policy in CI
+- [x] [P1] Release tagging and changelog publication policy in CI
 
 ## MVP 1: Core CMS Business Features
 
@@ -205,6 +205,10 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-10] CI quality workflow `.gitea/workflows/ci.yml` enforces `check`, `typecheck`, `test`, and `test:e2e` against a PostgreSQL service.
 - [2026-02-10] Admin app now uses a shared shell with permission-aware navigation and dedicated IA routes (`/pages`, `/media`, `/users`, `/commissions`).
 - [2026-02-10] Public app now has a shared site layout (`banner/header/footer`), DB-backed header banner config, and SEO defaults (`metadata`, `robots`, `sitemap`).
+- [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes.
+- [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`).
+- [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`).
+- [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`).
 
 ## How We Use This File
 

VERSIONING.md

@@ -0,0 +1,71 @@
+# Versioning Policy
+
+## Source Of Truth
+
+- Canonical version: root `package.json` field `version`
+- Tag format: `vX.Y.Z`
+
+Tag validation is enforced in CI:
+
+- `.gitea/scripts/validate-tag-version.sh`
+
+## SemVer Strategy
+
+- `major`: breaking API/behavior changes
+- `minor`: backward-compatible features
+- `patch`: backward-compatible fixes
+
+## Build Metadata Policy
+
+Use git metadata in runtime display format:
+
+- `<version>+sha.<short>`
+
+Example:
+
+- `0.1.0+sha.a1b2c3d`
+
+## Footer Display Plan (Admin + Web)
+
+Planned runtime footer fields:
+
+- app name
+- version from root `package.json`
+- commit hash (short)
+- environment (`dev|staging|production`)
+
+Implementation note:
+
+- inject values at build/deploy time through env vars
+- render in shared footer components
+
+## CI Version Injection
+
+Release/deploy workflows pass release tag and commit metadata:
+
+- `.gitea/workflows/release.yml`
+- `.gitea/workflows/deploy.yml`
+
+Required inputs:
+
+- release tag (`vX.Y.Z`)
+- image tag for deployment
+
+## Validation Strategy
+
+CI validations:
+
+- tag equals `v${package.json.version}`
+- required checks pass before release builds
+
+Runtime validations (planned):
+
+- smoke tests assert footer version/hash format
+- environment-specific deployment checks assert expected image tag
+
+## Changelog and Release Publication
+
+- changelog generation command:
+  - `bun run changelog:release`
+- release workflow generates changelog on tag pipeline
+- release notes publication remains a dedicated step in CI workflow.

apps/admin/src/i18n/server.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+
+import { resolveAdminLocaleFromCookieValue } from "./server"
+
+describe("resolveAdminLocaleFromCookieValue", () => {
+  it("accepts supported locales", () => {
+    expect(resolveAdminLocaleFromCookieValue("de")).toBe("de")
+    expect(resolveAdminLocaleFromCookieValue("en")).toBe("en")
+    expect(resolveAdminLocaleFromCookieValue("es")).toBe("es")
+    expect(resolveAdminLocaleFromCookieValue("fr")).toBe("fr")
+  })
+
+  it("falls back to default locale for unknown values", () => {
+    expect(resolveAdminLocaleFromCookieValue("it")).toBe("en")
+    expect(resolveAdminLocaleFromCookieValue(undefined)).toBe("en")
+  })
+})

apps/admin/src/i18n/server.ts

@@ -4,10 +4,7 @@ import { cookies } from "next/headers"
 import type { AdminMessages } from "./messages"
 import { ADMIN_LOCALE_COOKIE } from "./shared"
 
-export async function resolveAdminLocale(): Promise<AppLocale> {
+export function resolveAdminLocaleFromCookieValue(value: string | undefined): AppLocale {
-  const cookieStore = await cookies()
-  const value = cookieStore.get(ADMIN_LOCALE_COOKIE)?.value
-
   if (value && isAppLocale(value)) {
     return value
   }
@@ -15,6 +12,12 @@ export async function resolveAdminLocale(): Promise<AppLocale> {
   return defaultLocale
 }
 
+export async function resolveAdminLocale(): Promise<AppLocale> {
+  const cookieStore = await cookies()
+  const value = cookieStore.get(ADMIN_LOCALE_COOKIE)?.value
+  return resolveAdminLocaleFromCookieValue(value)
+}
+
 export async function getAdminMessages(locale: AppLocale): Promise<AdminMessages> {
   return (await import(`../messages/${locale}.json`)).default as AdminMessages
 }

apps/web/src/i18n/request.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest"
+
+import { resolveRequestLocale } from "./request"
+
+describe("resolveRequestLocale", () => {
+  it("accepts supported locales", () => {
+    expect(resolveRequestLocale("de")).toBe("de")
+    expect(resolveRequestLocale("en")).toBe("en")
+    expect(resolveRequestLocale("es")).toBe("es")
+    expect(resolveRequestLocale("fr")).toBe("fr")
+  })
+
+  it("falls back to default locale for unsupported values", () => {
+    expect(resolveRequestLocale("it")).toBe("en")
+    expect(resolveRequestLocale(undefined)).toBe("en")
+  })
+})

apps/web/src/i18n/request.ts

@@ -1,11 +1,16 @@
+import type { AppLocale } from "@cms/i18n"
 import { hasLocale } from "next-intl"
 import { getRequestConfig } from "next-intl/server"
 
 import { routing } from "./routing"
 
+export function resolveRequestLocale(requested: string | undefined): AppLocale {
+  return hasLocale(routing.locales, requested) ? requested : routing.defaultLocale
+}
+
 export default getRequestConfig(async ({ requestLocale }) => {
   const requested = await requestLocale
-  const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale
+  const locale = resolveRequestLocale(requested)
 
   return {
     locale,

docs/.vitepress/config.mts

@@ -21,9 +21,16 @@ 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" },
+          { text: "Domain Glossary", link: "/product-engineering/domain-glossary" },
+          { text: "Environment Runbook", link: "/product-engineering/environment-runbook" },
+          { text: "Delivery Pipeline", link: "/product-engineering/delivery-pipeline" },
+          { text: "Git Flow Governance", link: "/product-engineering/git-flow-governance" },
           { text: "Testing Strategy", link: "/product-engineering/testing-strategy" },
+          { text: "ADR Index", link: "/adr/" },
           { text: "Workflow", link: "/workflow" },
         ],
       },
@@ -33,7 +40,17 @@ export default defineConfig({
       },
       {
         text: "Public API",
-        items: [{ text: "Section Overview", link: "/public-api/" }],
+        items: [
+          { text: "Section Overview", link: "/public-api/" },
+          { text: "Glossary", link: "/public-api/glossary" },
+        ],
+      },
+      {
+        text: "ADR",
+        items: [
+          { text: "Index", link: "/adr/" },
+          { text: "0001 Monorepo Foundation", link: "/adr/0001-monorepo-foundation" },
+        ],
       },
     ],
     socialLinks: [{ icon: "github", link: "https://example.com/replace-with-repo" }],

docs/adr/0001-monorepo-foundation.md

@@ -0,0 +1,37 @@
+# ADR 0001: Monorepo Foundation
+
+- Status: Accepted
+- Date: 2026-02-10
+
+## Context
+
+The CMS platform requires:
+
+- separate admin and public apps
+- shared domain contracts and data access
+- consistent tooling and CI quality gates
+- incremental delivery through MVP stages
+
+A fragmented multi-repo setup would increase coordination overhead and duplicate shared contracts.
+
+## Decision
+
+Adopt a Bun workspace monorepo with:
+
+- `apps/admin` and `apps/web` for runtime surfaces
+- shared packages (`@cms/content`, `@cms/db`, `@cms/crud`, `@cms/ui`, `@cms/i18n`)
+- shared quality tooling (Biome, TypeScript, Vitest, Playwright, Turbo)
+
+## Consequences
+
+### Positive
+
+- shared contract updates propagate in one change set
+- easier cross-app refactors and testing
+- single CI pipeline with consistent gates
+
+### Negative
+
+- stronger need for workspace discipline and clear boundaries
+- larger repository clone/build surface
+- potential for cross-package coupling if conventions are not enforced

docs/adr/README.md

@@ -0,0 +1,17 @@
+# ADR Index
+
+Architecture Decision Records (ADRs) capture important technical decisions and context.
+
+## Format
+
+- Numbered files: `0001-<short-title>.md`
+- Immutable once accepted (new ADRs supersede old decisions)
+- Include:
+  - Status
+  - Context
+  - Decision
+  - Consequences
+
+## Records
+
+- [0001 - Monorepo Foundation](./0001-monorepo-foundation.md)

docs/index.md

@@ -7,6 +7,7 @@ Engineering documentation hub for this repository.
 - [Product / Engineering](/product-engineering/)
 - [Admin / User Guides](/admin-user-guides/)
 - [Public API](/public-api/)
+- [ADR Index](/adr/)
 
 ## Core Sources
 
@@ -14,6 +15,7 @@ Engineering documentation hub for this repository.
 - Branching and promotion flow: `BRANCHING.md`
 - Contribution and commit schema: `CONTRIBUTING.md`
 - Release history: `CHANGELOG.md`
+- Versioning and release policy: `VERSIONING.md`
 
 ## Documentation Scope
 

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/delivery-pipeline.md

@@ -0,0 +1,77 @@
+# Delivery Pipeline
+
+## Scope
+
+Operational pipeline baseline for image build/push, staging deploy, production promotion, and rollback.
+
+## Registry Credentials Strategy
+
+Use scoped Gitea secrets:
+
+- `CMS_IMAGE_REGISTRY`
+- `CMS_IMAGE_NAMESPACE`
+- `CMS_IMAGE_REGISTRY_USER`
+- `CMS_IMAGE_REGISTRY_PASSWORD`
+
+Policy:
+
+- credentials only in CI secrets
+- no plaintext credentials in repo
+- least privilege: push/pull for target namespace only
+
+## Build and Push Flow
+
+- Workflow: `.gitea/workflows/release.yml`
+- Trigger:
+  - tag push `vX.Y.Z`
+  - manual `workflow_dispatch`
+- Steps:
+  1. validate tag vs root `package.json` version
+  2. generate changelog
+  3. docker login
+  4. build and push `cms-web` and `cms-admin` images
+
+## Staging Deployment Automation
+
+- Workflow: `.gitea/workflows/deploy.yml`
+- Manual input:
+  - `environment=staging`
+  - `image_tag=vX.Y.Z`
+- Remote deployment uses SSH + compose file:
+  - `docker-compose.staging.yml`
+
+Required secrets:
+
+- `CMS_STAGING_HOST`
+- `CMS_STAGING_USER`
+- `CMS_DEPLOY_KEY`
+- `CMS_REMOTE_DEPLOY_PATH`
+
+## Production Promotion and Rollback
+
+Promotion:
+
+- run deploy workflow with:
+  - `environment=production`
+  - `image_tag=vX.Y.Z`
+
+Rollback:
+
+- release workflow supports rollback placeholder by image tag
+- deploy workflow supports `rollback_tag` input
+- recovery action:
+  - rerun deploy with previous known-good tag
+
+## Deployment Verification
+
+After deploy:
+
+1. app health checks (web/admin)
+2. auth smoke flow
+3. i18n smoke flow
+4. critical route checks (`/`, `/login`, `/todo`)
+
+## Notes
+
+- Current workflows are production-oriented scaffolds and require secret provisioning in Gitea.
+- Host hardening, network ACLs, and backup policy remain mandatory operational controls.

docs/product-engineering/domain-glossary.md

@@ -0,0 +1,35 @@
+# Domain Glossary
+
+## Core Terms
+
+### Owner
+
+Highest-privilege admin role. Exactly one canonical owner must exist at all times.
+
+### Support User
+
+Hidden technical support account used for break-glass access and operational recovery.
+
+### Admin Registration Policy
+
+Runtime policy controlling whether `/register` can create additional admin users after owner bootstrap.
+
+### Protected Account
+
+Account that cannot be deleted/demoted through self-service flows (support + canonical owner).
+
+### CRUD Service
+
+Shared `@cms/crud` service abstraction combining schema validation, repository orchestration, and audit hooks.
+
+### Permission Scope
+
+RBAC access scope granularity: `own`, `team`, `global`.
+
+### Roadmap Source Of Truth
+
+`TODO.md` in repository root. Rendered in admin via `/todo`.
+
+### Header Banner
+
+Public-site announcement strip configured through `system_setting` key `public.header_banner`.

docs/product-engineering/environment-runbook.md

@@ -0,0 +1,103 @@
+# Environment and Deployment Runbook
+
+## Scope
+
+Operational baseline for `dev`, `staging`, and `production`.
+
+## Environments
+
+### Dev (local)
+
+- Runtime: Bun + local Next dev servers
+- Entry point: `bun run dev`
+- Database: local/remote dev Postgres from `.env`
+- Characteristics:
+  - fastest feedback
+  - non-production data acceptable
+  - migrations created here first
+
+### Staging
+
+- Runtime: Docker Compose (`docker-compose.staging.yml`)
+- Purpose: integration validation and release candidate checks
+- Characteristics:
+  - production-like environment
+  - controlled test data
+  - candidate for production promotion
+
+### Production
+
+- Runtime: Docker Compose (`docker-compose.production.yml`)
+- Purpose: end-user traffic
+- Characteristics:
+  - protected secrets and stricter access controls
+  - immutable release artifacts
+  - rollback procedures required
+
+## Core Commands
+
+### Local development
+
+```bash
+bun install
+bun run db:generate
+bun run db:migrate
+bun run db:seed
+bun run dev
+```
+
+### Staging compose
+
+```bash
+bun run docker:staging:up
+bun run docker:staging:down
+```
+
+### Production compose
+
+```bash
+bun run docker:production:up
+bun run docker:production:down
+```
+
+## Release Flow
+
+1. Complete work on task branch.
+2. Merge into `dev` and pass quality gates.
+3. Promote `dev` -> `staging`.
+4. Validate staging smoke/e2e + manual checks.
+5. Promote `staging` -> `main` and tag release.
+
+## Migration Policy
+
+- Create migrations in development only.
+- Apply migrations in deployment using `prisma migrate deploy`.
+- Never hand-edit applied migration history.
+
+## Rollback Baseline
+
+Current baseline strategy:
+
+- rollback app image/tag to previous known-good release
+- restore database from backup when schema/data changes require recovery
+
+## Secrets and Config
+
+- Dev: `.env`
+- Staging: `.env.staging` (from `.env.staging.example`)
+- Production: `.env.production` (from `.env.production.example`)
+
+Minimum sensitive values:
+
+- `DATABASE_URL`
+- `BETTER_AUTH_SECRET`
+- `CMS_SUPPORT_*` credentials/keys
+
+## Verification Checklist
+
+- `bun run check`
+- `bun run typecheck`
+- `bun run test`
+- `bun run test:e2e`
+- app startup health for web/admin
+- login flow and permissions smoke

docs/product-engineering/git-flow-governance.md

@@ -0,0 +1,66 @@
+# Git Flow Governance
+
+## Scope
+
+Governance rules for branch protections, PR gates, branch naming, and merge discipline.
+
+## Branch Protection
+
+Protected branches:
+
+- `main`
+- `staging`
+
+Apply protections using:
+
+- Gitea UI settings
+- or automation script: `.gitea/scripts/configure-branch-protection.sh`
+
+Minimum policy:
+
+- no direct pushes
+- PR merge required
+- required status checks
+- at least one reviewer approval
+
+## PR Gates
+
+Required checks are implemented in `.gitea/workflows/ci.yml`:
+
+- Governance Checks
+- Lint Typecheck Unit E2E
+
+## Branch Naming and TODO Scope
+
+Allowed branch prefixes:
+
+- `todo/`
+- `refactor/`
+- `code/`
+
+Validation script:
+
+- `.gitea/scripts/check-branch-name.sh`
+
+Rule:
+
+- one primary TODO item per delivery branch
+
+PR TODO reference enforcement:
+
+- template: `.gitea/PULL_REQUEST_TEMPLATE.md`
+- CI check: `.gitea/scripts/check-pr-todo-reference.sh`
+
+## Branch Lifecycle
+
+1. Create short-lived branch from latest integration tip.
+2. Implement one primary scope.
+3. Open PR and pass required checks.
+4. Merge into `dev`.
+5. Promote `dev -> staging -> main`.
+
+## Commit and Tag Policy
+
+- Conventional commits required (`CONTRIBUTING.md`)
+- release tags: `vX.Y.Z`
+- changelog generated from commit history

docs/product-engineering/i18n-baseline.md

@@ -18,4 +18,4 @@ Current baseline:
 
 - Public app locale is resolved through `next-intl` middleware + cookie.
 - Enabled locales are currently static in code and will later be managed from admin settings.
-- Translation key conventions and workflow docs are tracked in `TODO.md`.
+- Translation key and workflow standards are documented in `i18n-conventions.md`.

docs/product-engineering/i18n-conventions.md

@@ -0,0 +1,86 @@
+# i18n Conventions
+
+## Scope
+
+This document defines translation conventions for both apps in MVP0+.
+
+- Public app i18n: `next-intl` message namespaces and route-level usage
+- Admin app i18n: JSON dictionaries + runtime resolver/provider
+- Shared locale contract: `@cms/i18n` (`de`, `en`, `es`, `fr`; default `en`)
+
+## Locale Policy
+
+- Source of truth: `packages/i18n/src/index.ts`
+- Current enabled locales are code-driven and shared across web/admin.
+- Admin-managed locale toggles are planned for a later MVP.
+
+## Key Naming Conventions
+
+- Use `camelCase` for keys.
+- Group by domain namespace (not by component filename).
+- Keep keys stable; update values, not key names, during copy edits.
+
+### Public app namespaces
+
+- `Layout.*`
+- `Home.*`
+- `LanguageSwitcher.*`
+- Page-specific namespaces, e.g. `About.*`, `Contact.*`
+- Metadata namespace: `Seo.*`
+
+### Admin app namespaces
+
+- `common.*`
+- `auth.*`
+- `dashboard.*`
+- `settings.*`
+
+## Message Structure
+
+- Keep messages as nested JSON objects.
+- Avoid very deep nesting (prefer 2-3 levels).
+- Keep punctuation in translation values, not code.
+- Avoid embedding HTML in message strings.
+
+## Fallback Rules
+
+- Unknown/invalid locale values fallback to default locale `en`.
+- Missing translation key behavior:
+  - Admin: `translateMessage` returns provided fallback, else key.
+  - Public: ensure required keys exist in locale JSON; avoid runtime missing-key states.
+
+## Adding New Translation Keys
+
+1. Add key/value in `apps/*/src/messages/en.json`.
+2. Add equivalent key in `de/es/fr` JSON files.
+3. Use key via translator:
+   - Web: `useTranslations("Namespace")` or `getTranslations("Namespace")`
+   - Admin: `useAdminT()` or server-side `translateMessage(...)`
+4. Add/adjust tests for behavior where relevant.
+
+## Translation Workflow
+
+1. Author English source copy first.
+2. Add keys in all supported locales in same change.
+3. Keep semantic parity across locales.
+4. Run checks:
+   - `bun run check`
+   - `bun run typecheck`
+   - `bun run test`
+5. For route-level i18n behavior changes, run e2e smoke:
+   - `bunx playwright test --grep "i18n smoke"`
+
+## QA Checklist
+
+- Locale switch persists after refresh.
+- Page headings and navigation labels translate correctly.
+- Metadata (`Seo`) strings resolve per locale.
+- No missing-key placeholders visible in UI.
+
+## Related Files
+
+- `apps/web/src/i18n/request.ts`
+- `apps/web/src/i18n/routing.ts`
+- `apps/admin/src/i18n/server.ts`
+- `apps/admin/src/i18n/messages.ts`
+- `packages/i18n/src/index.ts`

docs/product-engineering/index.md

@@ -8,7 +8,14 @@ This section covers platform and implementation documentation for engineers and
 - [Architecture](/architecture)
 - [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)
+- [Domain Glossary](/product-engineering/domain-glossary)
+- [Environment Runbook](/product-engineering/environment-runbook)
+- [Delivery Pipeline](/product-engineering/delivery-pipeline)
+- [Git Flow Governance](/product-engineering/git-flow-governance)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
+- [ADR Index](/adr/)
 - [Workflow](/workflow)
 
 ## Scope
@@ -20,6 +27,4 @@ This section covers platform and implementation documentation for engineers and
 
 ## Planned Expansions
 
-- Domain model and glossary
-- ADR (Architecture Decision Record) index
 - Operational playbooks (incident, rollback, recovery)

docs/public-api/glossary.md

@@ -0,0 +1,43 @@
+# Public API Glossary
+
+## Scope
+
+Baseline terms for future public API design and integration discussions.
+
+## Terms
+
+### Public API
+
+Externally consumable endpoints intended for non-admin clients.
+
+### Resource
+
+Entity exposed by an API endpoint (for example: `page`, `media`, `news`).
+
+### Contract
+
+The stable request/response schema for an endpoint version.
+
+### Version
+
+Compatibility boundary for API contracts (for example: `v1`).
+
+### Authentication
+
+Identity verification mechanism for protected API routes.
+
+### Authorization
+
+Permission check determining whether an authenticated actor can access a resource/action.
+
+### Pagination
+
+Mechanism for splitting large result sets across requests.
+
+### Idempotency
+
+Property where repeating a request does not change final state beyond the first successful call.
+
+### Rate Limit
+
+Request threshold policy applied per consumer/time window.

docs/public-api/index.md

@@ -11,6 +11,11 @@ No stable public API surface is documented yet.
 - Add API docs when real endpoints are implemented and versioned
 - Use OpenAPI as source of truth for endpoint reference
 - Keep integration guides and authentication examples here
+- Use glossary terms consistently across API specs and guides
+
+## Reference
+
+- [Public API Glossary](/public-api/glossary)
 
 ## Notes
 

docs/workflow.md

@@ -28,3 +28,9 @@ Follow `BRANCHING.md`:
 ```bash
 bun run changelog:release
 ```
+
+## Governance
+
+- Branch and PR governance checks run in `.gitea/workflows/ci.yml`.
+- PR template: `.gitea/PULL_REQUEST_TEMPLATE.md`
+- Versioning policy: `VERSIONING.md`

e2e/i18n-smoke.pw.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test"
+
+test.describe("i18n smoke", () => {
+  test("web renders localized page headings on key routes", async ({ page }, testInfo) => {
+    test.skip(testInfo.project.name !== "web-chromium")
+
+    await page.goto("/")
+    await page.locator("select").first().selectOption("de")
+    await expect(page.getByRole("heading", { name: /dein next\.js cms frontend/i })).toBeVisible()
+
+    await page.getByRole("link", { name: /über uns/i }).click()
+    await expect(page.getByRole("heading", { name: /über dieses projekt/i })).toBeVisible()
+
+    await page.locator("select").first().selectOption("es")
+    await expect(page.getByRole("heading", { name: /sobre este proyecto/i })).toBeVisible()
+
+    await page.getByRole("link", { name: /contacto/i }).click()
+    await expect(page.getByRole("heading", { name: /^contacto$/i })).toBeVisible()
+  })
+
+  test("admin login renders localized heading and labels", async ({ page }, testInfo) => {
+    test.skip(testInfo.project.name !== "admin-chromium")
+
+    await page.goto("/login")
+    await expect(page.getByRole("heading", { name: /sign in to cms admin/i })).toBeVisible()
+
+    await page.locator("select").first().selectOption("fr")
+    await expect(page.getByRole("heading", { name: /se connecter à cms admin/i })).toBeVisible()
+    await expect(page.getByLabel(/e-mail ou nom d’utilisateur/i)).toBeVisible()
+
+    await page.locator("select").first().selectOption("es")
+    await expect(page.getByRole("heading", { name: /iniciar sesión en cms admin/i })).toBeVisible()
+    await expect(page.getByLabel(/correo o nombre de usuario/i)).toBeVisible()
+  })
+})

packages/content/src/rbac.test.ts

@@ -28,4 +28,31 @@ describe("rbac model", () => {
     expect(permissionMatrix.editor.length).toBeGreaterThan(0)
     expect(permissionMatrix.manager.length).toBeGreaterThan(0)
   })
+
+  it("prevents privilege escalation for non-admin roles", () => {
+    expect(hasPermission("editor", "users:manage_roles", "global")).toBe(false)
+    expect(hasPermission("manager", "users:manage_roles", "global")).toBe(false)
+    expect(hasPermission("editor", "dashboard:read", "global")).toBe(true)
+  })
+
+  it("keeps role policy regressions visible for critical permissions", () => {
+    const criticalChecks: Array<{
+      role: "owner" | "support" | "admin" | "manager" | "editor"
+      permission: Parameters<typeof hasPermission>[1]
+      scope: Parameters<typeof hasPermission>[2]
+      allowed: boolean
+    }> = [
+      { role: "owner", permission: "users:manage_roles", scope: "global", allowed: true },
+      { role: "support", permission: "users:manage_roles", scope: "global", allowed: true },
+      { role: "admin", permission: "banner:write", scope: "global", allowed: true },
+      { role: "manager", permission: "users:write", scope: "global", allowed: false },
+      { role: "manager", permission: "users:write", scope: "team", allowed: true },
+      { role: "editor", permission: "news:publish", scope: "team", allowed: false },
+      { role: "editor", permission: "news:publish", scope: "own", allowed: true },
+    ]
+
+    for (const check of criticalChecks) {
+      expect(hasPermission(check.role, check.permission, check.scope)).toBe(check.allowed)
+    }
+  })
 })

packages/crud/src/contract.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest"
+import { z } from "zod"
+
+import { createCrudService } from "./service"
+
+type RecordItem = {
+  id: string
+  title: string
+}
+
+describe("crud service contract", () => {
+  it("calls repository in expected order for update and delete", async () => {
+    const calls: string[] = []
+    const state = new Map<string, RecordItem>([["1", { id: "1", title: "Initial" }]])
+
+    const service = createCrudService({
+      resource: "item",
+      repository: {
+        list: async () => {
+          calls.push("list")
+          return Array.from(state.values())
+        },
+        findById: async (id) => {
+          calls.push(`findById:${id}`)
+          return state.get(id) ?? null
+        },
+        create: async (input: { title: string }) => {
+          calls.push("create")
+          return {
+            id: "2",
+            title: input.title,
+          }
+        },
+        update: async (id, input: { title?: string }) => {
+          calls.push(`update:${id}`)
+          const current = state.get(id)
+          if (!current) {
+            throw new Error("missing")
+          }
+          const updated = {
+            ...current,
+            ...input,
+          }
+          state.set(id, updated)
+          return updated
+        },
+        delete: async (id) => {
+          calls.push(`delete:${id}`)
+          const current = state.get(id)
+          if (!current) {
+            throw new Error("missing")
+          }
+          state.delete(id)
+          return current
+        },
+      },
+      schemas: {
+        create: z.object({
+          title: z.string().min(3),
+        }),
+        update: z.object({
+          title: z.string().min(3).optional(),
+        }),
+      },
+    })
+
+    await service.update("1", { title: "Updated" })
+    await service.delete("1")
+
+    expect(calls).toEqual(["findById:1", "update:1", "findById:1", "delete:1"])
+  })
+
+  it("passes parsed payload to repository create/update contracts", async () => {
+    let createPayload: unknown = null
+    let updatePayload: unknown = null
+
+    const service = createCrudService({
+      resource: "item",
+      repository: {
+        list: async () => [],
+        findById: async () => ({
+          id: "1",
+          title: "Existing",
+        }),
+        create: async (input: { title: string }) => {
+          createPayload = input
+          return {
+            id: "2",
+            title: input.title,
+          }
+        },
+        update: async (_id, input: { title?: string }) => {
+          updatePayload = input
+          return {
+            id: "1",
+            title: input.title ?? "Existing",
+          }
+        },
+        delete: async () => ({
+          id: "1",
+          title: "Existing",
+        }),
+      },
+      schemas: {
+        create: z.object({
+          title: z.string().trim().min(3),
+        }),
+        update: z.object({
+          title: z.string().trim().min(3).optional(),
+        }),
+      },
+    })
+
+    await service.create({
+      title: "  Created  ",
+    })
+    await service.update("1", {
+      title: "  Updated  ",
+    })
+
+    expect(createPayload).toEqual({ title: "Created" })
+    expect(updatePayload).toEqual({ title: "Updated" })
+  })
+})