videobook 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,102 @@ and the package uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-25
+
+### Added
+
+- KIE Kling 4.0 reference-to-video and keyframe-to-video, 3 to 30 seconds at
+  720p or 1080p. Reference-to-video takes up to ten images and five videos,
+  and generates from the prompt alone when none are connected. Keyframe-to-video
+  takes a first frame, up to eight middle keyframes and a last frame, as many
+  as the duration allows. Prompts name connected media the way Kling 4.0 does:
+  `@image_1`, `@video_1`, `@first_frame`, `@keyframe_1` and `@last_frame`.
+- KIE PixVerse V6 Max text-to-video and image-to-video, 1 to 15 seconds at
+  360p to 1080p, with optional generated audio and a seed. Image-to-video
+  follows the image's aspect ratio.
+- KIE OmniHuman 2.0, which animates one image to a driving audio track at 720p
+  for as long as the audio runs, with an optional prompt of up to 300
+  characters. KIE's watermark stays on by default (`enable_watermark`).
+- The KIE Grok Imagine Video 1.5 preview, the KIE Grok Imagine endpoint that
+  takes first and last frames, a loop image (`loop_url`) and up to four timed
+  `keyframes`. It shares the Grok Imagine Video 1.5 image-to-video frontier
+  ranking. Kling 4.0, PixVerse V6 Max and OmniHuman 2.0 are on no top-10 board
+  and appear in the unranked group.
+
+### Changed
+
+- Upgrade all `@apicity/*` dependencies to 0.18.1, which prices the new KIE
+  models. Its endpoint catalog now lists fal `v1.queue.status` and
+  `v1.queue.result`, with the other fal SDK methods written as method
+  shorthand, so `apicity har report` from `@apicity/cli` 0.18.1 can resolve the
+  fal polling captures Videobook writes. The requests sent to fal are
+  unchanged.
+- Image and video models default to a 12-second duration (or the nearest
+  allowed length), a 9:16 aspect ratio and their highest resolution, quality
+  and bitrate. Each notebook remembers the last duration, aspect ratio,
+  resolution and quality a cell used, and applies them to new cells and model
+  switches. Goals saved before this change keep their 2K scene; new goals use
+  4K.
+- On desktop, Settings shows AI providers in one column and accounts, storage
+  and diagnostics in another; on phones the columns stack behind section jump
+  buttons. The chat input stays a plain bar on Settings.
+- The Library opens from an Assets button in the notebook toolbar instead of
+  the header, and Arrange is renamed Clean.
+- Library browsing pages assets before building their rows and no longer runs
+  ffprobe while listing; proxy checks and duration backfills run as background
+  jobs.
+- A Post can take its published link without being saved to iPhone or Dropbox
+  first.
+
+### Fixed
+
+- HAR captures of KIE's nested Veo and Suno SDK calls are named by their
+  apicity catalog dot paths, such as `api.v1.veo.generate` and
+  `api.v1.generate.sounds`, instead of their SDK paths, so `apicity har report`
+  resolves them. Sub-provider prefixes that are URL segments stay:
+  `kie.claude.post.v1.messages` is named `claude.v1.messages`.
+- A generation that fails before reaching its provider, such as a request the
+  schema refuses, is captured under the provider's catalog endpoint, and fal,
+  Alibaba and KIE file uploads are captured as `storage.upload.initiate`,
+  `api.v1.uploads` and `api.fileStreamUpload`, so `apicity har report` resolves
+  them.
+- A notebook generation whose provider fails after accepting the request now
+  marks its plan failed with the provider error. `list_notebook_generation_plans`
+  and the Jobs screen kept reporting such plans as awaiting output.
+- v3 goals saved with a 2K scene load again and keep that resolution when they
+  are edited, approved or retried.
+- Image subject edits check the provider key before uploading the source image,
+  so a missing or placeholder key no longer sends the image to a public file
+  host for a request that cannot run.
+- Settings loads when the page opens on it, or when it opens before the MCP
+  connection is ready.
+- The multyculty workflow and video poster recovery tests no longer time out on
+  loaded hosts, and the chat-composer browser test no longer reads the runner's
+  `.env` or provider keys and matches the ranked model picker.
+
+## [0.3.0] - 2026-10-24
+
+### Added
+
+- Opt-in local provider HAR diagnostics with Settings, MCP and CLI controls, concurrent book attribution and retention limits.
+  Captured SDK calls are named by their apicity catalog dot path, such as
+  `api.v1.jobs.createTask`, so `apicity har report` attributes them to their
+  endpoints.
+- The Request payload panel of a queued, generating or failed cell downloads
+  the attempt's scrubbed captures as one HAR file, or shows "Capture off" with
+  a link to Settings. `inspect_generation_request` reports whether an asset has
+  a capture, with its path and outcome; the new `get_generation_har` tool
+  returns the HAR for an asset or attempt id.
+- `videobook har list` and `videobook har export --out <dir|file.tar.gz>`,
+  both with `--since`, `--failures` and `--provider`. Export re-runs the
+  `@apicity/har` scrubber on every capture and refuses, naming the file, when
+  scrubbing would change it. Otherwise it writes the captures with an index
+  and a manifest and prints the `apicity har report` hand-off.
+
+### Changed
+
+- Upgrade all Apicity dependencies to 0.18.0.
+
 ## [0.2.5] - 2026-10-24
 
 ### Added

