@indigoai-us/hq-cli 5.29.0 → 5.31.0

package/.claude/policies/hq-cli-interactive-reads-use-sts-vend.md

@@ -0,0 +1,49 @@
+---
+id: hq-cli-interactive-reads-use-sts-vend
+title: Interactive vault reads vend via /sts/vend, never the legacy POST /vend
+scope: repo
+trigger: any hq-cli command that vends vault credentials to read/list company objects (files browse, files cat, files get/search, or any new interactive read surface)
+enforcement: hard
+public: false
+version: 1
+created: 2026-05-29
+updated: 2026-05-29
+source: back-pressure-failure
+applies_to: [aws]
+---
+
+## Rule
+
+Interactive vault reads in hq-cli MUST vend through the multi-tenant STS
+routes — `VaultClient.sts.vend({ companyUid })` (`POST /sts/vend`, company) or
+`VaultClient.sts.vendSelf({ personUid })` (`POST /sts/vend-self`, personal).
+NEVER vend through the legacy `VaultClient.vend(...)` (`POST /vend`).
+
+The legacy `POST /vend` (hq-pro `VaultVendFunction` → `vend.handler`) builds
+its IAM policy against a static `process.env.BUCKET_ARN`, but the hq-pro infra
+(`infra/vault-service.ts`) deliberately does NOT set `BUCKET_ARN` — production
+is multi-tenant with one bucket per company. At runtime `BUCKET_ARN` is
+`undefined`, so the session policy contains `"Resource":[null,"undefined/…"]`
+and STS rejects it with `MalformedPolicyDocument: Syntax error at position
+(-1,-1)` → the client sees a 500 "Failed to generate credentials". Only
+`/sts/vend{,-self,-child}` resolve the per-entity bucket (`entity.bucketArn`)
+and apply role/ACL scoping server-side (owner/admin → full access; member/
+guest → per-prefix). `policy-builder.ts` even documents that `POST /vend` "has
+no production callers" — treat it as dead.
+
+Related namespace rule: company vault bucket keys are **company-relative**
+(`knowledge/foo.md`, NOT `companies/<slug>/knowledge/foo.md`). Translate the
+CLI's anchored `companies/<slug>/…` form to the bucket-relative key at the S3
+boundary (`toBucketRelative` / `toCompanyAnchored` in `files-browse.ts`), and
+normalize ACL grant paths with `grantPathToPrefix` before `startsWith`
+classification. Listing/getting with the anchored prefix returns nothing.
+
+## Rationale
+
+`hq files browse`/`cat` (US-009) were wired to `POST /vend`, which 500'd on
+every multi-tenant call. The root cause was an undefined `BUCKET_ARN` env on
+the vend Lambda, not a stale deploy — redeploying clean source did not fix it.
+The working fix routed both commands through `/sts/vend` + `/sts/vend-self`
+(client-only, hq-cloud 5.43.0 / hq-cli 5.29.0) and fixed the company-relative
+namespace translation. Captured so future interactive-read surfaces reach for
+the STS routes from the start and don't resurrect the dead `POST /vend`.

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

@@ -300,6 +300,78 @@ export declare function runSharedWithMe(input: RunSharedWithMeInput): Promise<Sh
  * Render `shared-with-me` rows as a padded table. Mirrors `formatBrowseTable`.
  */
 export declare function formatSharedWithMeTable(rows: SharedWithMeRow[]): string;
+export interface RunSearchInput {
+    /** Case-insensitive substring matched against each object's full key. */
+    query: string;
+    /** Company slug to search (ignored under personalMode). */
+    companySlug: string;
+    personalMode?: boolean;
+    personalUid?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+}
+/**
+ * `hq files search <query>` orchestrator. Lists the company (or personal)
+ * vault under its root via `runBrowse`, then filters to keys containing the
+ * query (case-insensitive). v1 is a name/path search over the listing — no
+ * content search. Rows carry the same ACL-source classification as browse.
+ *
+ * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
+ */
+export declare function runSearch(input: RunSearchInput): Promise<BrowseRow[]>;
+interface PinFile {
+    version: number;
+    /** companySlug → sorted list of company-relative pinned prefixes. */
+    pins: Record<string, string[]>;
+}
+/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
+export declare function pinFilePath(hqRoot: string): string;
+/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
+export declare function readPins(hqRoot: string): PinFile;
+/**
+ * Register a company-relative prefix in the per-machine pin set. Pins are what
+ * keep an on-demand `hq files get` from being pruned by the next *scoped*
+ * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
+ * into its pull scope. Idempotent + sorted for stable diffs.
+ */
+export declare function addPin(hqRoot: string, companySlug: string, prefix: string): void;
+export interface RunGetInput {
+    /** Vault path to materialize: `companies/<slug>/...` (file or prefix). */
+    path: string;
+    /**
+     * Override destination directory. Default (omitted) writes in place under
+     * `<hqRoot>/companies/<slug>/...` — the tree `hq sync` manages — and
+     * registers a pin. `--into` writes outside that envelope and pins nothing.
+     */
+    into?: string;
+    hqRoot: string;
+    companySlug?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+}
+export interface RunGetResult {
+    filesWritten: number;
+    bytesWritten: number;
+    destinations: string[];
+    /** Set only for in-place (no `--into`) materialization. */
+    pinned?: {
+        companySlug: string;
+        prefix: string;
+    };
+}
+/**
+ * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
+ * the local HQ tree on demand. Unlike `cat` (which refuses to write under
+ * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
+ * default — that's the point: pull a path you have access to but don't sync.
+ * It then registers a pin so the next scoped sync keeps it.
+ *
+ * Company mode only in v1 — materializing a personal vault would target the
+ * HQ root itself, which is too broad to do implicitly.
+ */
+export declare function runGet(input: RunGetInput): Promise<RunGetResult>;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group
@@ -307,4 +379,5 @@ export declare function formatSharedWithMeTable(rows: SharedWithMeRow[]): string
  * new browse-vs-sync subcommands so they share the `--company` switch.
  */
 export declare function registerFilesBrowseCommands(filesCmd: Command): void;
