@catheadowl/ukp 0.2.5 → 0.3.0

package/README.md

@@ -12,6 +12,10 @@ memorize, no provider-specific commands to relearn.
 > [!NOTE]
 > Early-stage CLI (MVP) — commands and behavior may still change.
 
+```bash
+npm install -g @catheadowl/ukp    # or: bun add -g @catheadowl/ukp
+```
+
 ```bash
 $ ukp init service --name notes && ukp register
 initialized Service: notes
@@ -27,11 +31,15 @@ $ ukp read ukp://notes/2026/q3-plan.md      # read straight from the reference
 # Q3 Plan
 Goals for Q3: ship the knowledge plane.
 
-$ echo '[capabilities.propose]' >> .ukp/service.toml   # the write face is opt-in: declare propose
+$ echo '[capabilities.propose]' >> .ukp/service.toml   # the write path is opt-in: declare propose
+$ echo '# typo fix' > typo-fix.md                       # a proposal is any Markdown draft
 $ ukp propose --endpoint notes --id typo-fix --file typo-fix.md
 proposal typo-fix created (revision 1)
 ```
 
+A `ukp://` reference is not a web link — it names a registered endpoint
+(local or remote); open one with `ukp read <uri>`.
+
 ## Why UKP
 
 Knowledge work starts in folders, but repeated use needs stable names,
@@ -50,8 +58,9 @@ predictable scope, and a single command surface. Use UKP when:
 
 - Register local folders as named knowledge endpoints — a registered folder
   is a *Service*, addressed by its endpoint name.
-- `ukp inspect` shows which endpoints the current scope selects — see what a
-  command will touch before running it.
+- `ukp inspect` shows which endpoints the current scope selects (the
+  nearest `.ukp/client.toml`; every registered endpoint when there is
+  none) — see what a command will touch before running it.
 - Navigate the Markdown structure of an endpoint — folders, descriptions,
   depth — with zero provider dependency.
 - Read endpoint files through the built-in `read/file` capability — if a
@@ -71,13 +80,15 @@ predictable scope, and a single command surface. Use UKP when:
 - 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 every local binding as
-  a host door — when you want it reachable from other machines.
+- Serve an endpoint over HTTP — a single endpoint, a `--select`ed subset, 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, docid handoff keys, and durable `ukp://` references
-  when they need machine-readable results.
+  when they need machine-readable results; every `ukp://` reference opens
+  with `ukp read <uri>`.
 
 UKP owns endpoint names, Registry bindings, scope, and output shape; the
 provider owns collection setup, indexes, ranking, and maintenance. UKP
@@ -125,14 +136,17 @@ endpoint without it; `propose` works wherever it's declared.
 
 An agent can carry out the same flow on your behalf.
 
-For workspace defaults, use `ukp guide client` and `.ukp/client.toml`.
+For workspace defaults, run `ukp use <endpoint>` (see `ukp guide client`) —
+it writes `.ukp/client.toml` and keeps it committable in one step.
 
 ## Commands
 