package/README.md

@@ -65,6 +65,9 @@ videobook gc-books             # reclaim catalog storage in every book
 videobook doctor               # check Node, binaries, native modules and keys
 videobook config               # show where each provider key comes from
 videobook config set FAL_API_KEY op://Private/FAL_API_KEY/password
+videobook config set har_capture failures   # opt in to provider HAR capture
+videobook har list --failures  # captured provider calls, newest first
+videobook har export --out captures.tar.gz  # scrub-checked captures for apicity
 videobook setup 1password --op-vault Private
 videobook --version
 ```
@@ -104,10 +107,11 @@ run while a server owns the library.
 Installed data lives in `~/.videobook`:
 
 - `books/`, the library of books
-- `app-state.json`, connected X and Dropbox accounts
+- `app-state.json`, connected X and Dropbox accounts and the HAR capture setting
 - `.env`, provider keys, also editable from Settings in the web UI
+- `har/`, opt-in provider HAR captures (off by default) with an `index.jsonl`
 
-`VIDEOBOOK_HOME` or `--home` moves all three. `VIDEOBOOK_LIBRARY_DIR`,
+`VIDEOBOOK_HOME` or `--home` moves all four. `VIDEOBOOK_LIBRARY_DIR`,
 `VIDEOBOOK_APP_STATE_PATH` and `VIDEOBOOK_ENV_PATH` move one each; `--home`
 overrides any of them inherited from your shell. Set `VIDEOBOOK_HOME` and
 `VIDEOBOOK_ENV_PATH` in the environment, not in `.env`, because they decide

package/dist/archive-b2.js

@@ -1,4 +1,4 @@
-import { createB2 } from "@apicity/b2";
+import { createB2 } from "./usage-providers.js";
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { open, readFile, stat } from "node:fs/promises";

package/dist/asset-media-projection.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { findAudioFile, findPrimaryMediaFile, findVideoFile } from "videobook-engine";
+import { logger } from "./logger.js";
+import { queue } from "./queue.js";
+import { scheduleMediaDurationBackfill, scheduleVideoProxyAssessment, } from "./jobs/assess-media-probes.js";
+import { videoProxyAssessmentMatches, videoProxyMetadataMatches, } from "./video-proxy.js";
+export const PARTIAL_DOWNLOAD_RE = /\.(mp4|mov)\.part$/i;
+const DURATION_PROBE_EXT_RE = /\.(mp4|mov|webm|mkv|mp3|wav|m4a|aac|ogg|flac)$/i;
+const IMAGE_FILE_RE = /\.(jpg|jpeg|png|webp|gif)$/i;
+export function findAssetMediaFile(files, asset) {
+    return asset.kind === "audio"
+        ? findAudioFile(files, asset.kind)
+        : asset.kind === "video"
+            ? findVideoFile(files.filter((file) => file.name !== "proxy.mp4"))
+            : findPrimaryMediaFile(files, asset.kind);
+}
+// Content fingerprint for cache-busting media URLs. Pure function of the
+// manifest tuples; partial downloads are excluded because their size grows on
+// every poll while no served URL points at them.
+function computeAssetFingerprint(files) {
+    const settled = files.filter((f) => !PARTIAL_DOWNLOAD_RE.test(f.name));
+    if (settled.length === 0)
+        return "";
+    const sorted = [...settled].sort((a, b) => a.name.localeCompare(b.name));
+    const hash = createHash("sha1");
+    for (const f of sorted) {
+        hash.update(f.name);
+        hash.update("\0");
+        hash.update(String(f.sizeBytes ?? 0));
+        hash.update("\0");
+        hash.update(f.objectHash);
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 12);
+}
+export function indexByArtifactId(rows) {
+    const map = new Map();
+    for (const row of rows)
+        map.set(row.artifactId, row);
+    return map;
+}
+export function groupByArtifactId(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const list = map.get(row.artifactId);
+        if (list)
+            list.push(row);
+        else
+            map.set(row.artifactId, [row]);
+    }
+    return map;
+}
+function streamSeconds(stream) {
+    return stream.durationTicks * stream.timeBase.numerator / stream.timeBase.denominator;
+}
+export function assetStreamProfile(streams, meta) {
+    const videoStream = streams.find((stream) => stream.kind === "video" && stream.video);
+    const audioStream = streams.find((stream) => stream.kind === "audio" && stream.audio);
+    const frameRate = videoStream?.video?.averageFrameRate
+        ?? videoStream?.video?.nominalFrameRate;
+    const streamDuration = videoStream ? streamSeconds(videoStream) : 0;
+    const metadataDuration = Number(meta?.duration);
+    const sourceDuration = streamDuration > 0
+        ? streamDuration
+        : Number.isFinite(metadataDuration) ? metadataDuration : 0;
+    const sourceProfile = sourceDuration > 0
+        ? {
+            videoDuration: sourceDuration,
+            avgFps: frameRate ? frameRate.numerator / frameRate.denominator : null,
+            hasAudio: audioStream !== undefined || meta?.hasAudio === true,
+        }
+        : null;
+    return { videoStream, audioStream, frameRate, sourceProfile };
+}
+function isActiveWork(work) {
+    return work !== null && (work.status === "pending" || work.status === "working");
+}
+export function servedVideoProxyFile(input) {
+    if (input.artifact.kind !== "video" || !input.mediaFile)
+        return null;
+    const proxyFile = input.files.find((file) => file.name === "proxy.mp4");
+    if (!proxyFile)
+        return null;
+    const metadata = input.proxyMetadata;
+    if (metadata.ok && videoProxyMetadataMatches(metadata.value, input.mediaFile, proxyFile)) {
+        return proxyFile;
+    }
+    const assessed = metadata.ok
+        && videoProxyAssessmentMatches(metadata.value, input.mediaFile, proxyFile);
+    if (!assessed && !isActiveWork(input.work) && input.sourceProfile) {
+        scheduleVideoProxyAssessment({
+            bookId: input.bookId,
+            artifactId: input.artifact.artifactId,
+            sourceFile: input.mediaFile,
+            proxyFile,
+            sourceProfile: input.sourceProfile,
+        });
+    }
+    return null;
+}
+export function assetDuration(input) {
+    const stored = input.meta?.duration;
+    if (typeof stored === "number")
+        return stored;
+    const stream = input.profile.videoStream ?? input.profile.audioStream;
+    const measured = stream ? streamSeconds(stream) : 0;
+    if (measured > 0)
+        return measured;
+    if (input.meta && input.mediaFile && DURATION_PROBE_EXT_RE.test(input.mediaFile.name)) {
+        scheduleMediaDurationBackfill({
+            bookId: input.bookId,
+            artifactId: input.artifactId,
+            mediaFile: input.mediaFile,
+        });
+    }
+    return null;
+}
+function mediaCacheBust(kind, files, mediaFile) {
+    if (kind === "video" || kind === "image") {
+        const fingerprint = computeAssetFingerprint(files);
+        return fingerprint ? `?v=${fingerprint}` : "";
+    }
+    const mediaHash = mediaFile?.objectHash;
+    return mediaHash ? `?v=${mediaHash.slice(0, 12)}` : "";
+}
+export function assetMediaUrls(input) {
+    const { artifact, files } = input;
+    const base = `/files/${input.bookId}/${artifact.artifactId}`;
+    const cacheBust = mediaCacheBust(artifact.kind, files, input.mediaFile);
+    const characterImage = artifact.kind === "character"
+        ? files.find((file) => IMAGE_FILE_RE.test(file.name)) ?? null
+        : null;
+    const served = characterImage ?? input.proxyFile ?? input.mediaFile;
+    const media_url = served ? `${base}/${served.name}${cacheBust}` : null;
+    if (characterImage)
+        return { media_url, thumbnail_url: media_url };
+    const hasThumbnail = files.some((file) => file.name === "original.jpg");
+    const thumbnail_url = hasThumbnail
+        ? `${base}/original.jpg${cacheBust}`
+        : artifact.kind === "image" ? media_url : null;
+    return { media_url, thumbnail_url };
+}
+export async function scheduleMissingVideoPoster(engine, input) {
+    const { artifact, mediaFile } = input;
+    if (artifact.kind !== "video" || input.status !== "ready" || !mediaFile)
+        return;
+    if (input.files.some((file) => file.name === "original.jpg"))
+        return;
+    const recovery = await engine.metadata.artifacts.read(artifact.artifactId, "poster-recovery");
+    if (recovery.ok && recovery.value.failed && recovery.value.sourceHash === mediaFile.objectHash)
+        return;
+    void queue.enqueue(`extract-video-poster-${input.bookId}-${artifact.artifactId}-${mediaFile.objectHash}`, {
+        type: "extract_video_poster",
+        bookId: input.bookId,
+        posterArtifactId: artifact.artifactId,
+        sourceFilename: mediaFile.name,
+        sourceHash: mediaFile.objectHash,
+    }).catch((error) => {
+        logger.error("poster-enqueue-failed", { assetId: artifact.artifactId, error });
+    });
+}

package/dist/cli/args.js

@@ -7,9 +7,10 @@ export class CliUsageError extends Error {
     }
 }
 const LOG_LEVELS = new Set(["silent", "error", "warn", "info", "debug"]);
-const COMMANDS = new Set(["serve", "mcp", "run", "tools", "gc-books", "doctor", "setup", "config", "version", "help"]);
+const COMMANDS = new Set(["serve", "mcp", "run", "tools", "gc-books", "doctor", "setup", "config", "har", "version", "help"]);
 const CONFIG_ACTIONS = new Set(["list", "get", "set", "unset"]);
-const POSITIONAL_COMMANDS = new Set(["run", "setup", "config"]);
+const HAR_ACTIONS = new Set(["list", "export"]);
+const POSITIONAL_COMMANDS = new Set(["run", "setup", "config", "har"]);
 const DEFAULT_RUN_TIMEOUT_SECONDS = 600;
 const GLOBAL_OPTIONS = {
     port: { type: "string" },
@@ -28,6 +29,7 @@ const COMMAND_OPTIONS = {
     doctor: { json: { type: "boolean" } },
     setup: { "op-vault": { type: "string" }, "op-token": { type: "string" }, "no-verify": { type: "boolean" }, remove: { type: "boolean" } },
     config: { json: { type: "boolean" } },
+    har: { out: { type: "string" }, since: { type: "string" }, failures: { type: "boolean" }, provider: { type: "string" }, json: { type: "boolean" } },
 };
 function splitCommand(argv) {
     const [first, ...rest] = argv;
@@ -147,6 +149,35 @@ function buildConfig(values, positionals, flags) {
         flags: { ...flags, json: values.json === true },
     };
 }
+function buildHar(values, positionals, flags) {
+    const [action, ...extra] = positionals;
+    if (!action || !HAR_ACTIONS.has(action) || extra.length > 0) {
+        throw new CliUsageError("Usage: videobook har list [--since <date>] [--failures] [--provider <p>] [--json] | har export --out <dir|file.tar.gz> [--since <date>] [--failures] [--provider <p>]");
+    }
+    const out = stringValue(values.out);
+    if (action === "export" && out === undefined)
+        throw new CliUsageError("har export needs --out <dir|file.tar.gz>");
+    if (action === "list" && out !== undefined)
+        throw new CliUsageError("--out applies to har export only");
+    const since = stringValue(values.since);
+    if (since !== undefined && !Number.isFinite(Date.parse(since)))
+        throw new CliUsageError(`--since needs an ISO date or time, got "${since}".`);
+    const providers = typeof values.provider === "string"
+        ? values.provider.split(",").map((provider) => provider.trim()).filter(Boolean)
+        : [];
+    return {
+        command: "har",
+        action: action,
+        flags: {
+            ...flags,
+            ...(out === undefined ? {} : { out }),
+            ...(since === undefined ? {} : { since }),
+            failures: values.failures === true,
+            providers,
+            json: values.json === true,
+        },
+    };
+}
 function buildCommand(command, values, positionals) {
     const flags = globalFlags(values);
     switch (command) {
@@ -164,6 +195,8 @@ function buildCommand(command, values, positionals) {
             return buildSetup(values, positionals, flags);
         case "config":
             return buildConfig(values, positionals, flags);
+        case "har":
+            return buildHar(values, positionals, flags);
         default:
             return { command, flags };
     }
@@ -215,6 +248,8 @@ export function helpText() {
         "  gc-books           Reclaim catalog storage in every book",
         "  doctor             Check Node, media binaries, native modules and keys",
         "  config [action]    list | get <KEY> | set <KEY> <VALUE> | unset <KEY> in the data-home .env",
+        "  har list           List provider HAR captures, newest first",
+        "  har export         Copy scrub-checked captures and a manifest to share with apicity (--out)",
         "  setup 1password    Read keys from a 1Password vault (--op-vault, --op-token)",
         "  version            Print versions",
         "  help               Print this help",
@@ -228,7 +263,11 @@ export function helpText() {
         "  --open             serve: open the web UI in a browser",
         "  --no-wait          run: do not wait for queued jobs",
         "  --timeout <s>      run: seconds to wait for jobs (default 600)",
-        "  --json             doctor, config: print machine-readable results",
+        "  --json             doctor, config, har: print machine-readable results",
+        "  --out <path>       har export: a new directory, or a .tar.gz/.tgz file",
+        "  --since <date>     har: only calls at or after this ISO date or time",
+        "  --failures         har: only failed calls",
+        "  --provider <p>     har: only these providers, comma separated",
         "  --op-vault <name>  setup 1password: vault whose items are named after the keys",
         "  --op-token <tok>   setup 1password: service-account token, best as env:VAR",
         "  --no-verify        setup 1password: skip the op item list check",

package/dist/cli/config-command.js

@@ -1,3 +1,4 @@
+import { readHarSettings, writeHarSettings, harDirectory } from "../har-settings.js";
 import { hasControlCharacters, readEnvValues, updateEnvFile } from "../env-file.js";
 import { MANAGED_ENV_KEYS, getDefaultSecretStore, isSecretEnvKey, maskEnvValue, } from "../env-secrets.js";
 import { OP_TOKEN_SETTING, OP_VAULT_SETTING, isOpReference, vaultReference } from "../one-password.js";
@@ -83,10 +84,25 @@ async function unsetKey(key, envPath) {
     return 0;
 }
 export async function runConfigCommand(command) {
+    if (command.key === "har_capture") {
+        try {
+            const current = await readHarSettings();
+            const settings = command.action === "set" || command.action === "unset"
+                ? await writeHarSettings({ ...await readHarSettings(undefined, {}), mode: command.action === "unset" ? "off" : command.value })
+                : current;
+            process.stdout.write(`${JSON.stringify({ harCapture: settings, dir: harDirectory(), overridden: Boolean(process.env.VIDEOBOOK_HAR_CAPTURE?.trim()) })}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
     const envPath = getDefaultSecretStore().envPath();
     if (command.action === "list") {
         const file = readEnvValues(envPath);
-        printRows(CONFIG_KEYS.map((key) => configRow(key, file)), file, command.flags.json, envPath);
+        const har = await readHarSettings();
+        printRows([...CONFIG_KEYS.map((key) => configRow(key, file)), { key: "har_capture", source: process.env.VIDEOBOOK_HAR_CAPTURE?.trim() ? "environment" : "app state", value: har.mode }], file, command.flags.json, envPath);
         return 0;
     }
     const key = command.key ?? "";

