@catheadowl/ukp 0.2.5 → 0.3.0

package/src/commands/inventory.ts

@@ -1,16 +1,26 @@
-import { ENDPOINT_NAME, loadManifest } from "../config/manifest.ts";
+import { join } from "node:path";
+import { ENDPOINT_NAME, loadManifest, ServiceFolderInaccessibleError } from "../config/manifest.ts";
 import { FILE_NATIVE_CAPABILITIES, isFileNativeCapability } from "../config/file-native.ts";
+import { EXTERNAL_TOOL_CAPABILITIES } from "../config/external-tool.ts";
 import { diagnoseService, type ProviderResolver } from "./diagnose.ts";
+import {
+  assertUkpResidents,
+  ensureVersionVisibleUkpIgnore,
+  renderUkpIgnorePostureLine,
+  ukpIgnoreStarWarning,
+} from "./init.ts";
 import {
   assertRegistrableRemoteUrl,
   isRemoteBinding,
   parseRemoteUrl,
   readRegistry,
+  rebindAt,
   registerAt,
   registerRemoteAt,
   unregisterAt,
   type RegistryBinding,
 } from "../registry.ts";
+import { resolveScope, type ResolvedScope } from "../scope.ts";
 import {
   createTransportPool,
   fetchDiscoveryDocument,
@@ -73,6 +83,7 @@ export const REGISTER_SPEC: UkpCommandSpec = {
   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: "--rebind", help: "local only: relocate this endpoint name to the current Service folder in one step (the folder moved); the name must already be bound to a local folder - registering a name bound elsewhere without this flag is rejected with the recovery path" },
     { 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: "--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" },
@@ -82,12 +93,19 @@ export const REGISTER_SPEC: UkpCommandSpec = {
     "",
     "Recovery:",
     "  Registering a name already bound to a different location is rejected.",
-    "  Unregister the old binding first, then register from the new Service folder:",
+    "  If the Service folder moved, re-run register from the new folder with",
+    "  --rebind to relocate the name in one step (local bindings only):",
+    "  ukp register --rebind",
+    "  Without the flag the two-step path stays available:",
     "  ukp unregister --endpoint <name>",
     "",
     "Binding:",
     "  The Host Registry binds the Service Manifest's effective name to this",
-    "  folder's location; 'ukp list' shows the resulting bindings.",
+    "  folder's location; 'ukp list' shows the resulting bindings. A local",
+    "  register (plain or --rebind) also brings .ukp/.gitignore to the",
+    "  precise-ignore posture: created when absent, a legacy '*' template",
+    "  migrated so the declarations can be committed, an operator-owned",
+    "  file left untouched.",
     "  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",
@@ -111,11 +129,15 @@ export const REGISTER_SPEC: UkpCommandSpec = {
 
 export const LIST_SPEC: UkpCommandSpec = {
   name: "list",
-  summary: "list registered endpoint bindings",
+  summary: "list endpoint bindings - workspace scope by default, every registration with -g",
   group: "registry",
-  description: "List registered endpoint bindings and capabilities.",
-  usage: "[options]",
+  description: "List endpoint bindings and capabilities: the workspace scope by default (nearest .ukp/client.toml; every registered endpoint when there is none), or the full Host Registry with -g.",
+  usage: "[-g] [--json]",
   strictArguments: true,
+  options: [
+    { flags: "-g, --global", help: "list every registered endpoint (the full Host Registry), ignoring the workspace scope and without reading .ukp/client.toml" },
+    { flags: "--json", help: "emit the offline machine-readable endpoint snapshot (schema ukp.list.v1; registry facts only - remote bindings are not probed, their capability fields are null); rides the same scope as the text listing" },
+  ],
 };
 
 export const UNREGISTER_SPEC: UkpCommandSpec = {
@@ -142,6 +164,59 @@ const DEFAULT_CAPABILITIES = (Object.keys(FILE_NATIVE_CAPABILITIES) as Array<key
   .filter((name) => FILE_NATIVE_CAPABILITIES[name].derived)
   .sort();
 
+/** Base-tier membership for the machine snapshot (ukp.list.v1): the
+ * declaration-free baseline every healthy local endpoint carries — the
+ * derived file-native set (nav, read; ADR 0016 rule 2, the header's own
+ * statement) plus the external-tool base tier (rg; ADR-RG-003). Membership
+ * only: rg's runtime availability still degrades by tool presence (tier
+ * semantics unchanged — `base_tier` is not a liveness claim). */
+const BASE_TIER_CAPABILITIES = [
+  ...DEFAULT_CAPABILITIES,
+  ...(Object.keys(EXTERNAL_TOOL_CAPABILITIES) as Array<keyof typeof EXTERNAL_TOOL_CAPABILITIES>)
+    .filter((name) => EXTERNAL_TOOL_CAPABILITIES[name].baseTier),
+].sort();
+
+/** One endpoint as offline machine facts — the `ukp.list.v1` row (TODO
+ * 20261028-0053). The machine contract is a registry-snapshot projection:
+ * local rows read the Service Manifest (a local file read, never the
+ * network); remote rows carry registry facts only, because the registry
+ * pins no capability or liveness claims for remote bindings and the
+ * contract never probes — the text face's fresh discovery fetch is a
+ * per-invocation human affordance, not snapshot truth. Nullability is the
+ * contract's one rule: `null` = "not asserted in this snapshot". */
+export interface ListEndpointSnapshot {
+  /** Registry handle — the ukp:// authority and the `--endpoint` key. */
+  name: string;
+  /** Local/remote discriminator (registry `kind`; absence = local). */
+  kind: "local" | "remote";
+  /** Binding location: the local canonical absolute path, or the
+   * registered remote url verbatim. Exactly one of path/url is non-null. */
+  location: { path: string | null; url: string | null };
+  /** Remote-declared name snapshot (ADR-REM-007 provenance); null for
+   * local bindings and legacy remote bindings that predate the field. */
+  declared_name: string | null;
+  /** Sorted declared capability extras (the text capabilities cell as an
+   * array); null on degraded local rows and on every remote row. */
+  capabilities: string[] | null;
+  /** Declaration-free baseline members in effect (nav/read/rg today);
+   * null on degraded local rows and on every remote row. */
+  base_tier: string[] | null;
+  /** Local rows: the Service Manifest loaded (true) or the row degraded
+   * (false). Remote rows: null — remote liveness is not an offline fact. */
+  available: boolean | null;
+  /** The same one-line degradation headline the text face emits on
+   * stderr; null when the row is not degraded. */
+  warning: string | null;
+}
+
+/** Envelope of the `--json` snapshot — the repo machine-face convention
+ * (versioned schema id + pretty-printed single document, as nav/rg). */
+export interface ListSnapshotEnvelope {
+  schema: "ukp.list.v1";
+  command: "list";
+  endpoints: ListEndpointSnapshot[];
+}
+
 /** 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
@@ -158,7 +233,23 @@ interface InventoryListRow {
   warning?: string;
 }
 
-function renderLocalListRow(endpoint: { name: string; path: string }): InventoryListRow {
+/** Offline facts for one local binding — the single producer BOTH faces
+ * consume (the same-truth seam of the machine contract: the text row and
+ * the ukp.list.v1 row are projections of this, never parallel assemblies).
+ * Manifest load failures degrade exactly like the text face: no capability
+ * assertions plus the same one-line warning. */
+interface LocalListFacts {
+  name: string;
+  path: string;
+  /** Sorted declared extras; null on a degraded row. */
+  capabilities: string[] | null;
+  /** Baseline members; null on a degraded row. */
+  baseTier: string[] | null;
+  available: boolean;
+  warning: string | null;
+}
+
+function localListFacts(endpoint: { name: string; path: string }): LocalListFacts {
   let service;
   try {
     service = loadManifest(endpoint.path);
@@ -166,17 +257,100 @@ function renderLocalListRow(endpoint: { name: string; path: string }): Inventory
     // One-line headline only: an inventory warning must stay scannable even
     // when the underlying ManifestError carries a full zod schema dump.
     const headline = (error instanceof Error ? error.message : String(error)).split("\n")[0];
+    // A dead binding (folder unreachable) is a binding-level failure, not a
+    // capability degradation: the binding itself routes nowhere. It gets its
+    // own frame plus the one-step rebind remedy (dead-binding item 1; the
+    // `declared capabilities` qualifier stays reserved for manifest-level
+    // failures where the folder IS reachable — probe-anchored wording).
+    if (error instanceof ServiceFolderInaccessibleError) {
+      return {
+        name: endpoint.name,
+        path: endpoint.path,
+        capabilities: null,
+        baseTier: null,
+        available: false,
+        warning: `endpoint '${endpoint.name}' binding is dead: ${headline}; `
+          + `if the folder moved, run 'ukp register --rebind' from the new folder `
+          + `(or 'ukp unregister --endpoint ${endpoint.name}')`,
+      };
+    }
     return {
       name: endpoint.name,
-      location: endpoint.path,
-      capabilities: "(unavailable)",
+      path: endpoint.path,
+      capabilities: null,
+      baseTier: null,
+      available: false,
       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 { name: endpoint.name, location: endpoint.path, capabilities: extras.length > 0 ? extras.join(",") : "-" };
+  return { name: endpoint.name, path: endpoint.path, capabilities: extras, baseTier: [...BASE_TIER_CAPABILITIES], available: true, warning: null };
+}
+
+function renderLocalListRow(endpoint: { name: string; path: string }): InventoryListRow {
+  const facts = localListFacts(endpoint);
+  return {
+    name: facts.name,
+    location: facts.path,
+    capabilities: facts.available
+      ? (facts.capabilities!.length > 0 ? facts.capabilities!.join(",") : "-")
+      : "(unavailable)",
+    ...(facts.warning !== null ? { warning: facts.warning } : {}),
+  };
+}
+
+/** ukp.list.v1 projection of one local binding — the same localListFacts
+ * the text row renders from, shaped as snapshot fields. */
+function localSnapshotRow(endpoint: { name: string; path: string }): ListEndpointSnapshot {
+  const facts = localListFacts(endpoint);
+  return {
+    name: facts.name,
+    kind: "local",
+    location: { path: facts.path, url: null },
+    declared_name: null,
+    capabilities: facts.capabilities,
+    base_tier: facts.baseTier,
+    available: facts.available,
+    warning: facts.warning,
+  };
+}
+
+/** ukp.list.v1 row for one remote binding: pure registry projection, no
+ * transport. The handle stays the bare `name` — the text face's
+ * `name (declares X)` cell is a rendering; here the declaration rides in
+ * `declared_name` as structure. Capability and liveness fields are null
+ * per the offline contract (the registry pins none for remotes). */
+function remoteSnapshotRow(endpoint: RegistryBinding): ListEndpointSnapshot {
+  return {
+    name: endpoint.name,
+    kind: "remote",
+    location: { path: null, url: endpoint.url! },
+    declared_name: endpoint.declared_name ?? null,
+    capabilities: null,
+    base_tier: null,
+    available: null,
+    warning: null,
+  };
+}
+
+/** `--json` emission (TODO 20261028-0053 machine contract): one
+ * pretty-printed document in the repo machine-face convention, rows in the
+ * text face's order (locals first, then remotes, each in registry order).
+ * Offline and synchronous by construction — no transport pool is ever
+ * created for this path, so a registry full of remote bindings costs zero
+ * network. stderr stays empty in this mode: degradation truth rides in the
+ * rows' `warning` fields. */
+function renderListJsonSnapshot(endpoints: readonly RegistryBinding[]): InventoryCommandResult {
+  const rows = [
+    ...endpoints
+      .filter((endpoint) => !isRemoteBinding(endpoint))
+      .map((endpoint) => localSnapshotRow({ name: endpoint.name, path: endpoint.path! })),
+    ...endpoints.filter(isRemoteBinding).map(remoteSnapshotRow),
+  ];
+  const envelope: ListSnapshotEnvelope = { schema: "ukp.list.v1", command: "list", endpoints: rows };
+  return { exitCode: 0, stdout: `${JSON.stringify(envelope, null, 2)}\n`, stderr: "" };
 }
 
 export function executeRegisterCommand(
@@ -188,7 +362,7 @@ export function executeRegisterCommand(
   }
 
   try {
-    const parsed = parseKitArgs<{ url?: string; token?: string; select?: string; endpoint?: string; name?: string }>(REGISTER_SPEC, args);
+    const parsed = parseKitArgs<{ url?: string; token?: string; select?: string; endpoint?: string; name?: string; rebind?: boolean }>(REGISTER_SPEC, args);
     const expectedName = parsed.options.endpoint;
     if (expectedName !== undefined && !ENDPOINT_NAME.test(expectedName)) {
       throw new KitUsageError("--endpoint requires a valid endpoint name");
@@ -202,6 +376,11 @@ export function executeRegisterCommand(
       // folder owner controls; the registry naming slot is remote-only.
       throw new KitUsageError("--name chooses a remote registration handle and requires --url");
     }
+    if (parsed.options.rebind === true && parsed.options.url !== undefined) {
+      // --rebind is the narrow local relocation exit; remote handles keep
+      // the unregister path (registry-commands rebind-one-step, 2026-10-24).
+      throw new KitUsageError("--rebind relocates a local binding and cannot be combined with --url");
+    }
     if (parsed.options.url !== undefined) {
       return executeRegisterRemote(parsed.options.url, parsed.options.token, parsed.options.select, expectedName, handleName, context);
     }
@@ -212,11 +391,45 @@ export function executeRegisterCommand(
     if (expectedName !== undefined && expectedName !== report.service.effectiveName) {
       throw new Error(`expected endpoint '${expectedName}', but this Service effective name is '${report.service.effectiveName}'`);
     }
+    // INV-21 admission gate BEFORE the binding write: a foreign resident in
+    // .ukp/ refuses the whole gesture — registry untouched, guard not
+    // rewritten over material it no longer covers (the 2026-11-02 KB shape:
+    // a '*' guard swapped onto the current template above a legacy tls/).
+    const ukpDirectory = join(report.service.folder, ".ukp");
+    assertUkpResidents(ukpDirectory, { endpointName: report.service.effectiveName });
+    if (parsed.options.rebind === true) {
+      // Diagnosis already validated the new Service folder — a failed rebind
+      // (unknown name, remote handle, taken location) leaves the old binding
+      // untouched; the swap itself is one atomic registry transition.
+      const previous = readRegistry(context.registryPath).find(
+        (endpoint) => endpoint.name === report.service.effectiveName,
+      );
+      rebindAt(context.registryPath, report.service.effectiveName, report.service.folder);
+      // The service-side version-control step rides the same binding
+      // gestures (use is the client-face carrier; a pure Service folder —
+      // the fresh-clone revival path this command IS — has no reason to
+      // run use, and re-running init is refused once the manifest exists).
+      const posture = ensureVersionVisibleUkpIgnore(ukpDirectory);
+      const lines = [
+        `rebound: ${report.service.effectiveName}`,
+        `from: ${previous?.path ?? "(unknown)"}`,
+        ...(report.service.manifest.description ? [`description: ${report.service.manifest.description}`] : []),
+        `location: ${report.service.folder}`,
+        renderUkpIgnorePostureLine(posture, ukpDirectory),
+      ];
+      return {
+        exitCode: 0,
+        stdout: lines.join("\n"),
+        stderr: posture === "operator-owned-star" ? ukpIgnoreStarWarning(ukpDirectory) : "",
+      };
+    }
     registerAt(context.registryPath, report.service.effectiveName, report.service.folder);
+    const posture = ensureVersionVisibleUkpIgnore(ukpDirectory);
     const lines = [
       `registered: ${report.service.effectiveName}`,
       ...(report.service.manifest.description ? [`description: ${report.service.manifest.description}`] : []),
       `location: ${report.service.folder}`,
+      renderUkpIgnorePostureLine(posture, ukpDirectory),
       // Register never edits Client Config (guide client owns that); this is
       // a pointer for the cross-workspace consumption case, which is the
       // standard follow-up after registering a Service others will reference.
@@ -225,7 +438,7 @@ export function executeRegisterCommand(
     return {
       exitCode: 0,
       stdout: lines.join("\n"),
-      stderr: "",
+      stderr: posture === "operator-owned-star" ? ukpIgnoreStarWarning(ukpDirectory) : "",
     };
   } catch (error) {
     if (error instanceof HelpRequestError) {
@@ -541,14 +754,58 @@ export function executeListCommand(
   }
 
   try {
-    parseKitArgs(LIST_SPEC, args);
-    const endpoints = readRegistry(context.registryPath);
+    const parsed = parseKitArgs<{ json?: boolean; global?: boolean }>(LIST_SPEC, args);
+    // Scope semantics (owner ruling 2026-10-28 / ADR 0031, restoring the
+    // 13ae382 clause): list eats the workspace scope like every consumer
+    // command — the nearest client.toml's default_endpoints by default,
+    // full-registry fallback when there is none (bare machines unchanged) —
+    // and -g lists the full Host Registry without reading the config. No
+    // machine-face exemption: --json rides the same resolution (the
+    // exemption pattern is exactly what let the 09-21 contract ratify the
+    // implementation drift); ukp.list.v1's fields are unchanged, only the
+    // row set is selected.
+    const registry = readRegistry(context.registryPath);
+    let endpoints: readonly RegistryBinding[];
+    let scopeWarnings: string[] = [];
+    if (parsed.options.global === true) {
+      endpoints = registry;
+    } else {
+      let scope: ResolvedScope;
+      try {
+        scope = resolveScope({ currentDirectory: context.currentDirectory, registry });
+      } catch (error) {
+        // Same law as the scope family, no list exemption: an invalid
+        // client.toml or one that resolves to nothing fails the listing —
+        // with the -g escape taught in place (it never reads the config).
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `ukp list: ${message}; use 'ukp list -g' to list every registered endpoint\n`,
+        };
+      }
+      endpoints = scope.bindings;
+      scopeWarnings = scope.warnings;
+    }
+    if (parsed.options.json === true) {
+      // Machine contract (ukp.list.v1 / TODO 20261028-0053): the offline
+      // snapshot of the SELECTED endpoints. Returns before any transport
+      // pool exists — see renderListJsonSnapshot; the sync return with
+      // remote bindings present is the structural pin of the no-network
+      // promise. Scope-level dangling warnings ride stderr (same strings
+      // as the text face); row-level degradation truth stays in rows.
+      const snapshot = renderListJsonSnapshot(endpoints);
+      return {
+        ...snapshot,
+        stderr: scopeWarnings.length > 0 ? `${scopeWarnings.join("\n")}\n` : "",
+      };
+    }
     if (endpoints.length === 0) {
       return { exitCode: 0, stdout: "No endpoints registered.", stderr: "" };
     }
     const remotes = endpoints.filter(isRemoteBinding);
     if (remotes.length === 0) {
-      return renderListOutput(endpoints.map((endpoint) => renderLocalListRow({ name: endpoint.name, path: endpoint.path! })));
+      return renderListOutput(endpoints.map((endpoint) => renderLocalListRow({ name: endpoint.name, path: endpoint.path! })), scopeWarnings);
     }
     // Remote rows fetch the discovery document (fresh per invocation); the
     // same conditional-async seam as search/read keeps all-local listings
@@ -640,7 +897,9 @@ export function executeListCommand(
         // 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)];
+        // Scope dangling warnings lead (they qualify the selection itself),
+        // then row degradation, then the same-instance/drift notes.
+        const stderrLines = [...scopeWarnings, ...warnings, ...collectSameInstanceNotes(endpoints), ...(await drift)];
         return {
           exitCode: 0,
           stdout: context.emitStdout === undefined ? lines.join("\n") : "",
@@ -663,9 +922,10 @@ export function executeListCommand(
 
 function renderListOutput(
   rows: ReadonlyArray<InventoryListRow>,
+  leadingNotes: readonly string[] = [],
   extraNotes: readonly string[] = [],
 ): InventoryCommandResult {
-  const warnings = [...rows.flatMap((row) => (row.warning !== undefined ? [row.warning] : [])), ...extraNotes];
+  const warnings = [...leadingNotes, ...rows.flatMap((row) => (row.warning !== undefined ? [row.warning] : [])), ...extraNotes];
   const stdout = [listHeaderLine(), ...rows.map((row) => renderListLine(row, listRowGeometry(rows)))].join("\n");
   return {
     exitCode: 0,

package/src/commands/nav.ts

@@ -58,7 +58,7 @@ export const NAV_SPEC: UkpCommandSpec = {
   options: [
     {
       flags: "--depth <n>",
-      help: "how many directory levels to expand from the route root (0-10, default 0; deeper folders appear as [truncated: N], where N is that folder's total recursive .md count)",
+      help: "how many directory levels to expand from the route root (0-10, default 0; deeper folders appear as folder/ (+N .md), where N is that folder's total recursive .md count)",
     },
     { flags: "--json", help: "emit the structured response envelope" },
   ],
@@ -110,10 +110,10 @@ export function parseNavArgs(args: readonly string[]): NavRequest {
   };
 }
 
-export function executeNavCommand(
+export async function executeNavCommand(
   args: readonly string[],
   context: NavContext,
-): NavCommandResult | Promise<NavCommandResult> {
+): Promise<NavCommandResult> {
   if (isHelpRequest(args)) {
     return { exitCode: 0, stdout: renderNavHelp(), stderr: "" };
   }
@@ -132,15 +132,15 @@ export function executeNavCommand(
   }
 
   // Remote branch (ukp_remote W6): a remote binding routes through the
-  // remote transport; the sync local contract is unchanged
-  // (conditional-async seam, same as search/read).
+  // remote transport; local and remote now share one async contract (the
+  // scan-engine delegation made the local branch async, 2026-10-22).
   const binding = readRegistry(context.registryPath).find((entry) => entry.name === request.endpoint);
   if (binding !== undefined && isRemoteBinding(binding)) {
     return executeRemoteNav(request, binding, context);
   }
 
   try {
-    const outcome = runNav(request, context);
+    const outcome = await runNav(request, context);
     if (!outcome.ok) {
       // Single render source for failures too: the factual message is
       // capability data; only the prefix, exit code, and hint wording are
@@ -153,18 +153,23 @@ export function executeNavCommand(
     }
 
     const envelope = projectNavEnvelope(outcome.result);
-    // Diagnostics go to stderr in BOTH render modes (read's channel
-    // discipline: stdout is the payload, stderr is the operational
-    // channel). Without this, a Human-mode budget hit would be silent —
-    // violating ADR 0018's loud contract. JSON keeps the diagnostics in
-    // the envelope too.
+    // Consumer diagnostics go to stderr in BOTH render modes (read's channel
+    // discipline: stdout is the payload, stderr is the operational channel);
+    // JSON keeps them in the envelope too. Maintainer findings (E1,
+    // 2026-10-22) are human-face stderr only — the JSON face stays silent.
     const diagnosticLines = envelope.diagnostics
       .map((diagnostic) => `ukp nav: ${diagnostic.code}: ${diagnostic.message}`)
       .join("\n");
+    const maintainerLines = request.json
+      ? ""
+      : outcome.result.maintainerDiagnostics
+        .map((diagnostic) => `ukp nav: ${diagnostic.code}: ${diagnostic.message}`)
+        .join("\n");
+    const operational = [diagnosticLines, maintainerLines].filter((block) => block.length > 0).join("\n");
     return {
       exitCode: 0,
       stdout: request.json ? renderNavJson(envelope) : renderNavHuman(envelope),
-      stderr: diagnosticLines.length > 0 ? `${diagnosticLines}\n` : "",
+      stderr: operational.length > 0 ? `${operational}\n` : "",
     };
   } catch (error) {
     if (error instanceof NavUsageError) {

package/src/commands/read.ts

@@ -66,7 +66,7 @@ const READ_EXIT_BY_ERROR_CLASS: Record<ReadErrorClass, number> = {
  * dispatch and its precedence stay command-side. */
 export const READ_SPEC: UkpCommandSpec = {
   name: "read",
-  summary: "read an endpoint-scoped resource (exact path, ukp:// URI, or a docid from search results)",
+  summary: "read an endpoint-scoped resource (exact path, ukp:// URI, a docid from search results, or document-relative via --from)",
   group: "endpoint",
   description:
     "Read an endpoint-scoped resource reference from one Service endpoint (endpoint names come from 'ukp list'). "

package/src/commands/rg.ts

@@ -91,8 +91,8 @@ export const RG_SPEC: UkpCommandSpec = {
     "",
     "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",
+    "  wiring) by default; pass -- --hidden after '--' to include them, and",
+    "  -- --no-ignore to also lift .gitignore rules. --files lists every",
     "  non-hidden file, including empty and binary ones.",
     "",
   ].join("\n"),

package/src/commands/search.ts

@@ -51,14 +51,15 @@ export const SEARCH_SPEC: UkpCommandSpec = {
   name: "search",
   summary: "search a Service's indexed content (provider-backed; use 'ukp rg' to grep raw files)",
   group: "endpoint",
-  description: "Run atomic lexical search against the selected Service endpoints.",
-  usage: "<query> [--limit <1-1000>] [--endpoint <name> ... | -g] [--recursive] [--json]",
+  description: "Run a lexical (text) search across the selected Service endpoints through each endpoint's configured provider.",
+  usage: "<query> [--limit <1-1000>] [--endpoint <name> ... | -g] [--recursive] [--timeout <seconds>] [--json]",
   arguments: [{ name: "query", help: "one non-empty search query; quote multi-word queries" }],
   options: [
     { flags: "--limit <1-1000>", help: "maximum results requested from each endpoint (default: 20)" },
     { 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: "--recursive", help: "include direct authority and context dependencies" },
+    { flags: "--timeout <seconds>", help: "provider spawn timeout for this search in whole seconds; 0 disables the guard (wait indefinitely - interrupt is then the only cancel); default 60 (UKP_PROVIDER_TIMEOUT_MS applies when the flag is absent)" },
     { flags: "--json", help: "write provider-native results to artifacts and print an envelope" },
   ],
   helpSuffix: [
@@ -86,6 +87,7 @@ interface SearchCommandOptions extends Record<string, unknown> {
   endpoint?: string[];
   g?: boolean;
   recursive?: boolean;
+  timeout?: string;
   json?: boolean;
 }
 
@@ -106,6 +108,20 @@ export function parseSearchArgs(args: readonly string[]): ParsedSearch {
     }
   }
 
+  // Owner ruling 2026-10-28 (TODO 20261028-1113 option 3): whole seconds,
+  // 0 = disable the guard (the classic-interactive "zero disables"
+  // grammar), positive wins over the env override.
+  let timeoutSeconds: number | undefined;
+  if (parsed.options.timeout !== undefined) {
+    if (!/^[0-9]+$/.test(parsed.options.timeout)) {
+      throw new KitUsageError("--timeout must be a non-negative integer number of seconds (0 disables the guard)");
+    }
+    timeoutSeconds = Number(parsed.options.timeout);
+    if (!Number.isSafeInteger(timeoutSeconds)) {
+      throw new KitUsageError("--timeout is out of range");
+    }
+  }
+
   for (const endpoint of parsed.options.endpoint ?? []) {
     if (explicit.includes(endpoint)) warnings.push(`duplicate endpoint '${endpoint}' ignored`);
     else explicit.push(endpoint);
@@ -123,7 +139,7 @@ export function parseSearchArgs(args: readonly string[]): ParsedSearch {
     throw new KitUsageError("--endpoint and -g cannot be used together");
   }
   return {
-    request: { query, limit },
+    request: { query, limit, ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}) },
     options: {
       explicitEndpoints: explicit.length > 0 ? explicit : undefined,
       global: parsed.options.g ?? false,