omnius 1.0.159 → 1.0.160

package/docs/rest/INDEX.md

@@ -0,0 +1,129 @@
+# Omnius REST API Docs
+
+This directory is the human-readable REST API reference for Omnius. It is meant to be explored incrementally by agents and humans.
+
+Canonical sources:
+
+- Runtime OpenAPI generator: `packages/cli/src/api/openapi.ts`
+- Live OpenAPI document: `GET /openapi.json`
+- Swagger UI: `GET /docs` or `GET /api/docs`
+- ReDoc: `GET /redoc`
+- AsyncAPI voicechat document: generated from `packages/cli/src/api/openapi.ts`
+
+## How To Explore
+
+Use this index first, then open the smallest relevant family file:
+
+| Need | Read |
+| --- | --- |
+| Quick commands and examples | `docs/rest/QUICKREF.md` |
+| Full maintained endpoint inventory | `docs/reference/rest-api.md` |
+| Auth, scopes, rate limits, API keys | `docs/rest/auth-and-scopes.md` |
+| Errors, pagination, ETags, request IDs | `docs/rest/errors-pagination-etags.md` |
+| OpenAPI and docs renderers | `docs/rest/openapi-source.md` |
+| Chat, realtime, OpenAI-compatible inference | `docs/rest/endpoints/chat.md` |
+| Agentic jobs and run lifecycle | `docs/rest/endpoints/run.md` |
+| Config, endpoints, keys, profiles, projects | `docs/rest/endpoints/config.md` |
+| Memory, sessions, context | `docs/rest/endpoints/memory.md` |
+| Skills and slash commands | `docs/rest/endpoints/skills.md` |
+| AIWG cascade loader | `docs/rest/endpoints/aiwg.md` |
+| Tools, MCP, code graph | `docs/rest/endpoints/tools.md` |
+| Events, metrics, usage, audit, system | `docs/rest/endpoints/events.md` |
+| Files | `docs/rest/endpoints/files.md` |
+| Voice, audio, vision, voicechat WebSocket | `docs/rest/endpoints/voice-vision.md` |
+| AIMS governance | `docs/rest/endpoints/aims.md` |
+| Curl examples | `docs/rest/examples/curl.md` |
+| OpenAI SDK examples | `docs/rest/examples/openai-sdk.md` |
+
+## Start The Daemon
+
+```bash
+omnius serve
+```
+
+Default base URL:
+
+```text
+http://127.0.0.1:11435
+```
+
+Bind a custom port:
+
+```bash
+omnius serve --port 9000
+```
+
+Bind from environment:
+
+```bash
+OMNIUS_HOST=0.0.0.0:11435 omnius serve
+```
+
+## Auth Model
+
+Local anonymous requests default to read behavior unless the runtime is configured for insecure loopback admin. Remote/shared deployments should use bearer keys.
+
+```bash
+OMNIUS_API_KEY="admin-secret" omnius serve
+OMNIUS_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
+```
+
+Scopes:
+
+- `read`: inspect models, health, usage, memory search, skills, tools metadata, events, and summaries.
+- `run`: submit tasks and invoke permitted run-scope tools.
+- `admin`: mutate config, keys, high-risk controls, and admin-only tools.
+
+## Common Conventions
+
+- Errors use RFC 7807-style Problem Details where implemented.
+- List endpoints use `{ "data": [...], "pagination": { "limit": 50, "offset": 0, "total": 0, "has_more": false } }` where implemented.
+- Cacheable GET responses may include `ETag`; send `If-None-Match` for conditional reads.
+- Responses include `X-API-Version` and `X-Request-ID` where the API middleware can attach them.
+- Use `Authorization: Bearer <key>` when auth is enabled.
+- Use `X-Request-ID` to correlate client logs with the daemon audit log.
+
+## Endpoint Families
+
+| Family | Representative endpoints |
+| --- | --- |
+| Health | `/health`, `/health/ready`, `/health/startup`, `/version`, `/metrics` |
+| Inference and chat | `/v1/models`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/chat`, `/v1/generate`, `/api/generate`, `/v1/chat/sessions`, `/v1/chat/check-in` |
+| AIWG | `/v1/aiwg`, `/v1/aiwg/frameworks`, `/v1/aiwg/skills`, `/v1/aiwg/use`, `/v1/aiwg/expand` |
+| Runs | `/v1/run`, `/v1/runs`, `/v1/runs/{id}`, `/v1/todos`, `/v1/todos/{session_id}` |
+| Config | `/v1/config`, `/v1/config/model`, `/v1/config/endpoint`, `/v1/config/endpoint/test`, `/v1/config/endpoint/history`, `/v1/share/generate` |
+| Metering and audit | `/v1/usage`, `/v1/audit`, `/v1/cost`, `/v1/system` |
+| Runtime keys | `/v1/keys`, `/v1/keys/{prefix}` |
+| Profiles | `/v1/profiles`, `/v1/profiles/{name}` |
+| Files | `/v1/files`, `/v1/files/read` |
+| Skills and commands | `/v1/skills`, `/v1/skills/{name}`, `/v1/commands`, `/v1/commands/{cmd}` |
+| MCP | `/v1/mcps`, `/v1/mcps/{name}`, `/v1/mcps/{name}/call` |
+| Tools | `/v1/tools`, `/v1/tools/{name}`, `/v1/tools/{name}/call`, `/v1/hooks`, `/v1/agents` |
+| Memory | `/v1/memory`, `/v1/memory/search`, `/v1/memory/write`, `/v1/memory/episodes`, `/v1/memory/failures` |
+| Events | `/v1/events` |
+| Sessions and context | `/v1/sessions`, `/v1/sessions/{id}`, `/v1/context`, `/v1/context/save`, `/v1/context/restore`, `/v1/context/compact` |
+| Nexus | `/v1/nexus/status`, `/v1/sponsors` |
+| Ollama pool | `/v1/ollama/pool/processes`, `/v1/ollama/pool/cleanup` |
+| Voice and audio | `/v1/voice/state`, `/v1/voice/models`, `/v1/voice/tts`, `/v1/audio/speech`, `/v1/voice/transcribe`, `/v1/audio/transcriptions`, `/v1/voicechat/ws` |
+| Vision | `/v1/vision/describe` |
+| Projects | `/v1/projects`, `/v1/projects/current`, `/v1/projects/switch`, `/v1/projects/register`, `/v1/projects/rename`, `/v1/projects/preferences` |
+| Code graph | `/v1/codegraph/snapshot`, `/v1/codegraph/events` |
+| Scheduled jobs | `/v1/scheduled`, `/v1/scheduled/all`, `/v1/scheduled/status`, `/v1/scheduled/kill`, `/v1/scheduled/fixup`, `/v1/scheduled/reconcile` |
+| Services and update | `/v1/services/systemd`, `/v1/update` |
+| AIMS | `/v1/aims`, `/v1/aims/policies`, `/v1/aims/roles`, `/v1/aims/resources`, `/v1/aims/impact-assessments`, `/v1/aims/lifecycle`, `/v1/aims/data-quality`, `/v1/aims/transparency`, `/v1/aims/usage`, `/v1/aims/suppliers`, `/v1/aims/incidents`, `/v1/aims/oversight`, `/v1/aims/decisions`, `/v1/aims/config-history` |
+
+## Realtime REST Flag
+
+`POST /v1/chat` and `POST /v1/chat/completions` accept:
+
+```json
+{
+  "realtime": true,
+  "realtime_options": {
+    "max_history_messages": 12,
+    "max_tokens": 160
+  }
+}
+```
+
+This applies Omnius realtime conversation mode before proxying to the configured backend. It is intended for ASR/TTS clients and short back-and-forth speech.

package/docs/rest/QUICKREF.md

@@ -0,0 +1,125 @@
+# Omnius REST Quick Reference
+
+Start:
+
+```bash
+omnius serve
+```
+
+Base:
+
+```text
+http://127.0.0.1:11435
+```
+
+Docs:
+
+```text
+GET /docs
+GET /api/docs
+GET /openapi.json
+GET /openapi.yaml
+GET /redoc
+```
+
+Auth header:
+
+```text
+Authorization: Bearer <key>
+```
+
+## Health
+
+```bash
+curl -s http://127.0.0.1:11435/health
+curl -s http://127.0.0.1:11435/health/ready
+curl -s http://127.0.0.1:11435/version
+```
+
+## Models
+
+```bash
+curl -s http://127.0.0.1:11435/v1/models
+```
+
+## Chat
+
+```bash
+curl -s http://127.0.0.1:11435/v1/chat \
+  -H 'content-type: application/json' \
+  -d '{"message":"Summarize this repo in one paragraph.","tools":true}'
+```
+
+## Realtime Chat
+
+```bash
+curl -s http://127.0.0.1:11435/v1/chat \
+  -H 'content-type: application/json' \
+  -d '{"message":"Keep this short for voice.","realtime":true}'
+```
+
+## OpenAI-Compatible Chat
+
+```bash
+curl -s http://127.0.0.1:11435/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"qwen3:4b","messages":[{"role":"user","content":"hello"}]}'
+```
+
+## Ollama-Compatible Generate
+
+```bash
+curl -s http://127.0.0.1:11435/v1/generate \
+  -H 'content-type: application/json' \
+  -d '{"model":"qwen3:4b","prompt":"Return one sentence."}'
+```
+
+## Agentic Run
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/run \
+  -H 'content-type: application/json' \
+  -d '{"task":"Run tests and report failures.","sandbox":"none"}'
+```
+
+## Events
+
+```bash
+curl -N http://127.0.0.1:11435/v1/events
+curl -N 'http://127.0.0.1:11435/v1/events?type=tool.*'
+```
+
+## Skills
+
+```bash
+curl -s http://127.0.0.1:11435/v1/skills
+curl -s http://127.0.0.1:11435/v1/skills/omnius-rest-docs
+```
+
+## Tool Call
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/tools/memory_search/call \
+  -H 'content-type: application/json' \
+  -d '{"args":{"query":"rest api docs"}}'
+```
+
+## Voice TTS
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/voice/tts \
+  -H 'content-type: application/json' \
+  -d '{"text":"Hello from Omnius.","format":"wav"}' \
+  --output speech.wav
+```
+
+## Runtime Key Minting
+
+Requires admin scope:
+
+```bash
+curl -s -X POST http://127.0.0.1:11435/v1/keys \
+  -H 'authorization: Bearer admin-secret' \
+  -H 'content-type: application/json' \
+  -d '{"scope":"run","owner":"ci","rpm":60,"tpd":100000,"max_jobs":3}'
+```

