feat: pivot to social media workflow app

docs/LLM_DEVELOPMENT_WORKFLOW.md

@@ -0,0 +1,593 @@
+# LLM Development Workflow
+
+## Purpose
+This document defines how to use coding agents such as Codex, Claude Code, ChatGPT, or similar tools on this repository without losing architectural coherence over time.
+
+The core rule is simple:
+
+> The repository is the source of truth. The chat is only a temporary execution surface.
+
+Coding agents should not rely on long conversation history to understand the product, architecture, or current task. Important context must live in versioned files inside the repository.
+
+## Why This Workflow Exists
+
+LLM coding tools are very strong at creating an initial project or implementing isolated changes. They become less reliable when the work shifts from greenfield generation to incremental product engineering.
+
+The common failure mode is this:
+
+1. The first prompt creates a large amount of useful code.
+2. Later prompts become increasingly specific and corrective.
+3. The agent starts forgetting prior decisions, duplicating patterns, inventing architecture, or changing unrelated files.
+4. Most of the work becomes re-explaining context instead of shipping features.
+
+This does not mean the tools are useless. It means the workflow must change.
+
+Early-stage prompting can be broad. Mature product work must be driven by stable docs, scoped tasks, acceptance criteria, and reviewable diffs.
+
+## Operating Model
+
+Use coding agents as fast implementation partners, not as autonomous product owners.
+
+Agents should:
+
+- read repository documentation first;
+- understand the current task before editing;
+- propose a small implementation plan;
+- make minimal, reviewable changes;
+- preserve existing architecture and conventions;
+- report risks, assumptions, and validation steps.
+
+Agents should not:
+
+- use chat history as the primary source of truth;
+- invent product behavior when docs are missing;
+- perform broad rewrites during a feature task;
+- silently change unrelated files;
+- mix backend, frontend, database, UX, and refactoring work without a scoped plan.
+
+## Repository Documentation Model
+
+The repository should contain a small set of durable documents that agents always consult.
+
+Recommended structure:
+
+```text
+docs/
+  PRODUCT.md
+  ARCHITECTURE.md
+  CONVENTIONS.md
+  DECISIONS.md
+  BACKLOG.md
+  LLM_DEVELOPMENT_WORKFLOW.md
+  tasks/
+    TASK-001-example.md
+    TASK-002-example.md
+AGENTS.md
+```
+
+### `AGENTS.md`
+
+`AGENTS.md` is the entry point for coding agents.
+
+It should tell agents:
+
+- how to work in this repo;
+- what docs to read first;
+- how the backend and frontend are structured;
+- what commands to run;
+- what rules are non-negotiable;
+- how to validate work before finishing.
+
+This file should stay concise enough that agents actually follow it.
+
+### `docs/PRODUCT.md`
+
+Defines the product from the user's perspective.
+
+Include:
+
+- what the product is;
+- target users;
+- major workflows;
+- important UX principles;
+- feature boundaries;
+- what the product explicitly does not do yet.
+
+Use this file to prevent agents from inventing product behavior.
+
+### `docs/ARCHITECTURE.md`
+
+Defines the technical structure.
+
+Include:
+
+- backend architecture;
+- frontend architecture;
+- module boundaries;
+- authentication model;
+- data ownership;
+- routing model;
+- state management model;
+- API integration patterns.
+
+Use this file to prevent agents from inventing new architecture for each task.
+
+### `docs/CONVENTIONS.md`
+
+Defines repeatable implementation patterns.
+
+Include:
+
+- C# style and backend endpoint conventions;
+- FastEndpoints patterns;
+- EF Core migration rules;
+- Vue component conventions;
+- Pinia store conventions;
+- API client usage;
+- validation and error handling patterns;
+- testing expectations;
+- naming conventions.
+
+Use this file to reduce code style drift.
+
+### `docs/DECISIONS.md`
+
+A lightweight architecture decision log.
+
+Each entry should capture:
+
+- date;
+- decision;
+- context;
+- consequences.
+
+Example:
+
+```md
+## 2026-04-23 — Runtime frontend config is centralized
+
+Decision: Frontend runtime configuration must be accessed through `frontend/src/config.js`.
+
+Context: Direct `import.meta.env` reads scattered across feature code make configuration harder to audit.
+
+Consequence: New frontend code should import config from `frontend/src/config.js` instead of reading env variables directly.
+```
+
+Use this file to prevent agents from revisiting settled choices.
+
+### `docs/BACKLOG.md`
+
+A human-readable backlog of possible future work.
+
+Use this for ideas, improvements, bugs, and deferred refactors.
+
+Important rule:
+
+> If an agent sees an adjacent problem that is outside the current task, it should add or suggest a backlog item instead of fixing it opportunistically.
+
+### `docs/tasks/TASK-xxx.md`
+
+Task files are the LLM-friendly equivalent of Jira tickets.
+
+They are not just backend tickets. A product feature is usually fullstack and should describe backend, frontend, UX behavior, data model, validation, and acceptance criteria.
+
+The task file should be specific enough that a fresh agent can implement it without reading a long chat thread.
+
+## Task File Template
+
+Use this template for implementation tasks.
+
+```md
+# TASK-000 — Short Feature Name
+
+## Status
+Draft | Ready | In Progress | Done | Blocked
+
+## Objective
+Describe the user-visible or technical outcome in 1-3 sentences.
+
+## Product Context
+Explain why this exists and where it fits in the product workflow.
+
+## Scope
+- What this task includes.
+- Keep this list concrete.
+
+## Out of Scope
+- What this task explicitly must not include.
+- Add adjacent ideas here to prevent scope creep.
+
+## Existing References
+Agents must inspect these before implementation:
+- `docs/PRODUCT.md`
+- `docs/ARCHITECTURE.md`
+- `docs/CONVENTIONS.md`
+- relevant existing backend files
+- relevant existing frontend files
+
+## Backend Requirements
+### API Contract
+Endpoint:
+- `METHOD /api/example`
+
+Request:
+```json
+{
+  "example": "value"
+}
+```
+
+Response:
+```json
+{
+  "id": "string"
+}
+```
+
+### Validation
+- Rule 1
+- Rule 2
+
+### Data / Persistence
+- Entity changes, if any.
+- DbContext/module affected, if any.
+- Migration required: yes/no.
+
+### Security / Authorization
+- Authentication required: yes/no.
+- Roles or workspace access rules.
+
+## Frontend Requirements
+### Route / Screen
+- Route: `/app/example`
+- View file: `frontend/src/views/app/ExampleView.vue`
+
+### Components
+- `ExampleForm.vue`
+- `ExampleList.vue`
+
+### State Management
+- Pinia store used or created.
+- Existing store actions to reuse.
+
+### API Integration
+- Existing API client usage.
+- Expected loading, success, and error behavior.
+
+### UX Behavior
+- Empty state.
+- Loading state.
+- Validation display.
+- Toasts or inline errors.
+- Navigation after success, if any.
+
+## Files Likely Involved
+Backend:
+- `backend/...`
+
+Frontend:
+- `frontend/...`
+
+Docs:
+- `docs/...`
+
+## Acceptance Criteria
+- User can complete the intended workflow.
+- Backend validates invalid input correctly.
+- Frontend displays loading and error states correctly.
+- Existing auth, workspace scoping, and refresh behavior are preserved.
+- Build passes.
+
+## Validation Plan
+Backend:
+- `cd backend && dotnet build Socialize.Api.csproj`
+- Additional manual or automated checks.
+
+Frontend:
+- `cd frontend && npm run build`
+- Additional manual route/store checks.
+
+## Risks / Edge Cases
+- Risk 1
+- Risk 2
+
+## Open Questions
+- Question 1
+```
+
+## Feature Definition: Fullstack by Default
+
+A feature should normally be defined across these dimensions:
+
+1. Product workflow: what the user is trying to accomplish.
+2. UX behavior: screens, states, feedback, errors, navigation.
+3. Frontend implementation: routes, components, stores, API calls.
+4. Backend implementation: endpoints, validation, persistence, authorization.
+5. Data model: entities, migrations, ownership boundaries.
+6. Acceptance criteria: what must be true before the task is done.
+7. Validation plan: commands and manual checks.
+
+Avoid defining features as backend-only unless the task is explicitly backend-only.
+
+## Recommended Agent Workflow
+
+Use this sequence for non-trivial changes.
+
+### 1. Prepare or update the task file
+
+Create a `docs/tasks/TASK-xxx.md` file before asking an agent to implement a feature.
+
+The task can be rough at first, but it must state:
+
+- objective;
+- scope;
+- out of scope;
+- backend requirements, if any;
+- frontend requirements, if any;
+- acceptance criteria.
+
+### 2. Start a fresh agent thread per task
+
+Do not run an entire project through one endless chat.
+
+Use one thread for one task or one small group of tightly related subtasks.
+
+### 3. Ask for analysis before implementation
+
+Default prompt:
+
+```text
+Read AGENTS.md and the relevant docs first.
+Then read docs/tasks/TASK-000-short-name.md.
+Do not edit files yet.
+Summarize the task, identify the relevant backend and frontend files, list risks, and propose a minimal implementation plan.
+```
+
+### 4. Implement one bounded step at a time
+
+Default prompt:
+
+```text
+Implement only step 1 from the plan.
+Keep the diff minimal.
+Do not refactor unrelated code.
+Do not change public behavior outside this task.
+At the end, summarize changes and list validation steps.
+```
+
+### 5. Review the diff
+
+The repository owner reviews:
+
+- scope creep;
+- architectural drift;
+- duplicated code;
+- inconsistent UI behavior;
+- unsafe auth or workspace scoping changes;
+- broken conventions.
+
+### 6. Validate
+
+Run the relevant commands from `AGENTS.md` and the task file.
+
+Minimum expected validation:
+
+- backend build for backend changes;
+- frontend build for frontend changes;
+- affected user flow checked manually when UI behavior changes.
+
+### 7. Update docs if the task changed architecture or product behavior
+
+If implementation creates a durable decision, update `docs/DECISIONS.md`.
+
+If implementation changes structure, update `docs/ARCHITECTURE.md`.
+
+If implementation changes conventions, update `docs/CONVENTIONS.md`.
+
+If implementation changes user-facing behavior, update `docs/PRODUCT.md`.
+
+## Prompt Patterns
+
+### Planning Prompt
+
+```text
+You are working in an existing repository.
+
+First read:
+- AGENTS.md
+- docs/PRODUCT.md
+- docs/ARCHITECTURE.md
+- docs/CONVENTIONS.md
+- docs/DECISIONS.md
+- docs/tasks/TASK-000-short-name.md
+
+Do not edit files yet.
+
+Return:
+1. summary of the task;
+2. relevant existing files;
+3. backend impact;
+4. frontend impact;
+5. risks and ambiguities;
+6. minimal implementation plan;
+7. validation plan.
+```
+
+### Implementation Prompt
+
+```text
+Implement the task from docs/tasks/TASK-000-short-name.md.
+
+Rules:
+- follow AGENTS.md;
+- follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md;
+- keep the diff minimal;
+- do not refactor unrelated code;
+- preserve auth, workspace scoping, token refresh, and runtime config patterns;
+- if you discover missing requirements, stop and report them instead of inventing behavior.
+
+At the end, provide:
+- files changed;
+- summary of behavior added;
+- validation performed;
+- validation still needed;
+- risks or follow-up items.
+```
+
+### Frontend-Only Prompt
+
+```text
+Implement only the frontend part of docs/tasks/TASK-000-short-name.md.
+
+Do not modify backend code.
+Use existing routes, stores, API client, UI framework, and runtime config conventions.
+Preserve loading, error, empty, and success states described in the task.
+```
+
+### Backend-Only Prompt
+
+```text
+Implement only the backend part of docs/tasks/TASK-000-short-name.md.
+
+Do not modify frontend code.
+Follow the existing FastEndpoints, validation, module, DbContext, and migration conventions.
+Preserve auth and workspace scoping rules.
+```
+
+### Review Prompt
+
+```text
+Review the current diff against:
+- AGENTS.md
+- docs/ARCHITECTURE.md
+- docs/CONVENTIONS.md
+- docs/tasks/TASK-000-short-name.md
+
+Look specifically for:
+- scope creep;
+- architectural drift;
+- broken frontend state patterns;
+- broken backend module boundaries;
+- auth or workspace scoping regressions;
+- missing loading/error states;
+- missing validation;
+- missing tests or manual checks.
+
+Do not edit files. Return findings only.
+```
+
+## Rules for Frontend Work
+
+Frontend changes must be explicit in the task.
+
+A frontend task should identify:
+
+- route or screen;
+- components to create or modify;
+- Pinia stores involved;
+- API calls involved;
+- loading state;
+- error state;
+- empty state;
+- success feedback;
+- navigation behavior;
+- role/access behavior;
+- responsive or layout expectations, if relevant.
+
+Agents must not invent a new frontend architecture for a single feature.
+
+They should reuse:
+
+- existing Vue patterns;
+- existing Vuetify/Tailwind conventions;
+- existing Pinia stores where appropriate;
+- existing Axios client;
+- existing router guards;
+- existing toast/error patterns.
+
+## Rules for Backend Work
+
+Backend changes must respect module boundaries.
+
+A backend task should identify:
+
+- endpoint route and method;
+- request and response shape;
+- validation rules;
+- module ownership;
+- DbContext affected;
+- migration requirement;
+- authorization rules;
+- workspace scoping rules;
+- expected errors.
+
+Agents must not couple module DbContexts or bypass existing auth/security helpers.
+
+## Handling Ambiguity
+
+When a requirement is unclear, agents should not silently invent behavior.
+
+Preferred behavior:
+
+1. State the ambiguity.
+2. Propose the safest default.
+3. Keep implementation narrow.
+4. Add an open question or backlog item if needed.
+
+For small ambiguities that do not affect architecture or product behavior, the agent may choose the safest existing pattern and document the assumption.
+
+For large ambiguities, the agent should stop before implementation.
+
+## Handling Refactors
+
+Refactors should be separate tasks unless they are strictly required for the current feature.
+
+If a refactor is needed, the task should state:
+
+- why the refactor is necessary;
+- what files are in scope;
+- what behavior must remain unchanged;
+- how to validate no regression occurred.
+
+Agents should not do opportunistic cleanup in unrelated files.
+
+## Handling Backlog Items
+
+When an agent notices an issue outside scope, it should not fix it by default.
+
+It should report it as:
+
+```md
+Suggested backlog item:
+- Title:
+- Reason:
+- Affected files:
+- Risk if ignored:
+```
+
+The repository owner can then decide whether to create a task.
+
+## Definition of Done
+
+A task is done when:
+
+- implementation matches the task file;
+- scope and out-of-scope boundaries were respected;
+- relevant backend and/or frontend validation passed;
+- user-facing behavior was manually checked when applicable;
+- docs were updated if durable behavior or architecture changed;
+- remaining risks or follow-up items were explicitly listed.
+
+## Practical Mental Model
+
+Use this model:
+
+- `AGENTS.md` tells the agent how to behave.
+- `docs/PRODUCT.md` tells the agent what the product is.
+- `docs/ARCHITECTURE.md` tells the agent how the system is shaped.
+- `docs/CONVENTIONS.md` tells the agent how to write code here.
+- `docs/DECISIONS.md` tells the agent what choices are already settled.
+- `docs/BACKLOG.md` stores ideas that are not current work.
+- `docs/tasks/TASK-xxx.md` tells the agent what to do now.
+
+The more this information lives in the repo, the less each new prompt has to reconstruct the project from memory.

