chore: moving towards agentic development

docs/FEATURES/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/FEATURES/platform-scaffold.md

@@ -0,0 +1,60 @@
+# Feature: Agentic Platform Scaffold
+
+## Status
+
+In Progress
+
+## Goal
+
+Align Socialize with the structure generated by `bootstrap-vdp-agentic.sh` while preserving the current product implementation.
+
+## Backend
+
+The backend is located at:
+
+```txt
+backend/src/Socialize.Api
+```
+
+The solution is:
+
+```txt
+backend/Socialize.slnx
+```
+
+The test project is:
+
+```txt
+backend/tests/Socialize.Tests
+```
+
+## Frontend
+
+The frontend remains the existing Vue 3 app. The scaffold directories `frontend/src/api`, `frontend/src/features`, `frontend/src/pages`, `frontend/src/layouts`, and `frontend/src/app` are available for incremental migration.
+
+## API Contract
+
+OpenAPI workflow:
+
+```bash
+./scripts/update-openapi.sh
+```
+
+Writes:
+
+```txt
+shared/openapi/openapi.json
+frontend/src/api/schema.d.ts
+```
+
+## Done When
+
+- [x] Backend code lives under `backend/src/Socialize.Api`
+- [x] Backend solution exists at `backend/Socialize.slnx`
+- [x] Test project exists under `backend/tests/Socialize.Tests`
+- [x] Root scripts exist
+- [x] Docker Compose and Caddy files exist
+- [x] Agentic docs, specs, tasks, and prompts exist
+- [ ] OpenAPI generation verified against a running backend
+- [x] Backend build passes
+- [x] Frontend build passes

docs/FEATURES/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

docs/FEATURES/workspace-review-workflow.md

@@ -0,0 +1,52 @@
+# Feature: Workspace Review Workflow
+
+## Status
+
+Draft
+
+## Goal
+
+Support workspace-scoped social media content review from content creation through comments, revision, approval, and ready-to-publish handoff.
+
+## User Stories
+
+- As a social media manager, I want content items grouped by workspace, client, and project so that I can manage review work for multiple accounts.
+- As a client approver, I want one clear place to review content, comment, and approve or request changes.
+- As an account manager, I want notifications and review queues so that work does not stall silently.
+
+## Backend Modules
+
+- Identity
+- Workspaces
+- Clients
+- Projects
+- ContentItems
+- Assets
+- Comments
+- Approvals
+- Notifications
+
+## Frontend Areas
+
+- `/app`
+- `/app/workspaces/new`
+- `/app/clients`
+- `/app/projects`
+- `/app/content`
+- `/app/content/:id`
+- `/app/reviews`
+- `/app/settings`
+
+## Domain Rules
+
+- Workspace is the top-level scoping boundary.
+- Content items belong to a workspace and may belong to a client or project.
+- Comments, approvals, assets, and notifications must remain traceable to the workflow entity they relate to.
+- Ready-to-publish state should come from explicit approval workflow transitions.
+
+## Done When
+
+- [ ] Workspace access is enforced consistently
+- [ ] Content item lifecycle is documented as a state machine
+- [ ] Approval decisions create traceable notifications/events
+- [ ] Review queue behavior is covered by tasks and validation