From 5b47fafe89e7d1e4fb42646f8bac0e2423828c07 Mon Sep 17 00:00:00 2001
From: Citali <git@fellies.email>
Date: Wed, 11 Feb 2026 22:35:46 +0100
Subject: [PATCH] docs(product): add cms feature topics, package catalog, and
 inspiration notes

---
 TODO.md                                       |  62 ++++-
 .../artist-cms-inspiration.md                 |  52 ++++
 .../product-engineering/cms-feature-topics.md | 244 ++++++++++++++++++
 docs/product-engineering/index.md             |   4 +
 docs/product-engineering/package-catalog.md   | 153 +++++++++++
 .../user-personas-and-use-cases.md            | 116 +++++++++
 6 files changed, 623 insertions(+), 8 deletions(-)
 create mode 100644 docs/product-engineering/artist-cms-inspiration.md
 create mode 100644 docs/product-engineering/cms-feature-topics.md
 create mode 100644 docs/product-engineering/package-catalog.md
 create mode 100644 docs/product-engineering/user-personas-and-use-cases.md

diff --git a/TODO.md b/TODO.md
index e4763da..aad69b8 100644
--- a/TODO.md
+++ b/TODO.md
@@ -116,36 +116,73 @@ This file is the single source of truth for roadmap and delivery progress.
 
 ## MVP 1: Core CMS Business Features
 
+### MVP1 Suggested Branch Order
+
+- [ ] [P1] `todo/mvp1-media-foundation`:
+  media model, artwork entity, grouping primitives (gallery/album/category/tag), rendition slots
+- [ ] [P1] `todo/mvp1-media-upload-pipeline`:
+  S3/local upload adapter, media processing presets, metadata input flows, admin media CRUD UI
+- [ ] [P1] `todo/mvp1-pages-navigation-builder`:
+  page CRUD, navigation tree, reusable page blocks (forms/price cards/gallery embeds)
+- [ ] [P1] `todo/mvp1-commissions-customers`:
+  commission request intake + admin CRUD + kanban + customer entity/linking
+- [ ] [P1] `todo/mvp1-announcements-news`:
+  announcement management/rendering + news/blog CRUD and public rendering
+- [ ] [P1] `todo/mvp1-public-rendering-integration`:
+  public rendering for pages/navigation/media/portfolio/announcements and commissioning entrypoints
+- [ ] [P1] `todo/mvp1-e2e-happy-paths`:
+  end-to-end scenarios for page publish, media flow, announcement display, commission flow
+
+### Separate Product Ideas Backlog (Non-Blocking)
+
+- [ ] [P2] Smart homepage section presets for artists (featured artwork, latest news, open commissions)
+- [ ] [P2] Portfolio narrative mode (series story + process notes + ordered media sequence)
+- [ ] [P2] Reusable CTA/form snippets with per-page override tokens
+- [ ] [P2] Lightweight CRM timeline per customer (requests, replies, outcomes)
+- [ ] [P3] AI-assisted alt text and metadata suggestion workflow (human approval required)
+- [ ] [P3] Auto-generated social crops/promo packs from selected artworks
+
 ### Admin App (Primary Focus)
 
 - [ ] [P1] Page management (create/edit/publish/unpublish/schedule)
+- [ ] [P1] Page builder with reusable content blocks (hero, rich text, gallery, CTA, forms, price cards)
 - [ ] [P1] Navigation management (menus, nested items, order, visibility)
-- [ ] [P1] Media library (upload, browse, replace, delete)
-- [ ] [P1] Media enrichment metadata (alt text, copyright, author, source, tags)
-- [ ] [P1] Media refinement for artworks (medium, dimensions, year, framing, availability)
+- [ ] [P1] Media library (upload, browse, replace, delete) with media-type classification (artwork, banner, promo, generic, video/gif)
+- [ ] [P1] Media enrichment metadata (alt text, copyright, author, source, tags, licensing, usage context)
+- [ ] [P1] Portfolio grouping primitives (galleries, albums, categories, tags) with ordering/visibility controls
+- [ ] [P1] Artwork refinement fields (medium, dimensions, year, framing, availability, price visibility)
+- [ ] [P1] Artwork rendition management (thumbnail, card, full, retina/custom sizes)
+- [ ] [P1] Type-specific processing presets (artwork/banner/promo/video/gif) with validation rules
 - [ ] [P1] Users management (invite, roles, status)
 - [ ] [P1] Disable/ban user function and enforcement in auth/session checks
 - [~] [P1] Owner/support protection rules in user management actions (cannot delete/demote)
