@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/dist/commands/api-keys.js

@@ -1,14 +1,57 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { assertCognitoOnlyCommand } from "../utils/resolve-vault-credential.js";
+import { API_KEY_CAPABILITIES, CLI_API_KEY_CAPABILITIES, DEPLOY_APP_ALL, isApiKeyCapability, requireApiKeyCapability, unusableApiKeyCapabilities, } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+/**
+ * Key administration is Cognito-only: no capability in the catalog grants
+ * minting, listing, or revoking keys, so a key can never widen itself.
+ */
 async function requireCognitoForApiKeys(label) {
-    assertCognitoOnlyCommand(label);
+    requireApiKeyCapability(null, label);
     return ensureCognitoToken();
 }
 function collectRepeatedOption(value, previous) {
     return [...previous, value];
 }
+/**
+ * Parse repeated `--capability` values. Comma-separated values are accepted in
+ * one flag too, so `--capability files:read,search:query` and two flags agree.
+ * Unknown names are rejected locally with the catalog (the server rejects them
+ * too — this just saves a round trip and names the valid set).
+ */
+function parseCapabilities(values) {
+    const parsed = [];
+    for (const raw of values) {
+        for (const entry of raw.split(",")) {
+            const cap = entry.trim();
+            if (!cap)
+                continue;
+            if (!isApiKeyCapability(cap)) {
+                throw new Error(`Unknown capability '${cap}'. Supported: ${API_KEY_CAPABILITIES.join(", ")}`);
+            }
+            parsed.push(cap);
+        }
+    }
+    return [...new Set(parsed)];
+}
+function hasDeployCapability(capabilities) {
+    return capabilities.some((cap) => cap === "deploy:write" || cap === "deploy:read");
+}
+/**
+ * Deploy apps for the mint body. A deploy-capable key with no `--deploy-app`
+ * narrowing defaults to `["*"]` — every app its owner can reach at use time —
+ * matching hq-pro's `parseDeployScope`. `--deploy-app` still narrows to ids.
+ */
+function resolveDeployApps(deployApp) {
+    const apps = [...new Set(deployApp.map((app) => app.trim()).filter(Boolean))];
+    if (apps.length === 0 || apps.includes(DEPLOY_APP_ALL)) {
+        return [DEPLOY_APP_ALL];
+    }
+    return apps;
+}
+function formatCapabilities(capabilities) {
+    return capabilities && capabilities.length > 0 ? capabilities.join(", ") : "-";
+}
 function formatMaybe(value) {
     return value ?? "-";
 }
