@indigoai-us/hq-cli 5.28.0 → 5.30.0

package/src/commands/files-browse.ts

@@ -17,16 +17,21 @@
  *                 `hq sync` owns, and writing a peeked object there would
  *                 silently re-import it into the sync envelope.
  *
- * Both subcommands vend via the new `purpose: 'browse'` path
- * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
- * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
- * keeping browse on its own vend call is the acceptance-criteria-1
- * separation we need.
+ * Both subcommands vend through the multi-tenant STS routes —
+ * `VaultClient.sts.vend` (`/sts/vend`, company) and `.sts.vendSelf`
+ * (`/sts/vend-self`, personal). These resolve the caller's per-entity bucket
+ * and apply role/ACL scoping server-side (owner/admin → full access; member/
+ * guest → per-prefix). The legacy `POST /vend` is deliberately NOT used: it
+ * assumes a single static `BUCKET_ARN` that is unset in multi-tenant prod, so
+ * it builds an invalid policy and STS rejects it (`MalformedPolicyDocument`).
  *
- * Cross-package note: depends on `VendInput`/`VendResult` + the
- * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
- * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
- * `pnpm.overrides` until that release ships to npm.
+ * Namespace note: company vault keys are company-relative (no
+ * `companies/<slug>/` prefix). The CLI speaks the anchored form for user
+ * familiarity and translates at the S3 boundary via `toBucketRelative` /
+ * `toCompanyAnchored`.
+ *
+ * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
+ * methods and `grantPathToPrefix` from hq-cloud.
  */
 
 import { Command } from "commander";