package/docs/rest/REST-DOCS-MANIFEST.json

@@ -0,0 +1,27 @@
+{
+  "name": "omnius-rest-docs",
+  "description": "Explorable Omnius REST API documentation index.",
+  "canonical_sources": [
+    "packages/cli/src/api/openapi.ts",
+    "GET /openapi.json",
+    "GET /docs",
+    "GET /redoc"
+  ],
+  "entrypoint": "docs/rest/INDEX.md",
+  "quickref": "docs/rest/QUICKREF.md",
+  "full_reference": "docs/reference/rest-api.md",
+  "skill": ".aiwg/addons/omnius-rest-docs/skills/omnius-rest-docs/SKILL.md",
+  "families": [
+    { "name": "chat", "path": "docs/rest/endpoints/chat.md", "triggers": ["chat", "generate", "realtime", "OpenAI-compatible", "/v1/chat", "/v1/generate"] },
+    { "name": "run", "path": "docs/rest/endpoints/run.md", "triggers": ["run", "jobs", "todos", "scheduled"] },
+    { "name": "config", "path": "docs/rest/endpoints/config.md", "triggers": ["config", "keys", "profiles", "projects", "endpoint"] },
+    { "name": "memory", "path": "docs/rest/endpoints/memory.md", "triggers": ["memory", "context", "sessions"] },
+    { "name": "skills", "path": "docs/rest/endpoints/skills.md", "triggers": ["skills", "commands", "skill_execute"] },
+    { "name": "aiwg", "path": "docs/rest/endpoints/aiwg.md", "triggers": ["AIWG", "cascade", "expand", "use"] },
+    { "name": "tools", "path": "docs/rest/endpoints/tools.md", "triggers": ["tools", "MCP", "codegraph"] },
+    { "name": "events", "path": "docs/rest/endpoints/events.md", "triggers": ["events", "metrics", "audit", "usage", "system"] },
+    { "name": "files", "path": "docs/rest/endpoints/files.md", "triggers": ["files", "read file"] },
+    { "name": "voice-vision", "path": "docs/rest/endpoints/voice-vision.md", "triggers": ["voice", "TTS", "ASR", "voicechat", "vision"] },
+    { "name": "aims", "path": "docs/rest/endpoints/aims.md", "triggers": ["AIMS", "ISO 42001", "governance"] }
+  ]
+}

