@octocodeai/freellama-mcp-server 0.5.0 → 0.6.0

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,15 @@ 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.
+Read the [retained model profile](https://github.com/bgauryy/FreeLlama/blob/main/skills/freellama/references/model-profile-qwen3.8-27b-mlx.md)
+and [delegation measurements](https://github.com/bgauryy/FreeLlama/blob/main/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.
 
+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 +65,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 +80,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.
 
@@ -129,12 +132,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; low RAM and swapping never hold an already-resident runner) | `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 +170,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:
@@ -273,13 +277,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.

package/docs/PRODUCTION.md

@@ -12,9 +12,12 @@ not provide tenant isolation or billing.
 
 - Install one Ollama CLI and server version. Run `freellama doctor` and resolve any mismatch.
 - Install Node.js 20 or later for MCP and npm distribution use.
-- Use the release artifacts for your operating system, or build with Rust 1.85 or later.
+- Use the release artifacts for your operating system, or build with Rust 1.88 or later.
 - Preinstall and benchmark exact model tags. Discovery never authorizes a pull.
 - Keep the primary and optional CPU Ollama processes on distinct loopback sockets.
+- In a slim or distroless container, install the CA bundle (`ca-certificates`) or set
+  `SSL_CERT_FILE` if any upstream uses `https://`. Without one, FreeLlama starts with an empty trust
+  store and warns: plain-HTTP upstreams work, HTTPS upstreams fail their certificate check.
 
 After a tag has been published, install that exact checksummed release on macOS or Linux:
 
@@ -31,17 +34,14 @@ published tag:
 powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Version VERSION
 ```
 
-The [release workflow](../.github/workflows/release.yml) builds CLI and native artifacts for eight
-targets, assembles packages, verifies package contents, and publishes on version tags. The
-[CI workflow](../.github/workflows/ci.yml) runs Rust checks on macOS, Linux, and Windows, plus
-JavaScript/native checks on macOS and Linux. These workflows do not prove driver compatibility or
-complete the hardware promotion checklist below. Release artifact builds depend on the reusable CI checks.
-The publish step also verifies that a version tag matches the workspace version.
+The repository has no CI or release workflows; they were removed (see git history). Build, verify,
+and publish artifacts with the [release procedure](../RELEASE.md). The publish verifier checks that
+a version tag matches the workspace version.
 Live E2E and hardware qualification remain separate operator checks; verify those receipts before tagging.
 
 For manual assembly, build and test every claimed target in a clean
 environment, place each executable and matching addon under `release-artifacts/<target>/`, run
-`yarn release:assemble release-artifacts release` and `yarn release:verify:publish`, then attach
+`node scripts/assemble-release.mjs release-artifacts release` and `yarn release:verify:publish`, then attach
 `release/SHA256SUMS` and binaries to the release. Publish the eight `@octocodeai/freellama-native-*` packages
 first, followed by the exact-version `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server` packages. Configure
 registry credentials in the release environment; never store them in the repository.
@@ -197,12 +197,9 @@ the Ollama process does not expose to FreeLlama.
 Run compile and deterministic test checks from clean checkouts on Windows, Linux, and macOS. Live
 accelerator acceptance is separate because build machines do not necessarily represent production
 GPU drivers or memory topology. Prepare Apple Metal, NVIDIA Linux, AMD Linux, and NVIDIA Windows
-hosts, then run `benchmark/hardware/run_validation.py` directly on each host.
+hosts, then run a hardware acceptance check directly on each host.
 
-Each environment supplies its exact GPU and CPU model tags and a running FreeLlama endpoint. The
-portable runner in `benchmark/hardware/run_validation.py` executes GPU coding and CPU embedding
-concurrently, verifies physical processor receipts, checks admission receipts, and writes a JSON
-artifact. Add `--vision-model` and `--vision-image` for that host's OCR/vision gate.
+The portable hardware runners were removed from the repository; they remain in git history.
 
 Do not mark a hardware row validated until its archived receipt says `verdict: accept`. Missing
 hardware is an explicit release gap, not a result that documentation can waive.

package/docs/README.md

@@ -2,39 +2,35 @@
 
 FreeLlama helps agents offload bounded work to local models through Ollama. The calling agent owns
 the task and verifies the answer; FreeLlama manages model selection and resources around execution.
-Start with the [repository quick start](../README.md#quick-start) to run one managed task.
+Start with the [repository MCP setup](https://github.com/bgauryy/FreeLlama/blob/main/README.md#connect-your-agent-mcp) to run one managed task.
 
 ## Choose a guide
 
 | Goal | Guide |
 |---|---|
-| Connect an agent and choose a tool | [MCP server](../packages/mcp/README.md) |
-| Follow the agent's operating workflow | [FreeLlama skill](../skills/freellama/README.md) |
+| Connect an agent and choose a tool | [MCP server](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md) |
+| Follow the agent's operating workflow | [FreeLlama skill](https://github.com/bgauryy/FreeLlama/blob/main/skills/freellama/SKILL.md) |
 | Look up commands and task controls | [CLI reference](CLI.md) |
 | Understand task and resource ownership | [Architecture](ARCHITECTURE.md) |
-| Choose a model from measured evidence | [Model selection](MODEL_SELECTION.md) |
-| Interpret capabilities and public model metadata | [Model metadata](MODEL_METADATA.md) |
+| Choose a model and interpret its metadata | [Model selection](MODEL_SELECTION.md), [model metadata](MODEL_SELECTION.md#model-metadata) |
 | Configure CPU helpers alongside GPU work | [CPU/GPU routing](CPU_GPU_ROUTING.md) |
 | Inspect queues, memory, usage, and live settings | [Monitoring](MONITORING.md) |
 | Retain history, affinity, or residency | [Scopes and warming](SCOPES_AND_WARMING.md) |
-| Understand raw Ollama compatibility | [Sidecar boundary](OLLAMA_SIDECAR.md) |
-| Evaluate context offload and its cost | [Token economics](ECONOMICS.md) |
+| Understand raw Ollama compatibility | [Ollama sidecar](ARCHITECTURE.md#ollama-sidecar) |
+| Evaluate context offload and its cost | [Token economics](https://github.com/bgauryy/FreeLlama/blob/main/packages/mcp/README.md#token-economics) |
 | Deploy the management layer | [Production runbook](PRODUCTION.md) |
-| Run development and release checks | [Testing](TESTING.md), [release procedure](../RELEASE.md) |
-| Embed the routing core | [Rust core](../packages/rust-core/README.md) |
-| Use the read-only dashboard | [Runtime view](../packages/view/README.md) |
+| Run development and release checks | [Testing](TESTING.md), [release procedure](https://github.com/bgauryy/FreeLlama/blob/main/RELEASE.md) |
+| Embed the routing core | [Rust core](https://github.com/bgauryy/FreeLlama/blob/main/packages/rust-core/README.md) |
+| Use the read-only status page | `/_freellama/ui` on a running `serve` (see [Monitoring](MONITORING.md)) |
 
 ## Evidence and design
 
 | Goal | Source |
 |---|---|
-| Describe the product and its limits | [Product positioning](PRODUCT_POSITIONING.md) |
 | Review dated findings and project comparisons | [Findings report](dev/FINDINGS_AND_POSITIONING.md) |
 | Measure inference, device activity, and thermal behavior | [Local performance testing](dev/LOCAL_PERFORMANCE_TESTING.md) |
 | Separate management controls from inference tuning | [Ollama optimization boundary](dev/OLLAMA_SYSTEM_OPTIMIZATION.md) |
 | Understand backend selection decisions | [Resource-routing ADR](dev/ADR_RESOURCE_AWARE_BACKEND_ROUTING.md) |
-| Choose a model, adapter, or hardware benchmark | [Benchmark index](../benchmark/README.md) |
-| Inspect research adapter contracts and caveats | [Adapter reference](../benchmark/local/docs/07-adapter-contracts.md) |
 
 Historical measurements describe one model, machine, and workload. Inspect current state and
 repeat the relevant checks before using them to select models or set resource limits.

package/docs/SCOPES_AND_WARMING.md

@@ -41,15 +41,15 @@ Create accepts the following optional fields:
 | HTTP field | MCP field | Meaning |
 |---|---|---|
 | `messages` | `messages` | Initial Ollama messages, preserving fields, content, and order. |
-| `route_defaults` | `routeDefaults` | Task-routing defaults for later scoped execution. |
-| `limits` | `limits` | Per-scope bounds within the server's configured limits. |
+| `route_defaults` | — | Task-routing defaults for later scoped execution (HTTP/CLI only). |
+| `limits` | — | Per-scope bounds within the server's configured limits (HTTP/CLI only). |
 
 Messages require a supported role and can omit content, including for assistant tool calls.
 When present, content must be a string.
 
 Routing defaults accept `task`, `objective`, `model`, `required_capabilities`, `context_tokens`,
-`execution_preference`, `min_placement_evidence`, and `min_confidence`. MCP uses the corresponding
-camelCase field names. Defaults do not grant admission or qualify a model. Explicit task fields
+`execution_preference`, `min_placement_evidence`, and `min_confidence`. MCP callers set routing per
+`run_task` call instead. Defaults do not grant admission or qualify a model. Explicit task fields
 take precedence, and execution checks current eligibility and resources.
 
 The metadata receipt contains `scope_id`, `revision`, `route_defaults`, `limits`, `message_count`,
@@ -59,7 +59,7 @@ Token estimates derive from the full serialized message bytes and count both med
 This storage-budget estimate can refuse media-heavy history before inference; it does not measure
 image token cost or determine the model context required to execute the history.
 
-Fork requires `revision` and accepts optional replacement routing defaults and limit overrides. It creates a
+Fork requires `revision`; HTTP/CLI forks also accept replacement routing defaults and limit overrides. It creates a
 separate history snapshot with revision `0`; later writes to either scope do not change the other.
 Fork independent branches before parallel execution instead of submitting concurrent writes to one
 scope.
@@ -138,15 +138,14 @@ precedence. Inspect effective values and their sources with
 | `total_max_bytes` | `FREELLAMA_SCOPE_TOTAL_MAX_BYTES` | `16777216` | Aggregate retained history-byte budget. |
 | `ttl_seconds` | `FREELLAMA_SCOPE_TTL_SECONDS` | `3600` | Idle expiry since create, fork, or successful append; reads do not renew it. |
 
-Per-scope `limits` accepts `max_messages`, `max_bytes`, `max_estimated_tokens`, and `ttl_seconds`;
-MCP uses `maxMessages`, `maxBytes`, `maxEstimatedTokens`, and `ttlSeconds`. A request can lower these
-bounds within server policy. Finite safety bounds remain operator-owned. Lowering runtime caps
+Per-scope HTTP/CLI `limits` accepts `max_messages`, `max_bytes`, `max_estimated_tokens`, and
+`ttl_seconds` and can only lower these bounds within server policy. Finite safety bounds remain operator-owned. Lowering runtime caps
 does not summarize or trim stored transcripts; subsequent writes must satisfy the active caps.
 Expired entries are removed during store operations.
 
 ## Warm API
 
-`POST /warm`, MCP `warm_model`, and CLI `warm` load an exact installed model with a matching
+`POST /warm`, MCP `run_task {warm:true}`, and CLI `warm` load an exact installed model with a matching
 non-embedding task profile. They do not accept prompts or messages, pull a model, or store conversation
 history. The default task profile is `completion`.
 

package/docs/TESTING.md

@@ -19,6 +19,7 @@ flowchart LR
 ## Install and build
 
 ```bash
+corepack enable   # Yarn version comes from package.json "packageManager"
 yarn install
 yarn build
 ```
@@ -30,13 +31,16 @@ dependency rather than compiling Rust during installation.
 
 ## Run the test tiers
 
+The root `yarn build`, `yarn lint`, and `yarn test` run across every package: the Rust crates
+(`rust-core`, `cli`) through Cargo and the JavaScript workspaces (`mcp`, `cli`, `native/*`) through
+Yarn. Use the `:js` or `:rust` variants to run one side only.
+
 | Tier | Command | External requirements |
 |---|---|---|
-| JavaScript unit | `yarn test` | None |
-| JavaScript watch | `yarn test:watch` | None |
+| All package unit tests (JS + Rust) | `yarn test` | Rust toolchain |
+| JavaScript unit | `yarn test:js` | None |
 | Rust contracts | `yarn test:rust` | Rust toolchain |
-| Local-agent contracts | `yarn test:agents` | Python 3 standard library |
-| Hardware runner contracts | `python3 -m unittest discover -s benchmark/hardware -p 'test_*.py'` | Python 3 standard library; no inference |
+| Local-agent contracts | `yarn test:agents` | None after install; builds the MCP package |
 | TypeScript | `yarn typecheck` | None after install |
 | MCP integration | `yarn test:integration` | Ollama at `FREELLAMA_OLLAMA_ENDPOINT` (default `127.0.0.1:11434`) |
 | MCP end to end | `yarn test:e2e` | Ollama, `freellama serve`, and required models |
@@ -66,7 +70,7 @@ failures. MCP integration's `model-knowledge.test.ts` exercises the built server
 local HTTP fixtures for both Ollama API data and public HTML. It checks optional enrichment,
 assigned-backend inventory, tag pagination, validation, and preservation of benchmark/policy evidence.
 The fixture tests perform no inference, pulls, or deletions. See the
-[metadata reference](MODEL_METADATA.md) for the public states these tests protect.
+[metadata reference](MODEL_SELECTION.md#model-metadata) for the public states these tests protect.
 
 ## Run static Rust checks
 
@@ -156,8 +160,8 @@ a resident routing preview to agree with execution under a low-memory-only hold.
 Run the isolated control timing experiments separately from the full suite:
 
 ```bash
-cargo test --test control_timing_contract -- --include-ignored --nocapture
-cargo test --test task_jobs_contract measure_deferred_control_latency -- --ignored --nocapture
+cargo test --test integration control_timing_contract -- --include-ignored --nocapture
+cargo test --test integration task_jobs_contract::measure_deferred_control_latency -- --ignored --nocapture
 ```
 
 These fixed-budget experiments use simulated backends to measure status, discovery, queue
@@ -188,32 +192,19 @@ After rebuilding the release, a fresh concurrent smoke check completed both mana
 Qwen, one embedding from Nomic, positive Qwen VRAM, zero Nomic VRAM, and primary Ollama 0.33.2
 through raw passthrough.
 
-For promotion, use the portable [hardware acceptance runner](../benchmark/hardware/README.md) and
-archive its JSON receipt with the release evidence. Compilation alone does not validate a driver,
-physical placement, shared-memory contention, or OCR quality.
-
-The runner measures separate sequential and parallel runs of identical workloads across at least
-three pairs, and checks every result before reporting successful-task throughput. It requires a
-configurable median gain (default 5%). Resident GPU bytes establish placement; they do not measure
-device busy percentage, bandwidth or energy efficiency. Sustained throughput and tail latency
-require a representative workload and separate device/thermal observations.
+The portable hardware acceptance, workload, comparison, and load runners were removed from the
+repository; they remain in git history. Compilation alone does not validate a driver, physical
+placement, shared-memory contention, or OCR quality.
 
 The historical CPU/GPU observations above predate the corrected paired-run acceptance gate.
-They remain records of those runs, and do not qualify a release under the current gate.
-
-For a GPU workload with independent expected answers, use
-`benchmark/hardware/run_workload.py --workload MANIFEST.json --output RECEIPT.json`. It accepts
-distinct generation or vision cases, runs at least three alternating pairs, retains every
-result, and rejects incomplete or incorrect workloads. Its client deadline also bounds a hung
-measurement worker. See the [hardware guide](../benchmark/hardware/README.md) for the manifest
-contract.
+They remain records of those runs and do not qualify a release.
 
 ## Verify release packages
 
 ```bash
 # Collect each target's `freellama` executable and `freellama.<target>.node`
 # under release-artifacts/<target>/, then stage all eight platform packages.
-yarn release:assemble release-artifacts release
+node scripts/assemble-release.mjs release-artifacts release
 yarn release:verify:publish
 ```
 
@@ -225,11 +216,8 @@ prove registry publication or another hardware class.
 
 ## Test one layer while iterating
 
-The October 2, 2026 fixture investigation retained failed launches, raw dynamic-loader samples,
-and passing reruns. After the executable-fixture correction described above, the normal
-`yarn test` command passed 152 tests in 1.83 seconds of suite time. Test and production deadlines
-remain unchanged. Preserve failed and passing receipts together; this result does not qualify
-production startup timing.
+When investigating a fixture failure, preserve failed and passing receipts together; a passing
+rerun does not qualify production startup timing.
 
 ```bash
 yarn build:native