Docs / creative-plane.md · mirrored from the repo

Namaste Ji — Creative & Content Plane + Back Office

Status: design / brainstorm. Nothing here is built yet. This is the agreed direction, captured so decisions aren’t lost. Treat it as living.

This is the deep-dive on the execution plane’s creative half and the back office that supervises it. It extends ARCHITECTURE.md — read that first for the two-plane model, the Control DO policy engine, observability, and auth. Vocabulary here (stage modes, escalate-on-low-confidence, catalog-as-spine) is reused from there, not redefined. The downstream consumer-side delivery (how catalog content reaches users) is its own plane — see DISTRIBUTION.md.

1. The frame — a company of agents, not a pipeline

The cleanest model for the creative side is an org chart of agents, governed by the Control DO and supervised through the back office. Each role is either a shared service (reusable by anyone) or pipeline-specific.

Principle: shared services (Documentation Agent today; a Research Agent and a Memory service later) are built as standalone Workers/Agents that everyone calls via service binding or tool — never glued inside a single workflow.

2. The Creative Head (CPO + Creative Director)

A multi-agent system that fuses content strategy and product design (they move together: which feature is fed which kind of content).

Continuously / on-demand it:

• researches the web for new content ideas and trends (Browser Rendering / research tools, all model calls via AI Gateway);
• reads the current catalog as a navigable map: the shared multimodal embedding index (DISTRIBUTION.md DS-13) lets it cluster the catalog for a coverage map, find gaps / white space (sparse regions = under-served themes), spot redundancy (over-dense clusters), and — crossing the catalog with the share signal (Loop B) and the calendar — build a supply × demand × occasion grid that is the next-batch brief. The LLM narrates that structure into plain-language strategy. Slice by the structured axes (locale/language/deity/temporal_class) — that’s where the strategically important gaps hide. Plus the active content strategy + content↔feature map;
• reads the cultural calendar (see §10) to stay proactive, not reactive;
• (future) reads product analytics / usage — specifically share-intent aggregated by attribute (style/motif/palette/deity/theme/language), see DISTRIBUTION.md §9 (Loop B). A winning pattern means brief more distinct content in that vein (production amplification) — never “boost the hit item’s distribution” (DS-4). This is how hits feed back: more variety, not more reach;
• optionally collects founder/BO feedback, or proceeds autonomously on its own recommendations;
• emits a brief (§5) for the next content batch.

Run modes: founder/admin can run it manually anytime; it can also run on a schedule (§9). Output is viewable in the BO, saved, and versioned in the BO DB, and rendered to Notion by the Documentation Agent for human review/comment.

Narrative directives (the CEO’s steer). The admin (or an authorized BO user) can pass an optional high-level narrative — a theme / mood / design direction — to keep the brand human and dynamic. The founder owns these. If none is given, the Creative Head decides for itself: continue the running narrative (consistency) or introduce a fresh one (novelty) — and it logs the choice + rationale so the brand evolves legibly rather than drifting. The chosen narrative flows into the brief and the brand/style tokens (§11), so it propagates to generation. Narrative arcs are tracked over time.

3. Shared services

• Documentation Agent — the only writer to Notion. Renders structured BO objects (briefs, strategy, catalog stats) into human-readable Notion pages and pulls founder comments back as inputs. Reusable: any agent that needs to “write it down for a human” calls this one. Notion is a projection + feedback surface, never the system of record (see §4).
• Events Calendar Agent — keeps the events & cultural calendar (§10) fresh and date-validated against an authoritative source, enriches localization, and flags ambiguous instances for human spot-check. Reusable: creative, distribution, and the consumer app all read the same calendar. Runs on a schedule with long lead time.
• (Later) Research Agent and a Memory service factor out the same way.

4. Memory & documentation — three tiers (don’t conflate them)

The trap to avoid: using Notion as the pipeline’s database. The brief lives in D1 (versioned, immutable); Notion is a render of it.

5. The brief — the contract between strategy and production

