@indigoai-us/hq-cli 5.345.143 → 5.345.144

package/dist/commands/library.js

@@ -0,0 +1,527 @@
+/**
+ * `hq library search|add|tag|ls|fetch|describe|link` — the company media library.
+ * `add` and `tag` live in ./library-add.ts; AI captions (`add` and `describe`)
+ * live in ./library-caption.ts; `link` lives in ./library-link.ts; `fetch`
+ * wraps `hq storage fetch`.
+ *
+ * `hq library search <query> [--tag t] [--json]` — find library assets.
+ *
+ * A library asset is a `.hqcloud` placeholder (`vault: company`) that carries
+ * an `hq-asset` block: title, tags, description and media kind for a file whose
+ * bytes live in the company vault.
+ *
+ * Cloud first: POST /v1/search with `{ query, kind: "asset", tags }`. Under
+ * HQ_API_KEY vaultApiFetch rewrites the path to /v1/keys/search, and the server
+ * scopes results to the key's company. When the cloud cannot be reached (a
+ * transport failure, not an HTTP error), the command falls back to the local
+ * qmd index: the per-company `<co>-assets` collections (mask `**\/*.hqcloud`,
+ * see deriveCollections) searched with `--full`, so each hit's placeholder text
+ * can be parsed for its asset metadata.
+ *
+ * Wire contract (hq-pro US-007):
+ *   body    { query: string, kind: "asset", tags?: string[], company?: string }
+ *   200     { results: [{ title, snippet, metadata: { asset: {
+ *             placeholderPath, originalPath, title, tags, mediaKind, vaultKey } } }] }
+ *   400     { code: "INVALID_SEARCH_FILTER" }
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import chalk from "chalk";
+import { cloudPlaceholderPathFor, isCloudPlaceholderName, parseCloudPlaceholder, } from "@indigoai-us/hq-cloud";
+import { buildSearchArgs } from "./search.js";
+import { ASSET_COLLECTION_MASK, deriveCollections, runQmd, } from "../lib/search-index/index.js";
+import { findHqRoot } from "../utils/manifest.js";
+import { networkTransportErrorCode } from "../utils/network-transport-error.js";
+import { resolveVaultCredentialForCapability } from "../utils/resolve-vault-credential.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { defaultLibraryIo, runLibraryAdd, runLibraryTag, } from "./library-add.js";
+import { captionAddedAsset, extractCaptionFrames, runLibraryDescribe, runLocalClaude } from "./library-caption.js";
+import { LIBRARY_LINK_DEFAULT_MINUTES, LIBRARY_LINK_MAX_MINUTES, runLibraryLink } from "./library-link.js";
+/** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
+export const MAX_LIBRARY_SEARCH_TAGS = 20;
+const MAX_TAG_LENGTH = 100;
+/** Split repeatable / comma-listed `--tag` values into a validated tag list. */
+export function normalizeTags(values) {
+    const tags = [
+        ...new Set(values
+            .flatMap((value) => value.split(","))
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0)),
+    ];
+    if (tags.length > MAX_LIBRARY_SEARCH_TAGS) {
+        throw new Error(`At most ${MAX_LIBRARY_SEARCH_TAGS} --tag values are allowed.`);
+    }
+    const long = tags.find((tag) => tag.length > MAX_TAG_LENGTH);
+    if (long)
+        throw new Error(`Tag '${long.slice(0, 20)}…' is longer than ${MAX_TAG_LENGTH} characters.`);
+    return tags;
+}
+/** Case-insensitive: every requested tag must be on the asset (hq-pro assetHasTags). */
+export function hasAllTags(assetTags, wanted) {
+    const have = new Set(assetTags.map((tag) => tag.trim().toLowerCase()));
+    return wanted.every((tag) => have.has(tag.trim().toLowerCase()));
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Map one /v1/search result to a hit; null when it carries no asset metadata. */
+export function hitFromCloudResult(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const record = result;
+    const metadata = record.metadata;
+    const asset = metadata?.asset;
+    if (!asset || typeof asset !== "object")
+        return null;
+    const placeholderPath = asString(asset.placeholderPath);
+    if (!placeholderPath)
+        return null;
+    return {
+        placeholderPath,
+        originalPath: asString(asset.originalPath),
+        title: asString(asset.title) ?? asString(record.title) ?? placeholderPath,
+        tags: Array.isArray(asset.tags) ? asset.tags.filter((tag) => typeof tag === "string") : [],
+        mediaKind: asString(asset.mediaKind),
+        vaultKey: asString(asset.vaultKey),
+        snippet: asString(record.snippet),
+    };
+}
+/**
+ * Testable core. Cloud search first; a transport failure (offline, DNS, reset)
+ * falls back to the local qmd index. HTTP errors are not a fallback: a 401 or
+ * 400 is reported, since the local index cannot answer for the vault.
+ */
+export async function runLibrarySearch(query, options, deps) {
+    const trimmed = query.trim();
+    if (!trimmed && options.tags.length === 0) {
+        throw new Error("Pass a query, at least one --tag, or both.");
+    }
+    const body = { query: trimmed, kind: "asset" };
+    if (options.tags.length > 0)
+        body.tags = options.tags;
+    if (options.company)
+        body.company = options.company;
+    let res;
+    try {
+        const token = await deps.getToken();
+        res = await deps.post(token, body);
+    }
+    catch (err) {
+        const code = networkTransportErrorCode(err);
+        if (!code)
+            throw err;
+        return { source: "local", fallbackReason: code, results: deps.searchLocal(trimmed, options) };
+    }
+    const parsed = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        const msg = asString(parsed.error) ?? asString(parsed.message) ?? `HTTP ${res.status}`;
+        throw new Error(`Library search failed: ${msg}`);
+    }
+    const rows = Array.isArray(parsed.results) ? parsed.results : [];
+    let results = rows.map(hitFromCloudResult).filter((hit) => hit !== null);
+    if (options.count !== undefined)
+        results = results.slice(0, options.count);
+    return { source: "cloud", results };
+}
+/** A local hit, or null for a placeholder that is not a company library asset. */
+export function hitFromPlaceholder(placeholder, tags, snippet) {
+    if (!placeholder || placeholder.vault !== "company" || !placeholder.asset)
+        return null;
+    if (!hasAllTags(placeholder.asset.tags, tags))
+        return null;
+    return {
+        placeholderPath: cloudPlaceholderPathFor(placeholder.path),
+        originalPath: placeholder.path,
+        title: placeholder.asset.title ?? path.posix.basename(placeholder.path),
+        tags: placeholder.asset.tags,
+        mediaKind: placeholder.asset.media?.kind,
+        vaultKey: placeholder.key,
+        snippet: snippet ?? placeholder.asset.description,
+    };
+}
+/** Asset collections to search, narrowed to one company when asked. */
+export function assetCollections(collections, company) {
+    const wanted = company?.trim().toLowerCase();
+    return collections.filter((collection) => collection.mask === ASSET_COLLECTION_MASK &&
+        (!wanted || collection.name.toLowerCase() === `${wanted}-assets`));
+}
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+function walkPlaceholders(directory, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch (err) {
+        console.error(chalk.yellow(`Skipped ${directory}: ${err.message}`));
+        return;
+    }
+    for (const entry of entries) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walkPlaceholders(child, out);
+        }
+        else if (entry.isFile() && isCloudPlaceholderName(entry.name)) {
+            out.push(child);
+        }
+    }
+}
+/**
+ * Search the local qmd `<co>-assets` collections. With a query, qmd ranks
+ * hits and `--full` returns each placeholder's text (qmd normalises file
+ * paths, so the text, not the path, is the reliable record). Without a query
+ * (tags only), the collection directories are listed and filtered by tag.
+ */
+export function searchLocalAssets(query, options, env) {
+    const hits = [];
+    const seen = new Set();
+    const add = (hit) => {
+        if (!hit || seen.has(hit.placeholderPath))
+            return;
+        seen.add(hit.placeholderPath);
+        hits.push(hit);
+    };
+    for (const collection of assetCollections(env.collections, options.company)) {
+        if (query) {
+            const args = [
+                ...buildSearchArgs(query, { collection: collection.name, count: options.count, json: true }),
+                "--full",
+            ];
+            const { stdout, stderr } = env.runQmd(args);
+            let rows;
+            try {
+                rows = JSON.parse(stdout || "[]");
+            }
+            catch {
+                console.error(chalk.yellow(`Local search of ${collection.name} returned no usable results${stderr?.trim() ? `: ${stderr.trim()}` : "."}`));
+                continue;
+            }
+            if (!Array.isArray(rows))
+                continue;
+            for (const row of rows) {
+                const body = row?.body;
+                if (typeof body !== "string")
+                    continue;
+                add(hitFromPlaceholder(parseCloudPlaceholder(body), options.tags));
+            }
+        }
+        else {
+            for (const file of env.listPlaceholders(collection.path)) {
+                const text = env.readFile(file);
+                if (text !== null)
+                    add(hitFromPlaceholder(parseCloudPlaceholder(text), options.tags));
+            }
+        }
+    }
+    return options.count !== undefined ? hits.slice(0, options.count) : hits;
+}
+/**
+ * `hq library ls`: every company library placeholder under `directory`
+ * (HQ-relative paths), filtered by tag. Sorted by placeholder path.
+ */
+export function listLibraryAssets(hqRoot, directory, tags, env = defaultFileEnv()) {
+    const hits = [];
+    const root = fs.realpathSync(hqRoot);
+    for (const file of env.listPlaceholders(directory)) {
+        const text = env.readFile(file);
+        const hit = text === null ? null : hitFromPlaceholder(parseCloudPlaceholder(text), tags);
+        if (hit)
+            hits.push({ ...hit, placeholderPath: path.relative(root, file).split(path.sep).join("/") });
+    }
+    return hits;
+}
+function defaultFileEnv() {
+    return {
+        readFile: (file) => {
+            try {
+                return fs.readFileSync(file, "utf8");
+            }
+            catch (err) {
+                console.error(chalk.yellow(`Skipped ${file}: ${err.message}`));
+                return null;
+            }
+        },
+        listPlaceholders: (directory) => {
+            const out = [];
+            walkPlaceholders(directory, out);
+            return out.sort();
+        },
+    };
+}
+function defaultLocalEnv() {
+    const hqRoot = findHqRoot();
+    return {
+        collections: deriveCollections(hqRoot),
+        runQmd: (args) => runQmd(args, { cwd: hqRoot }),
+        ...defaultFileEnv(),
+    };
+}
+export function formatLibraryResult(result) {
+    const lines = [];
+    if (result.source === "local") {
+        lines.push(chalk.yellow(`HQ cloud unreachable (${result.fallbackReason}); showing local index results.`));
+    }
+    if (result.results.length === 0) {
+        lines.push("No library assets found.");
+        return lines.join("\n");
+    }
+    for (const hit of result.results) {
+        const media = hit.mediaKind ? chalk.dim(` [${hit.mediaKind}]`) : "";
+        lines.push(`${chalk.bold(hit.title)}${media}`);
+        lines.push(`  ${hit.placeholderPath}`);
+        if (hit.tags.length > 0)
+            lines.push(`  tags: ${hit.tags.join(", ")}`);
+        if (hit.vaultKey)
+            lines.push(chalk.dim(`  vault key: ${hit.vaultKey}`));
+    }
+    return lines.join("\n");
+}
+function collectTag(value, previous) {
+    return [...previous, value];
+}
+function formatHits(hits) {
+    return formatLibraryResult({ source: "cloud", results: [...hits] });
+}
+export function formatLibraryAddResult(result) {
+    return result.items
+        .map((item) => {
+        if (!item.ok)
+            return `${chalk.red("Not added")} ${item.source}: ${item.error}`;
+        const line = `${chalk.green("Added")} ${item.placeholderPath} ${chalk.dim(item.uploaded ? "(uploaded, sha256 verified)" : "(already in the vault, not uploaded again)")}`;
+        if (!item.caption)
+            return line;
+        if (item.caption.status === "captioned")
+            return `${line}\n  ${chalk.dim(`AI caption added (${item.caption.captionedBy}).`)}`;
+        return `${line}\n  ${chalk.yellow(item.caption.note ?? "Captioning skipped.")}`;
+    })
+        .join("\n");
+}
+/** GET a presigned URL. Errors never echo the URL, which carries a signature. */
+async function downloadPresigned(url) {
+    const res = await fetch(url);
+    if (!res.ok || !res.body)
+        throw new Error(`Could not download the asset (HTTP ${res.status}).`);
+    return Readable.fromWeb(res.body);
+}
+/** The active company membership for `slug`, via /membership/me. */
+async function libraryCompany(token, slug) {
+    const { companiesFromMemberships } = await import("./storage.js");
+    const res = await vaultApiFetch({ token, path: "/membership/me" });
+    if (!res.ok)
+        throw new Error(`Could not load your companies (HTTP ${res.status}). Run \`hq login\`.`);
+    const company = companiesFromMemberships(await res.json()).find((c) => c.slug === slug);
+    if (!company)
+        throw new Error(`You are not an active member of '${slug}'.`);
+    return { uid: company.uid, slug: company.slug };
+}
+export function registerLibraryCommand(program) {
+    const library = program
+        .command("library")
+        .description("Company media library (.hqcloud asset placeholders)");
+    library
+        .command("search")
+        .description("Search library assets in the cloud, falling back to the local index when offline")
+        .argument("[query...]", "Query terms (joined with spaces)")
+        .option("--tag <tag>", "Require a tag (repeatable or comma-separated)", collectTag, [])
+        .option("--company <slug>", "Restrict to one company")
+        .option("-n, --count <count>", "Maximum result count", (value) => Number(value))
+        .option("--json", "Print machine-readable JSON")
+        .action(async (queryParts = [], options) => {
+        try {
+            const searchOptions = {
+                tags: normalizeTags(options.tag ?? []),
+                company: options.company,
+                count: options.count,
+            };
+            const result = await runLibrarySearch(queryParts.join(" "), searchOptions, {
+                getToken: async () => (await resolveVaultCredentialForCapability("search:query", "library search", {
+                    interactive: true,
+                })).token,
+                post: (token, body) => vaultApiFetch({ token, path: "/v1/search", method: "POST", body }),
+                searchLocal: (query, opts) => searchLocalAssets(query, opts, defaultLocalEnv()),
+            });
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log(formatLibraryResult(result));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("add")
+        .description("Upload files or URLs to the company vault and add .hqcloud placeholders to the library")
+        .argument("<sources...>", "Local files or http(s) URLs")
+        .option("--to <dir>", "Library folder inside companies/<co>/ (default companies/<co>/library)")
+        .option("--tags <tags>", "Tags (comma-separated, repeatable)", collectTag, [])
+        .option("--title <title>", "Asset title (default: the file name)")
+        .option("--note <text>", "Asset description")
+        .option("--company <slug>", "Company whose vault receives the files")
+        .option("--no-caption", "Skip the AI description and suggested tags for images and videos")
+        .option("--json", "Print machine-readable JSON")
+        .action(async (sources, options) => {
+        try {
+            const { token } = await resolveVaultCredentialForCapability("files:write", "library add", {
+                interactive: true,
+            });
+            const result = await runLibraryAdd(sources, {
+                company: options.company,
+                to: options.to,
+                tags: normalizeTags(options.tags ?? []),
+                title: options.title,
+                note: options.note,
+            }, {
+                hqRoot: findHqRoot(),
+                now: () => new Date(),
+                resolveCompany: (slug) => libraryCompany(token, slug),
+                presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
+                ...defaultLibraryIo,
+                ...(options.caption === false
+                    ? {}
+                    : {
+                        caption: (request) => captionAddedAsset(request, {
+                            now: () => new Date(),
+                            openSource: defaultLibraryIo.openSource,
+                            runLocal: runLocalClaude,
+                            extractFrames: (file, kind) => extractCaptionFrames(file, kind),
+                        }),
+                    }),
+            });
+            console.log(options.json ? JSON.stringify(result, null, 2) : formatLibraryAddResult(result));
+            if (result.items.some((item) => !item.ok))
+                process.exitCode = 1;
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("tag")
+        .description("Add or remove tags on a library placeholder")
+        .argument("<placeholder>", "A .hqcloud placeholder (or the original path)")
+        .option("--add <tags>", "Tags to add (comma-separated, repeatable)", collectTag, [])
+        .option("--remove <tags>", "Tags to remove (comma-separated, repeatable)", collectTag, [])
+        .option("--json", "Print machine-readable JSON")
+        .action(async (target, options) => {
+        try {
+            const result = await runLibraryTag(findHqRoot(), target, {
+                add: normalizeTags(options.add ?? []),
+                remove: normalizeTags(options.remove ?? []),
+            });
+            console.log(options.json
+                ? JSON.stringify(result, null, 2)
+                : `${result.changed ? "Updated" : "No change to"} ${result.placeholderPath}: ${result.tags.length > 0 ? result.tags.join(", ") : "(no tags)"}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("ls")
+        .description("List library placeholders in a folder (default: companies/)")
+        .argument("[dir]", "Folder to list, relative to HQ")
+        .option("--tag <tag>", "Require a tag (repeatable or comma-separated)", collectTag, [])
+        .option("--json", "Print machine-readable JSON")
+        .action(async (dir, options) => {
+        try {
+            const { containedPath } = await import("./storage-offload.js");
+            const hqRoot = findHqRoot();
+            const hits = listLibraryAssets(hqRoot, containedPath(hqRoot, dir ?? "companies"), normalizeTags(options.tag ?? []));
+            console.log(options.json ? JSON.stringify({ results: hits }, null, 2) : formatHits(hits));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("describe")
+        .description("Re-run the AI description and suggested tags for a library image or video")
+        .argument("<placeholder>", "A .hqcloud placeholder (or the original path)")
+        .option("--json", "Print machine-readable JSON")
+        .action(async (target, options) => {
+        try {
+            const { token } = await resolveVaultCredentialForCapability("files:read", "library describe", {
+                interactive: true,
+            });
+            const result = await runLibraryDescribe(target, {
+                hqRoot: findHqRoot(),
+                now: () => new Date(),
+                resolveCompany: (slug) => libraryCompany(token, slug),
+                presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
+                download: downloadPresigned,
+                runLocal: runLocalClaude,
+                extractFrames: (file, kind) => extractCaptionFrames(file, kind),
+            });
+            console.log(options.json
+                ? JSON.stringify(result, null, 2)
+                : [
+                    `Described ${result.placeholderPath} ${chalk.dim(`(${result.captionedBy})`)}`,
+                    `  ${result.description}`,
+                    `  tags: ${result.tags.length > 0 ? result.tags.join(", ") : "(no tags)"}`,
+                ].join("\n"));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("fetch")
+        .description("Download a library asset next to its placeholder (wraps hq storage fetch)")
+        .argument("<placeholder>", "A .hqcloud placeholder (or the original path)")
+        .option("--json", "Print machine-readable JSON")
+        .action(async (target, options) => {
+        try {
+            const [{ buildOffloadDeps, formatBytes }, { runFetch }] = await Promise.all([
+                import("./storage.js"),
+                import("./storage-offload.js"),
+            ]);
+            const result = await runFetch(target, await buildOffloadDeps());
+            console.log(options.json
+                ? JSON.stringify(result, null, 2)
+                : `Restored ${result.path} (${formatBytes(result.bytes)}), checksum verified.`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    library
+        .command("link")
+        .description("Mint a short-lived download URL for a library asset (needs files:read)")
+        .argument("<target>", "A .hqcloud placeholder, its original path, or a vault key (.hq-offload/…)")
+        .option("--company <company>", "Company uid (cmp_…), or a slug on a session; default: the placeholder's company or the key's")
+        .option("--expires <minutes>", `Link lifetime in minutes, 1-${LIBRARY_LINK_MAX_MINUTES} (default ${LIBRARY_LINK_DEFAULT_MINUTES})`, (value) => Number(value))
+        .option("--json", "Print machine-readable JSON")
+        .action(async (target, options) => {
+        try {
+            const credential = await resolveVaultCredentialForCapability("files:read", "library link", {
+                interactive: true,
+            });
+            const { token } = credential;
+            const result = await runLibraryLink(target, { company: options.company, expiresMinutes: options.expires }, {
+                hqRoot: () => findHqRoot(),
+                apiKey: credential.kind === "api-key",
+                resolveCompany: (ref) => getCompanyUid(token, ref),
+                presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
+            });
+            // The URL is the only stdout line (or the JSON), so scripts can capture it.
+            console.log(options.json ? JSON.stringify(result, null, 2) : result.url);
+            console.error(chalk.dim(`Link expires ${result.expiresAt ?? `in ${Math.round(result.expiresIn / 60)} min`}. ` +
+                "Anyone with it can download the file — never post it in Slack or shared channels."));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=library.js.map

package/dist/commands/meetings.d.ts

@@ -1,5 +1,13 @@
 import { Command } from "commander";
+import { type PricingPlan } from "../lib/billing/usage-only.js";
 /** Upper bound on list pages one short-id lookup reads (per cursor chain). */
 export declare const SHORT_ID_MAX_PAGES = 50;
+/**
+ * The 402 copy for meeting bots. A usage-only company (US-012: the body or the
+ * company's billing summary says `pricingPlan: "usage-only"`) has no Workforce
+ * plan to buy, so it is told to add a card. Every other company keeps the
+ * Workforce copy.
+ */
+export declare function meetingPaymentRequiredLines(body: Record<string, unknown>, resolvePlan?: () => Promise<PricingPlan | null>): Promise<string[]>;
 export declare function registerMeetingsCommand(program: Command): void;
 //# sourceMappingURL=meetings.d.ts.map

package/dist/commands/meetings.js

@@ -4,6 +4,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 import { isPlanGateError, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
 import { mapWithConcurrency } from "./sync-manifest.js";
+import { isUsageOnly, pricingPlanFromBody, resolveCompanyPricingPlan, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
 const LIVE_SNAPSHOT_STATUSES = new Set([
     "joining",
     "recording",
@@ -316,6 +317,27 @@ async function resolveShortId(token, prefix, query) {
         : `No meeting matches ID "${prefix}". It may still be processing or attributed to a different company. Pass the full meeting id, or add --company <slug>.`));
     process.exit(1);
 }
+/**
+ * The 402 copy for meeting bots. A usage-only company (US-012: the body or the
+ * company's billing summary says `pricingPlan: "usage-only"`) has no Workforce
+ * plan to buy, so it is told to add a card. Every other company keeps the
+ * Workforce copy.
+ */
+export async function meetingPaymentRequiredLines(body, resolvePlan = () => resolveCompanyPricingPlan()) {
+    const plan = pricingPlanFromBody(body) ?? (await resolvePlan().catch(() => null));
+    if (isUsageOnly(plan)) {
+        return usageOnlyCardRequiredLines("A meeting notetaker bot").map((line, i) => i === 0 ? chalk.red(line) : chalk.dim(line));
+    }
+    const detail = typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+            ? body.error
+            : "Upgrade your company to HQ Workforce to record meetings.";
+    return [
+        chalk.red("Meeting notetaker bots require the $500/mo HQ Workforce plan."),
+        chalk.dim(detail),
+    ];
+}
 async function handleApiError(res, json = false) {
     const body = (await res.json().catch(() => ({})));
     const planGate = planGateErrorFromPayload(res.status, body);
@@ -334,8 +356,9 @@ async function handleApiError(res, json = false) {
         console.error(chalk.red(body.error ?? "Not found"));
     }
     else if (res.status === 402) {
-        console.error(chalk.red("Meeting notetaker bots require the $500/mo HQ Workforce plan."));
-        console.error(chalk.dim(body.message ?? body.error ?? "Upgrade your company to HQ Workforce to record meetings."));
+        for (const line of await meetingPaymentRequiredLines(body)) {
+            console.error(line);
+        }
     }
     else {
         console.error(chalk.red(`API error (${res.status}): ${body.error ?? res.statusText}`));

package/dist/commands/storage-offload.d.ts

@@ -96,19 +96,33 @@ export interface Pointer {
     /** Set by sync when a teammate deleted the remote file. */
     orphaned?: boolean;
 }
-export declare function renderPointer(p: Pointer): string;
+/** Company-vault key for library bytes: content-addressed by sha256, relative to the company bucket. */
+export declare function companyOffloadKey(sha256: string): string;
+/**
+ * Render a placeholder. `assetBlock` is the fenced `hq-asset` metadata block
+ * (from hq-cloud's `formatCloudAssetBlock`) that `hq library add` appends after
+ * the footer so the placeholder is a searchable library asset.
+ */
+export declare function renderPointer(p: Pointer, assetBlock?: string): string;
 /** ETags compare without the surrounding quotes S3 returns. */
 export declare function normalizeEtag(etag: string | undefined): string;
 /**
  * Parse pointer text. Returns null for anything that is not a valid v1 pointer.
  *
- * Two shapes are valid:
+ * Three shapes are valid:
  *   - an offload copy: `vault: personal`, key = offloadKey(git-blob), with a
  *     git blob id to verify against;
+ *   - a library copy: `vault: company`, key = companyOffloadKey(sha256), with
+ *     the sha256 to verify against (written by `hq library add`);
  *   - a vault object recorded by sync: either vault, a non-offload key, and a
  *     `remote-etag` to verify against (sha256 may be `unknown`).
  */
 export declare function parsePointer(text: string): Pointer | null;
+/**
+ * Library copy in a company vault: content-addressed under
+ * `.hq-offload/blobs/<sha256>`, verified by that sha256 (no git blob, no ETag).
+ */
+export declare function isCompanyOffloadCopy(p: Pointer): boolean;
 export interface FileDigest {
     size: number;
     sha256: string;