@catheadowl/ukp 0.1.0 → 0.2.0

package/src/capabilities/tls-identity.ts

@@ -1,7 +1,9 @@
-import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { hostname, networkInterfaces } from "node:os";
 import { X509Certificate, createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { acquireLock, releaseLock } from "../fslock.ts";
 
 /** TLS transport identity (ukp_remote W5' / D-079): the self-signed + TOFU
  * pinning path for serving over bare IPs without a public CA. Shared by the
@@ -28,60 +30,200 @@ export function certSanOf(cert: string | Buffer): string {
 export function selfSignedSanEntries(): string[] {
   const entries = new Set<string>(["IP:127.0.0.1", "IP:::1", "DNS:localhost"]);
   const host = hostname();
-  if (/^[A-Za-z0-9.-]+$/.test(host) && !host.includes("_")) entries.add(`DNS:${host}`);
+  if (/^[A-Za-z0-9.-]+$/.test(host) && !host.includes("_")) entries.add(`DNS:${host.toLowerCase()}`);
   for (const addresses of Object.values(networkInterfaces())) {
     for (const address of addresses ?? []) {
-      if (!address.internal) entries.add(`IP:${address.address}`);
+      if (!address.internal) entries.add(`IP:${address.address.toLowerCase()}`);
     }
   }
   return [...entries];
 }
 
+const DNS_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+
+/** One `--tls-san <ip|dns>` value → its canonical openssl SAN form
+ * (`IP:<addr>` / `DNS:<name>`, lowercased — SAN IP/DNS matching is
+ * case-insensitive, so the whole SAN pipeline compares on folded keys),
+ * classifying by shape: a bare IP becomes an IP SAN, anything else must be a
+ * legal DNS name. The classification is what lets a cloud NAT/EIP host add
+ * its public address — it is on no NIC, so the automatic coverage above can
+ * never see it. Throws on values that are neither. */
+export function normalizeTlsSanEntry(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) throw new Error("--tls-san entry must not be empty");
+  if (isIP(trimmed) !== 0) return `IP:${trimmed.toLowerCase()}`;
+  if (DNS_NAME.test(trimmed) && trimmed.length <= 253) return `DNS:${trimmed.toLowerCase()}`;
+  throw new Error(`--tls-san entry '${value}' is neither an IP address nor a DNS name`);
+}
+
+/** Fully expanded lowercase IPv6 form (group-wise parseInt also strips
+ * leading zeros); `fd00::1` and `fd00:0:0:0:0:0:0:1` are the same SAN, and
+ * openssl re-renders a compressed literal expanded on some platforms, so
+ * spellings must not leak into comparisons. Input is isIP-validated. */
+function expandIpv6(address: string): string {
+  const groupsOf = (part: string): string[] => {
+    if (part.length === 0) return [];
+    const groups: string[] = [];
+    for (const piece of part.split(":")) {
+      if (piece.includes(".")) {
+        // embedded IPv4 tail (::ffff:1.2.3.4) = two 16-bit groups
+        const [a = 0, b = 0, c = 0, d = 0] = piece.split(".").map(Number);
+        groups.push(((a << 8) | b).toString(16), ((c << 8) | d).toString(16));
+      } else {
+        groups.push(parseInt(piece, 16).toString(16));
+      }
+    }
+    return groups;
+  };
+  const halves = address.split("::");
+  if (halves.length === 1) return groupsOf(halves[0] ?? "").join(":");
+  if (halves.length !== 2) return address.toLowerCase();
+  const head = groupsOf(halves[0] ?? "");
+  const tail = groupsOf(halves[1] ?? "");
+  return [...head, ...Array.from({ length: 8 - head.length - tail.length }, () => "0"), ...tail].join(":");
+}
+
+/** Canonical comparison key for one `IP:x`/`DNS:y` SAN entry: uppercase
+ * type prefix, lowercase value, IPv6 expanded — the same shape openssl's
+ * addext wants, because re-signs emit inherited entries (canonical keys)
+ * back into the extension. Coverage decisions and deduplication compare
+ * keys, never spellings. */
+function sanKey(entry: string): string {
+  const separator = entry.indexOf(":");
+  if (separator < 1) return entry.toUpperCase();
+  const type = entry.slice(0, separator).toUpperCase();
+  const value = entry.slice(separator + 1);
+  if (type === "IP") return `IP:${isIP(value) === 6 ? expandIpv6(value) : value.toLowerCase()}`;
+  return `${type}:${value.toLowerCase()}`;
+}
+
+/** The SAN entries a certificate actually carries, as canonical keys
+ * (`IP:x` with IPv6 expanded / `DNS:y`, case-folded — X509Certificate
+ * renders "IP Address:x", and openssl may spell an IPv6 literal differently
+ * than the requester did). */
+export function certSanEntriesOf(cert: string | Buffer): Set<string> {
+  const raw = new X509Certificate(cert).subjectAltName ?? "";
+  const entries = new Set<string>();
+  for (const part of raw.split(",")) {
+    const entry = part.trim();
+    if (entry.startsWith("IP Address:")) entries.add(sanKey(`IP:${entry.slice("IP Address:".length)}`));
+    else if (entry.startsWith("DNS:")) entries.add(sanKey(entry));
+  }
+  return entries;
+}
+
 export interface SelfSignedIdentity {
   certPath: string;
   keyPath: string;
-  /** true when this call generated the pair; false when reusing the persisted one. */
-  created: boolean;
+  /** What this call did to the identity: `generated` = fresh keypair (first
+   * `--tls`), `re-signed` = new certificate over the existing key (coverage
+   * grew — `--tls-san` added an entry the persisted certificate lacked; the
+   * pin is unchanged and pinned clients re-anchor transparently), `persisted`
+   * = both files reused untouched. */
+  source: "generated" | "re-signed" | "persisted";
 }
 
 /** 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
  * identity is the keypair, so losing the key loses the identity (clients
- * re-register). `opensslCommand` is a test injection point. */
+ * re-register). `extraSanEntries` (the `--tls-san` flag, already normalized
+ * `IP:x`/`DNS:y`) merges into the SAN coverage; when a persisted certificate
+ * lacks requested entries it is re-signed over the SAME key — the SPKI pin
+ * survives, which is exactly the renewal semantics pinned clients already
+ * handle. Coverage only ever grows: the re-sign unions everything the
+ * certificate already carried with automatic coverage and the new entries,
+ * and dropping a flag entry never re-signs. The read-decide-write section
+ * holds the write-discipline sibling lock (`.lock` in the tls dir) so two
+ * concurrent serve starts cannot interleave openssl writes.
+ * `opensslCommand` is a test injection point. */
 export function ensureSelfSignedTlsFiles(
   tlsDir: string,
-  options: { opensslCommand?: readonly string[] } = {},
+  options: { opensslCommand?: readonly string[]; extraSanEntries?: readonly string[] } = {},
 ): SelfSignedIdentity {
   const certPath = join(tlsDir, "cert.pem");
   const keyPath = join(tlsDir, "key.pem");
-  if (existsSync(certPath) && existsSync(keyPath)) {
-    return { certPath, keyPath, created: false };
-  }
+  const extra = options.extraSanEntries ?? [];
   mkdirSync(tlsDir, { recursive: true, mode: 0o700 });
-  const proc = Bun.spawnSync(
-    [
-      ...(options.opensslCommand ?? ["openssl"]),
-      "req", "-x509", "-newkey", "rsa:2048",
-      "-keyout", keyPath,
-      "-out", certPath,
-      "-days", "3650",
-      "-nodes",
-      "-subj", "/CN=ukp serve self-signed",
-      "-addext", `subjectAltName=${selfSignedSanEntries().join(",")}`,
-    ],
-    { stdout: "ignore", stderr: "pipe" },
-  );
-  if (proc.exitCode !== 0 || !existsSync(certPath) || !existsSync(keyPath)) {
+  const lockPath = join(tlsDir, ".lock");
+  const descriptor = acquireLock(lockPath);
+  try {
+    if (existsSync(certPath) && existsSync(keyPath)) {
+      let carried: string[];
+      try {
+        carried = [...certSanEntriesOf(readFileSync(certPath, "utf8"))];
+      } catch (error) {
+        throw new Error(
+          `the persisted self-signed certificate is unreadable (${certPath}): ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const requestedButMissing = extra.filter((entry) => !carried.includes(sanKey(entry)));
+      if (requestedButMissing.length === 0) return { certPath, keyPath, source: "persisted" };
+      const san = mergedSanEntries(extra, carried);
+      runOpenssl(
+        [
+          ...(options.opensslCommand ?? ["openssl"]),
+          "req", "-x509",
+          "-key", keyPath,
+          "-out", certPath,
+          "-days", "3650",
+          "-subj", "/CN=ukp serve self-signed",
+          "-addext", `subjectAltName=${san.join(",")}`,
+        ],
+        [certPath],
+      );
+      return { certPath, keyPath, source: "re-signed" };
+    }
+    const san = mergedSanEntries(extra);
+    runOpenssl(
+      [
+        ...(options.opensslCommand ?? ["openssl"]),
+        "req", "-x509", "-newkey", "rsa:2048",
+        "-keyout", keyPath,
+        "-out", certPath,
+        "-days", "3650",
+        "-nodes",
+        "-subj", "/CN=ukp serve self-signed",
+        "-addext", `subjectAltName=${san.join(",")}`,
+      ],
+      [certPath, keyPath],
+    );
+    try {
+      chmodSync(keyPath, 0o600);
+    } catch {
+      // best-effort on platforms without POSIX modes
+    }
+    return { certPath, keyPath, source: "generated" };
+  } finally {
+    releaseLock(lockPath, descriptor);
+  }
+}
+
+/** The SAN list handed to openssl's subjectAltName extension: automatic
+ * coverage, then the requested extras, then (on re-sign) entries the
+ * persisted certificate already carried — deduplicated by canonical key so
+ * one spelling of each entry survives. */
+function mergedSanEntries(extra: readonly string[], carried: readonly string[] = []): string[] {
+  const seen = new Set<string>();
+  const entries: string[] = [];
+  for (const entry of [...selfSignedSanEntries(), ...extra, ...carried]) {
+    const key = sanKey(entry);
+    if (!seen.has(key)) {
+      seen.add(key);
+      entries.push(entry);
+    }
+  }
+  return entries;
+}
+
+/** Run one openssl signing command; every declared output must appear. */
+function runOpenssl(args: readonly string[], outputs: readonly string[]): void {
+  const proc = Bun.spawnSync([...args], { stdout: "ignore", stderr: "pipe" });
+  const failed = proc.exitCode !== 0 || outputs.some((path) => !existsSync(path));
+  if (failed) {
     const stderr = new TextDecoder().decode(proc.stderr).trim();
     throw new Error(
       `unable to generate a self-signed TLS identity with openssl (exit ${proc.exitCode}): ${stderr || "is openssl installed and on PATH? 'ukp serve --tls' self-signs through the local openssl"}`,
     );
   }
-  try {
-    chmodSync(keyPath, 0o600);
-  } catch {
-    // best-effort on platforms without POSIX modes
-  }
-  return { certPath, keyPath, created: true };
 }

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, renderProposeGuide } from "./commands/guide.ts";
+export { renderGuideHelp, renderServiceGuide, renderServiceQmdGuide, renderClientGuide, 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";

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

@@ -29,8 +29,20 @@ Model:
 4. Dangling defaults warn instead of failing silently
    A default_endpoints entry not registered yet is reported as a warning by inspect, and commands still run on the resolvable ones.
 
+5. Pin your own ukp:// references (optional; powers rename recovery)
+   A pin is a same-line HTML comment carrying the target's content hash:
+   see ukp://endpoint-a/docs/foo.md   <!-- ukp-pin: sha256-<64 lowercase hex> -->
+   Emit one with 'ukp read --show-pin <same reference>'; the pin covers the
+   whole file (line endings normalized, so a pin verifies on any platform).
+   When 'ukp read' recovers a moved target, the pin is verified against the
+   recovered file; a mismatch refuses. Boundary: without git history only
+   same-name moves are recoverable (search re-anchor); a true rename in a
+   non-git folder stays resource-missing.
+
 Remember:
 - Client path consumes Services; provider path (ukp guide service) creates them.
 - Client Config lists names, not paths or provider details.
 - Explicit selectors always beat Client Config defaults.
 - Register does not edit Client Config, and Client Config does not register endpoints.
+- Search run artifacts live outside your folders: %LOCALAPPDATA%\ukp\artifacts
+  on Windows, ~/.cache/ukp/artifacts (or $XDG_CACHE_HOME) elsewhere.

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

@@ -0,0 +1,64 @@
+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 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.
+
+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
+
+2. On the consuming machine, import the door (the first call wakes it)
+   ukp register --url ssh://<host>
+
+3. Use the imported endpoints by name; later calls reuse the warmed connection
+   ukp list
+   ukp read --endpoint <name> notes/x.md
+   ukp rg "keyword" --endpoint <name>
+
+LAN HTTPS path:
+1. On the host machine, run a tokened TLS door (keep it under your process manager)
+   UKP_SERVE_TOKEN=<token> ukp serve --host 0.0.0.0 --tls
+   NAT/EIP cloud host (public IP on no NIC)? Name the public IP explicitly:
+   UKP_SERVE_TOKEN=<token> ukp serve --host 0.0.0.0 --tls --tls-san <public-ip>
+   Linux hosts can go resident-free too: systemd socket activation holds the
+   port and spawns the door per use (ukp serve --systemd-socket, recipe in
+   the deployment handbook)
+
+2. On the consuming machine, import either the whole door or one endpoint
+   ukp register --url https://<ip>:8570 --token <token>
+   ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
+
+3. Use the imported endpoint normally
+   ukp nav --endpoint <name>
+   ukp read --endpoint <name> notes/x.md
+   ukp rg "keyword" --endpoint <name>
+
+Single endpoint mode:
+Use this when you deliberately want to expose only one endpoint instead of the whole host Registry.
+   UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --tls
+   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).
+- --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.
+- --tls names the host's interface IPs only. A NAT/EIP host's public IP needs --tls-san <public-ip>; without it registration fails on certificate name mismatch. Adding it later re-signs the persisted cert over the same key, so existing pins survive.
+- Non-loopback plain http is refused. Use https, ssh://, or loopback http for local testing.
+- 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; 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. The CLI does not install or autostart the door.
+- serve accepts --max-idle <seconds> to self-exit after that long without requests (the same backstop the woken doors use).
+
+Remember:
+- Local registration makes a folder addressable on the host.
+- Remote registration imports host-discovered endpoint bindings into the consumer Registry.
+- Client Config still stores endpoint names only; after remote import, guide client works the same way as local endpoints.

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

@@ -18,14 +18,19 @@ Fast path for a simple knowledge folder:
 1. Initialize QMD (qmd init)
 2. Add the searchable collections (qmd collection add)
    For a pure knowledge base, add the folder root; otherwise add the folder(s)
-   whose content should be searchable.
+   whose content should be searchable. Check what already exists first
+   (qmd collection list): re-adding an already-indexed folder creates a
+   duplicate collection, and add does not warn about it.
 3. Use a stable short collection name (qmd collection rename)
-   QMD names a collection from the indexed folder; rename it to a short
-   stable name so provider-native artifact URIs stay clean.
+   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
+   existing collection.
 4. Update the index (qmd update, qmd status)
 5. Verify the provider before returning to UKP (qmd search / qmd get)
    If a search returns matches, the provider is ready; return to
-   'ukp guide service' step 4.
+   'ukp guide service' step 7.
    A read smoke ('qmd get <reference> --no-line-numbers') is required for
    observe mode (external or nested collection root): it confirms the provider
    can resolve the provider references that ukp read will delegate to it

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

@@ -1,6 +1,6 @@
 UKP Service quickstart
 
-Goal: make a folder a named Knowledge Service, register it, inspect the route, search it, and read an endpoint-scoped reference.
+Goal: make a folder a named Knowledge Service, register it, inspect the route, and use the provider-free read/nav/rg baseline. Add QMD only when you want indexed search/update.
 Run the setup commands from the Service folder root.
 
 Fast path:
@@ -8,32 +8,34 @@ Fast path:
    ukp init service --name your-endpoint-name
    Optional: add --description "Short boundary note"
 
-2. Make content searchable through the provider
-   ukp guide service qmd
-
-3. Validate and register the Service
+2. Validate and register the Service
    ukp diagnose
    ukp register
    ukp list
 
-4. Inspect, search, then read
+3. Inspect, navigate, grep, then read
    ukp inspect --endpoint your-endpoint-name
+   ukp nav --endpoint your-endpoint-name --depth 2
+   ukp rg "keyword" --endpoint your-endpoint-name --limit 3
+   ukp read --endpoint your-endpoint-name docs/example.md
+
+4. Optional: add indexed search through the provider
+   ukp guide service qmd
    ukp search "keyword" --endpoint your-endpoint-name --limit 3
-   ukp read --endpoint your-endpoint-name <reference>
 
 Key boundary:
 - init/register makes the folder addressable as a Service.
-- provider setup makes the Service's content searchable.
-- Both are needed for an end-to-end search path.
+- read and nav are derived defaults of every local Service; rg is provider-free when the rg binary is installed.
+- QMD provider setup makes indexed search/update available. It is not required for the baseline Service path.
 
 Model:
 - A UKP Service is a knowledge endpoint that declares capabilities.
 - Four separate journeys:
-  - provider path: init service + register make a folder an addressable Service;
-  - content-searchable: provider setup decides what content is indexed (provider-owned; see 'ukp guide service qmd');
+  - provider-free Service path: init service + diagnose + register make a folder addressable, then nav/read/rg use endpoint files directly;
+  - indexed-search path: provider setup decides what content is indexed (provider-owned; see 'ukp guide service qmd');
   - declared dependencies: a Service Manifest can declare [[dependencies]] entries with endpoint + kind; this is declarative only;
   - client path: a workspace .ukp/client.toml default scope lets you use Services by default instead of naming one each call.
-- Registered as a Service does not mean its content is searchable; both steps are needed.
+- Registered as a Service does not mean indexed search is configured; use rg for the baseline lexical path or add provider setup for ukp search.
 - QMD is the current default search/update provider, not the definition of a Service.
 - Provider setup is provider-owned: the provider owns collection, index, ranking, and config.
 
@@ -46,49 +48,53 @@ Details:
    ukp init service --name your-endpoint-name
    Optional: add --description "Short boundary note"
    Name must be a lowercase endpoint slug, for example: cad-notes
-   This writes .ukp/service.toml with the current minimal provider declaration:
-   [capabilities.search]
-   provider = "qmd"
-
-3. Make content searchable through the provider (provider-owned)
-   Provider setup is not a UKP step. For the default QMD provider:
-   ukp guide service qmd
-   That topic points exact flags and arguments to the relevant QMD subcommand help.
+   This writes .ukp/service.toml with the provider-free baseline:
+   [capabilities]
 
+3. Optional: declare dependencies
    If this Service depends on other externally consumed knowledge endpoints,
    declare them in the Manifest with repeated --dependency <name> entries;
-   each entry becomes [[dependencies]] with kind = "context" and can be edited later.
+   each entry becomes [[dependencies]] with kind = "context" and can be
+   edited later (authority, implementation, evidence, or a reason).
 
 4. Validate and register
    ukp diagnose
    ukp register
    ukp list
    At this point the folder is a registered Service: addressable and callable.
-   Its content is searchable only because step 3 configured the provider.
+   Its file-native baseline is available through read/nav, and rg works when rg is installed.
 
 5. Inspect the effective route
    ukp inspect --endpoint your-endpoint-name
    Use inspect when you need to explain scope, Registry binding, Manifest capability, or provider availability.
 
-6. Search
+6. Explore without a provider
+   ukp nav --endpoint your-endpoint-name --depth 2
+   ukp rg "keyword" --endpoint your-endpoint-name --limit 3
+   rg results carry ukp:// references that can be read directly.
+
+7. Add indexed search when you need provider-backed search/update
+   Provider setup is not a UKP baseline step. For the default QMD provider:
+   ukp guide service qmd
+   That topic points exact flags and arguments to the relevant QMD subcommand help.
    ukp search "keyword" --endpoint your-endpoint-name --limit 3
    ukp search "keyword" --endpoint your-endpoint-name --limit 3 --json
    ukp search "keyword" --endpoint your-endpoint-name --recursive
    In a workspace with .ukp/client.toml default_endpoints, you can omit --endpoint for search.
 
-7. Read an endpoint-scoped reference
+8. Read an endpoint-scoped reference
    Every registered local Service has the derived read/file baseline; no Manifest get entry is needed.
    ukp read --endpoint your-endpoint-name docs/example.md
    ukp read --endpoint your-endpoint-name docs/example.md --lines 10:20
-   Search results carry copyable handoff lines you can paste straight into read:
+   rg and search results carry copyable handoff lines you can paste straight into read:
    - a ukp://<endpoint>/<path> URI is the durable, endpoint-scoped reference;
    - a bare docid is the provider's short-lived document id (QMD handoff key).
    On a QMD-backed Service (including observe mode), provider content is read with
    'ukp read --endpoint <name> <docid handoff key or qmd:// reference>'; do not
    manually convert qmd:// provider locations into Service-folder paths.
 
-8. Update provider-owned state
-   This is optional for the first search path. Add this capability to .ukp/service.toml when provider maintenance should be exposed:
+9. Update provider-owned state
+   This is optional and only applies after a provider-backed maintenance capability is declared. Add this capability to .ukp/service.toml when provider maintenance should be exposed:
    [capabilities.update]
    provider = "qmd"
    ukp update --endpoint your-endpoint-name
@@ -96,19 +102,14 @@ Details:
    Use ukp update -g only when you explicitly want to update every registered endpoint.
 
 Advanced:
-- Declared dependencies belong in the Service Manifest as [[dependencies]] entries.
-- ukp init service --dependency <name> emits a context dependency; edit the Manifest later for authority, implementation, evidence, or a reason.
 - Dependencies do not change ordinary search/read. Only explicit search --recursive traverses direct authority/context dependencies.
 - Workspace defaults belong to the client path; run 'ukp guide client' from the consuming workspace.
-- update is a provider-owned maintenance route, not part of the first search smoke.
 
 Remember:
 - Endpoint name identifies the Service.
 - Host Registry stores endpoint name -> Service folder path.
 - Provider collection decides what content is indexed; folder-external authoritative knowledge should be modeled as its own endpoint when UKP ownership matters.
-- Register makes the folder addressable; it does not make content searchable (provider indexing does).
 - Register does not edit .ukp/client.toml or provider configuration.
-- Declarative dependencies live in the Service Manifest as [[dependencies]] entries; they do not change ordinary search/read, while explicit search --recursive traverses direct authority/context dependencies.
 - Future providers should add provider adapters instead of turning provider internals into UKP rules.
 - To register an already-used name at a new location, unregister the old binding first:
   ukp unregister --endpoint <name>

package/src/commands/guide.ts

@@ -21,9 +21,10 @@ const GUIDE_CONTENT_URL = new URL("./guide-content/", import.meta.url);
  * 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]> = [
-  ["service", "first Service setup, inspect, search, read, and update path"],
+  ["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"],
+  ["remote", "serve and consume remote endpoints with a host door, ssh, or TLS"],
   ["propose", "submit idempotent change proposals to a Service"],
 ];
 
@@ -37,7 +38,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 | propose" },
+    { name: "topic", required: true, help: "guide topic: service | service qmd | client | remote | propose" },
     { name: "subtopic", help: "provider subtopic for a topic, e.g. 'qmd' as in 'ukp guide service qmd'" },
   ],
   strictArguments: true,
@@ -71,15 +72,17 @@ 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, propose`);
+      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, remote, propose`);
     }
     switch (topic) {
       case "client":
         return { exitCode: 0, stdout: renderClientGuide(), 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, propose`);
+        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, remote, propose`);
     }
   } catch (error) {
     if (error instanceof HelpRequestError) {
@@ -112,6 +115,10 @@ export function renderClientGuide(): string {
   return readGuideContent("client.txt");
 }
 
+export function renderRemoteGuide(): string {
+  return readGuideContent("remote.txt");
+}
+
 export function renderProposeGuide(): string {
   return readGuideContent("propose.txt");
 }

package/src/commands/init.ts

@@ -54,17 +54,17 @@ export const INIT_SERVICE_SPEC: UkpCommandSpec = {
   ],
   strictArguments: true,
   helpSuffix: [
-    "Creates .ukp/service.toml with the current minimal search provider:",
-    "  [capabilities.search]",
-    "  provider = \"qmd\"",
+    "Creates .ukp/service.toml with the provider-free Service baseline:",
+    "  [capabilities]",
     "Optional:",
+    "  ukp guide service qmd   add QMD-backed indexed search/update setup",
     "  --dependency <name>   declare another endpoint as a contextual dependency entry",
     "  each --dependency emits [[dependencies]] with endpoint + kind = \"context\"",
     "",
     "Next:",
-    "  ukp guide service qmd",
     "  ukp diagnose",
     "  ukp register",
+    "  ukp nav / ukp read / ukp rg",
     "",
   ].join("\n"),
 };
@@ -134,11 +134,7 @@ function renderServiceManifest(options: { name?: string; description?: string; d
     ...(options.name === undefined ? {} : { name: options.name }),
     ...(options.description === undefined ? {} : { description: options.description }),
     ...(options.dependencies === undefined ? {} : { dependencies: options.dependencies }),
-    capabilities: {
-      search: {
-        provider: "qmd",
-      },
-    },
+    capabilities: {},
   });
   return encoded.endsWith("\n") ? encoded : `${encoded}\n`;
 }
@@ -191,11 +187,19 @@ function executeInitServiceCommand(args: readonly string[], context: InitCommand
         `name_source: ${result.nameSource}`,
         `manifest: ${result.manifestPath}`,
         `location: ${result.folder}`,
-        "capability: search",
-        "provider: qmd",
-        "next: ukp guide service qmd",
+        "declared_capabilities: -",
+        "derived_capabilities: read, nav",
+        "provider_free: rg (if rg is installed)",
+        // Folder-existence probe only (no provider state read): an existing
+        // provider index means collections may already be registered — route
+        // to the provider-scoped topic instead of naming provider commands
+        // (provider-agnostic stdout, same pattern as diagnose's hint).
+        ...(existsSync(join(result.folder, ".qmd"))
+          ? ["note: existing provider index detected (.qmd/); align collection naming before adding new ones (see 'ukp guide service qmd')"]
+          : []),
         "next: ukp diagnose",
         "next: ukp register",
+        "optional: ukp guide service qmd",
       ].join("\n"),
       stderr: "",
     };