@catheadowl/ukp 0.2.2 → 0.2.4

package/README.md

@@ -1,13 +1,13 @@
-# UKP
+# UKP — Unified Knowledge Plane
 
 Folder as a Service: turn folders into named knowledge endpoints — one
 stable command surface, on this machine or your own server.
 
 Register a folder and it becomes an endpoint for humans and agents alike —
 nothing is started, the folder stays a folder. Navigate, read, and search
-it; propose changes back to the owner as reviewable suggestions; update
-provider-owned indexes (local today). No physical paths to memorize, no
-provider-specific commands to relearn.
+it; propose changes back to the owner as reviewable suggestions; refresh
+the search index behind it (local folders today). No physical paths to
+memorize, no provider-specific commands to relearn.
 
 > [!NOTE]
 > Early-stage CLI (MVP) — commands and behavior may still change.
@@ -27,7 +27,8 @@ $ ukp read ukp://notes/2026/q3-plan.md      # read straight from the reference
 # Q3 Plan
 Goals for Q3: ship the knowledge plane.
 
-$ ukp propose --endpoint notes --id typo-fix --file typo-fix.md   # the write face: declare propose first
+$ echo '[capabilities.propose]' >> .ukp/service.toml   # the write face is opt-in: declare propose
+$ ukp propose --endpoint notes --id typo-fix --file typo-fix.md
 proposal typo-fix created (revision 1)
 ```
 
@@ -53,38 +54,41 @@ predictable scope, and a single command surface. Use UKP when:
   command will touch before running it.
 - Navigate the Markdown structure of an endpoint — folders, descriptions,
   depth — with zero provider dependency.
-- Read endpoint-scoped references through `read/file` — if a file moves,
-  reference recovery re-finds it (git history first, then search). The
+- Read endpoint files through the built-in `read/file` capability — if a
+  file moves, reference recovery re-finds it best-effort (git history
+  first, then search). The
   optional `read/qmd` goes through QMD (an external tool — see
   Requirements). `read` and `nav` are derived defaults of every local
   Service.
-- Run base lexical search with `rg` across endpoint files — provider-free
-  and on by default, shaped into `read`-ready references.
-- Search one endpoint, a workspace default scope, the whole local Registry,
-  or endpoints you have explicitly declared as its dependencies
-  (authority/context links), with explicit recursion (QMD-backed).
+- Run base lexical search with `rg` across endpoint files — no search
+  provider needed, on by default, shaped into `read`-ready references.
+- Search indexed content, QMD-backed: one endpoint, the workspace default
+  scope, or the whole local Registry. `--recursive` additionally searches
+  the endpoints a Service declares in its manifest `dependencies` —
+  nothing recurs unless declared.
 - Propose changes as an idempotent, reviewable suggestion — the proposal
   lands in the endpoint's inbox and the verdict stays with its owner.
 - Update provider-owned indexes through a stable UKP command (QMD-backed).
-- Serve an endpoint over HTTP — a single endpoint, or the whole registry as
+- Serve an endpoint over HTTP — a single endpoint, or every local binding as
   a host door — when you want it reachable from other machines.
 - Want a read-only endpoint? Declare zero capabilities — an empty
   `[capabilities]` table still registers one (derived `read`/`nav` only).
 - Give agents JSON output (`--json`; `ukp read` uses `--format json`),
-  reference sidecars, and
-  `ukp://` handoff keys when they need machine-readable results.
+  reference sidecars, docid handoff keys, and durable `ukp://` references
+  when they need machine-readable results.
 
-UKP owns endpoint names, Registry bindings, Client scope, capability
-selection, routing, and output shape; the provider owns collection setup,
-indexes, ranking, and maintenance. UKP points to the delegated setup path —
-it does not rewrite provider config for you.
+UKP owns endpoint names, Registry bindings, scope, and output shape; the
+provider owns collection setup, indexes, ranking, and maintenance. UKP
+points you at the provider's own setup — it does not rewrite provider
+config for you.
 
 ## Install
 
 Requirements:
 