-- [ ] [P1] Commissions management (request intake, owner, due date, notes)
+- [ ] [P1] Commissions management (request intake, owner, due date, notes, linked customer, linked artworks)
+- [ ] [P1] Customer records (contact profile, notes, consent flags, recurrence marker)
+- [ ] [P1] Customer-to-commission linkage and reuse workflow (no re-entry for recurring customers)
 - [ ] [P1] Kanban workflow for commissions (new, scoped, in-progress, review, done)
 - [ ] [P1] Header banner management (message, CTA, active window)
+- [ ] [P1] Announcements management (prominent site notices with schedule, priority, and audience targeting)
+- [ ] [P2] News/blog editorial workflow (draft/review/publish, authoring metadata)
 
 ### Public App
 
 - [ ] [P1] Dynamic page rendering from CMS page entities
 - [ ] [P1] Navigation rendering from managed menu structure
 - [ ] [P1] Media entity rendering with enrichment data
+- [ ] [P1] Portfolio views (gallery/album/category/tag) for artworks with filter and sort controls
+- [ ] [P1] Rendition-aware media delivery (thumbnail/card/full) per template slot
 - [ ] [P1] Translation-ready content model for public entities (pages/news/navigation labels)
 - [ ] [P2] Artwork views and listing filters
 - [ ] [P1] Commission request submission flow
 - [ ] [P1] Header banner render logic and fallbacks
+- [ ] [P1] Announcement render slots (homepage + optional global/top banner position)
 
 ### News / Blog (Secondary Track)
 
-- [ ] [P2] News/blog content type (not primary CMS domain)
-- [ ] [P2] Admin list/editor for news posts
-- [ ] [P2] Public news index + detail pages
-- [ ] [P3] Tag/category and basic archive support
+- [ ] [P1] News/blog content type (editorial content for artist updates and process posts)
+- [ ] [P1] Admin list/editor for news posts
+- [ ] [P1] Public news index + detail pages
+- [ ] [P2] Tag/category and basic archive support
 
 ### Testing
 
@@ -165,6 +202,12 @@ This file is the single source of truth for roadmap and delivery progress.
 - [ ] [P1] Audit log for key content operations
 - [ ] [P2] Revision history for pages/navigation/media metadata
 - [ ] [P1] Permission matrix refinement with granular scopes
+- [ ] [P2] Media processing orchestration UI (queue status, retries, processing diagnostics)
+- [ ] [P2] Automatic color palette extraction from artworks (stored for theming/filtering)
+- [ ] [P2] Watermark pipeline for artwork renditions with configurable watermark asset/position/opacity
+- [ ] [P2] Advanced media transforms by type (video transcode profiles, gif optimization, banner safe-area presets)
+- [ ] [P2] Announcement targeting refinement (locale/segment targeting rules)
+- [ ] [P2] Customer lifecycle tooling (status stages, communication history, export)
 - [ ] [P1] Verify email pipeline and operational templates (welcome/verify/resend)
 - [ ] [P1] Forgot password/reset password pipeline and support tooling
 - [ ] [P2] GUI page to edit role-permission mappings with safety guardrails
@@ -179,6 +222,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [ ] [P2] Performance budget checks (Core Web Vitals)
 - [ ] [P1] 404/500 content-aware error pages
 - [ ] [P1] Accessibility review and fixes
+- [ ] [P2] Theme assistance from extracted artwork palettes (opt-in per page/section)
 
 ### Platform
 
@@ -221,6 +265,8 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-11] Release workflow now publishes changelog-derived notes to Gitea releases and supports executable production rollback via SSH + compose tag switch.
 - [2026-02-11] Branch protection verification checklist is now documented; final UI-level verification remains environment-specific.
 - [2026-02-11] Added a staging deployment execution checklist and deployment-record template to capture first real-host rollout evidence.
