> 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-session04-visual-promotion-tooling-and-budgets/spec.md).

# Session Specification

**Session ID**: `phase04-session04-visual-promotion-tooling-and-budgets` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Not Started **Created**: 2026-05-29 **Package**: cross-cutting **Package Stack**: Node 20 repository scripts, TypeScript catalog fixtures, static public demo assets, stable docs

***

## 1. Session Overview

This session creates repeatable visual media promotion tooling for FactionOS. It turns the Phase 04 media matrix, the typed catalog records, and the Session 03 draft manifest into executable checks for visual inventory, runtime paths, metadata policy, dimensions, byte budgets, app/demo parity, public-demo cache coverage, and documentation references.

The work is deliberately cross-cutting. The command surface lives in repository scripts, the source evidence spans `assets/`, `apps/web`, `public-demo`, and `docs/`, and the implementation must preserve the existing battlefield parity gate while broadening the promotion model for portraits, brand media, showcase media, generated references, and future visual drafts.

This session does not promote new generated media into runtime. It gives later Phase 04 sessions a dependable gate so visual assets cannot move from draft or conditional status to runtime use without source, rights, optimization, metadata, fallback, parity, accessibility, privacy, and size-budget evidence.

***

## 2. Objectives

1. Add a root visual promotion check that validates visual catalog inventory, repository-relative paths, expected formats, dimensions, byte sizes, metadata policy, and release blockers.
2. Preserve the existing battlefield app/demo parity gate and align its constants or coverage with the broader visual promotion command.
3. Validate shared visual media paths across `assets/`, `apps/web/public/`, `public-demo/`, service-worker cache entries, and stable docs.
4. Document local promotion prerequisites, failure remediation, and the non-runtime boundary for generated draft visual records.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase04-session01-media-requirements-and-provenance-baseline` - provides the media matrix, taxonomy, owner routing, and release-blocker baseline.
* [x] `phase04-session02-typed-media-catalog-contracts` - provides typed media catalog records, validation helpers, and current app-facing fixtures.
* [x] `phase04-session03-draft-asset-generation-and-source-capture` - provides redacted draft briefs and a non-runtime generation manifest.

### Required Tools/Knowledge

* Node 20 and npm workspace scripts.
* Existing `npm run media:check`, `npm run battlefield:check`, and `npm run media:drafts:check` behavior.
* `sharp`, ExifTool, WebP tools, ImageMagick, SVGO, and file-system metadata checks already verified by `npm run media:check`.
* Phase 04 media matrix rows M04-001 through M04-011, M04-021 through M04-031 for visual promotion scope.

### Environment Requirements

* Run commands from the repository root.
* `.env.local` provider credentials are not required for this session.
* No `EXAMPLES/` file may be copied, transformed, optimized, or promoted into a runtime, public-demo, docs, or release artifact path.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can run a root command to validate cataloged visual media promotion readiness - implement a deterministic Node script with explicit report codes and nonzero exit on blocking failures.
* Maintainers can verify image inventory, formats, dimensions, byte budgets, metadata state, and repository-relative paths - use current catalog evidence, script config, `sharp`, file stats, and bounded path allowlists.
* Maintainers can keep app and public demo copies aligned - preserve the battlefield parity gate and add broader mirror/cache/docs checks for visual categories that are shared across surfaces.
* Maintainers can see why a visual record is blocked - treat conditional, planned, deferred, prototype-only, rejected, unknown, and draft records as non-release unless blockers and conditions are explicit.
* Maintainers can remediate failures locally - document tool prerequisites, expected outputs, budget policies, metadata policy, and docs/cache update rules.

### Out of Scope (Deferred)

* Generating or regenerating provider-backed visual assets - *Reason: Session 03 captured non-runtime draft evidence; promotion tooling should not create media.*
* Browser audio runtime behavior - *Reason: Session 05 owns audio playback, settings, captions, and cleanup.*
* Public demo offline validation for changed media lists - *Reason: Session 06 owns full public-demo media parity and offline reload evidence.*
* Accessibility, privacy, and performance release certification - *Reason: Session 07 owns release-wide gates; this session records blockers and prepares the visual subset.*
* Adding a sprite atlas - *Reason: no Phase 04 matrix row proves standalone visual files are insufficient.*

***

## 5. Technical Approach

### Architecture

Add a repository-root visual promotion check under `scripts/` and expose it through `package.json`. The check should use a small explicit config for the visual groups currently owned by S0404: battlefield runtime, battlefield references, portraits, brand icons, showcase assets, generated visual drafts, HUD/achievement draft placeholders, and quarantined or deferred visual rows.

The script should avoid ad hoc broad filesystem scans. It should validate only repository-relative paths declared by the config, catalog fixtures, stable docs, or the Session 03 manifest. It should report structured error and warning codes for missing files, unsupported formats, unexpected dimensions, byte-budget drift, metadata policy drift, stale docs references, public-demo cache drift, workspace import risks, and accidental `EXAMPLES/` promotion.

The existing battlefield parity gate remains authoritative for the current six runtime battlefield files. This session may extract shared constants or invoke the battlefield check from the broader promotion flow, but it must not weaken the six-asset parity, hash, budget, service-worker, or docs checks.

### Design Patterns

* Explicit manifest over broad discovery: limits false positives and prevents quarantined media from slipping into runtime paths.
* Bounded path validation: rejects absolute, remote, parent-directory, and `EXAMPLES/` paths before probing files.
* Structured report codes: makes failures actionable in local runs and CI.
* Catalog-first promotion: approved runtime use requires catalog records and release-gate evidence before asset references expand.
* Stable docs as contract: docs and README updates describe how to fix common check failures.

### Technology Stack

* Node 20 ES modules in `scripts/`.
* Built-in `fs`, `path`, `crypto`, and `child_process` APIs.
* Existing media tooling packages verified by `npm run media:check`, including `sharp` and ExifTool.
* Vitest for focused node-side tests.
* Biome for format and lint checks.

***

## 6. Deliverables

### Files to Create

| File                                        | Purpose                                                                                                     | Est. Lines |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/media-visual-promotion-config.mjs` | Declared visual groups, budgets, dimensions, docs references, metadata policy, and safe path prefixes.      | \~180      |
| `scripts/check-visual-media-promotion.mjs`  | Root CLI for visual inventory, metadata, budget, parity, docs, draft, and quarantine checks.                | \~360      |
| `tests/mediaVisualPromotion.test.ts`        | Focused tests for config shape, path rejection, budget semantics, report codes, and blocked draft behavior. | \~170      |