-- Bun `1.3.14` or newer — npm installs the `ukp` command, but the CLI runs
-  on Bun.
+- Bun `1.3.14` or newer, installed by you — the npm package installs the
+  `ukp` command, but the CLI runs on Bun; when `bun` is missing the command
+  says how to install it instead of showing a stack trace.
 - QMD on `PATH` only for the QMD-backed capabilities (`search/qmd`,
   `read/qmd`, `update/qmd`). QMD is an external tool maintained as a
   separate project; see its own release channel for installation. UKP
@@ -114,8 +118,8 @@ For a human or agent starting from a folder:
 7. `ukp search "<query>" --endpoint <name>` finds indexed matches after
    provider setup.
 
-No QMD installed? Stop at step 6 — `nav`, `read`, `rg`, and `propose` work on
-any endpoint without it.
+No QMD installed? Stop at step 6 — `nav`, `read`, and `rg` work on any
+endpoint without it; `propose` works wherever it's declared.
 
 An agent can carry out the same flow on your behalf.
 
@@ -125,20 +129,21 @@ For workspace defaults, use `ukp guide client` and `.ukp/client.toml`.
 
 Grouping below follows `ukp --help`; every command stays a flat
 `ukp <verb>`. `--endpoint <name>` is the canonical endpoint selector
-(`-c` is a compatibility alias); `-g` selects the full local Host Registry
-where supported.
+(`ukp unregister <name>` still takes the endpoint as a positional legacy
+form); `-g` selects the full local Host Registry where supported.
 
-The same five commands work on local and remote endpoints — consuming a
-remote endpoint is a one-command gesture (see below).
+The same five commands — search, read, nav, rg, propose — work on local and
+remote endpoints; consuming a remote endpoint is a one-command gesture
+(see below).
 
 Endpoint commands:
 
 | Command | What it does |
 |---|---|
-| `ukp search` | Indexed search through the endpoint's provider (QMD today); `--recursive` expands endpoints explicitly declared as dependencies (authority/context). Results hand off via `ukp://` references. |
-| `ukp read` | Reads an endpoint-scoped resource — exact path, `ukp://` URI, or `docid` handoff key. |
+| `ukp search` | Indexed search through the endpoint's provider (QMD today); `--recursive` expands the manifest's declared `dependencies`. Results hand off via docid session keys and verified `ukp://` references. |
+| `ukp read` | Reads an endpoint-scoped resource — exact path, `ukp://` URI, or a `docid` handed off by search results. |
 | `ukp nav` | Markdown outline of an endpoint (`--depth`, respects `.gitignore`); on by default, configurable via `[capabilities.nav]`. |
-| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning (a single-endpoint run exits non-zero). |
+| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
 | `ukp propose` | Submits an idempotent change proposal (suggestion box — the owner decides what happens next). Created/unchanged/updated; the revision bumps only on `updated`. |
 
 Registry commands:
@@ -146,8 +151,8 @@ Registry commands:
 | Command | What it does |
 |---|---|
 | `ukp init service` | Creates a minimal `.ukp/service.toml`. |