+- [2026-02-11] Artist-focused feature map refined: MVP1 covers portfolio media/domain CRUD + announcements + customer/commission linking; MVP2 covers advanced automation (watermark, palette extraction, media transform pipelines).
+- [2026-02-11] `gaertan` inspiration to reuse: S3 object strategy with signed delivery, commission type/options/extras/custom-input modeling, request-status kanban mapping, and gallery rendition/color extraction patterns.
 
 ## How We Use This File
 
diff --git a/docs/product-engineering/artist-cms-inspiration.md b/docs/product-engineering/artist-cms-inspiration.md
new file mode 100644
index 0000000..c310fe5
--- /dev/null
+++ b/docs/product-engineering/artist-cms-inspiration.md
@@ -0,0 +1,52 @@
+# Artist CMS Inspiration Notes
+
+## Scope
+
+Inspiration-only notes for implementation direction.  
+These are not direct copy targets and do not override current CMS roadmap decisions.
+
+## Useful Patterns Observed in `gaertan`
+
+### Media and Delivery
+
+- S3-backed storage with signed URL/object access patterns.
+- Route-level image streaming/proxy from storage keys.
+- Multiple artwork variants/renditions for different view contexts.
+- Dedicated actions for generated gallery variants and missing-variant backfill.
+
+### Portfolio Domain
+
+- Artwork linked to galleries/albums/tags/categories.
+- Filterable portfolio pages (album/year/tag/search).
+- Gallery components designed for responsive/justified layouts.
+
+### Commissions Domain
+
+- Rich commission model:
+  - types
+  - options
+  - extras
+  - custom cards
+  - custom inputs
+- Public request form + admin request management.
+- Commission status/kanban-like mapping for intake/in-progress/completed.
+
+### Color and Processing
+
+- Artwork color extraction workflows (palette/tones) from stored image files.
+- Potential pipeline point for future theming and discovery filters.
+
+## How We Should Reuse These Ideas Here
+
+- Keep the domain approach, but normalize to current CMS architecture (`@cms/*` packages, Next app router, shared CRUD services).
+- Start with deterministic MVP1 primitives:
+  - media CRUD + rendition slots
+  - portfolio grouping entities
+  - commission/customer linking
+- Defer heavy media automation (advanced transforms/watermark/palette orchestration) to MVP2 after baseline reliability is proven.
+
+## Guardrails
+
+- No direct schema/code lift from `gaertan`; re-model explicitly for this repository.
+- Keep upload and processing abstraction pluggable (S3 now, alternative provider later).
+- Favor explicit auditability for media/commission mutations.
diff --git a/docs/product-engineering/cms-feature-topics.md b/docs/product-engineering/cms-feature-topics.md
new file mode 100644
index 0000000..9248b64
--- /dev/null
+++ b/docs/product-engineering/cms-feature-topics.md
@@ -0,0 +1,244 @@
+# CMS Feature Topics (Domain-Centric)
+
+## Purpose
+
+Describe the CMS by feature domains/modules (not personas), so implementation and UI structure stay clear.
+
+## 1) Pages
+
+Scope:
+
+- create/edit/publish/unpublish/schedule pages
+- slug + SEO metadata
+- draft and publish states
+
+Core entities:
+
+- `Page`
+- `PageVersion` (later)
+- `SeoMeta`
+
+MVP fit:
+
+- MVP1 core
+
+## 2) Navigation
+
+Scope:
+
+- menus, nested items, ordering, visibility
+- route linking to pages or external URLs
+
+Core entities:
+
+- `NavigationMenu`
+- `NavigationItem`
+
+MVP fit:
+
+- MVP1 core
+
+## 3) Media
+
+Scope:
+
+- upload/browse/replace/delete media
+- media-type classification (artwork, banner, promo, generic, video/gif)
+- metadata management
+
+Core entities:
+
+- `MediaAsset`
+- `MediaMetadata`
+- `MediaVariant` (renditions)
+
+MVP fit:
+
+- MVP1 core
+
+## 4) Portfolio / Artworks
+
+Scope:
+
+- artworks with grouped structures
+- grouping by galleries/albums/categories/tags
+- ordering and visibility
+
+Core entities:
+
+- `Artwork`
+- `Gallery`
+- `Album`
+- `Category`
+- `Tag`
+
+MVP fit:
+
+- MVP1 core
+
+## 5) Cards and Reusable Blocks
+
+Scope:
+
+- reusable content blocks for pages
+- card-based sections (price cards, promo cards, feature cards)
+
+Core entities:
+
+- `BlockTemplate`
+- `BlockInstance`
+- `CardPreset`
+
+MVP fit:
+
+- MVP1 (baseline blocks), MVP2 (advanced builder UX)
+
+## 6) Forms
+
+Scope:
+
+- embeddable forms on pages
+- schema-driven field definitions
+- submission handling and moderation
+
+Core entities:
+
+- `FormDefinition`
+- `FormField`
+- `FormSubmission`
+
+MVP fit:
+
+- MVP1 for commission request path
+- MVP2 for generic form builder
+
+## 7) Announcements and Banners
+
+Scope:
+
+- prominent notices on public pages
+- schedule windows and priority
+
+Core entities:
+
+- `Announcement`
+- `HeaderBanner`
+
+MVP fit:
+
+- MVP1 core
+
+## 8) News / Blog
+
+Scope:
+
+- editorial posts and updates
+- author metadata, status flow
+
+Core entities:
+
+- `NewsPost`
+- `NewsCategory`
+
+MVP fit:
+
+- MVP1 secondary core
+
+## 9) Commissions
+
+Scope:
+
+- commission request intake
+- admin processing and kanban status transitions
+
+Core entities:
+
+- `CommissionRequest`
+- `CommissionStatus`
+- `CommissionType` (options/extras/custom fields)
+
+MVP fit:
+
+- MVP1 core
+
+## 10) Customers (CRM-Lite)
+
+Scope:
+
+- recurring customer records
+- customer-to-commission linking and reuse
+
+Core entities:
+
+- `Customer`
+- `CustomerContact`
+- `CustomerCommissionLink`
+
+MVP fit:
+
+- MVP1 core
+
+## 11) Users, Roles, and Permissions
+
+Scope:
+
+- users, role assignment, status (active/banned)
+- protected owner/support invariants
+
+Core entities:
+
+- `User`
+- `Role`
+- `Permission`
+
+MVP fit:
+
+- MVP0/MVP1 bridge; refinements in MVP2
+
+## 12) Settings
+
+Scope:
+
+- system settings and feature flags
+- registration policy and future locale toggles
+
+Core entities:
+
+- `SystemSetting`
+
+MVP fit:
+
+- MVP0 baseline, expanded in MVP1/MVP2
+
+## 13) Processing Pipelines (Later)
+
+Scope:
+
+- watermarking
+- color extraction
+- advanced media transforms
+- queue/retry visibility
+
+Core entities:
+
+- `MediaJob`
+- `MediaJobRun`
+- `ExtractedPalette`
+
+MVP fit:
+
+- MVP2
+
+## Suggested Admin IA Alignment
+
+- Dashboard
+- Pages
+- Navigation
+- Media
+- Portfolio
+- Announcements
+- News
+- Commissions
+- Customers
+- Users
+- Settings
diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md
index 533ed9b..5887ea5 100644
--- a/docs/product-engineering/index.md
+++ b/docs/product-engineering/index.md
@@ -10,7 +10,11 @@ This section covers platform and implementation documentation for engineers and
 - [RBAC And Permissions](/product-engineering/rbac-permission-model)
 - [i18n Conventions](/product-engineering/i18n-conventions)
 - [CRUD Examples](/product-engineering/crud-examples)
