@octocodeai/freellama-mcp-server 0.1.0 → 0.5.0

package/docs/CPU_GPU_ROUTING.md

@@ -1,8 +1,13 @@
 # Run models on CPU and GPU
 
-Use two Ollama processes when a large model should remain on the GPU while smaller helper models run
-on the CPU. FreeLlama assigns exact model tags to the secondary process, pins those managed requests
-with `num_gpu: 0`, and reports the selected backend in catalog and task responses.
+To separate GPU work from CPU helpers, configure two Ollama processes and assign exact helper-model
+tags to the secondary process. FreeLlama routes managed tasks within those assignments, applies
+`num_gpu: 0` to CPU requests, and reports both the selected backend and observed processor placement.
+
+The calling agent submits tasks and placement preferences. FreeLlama coordinates admission,
+memory checks, and model transitions for each backend; the operator configures the processes and
+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.
 Benchmark large CPU workloads before adopting them. Apple silicon shares memory bandwidth; systems
@@ -110,7 +115,10 @@ 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 non-loopback listener or upstream
+- A nonloopback upstream
+
+A nonloopback FreeLlama listener requires `--allow-remote` and bearer-token authentication.
+See the [production runbook](PRODUCTION.md) for remote ingress requirements.
 
 Set independent admission budgets when the defaults do not fit the workload:
 
@@ -120,13 +128,18 @@ Set independent admission budgets when the defaults do not fit the workload:
     --cpu-upstream http://127.0.0.1:11436 \
     --cpu-model nomic-embed-text:latest \
     --max-concurrent-tasks 2 \
-    --cpu-max-concurrent-tasks 1
+    --cpu-max-concurrent-tasks 1 \
+    --max-queued-tasks 16 \
+    --cpu-max-queued-tasks 8
 ```
 
 The defaults above admit one ordinary primary-backend chat (cost 2) and one CPU embedding (cost 1)
 at the same time. They are conservative workload units for the common `OLLAMA_NUM_PARALLEL=1`
 layout, not a profile of the development Mac. Increase them only after measuring queue wait,
 resident memory, and Ollama's own parallel setting on the target host.
+Queue cardinality and wait time are separate bounds: excess waiters are refused immediately, while
+an admitted waiter may remain until `--max-queue-wait-seconds`. Automatic backend selection checks
+that the actual task cost fits the current slot snapshot before following historical speed.
 
 ## Let an agent express placement intent
 
@@ -194,12 +207,14 @@ The `execution` object separates the configured `backend`, requested compatibili
 post-run `observation`. The source is Ollama `/api/ps`; direct inspection remains useful:
 
 ```bash
-curl --silent http://127.0.0.1:11434/api/ps | jq '.models[] | {name, size_vram}'
-curl --silent http://127.0.0.1:11436/api/ps | jq '.models[] | {name, size_vram}'
+curl --silent http://127.0.0.1:11434/api/ps | jq '.models[] | {name, size, size_vram}'
+curl --silent http://127.0.0.1:11436/api/ps | jq '.models[] | {name, size, size_vram}'
 ```
 
-A fully CPU-loaded model reports `size_vram:0`; a fully GPU-loaded model reports positive resident
-VRAM. `observation.status` is `verified`, `mismatch`, or unavailable. Unknown, mixed, and mismatched
+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
 samples are reported but excluded from adaptive feedback.
 
 ## Understand concurrency
@@ -208,10 +223,16 @@ Each backend has its own weighted admission pool and its own resident/shared and
 transition/exclusive lock. CPU and GPU model transitions therefore do not block each other, and a
 GPU burst cannot spend the CPU helper's permit:
 
+Both pools also share local host-pressure sampling and forecast-memory reservations. Independent
+queues do not imply independent RAM on a unified-memory machine. A request can wait for available
+headroom even when its backend has a free weighted permit. Inspect `admission.resources` in health
+and `execution.resource_admission` in task receipts. Unknown thermal or GPU measurements are not
+reported as healthy readings. See [the execution architecture](ARCHITECTURE.md) for the complete gate.
+
 ```mermaid
 flowchart TD
     T["Managed task"] --> B{"Selected backend"}
