dsh-hyperframes 0.2.0 → 0.3.1

package/skills/hyperframes-keyframes/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: hyperframes-keyframes
+description: >
+  Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe,
+  Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe
+  2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths,
+  masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics.
+  Don't use for broad scene strategy, brand design, media sourcing, captions, or
+  general video planning.
+---
+
+# HyperFrames Keyframes
+
+Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.
+
+Use `hyperframes-animation` for broad scene recipes. Use `hyperframes-cli` for full command docs. Use `references/keyframe-patterns.md` only when choosing implementation mechanisms, not visual style.
+
+## Creator editing boundary
+
+Keyframes own visual motion, not clip assembly. Source-range hard cuts, trim,
+splice, and reorder belong to `/hyperframes-core`: author one media element per
+kept range, place it with `data-start` and `data-duration`, and select its source
+offset with `data-media-start`. Adjacent ranges make a hard cut. A crossfade
+uses overlapping clips on different tracks plus visual opacity keyframes; sound
+fades use `/hyperframes-audio`.
+
+| Creator request                         | Truthful mechanism                                                                                                                                                                                                          |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Punch-in / punch-out                    | Keyframe `scale` with `x`/`y` or percentage translation on a non-timed visual/crop wrapper inside the clip. Use a set/short tween for a hard punch and a tween for a smooth move.                                           |
+| Smooth multi-state zoom or reframe      | Keep one subject wrapper alive and author multiple zoom/reframe states as a pose ladder with per-segment easing.                                                                                                            |
+| Pan, reframe, or Ken Burns camera move  | Animate wrapper translation plus scale. Geometry is authored; this is not face tracking or automatic semantic reframing.                                                                                                    |
+| Chained camera moves                    | Chain labeled transform beats on one registered seek-safe timeline.                                                                                                                                                         |
+| Match cut or whip pan                   | `/hyperframes-animation` owns the visual handoff; `/hyperframes-registry` supplies primitives; keyframes preserve authored geometry, direction, and velocity. There is no automatic matching-frame discovery.               |
+| Crop and mask reframe                   | Interpolate `clip-path` or a mask on an inner visual wrapper to crop/reframe without changing source time. Polygon keyframes can form a polygon/mask transition.                                                            |
+| Directional wipe cut or iris/reveal cut | Animate a mask/clip boundary across overlapping visual clips; `/hyperframes-animation` owns the handoff choreography.                                                                                                       |
+| Split-screen handoff                    | Keep both visual clips placed by core, then keyframe their inner crop/mask wrappers and divider geometry.                                                                                                                   |
+| Constant source retime                  | `/hyperframes-core` owns normalized `data-playback-rate` (`0.1..5`) for render-safe picture and pitch-preserved sound. It is constant for the whole media element.                                                          |
+| Source speed ramps                      | Not supported: there is no time-varying playback-rate envelope. Preprocess a derived media asset, then place it through core.                                                                                               |
+| Freeze / hold                           | A visual pose, final source frame, or finished sub-composition can hold. Arbitrary mid-source freeze is not supported; preprocess a still/derived segment, place it as its own clip, then resume with another source range. |
+
+When editing picture and sound together, load `/hyperframes-core`, this skill for
+visual motion, and `/hyperframes-audio` for fades, crossfades, volume automation,
+ducking/carve, or effects on the placed tracks.
+
+A visual transition or cropping treatment is not a temporal source trim or
+splice. `/hyperframes-core` owns the timeline, clip timing, and source ranges;
+keyframes only animate the visible handoff or crop on wrappers inside those clips.
+For copyable combined picture/sound recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.
+
+## Procedure
+
+1. Identify the animated subject, visible states, final state, and runtime.
+2. Choose the smallest mechanism that proves the prompt. Read `references/keyframe-patterns.md` only if the mechanism is unclear.
+3. Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
+4. Verify with `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots at proof times.
+5. If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.
+
+## Contract
+
+- Name the moving subject.
+- Name the poses needed to prove the intended motion, including the final state.
+- Keyframe visible channels, not hidden helper state.
+- Preserve object identity when continuity matters.
+- Crossfade only when the intended motion is replacement or dissolve.
+- Hold readable or semantic states long enough to see.
+- Final frame is part of the animation, not cleanup.
+- Do not reset to rest unless requested.
+- Do not end on black unless requested.
+- If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.
+
+## Runtime Rules
+
+GSAP:
+
+- build synchronously at page load
+- use `gsap.timeline({ paused: true })`
+- register as `window.__timelines[compositionId]`
+- registry key must match `data-composition-id`
+- do not call `tl.play()` for render-critical motion
+- keep repeats finite
+
+CSS keyframes:
+
+- finite duration and iteration count
+- deterministic delay
+- `animation-fill-mode: both`
+- use `data-start` when timing belongs to a clip
+
+Anime.js:
+
+- create synchronously
+- `autoplay: false`
+- finite duration and loops
+- push every instance to `window.__hfAnime`
+
+WAAPI:
+
+- finite `duration`
+- `fill: "both"`
+- deterministic construction
+- the text surface does not list WAAPI; verify with `--shot` (it seeks WAAPI) and snapshots
+
+Never use for render-critical motion:
+
+- `Date.now()`
+- `performance.now()`
+- unseeded `Math.random()`
+- hover/scroll triggers
+- timers
+- async-created timelines
+- unregistered `requestAnimationFrame`
+- infinite loops
+
+## GSAP Skeleton
+
+```js
+const root = document.querySelector("[data-composition-id]");
+const compositionId = root.dataset.compositionId;
+const tl = gsap.timeline({ paused: true });
+
+tl.addLabel("state-a", 0);
+tl.to(".subject", {
+  keyframes: [
+    { x: 0, opacity: 1, duration: 0.2 },
+    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
+    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
+  ],
+  ease: "none",
+});
+
+window.__timelines = window.__timelines || {};
+window.__timelines[compositionId] = tl;
+```
+
+Use labels for semantic states. Use position parameters instead of chained delays. Use `immediateRender: false` for later `from()`/`fromTo()` tweens touching the same property.
+
+## Keyframe Forms
+
+- Array keyframes: pose ladder with per-step duration/ease.
+- Percentage keyframes: exact timing inside one tween.
+- Property arrays: compact multi-stop changes.
+- `ease: "none"` on the parent when each stop carries its own easing.
+- `easeEach` when every segment should share the same feel.
+
+Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.
+
+For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split `x/y/scale` into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.
+
+## Channels
+
+Prefer compositor/visual channels: `x/y/z`, `xPercent/yPercent`, `scale`, `rotationX/Y/Z`, `skew`, `transformOrigin`, `svgOrigin`, `opacity`, `autoAlpha`, `clip-path`, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.
+
+Avoid layout/lifecycle channels: `top/left/right/bottom`, `width/height`, `margin/padding`, `display`, `visibility`, late DOM creation, helper overlays doing subject motion.
+
+For visibility changes, use `autoAlpha` on the registered seekable GSAP timeline, or a zero-duration `tl.set()` at an explicit boundary. Target only a non-clip element or a wrapper inside the clip; never target `.clip` itself. Never duration-tween raw `visibility`, and never tween `display`.
+
+## Mechanism Choice
+
+Choose the smallest mechanism that proves the prompt:
+
+| Need                                  | Mechanism                                          |
+| ------------------------------------- | -------------------------------------------------- |
+| Same subject changes box or hierarchy | shared element / FLIP                              |
+| Subject travels a visible route       | path travel                                        |
+| Stroke grows or traces                | stroke draw                                        |
+| Shape becomes another shape           | shape interpolation                                |
+| Reveal boundary is visible            | clip, mask, or shader uniform                      |
+| Many items move with order            | stagger / indexed delay                            |
+| Text itself moves                     | line, word, character, or band subdivision         |
+| Surface bends, stretches, or crops    | parent/child counter-transform                     |
+| UI has states                         | explicit state machine                             |
+| Scene has depth                       | DOM 3D, Three.js, or WebGL camera/object keyframes |
+
+Mechanisms can combine, but each one must clarify the idea. Decoration is not proof.
+
+## Timing
+
+- Anticipation only when it clarifies cause or direction.
+- Acceleration leaves rest.
+- Peak proof shows the mechanism unmistakably.
+- Follow-through sells energy and direction.
+- Overshoot only when the subject should feel elastic or tactile.
+- Constant-speed path travel usually needs `ease: "none"`.
+- Discrete UI states usually need a sharp ease-out.
+- Repeated elements need ordered offsets, not identical timing.
+- Final lockups need longer holds than transition poses.
+- Smoothness means continuous velocity on the same subject.
+- Do not overlap tweens that write the same transform property unless the overlap is intentional and verified.
+- Avoid animating large `clip-path`/mask changes while the same hero surface is also scaling or traveling; use nested reveals after the main move settles.
+
+## Text
+
+Preserve line boxes, word spacing, readability, and final fit. If text moves internally, move the glyphs or masked bands, not only decorations around the text. Snapshot readable frames.
+
+## SVG
+
+For stroke growth prefer `DrawSVGPlugin`, then `stroke-dasharray`/`stroke-dashoffset`. For shape interpolation prefer `MorphSVGPlugin`; convert primitives to paths when needed and split complex silhouettes into simpler parts.
+
+## 3D
+
+Scale alone is fake depth. Use perspective on a stable parent, `transform-style: preserve-3d`, z travel, rotation, camera/world motion, occlusion, and layer order when objects cross.
+
+Use one or two diagnostic angles that expose the depth relationship. If angled proof shows no depth crossing, improve z/camera/occlusion.
+
+## Canvas / WebGL
+
+Keyframe camera position, camera target, object transform, material opacity, shader uniforms, and postprocess intensity through deterministic state. Render from HyperFrames time. Use `--ghost` because marker boxes cannot see internal canvas motion.
+
+## CLI Proof
+
+```bash
+npx hyperframes lint
+npx hyperframes check
+npx hyperframes keyframes .
+npx hyperframes keyframes . --json
+npx hyperframes keyframes . --runtime all
+npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
+npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
+npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
+npx hyperframes snapshot . --at <times>
+```
+
+Choose `<selector>` for the real animated subject. Choose `<times>` for first frame, proof poses, final-minus-hold, and exact final. Choose `<angle>` only when depth must be proven.
+
+| Tool             | Proves                                                                                              |
+| ---------------- | --------------------------------------------------------------------------------------------------- |
+| `keyframes`      | targets, explicit stops, paths, traces, composed parent/child motion, CSS stops, Anime registration |
+| `--shot`         | ghosts, route shape, time spacing, DOM 3D projection, focused selector proof                        |
+| `--layout strip` | in-place motion, overlaps, contact, subtle scale/opacity, text waves                                |
+| `--ghost`        | canvas, WebGL, shader motion, rendered 3D                                                           |
+| `snapshot --at`  | masks, text readability, full state, final lockup, black/reset tails                                |
+
+If selector proof looks wrong:
+
+1. rerun `--json`
+2. find the actual animated target
+3. shoot that target
+4. snapshot full frames
+5. trust painted pixels over logs
+
+## Diagnostic Reading
+
+`flat` means no explicit middle poses. `keyframes` means explicit stops exist. `motionPath` means a route exists. `trace` means multi-stroke drawing. `composed with` means child motion inherits parent motion.
+
+Even ghost spacing means constant speed. Clustered ghosts mean slow-in or settle. Large gaps mean fast travel.
+
+A helper-selector shot is not proof. An onion shot over a broken full frame is not proof.
+
+## Error Handling
+
+| Failure            | Fix                                                                                |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| endpoint-only      | add middle poses, hold peak proof, rerun `--shot`                                  |
+| identity break     | keep one element alive, use shared source/final boxes, remove substitute crossfade |
+| fake 3D            | add z/camera travel, occlusion, angled proof                                       |
+| wrong final        | add final hold, snapshot final-minus-hold and exact final                          |
+| unseekable runtime | pause autoplay, register instance, remove timers, build synchronously              |
+| unreadable text    | preserve line boxes, reduce displacement, add final hold, snapshot text frames     |
+
+## Done
+
+Run `hyperframes lint`, `hyperframes check`, `hyperframes keyframes`, one focused `--shot`, and snapshots. Confirm first frame, proof poses, final-minus-hold, exact final, subject-owned motion, and no debug overlays.

package/skills/hyperframes-keyframes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HyperFrames Keyframes"
+  short_description: "Author seek-safe video keyframes"
+  default_prompt: "Use $hyperframes-keyframes to author seek-safe 2D/3D keyframes and verify them with the CLI."

package/skills/hyperframes-keyframes/references/keyframe-patterns.md

@@ -0,0 +1,108 @@
+# Keyframe Mechanism Reference
+
+Use this after `SKILL.md` when choosing a concrete implementation mechanism. It is a parts shelf, not a style guide. Start with one primary mechanism; add supporting motion only when it clarifies the idea.
+
+## Runtime Skeletons
+
+GSAP:
+
+```js
+const root = document.querySelector("[data-composition-id]");
+const id = root.dataset.compositionId;
+const tl = gsap.timeline({ paused: true });
+tl.to("<selector>", {
+  keyframes: [
+    /* derive poses from the scene */
+  ],
+  ease: "none",
+});
+window.__timelines = window.__timelines || {};
+window.__timelines[id] = tl;
+```
+
+CSS:
+
+```css
+.<subject > {
+  animation: <name> <duration> <ease> both;
+  animation-iteration-count: 1;
+}
+@keyframes <name> {
+  0% {
+    transform: <pose-a>;
+    opacity: <a>;
+  }
+  100% {
+    transform: <pose-b>;
+    opacity: <b>;
+  }
+}
+```
+
+Anime.js:
+
+```js
+const animation = anime.createTimeline({ autoplay: false });
+animation.add("<selector>", {
+  /* derived channels */
+});
+window.__hfAnime = window.__hfAnime || [];
+window.__hfAnime.push(animation);
+```
+
+Three/WebGL:
+
+```js
+const state = { progress: 0 };
+tl.to(state, {
+  progress: 1,
+  duration: <duration>,
+  onUpdate: () => {
+    // derive camera/object/material values from state.progress
+    renderer.render(scene, camera);
+  },
+});
+```
+
+## Mechanisms
+
+| Mechanism           | Solves                                         | Keyframe                                                           | Runtime                                    | Verify                                         |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------- |
+| Path travel         | Subject must visibly follow a route            | path progress, tangent rotation, follower offset, trail opacity    | GSAP MotionPath or sampled x/y/z           | strip shot at bends; final snapshot            |
+| Stroke draw         | A line, ring, or outline appears over time     | dash/draw range, stroke opacity, endpoint state                    | DrawSVG or SVG dash fallback               | partial mid snapshot; complete final           |
+| Shape interpolation | One silhouette becomes another                 | source path, middle path, target path, fill/stroke                 | MorphSVG or path tween                     | first/mid/final snapshots                      |
+| Shared element      | Same subject changes box or hierarchy          | source box, target box, x/y, scale, radius, context opacity        | GSAP Flip or manual FLIP                   | one identity moves; no substitute crossfade    |
+| Clip/mask reveal    | Animated boundary exposes content              | clip path, mask position/size, edge softness, inner counter-motion | CSS, SVG, GSAP, or shader                  | snapshot edge frames and final unclipped state |
+| Ordered repetition  | Many items enter, leave, or transform in order | indexed delay, x/y, scale, opacity, final alignment                | GSAP stagger, Anime stagger, CSS vars      | check first/middle/last item timing            |
+| Text subdivision    | Text motion needs readable internal timing     | line/word/char/band wrappers, y/x, opacity, final fit              | SplitText, authored spans, Anime splitText | strip shot plus final readability snapshot     |
+| Surface transform   | Image/card stretches, crops, or changes shape  | parent scale/skew/clip, child counter-scale, transform origin      | GSAP/CSS keyframes                         | no accidental warped final                     |
+| UI state machine    | Interface passes through semantic states       | closed, active, loading, success/error, final                      | GSAP/CSS/Anime                             | snapshots hit states in order                  |
+| DOM depth           | HTML elements need 3D separation               | perspective, z, rotationX/Y, opacity, crossing layer order         | CSS 3D + GSAP/CSS/Anime                    | angled `--shot`; overlap snapshot              |
+| Camera/object 3D    | Canvas/WebGL scene moves in depth              | camera, target, object transform, material opacity                 | Three.js/WebGL + GSAP proxy                | `--ghost`; snapshots at proof poses            |
+| Shader uniform      | Pixel effect is driven by scalar progress      | progress, edge width, noise, color mix, opacity                    | ShaderMaterial/WebGL uniforms              | `--ghost`; snapshot 0/edge/mid/final           |
+| Instanced system    | Many 3D objects move as one system             | instance transforms, scale, color/opacity, camera                  | Three InstancedMesh                        | snapshots, because DOM boxes miss internals    |
+| Imported model      | Model animation must scrub deterministically   | `AnimationMixer.setTime`, camera, material, lights                 | Three AnimationMixer                       | drive from HyperFrames time; `--ghost`         |
+
+## Source Links
+
+- GSAP keyframes: https://gsap.com/resources/keyframes/
+- GSAP timeline: https://gsap.com/docs/v3/GSAP/Timeline/
+- GSAP MotionPathPlugin: https://gsap.com/docs/v3/Plugins/MotionPathPlugin/
+- GSAP Flip: https://gsap.com/docs/v3/Plugins/Flip/
+- GSAP DrawSVGPlugin: https://gsap.com/docs/v3/Plugins/DrawSVGPlugin/
+- GSAP MorphSVGPlugin: https://gsap.com/docs/v3/Plugins/MorphSVGPlugin/
+- GSAP SplitText: https://gsap.com/docs/v3/Plugins/SplitText/
+- GSAP CSSPlugin: https://gsap.com/docs/v3/GSAP/CorePlugins/CSS/
+- Anime.js documentation: https://animejs.com/documentation/
+- Anime.js stagger grid: https://animejs.com/documentation/utilities/stagger/stagger-parameters/stagger-grid/
+- Anime.js timeline: https://animejs.com/documentation/timeline/
+- Anime.js SVG helpers: https://animejs.com/documentation/svg/createmotionpath/
+- MDN CSS animations: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations
+- MDN `@keyframes`: https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes
+- MDN `clip-path`: https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path
+- MDN CSS masking: https://developer.mozilla.org/en-US/docs/Web/CSS/mask
+- MDN perspective: https://developer.mozilla.org/en-US/docs/Web/CSS/perspective
+- MDN transform-style: https://developer.mozilla.org/en-US/docs/Web/CSS/transform-style
+- Three.js AnimationMixer: https://threejs.org/docs/#api/en/animation/AnimationMixer
+- Three.js ShaderMaterial: https://threejs.org/docs/#api/en/materials/ShaderMaterial
+- Three.js InstancedMesh: https://threejs.org/docs/#api/en/objects/InstancedMesh

package/skills/hyperframes-registry/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: hyperframes-registry
-description: "Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery. 中文：安装/接线 HyperFrames 注册表组件（hyperframes add）时使用。"
-compatibility: Requires Node.js >= 22; the `hyperframes add` command needs network access to the registry.
-allowed-tools: Bash
+description: Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).
 ---
 
 # HyperFrames Registry
@@ -12,18 +10,12 @@ The registry provides reusable blocks and components installable via `hyperframe
 - **Blocks** — standalone sub-compositions (own dimensions, duration, timeline). Included via `data-composition-src` in a host composition.
 - **Components** — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.
 
