@catheadowl/ukp 0.2.3 → 0.2.5

package/src/commands/inventory.ts

@@ -36,6 +36,22 @@ export interface InventoryCommandContext {
   resolveProvider?: ProviderResolver;
   /** Test injection point for the ssh binary behind ssh:// transports. */
   sshCommand?: readonly string[];
+  /** Streaming seam (ukp_list W2 / ADR 0026 rule 3): when present, the
+   * remote-mixed branch delivers stdout line-by-line through it — the header
+   * and every local row flush synchronously before any network work starts,
+   * remote rows append in registry order as they resolve — and the returned
+   * result carries an empty stdout (the output already went out on this
+   * channel; writeCommandResult's falsy check skips the final print).
+   * Absent, the full text returns in result.stdout unchanged. The all-local
+   * path never streams: it stays synchronous and byte-identical either
+   * way. */
+  emitStdout?: (line: string) => void;
+  /** Progress seam (ukp_list W2 / ADR 0026 rule 3): self-contained stderr
+   * frames for the remote fetch — the first frame is plain text, updates
+   * carry a leading \r, the final frame clears the line. The wiring layer
+   * injects it only when stderr is a TTY, so piped runs stay silent and
+   * stdout never gains a control character. */
+  emitProgress?: (frame: string) => void;
 }
 
 export interface InventoryCommandResult {
@@ -52,13 +68,13 @@ export const REGISTER_SPEC: UkpCommandSpec = {
   summary: "register a Service endpoint",
   group: "registry",
   description:
-    "Register the current Service folder, a remote ukp-serve endpoint via --url, or — when that url is a host door — every endpoint behind it in one gesture.",
+    "Register the current Service folder, a remote ukp-serve endpoint via --url, or - when that url is a host door - every endpoint behind it in one gesture.",
   usage: "[options]",
   strictArguments: true,
   options: [
-    { flags: "--url <url>", help: "register a remote ukp-serve endpoint (https://host[:port], ssh://host[/endpoint] — ssh takes no port, the woken door picks its own — or loopback http); a host door url (its document declares scope:\"host\") imports every endpoint behind the door — binding urls gain the endpoint-name path (ssh://ali/notes)" },
+    { flags: "--url <url>", help: "register a remote ukp-serve endpoint (https://host[:port], ssh://host[/endpoint] - ssh takes no port, the woken door picks its own - or loopback http); a host door url (its document declares scope:\"host\") imports every endpoint behind the door - binding urls gain the endpoint-name path (ssh://ali/notes)" },
     { flags: "--endpoint <name>", help: "assert the remote-declared name of the endpoint being registered (expected-name assertion; with a host door this imports only that endpoint)" },
-    { flags: "--name <handle>", help: "remote only: register under this local handle — the registry key and ukp:// authority — instead of the declared name; use it when the declared name is already taken" },
+    { flags: "--name <handle>", help: "remote only: register under this local handle - the registry key and ukp:// authority - instead of the declared name; use it when the declared name is already taken" },
     { flags: "--select <names>", help: "with a host door url: import only the named endpoints (comma-separated); a name not on the door is a usage error" },
     { flags: "--token <token>", help: "store the bearer token in the binding (plaintext, 0600 registry file); with a host door it is copied into every imported binding; UKP_ENDPOINT_<NAME>_TOKEN overrides it at call time" },
   ],
@@ -75,7 +91,7 @@ export const REGISTER_SPEC: UkpCommandSpec = {
     "  With --url, the declared name and instance identity come from the",
     "  remote discovery document (/.well-known/ukp.json) and are pinned",
     "  TOFU-style as provenance; your registry binds them under a local",
-    "  handle — the declared name by default, or --name <handle> when that",
+    "  handle - the declared name by default, or --name <handle> when that",
     "  name is already taken. Use --endpoint <name> as an expected-name",
     "  assertion on the declared name; bearer-token services read",
     "  UKP_ENDPOINT_<NAME>_TOKEN (keyed by the handle) at call time.",
@@ -85,7 +101,7 @@ export const REGISTER_SPEC: UkpCommandSpec = {
     "  and imports every endpoint behind it (a door url may also name one",
     "  endpoint: ssh://ali/notes). Import is explicit and idempotent:",
     "  re-running refreshes TOFU pins and tokens. Name conflicts are skipped",
-    "  with a visible reason (never silently renamed) — re-register that one",
+    "  with a visible reason (never silently renamed) - re-register that one",
     "  endpoint with --name to land it under another handle; --select narrows",
     "  the import; door growth shows in 'ukp list' as drift notes until",
     "  imported.",
@@ -126,7 +142,23 @@ const DEFAULT_CAPABILITIES = (Object.keys(FILE_NATIVE_CAPABILITIES) as Array<key
   .filter((name) => FILE_NATIVE_CAPABILITIES[name].derived)
   .sort();
 
-function renderLocalListRow(endpoint: { name: string; path: string }): { line: string; warning?: string } {
+/** One list row as structured cells — column geometry is decided once, in
+ * renderListOutput, from every row's actual widths (raw tab stops made the
+ * columns land on a different multiple-of-8 per row once names, paths and
+ * urls of very different widths mixed). */
+interface InventoryListRow {
+  /** Endpoint handle; a remote handle that differs from its declared name
+   * carries the declaration inline (`name (declares X)`). */
+  name: string;
+  /** Local folder path or remote binding url. */
+  location: string;
+  /** Comma-separated declared extras, `-` for none, `(unavailable)` on
+   * degraded rows. */
+  capabilities: string;
+  warning?: string;
+}
+
+function renderLocalListRow(endpoint: { name: string; path: string }): InventoryListRow {
   let service;
   try {
     service = loadManifest(endpoint.path);
@@ -135,14 +167,16 @@ function renderLocalListRow(endpoint: { name: string; path: string }): { line: s
     // when the underlying ManifestError carries a full zod schema dump.
     const headline = (error instanceof Error ? error.message : String(error)).split("\n")[0];
     return {
-      line: `${endpoint.name}\t${endpoint.path}\t(unavailable)`,
-      warning: `endpoint '${endpoint.name}' capabilities unavailable: ${headline}`,
+      name: endpoint.name,
+      location: endpoint.path,
+      capabilities: "(unavailable)",
+      warning: `endpoint '${endpoint.name}' declared capabilities unavailable: ${headline}`,
     };
   }
   const extras = Object.keys(service.manifest.capabilities)
     .filter((name) => !(isFileNativeCapability(name) && FILE_NATIVE_CAPABILITIES[name].derived))
     .sort();
-  return { line: `${endpoint.name}\t${endpoint.path}\t${extras.length > 0 ? extras.join(",") : "-"}` };
+  return { name: endpoint.name, location: endpoint.path, capabilities: extras.length > 0 ? extras.join(",") : "-" };
 }
 
 export function executeRegisterCommand(
@@ -351,6 +385,7 @@ async function executeRegisterRemote(
     const wellKnown = await fetchRegistrationDocument(transport.base, {
       ...(token !== undefined ? { token } : {}),
       ...(pinSelfSigned && tlsProbe !== undefined ? { tlsAnchor: { ca: tlsProbe.certPem } } : {}),
+      displayUrl: parts.origin,
     });
 
     if (wellKnown.kind === "door") {
@@ -520,22 +555,97 @@ export function executeListCommand(
     // byte-identical and synchronous. One transport pool serves the whole
     // invocation (O-5): same-origin door bindings — and their drift check —
     // share a single ssh tunnel.
+    //
+    // Fan-out + streaming (ukp_list W1/W2 / ADR 0026 rules 1 and 3): local
+    // rows flush first — they are registry data in memory, so first output
+    // needs no network at all — then every remote fetch and the drift check
+    // start together (wall clock = max over origins, not the sum;
+    // same-origin acquires converge on the pool's single open promise), and
+    // remote rows append in registry order as they resolve, never rewriting
+    // an already-emitted line. Row order is W2's one agent-visible change:
+    // locals first, then remotes, each group in registry (name-sorted)
+    // order.
     return (async () => {
       const pool = createTransportPool({
         registryPath: context.registryPath,
         ...(context.sshCommand === undefined ? {} : { sshCommand: context.sshCommand }),
       });
       try {
-        const rendered: Array<{ line: string; warning?: string }> = [];
-        for (const endpoint of endpoints) {
-          if (!isRemoteBinding(endpoint)) {
-            rendered.push(renderLocalListRow({ name: endpoint.name, path: endpoint.path! }));
-            continue;
-          }
-          rendered.push(await renderRemoteListRow(endpoint, pool));
+        const localRows = endpoints
+          .filter((endpoint) => !isRemoteBinding(endpoint))
+          .map((endpoint) => renderLocalListRow({ name: endpoint.name, path: endpoint.path! }));
+        // Column geometry is decided once, before the first flush, from
+        // every row's registry-known leading cells (ADR 0026 rule 4): only
+        // the last cell depends on the network, so streaming never shifts a
+        // column width.
+        const geometry = listRowGeometry([
+          ...localRows,
+          ...remotes.map((endpoint) => ({ name: remoteRowName(endpoint), location: endpoint.url! })),
+        ]);
+        const lines: string[] = [];
+        // The progress line and the streamed rows share one terminal: a
+        // frame never ends with \n, so the cursor parks at its end — the
+        // next row would print BESIDE the frame and the following \r would
+        // overwrite the row's head (Windows Terminal dogfood finding). The
+        // interlock: every row flush clears the frame first, owns its line,
+        // and lets the next drawProgress redraw on the fresh bottom row.
+        // With no progress channel (piped runs) the clear is a no-op and
+        // the stream is untouched.
+        const progress = context.emitProgress;
+        let progressWidth = 0;
+        const drawProgress = (frame: string) => {
+          if (progress === undefined) return;
+          progress(frame);
+          progressWidth = frame.length;
+        };
+        const clearProgress = () => {
+          if (progress === undefined || progressWidth === 0) return;
+          progress(`\r${" ".repeat(progressWidth)}\r`);
+          progressWidth = 0;
+        };
+        const flush = (line: string) => {
+          clearProgress();
+          lines.push(line);
+          context.emitStdout?.(line);
+        };
+
+        flush(listHeaderLine());
+        for (const row of localRows) flush(renderListLine(row, geometry));
+
+        // Everything network-facing starts only after the local flush — and
+        // the progress line goes out first, so the user never watches a
+        // spinner-less wait. Frames must stay ASCII/narrow and each update
+        // at least as wide as its predecessor: the clear blanks
+        // progressWidth columns, so a wider glyph than code units (or a
+        // shorter update) would leave stale tail cells on a real terminal.
+        drawProgress(`fetching ${remotes.length} remote endpoint(s)...`);
+        const remoteRows = remotes.map((endpoint) => renderRemoteListRow(endpoint, pool));
+        const drift = collectDoorDriftNotes(endpoints, pool);
+
+        const warnings = localRows.flatMap((row) => (row.warning !== undefined ? [row.warning] : []));
+        let done = 0;
+        // Head-of-line emission: the fetches already run concurrently; rows
+        // print in registry order as their predecessors resolve. Each flush
+        // cleared the frame; the update redraws it on the fresh bottom row.
+        for (const row of remoteRows) {
+          const resolved = await row;
+          flush(renderListLine(resolved, geometry));
+          if (resolved.warning !== undefined) warnings.push(resolved.warning);
+          done += 1;
+          if (done < remotes.length) drawProgress(`\rfetching remote endpoint(s): ${done}/${remotes.length}`);
         }
-        const drift = await collectDoorDriftNotes(endpoints, pool);
-        return renderListOutput(rendered, [...collectSameInstanceNotes(endpoints), ...drift]);
+        // Cleared before the drift await (the last row's flush already
+        // blanked the frame): every row is on screen, so the table reads
+        // complete while the stderr footnotes gather — an https door's
+        // drift fetch may be the slowest leg and a spinner under a finished
+        // table would be noise.
+        clearProgress();
+        const stderrLines = [...warnings, ...collectSameInstanceNotes(endpoints), ...(await drift)];
+        return {
+          exitCode: 0,
+          stdout: context.emitStdout === undefined ? lines.join("\n") : "",
+          stderr: stderrLines.length > 0 ? `${stderrLines.join("\n")}\n` : "",
+        };
       } finally {
         pool.close();
       }
@@ -552,14 +662,11 @@ export function executeListCommand(
 }
 
 function renderListOutput(
-  rows: ReadonlyArray<{ line: string; warning?: string }>,
+  rows: ReadonlyArray<InventoryListRow>,
   extraNotes: readonly string[] = [],
 ): InventoryCommandResult {
   const warnings = [...rows.flatMap((row) => (row.warning !== undefined ? [row.warning] : [])), ...extraNotes];
-  const stdout = [
-    `capabilities on every endpoint: ${DEFAULT_CAPABILITIES.join(", ")} (derived file-native); additional declared capabilities per endpoint:`,
-    ...rows.map((row) => row.line),
-  ].join("\n");
+  const stdout = [listHeaderLine(), ...rows.map((row) => renderListLine(row, listRowGeometry(rows)))].join("\n");
   return {
     exitCode: 0,
     stdout,
@@ -567,20 +674,57 @@ function renderListOutput(
   };
 }
 
+function listHeaderLine(): string {
+  // The parenthetical is plain-language by probe verdict (20260921-list-wording):
+  // blank readers parsed "(built-in, from the folder itself)" directly, while
+  // "(derived file-native)" read as undefined jargon.
+  return `capabilities on every endpoint: ${DEFAULT_CAPABILITIES.join(", ")} (built-in, from the folder itself); additional declared capabilities per endpoint:`;
+}
+
+/** Space-padded columns: each cell pads to the widest same-column cell plus
+ * a two-space gutter (the guide topic list's idiom), last column unpadded so
+ * no line carries trailing whitespace. Tab-separated rows rendered ragged
+ * whenever name/location widths straddled the terminal's tab stops. The
+ * padded columns are registry-known strings (ADR 0026 rule 4): only the
+ * last, unpadded cell depends on the remote fetch — so geometry can be
+ * computed before the first flush and streaming never shifts a width. */
+interface ListRowGeometry {
+  nameWidth: number;
+  locationWidth: number;
+}
+
+function listRowGeometry(rows: ReadonlyArray<Pick<InventoryListRow, "name" | "location">>): ListRowGeometry {
+  return {
+    nameWidth: Math.max(...rows.map((row) => row.name.length)),
+    locationWidth: Math.max(...rows.map((row) => row.location.length)),
+  };
+}
+
+function renderListLine(row: InventoryListRow, geometry: ListRowGeometry): string {
+  return `${row.name.padEnd(geometry.nameWidth)}  ${row.location.padEnd(geometry.locationWidth)}  ${row.capabilities}`;
+}
+
+/** The name cell of a remote row — registry-known without any network, so
+ * column geometry and the streamed local flush can lay out before any
+ * fetch resolves. A handle that differs from the declared name
+ * (ADR-REM-007) carries the declaration inline for audit. */
+function remoteRowName(endpoint: RegistryBinding): string {
+  return endpoint.declared_name !== undefined && endpoint.declared_name !== endpoint.name
+    ? `${endpoint.name} (declares ${endpoint.declared_name})`
+    : endpoint.name;
+}
+
 /** Remote row: capabilities from the discovery document; unreachable
  * endpoints degrade to `(unavailable)` + one stderr warning — the same
  * inventory semantics as an unreadable local manifest. Door-form bindings
  * (`ssh://ali/notes`) fetch their per-endpoint document through the shared
- * pool's tunnel. A handle that differs from the declared name (ADR-REM-007)
- * carries the declaration inline for audit. */
+ * pool's tunnel. */
 async function renderRemoteListRow(
   endpoint: RegistryBinding,
   pool: RemoteTransportPool,
-): Promise<{ line: string; warning?: string }> {
+): Promise<InventoryListRow> {
   const url = endpoint.url!;
-  const declaredNote = endpoint.declared_name !== undefined && endpoint.declared_name !== endpoint.name
-    ? ` (declares ${endpoint.declared_name})`
-    : "";
+  const name = remoteRowName(endpoint);
   try {
     const transport = await pool.acquire(endpoint);
     const discovery = await fetchDiscoveryDocument(endpoint, transport, resolveRemoteToken(endpoint));
@@ -589,12 +733,14 @@ async function renderRemoteListRow(
       .map(([name]) => name)
       .sort();
     const warnings = discovery.warnings.length > 0 ? { warning: discovery.warnings.join("; ") } : {};
-    return { line: `${endpoint.name}${declaredNote}\t${url}\t${extras.length > 0 ? extras.join(",") : "-"}`, ...warnings };
+    return { name, location: url, capabilities: extras.length > 0 ? extras.join(",") : "-", ...warnings };
   } catch (error) {
     const headline = (error instanceof Error ? error.message : String(error)).split("\n")[0];
     return {
-      line: `${endpoint.name}${declaredNote}\t${url}\t(unavailable)`,
-      warning: `endpoint '${endpoint.name}' capabilities unavailable: ${headline}`,
+      name,
+      location: url,
+      capabilities: "(unavailable)",
+      warning: `endpoint '${endpoint.name}' declared capabilities unavailable: ${headline}`,
     };
   }
 }
@@ -616,7 +762,7 @@ function collectSameInstanceNotes(endpoints: readonly RegistryBinding[]): string
   for (const [uid, handles] of byUid) {
     if (handles.length > 1) {
       notes.push(
-        `note: ${[...handles].sort().map((handle) => `'${handle}'`).join(" and ")} pin the same instance_uid ${uid} — one service under two handles`,
+        `note: ${[...handles].sort().map((handle) => `'${handle}'`).join(" and ")} pin the same instance_uid ${uid} - one service under two handles`,
       );
     }
   }
@@ -661,7 +807,7 @@ async function collectDoorDriftNotes(
         url: origin,
         ...(anchor.tls_cert !== undefined ? { tls_cert: anchor.tls_cert, tls_pin: anchor.tls_pin } : {}),
       });
-      const door = await fetchDoorDocument(transport.base, {});
+      const door = await fetchDoorDocument(transport.base, { displayUrl: transport.displayUrl });
       const unimported = door.doc.endpoints
         .map((endpoint) => endpoint.name)
         .filter((name) => !group.imported.has(name));
@@ -674,12 +820,12 @@ async function collectDoorDriftNotes(
       const taken = unimported.filter((name) => endpoints.some((binding) => binding.name === name));
       if (free.length > 0) {
         notes.push(
-          `door ${origin}: ${free.length} unimported endpoint(s): ${free.join(", ")} — run 'ukp register --url ${origin}' to import`,
+          `door ${origin}: ${free.length} unimported endpoint(s): ${free.join(", ")} - run 'ukp register --url ${origin}' to import`,
         );
       }
       if (taken.length > 0) {
         notes.push(
-          `door ${origin}: name(s) taken: ${taken.join(", ")} — import under another handle: 'ukp register --url ${origin}/<name> --name <handle>'`,
+          `door ${origin}: name(s) taken: ${taken.join(", ")} - import under another handle: 'ukp register --url ${origin}/<name> --name <handle>'`,
         );
       }
     } catch {

package/src/commands/propose.ts

@@ -73,7 +73,7 @@ export const PROPOSE_SPEC: UkpCommandSpec = {
   options: [
     {
       flags: "--id <slug>",
-      help: "revision key: resubmitting the same id updates the same proposal (revision +1); 1-63 lowercase ASCII slug (enforced for explicit ids and the default alike); defaults to the --file basename, which then becomes the proposal's persistent id — renaming the file creates a new proposal",
+      help: "revision key: resubmitting the same id updates the same proposal (revision +1); 1-63 lowercase ASCII slug (enforced for explicit ids and the default alike); defaults to the --file basename, which then becomes the proposal's persistent id - renaming the file creates a new proposal",
     },
     { flags: "--file <path>", help: "read the proposal content from a file (required)" },
     { flags: "--json", help: "emit the structured response envelope" },

package/src/commands/read.ts

@@ -96,18 +96,18 @@ export const READ_SPEC: UkpCommandSpec = {
     },
     {
       flags: "--show-pin",
-      help: "emit the ukp-pin for the read resource on stderr (<!-- ukp-pin: sha256-… -->, whole-file LF-normalized sha256; embed next to a ukp:// reference to power rename recovery). Local reads allow a line window — the pin still covers the whole file; remote reads need the whole file, so drop the window there",
+      help: "emit the ukp-pin for the read resource on stderr (<!-- ukp-pin: sha256-... -->, whole-file LF-normalized sha256; embed next to a ukp:// reference to power rename recovery). Local reads allow a line window - the pin still covers the whole file; remote reads need the whole file, so drop the window there",
     },
     { flags: "--format <mode>", help: "output mode: 'json' emits a structured failure envelope (body still goes to stdout); default is human output" },
   ],
   helpSuffix: [
     "",
     "Reference forms:",
-    "  endpoint-local path — requires --endpoint <name>",
-    "  ukp://<endpoint>/<rel-path>[#L<line>] — carries its own endpoint",
-    "  docid[:line] / qmd://<reference> — provider-owned references;",
+    "  endpoint-local path - requires --endpoint <name>",
+    "  ukp://<endpoint>/<rel-path>[#L<line>] - carries its own endpoint",
+    "  docid[:line] / qmd://<reference> - provider-owned references;",
     "  require --endpoint <name> and are resolved by the Service's provider",
-    "  absolute filesystem path — the owning endpoint is matched from the",
+    "  absolute filesystem path - the owning endpoint is matched from the",
     "  Host Registry (mapping echoed on stderr)",
     "",
   ].join("\n"),
@@ -481,7 +481,7 @@ async function executeRemoteRead(
       exitCode: 2,
       stdout: "",
       stderr: renderReadUsageError(
-        "--show-pin needs whole-file content; drop the line window (--lines / #L) — the pin always covers the whole file",
+        "--show-pin needs whole-file content; drop the line window (--lines / #L) - the pin always covers the whole file",
       ),
     };
   }

package/src/commands/rg.ts

@@ -3,6 +3,7 @@ import {
   projectRgEnvelope,
   renderRgHuman,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   RgPlanningError,
   RgUsageError,
@@ -11,6 +12,7 @@ import {
   type RgAggregateStatus,
   type RgContext,
   type RgEndpointOutcome,
+  type RgMode,
   type RgResult,
 } from "../capabilities/rg.ts";
 import { EXTERNAL_PROVIDER } from "../config/external-tool.ts";
@@ -50,17 +52,19 @@ export const RG_SPEC: UkpCommandSpec = {
   summary: "grep raw endpoint files with ripgrep (no index or declaration needed; results as ukp:// references)",
   group: "endpoint",
   description:
-    "Run base lexical search (ripgrep) across one or more Service endpoints. "
+    "Run base lexical search (ripgrep) across one or more Service endpoints, "
+    + "or enumerate their files with --files. "
     + "Available on every registered endpoint by default; results are shaped into ukp:// references that 'ukp read' consumes directly. "
     + "For indexed/semantic search use 'ukp search'.",
-  usage: "[--endpoint <name> ... | -g] <pattern> [--limit <1-1000>] [--count] [--glob <glob>] [--type <type>] [-i] [-- <rg flags>]",
-  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell" }],
+  usage: "[--endpoint <name> ... | -g] (<pattern> | --files) [--limit <1-1000>] [--count] [--glob <glob> ...] [--type <type>] [-i] [-- <rg flags>]",
+  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell (omit with --files)" }],
   options: [
     { flags: "-c, --endpoint <name>", help: "select one endpoint; repeat to select multiple endpoints", multi: true },
     { flags: "-g", help: "search every endpoint in the Host Registry; takes no value" },
-    { flags: "--limit <1-1000>", help: `maximum matches per run (default: ${RG_DEFAULT_LIMIT})` },
+    { flags: "--limit <1-1000>", help: `maximum results per run (default: ${RG_DEFAULT_LIMIT}; ${RG_FILES_DEFAULT_LIMIT} with --files)` },
     { flags: "--count", help: "count mode: per-file match counts instead of matches" },
-    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\")" },
+    { flags: "--files", help: "files mode: enumerate files by tree walk with no pattern (empty and binary files included; combine with --glob/--type)" },
+    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\"); repeat to combine - a later glob may negate with !", multi: true },
     { flags: "--type <type>", help: "file type filter passed to rg (e.g. md, py)" },
     { flags: "-i", help: "case-insensitive search" },
     { flags: "--json", help: "emit the structured response envelope" },
@@ -69,7 +73,8 @@ export const RG_SPEC: UkpCommandSpec = {
     "",
     "Passthrough:",
     "  After '--', rg native flags are passed through on an allowlist",
-    "  (-A/-B/-C/-m/--glob/--type/--max-filesize and common boolean flags).",
+    "  (-A/-B/-C/-m/--glob/--iglob/--type/--max-filesize and common boolean",
+    "  flags).",
     "  Path operands and output-changing flags (--json, -r, --pre, --config)",
     "  are rejected: the endpoint selector owns scope, UKP owns the output.",
     "",
@@ -84,6 +89,12 @@ export const RG_SPEC: UkpCommandSpec = {
     "  'ukp search' covers indexed search where the Service declares a search",
     "  capability provider.",
     "",
+    "Visibility:",
+    "  Every rg mode skips hidden files (dot-prefixed, including the .ukp/",
+    "  wiring) by default; pass -- --hidden after '--' to include them",
+    "  (-uu additionally lifts .gitignore rules). --files lists every",
+    "  non-hidden file, including empty and binary ones.",
+    "",
   ].join("\n"),
 };
 
@@ -92,7 +103,8 @@ interface RgCommandOptions extends Record<string, unknown> {
   g?: boolean;
   limit?: string;
   count?: boolean;
-  glob?: string;
+  files?: boolean;
+  glob?: string[];
   type?: string;
   i?: boolean;
   json?: boolean;
@@ -102,10 +114,13 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
   const parsed = parseKitArgs<RgCommandOptions>(RG_SPEC, args);
   const explicit: string[] = [];
   const warnings: string[] = [];
+  const files = parsed.options.files === true;
 
   // Command-side semantic checks, in the pre-kit order: limit validation,
-  // duplicate warnings, excess positional, emptiness, conflict.
-  let limit = RG_DEFAULT_LIMIT;
+  // duplicate warnings, excess positional, mode conflicts, pattern rule,
+  // scope conflict. Files mode (ADR-RG-005) relaxes the pattern requirement
+  // and rejects combinations that would silently no-op.
+  let limit = files ? RG_FILES_DEFAULT_LIMIT : RG_DEFAULT_LIMIT;
   if (parsed.options.limit !== undefined) {
     if (!/^[0-9]+$/.test(parsed.options.limit)) throw new KitUsageError("--limit must be a decimal integer");
     limit = Number(parsed.options.limit);
@@ -125,20 +140,34 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
       `unexpected argument '${unexpected}'; rg accepts exactly one pattern. Use '--endpoint <name>' to select an endpoint; '-g' takes no value.`,
     );
   }
-  if (pattern === undefined || pattern.length === 0) throw new KitUsageError("rg pattern must be non-empty");
+  if (files && parsed.options.count === true) {
+    throw new KitUsageError("--files and --count cannot be used together (pick one output mode)");
+  }
+  if (files && parsed.options.i === true) {
+    throw new KitUsageError("--files cannot be combined with -i: there is no pattern to match; pass '-- --iglob <glob>' for a case-insensitive glob filter");
+  }
+  if (files) {
+    if (pattern !== undefined) {
+      throw new KitUsageError(`unexpected argument '${pattern}'; --files takes no pattern - use --glob to filter by name`);
+    }
+  } else if (pattern === undefined || pattern.length === 0) {
+    throw new KitUsageError("rg pattern must be non-empty (or pass --files to enumerate files without a pattern)");
+  }
   if (parsed.options.g && explicit.length > 0) {
     throw new KitUsageError("--endpoint and -g cannot be used together");
   }
 
+  const globs = parsed.options.glob ?? [];
   return {
-    request: { query: pattern, limit },
+    request: { query: files ? "" : pattern!, limit },
     options: {
       explicitEndpoints: explicit.length > 0 ? explicit : undefined,
       global: parsed.options.g ?? false,
-      ...(parsed.options.glob === undefined ? {} : { glob: parsed.options.glob }),
+      ...(globs.length > 0 ? { globs } : {}),
       ...(parsed.options.type === undefined ? {} : { type: parsed.options.type }),
       ...(parsed.options.i === true ? { ignoreCase: true } : {}),
       ...(parsed.options.count === true ? { count: true } : {}),
+      ...(files ? { files: true } : {}),
       ...(parsed.options.json === true ? { json: true } : {}),
       passthrough: [],
     },
@@ -238,7 +267,7 @@ function renderRgCommandResult(parsed: ParsedRg, result: RgResult): RgCommandRes
   if (parsed.options.json === true) {
     return {
       exitCode: RG_EXIT_BY_AGGREGATE[result.aggregate],
-      stdout: `${JSON.stringify(projectRgEnvelope(result, parsed.options.count === true), null, 2)}\n`,
+      stdout: `${JSON.stringify(projectRgEnvelope(result), null, 2)}\n`,
       stderr: view.diagnostics,
     };
   }
@@ -305,10 +334,11 @@ async function executeMixedRg(
         const execution = await remoteRg(binding, transport, token, {
           query: parsed.request.query,
           limit: parsed.request.limit,
-          ...(parsed.options.glob !== undefined ? { glob: parsed.options.glob } : {}),
+          ...(parsed.options.globs !== undefined ? { globs: parsed.options.globs } : {}),
           ...(parsed.options.type !== undefined ? { type: parsed.options.type } : {}),
           ...(parsed.options.ignoreCase === true ? { ignoreCase: true } : {}),
           ...(parsed.options.count === true ? { count: true } : {}),
+          ...(parsed.options.files === true ? { files: true } : {}),
           passthrough: parsed.options.passthrough,
         });
         remoteOutcomes.set(binding.name, execution.outcome);
@@ -343,6 +373,7 @@ async function executeMixedRg(
   return renderRgCommandResult(parsed, {
     query: parsed.request.query,
     limit: parsed.request.limit,
+    mode: (parsed.options.files === true ? "files" : parsed.options.count === true ? "count" : "match") as RgMode,
     endpoints,
     warnings,
     aggregate,