diff --git a/.gitignore b/.gitignore index 52719ff212..b12b8d1068 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,17 @@ Thumbs.db # with `bun run upload:docs-images`. Add explicit negations below for any # non-generated assets (logos, svgs) that should stay in the repo. docs/images/ +!docs/images/ +docs/images/* +!docs/images/studio/ +!docs/images/studio/*.jpg +# The introduction's explainer film. Not a generated preview: it is authored, it +# is the page's whole argument, and at 332KB silent it costs less than one +# catalog preview. Committed so the page cannot break when a CDN credential +# expires. The version with its music bed lives on the CDN instead. +!docs/images/showcase/ +!docs/images/showcase/*.mp4 +!docs/images/showcase/*.jpg videos/ diff --git a/README.md b/README.md index b3e8d69560..3966033fd1 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Install the HyperFrames skills, then describe the video you want: npx skills add heygen-com/hyperframes --full-depth ``` -> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas a non-interactive `skills add` without `--skill` installs all 19. +> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas a non-interactive `skills add` without `--skill` installs the full set. > > `--full-depth` does a full clone of the repo's current `main`. Without it, `skills add` fetches the skills.sh registry blob, which lags `main` by hours — you'd get an older copy of a skill. (`hyperframes skills update` already installs full-depth.) @@ -53,9 +53,9 @@ The skills teach agents the HyperFrames production loop: plan the video, write v ## Skills -HyperFrames ships 19 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below. +HyperFrames ships skills that agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below. -Default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes --full-depth`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 19. Use `npx skills add heygen-com/hyperframes --all --full-depth` to install all 19 deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill --full-depth` for just one (bare name, no leading `/`). Keep `--full-depth` — it installs the current `main`; without it `skills add` fetches the skills.sh blob, which lags by hours. +Default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes --full-depth`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs the full set. Use `npx skills add heygen-com/hyperframes --all --full-depth` to install everything deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill --full-depth` for just one (bare name, no leading `/`). Keep `--full-depth` — it installs the current `main`; without it `skills add` fetches the skills.sh blob, which lags by hours. Installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (the router, the `hyperframes-*` domain skills, and `media-use` — plus whatever is already installed; `/figma` stays on demand) and never expands a partial install; the creation workflows install **on demand** — the router runs `npx hyperframes skills update ` before entering one. Nothing re-pulls the full set behind your back. diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000000..caba40b490 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,124 @@ +# HyperFrames documentation rules + +Before changing anything in `docs/`, read: + +1. `../research/docs-refactor/PLAN.md` +2. `../research/docs-refactor/NOTES.md` +3. The complete body of every page you plan to change +4. The product source or tests that prove the behavior being documented + +These rules are persistent and apply to every documentation session: + +- Write for a smart general user first. Do not assume they are a developer. +- Explain what a person can accomplish before explaining implementation details. +- Prefer plain words, short examples, screenshots, and visible outcomes. +- Keep agent instructions copyable and specific. +- Put CLI, SDK, package, schema, deployment, and internals under **Developers**. +- Never infer product behavior from page titles or old docs. Verify it in current code. +- Do not preserve a page merely because it already exists. Merge, rewrite, redirect, or remove it when that improves the user journey. +- Do not publish empty, duplicated, outdated, or aspirational content as fact. +- A page should answer a real question or help complete a real task. +- Keep ordinary top-level groups inside each tab, with no nested `root`, `directory`, `expanded`, or drilldown behavior. +- Match the deployed main docs' sidebar rhythm: 14px medium group headings, square links, no horizontal group dividers, and a segmented vertical rail whose active segment follows the current page. Groups remain open and non-collapsible. +- Keep the Aspen sidebar aligned to the 56px header and disable its early scroll-fade mask. +- Keep Mintlify's right-side **On this page** behavior and styling unchanged. +- Keep Aspen's desktop header on one row: logo, tabs, search, compact GitHub link with its star count, Playground action, and theme toggle. Preserve the fixed-width star-count fallback so client-side navigation does not make the control blink or collapse. +- Keep the bottom-center agent input visually distinct from the page with its own surface, stronger border, and restrained shadow. +- Record important findings, uncertainties, and decisions in `../research/docs-refactor/NOTES.md`. +- Update progress and changed decisions in `../research/docs-refactor/PLAN.md`. + +## Page standard + +Most human-facing pages should contain: + +1. What this lets you do +2. When to use it +3. A visual or concrete example +4. The shortest successful path +5. What should happen +6. Common problems +7. Useful next steps + +Do not force this structure where it makes a page worse. Reference pages may stay reference-shaped. + +## Component doctrine + +One component per job. If two components on a page render the same list, delete one. + +| The job | Use | Never use | +| --- | --- | --- | +| Choose between destinations | `CardGroup` + `Card`, max 2 columns, linking to the real page | An accordion, or cards pointing at anchors on the same page | +| Ordered instructions | `Steps` | A flow diagram that repeats the same steps | +| Parallel variants of one instruction (source type, OS, language) | `Tabs` | Repeating the whole block per variant | +| Compare attributes across items | A table | Prose paragraphs per item | +| Any media | `Frame` with a caption that says what it is | A bare `img` with no context | +| Genuinely out-of-band aside | One `Note`, `Tip`, or `Warning` per page | Stacked callouts, or a callout for ordinary prose | + +**Accordions are not used.** They hide the thing the reader is choosing between, cost a click, break `Cmd+F` and printing, and render as grey bars. Long symptom or reference lists become visible `##` sections instead — they get anchors the support team can link directly, and they appear in the page contents. + +**No diagram that restates adjacent prose.** A four-node flow beside a four-step list is the same content twice. Keep whichever is more useful and delete the other. + +**Cards link to pages, never to anchors on the current page.** A card that scrolls the reader a short distance to the same words is the worst pattern in these docs; it has been removed twice. + +**Two columns is the practical maximum** for anything containing text. Three columns in this content width hyphenates titles mid-word. + +### Custom React components + +Mintlify compiles `.jsx` / `.tsx` from `docs/snippets/`. Use one when a native component genuinely cannot express the idea — a scrubber, a comparison slider, a live player — not for styling. + +- Named exports only: `export const Thing = () => ...`. Default exports do not work. +- `useState`, `useEffect`, `useRef`, `useCallback`, `useMemo`, `useContext`, `useReducer` are pre-injected; do not import React. +- **No third-party packages and no CDN scripts.** Browser built-ins only (`fetch`, `IntersectionObserver`, Canvas, `