@octocodeai/freellama-mcp-server 0.1.0 → 0.5.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) FreeLlama contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,23 +1,34 @@
 # FreeLlama MCP server
 
-Exposes FreeLlama's local-LLM control plane, and Ollama's lifecycle, as
-[MCP](https://modelcontextprotocol.io) tools, built on the official
-[TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+![A brown cartoon llama stands on a pastel cloud background.](assets/logo.jpg)
 
-## Understand the eight tools
+This package exposes FreeLlama's management layer as Model Context Protocol (MCP) tools.
+Agents offload bounded tasks to local Ollama models; FreeLlama handles model selection, resource
+admission, memory checks, and routing to configured CPU/GPU backends. Results include execution
+evidence for the calling agent to inspect.
 
-- `doctor`, `models`, `run_task`, `run_task_batch` — thin wrappers over the native NAPI bindings into the
+The agent owns prompts, task dependencies, and answer verification. The operator configures
+Ollama and model lifecycle permissions; Ollama performs inference. See
+[architecture](../../docs/ARCHITECTURE.md) for the full ownership boundary.
+The server uses the official [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## Understand the tools
+
+- `doctor`, `models`, `run_task`, `task_jobs`, `run_task_batch` — thin wrappers over the native NAPI bindings into the
   Rust core (`../rust-core/src/napi.rs`); no CLI subprocess, no reimplemented routing logic.
-  `run_task { preview: true }` is the free decision-only form (the former `route` tool).
+  `run_task { preview: true }` is the decision-only form and does not run inference.
   Preview and execution are separate calls: preview accepts routing fields only and rejects task
   payloads or runtime controls instead of silently ignoring them.
   `models { view: "library" }` queries the public `ollama.com` library (the former `search_models` tool).
+- `scope` — creates, inspects, forks, or deletes bounded process-local message history.
+- `warm_model` — warms an exact installed model through ordinary managed admission and placement.
 - `session` — creates and releases a bounded, idle-expiring model-affinity handle for related
   route/task calls. It does not store messages, prompt history, or Ollama's runner KV cache.
 - `ollama_manage`, `ollama_delete` — Ollama's HTTP API for lifecycle operations the routing layer
   doesn't cover.
 - `delegate_research` — offloads a grounded code-research question to a local model and returns a
-  verdict computed from what the run did.
+  verdict computed from model evidence, successful tool calls, and question-shape heuristics.
+  The verdict guides verification; it does not certify answer correctness.
 
 Use the smallest tool that owns the operation:
 
@@ -27,8 +38,11 @@ flowchart TD
     Q -->|"Diagnose the local runtime"| D["doctor"]
     Q -->|"Inspect installed, resident, detailed, raw, or online models"| M["models"]
     Q -->|"Choose or execute one task"| R["run_task"]
+    Q -->|"Inspect or cancel deferred work"| J["task_jobs"]
     Q -->|"Fan out independent tasks"| B["run_task_batch"]
     Q -->|"Keep/release related-task model affinity"| S["session"]
+    Q -->|"Retain or fork message history"| H["scope"]
+    Q -->|"Prepare runner residency"| W["warm_model"]
     Q -->|"Pull or stop a model"| O["ollama_manage"]
     Q -->|"Permanently remove a named model"| X["ollama_delete"]
     Q -->|"Ground an answer in workspace files"| G["delegate_research"]
@@ -39,15 +53,36 @@ flowchart TD
 | `doctor` | Makes runtime, version, memory, and configuration drift visible before work starts. |
 | `models` | Separates installed, resident, detailed, raw, and public-library questions instead of guessing from model names. |
 | `run_task` | Applies the same deterministic routing, confidence, admission, and execution contract as the Rust control plane. |
+| `task_jobs` | Lists, retrieves, cancels, or removes a bounded process-local task submitted with `defer:true`. Removal stops active work first. |
 | `run_task_batch` | Executes only caller-declared independent tasks. Stable IDs, a bounded dispatcher, 3:2:1 fair priority classes, and per-item errors make fan-out inspectable rather than implicit. |
 | `session` | Lets an agent explicitly own the lifetime of a bounded affinity handle without misrepresenting it as conversation or KV storage. |
+| `scope` | Retains bounded message history with expected revisions and explicit history reads. |
+| `warm_model` | Loads an installed runner profile using the same memory, admission, placement, and job controls as task execution. |
 | `ollama_manage` | Exposes additive lifecycle operations that FreeLlama routing intentionally does not perform. |
 | `ollama_delete` | Keeps irreversible deletion separate and explicit so a client can guard it. |
 | `delegate_research` | Gives a local model bounded read-only tools and returns citations plus an independently computed verification verdict. |
 
 ## Follow the agent workflow
 
-The server sends this workflow to every MCP client in its initialization instructions:
+The task lifecycle uses the UUID returned as `job.id` by `run_task {defer:true}`. A job is one
+submitted task; pass that UUID as `jobId` for every subsequent operation.
+
+| Operation | MCP call |
+|---|---|
+| List models | `models {view:"installed"}` |
+| Submit a task and receive its ID | `run_task {prompt:"Explain this code", defer:true}` |
+| List tasks with their states | `task_jobs {action:"list"}` |
+| Get one task's state, result, or error | `task_jobs {action:"get", jobId:"<returned UUID>"}` |
+| Stop one task and retain its record | `task_jobs {action:"cancel", jobId:"<returned UUID>"}` |
+| Stop one task and remove its record | `task_jobs {action:"remove", jobId:"<returned UUID>"}` |
+
+Removal waits for local permits to be released before deleting the record. It returns the ID and
+terminal status; subsequent lookup returns `404`. It does not unload a shared Ollama model or
+prove that physical computation has stopped. Receipts are bounded and lost on server restart;
+see [retention and task states](../../docs/MONITORING.md#read-the-live-status).
+
+Follow this workflow. The server's initialization instructions carry a compressed form of the
+same contract (inventory first, preview semantics, evidence levels, ownership, and pull approval):
 
 1. Start with `models {view:"installed"}`, then `models {view:"resident"}`. This gives a routing
    agent the smallest current inventory first.
@@ -89,7 +124,7 @@ Use this economical sequence:
 For a delegated agent, estimated usable input is `contextTokens - outputTokens - safetyMarginTokens`
 (the default margin is 256). The adapter pins the system instruction and question, preserves the
 newest observations, compacts older observations into breadcrumbs, and refuses a pinned overflow
-by default. `pinnedOverflow:"clip"` is a deliberate quality-risk override. Initial token counting
+by default. `FREELLAMA_AGENT_PINNED_OVERFLOW=clip` is a deliberate quality-risk override. Initial token counting
 is conservative; successful Ollama calls calibrate later estimates.
 
 Do not confuse operational evidence with answer quality. A receipt can prove admission, token
@@ -137,7 +172,7 @@ placement and admission. Ollama and the OS/driver own runner loading and physica
 
 ```mermaid
 flowchart TD
-    C["MCP client"] -->|"stdio JSON-RPC"| B["dist/index.js: eight tool registrations"]
+    C["MCP client"] -->|"stdio JSON-RPC"| B["dist/index.js: tool registrations"]
     B --> N["native/index.js and platform addon"]
     N -->|"doctor"| L["Rust diagnostics"]
     N -->|"models installed/resident; run_task"| S["freellama serve"]
@@ -200,12 +235,34 @@ artifact); `native/index.js` and `native/index.d.ts` are hand-written and checke
 
 ## Run
 
+**From npm (recommended):**
+
+```bash
+npx @octocodeai/freellama-mcp-server
+```
+
+**From the repository root after building:**
+
 ```bash
-node dist/index.js
+node packages/mcp/dist/index.js
+```
+
+The server speaks MCP over stdio — configure it in your MCP client, do not run it interactively.
+
+**Claude Desktop (`claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "freellama": {
+      "command": "npx",
+      "args": ["@octocodeai/freellama-mcp-server"]
+    }
+  }
+}
 ```
 
-The server speaks MCP over stdio — launch it from an MCP client (for example, Claude Desktop's
-`claude_desktop_config.json`), not interactively.
+**Cursor / other clients** — use the same `command`/`args` shape in their MCP server config.
 
 ## Test
 
@@ -214,28 +271,47 @@ Vitest, in three tiers (all TypeScript, under `test/`):
 | Tier | Command (from this package) | Checks | Needs |
 |---|---|---|---|
 | `test/unit/` | `yarn test` (watch: `yarn test:watch`) | pure functions straight from `src/*.ts` — no build step, this is the TDD loop | nothing, ~0.5s |
-| `test/integration/` | `yarn test:integration` | the built server over the real MCP protocol: tool contract, structured content, guardrails; rebuilds `dist/` itself | live Ollama on :11434, ~5s |
+| `test/integration/` | `yarn test:integration` | the built server over the real MCP protocol: tool contract, structured content, guardrails; rebuilds `dist/` itself | Ollama at `FREELLAMA_OLLAMA_ENDPOINT` (default :11434) |
 | `test/e2e/` | `yarn test:e2e` | every tool against the live system: real routing/execution, pull → delete round trip (net-zero), a real delegated research run | serve + Ollama + models, ~40s |
 
 The same commands work from the repository root (`yarn test` there also runs the CLI package's tests).
 The integration/e2e tiers fail fast with a readable message when Ollama is down, and the lifecycle
 test refuses to delete a model already installed on the test system.
 
+For default-endpoint autostart, a spawn failure, early exit, or readiness timeout rejects the
+request while leaving the MCP transport available for diagnosis or retry. Autostart does not apply
+to an explicit non-default endpoint; see `FREELLAMA_MCP_AUTOSTART_SERVE` below.
+
 ## Tools
 
 | Tool | Needs `freellama serve`? | What it does |
 |---|---|---|
-| `doctor` | No | Runtime/configuration diagnostic. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `scheduler` adds configured/snapshot admission data; `config` returns categorized settings; `full` adds all non-duplicated diagnostics. The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
-| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, real max context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for tags/`fitsInMemory`) |
+| `doctor` | No | Runtime/configuration diagnostic. `summary` (default) returns endpoint, version, resident count, host/profile signals, and next step; `scheduler` adds configured/snapshot admission data; `config` returns categorized settings; `full` adds all non-duplicated diagnostics; `status` returns serve's live view (per-backend queues, current and adaptive limits, circuit breakers, loaded models, host memory, Ollama's effective settings, today's usage); `usage` returns task and token totals per day and model (`days`, default 7). The report distinguishes an observed same-user macOS process from configuration hints and never claims remote process visibility. |
+| `models` | `installed` (default) and `resident` do; `detail`/`raw`/`library` don't | Views: `installed` (capabilities, use explanations, derived `model_type`, VRAM, context, policy_rank), `resident` (loaded now + managed GPU/CPU split), `detail` (one model, maximum context), paged `raw` (`GET /api/tags`), `library` (two-step ollama.com search: omit `model` for families, pass `model:"<family>"` for all tags/`fitsInMemory`). `includeLibrary:true` enriches installed/detail views with sourced public guidance; `includeReadme:true` returns bounded README text in library step 2 or enriched detail. |
 | `run_task` | Yes | **Routes or executes** a chat/generate/embed call. `preview: true` accepts routing fields only and returns a decision without generation. Execution omits preview and supplies the payload. Embedding results withhold raw vectors by default (`returnEmbeddings: true` to get them) |
+| `scope` | Yes | Creates, inspects, forks, or deletes process-local message history; history inclusion requires `includeMessages:true`. |
+| `warm_model` | Yes | Warms an exact installed model through managed admission; accepts residency/profile controls and optional `defer:true`. |
+| `session` | Yes | Creates or releases model affinity without storing messages or KV. |
+| `task_jobs` | Yes | Inspects, cancels, or removes a deferred task or warming operation. |
 | `run_task_batch` | Yes | Executes only typed `{id, independent:true, task}` items. The nested `task` exposes the same task, routing, payload, and runtime controls as `run_task`; `maxParallelism` bounds fan-out. It is not a dependency graph scheduler. |
 | `ollama_manage` | No (direct to Ollama) | `action: "pull"` downloads a model; `action: "stop"` force-unloads it. Both additive and idempotent |
 | `ollama_delete` | No (direct to Ollama) | **Destructive**: permanently removes a model. Call only on an explicit human instruction naming the exact model |
 | `delegate_research` | Yes (and spawns the adapter) | Answers a grounded question from files under `workspacePath`; managed coding turns return placement receipts, citations, and an independent verification verdict |
 
+### Inspect capabilities and intended uses
+
+Use `models {view:"installed", includeLibrary:true}` to enrich each installed model, or
+`models {view:"detail", model:"gemma3:1b", includeLibrary:true, includeReadme:true}` for one model.
+Website access is optional for installed/detail views. Public guidance requires a matching exact tag
+and digest prefix; local capabilities remain authoritative and benchmark/policy evidence stays separate.
+Family claims have source excerpts and fetch dates, and lookup failures retain local inventory.
+Search reports `cloudAvailable` and `cloudOnly:null`; inspect exact tags to establish local availability.
+See [Ollama model metadata](../../docs/MODEL_METADATA.md) for response fields, lookup states, cache bounds,
+custom models, and variant limitations.
+
 ### Preserve Ollama request controls
 
-All eight tools declare an MCP object `outputSchema`. Schemas type the stable fields FreeLlama owns
+The tools declare an MCP object `outputSchema`. Schemas type the stable fields FreeLlama owns
 (such as route decision, page, answer, and session identifiers) while leaving Ollama-owned nested
 payloads forward-compatible. `structuredContent` is canonical; normal text is a concise cue. For
 the narrow `delegate_research` legacy case, set `legacyText:true` to receive serialized JSON text.
@@ -245,16 +321,29 @@ refuses continuation if the live model list changed. Library tag responses use t
 shape. Do not request `doctor {view:"full"}` in an agent loop: use `summary`, `scheduler`, or
 `config` for the smallest diagnostic that answers the question.
 
+### Preview and execution
+
+For ordinary chat, `run_task {prompt:"Hello"}` is enough once the server and an eligible model
+are available. `task` defaults to `completion`, including inside batch items. Task profiles are
+optional routing presets, not restrictions on what you can ask the model.
+
+Default `balanced` routing prefers policy-qualified candidates when available. Without an eligible
+policy candidate, it falls back to capability/context-compatible models and reports low confidence,
+`quality_evidence:"none"`, and `balanced_without_quality_policy`. Set `minConfidence:"medium"`
+to require evidence, or `objective:"quality"` to require policy-based selection unless you pin a model.
+Memory admission, authentication, and capability requirements apply in every mode.
+
 `run_task` has two deliberately exclusive request shapes:
 
 - Preview: set `preview: true`; pass routing fields such as `task`, `objective`, `model`,
   `contextTokens`, `requiredCapabilities`, and placement/confidence gates. To preview tool use,
   pass `requiredCapabilities: ["tools"]` rather than function definitions.
-- Execution: omit `preview` (or set it to `false`) and pass `prompt`/`messages` for generative
+- Execution: omit `preview` (or set it to `false`) and pass `prompt`, `systemPrompt`, or `messages` for generative
   tasks or `input` for embeddings, plus any applicable Ollama runtime controls.
 
-Preview rejects `prompt`, `messages`, `input`, `images`, `tools`, `keepAlive`, `format`, `think`,
-`options`, `logprobs`, `topLogprobs`, and `returnEmbeddings`. This prevents a client from attaching
+Preview rejects `prompt`, `systemPrompt`, `messages`, `input`, `images`, `tools`, `keepAlive`, `format`, `think`,
+`options`, `logprobs`, `topLogprobs`, `returnEmbeddings`, `priority`, `maxWaitSeconds`, `timeoutSeconds`, and
+`defer`, `scopeId`, and `scopeRevision`. This prevents a client from attaching
 work to a decision-only call and mistakenly assuming it ran.
 
 `run_task.messages` preserves Ollama message fields beyond `role` and `content`, including images,
@@ -263,11 +352,54 @@ thinking, tool calls, and tool names. Managed requests also accept `format`, `th
 keys are rejected inside `options`. The raw proxy remains available when a caller needs an Ollama
 endpoint or feature that the managed MCP tool does not expose, including streaming.
 
+Managed execution waits for a slot and safe host capacity within the server's waiting budget
+(120 seconds by default). Set `maxWaitSeconds` on `run_task` or each batch task to request a
+shorter budget; the server caps it at its configured limit. Resource waiters remain counted in
+the bounded queue after returning their execution slots. They resume when capacity becomes
+available, and session cancellation removes pending work. A full queue or an expired deadline
+returns a capacity error with retry guidance.
+
+Set `defer:true` on `run_task` to return a job ID immediately. Use `task_jobs {action:"list"}` for
+metadata, `{action:"get", jobId}` for a retained result, and `{action:"cancel", jobId}` to cancel
+that task and wait for local permits to be released. `get` summarizes embedding vectors by default;
+set `returnEmbeddings:true` to include them. Cancellation does not unload a shared model or confirm
+physical runner shutdown. Jobs expire on restart; see [CLI controls](../../docs/CLI.md#execute-tasks)
+for input, result, registry, and retention limits. Batch items cannot defer.
+
+Set `timeoutSeconds` on a task or batch item for a total deadline covering discovery, queueing,
+loading, and inference. The server caps it at its task timeout. The admission wait budget remains
+separate; a queue refusal can happen before the total deadline. `priority` selects a fair scheduling
+class without bypassing resource checks.
+
+You own the task instructions. Pass system prompts as `messages` entries with `role:"system"`,
+or use `systemPrompt` to prepend one caller-supplied system message. FreeLlama preserves existing
+messages and adds no task instructions of its own. A plain `prompt` becomes one user message,
+and a supplied `messages` array takes precedence over `prompt`. This also applies to
+`task:"code_review"` (an alias for `coding`) and `run_task_batch`: no review wrapper, mandatory
+JSON review format, or review-specific output-token minimum is added.
+
+The separate `delegate_research` adapter and natural-language routing interpreter retain internal
+protocol prompts for their own bounded jobs. Those prompts are not injected into `run_task`
+conversations. Ollama can still apply the selected model's own template or Modelfile defaults.
+
 `model_type` is a display-oriented value derived from Ollama's additive capabilities:
 `generative`, `multimodal`, `embedding_only`, or `unknown`. Routing continues to use the original
 capability set, not this summary label. Unknown future Ollama capabilities are omitted from the
 typed routing set instead of being treated as a known capability.
 
+### Retain history and warm models
+
+Use `scope {action:"create",messages}` to retain a caller-owned prefix. Pass its returned ID and
+revision as `scopeId` and `scopeRevision` with only the new input to `run_task`; successful execution
+returns the next scope revision. Fork a snapshot before parallel branches. `sessionId` continues to
+mean model affinity only.
+
+Use `warm_model {model,contextTokens,keepAlive?}` for a matching runner profile. It accepts no task
+payload and does not pull a model. Add `defer:true` to inspect its progress through `task_jobs`.
+Explicit `keepAlive` wins over finite adaptive retention. See the canonical
+[Scope history and model warming reference](../../docs/SCOPES_AND_WARMING.md) for schemas, limits,
+concurrency, privacy, and cache boundaries.
+
 ### Use CPU assignments through MCP
 
 `run_task` delegates to `freellama serve`, so it honors the server's `--cpu-upstream` and
@@ -277,14 +409,27 @@ managed tasks execute on the primary GPU-capable process.
 Set `executionPreference` on `run_task` to `auto` (default), `prefer_cpu`, or `prefer_gpu`. This is a
 guarded hint: only exact operator-assigned CPU models are eligible, explicit model/session pins win,
 and `preview: true` returns `execution.preference_satisfied`, placement, upstream, admission, and a
-reason without generating. Automatic feedback normalizes work by tokens, waits for three successful
-warm, physically verified samples per task on both backends, requires a 10% advantage, and never
-steers the `quality` objective. `minPlacementEvidence:"observed"` fails closed unless resident
+reason without generating. Automatic feedback normalizes work by tokens and requires three
+comparable warm serial samples on both backends with a 10% advantage. It matches model digest,
+explicit observed context, effective controls, endpoint-attributed process settings, and managed
+admission class. Unknown identity, parallel intervals, and decision-only payload-free previews
+use capacity and policy signals. Stored legacy totals do not qualify speed hints. Feedback does
+not steer the `quality` objective. See [automatic feedback](../../docs/CPU_GPU_ROUTING.md#understand-automatic-feedback).
+`minPlacementEvidence:"observed"` fails closed unless resident
 `/api/ps` evidence matches the configured processor; warm cold models once with `"configured"`.
 `keepAlive:"0"` uses an observe-then-unload transaction: FreeLlama retains the runner long enough
 to inspect `/api/ps`, accepts feedback only for verified placement, requests an explicit unload,
 then reports the unload verification in `execution.lifecycle`.
 
+Preview `execution.agent_plan` separates `queue_readiness`, `resource_readiness`, and combined
+`dispatch_readiness`. Inspect `execution.resource_assessment` for required bytes and missing telemetry;
+the preview shares execution's footprint estimate but never reserves memory. Local inference requires
+RAM telemetry by default; configure an explicit alternative on `serve`, not in a model prompt.
+Resource errors retain a human-readable `error` plus machine-readable `code` and `resource_admission`
+fields in the HTTP response. MCP preserves JSON refusals in both error text and `structuredContent`,
+including queue-full codes, `retry_after_seconds`, resource assessments, and unload receipts.
+Agents can use those fields to back off or explain a capacity hold without parsing human prose.
+
 `models {view: "resident"}` uses the managed catalog, so it includes resident models from both
 Ollama processes and labels explicitly assigned CPU models instead of querying only the primary
 server.
@@ -302,14 +447,14 @@ inspect or modify that separate server. Read
 
 ## Configuration
 
-Every default is overridable through an environment variable — set them in the MCP client's
+The following settings have environment-variable overrides. Set them in the MCP client's
 server-launch config (for example `.mcp.json`'s `env` block) or the launching shell.
 
 | Variable | Default | Affects |
 |---|---|---|
 | `FREELLAMA_OLLAMA_ENDPOINT` | `http://127.0.0.1:11434` | `doctor` and all `ollama_*` tools' default Ollama endpoint |
 | `FREELLAMA_SERVE_ENDPOINT` | `http://127.0.0.1:11435` | Default `endpoint` for serve-backed tools and `delegate_research` |
-| `FREELLAMA_MCP_DEFAULT_MODEL` | `qwen3.8:27b-mlx` | `delegate_research`'s default `model` |
+| `FREELLAMA_MCP_DEFAULT_MODEL` | unset (routes to an installed coding model) | `delegate_research`'s default `model` |
 | `FREELLAMA_MCP_DEFAULT_ADAPTER` | `bash` | `delegate_research`'s adapter (`octocode` to switch) |
 | `FREELLAMA_MCP_MAX_TURNS` | `8` | Max agent turns for `delegate_research` |
 | `FREELLAMA_MCP_DELEGATE_TIMEOUT_SECONDS` | `180` | Whole-subprocess timeout for `delegate_research` |
@@ -324,9 +469,25 @@ server-launch config (for example `.mcp.json`'s `env` block) or the launching sh
 | `FREELLAMA_TASK_TIMEOUT_SECONDS` | `900` | Generation calls; read by `../rust-core/src/napi.rs` |
 | `FREELLAMA_AUTH_TOKEN_FILE` | unset | Bearer-token file used by the native client and research adapters for all serve routes |
 | `FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR` | platform data directory | Prompt-free, model-specific token-estimator calibration shared across adapter processes |
+| `FREELLAMA_MCP_AUTOSTART_SERVE` | `1` | When the default loopback serve endpoint does not answer, start `freellama serve` as a child of the MCP server (stopped with it). `0` disables |
+| `FREELLAMA_SERVE_BINARY` | checkout `target/release`/`debug`, then the platform package | Binary used for serve autostart |
+| `FREELLAMA_AGENT_OS_SANDBOX` | `auto` | Bash adapter OS confinement: `bwrap` on Linux, `sandbox-exec` on macOS, when present. `off` keeps only the restricted shell |
+| `FREELLAMA_AGENT_OCTOCODE_PACKAGE` | `octocode@19.1.0` | Pinned npm spec the Octocode adapter runs through `npx` |
+
+Serve-side placement settings (read by `freellama serve`, not the MCP process):
+
+| Variable | Default | Affects |
+|---|---|---|
+| `FREELLAMA_EVICT_IDLE_MODELS` | on | Unload idle, unpinned models using reuse and load costs when a cold load needs room. `0` turns eviction off |
+| `FREELLAMA_CPU_NUM_THREAD` | half the logical cores (not set on macOS) | `num_thread` for CPU-placed tasks only; GPU tasks leave it to Ollama |
+| `FREELLAMA_MAX_QUEUE_WAIT_SECONDS` | `120` | How long a managed task queues for a slot or memory |
+| `OLLAMA_NUM_PARALLEL`, `OLLAMA_KV_CACHE_TYPE`, `OLLAMA_FLASH_ATTENTION` | Ollama's | Read as hints for the memory estimate: parallel slots multiply the KV cache, and `q8_0`/`q4_0` shrink it only with flash attention. Set them for serve the same way as for Ollama |
 
 Research-adapter settings are deployment defaults. The optional `delegate_research.agent` object
-exposes the same values per call using camelCase; explicit per-call fields win.
+overrides the per-call budget (`maxTurns`, `contextTokens`, `outputTokens`, `temperature`, `seed`,
+`think`, `keepAlive`, `requestTimeoutSeconds`, `toolTimeoutSeconds`); explicit per-call fields win.
+The research subprocess receives only `FREELLAMA_*`, locale, temp, and proxy/CA variables from the
+server environment.
 
 | Variable | Default | Affects |
 |---|---:|---|
@@ -360,14 +521,22 @@ between model templates.
 **Security:** `delegate_research` grants a local model read access to `workspacePath`. The path is
 confined to `FREELLAMA_MCP_ALLOWED_ROOTS` (default: this repository in a checkout; unset in a published
 install until you set it), resolved through symlinks so a link inside an allowed root can't escape
-it. The default `bash` adapter also rejects home-directory paths, `..`, and absolute paths outside
-that workspace. Production deployments should generate a permission-restricted token with
+it. The default `bash` adapter runs an allowlist of read-only tools in a restricted shell with a
+scrubbed environment and, where available, an OS sandbox; it also rejects command substitution,
+home-directory paths, `..`, and absolute paths outside that workspace. Production deployments should generate a permission-restricted token with
 `freellama auth-token`, start `serve` with `--auth-token-file`, and set
 `FREELLAMA_AUTH_TOKEN_FILE` for MCP. Authentication covers managed and raw passthrough routes; use
 an external TLS and authorization layer for untrusted or multi-tenant networks.
 
 ### Runtime evidence
 
+Admission weights can be set by task kind in the server runtime file's `[task_costs]` table.
+Inspect `doctor {view:"full"}` at `platform_health.admission.costs.base_by_task` for effective
+weights and `run_task {preview:true}` for current cost and capacity advice. The table changes
+managed admission; it does not create Ollama
+slots or relax memory guards. Existing queued work keeps its captured cost. See
+[monitoring controls](../../docs/MONITORING.md#adaptive-concurrency).
+
 **No measurements are compiled in.** In a repository checkout, per-model research grades load from
 `benchmark/evidence/model-evidence.json`. A published package does not include that repository
 file, so its evidence table is empty unless you set `FREELLAMA_MCP_MODEL_EVIDENCE`. An unmeasured
@@ -400,17 +569,18 @@ See `skills/freellama/references/proxy-vs-serve.md` for the `proxy` vs `serve` d
 
 `packages/mcp/` is the portable JavaScript package. Its `package.json` lists the platform packages
 as exact-version optional dependencies; it intentionally does not embed a `.node` binary. Publish
-the eight `packages/native/*` packages first, then publish `@octocodeai/freellama` and `@octocodeai/freellama-mcp-server`
-at the same version. `yarn release:verify:publish` refuses a release if any platform package has a
-missing, empty, or unpacked executable/addon pair.
+the eight `packages/native/*` packages first, then publish `@octocodeai/freellama` (`npx @octocodeai/freellama`) and `@octocodeai/freellama-mcp-server` (`npx @octocodeai/freellama-mcp-server`)
+at the same version. `yarn release:verify:publish` refuses a release if any of the ten packages
+omits `assets/logo.jpg`, or if any platform package has a missing, empty, or unpacked
+executable/addon pair.
 
 ```bash
 cd packages/mcp
 npm pack --dry-run   # confirm exactly what a publish would ship
 ```
 
-Version 0.1.0 is not published to a registry. Treat `npm publish` as a real, irreversible public
-action, and confirm with the repository owner first.
+Treat `npm publish` as a public release action. Follow the repository
+[release procedure](../../RELEASE.md) and obtain the repository owner's release authorization first.
 
 ## Why native bindings