# 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.