package/dist/cli/doctor-command.js

@@ -1,3 +1,4 @@
+import { harDirectory, readHarSettings } from "../har-settings.js";
 import { execFile } from "node:child_process";
 import { access, constants, readdir } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -72,6 +73,19 @@ async function dataHomeCheck() {
         });
     }
 }
+async function harCaptureCheck() {
+    const settings = await readHarSettings();
+    const dir = harDirectory();
+    let writable = true;
+    try {
+        await access(await nearestExisting(dir), constants.W_OK);
+    }
+    catch {
+        writable = false;
+    }
+    return check({ id: "har-capture", label: "HAR capture", status: writable || settings.mode === "off" ? "ok" : "warn",
+        detail: `${settings.mode}; ${dir}; writable: ${writable ? "yes" : "no"}`, required: false });
+}
 async function libraryCheck() {
     const libraryDir = bookManager.rootDir;
     try {
@@ -255,6 +269,7 @@ async function collectDoctorChecks() {
     return [
         nodeCheck(),
         await dataHomeCheck(),
+        await harCaptureCheck(),
         await libraryCheck(),
         await binaryCheck("ffmpeg", "ffmpeg", FFMPEG, bundledPath("ffmpeg-static"), "VIDEOBOOK_FFMPEG_PATH"),
         await binaryCheck("ffprobe", "ffprobe", FFPROBE, bundledFfprobe(), "VIDEOBOOK_FFPROBE_PATH"),

package/dist/cli/har-command.js

@@ -0,0 +1,86 @@
+import { dirname, resolve } from "node:path";
+import { exportHarCaptures, selectHarRows } from "../har-export.js";
+import { readHarIndex } from "../har-index.js";
+import { harDirectory } from "../har-settings.js";
+const LISTED_SKIPS = 10;
+function selection(flags) {
+    return {
+        since: flags.since === undefined ? null : Date.parse(flags.since),
+        failures: flags.failures,
+        providers: flags.providers,
+    };
+}
+async function listCaptures(flags) {
+    const dir = harDirectory();
+    const rows = selectHarRows(await readHarIndex(dir), selection(flags)).sort((a, b) => b.ts.localeCompare(a.ts));
+    if (flags.json) {
+        process.stdout.write(`${JSON.stringify({ dir, captures: rows }, null, 2)}\n`);
+        return 0;
+    }
+    const lines = rows.map((row) => [row.ts, row.provider, row.endpoint, row.outcome, row.status ?? "-", row.file].join("\t"));
+    process.stdout.write(`${["ts\tprovider\tendpoint\toutcome\tstatus\tfile", ...lines].join("\n")}\n`);
+    if (rows.length === 0)
+        process.stderr.write(`No matching captures in ${dir}\n`);
+    return 0;
+}
+function outcomeSummary(outcomes) {
+    return Object.entries(outcomes).filter(([, count]) => count > 0).map(([outcome, count]) => `${outcome} ${count}`).join(", ");
+}
+function shellPath(path) {
+    return /^[\w./:@%+=,-]+$/u.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+}
+function handoff(out, archive, manifest) {
+    const target = shellPath(archive ? out.replace(/\.(?:tar\.gz|tgz)$/iu, "") : out);
+    return [
+        `Exported ${manifest.files} capture${manifest.files === 1 ? "" : "s"} (${manifest.dateRange.first} to ${manifest.dateRange.last}) to ${out}`,
+        ...manifest.providers.map((provider) => `  ${provider.provider}: ${provider.calls} (${outcomeSummary(provider.outcomes)})`),
+        `Every file passed the @apicity/har ${manifest.apicity.har} scrub check. The captures still contain prompts and media URLs; review them before sharing.`,
+        "",
+        "Hand-off to an apicity maintainer:",
+        ...(archive ? [`  tar -xzf ${shellPath(out)} -C ${shellPath(dirname(out))}`] : []),
+        `  apicity har report ${target} > report.md`,
+        "  apicity har scrub --check <capture.har>",
+        "  pnpm run har:promote -- <capture.har> --name <provider>/<test-name> --dry-run   (in the apicity repository, for a successful call)",
+        "",
+    ].join("\n");
+}
+function skippedWarning(skipped) {
+    if (skipped.length === 0)
+        return "";
+    const listed = skipped.slice(0, LISTED_SKIPS).map((file) => `  ${file}\n`).join("");
+    const more = skipped.length > LISTED_SKIPS ? `  and ${skipped.length - LISTED_SKIPS} more\n` : "";
+    return `Skipped ${skipped.length} indexed capture${skipped.length === 1 ? "" : "s"} that are missing or unreadable:\n${listed}${more}`;
+}
+async function exportCaptures(flags) {
+    const dir = harDirectory();
+    const out = resolve(process.cwd(), flags.out ?? "");
+    const result = await exportHarCaptures({ dir, out, ...selection(flags) });
+    switch (result.status) {
+        case "out-inside-captures":
+            process.stderr.write(`--out must be outside the capture directory ${dir}\n`);
+            return 2;
+        case "out-exists":
+            process.stderr.write(`${out} already exists; choose a new file or an empty directory\n`);
+            return 1;
+        case "needs-scrub":
+            process.stderr.write([
+                "Refusing to export: @apicity/har scrubHar would change these captures:",
+                ...result.files.map((file) => `  ${file}`),
+                "A scrub rule is missing upstream. Report it to apicity instead of editing the captures. Nothing was written.",
+                "",
+            ].join("\n"));
+            return 1;
+        case "empty":
+            process.stderr.write(`${skippedWarning(result.skipped)}No captures in ${dir} match the filters. Nothing was written.\n`);
+            return 1;
+        case "exported":
+            process.stderr.write(skippedWarning(result.skipped));
+            process.stdout.write(flags.json
+                ? `${JSON.stringify({ out: result.out, archive: result.archive, manifest: result.manifest, skipped: result.skipped }, null, 2)}\n`
+                : handoff(result.out, result.archive, result.manifest));
+            return 0;
+    }
+}
+export async function runHarCommand(command) {
+    return command.action === "export" ? exportCaptures(command.flags) : listCaptures(command.flags);
+}

package/dist/cli/main.js

@@ -54,6 +54,10 @@ async function runCommand(parsed) {
             const { runConfigCommand } = await import("./config-command.js");
             return runConfigCommand(parsed);
         }
+        case "har": {
+            const { runHarCommand } = await import("./har-command.js");
+            return runHarCommand(parsed);
+        }
     }
 }
 async function loadDotenv() {
@@ -77,7 +81,15 @@ async function main(argv) {
         redirectConsoleToStderr();
     if (parsed.command !== "setup" && parsed.command !== "config")
         await loadDotenv();
-    return runCommand(parsed);
+    try {
+        return await runCommand(parsed);
+    }
+    finally {
+        if (parsed.command === "run" || parsed.command === "mcp") {
+            const { flushHarCaptures } = await import("../har-capture.js");
+            await flushHarCaptures();
+        }
+    }
 }
 function flushed(stream) {
     return new Promise((resolveFlush) => stream.write("", () => resolveFlush()));

package/dist/command-reference.js

@@ -90,7 +90,7 @@ export function renderGenerationModels() {
 
 Generated by \`npm run docs:commands\` from the media catalog (\`server/src/media/catalog.ts\`). Call \`generate_image\`, \`generate_video\` or \`generate_audio\` with one of these model ids; \`list_generation_models\` returns the same list with every option, enum, range and default read from the apicity schemas.
 
-Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.17.1, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
+Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.18.1, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
 
 Configured frontier models appear first; other models retain their existing order in a separate group. Providers without credentials are marked unavailable. Saved selections and defaults stay unchanged. Catalog variants on a frontier board are included even if previously hidden; non-frontier hidden variants remain hidden. A model version or lite variant never inherits another endpoint's score.
 
@@ -98,6 +98,8 @@ Kling 4 supports text, frames, references and video editing; it appears in the u
 
 HeyGen Avatar 3 and 4 digital twins are text-to-video with a stock avatar (Abigail Office Front) and voice (Ivy); the prompt is the spoken script. Avatar 5 uses the SDK defaults Abigail Sofa Front and Warm Pro Narrator. Avatar 4 image-to-video animates an image with the script and defaults to Ivy. Connected audio overrides speech synthesis. Video Agent v2 and v3 accept a production prompt. HeyGen lipsync, translation, filler-word removal, HeyGen Voice TTS and Ideogram vector endpoints are outside this catalog addition.
 
+Kie Kling 4.0 reference-to-video and keyframe-to-video, PixVerse V6 Max text-to-video and image-to-video, and OmniHuman 2.0 are on no top-10 board, so they appear in the unranked group. Kling 4.0 prompts name connected media as Kling 4.0 documents them: \`@image_1\` and \`@video_1\` for references, \`@first_frame\`, \`@keyframe_1\` and \`@last_frame\` for frames; with no media connected, both endpoints generate from the prompt alone. PixVerse V6 Max image-to-video follows the image's aspect ratio. OmniHuman 2.0 renders as long as its driving audio. The Kie Grok Imagine Video 1.5 preview takes first and last frames, a loop image (\`loop_url\`) and up to four timed \`keyframes\`, and shares the Grok Imagine Video 1.5 image-to-video ranking.
+
 Top-10 coverage policy: every registry endpoint must map exactly to a catalog entry or appear in the known gaps below. Models with no provider endpoint in the registry: ${unmapped.join(", ")}. Catalog gaps do not imply provider API support is missing; adding those endpoints is separate work.
 
 | Known endpoint gap | Reason |

package/dist/content-store.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { B2Error, createB2 } from "@apicity/b2";
+import { createB2 } from "./usage-providers.js";
+import { B2Error } from "@apicity/b2";
 function createB2ContentStore(config) {
     const provider = createB2({
         accessKeyId: config.accessKeyId,

package/dist/diagnostics.js

@@ -4,7 +4,7 @@ const EVENTS = [
     "book-open", "book-open-slow", "book-catalog-gc", "provider-poll-failed",
     "ace-server-exited", "scheduled-post-failed", "scheduled-post-rearm-failed",
     "generation-record-failed", "generation-update-failed", "generation-list-failed",
-    "provider-task-record-failed",
+    "provider-task-record-failed", "har-capture-failed",
     "prompt-record-failed",
     "waveform-empty", "waveform-failed", "heartbeat-failed", "subtitle-cache-failed",
     "subtitle-translation-failed", "overlay-skipped", "kie-upload-fallback",
@@ -14,7 +14,7 @@ const EVENTS = [
     "process-video-enqueue-failed", "waveform-write-failed", "timeline-reencode",
     "pad-video-started", "video-analysis-failed", "description-truncated",
     "description-cache-failed", "watermark-placement-fallback", "waveform-enqueue-failed",
-    "poster-enqueue-failed",
+    "poster-enqueue-failed", "proxy-assessment-enqueue-failed", "duration-backfill-enqueue-failed",
     "watermark-probe-fallback", "generation-error-clear-failed", "timeline-orientation-failed",
     "generation-cost-estimate", "job-error", "semantic-index-deferred",
     "tag-asset-failed", "voice-session-closed", "alive-captions-regions-failed",

package/dist/env-secrets.js

@@ -48,6 +48,7 @@ export const MANAGED_ENV_KEYS = [
     "B2_ARCHIVE_PREFIX",
 ];
 const NON_SECRET_ENV_KEYS = new Set([
+    "VIDEOBOOK_HAR_CAPTURE",
     "B2_REGION",
     "B2_BUCKET",
     "B2_ENDPOINT",