docs/README.md

@@ -0,0 +1,32 @@
+# Docs
+
+This folder contains the project documentation used to guide product, implementation, and architecture work.
+
+## Current Product Docs
+
+- [product/vision.md](/home/jbourdon/repos/social-media/docs/product/vision.md): current product intent, users, scope, and priorities.
+- [product/glossary.md](/home/jbourdon/repos/social-media/docs/product/glossary.md): canonical domain vocabulary. Prefer these terms in code, UI copy, and specs.
+- [constraints.md](/home/jbourdon/repos/social-media/docs/constraints.md): business and technical invariants that should not be violated casually.
+
+## Current Delivery Docs
+
+- [use-cases/review-workflows.md](/home/jbourdon/repos/social-media/docs/use-cases/review-workflows.md): scenario-driven workflow descriptions.
+- [specs/content-approval-workflow.md](/home/jbourdon/repos/social-media/docs/specs/content-approval-workflow.md): structured feature spec for the primary workflow.
+- [specs/TEMPLATE.md](/home/jbourdon/repos/social-media/docs/specs/TEMPLATE.md): template for future feature specs.
+
+## Decision Records
+
+- [decisions/README.md](/home/jbourdon/repos/social-media/docs/decisions/README.md): ADR conventions and when to add a decision record.
+- [decisions/ADR-TEMPLATE.md](/home/jbourdon/repos/social-media/docs/decisions/ADR-TEMPLATE.md): template for new architecture or product decisions.
+
+## Archived
+
+- [archive/PLAN.md](/home/jbourdon/repos/social-media/docs/archive/PLAN.md): early pivot plan; useful for historical context, but stale as an execution checklist.
+- [archive/SOCIALIZE.md](/home/jbourdon/repos/social-media/docs/archive/SOCIALIZE.md): original consolidated product brief before the docs were split into focused source-of-truth files.
+- [archive/Stripe.md](/home/jbourdon/repos/social-media/docs/archive/Stripe.md): legacy Hutopy monetization notes for memberships and tips.
+- [archive/WORKSHEET.md](/home/jbourdon/repos/social-media/docs/archive/WORKSHEET.md): historical implementation worksheet from an earlier transition phase.
+
+## Root Docs
+
+- [README.md](/home/jbourdon/repos/social-media/README.md): repository overview and local development setup.
+- [AGENTS.md](/home/jbourdon/repos/social-media/AGENTS.md): working guide for coding agents. This stays at repo root intentionally.

