@catheadowl/ukp 0.2.4 → 0.2.6

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.
@@ -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/tls-identity.ts

@@ -124,8 +124,9 @@ export interface SelfSignedIdentity {
 }
 
 /** Idempotent self-signed identity for `ukp serve --tls`: persisted under
- * `<serviceFolder>/.ukp/tls/` (machine-local, gitignored — the instance-uid
- * posture). openssl signs it because node:crypto cannot issue X.509; the
+ * `<serviceFolder>/.ukp/tls/` (machine-local; `init service` self-ignores
+ * `.ukp/` via its `.gitignore` — the instance-uid posture). openssl signs
+ * it because node:crypto cannot issue X.509; the
  * identity is the keypair, so losing the key loses the identity (clients
  * re-register). `extraSanEntries` (the `--tls-san` flag, already normalized
  * `IP:x`/`DNS:y`) merges into the SAN coverage; when a persisted certificate

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";
@@ -95,6 +95,10 @@ export interface CliContext {
   artifactRoot?: string;
   artifactRunId?: string;
   now?: Date;
+  /** Overrides the door system snapshot behind `diagnose --door` for tests. */
+  doorProbe?: () => import("./capabilities/door-health.ts").DoorSystemSnapshot;
+  /** Overrides door-file reads behind `diagnose --door` for tests. */
+  readTextFile?: (path: string) => string;
 }
 
 interface CliCommandResult {
@@ -353,6 +357,8 @@ export function runCli(
       currentDirectory,
       registryPath,
       resolveProvider: context.resolveProvider,
+      doorProbe: context.doorProbe,
+      readTextFile: context.readTextFile,
     }), stdout, stderr);
   }
 

package/src/commands/diagnose.ts

@@ -8,6 +8,15 @@ import { HelpRequestError, isHelpRequest } from "./flags.ts";
 import { defaultQmdCommand } from "../capabilities/qmd.ts";
 import { resolveProposeFolder } from "../capabilities/propose.ts";
 import { rgExecutableAvailable } from "../capabilities/rg.ts";
