@jmanuelcorral/openteam 0.2.2 → 0.9.1

package/README.md

@@ -19,8 +19,12 @@
 - [Installation](#installation)
 - [Quickstart: `openteam setup`](#quickstart-openteam-setup)
 - [The `openteam` agent](#the-openteam-agent)
-- [Runtime commands](#runtime-commands)
+- [Try it on another machine](#try-it-on-another-machine)
+- [Updating openteam](#updating-openteam)
 - [Configuration](#configuration)
+- [Usage](#usage)
+- [Runtime commands](#runtime-commands)
+- [Safe publishing](#safe-publishing)
 - [Privacy](#privacy)
 - [Quality](#quality)
 - [Compatibility](#compatibility)
@@ -38,7 +42,7 @@ The router keeps a privacy guarantee: with `privacyMode: "forceLocalOnSensitive"
 ## Features
 
 - Per-turn routing from the `chat.message` hook, mutating `output.message.model` before opencode persists the message.
-- Registration of OpenAI-compatible local runtimes: **Ollama**, **LM Studio** and **Foundry Local**.
+- Registration of OpenAI-compatible local runtimes: **Ollama**, **LM Studio**, **Lemonade Server** and **Foundry Local**.
 - Local JSON classifier with a deterministic heuristic fallback.
 - Capability profiles from [Models.dev](https://models.dev), with cache and a curated fallback when the catalog is unavailable.
 - **Cheapest-capable** frontier selection by blended cost `0.75 * inputUSD + 0.25 * outputUSD`.
@@ -46,23 +50,26 @@ The router keeps a privacy guarantee: with `privacyMode: "forceLocalOnSensitive"
 - Hash-only `CostRecord` JSONL telemetry: stores `promptHash`, cost/decision metrics — **never raw prompts**.
 - Multi-agent orchestration with `runRoleTask` / `runRoleTasks`, SDK child sessions and an explicit model in `client.session.prompt({ body: { model } })`.
 - Local availability refresh at startup and on `session.created` / `session.idle` events.
-- A local web **Console** aggregating every opencode session (cost, tokens, tool calls, routing, decisions) — redacted, loopback-only. **(alpha — see note below)**
+- A local web **Console** aggregating every opencode session (cost, tokens, tool calls, routing, decisions) — redacted, loopback-only.
 - A read-only **MCP server** exposing aggregated team memory, plus opt-in semantic recall.
 
 ## Requirements
 
-- opencode compatible with `@opencode-ai/plugin` `1.18.18`.
+- opencode compatible with `@opencode-ai/plugin` `1.18.19`.
 - [Bun](https://bun.sh) `1.3.14` for reproducible installs, development, and tests.
 - Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` for the published CLI/plugin.
 - Optional local runtimes:
   - Ollama at `http://localhost:11434/v1`.
   - LM Studio at `http://localhost:1234/v1`.
+  - Lemonade Server at `http://localhost:8000/api/v1`.
   - Foundry Local with a dynamic port discovered via CLI on Windows.
 
-> Local runtimes are **optional**. You can run openteam **frontier-only**, or point it at an Ollama / LM Studio running on **another machine on your LAN**.
+> Local runtimes are **optional**. You can run openteam **frontier-only**, or point it at an Ollama / LM Studio / Lemonade Server running on **another machine on your LAN**.
 
 ## Installation
 
+### Option A: npm package
+
 The package is published as [`@jmanuelcorral/openteam`](https://www.npmjs.com/package/@jmanuelcorral/openteam). These are the supported installation paths:
 
 | Need | Supported method |
@@ -73,6 +80,8 @@ The package is published as [`@jmanuelcorral/openteam`](https://www.npmjs.com/pa
 
 Global installation with npm is **not supported**. Bun is the only supported package installer. Node.js runs the published CLI/plugin within the declared engine range; npm is limited to maintainer-only `pack`, Trusted Publishing, and `link:local` operations.
 
+> **GitHub Packages route:** releases are published to both npmjs and private GitHub Packages. See [docs/guide/install-github-packages.md](docs/guide/install-github-packages.md) for the authenticated GitHub Packages install procedure, PATH setup on zsh, and Lemonade provider verification.
+
 For direct opencode loading, reference the package name:
 
 ```jsonc
@@ -112,7 +121,7 @@ For direct opencode loading, reference the package name:
           "hardStopOnBudgetExhaustion": false
         },
         "privacyMode": "forceLocalOnSensitive",
-        "telemetry": { "enabled": true, "path": ".opencode/openteam-telemetry.jsonl" }
+        "telemetry": { "enabled": true, "path": ".opencode/openteam-local/telemetry.jsonl" }
       }
     ]
   ]
@@ -121,12 +130,39 @@ For direct opencode loading, reference the package name:
 
 The fastest way to get a repository ready is the interactive `openteam setup` command (below), which generates this configuration for you.
 
+### Option B: development path
+
+During development you can load a local plugin from `.opencode/plugins/openteam.ts`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./.opencode/plugins/openteam.ts",
+      {
+        "router": {
+          "mode": "balanced",
+          "localDefault": {
+            "providerID": "ollama",
+            "modelID": "qwen3:8b"
+          }
+        },
+        "telemetry": {
+          "path": ".opencode/openteam-local/telemetry.jsonl"
+        }
+      }
+    ]
+  ]
+}
+```
+
 ## Quickstart: `openteam setup`
 
-`openteam setup` detects the installed local runtimes (Ollama, LM Studio, Foundry Local — all optional), lets you pick the local models and the **frontier baseline** model (sorted cheapest-capable first), and writes three files:
+`openteam setup` detects the installed local runtimes (Ollama, LM Studio, Lemonade Server, Foundry Local — all optional), lets you pick the local models and the **frontier baseline** model (sorted cheapest-capable first), and writes three files:
 
 - `opencode.json` at the repo root: declares the `@jmanuelcorral/openteam` plugin, the OpenAI-compatible local `provider`s, the frontier `model` and the local `small_model`.
-- `.opencode/openteam.json`: openteam's validated runtime configuration (baseline, routing, local runtimes and privacy).
+- `.opencode/openteam.json`: openteam's validated runtime configuration (baseline, routing, local runtimes, orchestrator roles and privacy).
 - `.opencode/agent/openteam.md`: the **primary `openteam` agent**, visible in the Tab switcher.
 
 ```powershell
@@ -152,16 +188,196 @@ After `setup`, authenticate the frontier provider (`opencode auth login`), make
 
 `openteam setup` generates a single **primary agent** named `openteam`. Press **Tab** in opencode to select it: you explicitly know you are in openteam mode while the plugin keeps optimizing the model underneath.
 
-That orchestrator ships **no pre-created subagents**. On **every request** its first action is to check whether a team already exists (`.opencode/openteam-roster.md` + subagents in `.opencode/agent/`). If it does, it hands work to the right specialists; if not, it understands the tasks your request implies, designs the minimal team and **creates it on demand** (writing `.opencode/agent/<name>.md` with `mode: subagent`), reusing existing agents before creating new ones. Mechanical/bulk roles are left to route to local models; only architecture, security or ambiguous debugging escalate to frontier. (This on-demand, themed-team model is inspired by [Squad](https://bradygaster.github.io/squad/) — see [Acknowledgements](#acknowledgements).)
+That orchestrator ships **no pre-created subagents**. On **every request** its first action is to check whether a team already exists (`.opencode/openteam/roster.md` + subagents in `.opencode/agent/`). If it does, it hands work to the right specialists; if not, it understands the tasks your request implies, designs the minimal team and **creates it on demand** (writing `.opencode/agent/<name>.md` with `mode: subagent`), reusing existing agents before creating new ones. Mechanical/bulk roles are left to route to local models; only architecture, security or ambiguous debugging escalate to frontier. (This on-demand, themed-team model is inspired by [Squad](https://bradygaster.github.io/squad/) — see [Acknowledgements](#acknowledgements).)
 
-The team has a **themed identity**: the orchestrator picks (or asks for) a **universe** and names each agent after a character, recording the cast in `.opencode/openteam-roster.md` so names **persist** across sessions. Besides project-specific roles, it plans three **standard roles** created on demand:
+The team has a **themed identity**: the orchestrator picks (or asks for) a **universe** and names each agent after a character, recording the cast in `.opencode/openteam/roster.md` so names **persist** across sessions. Besides project-specific roles, it plans three **standard roles** created on demand:
 
-- **scribe** — silent memory: logs decisions and learnings to `.opencode/openteam-decisions.md` without touching code (local model).
+- **scribe** — silent memory: logs decisions and learnings to `.opencode/openteam/decisions.md` without touching code (local model).
 - **ralph** — automation and triage: monitors the backlog, prioritizes, coordinates execution and **escalates to the human** on blockers or approvals.
 - **guardian** — security and privacy: **detects and masks sensitive data** (PII, secrets, API keys, tokens) before it reaches frontier; always runs locally and respects `forceLocalOnSensitive`.
 
 Before delegating, the orchestrator **plans dependencies and parallelizes**: it splits the request into tasks and, since opencode runs all `task` calls emitted in a single turn in parallel (Vercel AI SDK), it launches independent tasks together and sequences only the dependent ones into waves. Work that collides on the same files is separated into distinct waves to avoid conflicts. In the **todo list** each entry shows the responsible agent via a name prefix, e.g. `[@Basher] Implement the router`.
 
+## Try it on another machine
+
+To install and try openteam on another machine that already has [opencode](https://opencode.ai) and [Bun](https://bun.sh):
+
+1. **Run or install the CLI.** Pick one of the supported paths:
+
+   ```powershell
+   # Global option (leaves the `openteam` command on the PATH)
+   bun add --global @jmanuelcorral/openteam@latest
+
+   # One-off option (no global install)
+   bunx --package @jmanuelcorral/openteam@latest openteam setup
+   ```
+
+2. **Initialize the repository** you will work in. It generates `opencode.json`, `.opencode/openteam.json` and `.opencode/agent/openteam.md`:
+
+   ```powershell
+   cd C:\path\to\your\repo
+   openteam setup          # global
+   # The one-off option already ran setup in the previous step.
+   ```
+
+   The wizard detects Ollama / LM Studio / Foundry Local, lets you pick the local models (local or on another machine on the LAN) or **none** to run frontier-only, and the frontier baseline, then writes the configuration.
+
+3. **Authenticate the frontier provider** you chose:
+
+   ```powershell
+   opencode auth login
+   ```
+
+4. **Start your local runtime** if you enabled one and it was not already up (e.g. `ollama serve`, or open LM Studio / Foundry Local). If you pointed at a runtime on **another machine on the LAN**, make sure it is reachable from this machine (host exposed and port open); for Ollama this usually means starting it with `OLLAMA_HOST=0.0.0.0 ollama serve` on the remote machine. If you configured **frontier-only**, skip this step.
+
+5. **Open opencode in the repo**, press **Tab** and pick the `openteam` agent. Give it the first prompt: it will create the subagent team on demand and route local-first automatically.
+
+Check the status with `openteam doctor` (runtimes + config) and the savings with `openteam report`.
+
+## Updating openteam
+
+openteam is published to npm when a GitHub Release is published. To pull the latest version:
+
+```powershell
+# Global install
+bun add --global @jmanuelcorral/openteam@latest
+```
+
+Check versions:
+
+```powershell
+bun pm ls --global                         # installed global packages
+```
+
+The most recent published version is shown at
+<https://www.npmjs.com/package/@jmanuelcorral/openteam>.
+
+Notes when updating:
+
+- **You do not need to re-run `openteam setup`** to update the plugin: opencode resolves the `@jmanuelcorral/openteam` package declared in `opencode.json` to the installed version. Restart opencode so it reloads the plugin.
+- Re-run `openteam setup` **only** if you want to regenerate the configuration (change runtimes, models or baseline). It asks for confirmation before overwriting `opencode.json`, `.opencode/openteam.json` or `.opencode/agent/openteam.md`; it **does not touch the subagents** the orchestrator created on demand.
+- One-off adjustments without a re-init: `openteam baseline set <provider/model>` or `openteam baseline auto`.
+
+## Configuration
+
+The canonical runtime configuration lives in `.opencode/openteam.json`; this repo ships `.opencode/openteam.example.json` as a complete example. The Zod-validated shape is in `src/config/schema.ts`. `telemetry` is a plugin option read by `src/index.ts`, not part of the persisted `OpenTeamConfig`.
+
+Config files are strict: unknown keys fail closed in both the CLI and plugin
+instead of being silently ignored. Errors name each rejected path (for example
+`router.trivialPromptMxChars`) and include a nearest-key hint when available.
+This strict validation applies to the config file on both paths; programmatic
+plugin options are a separate surface and are not yet strictly validated (#102).
+Existing configs without `configVersion` remain valid because openteam migrates
+them to the current version before validation.
+
+### opencode config file resolution
+
+openteam reads the opencode project config from **two candidate paths** and
+merges them — the same way opencode itself handles multiple config files:
+
+| Priority | Path |
+| --- | --- |
+| Higher (overrides) | `.opencode/opencode.json` |
+| Base | `opencode.json` (project root) |
+
+Non-conflicting keys from both files survive. When the same key appears in
+both, `.opencode/opencode.json` wins. This is verified against opencode 1.18.18:
+a provider declared in either location appears in `opencode models --pure`.
+
+**JSONC comments** (`//` line comments and `/* … */` block comments) are
+tolerated in both files — opencode itself accepts them, and openteam strips them
+before parsing, so a commented config file works identically to a plain JSON one.
+
+**Malformed config** — if one of the candidate files is present but cannot be
+parsed (invalid JSON, schema violation), `doctor` and `agents` emit a warning
+that names the offending file and continue rather than aborting. A bad config
+file is not treated as a fatal error.
+
+**"Provider not configured"** messages name the two paths that were searched,
+so you immediately know whether the file was not found or the provider is
+genuinely absent from both locations.
+
+**`openteam setup` write location** — when setting up a fresh project (no
+existing opencode config file), `setup` now writes to `.opencode/opencode.json`.
+When an existing file is detected it is updated in place — only one file is
+written, never both. Upgrading users: a re-run of `setup` will land in
+`.opencode/` if no root `opencode.json` is present.
+
+**No upward traversal** — openteam reads only the two cwd-relative candidates
+above. It does not walk up to the git root. Commands are designed to be run from
+the project root; if you run them from a subdirectory you will see "provider not
+configured" and should `cd` to the project root first.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | In `auto`, uses cheapest-capable frontier profiles when passed to the router; in `pinned`, uses `baseline.pinnedModel` if set. |
+| `baseline.pinnedModel` | `ModelRef \| null` | `null` | Explicitly pinned frontier model. `ModelRef` is `{ "providerID": string, "modelID": string }`. |
+| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Frontier fallback when there are no cheapest-capable profiles or a valid pin. |
+| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Validated routing mode reserved for policy. |
+| `router.localDefault` | `ModelRef \| null` | `null` | Primary local model. Not set by default — no local model is routed until you configure one via `openteam setup` or by hand. |
+| `router.trivialPromptMaxChars` | positive integer | `280` | Code-free prompts up to this size prefer local. |
+| `router.frontierPromptMinChars` | positive integer | `2000` | Prompts from this size are frontier candidates if no guards apply. |
+| `local.runtimes` | `LocalRuntime[]` | `[]` | Local runtimes to probe. Empty by default — no runtime is configured until you run `openteam setup` or add an entry by hand. |
+| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local" \| "lemonade"` | required | Local runtime. |
+| `local.runtimes[].enabled` | `boolean` | `true` | Enable or disable that runtime. |
+| `local.runtimes[].baseURL` | optional URL | per runtime/config | OpenAI-compatible endpoint (`/v1` for Ollama/LM Studio, `/api/v1` for Lemonade); Foundry Local may omit it when using discovery. |
+| `local.runtimes[].discovery` | `"cli" \| "sdk" \| "manual"` optional | none per item | Foundry Local discovery; the registry uses CLI when configured and not `manual`. |
+| `local.runtimes[].defaultModel` | `ModelRef` | required | Default model for that runtime. |
+| `budgets.sessionUSD` | positive number, optional | unlimited | Frontier budget per session. |
+| `budgets.monthlyUSD` | positive number, optional | unlimited | Monthly frontier budget. |
+| `budgets.frontierTokensPerSession` | positive integer, optional | unlimited | Frontier token limit per session. |
+| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | If `true`, an exhausted budget returns `blockFrontier`; if `false`, it forces local. |
+| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Privacy policy for sensitive tasks. |
+| `orchestrator.roles` | `Record<string, AgentRoleProfile>` | `{}` | Custom or overridden role profiles keyed by role ID. Config entries are validated with the same strict role profile schema as built-in roles and take precedence over `TEAM_ROLES`; if an entry omits `roleID`, the map key is used. Unknown roles not declared here still use the neutral fallback and warn once. |
+| `orchestrator.roles.<role>.opencodeAgent` | non-empty string, optional | role ID | opencode agent name to dispatch for that role. |
+| `orchestrator.roles.<role>.defaultTier` | `"trivial" \| "simple" \| "moderate" \| "hard"` | required | Baseline complexity tier used before heuristic and permission elevation. |
+| `orchestrator.roles.<role>.minReasoningTier` | `1`–`5` | required | Minimum reasoning capability for frontier candidates. |
+| `orchestrator.roles.<role>.minCodeQualityTier` | `1`–`5` | required | Minimum code-quality capability for frontier candidates. |
+| `orchestrator.roles.<role>.needsToolCallingByDefault` | `boolean` | required | Whether this role requires tool-calling capability unless the task says otherwise. |
+| `orchestrator.roles.<role>.preferredFrontierModels` | `Array<ModelRef \| "auto">` | required | Preferred frontier models; use `[]` for a local-first role with no explicit frontier preference. |
+| `orchestrator.roles.<role>.localFirst` | `boolean` | required | Whether the role should keep the normal local-first posture instead of forcing hard frontier routing. |
+| `telemetry.enabled` | `boolean` (plugin option) | `true` | Enable/disable JSONL writing. |
+| `telemetry.path` | `string` (plugin option) | `.opencode/openteam-local/telemetry.jsonl` | Path of the `CostRecord` JSONL log. |
+
+Example custom privacy/security auditor:
+
+```jsonc
+{
+  "orchestrator": {
+    "roles": {
+      "galadriel": {
+        "opencodeAgent": "galadriel",
+        "defaultTier": "moderate",
+        "minReasoningTier": 3,
+        "minCodeQualityTier": 3,
+        "needsToolCallingByDefault": true,
+        "preferredFrontierModels": [],
+        "localFirst": true
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+On each turn, openteam derives signals from the prompt (`promptChars`, `hasCode`, `privacySensitive`, `requiresTools` and a model override if present), runs `chooseModel` and assigns `output.message.model`.
+
+Multi-agent orchestration uses static roles and opencode subsessions:
+
+| Role | opencode agent | Base tier | Policy |
+| --- | --- | --- | --- |
+| `rusty` | `architect` | `hard` | Architecture and high-risk decisions; frontier auto. |
+| `livingston` | `integration` | `moderate` | TS/opencode integration; tool calling by default. |
+| `yen` | `local-runtime` | `moderate` | Local runtimes; local-first with frontier fallback. |
+| `basher` | `routing-cost` | `moderate` | Router, cost and budget; local-first. |
+| `scribe` | `scribe` | `trivial` | Documentation and summaries; local-first. |
+| `linus` | `tester` | `simple` | Tests and contracts; local-first with tools. |
+
+`runRoleTask` runs a single subsession; `runRoleTasks` runs several with a `batchID`. Roles with `destructive` or `multiFileEdit` elevate the tier before choosing a model.
+
+To see savings and decisions, read the telemetry JSONL. Key fields: `promptHash`, `promptChars`, `tier`, `routeKind`, `selected`, `rationale`, `estimatedCostUSD`, `baselineCostUSD`, `estimatedSavingsUSD`, `budgetAction`, `tokensIn` and `tokensOut`.
+
 ## Runtime commands
 
 openteam exposes commands to inspect and change routing without editing JSON by hand, over three equivalent surfaces.
@@ -205,16 +421,18 @@ openteam baseline set openai/gpt-5-mini
 openteam doctor --config .opencode/openteam.json
 openteam agents
 openteam console
-openteam report --telemetry .opencode/openteam-telemetry.jsonl
+openteam report --telemetry .opencode/openteam-local/telemetry.jsonl
 openteam yolo status
 openteam local status
+openteam clear-cache
+openteam clear-cache --delete
 ```
 
-Flags: `--config <path>` and `--telemetry <path>` override the default paths; `--opencode <path>` points the `yolo` command at a specific `opencode.json`.
+Flags: `--config <path>` and `--telemetry <path>` override the default paths; `--opencode <path>` points the `yolo` command at a specific `opencode.json`. An explicit `--config` may be relative or absolute and must be readable; only the default `.opencode/openteam.json` lookup falls back to built-in defaults when absent.
 
 ### See each agent's LLM: `openteam agents`
 
-Lists the agents in `.opencode/agent/`, showing **which LLM each one uses**: whether it is **local** (Ollama/LM Studio/Foundry, no token cost) or **frontier** (consumes your subscription), and the provider. Agents without their own `model` **inherit** the `opencode.json` default (which openteam routes local-first per message).
+Lists the agents in `.opencode/agent/`, showing **which LLM each one uses**: whether it is **local** (Ollama/LM Studio/Lemonade/Foundry, no token cost) or **frontier** (consumes your subscription), and the provider. Agents without their own `model` **inherit** the `opencode.json` default (which openteam routes local-first per message).
 
 ### YOLO mode (auto-approve permissions)
 
@@ -242,44 +460,82 @@ openteam local on       # back to local-first routing
 
 This persists the `router.frontierOnly` flag in `.opencode/openteam.json`. With `frontierOnly` active the router picks the **cheapest-capable frontier**, but still **respects privacy, budgets and explicit per-task overrides**. Sensitive prompts with `forceLocalOnSensitive` don't leave for frontier; `local off` degrades that policy to `consentBeforeFrontier` (local can't be forced without a runtime) and tells you about the change.
 
-### Multi-session web Console: `openteam console` (alpha)
+### Updating the plugin and clearing the cache: `openteam clear-cache`
+
+opencode caches each plugin installation and never refreshes an existing entry —
+there is no version comparison, TTL, or upstream eviction command. Publishing a
+new version of the plugin has **no effect** on a machine that already has a
+cache entry. Deleting the cache directory is the only eviction path.
+
+```powershell
+openteam clear-cache                       # report only — prints the table, deletes nothing
+openteam clear-cache --delete              # delete all matched cache entries
+openteam clear-cache --cache-root <path>   # override the auto-resolved cache root
+```
+
+Slash command alias inside opencode: `/openteam-clear-cache`
+
+The default (no flags) prints a table with columns `spec dir`, `spec-pinned`,
+`installed` and `mtime` for every `@jmanuelcorral/openteam*` cache entry found.
+Only entries in that scope are ever touched. Symlinks and Windows reparse points
+are listed as `[SKIP — reparse point]` and never deleted. On Windows, close
+opencode before running `--delete` to avoid `[LOCKED]` errors.
+
+See [docs/guide/update-plugin.md](docs/guide/update-plugin.md) for the full
+explanation of the freeze mechanism and a step-by-step update procedure.
+
+### Unattended mode: `openteam loop` (Ralph pattern) 🎯 *(`--dry-run` verified; live dispatch design-stage)*
+
+A second mode of operation: an **external loop** that invokes `opencode run` against a persistent backlog until it is drained, with fresh context per iteration and safety caps (budget, max iterations, no-progress). It complements the interactive orchestrator, it does not replace it. As a safety property, `openteam loop` **refuses to run unattended without explicit confirmation** — running bare it prints *"Refusing to run unattended without confirmation. Re-run with --dry-run to preview the plan, or --yes to run."* and exits non-zero; `openteam loop --dry-run` previews the plan (backlog, iteration and budget caps, sleep, fresh-context and stop conditions) without dispatching anything. The `--dry-run` preview and the bare-invocation refusal are **verified against the shipped binary** (`node dist/cli.js loop --dry-run` exits 0 and prints the plan; running bare exits non-zero); the actual unattended dispatch (`--yes`) is **not yet verified end-to-end and remains design-stage**. See the design and examples in **[docs/loop.md](docs/loop.md)**.
 
-> ⚠️ **Alpha — not finished.** The Console (and the `tunnel` command below) is an
-> early, experimental feature that may still be **reworked or rebuilt**, with
-> breaking changes to its UI, endpoints, config (`console` block) and event
-> format. The routing, budgets, telemetry and memory core are stable; the web
-> surface is not yet. Use it for local observation, not as a stable API.
+### Multi-session web Console: `openteam console`
 
 openteam exposes a **local web Console** you launch from the CLI with `openteam console`. It aggregates **all** opencode sessions at once (one tab per session, plus "All"), because each plugin **writes redacted events** to per-session JSONL logs that the Console watches (`fs.watch`) and aggregates.
 
 It shows live: **real cost and tokens per message** (input/output/reasoning/cache), **tool calls with duration** and ok/fail, recent routing (cost/savings and chosen model — **prompt hashes only, never text**), agent **decisions** (scribe) and **meetings** (multi-agent batches), loop backlog progress, the agent team and latest commits. It updates over **SSE** (with polling fallback).
 
+Each session tab also includes a **"Session" view**: a console where you can **watch the live output** (SSE) and **send prompts** or **answer permissions** for that opencode session, authenticated with an **ephemeral token** per launch. Optionally, with the `terminal.pty` flag, a **"Terminal" view** opens a **real shell** in the workspace via opencode's PTY API (no `node-pty`).
+
 ```powershell
 openteam console          # print the URL and serve the multi-session Console
 openteam console --open   # also open the browser
 openteam console --status # print the config only (don't launch the server)
 ```
 
-> **Security**: the server listens **on loopback only** (`127.0.0.1`/`localhost`, Zod-validated) and **never exposes prompts** (only `promptHash`), tool-call args or message content — only counters, costs and redacted summaries. The "Session"/"Terminal" view requires the ephemeral token.
+See the [Console guide](docs/console.md) for the full reference.
 
-### Secure remote access: `openteam tunnel` (alpha)
+Sessions are read from:
 
-> ⚠️ **Alpha — not finished.** Like the Console, `tunnel` is experimental and may
-> be reworked or rebuilt. Treat its flags and behavior as unstable.
+```text
+.opencode/openteam-local/sessions/*.jsonl
+```
 
-To reach the Console (and optionally operate the terminal) **from outside**, `openteam tunnel` exposes it via **Microsoft Dev Tunnels** instead of binding to `0.0.0.0`:
+You can tune host/port and the terminal in `.opencode/openteam.json` (`console`
+block):
 
-```powershell
-openteam tunnel                    # expose only the Console (observation), authenticated
-openteam tunnel --terminal         # also expose opencode for the remote terminal
-openteam tunnel --allow-anonymous --yes  # anonymous tunnel (requires double confirmation)
+```json
+{
+  "console": {
+    "host": "127.0.0.1",
+    "port": 4599,
+    "autoPortFallback": true,
+    "refreshMs": 2000,
+    "recentRoutes": 50,
+    "openBrowser": false,
+    "terminal": { "enabled": true, "pty": false }
+  }
+}
 ```
 
-> **Tunnel security**: authenticated by default. The **remote terminal** requires `OPENCODE_SERVER_PASSWORD` to be set; without it, `--terminal` is ignored. Install devtunnel with `winget install Microsoft.devtunnel` and sign in with `devtunnel user login`.
+**Live agent-graph view.** The Console can also render a live **agent graph** of a Graph run; it is **off by default** and turned on with `console.graphView.enabled: true` — see [Graph observability web](docs/guide/graph-observability-web.md) for setup and the full requirements.
+
+> **Security**: the server listens **on loopback only** (`127.0.0.1`/`localhost`, Zod-validated) and **never exposes prompts** (only `promptHash`), tool-call args or message content — only counters, costs and redacted summaries. The "Session"/"Terminal" view requires the ephemeral token. If the port is busy and `autoPortFallback` is `true`, it tries the next free one. Remote access via `openteam tunnel` was **removed from the MVP** (2026-08-31) and will be redefined later; the Console has no built-in remote-exposure path.
+
+**Interface stability.** The Console's web surface is **pre-1.0**: its UI, endpoints, `console` config block and event format may still change. The routing, budgets, telemetry and memory core are stable.
 
 ### Team memory over MCP (read-only): `openteam mcp`
 
-`openteam mcp` starts a **read-only MCP server** (JSON-RPC 2.0 over stdio, no dependencies) that exposes the team memory aggregated from per-session events. It uses the same `StorageProvider` as the Console and **never** exposes raw prompts. Tools: `list_decisions` (filterable by `agent`/`tag`), `list_meetings`, `list_sessions` and `cost_summary`.
+`openteam mcp` starts a **read-only MCP server** (JSON-RPC 2.0 over stdio, no dependencies) that exposes the team memory aggregated from per-session events. It uses the same `StorageProvider` as the Console and **never** exposes raw prompts. Tools: `list_decisions` (filterable by `agent`/`tag`), `list_meetings`, `list_sessions` and `cost_summary` (real cost/tokens + estimated savings vs the all-frontier baseline).
 
 Register it in `opencode.json` like any local MCP server:
 
@@ -291,34 +547,134 @@ Register it in `opencode.json` like any local MCP server:
 }
 ```
 
-Opt-in **semantic recall** (`recall_facts`, `recall_preferences`, `similar_tasks`) is available via the `memory.semantic` block in `.opencode/openteam.json`; queries are embedded **locally** (never leave for frontier). See [docs/architecture.md](docs/architecture.md) and the Spanish [README.es.md](README.es.md) for full details.
+#### Semantic recall (opt-in): `recall_facts`, `recall_preferences`, `similar_tasks`
 
-## Configuration
+Beyond team memory, `openteam mcp` can expose **semantic recall** of the long-term knowledge memory (facts, preferences, similar tasks). It is **disabled by default**; enable it with the `memory.semantic` block in `.opencode/openteam.json`:
 
-The canonical runtime configuration lives in `.opencode/openteam.json`; this repo ships `.opencode/openteam.example.json` as a complete example. The Zod-validated shape is in `src/config/schema.ts`. `telemetry` is a plugin option read by `src/index.ts`, not part of the persisted `OpenTeamConfig`.
+```json
+{
+  "memory": {
+    "semantic": { "enabled": true }
+  }
+}
+```
 
-| Key | Type | Default | Description |
-| --- | --- | --- | --- |
-| `baseline.mode` | `"auto" \| "pinned"` | `"auto"` | In `auto`, uses cheapest-capable frontier profiles when passed to the router; in `pinned`, uses `baseline.pinnedModel` if set. |
-| `baseline.pinnedModel` | `ModelRef \| null` | `null` | Explicitly pinned frontier model. `ModelRef` is `{ "providerID": string, "modelID": string }`. |
-| `baseline.hardDefault` | `ModelRef` | `{ "providerID": "anthropic", "modelID": "claude-sonnet-4-5" }` | Frontier fallback when there are no cheapest-capable profiles or a valid pin. |
-| `router.mode` | `"economy" \| "balanced" \| "quality"` | `"balanced"` | Validated routing mode reserved for policy. |
-| `router.localDefault` | `ModelRef` | `{ "providerID": "ollama", "modelID": "qwen3:8b" }` | Primary local model. |
-| `router.trivialPromptMaxChars` | positive integer | `280` | Code-free prompts up to this size prefer local. |
-| `router.frontierPromptMinChars` | positive integer | `2000` | Prompts from this size are frontier candidates if no guards apply. |
-| `local.runtimes` | `LocalRuntime[]` | Ollama enabled at `http://localhost:11434/v1` with `qwen3:8b` | Minimal list of one local runtime. |
-| `local.runtimes[].id` | `"ollama" \| "lmstudio" \| "foundry-local"` | required | Local runtime. |
-| `local.runtimes[].enabled` | `boolean` | `true` | Enable or disable that runtime. |
-| `local.runtimes[].baseURL` | optional URL | per runtime/config | OpenAI-compatible `/v1` endpoint; Foundry Local may omit it when using discovery. |
-| `local.runtimes[].discovery` | `"cli" \| "sdk" \| "manual"` optional | none per item | Foundry Local discovery; the registry uses CLI when configured and not `manual`. |
-| `local.runtimes[].defaultModel` | `ModelRef` | required | Default model for that runtime. |
-| `budgets.sessionUSD` | positive number, optional | unlimited | Frontier budget per session. |
-| `budgets.monthlyUSD` | positive number, optional | unlimited | Monthly frontier budget. |
-| `budgets.frontierTokensPerSession` | positive integer, optional | unlimited | Frontier token limit per session. |
-| `budgets.hardStopOnBudgetExhaustion` | `boolean` | `false` | If `true`, an exhausted budget returns `blockFrontier`; if `false`, it forces local. |
-| `privacyMode` | `"forceLocalOnSensitive" \| "consentBeforeFrontier" \| "off"` | `"forceLocalOnSensitive"` | Privacy policy for sensitive tasks. |
-| `telemetry.enabled` | `boolean` (plugin option) | `true` | Enable/disable JSONL writing. |
-| `telemetry.path` | `string` (plugin option) | `.opencode/openteam-telemetry.jsonl` | Path of the `CostRecord` JSONL log. |
+When enabled, and if there is a local runtime with a `baseURL`, the server adds three tools: `recall_facts`, `recall_preferences` and `similar_tasks`. The query is embedded **locally** (never leaves for frontier) and records are **redacted at the source** (`storeContent=false` by default), so the tools never return raw prompts. If `bun:sqlite` is missing or the index cannot be opened, `openteam mcp` **degrades safely** and keeps exposing team memory only.
+
+#### Consolidation / forgetting: `openteam memory consolidate`
+
+Long-term memory **forgets** by decay: each record's confidence decays over time and, once it falls below the threshold, it is marked soft-invalidated (without deleting: the history is kept for "as-of" auditing). Run the forgetting pass with:
+
+```powershell
+openteam memory consolidate
+```
+
+It appends *tombstones* to the memory log and reports how many records were forgotten. It is idempotent and non-destructive.
+
+#### Automatic push to context (opt-in)
+
+With injection enabled, openteam **prepends** relevant memory to the prompt on each turn (`chat.message`), respecting a token budget:
+
+```json
+{
+  "memory": {
+    "semantic": {
+      "enabled": true,
+      "injection": { "enabled": true, "maxChars": 1200, "maxItems": 8 }
+    }
+  }
+}
+```
+
+It is **disabled by default**. Injection happens **after** the model is chosen, so it does not alter routing or telemetry, and it **never breaks the turn** if recall fails. It only injects what is already in the records (redacted at the source if `storeContent=false`).
+
+### Ollama
+
+```powershell
+ollama serve
+ollama pull qwen3:8b
+Invoke-RestMethod -Uri "http://localhost:11434/v1/models" -Method Get
+```
+
+### LM Studio
+
+1. Open LM Studio.
+2. Load a compatible model.
+3. Enable the local OpenAI-compatible server on port `1234`.
+
+```powershell
+Invoke-RestMethod -Uri "http://localhost:1234/v1/models" -Method Get
+```
+
+### Lemonade Server
+
+```powershell
+Invoke-RestMethod -Uri "http://localhost:8000/api/v1/models" -Method Get
+```
+
+### Foundry Local
+
+```powershell
+foundry service status
+```
+
+openteam extracts the port from the CLI output and normalizes the endpoint to `http://localhost:<PORT>/v1`.
+
+### Telemetry
+
+openteam writes a hash-only `CostRecord` JSONL log (never raw prompts). Tail the most recent entries:
+
+```powershell
+Get-Content -Path ".opencode/openteam-local/telemetry.jsonl" -Tail 5
+```
+
+### Local verification
+
+```powershell
+bun test
+bun run typecheck
+bun run lint
+bun run format:check
+bun run build
+```
+
+### Local development in dev mode (no registry)
+
+To make the global `openteam` CLI and opencode use this repo's local build instead
+of the published version (without going through any registry), the package is
+linked with a global symlink:
+
+```powershell
+bun run link:local   # = bun run build && npm link
+```
+
+`npm link` creates a global link (junction/symlink) to this repo, so after each
+`bun run build` the global CLI reflects the local code.
+
+A versioned `pre-push` hook (`.githooks/pre-push`) can run `bun run link:local`
+before each `git push`, keeping the local install current. Installing
+dependencies does **not** modify Git. Enable the hook explicitly, once per clone:
+
+```powershell
+bun run hooks:install
+```
+
+The hook warns if the build or the link fails, but it **does not block** the push.
+
+## Safe publishing
+
+The release workflow builds and verifies a single tarball with no write
+permissions and no OIDC. Another job publishes exactly that artifact, after
+validating its integrity, via npm Trusted Publishing; a final job with only
+`contents: write` attaches it to the GitHub Release. There is no fallback to
+persistent credentials, and normal CI needs no npm configuration.
+
+Before the first real release, the owner must register an npm Trusted Publisher
+for `@jmanuelcorral/openteam` with owner `jmanuelcorral`, repository `openteam`,
+workflow `release.yml`, allowed action `npm publish` and no environment. Until
+that one-time registration is complete, publishing fails closed. After the first
+successful OIDC publish, enforce token-less 2FA, revoke the old automation token
+and remove its inherited GitHub Actions secret.
 
 ## Privacy
 
@@ -340,13 +696,13 @@ Non-negotiable gates (see [docs/testing-and-quality.md](docs/testing-and-quality
 
 ## Compatibility
 
-See [docs/compatibility.md](docs/compatibility.md). Verified summary as of `2026-08-23`:
+See [docs/compatibility.md](docs/compatibility.md). Verified summary as of `2026-08-24`:
 
 | Surface | Version / contract |
 | --- | --- |
-| openteam | `0.2.2`; current package version |
-| `@opencode-ai/plugin` | `1.18.18` |
-| `@opencode-ai/sdk` | `1.18.18` |
+| openteam | `0.9.1`; current package version |
+| `@opencode-ai/plugin` | `1.18.19` |
+| `@opencode-ai/sdk` | `1.18.19` |
 | Routing hook | `chat.message`; not `chat.params` for model changes |
 | Child sessions | `client.session.create` + `client.session.prompt({ body: { model } })` |
 
@@ -359,12 +715,12 @@ Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for th
 | Phase | Status | Deliverables |
 | --- | --- | --- |
 | 0. Scaffold / PoC | Done | TS/Bun, minimal plugin, `chat.message` hook. |
-| 1. Local registry + heuristic router | Done | Ollama/LM Studio/Foundry, probes and deterministic `chooseModel`. |
+| 1. Local registry + heuristic router | Done | Ollama/LM Studio/Lemonade/Foundry, probes and deterministic `chooseModel`. |
 | 2. Classifier + profiles + budget + telemetry | Done | Local classifier, `ModelCapabilityProfile`, budgets and `CostRecord`. |
 | 3. Multi-agent orchestration | Done | Coordinator, roles, child sessions and permissions. |
 | 4. npm packaging + docs | Done | Exportable package, README, Windows examples and compatibility matrix. |
 | 5. Runtime commands | Done | `baseline show/set/auto`, `doctor` and `report` via tool, `/openteam` and CLI `bin`. |
-| 6. Web Console + MCP memory | Done (Console/tunnel **alpha**) | Multi-session Console and `tunnel` are experimental and may be reworked; read-only MCP server and semantic recall are stable. |
+| 6. Web Console + MCP memory | Done | The multi-session Console is loopback-only and gate-covered; read-only MCP server and semantic recall are stable. |
 
 ## License