package/docs/rest/auth-and-scopes.md

@@ -0,0 +1,101 @@
+# Auth And Scopes
+
+Omnius can run without auth for local development, but shared deployments should use bearer keys.
+
+## Environment Keys
+
+Single admin key:
+
+```bash
+OMNIUS_API_KEY="admin-secret" omnius serve
+```
+
+Multiple scoped keys:
+
+```bash
+OMNIUS_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve
+```
+
+Format:
+
+```text
+key:scope:owner:rpm:tpd:max_jobs
+```
+
+Fields:
+
+- `key`: bearer token.
+- `scope`: `read`, `run`, or `admin`.
+- `owner`: audit label.
+- `rpm`: optional requests-per-minute cap.
+- `tpd`: optional tokens-per-day cap.
+- `max_jobs`: optional concurrent job cap.
+
+## Runtime Keys
+
+Runtime keys are stored under `~/.omnius/keys.json` and are checked after environment keys.
+
+| Method | Path | Scope | Purpose |
+| --- | --- | --- | --- |
+| `GET` | `/v1/keys` | admin | List masked runtime keys |
+| `POST` | `/v1/keys` | admin | Mint a key; response contains the full secret once |
+| `DELETE` | `/v1/keys/{prefix}` | admin | Revoke keys matching a prefix |
+
+Mint body:
+
+```json
+{
+  "scope": "run",
+  "owner": "ci",
+  "profile": "readonly",
+  "rpm": 60,
+  "tpd": 100000,
+  "max_jobs": 3
+}
+```
+
+## Scope Semantics
+
+`read` is for inspection:
+
+- health, version, metrics
+- models
+- config summaries
+- usage, cost, audit reads
+- skills and tools metadata
+- memory search
+- events
+
+`run` can execute:
+
+- `/v1/run`
+- run-scope tools
+- memory writes where allowed
+- chat and agentic endpoints
+
+`admin` can mutate:
+
+- config
+- runtime keys
+- profiles
+- admin-only tools
+- AIMS policy registers
+- high-risk local controls
+
+Tool calls are additionally gated by each tool's security metadata. Scope alone is not the only control.
+
+## Request Header
+
+```text
+Authorization: Bearer <key>
+```
+
+## Network Access
+
+For local development, bind to loopback. For remote access, set explicit auth and access policy:
+
+```bash
+OMNIUS_HOST=0.0.0.0:11435 OMNIUS_API_KEYS="run-key:run:remote" omnius serve
+```
+
+Do not expose an unauthenticated daemon on a public interface.