+export {};
 //# sourceMappingURL=files-browse.d.ts.map

package/dist/commands/files-browse.js

@@ -34,7 +34,7 @@
  * methods and `grantPathToPrefix` from hq-cloud.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e2f338ce-5871-59ad-ae56-99bd29e1711c")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cad165f9-6445-5434-969b-e0705274aa56")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -400,6 +400,148 @@ export function formatSharedWithMeTable(rows) {
         ...data.map(renderRow),
     ].join("\n");
 }
+/**
+ * `hq files search <query>` orchestrator. Lists the company (or personal)
+ * vault under its root via `runBrowse`, then filters to keys containing the
+ * query (case-insensitive). v1 is a name/path search over the listing — no
+ * content search. Rows carry the same ACL-source classification as browse.
+ *
+ * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
+ */
+export async function runSearch(input) {
+    const prefix = input.personalMode ? "" : `companies/${input.companySlug}/`;
+    const { rows } = await runBrowse({
+        pathPrefix: prefix,
+        companySlug: input.companySlug,
+        personalMode: input.personalMode,
+        personalUid: input.personalUid,
+        vaultClient: input.vaultClient,
+        s3Factory: input.s3Factory,
+        region: input.region,
+    });
+    const q = input.query.toLowerCase();
+    return rows.filter((r) => r.key.toLowerCase().includes(q));
+}
+/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
+export function pinFilePath(hqRoot) {
+    return path.join(hqRoot, ".hq", "pins.json");
+}
+/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
+export function readPins(hqRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(pinFilePath(hqRoot), "utf-8"));
+        if (parsed && typeof parsed === "object" && parsed.pins) {
+            return { version: parsed.version ?? 1, pins: parsed.pins };
+        }
+    }
+    catch {
+        /* missing / unreadable / malformed → start fresh */
+    }
+    return { version: 1, pins: {} };
+}
+/**
+ * Register a company-relative prefix in the per-machine pin set. Pins are what
+ * keep an on-demand `hq files get` from being pruned by the next *scoped*
+ * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
+ * into its pull scope. Idempotent + sorted for stable diffs.
+ */
+export function addPin(hqRoot, companySlug, prefix) {
+    const pf = readPins(hqRoot);
+    const list = pf.pins[companySlug] ?? [];
+    if (!list.includes(prefix))
+        list.push(prefix);
+    list.sort();
+    pf.pins[companySlug] = list;
+    const f = pinFilePath(hqRoot);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(pf, null, 2) + "\n");
+}
+/**
+ * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
+ * the local HQ tree on demand. Unlike `cat` (which refuses to write under
+ * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
+ * default — that's the point: pull a path you have access to but don't sync.
+ * It then registers a pin so the next scoped sync keeps it.
+ *
+ * Company mode only in v1 — materializing a personal vault would target the
+ * HQ root itself, which is too broad to do implicitly.
+ */
+export async function runGet(input) {
+    const { path: vaultPath, vaultClient, s3Factory, region, hqRoot } = input;
+    const slug = input.companySlug ?? parseCompanySlugFromPath(vaultPath);
+    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+    if (!entity) {
+        throw new Error(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
+    }
+    if (!entity.bucketName) {
+        throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+    }
+    const bucket = entity.bucketName;
+    const vend = await vaultClient.sts.vend({ companyUid: entity.uid });
+    const s3 = s3Factory({
+        region,
+        credentials: {
+            accessKeyId: vend.credentials.accessKeyId,
+            secretAccessKey: vend.credentials.secretAccessKey,
+            sessionToken: vend.credentials.sessionToken,
+        },
+    });
+    // Company-relative prefix to list/fetch (bucket keys carry no anchor).
+    const bucketPrefix = toBucketRelative(vaultPath, slug);
+    const keys = [];
+    let continuationToken;
+    do {
+        const resp = (await s3.send(new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: bucketPrefix,
+            ContinuationToken: continuationToken,
+        })));
+        for (const obj of resp.Contents ?? []) {
+            if (!obj.Key)
+                continue;
+            if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
+                continue;
+            keys.push(obj.Key);
+        }
+        continuationToken = resp.NextContinuationToken ?? undefined;
+    } while (continuationToken);
+    if (keys.length === 0) {
+        throw new Error(`No objects under '${vaultPath}'.`);
+    }
+    const destinations = [];
+    let bytesWritten = 0;
+    for (const key of keys) {
+        // Default: in-place under companies/<slug>/<company-relative key>.
+        // --into: write the path relative to the requested prefix under <into>.
+        let destAbs;
+        if (input.into !== undefined) {
+            const rel = key.startsWith(bucketPrefix)
+                ? key.slice(bucketPrefix.length)
+                : key;
+            destAbs = path.resolve(input.into, rel || path.basename(key));
+        }
+        else {
+            destAbs = path.join(hqRoot, "companies", slug, key);
+        }
+        const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+        if (!resp.Body) {
+            throw new Error(`GetObject for '${key}' returned no body.`);
+        }
+        const body = resp.Body;
+        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+        await pipeline(body, fs.createWriteStream(destAbs));
+        bytesWritten += fs.statSync(destAbs).size;
+        destinations.push(destAbs);
+    }
+    // Pin only the in-place case — `--into` writes outside the sync envelope, so
+    // there's nothing for a scoped sync to prune.
+    let pinned;
+    if (input.into === undefined) {
+        addPin(hqRoot, slug, bucketPrefix);
+        pinned = { companySlug: slug, prefix: bucketPrefix };
+    }
+    return { filesWritten: keys.length, bytesWritten, destinations, pinned };
+}
 // ── CLI registration ────────────────────────────────────────────────────────
 const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
 /**
@@ -417,9 +559,12 @@ export function registerFilesBrowseCommands(filesCmd) {
         "bucket-relative (omit it to list the vault root). Mutually exclusive " +
         "with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action(async (pathArg, options) => {
+        .action(async (pathArg, options, command) => {
         try {
-            if (options.personal && options.company) {
+            // `--company` is declared on the parent `files` group, so commander
+            // binds it there — read merged opts to see it from the subcommand.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
             const accessToken = await ensureCognitoToken();
@@ -452,12 +597,12 @@ export function registerFilesBrowseCommands(filesCmd) {
                     "browse your personal vault.");
             }
             // Resolve slug — CLI flag wins, otherwise parse from path arg.
-            const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+            const slug = company ?? parseCompanySlugFromPath(pathArg);
             // If the user passed `--company` AND the path doesn't begin with
             // companies/<that-slug>/, refuse — we'd otherwise vend creds for
             // one company and list keys from another tree, which never makes
             // sense (defense in depth against operator typos).
-            if (options.company !== undefined) {
+            if (company !== undefined) {
                 const fromPath = (() => {
                     try {
                         return parseCompanySlugFromPath(pathArg);
@@ -466,8 +611,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                         return undefined;
                     }
                 })();
-                if (fromPath && fromPath !== options.company) {
-                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                if (fromPath && fromPath !== company) {
+                    throw new Error(`--company '${company}' disagrees with path slug '${fromPath}'.`);
                 }
             }
             // Confirm the slug resolves to a known membership — same pattern
@@ -502,9 +647,11 @@ export function registerFilesBrowseCommands(filesCmd) {
         .option("--personal", "Read from the caller's canonical personal vault. <path> is treated as " +
         "bucket-relative. Mutually exclusive with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action(async (keyArg, options) => {
+        .action(async (keyArg, options, command) => {
         try {
-            if (options.personal && options.company) {
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
             const accessToken = await ensureCognitoToken();
@@ -531,8 +678,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                 }
                 return;
             }
-            const slug = options.company ?? parseCompanySlugFromPath(keyArg);
-            if (options.company !== undefined) {
+            const slug = company ?? parseCompanySlugFromPath(keyArg);
+            if (company !== undefined) {
                 const fromPath = (() => {
                     try {
                         return parseCompanySlugFromPath(keyArg);
@@ -541,8 +688,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                         return undefined;
                     }
                 })();
-                if (fromPath && fromPath !== options.company) {
-                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                if (fromPath && fromPath !== company) {
+                    throw new Error(`--company '${company}' disagrees with path slug '${fromPath}'.`);
                 }
             }
             await getCompanyUid(accessToken, slug);
@@ -568,21 +715,23 @@ export function registerFilesBrowseCommands(filesCmd) {
         .command("shared-with-me")
         .description("List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
         .option("--company <slug>", "Scope to a single company (defaults to a cross-company roll-up).")
-        .action(async (options) => {
+        .action(async (options, command) => {
         try {
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const company = command.optsWithGlobals().company;
             const accessToken = await ensureCognitoToken();
             const vaultConfig = buildVaultConfig(accessToken);
             const client = new VaultClient(vaultConfig);
             let companyUid;
-            if (options.company) {
+            if (company) {
                 // Confirm membership + resolve UID, same early-failure pattern as
                 // browse/cat. Roll-up mode skips this and fans out internally.
-                companyUid = await getCompanyUid(accessToken, options.company);
+                companyUid = await getCompanyUid(accessToken, company);
             }
             const rows = await runSharedWithMe({
                 vaultClient: client,
                 companyUid,
-                companySlug: options.company,
+                companySlug: company,
             });
             console.log(formatSharedWithMeTable(rows));
         }
@@ -591,6 +740,103 @@ export function registerFilesBrowseCommands(filesCmd) {
             process.exit(1);
         }
     });
+    filesCmd
+        .command("search <query>")
+        .description("Search vault object keys (case-insensitive path/name match) under a company without downloading. Requires --company (or --personal). Content search is not supported in v1.")
+        .option("--company <slug>", "Company slug to search.")
+        .option("--personal", "Search the caller's canonical personal vault. Mutually exclusive with --company.")
+        .action(async (query, options, command) => {
+        try {
+            // `--company` is declared on the parent `files` group too, so commander
+            // binds it there; read the merged (global+local) opts to see it.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
+                throw new Error("--personal and --company are mutually exclusive. Pick one.");
+            }
+            const accessToken = await ensureCognitoToken();
+            const client = new VaultClient(buildVaultConfig(accessToken));
+            if (options.personal) {
+                const personalUid = await resolveCanonicalPersonUid({
+                    listMyMemberships: () => client.listMyMemberships(),
+                    listPersonEntities: () => client.entity.listByType("person"),
+                    getEntity: async () => null,
+                });
+                const rows = await runSearch({
+                    query,
+                    companySlug: "personal",
+                    personalMode: true,
+                    personalUid,
+                    vaultClient: client,
+                    s3Factory: defaultS3Factory,
+                    region: DEFAULT_COGNITO.region,
+                });
+                console.log(formatBrowseTable(rows));
+                return;
+            }
+            if (!company) {
+                throw new Error("search: --company <slug> is required (or --personal to search your personal vault).");
+            }
+            await getCompanyUid(accessToken, company);
+            const rows = await runSearch({
+                query,
+                companySlug: company,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            console.log(formatBrowseTable(rows));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    filesCmd
+        .command("get <path>")
+        .description("Download (materialize) a vault file or prefix into local HQ on demand. Default writes in place under <hqRoot>/companies/<slug>/<path> and registers a pin so a scoped sync (mode shared|custom) won't prune it. Use --into to write elsewhere (no pin). Company mode only.")
+        .option("--into <dir>", "Write into this directory instead of the in-place companies/<slug>/ location. No pin is registered.")
+        .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>).")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(async (pathArg, options, command) => {
+        try {
+            const accessToken = await ensureCognitoToken();
+            const client = new VaultClient(buildVaultConfig(accessToken));
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const companyOpt = command.optsWithGlobals().company;
+            const slug = companyOpt ?? parseCompanySlugFromPath(pathArg);
+            if (companyOpt !== undefined) {
+                const fromPath = (() => {
+                    try {
+                        return parseCompanySlugFromPath(pathArg);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                if (fromPath && fromPath !== companyOpt) {
+                    throw new Error(`--company '${companyOpt}' disagrees with path slug '${fromPath}'.`);
+                }
+            }
+            await getCompanyUid(accessToken, slug);
+            const result = await runGet({
+                path: pathArg,
+                into: options.into,
+                hqRoot: options.hqRoot,
+                companySlug: slug,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            console.error(chalk.green("✓"), `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`);
+            if (result.pinned) {
+                console.error(chalk.dim(`Pinned ${result.pinned.companySlug}:${result.pinned.prefix} — survives scoped sync.`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=e2f338ce-5871-59ad-ae56-99bd29e1711c
+//# debugId=cad165f9-6445-5434-969b-e0705274aa56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.29.0",
+  "version": "5.31.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "~5.43.0",
+    "@indigoai-us/hq-cloud": "~5.44.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/files-browse.test.ts

@@ -20,6 +20,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -34,6 +35,11 @@ import {
   toCompanyAnchored,
   runBrowse,
   runCat,
+  runSearch,
+  runGet,
+  readPins,
+  addPin,
+  pinFilePath,
   runSharedWithMe,
   formatSharedWithMeTable,
   type BrowseVendResult,
@@ -831,3 +837,249 @@ describe("runSharedWithMe", () => {
     expect(out).toContain("knowledge/");
   });
 });
+
+// ── runSearch ─────────────────────────────────────────────────────────────
+
+describe("runSearch", () => {
+  it("filters the company listing by case-insensitive substring on the key", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({
+      listResponses: [
+        {
+          Contents: [
+            { Key: "knowledge/Roadmap.md", Size: 1, LastModified: new Date() },
+            { Key: "reports/q3.pdf", Size: 2, LastModified: new Date() },
+            { Key: "knowledge/notes.md", Size: 3, LastModified: new Date() },
+          ],
+        },
+      ],
+    });
+    const rows = await runSearch({
+      query: "roadmap", // lower-case query matches mixed-case key
+      companySlug: "indigo",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+    // Keys are re-anchored for display; only the matching one survives.
+    expect(rows.map((r) => r.key)).toEqual([
+      "companies/indigo/knowledge/Roadmap.md",
+    ]);
+    // Vends via the multi-tenant route (inherited from runBrowse).
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns an empty array when nothing matches", async () => {
+    const { client } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({
+      listResponses: [
+        { Contents: [{ Key: "knowledge/a.md", Size: 1, LastModified: new Date() }] },
+      ],
+    });
+    const rows = await runSearch({
+      query: "zzz-no-match",
+      companySlug: "indigo",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+    expect(rows).toEqual([]);
+  });
+});
+
+// ── pin set (readPins / addPin) ─────────────────────────────────────────────
+
+describe("pin set", () => {
+  it("readPins returns an empty set when the file is missing", () => {
+    expect(readPins(tmpRoot)).toEqual({ version: 1, pins: {} });
+  });
+
+  it("addPin creates the file, dedups, and sorts prefixes", () => {
+    addPin(tmpRoot, "indigo", "knowledge/");
+    addPin(tmpRoot, "indigo", "knowledge/"); // duplicate — ignored
+    addPin(tmpRoot, "indigo", "data/");
+    const pf = readPins(tmpRoot);
+    expect(pf.pins.indigo).toEqual(["data/", "knowledge/"]);
+    expect(fs.existsSync(pinFilePath(tmpRoot))).toBe(true);
+  });
+
+  it("addPin keeps per-company lists separate", () => {
+    addPin(tmpRoot, "indigo", "knowledge/");
+    addPin(tmpRoot, "acme", "docs/");
+    const pf = readPins(tmpRoot);
+    expect(pf.pins).toEqual({ indigo: ["knowledge/"], acme: ["docs/"] });
+  });
+
+  it("readPins tolerates a corrupt pins.json (→ fresh)", () => {
+    fs.mkdirSync(path.dirname(pinFilePath(tmpRoot)), { recursive: true });
+    fs.writeFileSync(pinFilePath(tmpRoot), "{ not valid json");
+    expect(readPins(tmpRoot)).toEqual({ version: 1, pins: {} });
+  });
+});
+
+// ── runGet ────────────────────────────────────────────────────────────────
+
+function makeGetStubS3(opts: {
+  listKeys: Array<{ Key: string; Size: number }>;
+  bodyFor: (key: string) => Buffer;
+}): { factory: S3ClientFactory; sendSpy: ReturnType<typeof vi.fn> } {
+  const sendSpy = vi.fn(async (cmd: unknown) => {
+    if (cmd instanceof ListObjectsV2Command) {
+      return {
+        Contents: opts.listKeys.map((k) => ({ ...k, LastModified: new Date() })),
+      } as ListObjectsV2CommandOutput;
+    }
+    if (cmd instanceof GetObjectCommand) {
+      const key = (cmd as GetObjectCommand).input.Key as string;
+      return {
+        Body: Readable.from(opts.bodyFor(key)),
+      } as unknown as GetObjectCommandOutput;
+    }
+    throw new Error(`unexpected command: ${cmd}`);
+  });
+  const factory = vi.fn(
+    () => ({ send: sendSpy }) as unknown as FilesBrowseS3Client,
+  ) as unknown as S3ClientFactory;
+  return { factory, sendSpy };
+}
+
+describe("runGet", () => {
+  it("materializes a prefix in-place under companies/<slug>/ and registers a pin", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory, sendSpy } = makeGetStubS3({
+      listKeys: [
+        { Key: "knowledge/a.md", Size: 3 },
+        { Key: "knowledge/sub/b.md", Size: 3 },
+      ],
+      bodyFor: (k) => Buffer.from(k === "knowledge/a.md" ? "AAA" : "BBB"),
+    });
+
+    const result = await runGet({
+      path: "companies/indigo/knowledge/",
+      hqRoot: tmpRoot,
+      companySlug: "indigo",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+
+    // Vends via the multi-tenant company route.
+    expect(spies.stsVend).toHaveBeenCalledWith({ companyUid: "cmp_indigo" });
+    expect(result.filesWritten).toBe(2);
+
+    // Files landed in place under companies/<slug>/.
+    expect(
+      fs.readFileSync(
+        path.join(tmpRoot, "companies", "indigo", "knowledge", "a.md"),
+        "utf-8",
+      ),
+    ).toBe("AAA");
+    expect(
+      fs.readFileSync(
+        path.join(tmpRoot, "companies", "indigo", "knowledge", "sub", "b.md"),
+        "utf-8",
+      ),
+    ).toBe("BBB");
+
+    // GetObject used company-relative keys (no companies/<slug>/ anchor).
+    const getKeys = sendSpy.mock.calls
+      .filter((c) => c[0] instanceof GetObjectCommand)
+      .map((c) => (c[0] as GetObjectCommand).input.Key);
+    expect(getKeys).toEqual(["knowledge/a.md", "knowledge/sub/b.md"]);
+
+    // Pin registered for the in-place prefix.
+    expect(readPins(tmpRoot).pins.indigo).toEqual(["knowledge/"]);
+    expect(result.pinned).toEqual({ companySlug: "indigo", prefix: "knowledge/" });
+  });
+
+  it("--into writes outside companies/ and registers NO pin", async () => {
+    const into = path.join(tmpRoot, "extract");
+    const { client } = makeStubVaultClient({});
+    const { factory } = makeGetStubS3({
+      listKeys: [{ Key: "knowledge/a.md", Size: 3 }],
+      bodyFor: () => Buffer.from("AAA"),
+    });
+
+    const result = await runGet({
+      path: "companies/indigo/knowledge/",
+      into,
+      hqRoot: tmpRoot,
+      companySlug: "indigo",
+      vaultClient: client,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+
+    // Written relative to the requested prefix, under --into.
+    expect(fs.readFileSync(path.join(into, "a.md"), "utf-8")).toBe("AAA");
+    // No pin — --into is outside the sync envelope.
+    expect(result.pinned).toBeUndefined();
+    expect(fs.existsSync(pinFilePath(tmpRoot))).toBe(false);
+  });
+
+  it("throws when no objects exist under the path", async () => {
+    const { client } = makeStubVaultClient({});
+    const { factory } = makeGetStubS3({
+      listKeys: [],
+      bodyFor: () => Buffer.from(""),
+    });
+    await expect(
+      runGet({
+        path: "companies/indigo/nope/",
+        hqRoot: tmpRoot,
+        companySlug: "indigo",
+        vaultClient: client,
+        s3Factory: factory,
+        region: "us-east-1",
+      }),
+    ).rejects.toThrow(/No objects under/);
+  });
+});
+
+// ── --company parent-binding (regression) ───────────────────────────────────
+//
+// The `files` parent group declares `--company`, so commander binds the flag
+// to the PARENT command, not the subcommand — `subcommand.opts().company` is
+// empty. The browse/cat/search/get/shared-with-me actions therefore resolve
+// it via `command.optsWithGlobals().company`. This guards that contract so a
+// future refactor doesn't silently regress `hq files <sub> ... --company X`
+// back to the swallowed-flag bug.
+
+describe("--company parent binding (optsWithGlobals)", () => {
+  it("a subcommand sees --company declared on the parent group", () => {
+    const program = new Command();
+    const files = program
+      .command("files")
+      .option("--company <slug>", "Company slug");
+    let seen: string | undefined = "UNSET";
+    files
+      .command("search <query>")
+      .option("--personal")
+      .action((_query: string, _options: unknown, command: Command) => {
+        seen = command.optsWithGlobals().company as string | undefined;
+      });
+    program.parse(
+      ["files", "search", "README", "--company", "indigo"],
+      { from: "user" } as never,
+    );
+    expect(seen).toBe("indigo");
+  });
+
+  it("documents the bug: subcommand-local opts.company is empty for a parent-bound flag", () => {
+    const program = new Command();
+    const files = program
+      .command("files")
+      .option("--company <slug>", "Company slug");
+    let local: string | undefined = "UNSET";
+    files
+      .command("search <query>")
+      .action((_query: string, options: { company?: string }) => {
+        local = options.company;
+      });
+    program.parse(
+      ["files", "search", "README", "--company", "indigo"],
+      { from: "user" } as never,
+    );
+    expect(local).toBeUndefined();
+  });
+});

package/src/commands/files-browse.ts

@@ -676,6 +676,207 @@ export function formatSharedWithMeTable(rows: SharedWithMeRow[]): string {
   ].join("\n");
 }
 
+// ── search ───────────────────────────────────────────────────────────────
+
+export interface RunSearchInput {
+  /** Case-insensitive substring matched against each object's full key. */
+  query: string;
+  /** Company slug to search (ignored under personalMode). */
+  companySlug: string;
+  personalMode?: boolean;
+  personalUid?: string;
+  vaultClient: FilesBrowseVaultClient;
+  s3Factory: S3ClientFactory;
+  region: string;
+}
+
+/**
+ * `hq files search <query>` orchestrator. Lists the company (or personal)
+ * vault under its root via `runBrowse`, then filters to keys containing the
+ * query (case-insensitive). v1 is a name/path search over the listing — no
+ * content search. Rows carry the same ACL-source classification as browse.
+ *
+ * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
+ */
+export async function runSearch(input: RunSearchInput): Promise<BrowseRow[]> {
+  const prefix = input.personalMode ? "" : `companies/${input.companySlug}/`;
+  const { rows } = await runBrowse({
+    pathPrefix: prefix,
+    companySlug: input.companySlug,
+    personalMode: input.personalMode,
+    personalUid: input.personalUid,
+    vaultClient: input.vaultClient,
+    s3Factory: input.s3Factory,
+    region: input.region,
+  });
+  const q = input.query.toLowerCase();
+  return rows.filter((r) => r.key.toLowerCase().includes(q));
+}
+
+// ── get (materialize + pin) ─────────────────────────────────────────────────
+
+interface PinFile {
+  version: number;
+  /** companySlug → sorted list of company-relative pinned prefixes. */
+  pins: Record<string, string[]>;
+}
+
+/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
+export function pinFilePath(hqRoot: string): string {
+  return path.join(hqRoot, ".hq", "pins.json");
+}
+
+/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
+export function readPins(hqRoot: string): PinFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(pinFilePath(hqRoot), "utf-8"));
+    if (parsed && typeof parsed === "object" && parsed.pins) {
+      return { version: parsed.version ?? 1, pins: parsed.pins };
+    }
+  } catch {
+    /* missing / unreadable / malformed → start fresh */
+  }
+  return { version: 1, pins: {} };
+}
+
+/**
+ * Register a company-relative prefix in the per-machine pin set. Pins are what
+ * keep an on-demand `hq files get` from being pruned by the next *scoped*
+ * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
+ * into its pull scope. Idempotent + sorted for stable diffs.
+ */
+export function addPin(hqRoot: string, companySlug: string, prefix: string): void {
+  const pf = readPins(hqRoot);
+  const list = pf.pins[companySlug] ?? [];
+  if (!list.includes(prefix)) list.push(prefix);
+  list.sort();
+  pf.pins[companySlug] = list;
+  const f = pinFilePath(hqRoot);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(pf, null, 2) + "\n");
+}
+
+export interface RunGetInput {
+  /** Vault path to materialize: `companies/<slug>/...` (file or prefix). */
+  path: string;
+  /**
+   * Override destination directory. Default (omitted) writes in place under
+   * `<hqRoot>/companies/<slug>/...` — the tree `hq sync` manages — and
+   * registers a pin. `--into` writes outside that envelope and pins nothing.
+   */
+  into?: string;
+  hqRoot: string;
+  companySlug?: string;
+  vaultClient: FilesBrowseVaultClient;
+  s3Factory: S3ClientFactory;
+  region: string;
+}
+
+export interface RunGetResult {
+  filesWritten: number;
+  bytesWritten: number;
+  destinations: string[];
+  /** Set only for in-place (no `--into`) materialization. */
+  pinned?: { companySlug: string; prefix: string };
+}
+
+/**
+ * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
+ * the local HQ tree on demand. Unlike `cat` (which refuses to write under
+ * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
+ * default — that's the point: pull a path you have access to but don't sync.
+ * It then registers a pin so the next scoped sync keeps it.
+ *
+ * Company mode only in v1 — materializing a personal vault would target the
+ * HQ root itself, which is too broad to do implicitly.
+ */
+export async function runGet(input: RunGetInput): Promise<RunGetResult> {
+  const { path: vaultPath, vaultClient, s3Factory, region, hqRoot } = input;
+  const slug = input.companySlug ?? parseCompanySlugFromPath(vaultPath);
+
+  const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+  if (!entity) {
+    throw new Error(
+      `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
+    );
+  }
+  if (!entity.bucketName) {
+    throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+  }
+  const bucket = entity.bucketName;
+  const vend = await vaultClient.sts.vend({ companyUid: entity.uid });
+  const s3 = s3Factory({
+    region,
+    credentials: {
+      accessKeyId: vend.credentials.accessKeyId,
+      secretAccessKey: vend.credentials.secretAccessKey,
+      sessionToken: vend.credentials.sessionToken,
+    },
+  });
+
+  // Company-relative prefix to list/fetch (bucket keys carry no anchor).
+  const bucketPrefix = toBucketRelative(vaultPath, slug);
+
+  const keys: string[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const resp = (await s3.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: bucketPrefix,
+        ContinuationToken: continuationToken,
+      }),
+    )) as ListObjectsV2CommandOutput;
+    for (const obj of resp.Contents ?? []) {
+      if (!obj.Key) continue;
+      if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0) continue;
+      keys.push(obj.Key);
+    }
+    continuationToken = resp.NextContinuationToken ?? undefined;
+  } while (continuationToken);
+
+  if (keys.length === 0) {
+    throw new Error(`No objects under '${vaultPath}'.`);
+  }
+
+  const destinations: string[] = [];
+  let bytesWritten = 0;
+  for (const key of keys) {
+    // Default: in-place under companies/<slug>/<company-relative key>.
+    // --into: write the path relative to the requested prefix under <into>.
+    let destAbs: string;
+    if (input.into !== undefined) {
+      const rel = key.startsWith(bucketPrefix)
+        ? key.slice(bucketPrefix.length)
+        : key;
+      destAbs = path.resolve(input.into, rel || path.basename(key));
+    } else {
+      destAbs = path.join(hqRoot, "companies", slug, key);
+    }
+    const resp = (await s3.send(
+      new GetObjectCommand({ Bucket: bucket, Key: key }),
+    )) as GetObjectCommandOutput;
+    if (!resp.Body) {
+      throw new Error(`GetObject for '${key}' returned no body.`);
+    }
+    const body = resp.Body as unknown as Readable;
+    fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+    await pipeline(body, fs.createWriteStream(destAbs));
+    bytesWritten += fs.statSync(destAbs).size;
+    destinations.push(destAbs);
+  }
+
+  // Pin only the in-place case — `--into` writes outside the sync envelope, so
+  // there's nothing for a scoped sync to prune.
+  let pinned: RunGetResult["pinned"];
+  if (input.into === undefined) {
+    addPin(hqRoot, slug, bucketPrefix);
+    pinned = { companySlug: slug, prefix: bucketPrefix };
+  }
+
+  return { filesWritten: keys.length, bytesWritten, destinations, pinned };
+}
+
 // ── CLI registration ────────────────────────────────────────────────────────
 
 const defaultS3Factory: S3ClientFactory = ({ region, credentials }) =>
@@ -697,6 +898,17 @@ interface FilesCatCliOptions extends FilesBrowseCliOptions {
   out?: string;
 }
 
+interface FilesSearchCliOptions {
+  company?: string;
+  personal?: boolean;
+}
+
+interface FilesGetCliOptions {
+  company?: string;
+  hqRoot: string;
+  into?: string;
+}
+
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group
@@ -724,9 +936,12 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
       `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
       DEFAULT_HQ_ROOT,
     )
-    .action(async (pathArg: string | undefined, options: FilesBrowseCliOptions) => {
+    .action(async (pathArg: string | undefined, options: FilesBrowseCliOptions, command: Command) => {
       try {
-        if (options.personal && options.company) {
+        // `--company` is declared on the parent `files` group, so commander
+        // binds it there — read merged opts to see it from the subcommand.
+        const company = command.optsWithGlobals().company as string | undefined;
+        if (options.personal && company) {
           throw new Error(
             "--personal and --company are mutually exclusive. Pick one.",
           );
@@ -769,13 +984,13 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
         }
 
         // Resolve slug — CLI flag wins, otherwise parse from path arg.
-        const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+        const slug = company ?? parseCompanySlugFromPath(pathArg);
 
         // If the user passed `--company` AND the path doesn't begin with
         // companies/<that-slug>/, refuse — we'd otherwise vend creds for
         // one company and list keys from another tree, which never makes
         // sense (defense in depth against operator typos).
-        if (options.company !== undefined) {
+        if (company !== undefined) {
           const fromPath = (() => {
             try {
               return parseCompanySlugFromPath(pathArg);
@@ -783,9 +998,9 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
               return undefined;
             }
           })();
-          if (fromPath && fromPath !== options.company) {
+          if (fromPath && fromPath !== company) {
             throw new Error(
-              `--company '${options.company}' disagrees with path slug '${fromPath}'.`,
+              `--company '${company}' disagrees with path slug '${fromPath}'.`,
             );
           }
         }
@@ -848,9 +1063,11 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
       `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
       DEFAULT_HQ_ROOT,
     )
-    .action(async (keyArg: string, options: FilesCatCliOptions) => {
+    .action(async (keyArg: string, options: FilesCatCliOptions, command: Command) => {
       try {
-        if (options.personal && options.company) {
+        // `--company` is bound on the parent `files` group — read merged opts.
+        const company = command.optsWithGlobals().company as string | undefined;
+        if (options.personal && company) {
           throw new Error(
             "--personal and --company are mutually exclusive. Pick one.",
           );
@@ -887,8 +1104,8 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
           return;
         }
 
-        const slug = options.company ?? parseCompanySlugFromPath(keyArg);
-        if (options.company !== undefined) {
+        const slug = company ?? parseCompanySlugFromPath(keyArg);
+        if (company !== undefined) {
           const fromPath = (() => {
             try {
               return parseCompanySlugFromPath(keyArg);
@@ -896,9 +1113,9 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
               return undefined;
             }
           })();
-          if (fromPath && fromPath !== options.company) {
+          if (fromPath && fromPath !== company) {
             throw new Error(
-              `--company '${options.company}' disagrees with path slug '${fromPath}'.`,
+              `--company '${company}' disagrees with path slug '${fromPath}'.`,
             );
           }
         }
@@ -938,23 +1155,25 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
       "--company <slug>",
       "Scope to a single company (defaults to a cross-company roll-up).",
     )
-    .action(async (options: { company?: string }) => {
+    .action(async (options: { company?: string }, command: Command) => {
       try {
+        // `--company` is bound on the parent `files` group — read merged opts.
+        const company = command.optsWithGlobals().company as string | undefined;
         const accessToken = await ensureCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const client = new VaultClient(vaultConfig);
 
         let companyUid: string | undefined;
-        if (options.company) {
+        if (company) {
           // Confirm membership + resolve UID, same early-failure pattern as
           // browse/cat. Roll-up mode skips this and fans out internally.
-          companyUid = await getCompanyUid(accessToken, options.company);
+          companyUid = await getCompanyUid(accessToken, company);
         }
 
         const rows = await runSharedWithMe({
           vaultClient: client,
           companyUid,
-          companySlug: options.company,
+          companySlug: company,
         });
 
         console.log(formatSharedWithMeTable(rows));
@@ -966,4 +1185,143 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
         process.exit(1);
       }
     });
+
+  filesCmd
+    .command("search <query>")
+    .description(
+      "Search vault object keys (case-insensitive path/name match) under a company without downloading. Requires --company (or --personal). Content search is not supported in v1.",
+    )
+    .option("--company <slug>", "Company slug to search.")
+    .option(
+      "--personal",
+      "Search the caller's canonical personal vault. Mutually exclusive with --company.",
+    )
+    .action(async (query: string, options: FilesSearchCliOptions, command: Command) => {
+      try {
+        // `--company` is declared on the parent `files` group too, so commander
+        // binds it there; read the merged (global+local) opts to see it.
+        const company = command.optsWithGlobals().company as string | undefined;
+        if (options.personal && company) {
+          throw new Error(
+            "--personal and --company are mutually exclusive. Pick one.",
+          );
+        }
+
+        const accessToken = await ensureCognitoToken();
+        const client = new VaultClient(buildVaultConfig(accessToken));
+
+        if (options.personal) {
+          const personalUid = await resolveCanonicalPersonUid({
+            listMyMemberships: () => client.listMyMemberships(),
+            listPersonEntities: () => client.entity.listByType("person"),
+            getEntity: async () => null,
+          });
+          const rows = await runSearch({
+            query,
+            companySlug: "personal",
+            personalMode: true,
+            personalUid,
+            vaultClient: client,
+            s3Factory: defaultS3Factory,
+            region: DEFAULT_COGNITO.region,
+          });
+          console.log(formatBrowseTable(rows));
+          return;
+        }
+
+        if (!company) {
+          throw new Error(
+            "search: --company <slug> is required (or --personal to search your personal vault).",
+          );
+        }
+        await getCompanyUid(accessToken, company);
+
+        const rows = await runSearch({
+          query,
+          companySlug: company,
+          vaultClient: client,
+          s3Factory: defaultS3Factory,
+          region: DEFAULT_COGNITO.region,
+        });
+        console.log(formatBrowseTable(rows));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  filesCmd
+    .command("get <path>")
+    .description(
+      "Download (materialize) a vault file or prefix into local HQ on demand. Default writes in place under <hqRoot>/companies/<slug>/<path> and registers a pin so a scoped sync (mode shared|custom) won't prune it. Use --into to write elsewhere (no pin). Company mode only.",
+    )
+    .option(
+      "--into <dir>",
+      "Write into this directory instead of the in-place companies/<slug>/ location. No pin is registered.",
+    )
+    .option(
+      "--company <slug>",
+      "Company slug (defaults to the slug parsed from <path>).",
+    )
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (pathArg: string, options: FilesGetCliOptions, command: Command) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const client = new VaultClient(buildVaultConfig(accessToken));
+
+        // `--company` is bound on the parent `files` group — read merged opts.
+        const companyOpt = command.optsWithGlobals().company as string | undefined;
+        const slug = companyOpt ?? parseCompanySlugFromPath(pathArg);
+        if (companyOpt !== undefined) {
+          const fromPath = (() => {
+            try {
+              return parseCompanySlugFromPath(pathArg);
+            } catch {
+              return undefined;
+            }
+          })();
+          if (fromPath && fromPath !== companyOpt) {
+            throw new Error(
+              `--company '${companyOpt}' disagrees with path slug '${fromPath}'.`,
+            );
+          }
+        }
+        await getCompanyUid(accessToken, slug);
+
+        const result = await runGet({
+          path: pathArg,
+          into: options.into,
+          hqRoot: options.hqRoot,
+          companySlug: slug,
+          vaultClient: client,
+          s3Factory: defaultS3Factory,
+          region: DEFAULT_COGNITO.region,
+        });
+
+        console.error(
+          chalk.green("✓"),
+          `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`,
+        );
+        if (result.pinned) {
+          console.error(
+            chalk.dim(
+              `Pinned ${result.pinned.companySlug}:${result.pinned.prefix} — survives scoped sync.`,
+            ),
+          );
+        }
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
 }