docs/archive/PLAN.md

@@ -0,0 +1,431 @@
+# PLAN
+
+> Historical planning snapshot. This document reflects the early product-pivot plan and is not the source of truth for the current implementation state.
+
+## Purpose
+
+This document defines the build plan to close the gap between the current codebase and the target product described in [SOCIALIZE.md](/home/jbourdon/repos/social-media/docs/archive/SOCIALIZE.md).
+
+The current repository is a dead `Hutopy` codebase. The target product, temporarily named `Socialize`, is a workflow application for social media content review, revision, approval, and readiness for publication.
+
+This is a full product pivot, not a gradual feature expansion.
+
+## Goal
+
+Build a product that becomes the system of workflow for:
+
+- internal content review
+- provider collaboration
+- client approval
+- version tracking
+- audit trail
+- notification-driven progress
+- publication readiness handoff
+
+The first version should solve the approval pain cleanly before deeper integrations or scheduling features are added.
+
+## Gap Summary
+
+### Current Codebase
+
+The current repository contains:
+
+- backend modular structure with FastEndpoints and Entity Framework Core
+- authentication and infrastructure foundations
+- file storage patterns
+- frontend Vue application shell
+- legacy business modules centered on creators, tipping, memberships, and creator-facing experiences
+
+### Target Product
+
+The target product needs:
+
+- workspace and client management
+- provider and internal team collaboration
+- content item lifecycle management
+- asset and revision tracking
+- comments and approval workflow
+- workflow events and notifications
+- client-facing review portal
+- Google Drive-centered asset ownership
+- billing readiness for a future Software as a Service offering
+
+### Core Gap
+
+The codebase has technical scaffolding that can be reused, but the business domain is largely wrong for the target product.
+
+The main gap is not infrastructure. The main gap is domain shape, frontend surface, and workflow behavior.
+
+## Build Principles
+
+1. Reuse technical foundations when they help, but do not keep old business concepts for convenience.
+2. Keep the modular backend structure.
+3. Prefer clean domain language from day one over transitional naming.
+4. Build around Google Drive ownership first, not direct-upload-first assumptions.
+5. Deliver one vertical workflow before broad integrations.
+6. Remove legacy Hutopy product concepts early to reduce semantic drag.
+7. Keep changes reviewable and validate each phase before widening scope.
+
+## Keep, Replace, Remove
+
+### Keep
+
+- ASP.NET Core backend shell
+- FastEndpoints setup
+- modular registration pattern
+- Entity Framework Core with per-module context where useful
+- infrastructure wiring
+- authentication foundation if it can be adapted cleanly
+- payment infrastructure patterns and Stripe integration capability for future billing
+- blob or file-handling patterns that still apply
+- Vue, Vite, Pinia, router, and API client shell
+- deployment workflows if still useful for the new product
+
+### Replace
+
+- domain module set
+- route design
+- data model
+- frontend information architecture
+- user flows
+- branding and product language
+
+### Remove
+
+- creator domain concepts
+- creator public profile features
+- creator monetization flows
+- Hutopy naming across code and frontend copy
+- dead UI components and stores tied only to the old product
+
+### Retire And Rebuild
+
+- old tipping business flows
+- old membership business flows
+- creator-specific Stripe onboarding flows
+- payment routes and models that are tightly coupled to the dead Hutopy business model
+
+Keep the underlying payment capability, but rebuild the business-facing billing model around the new product when pricing and subscription design are ready.
+
+## Target Product Scope For Version 1
+
+Version 1 should own this workflow:
+
+1. Internal team creates a content item.
+2. Assets are linked from Google Drive.
+3. Publication message and metadata are attached.
+4. Internal reviewer or provider receives a request.
+5. Comments and revisions happen in one place.
+6. Client receives a review request.
+7. Client approves, rejects, or requests changes.
+8. Item becomes ready for publishing handoff.
+
+Not version 1:
+
+- full scheduling engine
+- full social publishing
+- advanced third-party synchronization
+- analytics suite
+- full digital asset management platform
+- full creative production tooling
+- customer billing and subscription management user flows
+
+## Target Backend Module Map
+
+Recommended backend modules:
+
+- `Identity`
+  - users, authentication, internal roles
+- `Workspaces`
+  - agencies or operating teams
+- `Clients`
+  - brands, creators, businesses served by a workspace
+- `Providers`
+  - external production partners
+- `Projects`
+  - grouped bodies of work for a client, which may later contain campaign concepts if needed
+- `ContentItems`
+  - reviewable units with metadata, copy, due dates, and status
+- `Assets`
+  - asset references, Google Drive linkage, versions, previews
+- `Approvals`
+  - review requests, approvers, decisions, status transitions
+- `Comments`
+  - threads, replies, resolution state, contextual discussion
+- `Notifications`
+  - workflow events, reminders, delivery preferences
+
+Possible later modules:
+
+- `Campaigns`
+- `Calendars`
+- `Integrations`
+- `Publishing`
+- `Analytics`
+- `Billing`
+
+## Target Frontend Surface
+
+Recommended frontend areas:
+
+- authentication
+- workspace switcher or workspace context
+- client list
+- project list
+- review queue dashboard
+- content item detail page
+- revision and comment timeline
+- approval status panel
+- notification center
+- external client review portal
+
+Later frontend areas:
+
+- calendar view
+- integration settings
+- publishing handoff dashboard
+- workflow analytics
+
+## Proposed Data Backbone
+
+### Content Item
+
+A content item should carry:
+
+- title
+- publication message
+- notes
+- project
+- client
+- creator or brand context where relevant
+- publication targets
+- publication dates by network when relevant
+- due date
+- current status
+- current active revision set
+
+### Asset
+
+An asset should carry:
+
+- asset type
+- source type
+- Google Drive file reference
+- preview metadata
+- current version
+- version history
+
+### Approval Request
+
+An approval request should carry:
+
+- target content item
+- requested reviewers
+- stage type
+- sent at
+- due at
+- decision state
+- decision history
+
+### Notification Event
+
+A notification event should carry:
+
+- event type
+- triggered by
+- target entity
+- recipients
+- delivery status
+- timestamps
+
+## Execution Strategy
+
+### Phase 0: Freeze Product Direction
+
+Deliverables:
+
+- validated worksheet in English
+- optional French mirror of the worksheet
+- agreed module map
+- agreed version 1 scope and anti-scope
+
+Exit criteria:
+
+- no ambiguity about the first workflow to build
+- no unresolved disagreement about Google Drive ownership
+
+### Phase 1: Remove Legacy Product Surface
+
+Goals:
+
+- reduce confusion from Hutopy concepts
+- make the codebase ready for the new domain
+
+Work:
+
+- remove or retire legacy frontend views tied to creators, tipping, and memberships
+- remove legacy backend modules that are clearly dead
+- rename product-facing strings, assets, and configuration references
+- identify infrastructure pieces that stay
+- preserve Stripe and payment infrastructure that can support future Software as a Service billing
+- identify backend modules that should be replaced instead of adapted
+
+Exit criteria:
+
+- codebase no longer communicates the old product direction
+- remaining code clearly supports reuse or is queued for replacement
+
+### Phase 2: Establish New Domain Skeleton
+
+Goals:
+
+- introduce the new product vocabulary into code
+- prepare clean module boundaries
+
+Work:
+
+- create new backend modules
+- define initial entities and contexts
+- wire modules in `Program.cs`
+- define route namespaces and tags
+- create frontend route skeleton for the new product
+- define new stores for auth, workspace context, review queue, and content items
+
+Exit criteria:
+
+- application compiles with the new module map in place
+- legacy domain is no longer the center of the app
+
+### Phase 3: Build The First Vertical Slice
+
+Vertical slice:
+
+- create content item
+- link Google Drive asset
+- add publication message and publication target data
+- request internal review
+- comment on item
+- request changes
+- upload or register a new revision
+- request client review
+- approve from client portal
+- mark ready to publish
+
+Backend work:
+
+- commands and queries for content item creation and retrieval
+- asset linkage and versioning
+- comment creation and retrieval
+- approval request and decision endpoints
+- status transition logic
+- workflow event emission
+
+Frontend work:
+
+- content item creation flow
+- content item detail view
+- comments panel
+- approval action UI
+- status timeline
+- simple client review page
+
+Exit criteria:
+
+- one item can move end-to-end from draft to approved
+- all actions are traceable in one place
+
+### Phase 4: Add Notification Backbone
+
+Goals:
+
+- make workflow movement visible without manual follow-up
+
+Work:
+
+- define notification event types
+- trigger events on comments, revisions, requests, and decisions
+- add email notifications
+- add in-app notification center or lightweight feed
+- add reminder jobs for pending reviews
+
+Exit criteria:
+
+- users are informed when workflow events occur
+- delayed approvals can be followed without manual chasing
+
+### Phase 5: Harden Version 1 For Real Usage
+
+Goals:
+
+- make the workflow usable for the first real client
+
+Work:
+
+- permissions and role hardening
+- validation and error handling
+- audit trail review
+- filtering and dashboard improvements
+- comment resolution
+- required approver logic if needed
+- publication dates by network support
+- quality pass on mobile review experience
+
+Exit criteria:
+
+- the first client can run a real approval cycle in the product
+
+### Phase 6: Evaluate Phase 2 Expansion
+
+Candidates:
+
+- calendar visibility
+- Google Drive sync improvements
+- Canva linkage
+- MailChimp approval path
+- scheduler handoff integrations
+- billing and subscription management for the Software as a Service offer
+
+Rule:
+
+Only start these after version 1 workflow is demonstrably useful.
+
+## Immediate Technical Tasks
+
+Recommended next implementation tasks:
+
+1. Rename the product and remove visible Hutopy branding.
+2. Inventory which backend modules are deleted versus replaced.
+3. Define the new backend module directories and initial project structure.
+4. Replace the frontend router with the new application surface.
+5. Model `ContentItem`, `Asset`, `AssetVersion`, `ApprovalRequest`, `ApprovalDecision`, `CommentThread`, and `NotificationEvent`.
+6. Implement the first vertical slice end to end.
+
+## Risks
+
+- scope creep into scheduling and publishing too early
+- forcing the new domain into old creator-centric structures
+- under-designing workflow status and revision semantics
+- overbuilding integrations before the core workflow is proven
+- making external review too heavy for clients
+
+## Validation Checklist
+
+Before claiming version 1 readiness:
+
+- a workspace can manage at least one client
+- a content item can include publication message and publication targets
+- assets can be linked from Google Drive
+- internal review can request changes
+- client review can approve or reject
+- status history is visible
+- notification events are triggered
+- the latest approved state is clear
+
+## Working Note
+
+This plan should be updated as soon as the first implementation decisions are made, especially:
+
+- exact module names
+- exact database boundaries
+- whether `Providers` stands alone or is modeled as a participant role
+- whether notifications are their own module or an infrastructure concern

