@octocodeai/freellama-mcp-server 0.5.0 → 0.6.1

package/docs/CLI.md

@@ -2,7 +2,7 @@
 
 The `freellama` command starts and inspects the local management layer that agents use to offload
 work. It exposes diagnostics, model routing, managed execution, resource controls, benchmarking,
-and Ollama-compatible passthrough. Use the [README quick start](../README.md#quick-start) for first
+and Ollama-compatible passthrough. Use the [README CLI section](https://github.com/bgauryy/FreeLlama/blob/main/README.md#from-the-terminal) for first
 use and this reference to look up commands and controls.
 
 ## Choose a command
@@ -12,13 +12,12 @@ flowchart TD
     Q{"What do you need?"}
     Q -->|"Prepare first use"| I["init"]
     Q -->|"Inspect this machine"| D["doctor or machine"]
-    Q -->|"Inspect or choose a model"| M["models, route, or recommend"]
-    Q -->|"Execute a managed request"| T["session, natural-route, or task"]
+    Q -->|"Inspect or choose a model"| M["models or route"]
+    Q -->|"Execute a managed request"| T["session or task"]
     Q -->|"Run the control plane"| S["serve"]
     Q -->|"Preserve only Ollama APIs"| P["proxy"]
-    Q -->|"Measure or compare"| B["bench-all, run, or eval"]
-    Q -->|"Create a routing policy"| E["policy-from-eval"]
-    Q -->|"Compare CLI and MCP"| L["tools"]
+    Q -->|"Measure models"| B["bench-all"]
+    Q -->|"Write a routing policy"| PE["policy from-eval"]
 ```
 
 | Command | Purpose | Needs `freellama serve` |
@@ -35,17 +34,12 @@ flowchart TD
 | `scope` | Create, inspect, fork, or delete bounded message history | Yes |
 | `warm` | Warm an installed model through managed admission | Yes |
 | `route` | Choose a model and request profile without executing it | Yes |
-| `recommend` | Return an installed route or a reviewed installation plan | Yes |
-| `natural-route` | Convert natural language to a route intent locally, then route it | Yes |
 | `task` | Route and execute one nonstreaming task | Yes |
 | `jobs` | List, inspect, cancel, or remove deferred tasks and warming operations | Yes |
 | `proxy` | Run only the Ollama-compatible retry and telemetry sidecar | No |
 | `bench-all` | Measure installed models by capability group | No |
-| `policy-from-eval` | Generate policy from quality-evaluation pass rates | No |
-| `tools` | Print MCP tools and their CLI equivalents | No |
+| `policy from-eval` | Write a task policy (`platform.toml`) from a quality-evaluation aggregate and the installed tags | No |
 | `doctor` | Inspect Ollama, hardware, versions, and effective settings | No |
-| `run` | Run a frozen suite against one Ollama build | No |
-| `eval` | Compare the same frozen suite against stock and candidate builds | No |
 
 Run `npx @octocodeai/freellama <command> --help` for every accepted flag and enum value. The executable's help
 is authoritative; this page explains how the commands fit together.
@@ -53,13 +47,16 @@ is authoritative; this page explains how the commands fit together.
 ## Start the control plane
 
 ```bash
-npx @octocodeai/freellama serve --recommendation-catalog recommendations.example.toml
+npx @octocodeai/freellama serve
 ```
 
 The default listener is `http://127.0.0.1:11435`, and the default Ollama upstream is
 `http://127.0.0.1:11434`. Use `--listen` and `--upstream` to change them. Nonloopback listeners
 require `--allow-remote` and a token from `--auth-token-file` or
-`FREELLAMA_AUTH_TOKEN_FILE`. Authentication applies to managed and passthrough routes.
+`FREELLAMA_AUTH_TOKEN_FILE`. Authentication applies to managed and passthrough routes. The token
+file must be a regular file, not a symlink, and hold one token of at least 32 bytes; surrounding
+whitespace is trimmed. On Unix it must also be owner-only (mode 0600). Windows file permissions
+(ACLs) are not checked, so protect the file with your user profile's permissions there.
 
 `serve` persists bounded adaptive feedback under the platform data directory by default. Override
 the path with `--feedback-file`; use `--ephemeral-feedback` only for disposable runs. See the
@@ -81,8 +78,9 @@ npx @octocodeai/freellama serve \
   --cpu-model nomic-embed-text:latest
 ```
 
-FreeLlama rejects a CPU upstream with no assignments, nonloopback upstreams, and endpoints that are
-aliases for the same socket. It also sets `options.num_gpu=0` on CPU-assigned managed requests.
+FreeLlama rejects a CPU upstream with no assignments, `--cpu-model` without `--cpu-upstream`, and a
+CPU upstream that is the same Ollama endpoint as `--upstream`, including loopback aliases on one port.
+It also sets `options.num_gpu=0` on CPU-assigned managed requests.
 Read [CPU and GPU model routing](CPU_GPU_ROUTING.md) before deploying this layout.
 
 After startup, require `contracts.placement_observation` and `placement_evidence_gate`, then inspect
@@ -98,8 +96,8 @@ placement.
 
 ### Bound admission
 
-`--max-concurrent-tasks` is the primary/GPU cost budget, not a request count. Without a flag,
-environment variable, or runtime-file value it defaults to 2 units per `OLLAMA_NUM_PARALLEL` slot of
+`--max-concurrent-tasks` is the primary/GPU cost budget, not a request count. Without a flag or
+runtime-file value it defaults to 2 units per `OLLAMA_NUM_PARALLEL` slot of
 the Ollama server (read from its process environment where visible; Ollama's own default is 1, so 2).
 `freellama config` shows the effective value and where it came from.
 `--cpu-max-concurrent-tasks` controls the independent CPU pool and defaults to 1. Default base costs
@@ -133,27 +131,39 @@ context sizing, can also live in a runtime file (`--runtime-config`) that `serve
 changes. See [Monitoring and live tuning](MONITORING.md). The standalone
 `proxy` command keeps its cap opt-in for compatibility.
 
-The local host-pressure gate defaults to holding below 15% available RAM and resuming above 20%
-after two healthy samples; minimum reserves are 1 GiB and 2 GiB, respectively. Tune the percentages
-with `--resource-hold-available-percent` and `--resource-resume-available-percent`; the hold value
-must be lower than the resume value, and neither can exceed 100. Health reports the policy, sampled
-signals, unknown measurements, and reserved memory. These flags do not change Ollama or OS settings.
-
-The reserve applies to every new managed load, not only to the pressure gate: a task is admitted
-when effective available RAM covers already-reserved bytes, the task's estimated bytes, and the
-reserve (the hold reserve normally; the larger resume reserve while capacity is recovering).
-Effective available RAM is free memory plus a bounded reclaimable estimate, so it can be far lower
-than the OS "free" percentage. A refusal reports `assessment.status: "held_insufficient_capacity"`
-with `required_with_reserve_bytes` and `effective_available_bytes`; free memory, choose a smaller
-model, or lower the percentages deliberately.
+The local host-pressure gate reports low available RAM below 15% and clears it above 20% after two
+healthy samples; minimum reserves are 1 GiB and 2 GiB, respectively. Tune the percentages with
+`--resource-hold-available-percent` and `--resource-resume-available-percent`; the hold value must be
+lower than the resume value, and neither can exceed 100. Health reports the policy, sampled signals,
+unknown measurements, and reserved memory. These flags do not change Ollama or OS settings.
+
+On macOS, low available RAM is advisory and never refuses a task. Effective available RAM is free
+memory plus a bounded reclaimable estimate, so it can be far lower than what the OS can actually
+reclaim. When it does not cover already-reserved bytes, the task's estimated bytes, and the reserve,
+FreeLlama first unloads idle unpinned runners, then dispatches anyway: the receipt reports
+`status: "admitted_low_memory_estimate"` and `assessment.memory_advisory: "below_reserve"` with
+`required_with_reserve_bytes` and `effective_available_bytes`. Ollama and the OS decide whether the
+load fits. On Linux, Windows, and other platforms, where available RAM already counts reclaimable
+cache (and is the hard cap in a container), the same shortfall unloads idle runners and then holds the
+new load with `held_insufficient_capacity` until capacity returns, refusing with 503 at its deadline.
+OS memory pressure holds all work where the OS reports it (macOS, and Linux when the kernel
+exposes `/proc/pressure/memory`; Windows has no host collector yet). Active swapping and low RAM hold new loads only:
+an already-resident runner adds no memory and stays admitted. CPU-load (one-minute load at or above
+1.5 per logical CPU) and thermal-throttling holds apply to CPU-assigned work and to cold loads, which
+decode weights on the host cores and add a new heat source; a bounded request on a runner already
+resident on the GPU neither waits for the cores nor cools the package by waiting, so it proceeds. The receipt's `resource_admission.assessment.held_by`
+lists the holds that applied to the request.
 Both `serve` and `proxy` accept `--resource-telemetry-policy`:
 
-- `require-memory` (default): wait or refuse local inference when available RAM is unknown, including
-  raw requests with zero forecast bytes. Missing thermal data alone does not block this policy.
-- `require-all`: require all signals applicable to the collector. The built-in Linux collector does
-  not provide OS pressure or thermal signals and marks those as unsupported; custom collectors must
-  provide them. Unsupported signals are not evidence of healthy hardware.
-- `best-effort`: explicitly permit unknown telemetry unless an observed pressure hold is active.
+- `require-memory` (default on Linux and macOS): wait or refuse local inference when available RAM is
+  unknown, including raw requests with zero forecast bytes. Missing thermal data alone does not block
+  this policy.
+- `require-all`: require all signals applicable to the collector. The built-in Linux collector reads
+  OS memory pressure from `/proc/pressure/memory` when the kernel provides it, but has no thermal
+  signal and marks it as unsupported; custom collectors must provide it. Unsupported signals are not
+  evidence of healthy hardware.
+- `best-effort`: explicitly permit unknown telemetry unless an observed pressure hold is active. This
+  is the default on Windows, which has no built-in memory collector.
 
 Remote upstreams bypass local host policy. Raw metadata and empty unload requests remain available
 during a hold. Route receipts separate `queue_readiness` from `resource_readiness`, and include
@@ -163,7 +173,7 @@ its phase and omits estimates that were not obtained.
 
 See [resource admission](ARCHITECTURE.md#managed-task-execution) for scope and limitations.
 
-`route`, `recommend`, and `task` accept
+`route` and `task` accept
 `--execution-preference auto|prefer-cpu|prefer-gpu`. This is a fallback-capable hint over models
 already assigned by the operator; it never rewrites raw passthrough and never makes an ineligible
 model eligible. Preview the route and inspect the `execution` receipt to confirm whether the hint
@@ -203,13 +213,6 @@ without them it falls back to capability/context-compatible models and reports l
 and missing quality evidence. `quality` requires a policy unless you supply an explicit model.
 An explicit minimum-confidence gate still refuses insufficient evidence in every objective.
 
-`recommend` is side-effect-free. If no installed model qualifies, it can return an installation
-plan from the reviewed recommendation catalog, but it never pulls a model.
-
-`natural-route` asks the configured local intent model to produce structured intent, validates that
-intent, and then invokes the same deterministic router as `route`. It does not let the intent model
-choose the final model directly.
-
 ## Execute tasks
 
 The prompt for `task` is positional:
@@ -233,6 +236,8 @@ Useful task options include:
 - `--priority interactive|normal|background` for fair admission scheduling.
 - `--max-wait-seconds` for a shorter admission/resource wait budget.
 - `--timeout-seconds` for a total deadline including discovery, waiting, loading, and inference.
+- `--stop-on-repetition` to stream the task and stop once the output repeats itself, keeping all
+  generated text.
 - `--defer` to return a job ID immediately.
 
 Inspect deferred work with `jobs`, retrieve a result with `jobs --id <uuid>`, and cancel one task
@@ -266,7 +271,7 @@ benchmark record for the selected model.
 
 ```mermaid
 flowchart LR
-    Q["Quality evaluation aggregate"] --> P["policy-from-eval"]
+    Q["Quality evaluation aggregate"] --> P["freellama policy from-eval"]
     P --> PF["platform.toml"]
     T["Local throughput benchmark"] --> BR["benchmark-report.json"]
     PF --> S["freellama serve"]
@@ -274,36 +279,62 @@ flowchart LR
     S --> C["Medium confidence for configured, measured routes"]
 ```
 
-Generate the policy from correctness data and the benchmark report from local runtime data:
+Generate the policy from correctness data with `policy from-eval` and the benchmark report from
+local runtime data:
 
 ```bash
-npx @octocodeai/freellama policy-from-eval \
-  --aggregate benchmark/local/results/MODEL/aggregate.json \
+npx @octocodeai/freellama policy from-eval \
+  --aggregate aggregate.json \
   --task coding \
   --min-pass 0.8 \
   --out platform.toml
 
 npx @octocodeai/freellama bench-all --output benchmark-report.json
-npx @octocodeai/freellama serve --recommendation-catalog recommendations.example.toml
+npx @octocodeai/freellama serve
 ```
 
-`serve` discovers `platform.toml` and `benchmark-report.json` in its working directory. Explicit
-`--policy-file` and `--benchmark-report` values take precedence.
+`serve` resolves each file in this order: the explicit flag, its environment variable, the working
+directory, then the per-user config directory (`$XDG_CONFIG_HOME/freellama/` or
+`~/.config/freellama/`; `%APPDATA%\FreeLlama\` on Windows).
 
-Replace `MODEL` with the directory containing your completed quality-evaluation aggregate.
+| File | Flag | Environment variable | Discovered name |
+|---|---|---|---|
+| Task policy | `--policy-file` | `FREELLAMA_POLICY_FILE` | `platform.toml` |
+| Benchmark report | `--benchmark-report` | `FREELLAMA_BENCHMARK_REPORT` | `benchmark-report.json` |
 
-`policy-from-eval` reads `pass_at_1`, not the throughput produced by `bench-all`. It refuses expired
-aggregates and fewer than three trials unless `--allow-smoke` is explicit, and it skips models that
-are not installed. This prevents speed data from being mislabeled as quality evidence.
+A task policy file has this shape:
 
-## Compare the CLI and MCP surfaces
+```toml
+schema_version = 1
 
-```bash
-npx @octocodeai/freellama tools
+[policies.code_repair]
+qualified_models = ["qwen3.8:27b-mlx"]   # best first; quality-qualified only
+
+# Optional request defaults for one exact tag on this task: think and num_predict (>= 1).
+[policies.code_repair.model_options."qwen3.8:27b-mlx"]
+think = false
+num_predict = 512
 ```
 
-The command prints the maintained parity map. MCP-only operations are `delegate_research` and the
-online `models { view: "library" }` view. CLI-only operations include `serve`, `proxy`,
-`recommend`, `natural-route`, `bench-all`, `policy-from-eval`, `run`, and `eval`.
+`serve` rejects unknown fields, including `num_ctx`: context size is routing-owned, so set
+`context_tokens` per request instead. Caller request options win over `model_options`, and
+`think = true` applies only to models with the thinking capability. See the annotated
+[platform.example.toml](https://github.com/bgauryy/FreeLlama/blob/main/platform.example.toml).
+
+The MCP server autostarts `serve` with its own environment and an arbitrary working directory, so
+put a machine-wide policy in the config directory or set the variables in the MCP client's `env`.
+`serve` prints each file it picked up.
+
+`policy from-eval` reads `pass_at_1`, not the throughput produced by `bench-all`. It refuses
+expired aggregates and fewer than three trials unless `--allow-smoke` is explicit, and it skips
+models that are not installed on `--ollama-endpoint` (default `FREELLAMA_OLLAMA_ENDPOINT`, then
+`http://127.0.0.1:11434`). This prevents speed data from being mislabeled as quality evidence.
+It accepts the task kinds `route` accepts, with `-` or `_` (`code-repair` or `code_repair`), writes
+to stdout unless `--out` is given, and reports a refusal as one `error: ...` line with exit status 1.
+
+## Compare the CLI and MCP surfaces
+
+MCP-only operations are `delegate_research` and the online `models { view: "library" }` view.
+CLI-only operations include `serve`, `proxy`, `bench-all`, `policy from-eval`, and `auth-token`.
 
-For the MCP tool contracts, read the [MCP package reference](../packages/mcp/README.md).
+For the MCP tool contracts, read the [MCP package reference](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md).

package/docs/CPU_GPU_ROUTING.md

@@ -9,7 +9,7 @@ memory checks, and model transitions for each backend; the operator configures t
 eligible tags. A configured CPU backend is intent: inspect the placement observation before
 treating it as proof of CPU execution.
 
-This configuration is useful for embeddings, intent interpretation, and other small helper models.
+This configuration is useful for embeddings, short classification, and other small helper models.
 Benchmark large CPU workloads before adopting them. Apple silicon shares memory bandwidth; systems
 with discrete GPUs have different contention and transfer costs, so neither result transfers
 without measurement.
@@ -28,7 +28,9 @@ machine-specific:
 
 `doctor` reports `machine.memory_bytes` on macOS, Linux, and Windows. It reports
 `machine.unified_memory_bytes` only when unified memory is known; that compatibility field is not a
-VRAM estimate on discrete-GPU hosts. Model-library fit is therefore a host-memory preflight, and
+VRAM estimate on discrete-GPU hosts. `machine.gpu` names the accelerator when the OS reports it
+(Apple model and core count, or NVIDIA name and memory on Linux), and `performance_cpus` /
+`efficiency_cpus` split hybrid CPUs on macOS. These are identity facts, not placement proof. Model-library fit is therefore a host-memory preflight, and
 actual accelerator placement must come from Ollama's resident-runner report.
 
 An agent can choose `auto`, `prefer_cpu`, or `prefer_gpu`, but it cannot invent topology. The
@@ -54,7 +56,7 @@ flowchart TB
     CP --> CPU["CPU runner"]
 ```
 
-FreeLlama does not inspect or rewrite raw passthrough request bodies. A direct Ollama client that
+FreeLlama does not rewrite raw passthrough request bodies or route them by model. A direct Ollama client that
 needs model-aware CPU placement must use the managed task endpoint instead.
 
 ## Start the backends
@@ -115,7 +117,7 @@ unsafe or ambiguous configurations:
 - A CPU model assignment without `--cpu-upstream`
 - Empty model names
 - The same socket expressed through aliases such as `localhost:11434` and `127.0.0.1:11434`
-- A nonloopback upstream
+- An upstream that points back to the FreeLlama listener, or an unspecified host such as `0.0.0.0`
 
 A nonloopback FreeLlama listener requires `--allow-remote` and bearer-token authentication.
 See the [production runbook](PRODUCTION.md) for remote ingress requirements.
@@ -214,7 +216,7 @@ curl --silent http://127.0.0.1:11436/api/ps | jq '.models[] | {name, size, size_
 A fully CPU-loaded model reports `size_vram:0`; a fully GPU-loaded model reports positive VRAM
 covering its resident `size`. Compare both values from the same `/api/ps` entry. Installed `/api/tags`
 file bytes can differ from resident memory and cannot prove a mixed placement. Positive VRAM without
-total resident size stays unknown. `observation.status` is `verified`, `mismatch`, or unavailable. Unknown, mixed, and mismatched
+total resident size stays unknown. `observation.status` is `verified`, `mismatch`, `not_resident`, or `unavailable`. Unknown, mixed, and mismatched
 samples are reported but excluded from adaptive feedback.
 
 ## Understand concurrency
@@ -250,17 +252,18 @@ FreeLlama can overlap requests across the two servers even when each Ollama proc
 `OLLAMA_NUM_PARALLEL=1`. Raising `OLLAMA_NUM_PARALLEL` affects parallel requests within one server
 and multiplies K/V-cache memory; it is a separate tuning decision. `OLLAMA_MAX_QUEUE` likewise
 bounds each Ollama process after FreeLlama admission. It does not replace either backend's weighted
-FreeLlama budget, bounded waiter count, or queue-wait deadline. Raw passthrough uses a separate
-one-stream default cap in `serve`; its permit is held until the streamed response ends or is dropped.
+FreeLlama budget, bounded waiter count, or queue-wait deadline. Raw generation passthrough uses a
+separate one-stream default cap in `serve`; its permit is held until the streamed response ends or is dropped.
 
 The runtime file's `[task_costs]` table can tune individual task-kind weights without increasing
 the entire pool's ceiling. Default vision weight four can serialize two vision requests under a
 four-unit budget even when Ollama has two slots. A lower weight requires a qualified workload;
 it does not add engine slots or relax memory checks. See
 [monitoring controls](MONITORING.md#adaptive-concurrency).
-Mutating raw requests also require exclusive access to the primary backend's managed transition
-lock and receive 503 while it is busy. Metadata GET/HEAD calls remain available. This prevents raw
-inference or model lifecycle calls from overlapping a managed generation on that backend.
+Raw generation requests also require exclusive access to the primary backend's managed transition
+lock and receive 503 if it stays busy past the raw queue wait. Metadata GET/HEAD, `/api/show`,
+model-store calls (pull, push, copy, delete), and empty `keep_alive:0` unloads remain available.
+This prevents raw inference from overlapping a managed generation on that backend.
 
 ## Understand automatic feedback
 
@@ -352,7 +355,6 @@ and `execution.lifecycle`; a failed unload is reported without discarding the co
 Prefer the following assignments:
 
 - Small embedding models
-- Lightweight intent models
 - Short extraction or classification helpers with measured CPU behavior
 
 Benchmark these assignments before adopting them:
@@ -381,9 +383,8 @@ A configured but unreachable CPU backend causes model discovery to fail closed.
 can also be unavailable until the secondary server returns. Raw passthrough to the primary server
 continues to work because it does not depend on catalog discovery.
 
-For the surrounding runtime settings, see
-[Ollama and FreeLlama optimization](dev/OLLAMA_SYSTEM_OPTIMIZATION.md). For all `serve` flags, see the
-[CLI reference](CLI.md).
+For the surrounding Ollama settings, see [Production](PRODUCTION.md#configure-ollama-explicitly). For
+all `serve` flags, see the [CLI reference](CLI.md).
 
 ## Upstream sources
 

package/docs/MODEL_SELECTION.md

@@ -10,8 +10,7 @@ are not compiled into routing. Re-run
 `doctor.machine.memory_bytes` is host RAM; a discrete GPU's usable VRAM must be observed separately.
 
 For supported features and sourced publisher use-case guidance, inspect
-`models {view:"installed", includeLibrary:true}` through MCP. The
-[Ollama metadata reference](MODEL_METADATA.md) explains digest matching, variant capabilities,
+`models {view:"installed", includeLibrary:true}` through MCP. [Model metadata](#model-metadata) explains digest matching, variant capabilities,
 custom-model fallbacks, and how to read family claims without treating them as quality measurements.
 
 ```mermaid
@@ -33,10 +32,16 @@ flowchart TD
 grounded research, image description, OCR, and summarization. Using one large multimodal model also
 avoided contention between separate heavy text and vision runners.
 
-Read the [retained model profile](../skills/freellama/references/model-profile-qwen3.8-27b-mlx.md)
-and [delegation measurements](../skills/freellama/references/task-delegation.md) for scope and limits.
+In those evaluations it was strong at grounded lookup, long-context retrieval and strict instruction
+following, needed `think:true` and a generous output budget for multi-step reasoning, and about a
+third of its unsupervised code-review findings were false or context-limited.
 These examples do not establish that a tag is installed or suitable on your host.
 
+Dedicated OCR models answer best to the prompts their model card documents; send them with base64
+`images` in `run_task`. A model that repeats its answer until the output cap can run with
+`stopOnRepetition:true`. See [Route images](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md#route-images)
+for the early stop and the `output_check` receipt.
+
 `muse-glimmer:30b-mlx` was a credible alternative and answered 29 of 30 questions correctly
 (96.7%) with the Bash adapter, but it was slower and did not add a required capability in this
 workload.
@@ -61,7 +66,7 @@ keywords, repository search was both faster and more accurate in the measured sa
 
 ## Place helper models on CPU when useful
 
-A small embedding or intent model can be assigned to a second CPU Ollama process while a large
+A small embedding or helper model can be assigned to a second CPU Ollama process while a large
 generation model remains resident on the primary GPU-capable process. This can overlap independent
 work, but it does not make CPU inference fast. Apple silicon shares memory bandwidth; discrete-GPU
 systems have different transfer and contention costs and need their own benchmark.
@@ -76,3 +81,109 @@ this machine and workload, not a universal model-placement rule. Follow
 `bench-all` measures local performance. A quality benchmark measures correctness. FreeLlama needs
 both the generated task policy and local benchmark data before grading a route medium confidence.
 See the [CLI reference](CLI.md#earn-medium-routing-confidence) for the commands.
+
+## Model metadata
+
+The MCP `models` tool reads your Ollama instance and can enrich results with Ollama's public model
+library. Supported features and advertised use cases are metadata: they do not change routing
+confidence, and exact-model benchmarks and policy remain the quality evidence. The CLI's `models`
+command reports the core catalog and does not expose these enrichment flags.
+
+| Request | Result | External access |
+|---|---|---|
+| `models {view:"installed"}` | Managed inventory with a `knowledge` object for each model | Local backend data only |
+| `models {view:"installed", includeLibrary:true}` | Inventory enriched with public guidance for verified local tags | Fetches model family and tag pages from ollama.com |
+| `models {view:"detail", model:"gemma3:1b"}` | Ollama details, maximum context, and supported-use explanations | Selected Ollama endpoint only |
+| `models {view:"detail", model:"gemma3:1b", includeLibrary:true}` | Details plus public guidance after a tag and digest check | Selected Ollama endpoint and ollama.com |
+| `models {view:"library", query:"coding"}` | Public family search with descriptions and advertised feature chips | ollama.com and optional local inventory/profile reads |
+| `models {view:"library", model:"gemma3"}` | All public tags with size, digest prefix, context, modalities, and cloud status | ollama.com and optional local inventory/profile reads |
+
+
+| Option | Valid views | Default | Meaning |
+|---|---|---|---|
+| `includeLibrary` | `installed`, `detail` | `false` | Requests public metadata; the default makes no website calls |
+| `includeReadme` | Library step 2, or `detail` with `includeLibrary:true` | `false` | Returns README text, capped at 65,536 characters, with its format and truncation flag |
+| `includeVerbose` | `detail` | `false` | Returns Ollama's license and Modelfile fields independently of README enrichment |
+| `limit`, `cursor` | `raw`, library tag listings; `limit` also applies to library search | Tag/raw page size 20; search limit 10 | Pages large lists; the tag cursor rejects a changed tag list |
+| `ollamaEndpoint` | Direct Ollama views and library inventory reads | Configured Ollama endpoint | Chooses the Ollama instance; enriched managed inventory uses each model's assigned backend |
+
+An incompatible option returns an error before any lookup. Installed enrichment omits full READMEs;
+request one model's detail to read its README.
+
+### Supported features
+
+`knowledge.supportedFeatures` preserves the feature strings from the selected source
+(`supportedFeaturesSource`: `ollama_api` or `freellama_catalog`). Unknown future strings stay visible
+but do not create routing requirements. `knowledge.supportedUseCases` explains each recognized
+feature with `capability`, `use`, `reason`, and `basis:"supported_feature"`;
+`knowledge.quality` stays `"metadata_only"`.
+
+| Feature | Supported workflow | What to evaluate separately |
+|---|---|---|
+| `completion` | Text generation | Coding, summarization, reasoning, and instruction-following accuracy |
+| `tools` | Tool calls | Argument correctness, tool selection, and agent-loop reliability |
+| `vision` | Image input | OCR and visual understanding accuracy |
+| `audio` | Audio workflows advertised by the model | Supported audio task and accuracy |
+| `embedding` | Retrieval and similarity vectors | Retrieval quality on your documents |
+| `thinking` | A thinking mode | Reasoning accuracy, latency, and token cost |
+| `insert` | Suffix-based text insertion | Completion accuracy in the target code or text |
+| `image` | Image generation | Output quality and supported controls |
+
+
+### Public guidance and provenance
+
+For a verified installed model, `knowledge.library` contains the source page, tag-page URL,
+`fetchedAt`, `expiresAt`, `cached`, exact public tag metadata, and:
+
+| Field | Meaning |
+|---|---|
+| `description` | The public family description |
+| `advertisedFamilyCapabilities` | Family feature chips; these do not extend the local tag's capabilities |
+| `advertisedUseCases` | Recognized coding, tool-calling, image-understanding/OCR, reasoning, embedding, summarization, question-answering, translation, and long-context claims |
+| `advertisedUseCases[].evidence` | A bounded source excerpt, source URL, and fetch timestamp |
+| `usageNotes` | Bounded excerpts about requirements, restrictions, context, memory, languages, or query prefixes |
+| `readmeAvailable` | Whether a README was extracted |
+| `readme` | Requested text with `format` (`markdown` or `text`) and `truncated` |
+
+
+Advertised uses have `basis:"advertised"`, `scope:"family"`, and `quality:"unmeasured"`. Extraction
+skips fenced code and negative statements; an omitted use means no recognized claim, not absence.
+These labels are not the `run_task` task enum. Local capabilities filter advertised uses: a family
+vision chip cannot make `gemma3:1b` a vision candidate.
+
+Installed enrichment requires the exact public tag and a digest-prefix match of at least 12 hex
+characters. Custom names are never mapped by architecture or guessed base model; without a verified
+match, public guidance is withheld. Library step 2 describes public models before installation, so
+its guidance stays family-scoped; each `tags[]` entry carries its own modalities, context, digest
+prefix, and `cloud` flag. Search's `cloudAvailable` badge does not prove local downloads are absent.
+
+### Lookup states
+
+| `library.status` | Meaning | Next action |
+|---|---|---|
+| `not_requested` | Website enrichment was not requested | Set `includeLibrary:true` if external lookup is useful |
+| `matched` | Installed tag and public digest prefix match | Read the sourced guidance, then evaluate the exact tag |
+| `available` | Public family and tag pages were parsed in library step 2 | Inspect the exact tag before recommending a download |
+| `unverified` | Digest or current backend inventory could not be verified | Recheck local inventory; retain local feature information |
+| `digest_mismatch` | The public tag differs from the installed digest | Treat public guidance as unavailable for this installed model |
+| `tag_not_found` | The parsed public tag list has no exact matching tag | Check the source and custom-model provenance |
+| `unmatched` | The name cannot resolve to an exact public Ollama name | Keep use-case suitability unknown until provenance is verified |
+| `not_found` | A requested public page returned HTTP 404 | Check the source URL or custom name |
+| `unavailable` | Transport, timeout, HTTP refusal, or page-size limit prevented lookup | Retry later; local results remain available |
+| `parse_error` | HTML content or tag rows were not recognized | Inspect the source; do not conclude the model is absent |
+| `remote_model`, `remote_tag` | Remote Ollama fields or a hosted tag identify cloud execution | Select a local download tag for local execution |
+
+
+`localModel:false` flags detected remote entries; cloud tags never become local trial
+recommendations. This metadata is not processor-placement evidence.
+
+### Cache and request bounds
+
+Each MCP process caches at most 128 families: successes for one hour, failures for one minute;
+concurrent requests share one lookup and a restart clears the cache. Installed enrichment runs at
+most four family lookups concurrently. Requests use GET, refuse redirects, cap each page at 2 MiB,
+and time out after the smaller of 10 seconds and `FREELLAMA_MCP_FETCH_TIMEOUT_SECONDS`. They disclose
+the requested public family name to ollama.com. Download size does not establish runtime memory
+fit, placement, or quality, and model discovery never authorizes a pull. Sources:
+[model details API](https://docs.ollama.com/api-reference/show-model-details),
+[model-list API](https://docs.ollama.com/api/tags).

package/docs/MONITORING.md

@@ -38,7 +38,9 @@ token and keeps it only for the browser tab.
   whether the model is pinned.
 - **`host`**: available and reserved RAM, whether the pressure gate is holding, and discrete-GPU
   total and free memory (`nvidia-smi` or amdgpu sysfs) when available. Optional `gpu_activity`
-  reports driver counters separately from resident memory.
+  reports driver counters separately from resident memory. On macOS, `thermal_pressure` is the
+  system thermal pressure level (`nominal`, `moderate`, `heavy`, `trapping`, `sleeping`); `heavy`
+  or worse holds CPU-assigned work and cold loads. Other platforms report `null`.
 - **`ollama`**: the Ollama server's effective `OLLAMA_*` settings with a source for each — the
   running process's environment (Linux `/proc/<pid>/environ`, macOS `ps eww` for a same-user
   process), `launchctl getenv` for the macOS app, FreeLlama's own environment, or Ollama's default.
@@ -72,7 +74,8 @@ FreeLlama admission limits remain governed by its runtime configuration.
 
 `host.gpu_activity` is nullable. When available, it identifies its `source`,
 `scope: "observed_devices_all_processes"`, `window: "driver_defined"`, and individual `devices`.
-Each device has an identity, nullable `busy_percent`, and nullable `memory_busy_percent`.
+Each device has an identity, nullable `busy_percent`, and nullable `memory_busy_percent`. Apple
+devices may add `allocated_memory_bytes`, the driver's allocated memory across all processes.
 An observed zero means the driver reported zero; a missing or malformed counter remains unknown.
 Use `host.sample_age_ms` to check freshness.
 
@@ -115,8 +118,9 @@ The ledger lives next to the feedback file in the platform data directory. Choos
 `/metrics` exposes counters (`freellama_tasks_total`, `freellama_prompt_tokens_total`,
 `freellama_output_tokens_total`, `freellama_task_seconds_total`, `freellama_queue_wait_seconds_total`,
 `freellama_load_seconds_total`, `freellama_raw_requests_total`, `freellama_evictions_total`,
-`freellama_circuit_open_total`, `freellama_concurrency_limit_changes_total`) labelled by model,
-backend, task, and outcome, plus gauges for admission, queues, the raw proxy, host and GPU memory,
+`freellama_circuit_open_total`, `freellama_concurrency_limit_changes_total`); task counters are
+labelled by model, backend, task, and outcome, raw requests by kind and outcome, and the rest by
+backend. Gauges cover admission, queues, the raw proxy, host and GPU memory,
 loaded models, and `freellama_ollama_num_parallel`. Point Prometheus, Grafana Agent, or any
 OpenMetrics-compatible scraper at it.
 
@@ -129,12 +133,13 @@ FreeLlama waits for safe capacity within a deadline and bounds the retained back
 | Managed queue full | `429` | `admission_queue_full` |
 | Raw proxy over its cap after `raw_queue_wait_seconds` | `429` | |
 | Managed wait exceeded `max_queue_wait_seconds` (or the task's `max_wait_seconds`) | `503` | `admission_timeout` |
-| Host resources remain held when the waiting budget expires | `503` | `resource_admission_unavailable` |
+| OS pressure, swapping, CPU, thermal, or required telemetry still holds when the waiting budget expires (low available RAM alone only warns on macOS; low RAM and swapping never hold an already-resident runner, and CPU load and thermal never hold one on the GPU) | `503` | `resource_admission_unavailable` |
 | Backend circuit open | `503` | `upstream_circuit_open` |
 
 These capacity refusals carry a `Retry-After` header and `retry_after_seconds` in the body. For a queue it
-is estimated from the queue depth, the current limit, and the backend's recent average task time
-(1 to 120 seconds). A task can ask for a shorter wait with `max_wait_seconds` (`maxWaitSeconds`
+is estimated from the queue depth, the lanes that can run at once (current limit divided by the
+task's cost), and the backend's recent average service time, which excludes queue wait (1 to 120
+seconds). A task can ask for a shorter wait with `max_wait_seconds` (`maxWaitSeconds`
 in MCP); the server caps it at the configured maximum.
 
 ## Circuit breaker
@@ -166,7 +171,7 @@ costs, and execution receipts use the resolved policy. Health retains its summar
 exposes the complete task-kind map under `admission.costs.base_by_task`. Task kinds remain
 caller-declared; these weights are cooperative scheduling policy, not workload classification.
 See the
-[runtime example](../freellama.runtime.example.toml) for the table syntax.
+[runtime example](https://github.com/bgauryy/FreeLlama/blob/main/freellama.runtime.example.toml) for the table syntax.
 
 With `adaptive_concurrency = "cpu"` (the default) or `"all"`, each pool's limit moves between 1 and
 its configured ceiling:
@@ -263,9 +268,10 @@ out-of-memory shrink-and-retry only applies when the context was not requested e
 
 With `context_mode = "ollama_default"` (the default), FreeLlama sizes the context as before but
 omits `num_ctx` when Ollama's own default for the model is known, covers the request, and is at most
-`auto_context_max` (32768). The default is resolved in Ollama's order: the Modelfile's `num_ctx`,
-then `OLLAMA_CONTEXT_LENGTH`, then (discrete GPU only) Ollama's VRAM tier — 4096 below 24 GiB, 32768
-below 48 GiB, 262144 above. Receipts show `context_sizing.num_ctx_sent` and the default used.
+`auto_context_max` (32768). The default is the Modelfile's `num_ctx`, then the
+runtime file's `ollama_default_context`, then `OLLAMA_CONTEXT_LENGTH`, then (primary backend
+on a discrete GPU only) Ollama's VRAM tier, from total VRAM minus `OLLAMA_GPU_OVERHEAD` — 4096 below
+23 GiB, 32768 below 47 GiB, 262144 from 47 GiB. Receipts show `context_sizing.num_ctx_sent` and the default used.
 Memory estimates always use the context Ollama can allocate. Use `"explicit"` to always
 send `num_ctx`.
 
@@ -273,13 +279,17 @@ send `num_ctx`.
 
 Put any of the settings above in a TOML file and start `serve --runtime-config <file>` (or set
 `FREELLAMA_RUNTIME_CONFIG`). Start from
-[`freellama.runtime.example.toml`](../freellama.runtime.example.toml). `serve` checks the file every
+[`freellama.runtime.example.toml`](https://github.com/bgauryy/FreeLlama/blob/main/freellama.runtime.example.toml). `serve` checks the file every
 two seconds and applies changes to live admission pools; a waiting task sees the new limit at once.
 
-Precedence for every setting, strongest first: CLI flag, `FREELLAMA_*` environment variable, the
-runtime file, the built-in default. A flag or variable pins a value, so editing the file cannot
-override it; `freellama config` shows which source won. A malformed file or an unknown key is
-rejected at reload and the previous values stay in force.
+Precedence for every setting, strongest first: CLI flag, environment variable (where one exists),
+the runtime file, the built-in default. Only these settings have an environment variable:
+`FREELLAMA_MAX_QUEUE_WAIT_SECONDS`, `FREELLAMA_EVICT_IDLE_MODELS`, `FREELLAMA_USAGE_QUEUE_CAPACITY`,
+and the individual `FREELLAMA_SCOPE_*` and `FREELLAMA_KEEP_ALIVE_*` limits. Set every other key in
+the runtime file or with its CLI flag. A flag or variable pins a value, so editing the file cannot
+override it; `freellama config` shows which source won: `cli`, `env`, `file`, a default source
+such as `default` or `ollama_num_parallel`, or `env_invalid` when a set variable failed validation.
+A malformed file or an unknown key is rejected at reload and the previous values stay in force.
 
 The default GPU budget follows the Ollama server: 2 units per `OLLAMA_NUM_PARALLEL` slot (one chat
 per decoding slot), read from the running Ollama process where visible.