diff --git a/docs/prompting/capstone.mdx b/docs/prompting/capstone.mdx index b2e73f907..b58c39445 100644 --- a/docs/prompting/capstone.mdx +++ b/docs/prompting/capstone.mdx @@ -6,6 +6,8 @@ description: "One prompt, one continuous camera move, every technique in this gu *"The Timeline" — 1920x1080, ~62 seconds, one prompt, one unbroken camera move, unedited.* +The prompt targeted roughly 60 seconds; the delivered render runs 1:02 because the final lockup holds for a two-second breath. + If you read the guide in order, you have already seen every piece of this film. Each region was cut out and embedded in the chapter that teaches its technique — the typed opening in [Code animations](/prompting/code-blocks), the chart and map in [Data and maps](/prompting/data-and-maps), the footage pipeline in [Media and audio](/prompting/media-and-audio), the glass and mural in [VFX](/prompting/vfx-and-liquid-glass) and [Generated artwork](/prompting/generated-artwork), the beat grid in [Music](/prompting/music-and-slideshows), the 3D coil in [Runtimes and 3D](/prompting/runtimes-and-3d), the continuous camera in [Motion](/prompting/motion), the seeded finale in [Rendering and output](/prompting/rendering-and-output). This page is where the pieces become one composition, and the prompt below is the glue: every paragraph of it is a chapter of this guide restated as a binding clause. The concept is the product: the viewer travels along one literal timeline — the thing HyperFrames is built on — from the first typed character to the finished MP4. Everything in it is true: real catalog counts, real cloud regions, real product surfaces, footage staged as the material the tool processes. And the film has no scenes in the slideshow sense — it is one continuous camera journey through one wide world, which is the chapter's biggest lesson. diff --git a/docs/prompting/motion.mdx b/docs/prompting/motion.mdx index 168c6a416..315e2ffa3 100644 --- a/docs/prompting/motion.mdx +++ b/docs/prompting/motion.mdx @@ -1,6 +1,6 @@ --- title: Motion that reads premium -description: "Seven motion-grammar rules from frame-by-frame study of professional work — nothing stops, the camera acts, action overlaps, imperfection stays reproducible." +description: "Eight motion-grammar rules from frame-by-frame study of professional work — nothing stops, the camera acts, action overlaps, imperfection stays reproducible." --- By now you can specify a frame precisely — exact copy, exact colors, exact layout, exact timing. This level makes it move. But "make it move" is the wrong instruction, and it is worth understanding why before you write a single motion clause. diff --git a/docs/prompting/storyboards.mdx b/docs/prompting/storyboards.mdx index c46589afa..a36e60ad1 100644 --- a/docs/prompting/storyboards.mdx +++ b/docs/prompting/storyboards.mdx @@ -5,6 +5,8 @@ description: "For multi-scene work, don't prompt the scenes one by one — promp [Variables and templating](/prompting/variables-and-templating) was about reusing one composition across many renders. This page is the other axis of scale: one film with many scenes. Past a handful of beats, describing each scene from a blank page — "then frame 2 shows X, then frame 3 shows Y" — is the slow way and the way that drifts, because nothing ties the frames to each other. The fast way is to prompt the **plan** once — the throughline, the job each frame does, the rule that paces reveals — and let the build put frames against it. +This narrative vocabulary is a writing discipline, not additional `STORYBOARD.md` schema: the workflow translates the plan into the smaller machine-readable shape the build consumes. + ## Prompt the plan, not the scenes A storyboard is a short, structured document that sits above the individual frames: one arc, one direction block that every frame inherits, and a light per-frame spec (not a full description) for each key moment. The workflow reads the plan and builds each frame's HTML sub-composition against it — so a plan that's precise about the *shape* of the film produces frames that already agree with each other on pacing, palette, and payoff, without you re-stating any of that per frame. diff --git a/plans/prompt-guide-arc-plan.md b/plans/prompt-guide-arc-plan.md deleted file mode 100644 index 7e038c0e7..000000000 --- a/plans/prompt-guide-arc-plan.md +++ /dev/null @@ -1,508 +0,0 @@ -# Prompt Guide Arc Restructure — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Restructure the 29-page Prompt Guide from a reference manual into a novice→advanced arc (spec: `plans/prompt-guide-arc.md`) where each level builds on the prior one and ends in a validated capstone film. - -**Architecture:** Pages keep their slugs (`docs/prompting/*.mdx`) — only `docs.json` grouping, page content framing, and two new pages (`storyboards`, `capstone`) change. Content rewrites are per-level editorial passes with a fixed bridge template. New prompts follow the standing validation protocol (built as written → lint/check → render → embed). - -**Tech Stack:** Mintlify docs (`docs/`), oxfmt/oxlint, HyperFrames CLI validation builds, S3 render hosting via `scripts/upload-docs-images.sh`. - -## Global Constraints - -- All work in worktree `~/src/wt/hyperframes/prompt-guide` on branch `fix/prompt-guide-validation-bugs` (PR #2109). Commit with `/usr/bin/git` (the `rtk` proxy silently no-ops commits). Conventional commits; header ≤ 100 chars. -- **No prompt ships unverified.** Every NEW prompt printed in the guide must pass the Validation Protocol below before its page is committed. Existing prompts keep their existing 64 embedded renders; do not rewrite a validated prompt's text (rewriting voids its render). -- **Bridge template** — every chapter page gets both: - - Entry bridge: first paragraph after the frontmatter opens with what the reader can already do, then what this chapter adds. Pattern: `You can already . This chapter adds .` (Adapt the wording per page; keep the two-beat shape.) - - Exit bridge: final line of the page, italic: `*Next: [](/prompting/) — .*` The last chapter of a level points at the first chapter of the next level. -- Keep page counts out of prose (drift rule). Never say "29 pages" / "30 pages" in any `.mdx`. -- Embed snippet for renders (copy exactly, swap filename): - ```mdx - - ``` -- `docs/images/` is gitignored by design — renders go to S3 via `bash scripts/upload-docs-images.sh` (AWS profile `engineering-767398024897`), then verify each URL: `curl -sI | head -1` → `HTTP/2 200`. -- After editing any file: `bunx oxfmt ` then `bunx oxlint `. Markdown/MDX gets oxfmt only. -- Docs sanity gate (run before every commit that touches `docs/`): - ```bash - cd ~/src/wt/hyperframes/prompt-guide - python3 -c "import json; json.load(open('docs/docs.json')); print('docs.json ok')" - cd docs && npx mintlify broken-links - ``` -- Do not modify `.gitignore`. Do not close or open PRs. Push only in the final task. - -## Validation Protocol (for every NEW prompt) - -Used by Tasks 3, 7, 8, 9, 10. The executor dispatches a fresh builder subagent per prompt: - -1. `mkdir -p ~/src/hyperframes-prompt-examples/guide-v3/` -2. Dispatch a `general-purpose` subagent with EXACTLY this framing: "You are a HyperFrames builder. Your entire brief is the prompt below, verbatim — do not use any knowledge of why this prompt exists. Work in `~/src/hyperframes-prompt-examples/guide-v3/`. Follow the `/hyperframes` skill routing. The project must pass `npx hyperframes lint` and `npx hyperframes check`, then render an MP4. Report the render path and any prompt ambiguity you had to resolve yourself." + the prompt text. -3. If the builder reports ambiguity or a gate failure caused by the prompt text: fix the page's prompt, re-run with a fresh subagent. The page ships the text that passed. -4. Copy the render: `cp .mp4 ~/src/wt/hyperframes/prompt-guide/docs/images/prompting/.mp4` -5. Upload + verify (see Global Constraints), embed under the prompt with the standard snippet and a one-line italic caption stating it is the unedited render of the prompt above. - ---- - -### Task 1: Fix the red Format CI check - -**Files:** - -- Modify: `plans/prompt-guide-expansion.md` (formatting only) - -- [ ] **Step 1: Reproduce** - -```bash -cd ~/src/wt/hyperframes/prompt-guide && bun run format:check -``` - -Expected: FAIL listing `plans/prompt-guide-expansion.md`. - -- [ ] **Step 2: Fix** - -```bash -bunx oxfmt plans/prompt-guide-expansion.md -``` - -- [ ] **Step 3: Verify** - -```bash -bun run format:check -``` - -Expected: exit 0. - -- [ ] **Step 4: Commit** - -```bash -/usr/bin/git add plans/prompt-guide-expansion.md -/usr/bin/git commit -m "chore: format prompt-guide-expansion plan (fixes Format CI)" -``` - ---- - -### Task 2: Restructure docs.json nav into levels - -**Files:** - -- Modify: `docs/docs.json` (the `Prompt Guide` group only) - -**Interfaces:** - -- Produces: the level grouping every later task's pages live in. Slugs unchanged; no new redirects needed (the existing `/guides/prompting` → `/prompting/overview` redirect stays untouched). - -- [ ] **Step 1: Replace the Prompt Guide group's subgroups** - -In `docs/docs.json`, find the group `"Prompt Guide"` and replace its `pages` array with: - -```json -[ - "prompting/overview", - { - "group": "Level 1 — Your first video", - "pages": [ - "prompting/product-launch", - "prompting/explainers", - "prompting/code-and-prs", - "prompting/captions-and-talking-heads", - "prompting/music-and-slideshows", - "prompting/motion-graphics" - ] - }, - { - "group": "Level 2 — Control", - "pages": [ - "prompting/anatomy", - "prompting/specification-dial", - "prompting/vocabulary", - "prompting/visual-specs", - "prompting/examples" - ] - }, - { - "group": "Level 3 — Life", - "pages": ["prompting/motion", "prompting/transitions"] - }, - { - "group": "Level 4 — Substance", - "pages": [ - "prompting/code-blocks", - "prompting/data-and-maps", - "prompting/overlays-and-lower-thirds", - "prompting/captions-catalog", - "prompting/generated-artwork", - "prompting/vfx-and-liquid-glass", - "prompting/runtimes-and-3d" - ] - }, - { - "group": "Level 5 — Voice and sound", - "pages": ["prompting/media-and-audio"] - }, - { - "group": "Level 6 — Scale", - "pages": [ - "prompting/design-systems", - "prompting/variables-and-templating", - "prompting/editing-existing-videos", - "prompting/iterating", - "prompting/recreating-references", - "prompting/rendering-and-output", - "prompting/remotion-migration" - ] - }, - { - "group": "Appendix", - "pages": ["prompting/rules-and-anti-patterns"] - } -] -``` - -Notes: `prompting/storyboards` is added to Level 6 (before `editing-existing-videos`) in Task 9 when the file exists; `prompting/capstone` is added as a `"Level 7 — Capstone"` group between Level 6 and Appendix in Task 11. Mintlify fails on nav entries whose files don't exist yet — that's why they're deferred. - -- [ ] **Step 2: Verify** - -Run the docs sanity gate (Global Constraints). Expected: `docs.json ok`, no broken links. - -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/docs.json -/usr/bin/git commit -m "docs(prompting): regroup Prompt Guide nav into novice-to-advanced levels" -``` - ---- - -### Task 3: Level 1 — workflow-ride rewrites (6 pages) - -**Files:** - -- Modify: `docs/prompting/product-launch.mdx`, `docs/prompting/explainers.mdx`, `docs/prompting/code-and-prs.mdx`, `docs/prompting/captions-and-talking-heads.mdx`, `docs/prompting/music-and-slideshows.mdx`, `docs/prompting/motion-graphics.mdx` - -**Interfaces:** - -- Consumes: nav order from Task 2 (bridge targets follow that order: product-launch → explainers → code-and-prs → captions-and-talking-heads → music-and-slideshows → motion-graphics → anatomy). -- Produces: L1 framing later levels refer back to ("you rode a workflow; now open the hood"). - -**Editorial contract (each page):** - -1. Reframe the page intro as a _first win_: one prompt to the workflow gets a finished video; the page's first validated prompt + its existing render move to the top. -2. Keep every existing validated prompt and embed verbatim (moving them on the page is fine; editing their text is not). -3. Existing "knobs that matter" material stays but moves after the first-win section, introduced as "what you can steer from the prompt before you've learned any technique." -4. Apply the bridge template. Entry bridge for `product-launch` (the arc's first chapter) instead states the level premise: you need zero technique to get a first video — one sentence describing your product is enough. -5. `motion-graphics` exit bridge points to `anatomy` and names the turn: "you've been riding workflows; Level 2 opens the prompt itself." - -**`code-and-prs` additionally** gains a short "Changelog videos" section: the `changelog-video` skill (landed after the original guide) turns a repo's recent merges into a changelog video. Write one prompt for it and run the Validation Protocol with name `changelog-video` — the builder runs against the public `heygen-com/hyperframes` repo history so the render is publishable. - -- [ ] **Step 1: Rewrite the 6 pages per the contract** -- [ ] **Step 2: Validate the new changelog-video prompt** (Validation Protocol, name `changelog-video`; embed render in `code-and-prs.mdx`) -- [ ] **Step 3: Format + docs sanity gate** - -```bash -bunx oxfmt docs/prompting/product-launch.mdx docs/prompting/explainers.mdx docs/prompting/code-and-prs.mdx docs/prompting/captions-and-talking-heads.mdx docs/prompting/music-and-slideshows.mdx docs/prompting/motion-graphics.mdx -``` - -Then the docs sanity gate. - -- [ ] **Step 4: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): Level 1 — reframe workflow pages as first-win rides + changelog-video" -``` - ---- - -### Task 4: Level 2 — Control rewrites (5 pages) - -**Files:** - -- Modify: `docs/prompting/anatomy.mdx`, `docs/prompting/specification-dial.mdx`, `docs/prompting/vocabulary.mdx`, `docs/prompting/visual-specs.mdx`, `docs/prompting/examples.mdx` - -**Editorial contract:** - -1. `anatomy` entry bridge: "your Level 1 prompts worked because the workflow filled the gaps; the skeleton is how you take that control yourself." Add one short paragraph noting the composition-structure mandate now enforced by the framework (main commit `0aaac7aa3` / PR #2599): compositions follow a required structural shape, so the skeleton isn't style advice — the framework soft-warns when structure drifts. No new prompt needed. -2. `examples` reframed as the level-end gallery: entry bridge frames the 18 dissections as "read these with your new vocabulary — spot the skeleton parts in each." -3. Chapter order for bridges: anatomy → specification-dial → vocabulary → visual-specs → examples → motion. -4. All existing prompts/renders/tables stay verbatim. - -- [ ] **Step 1: Rewrite the 5 pages per the contract** -- [ ] **Step 2: Format + docs sanity gate** (`bunx oxfmt` the five files, then the gate) -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): Level 2 — control chapters with bridges + structure mandate note" -``` - ---- - -### Task 5: Level 3 — Life rewrites (2 pages) - -**Files:** - -- Modify: `docs/prompting/motion.mdx`, `docs/prompting/transitions.mdx` - -**Editorial contract:** - -1. `motion` entry bridge: "you can specify a frame precisely; this level makes it feel alive." Content (grammar, measured A/B, rule 7 seeded motion) already complete — bridges only. -2. `transitions` moves from feature-reference framing to "motion between scenes": entry bridge builds on the grammar ("rule 2's camera and rule 3's overlap apply _between_ scenes too"). Existing prompts/renders stay. -3. Bridge order: motion → transitions → code-blocks. - -- [ ] **Step 1: Rewrite the 2 pages per the contract** -- [ ] **Step 2: Format + docs sanity gate** -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): Level 3 — life chapters with bridges" -``` - ---- - -### Task 6: Level 4 — Substance rewrites (7 pages) - -**Files:** - -- Modify: `docs/prompting/code-blocks.mdx`, `docs/prompting/data-and-maps.mdx`, `docs/prompting/overlays-and-lower-thirds.mdx`, `docs/prompting/captions-catalog.mdx`, `docs/prompting/generated-artwork.mdx`, `docs/prompting/vfx-and-liquid-glass.mdx`, `docs/prompting/runtimes-and-3d.mdx` - -**Editorial contract:** - -1. Every page reframes from "the X feature" to "add X to what you already have": the entry bridge names a Level 1-3 artifact the capability slots into (e.g. code-blocks → "your PR video from Level 1, now with a diff that types itself"). -2. All existing prompts/renders stay verbatim. -3. Bridge order: code-blocks → data-and-maps → overlays-and-lower-thirds → captions-catalog → generated-artwork → vfx-and-liquid-glass → runtimes-and-3d → media-and-audio. - -- [ ] **Step 1: Rewrite the 7 pages per the contract** -- [ ] **Step 2: Format + docs sanity gate** -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): Level 4 — capability chapters framed as additive" -``` - ---- - -### Task 7: Level 5 — media-and-audio + the proxy subsystem - -**Files:** - -- Modify: `docs/prompting/media-and-audio.mdx` -- Read for grounding: `git log main --oneline` commits `9ca1e1710`, `9d148d288`, `645880706`, `39b588cbd`, `74b4f1e8c`, `35eff5038`, `e8371a7ac`, `664c39db9`, and `docs/` pages touched by `5f2819b1e`, `8c1b6c515` (the existing proxy docs — link to them rather than duplicating mechanics). - -**Editorial contract:** - -1. Entry bridge: "your video moves and reads right; this level gives it a voice" — narration/TTS/BGM material stays. -2. New section "Bring any footage" covering the proxy subsystem _from the prompter's perspective_: you can now hand the workflow HEVC/HDR/odd-codec footage and preview/play/publish keep working — the framework probes codecs and builds bounded H.264 (and alpha-capable) proxies automatically; renders still use the original; `hyperframes lint` flags hostile codecs at info level; projects can opt out. Link to the concepts/media docs added by `8c1b6c515` for mechanics. -3. One new validated prompt exercising it: a prompt that builds a short picture-in-picture piece from a provided HEVC clip. Validation Protocol name `proxy-footage`; the builder gets a real HEVC test clip (generate one first: `ffmpeg -f lavfi -i testsrc2=size=1280x720:rate=30 -t 6 -c:v libx265 -tag:v hvc1 ~/src/hyperframes-prompt-examples/guide-v3/proxy-footage/source-hevc.mp4`) and the prompt references `source-hevc.mp4` by relative path. - -- [ ] **Step 1: Ground against the proxy commits, then rewrite the page** -- [ ] **Step 2: Validate the proxy-footage prompt** (Validation Protocol; embed render) -- [ ] **Step 3: Format + docs sanity gate** -- [ ] **Step 4: Commit** - -```bash -/usr/bin/git add docs/prompting/media-and-audio.mdx -/usr/bin/git commit -m "docs(prompting): Level 5 — voice, sound, and automatic media proxies" -``` - ---- - -### Task 8: Level 6 — Scale rewrites (7 pages) - -**Files:** - -- Modify: `docs/prompting/design-systems.mdx`, `docs/prompting/variables-and-templating.mdx`, `docs/prompting/editing-existing-videos.mdx`, `docs/prompting/iterating.mdx`, `docs/prompting/recreating-references.mdx`, `docs/prompting/rendering-and-output.mdx`, `docs/prompting/remotion-migration.mdx` - -**Editorial contract:** - -1. Level premise (design-systems entry bridge): "everything so far was one scene at a time; this level is about videos as systems — design that persists across scenes, edits that don't regress, output that ships." -2. `variables-and-templating`: add a correction note — composition variables no longer shadow authored CSS custom properties (main commit `406894061`); verify the page's existing wording against that commit's behavior and fix any sentence it invalidates. Existing default-vs-overridden render pair stays. -3. `remotion-migration` framed as "bringing an existing Remotion project into everything you now know," last chapter before the capstone level. -4. Bridge order: design-systems → variables-and-templating → storyboards (added in Task 9) → editing-existing-videos → iterating → recreating-references → rendering-and-output → remotion-migration → capstone (added in Task 11; until then point remotion-migration's exit bridge at rules-and-anti-patterns and fix it in Task 11). - -- [ ] **Step 1: Verify the variables claim against `git show 406894061`, then rewrite the 7 pages** -- [ ] **Step 2: Format + docs sanity gate** -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): Level 6 — scale chapters + variables CSS-shadow correction" -``` - ---- - -### Task 9: New chapter — storyboards - -**Files:** - -- Create: `docs/prompting/storyboards.mdx` -- Modify: `docs/docs.json` (insert `prompting/storyboards` into Level 6 before `editing-existing-videos`), `docs/prompting/variables-and-templating.mdx` (exit bridge now points to storyboards) -- Source material: `videos/team-vault-explained/STORYBOARD.md` (in-repo), `~/src/videos/hyperframes-infra-proposals/STORYBOARD.md` — mine structure, not content. - -**Editorial contract:** - -1. Teach prompting _into_ a storyboard: for multi-scene work you don't prompt scenes, you prompt the plan — arc, per-frame beats, VO pacing — and the workflow builds frames against it. -2. Document the storyboard vocabulary the internal films prove, as prompt language: narrative arc line, VO-paced reveals ("at t=0 only what the narrator is saying is on screen; each element lands on its spoken cue"), persuasion/beat per frame, a callback (an early motif returning denser late), exactly one breather frame, a per-frame negative list. Do NOT reproduce internal film content — invent neutral examples. -3. One new validated prompt: a 3-frame mini storyboard piece (hook → substance → landing with callback), ~15s, no narration (keeps the build cheap). Validation Protocol name `storyboard-mini`; embed render. -4. Bridges: entry from variables-and-templating; exit to editing-existing-videos. - -- [ ] **Step 1: Write the chapter per the contract** -- [ ] **Step 2: Validate the storyboard-mini prompt** (Validation Protocol; embed render) -- [ ] **Step 3: Add to nav, fix neighboring bridges, format + docs sanity gate** -- [ ] **Step 4: Commit** - -```bash -/usr/bin/git add docs/prompting/storyboards.mdx docs/prompting/variables-and-templating.mdx docs/prompting/editing-existing-videos.mdx docs/docs.json -/usr/bin/git commit -m "docs(prompting): add storyboards chapter — prompting the plan, not the scenes" -``` - ---- - -### Task 10: Appendix — rules cheat sheet + new lint rules - -**Files:** - -- Modify: `docs/prompting/rules-and-anti-patterns.mdx`; plus one-sentence in-context mentions on `docs/prompting/motion.mdx` (seek-safety) and `docs/prompting/runtimes-and-3d.mdx` (SVG draw-on) where the gotchas bite. - -**Editorial contract:** - -1. Reframe as the consolidated cheat sheet: entry bridge says every rule here was taught in context — this page is the lookup table; each rule row links its teaching chapter. -2. Add the post-guide lint rules, phrased as prompt guidance (what to write / avoid so the build passes first try), each verified against its lint source before writing: - - `gsap_cold_seek_hidden_fromto_missing_reveal` (#2503) — elements hidden at t=0 need an explicit reveal tween. - - `gsap_callback_dom_measurement`, `gsap_function_value_hazard`, `gsap_repeat_refresh_relative_value`, `svg_drawon_css_dasharray_conflict`, `svg_measure_before_path_d` (#2611 / `f3d210066`) — seek-order safety and SVG draw-on. - - `gsap_relative_value_second_writer`, `gsap_timeline_set_initial_hide` (#2612 / `4ad582606`). - Ground each row: `git show -- packages/lint/src/rules/gsap.ts` and read the rule's message string; the guide row must match what the linter actually says. -3. Rows are prompt guidance, not prompts — but any row that prints a runnable example prompt must pass the Validation Protocol (name `lint-`); rows with phrasing-only guidance need no build. - -- [ ] **Step 1: Ground each rule against lint source, write the rows + in-context mentions** -- [ ] **Step 2: Format + docs sanity gate** -- [ ] **Step 3: Commit** - -```bash -/usr/bin/git add docs/prompting/ -/usr/bin/git commit -m "docs(prompting): appendix cheat sheet + post-guide lint rules as prompt guidance" -``` - ---- - -### Task 11: Capstone film — build, validate, render - -**Files:** - -- Create (outside repo): `~/src/hyperframes-prompt-examples/capstone/` (brief, `frame.md`, `STORYBOARD.md`, compositions, audio, renders) -- Create (repo, this task): nothing yet — the chapter is Task 12; this task produces the artifacts. - -**The film (from the spec):** public promo for HyperFrames itself ("write HTML, render video"), ~45-60s, 7 frames, 1920×1080. Required technique checklist and its frame mapping: - -| Frame | Content | Techniques it must carry | -| ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| F1 | Hook — kinetic type on the one-line pitch | L2 skeleton, L3 grammar (staggered overshoot entrances) | -| F2 | "Write HTML" — a composition types itself | L4 code-blocks (per-character typing beat) | -| F3 | "It becomes video" — pipeline diagram; **matched-motion transition into F4** (a diagram line becomes the F4 chart axis) | L3 transitions | -| F4 | Proof — data-viz beat (e.g. render-speed or catalog count-up) | L4 data-and-maps | -| F5 | Generated-artwork hybrid — one illustration-led beat (generated raster on contrasting solid bg, keyed, code-layer animation on top) | L4 generated-artwork | -| F6 | Capability montage — quick cuts, continuous camera push across them | L3 camera-as-actor, L1 callbacks to workflows | -| F7 | Landing lockup — F1 motif returns denser (callback), the film's one breather, CTA `npx skills add heygen-com/hyperframes` | L6 storyboard craft | - -Production constraints: - -- `frame.md`: strict two-color system + negative list, per the internal-promo pattern — but pick a palette that is NOT cream/cobalt (do not read as a reuse of the internal films). -- `STORYBOARD.md` uses the same frontmatter + per-frame field shape as `videos/team-vault-explained/STORYBOARD.md` (format/message/arc/audience/music; per-frame scene/voiceover/duration/transition_in/type/persuasion/beat/blueprint/focal). VO-paced reveals throughout. -- Narration: TTS via `/media-use` (pick a voice explicitly — pass `--voice`); BGM resolved via `/media-use` at the default bed level (post-#2110 `bgmDefaultVolume`, do not override). -- Variables: expose the two palette colors + product name as composition variables; render twice — default, and one `--variables` re-skin. -- The film is built BY a builder subagent from a single long-form prompt (the "capstone prompt") that the guide will print in full — this is the point: the prompt IS the most advanced artifact. Author the capstone prompt first (brief + design system + storyboard direction + technique requirements in prose, per the guide's own anatomy), then run the Validation Protocol with name `capstone`. Iterate the prompt (fresh builder each time) until the render passes review; the shipped chapter prints the exact prompt that produced the shipped render. - -- [ ] **Step 1: Author the capstone prompt** (long-form; follows the guide's own 6-part anatomy; encodes the table above without naming levels) -- [ ] **Step 2: Run the Validation Protocol, name `capstone`** — builder must produce: `frame.md`, `STORYBOARD.md`, frames, passing `lint`/`check`, `capstone.mp4` -- [ ] **Step 3: Re-skin render** — `npx hyperframes render` with `--variables` overriding the palette colors → `capstone-reskin.mp4` -- [ ] **Step 4: Review gate** — watch both renders; check every row of the technique table is visibly present; if not, revise the prompt and re-run Step 2 with a fresh builder -- [ ] **Step 5: Upload** — copy `capstone.mp4` + `capstone-reskin.mp4` to `docs/images/prompting/`, run `bash scripts/upload-docs-images.sh`, `curl -sI` both URLs → 200 - -No repo commit in this task (artifacts live outside the repo + on S3). - ---- - -### Task 12: Capstone chapter + overview rewrite - -**Files:** - -- Create: `docs/prompting/capstone.mdx` -- Modify: `docs/prompting/overview.mdx` (full rewrite), `docs/docs.json` (add `"Level 7 — Capstone"` group with `["prompting/capstone"]` between Level 6 and Appendix), `docs/prompting/remotion-migration.mdx` (exit bridge → capstone) - -**Editorial contract — `capstone.mdx`:** - -1. Opens with the embedded `capstone.mp4` render, then: "every technique in this film has a chapter in this guide." -2. Prints the full capstone prompt verbatim (the one that produced the render), then dissects it: walk brief → design system → storyboard → frames → validation → render, each step linking the chapter that taught it (anatomy, visual-specs, motion, transitions, code-blocks, data-and-maps, generated-artwork, media-and-audio, design-systems, variables-and-templating, storyboards, rendering-and-output). -3. Shows the `capstone-reskin.mp4` pair with the exact `--variables` invocation used. -4. Exit bridge points at the Appendix cheat sheet: "keep this open while you build." - -**Editorial contract — `overview.mdx`:** - -1. Rewrite as the arc's map: open with the capstone embed and the promise "by the end of this guide you can build this with a prompt"; then the level ladder (one line per level: what you can do after it); then the existing one-time skill setup; then the two prompt shapes + workflow loop condensed. -2. Existing "best of" example embeds may stay at the bottom. - -- [ ] **Step 1: Write `capstone.mdx` per the contract** -- [ ] **Step 2: Rewrite `overview.mdx` per the contract** -- [ ] **Step 3: Nav + bridges, format + docs sanity gate** -- [ ] **Step 4: Commit** - -```bash -/usr/bin/git add docs/prompting/capstone.mdx docs/prompting/overview.mdx docs/prompting/remotion-migration.mdx docs/docs.json -/usr/bin/git commit -m "docs(prompting): capstone chapter + overview rewritten as the arc's map" -``` - ---- - -### Task 13: Final QA + PR update - -**Files:** - -- Modify: PR #2109 description (via `gh`), spec `plans/prompt-guide-arc.md` status line. - -- [ ] **Step 1: Full-guide QA sweep** - -```bash -cd ~/src/wt/hyperframes/prompt-guide -bun run format:check # expect exit 0 -python3 -c "import json; json.load(open('docs/docs.json')); print('ok')" -cd docs && npx mintlify broken-links # expect none -# every S3 embed resolves: -grep -rhoE 'https://static\.heygen\.ai/[^" ]+\.mp4' docs/prompting/ | sort -u | while read u; do - code=$(curl -s -o /dev/null -w '%{http_code}' -I "$u"); [ "$code" = 200 ] || echo "BROKEN $code $u" -done -``` - -Also start `npx mintlify dev --port 3333` in `docs/` and click through the level nav once. - -- [ ] **Step 2: Bridge-chain check** — read only entry/exit bridges of all chapters in nav order; every exit target matches the next chapter; fix any mismatch. - -- [ ] **Step 3: Update spec status** — change `plans/prompt-guide-arc.md` line 3 `Status:` to `implemented `; commit with the bridge fixes if any: - -```bash -/usr/bin/git add -A plans/prompt-guide-arc.md docs/ -/usr/bin/git commit -m "docs(prompting): final QA pass for the guide arc" -``` - -- [ ] **Step 4: Push + update PR #2109** - -```bash -/usr/bin/git push origin fix/prompt-guide-validation-bugs -gh pr edit 2109 --title "docs: Prompt Guide as a novice-to-capstone arc + text corrections from validation" -``` - -Rewrite the PR body (via `gh pr edit 2109 --body-file`) to describe: the arc restructure (levels, full dissolve, bridges), the capstone film + its validated prompt, new topics covered (proxies, new lint rules, changelog-video, structure mandate, variables/CSS fix), the new validation builds, and keep the existing "text corrections" section. Keep the existing footer convention. - -- [ ] **Step 5: Verify CI green** - -```bash -gh pr checks 2109 --watch -``` - -Expected: Format passes (Task 1); docs-only lanes skip as before. diff --git a/plans/prompt-guide-arc.md b/plans/prompt-guide-arc.md deleted file mode 100644 index aa58fe977..000000000 --- a/plans/prompt-guide-arc.md +++ /dev/null @@ -1,98 +0,0 @@ -# Prompt Guide arc restructure — novice → capstone - -Status: implemented 2026-07-22. Owner: Vance. Supersedes the _structure_ of -`plans/prompt-guide-expansion.md` (its content and validation rule carry over unchanged). -Lands on `fix/prompt-guide-validation-bugs`, amending PR #2109. - -## Why - -Reviewer feedback on the 29-page guide: it reads as a reference manual — "how to do -specific things with prompts" — with no story in the hierarchy. The fix: restructure as a -progression from novice to advanced where each section builds on techniques learned in the -prior one, culminating in the most advanced artifact a reader can build with everything -the guide teaches. - -Structure model ("full dissolve"): no standalone by-video-type / by-feature reference -sections survive. Every page becomes a chapter at the level where the reader is ready for -it, with an entry bridge ("you can now X") and an exit bridge ("next you'll Y"). - -## The capstone (design target — everything builds to this) - -A new, public, promo-style film about HyperFrames itself ("write HTML, render video"), -~45–60s, 6–8 frames. It is the "final form": the artifact only a reader who has absorbed -every level can prompt into existence. Modeled on the internal promo compositions -(`videos/team-vault-explained`, `~/src/videos/hyperframes-infra-proposals`) — the proven -advanced stack: - -- `frame.md` design system: strict two-color palette discipline, negative list, - permanent grid/chrome that rides every frame -- Storyboard with narrative arc, VO-paced reveals (each element lands on its spoken cue), - persuasion/beat columns, a callback (early motif returns denser late), one breather frame -- TTS narration + BGM at the fixed bed level (post-#2110 default) -- One generated-artwork hybrid frame (illustration-led → generated raster + code-layer - animation), one data-viz frame, one code frame -- Matched-motion transition between at least one frame pair -- Variables re-skin: default vs overridden render pair -- Full `lint` / `check` / render validation; built for real in - `~/src/hyperframes-prompt-examples/capstone/`; renders hosted on static.heygen.ai - -The capstone chapter walks brief → design system → storyboard → per-frame build → -validate → render, and each step links back to the level that taught it. The finished -MP4 is also embedded in the overview intro as the guide's promise ("by the end you can -build this"). - -## Level structure and page mapping - -Nav: the `Prompt Guide` top-level group's subgroups become levels. - -| Level | Title | Chapters (existing page → new role) | -| ----- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| — | Start here | `overview` — rewritten: the arc's map, skill setup, capstone teaser embed | -| L1 | Your first video | Workflow rides, one prompt + embedded render each: `product-launch`, `explainers`, `code-and-prs` (gains changelog-video), `captions-and-talking-heads`, `music-and-slideshows`, `motion-graphics` | -| L2 | Control | `anatomy`, `specification-dial`, `vocabulary`, `visual-specs`; `examples` becomes the level-end gallery (18 dissections) | -| L3 | Life | `motion` (grammar + measured A/B), `transitions`, seeded-motion rule 7 material | -| L4 | Substance | Capability chapters framed as "add this to what you have": `code-blocks`, `data-and-maps`, `overlays-and-lower-thirds`, `captions-catalog`, `generated-artwork`, `vfx-and-liquid-glass`, `runtimes-and-3d` | -| L5 | Voice & sound | `media-and-audio` expanded with the media-proxy subsystem (see New topics) | -| L6 | Scale | `design-systems`, `variables-and-templating` (+ CSS-shadow fix), **storyboards** (new chapter, extracted from internal-promo practice), `editing-existing-videos`, `iterating`, `recreating-references`, `rendering-and-output`, `remotion-migration` | -| L7 | Capstone | New chapter as specified above | -| — | Appendix | `rules-and-anti-patterns` kept as the consolidated cheat sheet; each rule is _also_ taught in-context at its level | - -Page count: ~30 (29 existing, minus none, plus storyboards + capstone; overview rewritten). -Keep page counts out of prose (standing drift rule). - -## New topics (landed on main after the guide was written, Jul 9–22) - -1. **Media proxy subsystem** → L5 chapter section: HEVC/hostile-codec probe, automatic - bounded H.264 and alpha-capable authoring proxies, serving from preview/play/static - server, baking into published archives, project opt-out, runtime swap of undecodable - video (#2585–#2598 range). -2. **New lint rules** → taught at the level where each gotcha becomes relevant AND listed - in the appendix: seek-order safety, SVG draw-on rules, relative-value second writers, - `tl.set` initial hides, cold-seek opacity reveals (#2503, #2612, f3d210066). -3. **Composition-structure mandate block** (#2599, 0aaac7aa3) → L2 anatomy context. -4. **changelog-video skill** (e96ebd74d) → L1 code-and-prs chapter. -5. **Variables no longer shadow authored CSS custom properties** (406894061) → L6 - variables chapter correction. - -## Validation - -Standing rule unchanged: no prompt ships unverified. Existing 64 renders are reused -wherever the prompt text survives the move verbatim. New validation builds required for: -the capstone film (full pipeline), the proxy-chapter prompt, new-lint-gotcha examples, -and the storyboard-chapter example. Same bar: built exactly as written by a builder -agent, lint/check pass, render embedded. - -## Mechanics - -- All work on `fix/prompt-guide-validation-bugs` in worktree - `~/src/wt/hyperframes/prompt-guide`; PR #2109 description updated to describe the arc. -- `docs.json` nav rewritten to the level groups; Mintlify redirects for any `prompting/*` - slug that moves; the existing `guides/prompting` → `prompting/overview` redirect stays. -- Renders synced via `scripts/upload-docs-images.sh` (S3, `docs/images/` stays gitignored). -- Fix the currently red Format CI check on the branch while in there. - -## Out of scope - -- Tier 3 registry-block overhauls (issue #2107) — unchanged. -- HeyGenVerse article resync / llms.txt check — post-deploy follow-ups as before. -- No behavior changes to skills or pipeline (that was PR #2110, merged). diff --git a/plans/prompt-guide-expansion.md b/plans/prompt-guide-expansion.md deleted file mode 100644 index bff69fac9..000000000 --- a/plans/prompt-guide-expansion.md +++ /dev/null @@ -1,266 +0,0 @@ -# Prompt Guide expansion plan - -Status: draft 2026-07-08. Owner: Vance. Source of validated content: the 2026-07-07/08 -prompting-guide work (18 verified example prompts, showreel recreation, motion grammar, -asset-gen hybrid, recreation protocol; renders in ~/src/hyperframes-prompt-examples, -preview page https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe). - -## Goal - -Promote `guides/prompting` from a single page to a top-level **Prompt Guide** nav group: -the current page splits into focused sub-pages, each expanded, and every documented -feature that _implies_ a promptable action gets actual prompting guidance. Standing -rule carried over from the original guide: **no prompt ships unverified** — every -example is built, rendered, and (where feasible) embedded next to its prompt. - -## Navigation (docs.json) - -New top-level group between **Concepts** and **Guides**: - -``` -[Prompt Guide] - prompting/overview - [Fundamentals] - prompting/anatomy - prompting/specification-dial - prompting/vocabulary - prompting/iterating - prompting/rules-and-anti-patterns - [Making it look good] - prompting/visual-specs - prompting/motion - prompting/generated-artwork - prompting/recreating-references - [By video type] - prompting/product-launch - prompting/explainers - prompting/code-and-prs - prompting/music-and-slideshows - prompting/captions-and-talking-heads - prompting/motion-graphics - [By feature] - prompting/transitions - prompting/captions-catalog - prompting/overlays-and-lower-thirds - prompting/code-blocks - prompting/data-and-maps - prompting/vfx-and-liquid-glass - prompting/rendering-and-output - prompting/editing-existing-videos - prompting/media-and-audio - prompting/variables-and-templating - prompting/runtimes-and-3d - prompting/design-systems -``` - -`guides/prompting` becomes a redirect to `prompting/overview`. Keep the page count out -of prose (drift rule, same as skills.mdx). - -## Page-by-page - -### prompting/overview - -Landing: what prompting a video means, one-time skill setup (moved from current page), -the two prompt shapes (cold/warm), the recommended workflow loop, and a map of the -section. Ends with 3 "best of" example prompts w/ embedded renders. - -### Fundamentals (split + expand current content — all already validated) - -- **anatomy** — the 6-part skeleton, per-part rationale, assembled terminal example, - plus 3 dissections: take a weak prompt, show the fixed version, diff annotated. -- **specification-dial** — mood → style tokens → full spec; cross-model validation - result; the two always-pins (Three.js, sequencing). Expand: when looseness is a - feature (creative exploration) vs when density is mandatory. -- **vocabulary** — existing mapping tables (easing, caption tones, transition energy, - audio-reactive, marker highlights, TTS voices, render quality) + new validated ones: - camera language ("push in 6%", "drone orbit"), depth language ("near-lens bokeh"), - pacing language ("punchy 2s cuts" vs "cinematic holds"). -- **iterating** — talk-like-an-editor edits (existing) + the calibration rules from the - recreation work: absolute targets not relative nudges, one axis at a time, freeze - what works. -- **rules-and-anti-patterns** — the 7 technical rules, anti-patterns, plus the newly - validated ones: never "holds motionless", don't create simultaneity conflicts, - don't override skill-mandated styles, "~60s" with verbatim scripts. - -### Making it look good (current sections promoted to pages, each gains examples) - -- **visual-specs** — density ladder + mountain-title worked example + 2 more specs - (one UI piece, one typographic piece) with renders. -- **motion** — the six-rule premium-motion grammar; before/after render pair - (frozen-hold build vs motion-pass build of the same piece — we have both). -- **generated-artwork** — hybrid pattern, 3 keying/restraint rules, before/after - (hand-drawn SVG team vs asset-gen team — we have both renders). -- **recreating-references** — the transcribe → iterate → distill protocol, fidelity - table, globe worked example + its one-shot render; honest-ceiling callout. - -### By video type (one page per workflow; the 8 current examples seed them) - -Each page: what the workflow does, 3-5 verified prompts (the existing one + variants: -different durations, aspect ratios, tones), the knobs that matter for that workflow -(e.g. explainer: verbatim vs summarized script, caption style, scene density), and -common failure modes. NEW VALIDATION NEEDED: ~2-4 variant builds per page. -Pages: product-launch (also covers website-to-video), explainers, code-and-prs -(pr-to-video + code blocks context), music-and-slideshows, captions-and-talking-heads -(embedded-captions + talking-head-recut), motion-graphics (also logo stings, stats). - -### By feature — the "implied but unguided" gap pages - -Sourced from existing docs that document a capability without prompting guidance: - -- **transitions** (sources: 14 shader + 13 CSS catalog groups, transitions skill) — - energy/mood → named block mapping, when shader vs CSS, per-seam prompting - ("whip-pan on phrase changes"), full block name table. Validation: montage build - exercising ~6 transitions. -- **captions-catalog** (sources: 15 caption components + embedded-captions skill) — - tone → component mapping ("karaoke pill", "kinetic slam", "matrix decode"), per-word - styling asks, safe-area/vertical notes. Validation: one clip rendered with 4 styles. -- **overlays-and-lower-thirds** (sources: social overlays, lower-thirds, news-ticker - catalog groups) — "add a lower third at 0:03 with name/title" class of prompts, - picking styles by brand tone, transparent-overlay output for NLEs. -- **code-blocks** (sources: code animations + 24 code-snippet themes) — prompting - code walkthroughs: typing, diff, highlight, scroll; theme selection language. -- **data-and-maps** (sources: data-chart, 5 US-map variants, world/spain maps) — chart - prompts from CSV/inline data, map highlight/flow/bubble asks, the animated-map - motion-graphics pattern. -- **vfx-and-liquid-glass** (sources: HTML-in-Canvas group, html-in-canvas guide) — - device mockups, liquid glass, shatter/portal/magnetic effects; when these need the - canvas pipeline and what to say. -- **rendering-and-output** (sources: rendering, 4k-rendering, hdr, deploy/lambda) — - quality/format/framerate asks, transparent WebM (and when it's incoherent — full-frame - designs), 4K/HDR guidance incl. cost warnings, "render this on Lambda" cloud prompts. -- **editing-existing-videos** (sources: timeline-editing, keyframes, - video-editor-cheatsheet, studio docs) — NLE-verb prompts: trim/split/move/retime - scenes, keyframe nudges, "make scene 2 snappier", swap assets; maps the cheatsheet's - editor verbs to prompt phrasings. Likely the highest-traffic page of the group. -- **media-and-audio** (sources: video-components, remove-background, media-use skill) - — TTS voice/tone/speed asks, BGM mood + loudness targets ("under -18dB"), SFX cues, - transcription/captions from audio, background removal, video-in-video/PiP, and the - supplied-assets rule (explicit paths). -- **variables-and-templating** (sources: concepts/variables, sdk) — parameterized - compositions ("make name/logo/color variables"), batch/personalization prompts, - template-then-instantiate pattern. -- **runtimes-and-3d** (sources: concepts/frame-adapters, gsap-animation) — the - Three.js-via-adapter pin with worked language, when Lottie/CSS/WAAPI make sense to - request, shader transition requests, canvas/WebGL determinism caveats in prompt form. -- **design-systems** (sources: claude-design, open-design, figma skill) — design.md / - brand-token driven prompting, "use the site's own palette", Figma import asks. - -## Validation & build plan - -Reuse the proven pipeline: Opus builder subagents, one-shot from the page's prompts, -lint+validate+render gates, frame verification; embed finished MP4s next to prompts -(Mintlify supports video embeds; assets go wherever docs media lives today — confirm -hosting path, else link the HeyGenVerse gallery). - -Phasing (each phase shippable): - -1. **Restructure** — split current page into overview + Fundamentals + Making-it-look-good - (no new validation needed; content exists). Add nav group + redirect. ~1 PR. -2. **High-traffic gaps** — editing-existing-videos, rendering-and-output, - media-and-audio, transitions, captions-catalog. Each needs a validation build day. -3. **By video type** — 6 pages, variant builds per workflow. -4. **Long tail** — remaining feature pages (data-and-maps, vfx, variables, runtimes, - design-systems, overlays, code-blocks). - -## Competitive research findings (2026-07-08, adversarially verified) - -Deep-research survey of first-party prompt guides — Sora 2 (OpenAI Cookbook), Runway -Gen-3/Gen-4, Veo (DeepMind + Cloud Veo 3.1), Luma, Anthropic prompt-engineering docs. -(Pika/Kling/Midjourney/Gemini/Copilot claims failed verification — resurvey later.) -What the best guides converge on, and what we adopt: - -1. **Named content-slot anatomy.** Every major guide teaches a slot formula - (camera + subject + action + context + style [+ audio]); Veo 3.1 and Runway Gen-3 - make it a literal bracket template. We already have a _process_ skeleton - (route/spec/beats/copy/technique/negatives) — ADD a named _content_ formula whose - slots map to HyperFrames concepts (beat + element + motion + layout + style/brand - - audio), demonstrated in one worked example. Lives on the anatomy page. -2. **Keyword→Output tables.** Runway Gen-3's gold standard: six categorized keyword - tables where every row pairs the keyword with the actual generated output. Our - vocabulary tables get the same treatment: motion verbs → GSAP behavior, camera - terms → transform/Three.js choreography, style terms → CSS treatment — each row - with a small rendered clip. (Borrow the format, not their legacy keywords.) -3. **Output pairing is the differentiator.** Even the best guides skip outputs on - their most complex examples (Sora's longest templates ship without any; both Veo - guides mostly unpaired — refuted 0-3). Our article standard (every prompt + - unedited render) beats the field; keep it absolute. -4. **❌/✅ paired rewrites under named rules with engine rationale** — Runway's - dominant device (e.g. ❌ "no clouds in the sky" → ✅ "a clear blue sky", because - negative prompts backfire). Adopt across anatomy + rules pages using our own - validated pairs: ❌ "holds motionless" → ✅ "settles into ambient idle"; - ❌ "both at 4s" → ✅ "fades out by 4.2s; at 4.2s..."; ❌ "make dots 2x finer" → - ✅ "dot radius = 25% of row spacing". -5. **Iteration as single-variable science.** Sora: "editing is for nudging, not - gambling" — one change per edit; Runway Gen-4: minimal motion-only prompt first, - then add ONE element type at a time; strip-then-relayer when a shot misfires. - Expand the iterating page with these three moves + our absolute-targets rule. -6. **Timestamped/beat-segmented prompting as a signature device.** Veo 3.1's - [00:00-00:02] per-segment prompting is the survey's most distinctive device — and - it maps one-to-one onto HyperFrames' native data-\* timing. Our "Beat N (x-ys)" - convention is this; promote it explicitly ("more native here than in any - diffusion model") on anatomy + by-video-type pages. -7. **Anthropic's IA moves**: thin-router overview, one consolidated living - best-practices reference (legacy URLs 301 into anchors), prerequisite gate - ("before prompting, have X"). Adopt: keep overview thin; add a short - prerequisites block (skills installed, preview running, project scaffolded); - plan redirects when pages consolidate later. -8. **Efficacy evidence as differentiation** (research open question): no surveyed - guide shows its advice measurably works. Ours can — renders are deterministic and - cheap; we already hold before/after pairs (frozen vs motion-passed, hand-drawn vs - generated, loose vs dense builds). Add "before/after" render pairs as a standard - device on making-it-look-good pages. - -Full cited report: deep-research run wf_c81199b6-b15 (22 confirmed claims, 3 refuted; -sources incl. cookbook.openai.com, help.runwayml.com, deepmind.google, cloud.google.com, -lumalabs.ai, platform.claude.com). - -## Incorporate the article's drafted guidance - -The HeyGenVerse article (https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe) -drafted guidance and presentation patterns beyond the current mdx — these become the -template for every expanded page: - -- **Proof pairing**: every example prompt is immediately followed by its unedited - render with the label "Rendered from the prompt above, unedited." This is the - guide's core credibility device — pages without renders don't ship. -- **Provenance line**: each page states how its claims were validated (built, - rendered, frame-verified) and when. The article's footer wording is the model. -- **Example tags**: prompts carry a visible registry-block / workflow / freeform tag - so readers learn which layer of the system they're exercising. -- **Drafted section prose to carry over into the split pages** (the article's phrasing - is tighter than the mdx in places — reconcile toward the article): - - Specification dial: "controls how far the result drifts from what you imagined, - not whether it works" + the two-pins callout as a distinct highlighted element. - - Generated artwork: the wins/loses two-column comparison (code-drawn wins / - code-drawn loses) rather than prose paragraphs. - - Motion: six numbered rules with the "frozen final second is the biggest - cheap-motion tell" line. - - Recreation: the 3-row fidelity table (transcribe ~75% / iterate ~90% / - distill ~80-90%) + honest-ceiling callout, with the one-shot render embedded - under the distilled spec (not the hand-tuned version — the honest artifact). -- **Article lifecycle**: the HV page stays the shareable preview/marketing surface; - it gets regenerated from the docs content at the end of each phase so the two never - fork. Renders already uploaded as HV assets (19 MP4s) are reusable by URL in the - docs if we choose the link-out hosting option (open question 2). - -## Consistency obligations - -- CLAUDE.md "skill catalog maintenance" applies: skills' SKILL.md descriptions stay the - source of truth for one-line blurbs; the by-video-type pages must link the matching - skill and not fork its routing language. -- llms.txt regenerates from docs — verify the new group lands there. -- Vocabulary tables must match what skills actually implement (easing map, caption - tones) — audit against skills/hyperframes-animation + embedded-captions at write time. -- Catalog pages already demo each block; feature pages link to them rather than - duplicating block docs. Prompting pages own only the "what to say" layer. - -## Open questions - -1. Group vs tab in docs.json (Mintlify): group keeps single-sidebar; tab gives the - guide its own sidebar. Current nav is single-tab groups — start as group, promote to - tab if it crowds. -2. Where do example MP4s live for docs embeds — repo (heavy), CDN bucket, or link out - to the HeyGenVerse gallery page? Decide before Phase 1 ships renders. -3. Do by-video-type pages absorb the existing standalone guides (website-to-video) or - link them? Proposal: link, don't absorb — those guides cover mechanics, prompting - pages cover phrasing. diff --git a/skills-manifest.json b/skills-manifest.json index 7dd28d9f0..6d8a47100 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -22,7 +22,7 @@ "files": 17 }, "hyperframes-animation": { - "hash": "07ca0a5ce9d127ac", + "hash": "6c13cdce4f3a23c2", "files": 121 }, "hyperframes-cli": {