diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 29f4a09fc..81b83b69f 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -5,7 +5,14 @@
 // `hyperframes --version` near-instant (~10ms vs ~80ms).
 import { VERSION } from "./version.js";
 
-if (process.argv.includes("--version") || process.argv.includes("-V")) {
+const argv = process.argv.slice(2);
+const commandArg = argv[0];
+const rootVersionRequested =
+  commandArg === "--version" ||
+  commandArg === "-V" ||
+  (commandArg === undefined && (argv.includes("--version") || argv.includes("-V")));
+
+if (rootVersionRequested) {
   console.log(VERSION);
   process.exit(0);
 }
@@ -64,8 +71,8 @@ const main = defineCommand({
 // Telemetry — lazy-loaded, captured references for exit handlers
 // ---------------------------------------------------------------------------
 
-const commandArg = process.argv[2];
-const command = commandArg && commandArg in subCommands ? commandArg : "unknown";
+const cliCommandArg = process.argv[2];
+const command = cliCommandArg && cliCommandArg in subCommands ? cliCommandArg : "unknown";
 const hasJsonFlag = process.argv.includes("--json");
 
 // Captured references — populated when the lazy imports resolve.
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index 59cfa7ca4..392b0a936 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -132,6 +132,46 @@ describe("hyperframes init flag rename", () => {
     expect(injected).not.toContain("setTimeout");
   });
 
+  it("-v works as the short alias for --video", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
+    const target = join(dir, "proj");
+    try {
+      const res = runInit([
+        target,
+        "--example",
+        "blank",
+        "--non-interactive",
+        "--skip-skills",
+        "-v",
+        "missing.mp4",
+      ]);
+      expect(res.status).toBe(1);
+      expect(res.stderr).toContain("Video file not found: missing.mp4");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("-V prints a migration error instead of version fast-path", () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
+    const target = join(dir, "proj");
+    try {
+      const res = runInit([
+        target,
+        "--example",
+        "blank",
+        "--non-interactive",
+        "--skip-skills",
+        "-V",
+        "missing.mp4",
+      ]);
+      expect(res.status).toBe(1);
+      expect(res.stderr).toContain("The -V short flag no longer maps to --video");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("--template prints a rename hint and exits non-zero", () => {
     const dir = mkdtempSync(join(tmpdir(), "hf-init-test-"));
     const target = join(dir, "proj");
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index 443368619..6136cdaa5 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -588,7 +588,13 @@ export default defineCommand({
     video: {
       type: "string",
       description: "Path to a video file (MP4, WebM, MOV)",
+      alias: "v",
+    },
+    "video-legacy": {
+      type: "string",
+      description: "[renamed] Use --video (or -v) instead of -V.",
       alias: "V",
+      hidden: true,
     },
     audio: {
       type: "string",
@@ -638,6 +644,14 @@ export default defineCommand({
       );
       process.exit(1);
     }
+    if (args["video-legacy"] !== undefined) {
+      console.error(
+        c.error(
+          `The -V short flag no longer maps to --video. Use --video (or -v). Example:\n  npx hyperframes init ${args.name ?? "my-video"} --video "${args["video-legacy"]}"`,
+        ),
+      );
+      process.exit(1);
+    }
     const exampleFlag = args.example;
     const videoFlag = args.video;
     const audioFlag = args.audio;