> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session10-assets-and-media-compliance/spec.md).

# Session Specification

**Session ID**: `phase40-session10-assets-and-media-compliance` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 6ffd21e988c9eb52fde381b0743ce6cd9aaa1797

***

## 1. Session Overview

This session closes the Phase 40 media gap before the chat selector and Ministry UI sessions depend on provider visuals. The current repo already contains the 15 staged upstream provider SVG files at `src/assets/logo-*.svg` and an optimized `src/assets/ministry-hero.webp` copy, but the final AI OS paths, duplicate decisions, SVG safety evidence, and reusable lookup contract still need to be recorded.

The session is next because Sessions 01 and 09 are complete. Session 01 recorded the media invariants and the upstream hero-size risk, while Session 09 completed the final Ministry model-intelligence lineup that the asset audit can use. Session 10 turns those facts into a small, tested asset registry and an asset provenance record without wiring new product UI.

The implementation keeps the port semantic rather than wholesale. Provider logos should be rehomed under AI OS logo conventions, the optimized Ministry hero should stay under the media-policy cap, and future UI sessions should have a stable import helper instead of importing raw upstream asset paths directly.

***

## 2. Objectives

1. Rehome the 15 staged provider logo SVGs into the AI OS logo asset namespace and remove root-level provider-logo usage.
2. Verify provider SVG safety, duplicate-logo decisions, Ministry hero size, and media-policy compliance with repeatable tests.
3. Add a browser-safe Hermes provider asset registry that maps Phase 40 provider aliases to final logo assets and explicit fallbacks.
4. Record provenance, source-path gap audit, duplicate comparisons, hero compression details, and validation results for later UI sessions.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session01-baseline-and-port-invariants` - Provides Phase 40 media invariants, the upstream media gap, and the decision not to commit the raw oversized upstream Ministry hero.
* [x] `phase40-session09-model-intelligence-and-pricing` - Provides the final Ministry model-intelligence lineup and provider set needed for asset coverage.

### Required Tools Or Knowledge

* Bun 1.3.14, Vitest, TypeScript, ESLint, and Prettier.
* Existing AI OS media policy in `docs/media-policy.md`.
* Existing Hermes model catalog and provider presentation helpers in `scripts/lib/hermes-dev-bridge.ts` and `scripts/lib/hermes-provider-readiness.ts`.
* Shell tools available in the repo environment: `rg`, `file`, `du`, and `bash scripts/check-asset-sizes.sh`.

### Environment Requirements

* No external credentials, network access, image-generation service, database, migration tool, or upstream checkout access is required.
* Work is limited to committed repo assets and source files.

***

## 4. Scope

### In Scope (MVP)

* Hermes maintainers can audit the 15 staged upstream provider logo SVGs - Rehome them to `src/assets/logos/hermes/`, verify forbidden SVG constructs are absent, and record final source-to-target mapping.
* Hermes maintainers can keep the optimized Ministry visual policy-compliant - Retain `src/assets/ministry-hero.webp` as the 520x654, 185,156-byte AI OS copy unless validation unexpectedly fails.
* Future UI sessions can use provider visuals without raw path guessing - Add a typed browser helper under `src/lib/` with provider alias lookup, alt labels, logo source metadata, and null fallbacks for providers without approved logos with types matching declared contract; exhaustive enum handling.
* Developers can rerun asset safety checks - Add script-side audit coverage for expected files, size caps, unsafe SVG tokens, duplicate decisions, and root path cleanup.
* Session evidence is preserved - Write asset provenance notes with source paths, duplicate comparisons, media-policy checks, and command results.

### Out Of Scope (Deferred)

* Chat selector UI wiring - Reason: Session 11 owns the chat model selector and context meter.
* Ministry builder or Pantheon UI rendering - Reason: Sessions 14 and 15 own Ministry product integration, analytics, and save UX.
* New media policy exceptions - Reason: Phase 40 explicitly requires no media policy exceptions for this port.
* Adding upstream media outside the audited 2.8.1 to 2.10.1 gap - Reason: Session 10 is limited to the listed provider logos and optimized Ministry hero.
* Changing AI OS package identity, graph files, or public demo fixture data - Reason: these are separate Phase 40 boundaries.

***

## 5. Technical Approach

### Architecture

Move the staged provider logo SVGs out of the root `src/assets/` namespace and into `src/assets/logos/hermes/`. Keep the final filenames stable and provider-oriented so later UI code can import from one namespace. The existing `src/assets/logos/` assets remain available for already-shipped host surfaces; Session 10 should document when a staged Hermes logo duplicates an existing AI OS logo and why the final Hermes asset path is still retained or mapped to the existing logo.

Add `scripts/lib/hermes-media-audit.ts` as a script-side asset audit owner. It should expose deterministic expected-file metadata, forbidden SVG pattern checks, logo and hero byte-size checks, root-path cleanup checks, and duplicate decision output. Tests should read the actual files from disk rather than testing only hardcoded constants.

Add `src/lib/hermes-provider-assets.ts` as the browser-facing asset registry. It should import final logo assets and the Ministry hero, normalize supported provider aliases from the Hermes catalog and Ministry model intelligence rows, return product-safe labels and alt text, and return `null` for providers whose logo is not part of the approved Session 10 media gap.

### Design Patterns

* Existing asset namespace: Provider logos live under `src/assets/logos/`, matching the media policy and current home/setup logo patterns.
* Parser-like helper boundary: Normalize provider aliases in a shared helper so UI components do not duplicate provider-id conditionals.
* Filesystem-backed audit tests: Validate the actual committed media files for size, unsafe SVG constructs, path cleanup, and provenance alignment.
* Product-surface separation: Add no visible route copy in this session; later UI sessions can consume the registry.

***

## 6. Deliverables

### Files To Create

| File                                                                                   | Purpose                                                                                                                     | Est. Lines |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/assets/logos/hermes/*.svg`                                                        | Final rehomed Hermes provider logo assets from the staged root SVG set                                                      | \~15 files |
| `scripts/lib/hermes-media-audit.ts`                                                    | Deterministic media audit owner for expected assets, size caps, SVG safety, duplicate decisions, and path cleanup           | \~220      |
| `scripts/lib/__tests__/hermes-media-audit.test.ts`                                     | Tests for provider-logo inventory, forbidden SVG tokens, size caps, root cleanup, hero compliance, and provenance decisions | \~190      |
| `src/lib/hermes-provider-assets.ts`                                                    | Browser-safe Hermes provider logo and Ministry hero registry with alias normalization and fallbacks                         | \~170      |
| `src/lib/__tests__/hermes-provider-assets.test.ts`                                     | Tests for provider alias lookup, fallback behavior, product labels, alt text, and Ministry hero metadata                    | \~150      |
| `.spec_system/specs/phase40-session10-assets-and-media-compliance/asset-provenance.md` | Source-path gap audit, final path decisions, duplicate comparisons, hero compression details, and validation evidence       | \~170      |

