Skip to content

Bootstrap Context

Last generated: 2026-07-06

This page gives Codex and maintainers a product-aware starting point for work in anuvax-cms. It summarizes repository boundaries, integration points, verification expectations, docs parity rules, and product-main handoff expectations for Anuva Video Creator.

This draft was generated from anuva-main-video-creator product docs and the current anuvax-cms/docs set. The anuvax-cms/docs/_stale folder was ignored because current CMS docs say those files may conflict with active code and current repository maps.

For implementation details, prefer the repository docs listed here over this summary. When sources conflict, follow this order:

  1. Explicit user instructions in the current task
  2. Current anuvax-cms/docs/core docs
  3. Current anuvax-cms/docs/state docs
  4. Existing code and tests in anuvax-cms
  5. anuvax-cms/AGENTS.md
  6. This bootstrap context

Do not use docs/_stale as an implementation source of truth unless a maintainer explicitly asks for historical background.

Product Role

anuvax-cms is the Web implementation repository for Anuva Video Creator. It owns the user-facing application, Payload CMS data model, AI planning flows, RAG, PresentationConfig generation, asset management, billing, content store, render job creation, render-worker API, and Web-local documentation.

In the end-to-end product flow:

  1. Users create projects, manage knowledge/media, choose product options, and review generated presentation state in anuvax-cms.
  2. anuvax-cms runs AI planning and RAG-backed workflows through Mastra, persists presentation state in Payload, and compiles deterministic PresentationConfig snapshots.
  3. anuvax-cms creates render jobs and exposes /api/worker/v1 routes for the external Python render worker.
  4. anuva-python-server claims render jobs, prepares assets, supervises Unity, uploads output, and reports completion or failure back to the Web App.
  5. anuva-unity-video-creator renders the final video from the config and assets prepared by the worker.
  6. anuvax-cms presents completed video state and media to the user.

Repository Boundary

This repository owns:

  • Next.js App Router frontend routes for public, authenticated app, and Payload admin surfaces.
  • Payload CMS configuration, collections, globals, generated types, access control, workspace scoping, and local data model docs.
  • Better Auth integration, workspace resolution, server action patterns, and tenant-boundary enforcement.
  • Presentation Video create, review, scene edit, preview, audio, and final generation flows.
  • Mastra runtime, agents, tools, workflows, memory, model configuration, and metered AI execution.
  • RAG ingestion, source handling, chunking, embeddings, retrieval, web source normalization, and workspace-scoped knowledge use.
  • PresentationConfig schema, v1 compilation contracts, deterministic compiler tools, persisted config snapshots, and render handoff package source data.
  • Media assets, voiceover audio assets, generated images, S3-compatible storage references, signed URLs, and upload/download handoff data.
  • Brand kits, content store catalog surfaces, set variants, bot variants, entitlements, and Web-side product selection UX.
  • Billing, coins, subscriptions, credit packs, Zoho Billing integration, webhook idempotency, reconciliation, and billing-related docs.
  • Worker-facing render API routes under /api/worker/v1, including job claim, package, status, heartbeat, signed upload, completion, failure, and cancellation behavior.
  • Repository-local docs, tests, and completion reports for Web App work.

This repository does not own:

  • Python render worker process supervision, local worker workspace layout, Unity lifecycle control, ZeroMQ protocol mediation, local content server, or upload execution after a job is claimed.
  • Unity scene implementation, virtual production runtime, cameras, Bot Presenter behavior, Virtual Screens rendering, capture pipeline, or final video rendering internals.
  • Product-level roadmap, feature acceptance criteria, repository registry, capability ownership, GitHub Project coordination, or release review.
  • Shared Anuva engineering process, templates, skills, or publishing mechanics.

Keep Web App, Python server, and Unity contracts explicit. If a task requires a new cross-repository contract that is not already documented locally, route it through product-main planning or a repository-scoped GitHub issue instead of burying the assumption in code.

Owned Capabilities

The product capability map identifies anuvax-cms as the primary owner for AI planning, RAG, PresentationConfig compilation, Brand Sets, Content Store, billing/user experience, and Web-side render queue participation.