docs/archive/SOCIALIZE.md

@@ -0,0 +1,328 @@
+# Social Media Approval Workflow
+
+Temporary product name: `Socialize`
+
+## Project Intent
+
+Build `Socialize`, an application that replaces the current approval process based on Google Drive, phone calls, emails, and spreadsheets.
+
+The product is not a public social network. It is an internal/external workflow tool for content review, feedback, approval, and publication readiness.
+
+## Shared Vocabulary
+
+- Approval workflow: the end-to-end process from draft creation to final approval.
+- Content item: the reviewable unit that bundles assets, publication message or copy, dates, and channel targets.
+- Asset: a file attached to a content item, such as a video, image, or document.
+- Revision: a new version of an asset or copy after feedback.
+- External reviewer: a client or partner who reviews content without being part of the internal team.
+- Provider: an external production partner, such as a film crew, photographer, editor, or designer, who may deliver drafts and receive change requests.
+- Software as a Service (SaaS): a cloud-based product used through the web, such as Canva, MailChimp, HootSuite, or Metricool.
+- Minimum Viable Product (MVP): the smallest product version that solves the main pain point well enough to validate the market.
+- Service Level Agreement (SLA): an agreed service target, such as a review deadline or escalation threshold.
+
+## Problem Statement
+
+Social media managers and production teams currently manage content approvals manually:
+
+- Assets are stored in Google Drive.
+- The social media manager may have back-and-forth with both upstream providers and downstream clients.
+- Feedback is exchanged by phone, email, messages, and spreadsheets.
+- Version history is unclear.
+- It is hard to know which file is the latest one.
+- Comments are scattered across multiple channels.
+- Internal approvals and client approvals follow similar patterns but are not centralized.
+- Follow-ups are manual, so approvals get delayed.
+
+Result: too much back-and-forth, poor traceability, avoidable delays, and risk of publishing the wrong asset or outdated copy.
+
+## Existing Tools Observed
+
+- Google Drive for videos, images, calendars, and documents
+- Google Sheets or similar for tracking comments and status
+- Phone and email for review/approval conversations
+- HootSuite
+- Metricool
+- Canva
+- MailChimp
+
+## Primary Users
+
+- Social media manager
+- Account manager / customer success
+- Client approver
+- External provider / production partner
+- Internal producer
+- Internal employee / content contributor
+- Administrator
+
+## Core Use Cases
+
+### 1. Client Approval Workflow
+
+A social media manager prepares content for a client and sends it for approval.
+
+The client should be able to:
+
+- view the content package
+- preview files
+- read captions, descriptions, and project notes
+- leave comments
+- request changes
+- approve or reject
+
+The team should be able to:
+
+- see approval status in real time
+- answer comments in context
+- upload revised versions
+- keep a clear audit trail of who said what and when
+- know exactly which version is approved
+
+### 2. Internal Production Workflow
+
+The same workflow should work internally for producers, employees, and external production partners before the content is shown to the client or scheduled for publishing.
+
+Example:
+
+- contributor uploads draft
+- external provider can upload draft or revised media
+- producer reviews and requests changes
+- manager approves for client review
+- client approves
+- content is marked ready to publish
+
+### 3. Content Package Review
+
+Approval should not be limited to a single file. A review item may include:
+
+- video
+- image
+- document
+- publication message / caption / copy
+- hashtags
+- links
+- publication dates
+- target channels or social networks
+
+## Current Workflow Summary
+
+Typical current flow:
+
+1. Team creates media assets.
+2. Files are placed in Google Drive by the team or by external providers.
+3. A manager sends links by email or message to providers, internal stakeholders, or clients.
+4. Feedback comes back by phone, email, spreadsheet, or chat.
+5. Team manually consolidates comments across provider feedback and client feedback.
+6. A revised version is uploaded.
+7. The cycle repeats until someone says it is approved.
+8. Approval status is manually tracked elsewhere.
+
+Main failure points:
+
+- no single source of truth
+- no structured approval states
+- no centralized threaded comments
+- no deadline reminders
+- no reliable audit trail
+- no approval gate before publishing
+
+## Target Workflow
+
+1. Create a project and associate it with a client.
+2. Create a review item or approval request.
+3. Attach assets or import them from Google Drive.
+4. Add metadata:
+   - title
+   - publication message / caption / copy
+   - target platform or social network
+   - publication dates by network when relevant
+   - due date
+   - reviewer(s)
+5. Send review request.
+6. Reviewers comment directly on the item.
+7. Team or provider uploads a revision or responds to comments.
+8. System tracks versions, status changes, and workflow events.
+9. Reviewer approves, rejects, or requests changes.
+10. Once all required approvals are complete, item becomes ready for scheduling/publishing.
+
+## Core Domain Objects
+
+- Workspace: the top-level account boundary for one agency or one operating team.
+- Client: the business, creator, or brand receiving the service and approving content.
+- Team member: an internal user working on content, reviews, or coordination.
+- Reviewer: any person asked to review and approve, whether internal or external.
+- Provider: an external production contributor such as a photographer, videographer, editor, or designer.
+- Project: the main work container for a client, grouping related content items, notes, participants, and timelines.
+- Content item: the reviewable unit that contains assets, publication message, channel targets, due dates, and approval state.
+- Asset: an attached file, such as a video, image, or document, referenced from Google Drive or stored directly.
+- Asset version: a specific revision of an asset, with traceability to who uploaded it and when.
+- Comment thread: a contextual discussion attached to a content item, asset, or revision.
+- Approval request: the act of asking one or more reviewers to review a specific version.
+- Approval decision: the outcome of a review request, such as approved, rejected, or changes requested.
+- Status history: the audit trail of workflow states and transitions over time.
+- Publication target: the intended destination for publication, such as Instagram, Facebook, LinkedIn, or a newsletter.
+- Notification event: a workflow event that informs users something changed, such as a new comment, revision, request, or approval.
+
+## Suggested Status Model
+
+- Draft
+- In internal review
+- Changes requested internally
+- Internal changes in progress
+- Ready for client review
+- In client review
+- Changes requested by client
+- Client changes in progress
+- Approved
+- Rejected
+- Ready to publish
+- Published
+- Archived
+
+## Minimum Viable Product (MVP) Scope
+
+The first version should focus on approval workflow, not direct publishing.
+
+### MVP Features
+
+- authentication and user roles
+- workspace/client/project structure
+- create a content item with metadata
+- upload assets or attach Google Drive links while keeping Google Drive as the source of truth when required by the client
+- version tracking for files and copy
+- centralized comments
+- approval decisions: approve, reject, request changes
+- activity timeline / audit trail
+- status dashboard by client, project, and due date
+- notifications and reminders when actions are completed or workflow events occur
+- simple approval portal for external clients
+
+### Strong MVP Candidate Features
+
+- required approvers
+- approval deadline
+- due dates per publication target or social network
+- compare current version vs previous version
+- "latest approved version" indicator
+- comment resolution
+- filtering by status, client, assignee, due date
+
+## Phase 2 Opportunities
+
+- Google Drive integration with file sync/import
+- HootSuite / Metricool export or handoff
+- Canva asset linking
+- MailChimp approval workflow for newsletters
+- calendar integration for publication planning visibility
+- annotated comments on images or video timestamps
+- reusable approval templates by content type
+- Service Level Agreement (SLA) reminders and escalations
+- analytics on turnaround time and bottlenecks
+- approval by email link
+- multi-stage approval rules per client
+
+## Key Automation Opportunities
+
+- auto-request approval when a content item reaches a defined stage
+- automatic notifications when a workflow action is completed or a workflow event occurs
+- automatic reminders before approval deadlines
+- automatic escalation when approval is overdue
+- automatic version labeling
+- automatic "ready to publish" state when all approvals are complete
+- automatic audit trail for every upload, comment, and decision
+- automatic client-facing review link generation
+- automatic notification when a new revision addresses requested changes
+
+## Important Product Decisions
+
+### 1. System of record for assets
+
+Options:
+
+- keep Google Drive as file storage and build workflow around it
+- upload files directly into this new application
+- support both
+
+Recommended first assumption:
+
+Keep Google Drive as the source of truth when the client requires ownership there, and support direct uploads later as an option. The first version should work cleanly with Drive links and imported metadata before deeper synchronization is considered.
+
+### 2. External reviewer experience
+
+Options:
+
+- reviewer account required
+- magic-link access without full account
+- both
+
+Recommended first assumption:
+
+Use magic-link review access for clients to reduce friction.
+
+### 3. Approval granularity
+
+Possible approval units:
+
+- entire content item
+- per asset
+- per caption/copy
+- per channel variation
+
+Recommended first assumption:
+
+Approve at the content item level in the Minimum Viable Product (MVP), with comments attached to assets and copy.
+
+## Business Rules To Confirm
+
+These do not block initial scoping, but we should capture them early so the product behavior matches the real approval process.
+
+- Can a client approve with unresolved comments?
+- Does approval require one reviewer or multiple reviewers?
+- Can internal approval and client approval happen in parallel?
+- Is approval valid only for the latest version?
+- Can an approved item be edited without reopening review?
+- Do different clients require different workflows?
+- Are videos, images, and documents all equally important on day one?
+- Is scheduling/publishing inside scope, or only "approval-ready" handoff?
+
+## Open Questions For Next Interview
+
+- Who is the buyer: agency, freelancer, or in-house marketing team?
+- Is the first target market agency-to-client approval, internal team approval, or both?
+- What content types are highest priority: video, image, documents, captions, newsletters?
+- How often do clients request changes after verbal approval?
+- What is the most painful step today?
+- What tools must remain in place at launch?
+- What approvals need legal or compliance traceability?
+- How many reviewers usually participate per item?
+- Is bilingual support required?
+- Is mobile review important on day one?
+
+## Minimum Viable Product (MVP) Success Criteria
+
+- reduce approval turnaround time
+- reduce back-and-forth across email/phone/spreadsheets
+- give one clear source of truth for latest version and current status
+- let a client approve without training
+- let the team see blocked items instantly
+
+## Product Positioning
+
+This product should be positioned as:
+
+"A review and approval workflow for social media content, not another content creation tool."
+
+The value is coordination, traceability, and faster approval cycles.
+
+## First Build Recommendation
+
+Build the first release around this narrow flow:
+
+1. team creates content item
+2. team uploads files and copy
+3. internal reviewer comments and requests changes
+4. team submits to client
+5. client comments and approves via simple link
+6. item becomes ready for publishing handoff
+
+If this flow works cleanly, integrations and scheduling can be added later.

