@catheadowl/ukp 0.2.3 → 0.2.4

package/src/cli.ts

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

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

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

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

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

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

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

package/src/commands/inventory.ts

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

package/src/commands/propose.ts

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

package/src/commands/read.ts

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