@startsimpli/integrations 0.2.34 → 0.2.35

package/src/components/pages/LibraryPage.tsx

@@ -27,6 +27,9 @@
  */
 import * as React from 'react';
 
+import { FolderTree, folderTrail } from '../FolderTree';
+import { folderName } from '../../corpus/entities';
+import type { FolderTreeSlot } from '../FolderTree';
 import { Markdown, stripMarkdown } from '../Markdown';
 import { enforceScope } from '../../corpus/retrieval';
 import type {
@@ -46,8 +49,34 @@ export interface LibraryPageProps {
   initialDocumentId?: string;
   /** Told whenever the open record changes, so an app can put it in the URL. */
   onSelectDocument?: (documentId: string | null) => void;
+  /** Open straight into a folder — how a link to a location lands. */
+  initialFolder?: string;
+  /** Told whenever the open folder changes, so an app can put it in the URL. */
+  onSelectFolder?: (folder: string | null) => void;
+  /**
+   * PULL THE TEXT OF ONE RECORD. Supply it and the control on a text-less row is
+   * live; leave it out and the same control is there and DISABLED.
+   *
+   * IT IS A CONTROL EITHER WAY, and that is the whole point of the seam
+   * (Quinn, 2026-08-27, on the sentence this replaced: "don't say stupid shit
+   * like 'no text blah blah'. either have a button to pull the text, or have it
+   * grayed out if we can't do the action. simple ui."). A sentence in the place
+   * a control belongs tells a reader what happened; a greyed-out control tells
+   * them what they may do, which is the question they were actually asking.
+   *
+   * NOTHING SUPPLIES IT TODAY, and that is correct rather than a stub. Content
+   * is OPT-IN and never the default (bd startsim-h6xnu): the index owes what
+   * exists, where it lives and findability, and pulling the bytes of every file
+   * is the expensive, privacy-loaded half nobody asked for. The route that would
+   * fill this in is bd startsim-99g8.2 and it is deliberately unshipped, so on
+   * today's tenant the control is disabled — which is the honest answer to "can
+   * I read this .ttf".
+   */
+  onRequestText?: (document: SourceDocument) => void | Promise<void>;
   pageSize?: number;
   classNames?: Partial<Record<LibrarySlot, string>>;
+  /** Theme slots for the folder tree, passed straight through. */
+  folderClassNames?: Partial<Record<FolderTreeSlot, string>>;
 }
 
 type LibrarySlot =
@@ -169,12 +198,51 @@ export function LibraryPage({
   scope,
   initialDocumentId,
   onSelectDocument,
+  initialFolder,
+  onSelectFolder,
+  onRequestText,
   pageSize = 20,
   classNames = {},
+  folderClassNames = {},
 }: LibraryPageProps) {
   const cn = { ...DEFAULTS, ...classNames };
 
   const [filters, setFilters] = React.useState<DocumentQuery>({ page: 1, pageSize });
+  /**
+   * THE OPEN FOLDER, or `null` for the whole corpus.
+   *
+   * `null` IS NOT A BUCKET AND MUST NOT BECOME ONE. The facet read enumerates
+   * values of `path` and skips records that have none, so a meeting note and an
+   * email are in NO folder — which on today's tandem is most of the corpus. The
+   * top of the tree therefore clears the path filter rather than narrowing to
+   * some invented "unfiled", and every record stays one click from the top the
+   * way it is in any file browser.
+   */
+  const [folder, setFolder] = React.useState<string | null>(initialFolder ?? null);
+  /** Set once the corpus proves it cannot enumerate folders; see `FolderTree`. */
+  const [noTree, setNoTree] = React.useState(false);
+  /**
+   * Whether an open folder means IT AND EVERYTHING BELOW IT. Default yes, and
+   * the default is the whole point.
+   *
+   * THE NUMBER THE READER JUST CLICKED HAS TO BE THE LIST THEY GET. A folder's
+   * count is DESCENDANTS — the tenant says so outright, because that is the
+   * number a person reading a collapsed folder wants — so a list bounded to the
+   * exact shelf disagrees with it the moment a folder is a container. On the
+   * live tandem corpus that is the two biggest folders: `/ERA22 Shared` (142)
+   * and `/Demo Day Presentations` (37) both hold their documents in subfolders.
+   * Bounded exactly, clicking either showed "0 records" beside a sidebar reading
+   * 142, under the sentence "Nothing matches those filters. Clear them to see
+   * everything." — filters the reader never set, in the place a control belongs.
+   * That is the same fault as the row sentence this screen just removed.
+   *
+   * IT IS A CONTROL, so the other reading stays available: uncheck it and the
+   * list is the shelf. What it is not is a hidden mode — the bound used to
+   * depend on whether the search box had a term in it, which meant the same
+   * click answered two different questions depending on state the reader was not
+   * looking at.
+   */
+  const [includeSubfolders, setIncludeSubfolders] = React.useState(true);
   const [draftSearch, setDraftSearch] = React.useState('');
   const [documents, setDocuments] = React.useState<SourceDocument[]>([]);
   const [count, setCount] = React.useState(0);
@@ -218,12 +286,25 @@ export function LibraryPage({
     return () => { live = false; };
   }, [api]);
 
+  /**
+   * The list query: the filter bar PLUS the open folder, bounded the way the
+   * reader asked for it — see `includeSubfolders` for why the default is the
+   * subtree and not the shelf.
+   */
+  const query = React.useMemo<DocumentQuery>(() => {
+    if (!folder) return filters;
+    // ONE OF THE TWO, NEVER BOTH: the list endpoint ANDs its filters, so sending
+    // both would intersect a folder with its own subtree and quietly answer with
+    // the shelf.
+    return includeSubfolders ? { ...filters, underFolder: folder } : { ...filters, folder };
+  }, [filters, folder, includeSubfolders]);
+
   React.useEffect(() => {
     let live = true;
     setLoading(true);
     void (async () => {
       try {
-        const page = await api.listDocuments(filters);
+        const page = await api.listDocuments(query);
         if (!live) return;
         // THE GUARD RUNS ON THE LIST, not only on the detail panel. A row from
         // another workspace is a leak the moment it is drawn — its title and its
@@ -243,7 +324,7 @@ export function LibraryPage({
       }
     })();
     return () => { live = false; };
-  }, [api, filters, scope]);
+  }, [api, query, scope]);
 
   React.useEffect(() => {
     if (!selectedId) { setSelected(null); setSelectError(''); return; }
@@ -279,6 +360,25 @@ export function LibraryPage({
     setFilters((prev) => ({ ...prev, ...patch, page: patch.page ?? 1 }));
   }, []);
 
+  /**
+   * Move to a folder. Same page-1 reset as any other narrowing, and for the
+   * same reason: page 3 of `/Contracts` is not page 3 of the corpus.
+   */
+  const openFolder = React.useCallback((next: string | null) => {
+    setFolder(next);
+    setFilters((prev) => ({ ...prev, page: 1 }));
+    // AND THE BOUND RESETS WITH IT. "Only this shelf" is a thing the reader
+    // wanted to know about THAT folder, not a mode they signed up to carry
+    // around: left sticky, unchecking it on a container like `/Decks` and then
+    // clicking `/Contracts` — which does have files of its own — lists 2 of its
+    // 7 under a sidebar reading 7, which is the disagreement this screen just
+    // spent a commit removing, reachable in two clicks. Same reasoning as the
+    // page reset above: the answer to the old question is not the answer to the
+    // new one, and the control is one click away for anyone who wants it back.
+    setIncludeSubfolders(true);
+    onSelectFolder?.(next);
+  }, [onSelectFolder]);
+
   const page = filters.page ?? 1;
   const size = filters.pageSize ?? pageSize;
   const lastPage = Math.max(1, Math.ceil(count / size));
@@ -295,15 +395,20 @@ export function LibraryPage({
       ['source', filters.source],
       ['party', filters.partyId],
       ['date', filters.occurredAfter || filters.occurredBefore],
+      // THE ONE THAT MATTERS MOST HERE. A tree the server cannot narrow by is
+      // worse than no tree: the reader clicks `/Contracts`, the list does not
+      // change, and nothing on the screen says why. Same rule as the search box.
+      ['folder', query.folder || query.underFolder],
     ];
     const keyFor: Record<string, string[]> = {
       search: ['search'], source: ['source'], party: ['partyId'],
       date: ['occurredAfter', 'occurredBefore'],
+      folder: ['folder', 'underFolder'],
     };
     return requested
       .filter(([name, value]) => value && !keyFor[name].some((key) => applied.includes(key)))
       .map(([name]) => name);
-  }, [applied, filters]);
+  }, [applied, filters, query]);
 
   if (loadError) {
     return <p className={cn.error} role="alert">{loadError}</p>;
@@ -386,7 +491,16 @@ export function LibraryPage({
           <button
             type="button"
             className={cn.button}
-            onClick={() => { setDraftSearch(''); setFilters({ page: 1, pageSize: size }); }}
+            onClick={() => {
+              setDraftSearch('');
+              setFilters({ page: 1, pageSize: size });
+              setIncludeSubfolders(true);
+              // "Clear" resets the VIEW, and the open folder is part of the view
+              // a reader is looking at. Leaving them inside a folder with an
+              // emptied filter bar is the same half-answer as leaving the search
+              // term in the box.
+              openFolder(null);
+            }}
           >
             Clear
           </button>
@@ -411,52 +525,169 @@ export function LibraryPage({
         ) : null}
       </section>
 
+      {/* ONE LIST, CATEGORISED BY FOLDER STRUCTURE (bd startsim-nbhno). The tree
+          is not a second surface and not a second taxonomy — it is the shelf the
+          one list is standing on, which is the arrangement every computer user
+          already knows. When the corpus cannot enumerate folders the aside
+          simply is not there and this is the single-column list it has always
+          been; a half-drawn tree would be worse than none. */}
+      <div className={noTree ? '' : 'grid gap-6 md:grid-cols-[minmax(0,16rem)_minmax(0,1fr)]'}>
+        {noTree ? null : (
+          <aside className={`${cn.card} h-max`}>
+            <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-gray-500">
+              Folders
+            </h2>
+            <FolderTree
+              api={api}
+              selected={folder}
+              onSelect={openFolder}
+              classNames={folderClassNames}
+              onUnavailable={() => setNoTree(true)}
+            />
+          </aside>
+        )}
+
       <section className={cn.section}>
-        <div className="flex items-baseline justify-between">
-          <h2 className={cn.heading}>Library</h2>
+        <div className="flex items-baseline justify-between gap-4">
+          <h2 className={cn.heading}>{folder ? folderName(folder) : 'Library'}</h2>
           <p className={cn.muted}>
             {count} record{count === 1 ? '' : 's'}
             {count > 0 ? ` · page ${page} of ${lastPage}` : ''}
           </p>
         </div>
 
+        {/* WHERE YOU ARE. Derived from the open path, which the server returned;
+            every crumb re-asks the server for that container rather than
+            reusing anything already on screen. */}
+        {folder ? (
+          <nav aria-label="Folder path" className="flex flex-wrap items-center gap-1 text-sm">
+            <button
+              type="button"
+              className="text-gray-500 underline underline-offset-2 hover:text-gray-900"
+              onClick={() => openFolder(null)}
+            >
+              All documents
+            </button>
+            {folderTrail(folder).map((crumb, index, all) => (
+              <React.Fragment key={crumb.path}>
+                <span aria-hidden="true" className="text-gray-300">/</span>
+                {index === all.length - 1 ? (
+                  <span className="font-medium text-gray-900" aria-current="page">{crumb.name}</span>
+                ) : (
+                  <button
+                    type="button"
+                    className="text-gray-500 underline underline-offset-2 hover:text-gray-900"
+                    onClick={() => openFolder(crumb.path)}
+                  >
+                    {crumb.name}
+                  </button>
+                )}
+              </React.Fragment>
+            ))}
+            {/* THE CONTROL THAT MAKES THE BOUND VISIBLE, rather than a mode the
+                reader has to infer. Checked, the count beside the folder in the
+                tree is the count above the list; unchecked, the list is the
+                shelf and the difference is on screen as a thing they did. */}
+            <label className="ml-3 flex items-center gap-1.5 text-xs text-gray-600">
+              <input
+                type="checkbox"
+                checked={includeSubfolders}
+                onChange={(event) => {
+                  setIncludeSubfolders(event.target.checked);
+                  // A narrowing is a filter change: page 3 of the subtree is not
+                  // page 3 of the shelf.
+                  setFilters((prev) => ({ ...prev, page: 1 }));
+                }}
+              />
+              Include subfolders
+            </label>
+          </nav>
+        ) : null}
+
         {loading && documents.length === 0 ? <p className={cn.muted}>Loading…</p> : null}
 
         {!loading && documents.length === 0 ? (
-          <EmptyState hasFilters={Boolean(filters.search || filters.source || filters.partyId || filters.occurredAfter || filters.occurredBefore)} sources={sources} classNames={cn} />
+          // A FOLDER THAT HOLDS ITS DOCUMENTS ONE LEVEL DOWN, with the reader
+          // having narrowed to the shelf. Zero is the true answer to what they
+          // asked, but "Nothing matches those filters. Clear them to see
+          // everything." is the wrong advice — there is no filter to clear, and
+          // the remedy is one specific thing. So the remedy IS what stands here:
+          // the control, in the place the sentence was. Same rule as the row's
+          // Get text button, and the same reason.
+          folder && !includeSubfolders ? (
+            <button
+              type="button"
+              className={cn.button}
+              onClick={() => {
+                setIncludeSubfolders(true);
+                setFilters((prev) => ({ ...prev, page: 1 }));
+              }}
+            >
+              Include subfolders
+            </button>
+          ) : (
+            <EmptyState
+              hasFilters={Boolean(
+                filters.search || filters.source || filters.partyId
+                || filters.occurredAfter || filters.occurredBefore || folder,
+              )}
+              sources={sources}
+              classNames={cn}
+            />
+          )
         ) : null}
 
         <div className="space-y-2">
           {documents.map((document) => (
-            <button
-              key={document.id}
-              type="button"
-              className={cn.row}
-              aria-expanded={selectedId === document.id}
-              onClick={() => select(selectedId === document.id ? null : document.id)}
-            >
-              <div className="flex flex-wrap items-center gap-2">
-                {/* The source is a BADGE on every row, never a hidden column:
-                    "the AI learned this from a meeting" and "…from a contract in
-                    Drive" are different claims to whoever reads a draft later. */}
-                <span className={cn.badge}>{document.sourceLabel || document.source}</span>
-                <span className="font-medium text-gray-900">{document.title}</span>
-              </div>
-              <p className={cn.muted}>
-                {formatDate(document.occurredAt)}
-                {document.participants.length
-                  ? ` · ${document.participants.map((party) => party.name).join(', ')}`
-                  : ''}
-                {document.sections.length
-                  ? ` · ${document.sections.map((section) => section.label).join(', ')}`
-                  : ''}
-              </p>
-              {preview(document) ? (
-                <p className="mt-1 text-sm text-gray-600">{preview(document)}</p>
-              ) : (
-                <p className={cn.muted}>No text was captured for this record.</p>
+            // A DIV WRAPPING TWO BUTTONS, not one button wrapping everything.
+            // The row now carries an action of its own, and a button inside a
+            // button is invalid HTML that browsers resolve by dropping one of
+            // them — usually the one you wanted.
+            <div key={document.id} className={`${cn.row} flex items-start gap-3`}>
+              <button
+                type="button"
+                className="min-w-0 flex-1 text-left"
+                aria-expanded={selectedId === document.id}
+                onClick={() => select(selectedId === document.id ? null : document.id)}
+              >
+                <div className="flex flex-wrap items-center gap-2">
+                  {/* The source is a BADGE on every row, never a hidden column:
+                      "the AI learned this from a meeting" and "…from a contract
+                      in Drive" are different claims to whoever reads a draft
+                      later. */}
+                  <span className={cn.badge}>{document.sourceLabel || document.source}</span>
+                  <span className="font-medium text-gray-900">{document.title}</span>
+                </div>
+                <p className={cn.muted}>
+                  {formatDate(document.occurredAt)}
+                  {document.participants.length
+                    ? ` · ${document.participants.map((party) => party.name).join(', ')}`
+                    : ''}
+                  {document.sections.length
+                    ? ` · ${document.sections.map((section) => section.label).join(', ')}`
+                    : ''}
+                </p>
+                {preview(document) ? (
+                  <p className="mt-1 text-sm text-gray-600">{preview(document)}</p>
+                ) : null}
+              </button>
+
+              {/* WHERE THE SENTENCE USED TO BE. A row with no captured text said
+                  "No text was captured for this record." — an explanation
+                  standing in the place a control belongs, which tells a reader
+                  what happened and not what they may do. It is a BUTTON now,
+                  and it is disabled when the action genuinely cannot be
+                  performed. Quinn, 2026-08-27: "either have a button to pull the
+                  text, or have it grayed out if we can't do the action. simple
+                  ui." */}
+              {preview(document) ? null : (
+                <GetTextButton
+                  document={document}
+                  className={cn.button}
+                  onRequestText={onRequestText}
+                />
               )}
-            </button>
+            </div>
           ))}
         </div>
 
@@ -484,6 +715,7 @@ export function LibraryPage({
           </div>
         ) : null}
       </section>
+      </div>
 
       {selected ? (
         <DocumentDetail
@@ -508,6 +740,72 @@ export function LibraryPage({
   );
 }
 
+// ---------------------------------------------------------------------------
+//  the row's own action
+// ---------------------------------------------------------------------------
+
+/**
+ * "Get text" on a record that has none — ENABLED when the corpus can fetch it,
+ * GREYED OUT when it cannot (bd startsim-ei8gm.5).
+ *
+ * THIS REPLACED A SENTENCE, and the swap is the point. The row used to read
+ * "No text was captured for this record." in exactly this slot. That is an
+ * explanation where a control belongs: it answers "what happened" when the
+ * reader was asking "what can I do", and it is the thing Quinn objected to in
+ * those words — "don't say stupid shit like 'no text blah blah'. either have a
+ * button to pull the text, or have it grayed out if we can't do the action.
+ * simple ui." A disabled control answers the real question in the standard
+ * vocabulary of every desktop application ever written.
+ *
+ * DISABLED IS THE HONEST STATE TODAY, not a placeholder. Content is opt-in and
+ * never the default (bd startsim-h6xnu) — the corpus owes what exists, where it
+ * lives and findability, and pulling every file's bytes is the expensive,
+ * privacy-loaded half that was deliberately not built. The route that would make
+ * this live is bd startsim-99g8.2. When it lands, an app passes `onRequestText`
+ * and the same control wakes up; nothing here changes.
+ *
+ * `title` CARRIES THE WHY, and a tooltip on a control is not the sentence that
+ * was removed: it is attached to the thing it is about, costs no row space, and
+ * a reader who does not care never reads it. `aria-disabled` is not used in its
+ * place — a genuinely inert control should not be focusable-and-lying.
+ */
+function GetTextButton({
+  document, className, onRequestText,
+}: {
+  document: SourceDocument;
+  className: string;
+  onRequestText?: (document: SourceDocument) => void | Promise<void>;
+}) {
+  const [busy, setBusy] = React.useState(false);
+  const [failed, setFailed] = React.useState('');
+  const can = Boolean(onRequestText);
+
+  return (
+    <button
+      type="button"
+      className={`${className} shrink-0 self-start`}
+      disabled={!can || busy}
+      title={
+        can
+          ? `Fetch the text of ${document.title}`
+          : 'This workspace does not pull file contents. Nothing has been extracted from this record.'
+      }
+      onClick={() => {
+        if (!onRequestText) return;
+        setBusy(true);
+        setFailed('');
+        void Promise.resolve(onRequestText(document))
+          .catch((err: unknown) => setFailed(
+            (err as { message?: string })?.message || 'Could not fetch the text.',
+          ))
+          .finally(() => setBusy(false));
+      }}
+    >
+      {busy ? 'Getting…' : failed ? 'Retry' : 'Get text'}
+    </button>
+  );
+}
+
 // ---------------------------------------------------------------------------
 //  freshness
 // ---------------------------------------------------------------------------

package/src/corpus/client.ts

@@ -32,6 +32,7 @@
  */
 import {
   DEFAULT_PARTICIPANT_EDGES,
+  FOLDER_ROOT,
   DEFAULT_RUN_KEY,
   DEFAULT_TYPE_KEYS,
   MAX_ID_LIST,
@@ -40,11 +41,14 @@ import {
   indexParticipants,
   toCommitment,
   toExtractionRun,
+  toFolder,
   toMoneyEvent,
   toParty,
   toSourceDocument,
 } from './entities';
-import type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
+import type {
+  CorpusTypeKeys, TenantEntity, TenantFacetRow, TenantRelationship,
+} from './entities';
 import {
   FOCUS_TYPE,
   IN_FOCUS,
@@ -58,9 +62,11 @@ import type {
   CommitmentApi,
   CommitmentQuery,
   CorpusApi,
+  CorpusFolder,
   CorpusPage,
   CorpusScope,
   DocumentQuery,
+  FolderQuery,
   ExtractionRun,
   ExtractionRunStore,
   AuthoredItem,
@@ -214,6 +220,17 @@ interface ServerFilterReport {
  */
 const TEXT_FILTER_MAX = 500;
 
+/**
+ * The attribute the folder tree is DERIVED from (start-simpli-api#369 ships it
+ * as a source-agnostic container: `/Contracts`, never `/Contracts/SOW.pdf`).
+ *
+ * One name, in one place, because the facet read enumerates it and the document
+ * filter narrows on it — and a tree whose nodes came from one attribute while
+ * its file lists filtered on another would draw folders that open onto nothing.
+ */
+const PATH_ATTRIBUTE = 'path';
+
+
 function commitmentParams(query: CommitmentQuery, type: string): Record<string, unknown> {
   const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
   const out: Record<string, unknown> = {
@@ -270,6 +287,8 @@ const DOCUMENT_FILTER_PARAMS: Array<[keyof DocumentQuery, string[]]> = [
   ['partyId', ['party', 'related_to']],
   ['occurredAfter', ['occurred_after', 'attr.occurred_at__gte']],
   ['occurredBefore', ['occurred_before', 'attr.occurred_at__lte']],
+  ['folder', ['attr.path']],
+  ['underFolder', ['attr.path__under']],
 ];
 
 function reportedDocumentFilters(query: DocumentQuery, applied: string[]): string[] {
@@ -351,6 +370,39 @@ function params(query: DocumentQuery, type: string) {
   if (query.partyId) out.party = query.partyId;
   if (query.occurredAfter) out.occurred_after = query.occurredAfter;
   if (query.occurredBefore) out.occurred_before = query.occurredBefore;
+  // THE FOLDER BOUNDS, and only ever one of them. `attr.path` is the shelf and
+  // `attr.path__under` is the subtree; sending both would AND an exact match
+  // with its own subtree and answer with the shelf, which is the exact-match
+  // query wearing a second parameter. The composer chooses; this just refuses to
+  // send a contradiction.
+  if (query.underFolder) out['attr.path__under'] = query.underFolder;
+  else if (query.folder) out['attr.path'] = query.folder;
+  return out;
+}
+
+/**
+ * `GET /api/v1/entities/facets/` — its OWN parameter builder, and that is not
+ * tidiness (bd startsim-ei8gm.5).
+ *
+ * THE FACET ACTION REFUSES UNKNOWN PARAMETERS. `_Scoped.initial()` screens it
+ * against `_FACET_FILTERS` before any handler runs — the tenant added
+ * `extra_list_parameters` precisely so a new list-shaped route could not inherit
+ * the old fail-open posture — so handing it `params(query, type)` would 400 the
+ * whole read on `occurred_after`, `party` or `source` the moment a filter was
+ * set. Its vocabulary is the entity filters PLUS `attr` and `under`, and this
+ * sends exactly `type`, `attr`, `under` and the page.
+ */
+function facetParams(query: FolderQuery, type: string) {
+  const out: Record<string, unknown> = {
+    type,
+    attr: PATH_ATTRIBUTE,
+    // The FULL path the server handed back, verbatim. `/` is the root and means
+    // the whole corpus — `subtree_bound()` makes the root's descendant prefix
+    // `/`, which every stored path begins with.
+    under: query.under || FOLDER_ROOT,
+    page: query.page ?? 1,
+  };
+  if (query.pageSize) out.page_size = query.pageSize;
   return out;
 }
 
@@ -359,9 +411,9 @@ function appliedFilters(
   query: DocumentQuery,
   supported: Array<string>,
 ): string[] {
-  const requested = (['search', 'source', 'partyId', 'occurredAfter', 'occurredBefore'] as const).filter(
-    (key) => Boolean(query[key]),
-  );
+  const requested = ([
+    'search', 'source', 'partyId', 'occurredAfter', 'occurredBefore', 'folder', 'underFolder',
+  ] as const).filter((key) => Boolean(query[key]));
   return requested.filter((key) => supported.includes(key));
 }
 
@@ -683,6 +735,38 @@ export function createCorpusApi(
       return page<Party>(types.party, query, (entity) => toParty(entity, scope));
     },
 
+    /**
+     * ONE LEVEL of the folder tree (bd startsim-ei8gm.5).
+     *
+     * `GET /api/v1/entities/facets/?type=source_document&attr=path&under=/Contracts`
+     * -> the CHILD FOLDERS of `/Contracts`, paginated, each row already carrying
+     * its descendant count and whether anything sits below it.
+     *
+     * THE GATE IS THE SERVER'S AND IT STAYS THERE. The tenant answers this out
+     * of `EntityViewSet.get_queryset()` itself — the same type gate, row gate,
+     * field gate and filters the row read composes — so the folders a member is
+     * shown are the folders their own documents are in, and nothing else. On a
+     * tenant whose `source_document` is `row_scope: personal` that is the whole
+     * of the protection: a folder name leaks plenty on its own
+     * (`/Legal/Terminations`, `/Acquisition-TargetCo`). Which is why this method
+     * asks for ONE `under=` and returns exactly what came back for it. It does
+     * not cache across containers, does not merge two responses, and does not
+     * infer a parent from a child's path — any of which would rebuild the leak
+     * client-side out of rows the server was careful about.
+     */
+    async listFolders(query: FolderQuery): Promise<CorpusPage<CorpusFolder>> {
+      const response = await http.get<DrfPage<TenantFacetRow> & ServerFilterReport>(
+        `${entities}/facets`,
+        { params: facetParams(query, types.document) },
+      );
+      return {
+        count: response.count ?? response.results?.length ?? 0,
+        next: response.next ?? null,
+        previous: response.previous ?? null,
+        results: (response.results ?? []).map(toFolder),
+      };
+    },
+
     async listMoneyEvents(query = {}) {
       const events = await page<TenantEntity>(types.moneyEvent, query, (entity) => entity);
       const byRecord = await participantsFor(events.results.map((entity) => entity.id));