-## When to use this skill
-
-- User mentions `hyperframes add`, "block", "component", or `hyperframes.json`
-- Output from `hyperframes add` appears in the session (file paths, clipboard snippet)
-- You need to wire an installed item into an existing composition
-- You want to discover what's available in the registry
-
 ## Quick reference
 
 ```bash
 hyperframes add data-chart              # install a block
 hyperframes add grain-overlay           # install a component
+hyperframes add captions                # install every block tagged captions
 hyperframes add shimmer-sweep --dir .   # target a specific project
 hyperframes add data-chart --json       # machine-readable output
 hyperframes add data-chart --no-clipboard  # skip clipboard (CI/headless)
@@ -31,12 +23,11 @@ hyperframes add data-chart --no-clipboard  # skip clipboard (CI/headless)
 
 After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add `data-composition-id` (must match the block's internal composition ID), `data-start`, and `data-track-index` attributes when wiring blocks.
 
-Note: `hyperframes add` only works for blocks and components. For examples, use `hyperframes init <dir> --example <name>` instead.
+The positional value is resolved as an exact item name first. If no item matches and the value is a tag, the command installs every block with that tag. Registry dependencies are installed before the requested item. `hyperframes add` works only for blocks and components; for examples, use `hyperframes init <dir> --example <name>` instead.
 
 ## Install locations
 
-Blocks install to `compositions/<name>.html` by default.
-Components install to `compositions/components/<name>.html` by default.
+Blocks install to `compositions/<name>.html` by default. Components install to `compositions/components/<name>.html` by default.
 
 These paths are configurable in `hyperframes.json`:
 
@@ -94,13 +85,61 @@ See [wiring-components.md](./references/wiring-components.md) for full details.
 
 ## Discovery
 
-Browse available items:
+Use the CLI as the primary discovery surface. **Search by intent before browsing:** the registry holds more items than you can scan by eye, so listing them and matching on names or tags is the slow path, and it fails whenever the author's wording differs from yours.
+
+```bash
+# Rank the whole catalog against what the beat should do
+npx hyperframes catalog --query "reveal a headline one line at a time"
+npx hyperframes add caption-clip-wipe
+```
+
+Search is local and sends nothing. By default it ranks on vocabulary shared with the item's name, title and description, so it only finds items that reuse your words; `--on-device` ranks by meaning instead, after a one-time model download. With `--json` the envelope names which tier answered, so check that rather than assuming a ranking happened.
+
+**Always query in English, whatever language the video is in.** The catalog is written in English and both tiers index it that way (the on-device model is English-only too). A query in another script produces no searchable terms and returns nothing at all. This is easy to get wrong on a Japanese or Chinese project, where the brief, the captions and the narration are all in that language and the query naturally follows: describe the _move_ in English, then write the on-screen copy in whatever language the video needs. If a query does come back with `No searchable words in query`, that is this rule, not a missing component, and it is not worth a gap report.
+
+Installability is applied after ranking, not before it: a name the vectors carry but this registry cannot serve is dropped from the results and counted in `dropped`, so a non-zero `dropped` means the two are different generations. See `/hyperframes-cli` for the offline tier, the consent gates, and how to refresh a stale index.
+
+To browse or filter instead of search:
+
+```bash
+npx hyperframes catalog
+npx hyperframes catalog --type block
+npx hyperframes catalog --type component
+npx hyperframes catalog --type block --tag social
+npx hyperframes catalog --json
+npx hyperframes catalog --human-friendly
+```
+
+The normal table and `--json` modes only list matches; install a selected name with `hyperframes add <name>`. `--human-friendly` opens an interactive picker and installs the selected item immediately. In CI or agent workflows, prefer `--json` followed by an explicit `add`.
+
+### Report what the catalog does not have
+
+When the search comes back and nothing in it does the job, say so before you hand-author the move:
+
+```bash
+npx hyperframes feedback --search-miss "<the query you ran>" --wanted "<the move you needed>" --tier on-device
+```
+
+`catalog --query` prints this line for you, pre-filled, and `--json` carries it as `report_gap` — so it is already in hand at the moment you decide nothing fits.
+
+**Report whenever nothing in the results does the job, on either tier.** Do not wait for the on-device tier to have answered: it needs a consented 33 MB download, so an agent run is on `words` unless it explicitly opted in, and gating on `on-device` would silence almost every report. The `--tier` value rides along so a vocabulary miss stays distinguishable from a meaning miss when these are read. Describe the effect you wanted, not the item name you imagined: what comes back is a list of moves worth building, and a report naming a non-existent item teaches nothing. This is the only path that sends a query anywhere, which is exactly why it is a separate deliberate command rather than something the search does on its own. It carries no rating and never lands in the rating metric.
+
+This is the whole demand signal for the catalog. Skipping it means the gap you hit gets guessed at from install counts instead, which cannot see a move nobody could install.
+
+If the CLI cannot reach the configured registry, inspect the raw manifest as a fallback:
 
 ```bash
-# Read the registry manifest
 curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
 ```
 
+A registry the CLI cannot reach does **not** empty the catalog for **discovery**: a previously fetched manifest keeps serving past its 24h refresh window whenever revalidation fails, so `catalog` and `catalog --query` still list and rank against the last copy on disk.
+
+**`add` still needs the network, even for an item you installed yesterday.** Only manifests are cached; the item's actual files are fetched on every install. So offline you can search, and you can see what an item is, but installing it fails at the file fetch. Do not promise a user an offline install.
+
 Each item's `registry-item.json` contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.
 
-See [discovery.md](./references/discovery.md) for details on filtering by type and tags.
+See [discovery.md](./references/discovery.md) for details on filtering by type and tags.
+
+## Contributing a new block or component
+
+To author a NEW registry item (caption style, VFX block, transition, lower third, or a reusable component) and ship it as an upstream PR — not install an existing one — follow the full idea → scaffold → build → validate → preview → ship workflow in [contributing.md](./references/contributing.md). Copy-paste starter templates (caption / VFX / component / `registry-item.json`) are in [templates.md](./references/templates.md).