### Files to Modify

| File                                                                                                | Changes                                                                                                             | Est. Lines |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- |
| `package.json`                                                                                      | Add a root `media:visual:check` script and optionally include it in documented media validation flow.               | \~4        |
| `vitest.config.ts`                                                                                  | Include top-level node tests if needed for script coverage.                                                         | \~8        |
| `scripts/check-battlefield-assets.mjs`                                                              | Preserve current parity behavior while sharing or aligning constants with visual promotion coverage when practical. | \~60       |
| `scripts/README_scripts.md`                                                                         | Document the new visual promotion command, prerequisites, and failure remediation.                                  | \~50       |
| `docs/media-assets.md`                                                                              | Document the Session 04 visual promotion flow and current visual release blockers.                                  | \~80       |
| `assets/README_assets.md`                                                                           | Clarify promotion paths for references, brand/showcase media, generated drafts, and runtime copies.                 | \~40       |
| `.spec_system/specs/phase04-session04-visual-promotion-tooling-and-budgets/implementation-notes.md` | Record implementation decisions, prerequisite outputs, and validation evidence.                                     | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `npm run media:visual:check` exists and validates current visual media paths, dimensions, byte budgets, metadata policy, docs references, and blocked non-release states.
* [ ] Existing `npm run battlefield:check` behavior remains passing and keeps app/demo battlefield hashes, byte budgets, service-worker coverage, and docs references intact.
* [ ] Visual promotion checks reject absolute paths, remote paths, parent directory traversal, direct `EXAMPLES/` promotion, missing files, unsupported formats, and stale public-demo cache entries.
* [ ] Conditional, planned, deferred, prototype-only, rejected, and unknown visual records cannot appear release-ready without explicit blocker context.
* [ ] Docs explain how maintainers add or promote visual media without copying quarantined assets or exposing provider secrets.

