@catheadowl/ukp 0.2.6 → 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
@@ -78,7 +87,8 @@ predictable scope, and a single command surface. Use UKP when:
   `[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
@@ -126,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
@@ -143,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. |
@@ -153,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:
 
@@ -181,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
@@ -199,6 +219,21 @@ 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
@@ -219,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
@@ -231,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
@@ -219,6 +288,13 @@ Pitfalls the verification run caught:
 - `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):
@@ -237,11 +313,13 @@ prints this checklist as its §5):
    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 identity in the served
-   folder's `.ukp\tls\` (single-endpoint door: *inside* the KB folder,
-   so git or cloud sync carries the private key out;
-   `ukp init service` drops a self-ignoring `.ukp\.gitignore` there) or
-   beside the host registry (host door). The endpoints stay registered
+   `--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 —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.2.6",
+  "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"

package/skills/ukp/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: ukp
+description: "ukp — a CLI tool for named knowledge endpoints(registered local or remote folders)"
+---
+
+# ukp
+
+A CLI tool for knowledge endpoints: register any local or remote folder
+as a named endpoint, then address knowledge by name through one stable
+command surface.
+
+## Entry
+
+Run `ukp --help` — the command surface teaches itself: grouped help,
+per-command `--help` for exact grammar, `ukp guide <topic>` for
+role-based walkthroughs, `ukp list` for the registered endpoints.
+
+## Handoff: ukp:// references
+
+Knowledge you got from ukp is handed off as
+`ukp://<endpoint>/<path>` — name-addressed, so folders can move while
+references stay valid. 
+
+`ukp read <uri>` opens one as-is, replayable in
+any session. The cross-repo `{name}:path` shorthand resolves the same
+way.
+
+## Writes: propose
+
+Endpoints are read-only by default. Changes go through `ukp propose` —
+an idempotent suggestion box (created / unchanged / updated; a revision
+bumps only on updated) that the endpoint owner adjudicates.