docs/archive/Stripe.md

@@ -0,0 +1,32 @@
+# Stripe
+
+> Legacy Hutopy-era notes. These flows describe the old creator membership and tipping model and do not match the current workflow product.
+
+## Events Workflow
+
+### Membership
+
+1. checkout.session.completed	    
+  - Store StripeSubscriptionId, UserId, CreatorId, TierId
+  - Save a new Subscription entity with the status "Pending"
+
+2. invoice.payment_succeeded        
+  - Grant access (set Subscription.Active = true or similar)
+  - Record transaction or set StartDate
+  - Notify Creator (e.g., new member)
+
+3. customer.subscription.updated    
+  - Update `EndDate = CancelAt ?? CanceledAt`
+
+4. customer.subscription.deleted	
+  - Revoke access
+  - Mark Subscription as inactive/ended
+
+### Tips
+
+1. checkout.session.completed	    
+  - Store TipId, StripeSessionId, TipperId, CreatorId
+  - PaymentIntentStatus == "paid"
+  - Status = "Paid"
+  - Notify creator
+  - Record transaction

docs/archive/WORKSHEET.md

@@ -0,0 +1,35 @@
+> Historical worksheet from the product-pivot phase. Several items are completed, renamed, or superseded by the current codebase.
+
+What is left to do:
+
+  1. Replace frontend seeded stores with real API-backed stores.
+  2. Build authenticated loading for:
+      - workspaces
+      - clients
+      - projects
+      - content items
+  3. Add create flows:
+      - create workspace
+      - create client
+      - create project
+      - create content item
+  4. Build the first real content-item detail page.
+  5. Add the actual approval workflow domain:
+      - approval requests
+      - approval decisions
+      - status transitions
+  6. Add comments and revision tracking.
+  7. Add Google Drive asset linkage instead of placeholder source fields only.
+  8. Add notification/event backbone.
+  9. Remove or retire old Hutopy modules and routes once the new vertical slice replaces them.
+  10. Rename remaining Hutopy namespaces/product strings in the backend if you want the codebase semantics
+     cleaned up now instead of later.
+
+
+  So the main remaining substantive work is:
+
+1. finish full-site localization
+2. build real integrations backend for Google Drive and API keys
+3. deepen workspace/settings management
+4. continue workflow polish and broader comment/thread modeling if you want that
+   generalized again