Repository-owned capabilities include:

  • AI-assisted presentation generation from setup inputs, uploaded knowledge, described web sources, selected identity, and user review.
  • RAG ingestion, retrieval, chunk persistence, vector index use, and source-aware presentation context.
  • Mastra workflow orchestration for intent, knowledge, narrative, visuals, slides, direction, compilation, audio planning, and final render handoff.
  • Human-in-the-loop narrative review before scene-detail generation.
  • Scene editor behavior for voiceover, captions, visuals, pause timing, preview regeneration, dirty state, and audio recovery.
  • Deterministic PresentationConfig compilation and public config snapshot persistence.
  • Render job creation and worker-facing API state for video_generation_jobs, render_workers, and render_worker_reports.
  • Workspace-aware app state, auth, access control, and Payload collection behavior.
  • Billing, metering, entitlements, subscription state, and Zoho webhook handling.
  • Web-local docs and implementation maps under docs/core and docs/state.

Supported But Not Owned Capabilities

This repository supports these product capabilities without owning their primary implementation:

  • Automated rendering: create render jobs, expose worker APIs, provide package data, and persist final status; do not own Python worker execution or Unity rendering.
  • Virtual Screens: provide Reveal markup, media references, captions, and config data; Unity owns runtime staging and rendering.
  • Bot Presenter: provide selected bot variant, script, timing, and config data; Unity owns presenter runtime behavior.
  • Cameras and shots: compile or persist direction intent; Unity owns execution, framing, movement, and capture behavior.
  • Render upload execution: issue signed upload URLs and confirm completed media; Python owns worker-side upload behavior.
  • Product task coordination: consume product-main issues and report status back through issues, PR reports, project fields, and product-main progress docs.

Integration Points

Upstream

anuva-main-video-creator is upstream for:

  • Product feature briefs, repository impact analysis, acceptance criteria, and cross-repository sequencing.
  • GitHub issue handoffs and Anuva Video Creator GitHub Project fields.
  • Product Architecture, Product Repository Registry, Product Capability Map, product playbooks, release notes, and progress review.

External providers and platform services are also upstream dependencies for runtime behavior:

  • Postgres via DATABASE_URI for Payload, app data, and Mastra storage.
  • S3-compatible storage via S3_* for media and generated artifacts.
  • OpenAI for text, web search, embeddings, and image generation where configured.
  • Google Generative AI where active code uses that provider.
  • ElevenLabs for TTS/audio generation.
  • Resend for email delivery.
  • Zoho Billing for plans, customers, credit purchases, webhooks, and reconciliation.

Downstream

anuva-python-server is downstream for:

  • Worker API routes under /api/worker/v1.
  • Worker bearer token configuration through ANUVA_WORKER_API_TOKEN.
  • Render job discovery, claim, package, status, heartbeat, upload, completion, failure, and cancellation flows.
  • RenderJobPackage.config, which is the persisted PresentationConfigPublic snapshot from configSnapshot.publicConfig.
  • Asset manifests, signed asset URLs, signed upload URLs, final media records, progress values, and render diagnostics.

anuva-unity-video-creator is indirectly downstream through the Python server for:

  • PresentationConfig semantics.
  • Scene ordering, timing, voiceover audio, media references, Reveal markup, screen content, direction intent, brand/set/bot selections, and render target metadata.

When a Web App change affects the Python worker API or Unity runtime semantics, the product-main change should include repository-specific tasks for the affected implementation repositories.

Current Implementation Orientation

Current CMS docs describe the implementation as a Next.js 15 App Router app with Payload CMS 3.65 embedded in the same runtime. React 19 powers the UI, and Payload uses Postgres through @payloadcms/db-postgres.

Important entry points:

  • src/app/(frontend)/(public): public pages, auth pages, blog, and legal pages.
  • src/app/(frontend)/app: authenticated app routes and server actions.
  • src/app/(payload): Payload admin shell and generated API handlers.
  • src/app/api: Better Auth, presentation APIs, worker render APIs, and Zoho webhook routes.
  • src/mastra: Mastra runtime, agents, tools, workflows, memory, and TTS adapter.
  • src/lib: shared app services, Payload helpers, auth, billing, RAG, PresentationConfig, and Anuva contracts.
  • src/collections/anuvax: Anuva app collections.
  • scripts: workers, seeders, fixtures, diagnostics, and reconciliation tools.

