patina-cli 3.11.0 → 4.0.0

package/docs/AUTHENTICATION.md

@@ -7,48 +7,54 @@ patina runs through one of several backends. Pick whichever matches your existin
 | Backend | Setup | Cost |
 |---------|-------|------|
 | `codex-cli` | `codex login` | **Free** (ChatGPT OAuth) |
-| `claude-cli` | `claude` (one-time interactive OAuth) | **Free** (Claude subscription) |
+| `claude-cli` | `claude auth login` (one-time interactive OAuth) | **Free** (Claude subscription) |
 | `gemini-cli` | `gemini` (one-time interactive OAuth) or `GEMINI_API_KEY=...` | **Free** (Code Assist OAuth or AI Studio) |
+| `kimi-cli` | `kimi login` (one-time browser OAuth) or `KIMI_API_KEY=...` | Kimi account / Moonshot API |
 | OpenAI-compatible HTTP | `PATINA_API_KEY=...` | Per provider |
 | Google Gemini (HTTP) | `GEMINI_API_KEY=...` + `--provider gemini` | Free tier |
 | Groq | `GROQ_API_KEY=...` + `--provider groq` | Free tier |
+| Kimi / Moonshot (HTTP) | `KIMI_API_KEY=...` + `--provider kimi`, or `MOONSHOT_API_KEY=...` + `--provider moonshot` | Per provider |
 | Together AI | `TOGETHER_API_KEY=...` + `--provider together` | Free models available |
 | OpenRouter | `--base-url https://openrouter.ai/api/v1` + key | Per provider (mix any provider) |
 
 ```bash
 patina auth status         # backend availability + auth state
 patina auth login          # per-backend login instructions
-patina --list-providers    # preset providers + key status
+patina auth login codex-cli # confirm, then run `codex login`
+patina --list-backends     # backend selectors + auth state
 ```
 
