@catheadowl/ukp 0.2.1 → 0.2.3

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/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.1",
+  "version": "0.2.3",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "src",
+    "docs",
     "README.md",
     "LICENSE",
     "package.json"

package/src/capabilities/remote-client.ts

@@ -343,11 +343,40 @@ function wakeDoorCommand(remotePort: number, form: WakeShellForm = "posix"): str
 /** Wrong-shell failure signature for the wake ladder: the remote shell could
  * not even parse the sent form, so the OTHER form is the retry — as opposed
  * to a missing-ukp failure, where the shell ran fine and named 'ukp' as the
- * thing it cannot find. cmd.exe errors quote the missing token ('sh' is not
- * recognized, exit 9009); POSIX shells print "<token>: command not found". */
+ * thing it cannot find. Language-independent: cmd.exe locales vary the
+ * message body (English, zh-CN, German … all differ) but always quote the
+ * missing ASCII token; POSIX shells prefix the
+ * token ("sh: command not found"). */
 function wrongShellSignature(form: WakeShellForm, diagnostics: string): boolean {
-  if (form === "posix") return /'sh' is not recognized|sh: command not found/i.test(diagnostics);
-  return /'cmd' is not recognized|cmd: command not found/i.test(diagnostics);
+  if (form === "posix") return /['"]sh['"]|sh: (?:command )?not found/i.test(diagnostics);
+  return /['"]cmd['"]|cmd: (?:command )?not found/i.test(diagnostics);
+}
+
+/** One cheap, language-independent roundtrip to learn the host shell family
+ * BEFORE the first wake attempt (2026-09-20, liku 9.5 finding): cmd.exe
+ * expands `%OS%` to `Windows_NT`; a POSIX shell echoes the literal token.
+ * Choosing the form up front avoids the blind POSIX-first attempt costing a
+ * full ready-timeout on every Windows invocation, and picks the right tty
+ * stance — `-tt` exists for POSIX SIGHUP reaping; on Windows there is no
+ * SIGHUP (max-idle bounds the door), and at least one Win32-OpenSSH 9.5
+ * build LOSES a quoted remote command under a pty (an interactive cmd
+ * swallows it and waits on stdin forever — the no-pty path executes it
+ * correctly). Defaults to POSIX (the common server shape) when the probe
+ * errors or times out; the ladder remains as the backstop. */
+async function probeHostShellFamily(
+  options: { sshCommand?: readonly string[] },
+  target: string,
+): Promise<WakeShellForm> {
+  const proc = Bun.spawn(
+    [...(options.sshCommand ?? ["ssh"]), "-o", "BatchMode=yes", target, "echo %OS%"],
+    { stdout: "pipe", stderr: "pipe", stdin: "ignore" },
+  );
+  const output = await Promise.race([
+    new Response(proc.stdout).text().catch(() => ""),
+    Bun.sleep(5_000).then(() => ""),
+  ]);
+  proc.kill();
+  return /Windows_NT/i.test(output) ? "cmd" : "posix";
 }
 
 /** HTTP-level readiness probe through the tunnel (W9): a TCP accept on the
@@ -428,11 +457,10 @@ async function openSshTunnel(
   // options for the remaining attempts so the endpoint degrades to Tier 0
   // instead of hard-failing what worked without mux.
   let muxDisabled = false;
-  // Shell-form ladder (2026-09-20): POSIX first (the common server shell),
-  // cmd second — a Windows host whose OpenSSH default shell is cmd.exe fails
-  // the POSIX form with an 'sh'-not-recognized signature (not a missing-ukp
-  // failure: the shell never got as far as looking for ukp).
-  let form: WakeShellForm = "posix";
+  // Shell form (2026-09-20): probed up front via `echo %OS%` (language-
+  // independent — see probeHostShellFamily), POSIX by default; the wrong-
+  // shell ladder below remains the backstop for a lying or timed-out probe.
+  let form: WakeShellForm = await probeHostShellFamily(options, target);
   const attempts = 3;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     const localPort = await freePort();
@@ -443,8 +471,11 @@ async function openSshTunnel(
       // SIGHUP on disconnect — normal disconnect included, the door only ever
       // died to --max-idle. Forcing a pty gives the session a controlling
       // terminal, so killing the client reaps the door in seconds (verified:
-      // kill -9 of the local ssh → door gone within 3s).
-      "-tt",
+      // kill -9 of the local ssh → door gone within 3s). POSIX hosts only:
+      // Windows has no SIGHUP (max-idle bounds the door there), and pty
+      // sessions lose quoted remote commands on at least one
+      // Win32-OpenSSH 9.5 build — the cmd form goes without -tt.
+      ...(form === "posix" ? ["-tt"] : []),
       "-o", "ExitOnForwardFailure=yes",
       "-o", "BatchMode=yes",
       ...(muxDisabled ? [] : muxClientOptions()),

package/src/cli.ts

@@ -198,9 +198,9 @@ export function renderHelp(): string {
     ]),
     "Endpoint names for --endpoint come from 'ukp list'.",
     "",
-    "A Service's declared capabilities are backed by a provider (QMD backs search and update today); rg and nav work on endpoint files directly, no provider needed.",
+    "A Service's declared capabilities are backed by a provider (QMD, an external tool, backs search and update today); rg and nav work on endpoint files directly, no provider needed.",
     "",
-    "A Service is a folder with a manifest (a name plus optional declared capabilities); registering it binds that name as an endpoint you address with --endpoint. The scope is which endpoints commands use when no --endpoint or -g (every registered endpoint) is given; 'ukp guide client' shows how to set the workspace default.",
+    "A Service is a folder with a manifest (a name plus optional declared capabilities); registering it binds that name as an endpoint you address with --endpoint. The scope is which endpoints commands use when no --endpoint is given; -g widens a command to every registered endpoint; 'ukp guide client' shows how to set the workspace default.",
     "",
     "Guides:",
     ...GUIDE_TOPICS.map(([topic, summary]) => `  ukp ${`guide ${topic}`.padEnd(17)} ${summary}`),

package/src/commands/diagnose.ts

@@ -227,7 +227,7 @@ function diagnoseBinding(
   if (isRemoteBinding(binding)) {
     return {
       status: "failed",
-      message: `remote endpoint '${binding.name}' (${binding.url}): diagnose is local-only in ukp_remote W2; reachability shows in 'ukp list'`,
+      message: `remote endpoint '${binding.name}' (${binding.url}): diagnose is local-only for remote endpoints; reachability shows in 'ukp list'`,
     };
   }
   try {

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

@@ -55,7 +55,8 @@ Name and identity:
 
 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.
+- 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/init.ts

@@ -189,7 +189,7 @@ function executeInitServiceCommand(args: readonly string[], context: InitCommand
         `location: ${result.folder}`,
         "declared_capabilities: -",
         "derived_capabilities: read, nav",
-        "provider_free: rg (if rg is installed)",
+        "base_tier: rg (external tool; active when ripgrep 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

package/src/commands/inspect.ts

@@ -66,7 +66,7 @@ function inspectBinding(
   if (isRemoteBinding(binding)) {
     return {
       status: "failed",
-      message: `remote endpoint '${binding.name}' (${binding.url}): inspect deep-dive is local-only in ukp_remote W2; capabilities show in 'ukp list'`,
+      message: `remote endpoint '${binding.name}' (${binding.url}): inspect deep-dive is local-only for remote endpoints; capabilities show in 'ukp list'`,
     };
   }
   try {

package/src/commands/inventory.ts

@@ -665,9 +665,21 @@ async function collectDoorDriftNotes(
       const unimported = door.doc.endpoints
         .map((endpoint) => endpoint.name)
         .filter((name) => !group.imported.has(name));
-      if (unimported.length > 0) {
+      if (unimported.length === 0) continue;
+      // A roster name can be unimported because it COLLIDED — the name is
+      // held by another binding, and the plain import remedy would skip it
+      // again. Those names get the single-endpoint --name remedy instead
+      // (W11 / ADR-REM-007).
+      const free = unimported.filter((name) => !endpoints.some((binding) => binding.name === name));
+      const taken = unimported.filter((name) => endpoints.some((binding) => binding.name === name));
+      if (free.length > 0) {
         notes.push(
-          `door ${origin}: ${unimported.length} unimported endpoint(s): ${unimported.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>'`,
         );
       }
     } catch {

package/src/commands/read.ts

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

package/src/commands/serve-task.ts

@@ -0,0 +1,198 @@
+/** Windows resident-door artifact generator (W12): `ukp serve --print-task`
+ * renders the process-manager artifacts for an https door on a Windows host
+ * — the start script, the hidden launcher (vbs), the Task Scheduler command,
+ * the firewall rule — as text the operator reviews and applies. Print-only
+ * by construction: UKP installs nothing, starts nothing, and never sees the
+ * real token (the script line carries a placeholder; the operator pastes the
+ * token into the file they save, under their own permission regime).
+ *
+ * The emitted shapes mirror the machine-verified liku recipe (deployment
+ * handbook, Windows section): a bare `ukp` resolves through the logged-on
+ * task's per-user PATH and the self-locating launcher finds bun itself, so
+ * no PATH export is emitted. The hidden launcher is the product default
+ * (owner ruling 2026-09-21: a visibly popping cmd window is not a correct
+ * product form): zero flash (hidden at process creation), door.log capture,
+ * exit-code propagation, bounded crash retry — Task Scheduler's own
+ * restart-on-failure does not fire on exit codes (disproven on liku). */
+
+export interface ServeTaskTlsSelfSigned {
+  mode: "self-signed";
+  sanEntries: string[];
+}
+
+export interface ServeTaskTlsCertificates {
+  mode: "certificates";
+  certPath: string;
+  keyPath: string;
+}
+
+export type ServeTaskTls = ServeTaskTlsSelfSigned | ServeTaskTlsCertificates;
+
+export interface ServeTaskInput {
+  /** Present = single-endpoint mode; absent = host door mode. */
+  endpoint?: string;
+  host: string;
+  port: number;
+  tls?: ServeTaskTls;
+}
+
+/** Door-shape guards the command layer runs before printing. Pure so both
+ * platforms are testable: `platform` is `process.platform` in production.
+ * These mirror what serve itself would refuse at task start — they never
+ * widen admission, and the TLS one stops a dead-end artifact before it is
+ * applied (clients refuse to register plain-http urls off loopback). */
+export function printTaskPreflightError(input: {
+  platform: string;
+  host: string;
+  hasTls: boolean;
+  allowAnonymous: boolean;
+}): string | undefined {
+  if (input.platform !== "win32") {
+    return "--print-task is Windows-only; on Linux prefer systemd socket activation (ukp serve --systemd-socket) — the deployment handbook carries that recipe";
+  }
+  const loopback =
+    input.host === "127.0.0.1" || input.host === "localhost" || input.host === "::1" || input.host === "[::1]";
+  if (!loopback && !input.hasTls) {
+    return "refusing to print an off-loopback door without TLS: clients refuse to register plain-http urls — pass --tls (self-signed, pinned at registration) or --tls-cert/--tls-key, or bind loopback behind a TLS-terminating proxy";
+  }
+  if (input.allowAnonymous && !loopback) {
+    return "refusing to print this shape: --allow-anonymous is loopback-only and serve would refuse it at task start — set the token in the generated script instead";
+  }
+  return undefined;
+}
+
+function serveCommandLine(input: ServeTaskInput): string {
+  const tls =
+    input.tls === undefined
+      ? []
+      : input.tls.mode === "self-signed"
+        ? ["--tls", ...input.tls.sanEntries.map((entry) => `--tls-san ${entry}`)]
+        : [`--tls-cert "${input.tls.certPath}"`, `--tls-key "${input.tls.keyPath}"`];
+  return [
+    "ukp serve",
+    ...(input.endpoint !== undefined ? [`--endpoint ${input.endpoint}`] : []),
+    `--host ${input.host}`,
+    `--port ${input.port}`,
+    ...tls,
+  ].join(" ");
+}
+
+/** Parent directory of a path string, or undefined for a bare filename. */
+function parentDirOf(path: string): string | undefined {
+  const cut = Math.max(path.lastIndexOf("\\"), path.lastIndexOf("/"));
+  return cut > 0 ? path.slice(0, cut) : undefined;
+}
+
+export function renderServeTaskArtifacts(input: ServeTaskInput): string {
+  const serveLine = serveCommandLine(input);
+  const out: string[] = [
+    "ukp serve --print-task — Windows resident-door artifacts",
+    "",
+    "Print-only: review these, then apply them yourself. UKP installs nothing,",
+    "starts nothing, and supervises nothing — the door's lifecycle belongs to",
+    "you and your process manager.",
+    "",
+  ];
+
+  if (input.tls?.mode === "certificates") {
+    const certDir = parentDirOf(input.tls.certPath);
+    out.push(
+      "0) Certificate — generate ONCE (Git for Windows' openssl works; this",
+      "   avoids any runtime openssl dependency of --tls):",
+      "",
+      "   openssl req -x509 -newkey rsa:2048 -nodes -days 825 -keyout",
+      `   ${input.tls.keyPath} -out ${input.tls.certPath}`,
+      "   -subj \"/CN=ukp\" -addext \"subjectAltName=IP:<lan-ip>,DNS:localhost\"",
+      "",
+      "   The SAN must carry the address consumers dial (find <lan-ip> with",
+      "   ipconfig); a mismatch fails registration with a certificate name",
+      "   error. Renewing over the same key keeps client pins valid.",
+      "",
+    );
+    if (certDir !== undefined) {
+      out.push(`   (openssl will not create the directory: if not exist "${certDir}" mkdir "${certDir}" first)`, "");
+    }
+  }
+
+  out.push(
+    "1) Start script — save as %USERPROFILE%\\.ukp\\start-door.cmd",
+    "   (write it with a real editor and CRLF line endings; writing cmd",
+    "   files over ssh echo mangles % escaping)",
+    "",
+    "   @echo off",
+    "   rem UKP resident door (generated by ukp serve --print-task)",
+    "   rem The token line is the only secret: mint a long random string",
+    "   rem (e.g. openssl rand -hex 32), paste it in, keep this file private.",
+    "   set \"UKP_SERVE_TOKEN=<paste-your-token>\"",
+    "   rem ukp resolves through the logged-on task's per-user PATH; the",
+    "   rem launcher finds bun itself — no PATH export needed.",
+    "   if not exist \"%USERPROFILE%\\.ukp\" mkdir \"%USERPROFILE%\\.ukp\"",
+    `   ${serveLine} >> "%USERPROFILE%\\.ukp\\door.log" 2>&1`,
+    "",
+    "2) Hidden launcher — save as %USERPROFILE%\\.ukp\\start-door-hidden.vbs",
+    "   (CRLF and a real editor again: the vbs carries literal % signs that",
+    "   ssh echo would expand — copy the file instead)",
+    "",
+    "   ' UKP door hidden launcher: runs start-door.cmd with NO visible",
+    "   ' window (hidden at process creation - nothing flashes), captures",
+    "   ' everything to door.log, waits out the door's lifetime, propagates",
+    "   ' its exit code, and retries a crashed door 3 times, 30s apart.",
+    "   Dim shell : Set shell = CreateObject(\"WScript.Shell\")",
+    "   Dim q : q = Chr(34)",
+    "   Dim home : home = shell.ExpandEnvironmentStrings(\"%USERPROFILE%\")",
+    "   Dim cmdline : cmdline = \"cmd /c \" & q & q & home & \"\\.ukp\\start-door.cmd\" & q & \" >> \" & q & home & \"\\.ukp\\door.log\" & q & \" 2>&1\" & q",
+    "   Dim rc : rc = 0",
+    "   Dim attempt",
+    "   For attempt = 1 To 3",
+    "     rc = shell.Run(cmdline, 0, True)",
+    "     If rc = 0 Then Exit For",
+    "     If attempt < 3 Then WScript.Sleep 30000",
+    "   Next",
+    "   WScript.Quit rc",
+    "",
+    "3) Scheduled task — starts the door at LOGON, hidden",
+    "   (create it from an elevated shell: creating an ONLOGON task from a",
+    "    plain shell fails with Access denied)",
+    "",
+    "   schtasks /Create /TN ukp-door /TR \"wscript.exe \\\"%USERPROFILE%\\.ukp\\start-door-hidden.vbs\\\"\" /SC ONLOGON /F",
+    "   schtasks /Run /TN ukp-door",
+    "",
+    "4) Firewall rule for the port (from an elevated shell)",
+    "",
+    `   netsh advfirewall firewall add rule name="ukp-door" dir=in action=allow protocol=TCP localport=${input.port}`,
+    "",
+    "Notes:",
+    ...(input.tls?.mode === "self-signed"
+      ? [
+          "- --tls self-signs at first start using an openssl on PATH (Git",
+          "  for Windows' openssl qualifies). On a host with no openssl",
+          "  anywhere, pre-generate the certificate once instead: re-run with",
+          "  --tls-cert/--tls-key — the handbook's Windows section carries",
+          "  that recipe.",
+        ]
+      : []),
+    "- No visible window, by design: the hidden launcher starts the console",
+    "  hidden at process creation (nothing ever flashes on the desktop) and",
+    "  captures everything to door.log — that redirect is the paper trail (a",
+    "  silent EADDRINUSE exit leaves a line).",
+    "- Crash self-recovery is the launcher's bounded retry: a non-zero exit",
+    "  is retried up to 3 times, 30s apart; exhausted retries leave the",
+    "  failure visible (non-zero task result + door.log). Do not rely on",
+    "  Task Scheduler's restart-on-failure setting — it does not fire on",
+    "  exit codes.",
+    "- 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).",
+    "- LOGON, not boot: the door starts when someone logs on — nobody",
+    "  logged on means no door. Unattended-boot always-on needs a service",
+    "  wrapper (WinSW-class) — deliberately outside this recipe; prefer the",
+    "  ssh:// path or a Linux host (systemd socket activation) for that.",
+    "- Re-run ukp serve --print-task with different flags to regenerate;",
+    "  edits land by saving the files and re-running schtasks /Run.",
+    "- Full recipes and hardening: the deployment handbook —",
+    "  docs/remote-deployment.md in this package, or",
+    "  https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md",
+    "",
+  );
+  return out.join("\n");
+}

package/src/commands/serve.ts

@@ -9,6 +9,7 @@ import {
 } from "./kit.ts";
 import { normalizeTlsSanEntry } from "../capabilities/tls-identity.ts";
 import { DISCOVERY_PATH, startUkpServer, type ServeInfo } from "../server.ts";
+import { printTaskPreflightError, renderServeTaskArtifacts, type ServeTaskTls } from "./serve-task.ts";
 
 export interface ServeCommandContext {
   currentDirectory: string;
@@ -33,11 +34,11 @@ function parseServeTokens(raw: string | undefined): string[] {
  * over `/e/<name>/` routing. */
 export const SERVE_SPEC: UkpCommandSpec = {
   name: "serve",
-  summary: "serve one endpoint — or the whole registry as a host door — over HTTP for remote UKP clients",
+  summary: "serve one endpoint — or the whole registry as a host door, one HTTP server for every endpoint — for remote UKP clients",
   group: "operations",
   description:
     "Expose a registered endpoint over HTTP using the ukp-remote wire, or — without --endpoint — serve every local endpoint as one host door routed by name.",
-  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]… | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket]",
+  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]… | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket] [--print-task]",
   options: [
     { flags: "--endpoint <name>", help: "the registered endpoint to expose; omit it to serve the whole registry as a host door (/e/<name>/ routing, all endpoints, one port)" },
     { flags: "--host <addr>", help: "listen address (default 127.0.0.1, loopback only without a token)" },
@@ -49,6 +50,7 @@ export const SERVE_SPEC: UkpCommandSpec = {
     { flags: "--allow-anonymous", help: "permit tokenless access on loopback (local testing, or an ssh-forwarded host door where SSH carries encryption and auth; reverse-proxy deployments still require UKP_SERVE_TOKEN)" },
     { flags: "--max-idle <seconds>", help: "exit after <seconds> without requests (self-reap; the orphan backstop for on-demand-woken doors — fractional values accepted for tests)" },
     { flags: "--systemd-socket", help: "serve on the systemd socket-activation listener (LISTEN_FDS fd 3) instead of binding a port — the port belongs to your .socket unit; Linux-only" },
+    { flags: "--print-task", help: "Windows: print this door's process-manager artifacts (start script, hidden launcher, Task Scheduler command, firewall rule) instead of serving — review and apply them yourself; nothing is installed or started for you, and the token is yours to paste (never printed)" },
   ],
   helpSuffix: [
     "",
@@ -81,7 +83,7 @@ export const SERVE_SPEC: UkpCommandSpec = {
     "  'ukp register --url ssh://<host>' — zero tokens, docker",
     "  DOCKER_HOST=ssh:// posture). It is not the way to consume a",
     "  same-machine endpoint — register its local path instead.",
-    "  TLS (W5'): pass --tls to serve HTTPS with a self-signed identity",
+    "  TLS: pass --tls to serve HTTPS with a self-signed identity",
     "  (generated under .ukp/tls/ — under the registry directory in door",
     "  mode —, SAN covers this host's addresses; remote clients TOFU-pin it",
     "  at registration and refresh by re-registering), or --tls-cert/--tls-key",
@@ -107,6 +109,9 @@ export interface ParsedServe {
   maxIdleSeconds?: number;
   /** Present = the systemd-passed listener (W10, Linux-only). */
   systemdSocket?: boolean;
+  /** Present = render the Windows process-manager artifacts instead of
+   * serving (W12; Windows-only, print-only, never starts a listener). */
+  printTask?: boolean;
   /** `--tls-san` values, normalized to `IP:x`/`DNS:y` SAN form (repeatable);
    * valid only next to `--tls` — the execute layer enforces the pairing.
    * Absent when the flag is not passed (parse output stays byte-identical
@@ -115,7 +120,7 @@ export interface ParsedServe {
 }
 
 function toParsedServe(parsed: KitParsed): ParsedServe {
-  const options = parsed.options as { host?: string; port?: string; endpoint?: string; maxIdle?: string; systemdSocket?: boolean; tlsSan?: string[] };
+  const options = parsed.options as { host?: string; port?: string; endpoint?: string; maxIdle?: string; systemdSocket?: boolean; printTask?: boolean; tlsSan?: string[] };
   const endpoint = options.endpoint;
   if (endpoint !== undefined && endpoint.length === 0) {
     throw new KitUsageError("--endpoint <name> must not be empty (omit it to serve a host door)");
@@ -129,12 +134,19 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
   if (systemdSocket && options.port !== undefined) {
     throw new KitUsageError("--systemd-socket and --port are mutually exclusive (the socket unit owns the port)");
   }
+  const printTask = options.printTask === true;
+  if (printTask && systemdSocket) {
+    throw new KitUsageError("--print-task is the Windows resident form; --systemd-socket is the Linux one (systemd holds the port — see the deployment handbook)");
+  }
   let maxIdleSeconds: number | undefined;
   if (options.maxIdle !== undefined) {
     maxIdleSeconds = Number(options.maxIdle);
     if (!Number.isFinite(maxIdleSeconds) || maxIdleSeconds <= 0 || maxIdleSeconds > 86400) {
       throw new KitUsageError("--max-idle must be a positive number of seconds (at most 86400)");
     }
+    if (printTask) {
+      throw new KitUsageError("--print-task is for a resident door; --max-idle self-reaps (it is the on-demand backstop) and would leave the door down until the next logon");
+    }
   }
   let tlsSan: string[] = [];
   if (options.tlsSan !== undefined) {
@@ -152,6 +164,7 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
     port,
     ...(maxIdleSeconds !== undefined ? { maxIdleSeconds } : {}),
     ...(systemdSocket ? { systemdSocket } : {}),
+    ...(printTask ? { printTask } : {}),
     ...(tlsSan.length > 0 ? { tlsSan } : {}),
   };
 }
@@ -173,6 +186,7 @@ export function renderServeBanner(info: ServeInfo): string {
       `  endpoints: ${info.door!.endpoints.length > 0 ? info.door!.endpoints.join(", ") : "(none — register endpoints on this host)"}`,
       `  write: ${info.door!.write.length > 0 ? info.door!.write.join(", ") + " (propose via PUT /e/<name>/v1/propose/<id>)" : "(no endpoint declares propose)"}`,
       `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback bind; ssh-forwarded clients authenticate by SSH key)"}`,
+      `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
       ...(info.maxIdleSeconds !== undefined
         ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
         : []),
@@ -187,6 +201,7 @@ export function renderServeBanner(info: ServeInfo): string {
     `  listening: ${info.url}`,
     `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url}`,
     `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback only)"}`,
+    `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
     ...(info.maxIdleSeconds !== undefined
       ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
       : []),
@@ -228,6 +243,7 @@ export function executeServeCommand(
   return executeKitCommand(SERVE_SPEC, args, (parsed) => {
     const { endpoint, host, port, maxIdleSeconds, systemdSocket, tlsSan = [] } = toParsedServe(parsed);
     const allowAnonymous = (parsed.options as { allowAnonymous?: boolean }).allowAnonymous === true;
+    const printTask = (parsed.options as { printTask?: boolean }).printTask === true;
     const options = parsed.options as { tls?: boolean; tlsCert?: string; tlsKey?: string };
     // TLS flag family (W5'): --tls and --tls-cert/--tls-key are mutually
     // exclusive; the explicit pair must arrive complete. --tls-san only
@@ -242,6 +258,37 @@ export function executeServeCommand(
     if (tlsSan.length > 0 && options.tls !== true) {
       throw new KitUsageError("--tls-san is only used with --tls (an explicit --tls-cert certificate carries its own SAN)");
     }
+    // W12 print-only branch: render the Windows artifacts and stop. No
+    // listener, no admission token check (the token is pasted into the
+    // generated script later), and the env token is deliberately not read
+    // — the output is secret-free by construction.
+    if (printTask) {
+      const preflight = printTaskPreflightError({
+        platform: process.platform,
+        host,
+        hasTls: options.tls === true || options.tlsCert !== undefined,
+        allowAnonymous,
+      });
+      if (preflight !== undefined) {
+        throw new Error(preflight);
+      }
+      const tls: ServeTaskTls | undefined =
+        options.tls === true
+          ? { mode: "self-signed", sanEntries: tlsSan }
+          : options.tlsCert !== undefined && options.tlsKey !== undefined
+            ? { mode: "certificates", certPath: options.tlsCert, keyPath: options.tlsKey }
+            : undefined;
+      return {
+        exitCode: 0,
+        stdout: renderServeTaskArtifacts({
+          host,
+          port,
+          ...(endpoint !== undefined ? { endpoint } : {}),
+          ...(tls !== undefined ? { tls } : {}),
+        }),
+        stderr: "",
+      };
+    }
     const tokens = context.tokens ?? parseServeTokens(process.env.UKP_SERVE_TOKEN);
     // W10: socket activation must not admit tokenless serving — the bind
     // address belongs to the socket unit (possibly public), so the loopback

package/src/server.ts

@@ -29,6 +29,7 @@ import {
   type NavRequest,
 } from "./capabilities/nav.ts";
 import {
+  rgExecutableAvailable,
   runRg,
   projectRgEnvelope,
   RG_DEFAULT_LIMIT,
@@ -150,6 +151,14 @@ export interface ServeInfo {
   host: string;
   port: number;
   authRequired: boolean;
+  /** ripgrep availability probed once at startup IN THE DOOR'S OWN PROCESS
+   * (2026-09-20, liku feedback): /v1/rg serves every endpoint and a missing
+   * binary degrades per-endpoint on the wire by design — but that truth is
+   * consumer-channel only. The banner line is the operator channel, and the
+   * probe environment is by construction the one that matters (ukp diagnose
+   * measures the invoking shell instead, which can differ from the door's
+   * schtasks / wake environment). */
+  rg: "ok" | "missing";
   /** TLS identity summary (W5' / D-079) when serving over HTTPS; the pin is
    * what remote clients TOFU-pin at registration. `source` "re-signed" marks
    * the one start that grew SAN coverage over the existing key (--tls-san
@@ -893,6 +902,7 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
     host,
     port: listener.port,
     authRequired: (config.tokens?.length ?? 0) > 0,
+    rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
       : {}),
@@ -1026,6 +1036,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     host,
     port: listener.port,
     authRequired: (config.tokens?.length ?? 0) > 0,
+    rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
       : {}),