@hypabolic/crossbar 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,168 @@
+# Crossbar — Architecture & Frozen Contract (Phase 1)
+
+**Status:** Interface frozen pending sign-off · **Date:** 2026-06-21 · Companion to `RESEARCH.md`,
+`CAPABILITY-MATRIX.md`. The contract under `src/core/` is the **single source of truth**. Phase 2
+fan-out targets it and nothing else. Typechecked against Pi `0.79.9` (`tsc --noEmit` → clean).
+
+```
+discovery engine ──┐
+                   ├─► server registry ──► provider shim ──► pi.registerProvider(...)
+adapters[kind] ────┘         │                                         │
+   (BackendAdapter)          └─► crossbar.json (metadata)              └─► models appear in /model & /login
+                             secrets ─► Pi authStorage (auth.json,0600)
+onboarding overlay  ─────────────────────────────────────────────────► /crossbar (alias /local)
+loaded-model widget ─────────────────────────────────────────────────► ctx.ui.setStatus / setWidget
+```
+
+## 1. Module layout (Phase 2 fills these)
+
+```
+src/
+  index.ts                  # extension entry: registers /crossbar, wires session_start (STUB today)
+  core/                     # FROZEN CONTRACT — do not change without bumping CONTRACT_VERSION
+    capability.ts           # Capability enum, AuthMode, BackendKind
+    types.ts                # Probe, DiscoveredServer, ModelDescriptor, LoadedState, ServerRecord, PiModelEntry
+    backend-adapter.ts      # BackendAdapter interface + capability guards
+    index.ts                # re-exports
+  adapters/                 # one file per kind, each `implements BackendAdapter`
+    ollama.ts lmstudio.ts llamacpp.ts llamaswap.ts vllm.ts
+    openai.ts anthropic.ts generic.ts        # generic = openai-generic fallback
+    index.ts                # ADAPTERS registry (kind → instance), probe-order export
+  discovery/
+    probe.ts                # Probe impl: fetch + timeout + auth-header injection + redaction
+    engine.ts               # port sweep (localhost default), fingerprint dispatch, dedupe by origin
+  registry/
+    registry.ts             # ServerRecord CRUD, health poll, model cache, in-memory state
+    persistence.ts          # crossbar.json read/write via getAgentDir(); secrets via authStorage
+    ids.ts                  # stable provider-id generation (kind + host + port)
+  shim/
+    provider-shim.ts        # ServerRecord + ModelDescriptor[] → pi.registerProvider / unregisterProvider
+  ui/
+    onboarding.ts           # ctx.ui.custom overlay: discovered list + manual add + test + pick + save
+    loaded-widget.ts        # setStatus/setWidget live "currently loaded" indicator
+    theme.ts                # getSelectListTheme wrapper + token helpers
+tests/
+  conformance/              # runs EVERY adapter against the contract using fixtures
+  fixtures/<kind>/          # captured HTTP responses per backend (+ edge cases)
+```
+
+## 2. BackendAdapter contract (frozen)
+
+See `src/core/backend-adapter.ts`. Invariants every adapter MUST honour — the conformance suite checks
+each one:
+
+1. **Stateless & I/O-free.** No instance state; never call `fetch` directly — only the injected `Probe`.
+2. **Honest capabilities.** An optional method (`introspectLoaded`/`switchModel`/`loadUnload`/`health`)
+   is defined **iff** the matching `Capability` is in `capabilities`. Orchestrator uses the `canX`
+   guards, never feature-sniffs.
+3. **`fingerprint` is unauth & cheap.** Uses only public metadata endpoints; returns `null` fast for
+   non-matches; sets a calibrated `confidence` (exact unique-path match → ~1.0; generic `/v1/models`
+   shape → ~0.3). Cloud adapters return `null`.
+4. **`listModels` filters embeddings** out of chat registration (keeps them only if flagged).
+5. **`toPiModel` owns Pi mapping.** Sets `api`, `compat` quirk flags, `cost` zeros for local, and
+   conservative defaults: `contextWindow` from backend or a safe fallback, `input` defaults `["text"]`.
+6. **`switchModel` confirms or throws.** Must surface server-down-mid-switch and model-not-available as
+   rejections, not silent success.
+7. **No secret leakage.** Adapters receive `ServerCredential` but must never log/serialize `apiKey`.
+
+`CONTRACT_VERSION = 1`. Any breaking change bumps it; registry asserts adapters match.
+
+## 3. Provider-registration shim (`shim/provider-shim.ts`)
+
+The ONLY bridge to Pi. For each enabled, healthy server:
+
+```
+register(record):
+  adapter   = ADAPTERS[record.kind]
+  cred      = resolveCredential(record)          # apiKey from authStorage, or {mode:"none"}
+  models    = registry.cachedModels(record)      # from listModels, refreshed on poll
+  pi.registerProvider(record.id, {
+    name:    record.label,
+    baseUrl: adapter.inferenceBaseUrl(server),
+    apiKey:  cred.mode === "apiKey" ? `$${ENV_FOR(record.id)}` : undefined,  # see secret note
+    api:     adapter.piApi,
+    models:  models.map(m => adapter.toPiModel(server, m)),
+  })
+```
+
+- Re-registration on model-list change = `unregisterProvider(id)` then `registerProvider(id, ...)`.
+- Switching the served model updates the registered `models[]` (and the loaded widget), then
+  optionally `pi.setModel(...)` to point the agent at it.
+- **Secret handling:** keys are stored via `authStorage.set(record.id, {type:"api_key", key})`. The shim
+  passes the key to Pi using Pi's own indirection (env/`!cmd`/literal) — never inlining the plaintext
+  into long-lived structures. Exact mechanism (env handoff vs literal at register time) is the first
+  thing Phase 2 verifies against `auth-storage.ts`; default to letting Pi resolve from `auth.json`.
+
+## 4. Server registry & persistence
+
+- **State:** `ServerRecord[]` in memory; mirror to `getAgentDir()/crossbar.json` (`CrossbarConfigFile`,
+  `version:1`). Non-secret only — never write `apiKey` here.
+- **Secrets:** `ctx.modelRegistry.authStorage` (`auth.json`, `0600`), keyed by `record.id`.
+- **IDs:** stable, derived from `kind + host + port` (e.g. `crossbar-ollama-localhost-11434`) so a server
+  keeps its id and key across restarts. (`registry/ids.ts`)
+- **Health poll:** interval loop started in `session_start`, stopped in `session_shutdown` (per Pi's
+  long-lived-resource rule). Updates health, refreshes model cache, drives the loaded widget. On
+  `unreachable`, keep the registration but mark degraded; show last-known models/loaded.
+- **Lifecycle:** `session_start` → load `crossbar.json` → (if enabled) run auto-discovery →
+  register all enabled+reachable servers → start poll. `session_shutdown` → stop poll.
+
+## 5. Discovery engine (`discovery/`)
+
+- **Default scope: localhost only.** Probe ports `[11434,1234,8080,8000,5000,5001,1337]` on `127.0.0.1`.
+  LAN host-range probing is opt-in via `CrossbarSettings.lanDiscovery` (no mDNS exists for any backend).
+- **Per origin:** run the probe-order fingerprint chain (CAPABILITY-MATRIX §"probe order"); pick the
+  highest-confidence adapter; fall back to `openai-generic` when only `/v1/models` matches.
+- **Short timeouts** (e.g. 600ms) and bounded concurrency; a refused port returns `status:0` fast.
+- **Key-vs-no-auth:** probe public metadata first; a `401` on `/v1/chat/completions` with `200` on
+  `/v1/models` ⇒ "running but keyed" → onboarding prompts for a key.
+
+## 6. Onboarding flow (`ui/onboarding.ts`) — `/crossbar`
+
+Overlay via `ctx.ui.custom<T>(factory, { overlay:true, overlayOptions })` using `SelectList` +
+`Container`/`Text`/`DynamicBorder`, themed with `getSelectListTheme` / `theme.fg`:
+
+```
+/crossbar →
+  [Discovered]  Ollama (localhost:11434)  ✓ healthy
+                LM Studio (localhost:1234) ✓ healthy
+  [Manual add]  + Add server…  → input URL → optional API key (no-auth toggle) → Test connection
+  → on select/add: fingerprint → health → listModels → pick default model → save (registry + auth.json)
+```
+
+- Capability-driven: hide "switch model" when `!supports(SwitchModel)`; show load/unload only when
+  `LoadUnload`; show a no-auth toggle always, key entry only when needed.
+- Test-connection uses the same `Probe` + adapter `health`/`listModels` as production.
+- Cloud keys (OpenAI/Anthropic) can still be entered via stock `/login`; Crossbar's registered models
+  surface in `/model` regardless.
+
+## 7. Loaded-model widget (`ui/loaded-widget.ts`)
+
+- `ctx.ui.setStatus("crossbar-loaded", theme.fg("accent", "● <server>:<model>"))`, refreshed from the
+  health poll's `introspectLoaded` and from the `model_select` event.
+- When `!supports(IntrospectLoaded)` (OpenAI, Anthropic, vLLM, llamafile) → show **last-known**
+  selection from `ServerRecord.lastKnownLoaded`; never claim live state we can't read (`source` field).
+
+## 8. Conformance suite (`tests/conformance/`)
+
+One parameterized suite runs against **every** adapter using a fake `Probe` backed by per-backend
+fixtures. Required cases:
+
+- fingerprint: positive, negative (other backend's response), ambiguous-port disambiguation.
+- listModels: normal, empty, embeddings filtered, missing-caps defaults applied.
+- introspectLoaded / switchModel / loadUnload: present ⇔ capability; success + edge cases —
+  **auth failure (401), server-down-mid-switch, model-not-loaded, streaming cutoff**.
+- toPiModel: output validates against Pi's `ProviderConfig["models"]` element shape (compile + runtime).
+- capability honesty: every optional method present ⇔ its `Capability` is declared.
+
+Discovery validated on **zero / one / many** servers (Phase 3 hardening).
+
+## 9. Phase 2 waves (contract-driven fan-out — nothing starts before sign-off)
+
+- **Wave A (parallel):** conformance harness + fixtures · discovery engine + probe · registry +
+  persistence + id gen.
+- **Wave B (parallel, one adapter per agent):** ollama · lmstudio · llamacpp+llamaswap · vllm ·
+  openai+anthropic · generic. Each lands with its fixtures and passes conformance before merge.
+- **Wave C:** provider shim + `/crossbar` onboarding overlay + loaded widget; full integration; green
+  conformance across all adapters.
+
+After each wave: reconvene, integrate, run conformance against every adapter.

package/CAPABILITY-MATRIX.md

@@ -0,0 +1,49 @@
+# Crossbar — Capability Matrix (draft, Phase 0)
+
+**Date:** 2026-06-21 · companion to `RESEARCH.md`. Values: ✅ yes · ◐ partial/conditional · ❌ no.
+Backend endpoints are **[WEB]** — confirm live per adapter. `pi api` = which built-in Pi API type the
+adapter registers under (`oai` = `openai-completions`, `ant` = `anthropic-messages`).
+
+| Backend | port | pi api | listModels | introspectLoaded | switchModel | loadUnload | auth | health | perModelCaps | streaming | discovery fingerprint |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| **Ollama** | 11434 | oai | ✅ `/api/tags`,`/v1/models` | ✅ `/api/ps` | ✅ implicit (request id) | ✅ `keep_alive:0` | ◐ none local | ✅ `GET /` text | ✅ `/api/show` caps + ctx | ✅ | `GET /` → `Ollama is running` |
+| **LM Studio** | 1234 | oai | ✅ `/api/v0/models`,`/v1/models` | ✅ `state` field | ✅ JIT + `/api/v1/models/load` | ✅ load/unload + `lms` | ◐ Bearer, none default | ◐ infer 200 | ✅ type+`max_context_length` | ✅ | `/api/v0/models` w/ `state`,`compatibility_type` |
+| **llama-server** | 8080 | oai | ✅ `/v1/models` | ◐ `/props`,`/slots` (single) | ❌ (1/instance) | ❌ classic | ◐ none / `--api-key` | ✅ `/health` | ◐ ctx via `/props`,`meta` | ✅ | `/props` w/ `default_generation_settings`+`build_info` |
+| **llama-swap** | 8080 | oai/ant | ✅ `/v1/models` (all config) | ✅ `/running` | ✅ via `model` → restart upstream | ✅ `/api/models/unload`, ttl | ◐ optional multi-scheme | ✅ `/health`→OK | ◐ via upstream | ✅ | `/` → `/ui/`; `/running`,`/upstream/{model}` |
+| **vLLM** | 8000 | oai | ✅ `/v1/models` | ◐ `/is_sleeping` (dev) | ❌ base · ◐ LoRA | ◐ sleep/wake + LoRA | ◐ none / `--api-key` | ✅ `/health` | ◐ `max_model_len` only | ✅ | `/version` + `/metrics` `vllm:` + `owned_by:"vllm"` |
+| **OpenAI** | cloud | oai | ✅ `/v1/models` | ❌ | ✅ (pick id) | ❌ managed | ✅ Bearer | ❌ (status page) | ❌ (static table needed) | ✅ | n/a (configured, not probed) |
+| **Anthropic** | cloud | ant | ✅ `/v1/models` | ❌ | ✅ (pick id) | ❌ managed | ✅ x-api-key+version | ❌ | ✅ caps + `max_input_tokens` | ✅ | n/a |
+| **TabbyAPI** | 5000 | oai | ✅ `/v1/model/list` | ✅ `/v1/model` | ✅ load | ✅ `/v1/model/{load,unload}` | ✅ x-api-key/x-admin-key | ◐ | ◐ | ✅ | `/v1/model/*` + `x-admin-key` |
+| **KoboldCpp** | 5001 | oai | ✅ `/v1/models` | ✅ `/api/v1/model` | ❌ (1 GGUF) | ❌ | ◐ `--password` | ✅ `/api/extra/version` | ◐ | ✅ | `/api/extra/version`→`{"result":"KoboldCpp"}` |
+| **oobabooga** | 5000 | oai | ✅ `/v1/models` | ✅ `/v1/internal/model/info` | ✅ load | ✅ `/v1/internal/model/{load,unload}` | ◐ `--api-key` | ◐ | ◐ | ✅ | `/v1/internal/*` namespace |
+| **Jan** | 1337 | oai | ✅ `/v1/models` | ◐ | ◐ engine | ◐ engine | ◐ Bearer | ❌ | ◐ | ✅ | weak (log line) |
+| **llamafile** | 8080 | oai | ✅ `/v1/models` | ◐ `/props` | ❌ | ❌ | ◐ `--api-key` | ✅ `/health` | ◐ via `/props` | ✅ | `/props` w/ non-`bNNNN` build_info |
+| **generic OpenAI-compat** | varies | oai | ✅ `/v1/models` | ❌ | ❌ | ❌ | ◐ optional Bearer | ◐ | ◐ | ✅ | anything serving `/v1/models` (fallback) |
+
+## Capability-driven UX rules (derived)
+
+- **switchModel ❌** (llama-server, vLLM-base, KoboldCpp, llamafile) → hide/disable the "switch model"
+  action; offer "restart server with model X" guidance only where applicable. Suggest llama-swap when a
+  bare llama-server is detected (it unlocks switching).
+- **introspectLoaded ❌/◐** (OpenAI, Anthropic, vLLM, llamafile) → show **last-known** selected model
+  rather than a live "loaded" indicator; never claim live state we can't read.
+- **perModelCaps ❌** (OpenAI) / ◐ (most local) → fall back to a maintained static capability table and
+  conservative defaults (`contextWindow` from `/props`/`max_*` when present, else a safe default).
+- **auth ◐** → onboarding offers a no-auth toggle; probe public metadata endpoints first, only require a
+  key for inference (a `401` on `/v1/chat/completions` but `200` on `/v1/models` ⇒ "running but keyed").
+- **loadUnload ✅** (Ollama, LM Studio, TabbyAPI, oobabooga, llama-swap) → expose explicit load/unload;
+  elsewhere degrade to implicit-on-use (Ollama) or nothing.
+
+## Discovery probe order (cheapest/most-specific first)
+
+1. `GET /` → `Ollama is running` ⇒ Ollama · redirect `/ui/` ⇒ llama-swap
+2. `GET /api/extra/version` → `{"result":"KoboldCpp"}` ⇒ KoboldCpp
+3. `GET /api/v0/models` 200 w/ `state`/`compatibility_type` ⇒ LM Studio
+4. `GET /props` w/ `default_generation_settings`+`build_info` ⇒ llama-server / llamafile
+5. `GET /version` + `/metrics` `vllm:` ⇒ vLLM
+6. `GET /v1/models` shape: `owned_by:"vllm"`⇒vLLM · `meta.n_ctx_train`⇒llama.cpp ·
+   multiple models on :8080⇒llama-swap · `/v1/internal/*`⇒oobabooga · `/v1/model/*`⇒TabbyAPI ·
+   else ⇒ generic OpenAI-compat
+
+Default probe ports (localhost): `11434, 1234, 8080, 8000, 5000, 5001, 1337`. **No mDNS exists for any
+backend** → LAN discovery, if enabled, is active port-probing across host IPs (opt-in).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hypabolic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# Crossbar
+
+[![CI](https://github.com/Hypabolic/Crossbar/actions/workflows/ci.yml/badge.svg)](https://github.com/Hypabolic/Crossbar/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@hypabolic/crossbar)](https://www.npmjs.com/package/@hypabolic/crossbar)
+
+**The local/self-hosted inference connector Pi should have shipped with.**
+
+Crossbar is an extension for the [Pi coding agent](https://github.com/earendil-works/pi) that makes
+wiring Pi to *any* local or self-hosted model backend effortless — zero hand-edited JSON, all setup
+inside Pi's TUI, with auto-discovery, multi-server support, live "currently loaded" indicators, and
+in-place model switching.
+
+> Built by [Hypabolic](https://github.com/hypabolic).
+
+---
+
+## Why Crossbar
+
+Existing connectors stop short: manual config files, a single server at a time, Ollama-only discovery,
+or hardcoded model lists. Crossbar beats them on three axes:
+
+1. **Widest backend support** — Ollama, LM Studio, llama.cpp, llama-swap, vLLM, OpenAI, Anthropic, plus
+   a generic adapter for the OpenAI-compatible long tail (TabbyAPI, KoboldCpp, text-generation-webui,
+   Jan, llamafile, …).
+2. **Easiest onboarding** — `/crossbar` auto-discovers running servers on localhost and registers them.
+   No JSON. API-key *and* no-auth endpoints, with a connection test before you commit.
+3. **Highest-fidelity UX** — multiple simultaneous servers, a live loaded-model widget, and capability-
+   driven model switching that gracefully hides what a backend can't do.
+
+## Supported backends
+
+| Backend | Discover | Loaded indicator | Switch model | Load/Unload | Auth |
+|---|:--:|:--:|:--:|:--:|---|
+| **Ollama** | ✅ | ✅ live | ✅ implicit | ✅ | none (local) |
+| **LM Studio** | ✅ | ✅ live | ✅ JIT | ✅ | optional key |
+| **llama.cpp** (`llama-server`) | ✅ | ✅ (single) | ❌¹ | ❌ | optional key |
+| **llama-swap** | ✅ | ✅ live | ✅ proxy swap | ✅ | optional key |
+| **vLLM** | ✅ | last-known | ❌¹ | ❌ | optional key |
+| **OpenAI** | configured | — | pick model | — | API key |
+| **Anthropic** | configured | last-known | pick model | — | API key |
+| **Generic OpenAI-compatible** | ✅ (fallback) | last-known | ❌ | ❌ | optional key |
+
+¹ Single model per instance. Run **llama-swap** in front of `llama-server`/vLLM to unlock switching —
+Crossbar detects it automatically and prefers it.
+
+Full endpoint-level detail is in [`CAPABILITY-MATRIX.md`](./CAPABILITY-MATRIX.md); research notes and
+Pi-integration citations are in [`RESEARCH.md`](./RESEARCH.md) and [`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+## Install
+
+```bash
+# from npm
+pi install npm:@hypabolic/crossbar
+
+# or from git
+pi install git:github.com/hypabolic/crossbar
+
+# or a local checkout
+pi install /path/to/crossbar
+```
+
+Then start Pi and run `/crossbar`.
+
+## Usage
+
+- **`/crossbar`** (alias **`/local`**) — open the onboarding overlay: pick from auto-discovered servers
+  or add one manually (URL + optional API key / no-auth toggle), test the connection, choose a model,
+  and save.
+- **Auto-discovery** runs on session start: reachable no-auth servers on localhost are registered
+  automatically; keyed servers are surfaced with a prompt to add them.
+- Registered models appear in Pi's standard **`/model`** picker and `/login` provider list.
+- The **loaded-model widget** shows what's currently resident (`●` live via introspection, `◷` with a
+  `(last-known)` suffix where a backend can't report live state).
+
+LAN discovery (beyond localhost) is **off by default** — no backend advertises over mDNS, so Crossbar
+never scans your network unless you opt in.
+
+## How it works
+
+- **Discovery** probes localhost ports and fingerprints each server by response shape (e.g. Ollama's
+  `GET /` banner, LM Studio's `/api/v0/models` state, vLLM's `/version` + `owned_by`), preferring the
+  most specific match. The generic adapter is the low-confidence fallback.
+- **Registration** maps discovered models onto Pi's built-in `openai-completions` / `anthropic-messages`
+  providers via `pi.registerProvider` — Crossbar writes no streaming code for OpenAI-compatible servers.
+- **Persistence** keeps non-secret server metadata in `~/.pi/agent/crossbar.json`; **API keys live only
+  in Pi's `auth.json`** (mode `0600`), keyed by the server's provider id, exactly like Pi's own creds.
+
+## Security
+
+- API keys are **never** written to `crossbar.json`, never logged, and never inlined into a provider
+  config — Pi resolves them from `auth.json` at request time.
+- Discovery is localhost-only by default.
+- Crossbar adds no telemetry.
+
+## Development
+
+```bash
+npm install
+npm run check   # tsc --noEmit
+npm test        # vitest (conformance + unit + live-socket integration)
+```
+
+The `BackendAdapter` contract (`src/core/`) is the frozen boundary every adapter implements; the
+conformance suite (`tests/conformance/`) validates every adapter against it, and
+`tests/integration/` exercises the real discovery path over live sockets.
+
+### CI / releasing
+
+- **CI** (`.github/workflows/ci.yml`) runs `tsc --noEmit` + the full test suite on every push and PR
+  (Node 22 & 24).
+- **Releases** (`.github/workflows/release.yml`) publish to npm via **GitHub→npm OIDC trusted
+  publishing** — no tokens or secrets. [Provenance](https://docs.npmjs.com/generating-provenance-statements)
+  is attached automatically. Two ways:
+  1. **Manual** — GitHub → *Actions → Release → Run workflow* → choose `patch` / `minor` / `major`.
+     It bumps `package.json`, commits, tags `vX.Y.Z`, and publishes.
+  2. **Tag push** — `npm version patch && git push --follow-tags` locally.
+
+  **One-time setup:** on npmjs.com, add a **Trusted Publisher** for `@hypabolic/crossbar`
+  (*Package settings → Trusted Publisher → GitHub Actions*) pointing at repo **`Hypabolic/Crossbar`**
+  and workflow **`release.yml`**. The workflow authenticates through the OIDC `id-token` it already
+  requests — no `NPM_TOKEN` needed.
+
+<!-- TODO: add an onboarding demo GIF (docs/onboarding.gif) recorded against a live Ollama + LM Studio. -->
+
+## License
+
+[MIT](./LICENSE) © Hypabolic