add plan to updateHEADmain

1 files changed, 225 insertions, 0 deletions

diff --git a/.rules/plan/17-20-readme-changelog-examples.md b/.rules/plan/17-20-readme-changelog-examples.md
new file mode 100644
index 0000000..55653d5
--- /dev/null
+++ b/.rules/plan/17-20-readme-changelog-examples.md
@@ -0,0 +1,225 @@
+# Phase 17 — README, CHANGELOG, and examples
+
+**Estimated time:** ~20 minutes
+**Touches:**
+`README.md`, `CHANGELOG.md`, `AGENTS.md`,
+`examples/ask_standing_sitting.rb`,
+`examples/usage_per_token.rb`,
+`bin/setup`, `bin/console`, `bin/install`, `bin/check`.
+
+## Goal
+
+Replace all remaining user-facing documentation and examples so the gem
+ships as a clean MiniMax adapter. By this phase the code and tests are
+already clean; this is documentation polish.
+
+## Steps
+
+### 1. Rewrite `README.md`
+
+Top to bottom rewrite. Required sections:
+
+- **Title:** `# dispatch-adapter-minimax`
+- **One-paragraph intro:** What it is. "Implements
+  `Dispatch::Adapter::Base` for MiniMax via the Anthropic-compatible
+  /v1/messages endpoint. Works with the MiniMax Token Plan."
+- **Installation:**
+  ```ruby
+  gem "dispatch-adapter-minimax"
+  ```
+- **Configuration:**
+  - The three API key resolution methods (constructor arg, env var,
+    file).
+  - Default base URL.
+  - Default model.
+- **Quick start:** A minimal working snippet showing how to chat.
+- **Supported models:** The 7-model table.
+- **Supported parameters:** A table mirroring MiniMax's compat docs
+  (model, messages, max_tokens, stream, system, temperature,
+  tool_choice, tools, top_p, metadata, thinking — all supported;
+  top_k, stop_sequences, service_tier, mcp_servers,
+  context_management, container — silently stripped).
+- **Unsupported content blocks:** Image and document blocks raise
+  `ArgumentError` at request-build time.
+- **Cache control:** Documented as best-effort; MiniMax docs do not
+  list cache_control as a recognized field, so any caching benefit is
+  upstream-dependent.
+- **Cost / quotas:** `Usage#cost.total_cost` is always `0.0` because
+  Token Plan is request-quota; no per-token rate applies.
+- **Running tests:** `bundle exec rubocop --autocorrect-all && bundle exec rspec`.
+- **Live smoke testing:** Brief note that smoke testing requires a
+  real Token Plan API key; not part of CI.
+
+DO NOT carry over any Claude / Anthropic / OAuth / PKCE / Stainless /
+Claude Code language. The README must read as if MiniMax was always
+the target.
+
+### 2. Rewrite `CHANGELOG.md`
+
+```markdown
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release.
+- MiniMax adapter implementing `Dispatch::Adapter::Base` via the
+  Anthropic-compatible `/v1/messages` endpoint at
+  `https://api.minimax.io/anthropic`.
+- Supports MiniMax-M2.7 (default), MiniMax-M2.7-highspeed,
+  MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1,
+  MiniMax-M2.1-highspeed, MiniMax-M2.
+- Token Plan static API key auth (constructor arg, ENV, or file).
+- Streaming and non-streaming `/v1/messages` calls.
+- `count_tokens` and `list_models` (best-effort; degrade gracefully if
+  the upstream endpoint is unavailable).
+- Strict-tool-schema fallback retry on `400 grammar/schema too large`.
+- Image and document content blocks raise `ArgumentError`
+  (unsupported by MiniMax).
+- `Usage#cost` is always `0.0` (Token Plan is request-quota).
+```
+
+### 3. Rewrite `AGENTS.md`
+
+Top to bottom. Mirror the Claude AGENTS.md structure but for MiniMax.
+Required sections:
+
+- **Purpose:** "Implements `Dispatch::Adapter::Base` for MiniMax via
+  their Anthropic-compatible /v1/messages endpoint. Targets the Token
+  Plan static API key flow."
+- **File map:** updated tree:
+  ```text
+  lib/dispatch/adapter/minimax.rb
+  lib/dispatch/adapter/minimax/
+    version.rb
+    errors.rb
+    key_store.rb
+    headers.rb
+    pricing_table.rb
+    model_catalog.rb
+    request_builder.rb
+    request_builder/messages.rb
+    request_builder/tools.rb
+    request_builder/cache_control.rb
+    request_builder/thinking.rb
+    response_builder.rb
+    sse_parser.rb
+    stream_collector.rb
+    http_client.rb
+    data/minimax_pricing.json
+  ```
+- **Key design decisions:**
+  - No OAuth (Token Plan is static-key).
+  - `temperature` validated to `(0.0, 1.0]` per MiniMax docs.
+  - Image / document content rejected at request-build.
+  - Strict-tool-schema fallback uses a broadened regex.
+  - `Usage#cost` always 0.0.
+- **Constants to track:** None beyond DEFAULT_BASE_URL / DEFAULT_MODEL.
+  MiniMax has no equivalent of the Claude Code version + Stainless
+  version drift.
+- **Running tests:** Same as README.
+
+### 4. Rewrite the examples
+
+`examples/ask_standing_sitting.rb` and
+`examples/usage_per_token.rb` (rename the latter — there is no
+per-token usage to demonstrate).
+
+DELETE `examples/usage_per_token.rb`. Replace with
+`examples/list_models.rb` (or similar) which shows how to call
+`adapter.list_models` and prints the resulting catalog.
+
+For `examples/ask_standing_sitting.rb`: rewrite as a minimal MiniMax
+hello-world. Example:
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Minimal MiniMax adapter usage example.
+# Requires MINIMAX_API_KEY in env, or ~/.config/dispatch/minimax_api_key.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "dispatch/adapter/minimax"
+
+adapter = Dispatch::Adapter::MiniMax.new(model: "MiniMax-M2.7", thinking: "high")
+
+response = adapter.chat(
+  [Dispatch::Adapter::Message.new(
+    role: "user",
+    content: [Dispatch::Adapter::TextBlock.new(text: "Say hi in one word.")]
+  )],
+  system: "You are concise."
+)
+
+response.content.each do |block|
+  case block
+  when Dispatch::Adapter::TextBlock     then puts "[text] #{block.text}"
+  when Dispatch::Adapter::ThinkingBlock then puts "[thinking] #{block.thinking}"
+  end
+end
+
+puts "stop_reason: #{response.stop_reason}"
+puts "tokens: #{response.usage.input_tokens} in / #{response.usage.output_tokens} out"
+```
+
+DELETE `usage_per_token_error.log` if it still exists in the gem root.
+
+### 5. Update `bin/setup`, `bin/install`, `bin/check`, `bin/console`
+
+These bin scripts probably reference Claude. Rename references and
+update any `require` statement to point at `dispatch/adapter/minimax`.
+
+If a bin script does something Claude-specific that has no MiniMax
+analogue (e.g. an OAuth login helper), DELETE the script.
+
+### 6. Final cleanup
+
+- Delete `usage_per_token_error.log` from the gem root if present.
+- Verify `Gemfile.lock` regenerates cleanly via `bundle install`. If
+  the lock is stale, delete it and let `run_tests` rebuild it via
+  `bundle install` (the test gate runs bundler).
+
+## Acceptance criteria
+
+- `README.md`, `CHANGELOG.md`, `AGENTS.md` are all rewritten and
+  contain ZERO Claude / Anthropic / OAuth / Claude Code references.
+- `grep -rn 'Claude\|claude\|anthropic\|Anthropic' README.md CHANGELOG.md AGENTS.md examples/ bin/`
+  returns ZERO matches (case-sensitive — except that the words
+  "Anthropic-compatible" describing MiniMax's choice of wire format
+  ARE allowed in the README and AGENTS.md only as a factual
+  description; if you keep them, document why with a comment like
+  "MiniMax exposes an Anthropic-compatible /v1/messages endpoint" and
+  refine the grep accordingly).
+- `examples/` contains no broken Ruby — every script `bundle exec ruby
+  examples/<name>.rb` should at least load (it's OK if it then fails
+  because no API key is available — that proves the require chain
+  works).
+- `bin/check` (or equivalent) runs cleanly.
+- `bundle exec rubocop --autocorrect-all` exits 0.
+- `bundle exec rspec` exits 0 with no skipped or pending examples.
+
+## Verification
+
+Run `run_tests` with `project_path=reference/dispatch-adapter-minimax`.
+
+This is the FINAL phase. The gate is strict:
+
+- Both rubocop and rspec must exit 0.
+- No examples may be skipped or pending.
+- Documentation greps above must be clean.
+
+After `ask_for_next_plan` is called, the runner should report no
+remaining plans and the agent should end its turn.
+
+## Post-plan manual steps (NOT for the agent)
+
+The user will smoke-test against a live MiniMax Token Plan key:
+
+1. `export MINIMAX_API_KEY=<real key>`
+2. `cd reference/dispatch-adapter-minimax && bundle install`
+3. `ruby examples/<hello>.rb` — expect a real response.
+4. Verify `count_tokens` and `list_models` either work or degrade
+   gracefully.
+5. Verify `cache_control` blocks do not produce 400 errors.
+6. If any of those fail, file an issue describing the wire shape and
+   we'll add a follow-up plan.