### Files To Modify

| File                            | Changes                                                                                                                                               | Est. Lines              |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `src/assets/logo-*.svg`         | Remove root-level staged provider logo paths by moving them to `src/assets/logos/hermes/`                                                             | \~15 files moved        |
| `src/assets/ministry-hero.webp` | Retain the optimized AI OS Ministry hero and verify it remains under the non-logo asset cap                                                           | no byte change expected |
| `docs/media-policy.md`          | Update only if implementation finds a current-policy ambiguity that must be documented; otherwise leave unchanged and record compliance in provenance | \~0-20                  |

***

## 7. Success Criteria

### Functional Requirements

* [ ] The 15 staged provider SVGs are rehomed under `src/assets/logos/hermes/` with no root-level `src/assets/logo-*.svg` files left behind.
* [ ] The Hermes provider asset registry returns approved logo assets for the Phase 40 providers covered by the staged media gap and returns explicit null fallbacks for uncovered providers.
* [ ] `src/assets/ministry-hero.webp` is retained as the optimized AI OS copy and remains under the 200 KB non-logo cap.
* [ ] Asset provenance records source-path gap audit, duplicate logo decisions, final path decisions, hero compression details, and validation commands.

### Testing Requirements

* [ ] Script-side media audit tests pass.
* [ ] Browser-side provider asset registry tests pass.
* [ ] `bash scripts/check-asset-sizes.sh` passes.
* [ ] Focused Vitest command for media audit and provider registry passes.

### Non-Functional Requirements

* [ ] SVG logos contain no `<script>`, `foreignObject`, inline event handlers, `javascript:`, data URI, or external href patterns.
* [ ] Logo assets stay below the 500 KB manual-review cap from `docs/media-policy.md`.
* [ ] Browser-facing asset metadata contains no upstream local absolute paths, raw home-directory paths, auth material, tokens, prompts, transcripts, or private generated data.
* [ ] No product route renders new debug or scaffold copy in this session.

### Quality Gates

* [ ] All files ASCII-encoded where applicable.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new global `findtrend` identifiers.
* [ ] Primary user-facing surfaces contain product-facing copy only; no new visible UI surface is expected in this session.

***

## 8. Implementation Notes

### Working Assumptions