@@ -46,7 +51,7 @@ import {
 
 import {
   VaultClient,
-  type VendResult,
+  grantPathToPrefix,
   type ExplicitGrant,
 } from "@indigoai-us/hq-cloud";
 
@@ -61,17 +66,40 @@ import { resolveCanonicalPersonUid } from "./cloud.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+/** STS-vended credential set the browse/cat path consumes. */
+export interface BrowseCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+/** Minimal STS-vend response shape (both `/sts/vend` and `/sts/vend-self`). */
+export interface BrowseVendResult {
+  credentials: BrowseCredentials;
+}
+
 /**
  * Subset of `VaultClient` this command actually uses — exposed so tests
  * can stub vend + grants without standing up a real `VaultClient`.
+ *
+ * Browse/cat vend through the multi-tenant `/sts/vend` (company) and
+ * `/sts/vend-self` (personal) routes — NOT the legacy `POST /vend`, which
+ * assumes a single static bucket and is non-functional in multi-tenant
+ * production (it builds a policy against an undefined `BUCKET_ARN`, so STS
+ * rejects it with `MalformedPolicyDocument`). The STS routes resolve the
+ * caller's per-entity bucket and apply role/ACL scoping server-side.
  */
 export interface FilesBrowseVaultClient {
-  vend(input: {
-    paths: string[];
-    operations: "read-only" | "read-write" | "staged-write";
-    purpose: "sync" | "browse";
-    duration?: number;
-  }): Promise<VendResult>;
+  sts: {
+    vend(input: {
+      companyUid: string;
+      durationSeconds?: number;
+    }): Promise<BrowseVendResult>;
+    vendSelf(input: {
+      personUid: string;
+      durationSeconds?: number;
+    }): Promise<BrowseVendResult>;
+  };
   listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
   entity: {
     get(uid: string): Promise<{ uid: string; slug: string; name?: string; bucketName?: string }>;
@@ -138,20 +166,48 @@ export function parseCompanySlugFromPath(prefix: string): string {
 }
 
 /**
- * Classify a single S3 key against the caller's explicit-grant list. Any
- * grant whose `path` is a prefix of the key contributes `shared-with-you`;
- * otherwise the key is only visible via role-bypass on the vend call.
+ * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
+ * the vault bucket actually stores. Company vault buckets are already
+ * company-scoped, so their keys carry NO `companies/<slug>/` prefix (e.g.
+ * `knowledge/foo.md`, not `companies/indigo/knowledge/foo.md`). The CLI speaks
+ * the anchored form for user familiarity; we strip the anchor at the S3
+ * boundary. A path without the anchor (or personal-mode, bucket-relative
+ * paths) passes through unchanged.
+ */
+export function toBucketRelative(pathOrPrefix: string, slug: string): string {
+  const anchor = `companies/${slug}/`;
+  const normalized = pathOrPrefix.replace(/^\/+/, "");
+  return normalized.startsWith(anchor)
+    ? normalized.slice(anchor.length)
+    : normalized;
+}
+
+/**
+ * Re-attach the `companies/<slug>/` anchor to a company-relative bucket key
+ * for display + `hq files cat` round-trip, so the CLI surface keeps speaking
+ * the anchored form the user passed in.
+ */
+export function toCompanyAnchored(bucketRelKey: string, slug: string): string {
+  return `companies/${slug}/${bucketRelKey}`;
+}
+
+/**
+ * Classify a single company-relative S3 key against the caller's
+ * (already-normalized) explicit-grant prefixes. Any prefix that covers the
+ * key contributes `shared-with-you`; otherwise the key is visible only via
+ * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
+ * prefix is a company-wide grant and matches everything.
  *
- * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
- * `coalescePrefixes` would shrink the list further but isn't required for
- * correctness — `startsWith` already short-circuits on the first match.
+ * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
+ * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
+ * calling this — keeping this helper pure and trivially testable.
  */
 export function classifyAclSource(
-  key: string,
-  grants: ExplicitGrant[],
+  bucketRelKey: string,
+  grantPrefixes: string[],
 ): AclSource {
-  for (const g of grants) {
-    if (g.path && key.startsWith(g.path)) return "shared-with-you";
+  for (const p of grantPrefixes) {
+    if (p === "" || bucketRelKey.startsWith(p)) return "shared-with-you";
   }
   return "role-bypass";
 }
@@ -242,7 +298,7 @@ export interface RunBrowseInput {
 
 export interface RunBrowseResult {
   rows: BrowseRow[];
-  vend: VendResult;
+  vend: BrowseVendResult;
 }
 
 /**
@@ -250,8 +306,10 @@ export interface RunBrowseResult {
  *
  *   1. Parse slug from prefix (or use override).
  *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
- *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   3. Vend read creds via the multi-tenant STS route (`/sts/vend` company,
+ *      `/sts/vend-self` personal) — resolves the per-entity bucket + role/ACL.
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2 over the
+ *      company-relative key space.
  *   5. Fetch explicit grants once, classify each key.
  *
  * Pure-ish: no console output, no process.exit — caller renders + exits.
@@ -262,10 +320,11 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
   // Branch by mode. Company mode parses slug from path and looks up by
   // namespace; personal mode resolves the entity directly by the supplied
   // person UID and skips the slug + grants machinery (a person bucket has
-  // no grants graph — the owner is the only principal). The vend call is
-  // identical for both modes once we have the entity in hand.
+  // no grants graph — the owner is the only principal).
   let bucket: string;
   let entityUid: string;
+  let slug: string | undefined;
+  let vend: BrowseVendResult;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -281,8 +340,9 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     entityUid = entity.uid;
     bucket = entity.bucketName;
+    vend = await vaultClient.sts.vendSelf({ personUid: entityUid });
   } else {
-    const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
+    slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
     const entity = await vaultClient.entity.findInMyNamespace("company", slug);
     if (!entity) {
       throw new Error(
@@ -296,19 +356,12 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     entityUid = entity.uid;
     bucket = entity.bucketName;
+    // Multi-tenant vend: the server resolves this company's bucket + applies
+    // owner/admin role-bypass (full access) or member/guest ACL scoping. The
+    // legacy `POST /vend` is unused here — see FilesBrowseVaultClient docs.
+    vend = await vaultClient.sts.vend({ companyUid: entityUid });
   }
 
-  // Distinct vend call from sync — `purpose: 'browse'` opts the request
-  // into the role-bypass-allowed code path on the server (US-009). The
-  // personal mode vends against the person entity which is owner-only by
-  // construction; the vend response shape is identical so downstream
-  // S3Client construction doesn't branch.
-  const vend = await vaultClient.vend({
-    paths: [pathPrefix],
-    operations: "read-only",
-    purpose: "browse",
-  });
-
   const s3 = s3Factory({
     region,
     credentials: {
@@ -318,13 +371,25 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     },
   });
 
+  // Company vault keys are company-relative (no `companies/<slug>/` prefix), so
+  // translate the CLI's anchored prefix into the bucket-relative form before
+  // listing. Personal-mode paths are already bucket-relative.
+  const listPrefix =
+    personalMode || slug === undefined
+      ? pathPrefix
+      : toBucketRelative(pathPrefix, slug);
+
   // Pull the caller's explicit-grant graph once so per-key classification
-  // is O(grants) without N round-trips. Skipped in personal mode — the
-  // grants graph is a company concept; a person bucket marks every row
-  // as `"personal-vault"` directly.
-  const grants = personalMode
-    ? ([] as ExplicitGrant[])
-    : await vaultClient.listMyExplicitGrants(entityUid);
+  // is O(grants) without N round-trips. Grant `path`s are normalized to
+  // company-relative `startsWith` prefixes (matching the bucket key space)
+  // via `grantPathToPrefix`. Skipped in personal mode — the grants graph is a
+  // company concept; a person bucket marks every row `"personal-vault"`.
+  const grantPrefixes =
+    personalMode || slug === undefined
+      ? []
+      : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) =>
+          grantPathToPrefix(g.path, slug as string),
+        );
 
   const rows: BrowseRow[] = [];
   let continuationToken: string | undefined;
@@ -332,7 +397,7 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     const resp = (await s3.send(
       new ListObjectsV2Command({
         Bucket: bucket,
-        Prefix: pathPrefix,
+        Prefix: listPrefix,
         ContinuationToken: continuationToken,
       }),
     )) as ListObjectsV2CommandOutput;
@@ -342,11 +407,18 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
       // Skip S3 "directory marker" objects (0-byte, trailing slash).
       if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0) continue;
 
+      // `obj.Key` is company-relative. Classify in that space, then re-anchor
+      // for display so the CLI keeps speaking `companies/<slug>/...`.
       rows.push({
-        key: obj.Key,
+        key:
+          personalMode || slug === undefined
+            ? obj.Key
+            : toCompanyAnchored(obj.Key, slug),
         size: obj.Size ?? 0,
         lastModified: obj.LastModified,
-        aclSource: personalMode ? "personal-vault" : classifyAclSource(obj.Key, grants),
+        aclSource: personalMode
+          ? "personal-vault"
+          : classifyAclSource(obj.Key, grantPrefixes),
       });
     }
 
@@ -384,7 +456,7 @@ export interface RunCatInput {
 export interface RunCatResult {
   bytesWritten: number;
   destination: { kind: "stdout" } | { kind: "file"; absPath: string };
-  vend: VendResult;
+  vend: BrowseVendResult;
 }
 
 /**
@@ -405,6 +477,8 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   // Same branch logic as runBrowse — see that function's doc-block for
   // the personal-vs-company rationale.
   let bucket: string;
+  let s3Key: string;
+  let vend: BrowseVendResult;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -419,6 +493,8 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
       );
     }
     bucket = entity.bucketName;
+    s3Key = key; // personal-mode keys are already bucket-relative
+    vend = await vaultClient.sts.vendSelf({ personUid: entity.uid });
   } else {
     const slug = input.companySlug ?? parseCompanySlugFromPath(key);
     const entity = await vaultClient.entity.findInMyNamespace("company", slug);
@@ -433,14 +509,11 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
       );
     }
     bucket = entity.bucketName;
+    // Translate the anchored CLI key into the company-relative bucket key.
+    s3Key = toBucketRelative(key, slug);
+    vend = await vaultClient.sts.vend({ companyUid: entity.uid });
   }
 
-  const vend = await vaultClient.vend({
-    paths: [key],
-    operations: "read-only",
-    purpose: "browse",
-  });
-
   const s3 = s3Factory({
     region,
     credentials: {
@@ -451,7 +524,7 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   });
 
   const resp = (await s3.send(
-    new GetObjectCommand({ Bucket: bucket, Key: key }),
+    new GetObjectCommand({ Bucket: bucket, Key: s3Key }),
   )) as GetObjectCommandOutput;
 
   if (!resp.Body) {
@@ -603,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 }) =>
@@ -624,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
@@ -893,4 +1178,138 @@ 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) => {
+      try {
+        if (options.personal && options.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 (!options.company) {
+          throw new Error(
+            "search: --company <slug> is required (or --personal to search your personal vault).",
+          );
+        }
+        await getCompanyUid(accessToken, options.company);
+
+        const rows = await runSearch({
+          query,
+          companySlug: options.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) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const client = new VaultClient(buildVaultConfig(accessToken));
+
+        const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+        if (options.company !== undefined) {
+          const fromPath = (() => {
+            try {
+              return parseCompanySlugFromPath(pathArg);
+            } catch {
+              return undefined;
+            }
+          })();
+          if (fromPath && fromPath !== options.company) {
+            throw new Error(
+              `--company '${options.company}' 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);
+      }
+    });
 }