patina-cli 3.11.0

package/README.md

@@ -0,0 +1,319 @@
+<p align="center">
+  <a href="README_KR.md"><b>한국어</b></a> ·
+  <a href="README_ZH.md"><b>中文</b></a> ·
+  <a href="README_JA.md"><b>日本語</b></a> ·
+  <b>English</b>
+</p>
+
+<p align="center">
+  <img src="assets/brand/patina-logo.svg" alt="patina — Strip the AI packaging. Keep the meaning." width="440">
+</p>
+
+<h1 align="center">patina</h1>
+
+<p align="center">
+  <strong>Strip the AI packaging. Keep the meaning.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/devswha/patina/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/devswha/patina/actions/workflows/test.yml/badge.svg"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <a href="#quick-start"><img alt="Skill: Claude Code | Codex | Cursor | OpenCode" src="https://img.shields.io/badge/Skill-Claude%20Code%20%7C%20Codex%20%7C%20Cursor%20%7C%20OpenCode-blueviolet"></a>
+  <a href="https://github.com/devswha/patina"><img alt="Languages: KO | EN | ZH | JA" src="https://img.shields.io/badge/Languages-KO%20%7C%20EN%20%7C%20ZH%20%7C%20JA-green"></a>
+  <a href="CHANGELOG.md"><img alt="Version 3.11.0" src="https://img.shields.io/badge/version-3.11.0-blue"></a>
+</p>
+
+patina looks for AI-sounding patterns in Korean, English, Chinese, and Japanese, then rewrites them without changing the claim. Use it as a skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), [Cursor](https://cursor.sh), and OpenCode, or run it as a standalone Node.js CLI.
+
+It is not a black-box paraphraser. patina is **pattern-based and auditable**: it shows what changed, why it changed, and whether the original claims were preserved.
+
+## Demo
+
+**Before** *(AI-sounding)*:
+> Coffee has emerged as a **pivotal cultural phenomenon** that has **fundamentally transformed** social interactions across the globe. This beloved beverage serves as a catalyst for community building, fosters meaningful connections, and facilitates cross-cultural dialogue.
+
+**After** *(`/patina --lang en` — same claims, AI packaging removed)*:
+> Coffee has quietly changed how people meet. Sit across from someone long enough, and something like a real connection tends to form — even between people from very different cultures.
+
+> **MPS = 100** · cultural transformation ✓ · community building ✓ · meaningful connections ✓ · cross-cultural dialogue ✓
+
+**More demo slices**
+
+| Input type | AI packaging removed | Preserved meaning |
+|---|---|---|
+| Korean marketing | “혁신적인 솔루션”, “새로운 패러다임” | 30 Notion templates, workflow fit, copy-and-edit usage |
+| Academic | “획기적인 성과”, broad significance claims | 60 GitHub projects, 72h→10m setup time, p<0.01, limits noted |
+| Technical | “핵심적인 역할”, future-standard hype | GPU management, one-command provisioning, 5× result caveat |
+
+Try it quickly: [30-second terminal demo](docs/DEMO.md). More examples: [Before/After Gallery](docs/EXAMPLES.md) ([한국어](docs/EXAMPLES_KR.md)).
+Brand assets: [logo](assets/brand/patina-logo.svg), [icon](assets/brand/patina-icon.svg),
+[social preview](assets/social/patina-og.svg), and [before/after card](assets/social/patina-before-after.svg).
+Usage notes: [BRANDING.md](docs/BRANDING.md).
+
+## At a Glance
+
+|  |  |
+|---|---|
+| **160 patterns** | 40 KO + 40 EN + 40 ZH + 40 JA (each incl. 8 score-only viral-hook) — see [PATTERNS.md](docs/PATTERNS.md) |
+| **Editing hotspot recall** | 91% Korean [84.0–95.4%] (n=100) / 76% English [66.7–83.3%] (n=100), binomial 95% CI |
+| **Benchmark report** | Reproducible ko/en/zh/ja suspect-zone benchmark: [latest.md](docs/benchmarks/latest.md) · [latest.json](docs/benchmarks/latest.json) · [detector comparison](docs/benchmarks/detector-comparison.md) |
+| **False positives** | 13–25% point-estimate range across human registers *(not a CI; boundary intrinsic to encyclopedic register, [documented](core/stylometry.md))* |
+| **Modes** | rewrite · audit · score · diff · ouroboros |
+| **Free tier** | Yes — via `codex` CLI (no API key) |
+| **Determinism** | Scoring formula is deterministic; LLM severity assignment ±8–10 pt per run ([scoring.md §8](core/scoring.md)) |
+| **License** | MIT |
+
+## Quick Start
+
+### As a Claude Code or Codex CLI skill
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash
+```
+
+The installer wires patina into Claude Code, [Codex CLI](https://github.com/openai/codex), Cursor, and OpenCode. It resolves the repository HEAD to a concrete commit before checkout; set `PATINA_REF=<tag-or-full-sha>` when you need a fully pinned install. Then:
+
+```
+/patina --lang en
+
+[paste your text here]
+```
+
+Rewrite with a specific tone:
+
+```
+/patina --tone narrative
+
+[paste your essay draft here]
+```
+
+Auto-detect and apply the best-fit tone:
+
+```
+/patina --tone auto --lang en
+
+[paste your text here]
+```
+
+### As a standalone CLI
+
+Requires Node.js ≥ 18. After the npm release is cut, use the package directly:
+
+```bash
+npx patina-cli init --defaults
+npx patina-cli doctor
+npx patina-cli --lang en input.txt
+```
+
+Until then, or when you want to hack on the repo:
+
+```bash
+git clone https://github.com/devswha/patina.git
+cd patina && npm install && npm link
+patina --lang en input.txt
+```
+
+Or try stdin after linking:
+
+```bash
+printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon that has fundamentally transformed social interactions across the globe.' \
+  | patina --lang en --backend codex-cli
+```
+
+> 🆓 **No API key required** if you have any of [`codex`](https://github.com/openai/codex), [`claude`](https://docs.anthropic.com/en/docs/claude-code), or [`gemini`](https://github.com/google-gemini/gemini-cli) CLIs logged in. Pick one with `--backend codex-cli | claude-cli | gemini-cli`, declare an explicit fallback chain such as `--backend claude-cli,codex-cli`, or let the model heuristic route automatically (`--model claude-*` → claude-cli, etc.). See [AUTHENTICATION.md](docs/AUTHENTICATION.md) for the full backend list.
+
+### CI integrations
+
+Patina also ships a no-key, deterministic CI check for prose review:
+
+```yaml
+# .github/workflows/patina.yml
+steps:
+  - uses: actions/checkout@v6
+  - uses: devswha/patina-action@main # use @v1 after npm publish + action tag
+    with:
+      patina-package: github:devswha/patina # remove after patina-cli@latest is on npm
+      report-threshold: 30
+      comment: true
+```
+
+Docker image publishing is tracked separately from the npm release path. Until
+the GHCR image is published, build the local image when you need a container:
+
+```bash
+docker build -t patina:local .
+printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \
+  | docker run --rm -i -e PATINA_API_KEY patina:local --lang en --provider openai
+```
+
+Pre-commit, Husky, Lefthook, Docker, and release workflow notes live in [docs/integrations/](docs/integrations/).
+
+## Intended Use
+
+Use Patina for post-AI editing, audit trails, and voice cleanup when the author is allowed to use AI assistance. It does not promise that text was “originally human,” and it should not be used for academic honor-code evasion, publisher disclosure circumvention, plagiarism laundering, or detector-bypass claims. See [ETHICS.md](docs/ETHICS.md).
+
+## Modes
+
+```
+patina --lang <ko|en|zh|ja> [mode] [--profile <name>] input.txt
+```
+
+| Flag | What it does |
+|------|-------------|
+| *(default)* | Rewrite |
+| `--audit` | Detect AI patterns only |
+| `--score` | 0–100 AI-likeness score with category breakdown |
+| `--score --exit-on <n>` | Keep CI strict: exit code `3` when `overall > n` (`--gate` is kept as an alias) |
+| `--diff` | Show changes pattern by pattern |
+| `--ouroboros` | Iterate the rewrite until score converges (with MPS rollback) |
+| `--lang <ko\|en\|zh\|ja>` | Select language (default: `ko`) |
+| `--profile <name>` | Tone preset: `blog`, `academic`, `technical`, `formal`, `social`, `email`, `legal`, `medical`, `marketing`, `narrative`, `instructional`, `casual-conversation`, `code-comment`, `commit-message`, `release-notes` |
+| `--tone <name>` | Tone category: `casual`, `professional`, `academic`, `narrative`, `marketing`, `instructional`, `auto` |
+| `--batch` | Treat positional args as a list of files (e.g. `--batch docs/*.md`) |
+| `--format json\|text\|markdown` | Select machine-readable JSON, plain text, or default Markdown output |
+| `--quiet` | Suppress status, warning, and progress logs on stderr |
+| `--json-logs` | Emit stderr logs as NDJSON with `level`, `event`, `model`, and `latency_ms` fields |
+| `--prompt-mode strict\|minimal\|auto` | Choose full pattern-pack prompting, compressed prompting, or backend-aware auto |
+| `--variants <1-5>` | Generate multiple rewrite variants with the same facts and meaning anchors |
+
+`patina --help` for the full flag list. `patina doctor --json` checks Node/backend/tmux/API-key readiness without making an LLM call, and `patina init` writes a project `.patina.yaml`.
+
+Dev-native profile shortcuts are available for Markdown-heavy engineering workflows:
+`code-comment` tightens inline comments/docstrings, `commit-message` rewrites Git history text around intent and verification, and `release-notes` turns changelog bullets into user-impact notes with migration risks visible.
+
+### Score-only patterns
+
+`--score` and `--audit` measure a slightly broader set of signals than `--rewrite` does. The viral-hook packs (`ko/en/zh/ja-viral-hook`, 8 patterns each: shock-number hooks, clickbait closings, source-skipping authority claims, breath-optimized short-sentence stacking, hyperbolic engagement lexicon, fake-stat citations, stacked credentials, future-self/parasocial promises) are **detection-only**.
+
+They appear in score and audit output so the benchmark matches human intuition for SNS-style marketing copy across all four languages. `--rewrite`/`--diff`/`--ouroboros` skip them because those signals are often intentional rhetoric. Real-world demos: [`examples/viral-hook/`](examples/viral-hook/).
+
+### Prompt-mode tuning (v3.11)
+
+`--prompt-mode strict|minimal|auto` lets you trade off between the full pattern packs (~34KB structured prompt) and a compressed casual instruction (~3KB). `auto` picks per backend — Gemini does better on minimal (it gets over-constrained by long structured prompts), while Claude leverages the full packs and Codex is roughly insensitive. case-05 documents the A/B.
+
+### Multiple stylistic variants (v3.11)
+
+`--variants <1-5>` asks the model for N voice variants of the rewrite in one call (e.g., V1 casual, V2 direct, V3 measured) — facts, numbers, and causation stay identical across variants. Each comes back as `## Variant N` so you can pick the voice you want.
+
+### Short-text scoring boost (v3.11)
+
+For inputs ≤200 chars or ≤3 paragraphs, register-sensitive categories (`language`, `style`, `viral-hook`) get a 1.5× severity multiplier so single-paragraph voice shifts surface in the score. case-04 found these were undercounted by the long-text formula.
+
+### Self-audit isolation (v3.11)
+
+In rewrite mode, the model emits its self-audit notes inside `[SELF_AUDIT]`/`[/SELF_AUDIT]` tags wrapped around a `[BODY]`/`[/BODY]` block (or `[VARIANT n]` blocks when `--variants > 1`). patina strips the audit before showing the user, so raw output is clean — earlier versions sometimes leaked phrases like "남아 있는 AI 티" or "Phase 3" preambles into the user-facing text.
+
+### Machine-readable output and exit codes
+
+`--format json` wraps every mode in a stable envelope with `overall`, `categories[]`, `tone`, `mps`, `gateResult`, and the cleaned `output` body. `--json-logs` keeps stderr machine-readable as NDJSON, while `--quiet` silences status/warning/progress logs for scripts that only want stdout. `--format markdown` is the default; `--format text` keeps the user-facing body without the YAML tone footer. Exit codes are standardized in [EXIT-CODES.md](docs/EXIT-CODES.md): `0` success, `1` runtime/backend, `2` input/usage, `3` score gate exceeded, `4` MAX MPS fallback/all-candidates-failed.
+
+### Score weight drift detection (v3.11)
+
+`--score` runs cross-check the Weight column the model emits against your config's `category-weights`. If the model invents a category (e.g., `discord`) or substitutes a different number, `[patina]` warnings hit stderr — observability only, the weight check itself doesn't alter the score. A deterministic shadow score from `src/features/*` is also recorded; when it differs from the LLM score by more than 20 points, patina warns and uses the more pessimistic value for gates.
+
+`--save-run <dir>` now writes manifest schema v2: result entries include prompt and response hashes, available input/output token counts, temperature/seed, score details, per-call cost when a provider returns it, and Ouroboros iteration logs.
+
+For repeat benchmarks, opt into the HTTP response cache with `--cache <dir>` or `PATINA_CACHE_DIR`. Cache keys include prompt, model, temperature, and API host; `--cache-ttl <sec>` controls expiry and `--no-cache` bypasses it for fresh runs. Patina prints hit/miss/write stats at the end of cached runs.
+
+Use `--voice-sample <path>` or `voice-sample: <path>` in config to anchor rewrites to 1–3 paragraphs you wrote. Profile and tone still set the requested register; the sample only teaches cadence, specificity, POV, and sentence texture, and the prompt explicitly forbids importing sample facts.
+
+## Tones
+
+`--tone` selects a named voice axis applied on top of pattern rewriting. Resolution order: `--tone` CLI > `tone:` config > `profile:` config.
+
+| Tone | Intended for | Key behaviors |
+|------|-------------|---------------|
+| `casual` | Blog posts, social content, personal notes | Contractions, first-person, emoticons OK, low formality |
+| `professional` | Work emails, reports, business writing | Clear and concise, formal but not stiff; legal/medical sub-profiles force fidelity floor |
+| `academic` | Papers, research summaries, technical analysis | Objective, evidence-oriented, minimal first-person |
+| `narrative` | Personal essays, memoir, experience-based writing | First-person anchor, scene detail, emotional presence, time flow |
+| `marketing` | Ad copy, landing pages, product announcements | Short impact sentences, persuasive, CTA-friendly |
+| `instructional` | Tutorials, how-to guides, technical docs | Imperative verbs, numbered structure, hedging suppressed |
+
+`--tone auto` runs heuristic detection (lexical + structural signals) and selects the best-fit tone. zh/ja with any tone (including `auto`) emits a warning and falls back to profile-only mode — Phase 4.5b heuristics only cover ko/en.
+
+### MAX mode
+
+Run the same text through Claude, Codex, and Gemini independently. The lowest AI-score result that passes MPS ≥ 70 wins:
+
+```
+/patina-max
+
+[paste your text here]
+```
+
+`/patina-max` uses tmux panes for parallel local-CLI dispatch when `dispatch: omc` is enabled. If tmux is unavailable, pass `--dispatch direct` for the no-tmux path; it runs the selected models sequentially and can take roughly one model timeout per model. When `dispatch: omc` falls back automatically outside tmux, Patina prints the expected sequential-vs-parallel wall-clock warning.
+
+Standalone CLI MAX (`patina --models ...`) caps HTTP fanout at `min(models, 3)` by default to avoid quota storms on free-tier providers. Pass `--max-concurrency <n>` to tune the cap, or `--max-concurrency 0` only when you intentionally want unlimited parallel requests.
+
+## How It Works
+
+```
+Input
+  ↓
+[Step 4.5]   Semantic anchor extraction (claims, polarity, causation, numbers)
+[Step 4.6]   Stylometric pre-pass (burstiness CV + MATTR; zh/ja character-token fallback)
+[Step 4.7]   AI-lexicon overlap (~108 EN / 102 KO entries)
+[Phase 1]    Structure scan + anchor verification
+[Phase 2]    Sentence rewrite + anchor verification
+[Phase 3]    Self-audit (polarity, regression, MPS)
+  ↓
+Natural-sounding text (meaning verified)
+```
+
+If meaning drifts at any verification step, the change is retried or rolled back.
+
+**Calibration** *(500-paragraph corpus, reproducible via `.omc/research/v3_8_remeasure.py`)*: 76% editing-hotspot recall on HC3 ChatGPT (en) [66.7–83.3%] and 91% on paired ko/AI corpus [84.0–95.4%], each n=100 with binomial 95% CI. Human-prose false positives are reported separately as a 13–25% point-estimate range across registers, not as a confidence interval. Acceptance gates: AI ≥ 75%, max FP ≤ 25%. See [stylometry.md](core/stylometry.md) for the algorithm.
+
+## Configuration
+
+```yaml
+# .patina.default.yaml
+version: "3.11.0"
+language: ko              # ko | en | zh | ja
+profile: default
+output: rewrite           # rewrite | diff | audit | score
+tone:                     # casual | professional | academic | narrative | marketing | instructional | auto
+max-models: [claude, gemini]
+```
+
+Pattern packs are auto-discovered by language prefix. `.patina.yaml` in the working directory overrides defaults. List keys that extend detection (`blocklist`, `allowlist`, `skip-patterns`) merge additively across default/global/project configs; provider lists such as `max-models` replace so users can choose an exact backend set.
+
+## Documentation
+
+- **[Cookbook](docs/COOKBOOK.md)** — practical recipes (Hugo batch scoring, GitHub Actions, MAX-mode comparison, false-positive triage, custom profiles, pre-commit)
+- **[Glossary](docs/GLOSSARY.md)** — short definitions for MPS, fidelity, burstiness, MATTR, modes, and other recurring terms
+- **[Demo](docs/DEMO.md)** — terminal transcript and multi-genre before/after snapshots
+- **[Patterns](docs/PATTERNS.md)** — full 160-pattern catalog
+- **[Authentication](docs/AUTHENTICATION.md)** ([한국어](docs/AUTHENTICATION_KR.md)) — backends, providers, free-tier setup
+- **[GitHub Action](docs/integrations/github-action.md)** — PR hotspot comments without a live model key
+- **[Pre-commit](docs/integrations/pre-commit.md)** — pre-commit, Husky, and Lefthook score-only recipes
+- **[Docker](docs/integrations/docker.md)** — GHCR image usage and release tags
+- **[Release workflow](docs/integrations/release.md)** — npm provenance + GHCR publishing checklist
+- **[CLI Contract](docs/CLI.md)** — score gate, JSON/text/Markdown output, and automation-safe surfaces
+- **[Flag Parity](docs/FLAG-PARITY.md)** — standalone CLI vs `/patina` vs `/patina-max` option support
+- **[Exit Codes](docs/EXIT-CODES.md)** — process code contract for CI and editor integrations
+- **[Ethics](docs/ETHICS.md)** — intended use, non-use, and disclosure stance
+- **[FAQ](docs/FAQ.md)** ([한국어](docs/FAQ_KR.md)) — detector-bypass concerns, MPS, false positives, contribution starting points
+- **[Comparison](docs/COMPARISON.md)** — factual comparison with common paraphraser/humanizer tools
+- **[Branding](docs/BRANDING.md)** — canonical logo/social assets and OG setup notes
+- **[Design](DESIGN.md)** — product/brand source of truth for repo-native SVG and README surfaces
+- **[Roadmap](docs/ROADMAP.md)** — quality, benchmark, product, community, and launch priorities
+- **[Benchmark Report](docs/benchmarks/latest.md)** — latest reproducible suspect-zone benchmark summary
+- **[Detector Comparison Harness](docs/benchmarks/detector-comparison.md)** — offline/manual comparison protocol for third-party detectors
+- **[AI/Human Metrics Research](docs/research/ai-human-metrics.md)** — benchmark design notes for measuring AI-like writing signals
+- **[2025+ Re-baseline Plan](docs/research/2025-rebaseline-plan.md)** — evidence gate before broader model-era claims
+- **[Launch Copy](docs/social/patina-launch-copy.md)** — Show HN, Reddit, X, Korean community drafts
+- **[Stylometry](core/stylometry.md)** — burstiness + MATTR + AI-lexicon algorithm
+- **[Scoring](core/scoring.md)** — AI-likeness + fidelity + MPS
+- **[Changelog](CHANGELOG.md)** — release notes and methodology
+- **[Contributing](CONTRIBUTING.md)** ([한국어](CONTRIBUTING_KR.md)) — pattern submissions, false-positive triage, benchmark fixtures, versioning
+- **[Governance](GOVERNANCE.md)** / **[Maintainers](MAINTAINERS.md)** — lightweight project decision rules
+
+## Acknowledgements
+
+Inspired by [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)'s plugin architecture (patterns are plugins, profiles are themes), [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) catalog, and [blader/humanizer](https://github.com/blader/humanizer).
+
+## License
+
+MIT

package/README_JA.md

@@ -0,0 +1,254 @@
+**[한국어](README_KR.md)** | **[English](README.md)** | **[中文](README_ZH.md)** | 日本語
+
+# patina
+
+[![Tests](https://github.com/devswha/patina/actions/workflows/test.yml/badge.svg)](https://github.com/devswha/patina/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Skill](https://img.shields.io/badge/Skill-Claude%20Code%20%7C%20Codex%20%7C%20Cursor%20%7C%20OpenCode-blueviolet)](#クイックスタート)
+[![Multi-language](https://img.shields.io/badge/Languages-KO%20%7C%20EN%20%7C%20ZH%20%7C%20JA-green)](https://github.com/devswha/patina)
+[![Version](https://img.shields.io/badge/version-3.11.0-blue)](CHANGELOG.md)
+
+> **AI の装飾だけを剥がし、意味はそのまま。**
+
+patina は、韓国語・英語・中国語・日本語の文章から AI っぽさの強いパターンを見つけ、意味を変えずに書き換えます。[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex CLI](https://github.com/openai/codex)、[Cursor](https://cursor.sh)、OpenCode 向けのスキルとして使うことも、スタンドアロン Node.js CLI として実行することもできます。
+
+一般的なパラフレーザーのようなブラックボックスではありません。patina は **パターンベースで監査可能**で、何をなぜ変更したか、原文の主張が保たれているかを示します。
+
+## デモ
+
+**修正前** *(AI 風の文章)*：
+> コーヒーは、世界中の社会的交流を**根本的に変革した****中核的な文化現象**として台頭してきました。この愛される飲料はコミュニティ構築の触媒として機能し、意義ある繋がりを促進し、異文化間の対話を導いています。
+
+**修正後** *(`/patina --lang ja` — 同じ内容、AI 装飾のみ除去)*：
+> コーヒーは、人の会い方をかなり変えてきたと思う。誰かと向かい合って座っているうちに自然と関係ができるし、文化が違う人同士でも会話が生まれやすくなる。
+
+> **MPS = 100** · 社会的交流の変革 ✓ · コミュニティ構築 ✓ · 意義ある繋がり ✓ · 異文化間の対話 ✓
+
+## 概要
+
+|  |  |
+|---|---|
+| **160 パターン** | 韓国語 40 + 英語 40 + 中国語 40 + 日本語 40 (各8個のスコア専用 viral-hook を含む) — [PATTERNS.md](docs/PATTERNS.md) |
+| **編集ホットスポット再現率** | 韓国語 91% [84.0–95.4%] (n=100) / 英語 76% [66.7–83.3%] (n=100), binomial 95% CI |
+| **誤検出率** | 人間文章レジスター別 13–25% の点推定範囲 *(CI ではない；百科事典体の本質的限界、[文書化済み](core/stylometry.md))* |
+| **モード** | rewrite · audit · score · diff · ouroboros |
+| **無料利用** | 可能 — `codex` CLI 経由 (API キー不要) |
+| **決定性** | スコアリング式は決定的、LLM の severity 判定段階に ±8–10pt の変動 ([scoring.md §8](core/scoring.md)) |
+| **ライセンス** | MIT |
+
+## クイックスタート
+
+### Claude Code または Codex CLI スキルとして
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash
+```
+
+インストーラは Claude Code、[Codex CLI](https://github.com/openai/codex)、Cursor、OpenCode に一括で接続します。checkout 前に repository HEAD を具体的な commit に解決します。完全に固定したインストールが必要な場合は `PATINA_REF=<tag-or-full-sha>` を設定してください。続いて：
+
+```
+/patina --lang ja
+
+[ここにテキストを貼り付け]
+```
+
+特定のトーンで書き換え：
+
+```
+/patina --tone narrative
+
+[ここにエッセイの下書きを貼り付け]
+```
+
+最適なトーンを自動検出：
+
+```
+/patina --tone auto --lang en
+
+[ここにテキストを貼り付け]
+```
+
+> 注意：v1 では `--tone`（`auto` 含む）は ko/en のみ対応。zh/ja では警告を出して profile-only モードにフォールバックします。
+
+### スタンドアロン CLI として
+
+Node.js ≥ 18 が必要です。
+
+```bash
+git clone https://github.com/devswha/patina.git
+cd patina && npm install && npm link
+patina --lang ja input.txt
+```
+
+link 後に stdin でも試せます:
+
+```bash
+printf '%s\n' 'コーヒーは、世界中の社会的交流を根本的に変えた重要な文化現象として浮上しました。' \
+  | patina --lang ja --backend codex-cli
+```
+
+> 🆓 **API キー不要** — [`codex`](https://github.com/openai/codex)、[`claude`](https://docs.anthropic.com/en/docs/claude-code)、[`gemini`](https://github.com/google-gemini/gemini-cli) のいずれか CLI にログイン済みであれば OK。`--backend codex-cli | claude-cli | gemini-cli` で直接選択するか、`--model claude-*` / `--model gemini-*` のようにモデル名でルーティングできます。全バックエンドは [AUTHENTICATION.md](docs/AUTHENTICATION.md) を参照。
+
+### CI integrations
+
+Patina には、live model key なしで使える deterministic な prose review CI チェックもあります:
+
+```yaml
+# .github/workflows/patina.yml
+steps:
+  - uses: actions/checkout@v6
+  - uses: devswha/patina-action@main # npm publish + Action タグ後は @v1 を使用
+    with:
+      patina-package: github:devswha/patina # patina-cli@latest が npm に出たら削除
+      report-threshold: 30
+      comment: true
+```
+
+Pre-commit、Husky、Lefthook、Docker、release workflow のメモは [docs/integrations/](docs/integrations/) にあります。
+
+## 想定用途
+
+Patina は、著者が AI 支援を使ってよい場面で、AI 後編集、audit trail、voice cleanup を行うためのツールです。テキストが「もともと人間によって書かれた」ことを約束するものではなく、学業上の honor-code 回避、出版社 disclosure の迂回、盗用の洗浄、detector-bypass 主張に使うべきではありません。[ETHICS.md](docs/ETHICS.md) を参照してください。
+
+## モード
+
+```
+patina --lang <ko|en|zh|ja> [モード] [--profile <名前>] input.txt
+```
+
+| フラグ | 機能 |
+|--------|------|
+| *(デフォルト)* | 書き換え |
+| `--audit` | AI パターン検出のみ |
+| `--score` | 0–100 AI 類似度スコア + カテゴリ別内訳 |
+| `--score --exit-on <n>` | CI を厳格に保つ: `overall > n` の場合は終了コード `3`（`--gate` は alias） |
+| `--diff` | 変更箇所をパターンごとに表示 |
+| `--ouroboros` | スコア収束まで反復（MPS ロールバック付き） |
+| `--lang <ko\|en\|zh\|ja>` | 言語選択（デフォルト：`ko`） |
+| `--profile <名前>` | トーンプリセット：`blog`, `academic`, `technical`, `formal`, `social`, `email`, `legal`, `medical`, `marketing`, `narrative`, `instructional`, `casual-conversation` |
+| `--tone <名前>` | トーンカテゴリ：`casual`, `professional`, `academic`, `narrative`, `marketing`, `instructional`, `auto` |
+| `--batch` | 位置引数をファイル一覧として処理（例：`--batch docs/*.md`） |
+| `--format json\|text\|markdown` | JSON、プレーンテキスト、デフォルト Markdown 出力を選択 |
+| `--prompt-mode strict\|minimal\|auto` | 完全なパターンパック、圧縮プロンプト、またはバックエンド別 auto を選択 |
+| `--variants <1-5>` | 同じ事実と意味アンカーを保った複数の rewrite バリアントを生成 |
+
+全オプションは `patina --help`。
+
+### スコア専用パターン
+
+`--score`と`--audit`は`--rewrite`より少し広い範囲のシグナルを測定します。viral-hook パック（`ko/en/zh/ja-viral-hook`、各8パターン: 数字ショックフック、クリックベイト末尾、出典を飛ばした権威主張、息継ぎに最適化された短文の積み重ね、誇張されたエンゲージメント語彙、偽統計引用、肩書き積み上げ、未来の自分への約束）は**検出専用**です。
+
+これらのシグナルはスコアと監査にだけ現れ、4言語のSNSマーケティングコピーに対するユーザーの直感とベンチマークを揃えるために使います。`--rewrite`/`--diff`/`--ouroboros` は、意図的な修辞であることが多いので対象外です。実例: [`examples/viral-hook/`](examples/viral-hook/).
+
+### プロンプトモード調整 (v3.11)
+
+`--prompt-mode strict|minimal|auto` では、完全なパターンパック（約34KBの構造化プロンプト）と圧縮されたカジュアル指示（約3KB）のどちらを使うかを調整できます。`auto` はバックエンドごとに選択します — Gemini は minimal の方が良く（長い構造化プロンプトで過度に制約されるため）、Claude は完全なパックを活用し、Codex はおおむね影響を受けません。case-05 が A/B を記録しています。
+
+### 複数の文体バリアント (v3.11)
+
+`--variants <1-5>` は、1回の呼び出しで N 個のリライト音声バリアントを求めます（例: V1 casual、V2 direct、V3 measured）。事実、数値、因果関係はすべてのバリアントで同一に保たれます。各結果は `## Variant N` として返るため、必要な声色を選べます。
+
+### 短文スコアリング補正 (v3.11)
+
+入力が200文字以下、または3段落以下の場合、register に敏感なカテゴリ（`language`、`style`、`viral-hook`）へ 1.5 倍の severity multiplier を適用し、単一段落の声色変化もスコアに反映されるようにします。case-04 では、長文向けの式がこれらを過小評価していたことが確認されました。
+
+### セルフ監査の分離 (v3.11)
+
+rewrite モードでは、モデルは `[BODY]`/`[/BODY]` ブロック（`--variants > 1` の場合は `[VARIANT n]` ブロック）を囲む `[SELF_AUDIT]`/`[/SELF_AUDIT]` タグの中にセルフ監査メモを出力します。patina はユーザーに表示する前に監査部分を取り除くため、出力はクリーンです — 以前のバージョンでは "남아 있는 AI 티" や "Phase 3" のような前置きがユーザー向けテキストに漏れることがありました。
+
+### Machine-readable output and exit codes
+
+`--format json` は、すべてのモードを `overall`、`categories[]`、`tone`、`mps`、`gateResult`、クリーンな `output` 本文を含む安定した envelope で包みます。`--format markdown` がデフォルトで、`--format text` は YAML tone footer なしのユーザー向け本文だけを保持します。終了コードは [EXIT-CODES.md](docs/EXIT-CODES.md) にまとまっています: `0` success、`1` runtime/backend、`2` input/usage、`3` score gate exceeded、`4` MAX MPS fallback/all-candidates-failed。
+
+### スコア重みドリフト検出 (v3.11)
+
+`--score` 実行時は、モデルが出力した Weight 列を設定の `category-weights` と照合します。モデルが存在しないカテゴリ（例: `discord`）を作ったり、別の数値に置き換えたりした場合、stderr に `[patina]` 警告が出ます — これは観測用であり、スコア自体は変更しません。
+
+## トーン
+
+`--tone` はパターン書き換えの上に重ねる、名前付きの声色軸です。優先順位：`--tone` CLI > `tone:` 設定 > `profile:` 設定。
+
+| トーン | 用途 | 主な特徴 |
+|--------|------|----------|
+| `casual` | ブログ、SNS、個人メモ | 短縮形、一人称、絵文字 OK、低い形式度 |
+| `professional` | 業務メール、レポート、ビジネス文書 | 明確で簡潔、形式的だが堅すぎない（legal/medical サブプロファイルは fidelity 下限を強制） |
+| `academic` | 論文、研究要旨、技術分析 | 客観的、根拠重視、一人称は最小限 |
+| `narrative` | 個人エッセイ、回想録、体験談 | 一人称基点、シーンの細部、感情の存在感 |
+| `marketing` | 広告コピー、ランディングページ、製品告知 | 短くインパクトのある文、説得力、CTA 親和 |
+| `instructional` | チュートリアル、ハウツー、技術ドキュメント | 命令形動詞、番号付き構造、推測表現を抑制 |
+
+`--tone auto` はヒューリスティック（語彙 + 構造シグナル）で最適なトーンを自動選択します。zh/ja では `auto` を含む全トーン指定時に警告を出して profile-only モードにフォールバックします — Phase 4.5b ヒューリスティックは ko/en のみ対応のためです。
+
+### MAX モード
+
+同じテキストを Claude、Codex、Gemini に独立に通します。MPS ≥ 70 を満たす中で最もスコアが低い（最も人間らしい）結果が採用されます：
+
+```
+/patina-max
+
+[ここにテキストを貼り付け]
+```
+
+## 仕組み
+
+```
+入力
+  ↓
+[ステップ 4.5]   セマンティックアンカー抽出 (主張、極性、因果、数値)
+[ステップ 4.6]   文体統計プリパス (burstiness CV + MATTR)
+[ステップ 4.7]   AI 語彙オーバーラップ (英 ~108 / 韓 102 項目)
+[フェーズ 1]     構造スキャン + アンカー検証
+[フェーズ 2]     文章リライト + アンカー検証
+[フェーズ 3]     セルフ監査 (極性、回帰、MPS)
+  ↓
+自然なテキスト（意味検証済み）
+```
+
+各検証ステップで意味が損なわれた場合、変更は再試行またはロールバックされます。
+
+**キャリブレーション** *(500 段落コーパス、`.omc/research/v3_8_remeasure.py` で再現可能)*：HC3 ChatGPT (en) 編集ホットスポット再現率 76% [66.7–83.3%]、paired ko/AI コーパス 91% [84.0–95.4%]（各 n=100、binomial 95% CI）。人間文章の誤検出はレジスター別 13–25% の点推定範囲として別に報告します。受け入れ基準：AI ≥ 75%、最大 FP ≤ 25%。アルゴリズムは [stylometry.md](core/stylometry.md)。
+
+## 設定
+
+```yaml
+# .patina.default.yaml
+version: "3.11.0"
+language: ko              # ko | en | zh | ja
+profile: default
+output: rewrite           # rewrite | diff | audit | score
+tone:                     # casual | professional | academic | narrative | marketing | instructional | auto
+max-models: [claude, gemini]
+```
+
+パターンパックは言語プレフィックスで自動検出されます。作業ディレクトリの `.patina.yaml` がデフォルトを上書きします。検出を拡張するリストキー（`blocklist`、`allowlist`、`skip-patterns`）は default/global/project 設定の間で追加的にマージされ、`max-models` などの provider リストはユーザーが正確なバックエンド集合を選べるように置き換えられます。
+
+## ドキュメント
+
+- **[Glossary](docs/GLOSSARY.md)** — MPS、fidelity、burstiness、MATTR、モードなどの反復用語の短い定義
+- **[Demo](docs/DEMO.md)** — ターミナル transcript と複数ジャンルの before/after スナップショット
+- **[Patterns](docs/PATTERNS.md)** — 160 パターンカタログ
+- **[Authentication](docs/AUTHENTICATION.md)** — バックエンド、プロバイダ、無料ティア設定
+- **[CLI Contract](docs/CLI.md)** — score gate、終了コード、自動化に安全なインターフェイス
+- **[Flag Parity](docs/FLAG-PARITY.md)** — standalone CLI、`/patina`、`/patina-max` のオプション対応範囲
+- **[Ethics](docs/ETHICS.md)** — 想定用途、禁止用途、disclosure 方針
+- **[FAQ](docs/FAQ.md)** — detector-bypass の懸念、MPS、誤検出、貢献の始め方
+- **[Comparison](docs/COMPARISON.md)** — 一般的な paraphraser/humanizer ツールとの事実ベース比較
+- **[Branding](docs/BRANDING.md)** — canonical logo/social assets と OG 設定メモ
+- **[Design](DESIGN.md)** — repo-native SVG と README surface の製品/ブランド基準
+- **[Roadmap](docs/ROADMAP.md)** — 品質、ベンチマーク、プロダクト、コミュニティ、ローンチ優先事項
+- **[Benchmark Report](docs/benchmarks/latest.md)** — 最新の再現可能な suspect-zone ベンチマーク要約
+- **[AI/Human Metrics Research](docs/research/ai-human-metrics.md)** — AI-like writing signals 測定用ベンチマーク設計メモ
+- **[Launch Copy](docs/social/patina-launch-copy.md)** — Show HN、Reddit、X、韓国コミュニティ向け下書き
+- **[Stylometry](core/stylometry.md)** — burstiness + MATTR + AI 語彙アルゴリズム
+- **[Scoring](core/scoring.md)** — AI 類似度 + 忠実度 + MPS
+- **[Changelog](CHANGELOG.md)** — リリースノートと方法論
+- **[Contributing](CONTRIBUTING.md)** — パターン提出、誤検出 triage、ベンチマーク fixture、バージョン管理
+- **[Governance](GOVERNANCE.md)** / **[Maintainers](MAINTAINERS.md)** — 軽量なプロジェクト意思決定ルール
+
+## 着想元
+
+[oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) のプラグインアーキテクチャ（パターンがプラグイン、プロファイルがテーマ）、[Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)、[blader/humanizer](https://github.com/blader/humanizer)。
+
+## ライセンス
+
+MIT