### Testing Requirements

* [ ] Focused Vitest coverage written and passing for visual promotion helpers.
* [ ] `npm run media:visual:check` passes.
* [ ] `npm run battlefield:check` passes.
* [ ] `npm run media:drafts:check` passes.

### Non-Functional Requirements

* [ ] Command output uses deterministic ordering and stable report codes.
* [ ] Checks avoid logging provider secrets, raw prompt context, absolute local paths, account identifiers, or raw provider payloads.
* [ ] Script runtime remains local-first and does not require hosted services, provider credentials, analytics, or network access.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `npm run format:check`, focused tests, and media gates pass or have documented blockers in implementation notes.

***

## 8. Implementation Notes

### Key Considerations

* `npm run media:check`, `npm run battlefield:check`, and `npm run media:drafts:check` passed during planning on 2026-05-29.
* Current battlefield runtime bytes are 668,358 per surface; reference bytes are 15,542,218; public-demo service-worker cache version is `factionos-demo-v9`.
* Visual promotion should build on current catalog records in `apps/web/src/data/mediaCatalog.ts` without requiring the public demo to import workspace TypeScript.

### Potential Challenges

* TypeScript catalog data is not directly executable from plain Node scripts: use explicit script config or generated-safe data instead of brittle TS source parsing.
* Metadata probes may vary across tools: make release-blocking checks rely on deterministic file/path/config state and keep host-tool details bounded.
* Existing battlefield checks are narrower but stable: preserve them as a separate gate unless shared constants can be extracted without churn.

### Relevant Considerations

* \[P00] **Asset provenance gate**: Promotion tooling must block unknown source, rights, attribution, optimization, metadata, and size-budget gaps.
* \[P03] **Redaction is boundary-specific**: Reports and docs must avoid raw prompts, tokens, provider payloads, broad local paths, and `EXAMPLES/` excerpts.
* \[P03] **Stable docs are the current contract**: Update docs and README files for command behavior and remediation.
* \[P02] **Explicit asset parity checks catch app/demo drift sooner**: Preserve and extend deterministic parity checks rather than relying on browser inspection alone.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* A script accepts an unsafe path and probes or promotes media outside declared repository surfaces.
* A media record appears release-ready even though provenance, metadata, attribution, fallback, or blocker context is incomplete.
* Tool output leaks sensitive local paths, provider details, raw prompt context, or quarantined historical excerpts while explaining failures.

***

## 9. Testing Strategy

### Unit Tests

* Validate visual promotion config records for required ids, declared safe path prefixes, deterministic ordering, allowed formats, and blocker context.
* Validate path rejection for absolute, remote, parent-directory, and `EXAMPLES/` paths.
* Validate budget and report-code semantics with small test fixtures.

### Integration Tests

* Run `npm run media:visual:check`.
* Run `npm run battlefield:check`.
* Run `npm run media:drafts:check`.

### Manual Testing

* Review command output for actionable remediation and no sensitive local path or provider-secret exposure.
* Review docs to confirm a maintainer can add or promote a visual asset through catalog, promotion, docs, app/demo parity, and cache checks.

### Edge Cases

* Missing app asset with existing public-demo mirror.
* Public-demo cache entry points to a missing or stale visual path.
* Conditional or planned visual record has no release blockers.
* Metadata is pending for a runtime-approved visual asset.
* Docs reference an app/demo path that no longer exists.

***

## 10. Dependencies

### External Libraries

* `sharp`: image metadata and format probing.
* `exiftool-vendored`: metadata inspection when needed.
* `svgo`, `oxipng`, WebP tools, AVIF encoder, ImageMagick, FFmpeg, and ffprobe: prerequisite media tooling checks already covered by `npm run media:check`.

### Other Sessions

* **Depends on**: `phase04-session01-media-requirements-and-provenance-baseline`, `phase04-session02-typed-media-catalog-contracts`, `phase04-session03-draft-asset-generation-and-source-capture`.
* **Depended by**: `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

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-session04-visual-promotion-tooling-and-budgets/spec.md?ask=<question>&goal=<endgoal>
```

`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.