# Private CartoonOS Control Center / CRM

Status: active implementation specification plus reviewed-plan dashboard.  
Accountable content owner: **Head of Content (A0)**.  
Runtime owner: Engineering / Platform Core.  
Updated: 2026-09-08.

Canonical governance:
- `docs/agents/HEAD_OF_CONTENT_OS_v0_9.md`
- `data/operations/head-of-content-control-plane-v0_1.json`
- `docs/agents/AGENT_ROSTER_v0_3.md`
- `docs/product/COMMAND_CENTER_UX_ARCHITECTURE_v0_2.md`

## First release scope

One authenticated owner, one organization/project scope, current seven-mascot catalog and **one story-selected Golden Short proof package**.

Do not hardcode S01E01 or a Lumi/Tiko pair into the Control Center architecture. S01E01 remains an episode-specific asset/provenance object and can enter production after the Golden Short loop is proven.

Preserve the current Next.js Studio and Python API rather than starting another application.

The Control Center is the operator façade over existing truths. It does not create a second workflow, second canon, second analytics store or new executive-agent layer.

## Primary operator model

`DECIDE → MAKE → RELEASE → LEARN`

The Home/Command Center should answer:
- what is blocked;
- what A0 must decide now;
- whether evidence/canon/docs/prompts are current;
- whether the selected cast/assets/environment/provider are ready;
- what the next hard production gate is;
- whether a release is approved for autopost;
- whether a platform mutation is reconciled;
- what measured learning is ready to accept/reject.

## A0 decision surfaces

The UI should expose decision state for these controlled domains without making A0 manually execute their underlying tasks:

1. portfolio priority;
2. documentation/canon source-of-truth conflicts;
3. scenario approval/revision/rejection;
4. prompt promotion/hold/rollback;
5. data fitness-for-decision;
6. cast/production go-repair-hold-stop;
7. release/autopost approval;
8. publication exception/reconciliation escalation;
9. learning accept/hold/reject.

Hard safety/factuality/rights/privacy/budget/runtime gates remain separately visible and cannot be overridden from the UI.

## Views and acceptance

| View | Questions it answers | Acceptance |
|---|---|---|
| Home | What requires an A0 decision; what is blocked; what is stale; what is affordable? | Source/state/freshness on every KPI; no sample value shown as measured |
| Content | Which opportunity/scenario/cast is approved and why? | Evidence/canon versions, situational review, cast rationale, A0 decision state |
| Production | Which package/shot/attempt is running, rejected or awaiting QA? | Exact refs, prompt/compiler version, capability, quote/budget, provider ID, output checksum and QA linked |
| Distribution | What is A0-approved for release/autopost and what is reconciled? | Rendition checksum, audience/policy state, authorization, publication/idempotency identity, platform final status |
| Analytics | Is quality-gated value improving at comparable age/sample? | D1→D90, filters, null states, revisions, matched cohorts and uncertainty |
| Economics | Where do cash, accepted seconds, reuse and rework go? | Currency/credits separate; all attempts retained; budget reservations/reconciliation explicit |
| Ownership | Who produced evidence/output and who owns the decision? | A0 vs A1–A7 execution clearly distinguished; provenance and per-run cost/latency |
| Knowledge | What supports this claim and can this character access it? | Source locator, rights, version, freshness, contradictions, character-access path |
| CRM | Which adult partner/vendor needs a next step? | Contact source/consent, organization, opportunity, stage, owner, notes and audit trail |
| Integrations | Is it configured, authorized, healthy and affordable? | Distinct states and last successful proof; no secret values in UI |

Target top-level Studio navigation remains ≤6 groups; deeper views may be nested rather than exposed as separate top-level products.

## Canonical model

PostgreSQL owns operational state; object storage owns immutable media; Temporal owns durable execution; Git/versioned files own reviewed code/canon/docs/manifests. Dashboard is a projection.

`ProductionPackage` is the operator-facing façade/reference aggregate. Detailed typed artifacts remain authoritative and must not be duplicated into another truth store.

Core lineage:

`Project → CanonicalContent/ProductionPackage → Scene → Shot → CompiledRequest → GenerationAttempt → MediaObject → QA/RoughCut → Rendition → Publication → MetricSnapshot → Experiment → LearningProposal → A0Decision`