* The upstream checkout is not required for Session 10 implementation: the Phase 40 PRD, Session 01 artifacts, and current repo asset inventory already identify the upstream media gap, source paths, optimized hero copy, and staged provider SVG set. Planning can proceed because the session work is a repo-local audit and rehome of those committed/staged files.
* A shared provider asset registry is the right amount of UI preparation: Sessions 11, 14, and 15 own visible selector and Ministry surfaces, while Session 10 owns the final media paths and reusable lookup contract those sessions can consume.

### Conflict Resolutions

* Root-staged provider logos versus AI OS logo conventions: the Phase 40 stub says the upstream gap is staged as `src/assets/logo-*.svg`, while `docs/media-policy.md` and `.spec_system/CONVENTIONS.md` identify `src/assets/logos/` as the logo namespace. The chosen interpretation is to rehome the 15 provider logos under `src/assets/logos/hermes/` and document the final source-to-target mapping because no current code imports the root paths.
* Asset readiness versus product UI wiring: the session acceptance criteria require compliant assets, not a rendered selector or Ministry builder. The chosen interpretation is to add registry and tests only, leaving visible UI consumption to Sessions 11, 14, and 15 as defined by the Phase 40 PRD.

### Key Considerations

* Keep the raw oversized upstream Ministry hero out of the repo; retain the optimized AI OS copy unless validation fails.
* Keep duplicate logo decisions explicit so future UI sessions know whether to use a Hermes-specific logo asset or an existing AI OS logo.
* Avoid external CDN logo fetches for the covered Phase 40 provider set where a committed asset now exists.
* Keep provenance notes browser-safe by using repo-relative paths and upstream version labels, not local absolute paths in runtime code.

### Potential Challenges

* Provider alias mismatch: Use the existing provider readiness/catalog aliases as evidence, then add registry tests for common aliases such as `anthropic`, `anthropic-oauth`, `openai`, `openai-codex`, `googlegemini`, `gemini`, `xai`, `xai-oauth`, `zai`, and `kimi-coding`.
* Duplicate logos: Keep the duplicate comparison in provenance and tests so duplicate root usage does not leak into later UI wiring.
* SVG false positives: Keep the forbidden-token check targeted to executable or external-reference constructs; normal SVG path, fill, viewBox, and title content should remain allowed.
* Asset-size drift: Enforce the Ministry hero with the existing size script and logo manual-review caps with the media audit tests.

### Relevant Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Rehome and document media assets inside AI OS owners instead of preserving upstream root paths as product contracts.
* \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Media changes require asset-size and browser-safe/private-output checks before widening visibility.
* \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, and existing `src/assets/`, `src/lib/`, `scripts/lib/`, and local test placement remain baseline constraints.
* \[P38] **Do not copy upstream flat files wholesale**: Asset usage should be adapted into current AI OS asset namespaces and provenance records.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Future UI can show broken or duplicate logos if provider aliases are not normalized centrally; tasks include registry helpers and alias tests.
* Browser-facing metadata can accidentally expose local upstream paths if provenance and runtime metadata are mixed; tasks keep runtime metadata repo-relative and provenance in session artifacts.
* SVG assets can introduce executable or external-reference constructs; tasks include file-backed forbidden-token tests and focused audit coverage.

***

## 9. Testing Strategy

### Unit Tests

* Test `scripts/lib/hermes-media-audit.ts` for expected provider-logo inventory, rehomed paths, root-path cleanup, forbidden SVG tokens, logo manual-review caps, Ministry hero cap, and duplicate-decision output.
* Test `src/lib/hermes-provider-assets.ts` for provider alias normalization, logo lookup, null fallback for uncovered providers, product-safe labels, descriptive alt text, and Ministry hero metadata.

### Integration Tests

* Run focused Vitest covering both script-side media audit tests and browser-side provider asset registry tests.
* Run TypeScript checks for app and script code to prove imports and filesystem audit types remain valid.

### Runtime Verification

* Run `bash scripts/check-asset-sizes.sh`.
* Run `rg -n "src/assets/logo-|@/assets/logo-" src scripts docs .spec_system` and confirm only historical/provenance references remain.
* Run `file` and non-ASCII/CRLF scans on changed source, tests, and session artifacts.

### Edge Cases

* Missing or accidentally retained root provider logo paths.
* Provider aliases that should resolve to the same logo, including OAuth and upstream-compatible aliases.
* Providers in the catalog that have no approved logo in the Session 10 media gap.
* SVG files containing executable constructs, external references, or embedded data URIs.
* Ministry hero replaced with a file over the 200 KB cap.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session01-baseline-and-port-invariants`, `phase40-session09-model-intelligence-and-pricing`
* Depended by: `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session14-ministry-builder-and-pantheon`, `phase40-session15-ministry-config-analytics-and-save-ux`, `phase40-session18-full-validation-and-handoff`

***

## Next Steps

Run the `implement` workflow step to begin 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://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session10-assets-and-media-compliance/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.