Update (CH-1): the brief and the standing content strategy are unified into a single versioned Content Strategy artifact (strategy@vN) — see agents/CREATIVE-HEAD.md §3. “Brief” below is that artifact’s production block; the lifecycle (§6) and Content Director (§7) pin to strategy@vN. The contract guarantees (immutable, versioned, reproducible — CP-3) are unchanged.

The brief is the immutable, versioned, machine-readable contract. A generation run pins to a brief version (brief@v7), giving reproducibility, strategy A/B, and a clean audit trail. Sketch:

{
  "brief_id": "...", "version": 7, "created_at": "2026-06-14T...Z",
  "strategy_version": "...",            // which strategy produced this
  "catalog_snapshot": "...",            // catalog state it reasoned over
  "themes": [ /* e.g. "Diwali diyas", "Ganesh blessings" */ ],
  "targets": { "count": 200, "languages": ["hi","mr","ta"], "feature": "morning-feed" },
  "occasion": { "event_id": "diwali", "region": "IN-MH", "instance_date": "2026-11-08",
                "prebuild_by": "2026-10-25" },   // null for evergreen/daily content; see §10
  "metadata_spec": { /* fields each generated asset must carry */ },
  "style_tokens": "brandbook@v2",       // see §11
  "quality_rubric": "rubric@v3",        // see §8
  "rationale": "...",                   // why, for the human
  "status": "draft|approved|in_production|archived"
}

6. Content lifecycle — an explicit state machine

Every asset walks a state machine; each transition is an event. Queues fan out generation; Workflows run the durable per-piece path (with waitForEvent for human gates).

flowchart LR
  D[DRAFTED] --> G[GENERATED] --> A[AUTO_EVALUATED]
  A -->|Judge flags| F[FLAGGED] --> H[HUMAN_REVIEWED] --> S[SCORED]
  A -->|clean| S
  S --> I["INGESTED<br/>(quarantined)"]
  I -->|publish gate| L[LIVE]
  L -.->|rollback| U[UNPUBLISHED]

Each gate does one RPC to the Control DO: “auto or manual for this stage?” — the existing stageMode[stage] + escalate-on-low-confidence mechanism. Batch size, N-human count, and approval-required are all Control DO config, not new machinery. MVP: every stage auto, N = 0 humans.

7. Generation — Content Director + generators

The Content Director takes an approved brief, expands it into per-asset jobs (theme, language, metadata, style tokens), and fans them out over Queues to generator subagents (one asset to spec each). Generators are swappable and horizontally scalable — this is where event-driven architecture earns its keep. Output assets land in R2 with a DB row in state GENERATED.

8. Evaluation — the rubric, the Judge, scorecards

• Define the rubric first, before any code. It is a composite quality score, but cultural/religious correctness is a hard veto gate, not an averaged term. For devotional content aimed at a religious audience, the existential risk is a wrong or disrespectful image (wrong deity attributes/vahana/consort, mixed iconography across faiths, wrong festival date, misspelt vernacular blessing) — one screenshot can end the brand. The Judge’s primary question is “safe to ship to a devout audience?”, with aesthetics secondary.
• Auto-eval always runs — a sequence of evaluator agents scoring various metrics + the one well-defined main metric → a scorecard persisted per piece (and per batch) for the admin.
• The Judge flags low-confidence / risky pieces. In auto mode these escalate to a human even though the pipeline is autonomous (reuse escalate-on-low-confidence).
• Human validators (when N > 0): a small batch is generated; only flagged/sampled pieces reach validators. Validators get dead-simple, one-task-at-a-time jobs typed by task (good/bad, grade 1–5, …). Consensus across X validators (majority / agreement threshold) produces the human scorecard. MVP: image validators only; more roles/task-types added later.

Humans are exception + sample reviewers — never a valve every piece must pass. That is what lets the system scale to millions of assets without a labeling sweatshop.

9. Ingest vs publish — decouple them

Splitting these is the key decision for safe autonomy:

• Ingest (prepare → store as quarantined) is always automatic: optimize, CDN-prep, thumbnails, compression, watermark/branding, generate embeddings (Vectorize), tag temporal_class: timeless | time_bound (time-bound links to an EventInstance, §10), attribute-tag (style/motif/palette/deity/composition/theme/language — powers the generative feedback loop, DISTRIBUTION.md §9 Loop B), drop only near-identical duplicates, prep for the recommendation engine.

  Variety is the goal, not something dedup fights: ingest kills only near-identical waste; repetition is managed at serve time (per-user cooldown + diversity ranking). So generate broadly — many distinct takes per theme. See DISTRIBUTION.md §2 (timeless vs time-bound) and §7 (diversity).

• Publish/activate (make visible to end users) is the gated step the Control DO governs.

Recommendation: never put a human on the volume path. For the fully-auto MVP, auto-publish is fine if (a) the scorecard is always produced, (b) there’s an instant unpublish/rollback, and (c) the Judge escalates low-confidence pieces to a human even in auto mode. Manual-approve-on-publish becomes a Control DO flag you flip later, per stage, without re-architecting.

Ingest tech (CF): default to Cloudflare Images for transforms + watermark (named variants, AVIF/WebP negotiation, resize) on R2 origin behind Cache; global low-latency loads come from the edge. Hand-roll R2 + transforms only if Images’ pricing/limits bite. (This resolves ARCHITECTURE.md open question #4.)

10. Events & cultural calendar — the temporal spine

Every agent must know today’s date/time (locale-aware — see below) — but for this product the calendar is far bigger than a timestamp. It’s a first-class, shared data asset that drives strategy, generation timing, distribution, and consumer-app features. Content is time-critical: pieces are pumped harder on specific days, and we plan campaigns around occasions/events. It’s what turns the studio from reactive to genuinely proactive.

Multi-granularity cadence — not just big festivals:

• Daily — Good Morning / Good Night (the core surface, the base cadence).
• Weekly — weekday↔deity (e.g. Mon–Shiva, Tue–Hanuman, Sat–Shani).
• Monthly (lunar) — Ekadashi, Purnima, Amavasya, Sankashti, …
• Annual festivals — Diwali, Holi, regional new years (Ugadi/Gudi Padwa/Puthandu/ Vishu/Baisakhi), Eid, Christmas, … plus national/secular days.
• (Later) Personal — birthdays/anniversaries.

The daily base is modulated by the weekly/monthly/festival overlays.

Domain model — event vs event-instance. A festival isn’t one date. An event is the canonical concept; its dates resolve per region and per year (lunisolar/Hijri math + genuine regional differences — same festival, different day North vs South; different name/customs/deity/spelling per locale). So:

• Event (canonical) → many EventInstance(region, year), each with a resolved, validated date, localized name/blessing/iconography, an importance tier, and a campaign window.

Campaign window makes “time-critical” operational. Each instance carries prebuild_by (assets ready) · promote_from (start surfacing) · peak (the day) · decay_until. This gives the Content Director a hard deadline (generation starts before the nominal date, with lead time) and the distribution layer a schedule (pre-stage to edge, push in advance, surface on the right local day).

Hard rule — dates are sourced and validated, never LLM-generated. Panchang is lunisolar; LLMs hallucinate festival dates; a wrong Diwali date is the same class of brand catastrophe as wrong iconography (CP-4). Resolved dates come from an authoritative Panchang/holiday source (library/dataset/API) as ground truth; the Events Calendar Agent (§3) enriches + cross-validates, and tier-1 events get a human spot-check.

Consumers (why it lives in the shared spine, edge-readable — not BO-only):

• Creative Head — plans batches by lead time (“brief Diwali now”).
• Content Director — schedules generation against prebuild_by.
• Distribution / recommendation (DISTRIBUTION.md) — pre-stage + push content in advance, per user region + preference, on the right local day.
• Consumer app — event-keyed features, themes, animations, skins (e.g. a Diwali home screen) built by engineering agents from this metadata.

Locale-aware “today”. “Today” and a festival’s “day” are local, not server-UTC; greetings fire on the user’s local morning. Temporal context is region/timezone-aware.

Data boundary. The calendar is public content metadata (geo-portable); a user’s event preferences are PII (region-pinned) — keep them separate (§14).

11. Brand identity — human doc + machine config

A brandbook and logo are needed. The brandbook isn’t only a PDF: extract brand tokens (palette, logo lockups, watermark spec, voice/tone) into a versioned, machine-readable object (brandbook@v2) that feeds generators (style consistency) and ingest (watermark). Same source, two consumers. Watermarking also doubles as attribution/discovery for users (a business-plan discussion).

12. Back office — the surfaces to build

RBAC (per ARCHITECTURE.md §5): Cloudflare Access at the perimeter + roles in D1. MVP: admin only (the founder; all rights, incl. creating BO users later). Roles (creative-lead, validator, viewer, …) and end-user creation come later.

13. Logging & observability — a dataset for agents, not text for humans

Design this now because of the goal: agents that monitor production, notify, and file PRs. If an agent can’t query the logs against a stable schema, it can’t triage or fix. Treat the log schema like an API contract. Two streams, both structured JSON with correlation IDs (run_id, brief_version, content_id, agent_id):

1. Platform logs — Worker/Workflow execution → Workers Logs + Logpush to R2/sink; Analytics Engine for metrics.
2. Domain / audit events — BO actions, gate decisions, agent decisions. Append-only; this is a product surface and a compliance artifact.

14. Compliance & data residency (posture, not a project yet)

Extends ARCHITECTURE.md §6. The content/audit plane carries little PII and is broadly geo-portable; the risk lands when end-user analytics arrive. Set the boundary now: PII plane separate from content plane, region-pinned storage for user data (CF jurisdictional D1/DO/R2 placement), a consent ledger, India DPDP + GDPR as the bar.

15. Cloudflare mapping (everything-CF holds)

16. Decisions log (extends ARCHITECTURE.md D1–D8)

17. Open questions

• The quality rubric + the cultural-veto definition (do this first).
• Brief schema + versioning details.
• Calendar date source — build vs license a Panchang/holiday dataset vs API; the date-resolution/recurrence engine (lunisolar + Hijri + regional rules).
• Where per-user event preferences live (PII plane) and how distribution reads them.
• Validator consensus rule (majority vs threshold vs weighted).
• Where domain/audit logs are queried from by future agents (Analytics Engine vs R2 + query layer vs external sink).
• Brandbook + logo: in-house (generated) vs commissioned.

18. Suggested build order (creative-plane)

1. Quality rubric + cultural-veto spec (doc, no code).
2. Events & cultural calendar v1 — curated, date-validated for launch geographies + daily cadence (the temporal spine); thin Events Calendar Agent to refresh it.
3. Brief schema in D1 (the contract) + versioning (incl. the occasion/lead-time link).
4. Documentation Agent (reusable Notion service) — useful immediately.
5. Control DO stage config for the lifecycle (modes, batch size, N-human).
6. Creative Head v1 (research + calendar → brief), run manually from a thin BO.
7. Content Director + generators (Queues fan-out) → R2/D1.
8. Auto-eval + Judge + scorecard; then ingest (Images) → quarantine → publish.
9. Agent registry + run console + audit log in the BO.
10. Human validators + validator inbox (only when N > 0 is needed).

19. MVP cut line

In: admin role only · curated, date-validated events calendar for launch geographies (major pan-India + a few regional festivals) + daily good-morning cadence · Creative Head (manual run) · brief (with occasion/lead-time) · Content Director + generators · auto-eval + Judge + scorecard · ingest (Images) · fully autonomous (auto-publish + rollback) · structured logs + audit · agent registry/run console.

Out (later): other BO roles + human validators · end-user creation · product-analytics feedback into strategy · per-user event preferences + pre-staged/advance distribution · consumer-app event themes/animations · personal-date events · video/music/other media · log-monitoring/auto-PR agents · fine-grained per-stage manual gates.