@@ -60,6 +103,7 @@ function renderApiKeysTable(apiKeys) {
         keyId: apiKey.keyId,
         name: apiKey.name,
         permission: apiKey.scope.permission,
+        capabilities: formatCapabilities(apiKey.scope.capabilities),
         prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
         deployApps: formatDeployApps(apiKey.scope.deploy),
         status: apiKey.status,
@@ -69,6 +113,7 @@ function renderApiKeysTable(apiKeys) {
     const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
     const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
     const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
+    const capabilitiesWidth = Math.max(12, ...rows.map((row) => row.capabilities.length));
     const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
     const deployWidth = Math.max(6, ...rows.map((row) => row.deployApps.length));
     const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
@@ -78,6 +123,7 @@ function renderApiKeysTable(apiKeys) {
         "KEY ID".padEnd(keyIdWidth),
         "NAME".padEnd(nameWidth),
         "PERMISSION".padEnd(permissionWidth),
+        "CAPABILITIES".padEnd(capabilitiesWidth),
         "PREFIXES".padEnd(prefixesWidth),
         "DEPLOY".padEnd(deployWidth),
         "STATUS".padEnd(statusWidth),
@@ -90,6 +136,7 @@ function renderApiKeysTable(apiKeys) {
             row.keyId.padEnd(keyIdWidth),
             row.name.padEnd(nameWidth),
             row.permission.padEnd(permissionWidth),
+            row.capabilities.padEnd(capabilitiesWidth),
             row.prefixes.padEnd(prefixesWidth),
             row.deployApps.padEnd(deployWidth),
             row.status.padEnd(statusWidth),
@@ -107,17 +154,40 @@ export function registerApiKeysCommand(program) {
         .command("create")
         .description("Create a new API key (vault secrets and/or scoped deploy via --deploy-app)")
         .requiredOption("--name <label>", "Human-readable label for the API key")
-        .option("--scope <prefix>", "Allowed secret prefix (repeatable)", collectRepeatedOption, [])
-        .option("--deploy-app <id>", "Deploy app id/slug allowed for publish (repeatable)", collectRepeatedOption, [])
-        .option("--permission <level>", "Secret permission level: read | write | admin (required when --scope is set)", "read")
+        .option("--scope <prefix>", "Secret scope (repeatable): exact name or slash descendants (FOO or FOO/...), not underscore siblings (FOO_BAR)", collectRepeatedOption, [])
+        .option("--capability <cap>", `Capability to grant (repeatable, comma-separated ok): ${API_KEY_CAPABILITIES.join(" | ")}`, collectRepeatedOption, [])
+        .option("--deploy", `Grant deploy:write over all apps the owner can reach (apps ${DEPLOY_APP_ALL}); narrow with --deploy-app`)
+        .option("--deploy-app <id>", "Deploy app id/slug allowed for publish (repeatable); narrows the deploy grant", collectRepeatedOption, [])
+        .option("--permission <level>", "Secret permission level: read | write | admin (applies to secret scopes; defaults to read)")
         .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
         .action(async (opts) => {
         try {
-            if (opts.scope.length === 0 && opts.deployApp.length === 0) {
-                console.error(chalk.red("Error: provide at least one --scope <prefix> and/or --deploy-app <id>."));
+            const capabilities = parseCapabilities(opts.capability);
+            const wantsDeploy = hasDeployCapability(capabilities) ||
+                opts.deploy === true ||
+                opts.deployApp.length > 0;
+            const wantsSecrets = opts.scope.length > 0 ||
+                capabilities.some((cap) => cap.startsWith("secrets:"));
+            if (capabilities.length === 0 && opts.scope.length === 0 && !wantsDeploy) {
+                console.error(chalk.red("Error: provide at least one --capability <cap>, --scope <prefix>, --deploy, and/or --deploy-app <id>."));
+                process.exit(1);
+            }
+            const explicitPermission = opts.permission !== undefined
+                ? parsePermission(opts.permission)
+                : undefined;
+            if (explicitPermission !== undefined && !wantsSecrets) {
+                console.error(chalk.red("Error: --permission applies to secrets only — pass --scope <prefix> or a secrets:* --capability."));
                 process.exit(1);
             }
-            const permission = parsePermission(opts.permission);
+            // Secret scopes keep their historical default of read. With only
+            // secrets:* capabilities and no explicit level, hq-pro derives it
+            // (write for secrets:write/secrets:share, else read).
+            const permission = explicitPermission ??
+                (opts.scope.length > 0 ? parsePermission("read") : undefined);
+            // Deploy capabilities travel in BOTH `capabilities` (catalog) and
+            // `deploy.capabilities` (app-scoped block) — hq-pro reads the latter
+            // for app authorization and defaults to deploy:write.
+            const deployCapabilities = capabilities.filter((cap) => cap === "deploy:write" || cap === "deploy:read");
             const expiresAt = parseExpires(opts.expires);
             const token = await requireCognitoForApiKeys("api-keys create");
             const companyUid = await getCompanyUid(token, apiKeys.opts().company);
@@ -128,20 +198,19 @@ export function registerApiKeysCommand(program) {
                 body: {
                     companyUid,
                     name: opts.name,
-                    ...(opts.scope.length > 0
-                        ? { allowedPrefixes: opts.scope, permission }
-                        : {}),
-                    ...(opts.deployApp.length > 0
+                    ...(capabilities.length > 0 ? { capabilities } : {}),
+                    ...(opts.scope.length > 0 ? { allowedPrefixes: opts.scope } : {}),
+                    ...(permission !== undefined ? { permission } : {}),
+                    ...(wantsDeploy
                         ? {
                             deploy: {
-                                apps: opts.deployApp,
-                                capabilities: ["deploy:write"],
+                                apps: resolveDeployApps(opts.deployApp),
+                                capabilities: deployCapabilities.length > 0
+                                    ? deployCapabilities
+                                    : ["deploy:write"],
                             },
                         }
                         : {}),
-                    ...(opts.scope.length === 0 && opts.deployApp.length > 0
-                        ? { permission }
-                        : {}),
                     ...(expiresAt ? { expiresAt } : {}),
                 },
             });
@@ -157,6 +226,7 @@ export function registerApiKeysCommand(program) {
             console.log(`  Name: ${data.apiKey.name}`);
             console.log(`  Company: ${data.apiKey.companyUid}`);
             console.log(`  Permission: ${data.apiKey.scope.permission}`);
+            console.log(`  Capabilities: ${formatCapabilities(data.apiKey.scope.capabilities ?? capabilities)}`);
             console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
             console.log(`  Deploy apps: ${formatDeployApps(data.apiKey.scope.deploy)}`);
             console.log(`  Status: ${data.apiKey.status}`);
@@ -166,18 +236,28 @@ export function registerApiKeysCommand(program) {
             console.log("");
             console.log(chalk.bold("Usage"));
             console.log("  This key acts as you (Cognito identity), limited to the scopes above.");
+            if (data.apiKey.scope.allowedPrefixes.length > 0) {
+                console.log(chalk.dim("  Secret scopes allow the exact name and slash descendants only (FOO and FOO/...), not FOO_BAR."));
+            }
             console.log("  Export it for automation (never falls back to a session):");
             console.log(`\n  export HQ_API_KEY='${data.key.value}'\n`);
             console.log("  Vault secrets:");
             console.log("    hq secrets get <NAME> --reveal");
             console.log("    hq secrets exec --only <NAME> -- <command>");
+            console.log("    hq secrets list --company <cmp_uid>   (secrets:read)");
+            console.log("    hq secrets set <NAME> --from-stdin --company <cmp_uid>   (secrets:write)");
             console.log("    Or HTTP: POST /v1/keys/secrets/fetch with Authorization: Bearer <key>");
+            console.log(chalk.dim("    Company-scoped commands need --company <cmp_uid> (or HQ_COMPANY_UID) — slug lookup needs a session."));
             if (data.apiKey.scope.deploy?.apps?.length) {
-                console.log("  Deploy (scoped apps only):");
-                console.log("    Authorization: Bearer <key> against the hq-deploy API");
+                const deployApps = data.apiKey.scope.deploy.apps;
+                console.log(deployApps.includes(DEPLOY_APP_ALL)
+                    ? "  Deploy (every app the key owner can access):"
+                    : "  Deploy (scoped apps only):");
+                console.log("    Authorization: Bearer <key> against https://api.indigo-hq.com");
                 console.log(chalk.dim("    Cannot change access-mode, password, or mint hqd_ keys."));
             }
-            console.log(chalk.dim("  Unsupported under HQ_API_KEY: secrets list/set/share/acl (use a Cognito session)."));
+            console.log(chalk.dim(`  Usable in hq-cli with HQ_API_KEY: ${CLI_API_KEY_CAPABILITIES.join(", ")}.`));
+            console.log(chalk.dim(`  Cognito session still required for: ${unusableApiKeyCapabilities().join(", ")} (deploy:* is consumed by hq-deploy).`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));

package/dist/commands/core.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `hq core <name>` — hidden host for HQ scaffold scripts that ship inside this
+ * package rather than inside the user's HQ tree.
+ *
+ * ## Why hidden
+ *
+ * These are not a public CLI surface. Every one of them is invoked by an HQ
+ * skill, hook, or another script — never typed by a person — and several are
+ * maintainer tools that would be actively harmful if a user ran them against
+ * their own install by mistake. Hiding them keeps `hq --help` describing the
+ * product rather than its plumbing. Hidden is discoverability control, not
+ * authorization: `hq core <name>` still dispatches normally, and
+ * `hq core --help` still lists the group's own contents.
+ *
+ * ## Why a manifest
+ *
+ * The direct commands and indexed rebuild targets each come from data tables,
+ * rather than one hand-written action per asset. The target table keeps all ten
+ * rebuilders behind one command while retaining the one-to-one asset mapping.
+ * It also gives the packaging test something to iterate: every entry must
+ * resolve to a real bundled asset.
+ *
+ * ## Root binding is per-entry and load-bearing
+ *
+ * Each entry declares how its ORIGINAL script found its root, and the wrapper
+ * reproduces exactly that. `"live"` scripts had a self-location fallback, so the
+ * CLI resolves and injects a root; `"cwd"` scripts had none — they read the
+ * caller's cwd — so the CLI injects nothing and leaves them in it. See
+ * `ScaffoldRoot`.
+ */
+import { Command } from "commander";
+/**
+ * Which tree a scaffold script operates on, mirroring how the ORIGINAL script
+ * found its root before it moved. Getting this wrong is not cosmetic: injecting a
+ * root into a script that derived one from cwd silently retargets it.
+ *
+ *   "live"  The original fell back to its own location inside the HQ tree
+ *           (`${HQ_ROOT:-$(dirname $0)/../..}`). The CLI resolves the live root
+ *           and exports it, reproducing that fallback.
+ *
+ *   "cwd"   The original derived its root from the CALLER's cwd
+ *           (`git rev-parse --show-toplevel || pwd`, a cwd walk, or an argument).
+ *           The CLI injects NOTHING and runs it in the caller's cwd, so it keeps
+ *           resolving exactly as it always did. Any root the caller already has in
+ *           the environment still wins, because the environment passes through
+ *           untouched.
+ *
+ * There is deliberately no "source" mode: release-source tooling — the linters,
+ * generators, and validators that rewrite checked-in artifacts — stays
+ * scaffold-owned. hq-core's own CI executes those directly, so hosting them here
+ * would mean a linter fix could not be validated until a CLI release was
+ * published. See the scaffold-vs-cli-code-ownership policy.
+ */
+export type ScaffoldRoot = "live" | "cwd";
+type ScaffoldAsset = {
+    /** Path under `assets/scaffold/`. */
+    asset: string;
+    /** Which tree this script reads and writes. */
+    root: ScaffoldRoot;
+    /** One-line summary, shown in `hq core --help`. */
+    summary: string;
+};
+export type ScaffoldCommand = ScaffoldAsset & {
+    /** Direct subcommand name — `hq core <name>`. */
+    name: string;
+};
+export type RebuildIndexTarget = ScaffoldAsset & {
+    /** Rebuild target — `hq core rebuild-index <target>`. */
+    target: string;
+};
+/**
+ * The ten index rebuild targets. The command registration below intentionally
+ * loops over this table for lookup, so adding a target never requires another
+ * action handler and every target retains its own bundled asset.
+ */
+export declare const REBUILD_INDEX_TARGETS: RebuildIndexTarget[];
+/**
+ * The relocated scaffold scripts with direct `hq core <name>` commands.
+ *
+ * Ordering is by group, then alphabetical, so a reader can see the shape of
+ * what moved. Names match the original script basenames minus the extension,
+ * because every existing caller already refers to them that way and a rename
+ * would make the forwarders harder to audit against this table.
+ */
+export declare const SCAFFOLD_COMMANDS: ScaffoldCommand[];
+/** Every bundled asset, used by packaging and interpreter tests. */
+export declare const SCAFFOLD_ASSETS: ScaffoldAsset[];
+export declare function registerCoreCommands(program: Command): Command;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/commands/core.js

@@ -0,0 +1,279 @@
+/**
+ * `hq core <name>` — hidden host for HQ scaffold scripts that ship inside this
+ * package rather than inside the user's HQ tree.
+ *
+ * ## Why hidden
+ *
+ * These are not a public CLI surface. Every one of them is invoked by an HQ
+ * skill, hook, or another script — never typed by a person — and several are
+ * maintainer tools that would be actively harmful if a user ran them against
+ * their own install by mistake. Hiding them keeps `hq --help` describing the
+ * product rather than its plumbing. Hidden is discoverability control, not
+ * authorization: `hq core <name>` still dispatches normally, and
+ * `hq core --help` still lists the group's own contents.
+ *
+ * ## Why a manifest
+ *
+ * The direct commands and indexed rebuild targets each come from data tables,
+ * rather than one hand-written action per asset. The target table keeps all ten
+ * rebuilders behind one command while retaining the one-to-one asset mapping.
+ * It also gives the packaging test something to iterate: every entry must
+ * resolve to a real bundled asset.
+ *
+ * ## Root binding is per-entry and load-bearing
+ *
+ * Each entry declares how its ORIGINAL script found its root, and the wrapper
+ * reproduces exactly that. `"live"` scripts had a self-location fallback, so the
+ * CLI resolves and injects a root; `"cwd"` scripts had none — they read the
+ * caller's cwd — so the CLI injects nothing and leaves them in it. See
+ * `ScaffoldRoot`.
+ */
+import { Option } from "commander";
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+/**
+ * The ten index rebuild targets. The command registration below intentionally
+ * loops over this table for lookup, so adding a target never requires another
+ * action handler and every target retains its own bundled asset.
+ */
+export const REBUILD_INDEX_TARGETS = [
+    {
+        target: "all",
+        asset: "core/scripts/rebuild-all-indexes.sh",
+        root: "live",
+        summary: "Regenerate every INDEX.md across the HQ tree",
+    },
+    {
+        target: "companies",
+        asset: "core/scripts/rebuild-companies-index.sh",
+        root: "live",
+        summary: "Regenerate companies/INDEX.md",
+    },
+    {
+        target: "company-knowledge",
+        asset: "core/scripts/rebuild-company-knowledge-index.sh",
+        root: "live",
+        summary: "Regenerate a company's knowledge INDEX.md",
+    },
+    {
+        target: "orchestrator",
+        asset: "core/scripts/rebuild-orchestrator-index.sh",
+        root: "live",
+        summary: "Regenerate the orchestrator workspace INDEX.md",
+    },
+    {
+        target: "projects",
+        asset: "core/scripts/rebuild-projects-index.sh",
+        root: "live",
+        summary: "Regenerate the projects INDEX.md",
+    },
+    {
+        target: "public-knowledge",
+        asset: "core/scripts/rebuild-public-knowledge-index.sh",
+        root: "live",
+        summary: "Regenerate core/knowledge/public/INDEX.md",
+    },
+    {
+        target: "reports",
+        asset: "core/scripts/rebuild-reports-index.sh",
+        root: "live",
+        summary: "Regenerate the reports INDEX.md",
+    },
+    {
+        target: "social-drafts",
+        asset: "core/scripts/rebuild-social-drafts-index.sh",
+        root: "live",
+        summary: "Regenerate workspace/social-drafts/INDEX.md",
+    },
+    {
+        target: "threads",
+        asset: "core/scripts/rebuild-threads-index.sh",
+        root: "live",
+        summary: "Regenerate the session-threads INDEX.md",
+    },
+    {
+        target: "workers",
+        asset: "core/scripts/rebuild-workers-index.sh",
+        root: "live",
+        summary: "Regenerate the workers INDEX.md",
+    },
+];
+/**
+ * The relocated scaffold scripts with direct `hq core <name>` commands.
+ *
+ * Ordering is by group, then alphabetical, so a reader can see the shape of
+ * what moved. Names match the original script basenames minus the extension,
+ * because every existing caller already refers to them that way and a rename
+ * would make the forwarders harder to audit against this table.
+ */
+export const SCAFFOLD_COMMANDS = [
+    // ---- One-shot migrations and maintenance (live tree) ----
+    {
+        name: "archive-old-threads",
+        asset: "core/scripts/archive-old-threads.sh",
+        root: "live",
+        summary: "Archive aged session-thread files",
+    },
+    {
+        name: "backfill-company-skill-mirrors",
+        asset: "core/scripts/backfill-company-skill-mirrors.sh",
+        root: "cwd",
+        summary: "One-shot: mirror company skills into place",
+    },
+    {
+        name: "backfill-workspace-mirror",
+        asset: "core/scripts/backfill-workspace-mirror.sh",
+        root: "cwd",
+        summary: "One-shot: mirror threads into company workspaces",
+    },
+    {
+        name: "detect-stale-core-policy-mirror",
+        asset: "core/scripts/detect-stale-core-policy-mirror.sh",
+        root: "live",
+        summary: "Find (and prune) stale personal-policy mirrors in core",
+    },
+    {
+        name: "qmd-reindex-after-sync",
+        asset: "core/scripts/qmd-reindex-after-sync.sh",
+        root: "cwd",
+        summary: "Refresh qmd collections after a sync",
+    },
+    // ---- Reporting and utilities (live tree) ----
+    {
+        name: "codex-skill-bridge",
+        asset: "core/scripts/codex-skill-bridge.sh",
+        root: "live",
+        summary: "Install/inspect the Codex skill bridge",
+    },
+    {
+        name: "hq-status-summary",
+        asset: "core/scripts/hq-status-summary.sh",
+        root: "cwd",
+        summary: "Summarize working-tree status across the HQ tree",
+    },
+    {
+        name: "ontology-readme-drift",
+        asset: "core/scripts/ontology-readme-drift.sh",
+        root: "live",
+        summary: "Check a company's ontology README for drift",
+    },
+    {
+        name: "resize-screenshot",
+        asset: "core/scripts/resize-screenshot.sh",
+        root: "cwd",
+        summary: "Downscale a screenshot for context efficiency",
+    },
+    {
+        name: "token-usage-report",
+        asset: "core/scripts/token-usage-report.sh",
+        root: "cwd",
+        summary: "Report session token usage",
+    },
+    {
+        name: "worktree",
+        asset: "core/scripts/worktree.sh",
+        root: "live",
+        summary: "Create a git worktree under workspace/worktrees/",
+    },
+];
+/** Every bundled asset, used by packaging and interpreter tests. */
+export const SCAFFOLD_ASSETS = [
+    ...REBUILD_INDEX_TARGETS,
+    ...SCAFFOLD_COMMANDS,
+];
+/**
+ * Resolve the tree an entry runs against, and the cwd to run it in.
+ *
+ * For "live" entries cwd is set to the resolved root, reproducing the
+ * self-location fallback the original script had when it lived in the tree.
+ *
+ * For "cwd" entries nothing is resolved and nothing is injected. Those scripts
+ * derived their root from the caller's cwd — `git rev-parse --show-toplevel ||
+ * pwd`, a cwd walk, or a positional argument — and injecting a root would
+ * retarget them at the tree the CLI happens to be near instead of the tree the
+ * caller is standing in. That regression is not hypothetical: it made four
+ * release linters silently lint the real checkout instead of the fixture holding
+ * the violation they were asked to catch, so they reported clean and their tests
+ * failed with "should fail the lint, but it passed".
+ */
+function resolveEntryRoot(entry, scope) {
+    if (entry.root === "cwd") {
+        if (scope.hqRoot) {
+            // An explicit override is still honored — it is the caller asking for it.
+            const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
+            return { cwd: hqRoot, hqRoot };
+        }
+        return { cwd: process.cwd() };
+    }
+    const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
+    return { cwd: hqRoot, hqRoot };
+}
+function runEntry(entry, scope, args) {
+    const { cwd, hqRoot } = resolveEntryRoot(entry, scope);
+    const { code } = runBundledScript({
+        asset: entry.asset,
+        args,
+        cwd,
+        hqRoot,
+    });
+    // Propagate verbatim. Several of these scripts use their exit code as their
+    // interface (drift detected, lint failed), so remapping it would break the
+    // caller's contract.
+    if (code !== 0)
+        process.exit(code);
+}
+function expectedUserError(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+export function registerCoreCommands(program) {
+    const core = program
+        .command("core", { hidden: true })
+        .description("HQ scaffold scripts hosted by the CLI (core; not a stable surface)")
+        // The root override lives on the GROUP, not the subcommands, so it can never
+        // collide with a wrapped script's own flags — everything after the
+        // subcommand name is passed through untouched.
+        .addOption(new Option("--hq-root <path>", "HQ installation to operate on (live-root commands)").hideHelp());
+    const runCommand = (entry, args = [], cmd, target) => {
+        const scope = core.opts();
+        // `cmd.args` is the authoritative operand list: with
+        // allowUnknownOption() it retains unknown flags in their original order,
+        // which the declared variadic argument alone does not guarantee.
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        const passthrough = target === undefined ? operands : operands.slice(1);
+        runEntry(entry, scope, passthrough);
+    };
+    const validTargets = REBUILD_INDEX_TARGETS.map((entry) => entry.target);
+    core
+        .command("rebuild-index <target> [args...]")
+        .description(`Regenerate one index (target: ${validTargets.join(", ")})`)
+        // Pure passthrough: the wrapped script owns its own argument grammar, so
+        // Commander must not interpret, validate, or reorder anything after the
+        // target name.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .helpOption(false)
+        .action((target, args = [], _opts, cmd) => {
+        const entry = REBUILD_INDEX_TARGETS.find((candidate) => candidate.target === target);
+        if (!entry) {
+            throw expectedUserError(`Unknown rebuild-index target "${target}". Valid targets: ${validTargets.join(", ")}.`);
+        }
+        runCommand(entry, args, cmd, target);
+    });
+    for (const entry of SCAFFOLD_COMMANDS) {
+        core
+            .command(entry.name)
+            .description(entry.summary)
+            // Pure passthrough: the wrapped script owns its own argument grammar, so
+            // Commander must not interpret, validate, or reorder anything after the
+            // subcommand name.
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments passed through to the script")
+            .action((args = [], _opts, cmd) => {
+            runCommand(entry, args, cmd);
+        });
+    }
+    return core;
+}
+//# sourceMappingURL=core.js.map

package/dist/commands/files-browse.d.ts

@@ -412,6 +412,27 @@ export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;
 }): FilesBrowseS3Client;
+/**
+ * `FilesBrowseVaultClient` for a Bearer `hqk_` key.
+ *
+ * `VaultClient` talks to the Cognito-JWT routes directly — it never passes
+ * through `vaultApiFetch`, so it cannot be handed an `hqk_` token: the key
+ * would arrive at a JWT-only route and come back as a 401 that reads like the
+ * caller is logged out. Company browse/cat/get/search need only three things
+ * from the client, and each has a keyed answer:
+ *
+ *   - the company uid — supplied explicitly (`--company cmp_…` or
+ *     HQ_COMPANY_UID). A key is company-bound and entity slug resolution has no
+ *     keyed route, so a slug is refused rather than guessed.
+ *   - the bucket name — unused on this path (see the constant above).
+ *   - the caller's explicit grants — `GET /v1/keys/files/grants` (files:read),
+ *     so the `shared-with-you` vs `role-bypass` column stays accurate.
+ *
+ * The identity surfaces a key cannot reach (`sts.vend`/`vendSelf` for the
+ * personal vault, `entity.get`, `listMyMemberships` for the cross-company
+ * roll-up) throw a fail-closed error naming the Cognito requirement.
+ */
+export declare function createApiKeyBrowseVaultClient(token: string): FilesBrowseVaultClient & FilesSharedWithMeVaultClient;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group