The active Presentation Video flow lives under:

  • src/app/(frontend)/app/create/presentation
  • src/app/(frontend)/app/videos
  • src/app/(frontend)/app/videos/[id]
  • src/app/(frontend)/app/presentation/actions.ts
  • src/app/(frontend)/app/videos/actions.ts

The current create flow includes a human review boundary: users review a preview-only voiceover script before downstream scene details, visuals, slides, direction, compilation, audio, and render handoff continue.

PresentationConfig And Render Handoff

The public config schema lives in:

  • src/lib/presentation-config/schema.ts
  • src/lib/anuva/contracts-v1.ts
  • src/lib/anuva/deterministic-tools.ts
  • src/mastra/tools/compiler/index.ts

Persisted snapshots live in presentation_compilations.

External render handoff uses:

  • video_generation_jobs.configSnapshot.publicConfig
  • /api/worker/v1/jobs/{jobId}/package

RenderJobPackage.config is the persisted PresentationConfigPublic snapshot. The worker package may add job identity, normalized asset manifest, and render target metadata, but it does not wrap or transform the public config into a separate renderer-specific schema before handoff.

Preview config, persisted compilation state, scene dirty flags, and audio readiness must agree. If a scene edit affects voiceover, caption, Reveal, visual, direction, or audio, downstream readiness must be invalidated until the relevant preview or audio path reruns.

Worker And Job Boundaries

Repository-local workers include:

  • pnpm rag:worker: polls rag_ingestion_jobs, processes sources, writes chunks, upserts vectors, and updates source/job status.
  • pnpm presentation:worker: handles queued image generation and voiceover audio work for presentation_generation_jobs.
  • pnpm anuva:worker: upgrade-path worker entry point. Confirm queue semantics in src/lib/anuva/worker-queue.ts before extending it.

External render-worker state uses:

  • video_generation_jobs: final render queue and worker-visible status.
  • render_workers: latest external worker heartbeat and active-job state.
  • render_worker_reports: append-only worker diagnostics.

The external Python render worker talks to /api/worker/v1; it should not use Payload collection APIs directly.

Local Docs Map

Read these CMS docs before making implementation changes:

  • docs/core/SystemArchitecture.md: runtime topology and major entry points.
  • docs/core/PresentationVideoWorkflow.md: create flow, Mastra sequence, generated artifacts, review boundaries, scene edit loop, and readiness rules.
  • docs/core/PresentationConfig.md: public config, v1 contracts, timing/audio authority, preview/render invariants, and render contract.
  • docs/core/PayloadDataModel.md: collections, generated files, schema ownership, and schema change checklist.
  • docs/core/AuthAndWorkspace.md: Better Auth, workspace resolution, server action pattern, and tenant-boundary rules.
  • docs/core/RagAndSources.md: source types, ingestion, vector store, retrieval, web sources, and workspace scoping.
  • docs/core/MastraAgentsAndTools.md: runtime, agents, workflows, tools, model configuration, metering, and deterministic boundaries.
  • docs/core/WorkersAndJobs.md: worker scripts, job collections, Python render worker API, statuses, retries, and required environment.
  • docs/core/BillingAndEntitlements.md: plans, Gold Coins, Silver Coins, entitlements, Zoho Billing, and provider environment.
  • docs/core/TestingAndVerification.md: commands, test layout, harness notes, and when to run each check.
  • docs/state/CurrentImplementationMap.md: canonical code paths, generated files, current presentation boundaries, and external render boundary.
  • docs/state/RouteMap.md: public routes, app routes, API routes, Payload routes, and layouts.
  • docs/state/ServerActionsMap.md: shared action pattern and action ownership.
  • docs/state/CollectionMap.md: collection categories and relationship chains.
  • docs/state/WorkflowMap.md: workflow IDs, entry points, sequence, contracts, and persistence.
  • docs/state/ScriptsAndCommands.md: development, quality, Payload, worker, seeder, fixture, diagnostic, and provider registry commands.
  • docs/state/EnvAndServices.md: environment keys, service assumptions, and Payload DB push cautions.
  • docs/state/KnownGaps.md: current risks around docs, presentation generation, upgrade state, RAG, billing, and infrastructure.
  • docs/state/DocsUpdateChecklist.md: docs parity checklist by change type.
  • docs/process/ChangeWorkflow.md: repository-local change workflow.