docs/constraints.md

@@ -0,0 +1,44 @@
+# Constraints
+
+These are cross-cutting rules for the current product and codebase. They are intended to reduce ambiguity for both humans and AI agents.
+
+## Product Constraints
+
+- The product is a workflow tool, not a public social network.
+- Internal review and client review should be modeled as related workflow stages, not isolated products.
+- Content approval must preserve traceability of comments, revisions, decisions, and status changes.
+- “Ready to publish” should only be reachable from an explicit workflow state transition, not inferred casually in UI code.
+
+## Domain Constraints
+
+- `Workspace` is the top-level scoping boundary.
+- An agency may manage multiple workspaces.
+- `ContentItem` belongs to a workspace scope.
+- Comments, approvals, assets, and notifications must remain traceable to the underlying workflow entity they relate to.
+
+## Backend Constraints
+
+- Keep module boundaries intact. Do not couple DbContexts across modules.
+- When adding schema changes, create migrations in the owning module only.
+- Follow the existing FastEndpoints handler pattern with explicit route and tag metadata.
+- Preserve development HTTP behavior locally; HTTPS redirection is not enabled in development.
+
+## Frontend Constraints
+
+- Frontend runtime config must flow through `frontend/src/config.js`.
+- Do not add feature-level `import.meta.env` reads.
+- Avoid introducing fallback env chains that create multiple configuration sources of truth.
+- Preserve token refresh concurrency protections in `authStore` and the API client.
+- Preserve route-level auth and role checks unless the product requirement explicitly changes.
+
+## Documentation Constraints
+
+- One topic should have one current source of truth.
+- Historical docs must be marked archived or legacy.
+- Specs should distinguish current behavior from proposed behavior.
+- Open questions should be listed explicitly rather than hidden in narrative text.
+
+## Naming Constraints
+
+- Prefer current product/domain language over Hutopy-era terminology.
+- Avoid reviving creator/tipping/membership concepts unless intentionally rebuilding them for the new product.

