rockycode 0.1.1__tar.gz → 0.2.0__tar.gz

rockycode-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+# One job: build sdist+wheel on ubuntu, publish to PyPI via Trusted Publishing.
+# The old macos-13 matrix (built a cbor2 x86_64-mac wheel for the release page)
+# is gone: the runner label was retired, so it never actually ran — 0.1.0 and
+# 0.1.1 both sat in its queue until cancelled and shipped fine without it — and
+# cbor2 still publishes no x86_64-mac wheel to attach anyway (arm64 only; an
+# Intel-Mac install builds it from source via Rust, PyPI-side, as it always
+# has). GitHub releases are created by hand: gh release create --notes-file.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write            # OIDC — this is what Trusted Publishing uses
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build rockycode (sdist + wheel — only our project lands in dist/)
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing, no token)
+        uses: pypa/gh-action-pypi-publish@release/v1

rockycode-0.2.0/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+All notable changes to rockycode are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project follows
+[Semantic Versioning](https://semver.org/) — pre-1.0, so the surface may still
+change between minor versions.
+
+## [Unreleased]
+
+## [0.2.0] — models are data, loops, approval switch
+
+### Added
+- **Loops** (`/loop`, alias `/cron`): re-fire one prompt into THIS chat on an
+  interval — `/loop 5m check whether results/run3 has a summary.json; if so
+  give me the headline numbers`. Each tick is an ordinary turn on the session
+  engine (it sees the whole conversation), runs only when the chat is idle,
+  ends with `LOOP QUIET / NOTE / DONE`, and never prompts: a call that needs
+  approval pauses the loop (`/loop allow` decides it, `/loop resume` retries,
+  `/permission yolo` or shift+tab resumes every approval-paused loop; a manual
+  `/loop pause` stays paused). Quiet ticks fold into one streak line and roll
+  out of live context (the trajectory keeps them). No cap unless you set one
+  (`for 3h`, `x12`, `max $2`); soft running-cost reminders otherwise. Rocky
+  can start one itself (`loop_start` / `loop_stop`, through the normal
+  approval). Session-only — a loop dies with the session; `/routines` stays
+  the cross-launch scheduler.
+- **Models are data.** The whole model catalog now lives in
+  `rockycode/models.toml` — per provider a China base URL, a rocky-owned key
+  name, a reasoning wire shape (`thinking` · `effort` · `enable_thinking` ·
+  `minimax` · `openai` · `none`), its own effort tiers, whether thinking can
+  be switched off, and where usage reports cache hits; per model its context
+  window, output cap, vision flag, price tables (USD + CNY) and roles. The
+  engine consumes a `ModelSpec` and carries no model-specific numbers of its
+  own. `~/.rockycode/models.toml` (same shape) is deep-merged on top: add a
+  model, correct a limit, add a price, `hidden = true` to drop a row.
+- The 2026-09 roster: `deepseek-flash` (V4.1 Flash — native vision, the
+  default and the sidecar/search model) + `deepseek-v4-pro`; `glm-5.3` +
+  `glm-5.3-flash`; `kimi-k3`; `minimax-m3`; `step-5-preview`; `qwen3.8-max`
+  + `qwen3.8-flash`; `mimo-v2.6-pro`; `ollama` (live-discovered). Limits and
+  DeepSeek's V4.1 prices verified at each provider's docs on 2026-09-29.
+- Subscription-plan endpoints as their own picker rows: `qwen-plan` (Bailian
+  Token Plan), `mimo-plan`, `stepfun-plan` — own URL, own key
+  (`ROCKYCODE_<PROVIDER>_PLAN_API_KEY`).
+- Context window and output cap follow the active model: config
+  `context_window` / `max_tokens` default to `0` (= the registry value) and
+  re-pace on every `/model` switch; a positive number pins your own ceiling.
+  `/config context_window 0` un-pins.
+- `/effort off|low|high|max` — the dial now reaches `low` (DeepSeek, GLM and
+  Kimi all take low|high|max), is clamped onto each provider's own tiers by
+  position at the wire (StepFun's `low|medium|high` gets `medium` for
+  rocky's `high`), and sends the lowest tier for `off` on a model that
+  can't disable thinking (GLM, Kimi). The status line says what is sent.
+  `xhigh` stays accepted as `max`.
+- `image_route auto` (new default): a pasted image on a text-only model is
+  described silently by the registry's sidecar (`deepseek-flash` on the home
+  key) or your image CLI — no picker in the way; `ask` keeps the picker.
+- **Rocky configures rocky.** A built-in `rocky-setup` skill plus the
+  ask-tier `rocky_config` tool (show · set · set_url · add_provider) let a
+  user ask rocky to use a proxy, add a vLLM box, change the default model or
+  a limit — writes go under `~/.rockycode` only, through the same validated
+  setters as the CLI. Key-shaped values are refused with the env var to use.
+- `rockycode exec --profile read|write|full`: `read` (read_file/grep/glob/
+  view_image) and `write` (+ jailed write_file/edit_file) have no shell, so
+  they run on the host with no Docker and start instantly — the profiles a
+  calling agent (Claude Code, Codex) wants for "look and tell" and small
+  edits. `full` keeps bash in the Docker sandbox by default. The stream is
+  now meta → text → result by default; `--events` restores the tool.*/turn.*
+  receipt lines (`--include-thinking` implies it). `meta.profile` reports
+  name, mode and tool set.
+- Peak-hour pricing honors DeepSeek's calendar: Monday–Friday only, with a
+  `holidays` list (ISO dates, Beijing) on the schedule for Chinese public
+  holidays — weekends and holidays bill off-peak.
+- Approval mode is switchable without typing: `shift+tab` steps it one notch
+  looser (careful → ask → yolo, wrapping back to careful, so a run of presses
+  never parks you in yolo). The status-bar 🔒 chip now spells that key out and
+  opens a picker when clicked — three rows saying what each mode actually
+  allows — and bare `/permission` opens the same picker. The cycle stays inert
+  while an approval prompt is waiting, and landing in yolo still prints the
+  "runs on your machine" warning.
+- Local models: a builtin `ollama` provider (`http://localhost:11434/v1`,
+  override with `ROCKYCODE_OLLAMA_URL`) — keyless, priced `$0 · local`, model
+  list discovered live from the running server's `GET /v1/models` so the
+  `/model` picker shows what's actually pulled. Server down → a dimmed
+  "not running · start it: ollama serve" row instead of silence.
+- `/model` readiness preflight for local providers: before the engine is
+  switched, rocky checks server reachability, that the model is pulled, that
+  it supports tool calling, and the serving context length (Ollama truncates
+  silently — the #1 agent-loop killer). Not ready → the switch is refused and
+  every failed check carries its exact fix (`ollama pull …`,
+  `export OLLAMA_CONTEXT_LENGTH=65536`); ready → rocky's `context_window` is
+  paced to the server's verified value (restored on switching back to a cloud
+  provider), and a server-reported vision capability turns image input on.
+- Keyless endpoints: `local = true` on a `~/.rockycode/providers.toml`
+  provider (LM Studio, llama.cpp, vLLM, a remote box's ollama) marks its
+  endpoints keyless — always configured, no placeholder-key hack needed.
+- Compaction on a local provider sends no tool schemas in the summarize call
+  (local compat layers ignore `tool_choice="none"` and may answer with a tool
+  call instead of a summary), and the thinking-off field is now shaped per
+  the provider's reasoning policy instead of always DeepSeek's.
+- Vision is now per-MODEL, not per-provider (`Provider.vision_models`,
+  choice-level `❖` badge). Config key `vision_models` marks additional ids as
+  image-capable from any shell (`rockycode config vision_models <id>`) — for
+  when a provider ships vision on an existing model before the registry
+  catches up.
+- Config key `model`: a sticky launch default (`rockycode config model
+  <spec>`), resolved against the registry; precedence `--model` flag →
+  `ROCKYCODE_MODEL` env → config. Global config only — a cloned repo can
+  never redirect requests.
+- The `/model` picker is now two-step, model first: one row per model, and a
+  model with several endpoints then asks which URL serves it — including a
+  "custom base URL" row that remembers your own gateway/proxy per provider
+  (`~/.rockycode/endpoints.toml`, addressable as `<provider>-custom`, riding
+  the provider's key).
+- Images are best-effort downscaled to 2048px before hitting the wire (PIL if
+  installed, macOS `sips` otherwise, original on any failure) — vision
+  providers bill image tokens by dimensions, and a Retina screenshot was
+  paying severalfold for nothing.
+
+### Changed
+- One China endpoint per provider (no more `kimi-cn`/`kimi-en`, `zai`/`glm-cn`,
+  `minimax-cn`/`-en`): `/model kimi`, `/model glm`, `/model minimax`. Keys are
+  `ROCKYCODE_<PROVIDER>_API_KEY`; the older `_CN_`/`_EN_`/`ZAI_EN` names are
+  still read as aliases (the picker names the alias in use), so no setup
+  breaks. An international or proxy URL is the custom-URL row.
+- `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` are retired from
+  the list (DeepSeek retired the models on 2026-09-10 and serves those names
+  with V4.1-Flash); rocky aliases both to `deepseek-flash`, so old configs,
+  trajectories and `/model` habits keep working. `deepseek-v4-pro` stays
+  listed, labelled: since 2026-09-14 DeepSeek routes it to V4.1-Flash at
+  Flash rates until V4.1-Pro ships.
+- `glm-5.2` and `step-3.7-flash` drop off the roster in favor of GLM-5.3 /
+  Step 5 Preview.
+- Session titles, image describe, and the native web search all use the
+  registry's `sidecar` / `search` role (deepseek-flash) — a session on Kimi
+  or GLM no longer sends a DeepSeek model id down its own client for the
+  title call.
+- `--max-tokens` / `--context-window` default to `0` (= the model's registry
+  value) on `chat` and `serve`; `bench` keeps its pinned reproducible numbers.
+- The CLI help, status line and context reminder no longer speak of
+  "DeepSeek V4" as the only model.
+- `view_image` on a vision-capable active model now attaches the real image
+  to the conversation (as the next user message) instead of a sidecar text
+  description — the model reads the pixels and decides what matters itself.
+  Text-only models keep the describe routes unchanged.
+- Launch honors the registry: starting with `--model minimax-m3` (or any
+  registry model) now gets the right reasoning params, tools flag, and vision
+  capability from step one instead of DeepSeek-shaped defaults until the
+  first `/model` switch. Unresolved specs and injected clients behave exactly
+  as before.
+- `/model` spec resolution prefers exact ids, and a base model wins its own
+  substring — `glm:5.3` means `glm-5.3`, not ambiguity with `glm-5.3-flash`;
+  the variant stays reachable via `glm:flash`.
+
+### Fixed
+- The prompt-cache observer and the cost ledger read cache hits from
+  OpenAI-style `prompt_tokens_details.cached_tokens` too (Kimi, GLM, MiniMax,
+  Qwen, MiMo), not only DeepSeek's `prompt_cache_hit_tokens`.
+- Launching on a `<provider>-custom` endpoint of the home provider now uses
+  that URL (it used to fall back to the env base URL).
+
+## [0.1.2] — `--version` flag, GA price tables
+
+### Added
+- `rockycode --version` / `-V` prints the installed version. One version
+  source: package metadata (pyproject) — the serve handshake reports the same
+  value instead of a hardcoded string.
+
+### Changed
+- DeepSeek price tables refreshed to the GA snapshots (V4-Flash-0731 /
+  V4-Pro-0813), both USD and CNY, verified 2026-08-20 at the source;
+  peak-valley billing confirmed live (2× in the published UTC windows).
+- README results updated: `deepseek-v4-flash` GA carries three clean full-500
+  SWE-bench Verified rounds (88.8% average, 95.4% pass@3); the
+  `deepseek-v4-pro` column is explicitly marked preview (pre-0813).
+
+### CI
+- Release workflow reduced to the single ubuntu PyPI Trusted-Publishing job;
+  the dead macos-13 matrix (retired runner, never ran) is gone.
+
+## [0.1.1] — session artifacts, images in chat, real sandbox cancel
+
+### Added
+- Images in chat: paste (`ctrl+v` / `/paste`) or drag an image in. Vision models
+  see it raw; no-vision models route through a provider sidecar, your own image
+  CLI, or a `view_image` tool — picked once, remembered. Known CLIs set up with
+  one word (`/config image_cli mmx` — rocky knows the invocation).
+- Session artifact inventory: `/artifact list · open <n> · stop · live on|off`,
+  a footer badge with open-tab counts, and an Artifacts tree in the VS Code
+  extension fed live by `rockycode serve`.
+- Bare `/model` opens a live provider + model picker.
+
+### Fixed
+- Live artifacts no longer drop and reconnect every 30 s; the artifact server
+  stops/restarts cleanly and rebinds saved live pages to the new port.
+- Sandbox cancel/timeout kills the in-container process group, not just the
+  host-side docker client; images without `python3` fall back to plain `bash -c`.
+- Resume self-heals after a hard kill; closing the doc dock no longer wedges the TUI.
+
+### Internal
+- CI: conservative ruff correctness gate (pinned `0.16.1`) ahead of the smoke suite.
+
+## [0.1.0] — first public release
+
+Initial public release. One repo, one engine, three ways to use it — interactive
+`chat`, autonomous `goal`, and the `bench` measurement rig — running on DeepSeek
+or any OpenAI-compatible model.
+
+Some capabilities ship as **experimental and default-off** (self-improvement,
+`prove` / `lean-prover`, `explore`, and providers other than DeepSeek); see the
+README's Experimental section for what they are and how to enable them.

{rockycode-0.1.1 → rockycode-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rockycode
-Version: 0.1.1
+Version: 0.2.0
 Summary: A coding agent harness, benchmarked on SWE-bench Verified. amaze!
 Author: rockycode contributors
 License: MIT
@@ -42,8 +42,8 @@ Built for the DeepSeek V4 series, with a unique research mode, bench-tested, and
 
 [English](README.md) · [简体中文](README.zh-CN.md)
 
-![SWE-bench Verified](https://img.shields.io/badge/SWE--bench_Verified-79.8%25_V4--flash-7d5cc6)
-![V4-pro preview](https://img.shields.io/badge/V4--pro_preview-81.8%25_pass@3-8d6cd0)
+![SWE-bench Verified](https://img.shields.io/badge/SWE--bench_Verified-88.8%25_V4--flash_GA-7d5cc6)
+![V4-pro preview](https://img.shields.io/badge/V4--pro_preview-74.9%25-8d6cd0)
 ![Python](https://img.shields.io/badge/Python-3.11%2B-9d7cd8)
 ![License](https://img.shields.io/badge/License-MIT-a9b1d6)
 
@@ -77,31 +77,37 @@ against it.
 
 ## Results — SWE-bench Verified
 
-Full-set numbers: **independent full-500 runs** (three each for
-`deepseek-v4-pro` and `minimax-m3`, one so far for `deepseek-v4-flash`), same
+Full-set numbers: **independent full-500 runs**, three rounds per model, same
 harness and config for all (100-step cap, 32,768 max output tokens, reasoning
 effort `max`, thinking on), scored with the official SWE-bench harness. No
-tuning against the tasks.
+tuning against the tasks. Mind the versions: the `deepseek-v4-flash` column is
+the **GA release** (V4-Flash-0731), while the `deepseek-v4-pro` rounds ran
+before the GA V4-Pro-0813 shipped — that column is the **preview** pro, so the
+flash/pro gap reflects a version difference, not a same-vintage comparison.
 
-| run | `deepseek-v4-pro` | `deepseek-v4-flash` | `minimax-m3` |
+| run | `deepseek-v4-flash` (GA) | `deepseek-v4-pro` (preview) | `minimax-m3` |
 |---|---|---|---|
-| round 1 | 75.6% (378/500) | 79.8% (399/500) | 72.8% (364/500) |
-| round 2 | 74.8% (374/500) | — | 71.2% (356/500) |
-| round 3 | 74.4% (372/500) | — | 70.0% (350/500) |
-| **average** | **74.9%** | **79.8%** *(1 run)* | **71.3%** |
-| union of runs (pass@3) | 81.8% (409/500) | — | 83.6% (418/500) |
+| round 1 | 90.0% (450/500) | 75.6% (378/500) | 72.8% (364/500) |
+| round 2 | 88.6% (443/500) | 74.8% (374/500) | 71.2% (356/500) |
+| round 3 | 87.8% (439/500) | 74.4% (372/500) | 70.0% (350/500) |
+| **average** | **88.8%** | **74.9%** | **71.3%** |
+| union of runs (pass@3) | 95.4% (477/500) | 81.8% (409/500) | 83.6% (418/500) |
 
 Read the two summary rows differently. The **average** is the
 leaderboard-comparable number — each round is an independent single-pass run
 over the full 500. The **union** is pass@3: tasks solved by at least one
-round. The gap between them (~7 points for DeepSeek, ~12 for MiniMax) is
-run-to-run variance, not capability — the models already reach these tasks
-under this harness, they just don't hold them every run. Closing that gap
-(verify-before-finish gating and run selection, not more prompting) is the
-current line of work. For reference, DeepSeek reports 80.6% with its own
-scaffold; the three-run union crosses that mark. Per-round breakdowns:
+round. The gap between them (~7 points for both DeepSeek models, ~12 for
+MiniMax) is run-to-run variance, not capability — the models already reach
+these tasks under this harness, they just don't hold them every run. Closing
+that gap (verify-before-finish gating and run selection, not more prompting)
+is the current line of work. For reference, DeepSeek reported 80.6% for V4
+Pro (Preview) with its own scaffold. Per-round breakdowns:
 [@rockycode_ai](https://x.com/rockycode_ai).
 
+Two earlier flash rounds (79.8% — previously listed here — and 81.2%) hit
+local network outages mid-run, visible as contiguous blocks of empty-patch
+tasks; they were replaced by clean re-runs rather than averaged in.
+
 We plan to add **DeepSWE-bench** support as well — currently in progress.
 
 ## Getting started
@@ -121,6 +127,10 @@ uv tool install rockycode     # recommended — puts the `rockycode` command on
 rockycode                     # the first run walks you through API-key setup
 ```
 
+Already installed and a new release is out? **`uv tool upgrade rockycode`** —
+note that re-running `uv tool install` does NOT upgrade: it sees the existing
+install and quietly keeps the old version.
+
 Don't have uv yet? One command installs it:
 `curl -LsSf https://astral.sh/uv/install.sh | sh` — Windows and other options
 in the [uv install docs](https://docs.astral.sh/uv/getting-started/installation/).
@@ -195,8 +205,8 @@ clipboard" (or your terminal's equivalent) on the local end.
 | `/research` | Research modes: deep-research · paper-reading · whiteboard · prove |
 | `/learn` | Tutor mode — your understanding is the goal, not the diff |
 | `/model` | Switch provider and model (see below) |
-| `/effort off\|high\|xhigh\|max` | Reasoning depth, adjustable live per session |
-| `/permission yolo\|ask\|careful` | Tool-approval strictness for the session |
+| `/effort off\|low\|high\|max` | Reasoning depth, adjustable live per session (clamped onto each provider's own tiers) |
+| `/permission yolo\|ask\|careful` | Tool-approval strictness for the session — bare opens a picker; `shift+tab` cycles it, or click the 🔒 chip in the status bar |
 | `/sandbox on\|off\|status` | Isolate tool execution in a container |
 | `/lsp` | Language-server status; diagnostics ride along with `read_file` |
 | `/artifact` | Session artifacts: `list` · `open <n>` · `stop` · `live on\|off` |
@@ -228,27 +238,79 @@ clipboard" (or your terminal's equivalent) on the local end.
 
 ### Models and providers
 
-DeepSeek is the home model, but providers are data, not code: each is a
-base URL, a model list, a key variable, and a reasoning shape over the
-OpenAI-compatible API.
+DeepSeek is the home model, but **models are data, not code**: the whole
+catalog lives in `rockycode/models.toml` — per provider a China base URL, a
+key name and a reasoning wire shape; per model its context window, output
+cap, vision flag, price and roles. The engine reads that spec and carries no
+model-specific numbers of its own, so a new model is a data edit. Your own
+`~/.rockycode/models.toml` (same shape) is deep-merged on top: add a model,
+correct a limit, add a price, hide a row.
 
-| Provider | Models |
-|---|---|
-| **deepseek** (default) | `deepseek-v4-flash` (default), `deepseek-v4-pro` (preview) |
-| **minimax** | `minimax-m3` |
-| **kimi** | `kimi-k3` |
-| **glm** | `glm-5.2` |
-
-Regional endpoints are addressable as `<provider>-<region>` (e.g. `kimi-cn`),
-and custom providers — including local vLLM/SGLang servers — go in
-`~/.rockycode/providers.toml`. The `/model` picker only offers providers whose
-keys are actually configured. DeepSeek and MiniMax both carry full-500 bench
-numbers (see [Results](#results--swe-bench-verified)); Kimi and GLM are
-[experimental](#experimental).
-
-The effort dial (`/effort off|high|xhigh|max`) is provider-neutral; each
-provider maps it to its own reasoning tiers at the wire (DeepSeek, for
-example, only distinguishes `high|max`, so `xhigh` clamps to `max`).
+| Provider | Models (❖ = takes image input) | ctx / max out |
+|---|---|---|
+| **deepseek** (default) | `deepseek-flash` (V4.1 Flash, default) ❖, `deepseek-v4-pro` | 1M / 384K |
+| **glm** | `glm-5.3`, `glm-5.3-flash` ❖ | 1M / 128K |
+| **kimi** | `kimi-k3` ❖ | 1M / 128K |
+| **minimax** | `minimax-m3` ❖ | 1M / 128K |
+| **stepfun** | `step-5-preview` ❖ | 1M / 64K |
+| **qwen** | `qwen3.8-max` ❖, `qwen3.8-flash` ❖ | 1M / 64K |
+| **mimo** | `mimo-v2.6-pro` ❖ | 1M / 128K |
+| **ollama** (local, $0) | whatever you've pulled — discovered live from the running server | server-verified |
+
+One China endpoint per provider (`ROCKYCODE_<PROVIDER>_API_KEY`; the older
+`_CN_`/`_EN_` names are still read). Subscription plans with their own URL
+and key are their own rows — `qwen-plan` (Bailian Token Plan), `mimo-plan`,
+`stepfun-plan` — keyed as `ROCKYCODE_<PROVIDER>_PLAN_API_KEY`. The `/model`
+picker lists **models first**, one row each; a model with several endpoints
+then asks which URL serves it (official · plan · your own), and the "custom
+base URL" row remembers a gateway or proxy per provider
+(`~/.rockycode/endpoints.toml`, addressable as `<provider>-custom`). Typed
+specs skip all of that: `/model glm:flash`, `/model qwen-plan:qwen3.8-max`.
+The retired `deepseek-v4-flash` / `-vision-exp` ids still resolve (to
+`deepseek-flash`, exactly as DeepSeek serves them). The picker only offers
+providers whose keys are actually configured.
+
+Vision is per-model: `deepseek-flash` sees images on the home key, so the
+default session just takes a paste. A text-only model (`deepseek-v4-pro`,
+`glm-5.3`) gets pasted images described by `deepseek-flash` silently
+(`image_route auto`), or by your own CLI. `rockycode config model <spec>`
+makes any pick the sticky launch default. Context window and output cap
+follow the active model (config `context_window` / `max_tokens` = `0`); a
+number pins your own ceiling across switches. DeepSeek and MiniMax carry
+full-500 bench numbers (see [Results](#results--swe-bench-verified)); the
+other providers are [experimental](#experimental).
+
+The effort dial (`/effort off|low|high|max`) is provider-neutral; each
+provider's own tiers come from the registry and the dial is clamped onto
+them by position at the wire (StepFun's `low|medium|high` gets `medium` for
+rocky's `high`; GLM and Kimi can't switch thinking off, so `off` sends their
+lowest tier). `xhigh` is still accepted and means `max`.
+
+Rocky can also configure itself: ask it to "use my proxy", "add my vLLM
+server", or "switch the default model" and the built-in `rocky-setup` skill
+plus the ask-tier `rocky_config` tool make the change under `~/.rockycode`.
+Keys are the one thing it never touches — it names the variable and you
+paste the value.
+
+#### Local models (Ollama)
+
+Rocky integrates the OpenAI-compatible *protocol*, never a runtime — and
+recommends [Ollama](https://ollama.com) (its MLX engine covers Apple Silicon
+since 0.19). No key, no config: run `ollama serve`, pull a tool-capable model
+(`ollama pull qwen3.8:27b-mlx` is the tested recommendation), and it appears
+in `/model` with what's actually pulled, priced `$0 · local`.
+
+Switching to a local model runs a **readiness preflight** first — server up,
+model pulled, tool-calling support, serving context — and refuses the switch
+with the exact fix (`ollama pull …`, `export OLLAMA_CONTEXT_LENGTH=65536`)
+when something would break mid-session. The one to respect: Ollama's default
+context is small and it **truncates silently**, which kills agent sessions in
+confusing ways — serve with `OLLAMA_CONTEXT_LENGTH=65536`. Rocky paces its own
+`context_window` to the server's verified value on every switch.
+
+Other local servers (LM Studio, llama.cpp, vLLM) work as data too: add a
+provider with `local = true` in `~/.rockycode/providers.toml` and its
+endpoints need no key.
 
 ## Autonomous use
 
@@ -278,11 +340,26 @@ rockycode goal "add a docstring to <fn> and run the linter" --max-usd 0.50 --max
 ### Headless delegation: `exec`
 
 `rockycode exec "<task>"` is the single-shot, non-interactive entry point,
-designed to be called by *other* agents and scripts. Events stream as JSONL on
-stdout; the Docker sandbox is **on by default** (the command classifier is
-defense-in-depth, not the boundary); budgets are always enforced; and exit
-codes distinguish success, failure, needs-approval, and budget-stop — so a
-calling agent can grant an approval and resume instead of guessing.
+designed to be called by *other* agents and scripts. stdout is JSONL: a
+`meta` line, the model's `text`, and a `result` envelope with evidence
+(files changed, commands run, refusals) — never verdicts, the caller
+verifies; `--events` adds the per-tool receipt lines. Budgets are always
+enforced, and exit codes distinguish success, failure, needs-approval, and
+budget-stop — so a calling agent can grant an approval and resume instead
+of guessing.
+
+Pick how much rocky may do with `--profile`: `read` (read_file / grep /
+glob / view_image — no shell, no writes) and `write` (+ write_file /
+edit_file jailed to `--workdir`) run on the host with **no Docker** and
+start instantly — what Claude Code or Codex wants for "look at this repo and
+tell me" or a small edit on a cheap, fast model. `full` adds bash, in the
+Docker sandbox **by default** (the command classifier is defense-in-depth,
+not the boundary).
+
+```bash
+rockycode exec --profile read "which module owns retry logic, and where is it called?"
+rockycode exec --profile write "add a docstring to every public function in utils.py"
+```
 
 ### Editor integration: `serve` and the VS Code extension
 
@@ -337,10 +414,13 @@ change. Anything that could act on its own is **off by default**.
   investigation from a fresh-context child that returns only a cited,
   mechanically-verified report; the search noise never enters your session. It
   also grounds goal mode's branch review and milestone verification.
-- **Providers beyond DeepSeek.** MiniMax, GLM / z.ai, and Kimi are wired as
-  OpenAI-compatible profiles (`/model`). DeepSeek and MiniMax carry full
-  bench numbers (see Results); treat GLM and Kimi as untested until they do
-  too.
+- **Providers beyond DeepSeek.** GLM, Kimi, MiniMax, StepFun, Qwen, and MiMo
+  are wired as OpenAI-compatible registry entries (`/model`). DeepSeek and
+  MiniMax carry full bench numbers (see Results); treat the rest as untested
+  until they do too. Registry entries marked `note = "… verify …"` in
+  `models.toml` (MiniMax's endpoint host, MiMo's auth header, the plan URLs)
+  were taken from each provider's docs on 2026-09-29 and not yet exercised
+  live — a wrong one is a one-line data fix.
 
 ## Works with your existing setup