> 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/docs/media-policy.md). # Media Policy Guidelines for image and media assets committed to the repository. ## Size Limits | Category | Maximum Size | Enforcement | | ----------------------------------------- | ------------- | ------------------------------ | | Non-logo committed asset in `src/assets/` | 200 KB | `scripts/check-asset-sizes.sh` | | AI Rogue music track in `src/assets/` | 900 KB | `scripts/check-asset-sizes.sh` | | Logo asset in `src/assets/logos/` | 500 KB | Manual review | | Public served asset in `public/assets/` | 250 KB target | Manual review | | Total `src/assets/` directory | 15 MB | Manual review | Assets that exceed these limits must be compressed before committing. The check script exits nonzero if any non-logo file in `src/assets/` exceeds its configured limit. AI Rogue music tracks use the larger reviewed cap because looped compressed audio is inherently larger than image assets. Logo files under `src/assets/logos/` are excluded from the automated check because small vendor logos can be hard to convert cleanly; keep them under the 500 KB manual-review ceiling. Public assets are served by path instead of imported through Vite. Keep them compressed and under the 250 KB target unless a route-specific visual asset has been reviewed; `scripts/check-asset-sizes.sh` does not currently enforce `public/assets/`. ## Format Requirements | Use Case | Preferred Format | Notes | | ----------------------- | ---------------- | ---------------------------------------------- | | Photos and rich imagery | WebP | Use `cwebp -q 80` for conversion from PNG/JPG | | Icons and logos | SVG | Vector format scales cleanly at any size | | Simple raster icons | PNG | Only when SVG is unavailable; keep under 50 KB | | Screenshots (docs only) | PNG or WebP | Compress before committing | | Game music | Ogg Opus | 48 kHz stereo, normalized, under 900 KB | | Game theme ambience | Ogg Opus | 48 kHz stereo loop, normalized, under 900 KB | | Game SFX | Ogg Opus | 48 kHz mono, normalized, under 200 KB | ### Why WebP * 70-90% smaller than equivalent PNG for photographic content * Supported by all modern browsers * Vite handles WebP natively with no plugin configuration * Preserves alpha transparency ## Compression Workflow When adding new image assets: 1. Create or obtain the source image in any format 2. Convert to WebP: `cwebp -q 80 input.png -o output.webp` 3. Verify the output is under 200 KB, or under 500 KB for a reviewed logo asset 4. If over 200 KB, lower quality: `cwebp -q 70 input.png -o output.webp` 5. Run `bash scripts/check-asset-sizes.sh` before committing For batch conversion of existing assets: ```bash for f in src/assets/**/*.png; do cwebp -q 80 "$f" -o "${f%.png}.webp" done ``` When adding AI Rogue music: 1. Keep raw generated exports in `tmp/suno/`. 2. Trim loops, ambience beds, and stings to their documented in-game cue lengths. 3. Encode final assets as 48 kHz stereo Ogg Opus and normalize loudness. 4. Verify each final track is under 900 KB. 5. Save provenance beside the final files and rerun `bash scripts/check-asset-sizes.sh`. AI Rogue theme ambience loops use the music workflow and cap. Store final theme ambience loops under `src/assets/ai-rogue/audio/music/`, not `sfx/`, so the runtime can load them through the music asset glob and the size checker applies the reviewed 900 KB music-track limit. Current AI Rogue Phase 36 music inventory, validated on 2026-06-28: * Six primary Ogg Opus music tracks and five Ogg Opus theme ambience loops are committed under `src/assets/ai-rogue/audio/music/`. * `src/assets/ai-rogue/audio/music/provenance.json` covers every committed primary music and theme ambience file. * `bash scripts/check-asset-sizes.sh` passes with all music and ambience files under the reviewed 900 KB per-track cap. When adding AI Rogue SFX: 1. Keep raw ElevenLabs API responses under `tmp/elevenlabs/`. 2. Use `ELEVENLABS_API_KEY` from `.env.local` in local scripts only. 3. Encode final assets as 48 kHz mono Ogg Opus and normalize loudness. 4. Save prompt, request, render, and raw-response metadata in `src/assets/ai-rogue/audio/sfx/provenance.json`. 5. Rerun `bash scripts/check-asset-sizes.sh`. Current AI Rogue Phase 36 SFX inventory, validated on 2026-06-28: * 64 Ogg Opus SFX files are committed under `src/assets/ai-rogue/audio/sfx/`, including seven adaptive stingers. * Dedicated adaptive stingers use the SFX workflow and cap because they are short one-shot cues, not looping music tracks. * `src/assets/ai-rogue/audio/sfx/provenance.json` covers every committed SFX and adaptive stinger file. * `bash scripts/check-asset-sizes.sh` passes with all SFX and stinger files under the default 200 KB non-logo asset cap. ## Accessibility * All meaningful images must have descriptive `alt` text * Decorative images should use `alt=""` and `aria-hidden="true"` * Avoid text embedded in images; use HTML/CSS text overlays instead * Ensure sufficient contrast between image content and overlay text ## Asset Organization ``` src/assets/ ai-rogue/ audio/ music/ -- AI Rogue Ogg Opus music loops, stings, and theme ambience loops sfx/ -- AI Rogue Ogg Opus sound effects dream/ -- Dream carousel imagery skills/ -- Skills page hero and card imagery logos/ -- Tool and service logos (SVG preferred) *.webp -- Top-level assets (setup hero, etc.) public/assets/ ai-os/ -- Public social/share assets trend-finder/ -- Trend Finder route background and hero imagery ``` ## CDN Strategy (Deferred) Large or frequently-updated assets may move to an external CDN or Cloudflare R2 bucket in a future phase. Until then, all assets are committed to the repository and served through Vite's asset pipeline. When CDN infrastructure is available: * Assets over 100 KB should be candidates for CDN hosting * Use content-addressed URLs for cache busting * Keep a local fallback for development without network access ## Enforcement The `scripts/check-asset-sizes.sh` script verifies non-logo asset compliance: ```bash bash scripts/check-asset-sizes.sh ``` It exits 0 if all non-logo `src/assets/` assets are within configured limits, or 1 with a list of violations. Logo size, public assets, and total directory size remain manual review items. --- # 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/docs/media-policy.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.