-    B -->|"GPU"| GA["GPU admission pool<br/>default 2 units"]
+    B -->|"GPU"| GA["GPU admission pool<br/>default 2 units per Ollama slot"]
     B -->|"CPU"| CA["CPU admission pool<br/>default 1 unit"]
     GA --> GL{"Resident?"}
     CA --> CL{"Resident?"}
@@ -229,16 +250,28 @@ 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 or queue-wait deadline.
+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.
+
+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.
 
 ## Understand automatic feedback
 
 With `executionPreference: "auto"`, unpinned `fastest` and `balanced` work can select a backend from
-observed warm task duration. The loop is deliberately bounded:
+comparable observed warm task duration. Learned hints require two eligible backends, explicit
+context, and a known execution payload-control projection. A decision-only preview cannot supply
+that payload projection and uses capacity and policy signals. The loop is bounded:
 
 ```mermaid
 flowchart LR
-    X["Successful resident task"] --> O["Record duration by<br/>task + backend"]
+    X["Comparable warm serial task"] --> O["Record duration by<br/>task + backend + profile"]
     O --> N{"At least 3 samples<br/>on both backends?"}
     N -->|"No"| D["Keep deterministic default"]
     N -->|"Yes"| C{"More than 10% faster<br/>per work unit?"}
@@ -248,13 +281,25 @@ flowchart LR
 ```
 
 Generation compares decode nanoseconds per output token; embeddings compare total nanoseconds per
-input token. Buckets are model-specific and reset when the selected model changes. Only physically
-verified placement contributes; cold transitions and assignment mismatches do not. A difference
+input token. Each task/backend has one current profile window, reset when identity changes.
+Identity includes installed/resident digest, rate metric kind, explicit observed context, effective controls,
+endpoint-attributed process settings, and serial admission class. Unknown or changed evidence,
+cold transitions, and overlapping managed work supply no speed sample. A difference
 of 10% or less is treated as noise. Feedback never overrides an explicit model, session affinity,
 capability or policy guards, or the `quality` objective. The CLI persists the bounded, versioned,
-prompt-free aggregate snapshot atomically by default; `--ephemeral-feedback` opts into reset-on-
-restart behavior. `GET /_freellama/v1/health` exposes persistence status, sample counts, readiness,
-and per-backend admission capacity so an agent can inspect the loop instead of guessing.
+prompt-free snapshot atomically by default; `--ephemeral-feedback` opts into reset-on-restart
+behavior. Legacy aggregate fields survive loading but do not qualify learned hints. Health's
+`decision_ready` describes the stored profile window; the current request must independently
+match it before routing can use its speed. `GET /_freellama/v1/health` exposes profile identity,
+profile sample counts, persistence status, and per-backend admission capacity. Physically verified
+warm completions still contribute legacy duration diagnostics even when their interval cannot
+qualify a speed-learning sample.
+
+Configured processor intent, verified placement, and speed-learning eligibility remain separate
+receipt fields. Missing endpoint-attributed process inspection disables learned hints and recovery,
+including remote backends; ordinary routing, admission, and pressure/error safeguards still work.
+Fresh process probes run for candidate serial learning or an eligible learned-route lookup, not
+for pinned, quality-only, preview-only, or single-backend route selection.
 
 ## Interpret the measured Mac result
 
@@ -318,7 +363,7 @@ Benchmark these assignments before adopting them:
 
 The local measurement receipt is written to
 `.octocode/evals/cpu-gpu-concurrency-benchmark.md`. Git intentionally ignores that path, so the
