@octocodeai/freellama-mcp-server 0.5.0 → 0.6.1

package/docs/ARCHITECTURE.md

@@ -11,10 +11,14 @@ the operating system and drivers schedule physical work.
 
 ## Responsibility boundary
 
-The following table defines the ownership boundary:
+This is the canonical ownership rule; other guides link here.
 
 | Responsibility | Owner |
 |---|---|
+| Goal decomposition, prompts, system messages, task dependencies, and answer verification | Calling agent |
+| Ollama processes and endpoints, exact `--cpu-model` assignments, runtime settings, and approval of pulls, stops, and deletes | Operator |
+| Prompt templates and model defaults | Ollama model metadata or a `Modelfile` |
+| Physical CPU/GPU scheduling and memory | OS, drivers, and accelerator runtime |
 | Model files, runners, Metal, MLX, llama.cpp, and token generation | Ollama |
 | Native `/api/*` and OpenAI-compatible `/v1/*` semantics | Ollama |
 | Installed-model discovery and capability normalization | FreeLlama |
@@ -23,9 +27,33 @@ The following table defines the ownership boundary:
 | Forecast memory reservations, host-pressure holds, and requests to unload idle unpinned models | FreeLlama managed execution |
 | Explicit per-model CPU/GPU backend assignment | FreeLlama and separate Ollama processes |
 | Grounded research adapters, citations, and verification verdicts | FreeLlama MCP server |
+| Bearer authentication of every route except the static `/_freellama/ui` shell | FreeLlama; external ingress owns TLS and tenant authorization |
 