package/docs/rest/endpoints/aims.md

@@ -0,0 +1,26 @@
+# AIMS Governance Endpoints
+
+Omnius exposes an ISO/IEC 42001-oriented AI Management System surface for audit-aligned deployments.
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/aims` | AIMS root, control map, endpoint index |
+| `GET`/`PUT` | `/v1/aims/policies` | Policy register |
+| `GET` | `/v1/aims/roles` | Roles and responsibilities |
+| `GET` | `/v1/aims/resources` | Compute and backend inventory |
+| `GET`/`POST` | `/v1/aims/impact-assessments` | Impact assessment records |
+| `GET` | `/v1/aims/lifecycle` | AI system lifecycle state |
+| `GET` | `/v1/aims/data-quality` | Data quality controls |
+| `GET` | `/v1/aims/transparency` | Model cards and transparency info |
+| `GET` | `/v1/aims/usage` | Alias of usage reporting |
+| `GET` | `/v1/aims/suppliers` | Third-party suppliers, sponsors, backends |
+| `GET`/`POST` | `/v1/aims/incidents` | Incident records |
+| `GET` | `/v1/aims/oversight` | Human oversight gates |
+| `GET` | `/v1/aims/decisions` | Consequential decision log |
+| `GET` | `/v1/aims/config-history` | Config change history |
+
+## Use
+
+Use these endpoints for compliance dashboards, deployment reviews, supplier tracking, and audit evidence. Mutating endpoints require admin scope.

package/docs/rest/endpoints/aiwg.md

@@ -0,0 +1,44 @@
+# AIWG Cascade Endpoints
+
+AIWG endpoints expose a discover-then-expand documentation and workflow model for small and large context agents.
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/aiwg` | AIWG installation root and control map |
+| `GET` | `/v1/aiwg/frameworks` | List frameworks |
+| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details and items |
+| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware framework content |
+| `GET` | `/v1/aiwg/skills` | List AIWG skills |
+| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill content |
+| `GET` | `/v1/aiwg/agents` | List AIWG agents |
+| `GET` | `/v1/aiwg/agents/{name}` | Load agent definition |
+| `GET` | `/v1/aiwg/addons` | List addons |
+| `POST` | `/v1/aiwg/use` | Return tier-sized activation bundle |
+| `POST` | `/v1/aiwg/expand` | Expand matching item by trigger or name |
+
+## Cascade Model
+
+`/v1/aiwg/use` returns a model-tier-sized activation bundle:
+
+- Small models: index and core pointers.
+- Medium models: metadata.
+- Large models: content excerpts.
+- Extra-large models: broader framework dumps.
+
+This prevents context overflow and mirrors the README docs-memory design.
+
+## Expand
+
+`POST /v1/aiwg/expand` accepts:
+
+```json
+{
+  "trigger": "rest api docs",
+  "name": "omnius-rest-docs",
+  "limit": 3
+}
+```
+
+It returns matching items for targeted unpacking.