-Grouping below follows `ukp --help`; every command stays a flat
-`ukp <verb>`. `--endpoint <name>` is the canonical endpoint selector
-(`ukp unregister <name>` still takes the endpoint as a positional legacy
-form); `-g` selects the full local Host Registry where supported.
+Grouping below follows `ukp --help`; primary capability commands stay a flat
+`ukp <verb>`, while multi-verb capability families appear as object command
+groups (`ukp init service`, `ukp guide <topic>`). `--endpoint <name>`
+is the canonical endpoint selector (`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 — search, read, nav, rg, propose — work on local and
 remote endpoints; consuming a remote endpoint is a one-command gesture
@@ -142,7 +156,7 @@ Endpoint commands:
 
 | Command | What it does |
 |---|---|
-| `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 search` | Indexed search through the endpoint's provider (QMD today); `--recursive` expands the manifest's declared `dependencies`. Results hand off a docid handoff key 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; `--files` enumerates them instead of searching. Results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
@@ -152,9 +166,14 @@ 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 — 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. |
+| `ukp init service` | Creates a minimal `.ukp/service.toml`. The `.ukp/.gitignore` it drops ignores machine-local state only (the instance identity; the serve TLS identity lives in `~/.ukp/tls/`) — `service.toml` and `client.toml` are pure declarations and committable by design (a fresh clone re-registers in one `ukp register`). |
+| `ukp use <endpoint> [endpoint...]` | One-step consumer gesture: sets this workspace's `default_endpoints` (`.ukp/client.toml`, explicit replace, idempotent — every name must be registered) and keeps the config version-visible in the same step. `ukp inspect` confirms the active scope. |
+| `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`. A folder that moved re-binds in one step: `ukp register --rebind` from the new location (local bindings). |
+| `ukp list` | Lists endpoint bindings and capabilities under the **workspace scope** by default (nearest `.ukp/client.toml`; every registered endpoint when there is none); `-g` lists the full Host Registry without reading the client config. `--json` emits the offline machine snapshot (`ukp.list.v1`) riding the same scope — stable field names, the same data core as the text listing, zero network (remote bindings are registry facts only, so their capability fields are `null`); pin `-g` for the full snapshot. New endpoints on a host door show as a stderr note (`door <origin>: N unimported endpoint(s) …`) — importing stays an explicit gesture. |
+
+A legacy `.ukp/.gitignore` (the retired `*` self-ignore template) migrates
+to this posture in passing whenever `ukp register` (local folders) or
+`ukp use` meets one.
 
 Operations commands:
 
@@ -163,7 +182,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`, every local binding as a **host door** — over HTTP (a discovery document plus the five command routes; loopback by default). |
+| `ukp serve` | Serves one endpoint — or, without `--endpoint`, local bindings as a **host door** (every one of them, or just the ones `--select` names — unselected endpoints are not served, routed, or declared) — over HTTP (a discovery document plus the five command routes; loopback by default). |
 
 Help commands:
 
@@ -180,9 +199,11 @@ Help commands:
 ## Remote in 60 seconds
 
 `ukp serve` exposes an endpoint over HTTP. Authentication is deny-by-default:
-serving with a `--host` beyond loopback requires `UKP_SERVE_TOKEN` (tokenless
-serving needs an explicit `--allow-anonymous` and is refused off loopback).
-The two fastest paths — each block notes where its commands run:
+serving with a `--host` beyond loopback requires a credential — the
+`UKP_SERVE_TOKEN` env token (full power) or a labeled key issued into
+the `~/.ukp/tokens` file (tokenless serving needs an explicit
+`--allow-anonymous` and is refused off loopback). The two fastest
+paths — each block notes where its commands run:
 
 ```bash
 # From the consumer machine — SSH between two personal machines; the door is
@@ -198,15 +219,34 @@ UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 -
 ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
 ```
 
+Handing a second machine or an agent a narrower key? Issue labeled, scoped,
+revocable keys instead of sharing the env token (ON THE HOST):
+
+```bash
+ukp serve token add liku "notes:ro,cad:rw"   # prints the raw key ONCE
+ukp serve token list                          # labels, key ids, scopes
+ukp serve token revoke liku                   # next request is a 401
+```
+
+Scopes are `name:ro|rw` comma-separated (full power is the explicit `*:rw`);
+the file stores hashes only, and the door re-reads it on every request —
+deleting a line revokes without a restart. A scoped key sees only its own
+endpoints: out-of-scope names answer exactly like nonexistent ones. While
+`UKP_SERVE_TOKEN` is set it takes precedence and the file is not consulted.
+
 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
+Registration mechanics: a **host door** url imports every endpoint it declares
 (`--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.
+re-running a registration refreshes it idempotently. A host whose registry
+mixes shareable knowledge with internal projects can serve
+`ukp serve --select a,b,c` — one port for exactly those endpoints; everything
+the door does not select behaves as if it did not exist (discovery, routes,
+and 404 rosters alike).
 
 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
@@ -214,6 +254,36 @@ registry), Caddy and Tailscale fronting, the certificate pinning lifecycle,
 and the hardening posture — lives in the
 [deployment guide](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md).
 
+## Security
+
+UKP is local-first: nothing listens on the network until you run
+`ukp serve`. When you do, the surface is deny-by-default — serving beyond
+loopback without a credential is refused, and anonymous serving is an
+explicit flag that only works on loopback. Credentials come in two forms:
+the `UKP_SERVE_TOKEN` env token (full power, takes precedence while set)
+and labeled keys in the 0600 `~/.ukp/tokens` file (hash-only storage,
+required per-key scopes, revocation by deleting the line — effective on
+the next request). Transport is `https://`, pinned
+automatically at registration (a certificate that renews on the same key
+re-pins silently; a different key hard-blocks with both fingerprints), or
+`ssh://`, where SSH carries both encryption and authentication. A
+`--select` door neither routes, declares, nor lists unselected endpoints —
+excluded and unknown names return byte-identical 404s, and a scoped key's
+out-of-scope endpoints answer the same way.
+
+Accepted tradeoffs, disclosed rather than hidden: tokens are long-lived
+static bearer secrets stored client-side in the 0600 registry file or an
+environment variable (the same tradeoff as `~/.aws/credentials`); the
+Windows door generator (`ukp serve --print-task`) embeds the token in a
+0600 `start-door.cmd` it never prints; identity pinning is
+trust-on-first-use (an SSH-style first-connect window). Hardening
+guidance — token strength, reverse proxies and their same-machine
+blind spot, firewalls — is in the
+[deployment guide](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md).
+
+Found something? Report it privately — see [SECURITY.md](SECURITY.md);
+please don't use public issues for security reports.
+
 ## Not Yet
 
 - remote operation of `update`, and a formally specified network protocol
@@ -226,6 +296,8 @@ and the hardening posture — lives in the
 ## Documentation
 
 - [Remote deployment](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md) — serving endpoints across machines: the full guide.
+  Also ships inside the npm package (`docs/remote-deployment.md` in the
+  installed package); the other docs live in the GitHub repository.
 - [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/SECURITY.md

@@ -0,0 +1,69 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report privately using GitHub security advisories:
+
+https://github.com/CatheadOwl/ukp/security/advisories/new
+
+Please do not open public issues for security reports. We follow
+coordinated vulnerability disclosure (the CERT process, with the 90-day
+convention as the default clock) and credit reporters unless they prefer
+to stay anonymous. Good-faith research on your own deployments is welcome.
+
+## Supported versions
+
+Only the latest published release line receives security fixes.
+
+## Scope
+
+In scope:
+
+- the `ukp` CLI runtime: local capability commands, `ukp serve`
+  (transport, authentication, TLS identity, door routing), the generated
+  door artifacts (`ukp serve --print-task`), and credential handling on
+  consumer machines;
+- the published package supply chain (npm tarball, GitHub repository).
+
+Out of scope:
+
+- hardening of your own host, SSH daemon, or reverse proxy — deployment
+  guidance exists, but operator-side misconfiguration is not a UKP
+  vulnerability;
+- private working materials that are not part of the published package.
+
+## Posture summary
+
+- Local-first: no network listener exists until you run `ukp serve`.
+- Deny-by-default serving: serving beyond loopback without
+  `UKP_SERVE_TOKEN` is refused; anonymous serving is an explicit flag and
+  loopback-only.
+- Transport: `https://` with registration-time pinning (self-signed
+  certificates are pinned by SPKI; a renewal on the same key re-pins
+  transparently, a different key hard-blocks) or `ssh://`, where SSH
+  carries both encryption and authentication.
+- Door scoping: a `--select` door neither routes, declares, nor lists
+  unselected endpoints; excluded and unknown names return byte-identical
+  404s.
+
+Deployment hardening (token strength, reverse proxies, firewalls,
+systemd) is covered in the
+[deployment guide](https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md).
+
+## Known, accepted tradeoffs
+
+Disclosed rather than hidden; each has a documented trigger for change:
+
+- Tokens are long-lived static bearer secrets. OAuth flows are deferred
+  until a multi-tenant or hosted scenario exists.
+- Read and write use the same token today; separation becomes mandatory
+  with the first remote content-write capability.
+- Client-side tokens live in the 0600 registry file or an environment
+  variable, in plaintext — the same tradeoff as `~/.aws/credentials`.
+- The Windows door artifact embeds the token in a 0600 `start-door.cmd`
+  and never prints it; a file that ever left the machine burns the token.
+- Identity pinning is trust-on-first-use, with the SSH-style
+  first-connect window that implies.
+- npm provenance attestations prove where and how a package was built,
+  not that the code is safe — verify with `npm audit signatures` and
+  treat provenance as one signal among several.

package/bin/ukp.js

@@ -56,28 +56,52 @@ function bunCandidates() {
   return candidates;
 }
 
-function fail(detail) {
+function fail(detail, hint = "") {
   process.stderr.write(
     "ukp: no bun executable found (" + detail + ").\n"
       + "ukp runs on bun — install it (https://bun.sh), or point UKP_BUN at the\n"
       + "bun executable. Standard install locations (~/.bun/bin and the npm\n"
-      + "global prefix) are checked before PATH.\n",
+      + "global prefix) are checked before PATH.\n"
+      + hint,
   );
   process.exit(1);
 }
 
+/** Windows-only diagnosis for a UKP_BUN that the user's shell accepts but
+ * existsSync rejects: name the shape mismatch instead of implying the file
+ * is absent. Two real shapes (0.3.0 release review): Git Bash converts an
+ * exported MSYS path (/c/.../bun) to a native form WITHOUT the .exe
+ * extension before this launcher sees it, so the .exe sibling exists while
+ * the named path does not; and a variable set outside a converting shell
+ * (cmd/PowerShell) reaches us as the raw /c/... or /cygdrive/... form,
+ * which Windows file APIs cannot resolve at all. */
+function ukpBunHint() {
+  const value = process.env.UKP_BUN;
+  if (!isWindows || typeof value !== "string") return "";
+  if (/^\/(?:[a-z]|cygdrive\/[a-z])\//i.test(value)) {
+    return "ukp: UKP_BUN looks like an MSYS-style path; Windows needs a native "
+      + "form like C:/path/to/bun.exe\n";
+  }
+  if (!/\.exe$/i.test(value) && existsSync(value + ".exe")) {
+    return "ukp: UKP_BUN omits the .exe extension (the executable sits next to "
+      + "it); use its full name, e.g. C:/path/to/bun.exe\n";
+  }
+  return "";
+}
+
 const bunPath = bunCandidates().find((candidate) => existsSync(candidate));
 if (bunPath === undefined) {
-  fail("looked at UKP_BUN, the standard install locations, and PATH");
+  fail("looked at UKP_BUN, the standard install locations, and PATH", ukpBunHint());
 }
 
 // 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
+// stdout/stderr keep their real TTY identity (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.
+// degraded TTY detection (the third dogfood round: progress frames
+// silently skipped while a direct run on the same console had them). 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));

package/docs/remote-deployment.md

@@ -1,3 +1,7 @@
+---
+description: Operational recipes for serving UKP endpoints remotely — ssh wake, native TLS, Windows resident door, socket activation, fronting proxies, scoped keys, and hardening posture
+---
+
 # Remote deployment
 
 Operational guide for exposing UKP endpoints over the network. For the
@@ -28,6 +32,17 @@ 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).
 
+The complete route list (ukp-remote v1) — what a client or a fronting proxy's
+path allowlist must account for: `GET /.well-known/ukp.json` (the public
+discovery document — the door's roster document in host door mode, where each
+endpoint also serves its own at `/e/<name>/.well-known/ukp.json`), the read
+face — `POST /v1/search`, `GET /v1/read`, `GET /v1/nav`, `GET /v1/rg` (each
+prefixed `/e/<name>` at a door) — and the one write route, `PUT
+/v1/propose/<id>` (`PUT /e/<name>/v1/propose/<id>` at a door): the proposal
+upsert. Propose needs the endpoint to declare the capability, and a scoped
+key must carry that endpoint at `rw` (`ro` keys reach the read face only —
+see Scoped keys below).
+
 ## Via SSH (two personal machines — zero extra components, zero ceremony)
 
 The `ssh://` URL scheme makes the transport transparent AND wakes the door
@@ -80,9 +95,12 @@ 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
+`--tls` self-signs on first start (identity = keypair, persisted in the
+machine home beside the host registry — `~/.ukp/tls/<endpoint-name>/` for a
+single endpoint, `~/.ukp/tls/` for a host door; SAN covers the host's
+addresses, so the identity never travels with the knowledge folder and a
+re-cloned endpoint on the same host keeps its pin). Clients pin the
+certificate automatically at registration — same command as any other
 remote, no flags added:
 
 ```bash
@@ -115,6 +133,57 @@ only grows: the re-sign keeps everything the certificate already carried
 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.
 
+## Scoped keys (second machines, agents — labeled, revocable)
+
+`UKP_SERVE_TOKEN` is the full-power shortcut: any listed token reaches every
+endpoint and the write face. When you hand access to a second machine or an
+agent, issue a **labeled, scoped key** instead — the issuance face is a serve
+subcommand, and the credential store is a plain file you can audit:
+
+```bash
+# ON THE HOST (run without UKP_SERVE_TOKEN set — while the env token is
+# present it takes precedence and the file is not consulted at all):
+ukp serve token add liku "notes:ro,cad:rw"
+#   issued key for 'liku' (scopes: notes:ro,cad:rw)
+#     ukp_liku_3f9c...TQ  <- the raw key, shown ONCE, never stored
+# stored in ~/.ukp/tokens (0600, hash-only)...
+
+# serve the door with NO env token — the key file arms the gate:
+ukp serve --host 0.0.0.0 --tls
+
+# consumer machine registers with the raw key as the token:
+ukp register --url https://<ip>:8570 --token ukp_liku_...
+```
+
+How the pieces behave:
+
+- **Scopes** are `name:ro|rw`, comma-separated (Docker-registry style); full
+  power is the explicit `*:rw` — a key with no scopes is a usage error, not a
+  wildcard. `rw` adds the propose route; `ro` keys get read/search/nav/rg
+  only. An endpoint outside the key's scope answers exactly like a name that
+  does not exist (same 404, same roster) — the key cannot even learn what it
+  cannot see.
+- **The file** is `~/.ukp/tokens`, one line per key (`label  key-id  sha256$
+  hash  scopes`), 0600, hash-only — a leaked file is not a leaked credential.
+  On POSIX, group/other permissions make the file unusable (machine refusal,
+  OpenSSH-style); Windows relies on the %USERPROFILE% ACLs instead.
+- **Revocation is deleting the line.** `ukp serve token revoke <label>`
+  removes every key carrying that label; the running door re-reads the file
+  on every request, so the next call is a 401 — no restart, no deploy step.
+  Hand-editing (deleting or `#`-commenting a line) works too.
+- **Rotation** is zero-downtime: `token add` with an existing label keeps the
+  old key active; hand out the new one, then revoke the label when the old
+  key's last consumer has switched. `ukp serve token list` shows labels, key
+  ids, and scopes (never hashes).
+- **Chain order**: while `UKP_SERVE_TOKEN` is set, the env token wins and the
+  file is ignored — the env is the shortcut form of the same gate (the same
+  order as `AWS_*` env vars over `~/.aws/credentials`, or `GH_TOKEN` over the
+  stored gh login). An env var set to an empty value counts as unset.
+
+The Windows resident form (`--print-task --write`) interpolates the env token
+into `start-door.cmd`; a file-key door instead wants the cmd's `set
+"UKP_SERVE_TOKEN=..."` line removed so the key file arms the gate.
+
 ## Windows host (https — resident form)
 
 Windows has no socket-activation equivalent, so the https path on a
@@ -123,12 +192,23 @@ 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
+host with a plain user-level install; the task recipe and the log
+ownership were re-verified end to end on 2026-09-23 (unelevated
+per-user registration, no execution time limit, whole-tree restart).
+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:
+and the pitfalls the verification run caught. A fast path exists for the
+two file artifacts: `ukp serve --print-task --write ...` writes
+`start-door.cmd` (token interpolated from your `UKP_SERVE_TOKEN` — never
+displayed) and the hidden launcher straight into `%USERPROFILE%\.ukp\`,
+CRLF by construction; existing files are never overwritten (manual edits
+— a PATH patch, say — are safe; regeneration means removing the old files
+first, as the removal section prescribes). The task-registration and
+firewall steps stay on stdout for you to run; the print-only form remains
+the full playbook (its Notes and the removal section):
 
 1. Install the usual way (bun's official installer + `npm i -g
    @catheadowl/ukp` — the npm shim needs bun on PATH, both land in
@@ -143,8 +223,11 @@ and the pitfalls the verification run caught:
    -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 **no redirect on the serve line** — door.log is owned solely by
+   the vbs launcher's outer redirect; a second redirect here deadlocks
+   the nested append-open and the door never starts. 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
@@ -152,11 +235,16 @@ and the pitfalls the verification run caught:
    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.
+6. Scheduled task — register from a **plain PowerShell shell** (no
+   elevation needed: a per-user logon trigger is the OneDrive/Teams-class
+   autostart path; a machine-level logon trigger or another user's
+   session still needs the elevated schtasks route). Use the
+   `Register-ScheduledTask` block `ukp serve --print-task` prints —
+   per-user `AtLogOn -User` trigger, battery flags, `IgnoreNew`, and
+   deliberately **no execution time limit**
+   (`-ExecutionTimeLimit ([TimeSpan]::Zero)`). Then the firewall rule
+   for the port (that one does need an elevated shell), and
+   `Start-ScheduledTask -TaskName ukp-door` to start now.
 7. Client: `ukp register --url https://<host>:8570 --token <token>` —
    TOFU pins the certificate; re-registering refreshes the pin.
 
@@ -168,16 +256,75 @@ Pitfalls the verification run caught:
 - 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.
+  `Start-ScheduledTask -TaskName ukp-door`. 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.)
+- **The 72-hour default**: a task without an explicit execution time
+  limit is stopped by Task Scheduler 72 hours after it starts — for a
+  resident door that is a silent kill (no window, no log line). The
+  recipe pins `-ExecutionTimeLimit ([TimeSpan]::Zero)` (PT0S in the task
+  XML); keep it when editing the task by hand.
+- To restart the door by hand (new token, ukp upgrade, new cert): kill
+  the **launcher root**, not just the serve leaf — `taskkill /PID
+  <wscript-pid> /T /F` on the `wscript.exe` running
+  `start-door-hidden.vbs`, then `Start-ScheduledTask -TaskName
+  ukp-door`. A leaf-only kill leaves the launcher's bounded retry to
+  re-grab the port within 30 seconds, racing the manual start (which
+  `IgnoreNew` turns into a no-op while the old launcher lives); the
+  scheduler's End-Task does not reliably kill the tree either. Each
+  door has its own wscript — in PowerShell, `Get-CimInstance
+  Win32_Process -Filter "Name='wscript.exe'" | Select-Object
+  ProcessId,CommandLine` and match the vbs name.
+- **Git Bash path conversion**: MSYS rewrites slash-style arguments into
+  Git paths (`taskkill /PID …` fails with a misleading
+  Invalid-argument error that reads like a permission problem). Prefix
+  such commands with `MSYS_NO_PATHCONV=1`.
+- **Do not edit start-door.cmd while the door runs**: cmd.exe resumes
+  reading a running batch file at a stale byte offset, so an in-place
+  edit above the current line makes it execute garbled fragments when
+  the current command returns (observed live: a mid-comment `a` ran as
+  a command). Stop the door first, edit, then restart.
 - `rg` on the host is the host's business — no ripgrep installed means
   the remote `rg` capability reports unavailable (everything else works).
 
+`ukp diagnose --door` is the read-only health check for this resident form:
+for every door it reports the task state, the wscript->cmd->bun process tree,
+the port (and who holds it), and the door.log tail — and exits 1 when a door
+is down (a host with no doors is healthy). Each finding names its repair;
+removal and restart moves live in the `ukp serve --print-task` §5 checklist
+(the three-level teardown below) and the pitfalls above.
+
+To remove the door — the inverse of steps 4–0, in three levels (stopping
+is not disabling, and disabling is not erasing; `ukp serve --print-task`
+prints this checklist as its §5):
+
+1. **Stop now**: `taskkill /PID <wscript-pid> /T /F` on the launcher
+   root (same lookup as the restart pitfall above). With the task still
+   registered, the next logon brings the door back.
+2. **Stop for good**:
+   `Unregister-ScheduledTask -TaskName ukp-door -Confirm:$false` from a
+   plain shell — the same zero-elevation path as registering it. The
+   cmdlet confirms by default (hence the flag), and unregistering does
+   **not** stop a running instance: the kill in step 1 is not optional.
+3. **Erase everything**: `netsh advfirewall firewall delete rule
+   name="ukp-door"` (the elevated shell again), then delete
+   `%USERPROFILE%\.ukp\start-door.cmd` (**it carries the token in
+   plaintext** — deleting it destroys this copy; if it ever left the
+   machine, treat the token as burned), `start-door-hidden.vbs`, and
+   `door.log`, plus the certificate material: your `--tls-cert` /
+   `--tls-key` paths, or — with `--tls` — the self-signed identity beside
+   the host registry: `%USERPROFILE%\.ukp\tls\<endpoint-name>\` for a
+   single-endpoint door, `%USERPROFILE%\.ukp\tls\` for a host door (it
+   never lives inside the knowledge folder, so git or cloud sync cannot
+   carry the private key out; `ukp unregister` leaves it in place on
+   purpose — a re-registered endpoint keeps its pin — so delete it by
+   hand when you are done). The endpoints stay registered
+   on the host for local use — `ukp unregister --endpoint <name>` per
+   endpoint only if you are done with them; and every consumer that
+   registered holds the token in plaintext in its own registry —
+   `ukp unregister --endpoint <name>` there too.
+
 ## Socket activation (Linux — no resident process on the https path either)
 
 systemd can hold the listening port itself and spawn the door on first
@@ -236,6 +383,15 @@ Notes:
   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.
+- **Removing the door** (the setup block's inverse — the same three
+  levels as the Windows teardown above, in one gesture):
+  `systemctl --user disable --now ukp-door.socket` (a door still
+  running stops with `systemctl --user stop ukp-door.service`), then
+  delete the two unit files and the token env file, and
+  `rm -rf ~/.ukp/tls` if you are done with the self-signed identity;
+  `loginctl disable-linger "$USER"` too if nothing else on the host
+  needs it. Nothing else is resident — consumer and host registry
+  bindings come off exactly as on the Windows side.
 
 ## Host door (one host, many endpoints — one gesture, zero tokens)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"
@@ -18,10 +18,12 @@
   "keywords": [
     "knowledge",
     "cli",
-    "bun",
-    "qmd",
     "search",
-    "agent"
+    "agent",
+    "ai-agents",
+    "knowledge-base",
+    "local-first",
+    "self-hosted"
   ],
   "bin": {
     "ukp": "bin/ukp.js"
@@ -30,16 +32,19 @@
     "bin",
     "src",
     "docs",
+    "skills/ukp/SKILL.md",
     "README.md",
-    "LICENSE",
-    "package.json"
+    "SECURITY.md",
+    "LICENSE"
   ],
   "scripts": {
     "dev": "bun run src/cli.ts",
+    "prepack": "bun ./scripts/pack-audit.mjs",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@any-nav/scan": "^0.2.0",
     "commander": "15.0.0",
     "smol-toml": "1.7.1",
     "zod": "4.4.3"