docs(product): add cms feature topics, package catalog, and inspiration notes

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.

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

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)

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

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.