@indigoai-us/hq-cli 5.28.0 → 5.29.0

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

@@ -17,31 +17,57 @@
  *                 `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";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
-import { type VendResult, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type ExplicitGrant } from "@indigoai-us/hq-cloud";
+/** 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<{
@@ -96,15 +122,33 @@ export interface BrowseRow {
  */
 export declare 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 declare function toBucketRelative(pathOrPrefix: string, slug: string): string;
+/**
+ * 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 declare function toCompanyAnchored(bucketRelKey: string, slug: string): string;
+/**
+ * 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 declare function classifyAclSource(key: string, grants: ExplicitGrant[]): AclSource;
+export declare function classifyAclSource(bucketRelKey: string, grantPrefixes: string[]): AclSource;
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -151,15 +195,17 @@ export interface RunBrowseInput {
 }
 export interface RunBrowseResult {
     rows: BrowseRow[];
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files browse <path>` orchestrator.
  *
  *   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.
@@ -197,7 +243,7 @@ export interface RunCatResult {
         kind: "file";
         absPath: string;
     };
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then

package/dist/commands/files-browse.js

@@ -17,25 +17,30 @@
  *                 `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.
  */
 
-!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]="102456e4-666a-5484-b432-7f0b73275818")}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]="e2f338ce-5871-59ad-ae56-99bd29e1711c")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
-import { VaultClient, } from "@indigoai-us/hq-cloud";
+import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
@@ -54,17 +59,43 @@ export function parseCompanySlugFromPath(prefix) {
     return parts[1];
 }
 /**
- * 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, slug) {
+    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, slug) {
+    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, grants) {
-    for (const g of grants) {
-        if (g.path && key.startsWith(g.path))
+export function classifyAclSource(bucketRelKey, grantPrefixes) {
+    for (const p of grantPrefixes) {
+        if (p === "" || bucketRelKey.startsWith(p))
             return "shared-with-you";
     }
     return "role-bypass";
@@ -116,8 +147,10 @@ export function formatBrowseTable(rows) {
  *
  *   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.
@@ -127,10 +160,11 @@ export async function runBrowse(input) {
     // 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;
     let entityUid;
+    let slug;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runBrowse: personalMode requires personalUid. Resolve via " +
@@ -142,9 +176,10 @@ export async function runBrowse(input) {
         }
         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(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
@@ -154,17 +189,11 @@ export async function runBrowse(input) {
         }
         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: {
@@ -173,19 +202,26 @@ export async function runBrowse(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
+    // 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
+    // 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);
+        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => grantPathToPrefix(g.path, slug));
     const rows = [];
     let continuationToken;
     do {
         const resp = (await s3.send(new ListObjectsV2Command({
             Bucket: bucket,
-            Prefix: pathPrefix,
+            Prefix: listPrefix,
             ContinuationToken: continuationToken,
         })));
         for (const obj of resp.Contents ?? []) {
@@ -194,11 +230,17 @@ export async function runBrowse(input) {
             // 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),
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -221,6 +263,8 @@ export async function runCat(input) {
     // Same branch logic as runBrowse — see that function's doc-block for
     // the personal-vs-company rationale.
     let bucket;
+    let s3Key;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runCat: personalMode requires personalUid. Resolve via " +
@@ -231,6 +275,8 @@ export async function runCat(input) {
             throw new Error(`Personal entity '${input.personalUid}' has no provisioned bucket.`);
         }
         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);
@@ -242,12 +288,10 @@ export async function runCat(input) {
             throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
         }
         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: {
@@ -256,7 +300,7 @@ export async function runCat(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
-    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
     }
@@ -549,4 +593,4 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=102456e4-666a-5484-b432-7f0b73275818
+//# debugId=e2f338ce-5871-59ad-ae56-99bd29e1711c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.28.0",
+  "version": "5.29.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.42.0",
+    "@indigoai-us/hq-cloud": "~5.43.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

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

@@ -1,17 +1,22 @@
 /**
  * Unit tests for `hq files browse` + `hq files cat` (files-browse.ts).
  *
- * Stubs VaultClient.vend / listMyExplicitGrants / entity.findInMyNamespace
- * and the S3 client so we cover the three acceptance criteria the unit
- * suite is responsible for (acceptance 6):
+ * Stubs the multi-tenant STS vend routes (`sts.vend` / `sts.vendSelf`),
+ * listMyExplicitGrants, entity.findInMyNamespace/get, and the S3 client.
+ * Coverage focus:
  *
- *   1. vend uses `purpose: 'browse'` (NOT `'sync'`) for both subcommands.
- *   2. `--out` refuses any destination under `<hqRoot>/companies/`.
- *   3. ACL-source classification: keys with a covering explicit grant →
- *      `shared-with-you`; keys with no covering grant → `role-bypass`.
+ *   1. Browse/cat vend via `/sts/vend` (company) and `/sts/vend-self`
+ *      (personal) — NOT the legacy `POST /vend`, which is non-functional in
+ *      multi-tenant prod (undefined BUCKET_ARN → MalformedPolicyDocument).
+ *   2. Namespace translation: company vault keys are company-relative, so the
+ *      S3 list/get prefix is the bucket-relative form while the CLI surface
+ *      stays anchored at `companies/<slug>/`.
+ *   3. `--out` refuses any destination under `<hqRoot>/companies/`.
+ *   4. ACL-source classification over the company-relative key space.
  *
- * Plus the pure helpers (parseCompanySlugFromPath, classifyAclSource,
- * assertOutPathOutsideCompanies, formatBrowseTable).
+ * Plus the pure helpers (parseCompanySlugFromPath, toBucketRelative,
+ * toCompanyAnchored, classifyAclSource, assertOutPathOutsideCompanies,
+ * formatBrowseTable).
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -25,16 +30,19 @@ import {
   classifyAclSource,
   formatBrowseTable,
   parseCompanySlugFromPath,
+  toBucketRelative,
+  toCompanyAnchored,
   runBrowse,
   runCat,
   runSharedWithMe,
   formatSharedWithMeTable,
+  type BrowseVendResult,
   type FilesBrowseS3Client,
   type FilesBrowseVaultClient,
   type FilesSharedWithMeVaultClient,
   type S3ClientFactory,
 } from "./files-browse.js";
-import type { ExplicitGrant, VendResult } from "@indigoai-us/hq-cloud";
+import type { ExplicitGrant } from "@indigoai-us/hq-cloud";
 import {
   ListObjectsV2Command,
   GetObjectCommand,
@@ -68,24 +76,17 @@ function fakeGrant(p: string): ExplicitGrant {
   };
 }
 
-function fakeVendResult(overrides: Partial<VendResult> = {}): VendResult {
+function fakeStsVend(): BrowseVendResult {
   return {
     credentials: {
       accessKeyId: "ASIA-test",
       secretAccessKey: "secret-test",
       sessionToken: "session-test",
-      expiration: new Date(Date.now() + 900_000).toISOString(),
     },
-    paths: ["companies/indigo/"],
-    operations: "read-only",
-    purpose: "browse",
-    policySize: 512,
-    ...overrides,
   };
 }
 
 interface StubVaultOpts {
-  vend?: VendResult;
   grants?: ExplicitGrant[];
   entity?:
     | { uid: string; slug: string; name?: string; bucketName?: string }
@@ -95,7 +96,8 @@ interface StubVaultOpts {
 function makeStubVaultClient(opts: StubVaultOpts = {}): {
   client: FilesBrowseVaultClient;
   spies: {
-    vend: ReturnType<typeof vi.fn>;
+    stsVend: ReturnType<typeof vi.fn>;
+    vendSelf: ReturnType<typeof vi.fn>;
     listMyExplicitGrants: ReturnType<typeof vi.fn>;
     findInMyNamespace: ReturnType<typeof vi.fn>;
   };
@@ -109,7 +111,8 @@ function makeStubVaultClient(opts: StubVaultOpts = {}): {
           name: "Indigo",
           bucketName: "hq-vault-cmp-indigo",
         });
-  const vend = vi.fn(async () => opts.vend ?? fakeVendResult());
+  const stsVend = vi.fn(async () => fakeStsVend());
+  const vendSelf = vi.fn(async () => fakeStsVend());
   const listMyExplicitGrants = vi.fn(async () => opts.grants ?? []);
   const findInMyNamespace = vi.fn(async () => entity);
   const get = vi.fn(async (uid: string) => {
@@ -117,11 +120,14 @@ function makeStubVaultClient(opts: StubVaultOpts = {}): {
     return entity;
   });
   const client: FilesBrowseVaultClient = {
-    vend,
+    sts: { vend: stsVend, vendSelf },
     listMyExplicitGrants,
     entity: { get, findInMyNamespace },
   };
-  return { client, spies: { vend, listMyExplicitGrants, findInMyNamespace } };
+  return {
+    client,
+    spies: { stsVend, vendSelf, listMyExplicitGrants, findInMyNamespace },
+  };
 }
 
 interface StubS3Opts {
@@ -174,36 +180,83 @@ describe("parseCompanySlugFromPath", () => {
   });
 });
 
+// ── toBucketRelative / toCompanyAnchored (namespace translation) ────────────
+
+describe("toBucketRelative", () => {
+  it("strips the companies/<slug>/ anchor to a company-relative key", () => {
+    expect(toBucketRelative("companies/indigo/knowledge/foo.md", "indigo")).toBe(
+      "knowledge/foo.md",
+    );
+  });
+
+  it("strips the anchor for a bare prefix (trailing slash preserved)", () => {
+    expect(toBucketRelative("companies/indigo/scratch/", "indigo")).toBe(
+      "scratch/",
+    );
+  });
+
+  it("yields empty string for the bare company root", () => {
+    expect(toBucketRelative("companies/indigo/", "indigo")).toBe("");
+  });
+
+  it("tolerates leading slashes", () => {
+    expect(toBucketRelative("/companies/indigo/x/y", "indigo")).toBe("x/y");
+  });
+
+  it("passes through a path that lacks the anchor (e.g. already relative)", () => {
+    expect(toBucketRelative("knowledge/foo.md", "indigo")).toBe(
+      "knowledge/foo.md",
+    );
+  });
+
+  it("does not strip a different company's anchor", () => {
+    expect(toBucketRelative("companies/acme/x", "indigo")).toBe(
+      "companies/acme/x",
+    );
+  });
+});
+
+describe("toCompanyAnchored", () => {
+  it("re-attaches the companies/<slug>/ anchor", () => {
+    expect(toCompanyAnchored("knowledge/foo.md", "indigo")).toBe(
+      "companies/indigo/knowledge/foo.md",
+    );
+  });
+
+  it("round-trips with toBucketRelative", () => {
+    const anchored = "companies/indigo/a/b/c.md";
+    expect(toCompanyAnchored(toBucketRelative(anchored, "indigo"), "indigo")).toBe(
+      anchored,
+    );
+  });
+});
+
 // ── classifyAclSource ───────────────────────────────────────────────────────
 
 describe("classifyAclSource", () => {
-  it("returns shared-with-you when any grant prefixes the key", () => {
-    const grants = [fakeGrant("companies/indigo/scratch/")];
-    expect(
-      classifyAclSource("companies/indigo/scratch/foo.txt", grants),
-    ).toBe("shared-with-you");
+  it("returns shared-with-you when any grant prefix covers the key", () => {
+    expect(classifyAclSource("scratch/foo.txt", ["scratch/"])).toBe(
+      "shared-with-you",
+    );
   });
 
-  it("returns role-bypass when no grant covers the key", () => {
-    const grants = [fakeGrant("companies/indigo/scratch/")];
-    expect(
-      classifyAclSource("companies/indigo/secrets/db.txt", grants),
-    ).toBe("role-bypass");
+  it("returns role-bypass when no grant prefix covers the key", () => {
+    expect(classifyAclSource("secrets/db.txt", ["scratch/"])).toBe(
+      "role-bypass",
+    );
   });
 
   it("returns role-bypass on an empty grant list", () => {
-    expect(classifyAclSource("companies/indigo/anything/x", [])).toBe(
-      "role-bypass",
-    );
+    expect(classifyAclSource("anything/x", [])).toBe("role-bypass");
   });
 
-  it("matches against the first covering grant — multiple grants are fine", () => {
-    const grants = [
-      fakeGrant("companies/other/"),
-      fakeGrant("companies/indigo/scratch/"),
-    ];
+  it("treats an empty-string prefix as a company-wide grant (shared)", () => {
+    expect(classifyAclSource("anything/x", [""])).toBe("shared-with-you");
+  });
+
+  it("matches against the first covering prefix — multiple are fine", () => {
     expect(
-      classifyAclSource("companies/indigo/scratch/sub/y.bin", grants),
+      classifyAclSource("scratch/sub/y.bin", ["other/", "scratch/"]),
     ).toBe("shared-with-you");
   });
 });
@@ -300,9 +353,9 @@ describe("formatBrowseTable", () => {
 // ── runBrowse ───────────────────────────────────────────────────────────────
 
 describe("runBrowse", () => {
-  it("vends with purpose='browse' (NOT 'sync') for the requested prefix", async () => {
+  it("vends via /sts/vend (company) and lists the company-relative prefix", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { factory, sendSpy } = makeStubS3Factory({
       listResponses: [{ Contents: [] }],
     });
     await runBrowse({
@@ -311,29 +364,32 @@ describe("runBrowse", () => {
       s3Factory: factory,
       region: "us-east-1",
     });
-    expect(spies.vend).toHaveBeenCalledTimes(1);
-    const arg = spies.vend.mock.calls[0][0];
-    expect(arg.purpose).toBe("browse");
-    expect(arg.purpose).not.toBe("sync");
-    expect(arg.operations).toBe("read-only");
-    expect(arg.paths).toEqual(["companies/indigo/scratch/"]);
+    // Vend through the multi-tenant STS route — NOT the legacy POST /vend.
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    expect(spies.vendSelf).not.toHaveBeenCalled();
+    // S3 list prefix is company-relative (the bug: was anchored → 0 results).
+    const listCmd = sendSpy.mock.calls[0][0] as ListObjectsV2Command;
+    expect(listCmd.input.Prefix).toBe("scratch/");
   });
 
-  it("paginates ListObjectsV2 fully and classifies each key's ACL source", async () => {
+  it("paginates ListObjectsV2 fully, classifies ACL, and re-anchors keys for display", async () => {
     const { client } = makeStubVaultClient({
-      grants: [fakeGrant("companies/indigo/scratch/")],
+      // Real grants are glob/anchored; normalization folds this to "scratch/".
+      grants: [fakeGrant("companies/indigo/scratch/*")],
     });
     const { factory, sendSpy } = makeStubS3Factory({
+      // S3 keys are company-relative (no companies/<slug>/ prefix).
       listResponses: [
         {
           Contents: [
             {
-              Key: "companies/indigo/scratch/a.txt",
+              Key: "scratch/a.txt",
               Size: 10,
               LastModified: new Date("2026-01-01T00:00:00Z"),
             },
             {
-              Key: "companies/indigo/secrets/db.txt",
+              Key: "secrets/db.txt",
               Size: 20,
               LastModified: new Date("2026-01-02T00:00:00Z"),
             },
@@ -343,13 +399,13 @@ describe("runBrowse", () => {
         {
           Contents: [
             {
-              Key: "companies/indigo/scratch/sub/b.bin",
+              Key: "scratch/sub/b.bin",
               Size: 30,
               LastModified: new Date("2026-01-03T00:00:00Z"),
             },
             // S3 directory marker — should be filtered out.
             {
-              Key: "companies/indigo/scratch/empty/",
+              Key: "scratch/empty/",
               Size: 0,
               LastModified: new Date("2026-01-04T00:00:00Z"),
             },
@@ -365,6 +421,7 @@ describe("runBrowse", () => {
     });
     expect(sendSpy).toHaveBeenCalledTimes(2); // pagination
     expect(result.rows).toHaveLength(3);
+    // Displayed keys are re-anchored to companies/<slug>/.
     const byKey = Object.fromEntries(result.rows.map((r) => [r.key, r]));
     expect(byKey["companies/indigo/scratch/a.txt"].aclSource).toBe(
       "shared-with-you",
@@ -394,13 +451,11 @@ describe("runBrowse", () => {
   // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
   //
   // Personal mode resolves the entity via `entity.get(personalUid)` (skipping
-  // the company-namespace lookup), omits the explicit-grants fetch, and tags
-  // every row with `aclSource: "personal-vault"`. The path arg is bucket-
-  // relative — companies/<slug>/ prefix is NOT required (and would be
-  // incorrect, since the person bucket is owner-only with no companies/
-  // subtree).
+  // the company-namespace lookup), vends via `/sts/vend-self`, omits the
+  // explicit-grants fetch, and tags every row `aclSource: "personal-vault"`.
+  // The path arg is bucket-relative — companies/<slug>/ prefix is NOT required.
 
-  it("personalMode: resolves entity via entity.get(personalUid), skips namespace lookup", async () => {
+  it("personalMode: resolves via entity.get, vends /sts/vend-self, skips namespace + grants", async () => {
     const { client, spies } = makeStubVaultClient({
       entity: {
         uid: "prs_test",
@@ -431,10 +486,9 @@ describe("runBrowse", () => {
     expect(spies.findInMyNamespace).not.toHaveBeenCalled();
     // Grants graph is a company concept — must not be fetched.
     expect(spies.listMyExplicitGrants).not.toHaveBeenCalled();
-    // Vend still issued for browse purpose, no policy difference.
-    expect(spies.vend).toHaveBeenCalledWith(
-      expect.objectContaining({ purpose: "browse", operations: "read-only" }),
-    );
+    // Personal vends self, never the company route.
+    expect(spies.vendSelf).toHaveBeenCalledWith({ personUid: "prs_test" });
+    expect(spies.stsVend).not.toHaveBeenCalled();
   });
 
   it("personalMode: empty pathPrefix lists the bucket root", async () => {
@@ -540,9 +594,9 @@ describe("runBrowse", () => {
 // ── runCat ──────────────────────────────────────────────────────────────────
 
 describe("runCat", () => {
-  it("vends with purpose='browse' for a cat call", async () => {
+  it("vends via /sts/vend and GetObjects the company-relative key", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { factory, sendSpy } = makeStubS3Factory({
       getResponse: {
         Body: Readable.from(Buffer.from("hello world")),
       } as GetObjectCommandOutput,
@@ -557,8 +611,14 @@ describe("runCat", () => {
       hqRoot: tmpRoot,
       stdout: sink,
     });
-    expect(spies.vend).toHaveBeenCalledTimes(1);
-    expect(spies.vend.mock.calls[0][0].purpose).toBe("browse");
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    // GetObject key is company-relative (anchor stripped).
+    const getCmd = sendSpy.mock.calls.find(
+      (c) => c[0] instanceof GetObjectCommand,
+    )?.[0] as GetObjectCommand;
+    expect(getCmd.input.Bucket).toBe("hq-vault-cmp-indigo");
+    expect(getCmd.input.Key).toBe("scratch/a.txt");
   });
 
   it("writes to --out when outside the companies tree and reports byte count", async () => {
@@ -601,7 +661,8 @@ describe("runCat", () => {
     ).rejects.toThrow(/Refusing to write/);
     // Critically: no vend was issued (guard runs first) and no S3 call
     // was made — failing closed is the whole point of the guard.
-    expect(spies.vend).not.toHaveBeenCalled();
+    expect(spies.stsVend).not.toHaveBeenCalled();
+    expect(spies.vendSelf).not.toHaveBeenCalled();
     expect(sendSpy).not.toHaveBeenCalled();
     // And no file was written under the protected tree.
     expect(fs.existsSync(badOut)).toBe(false);
@@ -623,7 +684,7 @@ describe("runCat", () => {
 
   // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
 
-  it("personalMode: streams from the person bucket, no slug parse on the key", async () => {
+  it("personalMode: streams from the person bucket via /sts/vend-self, no slug parse", async () => {
     const { client, spies } = makeStubVaultClient({
       entity: { uid: "prs_test", slug: "personal", bucketName: "hq-vault-prs-test" },
     });
@@ -657,14 +718,10 @@ describe("runCat", () => {
 
     expect(result.destination.kind).toBe("stdout");
     expect(spies.findInMyNamespace).not.toHaveBeenCalled();
-    // Vend issued against the bucket-relative key, browse purpose.
-    expect(spies.vend).toHaveBeenCalledWith(
-      expect.objectContaining({
-        paths: [".claude/CLAUDE.md"],
-        purpose: "browse",
-      }),
-    );
-    // GetObject targeted the person bucket.
+    // Personal vends self, against the bucket-relative key.
+    expect(spies.vendSelf).toHaveBeenCalledWith({ personUid: "prs_test" });
+    expect(spies.stsVend).not.toHaveBeenCalled();
+    // GetObject targeted the person bucket with the bucket-relative key.
     const getCmd = sendSpy.mock.calls.find(
       (c) => c[0] instanceof GetObjectCommand,
     )?.[0] as GetObjectCommand;

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) {