fix(cli): default capture output to ./capture/ (auto-suffix capture-2/, capture-3/ on re-run)

`hyperframes capture <url>` (no -o) used to dump into `./captures/<hostname>/`,
which buries the project two levels deep and silently merges re-runs into the
previous dir — file-by-file, so leftover screenshots / assets from the prior
run stay mixed in and any later `glob` sees both.

Switch the default to `./capture/`. When it already exists, auto-suffix to
`./capture-2/`, `./capture-3/`, … (up to -99). Each capture is its own clean
directory — no crud, no friction, no clobber. The CLI prints a one-line note
when the suffix kicks in so the user sees which dir actually got written.
Explicit `-o <name>` is unaffected (still overwrite-tolerant).

docs/guides/website-to-video.mdx

@@ -141,7 +141,7 @@ npx hyperframes capture https://stripe.com
 ```
 
 ```
-◇  Captured Stripe | Financial Infrastructure → captures/stripe-com
+◇  Captured Stripe | Financial Infrastructure → capture
 
   Screenshots: 12
   Assets: 45
@@ -151,7 +151,7 @@ npx hyperframes capture https://stripe.com
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-o, --output` | `captures/<hostname>` | Output directory |
+| `-o, --output` | `./capture` | Output directory (auto-suffixes to `./capture-2/`, `./capture-3/`, … if `./capture/` is taken) |
 | `--timeout` | `120000` | Page load timeout in ms |
 | `--skip-assets` | `false` | Skip downloading images and fonts |
 | `--max-screenshots` | `24` | Maximum screenshot count |
@@ -208,7 +208,7 @@ See the [pipeline guide](/guides/pipeline#iterating) for more re-entry patterns.
     Sites using frameworks like Framer lazy-load images via IntersectionObserver. The capture scrolls through the page to trigger loading, but very long pages may miss images near the bottom. Adding a Gemini key improves descriptions of captured assets, but doesn't increase the count.
   </Accordion>
   <Accordion title="Colors look wrong">
-    The capture uses pixel sampling combined with DOM computed styles. Dark sites should show dark colors in the palette. Check the scroll screenshots in `captures/<name>/screenshots/` to see what the capture actually saw.
+    The capture uses pixel sampling combined with DOM computed styles. Dark sites should show dark colors in the palette. Check the scroll screenshots in `<output>/screenshots/` (default `./capture/screenshots/`) to see what the capture actually saw.
   </Accordion>
   <Accordion title="Agent doesn't find the skill">
     Verify skills are installed:

docs/packages/cli.mdx

@@ -407,12 +407,12 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     ```bash
     npx hyperframes capture https://stripe.com
-    npx hyperframes capture https://linear.app -o captures/linear
+    npx hyperframes capture https://linear.app -o linear-capture
     npx hyperframes capture https://example.com --json
     ```
 
     ```
-    ◇  Captured Stripe | Financial Infrastructure → captures/stripe-com
+    ◇  Captured Stripe | Financial Infrastructure → capture
 
       Screenshots: 12
       Assets: 45
@@ -422,7 +422,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     | Flag | Description |
     |------|-------------|
-    | `-o, --output` | Output directory (default: `captures/<hostname>`) |
+    | `-o, --output` | Output directory (default: `./capture`; auto-suffixes to `./capture-2/`, `./capture-3/`, … if `./capture/` is taken) |
     | `--timeout` | Page load timeout in ms (default: 120000) |
     | `--skip-assets` | Skip downloading images and fonts |
     | `--max-screenshots` | Maximum screenshot count (default: 24) |

packages/cli/src/commands/capture.ts