package/docs/rest/endpoints/chat.md

@@ -0,0 +1,101 @@
+# Chat And Inference Endpoints
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/models` | List aggregated models |
+| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
+| `POST` | `/v1/embeddings` | Generate embeddings |
+| `POST` | `/v1/chat` | Stateful Omnius chat with optional full agent tools |
+| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
+| `POST` | `/api/generate` | Ollama-compatible alias |
+| `GET` | `/v1/chat/sessions` | List active chat sessions |
+| `POST` | `/v1/chat/check-in` | Send a steering check-in to the active chat session |
+
+## `/v1/models`
+
+Returns an OpenAI-style model list aggregated from enabled endpoints. Model discovery should include local Ollama, configured external endpoints, sponsor endpoints, and COHERE/passthrough models where enabled.
+
+## `/v1/chat/completions`
+
+This is the OpenAI-compatible endpoint. It forwards standard chat-completion fields and adds Omnius controls.
+
+Important body fields:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `model` | string | Backend model name |
+| `messages` | array | OpenAI-style messages |
+| `stream` | boolean | SSE streaming when supported |
+| `realtime` | boolean | Enable Omnius realtime conversation mode |
+| `realtime_options` | object | Realtime history and max-token defaults |
+| `tools` | array | OpenAI-shape tools array |
+| `tool_choice` | any | OpenAI-shape tool choice |
+| `parallel_tool_calls` | boolean | Forwarded to backend |
+| `timeout_s` | number | Per-request timeout |
+| `agent_loop` | boolean | Run server-side tool loop |
+| `include_daemon_tools` | array | Merge daemon tools by scope: `read`, `run`, `admin` |
+| `max_turns` | integer | Server-side agent loop turn cap |
+| `prompt_template` | string | Optional template such as `factual-first` |
+
+Realtime example:
+
+```json
+{
+  "model": "qwen3:4b",
+  "realtime": true,
+  "realtime_options": {
+    "max_history_messages": 12,
+    "max_tokens": 160
+  },
+  "messages": [
+    { "role": "user", "content": "Make that shorter for voice." }
+  ]
+}
+```
+
+## `/v1/chat`
+
+This is the Omnius stateful chat endpoint. By default it runs the full Omnius agent stack with tools, memory, skills, and multi-agent context. Set `tools: false` to use the fast direct backend path. `realtime: true` also uses the direct backend path.
+
+Body fields:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `message` | string | User message |
+| `model` | string | Optional model override |
+| `session_id` | string | Reuse or name a session |
+| `stream` | boolean | Stream when supported |
+| `tools` | boolean | Full agent stack by default |
+| `realtime` | boolean | Short ASR/TTS conversation mode |
+| `realtime_options` | object | Realtime settings |
+
+## `/v1/generate` And `/api/generate`
+
+These endpoints provide one-shot Ollama-compatible generation. They are useful for clients that speak Ollama's generate shape rather than OpenAI chat messages. The route has no session history and can still use Omnius' backend routing layer.
+
+Common body fields:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `model` | string | Optional model override |
+| `prompt` | string | Prompt text |
+| `stream` | boolean | Stream when supported |
+
+## Realtime Behavior
+
+When `realtime: true`, Omnius:
+
+- Builds a compact system prompt from `SOUL.md` or `.aiwg/SOUL.md`.
+- Reads a compact voice profile from `.aiwg/voices/` when present.
+- Keeps only recent non-system history.
+- Preserves caller system messages under the realtime contract.
+- Defaults to short response settings.
+- Removes Omnius-only realtime fields before backend proxying.
+
+Use this for live voice clients, not long coding tasks.
+
+## Server-Side Agent Loop
+
+`/v1/chat/completions` can run an internal tool loop when `agent_loop: true`. This lets clients collapse multiple model/tool round trips into one daemon request. Daemon tool calls execute inline; client-owned tool calls can still be yielded in OpenAI-compatible shape.

package/docs/rest/endpoints/config.md

@@ -0,0 +1,53 @@
+# Config, Endpoints, Keys, Profiles, And Projects
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/config` | Get daemon config and settings |
+| `PATCH` | `/v1/config` | Update settings |
+| `GET` | `/v1/config/model` | Show active model |
+| `PUT` | `/v1/config/model` | Switch model |
+| `GET` | `/v1/config/endpoint` | Show active backend endpoint |
+| `PUT` | `/v1/config/endpoint` | Switch endpoint with TUI-compatible normalization |
+| `POST` | `/v1/config/endpoint/test` | Probe endpoint from daemon process |
+| `GET` | `/v1/config/endpoint/history` | List recently used endpoints |
+| `DELETE` | `/v1/config/endpoint/history` | Remove an endpoint from history |
+| `POST` | `/v1/share/generate` | Generate a remote-access share URL |
+| `GET` | `/v1/keys` | List runtime API keys |
+| `POST` | `/v1/keys` | Mint runtime API key |
+| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |
+| `GET` | `/v1/profiles` | List tool profiles |
+| `POST` | `/v1/profiles` | Create a tool profile |
+| `GET` | `/v1/profiles/{name}` | Get profile details |
+| `DELETE` | `/v1/profiles/{name}` | Delete profile |
+| `GET` | `/v1/projects` | List known projects |
+| `GET` | `/v1/projects/current` | Get active project |
+| `POST` | `/v1/projects/switch` | Switch active project |
+| `POST` | `/v1/projects/register` | Register project root |
+| `POST` | `/v1/projects/rename` | Rename project |
+| `GET`/`PUT` | `/v1/projects/preferences` | Read or patch project preferences |
+
+## Endpoint Switching
+
+Endpoint switching uses the same normalization as the TUI. Use `/v1/config/endpoint/test` before switching a remote endpoint in automation.
+
+Endpoint history mirrors the `/endpoint` TUI flow. It records recently used endpoints with metadata so users can reselect external routers, sponsor endpoints, and OpenAI-compatible URLs without retyping them.
+
+`POST /v1/share/generate` creates a remote-access URL embedding the daemon host and auth material needed by the browser client. Use it only in authenticated contexts.
+
+## Model Switching
+
+`PUT /v1/config/model` updates the active model for subsequent requests. Clients can still pass per-request `model` fields to chat endpoints.
+
+## Runtime Keys
+
+Runtime keys are persistent, scoped, and revocable. See `docs/rest/auth-and-scopes.md`.
+
+## Profiles
+
+Profiles constrain tools and runtime behavior for a key or request path. Use them for CI, dashboards, or remote clients that should not receive the full local tool surface.
+
+## Projects
+
+The daemon is process-wide, but project endpoints track the active workspace and per-project preferences such as selected model, chat session, and UI choices.