-| `ukp register` / `ukp unregister --endpoint <name>` | Manages Host Registry bindings. `ukp register --url <url>` registers a remote endpoint 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 <name>` stays an expected-name assertion on the declared name, and `--token <token>` stores the bearer credential in the binding. Identity is pinned TOFU-style (trust on first use), and self-signed certificates are pinned automatically. A **host door** url imports every endpoint behind it — the `--endpoint` assertion narrows the import to exactly that one endpoint, `--select` narrows to a subset, and re-running refreshes idempotently. |
-| `ukp list` | Lists registered endpoints with their declared capabilities. Door drift shows as a stderr note (`door <origin>: N unimported endpoint(s) …`) — importing stays an explicit gesture. |
+| `ukp register` / `ukp unregister --endpoint <name>` | Manages Host Registry bindings — local folders and remote endpoints alike (`ukp register --url`, see Remote in 60 seconds). `--name <handle>` disambiguates collisions: `notes` vs `ali-notes`. |
+| `ukp list` | Lists registered endpoints with their declared capabilities. New endpoints on a host door show as a stderr note (`door <origin>: N unimported endpoint(s) …`) — importing stays an explicit gesture. |
 
 Operations commands:
 
@@ -156,7 +161,7 @@ Operations commands:
 | `ukp diagnose` | Checks a Service folder or endpoint scope for wiring problems. |
 | `ukp inspect` | Explains current scope, bindings, manifest capabilities, and provider availability. |
 | `ukp update` | Runs provider-owned maintenance when `update/qmd` is declared (local endpoints today). |
-| `ukp serve` | Serves one endpoint — or, without `--endpoint`, the whole registry as a **host door** — over HTTP: a discovery document plus the five command routes (the write face requires the endpoint to declare propose). Loopback by default; `UKP_SERVE_TOKEN` enables bearer auth; `--tls` for HTTPS. |
+| `ukp serve` | Serves one endpoint — or, without `--endpoint`, every local binding as a **host door** — over HTTP (a discovery document plus the five command routes; loopback by default). |
 
 Help commands:
 
@@ -180,7 +185,7 @@ The two fastest paths — each block notes where its commands run:
 # From the consumer machine — SSH between two personal machines; the door is
 # woken on demand, nothing to start on the host (prerequisites: ssh
 # reachable + ukp on its PATH):
-ukp register --url ssh://<host>                        # once; TOFU stored
+ukp register --url ssh://<host>                        # once; trust-on-first-use pinned
 ukp read --endpoint <name> notes/x.md                  # just works, like local
 
 # Native TLS on a bare IP — self-signed, pinned automatically at registration.
@@ -188,11 +193,18 @@ ukp read --endpoint <name> notes/x.md                  # just works, like local
 # register line runs on the consumer machine:
 UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 --tls
 ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
-# NAT/EIP cloud host (public IP on no NIC)? Name it explicitly — the persisted
-# cert re-signs over the same key, so the pin (and every registration) survives:
-#   ukp serve … --tls --tls-san <public-ip>
 ```
 
+NAT/EIP cloud host (public IP on no NIC)? Name it with
+`ukp serve --tls --tls-san <public-ip>` — the persisted certificate re-signs
+over the same key, so the pin (and every registration) survives; details in
+the deployment guide.
+
+Registration mechanics: a **host door** url imports every endpoint behind it
+(`--endpoint <name>` checks the served name and narrows the import to that
+one, `--select` narrows to a subset); `--token` is stored with the binding;
+re-running a registration refreshes it idempotently.
+
 Remote endpoints take the same commands as local ones — search, read, nav,
 rg, propose. The full guide — the host door (one port for the whole
 registry), Caddy and Tailscale fronting, the certificate pinning lifecycle,
@@ -210,9 +222,7 @@ and the hardening posture — lives in the
 
 ## Documentation
 
