> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_04/prd_phase_04.md). # PRD Phase 04: Media Catalog and Audio/Visual Pipeline **Status**: Complete - Validate and Updateprd Complete **Sessions**: 8 **Estimated Duration**: 8-16 days **Progress**: 8/8 sessions completed (100%) *** ## Overview Phase 04 turns the current limited, documented media set into a cataloged and validated audio/visual pipeline. It defines source-backed media requirements, typed catalog records, promotion tooling, browser runtime behavior, public demo parity, accessibility, privacy, performance, and release gates for generated or owned media. This phase includes a dedicated first-draft generation step for owned media using local provider credentials when available. Draft provider outputs remain non-runtime until catalog, promotion, accessibility, privacy, performance, and public demo gates approve them. This phase preserves the existing quarantine policy. Historical files under `EXAMPLES/` may be inventoried as standards and gap evidence, but they must not be imported, copied, transformed, used as direct generation inputs, or shipped as product assets. This phase does not wire War Room Worker federation, hosted collaboration, hosted analytics, public replay hosting, broad remote execution, Docker isolation, real action executors, or final legacy decommission gates. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------------------------- | -------- | ---------- | ---------- | | 01 | Media Requirements and Provenance Baseline | Complete | \~14-18 | 2026-05-29 | | 02 | Typed Media Catalog Contracts | Complete | \~16-22 | 2026-05-29 | | 03 | Draft Asset Generation and Source Capture | Complete | \~16-24 | 2026-05-29 | | 04 | Visual Promotion Tooling and Budgets | Complete | \~16-22 | 2026-05-29 | | 05 | Browser Audio Runtime and Controls | Complete | \~16-24 | 2026-05-29 | | 06 | Public Demo Media Parity and Offline Loading | Complete | \~14-20 | 2026-05-29 | | 07 | Media Accessibility Privacy and Performance Gates | Complete | \~14-20 | 2026-05-29 | | 08 | Media Validation and Documentation Closeout | Complete | \~12-18 | 2026-05-29 | *** ## Completed Sessions * Session 01: Media Requirements and Provenance Baseline * Session 02: Typed Media Catalog Contracts * Session 03: Draft Asset Generation and Source Capture * Session 04: Visual Promotion Tooling and Budgets * Session 05: Browser Audio Runtime and Controls * Session 06: Public Demo Media Parity and Offline Loading * Session 07: Media Accessibility Privacy and Performance Gates * Session 08: Media Validation and Documentation Closeout ## Session 01 Baseline Artifact Session 01 owns the source-backed Phase 04 media matrix: * `.spec_system/archive/phases/phase_04/media_gap_matrix.md` Later Phase 04 sessions must use this matrix for current evidence, media taxonomy, owner-session routing, release blockers, and disposition decisions. The matrix separates approved battlefield runtime media from conditional tracked media, planned audio/visual categories, prototype-only historical evidence, rejected historical assets, unknown-provenance media, and deferred hosted or collaboration media. *** ## Session 08 Closeout Evidence Session 08 recorded Phase 04 closeout evidence in `.spec_system/specs/phase04-session08-media-validation-and-documentation-closeout/`. The implementation step ran and recorded: * Media gates: `npm run media:gates:check`, `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check`. * Browser evidence: app desktop/mobile and public-demo desktop/mobile Playwright projects, including media fallback, reduced motion, visible audio equivalents, public-demo offline shell, and browser guard coverage. * Repository quality: formatting, linting, workspace typecheck, full Vitest, workspace build, secret scan, whitespace, ASCII/LF, and quarantine checks. The closeout keeps only the battlefield runtime records release-ready: `media.battlefield.background` and `media.battlefield.heroStandees`. Portraits, brand, showcase, public-demo speech, public-demo music, generated references, generated drafts, unknown-provenance rows, and historical intake retain their conditional, planned, prototype-only, rejected, unknown, or deferred blockers until later reviewed promotion work closes them. Formal spec workflow validation is still the next step; this PRD update does not replace the `validate` and `updateprd` workflow commands. ## Upcoming Sessions No Phase 04 implementation sessions remain. Phase 04 is complete and the next workflow step is `audit`. *** ## Session Output Contract | Session | Primary output | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 01 | Source-backed media gap matrix, provenance baseline, catalog taxonomy, and deferral boundaries in `.spec_system/archive/phases/phase_04/media_gap_matrix.md`. | | 02 | Typed media catalog schemas, fixtures, validation helpers, and docs for image, audio, music, and optional video records. | | 03 | First-draft generated visual/audio assets, provider provenance, rights/cost capture, redacted briefs, and non-runtime handoff manifests. | | 04 | Visual asset promotion tooling for inventory, optimization, metadata stripping, parity checks, budgets, and docs updates. | | 05 | Opt-in browser audio runtime, settings integration, captions, fallback behavior, and tests. | | 06 | Public demo media parity, gesture-compatible loading, service worker updates, and offline validation. | | 07 | Accessibility, privacy, redaction, lazy-loading, size-budget, metadata, and release-blocker gates. | | 08 | End-to-end validation evidence, documentation closeout, state updates, and Phase 05 handoff notes. | *** ## Objectives 1. Define a source-backed media catalog taxonomy for tracked, generated, owned, prototype-only, and quarantined media. 2. Add typed catalog records before runtime code references new image, audio, music, or optional video assets. 3. Generate first-draft owned media only through local provider credentials, redacted briefs, source capture, and non-runtime catalog treatment. 4. Build repeatable promotion checks for provenance, attribution, optimization, metadata cleanup, path validity, and byte budgets. 5. Ship opt-in browser audio behavior only with clear settings, captions or visible equivalents, lazy-loading, and safe fallbacks. 6. Keep full app and public demo media behavior aligned while preserving the public demo standalone boundary. 7. Validate Phase 04 with focused tests, media tooling checks, browser smoke evidence, and stable documentation. *** ## Prerequisites * Phase 03 completed. * Current PRD, UX PRD, architecture docs, media asset docs, release docs, and package READMEs are reviewed. * Current battlefield asset records and public demo media behavior remain available. * `EXAMPLES/` remains quarantined evidence only and is not promoted into runtime paths. * Local provider credentials in `.env.local` may be used for generation, but secret values must never be copied into specs, logs, docs, committed files, or browser-visible code. *** ## Technical Considerations ### Architecture Catalog records should lead media promotion. Shared shapes should live in `packages/protocol` when runtime packages need typed media records; app-specific runtime assets remain with the app that loads them; cross-surface references remain under `assets/`; and public demo copies remain standalone under `public-demo/`. Runtime code should consume cataloged paths instead of ad hoc asset lists when practical. ### Technologies * TypeScript catalog contracts in `packages/protocol` where shared runtime types are needed * React 18, Vite, TypeScript, Tailwind, Zustand, and browser media APIs in `apps/web` * Static HTML, CSS, JavaScript, assets, manifest, and service worker in `public-demo` * Repository media tooling: `sharp`, FFmpeg, `ffprobe`, `svgo`, `oxipng`, ExifTool, ImageMagick, host WebP tools, AVIF tooling, and optional catalog packing utilities * Local provider integrations for fal.ai and ElevenLabs generation using `.env.local` credentials without logging secret values * Vitest, Testing Library, Playwright, Biome, npm workspace scripts, and media smoke checks ### Risks * Provenance drift: unknown ownership, license, attribution, source, or provider rights block release. * Quarantine bypass: historical media must remain reference-only and cannot become runtime product media. * Provider-secret exposure: `.env.local` values, provider account identifiers, raw command bodies, and sensitive prompts must not be persisted in tracked files or logs. * Cost and terms drift: paid provider generation needs budget limits and rights review before drafts are promoted. * Audio privacy and accessibility: audio must be opt-in, gesture-compatible, captioned or visibly equivalent, and never required to understand state. * Performance drift: large media must be lazy-loaded, measured, budgeted, and validated on supported desktop and mobile browser surfaces. * Demo drift: public demo media copies, service worker cache entries, and standalone boundaries must stay aligned with app-owned media changes. * Scope bleed: keep War Room federation, hosted services, analytics, collaboration, real executors, and final decommission outside Phase 04. ### Relevant Considerations * \[P03] **Redaction is boundary-specific**: media catalogs, previews, runtime errors, replay/export surfaces, and future hosted paths need explicit minimization. * \[P03] **Local server boundary must stay conservative**: any media route or diagnostics added later must inherit loopback, auth, Origin, CORS, validation, and size-limit defaults. * \[P00] **Asset provenance gate**: no image, audio, model, texture, or bundled chunk should ship from quarantined historical artifacts without source, rights, attribution, optimization, and size-budget review. * \[P04] **Provider generation is non-runtime by default**: fal.ai, ElevenLabs, or other provider outputs start as draft references with redacted provenance, cost notes, and release blockers until promotion gates approve them. * \[P02-apps/web] **Responsive and accessibility debt**: media UI changes need mobile, focus return, dialog semantics, reduced motion, contrast, and validation. * \[P03] **Stable docs are the current contract**: use README files, `docs/api/`, architecture, privacy, deployment, and legacy-consolidation docs as current truth. * \[P03] **Phase complete is not release complete**: War Room federation, collaboration, hosted services, analytics, mobile certification, trusted erasure, and decommission gates remain future work. *** ## Success Criteria Phase complete when: * [ ] All 8 sessions completed. * [ ] Media catalog records distinguish shipped, generated, owned, prototype-only, quarantined, deferred, and rejected media. * [ ] Generated first-draft assets have redacted briefs, provider/tool provenance, rights notes, cost estimates, non-runtime disposition, and explicit blockers before promotion. * [ ] New runtime media has provenance, rights, attribution, optimization, metadata, size, browser support, fallback, and product-use records. * [ ] Visual promotion tooling verifies paths, formats, byte budgets, metadata cleanup, app/demo parity, and stable docs references. * [ ] Browser audio behavior is opt-in, lazy-loaded, settings-controlled, visibly equivalent when muted or unavailable, and tested. * [ ] Public demo media remains standalone, synthetic, cache-aware, and offline validated after one online visit when cache entries change. * [ ] Stable docs identify shipped Phase 04 behavior and keep Phase 05-08 scope deferred. *** ## Dependencies ### Depends On * Phase 03: Agent Orchestration ### Enables * Phase 05: War Room Worker Integration * Phase 06: Collaboration, Isolation, and Mobile * Phase 08: Release Hardening and Legacy Decommission ## Phase 05 Handoff Phase 05 can use the validated Phase 04 media boundary as a stable input: * The web War Room panel must not assume new media transfer, public media hosting, or collaboration identity from Phase 04. * Any War Room media or shared replay work needs a separate consent, authorization, retention, redaction, and erasure design. * Public demo media remains a standalone artifact and cannot become a Worker dependency without a later deployment and privacy review. * Conditional media blockers must remain visible when War Room UI copy, docs, or demos reference portraits, showcase art, public-demo speech/music, or generated drafts. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_04/prd_phase_04.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.