Supporting entities include CharacterVersion, VoiceVersion, ReferenceBinding, EnvironmentState, EvidenceClaim/Source, KnowledgeAccessEvent, PromptVersion, ModelCapabilitySnapshot, WorkflowRun, StepEvent, Approval, CostEntry, BudgetReservation, IntegrationConnection, Contact and Deal.

Every operational record is project-scoped. Stable IDs, versions/checksums and scoped uniqueness prevent cross-project collisions and silent substitutions.

Money uses decimal/integer minor units with currency. Credits remain distinct from currency. Missing values remain null/unknown rather than fabricated zeroes.

## Workflow and approvals

Operator flow:

`Opportunity → Evidence → Scenario → A0 scenario decision → Animatic/Cast Readiness → MAKE → Packaging → A0 release/autopost decision → Platform Queue → Reconciliation → Metrics → Learning Proposal → A0 learning decision`

Implementation remains the existing 13-activity Temporal composition. The UI must not invent a parallel workflow.

Commands carry command ID, expected row version, actor and project scope. Use transactional transitions plus outbox/idempotency where side effects occur. Optimistic concurrency rejects stale edits.

No drag-and-drop action can bypass a server-side hard gate. Publish/spend actions show the exact reviewed target/checksum and authorization state.

## Documentation and prompt health

Control Center should surface:
- current active governance/canon/prompt versions;
- stale/superseded-source conflict count;
- unresolved source-of-truth conflicts;
- prompt candidate/regression/promotion state;
- evidence/provider/platform freshness state.

Active sources include:
- `MASCOT_BIBLE_v0_4.md`
- `RELATIONSHIP_AND_CROSSOVER_BIBLE_v0_5.md`
- `SCENARIO_WRITER_PROMPTOPS_v0_11.md`
- `PROMPT_ENGINEERING_STANDARD_v0_2.md`
- `OMNICHANNEL_CONTENT_ENGINE_v0_2.md`
- `COMMAND_CENTER_UX_ARCHITECTURE_v0_2.md`

Deterministic documentation health is checked by `scripts/validate_documentation_health.py` and the root `pnpm validate:docs` command.

Superseded files are provenance-only and should never be offered as current execution inputs.

## Seven-mascot production policy

Active roster:

`Lumi · Tiko · Nova · Marina · Rin · Arqueo · Pepe`

The UI must show:
- all-seven baseline identity/voice/reference state;
- story-selected deep readiness for the current package;
- no mandatory pair;
- sample size/uncertainty before comparative mascot claims.

Do not design a privileged Lumi/Tiko production unlock.

## Graph without premature graph infrastructure

Use normalized relational tables plus edge projections initially. Useful edge types include:

`OWNS · EXECUTES · READS · SUPPORTS · CONTRADICTS · QUALIFIES · DERIVED_FROM · APPROVES · PRODUCES · PUBLISHED_AS · MEASURED_BY · INFORMS`

Each material edge has source entity/version, destination entity/version, evidence reference and timestamp.

Knowledge graph relations do not themselves prove factual/causal claims. Character knowledge requires an explicit memory/observation/retrieval/handoff path.

Add a graph database only when measured queries justify it.

## Autopost and reconciliation

A0 approves what may enter autopost; A6/platform adapters execute.

Publication request requires:
- approved canonical lineage;
- final rendition checksum/version;
- audience/made-for-kids/disclosure/privacy state;
- account authorization;
- schedule slot;
- A0 release-decision reference;
- publication ID/idempotency key;
- adapter version;
- reconciliation/correction route.

Unknown mutating submission state is not failure and not permission to retry blindly. Reconcile first.

Publication is complete only after platform asset ID/final status is persisted.

## Security and deployment

Owner/editor/reviewer/analyst roles remain a target; start owner-only if appropriate. Reject anonymous internal reads, enforce project/org scope server-side, use private buckets and expiring media access.

No credential/raw OAuth token belongs in browser code. Log sensitive actions with secret-reference names only. Validate provider URL origins before attaching credentials.

Deploy only after auth, persistence, backups and smoke tests. API/worker releases need rollback and migration compatibility.

## Scale rule

Add channels through an explicit scoped onboarding contract. Test cross-project denial before onboarding.

Add independent worker pools only for demonstrated capacity/isolation needs. Add a graph database or another service only after measured need.

Do not add executive agents for docs, prompts, mascots, autoposting or routine analytics. Use A0 governance plus bounded roles, skills, validators and adapters.

**The Control Center must expose decisions and truth, not recreate the architecture.**