> 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/phase13-session05-asset-pipeline-and-brand-media-prep/spec.md).
# Session Specification
**Session ID**: `phase13-session05-asset-pipeline-and-brand-media-prep` **Phase**: 13 - Public Website Foundation **Status**: Complete **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro 6.4.2 / TypeScript 5.9.3 static site
***
## 1. Session Overview
This session completes the Phase 13 public website foundation by preparing approved brand and showcase media for the Astro website. Sessions 01-04 created the static Astro workspace, layout shell, metadata plumbing, blog/news publishing routes, RSS, and sitemap behavior. Session 05 adds the reviewed asset layer those surfaces can use for social previews, press downloads, future homepage visuals, and optimized Astro image examples.
The work matters because later homepage, product, trust, and conversion pages need real FactionOS media without weakening the existing media provenance boundary. The implementation should reuse tracked brand and showcase assets only when their source and release posture are documented, and it should keep unknown-provenance, generated draft, historical, audio, and video assets out of the website release path.
The session remains static-site-only. It does not add a CMS, analytics, hosted forms, auth, a server adapter, automated social-image generation, final press kit copy, broad media-readiness claims, or production-hosted validation claims.
***
## 2. Objectives
1. Review the existing brand and showcase media inventory and record which assets are launch-ready, conditional, or blocked for website use.
2. Prepare package-local `public-website/src/assets/` brand and showcase assets for Astro optimization without promoting unknown media.
3. Establish a durable Open Graph fallback image, favicon/manifest posture, and press pass-through folder policy.
4. Add reusable optimized image usage patterns and metadata wiring that later website pages can consume safely.
***
## 3. Prerequisites
### Required Sessions
* [x] `phase13-session01-astro-scaffold-and-workspace-wiring` - Provides the Astro workspace, package scripts, image integration dependencies, and static output posture.
* [x] `phase13-session02-design-tokens-and-layout-shell` - Provides shared layout, global styles, and reusable Astro component patterns.
* [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - Provides site data, SEO components, robots, manifest, sitemap, and RSS foundation.
* [x] `phase13-session04-content-collections-and-publishing-templates` - Provides publishing routes that can later consume article hero images.
### Required Tools/Knowledge
* Astro image asset handling with `src/assets/`, ``, and ``.
* Existing media promotion posture in `docs/media-assets.md` and `assets/README_assets.md`.
* Existing public website metadata helpers and SEO component contracts.
* Root media gates, Biome, package typecheck, package build, and ASCII/LF validation.
### Environment Requirements
* Node.js 26.2.0 or newer and npm 11.16.0 per repository baseline.
* On this machine, prepend `/home/aiwithapex/.nvm/versions/node/v26.2.0/bin` to `PATH` before package commands if the default shell resolves Node 24.
* Validation runs from the repository root or with `--workspace @factionos/public-website`.
***
## 4. Scope
### In Scope (MVP)
* Website maintainers can inspect asset release status before use - Record source, current location, intended website destination, and blockers for every imported brand or showcase asset.
* Page builders can import package-local media through Astro - Copy approved brand and showcase files into `public-website/src/assets/brand/` and `public-website/src/assets/showcase/` where optimization is intended.
* Social previews have a stable fallback - Create or select `public-website/src/assets/brand/og-default.png` from approved brand media and wire site metadata to it.
* Favicons and install metadata stay intentional pass-through assets - Review or refine `public-website/public/favicon.svg` and `public-website/public/site.webmanifest` without implying a hosted app or PWA install promise.
* Press downloads have a clear pass-through boundary - Create `public-website/public/press/` guidance and copy only approved launch files if available.
* Astro image usage is reusable - Add a package-local media registry and component example for optimized images with required alt text, dimensions, fallback copy, and provenance notes.
### Out of Scope (Deferred)
* Promoting unknown-provenance, generated draft, or historical media - *Reason: these require separate promotion evidence and rights review.*
* Full press kit copy and layout - *Reason: Phase 15 owns press and company page content.*
* Automated social-image generation - *Reason: this session creates a static fallback asset only.*
* Broad media-readiness claims - *Reason: existing security and media records keep most non-battlefield media conditional or blocked.*
* Audio or video pipeline work - *Reason: current website foundation is static visual media only.*
* Final homepage visual composition - *Reason: Phase 14 owns the homepage and product story implementation.*
***
## 5. Technical Approach
### Architecture
The website stays a static Astro package. Source-optimized website images live under `public-website/src/assets/`, while intentionally pass-through downloads and browser metadata files stay under `public-website/public/`. The session should first inventory the shared `assets/brand/` and `assets/showcase/` inputs, then copy only reviewed assets into package-local website paths.
The package should expose a small typed media registry, likely under `public-website/src/lib/media.ts`, that imports approved image assets and centralizes alt text, provenance status, and intended use. Reusable Astro components can consume that registry with `` or ``, giving later pages a working pattern without finishing their page designs.
Metadata wiring should move the default social image away from the favicon and toward the approved Open Graph fallback. The SEO path must keep absolute URL output, static build behavior, and no-tracking posture. Press files in `public/press/` bypass Astro processing by design and must be documented as download assets, not as an unchecked dumping ground.
### Design Patterns
* Provenance before import: Review and record asset status before package-local website copies are created.
* Source assets for optimized content: Put page media in `src/assets/` when Astro should optimize it.
* Explicit pass-through boundary: Keep only favicons, manifests, and approved downloadable press files in `public/`.
* Typed media registry: Keep image imports, alt text, and use cases in one component-facing source of truth.
* No-overclaim copy: Keep media, hosted, analytics, certification, and production validation claims scoped to existing evidence.
### Technology Stack
* Astro: 6.4.2
* `astro:assets` with `` and ``
* `sharp`: 0.34.5
* TypeScript: 5.9.3
* Biome: root formatting and linting
***
## 6. Deliverables
### Files to Create
| File | Purpose | Est. Lines |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase13-session05-asset-pipeline-and-brand-media-prep/asset-provenance-notes.md` | Website asset inventory, launch status, and blockers | \~120 |
| `public-website/src/assets/brand/factionos-logo.webp` | Package-local optimized logo source | binary |
| `public-website/src/assets/brand/factionos-logo-square.webp` | Package-local square logo source | binary |
| `public-website/src/assets/brand/og-default.png` | Default Open Graph/social preview image | binary |
| `public-website/src/assets/showcase/factionos-strip.webp` | Package-local animated showcase strip | binary |
| `public-website/src/assets/showcase/factionos-strip-cover.jpg` | Package-local static fallback cover | binary |
| `public-website/src/assets/showcase/heroes-banner.jpg` | Package-local showcase banner source | binary |
| `public-website/src/assets/showcase/strip-frames/1-dusk_muster.jpg` | Package-local first strip frame source | binary |
| `public-website/src/assets/showcase/strip-frames/2-mid_combat.jpg` | Package-local second strip frame source | binary |
| `public-website/src/assets/showcase/strip-frames/3-victory_chorus.jpg` | Package-local third strip frame source | binary |
| `public-website/src/assets/showcase/strip-frames/4-night_watch.jpg` | Package-local fourth strip frame source | binary |
| `public-website/src/lib/media.ts` | Typed website media registry with imports, alt text, and provenance status | \~140 |
| `public-website/src/components/media/OptimizedMedia.astro` | Reusable optimized image/picture usage pattern | \~130 |
| `public-website/public/press/README.md` | Press pass-through asset policy and launch-file notes | \~60 |
### Files to Modify
| File | Changes | Est. Lines |
| --------------------------------------------- | ---------------------------------------------------------------------- | ---------- |
| `public-website/public/favicon.svg` | Review or refine current favicon from approved brand mark | \~15 |
| `public-website/public/site.webmanifest` | Keep browser metadata aligned with static website posture | \~25 |
| `public-website/src/data/site.ts` | Wire default social image metadata and image alt text | \~25 |
| `public-website/src/lib/metadata.ts` | Support social image card behavior needed by the approved fallback | \~30 |
| `public-website/src/components/seo/Seo.astro` | Emit complete social preview metadata without breaking existing routes | \~25 |
| `public-website/README_public-website.md` | Document package-local asset placement and validation commands | \~35 |
***
## 7. Success Criteria
### Functional Requirements
* [ ] Approved website media exists under `public-website/src/assets/` where Astro should optimize it.
* [ ] `public-website/public/` contains only intentional pass-through assets such as favicon, manifest, robots, and documented press downloads.
* [ ] The default Open Graph fallback image exists and is wired through the SEO metadata path.
* [ ] Favicon and manifest files remain present and aligned with the static public website boundary.
* [ ] The website has a reusable Astro optimized image pattern with required alt text and deterministic fallback behavior.
* [ ] No unknown-provenance, generated draft, quarantined, audio, video, or non-release media is promoted by implication.
### Testing Requirements
* [ ] Package typecheck passes.
* [ ] Package build passes.
* [ ] Focused Biome lint and format checks pass for touched website and session files.
* [ ] Relevant media gates are run or explicitly recorded as not applicable to unchanged shared media inventories.
* [ ] Generated HTML metadata is inspected for absolute social image URLs.
### Non-Functional Requirements
* [ ] Static Astro output remains the deployment model.
* [ ] No analytics, trackers, hosted forms, auth, CMS adapter, React, Tailwind, server adapter, or runtime personalization is added.
* [ ] Binary media copies remain bounded to reviewed, source-backed assets.
* [ ] Asset copy and press-folder decisions preserve local-first, no-overclaim, and provenance boundaries.
### Quality Gates
* [ ] All text files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
***
## 8. Implementation Notes
### Key Considerations
* `public-website/public/favicon.svg` and `public-website/public/site.webmanifest` already exist from Session 03; this session should review and refine them, not duplicate them.
* Current social metadata uses the favicon as the default social image. This session should provide a stronger `og-default.png` fallback from approved brand media.
* `assets/showcase/factionos-website-mockup.png` is referenced as a possible canonical design blueprint, but the file is not present in the current asset inventory. Record that as absent rather than inventing a canonical mockup.
* Press files in `public/press/` intentionally bypass Astro optimization, so each file there needs an explicit launch reason.
* Existing media records keep many brand/showcase items conditional. Do not convert conditional media into broad release-ready claims.
### Potential Challenges
* Social image URL generation: Use Astro-compatible imports or public output paths so built meta tags resolve to absolute URLs.
* Binary asset drift: Prefer copying reviewed source files exactly unless generating `og-default.png` from an approved source is necessary and documented.
* Media overclaim risk: Keep provenance notes visible and avoid wording that implies formal media readiness, certification, or production-hosted validation.
### Relevant Considerations
* \[P04] **Asset provenance gate remains active**: Brand and showcase media retain blockers until source, rights, attribution, metadata, fallback, accessibility, privacy, and budget evidence closes. This session records launch status instead of broadening release claims.
* \[P08] **Release-candidate evidence is claim-scoped**: Passing local website build or media checks is not production-hosted validation.
* \[P03] **Stable docs are the current contract**: Use `docs/media-assets.md`, `assets/README_assets.md`, and public website README guidance as current asset placement truth.
### Behavioral Quality Focus
Checklist active: Yes Top behavioral risks for this session:
* Imported media could imply approval for conditional or blocked assets.
* Social preview metadata could point to a local-only or non-built asset path.
* Press pass-through files could bypass optimization and provenance review.
* Image examples could omit required alt text or fallback behavior.
***
## 9. Testing Strategy
### Unit Tests
* No dedicated unit tests are expected unless metadata helper behavior changes enough to justify focused coverage.
### Integration Tests
* Run `npm --workspace @factionos/public-website run typecheck`.
* Run `npm --workspace @factionos/public-website run build`.
* Inspect generated HTML for absolute Open Graph and Twitter image metadata.
### Manual Testing
* Confirm copied media appears only in package-local website paths or documented pass-through press paths.
* Confirm favicon and manifest still load from the built site.
* Confirm optimized image component usage has required alt text, dimensions, and fallback behavior.
### Edge Cases
* `assets/showcase/factionos-website-mockup.png` is absent.
* Existing social image defaults point to `/favicon.svg`.
* Press folder may have no approved downloadable files yet.
* Conditional showcase media must not be described as broadly release-ready.
***
## 10. Dependencies
### External Libraries
* No new external libraries are planned.
* Existing `sharp` and Astro image tooling provide optimization support.
### Other Sessions
* **Depends on**: `phase13-session01-astro-scaffold-and-workspace-wiring`, `phase13-session03-seo-metadata-and-static-site-plumbing`, and the completed Session 04 publishing routes.
* **Depended by**: Phase 14 homepage/product story sessions and Phase 15 press, company, content, and conversion pages.
***
## 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/phase13-session05-asset-pipeline-and-brand-media-prep/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.