@@ -16,7 +16,7 @@ npx skills add heygen-com/hyperframes --skill <name>  # a named match installs r
 
 > **Warning:** Never run `npx skills add ... --all` from inside a HyperFrames checkout: it selects the OpenClaw target, whose `skills/` directory is the repo's own `skills/`, and removes each existing `skills/<name>` destination before linking. A fresh clone restores tracked source, but uncommitted work under `skills/` does not recover. Run it from an empty directory or from your own project root. This happens regardless of `metadata.internal`.
 
-`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs from the current `main`; prefer it when freshness matters.
+`skills add` resolves the skills.sh registry blob, which can lag `main` by hours, so a freshly added skill may be a little behind. `npx hyperframes skills update` installs the skills from the release tag that matches the CLI version, so they match the CLI that runs them.
 
 Make any video by asking for it; the `/hyperframes` skill carries the render contract and the references (format, runtimes, motion, look, captions, film, overlays, storyboards). The skills carry knowledge, not process. The README skills section mirrors this list; keep them in sync (see "Skill catalog maintenance" below).
 
 
@@ -66,7 +66,7 @@ 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`.
 >
-> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill.
+> `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.
 
 Run project-local installs from your video project's directory. From a HyperFrames
 checkout, use `npx hyperframes skills update` for a global install instead: a
 
@@ -107,10 +107,12 @@ their final line, on stderr.
 `2` means the command line itself is wrong: an unknown command or flag, or a
 missing or invalid value.
 
-**Version notices.** An owned install (npm, bun, pnpm, brew) updates itself
+**Version notices.** An owned install (npm, bun, pnpm) updates itself
 quietly in the background and prints one line on the next run:
-`hyperframes auto-updated to v0.1.5`. It never crosses a major version. Anywhere
-it cannot install — `npx`, an unknown installer — you get a notice instead:
+`hyperframes auto-updated to v0.1.5`. It never crosses a major version (before
+1.0, a minor version: 0.8 to 0.9 is a notice, not an install). Anywhere
+it cannot install — Homebrew (run `brew upgrade hyperframes` yourself), `npx`, an
+unknown installer — you get a notice instead:
 
 ```
   Update available: 0.1.4 → 0.1.5
@@ -2193,7 +2195,9 @@ Set `HYPERFRAMES_SKIP_SKILLS=1` when something else manages the skills (CI, test
 or an install pinned to one commit). `skills update` and bare `skills` then exit 0
 with a one-line notice and leave the installed skills unchanged.
 
-The CLI installs from the current HyperFrames GitHub source and links the global
+The CLI installs the skills from the HyperFrames release tag that matches its own
+version (`v<version>`), and `check` compares against that same tag, so the skills
+match the CLI that runs them; a development build uses `main`. It links the global
 bundles into whichever compatible agents it finds. After scaffolding, `init`
 installs the core set if it is missing. It never refreshes or removes a skill you already have; run `skills update` for that.
 
 
