# ZoneGaze Social Studio

ZoneGaze Social Studio is a Matrix plugin for modular social-media work.

Current implemented scope:

- Matrix installable plugin shell under `plugins/social-studio/`
- Reusable product-owned module catalog under `packages/domain/`
- Reusable connector descriptors under `packages/connectors/`
- Reusable asset-ingest package under `packages/asset-ingest/`
- Reusable media-analysis package under `packages/media-analysis/`
- Reusable research package under `packages/research/`
- Reusable planning package under `packages/planning/`
- Reusable publishing/export package under `packages/publishing/`
- Reusable analytics package under `packages/analytics/`
- Reusable automation package under `packages/automation/`
- Workspace persistence through `social-studio.json` plus runtime revision sidecar `social-studio.meta.json`
- Runtime directory-ingest service and tRPC mutation for bounded local folder scans
- Runtime media-analysis service and tRPC mutation for persisted transcript/OCR/scene insight jobs
- Runtime research service and tRPC mutation for Cline SDK-backed evidence sessions
- Runtime planning service and tRPC mutation for Cline SDK-backed campaign briefs, variants, and draft calendars
- Runtime publishing service and tRPC mutation for real export artifacts plus manual-upload publish jobs
- Runtime analytics service and tRPC mutation for batch-aware CSV metric imports and performance summaries
- Runtime automation service and tRPC mutation for approval-gated workflow rules and audit logs
- Ingest UI for local folders, project context, and Whispr transcript imports
- Media-analysis UI for collection selection, insight review, and provider-gap reporting
- Research UI for market direction, audience, goals, competitor references, and saved evidence sessions
- Planning UI for research-backed campaign plans, post variants, and draft calendars
- Publishing UI for export-pack generation, artifact-path review, and normalized manual-upload jobs
- Analytics UI for importing normalized CSV metrics, batch warnings, and reviewing feedback summaries
- Automation UI for schedule selection, approval gates, retry limits, and audit-friendly rule creation
- BYO connector UX for `cline-sdk`, `ollama`, `exo`, and `custom-api`

Current operating model:

- Local-first ingest from folders, project context, and Whispr transcripts
- Local-first media understanding from embedded text plus provider-gated OCR/transcription/scene adapters
- Revision-safe workspace persistence with optimistic save replay, project-session scoping, stale async result drops, and conflict recovery
- Cline SDK-backed research and planning using the user's authenticated global provider catalog plus project-specific Social Studio provider/model/reasoning preferences
- Manual-upload export packs written to `social-studio-exports/<export-pack-id>/` with `manifest.json`, `publish-jobs.json`, and per-post Markdown artifacts
- CSV metric imports parsed with `d3-dsv`, stored as batches with warnings, and summarized per import
- Approval-gated automation rules and audit logs as the free baseline for workflow orchestration
- Reusable `i` help affordances plus a recommended workflow card across the shell and major module controls

Optional future adapters stay isolated so they can be reused elsewhere:

- Direct publish connectors for official platform APIs
- Direct analytics connectors for platform-native exports
- Heavier speech, OCR, and vision engines behind user-supplied providers
- Deeper research adapters layered on top of existing Matrix/Cline model sources

The shell is intentionally thin. Matrix owns install state, navigation, and composition. Social Studio owns its workspace model, module boundaries, and connector registries.

Development notes:

- Web-focused tests assume `flow/web/node_modules` exists in the current checkout. If that workspace has been pruned, run `npm ci --prefix flow/web` before `npm --prefix flow/web run typecheck` or the focused Social Studio web Vitest command.
- Social Studio project settings store only provider/model/reasoning preferences. OAuth tokens, API keys, and provider catalogs remain in the shared `@zonegaze/cline-sdk` layer.
