@catheadowl/ukp 0.2.3 → 0.2.5

package/src/capabilities/rg.ts

@@ -6,6 +6,7 @@ import { resolveExternalToolCapability, EXTERNAL_PROVIDER } from "../config/exte
 import { localPathOf, readRegistry } from "../registry.ts";
 import { resolveScope } from "../scope.ts";
 import { isInsideRealRoot } from "../path-safety.ts";
+import { toolRelayArgv, TOOL_NOT_FOUND_EXIT } from "../spawn-relay.ts";
 
 // rg capability (ADR-RG-001..004): an independent atomic
 // capability parallel to `search` — base lexical search over the endpoint's
@@ -15,6 +16,8 @@ import { isInsideRealRoot } from "../path-safety.ts";
 // Structured outcome per ADR 0021 — never rendered text, never exit codes.
 
 export interface RgRequest {
+  /** Search pattern (match/count modes). Empty only in files mode, where
+   * the parse layer guarantees it was omitted (ADR-RG-005 mutual exclusion). */
   query: string;
   limit: number;
 }
@@ -22,10 +25,15 @@ export interface RgRequest {
 export interface RgOptions {
   explicitEndpoints?: string[];
   global: boolean;
-  glob?: string;
+  /** Ordered glob filters (repeatable top-level flag, ADR-RG-005: rg glob
+   * grammar lets a later glob negate with `!` — include+exclude combos). */
+  globs?: readonly string[];
   type?: string;
   ignoreCase?: boolean;
   count?: boolean;
+  /** Files enumeration mode (ADR-RG-005): true tree walk via `rg --files` —
+   * no content matching, so empty and binary files are visible. */
+  files?: boolean;
   /** Validated passthrough args (allowlist + scope protection, ADR-RG-002). */
   passthrough: readonly string[];
   /** Surface concern (propose precedent): the capability never consumes it —
@@ -72,6 +80,14 @@ export interface RgCountEntry {
   count: number;
 }
 
+/** One enumerated file (files mode, ADR-RG-005): endpoint-relative path plus
+ * the durable slot key under the same containment-gated emission rule as
+ * matches (ADR 0019 stance). */
+export interface RgFileEntry {
+  path: string;
+  ukp_uri?: string;
+}
+
 export interface RgEndpointOutcome {
   name: string;
   provider: typeof EXTERNAL_PROVIDER;
@@ -91,13 +107,20 @@ export interface RgEndpointOutcome {
   matches?: RgMatch[];
   /** Count mode results (`--count`). */
   counts?: RgCountEntry[];
+  /** Files mode results (`--files`, sorted then capped). */
+  files?: RgFileEntry[];
   /** True when matches were truncated at the request limit. */
   truncated?: boolean;
 }
 
+/** The run's output mode — drives tool argv, intake, and both presentation
+ * stages (envelope count_mode/files_mode and the human render branches). */
+export type RgMode = "match" | "count" | "files";
+
 export interface RgResult {
   query: string;
   limit: number;
+  mode: RgMode;
   endpoints: RgEndpointOutcome[];
   warnings: string[];
   aggregate: RgAggregateStatus;
@@ -118,6 +141,10 @@ export class RgPlanningError extends Error {
 }
 
 export const RG_DEFAULT_LIMIT = 50;
+/** Files-mode request limit default (ADR-RG-005): enumeration units are a
+ * single path line vs the 3-4 line match unit, so the same consumer-comfort
+ * calibration that set 50 for matches lands on 500 here. */
+export const RG_FILES_DEFAULT_LIMIT = 500;
 export const RG_MAX_LIMIT = 1000;
 
 export function defaultRgCommand(): readonly string[] {
@@ -125,10 +152,23 @@ export function defaultRgCommand(): readonly string[] {
 }
 
 /** Base-tool availability probe (diagnose / provider resolver): true when a
- * ripgrep executable starts. */
+ * ripgrep executable starts. Memoized per process — PATH does not change
+ * mid-process, and server startup (the door's ServeInfo carries this field)
+ * must not pay the probe again per start; the win32 relay costs ~0.8s where
+ * the direct spawn was Defender-taxed ~5s (2026-09-22 finding, see
+ * spawn-relay.ts). The relay's not-found guard exits TOOL_NOT_FOUND_EXIT,
+ * which no real ripgrep invocation produces (rg exits 0/1/2 only). */
+let rgAvailabilityMemo: boolean | undefined;
+
 export function rgExecutableAvailable(): boolean {
-  const result = spawnSync("rg", ["--version"], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
-  return !result.error;
+  if (rgAvailabilityMemo === undefined) {
+    const probeArgv = process.platform === "win32"
+      ? toolRelayArgv(["rg", "--version"], { notFoundGuard: true })
+      : ["rg", "--version"];
+    const result = spawnSync(probeArgv[0]!, probeArgv.slice(1), { encoding: "utf8", windowsHide: true, timeout: 5_000 });
+    rgAvailabilityMemo = !result.error && result.status !== TOOL_NOT_FOUND_EXIT;
+  }
+  return rgAvailabilityMemo;
 }
 
 export function rgTimeoutMs(): number {
@@ -142,8 +182,9 @@ export function rgTimeoutMs(): number {
 // Passthrough validation (ADR-RG-002): allowlist + scope protection.
 // ---------------------------------------------------------------------------
 
-/** Value flags consume the next token (or an attached value: `-C2`). */
-const PASSTHROUGH_VALUE_FLAGS = new Set(["-A", "-B", "-C", "-m", "--max-count", "-g", "--glob", "-t", "--type", "--max-filesize"]);
+/** Value flags consume the next token (or an attached value: `-C2`). `--iglob`
+ * joined with ADR-RG-005 (case-insensitive glob variant, probe friction 2/8). */
+const PASSTHROUGH_VALUE_FLAGS = new Set(["-A", "-B", "-C", "-m", "--max-count", "-g", "--glob", "--iglob", "-t", "--type", "--max-filesize"]);
 const PASSTHROUGH_BOOL_FLAGS = new Set(["-i", "--ignore-case", "-S", "--smart-case", "-s", "--case-sensitive", "-w", "--word-regexp", "-F", "--fixed-strings", "-v", "--invert-match", "-U", "--multiline", "--no-ignore", "--hidden", "--no-messages", "--column", "--no-heading"]);
 
 /** Validates passthrough args: allowlist membership + scope protection.
@@ -155,7 +196,7 @@ export function validateRgPassthrough(args: readonly string[]): readonly string[
     const token = args[index]!;
     if (!token.startsWith("-")) {
       throw new RgUsageError(
-        `passthrough argument '${token}' is not allowed: rg targets the Service folder — no path operands (use the endpoint selector for scope)`,
+        `passthrough argument '${token}' is not allowed: rg targets the Service folder - no path operands (use the endpoint selector for scope)`,
       );
     }
     if (PASSTHROUGH_BOOL_FLAGS.has(token)) continue;
@@ -234,13 +275,15 @@ function toUkpUri(endpointName: string, path: string): string {
  * provider-location mapping. A miss silently drops the `ukp_uri` field
  * (the match and its `path` stay): rg output is tool output, not user
  * error. Output-side filtering is the second line of defense; the
- * passthrough allowlist (no path operands) is the first. */
-function ukpUriIfInside(endpointFolder: string, endpointName: string, path: string): string | undefined {
+ * passthrough allowlist (no path operands) is the first. The folder's
+ * realpath is passed in pre-resolved (per endpoint, not per entry — review
+ * 2026-09-22: per-file resolution paid 2 realpaths/file on exactly the
+ * win32 Defender-taxed path); an unresolvable folder emits nothing. */
+function ukpUriIfInside(folderReal: string | undefined, endpointFolder: string, endpointName: string, path: string): string | undefined {
+  if (folderReal === undefined) return undefined;
   const absolute = resolve(endpointFolder, ...path.replace(/\\/g, "/").split("/"));
-  let folderReal: string;
   let targetReal: string;
   try {
-    folderReal = realpathSync(endpointFolder);
     targetReal = realpathSync(absolute);
   } catch {
     return undefined;
@@ -259,6 +302,16 @@ interface RgJsonEvent {
 }
 
 function rgToolArgs(parsed: ParsedRg): string[] {
+  if (parsed.options.files) {
+    // Files mode (ADR-RG-005): true tree walk — rg lists paths without
+    // reading content, so empty and binary files are visible. No `-e`:
+    // the parse layer guarantees no pattern rides along.
+    const args: string[] = ["--files", "--no-messages"];
+    for (const glob of parsed.options.globs ?? []) args.push("--glob", glob);
+    if (parsed.options.type !== undefined) args.push("--type", parsed.options.type);
+    args.push(...parsed.options.passthrough);
+    return args;
+  }
   const args: string[] = ["--no-heading", "--no-messages"];
   if (parsed.options.count) {
     args.push("--count");
@@ -266,7 +319,7 @@ function rgToolArgs(parsed: ParsedRg): string[] {
     args.push("--json");
   }
   if (parsed.options.ignoreCase) args.push("-i");
-  if (parsed.options.glob !== undefined) args.push("--glob", parsed.options.glob);
+  for (const glob of parsed.options.globs ?? []) args.push("--glob", glob);
   if (parsed.options.type !== undefined) args.push("--type", parsed.options.type);
   args.push(...parsed.options.passthrough);
   args.push("-e", parsed.request.query);
@@ -280,6 +333,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
   validateRgPassthrough(parsed.options.passthrough);
   const { plan, warnings } = planRg(parsed, context);
   const command = context.rgCommand ?? defaultRgCommand();
+  const mode: RgMode = parsed.options.files === true ? "files" : parsed.options.count === true ? "count" : "match";
   const endpoints: RgEndpointOutcome[] = [];
   let succeeded = false;
   let failed = false;
@@ -293,13 +347,36 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       continue;
     }
 
+    // Lazy once-per-endpoint folder realpath for the uri emission rule: the
+    // folder cannot change mid-run, and a skip/fail path never pays for it.
+    // `null` marks "not attempted yet" vs `undefined` = "attempted, failed"
+    // (a failed resolution emits no uris without re-attempting per entry).
+    let endpointFolderReal: string | undefined | null = null;
+    const folderRealpath = (): string | undefined => {
+      if (endpointFolderReal === null) {
+        try {
+          endpointFolderReal = realpathSync(endpoint.folder);
+        } catch {
+          endpointFolderReal = undefined;
+        }
+      }
+      return endpointFolderReal;
+    };
+
     // Explicit search root: with no path operand rg searches stdin instead
     // of the cwd whenever stdin is not a tty (ISSUE-013 root cause,
     // confirmed on the ali repro host: spawned rg read an empty pipe and
     // exited 1 with zero traversal; tty and /dev/null stdin walk the cwd).
     // "." keeps rg's rendered paths endpoint-relative; the "./" prefix is
-    // stripped at both intakes below.
-    const result = spawnSync(command[0]!, [...command.slice(1), ...rgToolArgs(parsed), "."], {
+    // stripped at both intakes below. Win32: the real-tool invocation routes
+    // through the spawn relay (Defender taxes the direct bun-to-rg.exe edge
+    // ~5s — 2026-09-22 finding, see spawn-relay.ts); the injected test
+    // command is never wrapped, and the relay's not-found guard maps a
+    // missing rg onto the same skip path the spawn error always took.
+    const runArgv = process.platform === "win32" && context.rgCommand === undefined
+      ? toolRelayArgv([...command, ...rgToolArgs(parsed), "."], { notFoundGuard: true })
+      : [command[0]!, ...command.slice(1), ...rgToolArgs(parsed), "."];
+    const result = spawnSync(runArgv[0]!, runArgv.slice(1), {
       cwd: endpoint.folder,
       encoding: "utf8",
       windowsHide: true,
@@ -307,7 +384,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       timeout: rgTimeoutMs(),
     });
 
-    if (result.error) {
+    if (result.error || result.status === TOOL_NOT_FOUND_EXIT) {
       // ADR-RG-003/R-7: a missing base tool is a degradation, not a fault —
       // skipped + warning, the run continues with other endpoints.
       warnings.push(`endpoint '${endpoint.name}' rg unavailable: rg executable is not available`);
@@ -340,6 +417,42 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       continue;
     }
 
+    if (mode === "files") {
+      // Plain path-per-line intake. The full list is sorted BEFORE the
+      // client-side cap so truncation yields a deterministic window (the
+      // first N paths in lexicographic order, ADR-RG-005) rather than an
+      // arbitrary subset of rg's parallel-walk order.
+      const paths = (result.stdout ?? "")
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .map((line) => line.replace(/\\/g, "/").replace(/^\.\//, ""))
+        .sort();
+      const files: RgFileEntry[] = [];
+      let truncated = false;
+      for (const path of paths) {
+        if (files.length >= parsed.request.limit) {
+          truncated = true;
+          break;
+        }
+        const entry: RgFileEntry = { path };
+        const uri = ukpUriIfInside(folderRealpath(), endpoint.folder, endpoint.name, path);
+        if (uri !== undefined) entry.ukp_uri = uri;
+        files.push(entry);
+      }
+      if (files.length === 0 && !truncated) {
+        // An empty enumeration (empty folder or everything filtered out) is
+        // a successful result — same D-036 stance as a no-match search.
+        succeeded = true;
+        outcome.status = "no_matches";
+      } else {
+        succeeded = true;
+        outcome.status = "succeeded";
+        outcome.files = files;
+        if (truncated) outcome.truncated = true;
+      }
+      continue;
+    }
+
     if (parsed.options.count) {
       const counts: RgCountEntry[] = [];
       for (const line of (result.stdout ?? "").split(/\r?\n/)) {
@@ -386,7 +499,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
         const firstLine = text.split(/\r?\n/)[0] ?? "";
         if (firstLine.length > 0) entry.text = firstLine.length > 240 ? `${firstLine.slice(0, 240)}...` : firstLine;
       }
-      const uri = ukpUriIfInside(endpoint.folder, endpoint.name, entry.path);
+      const uri = ukpUriIfInside(folderRealpath(), endpoint.folder, endpoint.name, entry.path);
       if (uri !== undefined) entry.ukp_uri = uri;
       matches.push(entry);
     }
@@ -406,6 +519,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
   return {
     query: parsed.request.query,
     limit: parsed.request.limit,
+    mode,
     endpoints,
     warnings,
     aggregate: interrupted
@@ -426,35 +540,41 @@ export interface RgEnvelope {
   schema: "ukp.rg.v1";
   command: "rg";
   capability: "rg";
-  query: string;
+  /** Omitted in files mode (ADR-RG-005): there is no pattern to echo. */
+  query?: string;
   limit: number;
   count_mode: boolean;
+  files_mode: boolean;
   endpoints: Array<{
     name: string;
     provider: string;
     status: string;
     match_count?: number;
+    file_count?: number;
     truncated?: boolean;
     message?: string;
     matches?: RgMatch[];
     counts?: RgCountEntry[];
+    files?: RgFileEntry[];
   }>;
   warnings: string[];
 }
 
-export function projectRgEnvelope(result: RgResult, countMode: boolean): RgEnvelope {
+export function projectRgEnvelope(result: RgResult): RgEnvelope {
   return {
     schema: "ukp.rg.v1",
     command: "rg",
     capability: "rg",
-    query: result.query,
+    ...(result.mode === "files" ? {} : { query: result.query }),
     limit: result.limit,
-    count_mode: countMode,
+    count_mode: result.mode === "count",
+    files_mode: result.mode === "files",
     endpoints: result.endpoints.map((endpoint) => ({
       name: endpoint.name,
       provider: endpoint.provider,
       status: endpoint.status ?? "failed",
       ...(endpoint.matches !== undefined ? { match_count: endpoint.matches.length, matches: endpoint.matches } : {}),
+      ...(endpoint.files !== undefined ? { file_count: endpoint.files.length, files: endpoint.files } : {}),
       ...(endpoint.counts !== undefined ? { counts: endpoint.counts } : {}),
       ...(endpoint.truncated !== undefined ? { truncated: endpoint.truncated } : {}),
       ...(endpoint.message !== undefined ? { message: endpoint.message } : {}),
@@ -480,7 +600,14 @@ export function renderRgHuman(result: RgResult): RgHumanView {
       continue;
     }
     if (endpoint.status === "no_matches") {
-      lines.push("(no matches)");
+      lines.push(result.mode === "files" ? "(no files)" : "(no matches)");
+      continue;
+    }
+    if (endpoint.files !== undefined) {
+      // Exhibit form (probe 20260922, zero misreads): one line per file,
+      // the durable uri when containment allows it, the raw path otherwise.
+      for (const file of endpoint.files) lines.push(file.ukp_uri ?? file.path);
+      if (endpoint.truncated) lines.push(`(truncated at the result limit ${result.limit}; raise --limit)`);
       continue;
     }
     if (endpoint.counts !== undefined) {

package/src/capabilities/search.ts

@@ -872,7 +872,7 @@ function renderResultUnit(
   const base = basenameOf(providerLocation);
   const location = base ? (line ? `${base}:${line}` : base) : "";
   const identity = title
-    ? (location ? `${title} — ${location}` : title)
+    ? (location ? `${title} - ${location}` : title)
     : (location || "");
 
   const snippet = snippetOf(result);
@@ -890,7 +890,7 @@ function renderResultUnit(
     const key = line ? `${docid}:${line}` : docid;
     lines.push(`   read: ukp read --endpoint ${endpointName} ${key}`);
   } else {
-    lines.push(`   (no direct read — provider-managed result)`);
+    lines.push(`   (no direct read - provider-managed result)`);
   }
   if (ukpUri && remoteUri === undefined) lines.push(`   uri: ${ukpUri}`);
   return lines.join("\n");

package/src/cli.ts

@@ -24,7 +24,7 @@ import { executeSearchCommand, SEARCH_SPEC } from "./commands/search.ts";
 export { renderSearchHelp } from "./commands/search.ts";
 export { renderDiagnoseHelp } from "./commands/diagnose.ts";
 export { renderReadHelp } from "./commands/read.ts";
-export { renderGuideHelp, renderServiceGuide, renderServiceQmdGuide, renderClientGuide, renderRemoteGuide, renderProposeGuide } from "./commands/guide.ts";
+export { renderGuideHelp, renderServiceGuide, renderServiceQmdGuide, renderClientGuide, renderRgGuide, renderRemoteGuide, renderProposeGuide } from "./commands/guide.ts";
 export { renderInitHelp, renderInitServiceHelp } from "./commands/init.ts";
 export { renderInspectHelp } from "./commands/inspect.ts";
 export { renderUpdateHelp } from "./commands/update.ts";
@@ -186,7 +186,7 @@ export function renderHelp(): string {
   const lines = [
     "Usage: ukp <command> [options]",
     "",
-    "Start here: 'ukp guide service' (first setup — covers init and register) or 'ukp list' (see registered endpoints).",
+    "Start here: 'ukp guide service' (first setup - covers init and register) or 'ukp list' (see registered endpoints).",
     "",
     "Commands:",
     ...COMMAND_GROUPS.flatMap((group) => [
@@ -222,6 +222,51 @@ function writeCommandResult(
   return result.exitCode;
 }
 
+/** Channel philosophy for `ukp list` (ukp_list W2): stdout is the data
+ * channel — byte contract, one row per line, the terminal wraps what it
+ * must; stderr to an INTERACTIVE terminal is the human channel — progress
+ * frames already live there, and the footnote lines (degradation warnings,
+ * drift notes) may exceed any terminal width (pins are ~44 chars, urls
+ * longer), so the terminal would otherwise break them mid-word or
+ * mid-hash. This wraps them at word boundaries (over-long tokens
+ * hard-split at the width) — only when the emitter knows the width;
+ * piped/CI stderr keeps raw single lines, the machine-parseable form. */
+export function wrapLinesForTerminal(text: string, columns: number): string {
+  if (!Number.isSafeInteger(columns) || columns < 8) return text;
+  const wrapped: string[] = [];
+  for (const line of text.split("\n")) {
+    if (line.length <= columns) {
+      wrapped.push(line);
+      continue;
+    }
+    let current = "";
+    for (const token of line.split(" ")) {
+      // A token longer than the width hard-splits at the width (paths and
+      // SPKI pins have no spaces to break on); the remainder re-enters the
+      // same greedy fill so following words still pack.
+      const pieces: string[] = [];
+      let rest = token;
+      while (rest.length > columns) {
+        pieces.push(rest.slice(0, columns));
+        rest = rest.slice(columns);
+      }
+      pieces.push(rest);
+      for (const piece of pieces) {
+        if (current.length === 0) {
+          current = piece;
+        } else if (current.length + 1 + piece.length <= columns) {
+          current += ` ${piece}`;
+        } else {
+          wrapped.push(current);
+          current = piece;
+        }
+      }
+    }
+    wrapped.push(current);
+  }
+  return wrapped.join("\n");
+}
+
 function executeVersionCommand(args: readonly string[]): CliCommandResult {
   if (args.length === 0) {
     return { exitCode: 0, stdout: renderVersion(), stderr: "" };
@@ -369,10 +414,34 @@ export function runCli(
   }
 
   if (command === "list") {
-    return writeCommandResultMaybeAsync(executeListCommand(args.slice(1), {
+    // Streaming delivery (ukp_list W2 / ADR 0026 rule 3): line-by-line
+    // through the same stdout writer every other print uses (console.log
+    // per line ≡ the single print's trailing-newline form, so piped bytes
+    // match the returned-text contract); progress frames only on an
+    // interactive stderr, so piped runs stay progress-silent. The stderr
+    // footnotes wrap at the terminal width there too — piped stderr keeps
+    // the raw single lines (wrapLinesForTerminal's contract).
+    const stderrColumns = process.stderr.columns ?? process.stdout.columns;
+    const interactivelyWrap = (result: CliCommandResult): CliCommandResult =>
+      process.stderr.isTTY === true && typeof stderrColumns === "number" && result.stderr.length > 0
+        ? { ...result, stderr: wrapLinesForTerminal(result.stderr, stderrColumns) }
+        : result;
+    // Conditionality preserved (the W2 sync seam): an all-local listing
+    // stays a synchronous value wrapped synchronously; only the remote
+    // branch's promise goes through .then.
+    const result = executeListCommand(args.slice(1), {
       currentDirectory,
       registryPath,
-    }), stdout, stderr);
+      ...(process.stderr.isTTY === true
+        ? { emitProgress: (frame: string) => process.stderr.write(frame) }
+        : {}),
+      emitStdout: (line: string) => stdout(line),
+    });
+    return writeCommandResultMaybeAsync(
+      result instanceof Promise ? result.then(interactivelyWrap) : interactivelyWrap(result),
+      stdout,
+      stderr,
+    );
   }
 
   if (command === "nav") {

package/src/commands/guide-content/propose.txt

@@ -1,6 +1,6 @@
 UKP propose quickstart
 
-Goal: submit a change proposal to a Service endpoint as an idempotent, adjudicable document — not a file write.
+Goal: submit a change proposal to a Service endpoint as an idempotent, adjudicable document - not a file write.
 
 Model:
 - A proposal is a pending change the Service owner will adjudicate; the submitter proposes, the owner decides.

package/src/commands/guide-content/remote.txt

@@ -3,15 +3,17 @@ UKP Remote quickstart
 Goal: expose registered Services from one machine and consume them from another with the same endpoint commands: search, read, nav, rg, and propose when declared.
 
 Current model:
-- The ssh:// path needs nothing running on the host: each invocation wakes a loopback door over the SSH connection (it serves the host Registry fresh and self-reaps when idle). Host prerequisites: the host is ssh reachable and has ukp installed the usual way (npm i -g or bun add -g — the wake finds the standard locations).
+- The ssh:// path needs nothing running on the host: each invocation wakes a loopback door over the SSH connection (it serves the host Registry fresh and self-reaps when idle). Host prerequisites: the host is ssh reachable and has ukp installed the usual way (npm i -g or bun add -g - the wake finds the standard locations).
 - The https path (LAN, public IP, or behind a reverse proxy) uses a resident door: run ukp serve under your process manager. Arbitrary consumers have no SSH credentials, so the listener itself is the trust boundary (TLS + bearer token).
 - Prefer host door mode: run ukp serve without --endpoint to expose every local endpoint behind one port.
 - The door reads the host Registry fresh on each request, so newly registered local endpoints appear without restarting the door.
-- Declared endpoint names come from the host Service Manifest or discovery document; your registry binds each one under a local handle — the declared name by default, or --name <handle> when that name is already taken (two hosts both declaring 'notes' become your 'notes' and 'ali-notes'). --endpoint during register stays an expected-name assertion on the declared name.
+- Declared endpoint names come from the host Service Manifest or discovery document; your registry binds each one under a local handle - the declared name by default, or --name <handle> when that name is already taken (two hosts both declaring 'notes' become your 'notes' and 'ali-notes'). --endpoint during register stays an expected-name assertion on the declared name.
 
-Owner path over SSH (zero ceremony — nothing to start on the host):
+Owner path over SSH (zero ceremony - nothing to start on the host):
 1. Prerequisites (once): the host accepts your SSH key and has ukp installed the usual way
    ssh <host> ukp --help
+   Peek at the door before importing: ssh <host> ukp list shows the endpoint
+   names and capabilities the host declares
 
 2. On the consuming machine, import the door (the first call wakes it)
    ukp register --url ssh://<host>
@@ -45,7 +47,7 @@ Use this when you deliberately want to expose only one endpoint instead of the w
    ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
 
 Name and identity:
-- register --url fetches /.well-known/ukp.json and registers the declared name under a local handle (--name <handle> chooses another, e.g. when the name is taken).
+- register --url fetches /.well-known/ukp.json and registers the declared name under a local handle (--name <handle> chooses another, e.g. when the name is taken). That document is public - curl it before registering to preview the endpoint names and capabilities the door declares (self-signed doors: curl -k).
 - --endpoint <name> on register asserts the expected name; if discovery declares a different name, registration fails.
 - A host door can import everything, --select a comma-separated subset, or --endpoint exactly one endpoint.
 - Self-signed HTTPS certificates are pinned on first registration; compare the pinned fingerprint with the serve banner on untrusted networks.
@@ -54,9 +56,9 @@ Name and identity:
 - ssh:// urls take no port: registration rejects one (the woken door listens on a client-chosen loopback port; use an ssh config Host alias for a non-standard sshd port).
 
 Operational note:
-- ssh:// hosts: nothing to manage — ukp wakes and reaps doors itself (on Windows, enabling the built-in OpenSSH Server feature once is the low-burden path). SSH lockdown (login-shell restriction, why a forced authorized_keys command= does not compose) and nvm-style install layouts are deployment-handbook material.
-- https hosts: keep ukp serve under your normal process manager, for example systemd, Task Scheduler, or a terminal multiplexer. Linux can go resident-free (systemd socket activation, deployment handbook); Windows has no systemd equivalent, so a resident door wants a real service wrapper (WinSW-class) — prefer the ssh:// path there unless consumers have no SSH credentials. The CLI does not install or autostart the door; on Windows, ukp serve --print-task prints the resident-door artifacts (start script, hidden launcher, Task Scheduler command, firewall rule) for you to review and apply yourself — the token stays yours to paste, never printed.
-- The deployment handbook is where those recipes live: it ships with this package (docs/remote-deployment.md) and online (https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md) — Windows resident door (certificate, start script, Task Scheduler), systemd socket-activation units, Caddy, Tailscale, hardening notes.
+- ssh:// hosts: nothing to manage - ukp wakes and reaps doors itself (on Windows, enabling the built-in OpenSSH Server feature once is the low-burden path). SSH lockdown (login-shell restriction, why a forced authorized_keys command= does not compose) and nvm-style install layouts are deployment-handbook material.
+- https hosts: keep ukp serve under your normal process manager, for example systemd, Task Scheduler, or a terminal multiplexer. Linux can go resident-free (systemd socket activation, deployment handbook); Windows has no systemd equivalent, so a resident door wants a real service wrapper (WinSW-class) - prefer the ssh:// path there unless consumers have no SSH credentials. The CLI does not install or autostart the door; on Windows, ukp serve --print-task prints the resident-door artifacts (start script, hidden launcher, Task Scheduler command, firewall rule) for you to review and apply yourself - the token stays yours to paste, never printed.
+- The deployment handbook is where those recipes live: it ships with this package (docs/remote-deployment.md) and online (https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md) - Windows resident door (certificate, start script, Task Scheduler), systemd socket-activation units, Caddy, Tailscale, hardening notes.
 - serve accepts --max-idle <seconds> to self-exit after that long without requests (the same backstop the woken doors use).
 
 Remember:

package/src/commands/guide-content/rg.txt

@@ -0,0 +1,35 @@
+UKP rg quickstart
+
+Goal: search or enumerate a Service's own files with ripgrep - no index, no declaration, real-time.
+
+Model:
+- rg is the lexical baseline: it scans files at call time, so it works on every registered endpoint. 'ukp search' is the indexed path and needs the Service to declare a provider.
+- Output is ukp:// references that 'ukp read' consumes directly.
+- Three modes: match (default), --count (per-file totals), --files (enumeration).
+
+1. Search
+   ukp rg --endpoint <name> "pattern"
+   -i is case-insensitive; --glob narrows by name; --limit raises the cap (default 50 matches).
+
+2. Enumerate files (no pattern)
+   ukp rg --endpoint <name> --files
+   A true tree walk, not a content match: empty and binary files are listed too.
+   Narrow by name with --glob, by kind with --type. Output is sorted; the
+   cap defaults to 500 (--limit to change).
+
+3. Glob semantics
+   --glob follows ripgrep/gitignore rules: a glob without "/" matches the
+   file name at any depth ("*.md"); a glob containing "/" anchors to the
+   endpoint-relative path ("docs/*"). Matching is case-sensitive; pass
+   -- --iglob "<glob>" after '--' for a case-insensitive variant.
+   --glob repeats: a leading "!" excludes, so "*.md" plus "!docs/*" is
+   markdown outside docs/.
+
+4. Visibility (every rg mode)
+   Hidden files (dot-prefixed, including the .ukp/ wiring) are skipped by
+   default. Add -- --hidden after '--' to include them; -uu also lifts
+   .gitignore rules. 'ukp read' can address hidden files directly either way.
+
+Remember:
+- Exact flags and the passthrough allowlist live in 'ukp rg --help'.
+- Remote endpoints behave the same: one command drives local and door-registered endpoints alike.

package/src/commands/guide-content/service-qmd.txt

@@ -25,7 +25,7 @@ Fast path for a simple knowledge folder:
    By default add registers the collection under the folder's full path as
    its name; the short name comes from this rename, never from add itself.
    rename matches the exact current name only, so re-check collection list
-   before renaming — the short name you had in mind may already belong to an
+   before renaming - the short name you had in mind may already belong to an
    existing collection.
 4. Update the index (qmd update, qmd status)
 5. Verify the provider before returning to UKP (qmd search / qmd get)

package/src/commands/guide.ts

@@ -20,10 +20,11 @@ const GUIDE_CONTENT_URL = new URL("./guide-content/", import.meta.url);
  * `ukp guide --help` render the same summaries (blank-agent sweep 2026-09-11:
  * the inversion of root help describing guides better than guide's own help
  * was a confirmed doc-gap). */
-export const GUIDE_TOPICS: ReadonlyArray<readonly [topic: string, summary: string]> = [
+export const GUIDE_TOPICS: ReadonlyArray<readonly [string, string]> = [
   ["service", "first Service setup with provider-free nav/read/rg baseline"],
   ["service qmd", "provider setup for the default QMD provider"],
   ["client", "use registered Services by default from a workspace; set your default scope here"],
+  ["rg", "lexical search and file enumeration: modes, glob semantics, visibility tiers"],
   ["remote", "serve and consume remote endpoints with a host door, ssh, or TLS"],
   ["propose", "submit idempotent change proposals to a Service"],
 ];
@@ -38,7 +39,7 @@ export const GUIDE_SPEC: UkpCommandSpec = {
   description: "Show short operational guides.",
   usage: "<topic> [subtopic]",
   arguments: [
-    { name: "topic", required: true, help: "guide topic: service | service qmd | client | remote | propose" },
+    { name: "topic", required: true, help: "guide topic: service | service qmd | client | rg | remote | propose" },
     { name: "subtopic", help: "provider subtopic for a topic, e.g. 'qmd' as in 'ukp guide service qmd'" },
   ],
   strictArguments: true,
@@ -72,17 +73,19 @@ export function executeGuideCommand(args: readonly string[]): GuideCommandResult
       return { exitCode: 0, stdout: renderServiceGuide(), stderr: "" };
     }
     if (subtopic) {
-      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, remote, propose`);
+      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, rg, remote, propose`);
     }
     switch (topic) {
       case "client":
         return { exitCode: 0, stdout: renderClientGuide(), stderr: "" };
+      case "rg":
+        return { exitCode: 0, stdout: renderRgGuide(), stderr: "" };
       case "remote":
         return { exitCode: 0, stdout: renderRemoteGuide(), stderr: "" };
       case "propose":
         return { exitCode: 0, stdout: renderProposeGuide(), stderr: "" };
       default:
-        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, remote, propose`);
+        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, rg, remote, propose`);
     }
   } catch (error) {
     if (error instanceof HelpRequestError) {
@@ -115,6 +118,10 @@ export function renderClientGuide(): string {
   return readGuideContent("client.txt");
 }
 
+export function renderRgGuide(): string {
+  return readGuideContent("rg.txt");
+}
+
 export function renderRemoteGuide(): string {
   return readGuideContent("remote.txt");
 }