fix(cli): handle init -V with explicit migration error

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.

packages/cli/src/commands/init.test.ts

@@ -136,7 +136,15 @@ describe("hyperframes init flag rename", () => {
     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"]);
+      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 {
@@ -144,6 +152,26 @@ describe("hyperframes init flag rename", () => {
     }
   });
 
+  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");

packages/cli/src/commands/init.ts

@@ -590,6 +590,12 @@ export default defineCommand({
       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",
       description: "Path to an audio file (MP3, WAV, M4A)",
@@ -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;