+import {
+  defaultDoorSystemProbe,
+  defaultReadDoorFile,
+  evaluateDoorSnapshot,
+  renderDoorHealthReport,
+  type DoorSystemProbe,
+  type DoorSystemSnapshot,
+} from "../capabilities/door-health.ts";
+import { homedir } from "node:os";
 
 export interface ProviderCheck {
   supported: boolean;
@@ -31,6 +40,15 @@ export interface DiagnoseCommandContext {
   currentDirectory: string;
   registryPath: string;
   resolveProvider?: ProviderResolver;
+  /** Overrides the PowerShell door snapshot for tests (--door mode). */
+  doorProbe?: DoorSystemProbe;
+  /** Overrides file reads of the operator-authored door files for tests. */
+  readTextFile?: (path: string) => string;
+  /** Overrides the %USERPROFILE% expansion root for tests (--door mode). */
+  homeDir?: string;
+  /** Overrides the door-mode platform admission for tests (--door mode);
+   * process.platform in production. */
+  platform?: string;
 }
 
 export interface DiagnoseCommandResult {
@@ -52,8 +70,11 @@ export const DIAGNOSE_SPEC: UkpCommandSpec = {
   name: "diagnose",
   summary: "check a Service or endpoints for wiring problems (manifest, provider setup)",
   group: "operations",
-  description: "Validate a Service folder or selected registered Service endpoints.",
-  usage: "[--endpoint <name> ... | -g]",
+  description: "Validate a Service folder or selected registered Service endpoints, or this host's resident doors (--door).",
+  usage: "[--door] [--endpoint <name> ... | -g]",
+  options: [
+    { flags: "--door", help: "check this host's resident doors (Windows scheduled tasks running the print-task hidden launcher): task state, process tree, port holder, door.log tail - read-only" },
+  ],
   scope: {
     endpointHelp: "validate one registered endpoint; repeat to validate multiple endpoints",
     globalHelp: "validate every endpoint in the Host Registry; takes no value",
@@ -65,6 +86,16 @@ export const DIAGNOSE_SPEC: UkpCommandSpec = {
     "  Service (Manifest and provider wiring). -g validates every registered",
     "  endpoint; -g cannot be combined with --endpoint.",
     "",
+    "Doors:",
+    "  --door skips Service validation and checks this host's resident doors",
+    "  (Windows): every scheduled task running the print-task hidden launcher",
+    "  is reported with its task state, the wscript->cmd->bun process tree,",
+    "  its port (and who holds it), and the door.log tail. Read-only -",
+    "  repairs live in 'ukp serve --print-task' section 5 and the deployment",
+    "  handbook. A door that is down is a finding (exit 1); a host with no",
+    "  doors is healthy. Not combinable with --endpoint or -g; on Linux the",
+    "  door is a systemd socket-activation unit (see the handbook).",
+    "",
   ].join("\n"),
 };
 
@@ -208,18 +239,55 @@ export function renderDependencyRegistryWarnings(
 }
 
 function parseDiagnoseArgs(args: readonly string[]): {
+  door: boolean;
   explicitEndpoints?: string[];
   global: boolean;
   warnings: string[];
 } {
   const parsed = parseKitArgs(DIAGNOSE_SPEC, args);
   return {
+    door: (parsed.options as { door?: boolean }).door === true,
     explicitEndpoints: parsed.scope.explicitEndpoints,
     global: parsed.scope.global,
     warnings: parsed.scope.warnings,
   };
 }
 
+/** Door-mode platform admission (mirrors printTaskPreflightError: pure,
+ * `process.platform` in production). Linux doors are systemd units with
+ * their own check surface; running the Windows probe there is meaningless. */
+export function doorModePlatformError(platform: string): string | undefined {
+  if (platform !== "win32") {
+    return "--door is Windows-only; on Linux the door is a systemd socket-activation unit - check it with systemctl --user status ukp-door.socket (the deployment handbook carries the recipes)";
+  }
+  return undefined;
+}
+
+function executeDoorDiagnose(context: DiagnoseCommandContext): DiagnoseCommandResult {
+  const probe = context.doorProbe ?? defaultDoorSystemProbe;
+  const readTextFile = context.readTextFile ?? defaultReadDoorFile;
+  let snapshot: DoorSystemSnapshot;
+  try {
+    snapshot = probe();
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `ukp diagnose: door snapshot failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    };
+  }
+  const doors = evaluateDoorSnapshot(snapshot, {
+    homeDir: context.homeDir ?? homedir(),
+    readTextFile,
+  });
+  const unhealthy = doors.some((door) => door.status !== "ok");
+  return {
+    exitCode: unhealthy ? 1 : 0,
+    stdout: renderDoorHealthReport(doors),
+    stderr: "",
+  };
+}
+
 function diagnoseBinding(
   binding: RegistryBinding,
   resolveProvider: ProviderResolver | undefined,
@@ -254,6 +322,16 @@ export function executeDiagnoseCommand(
 
   try {
     const parsed = parseDiagnoseArgs(args);
+    if (parsed.door) {
+      if (parsed.explicitEndpoints !== undefined || parsed.global) {
+        throw new KitUsageError("--door checks this host's resident doors and cannot be combined with --endpoint or -g");
+      }
+      const gate = doorModePlatformError(context.platform ?? process.platform);
+      if (gate !== undefined) {
+        throw new Error(gate);
+      }
+      return executeDoorDiagnose(context);
+    }
     if (!parsed.explicitEndpoints && !parsed.global) {
       try {
         const report = diagnoseService(context.currentDirectory, context.resolveProvider);

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

@@ -5,13 +5,15 @@ Goal: expose registered Services from one machine and consume them from another
 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 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.
+- Prefer host door mode when the whole Registry is safe to declare: run ukp serve without --endpoint to expose every local endpoint behind one port. A Registry that mixes in endpoints you do not want to expose uses --select instead: ukp serve --select a,b,c keeps one port and one door for exactly the named endpoints - everything unselected is not served, routed, or declared (probing its name behaves exactly like probing one that never existed). Reserve per-endpoint --endpoint <name> doors for exposing a single endpoint to different consumers.
 - 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.
 
 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.

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.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");
 }