docs/decisions/ADR-TEMPLATE.md

@@ -0,0 +1,31 @@
+# ADR-XXX: Title
+
+## Status
+
+Proposed | Accepted | Superseded
+
+## Context
+
+What problem or choice exists?
+
+## Options Considered
+
+### Option 1
+
+- pros
+- cons
+
+### Option 2
+
+- pros
+- cons
+
+## Decision
+
+State the chosen option clearly.
+
+## Consequences
+
+- positive consequence
+- tradeoff
+- follow-up implication

docs/decisions/README.md

@@ -0,0 +1,26 @@
+# Decisions
+
+Use this folder for Architecture Decision Records (ADRs) and similarly durable implementation/product decisions.
+
+Add a decision record when:
+
+- a choice is likely to be revisited later
+- multiple plausible options exist
+- the team wants to preserve why a decision was made
+- future agents or developers could otherwise repeat the same debate
+
+Typical decision topics:
+
+- external review access model
+- Google Drive integration strategy
+- workflow status model
+- notification delivery model
+- module boundaries
+- approval rules
+
+Keep decisions short and explicit:
+
+- context
+- options considered
+- chosen option
+- consequences

docs/product/glossary.md

@@ -0,0 +1,120 @@
+# Product Glossary
+
+Use these terms consistently in product docs, specs, UI copy, and code discussions.
+
+## Workspace
+
+Top-level working container for a client account.
+
+An agency may manage multiple workspaces.
+
+Use:
+
+- ownership boundary
+- membership boundary
+- scoping boundary for content items, assets, comments, approvals, and notifications
+
+Do not use as:
+
+- synonym for internal role
+- synonym for team member role
+
+## Agency
+
+Operating organization managing one or more workspaces.
+
+An agency is above the workspace level in the business model.
+
+## Client
+
+Business, brand, or organization represented by a workspace and participating in review and approval flows.
+
+## Content Item
+
+Primary reviewable unit in the system. Contains metadata, copy, due dates, networks, channels, and linked assets.
+
+Examples:
+
+- one Instagram reel package
+- one newsletter draft
+- one campaign asset for approval
+
+## Asset
+
+A file or file reference attached to a content item, such as a video, image, or document.
+
+## Asset Revision
+
+Specific version of an asset with traceability to who linked or uploaded it and when.
+
+## Approval Workflow
+
+End-to-end process from draft creation to final approval and publishing handoff.
+
+## Approval Request
+
+Explicit request for one or more reviewers to review a specific content item or revision state.
+
+## Approval Decision
+
+Decision recorded by a reviewer, such as:
+
+- approved
+- rejected
+- changes requested
+
+## Reviewer
+
+Any person asked to review and approve work, whether internal or external.
+
+## External Reviewer
+
+Client or partner reviewing content without being part of the internal operating team.
+
+## Provider
+
+External production contributor such as a photographer, videographer, editor, or designer.
+
+## Comment Thread
+
+Contextual discussion attached to a content item, asset, or revision.
+
+## Status History
+
+Audit trail of workflow states and transitions over time.
+
+## Network
+
+Publishing platform or distribution surface, such as Instagram, Facebook, YouTube, LinkedIn, or a newsletter system.
+
+Examples:
+
+- TikTok
+- Instagram
+- Facebook
+- YouTube
+- LinkedIn
+- Newsletter
+- X
+- YouTube
+
+## Channel
+
+Specific destination, account, handle, page, or feed within a network.
+
+Examples:
+
+- `@MyBrand` on Instagram
+- `My Brand Page` on Facebook
+- `#Brand` if used as an internal destination label
+- a specific YouTube channel
+
+## Ready To Publish
+
+State meaning the required review/approval workflow is complete and the item can move to downstream publishing or handoff.
+
+It does not mean the item has already been published.
+
+## Audit Trail
+
+Chronological record of uploads, comments, approvals, and status changes.

docs/product/vision.md

@@ -0,0 +1,111 @@
+# Product Vision
+
+## Status
+
+Active
+
+## Product
+
+`Socialize` is a workflow application for social media content review, revision, approval, and publication readiness.
+
+It is not a public social network. It is a workspace-based coordination tool for internal teams, providers, and client approvers.
+
+## Problem
+
+Social media approval work is still fragmented across Google Drive, email, chat, phone calls, and spreadsheets.
+
+That fragmentation creates:
+
+- unclear latest-version ownership
+- scattered comments and decisions
+- manual follow-up work
+- weak auditability
+- avoidable delays before publication
+
+## Product Goal
+
+Provide one system of workflow for drafting, revising, reviewing, approving, and handing off content for publishing.
+
+## Primary Users
+
+- Social media manager
+- Account manager / customer success
+- Client approver
+- External provider / production partner
+- Internal producer
+- Internal employee / content contributor
+- Administrator
+
+## Core Product Shape
+
+- workspace-based account boundary
+- agencies able to manage multiple workspaces
+- content items as the main reviewable unit
+- assets and revisions tracked against content items
+- comments and approvals attached to the work itself
+- notifications driven by workflow events
+
+## What The Product Must Do Well
+
+- centralize review state
+- preserve a clear audit trail
+- make “latest approved version” obvious
+- support internal review before client review
+- support client-facing review with low friction
+- keep publication handoff clear once approval is complete
+
+## What The Product Is Not
+
+- not a social feed or public community platform
+- not a full publishing engine in version 1
+- not a full DAM platform in version 1
+- not a full analytics product in version 1
+- not a billing/subscription product in version 1
+
+## MVP Scope
+
+Version 1 should focus on approval workflow rather than direct publishing.
+
+### In Scope
+
+- authentication and user roles
+- workspace structure and access control
+- content item creation and editing
+- Google Drive asset linkage and asset metadata
+- revision history for assets and copy
+- centralized comments
+- approval decisions
+- activity timeline / audit trail
+- review queues and dashboards
+- notifications and reminders
+- simple external review experience
+
+### Out Of Scope
+
+- full scheduling engine
+- direct social publishing
+- advanced third-party synchronization
+- analytics suite
+- customer billing flows
+
+## Current Strategic Assumptions
+
+- Google Drive remains an important source of truth for many client-owned files.
+- Internal review and client review are variants of the same workflow, not separate products.
+- External reviewers should experience low-friction review access.
+
+## Near-Term Priorities
+
+- make the content approval workflow complete end-to-end
+- harden workspace scoping and role-based access
+- strengthen revision and comment traceability
+- clarify external review and approval flows
+
+## Phase 2 Opportunities
+
+- deeper Google Drive integration
+- publishing handoff integrations
+- calendar planning views
+- richer approval templates
+- SLA reminders and escalations
+- workflow analytics

