> 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-session03-draft-asset-generation-and-source-capture/spec.md). # Session Specification **Session ID**: `phase04-session03-draft-asset-generation-and-source-capture` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Completed **Created**: 2026-05-29 **Package**: Cross-cutting **Package Stack**: repository media assets, Node scripts, packages/protocol catalog contracts, apps/web TypeScript fixtures, public-demo media evidence, stable docs *** ## 1. Session Overview This session creates the first repeatable, secret-safe draft generation handoff for Phase 04 media. It turns the Session 01 matrix rows and Session 02 typed catalog records into scoped generation targets, redacted product briefs, ignored provider output staging, and tracked non-runtime provenance records. The work is cross-cutting because generated media can affect shared assets, app media records, public demo parity, and later promotion tooling. Raw provider outputs stay under ignored staging such as `tmp/media-generation/phase04-session03/`, while tracked files capture only reviewed brief summaries, safe provider/tool metadata, rights notes, cost estimates, review disposition, and explicit blockers. No generated draft becomes runtime media in this session. Later Phase 04 sessions own visual promotion, browser audio playback, public demo cache changes, accessibility/privacy/performance gates, and release approval. *** ## 2. Objectives 1. Select a bounded set of draft media targets from the Phase 04 media matrix rows owned by S0403. 2. Produce product-safe written briefs for visual, voice, SFX, music, HUD, achievement, and optional-video targets without copying `EXAMPLES/` media or sensitive prompt context. 3. Add local provider-generation commands that verify credential presence without printing values, enforce dry-run and budget limits, and write raw outputs only to ignored staging. 4. Record each generated, deferred, or rejected draft with provider/tool, model, date, non-sensitive variation data, path, metadata, rights, cost, reviewer disposition, and non-runtime blockers. *** ## 3. Prerequisites ### Required Sessions * [x] `phase04-session01-media-requirements-and-provenance-baseline` - provides the media gap matrix, taxonomy, S0403 row ownership, risk model, and quarantine boundary. * [x] `phase04-session02-typed-media-catalog-contracts` - provides media catalog contracts, app-facing fixture records, validation helpers, and catalog-first docs. * [x] `phase03-session07-orchestration-validation-and-documentation-closeout` - provides the current clean security and local-first baseline. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, Vitest, and repository media tooling. * `npm run media:check` for local image/audio/video tool availability. * `.env.local.example` provider variable names: `FAL_KEY` and `ELEVENLABS_API_KEY`. * Current docs: `docs/media-assets.md`, `assets/README_assets.md`, `public-demo/README_public-demo.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md`. ### Environment Requirements * Local checkout with dependencies installed. * `tmp/` remains ignored by git. * Local provider credentials may exist in `.env.local`, but implementers must check only whether values are present and must not print, copy, log, commit, or summarize secret values. * If provider credentials or approved budget are unavailable, the session must record explicit no-generation deferrals instead of fabricating drafts. *** ## 4. Scope ### In Scope (MVP) * Maintainers can see which S0403 matrix rows are targeted - map draft targets to M04-003, M04-011 through M04-013, M04-015 through M04-020, M04-022, M04-024, M04-027, M04-029 through M04-031 as applicable. * Maintainers can review safe generation intent - add redacted brief packs that describe product need, style, event mapping, fallback expectation, and rejection criteria without direct `EXAMPLES/` media inputs. * Operators can run generation locally - add a Node-based command that supports dry-run, credential-presence checks, budget caps, timeout/failure handling, and ignored output staging. * Reviewers can audit draft provenance - add a tracked manifest with provider/tool, model, date, non-sensitive IDs or seeds when available, staged output path, size, dimensions or duration, rights notes, cost estimate, reviewer disposition, rejection reason, and non-runtime blockers. * Runtime maintainers can see blocked catalog state - update app catalog fixtures or draft manifests so generated outputs and planned targets remain `generated_reference`, `planned`, `conditionally_promoted`, or blocked records rather than implicit runtime media. ### Out of Scope (Deferred) * Shipping generated images, audio, music, SFX, HUD art, achievements, or optional video in app runtime paths - *Reason: Sessions 04 through 07 own promotion, runtime, public-demo, accessibility, privacy, and performance gates.* * Copying, transforming, uploading, or using `EXAMPLES/` files as direct provider inputs - *Reason: the quarantine policy forbids direct promotion and direct generation input use.* * Storing provider API keys, provider account IDs, raw command bodies, unredacted request/response payloads, sensitive prompts, or raw local paths in tracked files or logs - *Reason: Phase 04 security posture requires minimization at provider boundaries.* * Adding full visual promotion automation, metadata stripping, runtime audio controls, service-worker cache changes, or offline demo validation - *Reason: later Phase 04 sessions own those deliverables.* * Creating a final production media pack - *Reason: this session creates first drafts and provenance only.* *** ## 5. Technical Approach ### Architecture Keep generated media work split into three layers. Tracked repository files define safe targets, briefs, manifest schema, catalog records, and docs. Ignored `tmp/media-generation/phase04-session03/` stores raw provider outputs and local run artifacts. Runtime packages continue to reference only already-approved media until later sessions promote drafts. The provider runner should be conservative: default to dry-run, load `.env.local` without echoing values, use allowlisted providers, enforce per-run limits, write a redacted run summary, and fail closed when credentials, target IDs, or budget inputs are invalid. Manifest validation should be independent enough to run without provider credentials. Catalog updates should preserve the Session 02 rules. Approved runtime battlefield records stay approved. Draft records and planned media stay non-release with explicit blockers, repository-relative paths, visible fallback expectations, privacy review notes, and no public-demo import dependency. ### Design Patterns * Catalog-first media workflow: media records or manifests precede runtime references. * Ignored raw output staging: provider outputs remain local until reviewed and deliberately promoted as non-runtime references. * Secret-safe command boundaries: scripts check presence, never print secret values, and redact provider request details. * Explicit non-release state: drafts, planned items, rejected items, and deferrals carry blockers so they cannot pass as release-ready media. * Standalone public demo boundary: public-demo paths may be referenced as evidence, but the demo imports no workspace code. ### Technology Stack * Node 20 ESM scripts under `scripts/`. * TypeScript app fixture updates in `apps/web`. * Existing `@factionos/protocol` media catalog contracts and validators. * Vitest for focused app catalog fixture coverage. * Biome for formatting and linting. * Existing media tooling via `npm run media:check`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- | | `assets/generated/phase04/README.md` | Explain generated-draft storage, non-runtime status, and promotion handoff rules | \~90 | | `assets/generated/phase04/draft-briefs.md` | Redacted product-safe visual/audio draft briefs and rejection criteria | \~180 | | `assets/generated/phase04/draft-generation-manifest.json` | Tracked provenance, rights, cost, disposition, and blocker records for generated or deferred drafts | \~220 | | `scripts/generate-media-drafts.mjs` | Local dry-run/provider runner with credential-presence checks and ignored output staging | \~260 | | `scripts/check-media-generation-manifest.mjs` | Manifest validator for required fields, safe paths, non-runtime blockers, and secret-sensitive strings | \~220 | | `.spec_system/specs/phase04-session03-draft-asset-generation-and-source-capture/implementation-notes.md` | Implementation evidence, command results, generated/deferred target log, and blocker record | \~120 | | `.spec_system/specs/phase04-session03-draft-asset-generation-and-source-capture/security-compliance.md` | Provider-secret, provenance, rights, privacy, quarantine, and no-runtime-promotion assessment | \~100 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Add root media draft generation and manifest-check scripts | \~4 | | `apps/web/src/data/mediaCatalog.ts` | Add blocked planned/generated-reference fixture coverage for S0403 draft categories where app-facing catalog records are useful | \~120 | | `apps/web/tests/mediaCatalog.test.ts` | Assert draft catalog records validate, remain blocked, and expose no runtime-ready generated media | \~60 | | `docs/media-assets.md` | Document draft generation workflow, manifest fields, ignored staging, and Session 04 promotion handoff | \~70 | | `assets/README_assets.md` | Document `assets/generated/phase04/` as non-runtime generated-draft evidence | \~30 | | `scripts/README_scripts.md` | Document the draft generation and manifest check commands | \~35 | | `.spec_system/PRD/phase_04/media_gap_matrix.md` | Record Session 03 target coverage or explicit deferrals without moving any row to release-ready status | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Draft targets are mapped to Phase 04 matrix rows and product need. * [ ] Redacted briefs exist for the selected visual and audio categories without direct `EXAMPLES/` media inputs. * [ ] Provider commands can run in dry-run mode without credentials and can verify credential presence without printing values. * [ ] Raw provider outputs, if any, are written only under ignored `tmp/media-generation/phase04-session03/`. * [ ] Every generated, rejected, or deferred draft has manifest provenance, rights, cost, review disposition, and non-runtime blockers. * [ ] No runtime app path, public-demo cache entry, or release docs page references generated drafts as approved media. ### Testing Requirements * [ ] `npm run media:check` passes or any existing host-tool gap is documented. * [ ] `npm run media:drafts:check` passes. * [ ] `npm run media:drafts -- --dry-run` passes without secrets. * [ ] Focused web catalog tests pass after fixture updates. * [ ] `npm --workspace apps/web run typecheck` passes. ### Non-Functional Requirements * [ ] No provider secrets, provider account IDs, raw command bodies, unredacted request/response payloads, sensitive prompts, or broad local paths are committed or logged. * [ ] No `EXAMPLES/` file is copied, transformed, uploaded, or used as a direct generation input. * [ ] Generated media remains non-runtime, non-release, and blocked until later promotion gates approve it. * [ ] Manifest and catalog paths are repository-relative except ignored staging paths explicitly rooted under `tmp/media-generation/phase04-session03/`. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Keep first-draft target count small enough for review and provider cost control. * Prefer draft briefs derived from stable docs, the media matrix, current app behavior, and product gaps rather than legacy media files. * Use provider names, model/tool names, generation dates, non-sensitive IDs, byte sizes, dimensions or duration, and reviewed cost estimates; do not store raw provider request/response payloads. * Preserve the public demo standalone boundary. This session may catalog or document demo media, but should not change service-worker cache behavior. * Keep optional video deferred unless a concrete product use and provider-safe brief are approved during implementation. ### Potential Challenges * Provider credentials may not exist locally: record deferrals and dry-run evidence rather than exposing or fabricating secret-dependent outputs. * Cost or terms uncertainty may block generation: capture the blocker in the manifest and leave the target non-runtime. * Manifest records could imply approval: keep statuses blocked and ensure catalog tests prove generated draft records are not release-ready. * Script logs could leak paths or command bodies: redact summaries and write only repository-relative or ignored staging paths. * Scope could bleed into promotion or runtime playback: leave optimization, metadata stripping, audio controls, demo cache updates, and release gates to later sessions. ### 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. * \[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. * \[P03] **Redaction is boundary-specific**: media catalogs, previews, runtime errors, replay/export surfaces, and future hosted paths need explicit minimization. * \[P03] **Local-first boundary is architectural**: provider use must be local, explicit, and optional; core workflows must work without hosted accounts. * \[P03] **Stable docs are the current contract**: use README files, docs, the Phase 04 matrix, and typed catalog fixtures as current truth. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Provider commands could expose secret values, raw prompts, account identifiers, or command bodies. * Generated drafts could be mistaken for release-ready runtime media. * Local output staging could accidentally create tracked binary assets or public-demo cache changes. *** ## 9. Testing Strategy ### Unit Tests * Test app catalog fixture changes with the protocol validator and release-ready helpers. * Test that generated-reference or planned draft records remain blocked and expose no approved runtime paths. * Test manifest check behavior through valid, missing-field, unsafe-path, and missing-blocker fixtures where practical. ### Integration Tests * Run `npm run media:drafts:check`. * Run `npm run media:drafts -- --dry-run`. * Run `npm --workspace apps/web run typecheck`. * Run focused Vitest coverage for `apps/web/tests/mediaCatalog.test.ts`. * Run `git diff --check`. ### Manual Testing * Review the target list against `.spec_system/PRD/phase_04/media_gap_matrix.md` S0403 rows. * Review generated or deferred manifest records for source, rights, cost, disposition, output path, and blocker completeness. * Confirm raw outputs are under `tmp/media-generation/phase04-session03/` and are not tracked. * Confirm no app runtime component, public-demo service worker, public-demo cache list, or release docs file treats drafts as approved media. ### Edge Cases * Missing `FAL_KEY` or `ELEVENLABS_API_KEY`. * Provider command timeout, rate limit, or partial failure. * Missing byte size, dimensions, or duration for a staged output. * Unsafe absolute path, parent path, remote URL, or `EXAMPLES/` path in the manifest. * Optional audio or music draft without visible-equivalent or caption notes. * Provider output selected for review but rejected for rights, cost, quality, format, or accessibility reasons. *** ## 10. Dependencies ### External Libraries * Existing Node 20 runtime and built-in `fetch`, `fs`, `path`, and `crypto` modules. * Existing media tooling verified by `npm run media:check`. * No new runtime dependency is required unless implementation proves the provider API needs a small, reviewed client package. ### Other Sessions * **Depends on**: `phase04-session01-media-requirements-and-provenance-baseline`, `phase04-session02-typed-media-catalog-contracts` * **Depended by**: `phase04-session04-visual-promotion-tooling-and-budgets`, `phase04-session05-browser-audio-runtime-and-controls`, `phase04-session06-public-demo-media-parity-and-offline-loading`, `phase04-session07-media-accessibility-privacy-and-performance-gates`, `phase04-session08-media-validation-and-documentation-closeout` *** ## Next Steps Session work is complete. Use the validation and updateprd reports to close the session, then return to `plansession` if Phase 04 still has remaining sessions. --- # 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-session03-draft-asset-generation-and-source-capture/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.