feat(cli): surface extract-cache dir in doctor + add --frames-cache-dir sugar

Windows users with the OS temp dir on a small system drive have hit
C: exhaustion mid-render (Slack ts=1784219488 · CLI v0.7.58 · win32
15 GB / 8-core, ~5500 frames). The engine already honors
HYPERFRAMES_EXTRACT_CACHE_DIR for relocation, but the knob was
undocumented and invisible in diagnostics — the reporter had to piece
together a 4-flag compound workaround including EXTRACT_CACHE_DIR=off.

Changes:
- Extract the env-var resolver into a public engine API
  (resolveExtractCacheDir, defaultExtractCacheDir,
  EXTRACT_CACHE_DIR_DISABLED_ALIASES) with a typed resolution shape
  distinguishing "disabled by user" vs "default" vs "env override".
- Add a Frames-cache check to `hyperframes doctor` that reports the
  effective directory, its free space, source (env or default), and
  fails with a relocation hint when <2 GB free at that mount.
- Add `hyperframes render --frames-cache-dir <path>` as discoverable
  CLI sugar for the env var, including the opt-out aliases
  (off/none/false/0) and CWD-safe absolute-path resolution.
- Document the flag in docs/packages/cli.mdx with the field-signal
  citation, and add a render example row for the Windows workflow.
- Cover both surfaces with unit tests (6 doctor cases + 4 engine
  cases including all disabled-alias variants).

Refs Slack #hyperframes-cli-feedback ts=1784219488 (win32 v0.7.58).

Co-authored-by: Via <via-heygen[bot]@users.noreply.github.com>

packages/engine/src/config.test.ts

@@ -8,6 +8,9 @@ import {
   shouldClampToScreenshotForConcreteGpu,
   applyConcreteGpuScreenshotClamp,
   shouldAutoDisableStreamingEncodeOnWin32Compound,
+  resolveExtractCacheDir,
+  defaultExtractCacheDir,
+  EXTRACT_CACHE_DIR_DISABLED_ALIASES,
 } from "./config.js";
 import type { EngineConfig } from "./config.js";
 import { isLowMemorySystem } from "./services/systemMemory.js";
@@ -798,3 +801,45 @@ describe("scaleProtocolTimeoutForComposition", () => {
     );
   });
 });
+
+describe("resolveExtractCacheDir", () => {
+  it("returns the OS-default cache dir when the env var is unset", () => {
+    const res = resolveExtractCacheDir({});
+    expect(res.disabled).toBe(false);
+    expect(res.source).toBe("default");
+    if (!res.disabled) {
+      expect(res.dir).toBe(defaultExtractCacheDir());
+    }
+  });
+
+  it("threads a positive env value through verbatim (source: env)", () => {
+    const res = resolveExtractCacheDir({
+      HYPERFRAMES_EXTRACT_CACHE_DIR: "D:/hf-cache",
+    });
+    expect(res.disabled).toBe(false);
+    expect(res.source).toBe("env");
+    if (!res.disabled) {
+      expect(res.dir).toBe("D:/hf-cache");
+      expect(res.rawValue).toBe("D:/hf-cache");
+    }
+  });
+
+  it.each(EXTRACT_CACHE_DIR_DISABLED_ALIASES.flatMap((v) => [v, v.toUpperCase(), `  ${v}  `]))(
+    "reports disabled for opt-out alias %s",
+    (value) => {
+      const res = resolveExtractCacheDir({ HYPERFRAMES_EXTRACT_CACHE_DIR: value });
+      expect(res.disabled).toBe(true);
+      if (res.disabled) {
+        expect(res.dir).toBeUndefined();
+        expect(res.rawValue).toBe(value);
+      }
+    },
+  );
+
+  it("defaults to process.env when no env argument is passed", () => {
+    // Signal-only smoke test — the previous callers rely on this default and
+    // both engine.resolveConfig() and doctor's checkFramesCache() would break
+    // silently if the signature drifted to require an env argument.
+    expect(() => resolveExtractCacheDir()).not.toThrow();
+  });
+});