+- [Package Catalog And Decision Notes](/product-engineering/package-catalog)
+- [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)
+- [Artist CMS Inspiration Notes](/product-engineering/artist-cms-inspiration)
 - [Environment Runbook](/product-engineering/environment-runbook)
 - [Staging Deployment Checklist](/product-engineering/staging-deployment-checklist)
 - [Delivery Pipeline](/product-engineering/delivery-pipeline)
diff --git a/docs/product-engineering/package-catalog.md b/docs/product-engineering/package-catalog.md
new file mode 100644
index 0000000..052b53b
--- /dev/null
+++ b/docs/product-engineering/package-catalog.md
@@ -0,0 +1,153 @@
+# Package Catalog And Decision Notes
+
+## Purpose
+
+Track package decisions in one place:
+
+- what is already used
+- why it is used
+- when to keep/remove/replace
+- which packages are candidates for later MVPs
+
+This file is decision support, not a lockfile replacement.
+
+## Current Core Stack (Used Now)
+
+### Runtime and App Foundation
+
+- `bun`:
+  workspace package manager + runtime for scripts and local dev.
+- `next` + `react` + `react-dom`:
+  app framework for `admin` and `web`.
+- `typescript`:
+  typed contracts across apps/packages.
+
+### Data and Validation
+
+- `prisma` + `@prisma/client` + `pg` + `@prisma/adapter-pg`:
+  DB schema/migrations + typed DB access on PostgreSQL.
+- `zod`:
+  shared runtime validation for domain schemas and CRUD inputs.
+
+### Auth, State, Data Fetching
+
+- `better-auth`:
+  admin auth/session + role metadata baseline.
+- `zustand`:
+  lightweight client state (e.g. locale/UI state).
+- `@tanstack/react-query`:
+  async state/query cache patterns for admin/public app data fetching.
+- `@tanstack/react-form` and `@tanstack/react-table`:
+  form/table primitives in admin workflows.
+
+### UI and Styling
+
+- `tailwindcss` + `@tailwindcss/postcss`:
+  utility-first styling baseline.
+- `class-variance-authority`, `clsx`, `tailwind-merge`:
+  component variant + class composition in `@cms/ui`.
+
+### Testing and Quality
+
+- `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@testing-library/user-event`, `msw`, `jsdom`:
+  unit/integration tests + UI interaction + API mocking.
+- `@playwright/test`:
+  end-to-end tests.
+- `@biomejs/biome`:
+  lint/format/check baseline.
+- `turbo`:
+  monorepo task orchestration.
+
+### Docs and Release Governance
+
+- `vitepress`:
+  docs site.
+- `conventional-changelog-cli`:
+  changelog generation from conventional commits.
+- `@commitlint/cli` + `@commitlint/config-conventional`:
+  commit message schema enforcement.
+
+## Media and Color Processing Notes
+
+### Why `sharp` is typically the default choice
+
+`sharp` is usually the best baseline for server-side image processing because:
+
+- strong performance and memory behavior
+- reliable resize/crop/format conversion pipeline
+- robust support for production workloads
+- good integration in Node/Bun server contexts
+
+Use cases for this CMS:
+
+- generate artwork renditions (thumb/card/full/custom)
+- normalize uploads and output formats
+- create banner/promo safe-size outputs
+- optional watermark compositing pipeline
+
+### Color extraction package options
+
+1. `node-vibrant`
+- Best for: quick dominant palette extraction for UI accents and tagging.
+- Tradeoff: less control over advanced color science.
+
+2. `colorthief`
+- Best for: simple dominant-color extraction with minimal setup.
+- Tradeoff: more limited output and tuning compared to richer libraries.
+
+3. `culori` / `chroma-js` (supporting libs, often combined with extractor)
+- Best for: color manipulation, conversion, contrast checks, palette normalization.
+- Tradeoff: not a full image extractor by itself.
+
+Recommended approach:
+
+- MVP2 start with `sharp` + `node-vibrant` + `culori`
+- keep extraction pipeline behind an internal adapter so replacement is easy
+
+## Candidate Packages For Later (Not Installed Yet)
+
+### File Upload and Storage Abstraction
+
+- `@aws-sdk/client-s3` (+ presign utilities):
+  for S3/R2/object storage adapters and signed upload/download flows.
+- `uploadthing` or custom presigned-upload implementation:
+  faster admin upload UX with secure direct-to-storage path.
+
+### Rich Text / Page Builder
+
+- `tiptap`:
+  rich editorial experience for pages/news.
+- `@dnd-kit/core`:
+  drag-and-drop block ordering/page-builder interactions.
+
+### Media Pipelines / Jobs
+
+- `bullmq` + `ioredis`:
+  background job queue for heavy media transforms (watermark/video/etc).
+
+### Commissions and CRM Extensions
+
+- `@tanstack/react-virtual`:
+  large admin tables (requests/customers) without rendering bottlenecks.
+
+### Observability / Reliability
+
+- `@sentry/nextjs`:
+  app error monitoring.
+- `pino`:
+  structured logs for services/workflows.
+
+## Add/Remove Decision Rules
+
+When adding a package, document:
+
+1. problem it solves
+2. why existing stack is insufficient
+3. expected maintenance/runtime cost
+4. fallback/exit plan
+
+When removing/replacing:
+
+1. list impacted modules
+2. verify tests and migration path
+3. update this catalog and related ADR/docs
diff --git a/docs/product-engineering/user-personas-and-use-cases.md b/docs/product-engineering/user-personas-and-use-cases.md
new file mode 100644
index 0000000..4f8af83
--- /dev/null
+++ b/docs/product-engineering/user-personas-and-use-cases.md
@@ -0,0 +1,116 @@
+# User Personas And Use-Case Topics
+
+## Purpose
+
+Define who uses this CMS and which feature topics matter for each role.  
+This keeps roadmap decisions grounded in real workflows instead of isolated features.
+
+## Primary Personas
+
+### 1. Owner Artist (Primary Operator)
+
+Main goals:
+
+- publish and maintain portfolio website content
+- manage artworks, grouped collections, and featured content
+- open/close commissions and track incoming requests
+
+Core topics:
+
+- pages + navigation builder
+- media library + artwork metadata + renditions
+- announcement/banner management
+- commissions + customer records
+- news/blog updates
+
+### 2. Studio Manager / Assistant
+
+Main goals:
+
+- handle operational content updates and commission administration
+- manage customer communication and request statuses
+
+Core topics:
+
+- commission kanban and request triage
+- customer profile maintenance
+- media organization and moderation
+- limited page edits under role constraints
+
+### 3. Content Editor / Social Manager
+
+Main goals:
+
+- publish updates, news posts, and campaign visuals
+- keep public-facing content fresh without deep admin privileges
+
+Core topics:
+
+- news/blog authoring
+- announcements/promotions
+- selected media uploads and metadata edits
+- landing page block updates (where permitted)
+
+### 4. Technical Support (Protected Role)
+
+Main goals:
+
+- break-glass access for incident support
+- diagnostics and recovery support without owning business content
+
+Core topics:
+
+- support access route/key flow
+- protected account safeguards
+- operational diagnostics and rollback awareness
+
+### 5. Returning Customer (Commission Client)
+
+Main goals:
+
+- submit repeat commission requests with reduced data re-entry
+- track active request state
+
+Core topics:
+
+- customer-linked commission intake
+- commission status visibility
+- communication and requirement updates
+
+### 6. Public Visitor / Collector / Fan
+
+Main goals:
+
+- discover artwork, updates, and commission availability
+- navigate pages and portfolio smoothly
+
+Core topics:
+
+- portfolio browsing (gallery/album/tag/category)
+- announcement visibility
+- news/blog consumption
+- commission request entry points
+
+## Role-to-Feature Responsibility Map
+
+- Owner Artist:
+  all core CMS domains
+- Studio Manager:
+  commissions/customers/media operations
+- Content Editor:
+  editorial/news/announcements + constrained page/media tasks
+- Technical Support:
+  operational support only, no business ownership transfer
+- Public personas:
+  consumption and request flows on public app
+
+## Planning Guidance
+
+When adding a roadmap item, always specify:
+
+1. target persona(s)
+2. primary user outcome
+3. permissions required
+4. public impact (if any)
+
+If an item cannot be mapped to at least one clear persona outcome, it should not be prioritized.