> 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/sessions/phase04-session01-media-requirements-and-provenance-baseline/spec.md). # Session Specification **Session ID**: `phase04-session01-media-requirements-and-provenance-baseline` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Complete **Created**: 2026-05-29 **Package**: Cross-cutting **Package Stack**: npm workspace documentation, repository media inventory, public demo static media, TypeScript catalog planning *** ## 1. Session Overview This session creates the source-backed media requirements and provenance baseline for Phase 04 before any new catalog schema, promotion script, runtime audio control, or public demo media change is implemented. It reconciles current tracked media, app-owned runtime assets, public demo media, media tooling, release blockers, and quarantined historical evidence into one routing matrix. The work is intentionally documentation-first and cross-cutting. It gives later Phase 04 sessions a stable media gap matrix with source evidence, owner session, acceptance notes, risk level, and final disposition for images, audio, music, optional video, HUD art, portraits, achievements, showcase media, generated references, and prototype-only evidence. The session also protects the existing quarantine and local-first posture. Historical `EXAMPLES/` files may be cited by path for standards and gaps, but must not be copied, transformed, used as direct generation inputs, imported into runtime paths, or presented as shippable product media. *** ## 2. Objectives 1. Create a source-backed Phase 04 media gap matrix with current media evidence, owner sessions, acceptance notes, risk levels, and final disposition. 2. Define a media catalog taxonomy covering tracked runtime media, generated references, owned showcase media, public demo media, prototype-only evidence, quarantined historical sources, and deferred media categories. 3. Align PRD, UX PRD, architecture, media, privacy, release, legacy, asset, app, and public demo docs around current-versus-planned media behavior. 4. Capture a provenance, attribution, optimization, metadata, accessibility, privacy, performance, and release-blocker baseline for later Phase 04 implementation sessions. *** ## 3. Prerequisites ### Required Sessions * [x] `phase03-session07-orchestration-validation-and-documentation-closeout` - provides the current Phase 03 closeout, quality gate baseline, security posture, and Phase 04 handoff. * [x] `phase02-session05-battlefield-asset-and-public-demo-parity` - provides the approved battlefield asset parity baseline and app/demo media validation pattern. * [x] `phase02-session07-product-surface-validation-and-documentation-closeout` - provides current browser and public demo closeout evidence for product-surface behavior. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, Vitest, Playwright, `npm run media:check`, and `npm run battlefield:check`. * Current stable docs: `docs/media-assets.md`, `docs/ARCHITECTURE.md`, `docs/privacy-and-security.md`, `docs/release.md`, `docs/legacy-consolidation.md`, `docs/public-demo-code-sharing.md`, `assets/README_assets.md`, `apps/web/README_web.md`, and `public-demo/README_public-demo.md`. * Spec system sources: `.spec_system/PRD/PRD.md`, `.spec_system/PRD/PRD_UX.md`, `.spec_system/PRD/phase_04/PRD_phase_04.md`, `.spec_system/CONSIDERATIONS.md`, `.spec_system/CONVENTIONS.md`, and `.spec_system/SECURITY-COMPLIANCE.md`. ### Environment Requirements * Local checkout of the FactionOS monorepo with Phase 04 session stubs available. * No hosted service credentials, cloud storage, analytics, or media provider accounts are required. * `EXAMPLES/` may be reviewed only as ignored, quarantined, reference-only evidence. *** ## 4. Scope ### In Scope (MVP) * Maintainers can identify each current tracked media group by source path, runtime owner, provenance status, release risk, and downstream Phase 04 owner - create a media gap matrix grounded in current docs and paths. * Implementers can route each media category to the correct later session - define categories for images, audio, music, optional video, HUD art, portraits, achievements, showcase media, generated references, public demo media, and prototype-only evidence. * Release reviewers can distinguish owned or generated runtime media from quarantined historical evidence - document source, rights, attribution, optimization, metadata, size, accessibility, privacy, and final disposition requirements. * Public demo maintainers can preserve the standalone artifact boundary - capture app/demo parity, service worker cache, speech, music, portrait, and battlefield media constraints without importing workspace packages. * Security reviewers can evaluate future media promotion against local-first privacy boundaries - record blockers for unknown provenance, sensitive metadata, raw local paths, unsupported formats, oversized files, and missing fallbacks. ### Out of Scope (Deferred) * Generating, recording, promoting, optimizing, copying, replacing, or deleting runtime media - *Reason: later Phase 04 sessions own media catalog implementation and promotion after the baseline exists.* * Implementing typed catalog schemas, validation helpers, visual promotion scripts, browser audio controls, or service worker changes - *Reason: Sessions 02 through 05 own implementation.* * Wiring hosted storage, analytics, War Room federation, collaboration, public replay hosting, real executors, Docker isolation, or final legacy deletion - *Reason: later phases own these surfaces and require separate consent, authorization, and release gates.* * Promoting `EXAMPLES/` files directly into tracked runtime paths - *Reason: current ADR and media policy keep historical media quarantined as evidence only.* *** ## 5. Technical Approach ### Architecture The session uses a documentation-as-contract approach. Current tracked files, stable docs, package README files, public demo records, media tooling scripts, and Phase 04 stubs are treated as source evidence. The output matrix becomes the routing artifact for later catalog, promotion, audio, public demo, accessibility, privacy, performance, and validation sessions. Catalog records should lead runtime media promotion in later sessions. Shared shapes should live in `packages/protocol` only 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/`. ### Design Patterns * Provenance-first planning: media cannot become release media until source, rights, attribution, optimization, metadata, size, browser support, fallback, and product use are recorded. * Evidence-only quarantine: `EXAMPLES/` can support standards and gap analysis by path, hash, and conclusion, but cannot be copied or transformed into runtime product assets. * Explicit disposition: each matrix row should end as approved, conditionally promoted, needs attribution, needs replacement, prototype only, rejected, unknown, planned, or deferred. * App/demo boundary preservation: public demo media may mirror product meaning, but the static artifact must not import workspace packages or depend on local server paths. * Local-first privacy baseline: media previews, errors, logs, docs, future catalogs, replay/export adjacency, and hosted candidates must minimize sensitive local paths, prompts, tokens, provider details, and metadata. ### Technology Stack * Markdown for PRD, UX PRD, docs, README, matrix, implementation notes, and security deliverables. * npm workspace with Node 20+ baseline. * Media tooling baseline: `sharp`, FFmpeg, `ffprobe`, `svgo`, `oxipng`, ExifTool, ImageMagick, WebP tools, AVIF tools, and optional catalog utilities. * Validation tools: `npm run media:check`, `npm run battlefield:check`, Biome formatting check where relevant, `git diff --check`, ASCII/LF scan, docs path review, and privacy-sensitive copy review. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_04/media_gap_matrix.md` | Source-backed Phase 04 media matrix with current evidence, owner sessions, acceptance notes, risk levels, and final disposition | \~240 | | `.spec_system/specs/phase04-session01-media-requirements-and-provenance-baseline/implementation-notes.md` | Session implementation record, command evidence, files changed, and risk handoff | \~100 | | `.spec_system/specs/phase04-session01-media-requirements-and-provenance-baseline/security-compliance.md` | Session-specific provenance, privacy, security, and release-blocker baseline | \~90 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Refine Phase 04 media catalog, audio/visual pipeline, and provenance boundaries | \~35 | | `.spec_system/PRD/PRD_UX.md` | Add media UX expectations for visible equivalents, captions, fallback states, and demo limits | \~30 | | `.spec_system/PRD/phase_04/PRD_phase_04.md` | Link Session 01 matrix and clarify baseline output contract if needed | \~25 | | `docs/ARCHITECTURE.md` | Clarify current versus planned media catalog architecture and runtime ownership | \~25 | | `docs/media-assets.md` | Update taxonomy, known-state, provenance, quarantine, and release-blocker wording | \~70 | | `docs/privacy-and-security.md` | Add media-specific privacy and metadata risks without claiming hosted transfer | \~30 | | `docs/release.md` | Add media release blockers, service worker cache cautions, and provenance gates | \~30 | | `docs/legacy-consolidation.md` | Capture media source-group ownership and evidence-only boundaries for Phase 04 | \~35 | | `docs/public-demo-code-sharing.md` | Clarify public demo media parity and standalone artifact constraints | \~20 | | `assets/README_assets.md` | Clarify catalog/manifests and cross-surface asset ownership | \~20 | | `apps/web/README_web.md` | Clarify app-owned runtime media and deferred browser audio/runtime catalog boundaries | \~20 | | `public-demo/README_public-demo.md` | Clarify demo speech, music, cache, and standalone media behavior | \~20 | | `packages/protocol/README_protocol.md` | Clarify that shared media catalog contracts are Session 02 work | \~15 | | `.spec_system/SECURITY-COMPLIANCE.md` | Record media provenance and privacy carryforward baseline if needed | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Phase 04 media gap matrix exists and routes every current or planned media category to a Phase 04 owner session or explicit deferral. * [ ] Matrix rows distinguish approved runtime media, generated references, public demo media, prototype-only evidence, quarantined historical sources, rejected media, unknown provenance, and deferred categories. * [ ] PRD and UX PRD separate current shipped media behavior from planned catalog, promotion, audio, public demo, accessibility, privacy, performance, and validation work. * [ ] Stable docs and package README files describe media ownership without implying `EXAMPLES/` promotion, hosted media storage, analytics, War Room federation, or release cleanup as shipped. * [ ] Security and release baseline identifies blockers for unknown source, unclear rights, missing attribution, unoptimized media, metadata risk, unsupported browser formats, oversized files, missing fallback, and sensitive path exposure. ### Testing Requirements * [ ] `npm run media:check` result recorded or blocker documented. * [ ] `npm run battlefield:check` result recorded or deferral documented if no asset paths changed. * [ ] Documentation path and link references reviewed for changed files. * [ ] Privacy-sensitive copy review completed for raw prompts, tokens, OAuth IDs, probe output, command bodies, raw local paths, copied historical excerpts, and direct `EXAMPLES/` media reuse. * [ ] ASCII/LF checks completed for all session outputs and touched docs. * [ ] `git diff --check` completed. ### Non-Functional Requirements * [ ] Local-first operation remains the default and no hosted media, analytics, cloud account, provider transfer, database, or public replay path becomes required. * [ ] Historical evidence is summarized by conclusion and path only, not copied into stable docs as raw content or runtime media. * [ ] Future media work has measurable release gates for provenance, rights, attribution, optimization, metadata, size budget, accessibility, privacy, performance, and fallback behavior. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. *** ## 8. Implementation Notes ### Key Considerations * Session 01 is a planning and documentation baseline, not runtime media implementation. * The media gap matrix should become the source material for Sessions 02 through 07. * Current stable docs and tracked files outrank historical extraction files. Historical paths may be cited for traceability only. * Do not use `EXAMPLES/` files as direct generation inputs or copy any historical media into tracked runtime paths. * Keep package README updates concise and route detailed catalog policy to the matrix and stable media docs. ### Potential Challenges * Scope bleed into generation or promotion: keep image, audio, music, video, optimization, and service worker changes as documented ownership and acceptance criteria only. * Provenance uncertainty: mark unknown rights, attribution, provider, source, metadata, or format state as release blockers instead of approving by implication. * Demo drift: public demo media can mirror app media, but must preserve the standalone no-workspace-import contract. * Privacy drift: avoid raw local paths, prompts, tokens, provider prompts, command bodies, terminal output, bundled code excerpts, and copied historical media details in stable docs. * Cross-package duplication: write shared catalog ownership once and keep app, asset, public demo, and protocol boundaries distinct. ### Relevant Considerations * \[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. * \[P03] **Redaction is boundary-specific**: media catalogs, previews, runtime errors, replay/export surfaces, diagnostics, logs, and future hosted paths need explicit minimization. * \[P03] **Local server boundary must stay conservative**: any future media route or diagnostics must inherit loopback, auth, Origin, CORS, validation, rate-limit, and size-limit defaults. * \[P03] **Stable docs are the current contract**: use README files, docs, architecture, privacy, deployment, and legacy-consolidation docs as current truth. * \[P02-apps/web] **Responsive and accessibility debt**: media UI changes need mobile, focus return, dialog semantics, reduced motion, contrast, and validation. * \[P03] **Phase complete is not release complete**: War Room federation, collaboration, hosted services, analytics, mobile certification, trusted erasure, and decommission gates remain future work. *** ## 9. Testing Strategy ### Unit Tests * No application unit tests are expected because this session produces documentation and planning artifacts only. ### Integration Tests * Run `npm run media:check` to verify the local media tooling baseline, or document the exact blocker. * Run `npm run battlefield:check` if app/demo battlefield records or asset references are touched; otherwise record why no asset parity change required it. * Run `git diff --check` for whitespace validation. ### Manual Testing * Review the media gap matrix against all seven Phase 04 stubs to confirm every row has clear ownership, acceptance notes, risk level, and disposition. * Review changed docs for current-versus-planned wording, public demo standalone boundaries, and local-first privacy posture. * Review package README changes for concise package ownership without duplicated catalog policy drift. ### Edge Cases * Historical media appears useful but lacks rights or attribution; keep it quarantined and mark replacement or review requirements. * Public demo media differs from full app runtime media; classify whether it is approved standalone demo media, a parity gap, or an intentional exception. * A media category belongs to War Room federation, hosted services, analytics, collaboration, or release cleanup; defer it explicitly. * Existing docs contain future-oriented media terms; rewrite them to separate shipped behavior from planned Phase 04 work. *** ## 10. Dependencies ### External Libraries * None for this documentation-first session. ### Other Sessions * **Depends on**: `phase03-session07-orchestration-validation-and-documentation-closeout`, `phase02-session05-battlefield-asset-and-public-demo-parity`, `phase02-session07-product-surface-validation-and-documentation-closeout` * **Depended by**: `phase04-session02-typed-media-catalog-contracts`, `phase04-session03-visual-promotion-tooling-and-budgets`, `phase04-session04-browser-audio-runtime-and-controls`, `phase04-session05-public-demo-media-parity-and-offline-loading`, `phase04-session06-media-accessibility-privacy-and-performance-gates`, `phase04-session07-media-validation-and-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase04-session01-media-requirements-and-provenance-baseline/spec.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.