-FreeLlama remains a sidecar rather than an Ollama fork. For the compatibility rationale, see the
-[Ollama sidecar boundary](OLLAMA_SIDECAR.md).
+FreeLlama is a governed router, not an unrestricted hardware scheduler: a CPU preference cannot move
+an arbitrary tag, and one managed call contains one task. Only the calling agent knows which tasks
+are independent.
+
+### Ollama sidecar
+
+FreeLlama is a loopback sidecar, not an Ollama fork. It talks to Ollama over its documented HTTP
+contract, which also makes a second, process-isolated CPU backend possible without changing client
+payloads:
+
+```mermaid
+flowchart LR
+    C["Ollama-compatible client"] --> F["FreeLlama loopback sidecar"]
+    F -->|"raw /api and /v1"| G["Primary Ollama"]
+    F -->|"managed primary task"| G
+    F -->|"managed assigned task"| U["Optional CPU Ollama"]
+    G --> E["Metal, MLX, CUDA, ROCm, Vulkan, or CPU runner"]
+    U --> E2["CPU runner"]
+```
+
+FreeLlama does not make an individual model decode faster. It can improve workload completion by
+avoiding unsuitable routes, reducing avoidable transitions, refusing unsupported work early, and
+overlapping independent CPU and GPU model requests when the machine benefits from that layout.
+Sources: [Ollama API](https://docs.ollama.com/api/introduction),
+[streaming](https://docs.ollama.com/api/streaming), [usage](https://docs.ollama.com/api/usage).
 
 ## System topology
 
@@ -64,9 +92,10 @@ flowchart TB
     ADAPTER --> GPU
 ```
 
-The CLI and MCP server do not reimplement routing. The CLI calls the core directly. The MCP server
-uses the feature-gated NAPI boundary for native operations and the control API for serve-backed
-operations.
+The CLI and MCP server do not reimplement routing. CLI commands other than `serve`, `doctor`,
+`init`, and benchmarking are HTTP clients of a running `freellama serve`. The MCP server reaches the
+same control API through the feature-gated NAPI boundary, and unless `FREELLAMA_MCP_AUTOSTART_SERVE=0`
+it starts the bundled `serve` in the background at launch when nothing answers on the default endpoint.
 
 ## Request classification
 
@@ -79,8 +108,7 @@ flowchart TD
     RAW --> PRIMARY["Primary Ollama"]
     P -->|"Yes"| C{"Control endpoint"}
     C -->|"health, machine, models"| READ["Read local and Ollama state"]
-    C -->|"recommendations, routes"| DECIDE["Decide without inference"]
-    C -->|"natural-routes"| INTENT["Run intent model, then route"]
+    C -->|"routes"| DECIDE["Decide without inference"]
     C -->|"tasks"| RUN["Route, admit, and execute"]
     C -->|"sessions"| SESSION["Create in-memory affinity id"]
     C -->|"scopes"| SCOPES["Retain revision-protected messages"]
@@ -94,30 +122,72 @@ The control API exposes these endpoints:
 | `GET /_freellama/v1/health` | Health, admission capacity, and configured backends | No |
 | `GET /_freellama/v1/machine` | Machine profile | No |
 | `GET /_freellama/v1/models` | Normalized installed catalog, evidence, residency, and execution backend | No |
-| `POST /_freellama/v1/recommendations` | Installed route or reviewed installation plan | No |
 | `POST /_freellama/v1/routes` | Deterministic route decision | No |
-| `POST /_freellama/v1/natural-routes` | Schema-bound intent interpretation followed by deterministic routing | Intent model only |
 | `POST /_freellama/v1/sessions` | New model-affinity session | No |
 | `DELETE /_freellama/v1/sessions/:session_id` | Release model-affinity session | No |
+| `POST /_freellama/v1/sessions/:session_id/kill` | Release a session and cancel its in-flight tasks; the runner stays loaded | No new inference |
 | `POST /_freellama/v1/scopes` | Create bounded message history | No |
 | `GET /_freellama/v1/scopes/:id` | Scope metadata; optional explicit history inclusion | No |
 | `POST /_freellama/v1/scopes/:id/fork` | Fork history at an expected revision | No |
 | `DELETE /_freellama/v1/scopes/:id` | Delete retained history | No |
 | `POST /_freellama/v1/warm` | Admitted load of an exact installed runner profile | Load only |
-| `POST /_freellama/v1/tasks` | Managed chat, vision, tools, or embedding task | Yes |
+| `POST /_freellama/v1/tasks` | Managed chat, vision, tools, or embedding task (body shape under [Request shapes](#request-shapes)) | Yes |
+| `POST /_freellama/v1/task-batches` | Caller-declared independent tasks with ordered per-item receipts | Yes |
 | `GET /_freellama/v1/jobs` | Deferred job metadata without prompts or results | No |
 | `GET /_freellama/v1/jobs/:id` | One deferred receipt and retained result | No |
 | `POST /_freellama/v1/jobs/:id/cancel` | Cancel one deferred task and release its local permits | No new inference |
 | `DELETE /_freellama/v1/jobs/:id` | Cancel active work, release local permits, and remove its retained record | No new inference |
 
+Status, usage, metrics, and runtime-config endpoints are listed in [monitoring](MONITORING.md).
+
+### Request shapes
+
+The control API uses snake_case JSON. A managed task body is the routing fields plus the payload:
+
+```json
+{
+  "task": "vision", "objective": "fastest", "model": "my-vision-model",
+  "session_id": "<uuid from POST /sessions>", "required_capabilities": ["vision"],
+  "prompt": "Text Recognition:", "images": ["<base64, no data-URI prefix>"],
+  "priority": "background", "keep_alive": "5m", "max_wait_seconds": 30, "timeout_seconds": 120,
+  "stop_on_repetition": true,
+  "request_options": { "options": { "temperature": 0, "num_predict": 600 }, "format": "json", "think": false }
+}
+```
+
+`model` is read the way Ollama reads it: an exact installed tag, else `name:latest`, else the one
+installed tag of that family; an unknown or ambiguous name is refused with the installed candidates.
+`messages` (Ollama message objects, images included) replaces `prompt`; `input` serves embeddings;
+`context_tokens` owns `num_ctx` and placement owns `num_gpu`, so neither is accepted inside
+`request_options.options`. `stop_on_repetition: true` streams the chat from Ollama and stops as soon
+as the output repeats its unit twice after the first copy over 96+ characters: the connection
+closes, which cancels generation upstream, and everything generated is kept with
+`done_reason: "repetition"`. An Ollama "token repeat limit" abort is kept the same way
+(`done_reason: "repeat_limit"`). A stopped stream has no Ollama timing fields, so it trains no
+throughput feedback. The receipt holds `route`, `admission` (`queue_wait_ms`,
+`resource_wait_ms`, `transition_wait_ms`, `total_wait_ms`), `execution` (placement, observation,
+`resource_admission`, `context_sizing`, `memory_reservation`), `metrics`, `feedback` and
+`response`, which is Ollama's own answer (`message.content`, `eval_count`, durations).
+
+A batch nests whole task bodies:
+
+```json
+{ "max_parallelism": 2, "tasks": [ { "id": "item-1", "independent": true, "task": { "task": "vision", "model": "my-vision-model", "prompt": "...", "images": ["..."] } } ] }
+```
+
+`POST /sessions` with an empty object returns `session_id`; `POST /warm` takes `{"model": "<tag>"}`.
+
 The machine profile is host-derived rather than model-name-derived. It reports total physical
-memory on macOS (`sysctl`), Linux (`/proc`), and Windows (system APIs), along with CPU, OS,
+memory on macOS (`sysctl`), Linux (`/proc`), and Windows (CIM through PowerShell), along with CPU, OS,
 architecture, and disk. `memory_bytes` is portable host RAM. `unified_memory_bytes` is populated
 only when host and accelerator memory are known to share a pool; it must not be treated as discrete
 GPU VRAM. Ollama's `/api/ps` remains the placement authority.
 
 All other paths use the compatibility proxy. It buffers request bodies up to 64 MB so a retry can
-resend identical bytes, then streams the upstream response. It does not apply CPU model assignment.
+resend identical bytes, then streams the upstream response. It removes hop-by-hop headers, adds
+`x-freellama-proxy: 1`, always targets the primary upstream, and does not apply CPU model
+assignment. Existing Ollama clients keep predictable compatibility; clients that opt into the
+managed API receive routing and policy behavior.
 
 ## Model discovery
 
@@ -131,12 +201,26 @@ flowchart LR
     BENCH["Local benchmark report"] --> CAT
     POLICY["Task policy"] --> CAT
     ASSIGN["CPU model assignments"] --> CAT
-    CAT --> MODEL["CatalogModel<br/>capabilities · context · residency<br/>benchmark · policy rank · backend"]
+    LOOPS["Observed repetition loops"] --> CAT
+    CAT --> MODEL["CatalogModel<br/>capabilities · context · residency<br/>benchmark · policy rank · backend · loops"]
 ```
 
 FreeLlama fetches tags and residency from each configured backend. Models assigned to CPU are
 removed from the primary catalog view and included only from the secondary backend. Static catalog
-metadata is cached for 30 seconds; residency is refreshed before routing.
+metadata is cached for 30 seconds; residency and observed loops are refreshed before routing.
+
+Every field comes from the model's own metadata and from what FreeLlama observed, never from its
+name. `GET /_freellama/v1/models` adds, per model:
+
+- `context_default`: the context Ollama gives a request that leaves `num_ctx` unset (`source` is
+  `modelfile`, `config`, `ollama_context_length`, `vram_tier`, `resident_runner`, or `unknown`). A managed
+  task that sends a different `num_ctx` reloads the runner.
+- `resident_context`: the `context_length` of the loaded runner from `/api/ps`.
+- `observed_loops`: per task kind, managed runs since start and how many ended in a repetition
+  loop (`{runs, loops}`); process-local, not persisted.
+- `kv_cache_bytes_per_token_f16`: estimated from the declared architecture's block count, KV head
+  count and key/value lengths, for any architecture; `null` when the metadata declares recurrent,
+  state-space, sliding-window, shared or cross-attention caches, which the dense formula misstates.
 
 A failed `/api/show` response skips that model instead of failing the entire catalog. An unreachable
 configured backend fails catalog discovery closed because FreeLlama cannot prove the assigned model's
@@ -150,7 +234,7 @@ matches exact tags and digest prefixes, preserves local supported features, and
 source excerpts and usage notes. Its bounded in-memory cache expires successes after one hour and
 failures after one minute. Failed or unmatched lookups leave local inventory and evidence intact.
 Public claims do not enter the Rust catalog, task policy, quality confidence, or routing decisions.
-See [Ollama model metadata](MODEL_METADATA.md) for the public contract and request bounds.
+See [Model metadata](MODEL_SELECTION.md#model-metadata) for the public contract and request bounds.
 
 ## Deterministic routing
 
@@ -164,7 +248,7 @@ flowchart TD
     F --> X{"Explicit model?"}
     X -->|"Yes"| E["Use exact model or refuse"]
     X -->|"No"| O{"Objective"}
-    O -->|"fastest"| S["Rank local performance,<br/>residency, and deterministic ties"]
+    O -->|"fastest"| S["Rank local benchmark,<br/>smaller size, and deterministic ties"]
     O -->|"balanced"| B["Prefer policy-qualified candidates;<br/>otherwise use eligible models with low confidence"]
     O -->|"quality"| Q["Require policy-qualified candidates,<br/>then prefer policy order"]
     E --> H["Grade advertised-context compatibility and evidence"]
@@ -176,8 +260,18 @@ flowchart TD
     G -->|"Yes or unset"| D["RouteDecision"]
 ```
 
-Explicit model selection never substitutes another model. Every rejected candidate includes a
-reason so callers can distinguish capability, context, policy, and installation failures.
+Explicit model selection never substitutes another model. An explicit `model` is read the way
+Ollama reads it: the exact tag, else `name:latest`, else the one installed tag of that family; an
+unknown or ambiguous name is refused with the installed candidates. Every rejected candidate
+includes a reason so callers can distinguish capability, context, policy, and installation failures.
+
+Routing never ranks by a model's name or architecture. Automatic selection (fallback ranking and
+session affinity) ranks a model last for a task kind when it has looped on that kind at least twice
+in at most twice as many managed runs; the decision then carries
+`repeats_on_this_task_last_resort`. An operator policy naming the model for the task, or an explicit
+`model`, always wins. No request option is hard-coded for a model: apart from an operator policy's
+per-model `model_options` (`think`, `num_predict`), stop sequences and decoding settings belong to
+the caller.
 
 `context_window_fit` means only that requested `num_ctx` fits the model's advertised context
 window. It is not a live-memory, free-VRAM, K/V-cache, thermal, or runner-admission verdict.
@@ -198,37 +292,12 @@ Confidence is a grade derived from independent evidence dimensions:
 `minConfidence: "medium"` refuses before generation when either input is missing. The gate lives in
 `select_route`, so the HTTP API, CLI, MCP server, and embedded core share the same behavior.
 
-## Natural-language routing
-
-Natural-language routing cannot select a model directly:
-
-```mermaid
-sequenceDiagram
-    participant C as Client
-    participant F as FreeLlama
-    participant I as Intent model
-    participant R as Deterministic router
-
-    C->>F: Natural-language request
-    F->>I: Strict JSON schema and bounded profile
-    I-->>F: Task, objective, context, tool, and vision fields
-    F->>F: Apply deterministic guards
-    F->>R: Normalized RouteInput
-    R-->>F: RouteDecision
-    F-->>C: Intent, adjustments, and route
-```
-
-Word-boundary guards prevent incidental substrings such as `photosynthesis` from creating a vision
-requirement. Explicit requirements in the original text override weak or unsupported inferred fields.
-
-The natural route endpoint does not run the selected task. Submit a managed task to execute it.
-
 ## Managed task execution
 
-The implementation separates [admission scheduling](../packages/rust-core/src/platform/admission.rs),
-[execution coordination](../packages/rust-core/src/platform/execution.rs),
-[read-only readiness](../packages/rust-core/src/platform/readiness.rs), and
-[typed errors](../packages/rust-core/src/platform/error.rs). The platform module wires HTTP endpoints,
+The implementation separates [admission scheduling](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/admission.rs),
+[execution coordination](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/execution/mod.rs),
+[read-only readiness](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/readiness.rs), and
+[typed errors](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/error.rs). The platform module wires HTTP endpoints,
 configuration, discovery, and shared state; extracting these owners preserves the public routing API.
 
 Managed tasks combine routing with admission and backend-aware transition coordination. With
@@ -243,7 +312,7 @@ flowchart TD
     T["POST /tasks or /task-batches"] --> R["Select eligible model + backend"]
     R --> K["Estimate metadata-backed F16 K/V<br/>(or report unknown)"]
     K --> A{"Acquire selected backend's<br/>3:2:1 fair weighted budget"}
-    A -->|"No"| E503["503 server busy"]
+    A -->|"No"| E503["429 queue full or<br/>503 wait timeout"]
     A -->|"Yes"| B{"Execution backend"}
     B -->|"Primary"| GL{"GPU model resident<br/>under transition lock?"}
     B -->|"CPU assignment"| CO["Add num_gpu: 0"]
@@ -271,8 +340,8 @@ falling back to two. The optional CPU pool defaults to one. A saturated GPU burs
 consume the permit held for a small CPU helper. With one parallel slot, those values represent one
 ordinary chat and one embedding. Operators can tune both budgets from queue-wait and resident-memory evidence.
 After FreeLlama admission, each Ollama process applies its own `OLLAMA_MAX_QUEUE`, scheduler,
-`OLLAMA_NUM_PARALLEL`, and loaded-model limit. Raw proxy requests bypass weighted admission but
-still pass the raw concurrency cap, backend exclusion, and host-pressure gate.
+`OLLAMA_NUM_PARALLEL`, and loaded-model limit. Raw proxy generation requests bypass weighted
+admission but still pass the raw concurrency cap, backend exclusion, and host-pressure gate.
 
 | Task | Default cost |
 |---|---:|
@@ -312,9 +381,10 @@ stable ID and `independent:true`; dependent workflow execution is rejected befor
 It bounds local dispatch and returns ordered per-item success/error receipts. Every child still
 passes the same global admission and transition path above.
 
-The K/V preflight derives single-sequence F16 K+V bytes-per-token only for supported model
-architectures with sufficient metadata. Explicit key/value dimensions take precedence; sliding-window,
-shared-KV, recurrent, and unknown layouts report unknown. F16 is advisory because quantized KV can
+The K/V preflight derives single-sequence F16 K+V bytes-per-token for any architecture whose
+metadata declares the block count and head counts. Explicit key/value dimensions take precedence
+over embedding length divided by heads; sliding-window, shared-KV, recurrent, cross-attention, and
+unknown layouts report unknown. F16 is advisory because quantized KV can
 use less memory. The coarse model-file budget refuses files over 80% of local CPU/unified RAM only
 for loopback backends. Forecasts use each backend's independently attributed parallelism and KV
 cache settings where process inspection is available, with explicit fallback sources otherwise.
@@ -322,32 +392,45 @@ Process observations refresh on requests after five seconds; measurements made u
 settings cannot supply an exact-fit estimate. Ollama remains the live loader and final memory
 authority. Configured settings alone do not prove physical processor placement.
 
-The shared [resource governor](../packages/rust-core/src/platform/resources.rs) samples local
+The shared [resource governor](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/src/platform/resources/mod.rs) samples local
 available-memory estimates, load per logical CPU, OS memory pressure, active swap-out growth, and
-thermal throttling when reported. It holds new local work below the larger of 15% available RAM or
-1 GiB, and requires two healthy samples above the larger of 20% or 2 GiB to resume. Historical swap
-occupancy alone is not pressure. Samples are cached for two seconds; unavailable signals stay unknown.
-Remote backends bypass this host gate.
+thermal throttling when reported. OS memory pressure holds every local demand; active swap-out
+growth holds new loads; CPU-load and thermal holds apply to CPU-assigned work and to cold loads
+(decoding weights is CPU work and a new heat source) but not to a bounded request on a runner
+already resident on the GPU, which neither waits for the cores nor cools the package by waiting (`ResourceDemand::is_held_by`; the assessment's
+`held_by` lists the holds that applied). Low available RAM (below the larger of 15% or 1 GiB, clearing after two
+healthy samples above the larger of 20% or 2 GiB) depends on the platform (`ResourcePolicy::low_memory`).
+A new load must leave that reserve free, but never more than its own size above the 1 GiB floor.
+On macOS (`advisory`) the estimate undercounts what the OS can reclaim, so a load that does not cover
+it first unloads idle runners and then dispatches with a `memory_advisory`. On Linux and other
+platforms (`refuse`) a new load that does not fit first unloads idle runners and then waits
+with `held_insufficient_capacity` until a permit release or a fresh sample frees capacity, or refuses
+with 503 at its deadline: Linux `MemAvailable` already includes reclaimable cache and is the hard cap
+in a container, so over-admitting invites the OOM killer. Already-resident runners add no memory and
+are admitted in both modes, also during an active-swapping hold, so a large load never locks out
+reuse of its own runner; swapping still holds new loads. Historical swap occupancy alone is not pressure. Samples are cached for two
+seconds; unavailable signals stay unknown. Remote backends bypass this host gate.
 
 Each pressure signal recovers independently after two fresh samples that meet its recovery
-threshold. A recovered CPU-load signal therefore clears even while RAM remains low. That keeps
-unchanged resident runners eligible under a memory-only hold while cold loads continue waiting.
+threshold. A recovered CPU-load signal therefore clears even while RAM remains low.
 
-The default `require_memory` telemetry policy holds local inference when available RAM is missing,
-even when a raw request has no model-footprint estimate. `best_effort` is an explicit opt-in;
+On Linux and macOS the default `require_memory` telemetry policy holds local inference when
+available RAM is missing, even when a raw request has no model-footprint estimate. Windows and other
+platforms have no host collector, so they default to `best_effort` and admit with
+`admitted_telemetry_unknown`; elsewhere `best_effort` is an explicit opt-in;
 `require_all` additionally requires the collector's applicable load, OS-pressure, and thermal signals.
 Unsupported Linux collector signals remain explicitly unavailable rather than being fabricated.
 The pure `ResourceSnapshot::assess_capacity` calculation is shared by admission and previews.
 Previews use the same footprint lookup, subtract existing reservations, and expose both queue and
-resource readiness. An available weighted slot cannot by itself produce `runnable_now` when model
-headroom is insufficient. Preview capacity is advisory and conservative, never a reservation.
+resource readiness. Insufficient model headroom reports `runnable_low_memory_estimate` and admits
+no siblings on macOS; elsewhere it reports `held_insufficient_capacity`. Preview capacity is advisory and conservative, never a reservation.
 
 Managed CPU/unified-memory tasks reserve estimated additional model-file and known F16 KV bytes
 across both backends. Verified runner footprints replace that estimate only for the same backend,
 immutable model digest, and equal-or-larger observed context. Exact resident digest/context matches
-avoid double-counting existing allocations. The reservation is rechecked after transition locking;
-an increased requirement that no longer fits refuses with 503, without waiting while holding the
-backend lock. Permits release on completion or cancellation. On discrete-GPU hosts, observed free
+avoid double-counting existing allocations. The reservation is rechecked after transition locking
+without waiting while holding the backend lock; an increased requirement that no longer fits the
+estimate dispatches with a `memory_advisory`, and a pressure hold refuses with 503. Permits release on completion or cancellation. On discrete-GPU hosts, observed free
 VRAM discounts the estimated host-memory requirement by the bytes the GPU can hold. Missing VRAM
 telemetry reserves the full estimated footprint in host RAM. The governor cannot constrain external
 allocations or preempt an already-running model.
@@ -369,11 +452,11 @@ Resident tasks share a backend lock. Nonresident tasks take that backend's exclu
 load cannot race another managed task on the same server. CPU and GPU backends have separate locks
 and admission pools, so they can progress independently.
 
-In `serve`, mutating raw proxy requests also take the primary backend's exclusive transition lock,
-returning 503 when busy. The response body holds this guard through EOF or disconnect. Metadata
-GET/HEAD and `/api/show` requests remain available. Raw inference waits at most 500 ms for host
-pressure to clear, then returns 503 with `Retry-After`; empty `keep_alive:0` unload requests bypass
-pressure. Raw request-body collection has the configured request deadline too; an incomplete upload
+In `serve`, raw generation requests also take the primary backend's exclusive transition lock,
+returning 503 when it stays busy past the raw queue wait. The response body holds this guard through
+EOF or disconnect. Metadata GET/HEAD, `/api/show`, model-store calls (pull, push, copy, delete, and
+blob uploads), and empty `keep_alive:0` unload requests take no lock and bypass pressure. Raw
+inference waits at most two seconds for host pressure to clear, then returns 503 with `Retry-After`. Raw request-body collection has the configured request deadline too; an incomplete upload
 returns HTTP 408 and releases its guards without contacting Ollama. Admission receipts report
 `queue_wait_ms`, `resource_wait_ms`, `transition_wait_ms`, and
 their sum as `total_wait_ms`. Health and route receipts expose sampled pressure and reservations.
@@ -418,35 +501,18 @@ cold-load cost do not poison the comparison. It requires more than a 10% advanta
 break a tie before the sample threshold. Quality routing, explicit model selection, and session
 affinity do not follow the latency loop.
 
-The same selection function supplies preview/recommendation receipts, intent-model execution, and
-managed task execution. This keeps advertised placement and actual request routing aligned.
+The same selection function supplies preview receipts and managed task execution. This keeps advertised placement and actual request routing aligned.
 
 Raw proxy traffic always uses the primary upstream. For setup and runtime verification, see
 [Run models on CPU and GPU](CPU_GPU_ROUTING.md).
 
 ## MCP tool flow
 
-The MCP server keeps general model work separate from file-backed research and destructive lifecycle
-operations:
-
-```mermaid
-flowchart TD
-    MC["MCP client"] --> TOOL{"Tool"}
-    TOOL -->|"doctor"| NAPI["Native core diagnostics"]
-    TOOL -->|"models"| MIX["Control API or direct Ollama/library HTTP"]
-    TOOL -->|"run_task"| TASK["Control API route or task"]
-    TOOL -->|"task_jobs"| JOB["Deferred receipts and per-task cancellation"]
-    TOOL -->|"ollama_manage"| LIFE["Direct Ollama pull or unload"]
-    TOOL -->|"ollama_delete"| DELETE["Explicit destructive Ollama delete"]
-    TOOL -->|"delegate_research"| AD["Confined adapter subprocess"]
-    AD --> FS["Allowlisted workspace"]
-    AD --> TASK
-    AD --> VER["Answer, citations, usage,<br/>and verification verdict"]
-```
-
-The tool split prevents `run_task` from acquiring file access and prevents lifecycle operations from
-being hidden inside a generic action. For schemas and security annotations, see the
-[MCP server reference](../packages/mcp/README.md).
+The MCP server keeps general model work (`run_task`), file-backed research (`delegate_research`, a
+confined adapter subprocess), and destructive lifecycle operations (`ollama_manage`,
+`ollama_delete`) in separate tools, so `run_task` never acquires file access and lifecycle
+operations are not hidden inside a generic action. The canonical tool table, schemas, and security
+annotations are in the [MCP server reference](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md#tools).
 
 ## Grounded research flow
 
@@ -499,8 +565,8 @@ Adapter cache totals remain null if any turn is unreported, with partial-report
 See [Ollama usage](https://docs.ollama.com/api/usage) and
 [the pinned prefix-cache implementation](https://github.com/ggml-org/llama.cpp/blob/74a7c897f049c17e7080423aa2111776eff6ebbf/tools/server/server-context.cpp#L3201).
 
-For adapter implementation, defaults, and measured caveats, see the
-[local adapter reference](../benchmark/local/docs/07-adapter-contracts.md).
+Adapter implementations and defaults live in
+[`packages/mcp/src/research/`](../packages/mcp/src/research/).
 
 ## Context and token boundary
 
@@ -519,7 +585,7 @@ flowchart LR
 
 Raw source, images, and embedding vectors do not need to enter the frontier model's context.
 Embedding vectors are withheld by default because they are large and not human-readable. For the
-measured accounting, see [Token economics](ECONOMICS.md).
+measured accounting, see [Token economics](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md#token-economics).
 
 ## State and failure behavior
 
@@ -543,6 +609,14 @@ expected revision. Warming uses ordinary admission and fit checks; omitted resid
 a finite measured policy. See [Scope history and model warming](SCOPES_AND_WARMING.md) for the
 public contract and configured limits.
 
+In `serve`, raw generation traffic shares the primary transition lock and receives
+host-pressure gating, while managed tasks also reserve forecast memory. Direct Ollama callers bypass
+these controls. FreeLlama cannot preempt inference or constrain other processes. A configured but
+unreachable CPU backend makes managed catalog discovery fail closed; raw primary passthrough remains
+usable. Runtime feedback is task-specific, token-normalized, and warm-only: it can steer unpinned
+`fastest` or `balanced` work after three samples per backend and a greater-than-10% advantage, but
+cannot change CPU eligibility or steer quality routing.
+
 The design fails closed when it cannot establish a required contract. Examples include an
 unreachable configured backend, an unknown confidence grade, a policy without qualified models, an
 explicit model that is not installed, or a task that exceeds the advertised context window.
@@ -550,8 +624,9 @@ explicit model that is not installed, or a task that exceeds the advertised cont
 ## Product boundary
 
 FreeLlama is not an inference engine, remote provider marketplace, billing layer, hosted model
-registry, general agent runtime, or A2A coordinator. It can authenticate every route with one
-operator-managed bearer token and refuses unauthenticated nonloopback listeners. An external layer
+registry, general agent runtime, or A2A coordinator. It can authenticate every route except the
+static UI shell with one operator-managed bearer token and refuses unauthenticated nonloopback
+listeners. An external layer
 must still provide TLS, tenant authorization, tenant-specific limits, and isolation.
 
 Use Ollama directly when a caller only needs raw speed from one exact model. Use FreeLlama when the