-trial table in "Interpret the measured result" carries the durable result while the local artifact
+trial table in ["Interpret the measured Mac result"](#interpret-the-measured-mac-result) carries the durable result while the local artifact
 retains the full run detail.
 
 ## Troubleshoot the secondary backend
@@ -337,7 +382,7 @@ can also be unavailable until the secondary server returns. Raw passthrough to t
 continues to work because it does not depend on catalog discovery.
 
 For the surrounding runtime settings, see
-[Ollama and FreeLlama optimization](OLLAMA_SYSTEM_OPTIMIZATION.md). For all `serve` flags, see the
+[Ollama and FreeLlama optimization](dev/OLLAMA_SYSTEM_OPTIMIZATION.md). For all `serve` flags, see the
 [CLI reference](CLI.md).
 
 ## Upstream sources

package/docs/ECONOMICS.md

@@ -1,8 +1,11 @@
 # Token economics
 
-This reference keeps benchmark detail out of the README's "what, why, and run it" path. The
-per-call rows come from one machine (M4 Pro, 48 GB unified memory); values marked with `~` and the
-session projection are estimates derived from those calls.
+Offloading can keep source material and intermediate tool output out of the calling agent's
+context. FreeLlama returns compact results while the local model performs the work. This shifts
+computation to local hardware; it does not eliminate model tokens, power use, or waiting time.
+
+The per-call rows come from one machine (M4 Pro, 48 GB unified memory). Values marked with `~`
+and the session projection are estimates derived from those calls.
 
 ## Per-call, measured
 
@@ -13,13 +16,13 @@ session projection are estimates derived from those calls.
 | 1 image, OCR, byte-exact | 1,970 | 37 | **98.1%** |
 | Historical tool-schema surface, per turn | <3.2k | 0 | **100%** |
 
-## Current MCP-envelope audit (2026-09-03)
+## MCP-envelope audit (2026-09-03)
 
-The earlier table describes a historical workload on an M4 Pro. This audit measures the current
-eight-tool MCP build on the current host. JSON tokenization varies by client and model, so it records
+The earlier table describes a historical workload on an M4 Pro. This dated audit measured the
+eight-tool MCP build available on September 3, 2026. JSON tokenization varies by client and model, so it records
 bytes first and gives `characters / 4` only as a deliberately rough token estimate.
 
-| Current result | Canonical structured chars | Compact text chars | Duplicate chars avoided | Rough duplicate-token estimate |
+| Audited result | Canonical structured chars | Compact text chars | Duplicate chars avoided | Rough duplicate-token estimate |
 |---|---:|---:|---:|---:|
 | `doctor {view:"summary"}` | 3,099 | 35 | 3,064 | ~766 |
 | `doctor {view:"scheduler"}` | 3,933 | 35 | 3,898 | ~975 |
@@ -32,9 +35,11 @@ that FreeLlama does not emit. An MCP host that feeds both `structuredContent` an
 can avoid roughly the listed amount; a host that already keeps only one representation does not.
 The canonical structured payload still exists for deterministic clients that need it.
 
-The current eight-tool schema plus initialization instructions measured 17,935 characters, or
-~4,484 tokens using the same rough conversion. The integration suite enforces a ceiling below 4,500
-estimated tokens. This is tool-schema **rent**, not a saving: clients pay it whenever they expose
+The integration suite bounds the complete tool schema and initialization instructions using
+the same rough token conversion. Read the
+[protocol context-budget contract](../packages/mcp/test/integration/protocol.test.ts) for the
+enforced ceiling.
+This is tool-schema **rent**, not a saving: clients pay it whenever they expose
 the entire tool list to a model. Read the bundled documentation resource on demand and do not expose
 unneeded tools in a client that supports tool filtering.
 
@@ -64,11 +69,11 @@ because prompt caching makes cached input far cheaper,
 and because the rent only accrues at all if a *separate* small model holds the tool schemas. The
 first two rows are the uncontestable part: that data physically never reaches the orchestrator.
 
-**Do not lead with this number.** Providers, caching strategies, context windows, and pricing all
-move, and a token count moves with them. The durable benefit is **context isolation** — the
-orchestrator never receives whole files, raw vectors, OCR output, intermediate research, or
-repetitive schemas. That improves context *quality* as well as cost, and it does not depend on
-anyone's price list.
+**Do not lead with this number.** Providers, caching strategies, context windows, and pricing
+change. The durable benefit is context isolation: delegated research returns an answer and
+citations in place of its full local transcript, and embedding responses omit vectors by default.
+Caller-requested output and exposed tool schemas still enter the client's context. Measure that
+client's actual transcript before claiming a token or billing reduction.
 
 ## The cost side
 

package/docs/INDEX.md

@@ -2,14 +2,20 @@
 
 Read only the document relevant to the current operation. Repository `docs/` is the source of truth.
 
-- [ADR: Resource-aware backend routing](ADR_RESOURCE_AWARE_BACKEND_ROUTING.md)
 - [FreeLlama architecture](ARCHITECTURE.md)
 - [CLI reference](CLI.md)
 - [Run models on CPU and GPU](CPU_GPU_ROUTING.md)
 - [Token economics](ECONOMICS.md)
+- [Ollama model metadata](MODEL_METADATA.md)
 - [Choose local models](MODEL_SELECTION.md)
+- [Runtime status and live tuning](MONITORING.md)
 - [Ollama sidecar boundary](OLLAMA_SIDECAR.md)
-- [Ollama and FreeLlama optimization boundary](OLLAMA_SYSTEM_OPTIMIZATION.md)
 - [Prepare FreeLlama for production](PRODUCTION.md)
 - [Product positioning](PRODUCT_POSITIONING.md)
+- [FreeLlama documentation](README.md)
+- [Scope history and model warming](SCOPES_AND_WARMING.md)
 - [Test FreeLlama](TESTING.md)
+- [ADR: Resource-aware backend routing](dev/ADR_RESOURCE_AWARE_BACKEND_ROUTING.md)
+- [FreeLlama findings and open-source comparison](dev/FINDINGS_AND_POSITIONING.md)
+- [Test throughput, CPU/GPU activity, and thermal behavior on macOS](dev/LOCAL_PERFORMANCE_TESTING.md)
+- [Ollama and FreeLlama optimization boundary](dev/OLLAMA_SYSTEM_OPTIMIZATION.md)

package/docs/MODEL_METADATA.md

@@ -0,0 +1,106 @@
+# Ollama model metadata
+
+The MCP `models` tool gives an agent the inventory and capability metadata it needs before
+offloading work. It reads your Ollama instance and can enrich results with descriptions from
+Ollama's public model library. Supported features and advertised use cases are metadata;
+exact-model benchmarks and policy supply quality evidence. Public descriptions do not change
+routing confidence, and a successful response still needs task-specific verification.
+
+## Requests
+
+| 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 |
+
+These are MCP tool requests. The CLI's `models` command reports the core catalog and does not expose these enrichment flags. For CLI setup and routing, see the [CLI reference](CLI.md).
+
+| 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 to keep inventory responses bounded; request one model's detail to read its README.
+
+## Supported features
+
+`knowledge.supportedFeatures` preserves the feature strings available from the selected source. `supportedFeaturesSource` is `ollama_api` for direct Ollama metadata and `freellama_catalog` for the managed catalog. The catalog contains normalized routing capabilities; unknown future strings remain visible in `detail`, `raw`, or enriched installed inventory when Ollama's tag response supplies them. Unknown strings do not create new routing requirements.
+
+`knowledge.supportedUseCases` explains each recognized feature:
+
+| 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 |
+
+Each explanation contains its `capability`, `use`, `reason`, and `basis:"supported_feature"`. Ollama runtime/version support still applies. The inventory's existing benchmark and policy fields remain separate from `knowledge.quality:"metadata_only"`.
+
+## Public guidance and provenance
+
+For a verified installed model, `knowledge.library` contains the source page, full tag-page URL, `fetchedAt`, `expiresAt`, `cached`, and exact public tag metadata. It also contains:
+
+| 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 recognizes positive prose mentions and skips fenced code and explicit negative statements. It is a discovery aid, not a complete classification: an omitted use means extraction found no recognized claim. Usage notes also remain family-scoped and can describe other variants. Read the source for the full instructions. These use labels are not the `run_task` task enum; choose a supported routing profile with the capabilities and context your workload requires.
+
+Local capabilities filter advertised uses. For example, `gemma3:1b` accepts text, while larger Gemma 3 variants accept images. A family-level vision chip cannot make the 1B tag a vision candidate. Likewise, an embedding-only tag does not acquire text-generation workflows from its family description.
+
+Installed enrichment requires the exact public tag and a matching digest prefix of at least 12 hexadecimal characters against the local 64-character digest. Custom names are never mapped by architecture or guessed base model. Community names use their exact Ollama namespace. Without a verified match, public guidance is withheld. A local modification can therefore prevent enrichment even when its name resembles a public model.
+
+Library step 2 describes public models before installation, so its top-level `library` guidance remains family-scoped without claiming a local digest match. Each `tags[]` entry carries its own modalities, context, digest prefix, and `cloud` flag. Search returns `cloudAvailable` for the hosted-access badge and `cloudOnly:null`: a family badge alone does not establish that 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. Known remote entries skip public enrichment, and cloud tags never become local trial recommendations. This metadata is not processor-placement evidence; inspect the execution observation for CPU/GPU placement.
+
+## Cache and request bounds
+
+Each MCP process caches at most 128 families. Successful lookups expire after one hour, failures after one minute; concurrent requests for a family share one lookup. Expired content is not served as current metadata. Restarting the MCP process clears this in-memory cache.
+
+Installed enrichment runs at most four family lookups concurrently. Each lookup requests the family page and complete `/tags` page in parallel. 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`. These requests retrieve metadata without loading or executing a model. They disclose the requested public family name to ollama.com.
+
+The local inventory is not cached by the enrichment layer. A changed backend inventory or failed lookup leaves the managed model and its existing evidence intact. A size-based library recommendation is only a download trial candidate: download size does not establish runtime memory fit, CPU/GPU placement, or task quality. Model discovery never authorizes a pull.
+
+## Sources and related documentation
+
+- [Ollama model details API](https://docs.ollama.com/api-reference/show-model-details) provides runtime capability and architecture metadata.
+- [Ollama model-list API](https://docs.ollama.com/api/tags) provides installed tags and digests.
+- [Ollama Gemma 3 page](https://ollama.com/library/gemma3) illustrates variant-specific modalities.
+- [MCP tool reference](../packages/mcp/README.md#tools) documents the complete tool surface.
+- [Choose local models](MODEL_SELECTION.md) explains quality qualification and measured results.
+- [Test FreeLlama](TESTING.md) lists the parser, enrichment, and protocol checks.

package/docs/MODEL_SELECTION.md

@@ -1,10 +1,19 @@
 # Choose local models
 
-Choose models from local evidence, not model-card popularity. The measurements below come from one
-Apple M4 Pro machine with 48 GB unified memory and are not compiled into routing. Re-run
+To offload a task, select an installed model with the required capabilities and measured quality,
+then check its memory fit under the intended concurrency. FreeLlama applies model eligibility
+and admission; the calling agent still verifies the output.
+
+The measurements in this guide come from one Apple M4 Pro machine with 48 GB unified memory and
+are not compiled into routing. Re-run
 `npx @octocodeai/freellama doctor`, `models`, `bench-all`, and your quality suite on the target hardware.
 `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,
+custom-model fallbacks, and how to read family claims without treating them as quality measurements.
+
 ```mermaid
 flowchart TD
     T{"What must the task do?"}
@@ -24,6 +33,10 @@ 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.
+These examples do not establish that a tag is installed or suitable on your host.
+
 `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.