Kitolochi · Sep 16, 2026 · Sep 17, 2026 · Sep 17, 2026
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -18,5 +18,9 @@ jobs:
           python-version: "3.13"
       - name: Validate sources, templates and gallery
         run: python skills/motion-design/scripts/build_gallery.py
+      - name: Validate shot studies and retrieval index
+        run: python skills/motion-design/scripts/build_library.py
+      - name: Test catalog behavior and local media delivery
+        run: python -m unittest discover -s skills/motion-design/scripts/tests -v
       - name: Check generated files are current
-        run: git diff --exit-code -- skills/motion-design/assets/gallery.html skills/motion-design/references/preset-index.md
+        run: git diff --exit-code -- skills/motion-design/assets/gallery.html skills/motion-design/references/preset-index.md skills/motion-design/assets/library-index.js skills/motion-design/library/index.md
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md
@@ -14,8 +14,14 @@ Original prompts retain their source wording, including fictional brands and his
 
 ## Added workflow material
 
+The separate shot library begins with an [Infinex reference attributed to yb_visualz](https://x.com/yb_visualz/status/2099185156099874852). Its [study record](skills/motion-design/library/studies/infinex.md) separates observed behavior from an independently authored local AE/Blender reconstruction. The original project and prompt are unavailable. Reference videos, extracted excerpts and native evidence remain outside this repository and connect through optional private asset bindings. Attribution does not grant redistribution rights for those assets.
+
 The skill entrypoint, adaptation guides, preset navigation, gallery tooling, and workflow instructions were assembled to make these examples usable as a shared Codex and Claude Code skill. Adaptations are labeled separately from their originals.
 
+The expanded source library also documents [Cero's launch film](https://x.com/joinCero/status/2087953404190466515), [the Jaw film shared by vedu_boi](https://x.com/vedu_boi/status/2099511079412113752), [JB / Bhumimov's UI reference](https://x.com/Bhumimov/status/2097367794312675749), and [Ordinary Folk's Radial Delay project on Play](https://www.ordinaryfolk.co/play). A sharing account is not treated as verified production credit. Cero, Jaw and Infinex original scene files and software remain unverified. The Bhumimov Blender work is our local reconstruction, not the creator's original project.
+
+Ordinary Folk's downloaded project includes personal educational/noncommercial use terms. Its AEP, source artwork, copied expressions and personal viewing render remain outside the public package. The library describes factual source controls and a separately authored scheduling approach; it does not distribute the original project as a commercial template. All newly linked source clips, extracted frame sheets, posters and local native files remain in private asset roots.
+
 Attribution does not establish a license for third-party material. No repository-wide license has been applied to the combined package.
 
 ## README preview stills

diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 
 <p align="center">
   Turn a product, website or idea into a complete motion film.<br />
-  Choose a look. Adapt the prompt. Generate with Higgsfield.
+  Study a shot. Explore its construction. Build natively or generate with Higgsfield.
 </p>
 
 <p align="center">
@@ -111,7 +111,7 @@ Choose a look, select Codex or Claude Code, add your brief and copy the request
 
 ## Quick start
 
-Install the same skill in either app, then connect your own Higgsfield account for media generation. Browsing and prompt drafting work before you connect.
+Install the same skill in either app. Reference studies and native implementation browsing need no generation connection. Connect your own Higgsfield account when you want generated media.
 
 ### Codex
 
@@ -190,6 +190,8 @@ You can also ask for reference images alone. Requesting images does not commissi
 
 ## How it works
 
+Choose the route from the task: explore references, build in After Effects/Blender, or generate a film. The [shot library workflow](skills/motion-design/references/library-workflow.md) covers inspiration and native work; the sequence below applies to Higgsfield film generation.
+
 **Choose → Adapt → Generate → Review**
 
 The skill starts from the closest example's **complete original prompt** and the takeaway your viewer should leave with. It retains the source's effective visual and motion techniques while adapting scenes, sequence, timing and transitions to your subject. The resolved timed sequence is submitted as **one complete film** through Higgsfield MCP.
@@ -208,7 +210,27 @@ New campaigns generally target **15 seconds · 16:9 · music + effects**, withou
 
 ## Under the hood
 
-The package includes ten source examples, archived prompts with verified hashes, separate adaptation guides, a playable gallery and production review guidance. Both apps use the same skill folder.
+The package includes ten film presets, archived prompts with verified hashes, adaptation guides, and a separate shot and technique library. Both apps use the same complete skill folder.
+
+### Shot studies and technical breakdowns
+
+The library has **five complete source timelines and 44 entries**: Infinex, Cero, Jaw/vedu_boi, Ordinary Folk's Radial Delay, and the Bhumimov UI/Blender camera study. Browse by source, video type, story purpose, technique or implementation tool. Each shot has inspiration and technical views covering event timing, component counts, hierarchy, camera, typography, lighting, focus, transitions, construction controls and failures. Exact original or local controls are included where available; proposed recreations are labeled. Section links make deeper pages navigable.
+
+```sh
+python skills/motion-design/scripts/serve_library.py
+```
+
+Open [Shots & techniques](http://127.0.0.1:8766/assets/library.html). Text and timing diagrams work immediately. Source clips and native files stay in a separate workspace; connect them with the [local asset setup](docs/setup.md#5-browse-shots-and-technical-breakdowns). The original ten-preset gallery is available from the same navigation.
+
+For an assistant, start with the [compact index](skills/motion-design/library/index.md), then load only the selected record. For example:
+
+```text
+Find the Infinex phone-to-cards passage for a product launch.
+Explain the staging and timing, then show the Blender/After Effects
+construction and unresolved review notes.
+```
+
+Every interval of the five supplied references is covered, including montage inserts and end holds. Analysis is based on recorded source/frame inspection; it does not recover unknown original projects or establish continuous motion/audio quality. The Infinex V05 blur reconstruction remains rejected; V06 is pending. Register each new study immediately with `scripts/intake_study.py`, then update the same record during analysis, native construction and review. Blender and AE work need no generation connection or Seedance credits.
 
 <details>
 <summary><strong>Project status & validation</strong></summary>
@@ -226,9 +248,11 @@ Edit `skills/motion-design/`, then rebuild:
 
 ```sh
 python skills/motion-design/scripts/build_gallery.py
+python skills/motion-design/scripts/build_library.py
+python -m unittest discover -s skills/motion-design/scripts/tests -v
 ```
 
-Python 3.10+ is needed only for the builder or serving the gallery. The builder checks preset IDs, linked recipes/templates, timeline coverage and archived source hashes, then refreshes the gallery and index. Commit generated changes with source edits; GitHub Actions repeats the check.
+Python 3.10+ is needed only for builders, tests or serving the gallery. The preset builder checks IDs, linked recipes/templates, timeline coverage and archived source hashes. The study builder validates relationships, source-frame intervals, asset IDs, parameter provenance and review consistency. Commit generated changes with source edits; GitHub Actions repeats the checks. See the [data contract](skills/motion-design/library/schema.md) and [library validation](docs/library-validation.md).
 
 Keep original source prompts immutable. Update adaptation guides and workflow instructions for behavior changes. The catalog/template version tracks the source library; README and host-routing edits do not rewrite its provenance. Installed copies are separate from the repo: update the complete skill folder, including references and gallery, and preserve local customizations.
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -10,6 +10,10 @@ The shared workflow is implemented for Codex and Claude Code. This page separate
 - [x] Before/after production review using each preset's existing fidelity requirements, with observed timestamps and pass/fail/not-inspected status. See [quality-review.md](skills/motion-design/references/quality-review.md).
 - [x] Separate correction guidance for motion, identity, exact text/data, audio and export problems, with bounded retries.
 - [x] README source-preview stills and links, setup walkthrough and source attribution.
+- [x] One Infinex study with three complete documented shot breakdowns and two supporting technique/lighting records, inspiration and technical views, inline formulas/control tables, overlapping timelines, native evidence bindings and separate creative review states. See [validation](docs/library-validation.md).
+- [x] Explicit study/native/generation routing, portable retrieval data, local video seeking and catalog/server checks in CI.
+
+The pilot does not complete the broader four-study set. Next: select and audit the remaining references using the same data contract, validate a reusable native construction, and resolve the Infinex blur defect before approving that recipe. No new native render or creative approval was produced by the library integration.
 
 These items mean the instructions and package exist. They do not establish generation quality, production cost or successful end-to-end execution in both clients.
 

diff --git a/docs/library-validation.md b/docs/library-validation.md
@@ -0,0 +1,29 @@
+# Shot library validation
+
+Recorded September 16, 2026. Current scope: five complete source timelines, 44 entries (41 shot records and three supporting technique/lighting records), alongside the existing ten film presets. Infinex has 15 records, Cero 12, Jaw/vedu_boi 12, Ordinary Folk 1, and Bhumimov/Blender 4. Records can overlap and montage records can contain several edits; these numbers are not asserted source cut counts.
+
+## Package and delivery
+
+- Both builders pass. Original ten preset/source-prompt data remains unchanged. Generated library output is deterministic.
+- 25 standard-library tests pass: retrieval, preserved rejection state, full-source coverage without gaps, fractional FPS, intake without invented timing, duplicate-intake protection, overlapping events, technical provenance, portable paths, explicit assets, range delivery, native download names and missing media.
+- Skill frontmatter and JavaScript syntax checks pass.
+- The 44 records contain 278 technical sections, 110 tables and 63 formula/hierarchy blocks. Exact original controls are available for Radial Delay; exact local controls for the existing Infinex and Blender builds are distinct from proposed reconstructions.
+- CI is configured to repeat both builders, tests and generated-file checks. Local success does not claim hosted CI has passed; the upstream draft PR can require maintainer approval before workflows run.
+
+## Viewer and media
+
+An isolated headless Chromium session verified all 44 detail routes and their excerpt metadata, all five source filters, lazy card video loading, search/reset/empty state, section navigation, keyboard tabs, native evidence, retained rejected blur, missing-media browsing and the existing ten-preset request/copy flow. Playback and source-frame seeking were checked on the fractional-rate Jaw excerpt. No page-script errors occurred.
+
+All 44 local previews have the expected decoded frame counts and pass complete ffmpeg decoding. Preview dimensions preserve source aspect ratios: landscape references, 600×600 Radial Delay, and the wide UI source are not forced into one crop. Poster frames are documented inside each excerpt and do not change playback start. 177 explicitly bound local files exist, including dense evidence and source presentation-timestamp tables. These original/native/media payloads are not part of the public package.
+
+Desktop and 390px mobile screenshots were inspected, including the expanded filters and representative Infinex, Cero, Jaw, Ordinary Folk and camera-study technical pages. There is no horizontal page overflow; large tables and code scroll inside their own regions.
+
+## Inspection and creative limits
+
+Full timeline coverage means every supplied interval has an analytical record. It does not mean every boundary is frame-exact, every original technique has been recovered, or every proposed build has been rendered. The records state sampling scope: existing dense Infinex/Cero evidence, full-film 0.5s samples for Cero/Jaw, an additional every-three-frame Jaw typography check, original Radial Delay property inspection, and existing local Blender comparison evidence.
+
+No new AE/Blender production render, uninterrupted real-time aesthetic review, soundtrack audit or user approval was performed by this library expansion. Infinex V05 blur remains rejected and V06 remains pending. Cero/Jaw native builds are proposed. Radial Delay's independent scheduler is numerically tested, not production-approved. The existing Blender camera A/B is technically verified with creative preference pending.
+
+## Standing capture workflow
+
+The skill now registers every requested study/recreation immediately and updates stable records during inspection, construction and review. `intake_study.py` creates an in-progress source with unknown timing and an unbound media ID, refuses duplicates, and does not submit generation jobs. The user's preferred native tool takes precedence over the preset-generation route.
diff --git a/docs/setup.md b/docs/setup.md
@@ -1,6 +1,6 @@
 # Set up Codex or Claude Code
 
-Install the same `skills/motion-design/` folder in either app. It includes the prompt library, adaptation guides and gallery. App-specific image routes live in [tool-routing.md](../skills/motion-design/references/tool-routing.md).
+Install the same complete `skills/motion-design/` folder in either app. It includes film presets, shot studies, technical breakdowns and both galleries. App-specific image routes live in [tool-routing.md](../skills/motion-design/references/tool-routing.md). Higgsfield setup is only needed for generation; skip to section 5 for reference studies and native construction.
 
 ## Updating an earlier installation
 
@@ -100,6 +100,8 @@ Visit [the local gallery](http://127.0.0.1:8765/assets/gallery.html), choose a l
 
 ## Common fixes
 
+See [section 5](#5-browse-shots-and-technical-breakdowns) for the shot library and local media connection.
+
 | Symptom | Check |
 |---|---|
 | The skill is missing | Confirm the full folder and `SKILL.md` are at the correct discovery path; start a new session if necessary. |
@@ -109,3 +111,34 @@ Visit [the local gallery](http://127.0.0.1:8765/assets/gallery.html), choose a l
 | A preview is unavailable | Use its source article link. A failed preview does not remove the archived prompt or prove generation is unavailable. |
 | The gallery shows HTML source on GitHub | Open the downloaded file locally or use the loopback server above. |
 | Exact type or charts are wrong in the film | Inspect the output and use the supported correction/finishing route; a reference image cannot guarantee exact pixels. |
+
+## 5. Browse shots and technical breakdowns
+
+From a repository checkout, run:
+
+```sh
+python skills/motion-design/scripts/serve_library.py
+```
+
+Visit [the shot library](http://127.0.0.1:8766/assets/library.html). Search by story purpose, subject or technique, then switch between **Inspiration** and **Technical breakdown**. Event bars use source-frame timing and seek the corresponding excerpt when connected. Native links download evidence files; opening the gallery does not execute construction scripts or change an AE/Blender project.
+
+The packaged records work without local media. To connect existing source clips and native evidence:
+
+1. Copy `skills/motion-design/library/asset-map.example.json` to the ignored `work/library-assets.local.json` file; create `work/` if needed.
+2. Change `study-workspace` to your local study workspace and, if connecting the full UI reconstruction, `world-cup-workspace` to that project folder. The example's relative paths describe the original workspaces; adjust or remove bindings when your files differ. Use forward slashes in JSON paths.
+3. Start the server with that manifest:
+
+```sh
+python skills/motion-design/scripts/serve_library.py --assets-file work/library-assets.local.json
+```
+
+Only explicit asset IDs are served. Missing files are labeled disconnected, and the breakdown stays readable. Keep private manifests and media outside the shared skill; do not commit machine-specific paths. In an installed skill, run `python scripts/serve_library.py` from the skill folder and pass an absolute path to your private manifest. Stop the server with Ctrl+C.
+
+To retrieve evidence without a browser, run from the skill folder:
+
+```sh
+python scripts/build_library.py search "blur bounds" --tool "After Effects"
+python scripts/build_library.py show DETAIL-INF-DEFOCUS
+```
+
+The [library workflow](../skills/motion-design/references/library-workflow.md) explains native reuse and adding studies. Code validation and creative approval are separate: inspect the entry's review state before reusing a recipe.