[Vitozhu04]

Follow-up to #7013. The CLI and agents now notice an outdated CLI or outdated skills, and hyperframes update --check reports both in one call.

What

• Check interval 24h → 2h for the CLI update check and the skills check. The skills nudge is still printed at most once a day per project (its own 24h window), and the 1h failure backoff in launchBackgroundChecks is unchanged.
• Stale cache. A cached npm latest that is older than the running CLI is now due for a recheck on the next run. Before this, it waited out the full interval; fix(cli): the latest version in _meta is never older than the running CLI #7049 already hid that value from _meta. _meta gains checkedAt. Note: fix(cli): the latest version in _meta is never older than the running CLI #7049 chose to keep the daily cadence in this case, and this PR deliberately changes that. The 1h attempt backoff still caps how often the check retries.
• Agents see outdated skills in _meta. Every --json output now carries _meta.skillsOutdated: <n>, read from the cached background skills check, so the main process makes no network call. The cache is stamped with the CLI version whose release tag it was compared against (skillsCheckedVersion). A count taken under another version is left out and rechecked. A count more than 24h old is also left out (see the Genesis fix below). Unattended runs still print nothing on stderr for outdated-only skills (fix(cli): add help [cmd], suggest the closest command or flag, and quiet the nags #6621). HYPERFRAMES_SKIP_SKILLS=1 omits the field.
• New hyperframes update [--check] [--yes] [--json]. It runs one forced check of the CLI (npm, past the cache) and of the skills (manifest at the CLI's release tag).
  • --check only reports.
  • Without --check, it upgrades the CLI through the same plan and argv as upgrade --yes: upgradePlan is now shared, and the installer's output goes to stderr so a --json stdout stays one object. It then runs updateSkills at the release tag of the CLI that is now installed. For npm, pnpm and bun that is the exact version they pinned. For Homebrew it is the version the linked binary reports after brew upgrade: the outcome is unchanged when the formula has not moved, and unverified when the version can't be read. In both cases the skills stay at this CLI's tag.
  • An unattended run without --yes exits 2, like upgrade.
  • Under a plugin (HYPERFRAMES_PLUGIN_VERSION, set by plugin-cli.mjs), update reports but refuses to install (exit 1, plugin_managed), and skills are never touched.
  • update is excluded from the background-check/notice block, like upgrade and skills.
• doctor names the running binary and its path: npm/pnpm/bun global, Homebrew, project node_modules, npx/bunx, workspace link, or plugin. Its update hint is the command for that install, for example npx hyperframes@latest for npx and project-local runs (it was hyperframes upgrade for everyone). upgrade's fallback for unmanaged installs also prints npx hyperframes@latest. bunx's bunx-*/node_modules/… layout is now recognized as ephemeral (it used to read as unknown).
• _meta.updateNotice: the agent relays, the person updates. When the CLI or the skills are behind, a --json result carries one sentence addressed to the person, e.g. "For the user: HyperFrames CLI 0.9.8 is available (this run is 0.9.6), and 3 installed HyperFrames skills are out of date. To update both, run: npx hyperframes update".
  • The command is npx hyperframes update (npx hyperframes@latest update from an npx run, whose cache can hold the old CLI). A Homebrew install names brew upgrade hyperframes, or its own hyperframes update when the skills are behind too, since an npx copy would put the skills at npm's tag rather than brew's.
  • The skills half is left out when no skill is behind or under HYPERFRAMES_SKIP_SKILLS=1. The whole notice is left out under CI, dev, HYPERFRAMES_NO_UPDATE_CHECK=1 and an agent plugin (HYPERFRAMES_PLUGIN_VERSION), and from update's own output.
  • It appears at most once a day per project, through the same daily claim as the stderr skills nudge under its own key (update-notice.json; claimDailyNotice moved to utils/dailyNotice.ts). updateAvailable, latestVersion, checkedAt and the skills counts stay on every result.
• _meta.skillsMissing: core skills not installed, next to skillsOutdated, under the same rules (this CLI version's tag, dropped after 24h, absent under HYPERFRAMES_SKIP_SKILLS=1).
• One line in skills/hyperframes-cli/SKILL.md, naming no command: "A --json result may carry _meta.updateNotice: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide." Why: no skill text tells the agent to install, update or remove skills, even gated on consent. Skill graders (e.g. DeltaVerdict D5) fail any such line as self-modification of the agent's other skills, and they read skill source, not CLI output. The command lives in the CLI's notice, for the person to run. The Upkeep row is unchanged. The hyperframes-cli size budget in scripts/check-core-skills.mjs goes from 7168 to 7424 B for this line, and skills-manifest.json is regenerated.
• update wording. The confirmation hint (an agent run without --yes) now reads "Ask the person first; pass --yes only when they asked to update. --check only reports." update --check's skills command is npx hyperframes update, the same command _meta.updateNotice names, so this PR recommends one command for the job. skills update still works.
• plugin-cli.mjs is unchanged: it still pins the CLI and disables the nudges.

Genesis review fixes (at fadf861).

1. brew upgrade installs the formula's version (which trails npm) and exits 0 on a no-op. update --yes now reads the installed version back and puts the skills at that tag. It no longer claims "upgraded to ".
2. The nit: I chose to drop the count rather than add a checkedAt. _meta.skillsOutdated is dropped once the cached count is over 24h old, so it can't freeze when HYPERFRAMES_NO_UPDATE_CHECK (or CI/dev) stops the background checks.

4 new tests fail at fadf861: brew stays behind npm, brew moves to an in-between version, brew's version can't be read, and a 25h-old count. A 23h-old count is still reported; that guard passes on both.

How tested

Unit tests (vitest, targeted files only, 18 files, 354 pass on the branch). 52 new or changed tests fail on main (they were run against base sources with the branch tests):

Item	Fail on main	Where
4 · 2h interval	3	updateCheck.test, skillsUpdateCheck.test, backgroundChecks.test (plus a once-a-day-per-project guard that passes on both)
5 · stale cache + checkedAt	2	updateCheck.test (the #7049 test now expects due=true)
6 · _meta.skillsOutdated	5	updateCheck.test (count with no network call, zero), skillsUpdateCheck.test (version stamp, other-version cache, pre-stamp cache)
7 · update	21	update.test.ts, per channel through the real installer detection, upgrade plan and updateSkills; only spawn, config, manifest and registry are stubbed
8 · doctor + channels	21	doctor.install.test.ts (10), installerDetection.test.ts runningInstall (11)

Every install channel is covered in update.test.ts (--check and the install path), and in installerDetection.test.ts / doctor.install.test.ts: npm -g, pnpm, bun, Homebrew, npx, bunx, project-local, workspace and plugin. cli.agentMode.test.ts adds update to the "refuses to prompt, names --yes, exits 2" case (passes locally with bun). Lint (oxlint/oxfmt), fallow, the comment ratchet and citations, test reachability and the docs command check all pass.

updateNotice / skillsMissing (at 609b89e). 14 new tests in updateCheck.test.ts. They cover the full CLI+skills sentence; missing core skills in the skills half; a skills-only notice; the skills half dropped when none is behind and under HYPERFRAMES_SKIP_SKILLS; brew (brew upgrade hyperframes, and hyperframes update with skills behind); npx (@latest); absence under the update-check opt-out, CI, the plugin env, nothing behind, and { updateNotice: false }; once a day per project with the numeric fields still present on the second result and the notice back the next day; and a daily claim kept apart from the skills nudge's. skillsMissing has 5: reported, dropped when over a day old, taken under another version, not a count, or under HYPERFRAMES_SKIP_SKILLS. Targeted runs: updateCheck, skillsUpdateCheck, update, backgroundChecks, updateCheck.stalepin, autoUpdate.invocation, installerDetection, doctor.install (8 files, 172 pass), plus the update cases of cli.agentMode.test.ts (9 pass). check-core-skills, lint-skills, check-skill-mirror, gen-skills-manifest --check, test reachability and oxlint/oxfmt on the changed files pass.

Sandbox journeys, main vs branch. Each run used an isolated HOME and npm prefix/cache, HYPERFRAMES_NO_TELEMETRY=1, and env -i. Built bundles were laid out at each channel's real path, and two journeys used the real npm/npx installs.

Journey	main (b2acef5)	branch
J1: cache checked 10 min ago says latest 0.9.6, running 0.9.8	no recheck; _meta never gets latest	background recheck on run 1; run 2 _meta = latest 0.9.8 + checkedAt
J2: agent info --json, skills at v0.9.6 under CLI 0.9.8	cache knows 2 outdated, _meta doesn't say; stderr empty	_meta.skillsOutdated: 2; stderr empty (a missing core skill still prints)
J3: update --check --json	unknown command (2 calls needed)	CLI + skills in one object (0.9.6→0.9.8 / ref v0.9.6; or 2 outdated at v0.9.8)
J3 real: update --yes --json on a real npm i -g hyperframes@0.9.6	n/a	npm installed 0.9.8, then skills cloned at @ v0.9.8 (hyperframes-cli, media-use); stdout one JSON object
J4: Homebrew 0.9.6, attended, latest 0.9.8	notice brew upgrade hyperframes, no spawn	same; update --check names brew; explicit update --yes calls brew
J4: plugin env	no background checks	same; update --check reports plugin, skills skipped; update --yes exit 1 plugin_managed
J5: doctor npm-global / npx / project	hint hyperframes upgrade for all, no path	CLI binary line with channel + path; hint npm install -g hyperframes@0.9.8 / npx hyperframes@latest (also via a real npx hyperframes@0.9.6)

Please don't add to the merge queue; merge after owner OK.

— wanbi

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 4, 2026, 8:36 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 267 (base branch 267), smooth 115 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

• seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
• seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
• seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

Unstable (2)

• seqrotatenudge-none-pct-r0-root-z100: tracking 0.03, pressJump 0, drop 0, reload 3.03, render 0.04, renderKey -, undo false, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true
• seqrepeat-none-center-r0-root-z100: tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: APPROVE · 0 blocker · 1 important · 1 nit · head fadf861

No blockers. Required CI is green on this head. The Homebrew skills-tag issue below is worth fixing before merge, because it brings back the CLI/skills mismatch that #7013 closed. Details are inline.

Scope

Read end-to-end: update.ts, upgrade.ts (upgradePlan / upgradeRunningCli), installerDetection.ts, updateCheck.ts, skillsUpdateCheck.ts, skills.ts, doctor.ts, and the cli.ts exclusion list. Checked against backgroundChecks.ts (the 1h attempt backoff also caps the new always-due case for builds newer than npm latest) and prompts.confirmationRequired (it throws, so an unattended run without --yes cannot fall through to an install). Skimmed the tests and docs. There were no prior reviews.

— Genesis

[heygengenesis]

Verdict: APPROVE · 2 resolved, 0 open, 0 new · fadf861 → 00c30fb

— Genesis

[heygengenesis]

Verdict: APPROVE · 0 open, 0 new · 00c30fb → 92d59ab (rebuilt on main)

Scope

Re-read the whole diff on the new base, including how update's skills check works alongside #7120's write-destination change. Wording check: _meta.updateNotice is addressed "For the user:", and the SKILL.md line leaves the decision to the person. If an agent runs the command anyway, update stops without --yes (exit 2) and says "Ask the person first", before it touches the network or installs anything. CI run 41770055641 is green at this head.

— Genesis

[heygengenesis]

Verdict: APPROVE · 0 open, 0 new · 92d59ab → 8120874

— Genesis