@@ -3,8 +3,8 @@ import { resolve } from "node:path";
 import type { Example } from "./_examples.js";
 
 export const examples: Example[] = [
-  ["Capture a website", "hyperframes capture https://stripe.com"],
-  ["Capture to a specific directory", "hyperframes capture https://linear.app -o linear-video"],
+  ["Capture a website into ./capture/", "hyperframes capture https://stripe.com"],
+  ["Capture to a different directory", "hyperframes capture https://linear.app -o linear-video"],
   ["JSON output for AI agents", "hyperframes capture https://example.com --json"],
   [
     "Pull a video from the captured manifest by index",
@@ -29,7 +29,7 @@ export default defineCommand({
     },
     output: {
       type: "string",
-      description: "Output directory name",
+      description: "Output directory name (default: ./capture, then ./capture-2/, ./capture-3/, …)",
       alias: "o",
     },
     "skip-assets": {
@@ -69,6 +69,7 @@ export default defineCommand({
       default: false,
     },
   },
+  // fallow-ignore-next-line complexity
   async run({ args }) {
     if (args.video) {
       const { runVideoMode } = await import("./capture/video.js");
@@ -96,13 +97,25 @@ export default defineCommand({
       process.exit(1);
     }
 
-    // Determine output directory — default to captures/<hostname> to keep repo root clean
-    let outputName = args.output as string | undefined;
-    if (!outputName) {
-      const hostname = new URL(url).hostname.replace(/^www\./, "");
-      outputName = `captures/${hostname.replace(/\./g, "-")}`;
+    const isDefaultOutput = !args.output;
+    let outputName = (args.output as string | undefined) ?? "capture";
+    let outputDir = resolve(outputName);
+
+    if (isDefaultOutput) {
+      const { existsSync } = await import("node:fs");
+      // Auto-suffix when ./capture/ is taken: capture-2, capture-3, … so re-runs
+      // never silently merge into a previous capture's artifacts.
+      let n = 2;
+      while (existsSync(outputDir) && n < 100) {
+        outputName = `capture-${n}`;
+        outputDir = resolve(outputName);
+        n++;
+      }
+      if (existsSync(outputDir)) {
+        console.error(`./capture-{2..99} are all taken. Pass -o <name> to pick a directory.`);
+        process.exit(1);
+      }
     }
-    const outputDir = resolve(outputName);
 
     const isJson = args.json as boolean;
 
@@ -110,6 +123,9 @@ export default defineCommand({
       const { c } = await import("../ui/colors.js");
       console.log();
       console.log(c.dim("◆") + "  Capturing " + c.bold(url));
+      if (isDefaultOutput && outputName !== "capture") {
+        console.log(`  ${c.dim(`(./capture/ exists; writing to ./${outputName}/)`)}`);
+      }
       console.log();
     }
 

packages/cli/src/commands/snapshot.ts

@@ -84,8 +84,8 @@ async function extractVideoFrameToBuffer(
 }
 
 export const examples: Example[] = [
-  ["Capture 5 key frames from a composition", "snapshot captures/stripe"],
-  ["Capture 10 evenly-spaced frames", "snapshot captures/stripe --frames 10"],
+  ["Capture 5 key frames from a composition", "snapshot capture"],
+  ["Capture 10 evenly-spaced frames", "snapshot capture --frames 10"],
 ];
 
 /**

skills/website-to-video/references/step-0-capture.md

@@ -20,7 +20,7 @@ Example: `npx hyperframes capture https://stripe.com -o videos/stripe-launch/cap
 
 Keeping capture artifacts (`screenshots/`, `assets/`, `extracted/`, `AGENTS.md`, `CLAUDE.md`) in a dedicated `capture/` subfolder keeps them isolated from later build files (`SCRIPT.md`, `STORYBOARD.md`, `DESIGN.md`, `compositions/`, `index.html`, `narration.wav`, `transcript.json`, `renders/`, `snapshots/`), which all live at `<project-dir>/` root.
 
-For exploratory captures that aren't becoming a video yet, `-o captures/<name>` at the repo root is fine — the isolation convention only matters when you're building a video on top of the capture.
+For exploratory captures that aren't becoming a video yet, the default `./capture/` (or any `-o <name>` you pick) is fine — the isolation convention only matters when you're building a video on top of the capture.
 
 ## Confirm it succeeded