-- [Remote deployment](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md) — serving endpoints over
-  SSH/HTTPS, the host door, Caddy and Tailscale fronting, the certificate
-  pinning lifecycle, and the hardening posture.
+- [Remote deployment](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md) — serving endpoints across machines: the full guide.
 - [Contributing](https://github.com/CatheadOwl/ukp/blob/main/CONTRIBUTING.md) — development setup and release packaging.
 - [Changelog](https://github.com/CatheadOwl/ukp/blob/main/CHANGELOG.md) — what changed per release.
 - Repository: https://github.com/CatheadOwl/ukp ·

package/bin/ukp.js

@@ -12,7 +12,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const cli = join(here, "..", "src", "cli.ts");
@@ -68,15 +68,35 @@ function fail(detail) {
 
 const bunPath = bunCandidates().find((candidate) => existsSync(candidate));
 if (bunPath === undefined) {
-  fail("looked for UKP_BUN, the standard install locations, and PATH");
+  fail("looked at UKP_BUN, the standard install locations, and PATH");
 }
-const result = spawnSync(bunPath, [cli, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env: process.env,
-});
-if (result.error) {
-  // bunPath existed on disk a moment ago; a spawn failure here is exotic,
-  // but it must still land in the remedy, never a stack trace.
-  fail(`spawning '${bunPath}' failed: ${String(result.error.message ?? result.error)}`);
+
+// In-process handoff when this launcher already runs under bun (bun's own
+// bin links and `bunx`): importing the CLI keeps it in THIS process, where
+// stdout/stderr keep their real TTY identity (columns, isTTY) — a spawnSync
+// grandchild re-inherits duplicated handles, and on some hosts that layer
+// degraded TTY detection (the third dogfood round: progress/wrap silently
+// skipped while a direct run on the same console had both). One process
+// also starts faster. The node-interpreted path (npm shims) keeps spawning.
+if (runningUnderBun) {
+  const { runCli } = await import(pathToFileURL(cli).href);
+  const exit = runCli(process.argv.slice(2));
+  if (exit instanceof Promise) {
+    exit.then((code) => {
+      process.exitCode = code;
+    });
+  } else {
+    process.exitCode = exit;
+  }
+} else {
+  const result = spawnSync(bunPath, [cli, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.error) {
+    // bunPath existed on disk a moment ago; a spawn failure here is exotic,
+    // but it must still land in the remedy, never a stack trace.
+    fail(`spawning '${bunPath}' failed: ${String(result.error.message ?? result.error)}`);
+  }
+  process.exit(result.status === null ? (result.signal !== null ? 130 : 1) : result.status);
 }
-process.exit(result.status === null ? (result.signal !== null ? 130 : 1) : result.status);

package/docs/remote-deployment.md

@@ -0,0 +1,309 @@
+# Remote deployment
+
+Operational guide for exposing UKP endpoints over the network. For the
+two fastest consumer-side paths (SSH between personal machines, native TLS
+on a bare IP), see the README's "Remote in 60 seconds"; this guide covers
+every deployment shape end to end.
+
+**Choosing a path by burden** (someone always holds the port — the only
+question is who): the ssh:// path wakes the door on demand and adds zero
+resident processes on every OS (Windows hosts enable the built-in OpenSSH
+Server feature once). The https path needs a resident listener: on Linux,
+systemd socket activation holds the port and spawns the door per use
+(zero resident ukp); on Windows there is no systemd equivalent and a bun
+process cannot natively be a service — the resident door runs as a
+hidden logon task (no visible window, bounded crash retry; see the
+Windows section), and only unattended-boot always-on would want a real
+service wrapper (WinSW-class), or prefer ssh:// there. The https door is
+the right shape when consumers have no SSH credentials.
+
+`ukp serve` speaks plain HTTP by default; TLS and public exposure are either
+**native** (`--tls` self-signs through the local openssl, `--tls-cert/--tls-key`
+serve your own certificate) or **delegated to a fronting component** (reverse
+proxy, SSH tunnel, overlay). The trust model is public PKI, or automatic TOFU
+pinning for self-signed and private-CA certificates. **Authentication is
+deny-by-default**: serving requires `UKP_SERVE_TOKEN`; tokenless serving needs
+an explicit `--allow-anonymous` and is refused off loopback. A reverse proxy on
+the same host forwards from the public side to the loopback bind, so proxied
+deployments treat the token as mandatory (serve cannot see past its own bind
+address).
+
+## Via SSH (two personal machines — zero extra components, zero ceremony)
+
+The `ssh://` URL scheme makes the transport transparent AND wakes the door
+on demand: each invocation runs one ssh process that opens the forward and
+starts a pinned loopback `ukp serve` on the host (the door serves the host
+Registry fresh and self-reaps when idle — nothing to pre-start, no token:
+SSH carries encryption and auth). Later invocations within a couple of
+minutes reuse the warmed SSH connection. Prerequisites on the host: ssh
+reachable (your key) and ukp on its PATH. A first call that cannot find
+`ukp` on the remote PATH says so with the remedy.
+
+```bash
+ukp register --url ssh://<host>                        # once; the first call wakes the door
+ukp read --endpoint <name> notes/x.md                  # just works, like local
+```
+
+Notes:
+- The `ssh://` url port selects nothing — the woken door listens on a
+  client-chosen loopback port per invocation.
+- **Host prerequisite = a standard install.** `npm install -g
+  @catheadowl/ukp` (or `bun add -g`) on the host is all it takes — the wake
+  command prepends the standard install locations (`~/.bun/bin`,
+  `~/.npm-global/bin`, brew prefixes, then `$PATH`) before exec, so both
+  `ukp` and its bun shebang resolve even though `ssh host cmd` runs a bare
+  non-interactive PATH. Verified with a user-prefix npm install (ukp + bun
+  both in `~/.npm-global/bin`, invisible to a bare shell):
+  wake register 5.2s, day-2 read 4.8s, no orphans. Only exception:
+  nvm-style versioned layouts have no fixed path shape — link once with
+  `sudo ln -s "$(command -v ukp)" /usr/local/bin/ukp`.
+- Consecutive invocations share an ssh multiplexing master for two minutes
+  (handshake amortization); Windows' native ssh has no multiplexing and
+  quietly pays the handshake per call.
+- To lock down what SSH may run, restrict the login shell (git-shell
+  style). A forced `command=` in authorized_keys does NOT compose with
+  wake — the client chooses the door port per invocation, which a fixed
+  forced command cannot express.
+
+Windows hosts work out of the box: when the host's OpenSSH default shell
+(cmd.exe) rejects the POSIX wake form, the client detects the signature and
+resends the pinned cmd.exe form automatically — nothing to configure beyond
+the OpenSSH Server feature and your key. A powershell DefaultShell is not
+supported (its `-c` quoting drops the wake form).
+
+## Native TLS (bare IP, no domain — zero extra components)
+
+`--tls` self-signs on first start (identity = keypair, persisted under the
+Service folder's `.ukp/tls/`; SAN covers the host's addresses). Clients pin
+the certificate automatically at registration — same command as any other
+remote, no flags added:
+
+```bash
+UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 --tls
+# consumer machine (self-signed is TOFU-pinned at registration):
+ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
+ukp read --endpoint <name> notes/x.md                # just works, like local
+```
+
+A certificate renewal that keeps the key re-anchors transparently; a new key
+(reinstall) blocks with both fingerprints until you re-register. Prefer real
+certificates? Let's Encrypt issues IP-address certificates (GA 2026-01) —
+run certbot with a renewal timer and point `--tls-cert/--tls-key` at the
+files; clients then need no pinning at all.
+
+**NAT/EIP cloud hosts** (public IP on no NIC — Alibaba/AWS-style 1:1 NAT):
+the automatic SAN coverage can never see the public address, so name it
+explicitly with `--tls-san` (repeatable; DNS names too):
+
+```bash
+UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 \
+  --tls --tls-san <public-ip>
+```
+
+A persisted certificate missing a requested entry is re-signed over the
+SAME key — the pin (and thus every client registration) survives, the
+banner honestly reports `self-signed identity (re-signed)`, and coverage
+only grows: the re-sign keeps everything the certificate already carried
+(so changing the flag list loses nothing), and already-covered or
+narrower requests reuse the certificate untouched. Explicit `--tls-cert` certificates carry their own SAN, so
+`--tls-san` next to them is a usage error, not a no-op.
+
+## Windows host (https — resident form)
+
+Windows has no socket-activation equivalent, so the https path on a
+Windows host is the resident form: one-time setup, auto-start at logon,
+one bun process always running — with **no visible window** (a hidden
+launcher owns the console; a popping cmd box is not an acceptable product
+form) and bounded crash retry. Verified end to end (register/TOFU →
+read → nav, plus zero-flash and crash-recovery drills) on a Windows 11
+host with a plain user-level install. Steps 3–6 are exactly what
+`ukp serve --print-task --host 0.0.0.0 --tls`
+(or `--tls-cert/--tls-key`) prints for you — the generator assembles the
+mechanical half (start script, hidden launcher, Task Scheduler command,
+firewall rule, token placeholder); this section keeps the judgment calls
+and the pitfalls the verification run caught:
+
+1. Install the usual way (bun's official installer + `npm i -g
+   @catheadowl/ukp` — the npm shim needs bun on PATH, both land in
+   per-user PATH dirs, which is fine here: the door is started by a
+   logged-on task, not a bare ssh shell).
+2. `ukp init service` in each folder, then run `ukp register` from inside
+   it (register takes no folder argument) for every endpoint to expose.
+3. Certificate — generate ONCE (Git for Windows' openssl works; avoids
+   any runtime openssl dependency of `--tls`):
+   `openssl req -x509 -newkey rsa:2048 -nodes -days 825 -keyout
+   %USERPROFILE%\.ukp\tls\key.pem -out %USERPROFILE%\.ukp\tls\cert.pem
+   -subj "/CN=ukp" -addext "subjectAltName=IP:<lan-ip>,DNS:localhost"`
+4. `%USERPROFILE%\.ukp\start-door.cmd` (CRLF!) — set UKP_SERVE_TOKEN,
+   run `ukp serve --host 0.0.0.0 --port 8570 --tls-cert ... --tls-key ...`
+   with the door.log redirect. No PATH export: the launcher finds bun
+   itself, and the logged-on task carries the per-user PATH. Write it
+   with a real editor (writing cmd files over ssh echo mangles `%`
+   escaping — copy the file instead).
+5. `%USERPROFILE%\.ukp\start-door-hidden.vbs` (CRLF, real editor) — the
+   hidden launcher the task actually runs: it starts the console hidden
+   at process creation (nothing ever flashes), captures everything to
+   door.log, propagates the exit code, and retries a crashed door
+   3 times, 30s apart. `ukp serve --print-task` prints it verbatim.
+6. `schtasks /Create /TN ukp-door /TR "wscript.exe
+   \"%USERPROFILE%\.ukp\start-door-hidden.vbs\"" /SC ONLOGON /F` (from an
+   elevated shell — creating an ONLOGON task from a plain one fails with
+   Access denied) + a firewall rule for the port; `schtasks /Run /TN
+   ukp-door` to start now.
+7. Client: `ukp register --url https://<host>:8570 --token <token>` —
+   TOFU pins the certificate; re-registering refreshes the pin.
+
+Pitfalls the verification run caught:
+- **A silent bind failure**: if something already listens on the port
+  (a leftover manual door, say), the new door exits EADDRINUSE invisibly
+  — door.log carries the line (the hidden launcher captures everything);
+  check `netstat -ano | findstr :8570` and the PID's command line.
+- ONLOGON starts at LOGON, not boot, and the launcher's crash retry is
+  bounded (3×30s): after an unattended reboot nobody logs into, or after
+  exhausted retries, the door is down until the next logon or a manual
+  `schtasks /Run`. Unattended-boot always-on would need WinSW/NSSM-class
+  wrapping — or prefer ssh:// there. (Task Scheduler's own
+  restart-on-failure setting does not fire on exit codes — do not rely
+  on it.)
+- To restart the door by hand (new token, ukp upgrade, new cert):
+  `taskkill /PID <door-pid> /T /F`, then `schtasks /Run /TN ukp-door` —
+  `schtasks /End` does not reliably kill the process tree.
+- `rg` on the host is the host's business — no ripgrep installed means
+  the remote `rg` capability reports unavailable (everything else works).
+
+## Socket activation (Linux — no resident process on the https path either)
+
+systemd can hold the listening port itself and spawn the door on first
+connection; the door then self-reaps after `--max-idle` seconds of no
+requests and systemd re-spawns it on the next one. Nothing resident
+between uses — the same zero-maintenance posture as the ssh wake, for the
+consumer-facing https door (Cockpit and Ubuntu's own sshd run this way).
+
+Two user-level units (matches a user-local install). Two systemd facts
+learned the hard way: **`Environment=` does not expand
+`%h`/`$HOME`** (specifiers work in `ExecStart=` paths but NOT inside
+`Environment=` — a literal `%h/...` PATH yields 203/EXEC), and **units
+source no profile** — so write literal paths:
+
+```ini
+# ~/.config/systemd/user/ukp-door.socket
+[Unit]
+Description=ukp host door (socket-activated)
+
+[Socket]
+ListenStream=8570
+
+# ~/.config/systemd/user/ukp-door.service
+[Unit]
+Description=ukp host door
+
+[Service]
+Environment=PATH=/home/<user>/.npm-global/bin:/home/<user>/.bun/bin:/usr/local/bin:/usr/bin
+EnvironmentFile=-/home/<user>/.config/ukp-door.env   # UKP_SERVE_TOKEN=… (chmod 600)
+ExecStart=/home/<user>/.npm-global/bin/ukp serve --systemd-socket --max-idle 60 --tls
+```
+
+```bash
+loginctl enable-linger "$USER"          # let the socket answer while you're
+                                        # not logged in
+systemctl --user daemon-reload
+systemctl --user enable --now ukp-door.socket
+# nothing is running yet — the first client connection spawns the door:
+ukp register --url https://<host>:8570 --token <token>   # cold start, TOFU-pins
+```
+
+Notes:
+- The port belongs to the SOCKET unit — serve runs `--systemd-socket`
+  (`--port` is rejected alongside) and requires `UKP_SERVE_TOKEN`: the
+  bind address is the unit's (possibly public), so tokenless serving is
+  not verifiable from inside the process.
+- TLS: `--tls` self-signs on first start (identity under `~/.ukp/tls/`);
+  clients pin at registration. LE/mkcert: `--tls-cert/--tls-key` as usual.
+- Do NOT put an HTTP health-check in front of the socket — it would wake
+  the door on every probe and defeat `--max-idle`.
+- `systemctl --user` over bare ssh needs `XDG_RUNTIME_DIR=/run/user/$(id -u)`.
+- Restarting the SOCKET while a door is still running is refused
+  ("Socket service already active") — `systemctl --user restart
+  ukp-door.service` instead, or let the door idle out first.
+- **NAT/EIP hosts**: `--tls` self-signs with the machine's interface
+  addresses — a public EIP is not among them, and registration would fail
+  CERT_ALTNAME_INVALID. Add `--tls-san <public-ip>` next to `--tls`
+  (see Native TLS above): the SAN grows, the key (and pin) does not.
+
+## Host door (one host, many endpoints — one gesture, zero tokens)
+
+Trust's natural unit is the host, not the endpoint: if you can ssh to a
+machine, per-endpoint tokens are ceremony — and with the on-demand wake you
+don't even run the door yourself: `ukp register --url ssh://<host>`
+wakes a loopback door (`docker DOCKER_HOST=ssh://` posture — SSH carries
+encryption and auth), imports everything behind it, and the door reaps
+itself when idle:
+
+```bash
+# nothing to run on the host first — one gesture imports everything:
+ukp register --url ssh://<host>
+# door ssh://<host>: 2 endpoint(s)
+# imported: notes    (search,propose)
+# imported: archive  (-)
+ukp list                       # flat rows, urls like ssh://<host>/notes
+ukp read ukp://notes/plan.md   # day-2 is byte-identical to today's remotes
+```
+
+A manually started door still works (e.g. under systemd, for a host you
+deliberately keep serving): `ukp serve --allow-anonymous` without
+`--endpoint` exposes the same whole-registry door on a fixed loopback port —
+but the wake makes that an explicit choice, not a prerequisite.
+
+Imported endpoints are ordinary remote bindings (`url = <door>/<name>`); a
+name already bound elsewhere is skipped with a visible reason, re-running
+the import refreshes pins idempotently, and `--select a,b` narrows the
+take. When the door grows, `ukp list` says so on stderr (`1 unimported
+endpoint(s): …`) — importing it stays your call. The consumer variant of
+the same door is public: `ukp serve --host 0.0.0.0 --tls-cert …` with
+`UKP_SERVE_TOKEN`, imported with `ukp register --url https://<ip>:8570
+--token <t>` for the whole door, or `ukp register --url https://<ip>:8570
+--endpoint <name> --token <t>` for one asserted endpoint (token and pinned
+certificate copied into each binding).
+
+## Behind Caddy (public domain)
+
+```
+# Caddyfile — automatic Let's Encrypt
+kb.example.com {
+    reverse_proxy 127.0.0.1:8570
+}
+```
+
+```bash
+UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 127.0.0.1 --port 8570
+# on the consumer machine:
+UKP_ENDPOINT_<NAME>_TOKEN=<token> ukp register --url https://kb.example.com
+```
+
+## Via Tailscale (two machines on any network — including the same LAN)
+
+Enable HTTPS certificates on your tailnet once (admin console: DNS →
+MagicDNS → HTTPS Certificates); Tailscale then provisions Let's Encrypt
+certificates for your `*.ts.net` hostnames.
+
+```bash
+# both machines: tailscale up (same tailnet)
+# server machine:
+UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 127.0.0.1 --port 8570
+tailscale serve --bg --https=443 http://127.0.0.1:8570
+# consumer machine:
+UKP_ENDPOINT_<NAME>_TOKEN=<token> ukp register --url https://<machine>.<tailnet>.ts.net
+```
+
+The overlay covers LAN and roaming machines alike; a fully offline LAN (no
+coordination reachability) is the one gap — a dedicated private-CA recipe is
+not covered here.
+
+## Hardening posture
+
+- rate limiting, IP allowlists, and audit logging live at the proxy layer —
+  the `ukp` core stays thin;
+- multiple client tokens: comma-separate them — `UKP_SERVE_TOKEN=alice,bob`
+  (any listed token authorizes);
+- identity pinning is TOFU on `instance_uid`: a changed endpoint warns by
+  default; set `UKP_TOFU=block` on hostile networks to refuse it outright.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "src",
+    "docs",
     "README.md",
     "LICENSE",
     "package.json"

package/src/capabilities/propose.ts

@@ -442,7 +442,7 @@ export function runPropose(request: ProposeRequest, context: ProposeContext): Pr
       failure: {
         errorClass: "capability-undeclared",
         message: `endpoint '${binding.name}' does not declare the propose capability`
-          + ` — declare [capabilities.propose] in the Service Manifest (.ukp/service.toml); 'ukp guide propose' walks through it`,
+          + ` - declare [capabilities.propose] in the Service Manifest (.ukp/service.toml); 'ukp guide propose' walks through it`,
       },
     };
   }

package/src/capabilities/read.ts

@@ -870,7 +870,7 @@ function executeResolvedRead(
         return readFailure(
           "resource-missing",
           `resource-missing '${request.path}' in endpoint '${binding.name}'`
-            + ` (absolute paths address files exactly; the mapped route does not exist — the target may live one level deeper, e.g. under src/)\n`
+            + ` (absolute paths address files exactly; the mapped route does not exist - the target may live one level deeper, e.g. under src/)\n`
             + formatRecoveryCandidates(recovered.recovery.candidates).trimEnd(),
           recovered.recovery,
         );