Use docs/state/DocsUpdateChecklist.md to decide which local docs need parity updates for behavior changes.

Verification Expectations

Use the lightest relevant checks for the change:

pnpm lint
pnpm typecheck
pnpm test:int
pnpm test:e2e
pnpm test

Run generated-file commands after relevant Payload schema or admin component changes:

pnpm generate:types
pnpm generate:importmap

Useful worker and diagnostic commands include:

pnpm rag:worker
pnpm presentation:worker
pnpm anuva:worker
pnpm diagnose:presentation:generation
pnpm requeue:presentation:job
pnpm reconcile:zoho-billing

Before changing model/provider strings, use the repository-local Mastra provider registry helper:

node .agents/skills/mastra/scripts/provider-registry.mjs --list
node .agents/skills/mastra/scripts/provider-registry.mjs --provider openai

Change-specific verification guidance:

  • Docs-only changes: inspect generated docs; run no code checks unless links or scripts are touched.
  • Server action changes: run pnpm lint, pnpm typecheck, and pnpm test:int.
  • Presentation flow changes: add or run pnpm test:e2e coverage where route-level workflow behavior changes.
  • Payload schema changes: run pnpm generate:types, optionally pnpm generate:importmap, then typecheck and targeted tests.
  • Billing changes: run billing and metering unit tests through pnpm test:int.
  • RAG/source changes: run RAG/source unit tests and relevant presentation integration tests.
  • Worker API changes: run targeted tests around /api/worker/v1, package shape, status transitions, upload flows, and Python-server compatibility.

If verification cannot be run, the PR completion report should explain what was skipped, why it was skipped, and what evidence remains.

GitHub Issue And PR Expectations

GitHub issues are the durable handoff packet for implementation work. For non-trivial tasks, issue bodies should include:

  • Product Feature ID and product source folder when the task comes from anuva-main-video-creator.
  • Target repository: anuvax-cms.
  • Repository-owned scope and explicit non-goals.
  • Dependencies on Python server, Unity, product-main, handbook, or docs publisher.
  • Acceptance criteria and local verification expectations.
  • Docs impact and product-main sync requirements.

Implementation PRs should include a completion report with:

Product Feature ID:
Product Change Folder:
GitHub Issue:
Repository:

Implementation Summary:

Docs Updated:

Verification Run:

Verification Skipped:

Integration Notes for anuva-main-video-creator:

Open Questions:

Follow-ups:

When a CMS task affects product behavior, repository responsibility, cross-repository contracts, or release readiness, report that back through the issue, PR, GitHub Project fields, and product-main progress docs. Codex chat is not the source of truth for cross-repository execution state.

Docs Publishing Impact

This repository owns its local source docs. anuva-dev-docs owns aggregated docs publishing output.

When local docs change:

  • Keep CMS-local docs navigation aligned with new pages.
  • Run or request the CMS-local docs build if the repository has a configured docs build command.
  • Record whether anuva-dev-docs needs a refresh.
  • Do not edit generated publisher output from this repository unless the user explicitly opens that repository and asks for publishing work.

When product-main docs, GitHub Project status, or implementation docs change as part of one product feature, keep product-main GitHubTasks.md, Progress.md, implementation issues, PR reports, project fields, and docs publishing notes in sync.

Open Questions For Maintainers

  • What is the canonical command for building CMS docs, if any, beyond inspecting the Markdown output?
  • Which /api/worker/v1 payload fields are now considered stable contracts with anuva-python-server?
  • Which PresentationConfig fields are stable contracts with anuva-unity-video-creator, and which remain product experiments?
  • What migration workflow should be used for Payload schema changes in pooler-backed hosted database environments?
  • Which active environment keys should be promoted into .env.example before onboarding another developer or worker environment?
  • What is the durable persistence plan for src/lib/anuva/repository.ts upgrade runtime state?
  • Which Silver Coin behaviors are product-approved versus currently plan-level placeholders?
  • What artifacts should CMS PRs attach or summarize when changing render handoff, worker API, PresentationConfig, or final video readiness?
  • Which CMS docs are currently published through anuva-dev-docs, and what refresh process should CMS PRs trigger?

Mark unresolved contracts explicitly in the relevant local docs and, if they cross repository boundaries, route them back through product-main planning or a GitHub issue for the owning repository.