docs/specs/TEMPLATE.md

@@ -0,0 +1,61 @@
+# Feature Name
+
+## Status
+
+Proposed | Active | Deprecated
+
+## Goal
+
+One short paragraph describing the outcome this feature must produce.
+
+## Actors
+
+- Actor 1
+- Actor 2
+
+## Preconditions
+
+- precondition 1
+- precondition 2
+
+## Trigger
+
+What starts this flow.
+
+## Main Flow
+
+1. User or system does something.
+2. System validates.
+3. System stores or updates state.
+4. System emits responses, events, or notifications.
+
+## Alternate Flows
+
+- validation failure
+- unauthorized actor
+- missing dependency
+
+## Business Rules
+
+- rule 1
+- rule 2
+
+## Data / Entities
+
+- entity 1
+- entity 2
+
+## API / UI Surface
+
+- frontend routes
+- backend endpoints
+- roles or permissions
+
+## Acceptance Criteria
+
+- [ ] criterion 1
+- [ ] criterion 2
+
+## Open Questions
+
+- question 1

docs/specs/content-approval-workflow.md

@@ -0,0 +1,98 @@
+# Content Approval Workflow
+
+## Status
+
+Active
+
+## Goal
+
+Support the primary workflow from draft preparation through review, revision, approval decision, and readiness for publishing handoff.
+
+## Actors
+
+- Content contributor
+- Provider
+- Internal reviewer
+- Manager
+- Client approver
+
+## Preconditions
+
+- user is authenticated when acting as an internal team member
+- work is scoped to a workspace
+- content item exists inside a workspace context
+
+## Trigger
+
+A team member wants to send a content item through review and approval.
+
+## Main Flow
+
+1. A team member creates or updates a content item.
+2. Assets are linked to the content item, including Google Drive references when appropriate.
+3. The content item includes the relevant metadata:
+   - title
+   - publication message or caption
+   - networks
+   - channels
+   - due date
+   - notes
+4. The item enters internal review or client review.
+5. Reviewers leave comments and record decisions.
+6. If changes are requested, the team links a new revision and continues the workflow.
+7. Once required review is complete, the item can move to `Ready to publish`.
+
+## Alternate Flows
+
+- If a reviewer requests changes, the item should not be treated as approved.
+- If the actor lacks required workspace access, the workflow action must be denied.
+- If assets are missing, the item may still exist, but review readiness should remain explicit.
+
+## Business Rules
+
+- approvals and comments must remain attached to the content item context
+- workflow state changes must be traceable
+- revisions must not overwrite history invisibly
+- “Ready to publish” must correspond to explicit workflow completion, not optimistic UI state
+
+## Data / Entities
+
+- Workspace
+- ContentItem
+- Asset
+- AssetRevision
+- CommentThread
+- ApprovalRequest
+- ApprovalDecision
+- NotificationEvent
+
+## API / UI Surface
+
+### Frontend
+
+- `/app/content`
+- `/app/content/:id`
+- `/app/reviews`
+
+### Backend
+
+- content item handlers
+- asset linkage / revision handlers
+- approval handlers
+- comment handlers
+- notification handlers
+
+## Acceptance Criteria
+
+- [ ] a content item can carry the metadata needed for review
+- [ ] assets and revisions are visible in the item history
+- [ ] reviewers can leave comments and decisions in one place
+- [ ] the audit trail makes status transitions understandable
+- [ ] the approved state is distinguishable from changes-requested and rejected states
+- [ ] the workflow supports internal review before client approval
+
+## Open Questions
+
+- Should external review be account-based, magic-link-based, or both in version 1?
+- Which approval states are mandatory before transition to `Ready to publish`?
+- Should required approvers be modeled in version 1 or phase 2?

docs/use-cases/review-workflows.md

@@ -0,0 +1,90 @@
+# Review Workflows
+
+## Status
+
+Active
+
+## Use Case 1: Internal Review Before Client Review
+
+### Actors
+
+- Content contributor
+- Provider
+- Internal reviewer
+- Manager
+
+### Scenario
+
+1. A contributor or provider creates or updates a draft.
+2. The team links assets and updates the content item metadata.
+3. An internal reviewer leaves comments or requests changes.
+4. Revisions are linked or uploaded.
+5. A manager decides the content item is ready for client review.
+
+### Outcome
+
+- the content item has an internal review history
+- revisions are traceable
+- the item advances to client review only after internal readiness
+
+## Use Case 2: Client Approval
+
+### Actors
+
+- Social media manager
+- Client approver
+
+### Scenario
+
+1. The team sends a content item for client review.
+2. The client reviews assets, caption/copy, dates, and notes.
+3. The client records a decision:
+   - approve
+   - reject
+   - request changes
+4. The team responds with comments or revisions when necessary.
+
+### Outcome
+
+- the decision is captured in the system
+- the audit trail shows who decided what and when
+- the team knows whether the item is approved, blocked, or requires changes
+
+## Use Case 3: Revision Loop
+
+### Actors
+
+- Provider or internal contributor
+- Reviewer
+
+### Scenario
+
+1. A reviewer requests changes.
+2. The owner of the work creates a revised asset or revised copy.
+3. The new revision is linked to the content item.
+4. The reviewer can compare current state against prior feedback context.
+
+### Outcome
+
+- the latest revision is identifiable
+- older revisions remain traceable
+- feedback does not get detached from the work item
+
+## Use Case 4: Ready For Publishing Handoff
+
+### Actors
+
+- Manager
+- Publishing owner
+
+### Scenario
+
+1. All required review and approval work is complete.
+2. The content item transitions to `Ready to publish`.
+3. The downstream publishing owner uses the item as the approved handoff package.
+
+### Outcome
+
+- publishing handoff is based on an approved state
+- the approved revision and metadata are clear
+- the workflow history remains visible