@@ -210,7 +210,7 @@ describe("hyperframes skills", () => {
     const first = state.spawnCalls[0];
     expect(first).toBeDefined();
     expect(first!.command).toBe("npx");
-    expect(first!.args).toContain("skills");
+    expect(first!.args).toContain("skills@1.5.13");
     expect(first!.args).toContain("add");
     expect(first!.env?.GIT_CLONE_PROTECTION_ACTIVE).toBe("0");
     // --full-depth clones the repo; skip LFS so we don't drag in unrelated blobs.
@@ -223,7 +223,7 @@ describe("hyperframes skills", () => {
       "npx",
       ["--version"],
       [
-        "skills",
+        "skills@1.5.13",
         "add",
         "https://github.com/heygen-com/hyperframes",
         "--skill",
@@ -240,7 +240,7 @@ describe("hyperframes skills", () => {
       "npx",
       ["--version"],
       [
-        "skills",
+        "skills@1.5.13",
         "add",
         "https://github.com/heygen-com/hyperframes",
         "--skill",
@@ -261,7 +261,7 @@ describe("hyperframes skills", () => {
         "/s",
         "/c",
         "npx.cmd",
-        "skills",
+        "skills@1.5.13",
         "add",
         "https://github.com/heygen-com/hyperframes",
         "--skill",
@@ -322,6 +322,25 @@ describe("hyperframes skills", () => {
     expect(agentValue).not.toBe("*");
   });
 
+  // The install uses the ref the check compared against (the CLI's release
+  // tag), resolved once, through the pinned skills CLI.
+  it("skills update installs at the ref its check read, through the pinned skills CLI", async () => {
+    setPlatform("linux");
+    const { checkSkills } = await import("../utils/skillsManifest.js");
+    vi.mocked(checkSkills).mockResolvedValueOnce({ ...DEFAULT_CHECK, ref: "v0.9.3" } as never);
+
+    await runSkillsUpdate();
+
+    expect(await commandExitCode()).toBe(0);
+    const args = state.spawnCalls[0]?.args ?? [];
+    expect(args.slice(0, 3)).toEqual([
+      "[email protected]",
+      "add",
+      "https://github.com/heygen-com/hyperframes#v0.9.3",
+    ]);
+    expect(args).toContain("--full-depth");
+  });
+
   it("skills update refreshes an outdated installed workflow (but never expands)", async () => {
     setPlatform("linux");
     const { checkSkills } = await import("../utils/skillsManifest.js");
 
@@ -5,6 +5,7 @@ import * as clack from "../ui/prompts.js";
 import { c } from "../ui/colors.js";
 import { diag } from "../ui/diagnostics.js";
 import { buildNpxCommand } from "../utils/npxCommand.js";
+import { VERSION } from "../version.js";
 import { withMeta } from "../utils/updateCheck.js";
 import {
   checkSkills,
@@ -14,6 +15,7 @@ import {
   presentSkills,
   RETIRED_SKILLS,
   retiredSkillNotice,
+  cliReleaseTag,
   type SkillDiff,
   type SkillsCheckResult,
 } from "../utils/skillsManifest.js";
@@ -105,7 +107,7 @@ function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
 // Why --copy: real files (not the upstream symlink default, which re-serialises
 // each SKILL.md's frontmatter) so an installed bundle byte-matches the published
 // manifest and `skills check` reads it as current. Why --full-depth: it forces a
-// full `git clone` of HEAD; without it even a full-URL `skills add` fetches the
+// full `git clone` of the requested ref; without it even a full-URL `skills add` fetches the
 // skills.sh registry blob, which lags GitHub main by hours, so a fresh install
 // would read as several skills "outdated" (verified: blob → ~9 outdated;
 // --full-depth → all current).
@@ -129,13 +131,16 @@ function skillSelectionArgs(selection: SkillSelection): string[] {
   return names.flatMap((name) => ["--skill", name]);
 }
 
+// Pinned: a bare `npx skills` runs whatever upstream published last.
+const SKILLS_CLI = "[email protected]";
+
 function runSkillsAdd(
   source: string,
   selection: SkillSelection,
   opts: { cwd?: string } = {},
 ): Promise<void> {
   return spawnNpx(
-    ["skills", "add", source, ...skillSelectionArgs(selection), ...GLOBAL_INSTALL_ARGS_TAIL],
+    [SKILLS_CLI, "add", source, ...skillSelectionArgs(selection), ...GLOBAL_INSTALL_ARGS_TAIL],
     opts,
   );
 }
@@ -147,10 +152,9 @@ function runSkillsAdd(
 // on the Windows `cmd.exe` spawn path, where arg escaping is fragile.
 const PLAIN_SKILL_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
 
-// Use the full GitHub URL (not the `owner/repo` slug) as the clone source. The
-// freshness comes from --full-depth (see GLOBAL_INSTALL_ARGS_TAIL), which clones the
-// repo at latest `main`; the URL just names what to clone. Our freshness check
-// resolves "latest" straight from GitHub too, so install and check agree.
+// Use the full GitHub URL (not the `owner/repo` slug) as the clone source.
+// --full-depth (see GLOBAL_INSTALL_ARGS_TAIL) clones it at `#<ref>`: the ref the
+// check read its manifest at (this CLI's release tag), so check and install agree.
 const SOURCES = [{ name: "HyperFrames", url: "https://github.com/heygen-com/hyperframes" }];
 
 // Fan HyperFrames' own skills out to every other installed agent. Scope by the
@@ -242,21 +246,22 @@ function sanitizeSelection(selection: SkillSelection): SkillSelection | null {
 
 async function installSkills(
   selection: SkillSelection,
-  opts: { cwd?: string; strict?: boolean } = {},
+  opts: { cwd?: string; strict?: boolean; ref: string },
 ): Promise<void> {
   const safeSelection = sanitizeSelection(selection);
   if (safeSelection === null) return;
 
   if (!skillsToolingReady(opts.strict ?? false)) return;
 
+  const { ref } = opts;
   // stderr (via diag): installSkills runs on the `skills update --json` path before
   // its JSON envelope is written to stdout — progress here must not corrupt it.
   for (const source of SOURCES) {
     diag.notice();
     diag.notice(c.bold(`Installing ${source.name} skills...`));
     diag.notice();
     try {
-      await runSkillsAdd(source.url, safeSelection, opts);
+      await runSkillsAdd(ref === "main" ? source.url : `${source.url}#${ref}`, safeSelection, opts);
     } catch (err) {
       if (opts.strict) throw err instanceof Error ? err : new Error(String(err));
       // warn, not notice: this is a non-fatal skip after a caught install error.
@@ -341,7 +346,7 @@ export async function updateSkills(
     // that no longer exists, and verifyInstalled would strict-throw on a
     // "failure" that was never real. Resolving canonically means a retired
     // skill simply never appears as a target in the first place.
-    check = await checkSkills({ cwd: opts.cwd, canonical: true });
+    check = await checkSkills({ cwd: opts.cwd, canonical: true, cliVersion: VERSION });
   } catch (err) {
     // A *malformed* canonical manifest (the server was reached, but served a
     // bad shape) is otherwise indistinguishable from being offline — both fall
@@ -402,7 +407,7 @@ export async function updateSkills(
   };
 
   if (toInstall.length > 0) {
-    await installSkills(result.installed, { cwd: opts.cwd, strict });
+    await installSkills(result.installed, { cwd: opts.cwd, strict, ref: check.ref ?? "main" });
     verifyInstalled(result.installed, { strict, cwd: opts.cwd });
   }
   // The install (or the fresh canonical check confirming everything current)
@@ -479,7 +484,11 @@ async function updateSkillsOffline(
   );
 
   if (absent.length > 0) {
-    await installSkills(absent, { cwd: opts.cwd, strict: opts.strict });
+    await installSkills(absent, {
+      cwd: opts.cwd,
+      strict: opts.strict,
+      ref: cliReleaseTag(VERSION) ?? "main",
+    });
     verifyInstalled(absent, opts);
   }
   return {
@@ -572,6 +581,7 @@ const checkCommand = defineCommand({
     const result = await checkSkills({
       dir: args.dir,
       source: args.source,
+      cliVersion: VERSION,
     });
 
     if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
 
@@ -0,0 +1,108 @@
+import { afterEach, expect, it, vi } from "vitest";
+
+// Drives scheduleBackgroundInstall through the real installer detection, argv helper and installer
+// script; only the entry path, the settings file and spawn itself are stubbed.
+const BREW_ENTRY =
+  "/opt/homebrew/Cellar/hyperframes/0.8.231/libexec/lib/node_modules/hyperframes/dist/cli.js";
+const NPM_ENTRY = "/usr/local/lib/node_modules/hyperframes/dist/cli.js";
+
+const originalArgv = [...process.argv];
+const originalEnv = { ...process.env };
+const originalTTY = process.stderr.isTTY;
+const originalWrite = process.stderr.write.bind(process.stderr);
+
+afterEach(() => {
+  process.argv = [...originalArgv];
+  process.env = { ...originalEnv };
+  Object.defineProperty(process.stderr, "isTTY", { value: originalTTY, configurable: true });
+  process.stderr.write = originalWrite;
+  vi.resetModules();
+  vi.doUnmock("../telemetry/config.js");
+  vi.doUnmock("../version.js");
+  vi.doUnmock("./env.js");
+  vi.doUnmock("./attendedTerminal.js");
+  vi.doUnmock("node:child_process");
+  vi.doUnmock("node:fs");
+});
+
+/** A 0.8.231 install at `entry` whose cached latest is the allowed patch 0.8.232. */
+async function patchAvailableAt(entry: string) {
+  vi.resetModules();
+  const config: Record<string, unknown> = { latestVersion: "0.8.232" };
+  vi.doMock("../telemetry/config.js", () => ({
+    readConfig: () => ({ ...config }),
+    readConfigFresh: () => ({ ...config }),
+    writeConfig: (next: Record<string, unknown>) => {
+      for (const key of Object.keys(config)) delete config[key];
+      Object.assign(config, next);
+      return true;
+    },
+  }));
+  vi.doMock("../version.js", async (importOriginal) => ({
+    ...(await importOriginal<typeof import("../version.js")>()),
+    VERSION: "0.8.231",
+  }));
+  vi.doMock("./env.js", () => ({ isDevMode: () => false }));
+  vi.doMock("./attendedTerminal.js", async (importOriginal) => ({
+    ...(await importOriginal<typeof import("./attendedTerminal.js")>()),
+    isUnattended: () => false,
+  }));
+  const spawn = vi.fn((_bin: string, _args: readonly string[]) => ({ pid: 42, unref: () => {} }));
+  vi.doMock("node:child_process", async (importOriginal) => ({
+    ...(await importOriginal<typeof import("node:child_process")>()),
+    spawn,
+  }));
+  vi.doMock("node:fs", async (importOriginal) => ({
+    ...(await importOriginal<typeof import("node:fs")>()),
+    mkdirSync: () => {},
+    openSync: () => 99,
+    appendFileSync: () => {},
+  }));
+
+  process.argv = [process.argv[0] ?? "node", entry];
+  for (const name of ["CI", "HYPERFRAMES_NO_AUTO_INSTALL", "HYPERFRAMES_NO_UPDATE_CHECK"]) {
+    delete process.env[name];
+  }
+  Object.defineProperty(process.stderr, "isTTY", { value: true, configurable: true });
+  const stderr: string[] = [];
+  process.stderr.write = ((chunk: unknown) => {
+    stderr.push(String(chunk));
+    return true;
+  }) as typeof process.stderr.write;
+
+  const { scheduleBackgroundInstall } = await import("./autoUpdate.js");
+  const { printUpdateNotice } = await import("./updateCheck.js");
+  const scheduled = scheduleBackgroundInstall("0.8.232", "0.8.231");
+  printUpdateNotice();
+  return { scheduled, spawn, config, notice: stderr.join("") };
+}
+
+/** The bin and argv the spawned installer script would execFile. */
+function installerArgv(spawn: { mock: { calls: [string, readonly string[]][] } }) {
+  const script = spawn.mock.calls[0]?.[1][1] ?? "";
+  const bin = /const BIN = (.*);/.exec(script)?.[1];
+  const args = /const ARGS = (.*);/.exec(script)?.[1];
+  return { bin: bin && JSON.parse(bin), args: args && JSON.parse(args) };
+}
+
+it("never launches an upgrade on Homebrew, whose upgrade cannot be held to the patch", async () => {
+  const { scheduled, spawn, config, notice } = await patchAvailableAt(BREW_ENTRY);
+
+  expect(scheduled).toBe(false);
+  expect(spawn).not.toHaveBeenCalled();
+  expect(config["pendingUpdate"]).toBeUndefined();
+  expect(notice).toContain("Update available: 0.8.231 → 0.8.232");
+  expect(notice).toContain("Run: brew upgrade hyperframes");
+});
+
+it("still installs an allowed patch on npm at that exact version", async () => {
+  const { scheduled, spawn, notice } = await patchAvailableAt(NPM_ENTRY);
+
+  expect(scheduled).toBe(true);
+  expect(spawn).toHaveBeenCalledOnce();
+  expect(installerArgv(spawn)).toEqual({
+    bin: "npm",
+    args: ["install", "-g", "[email protected]"],
+  });
+  expect(notice).toBe("");
+});
@@ -150,6 +150,42 @@ describe("scheduleBackgroundInstall", () => {
     expect(spawnSpy).not.toHaveBeenCalled();
   });
 
+  // Before 1.0 a minor bump may break (semver), so 0.8.x -> 0.9.x is a "major"
+  // jump: notify only. Comparing the first number alone auto-installed it.
+  it("does NOT schedule across a 0.x minor jump", async () => {
+    const { spawnSpy, config } = setupMocks({
+      installer: { kind: "npm", command: "npm install -g [email protected]" },
+    });
+    const { scheduleBackgroundInstall } = await import("./autoUpdate.js");
+
+    expect(scheduleBackgroundInstall("0.9.3", "0.8.231")).toBe(false);
+    expect(spawnSpy).not.toHaveBeenCalled();
+    expect(config.pendingUpdate).toBeUndefined();
+  });
+
+  it.each([
+    ["0.8.232", "0.8.231"],
+    ["1.3.0", "1.2.5"],
+  ])("still schedules %s over %s (same breaking line)", async (latest, current) => {
+    const { spawnSpy } = setupMocks({
+      installer: { kind: "npm", command: `npm install -g hyperframes@${latest}` },
+    });
+    const { scheduleBackgroundInstall } = await import("./autoUpdate.js");
+
+    expect(scheduleBackgroundInstall(latest, current)).toBe(true);
+    expect(spawnSpy).toHaveBeenCalledOnce();
+  });
+
+  it("does NOT schedule across a major jump from 1.0 on", async () => {
+    const { spawnSpy } = setupMocks({
+      installer: { kind: "npm", command: "npm install -g [email protected]" },
+    });
+    const { scheduleBackgroundInstall } = await import("./autoUpdate.js");
+
+    expect(scheduleBackgroundInstall("2.0.0", "1.9.4")).toBe(false);
+    expect(spawnSpy).not.toHaveBeenCalled();
+  });
+
   it("skips in dev mode", async () => {
     const { spawnSpy } = setupMocks({
       installer: { kind: "npm", command: "npm install -g [email protected]" },
Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ npx skills add heygen-com/hyperframes`
`66`	`66`
`67`	`67`	> 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`.
`68`	`68`	`>`
`69`		-> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs from the current `main`, so reach for it when you need the newest copy of a skill.
	`69`	+> `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.
`70`	`70`
`71`	`71`	`Run project-local installs from your video project's directory. From a HyperFrames`
`72`	`72`	checkout, use `npx hyperframes skills update` for a global install instead: a