docs: rewrite the guides and landing pages - #2979
Conversation
There was a problem hiding this comment.
Pull request overview
This PR is a docs-only rewrite pass over the surviving Guides + landing pages, shifting each page to lead with what a reader can accomplish and pointing them at the restructured sections introduced in the prior stacked PR (#2978), while keeping the page set and navigation unchanged.
Changes:
- Standardizes docs video embeds by switching raw
<video>tags to the shared<DocsVideo />snippet where applicable. - Rewrites key entry pages (Introduction, Quickstart, Examples, core Guides) to be task-first and more directly actionable.
- Condenses/reshapes several deep-dive guides into shorter “do this / verify this / next” flows and refreshes cross-links to the new structure.
Reviewed changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/weekly-updates.mdx | Replaces inline <video> embeds with the shared <DocsVideo /> component for weekly update videos. |
| docs/quickstart.mdx | Reframes Quickstart as “Make your first video”, adds guided continuation components and an embedded walkthrough video. |
| docs/introduction.mdx | Rewrites Introduction to a task-first overview with showcase wall + live reference project embed. |
| docs/guides/video-components.mdx | Retitles/reorients guide to practical media import/placement workflow (Studio + agent), removing catalog-centric framing. |
| docs/guides/troubleshooting.mdx | Restructures troubleshooting into a symptom-first flow with a clearer diagnostic sequence and targeted fixes. |
| docs/guides/skills.mdx | Rewrites skills page into “Install and update agent skills”, emphasizing core install + on-demand workflows. |
| docs/guides/rendering.mdx | Condenses rendering guidance into a CLI-focused, task-driven reference with format/quality/Docker guidance. |
| docs/guides/performance.mdx | Rewrites performance guide into a shorter “symptom → measure → reduce cost” workflow. |
| docs/guides/open-design-hyperframes.md | Small wording update for registry description. |
| docs/guides/media-effects.mdx | Rewrites media effects into intent-driven selection + Studio/agent workflows and performance caveats. |
| docs/guides/mcp.mdx | Rewrites MCP guide into “Create through an AI chat” with hosted-vs-local positioning and updated setup steps. |
| docs/guides/hyperframes-vs-remotion.mdx | Refactors comparison into a practical decision guide and clarifies the animation model differences. |
| docs/guides/html-in-canvas.mdx | Reframes guide around “start with proven block”, support constraints, minimal pattern, and verification steps. |
| docs/guides/hdr.mdx | Condenses HDR guidance to a shorter “render + verify + limits” reference. |
| docs/guides/gsap-animation.mdx | Rewrites GSAP guide around the minimal seek-safe contract + verification workflow. |
| docs/guides/figma.mdx | Updates Figma guide language to reflect connector/token paths and adds related-topic links. |
| docs/guides/feedback.mdx | Rewrites feedback page into task-driven “send feedback / file issue safely” guidance. |
| docs/guides/deploy.mdx | Rewrites deploy guide into clearer template selection + operational safeguards before exposing endpoints. |
| docs/guides/color-grading.mdx | Refactors grading guide into an order-of-operations workflow, with Studio-first and agent prompts. |
| docs/guides/claude-design-hyperframes.md | Updates a resolution flag example and fixes internal skill-reference URLs. |
| docs/guides/authentication.mdx | Rewrites authentication guide around “when to sign in” + provider selection/fallback behavior. |
| docs/guides/4k-rendering.mdx | Rewrites 4K guide into “render vs author at 4K”, constraints, and verification steps. |
| docs/examples.mdx | Reworks Examples into “finished films + one open reference project + templates” with updated embeds/links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
faf1c6b to
0b8b631
Compare
0b8b631 to
0708e63
Compare
2aff6a5 to
d7d821a
Compare
0a46de1 to
5d7cbb1
Compare
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Reviewed at head 5d7cbb101996e81d0ff6c1e468b1ec407bc7d54e. You asked for claims verified against packages/ and skills/ rather than against the old docs, and for any rewrite that only reshuffles — so that is what this covers. Same state caveat as on #2978: the stack restacked mid-review, I re-verified via blob SHAs, and this is not a green-CI review (30+ checks cancelled from the restack, Validate docs among them, Analyze still running).
Confirmed first that the page set really is unchanged here: the docs/ tree at this head is identical to #2978's, so this PR is purely content. That makes "did any claim change meaning" the whole review surface.
The claims check, run mechanically
Commands — all real. I extracted every npx hyperframes <command> occurrence across the 24 rewritten files — 98 occurrences, 20 distinct commands — and checked each against packages/cli/src/commands/. Every one resolves to a real command module: add, auth, benchmark, browser, check, compositions, doctor, feedback, info, init, lint, media-treatment, preview, publish, remove-background, render, skills, snapshot, telemetry, tts. No phantoms.
Flags — also all real. 44 distinct --flag tokens across the same files. Five had no occurrence anywhere in packages/: --accent-dim, --font-body, --font-data, --font-display, --ink. Those are false positives from my own regex — they're CSS custom properties inside style blocks in claude-design-hyperframes.md and open-design-hyperframes.md, not CLI flags. Reading the sites rather than trusting the grep, the real phantom count is zero.
The +5/-5 diff is the most valuable change in the PR
docs/guides/claude-design-hyperframes.md is the file most likely to be dismissed as a reshuffle. It's the opposite — it's the one place where your "verify against packages/, never against the old docs" instruction visibly pays for itself:
-1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 3840x2160` to override.
+1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 4k` to override.Verified at source. --resolution is parsed by normalizeResolutionFlag (packages/parsers/src/types.ts), which accepts only members of VALID_CANVAS_RESOLUTIONS or keys of RESOLUTION_ALIASES and returns undefined for anything else. packages/cli/src/commands/render.ts:279 documents the accepted set: the presets landscape, portrait, landscape-4k, portrait-4k, square, square-4k, plus the aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square.
A raw 3840x2160 is not in either set. The old text documented a command that does not work; 4k is a documented alias and does. Worth calling out explicitly because a reviewer checking this PR against the old docs would have read a five-line diff to a widely-copied guide and flagged it as an unexplained regression. That's the exact failure mode your instruction was aimed at, and it would have landed on the one change that fixes a genuinely broken claim.
One cross-PR note
docs/weekly-updates.mdx picks up the DocsVideo import and converts four raw <video> tags to the component. That's a good change on its own terms — but #2978 removes that page from the navigation with no redirect and no deletion, so this PR is improving a page the PR beneath it orphans. Details are in my review on #2978; flagging it here because this diff is the strongest evidence the nav removal was accidental rather than deliberate.
On "reads as the same edit 24 times"
It largely does, and the compression is real (+1563/-3948). I sampled the meaning-bearing direction rather than the prose: the risk in a rewrite this uniform is a claim that quietly changes truth value, and the command/flag sweep above is the version of that check I could run exhaustively. It came back clean, and the one change that did alter a claim altered it in the correct direction. open-design-hyperframes.md at +1/-1 is the only genuine near-no-op, and it's a link-text touch.
Not stamping — you asked for review rather than approval, and the stack's parent still has an open changes-request against it, so any approval here would be orphaned by the next restack anyway.
- Rames Jusso
5d7cbb1 to
05773c2
Compare
|
Nothing to fix here, so this is mostly acknowledgement — but two parts of this review are worth pinning. The command and flag sweep. 98 occurrences, 20 distinct commands, 44 flag tokens, each resolved against The Your point about the failure mode is the one I'll carry: a reviewer checking this PR against the old docs would have seen an unexplained five-line diff to a stable guide and flagged it as a regression. That's precisely why the instruction said to verify against The cross-PR note. Correct, and fixed in #2978 —
|
05773c2 to
7c5f0c1
Compare
7c5f0c1 to
689644e
Compare
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Re-reviewed at head 689644e25e69bb85ca94528610acdf2805258d04. Approving.
The head moved since my last pass (5d7cbb10) and the old commit is no longer reachable after the restack, so I compared through the contents API at both SHAs instead of diffing. Every file my review rested on is byte-identical — weekly-updates.mdx, guides/claude-design-hyperframes.md, guides/open-design-hyperframes.md, guides/deploy.mdx. The only change is docs.json, inherited from #2978 below it. So the content review carries in full and there is nothing new to re-verify here.
My earlier pass came back clean on the thing you asked for: 98 npx hyperframes <command> occurrences across 20 distinct commands and 44 distinct flags, every one resolving to real source in packages/cli/src/commands/, with the five apparent phantoms turning out to be CSS custom properties in style blocks rather than CLI flags. The --resolution 3840x2160 → 4k correction is still the highest-value change in the PR — normalizeResolutionFlag rejects raw WxH, so the old text documented a command that does not work.
The cross-PR note I left is now closed. I flagged that this PR upgrades weekly-updates.mdx to DocsVideo while #2978 removed that page from the navigation, and used it as evidence the removal was accidental. #2978 has since restored both weekly-updates and changelog to the nav, so the stack no longer contradicts itself and this PR's investment in the page lands where a reader can reach it.
CI is terminal-green at this head: all eight required contexts report success.
One item that belongs to this PR but surfaced while reviewing #2976 above it, and is worth a one-character fix before merge rather than a follow-up. This diff introduces <CardGroup cols={3}> at docs/guides/deploy.mdx:93 — the new ## Source group, replacing a two-column one. There were zero cols={3} anywhere in docs/ at #2977, and this is still the only one. Two PRs later, #2976 writes docs/AGENTS.md saying "Two columns is the practical maximum for anything containing text. Three columns in this content width hyphenates titles mid-word," and these three cards do carry body text. Dropping it to cols={2} here leaves the doctrine clean at merge instead of shipping the only counterexample to it in the same stack. Not a blocker and not a reason to hold the approval — flagging it here because this is the diff that owns the line.
Approving on my own verification.
Review by Rames Jusso
596be87 to
1a55539
Compare
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Re-reviewed at head 1a555397 after the subtractive push retired my approval. Approving.
What this PR's own delta is
Against my last approved head, +3 / −513. Most of that is inherited from #2977 below it. This PR's own two changes:
docs/introduction.mdx— the## Change the project yourselfsection and theLiveReferenceProjectimport removed. Clean removal: the import goes with its only usage, and nothing else on the page referenced either.docs/guides/deploy.mdx:93—<CardGroup cols={3}>→cols={2}.
That second one is the fix I asked for two rounds ago, and it closes the item: there is now no cols={3} or higher anywhere in docs/, so #2976's column rule lands without a counterexample shipping in the same stack. Worth noting it was not in the summary of this PR's changes, which said the introduction edit was the only one — no harm here since the extra change is one I asked for and verified, but a reviewer taking the summary at face value would have skipped the file.
On the Tests on windows-latest red
The attribution checks out, with one correction to how it is being verified. Tests on windows-latest is currently in_progress at this head with no failure conclusion on the commit, consistent with a flake that cleared on re-run.
The supporting claim — that the stack modifies zero files under packages/ — is true, but not by the obvious comparison. git diff origin/main <head> reports 87 changed files under packages/, because main has advanced past the stack's branch point and that diff shows the reverse of everything landed since. Against the merge-base (1d0d4d89) the stack's own changes are docs, examples, registry, scripts, .github, and four root config files — and zero under packages/. So the conclusion holds; anyone re-checking it should use the merge-base or the comparison will contradict you.
CI
Seven of the eight required contexts are green at this head; regression has not reported and Tests on windows-latest is still running. Zero failure conclusions among any check on the commit.
Approving on my own verification, as a statement about 1a555397 specifically.
Review by Rames Jusso
1a55539 to
ca43dbe
Compare
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Re-reviewed at head ca43dbef. Approving. This PR owns both content changes in this push, so the verification is here.
quickstart.mdx — I checked the command, because it isn't the same one
The new paste-block tells the reader:
1. Run: npx hyperframes skills update
Step 1 of the manual path does something different — npx skills add heygen-com/hyperframes --full-depth, then "Choose Core Skills in the picker." And skills update's own description ends with "without names it never expands a partial install." So the obvious failure mode for a block whose whole pitch is "paste this and skip the rest of the page" is that it silently no-ops on a folder with nothing installed yet — which is exactly the audience the block names.
It doesn't. In updateSkills (packages/cli/src/commands/skills.ts), targets are selected with isCoreSkill(s.name) as an unconditional disjunct, and toInstall takes anything whose status is "missing":
const targets = manifestSkills.filter(
(s) => requested.includes(s.name) || isCoreSkill(s.name) || (opts.refreshInstalled === true && s.status !== "missing"),
);
const toInstall = targets.filter((s) => s.status === "missing" || s.status === "outdated");A fresh folder therefore installs the core set. The "never expands a partial install" caveat is about non-core skills, which need to be named. The block works as written, and "Everything below is the same thing done by hand" is a fair description of the outcome even though the command differs.
examples.mdx — the card wall
Collapsing four cards to one horizontal Card is doctrine-clean: a bare <Card> outside a CardGroup is an established pattern here (11 files use it), and the new one links to a real page rather than an anchor. It also deletes the stack's only anchor-linking card (VERIFICATION.md#2-v1--v2) — the exact pattern #2976's doctrine says "has been removed twice" — so this improves compliance rather than straining it.
One consequence to make deliberate: VERIFICATION.md now has zero inbound links anywhere in docs/. It was reachable only through the Revision and Checks cards you just removed. The file still exists and the new card points at the containing folder, so a reader can find it by browsing. If that's the curation call, fine — flagging it so it's a decision rather than a side effect of trimming the wall.
MDX integrity
Checked by hand because the docs workflow has not run on this head: all 45 snippet imports across docs/ resolve to files that exist, and the AgentAction import is gone from quickstart.mdx with no surviving reference anywhere in the tree.
CI
No workflow has run on this head. The Actions API returns zero runs for this SHA, and the only check runs present are Mintlify Deployment (skipped) and WIP. The most recent CI evidence on this branch is from the previous head.
Every branch in the stack except #2977 is in this state. The simultaneous force-push of all six looks to have left GitHub without a synchronize event for the stacked PRs — which also explains #2978's phantom conflict. Required checks hold the merge until they report, so nothing slips through; it just needs a re-trigger.
Approving on my own verification, as a statement about ca43dbef specifically.
Review by Rames Jusso
* docs: add the shared page components Adds the six React snippets the rebuilt documentation pages compose against, plus the styles they need. Nothing imports them yet, so this lands with no user-visible change and no navigation churn. - DocsVideo / ShowcaseWall — the film player and the Showcase grid - LiveReferenceProject — embeds the Reference Project via <hyperframes-player> - WorkflowChooser, AgentAction, and the two grid snippets The scrub indicator is a timecode bubble rather than a thumbnail. Mounting a second <video> with the same src to drive a preview frame made every page carrying a film download the whole file twice, which is not worth a thumbnail. * docs: add the Reference Project example One real 10-second project the documentation can point at instead of describing a hypothetical one: a live capture of example.com, synthesised narration, and caption timings measured from that narration. It passes its own gates — `hyperframes lint` clean, `hyperframes check` passed, 28/28 text checks WCAG AA. No page imports it yet, so this lands without touching navigation. Only the two WAV masters exceed the repository's 500 KB non-LFS limit, so only those go through LFS. The MP3 stings and the capture PNG stay plain, which keeps the example usable after a clone without `git lfs pull`. `bun run docs:bundle-reference` regenerates the single-file embed the Introduction page loads from the CDN. * docs: keep the Reference Project verification report The Examples page links this file twice — as "What changed after review" and as "The real verification report" — in the section that makes the project's brief, source, revision notes, and checks public end to end. It is a published artifact, not leftover scaffolding. * docs: state the Reference Project embed's isolation contract The composition is fetched from the CDN and handed to the player as a blob: URL, which inherits the docs origin, and <hyperframes-player> sandboxes its iframe with allow-scripts + allow-same-origin. So the embedded composition runs with script access to this origin. That is a consequence of how the player works — it drives seeking through the iframe's document, which a cross-origin frame does not expose — not something this component can fix. Serving the CDN URL directly would isolate the frame and break playback. The guard is therefore the source, so the comment says so out loud: src must stay a first-party path we publish, never user- or community-supplied HTML. * fix(docs): resolve reduced-motion on the first render, and the embed's dep gap Both defects from Rames Jusso's review on #2977. Neither is visible today because nothing imports these files yet, which is what makes them cheap now. **Reduced motion resolved one paint too late, in all three grids.** `useState(false)` plus a `matchMedia` read in an effect meant the first committed render always emitted `<video src autoPlay loop>`; a reduce-motion visitor had 6 + 8 + 4 tiles already fetching before the attributes came off. `autoPlay` also overrides `preload="metadata"`, so those were the files, not metadata probes — and dropping `src` with no following `load()` is not a reliable abort. A lazy initializer knows the answer on the first render. **LiveReferenceProject never sent the initial variables.** The sending effect read `playerRef.current`, assigned by the effect above it on the commit where `compositionSrc` lands — a commit with nothing in the sending effect's dep array. So it ran once against a null ref and never again. It looked correct only because the three defaults match what the composition already renders. Also from the same review: - The object URL could outlive its revoke: once the body resolves, `abort()` no longer stops the chain, so the blob could be minted after cleanup ran with `objectUrl` still undefined. Same `cancelled` guard the effect above uses. - `postMessage` targeted `"*"` while the isolation comment argues the frame is same-origin. Naming `window.location.origin` turns that prose guard into an enforced one. - Nothing reached a terminal state when the player script never arrived: `whenDefined()` does not reject, and a later mount reuses the tag without its error listener. A CSP rule or content blocker never fires `error` at all. A deadline covers every path instead of sitting on "Loading…" forever. - `loadFailed` was never cleared, so one transient failure stuck. - The README claimed a clone works without `git lfs pull`. It does for the visuals; both WAVs are pointers and they are the bed and the voiceover, so the captions would play over silence. Says so now. - The bundler stripped trailing whitespace document-wide while inlining the runtime, which reaches inside script template literals where those spaces are data. It also assumed a literal `<head>` and would silently ship an embed with no `<base>`. Strip removed, anchor asserted. Copilot's five "missing hook imports" comments are wrong — Mintlify pre-injects the hooks, and `TemplateCard.jsx`, cited as the counter-example, uses the `export function` form the same page says is unsupported. * fix(docs): stop preview loops when Reduce Motion is turned on mid-session Miguel's changes-requested on #2977. He is right about the mechanism: dropping `src` and `autoPlay` through React props neither pauses a playing element nor aborts its selected resource, so a visitor who turned Reduce Motion on with the page already open kept every tile running. Measured in a browser rather than argued from the spec, same clip, same sequence: playing paused=false t=2.90 readyState=4 networkState=1 React props only paused=false t=3.90 readyState=4 networkState=1 + pause/removeAttr/load paused=true t=0 readyState=0 networkState=0 The middle row is the bug: time still advancing, resource still held. Rames' follow-up asked for a remount-to-poster instead, because a video that ends with `src` removed holds its last frame and `poster` only paints before playback begins. `load()` covers that too — it drops readyState to HAVE_NOTHING, which is precisely the state that paints the poster. Confirmed side by side on screen: the React-props-only tile sits on an arbitrary mid-clip frame, the pause/load tile shows the poster again. So no remount is needed. The guard cannot be shared as code — Mintlify compiles each snippet in isolation and forbids one importing another — so it is copy-pasted into all three grids. A duplicated invariant is the kind that rots, and a rendering test would mean adding React to a repo that only carries it inside packages/studio, plus mocking Mintlify's hook-injection contract with a mock that can stay green while the page breaks. `scripts/check-docs-snippet-motion.mjs` asserts the source instead, wired into `bun run lint`, with unit tests covering both edges. That gate immediately found `docs/snippets/TemplateCard.jsx`: autoplays with no reduced-motion handling at all. It is imported by zero pages, and it uses the `export function` form Mintlify's constraints page says is unsupported, so it would not work if it were. Deleted rather than fixed. * refactor(scripts): split the motion guard into named predicates fallow flagged findMotionGuardViolations at CRAP 42 — a finding this branch introduced, so it gets fixed rather than suppressed, same as the catalog generator earlier in the stack. The two conditions are now their own predicates behind a small requirements table, which drops the branch count under the threshold and makes each rule readable on its own line. Same output, same tests. * fix(docs): move the stop effect above ShowcaseWall's early return Rames' changes-requested on `e1a03c63`. The effect I added in the previous commit landed below `if (open) return`, so `ShowcaseWall` called five hooks on the grid render and four once a tile was open. That is a conditional hook: clicking a tile — the component's primary interaction — threw "Rendered fewer hooks than expected". Worth naming why it landed in one of three. `workflow-chooser` and `advanced-path-grid` have no early return, so the same paste position was fine there. `ShowcaseWall` is the only one with a conditional return and it got the same copy. That is the duplication cost this script's own header warns about, showing up in the commit that added the script. **The bespoke gate could not have caught it, and now the generic one does.** `.oxlintrc.json` already loaded the `react` plugin and never excluded `docs/` — only `.prettierignore` does, which is why formatting is not a finding here but linting reaches these files. Naming the two hook rules in an override scoped to `docs/snippets/**` reports this bug directly, and also reports the `compositionSrc` dependency gap from round one that was found by reading. Verified both ways: reintroducing the conditional hook produces `react-hooks(rules-of-hooks)`, and `bunx oxlint .` is clean repo-wide, so nothing lit up in `packages/studio`. **Two holes in the script itself, both from the same review.** It matched whole files while the invariant is per component, so a second unguarded grid in `docs-video.jsx` would have ridden in on `ShowcaseWall`'s guard. It now splits by component. That immediately surfaced the distinction between a component that decides to autoplay and one that forwards its caller's `autoPlay` prop — `DocsVideo` only ever plays because a reader clicked, so it does not owe a preference check. And `readsPreferenceLazily` never tied its halves: any lazy initializer plus the media-query string anywhere in the file passed, which is the original bug satisfying the check written to prevent it. The query now has to sit inside the initializer's own expression. Both holes have tests. fallow is clean at 0 introduced. * fix(scripts): close the two silent gaps in the motion gate Both from Rames' approval pass on #2977, and both found by running these functions rather than reading them. Both fail the same quiet way: a component `autoplays` misses is filtered out before any requirement runs, so the gate reports zero problems instead of a violation. `autoplays` had become narrower than the version it replaced. Excluding the `autoPlay={autoPlay}` passthrough was right, but the replacement only matched `autoPlay={` or `autoPlay` alone on a line, so `<video autoPlay muted />` on one line slipped through. Restored the old breadth. Two things are stripped first rather than one — the passthrough, and the prop's own default in the signature, which is a declaration and not a use. Without the second strip, `DocsVideo` is asked to own a decision it only forwards. `splitComponents` anchored on `^export`, so anything not exported folded into the previous exported component and inherited its guard. Same hole as the whole-file match, narrowed from file scope to non-export scope. The anchor no longer requires `export`. Ten tests now, including his exact examples for both. * docs: remove the live-composition embed and its build apparatus The Introduction no longer carries the embed (removed in #2979), and nothing else used any of this: the 200-line snippet, 26 CSS rules, the bundler that built the single-file HTML for the CDN, its npm script, and the README section explaining how to regenerate it. The Reference Project itself stays — Examples, Developers, and Go further all link to it as the worked example; only the interactive embed of it is gone. This also retires the isolation contract I documented two rounds ago. That comment existed because the embed handed CDN HTML to a same-origin blob; with the embed gone there is no such surface to reason about, which is a better outcome than a comment explaining why it was acceptable. * docs: remove the AgentAction snippet Its only consumer is gone. The Quickstart now shows the agent instruction in a plain fence instead, because this component rendered a Copy button and never displayed the request — a reader copied text they could not read, which is the wrong shape for the one affordance a non-technical visitor depends on. Mintlify fences already carry a copy button and show their contents.
Rames' review on #2978. Two pages left the sidebar without a redirect and without being deleted, so they survived only as direct URLs: `docs/changelog.mdx` and `docs/weekly-updates.mdx`. Not deliberate, and the stack says so — #2979 upgrades `weekly-updates.mdx`, importing DocsVideo and converting four raw <video> tags. You do not invest in a page you meant to retire, and it carries `rss: true`, so it is a subscribable feed. `product-updates.mdx`, which this stack adds to both the nav and the footer, links to `/changelog` three times and `/weekly-updates` once. One of those is advice to read the release archive before upgrading a production workflow. Both are back in the Explore group next to Product updates, which is where a reader looking for "what changed" would go. Worth naming why the verification missed it: the checker walks navigation → file, which is why it correctly reported zero dangling entries. The file → navigation direction — a page that exists, is not in the sidebar, and has no redirect — was never checked, and that is exactly where these two sat. `--check-redirects` on the existing `mint broken-links` step closes the adjacent gap: it resolves every redirect destination, so a future restructure cannot leave a redirect pointing at a page it removed. It does not catch the orphan case above. Also retargets `/guides/pipeline`. It pointed at `/concepts`, which explains how a project is put together; the retired page was a seven-step process. `/workflows` is the closer intent. The old step 3, "Strategy & Messaging", has no successor anywhere in the docs — worth deciding deliberately rather than routing around.
Rewrites the pages that survive the restructure so they lead with what a reader can accomplish, and points them at the sections added in the previous commit. Page set and navigation are unchanged here; only content moves. Keeps the skill count in README. CLAUDE.md's catalog-maintenance rule requires the count to live in README and CLAUDE.md, and both now agree with the 19 directories under skills/.
The four destinations were a single bordered four-column strip, which reads as a tab bar — a control that switches the panel below it — when every cell is a link to GitHub. Replaced with a CardGroup, which is what AGENTS.md prescribes for choosing between destinations, at the two columns it also prescribes.
Rames' second item on #2976, fixed here because this is the line that owns it. It was the only cols={3} in docs/, and all three cards carry body text — the case docs/AGENTS.md names as hyphenating titles mid-word at this content width. The rules file is #2976's deliverable, so it should not ship with the tree beneath it holding the one counter-example.
Removed on request. The demo let a reader change a headline and an accent on a ten-second composition, which undersold the thing the page is arguing for — the Showcase wall above it does more for that in less space. The component and its build apparatus go with it in #2977; nothing else on the page referenced them.
…es link wall Two things a non-technical reader hits that the pages did not help with. **Quickstart made you do it by hand before you could ask.** Install through an interactive picker, choose the right group, restart the agent, then type a prompt — four manual terminal steps before anything happens. The copy-to-agent affordance existed but sat at the bottom of the page, after the step it would have replaced, and it copied only the prompt. It leads now, with the whole thing in one visible block: install, make, open the preview. It uses `hyperframes skills update` rather than the interactive `skills add`, which is the command the README already says agents should run — non-interactive, exactly the core set. The manual steps stay below for anyone who wants to see them. Plain code fence rather than the AgentAction component, deliberately: that component renders a Copy button and never shows the request, so a reader copies something they cannot read. Mintlify fences already carry a copy button and show the text. **Examples had four GitHub cards where one belongs.** Brief, Source, Revision, Checks — two of them pointing into a gate-output report. That is showing homework, not helping someone who came to see finished work. The render stays, with one link into the folder.
ca43dbe to
f720eb7
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Re-reviewed at head f720eb75, now based on main. Approving.
My approval at ca43dbef lapsed because the restack force-pushed the branch, so this is a fresh statement about f720eb75 specifically.
What actually changed since the head I approved
23 of the 24 files are byte-identical to ca43dbef (blob-SHA compare, not a visual diff). One file differs:
docs/guides/feedback.mdx, lines 67-69 — a new paragraph:
That also stops the feedback prompt and takes the install out of any
canary rollout — nothing that reports nothing
is ever picked for a staged release.
That is a correct resolution, and it is the inverse of what went wrong on #2978. Between the old base and main, the base changed exactly one line in these 24 files:
-Disabling telemetry suppresses the CLI feedback prompt and all other CLI usage tracking:
+Disabling telemetry suppresses the CLI feedback prompt, all other CLI usage tracking, and enrolment in any [canary rollout](…) — an install that reports nothing is never picked for a staged rollout:The rewrite deletes the sentence that clause landed in. Dropping the deletion would have lost information main had just added; keeping the sentence would have re-imported prose this page deliberately cut. The resolution does neither — it carries the fact forward, restated in the rewrite's voice, attached to the telemetry disable block where it now belongs. That is the one line of base drift in the whole PR, and it is accounted for.
Why the #2978 failure mode has no surface here
Worth stating as a checked fact rather than a hope. All 24 files are status M — zero deletions, zero additions, and docs.json is untouched. The keep-both-sides hazard is specifically a deletion hazard (a deletion is indistinguishable from "absent" in the other parent), so with no deleted file and no nav edit there is nothing for it to act on. The three-ref invariant confirms it empirically — is any nav page also a redirect source?
ca43dbef(approved head): 307 nav pages, 29 redirects, 0 collisionsf720eb75(this head): 308 / 29, 0origin/main: 308 / 29, 0
Also 0 dangling nav entries across all 308, and 0 duplicates. The 307→308 is contributing/canary-rollouts arriving via main, not anything this PR did.
The claim in the new paragraph, checked at source
packages/cli/src/telemetry/canary.ts:
if (override === undefined && !telemetryActive()) {
return { enabled: false, reason: "telemetry_opt_out" };
}telemetryActive() reads the runtime override then readConfig().telemetryEnabled, which is what npx hyperframes telemetry disable persists. So opting out really does remove the install from cohort selection, and the check sits ahead of evaluateCanary so an opted-out install is never bucketed at all. The one exception is an explicit HF_CANARY_* override, which still wins — but "picked for a staged release" describes automatic selection, and a deliberate local override isn't being picked. The wording holds.
Body vs diff
Two lines of the description no longer match the tree. Neither is a defect in the change:
- "Restores the skill count in
README.md."README.mdis byte-identical (blob2a34005a) across the old base,ca43dbef,main, and this head — this PR does not touch it at any head it has ever had. The outcome the sentence describes is nonetheless true: README says 19,CLAUDE.mdsays 19, and there are exactly 19 directories underskills/, so the catalog-maintenance rule is satisfied. Only the attribution is wrong. Worth correcting so nobody later bisects this PR looking for that edit. - "Stacked on #2978." #2978 has merged; this is now based on
main.
While I was there I re-ran the count-free half of that same rule against this head — docs/guides/skills.mdx, docs/prompting/overview.mdx, and docs/quickstart.mdx all still carry no skill count. All three are byte-identical to the head I approved.
Independently confirmed the two claims under Review notes: 0 dangling navigation entries (308 checked), and 0 broken internal links (90 internal targets across the 24 changed files, each resolving to a page file or a declared redirect source).
CI
This is the first head of this PR that has ever been tested. ca43dbef returned total_count: 0 from the runs API — as a stacked PR it got no workflow run at all, so its quiet check list meant "nothing ran", not "everything passed". Based on main, 7 workflow runs fired and all 7 completed success.
Check runs at f720eb75: 17 success, 27 skipped, 0 failure, 0 pending. Of the 8 required contexts, Semantic PR title and regression are green and the other 6 are skipped by the docs-only path filter. Nothing is outstanding.
mergeStateStatus is BLOCKED on the review gate alone, not on CI.
Approving on my own verification, as a statement about f720eb75 specifically.
Review by Rames Jusso
Third of three commits that replace #2973. Stacked on #2978.
Rewrites the 24 pages that survive the restructure so they lead with what a reader can accomplish, and points them at the sections added in #2978. The page set and the navigation are unchanged here — only content moves, which makes this a homogeneous read: the same kind of edit 24 times.
Review notes
README.md. CLAUDE.md's catalog-maintenance rule requires the count to live in both README and CLAUDE.md; the earlier draft removed it from README while CLAUDE.md still asserted19, so the two contradicted each other. Both now agree with the 19 directories underskills/.