package/docs/rest/endpoints/events.md

@@ -0,0 +1,63 @@
+# Events, Metrics, Usage, Audit, System, Nexus, And Ollama Pool
+
+## Endpoint Summary
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` | Liveness |
+| `GET` | `/health/ready` | Readiness |
+| `GET` | `/health/startup` | Startup complete |
+| `GET` | `/version` | Package version and platform |
+| `GET` | `/metrics` | Prometheus metrics |
+| `GET` | `/v1/events` | Server-sent events |
+| `GET` | `/v1/usage` | Token usage and rate limits |
+| `GET` | `/v1/audit` | Audit log query |
+| `GET` | `/v1/cost` | Cost tracker |
+| `GET` | `/v1/system` | System info and resource snapshot |
+| `GET` | `/v1/nexus/status` | Nexus peer state |
+| `GET` | `/v1/sponsors` | Local sponsor directory cache |
+| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |
+| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |
+
+## Events
+
+`GET /v1/events` is an SSE stream. Filter by exact type or prefix:
+
+```text
+/v1/events?type=tool.called
+/v1/events?type=tool.*
+```
+
+Documented event families include:
+
+- `config.changed`
+- `run.started`
+- `run.completed`
+- `run.aborted`
+- `run.failed`
+- `tool.called`
+- `memory.written`
+- `memory.searched`
+- `skill.invoked`
+- `mcp.called`
+- `engine.state_changed`
+- `auth.failed`
+- `rate_limit.hit`
+- `incident.raised`
+- `incident.resolved`
+- `session.created`
+- `session.ended`
+- `aims.policy_changed`
+- `aims.decision_recorded`
+
+## Usage And Cost
+
+Usage endpoints support dashboards for requests, token counts, rate limits, and provider cost estimates. Sponsor and COHERE dashboards should use these concepts consistently: requests per minute, daily tokens, concurrency, per-peer tokens, and per-model tokens.
+
+## Nexus And Sponsors
+
+`/v1/nexus/status` reports peer mesh state. `/v1/sponsors` exposes the local sponsor directory cache.
+
+## Ollama Pool
+
+The pool endpoints are admin-oriented process hygiene tools. They report managed `ollama serve` processes and cleanup decisions. Cleanup accounts for stale pool state and orphan runner risks.