Document asset library organization

docs/superpowers/specs/2026-04-26-asset-library-design.md

@@ -0,0 +1,114 @@
+# Asset Library Design
+
+## Purpose
+
+The watch run currently saves media under `assets/discovered/` using a source-mirrored path such as `komodostation.com/wp-content/uploads/YYYY/MM/...`. That preserves provenance but makes Finder browsing awkward.
+
+Add a generated browse-first asset library that groups downloaded assets by media type while keeping the raw source mirror intact.
+
+## Goals
+
+- Make it easy to browse all videos, all images, all poster frames, and all logos in one place.
+- Keep hardware identity visible in filenames.
+- Preserve source provenance through manifests.
+- Avoid duplicating or moving the raw `assets/discovered/` archive.
+- Avoid flooding primary folders with generated WordPress size variants.
+
+## Proposed Layout
+
+```text
+assets/
+  discovered/
+  library/
+    videos/
+    images/
+    logos/
+    poster-frames/
+    thumbnails/
+    variants/
+    unknown/
+  manifests/
+    asset-library.json
+    asset-library.tsv
+```
+
+## Classification
+
+Classify each retrieved asset from WordPress metadata and source context:
+
+- `videos`: MP4, WEBM, MOV, or M4V source assets.
+- `images`: full-size or primary still images that are not logos, poster frames, thumbnails, specs, or variants.
+- `logos`: SVGs or image files with logo/title branding signals.
+- `poster-frames`: video stills, especially `videoframe_*` assets tied to video sections.
+- `thumbnails`: small generated sizes such as `100x100`, `150x150`, or WordPress thumbnail roles.
+- `variants`: generated resized derivatives such as `768x432`, `1024x576`, `2048x988`, or any size-suffixed derivative that is not a thumbnail.
+- `unknown`: assets that cannot be classified confidently.
+
+Hardware should be inferred from section/product context first, then filename/title hints, then `unknown`.
+
+## Filenames
+
+Library filenames should be readable and stable:
+
+```text
+steam-controller_433313_3-in-1_1920x850.mp4
+steam-controller_433293_banner_1920x1080.webm
+steam-controller_433477_spec-image_2048x988.avif
+steam-controller_413728_controller-logo.svg
+```
+
+Use lowercase kebab-case labels. Include:
+
+- hardware slug
+- WordPress media ID when available
+- short role/title label
+- dimensions when available
+- original extension
+
+If a name collides, append a short hash or sequence suffix.
+
+## Manifests
+
+Generate both JSON and TSV manifests under `assets/manifests/`.
+
+Each manifest row should include:
+
+- original URL
+- raw source-mirrored path
+- library path
+- hardware slug
+- library category
+- WordPress media ID
+- WordPress parent post or section ID
+- title or slug
+- MIME type
+- detected format
+- width and height when available
+- file size when available
+- source JSON file path
+
+The manifest is the canonical provenance record. The library folders are for browsing.
+
+## Existing Reports
+
+Keep the current reports:
+
+- `discovered-visual-assets.tsv`
+- `retrieved-visual-assets.tsv`
+- `blocked-visual-assets.tsv`
+- `downloaded-visual-assets.tsv`
+- `manual-asset-urls.txt`
+
+Add library reports only if useful, but do not replace the existing reports in the first implementation.
+
+## Testing
+
+Add focused tests for:
+
+- media-type-first placement
+- WordPress size suffix detection
+- manifest entries preserving source URL and raw path
+- stable filenames with hardware, media ID, label, and dimensions
+- collision handling
+
+The existing fetchable Komodo AVIF regression test should continue to pass.