diff --git a/README.md b/README.md index 8d074d503a..40b70a505d 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ For standalone skills (including OpenCode), use: npx skills add heygen-com/hyperframes ``` -> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. +> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Without the picker (a script or a CI job), `npx hyperframes skills update` installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`. > > `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs the skills from the release tag that matches your CLI version, so they match the CLI that runs them. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index e66a8280de..293295ef94 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -55,13 +55,19 @@ system. ### The short way -If you already have a coding agent open in a folder, paste this. It installs the skills, makes the video, and opens -the preview. You only change the URL. +Unless the HyperFrames plugin is installed, install the skills once from a terminal in your project folder, then +open or restart your coding agent there: + +```bash +npx hyperframes skills update +``` + +Paste this into the agent. It makes the video and opens the preview. You only change the URL. ```text Set this folder up for HyperFrames and make me a video. -1. If the HyperFrames plugin is installed, use its bundled skills and launcher. Otherwise run: npx hyperframes skills update +1. If the HyperFrames plugin is installed, use its bundled skills and launcher. If the HyperFrames skills are missing, stop and tell me: I install them with npx hyperframes skills update 2. Then, using /hyperframes, make a 10-second product intro for https://example.com 3. Open the local preview when it is done and tell me the project folder. ``` diff --git a/packages/cli/src/commands/coreSkillContent.test.ts b/packages/cli/src/commands/coreSkillContent.test.ts index cefa8352bb..5c8f5a2c55 100644 --- a/packages/cli/src/commands/coreSkillContent.test.ts +++ b/packages/cli/src/commands/coreSkillContent.test.ts @@ -174,4 +174,19 @@ describe("media treatment routing documentation", () => { expect(template).not.toContain("run_in_background: true"); } }); + + // DeltaVerdict D5: text an agent reads may name the person's skills command but never + // tell the agent to install, update or remove skills, even gated on consent. + it("leaves installing and updating skills to the person in new project instructions", () => { + for (const file of ["AGENTS.md", "CLAUDE.md"]) { + const template = read("packages", "cli", "src", "templates", "_shared", file); + expect(template).toContain("do not run the install yourself"); + expect(template).toContain("For the user:\n> `npx hyperframes skills update `"); + for (const line of template.split("\n").filter((l) => /skills (update|add)/.test(l))) { + expect(line, file).not.toMatch( + /\b(Run|run|Re-run|Install|Update|Repair|Reinstall)\b[^`]*`npx (hyperframes )?skills/, + ); + } + } + }); }); diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index 50c1c59340..f84e07d452 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -180,6 +180,10 @@ describe("hyperframes init flag rename", () => { expect(res.status).toBe(0); expect(res.stdout).not.toContain("Checking AI coding skills"); expect(res.stdout).not.toContain("temporarily ignored"); + // Installing skills is the person's step, so the hint is addressed to them. + expect(res.stdout).toContain( + "For the user: use your HyperFrames plugin, or install standalone skills with:", + ); } finally { rmSync(dir, { recursive: true, force: true }); } diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 0e4d6862dc..f9d6c5acbc 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -690,7 +690,9 @@ async function keepSkillsCurrent(destDir: string): Promise { // "up to date"; the engine already reported what it could verify or // blind-install. Point at the recovery command instead. console.log( - c.dim("Skills freshness unverified — run `npx hyperframes skills update` when online."), + c.dim( + "Skills freshness unverified (offline?). For the user: `npx hyperframes skills update` refreshes them once online.", + ), ); } else if (result.installed.length === 0) { console.log(c.success("AI coding skills are already up to date.")); @@ -977,7 +979,7 @@ export default defineCommand({ console.log(); if (skipSkills) { console.log( - ` ${c.accent("1.")} Use your HyperFrames plugin, or install standalone skills:`, + ` ${c.accent("1.")} For the user: use your HyperFrames plugin, or install standalone skills with:`, ); console.log(` ${c.accent("npx hyperframes skills update")}`); } else { diff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.ts index 1237b6b447..9dc0e64f73 100644 --- a/packages/cli/src/commands/skills.ts +++ b/packages/cli/src/commands/skills.ts @@ -380,7 +380,7 @@ export async function updateSkills( // reinstate the 26-skill sweep this path exists to avoid. clack.log.warn( c.warn( - "Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.", + "Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. For the user: `hyperframes skills` installs the full set once online.", ), ); } @@ -550,7 +550,7 @@ function renderCheck(result: SkillsCheckResult): void { if (!result.location) { console.log(` ${c.dim("No HyperFrames skills found in the usual locations.")}`); - console.log(` ${c.accent("Install: npx hyperframes skills")}`); + console.log(` ${c.accent("For the user: npx hyperframes skills installs them")}`); console.log(); return; } @@ -577,14 +577,14 @@ function renderCheck(result: SkillsCheckResult): void { printSkillSection( result, "missing", - "Available on demand (install with `hyperframes skills update `):", + "Available on demand (`hyperframes skills update ` installs one):", "◦", c.dim, (s) => !isCoreSkill(s.name), ); console.log(); if (result.updateAvailable) { - console.log(` ${c.accent("Update: npx hyperframes skills update")}`); + console.log(` ${c.accent("For the user: npx hyperframes skills update refreshes them")}`); } else { console.log(` ${c.success("◇")} ${c.success("Installed skills are up to date")}`); } diff --git a/packages/cli/src/commands/update.test.ts b/packages/cli/src/commands/update.test.ts index 2eb4257e5a..6702191b49 100644 --- a/packages/cli/src/commands/update.test.ts +++ b/packages/cli/src/commands/update.test.ts @@ -202,6 +202,14 @@ describe("hyperframes update --check", () => { expect(text).not.toContain("latest"); }); + it("names both commands for the person, not as a bare Run: line", async () => { + await runUpdate(ENTRIES.npm, { check: true }); + const text = stdout.join("\n"); + expect(text).toContain("For the user: run npm install -g hyperframes@0.9.8"); + expect(text).toContain("For the user: run hyperframes update"); + expect(text).not.toMatch(/\bRun:/); + }); + it.each([ ["npm", ENTRIES.npm, "npm install -g hyperframes@0.9.8"], ["pnpm", ENTRIES.pnpm, "pnpm add -g hyperframes@0.9.8"], diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts index ff57d4776a..efd1786cfe 100644 --- a/packages/cli/src/commands/update.ts +++ b/packages/cli/src/commands/update.ts @@ -153,10 +153,12 @@ function printCheck(cli: CliReport, skills: SkillsReport): void { : c.success(`${cli.current} (${cli.checkedAt ? "latest" : "npm registry not reached"})`); console.log(` ${c.bold("CLI".padEnd(8))}${version}`); console.log(` ${" ".repeat(8)}${c.dim(where)}`); - if (cli.command) console.log(` ${" ".repeat(8)}${c.accent(`Run: ${cli.command}`)}`); + if (cli.command) { + console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${cli.command}`)}`); + } console.log(` ${c.bold("Skills".padEnd(8))}${skillsLine(skills)}`); if (skills.status === "checked" && skills.command) { - console.log(` ${" ".repeat(8)}${c.accent(`Run: ${skills.command}`)}`); + console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${skills.command}`)}`); } console.log(); } diff --git a/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs b/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs index 6522da28a9..f30edce9e3 100644 --- a/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs +++ b/packages/cli/src/media-use/lib/bundled-sfx-provider.mjs @@ -27,7 +27,7 @@ export const BUNDLED_SFX_RECOVERY_COMMAND = "npx hyperframes skills update media export class BundledSfxAssetsError extends Error { constructor(health) { super( - `bundled SFX assets are missing or incomplete (${health.detail}). Repair the installed media-use skill: ${health.fix}`, + `bundled SFX assets are missing or incomplete (${health.detail}). For the user: \`${health.fix}\` repairs the installed media-use skill.`, ); this.name = "BundledSfxAssetsError"; this.code = health.code; diff --git a/packages/cli/src/media-use/resolve.mjs b/packages/cli/src/media-use/resolve.mjs index 3bb82c299a..7eb0b573b5 100644 --- a/packages/cli/src/media-use/resolve.mjs +++ b/packages/cli/src/media-use/resolve.mjs @@ -56,7 +56,11 @@ import { flushHeygenFailureTracking, versionLessThan, } from "./lib/heygen-cli.mjs"; -import { BundledSfxAssetsError, inspectBundledSfxAssets } from "./lib/bundled-sfx-provider.mjs"; +import { + BUNDLED_SFX_RECOVERY_COMMAND, + BundledSfxAssetsError, + inspectBundledSfxAssets, +} from "./lib/bundled-sfx-provider.mjs"; import { OPENVERSE_SFX_PROVIDER } from "./lib/sfx-provider.mjs"; import { writeSfxCredit } from "./lib/openverse.mjs"; import { @@ -1150,7 +1154,13 @@ function printDoctor(checks) { const freePath = heygenChecks.has(check.name) ? " — free-usage path: bgm/image/voice/avatar-video" : ""; - const fix = check.ok || !check.fix ? "" : ` — fix: ${check.fix}`; + // Repairing a skill is the person's step, so that fix is addressed to them, not to the agent. + const fix = + check.ok || !check.fix + ? "" + : check.fix === BUNDLED_SFX_RECOVERY_COMMAND + ? ` — For the user: \`${check.fix}\` repairs it` + : ` — fix: ${check.fix}`; console.log(`${prefix} ${check.detail}${freePath}${fix}`); } } diff --git a/packages/cli/src/media-use/resolve.test.mjs b/packages/cli/src/media-use/resolve.test.mjs index 14557d7746..9c44aebcad 100644 --- a/packages/cli/src/media-use/resolve.test.mjs +++ b/packages/cli/src/media-use/resolve.test.mjs @@ -280,6 +280,23 @@ test("missing bundled SFX install returns a typed recovery command", () => { assert.equal(parsed.fix, "npx hyperframes skills update media-use"); assert.match(parsed.error, /bundled SFX assets are missing or incomplete/); assert.match(parsed.error, /manifest not found/); + // Repairing a skill is the person's step: the message names it for them, not the agent. + assert.match(parsed.error, /For the user: `npx hyperframes skills update media-use` repairs/); + assert.doesNotMatch(parsed.error, /Repair the installed/); + cleanup(); +}); + +test("--doctor addresses the bundled SFX repair to the person", () => { + setup(); + const result = spawnResolve(["--doctor"], { + env: { + HOME: tmp, + PATH: tmp, + HYPERFRAMES_MEDIA_USE_SFX_DIR: join(tmp, "missing-sfx-library"), + }, + }); + assert.match(result.stdout, /For the user: `npx hyperframes skills update media-use` repairs it/); + assert.doesNotMatch(result.stdout, /fix: npx hyperframes skills/); cleanup(); }); diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index c89627247c..45ab10842b 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -25,13 +25,14 @@ MP4. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind). > **Using a HyperFrames plugin?** Load skills from that installed bundle and follow -> its `hyperframes/references/plugin-installation.md` execution rules. Update via -> the plugin manager, not the standalone commands below. +> its `hyperframes/references/plugin-installation.md` execution rules. The person updates +> the plugin through its plugin manager; the standalone commands below do not apply. > -> **Standalone skill missing or stale?** Run `npx hyperframes skills update ` to install/refresh -> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus -> everything already installed — neither pulls the full set. Restart the agent session so -> newly installed skills load. +> **Standalone skill missing or stale?** Installing and updating skills is the person's step: +> tell them which skill is missing or stale, and do not run the install yourself. For the user: +> `npx hyperframes skills update ` installs/refreshes that skill, and bare +> `npx hyperframes skills update` refreshes the core set plus everything already installed — +> neither pulls the full set. Newly installed skills load in a new agent session. ## Commands diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index c89627247c..45ab10842b 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -25,13 +25,14 @@ MP4. > **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind). > **Using a HyperFrames plugin?** Load skills from that installed bundle and follow -> its `hyperframes/references/plugin-installation.md` execution rules. Update via -> the plugin manager, not the standalone commands below. +> its `hyperframes/references/plugin-installation.md` execution rules. The person updates +> the plugin through its plugin manager; the standalone commands below do not apply. > -> **Standalone skill missing or stale?** Run `npx hyperframes skills update ` to install/refresh -> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus -> everything already installed — neither pulls the full set. Restart the agent session so -> newly installed skills load. +> **Standalone skill missing or stale?** Installing and updating skills is the person's step: +> tell them which skill is missing or stale, and do not run the install yourself. For the user: +> `npx hyperframes skills update ` installs/refreshes that skill, and bare +> `npx hyperframes skills update` refreshes the core set plus everything already installed — +> neither pulls the full set. Newly installed skills load in a new agent session. ## Commands diff --git a/packages/cli/src/utils/skillsUpdateCheck.test.ts b/packages/cli/src/utils/skillsUpdateCheck.test.ts index 4d73b3cc2f..c279fa618b 100644 --- a/packages/cli/src/utils/skillsUpdateCheck.test.ts +++ b/packages/cli/src/utils/skillsUpdateCheck.test.ts @@ -191,6 +191,9 @@ describe("skillsUpdateCheck", () => { gate.noTty = true; const text = await noticeTextFor({ skillsOutdatedCount: 2, skillsMissingCount: 1 }); expect(text).toContain("3 HyperFrames skills out of date or missing"); + // The agent reads stderr too: the command is the person's to run (DeltaVerdict D5). + expect(text).toContain("For the user: npx hyperframes skills update"); + expect(text).not.toMatch(/\bRun:/); }); it("prints at most once a day per project", async () => { diff --git a/packages/cli/src/utils/skillsUpdateCheck.ts b/packages/cli/src/utils/skillsUpdateCheck.ts index c9f5b2af55..01d9b110b1 100644 --- a/packages/cli/src/utils/skillsUpdateCheck.ts +++ b/packages/cli/src/utils/skillsUpdateCheck.ts @@ -113,7 +113,7 @@ function skillsNoticeText(meta: SkillsUpdateMeta): string | null { const total = meta.outdated + meta.missing; if (total < 1) return null; const noun = total === 1 ? "skill" : "skills"; - return `\n ${total} HyperFrames ${noun} out of date or missing.\n Run: npx hyperframes skills update\n\n`; + return `\n ${total} HyperFrames ${noun} out of date or missing.\n For the user: npx hyperframes skills update refreshes them.\n\n`; } /**