-Backend selection requires an explicit signal: pass `--backend <name>` directly, pass a comma-separated fallback chain such as `--backend claude-cli,codex-cli`, or use `--model <prefix>` (`codex-*`, `claude-*`, `gemini-*` route to the matching local CLI). With no flags and no API key, patina exits with an error rather than silently dispatching to a coding agent. See [issue #88](https://github.com/devswha/patina/issues/88) for the rationale.
+Backend selection requires an explicit signal: pass `--backend <name>` directly, pass a comma-separated fallback chain such as `--backend claude-cli,codex-cli`, or use `--model <prefix>` (`codex-*`, `claude-*`, `gemini-*`, `kimi-*` route to the matching local CLI). With no flags and no API key, patina exits with an error rather than silently dispatching to a coding agent. See [issue #88](https://github.com/devswha/patina/issues/88) for the rationale.
 
 ## Environment variables
 
 ```bash
 PATINA_API_KEY=...                            # required for HTTP backend
 PATINA_API_BASE=https://api.openai.com/v1     # or proxy / OpenRouter / etc.
-PATINA_MODEL=gpt-4o                           # default model
+PATINA_MODEL=gpt-5.5                           # HTTP/OpenAI default model
 ```
 
-`--base-url`, `--model`, `--api-key`, `--provider` flags override these per run.
+`--base-url`, `--model`, `--api-key-file`, and `--provider` flags override these per run.
+When you do not pass `--model`, patina uses its strongest documented default per backend: `gpt-5.5` for OpenAI HTTP and `codex-cli`, `claude-sonnet-4-6` for `claude-cli`, `gemini-2.5-pro` for Gemini HTTP/CLI, `kimi-code/kimi-for-coding` for `kimi-cli`, and `kimi-k2.5` for Kimi/Moonshot HTTP. Exact selector aliases such as `--model codex`, `--model claude`, `--model gemini`, and `--model kimi` still route to the local CLI while using that backend default.
 
 ## codex-cli backend
 
-patina dispatches via the local [`codex`](https://github.com/openai/codex) CLI, which authenticates via OpenAI/ChatGPT OAuth — no API key needed.
+patina dispatches via the local [`codex`](https://github.com/openai/codex) CLI, which authenticates via OpenAI/ChatGPT OAuth — no API key needed. The default model passed to `codex exec` is `gpt-5.5` unless you provide a more specific Codex model id.
 
 ```bash
 codex login                                # one-time
+patina auth login codex-cli                # same, with confirmation
 patina --backend codex-cli --lang ko input.txt
-patina --model codex --lang ko input.txt   # same — auto-routes by model name
+patina --model codex --lang ko input.txt   # routes to codex-cli, uses gpt-5.5 default
 ```
 
 ## claude-cli backend
 
-Spawns local [`claude`](https://docs.anthropic.com/en/docs/claude-code) `-p` with the patina prompt on stdin. Free for anyone with a Claude subscription.
+Spawns local [`claude`](https://docs.anthropic.com/en/docs/claude-code) `-p` with the patina prompt on stdin. Free for anyone with a Claude subscription. Claude Code is an agent runtime, so patina treats it conservatively in batch mode: compact prompt mode, default max concurrency `1`, and default retries `0`. The default model passed to Claude Code is `claude-sonnet-4-6`; Claude Code may still apply its own model/session policy outside patina's control.
 
 ```bash
-claude                                     # one-time interactive OAuth
+claude auth login                          # one-time interactive OAuth
+patina auth login claude-cli               # same, with confirmation
 patina --backend claude-cli --lang ko input.txt
 patina --model claude-sonnet-4-6 --lang ko input.txt   # auto-routes
 ```
@@ -57,22 +63,46 @@ Auth file: `~/.claude/.credentials.json` (created by the OAuth flow).
 
 ## gemini-cli backend
 
-Spawns local [`gemini`](https://github.com/google-gemini/gemini-cli) `-p '' --output-format text` with the patina prompt on stdin. Works with the free Code Assist OAuth tier or with `GEMINI_API_KEY`.
+Spawns local [`gemini`](https://github.com/google-gemini/gemini-cli) `-p '' --output-format text` with the patina prompt on stdin. Works with the free Code Assist OAuth tier or with `GEMINI_API_KEY`. The default model is `gemini-2.5-pro`.
 
 ```bash
 gemini                                     # one-time interactive OAuth, OR
+patina auth login gemini-cli               # same, with confirmation
 export GEMINI_API_KEY="..."                # AI Studio key
 patina --backend gemini-cli --lang ko input.txt
 patina --model gemini-3-flash-preview --lang ko input.txt   # auto-routes
 ```
 
+## kimi-cli backend
+
+Spawns local [`kimi`](https://moonshotai.github.io/kimi-cli/) in print mode with the patina prompt on stdin. It works with Kimi Code CLI browser login, `KIMI_API_KEY`, or `MOONSHOT_API_KEY`. Kimi Code is an agent runtime, so patina treats it conservatively in batch mode: compact prompt mode, default max concurrency `1`, and default retries `0`. The default local CLI model is `kimi-code/kimi-for-coding`; the CLI display name may differ from Moonshot HTTP model IDs.
+
+```bash
+kimi login                                  # one-time browser OAuth, OR
+patina auth login kimi-cli                  # same, with confirmation
+export KIMI_API_KEY="..."                   # optional API key path
+patina --backend kimi-cli --lang ko input.txt
+patina --model kimi --lang ko input.txt     # routes to kimi-cli, uses backend default
+```
+
+Use `--yes` only for automation where the launch is already intentional:
+
+```bash
+patina auth login codex-cli --yes
+```
+
 Notes: patina passes `--skip-trust` because the prompt runs from a fresh temp directory (containment for prompt-injection in user text). Default timeout is higher than other CLIs because gemini's startup latency is longer.
 
-> **v1 limitation:** `codex-cli`, `claude-cli`, and `gemini-cli` all support single-mode rewrites only. `--audit`, `--score`, `--diff`, `--ouroboros`, and `--models`/MAX still go through the HTTP backend.
+> **Mode support:** `codex-cli`, `claude-cli`, `gemini-cli`, and `kimi-cli` can be used as rewrite backends without `PATINA_API_KEY` when their local CLIs are already authenticated. API-backed score/audit paths still use the configured HTTP/evaluator key.
 
-## Free-tier providers
+For large rewrite batches, prefer `openai-http` or another stateless
+OpenAI-compatible HTTP provider over local agent CLIs. Batch mode exposes
+`--timeout-ms`, `--max-concurrency`, `--max-retries`, `--max-failures`,
+`--max-failure-rate`, and `--stop-on-retryable-storm`; see [CLI.md](CLI.md#batch-safety-controls).
 
-Get an API key once, then it's free:
+## HTTP provider examples
+
+Get an API key from the provider you want to call:
 
 ```bash
 # Google Gemini — https://aistudio.google.com/app/apikey
@@ -86,20 +116,14 @@ patina --provider groq --lang ko input.txt
 # Together AI (free models suffixed with "-Free")
 export TOGETHER_API_KEY="..."
 patina --provider together --lang ko input.txt
-```
 
-`--provider` sets the right base URL, default model, and reads the provider-specific API key env var. Override any of these with `--base-url`, `--model`, or `--api-key`.
+# Kimi / Moonshot (paid API)
+export KIMI_API_KEY="..."
+patina --provider kimi --lang ko input.txt
 
-## MAX mode dispatch
-
-The Claude Code `/patina-max` skill bypasses HTTP entirely — it dispatches via local CLIs:
-
-| Model | Dispatch | Auth |
-|-------|----------|------|
-| `claude` | `claude -p` | Claude Code |
-| `codex` | `codex exec --skip-git-repo-check --output-last-message` | ChatGPT OAuth |
-| `gemini` | `gemini -p '' --output-format text` | Google AI Studio |
+export MOONSHOT_API_KEY="..."
+patina --provider moonshot --lang ko input.txt
+```
 
-No `PATINA_API_KEY` needed for the Claude Code path.
+`--provider` sets the right base URL, default model, and reads the provider-specific API key env var. Override these with `--base-url`, `--model`, or `--api-key-file`.
 
-The standalone CLI MAX (`patina --models <list>`) calls models via the same `--base-url` endpoint, so all listed models must be served by that endpoint. To mix providers (OpenAI + Anthropic + Google), point `--base-url` at OpenRouter or another multi-provider gateway.

package/docs/AUTHENTICATION_KR.md

@@ -1,78 +1,109 @@
 # 인증과 백엔드
 
-patina는 여러 backend 중 하나를 통해 실행됩니다. 이미 쓰고 있는 도구에 맞는 방식을 고르세요.
+patina는 여러 백엔드 가운데 하나로 실행됩니다. 지금 쓰는 도구와 인증 방식에 맞춰 고르면 됩니다.
 
 ## Backend matrix
 
 | Backend | Setup | Cost |
 |---------|-------|------|
 | `codex-cli` | `codex login` | **Free** (ChatGPT OAuth) |
-| `claude-cli` | `claude` (one-time interactive OAuth) | **Free** (Claude subscription) |
+| `claude-cli` | `claude auth login` (one-time interactive OAuth) | **Free** (Claude subscription) |
 | `gemini-cli` | `gemini` (one-time interactive OAuth) or `GEMINI_API_KEY=...` | **Free** (Code Assist OAuth or AI Studio) |
+| `kimi-cli` | `kimi login` (one-time browser OAuth) or `KIMI_API_KEY=...` | Kimi account / Moonshot API |
 | OpenAI-compatible HTTP | `PATINA_API_KEY=...` | Per provider |
 | Google Gemini (HTTP) | `GEMINI_API_KEY=...` + `--provider gemini` | Free tier |
 | Groq | `GROQ_API_KEY=...` + `--provider groq` | Free tier |
+| Kimi / Moonshot (HTTP) | `KIMI_API_KEY=...` + `--provider kimi`, 또는 `MOONSHOT_API_KEY=...` + `--provider moonshot` | Per provider |
 | Together AI | `TOGETHER_API_KEY=...` + `--provider together` | Free models available |
 | OpenRouter | `--base-url https://openrouter.ai/api/v1` + key | Per provider (mix any provider) |
 
 ```bash
 patina auth status         # backend availability + auth state
 patina auth login          # per-backend login instructions
-patina --list-providers    # preset providers + key status
+patina auth login codex-cli # confirm 후 `codex login` 실행
+patina --list-backends     # backend selector와 auth 상태
 ```
 
-Backend selection에는 명시적인 신호가 필요합니다. `--backend <name>`을 직접 넘기거나, `--backend claude-cli,codex-cli`처럼 comma-separated fallback chain을 넘기거나, `--model <prefix>`를 사용하세요. `codex-*`, `claude-*`, `gemini-*`는 각각 맞는 local CLI로 라우팅됩니다. flag도 API key도 없으면 patina는 coding agent로 조용히 보내지 않고 오류로 종료합니다. 이유는 [issue #88](https://github.com/devswha/patina/issues/88)를 참고하세요.
+백엔드는 명시적으로 골라야 합니다. `--backend <name>`을 직접 넘기거나, `--backend claude-cli,codex-cli`처럼 우선순위를 적거나, `--model <prefix>`를 쓰세요. `codex-*`, `claude-*`, `gemini-*`, `kimi-*`는 각각 해당 CLI로 연결됩니다. 아무 플래그도 없고 API 키도 없으면 patina는 다른 에이전트로 몰래 넘기지 않고 바로 오류로 끝납니다. 배경은 [issue #88](https://github.com/devswha/patina/issues/88)를 보면 됩니다.
 
 ## Environment variables
 
 ```bash
 PATINA_API_KEY=...                            # required for HTTP backend
 PATINA_API_BASE=https://api.openai.com/v1     # or proxy / OpenRouter / etc.
-PATINA_MODEL=gpt-4o                           # default model
+PATINA_MODEL=gpt-5.5                           # HTTP/OpenAI default model
 ```
 
-`--base-url`, `--model`, `--api-key`, `--provider` flag는 실행마다 이 값을 덮어씁니다.
+`--base-url`, `--model`, `--api-key-file`, `--provider` 플래그는 그 실행에 한해서 이 값을 덮어씁니다.
+`--model`을 따로 주지 않으면 patina는 백엔드마다 문서에 적어 둔 기본 모델을 씁니다. OpenAI HTTP와 `codex-cli`는 `gpt-5.5`, `claude-cli`는 `claude-sonnet-4-6`, Gemini HTTP/CLI는 `gemini-2.5-pro`, `kimi-cli`는 `kimi-code/kimi-for-coding`, Kimi/Moonshot HTTP는 `kimi-k2.5`입니다. `--model codex`, `--model claude`, `--model gemini`, `--model kimi` 같은 별칭도 각 CLI로 라우팅되지만 실제로 넘기는 값은 그 백엔드의 기본 모델입니다.
 
 ## codex-cli backend
 
-patina는 local [`codex`](https://github.com/openai/codex) CLI를 통해 dispatch합니다. 이 CLI는 OpenAI/ChatGPT OAuth로 인증하므로 API key가 필요 없습니다.
+patina는 로컬 [`codex`](https://github.com/openai/codex) CLI로 요청을 보냅니다. 이 CLI는 OpenAI/ChatGPT OAuth로 인증하므로 API 키가 필요 없습니다. `codex exec`에 기본으로 넘기는 모델은 `gpt-5.5`이고, 더 구체적인 Codex 모델 ID를 직접 주면 그 값을 그대로 씁니다.
 
 ```bash
 codex login                                # one-time
+patina auth login codex-cli                # same, with confirmation
 patina --backend codex-cli --lang ko input.txt
-patina --model codex --lang ko input.txt   # same — auto-routes by model name
+patina --model codex --lang ko input.txt   # codex-cli로 라우팅하고 gpt-5.5 기본값 사용
 ```
 
 ## claude-cli backend
 
-local [`claude`](https://docs.anthropic.com/en/docs/claude-code) `-p`를 실행하고 patina prompt를 stdin으로 넘깁니다. Claude subscription이 있으면 무료로 사용할 수 있습니다.
+로컬 [`claude`](https://docs.anthropic.com/en/docs/claude-code) `-p`에 patina 프롬프트를 stdin으로 넘겨 실행합니다. Claude 구독이 있으면 추가 API 키 없이 쓸 수 있습니다. Claude Code는 agent runtime이므로 batch 모드에서는 보수적으로 다룹니다: compact prompt mode, 기본 동시성 `1`, 기본 retry `0`. 기본 모델은 `claude-sonnet-4-6`이지만, Claude Code 자체의 모델/세션 정책은 patina가 완전히 통제하지 못할 수 있습니다.
 
 ```bash
-claude                                     # one-time interactive OAuth
+claude auth login                          # one-time interactive OAuth
+patina auth login claude-cli               # same, with confirmation
 patina --backend claude-cli --lang ko input.txt
 patina --model claude-sonnet-4-6 --lang ko input.txt   # auto-routes
 ```
 
-Auth file: `~/.claude/.credentials.json` (OAuth flow가 만듭니다).
+인증 파일: `~/.claude/.credentials.json` (OAuth 로그인 뒤 생성됩니다).
 
 ## gemini-cli backend
 
-local [`gemini`](https://github.com/google-gemini/gemini-cli) `-p '' --output-format text`를 실행하고 patina prompt를 stdin으로 넘깁니다. 무료 Code Assist OAuth tier 또는 `GEMINI_API_KEY`로 동작합니다.
+로컬 [`gemini`](https://github.com/google-gemini/gemini-cli) `-p '' --output-format text`에 patina 프롬프트를 stdin으로 넘겨 실행합니다. 무료 Code Assist OAuth tier나 `GEMINI_API_KEY`로 쓸 수 있고, 기본 모델은 `gemini-2.5-pro`입니다.
 
 ```bash
 gemini                                     # one-time interactive OAuth, OR
+patina auth login gemini-cli               # same, with confirmation
 export GEMINI_API_KEY="..."                # AI Studio key
 patina --backend gemini-cli --lang ko input.txt
 patina --model gemini-3-flash-preview --lang ko input.txt   # auto-routes
 ```
 
-Notes: patina는 user text 안의 prompt-injection을 격리하기 위해 새 temp directory에서 prompt를 실행하고 `--skip-trust`를 넘깁니다. gemini는 startup latency가 더 길어 default timeout이 다른 CLI보다 높습니다.
+## kimi-cli backend
 
-> **v1 limitation:** `codex-cli`, `claude-cli`, `gemini-cli`는 모두 single-mode rewrite만 지원합니다. `--audit`, `--score`, `--diff`, `--ouroboros`, `--models`/MAX는 여전히 HTTP backend를 사용합니다.
+로컬 [`kimi`](https://moonshotai.github.io/kimi-cli/)를 print mode로 실행하고 patina 프롬프트를 stdin으로 넘깁니다. Kimi Code CLI 브라우저 로그인이나 `KIMI_API_KEY`, `MOONSHOT_API_KEY` 중 하나로 인증할 수 있습니다. Kimi Code는 agent runtime이므로 batch 모드에서는 보수적으로 다룹니다: compact prompt mode, 기본 동시성 `1`, 기본 retry `0`. 로컬 CLI 기본 모델은 `kimi-code/kimi-for-coding`이며, CLI 표시 이름은 Moonshot HTTP 모델 ID와 다를 수 있습니다.
 
-## Free-tier providers
+```bash
+kimi login                                  # one-time browser OAuth, OR
+patina auth login kimi-cli                  # same, with confirmation
+export KIMI_API_KEY="..."                   # optional API key path
+patina --backend kimi-cli --lang ko input.txt
+patina --model kimi --lang ko input.txt     # kimi-cli로 라우팅하고 backend 기본값 사용
+```
+
+자동화에서는 이미 실행 의도가 분명할 때만 `--yes`를 쓰세요.
+
+```bash
+patina auth login codex-cli --yes
+```
+
+참고: patina는 사용자 텍스트 안의 prompt injection 영향을 줄이려고 새 임시 디렉터리에서 프롬프트를 실행하고 `--skip-trust`를 함께 넘깁니다. gemini는 시작이 느린 편이라 기본 timeout도 다른 CLI보다 더 길게 잡혀 있습니다.
 
-API key를 한 번 발급받으면 무료 tier로 사용할 수 있습니다.
+> **지원 범위:** `codex-cli`, `claude-cli`, `gemini-cli`, `kimi-cli`는 로컬 CLI 로그인만 되어 있으면 `PATINA_API_KEY` 없이 rewrite 백엔드로 쓸 수 있습니다. 반면 API 기반 score/audit 경로는 계속 설정된 HTTP/evaluator 키를 사용합니다.
+
+대량 rewrite batch는 가능한 한 로컬 agent CLI보다 `openai-http` 같은 stateless
+OpenAI-compatible HTTP provider를 쓰세요. Batch 모드는 `--timeout-ms`,
+`--max-concurrency`, `--max-retries`, `--max-failures`,
+`--max-failure-rate`, `--stop-on-retryable-storm`을 제공합니다. 자세한 내용은
+[CLI.md](CLI.md#batch-safety-controls)를 보세요.
+
+## HTTP provider examples
+
+호출할 프로바이더에 맞는 API 키를 준비한 뒤 아래처럼 실행하면 됩니다.
 
 ```bash
 # Google Gemini — https://aistudio.google.com/app/apikey
@@ -86,20 +117,14 @@ patina --provider groq --lang ko input.txt
 # Together AI (free models suffixed with "-Free")
 export TOGETHER_API_KEY="..."
 patina --provider together --lang ko input.txt
-```
 
-`--provider`는 알맞은 base URL, default model을 설정하고 provider-specific API key env var를 읽습니다. `--base-url`, `--model`, `--api-key`로 각각 덮어쓸 수 있습니다.
+# Kimi / Moonshot (paid API)
+export KIMI_API_KEY="..."
+patina --provider kimi --lang ko input.txt
 
-## MAX mode dispatch
-
-Claude Code `/patina-max` skill은 HTTP를 완전히 우회합니다. local CLI로 dispatch합니다.
-
-| Model | Dispatch | Auth |
-|-------|----------|------|
-| `claude` | `claude -p` | Claude Code |
-| `codex` | `codex exec --skip-git-repo-check --output-last-message` | ChatGPT OAuth |
-| `gemini` | `gemini -p '' --output-format text` | Google AI Studio |
+export MOONSHOT_API_KEY="..."
+patina --provider moonshot --lang ko input.txt
+```
 
-Claude Code 경로에서는 `PATINA_API_KEY`가 필요 없습니다.
+`--provider`를 쓰면 맞는 base URL과 기본 모델이 자동으로 잡히고, 그 프로바이더에 해당하는 API 키 환경변수도 함께 읽습니다. 필요하면 `--base-url`, `--model`, `--api-key-file`로 각각 덮어쓸 수 있습니다.
 
-Standalone CLI MAX(`patina --models <list>`)는 같은 `--base-url` endpoint를 통해 모델을 호출하므로, 나열된 모든 모델이 그 endpoint에서 제공되어야 합니다. provider를 섞으려면(OpenAI + Anthropic + Google) `--base-url`을 OpenRouter나 다른 multi-provider gateway로 지정하세요.

package/docs/BRANDING.md

@@ -6,22 +6,23 @@ Patina's production brand assets are hand-authored SVGs so maintainers can revie
 
 | Asset | Path | Use |
 |---|---|---|
-| Logo lockup | [`assets/brand/patina-logo.svg`](../assets/brand/patina-logo.svg) | README hero, package pages, docs landing pages |
-| App icon | [`assets/brand/patina-icon.svg`](../assets/brand/patina-icon.svg) | Favicon/app tile/avatar contexts |
+| Logo lockup | [`assets/brand/patina-logo.svg`](../assets/brand/patina-logo.svg) | Package pages and docs landing pages that need the full wordmark + tagline |
+| Transparent mark | [`assets/brand/patina-mark.svg`](../assets/brand/patina-mark.svg) | README hero and other places where surrounding text already supplies the project name |
+| App icon | [`assets/brand/patina-icon.svg`](../assets/brand/patina-icon.svg) | Favicon/app tile/avatar contexts that need a dark backplate |
 | Social preview | [`assets/social/patina-og.svg`](../assets/social/patina-og.svg) | Open Graph / social card export source |
 | Before/after card | [`assets/social/patina-before-after.svg`](../assets/social/patina-before-after.svg) | Launch posts and docs examples |
 
-`patina-logo.svg` is the single canonical horizontal logo. Do not reintroduce README-only duplicates unless the variant is visibly different and documented here.
+`patina-logo.svg` is the single canonical horizontal logo. README uses the transparent mark plus Markdown heading/tagline to avoid repeating the wordmark and tagline.
 
 ## Accessibility checklist
 
 - Keep `role="img"` on standalone SVG assets.
 - Include `<title>` and `<desc>`, or an `aria-label` when a tiny decorative asset cannot carry children.
 - Keep the square icon recognizable at 32px.
-- Keep the logo on a dark backplate so it works on GitHub light and dark themes.
+- Keep the app icon and logo lockup on a dark backplate so they work on GitHub light and dark themes. The transparent mark is for layouts that already provide their own page background.
 - Use system font fallbacks in SVG text; GitHub does not load external web fonts inside `<img>` SVGs.
 
-## Open Graph setup for a future docs site
+## Open Graph setup for the playground/docs site
 
 Markdown on GitHub cannot set Open Graph tags. If patina gets a docs site, use the checked-in social SVG or a generated PNG export and add:
 
@@ -29,9 +30,9 @@ Markdown on GitHub cannot set Open Graph tags. If patina gets a docs site, use t
 <meta property="og:title" content="patina — Strip the AI packaging. Keep the meaning.">
 <meta property="og:description" content="Auditable AI-prose cleanup for KO, EN, ZH, and JA with meaning-preservation checks.">
 <meta property="og:type" content="website">
-<meta property="og:image" content="https://patina.dev/patina-og.png">
+<meta property="og:image" content="https://patina.vibetip.help/assets/social/patina-og.svg">
 <meta name="twitter:card" content="summary_large_image">
-<meta name="twitter:image" content="https://patina.dev/patina-og.png">
+<meta name="twitter:image" content="https://patina.vibetip.help/assets/social/patina-og.svg">
 ```
 
-Export note: many social crawlers handle PNG more reliably than SVG, so keep the SVG as source and publish a PNG derivative from CI or the docs-site build.
+Export note: the playground uses the checked-in SVG directly. If a platform requires PNG, keep the SVG as source and publish a PNG derivative from CI or the docs-site build.

package/docs/CLI.md

@@ -4,7 +4,7 @@ patina's CLI is optimized for interactive editing, but a few surfaces are stable
 
 ## Score gate
 
-Use `--score --exit-on <n>` (or the older `--gate <n>` alias) when CI should fail if a text still reads too AI-like.
+Use `--score --exit-on <n>` when CI should fail if a text still reads too AI-like.
 
 ```bash
 patina --lang en --score --exit-on 30 draft.md
@@ -21,8 +21,7 @@ patina --lang en --score --exit-on 30 draft.md
 | `0` | Command completed; for `--score --exit-on`, the score was at or below the gate. |
 | `1` | Runtime or backend error, including API/auth/backend failures. |
 | `2` | Input/usage error from no interactive input or empty stdin. |
-| `3` | `--score --exit-on` / `--score --gate` completed, but the score exceeded the configured gate. |
-| `4` | MAX mode all candidates failed, or patina fell back because no candidate met the MPS floor. |
+| `3` | `--score --exit-on` completed, but the score exceeded the configured gate. |
 
 ## Output formats
 
@@ -43,11 +42,9 @@ patina --lang en --score --exit-on 30 draft.md
 
 - `overall` and `categories[]` are populated when patina can parse them from score JSON or score tables.
 - Score JSON may include `scores.llm`, `scores.deterministic`, and `scores.preference` when deterministic shadow scoring is available.
-- `mps` is populated for MAX-mode results when available.
-- `gateResult` is `null` unless `--exit-on` / `--gate` is used.
+- `mps` is populated when the underlying mode emits it.
+- `gateResult` is `null` unless `--exit-on` is used.
 - `--voice-sample <path>` or config `voice-sample: <path>` injects the first 1–3 user-written paragraphs into rewrite/Ouroboros prompts as style-only examples of how this person writes. `--profile` / `--tone` still define the outer register; samples refine cadence and texture without importing facts.
-- `--save-run <dir>` writes a schema-v2 `manifest.json` plus `output-N.txt` files for reproducible audit trails. Each result records prompt/response hashes, available token usage, temperature/seed, score details, per-call cost when providers return it, and the Ouroboros iteration log when used.
-- `--cache <dir>` or `PATINA_CACHE_DIR` enables an opt-in persistent HTTP response cache keyed by prompt, model, temperature, and API host. `--cache-ttl <sec>` / `PATINA_CACHE_TTL_SECONDS` set expiry, and `--no-cache` forces a fresh run.
 - `patina doctor --json` emits setup diagnostics for CI without making an LLM call.
 
 ## Stderr logs
@@ -55,12 +52,11 @@ patina --lang en --score --exit-on 30 draft.md
 Human-facing status, warnings, and progress indicators go to stderr so stdout
 stays reserved for the transformed text or JSON envelope.
 
-- `--quiet` suppresses stderr logs, including MAX/Ouroboros progress.
-- `--json-logs` emits newline-delimited JSON records with stable fields:
-  `ts`, `level`, `event`, `model`, `latency_ms`, and optional `message`.
-- MAX mode (`--models`) reports elapsed per-model status (`...`, `✓`, `✗`).
+- `--quiet` suppresses stderr logs, including Ouroboros progress.
 - Ouroboros reports per-iteration score movement and latency.
 
+
+
 ## Backend fallback chains
 
 `--backend <name>` selects one backend. `--backend a,b,c` selects an explicit
@@ -73,8 +69,53 @@ patina --backend claude-cli,codex-cli --lang en draft.md
 ```
 
 All backends share the same invocation contract:
-`invoke({ prompt, model, signal, timeout }): Promise<string>`. Local CLI
-backends honor `AbortSignal` by killing their child process; the HTTP backend
-bridges the same signal into fetch.
+`invoke({ prompt, model, modelSource, signal, timeout, maxRetries }): Promise<string>`.
+Local CLI backends honor `AbortSignal` by killing their child process. When no
+explicit model is set, local backends pass the strongest documented default to
+their CLI (`gpt-5.5`, `claude-sonnet-4-6`, `gemini-2.5-pro`, or
+`kimi-code/kimi-for-coding`); the HTTP backend bridges the same signal into
+fetch.
+
+## Batch safety controls
+
+Batch runs print a preflight safety line before the first request: file count,
+backend chain, prompt mode, backend concurrency cap, retry budget, timeout,
+worst-case request count, and largest/average prompt size.
+
+Defaults are intentionally conservative:
+
+| Backend | Prompt mode | Max concurrency | Max retries |
+|---|---|---:|---:|
+| `openai-http` | strict | 4 | 2 |
+| `codex-cli` | minimal | 2 | 0 |
+| `claude-cli` | minimal | 1 | 0 |
+| `gemini-cli` | minimal | 2 | 0 |
+| `kimi-cli` | minimal | 1 | 0 |
+
+Local CLIs are agent runtimes, not stateless completion APIs. For large rewrite
+batches, prefer an OpenAI-compatible HTTP provider. Override the guardrails only
+when you have measured the backend:
+
+```bash
+patina --batch --backend openai-http --max-concurrency 4 --max-retries 2 docs/*.md
+patina --batch --backend kimi-cli --max-concurrency 1 --max-retries 0 docs/*.md
+```
+
+Circuit breakers stop batch mode after repeated failure instead of burning quota:
+
+```bash
+patina --batch --max-failures 5 --max-failure-rate 0.25 --stop-on-retryable-storm docs/*.md
+patina --batch --timeout-ms 600000 docs/*.md
+```
+
+`--max-failure-rate` accepts either a ratio (`0.25`) or a percent (`25`). By
+default, batch mode stops after a small failure budget, after a 25% failure rate
+once enough files have run, or after repeated retryable storms such as HTTP 429,
+timeouts, empty local-CLI responses, or repeated Kimi/Claude process exits.
+
+MDX/frontmatter note: patina does not parse MDX or rewrite YAML frontmatter
+schemas. For `.mdx` batches, run your site's MDX/build validator after patina
+and keep project-specific guards for frontmatter quoting, trailing model footers,
+and JSX hazards such as malformed `<digit` fragments.
 
 See [EXIT-CODES.md](EXIT-CODES.md) for the full process contract.

package/docs/COOKBOOK.md

@@ -20,7 +20,7 @@ patina --lang en --score --batch content/posts/*.md
 For a stricter sweep that flags anything above 30/100, fail the run instead of just printing:
 
 ```bash
-patina --lang en --score --gate 30 --batch content/posts/*.md
+patina --lang en --score --exit-on 30 --batch content/posts/*.md
 ```
 
 When any file's `overall` exceeds the gate, patina exits with code `3` ([`CLI.md`](CLI.md) §Exit codes), which is perfect for a pre-publish check.
@@ -53,40 +53,27 @@ jobs:
         run: |
           changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '*.md')
           [ -z "$changed" ] && echo "no markdown changes" && exit 0
-          patina --lang en --score --gate 30 --batch $changed
+          patina --lang en --score --exit-on 30 --batch $changed
         env:
           # pick one backend that has a token in repo secrets
           GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
 ```
 
-Drop `--gate` while you calibrate the threshold for your project. Swap `GEMINI_API_KEY` for whichever backend you have (`claude` / `codex` / `gemini`) — see [`AUTHENTICATION.md`](AUTHENTICATION.md) for the full list.
+Drop `--exit-on` while you calibrate the threshold for your project. Swap `GEMINI_API_KEY` for whichever backend you have (`claude` / `codex` / `gemini`) — see [`AUTHENTICATION.md`](AUTHENTICATION.md) for the full list.
 
 ---
 
-## 3. Compare Claude vs Gemini output via MAX mode
+## 3. Compare Claude vs Gemini output manually
 
-When you want a defensible "best" rewrite, run the same paragraph through multiple backends and let MAX mode pick the lowest-AI result that still passes the MPS (Meaning Preservation Score) floor:
-
-```yaml
-# .patina.yaml (project root)
-max-models: [claude, gemini]
-```
-
-```bash
-# Skill flavor (Claude Code / Codex CLI / Cursor / OpenCode):
-/patina-max
-
-[paste your text here]
-```
+When you want to compare how two backends rewrite the same paragraph, run them side by side and diff the outputs directly:
 
 ```bash
-# Standalone CLI flavor — same idea, MAX mode runs each backend independently
 patina --lang en --backend claude-cli draft.md > /tmp/claude.txt
 patina --lang en --backend gemini-cli draft.md > /tmp/gemini.txt
 diff /tmp/claude.txt /tmp/gemini.txt
 ```
 
-MAX mode requires MPS ≥ 70 on each candidate before comparing scores, so the winner is the *lowest AI-likeness rewrite that still preserves meaning*. See [`GLOSSARY.md`](GLOSSARY.md) for MPS and the [`README.md`](../README.md#max-mode) MAX mode section for the selection rules.
+This keeps the comparison explicit: you can read both rewrites, inspect which one preserves your meaning better, and keep whichever voice you prefer.
 
 ---
 
@@ -158,10 +145,10 @@ Block commits that introduce too-AI-sounding markdown. Drop this into `.git/hook
 set -euo pipefail
 changed=$(git diff --cached --name-only --diff-filter=ACM -- '*.md')
 [ -z "$changed" ] && exit 0
-patina --lang en --score --gate 30 --batch $changed
+patina --lang en --score --exit-on 30 --batch $changed
 ```
 
-`--gate` returns exit code `3` when any file's `overall` exceeds the threshold, which the shell treats as failure and aborts the commit. To bypass once (e.g. you intentionally want hype copy), commit with `--no-verify`.
+`--exit-on` returns exit code `3` when any file's `overall` exceeds the threshold, which the shell treats as failure and aborts the commit. To bypass once (e.g. you intentionally want hype copy), commit with `--no-verify`.
 
 ---
 

package/docs/DEMO.md

@@ -2,18 +2,45 @@
 
 A copy/paste demo for showing what patina does: remove AI packaging while keeping the claims intact.
 
+The animated README heroes are language-suffixed:
+
+- English README: [`assets/demo/patina-demo-en.gif`](../assets/demo/patina-demo-en.gif), using
+  [`examples/short/marketing-launch-en.md`](../examples/short/marketing-launch-en.md) →
+  [`examples/short/marketing-launch-en-rewritten.md`](../examples/short/marketing-launch-en-rewritten.md)
+- Korean README: [`assets/demo/patina-demo-ko.gif`](../assets/demo/patina-demo-ko.gif), using
+  [`examples/short/marketing-launch.md`](../examples/short/marketing-launch.md) →
+  [`examples/short/marketing-launch-rewritten.md`](../examples/short/marketing-launch-rewritten.md)
+- Chinese and Japanese READMEs currently fall back to the English GIF until
+  localized recordings are useful enough to maintain.
+
+Re-recording notes live in [`assets/demo/README.md`](../assets/demo/README.md).
+
 ## 30-second terminal transcript
 
-This transcript uses the checked-in short marketing fixture so the example is reviewable without screenshots or a live model run.
+This transcript uses the checked-in English marketing fixture so the example is reviewable without screenshots or a live model run.
+
+```bash
+$ cat examples/short/marketing-launch-en.md
+The newly released Notion template pack is an innovative solution designed to transform productivity for modern teams. It offers 30 templates optimized for diverse workflows, with a user-friendly design that enables anyone to leverage them effortlessly. This product introduces a new paradigm for maximizing work efficiency.
+
+$ patina --lang en --tone marketing examples/short/marketing-launch-en.md
+If Notion still starts as a blank page for your team, open this pack first. It includes 30 templates for common workflows. Duplicate one, adjust the fields you need, and use it for a team project or your own planning without starting from scratch.
+```
+
+Full source/expected pair:
+[`examples/short/marketing-launch-en.md`](../examples/short/marketing-launch-en.md) →
+[`examples/short/marketing-launch-en-rewritten.md`](../examples/short/marketing-launch-en-rewritten.md).
+
+## Korean terminal transcript
+
+This is the Korean fixture used by `README_KR.md`.
 
 ```bash
 $ cat examples/short/marketing-launch.md
 새롭게 출시된 노션 템플릿 팩은 생산성 향상을 위한 혁신적인 솔루션입니다. 다양한 워크플로우에 최적화된 30개의 템플릿을 제공하며, 사용자 친화적인 디자인으로 누구나 손쉽게 활용 가능합니다. 본 제품은 업무 효율성을 극대화하는 새로운 패러다임을 제시합니다.
 
 $ patina --lang ko --tone marketing examples/short/marketing-launch.md
-새로 나온 노션 템플릿 팩에는 업무 흐름별로 바로 쓸 수 있는 템플릿 30개가 들어 있습니다. 복잡한 설정 없이 복제해서 쓰고, 팀이나 개인 작업 방식에 맞게 손보면 됩니다.
-
-노션을 매번 빈 페이지에서 시작했다면, 이제 그 시간부터 줄이세요.
+노션을 자주 쓰지만 매번 빈 페이지에서 막힌다면 이 팩부터 열어 보세요. 업무별 템플릿 30개를 담았습니다. 복잡한 설정 없이 복제해서 바로 고치고, 팀 프로젝트든 개인 정리든 필요한 형태로 손보면 됩니다.
 ```
 
 Full source/expected pair:
@@ -24,7 +51,7 @@ Full source/expected pair:
 
 | Genre | Before | After |
 |---|---|---|
-| Korean marketing | “생산성 향상을 위한 혁신적인 솔루션… 업무 효율성을 극대화하는 새로운 패러다임” | “업무 흐름별로 바로 쓸 수 있는 템플릿 30개… 빈 페이지에서 시작했다면, 이제 그 시간부터 줄이세요.” |
+| Korean marketing | “생산성 향상을 위한 혁신적인 솔루션… 업무 효율성을 극대화하는 새로운 패러다임” | “업무별 템플릿 30개… 팀 프로젝트든 개인 정리든 필요한 형태로 손보면 됩니다.” |
 | Academic | “획기적인 성과가 관찰되었으며… 중요한 역할을 수행할 수 있음을 시사한다” | “평균 구축 시간은 72시간에서 10분 이내로 줄었다… 일반화하기에는 주의가 필요하다.” |
 | Technical | “핵심적인 역할을 수행… 차세대 AI 인프라 환경의 표준” | “GPU 자원 관리는 배포 속도와 운영 비용에 직접 영향을 준다… 검토할 만한 선택지다.” |
 

package/docs/EXIT-CODES.md

@@ -7,8 +7,7 @@ patina uses stable exit codes so CI and editor integrations can distinguish cont
 | `0` | Success. For `--score --exit-on <n>`, the parsed `overall` score was at or below the threshold. |
 | `1` | Runtime/backend failure: API/auth/backend errors, failed doctor blockers, invalid runtime setup, or unexpected exceptions. |
 | `2` | Input/usage failure: unknown flags, missing required option values, empty stdin, or `--no-interactive` with no input. |
-| `3` | Score gate exceeded. `--score --exit-on <n>` or `--score --gate <n>` completed, but `overall > n`. |
-| `4` | MAX mode could not produce a fully acceptable candidate: all candidates failed, or no candidate reached the MPS floor and patina selected the highest-MPS fallback. |
+| `3` | Score gate exceeded. `--score --exit-on <n>` completed, but `overall > n`. |
 
 ## Score gates
 
@@ -16,7 +15,7 @@ patina uses stable exit codes so CI and editor integrations can distinguish cont
 patina --lang en --score --exit-on 30 draft.md
 ```
 
-`--gate <n>` remains as a backward-compatible alias for the same behavior. The command still prints the score output; only the process exit code changes to `3` when the gate fails.
+`--exit-on <n>` prints the score output as usual; only the process exit code changes to `3` when the threshold fails.
 
 ## Empty input