patina-cli 3.11.0

package/README_KR.md

@@ -0,0 +1,253 @@
+한국어 | **[English](README.md)** | **[中文](README_ZH.md)** | **[日本語](README_JA.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 ko` — 같은 내용, 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 |
+| **오탐율** | 사람 글 register별 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 에 한 번에 연결합니다. 체크아웃 전에 repository HEAD를 구체적인 commit으로 해석하므로, 완전히 고정된 설치가 필요하면 `PATINA_REF=<tag-or-full-sha>`를 설정하세요. 그런 다음:
+
+```
+/patina --lang ko
+
+[텍스트를 여기에 붙여넣기]
+```
+
+특정 톤으로 재작성:
+
+```
+/patina --tone narrative
+
+[에세이 초안을 여기에 붙여넣기]
+```
+
+자동 톤 감지:
+
+```
+/patina --tone auto --lang ko
+
+[텍스트를 여기에 붙여넣기]
+```
+
+### 독립형 CLI 로
+
+Node.js ≥ 18 필요.
+
+```bash
+git clone https://github.com/devswha/patina.git
+cd patina && npm install && npm link
+patina --lang ko input.txt
+```
+
+link 후 stdin으로도 시험할 수 있습니다:
+
+```bash
+printf '%s\n' '커피는 전 세계의 사회적 상호작용을 근본적으로 바꾼 중요한 문화 현상으로 부상했다.' \
+  | patina --lang ko --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 중 하나만 로그인되어 있으면 됩니다. `--backend codex-cli | claude-cli | gemini-cli` 로 직접 선택하거나 `--model claude-*` / `--model gemini-*` 처럼 모델명으로 라우팅됩니다. 전체 백엔드는 [AUTHENTICATION.md](docs/AUTHENTICATION.md) 참조.
+
+### CI integrations
+
+Patina는 live model key 없이도 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` | 전체 패턴 팩 프롬프트, 압축 프롬프트, 백엔드별 자동 선택 |
+| `--variants <1-5>` | 사실과 의미 앵커를 유지한 여러 rewrite 변형 생성 |
+
+전체 옵션은 `patina --help`.
+
+### 스코어 전용 패턴
+
+`--score`와 `--audit`는 `--rewrite`보다 약간 더 넓은 신호를 측정합니다. viral-hook 팩(`ko/en/zh/ja-viral-hook`, 각 8개 패턴: 숫자 충격 훅, 클릭베이트 종결, 출처 회피 권위 주장, 호흡 최적화 단문 배열, 과장된 참여 유도 어휘, 가짜 통계 인용, 권위 타이틀 쌓기, 미래의 나/친밀한 2인칭 약속)은 **탐지 전용**입니다.
+
+이 신호들은 score와 audit에만 나타나 네 언어의 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>` 는 한 번의 호출에서 N개의 보이스 변형을 요청합니다(예: V1 캐주얼, V2 직설적, V3 절제됨). 사실, 수치, 인과관계는 모든 변형에서 동일하게 유지됩니다. 각 결과는 `## Variant N` 형식으로 돌아오므로 원하는 보이스를 고를 수 있습니다.
+
+### 짧은 텍스트 점수 보정 (v3.11)
+
+입력이 200자 이하이거나 3문단 이하이면 레지스터에 민감한 카테고리(`language`, `style`, `viral-hook`)에 1.5배 severity multiplier를 적용해 단일 문단의 보이스 변화도 점수에 드러나게 합니다. case-04에서 긴 글 기준 공식이 이런 신호를 과소계산한다는 점을 확인했습니다.
+
+### 자기검수 분리 (v3.11)
+
+rewrite 모드에서 모델은 `[BODY]`/`[/BODY]` 블록(또는 `--variants > 1`일 때 `[VARIANT n]` 블록)을 감싸는 `[SELF_AUDIT]`/`[/SELF_AUDIT]` 태그 안에 자기검수 메모를 냅니다. patina는 사용자에게 보여주기 전에 audit을 제거하므로 원시 출력이 깔끔합니다 — 이전 버전에서는 "남아 있는 AI 티"나 "Phase 3" 같은 프리앰블이 사용자-facing 텍스트에 새어 나오는 경우가 있었습니다.
+
+### Machine-readable output and exit codes
+
+`--format json`은 모든 모드를 `overall`, `categories[]`, `tone`, `mps`, `gateResult`, 정리된 `output` 본문을 담은 안정적인 envelope로 감쌉니다. `--format markdown`이 기본값이고, `--format text`는 YAML tone footer 없는 사용자-facing 본문만 유지합니다. 종료 코드는 [EXIT-CODES.md](docs/EXIT-CODES.md)에 정리되어 있습니다: `0` 성공, `1` runtime/backend, `2` input/usage, `3` score gate 초과, `4` MAX MPS fallback/all-candidates-failed.
+
+### 점수 가중치 드리프트 감지 (v3.11)
+
+`--score` 실행은 모델이 출력한 Weight 열을 설정의 `category-weights`와 교차 확인합니다. 모델이 존재하지 않는 카테고리(예: `discord`)를 만들거나 다른 숫자로 바꾸면 `[patina]` 경고가 stderr에 출력됩니다 — 관측용일 뿐 점수 자체는 바꾸지 않습니다.
+
+## 톤
+
+`--tone` 은 패턴 재작성 위에 적용되는 명명된 보이스 축입니다. 우선순위: `--tone` CLI > `tone:` 설정 > `profile:` 설정.
+
+| 톤 | 용도 | 주요 특성 |
+|----|------|-----------|
+| `casual` | 블로그, SNS, 개인 메모 | 축약, 1인칭, 이모티콘 허용, 낮은 격식 |
+| `professional` | 업무 메일, 보고서, 비즈니스 | 명확하고 간결, 격식 있되 딱딱하지 않음 (legal/medical 하위 프로필은 fidelity 하한 강제) |
+| `academic` | 논문, 연구 요약, 기술 분석 | 객관적, 근거 중심, 1인칭 최소화 |
+| `narrative` | 에세이, 회고록, 경험담 | 1인칭 중심, 장면 디테일, 감정의 흐름 |
+| `marketing` | 광고 카피, 랜딩 페이지, 제품 알림 | 짧고 강한 문장, 설득력, CTA 친화 |
+| `instructional` | 튜토리얼, 하우투, 기술 문서 | 명령형 동사, 번호 매김 구조, 추측 표현 억제 |
+
+`--tone auto` 는 휴리스틱(어휘 + 구조 신호)으로 가장 적합한 톤을 자동 선택합니다. zh/ja 에서는 `auto` 포함 모든 톤 지정 시 경고를 내고 프로필 전용 모드로 폴백합니다 — Phase 4.5b 휴리스틱이 ko/en만 지원하기 때문입니다.
+
+### MAX 모드
+
+같은 텍스트를 Claude, Codex, Gemini 에 독립적으로 돌립니다. MPS ≥ 70 을 통과한 결과 중 AI 점수가 가장 낮은 (가장 사람다운) 결과가 선택됩니다:
+
+```
+/patina-max
+
+[텍스트를 여기에 붙여넣기]
+```
+
+## 동작 원리
+
+```
+입력
+  ↓
+[4.5단계]    의미 앵커 추출 (주장, 극성, 인과관계, 수치)
+[4.6단계]    문체 통계 전처리 (burstiness CV + MATTR)
+[4.7단계]    AI 어휘 오버랩 (영어 ~108 / 한국어 102 항목)
+[Phase 1]    구조 스캔 + 앵커 검증
+[Phase 2]    문장 재작성 + 앵커 검증
+[Phase 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). 사람 글 오탐은 register별 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_KR.md)** ([English](docs/AUTHENTICATION.md)) — 백엔드, 프로바이더, 무료 티어 설정
+- **[CLI Contract](docs/CLI.md)** — score gate, exit code, 자동화에 안전한 표면
+- **[Flag Parity](docs/FLAG-PARITY.md)** — standalone CLI, `/patina`, `/patina-max` 옵션 지원 범위
+- **[Ethics](docs/ETHICS.md)** — 의도한 사용, 금지 사용, disclosure 입장
+- **[FAQ](docs/FAQ_KR.md)** ([English](docs/FAQ.md)) — detector-bypass 우려, MPS, 오탐, 기여 시작점
+- **[Comparison](docs/COMPARISON.md)** — 일반 paraphraser/humanizer 도구와의 사실 기반 비교
+- **[Branding](docs/BRANDING.md)** — canonical 로고/소셜 asset과 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 signal 측정용 벤치마크 설계 메모
+- **[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)** — 릴리스 노트와 방법론
+- **[Examples](docs/EXAMPLES_KR.md)** ([English](docs/EXAMPLES.md)) — before/after 갤러리와 예시 fixture 안내
+- **[Contributing](CONTRIBUTING_KR.md)** ([English](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

package/README_ZH.md

@@ -0,0 +1,254 @@
+**[한국어](README_KR.md)** | **[English](README.md)** | 中文 | **[日本語](README_JA.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 zh` 处理 — 同样内容，仅去除 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 严重度判定阶段 ±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
+```
+
+安装脚本会把 patina 一次性接入 Claude Code、[Codex CLI](https://github.com/openai/codex)、Cursor、OpenCode。它会在 checkout 前把 repository HEAD 解析到具体 commit；如果需要完全固定安装，请设置 `PATINA_REF=<tag-or-full-sha>`。然后：
+
+```
+/patina --lang zh
+
+[在此粘贴你的文本]
+```
+
+以特定语调改写：
+
+```
+/patina --tone narrative
+
+[在此粘贴你的随笔草稿]
+```
+
+自动检测最适合的语调：
+
+```
+/patina --tone auto --lang en
+
+[在此粘贴你的文本]
+```
+
+> 注意：`--tone`（含 `auto`）在 v1 仅对 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 zh input.txt
+```
+
+也可以 link 后通过 stdin 试用：
+
+```bash
+printf '%s\n' '咖啡已成为一种关键文化现象，从根本上改变了全球各地的社会互动。' \
+  | patina --lang zh --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 已登录即可。可通过 `--backend codex-cli | claude-cli | gemini-cli` 直接选择，或用 `--model claude-*` / `--model gemini-*` 按模型名路由。完整后端列表见 [AUTHENTICATION.md](docs/AUTHENTICATION.md)。
+
+### CI integrations
+
+Patina 提供不需要 live model key 的确定性 CI prose review：
+
+```yaml
+# .github/workflows/patina.yml
+steps:
+  - uses: actions/checkout@v6
+  - uses: devswha/patina-action@main # npm 发布并打 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 后编辑、保留审计轨迹和清理 voice。它不承诺文本“原本由人类写成”，也不应被用于规避学术 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` | 选择完整模式包提示、压缩提示，或按后端自动选择 |
+| `--variants <1-5>` | 生成多个改写变体，同时保留相同事实和意义锚点 |
+
+完整选项请运行 `patina --help`。
+
+### 仅评分模式
+
+`--score` 和 `--audit` 测量的信号范围比 `--rewrite` 略广。viral-hook 包（`ko/en/zh/ja-viral-hook`，每种语言 8 个模式：数字震撼钩子、标题党收尾、跳过来源的权威断言、适合呼吸节奏的短句堆叠、夸张互动词汇、伪统计引用、头衔堆叠、未来自我承诺）为**仅检测**模式。
+
+这些信号只会出现在评分和审计中，用来让基准更贴近用户对四种语言 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>` 会在一次调用中请求 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 模式中，模型会把自审笔记放在 `[SELF_AUDIT]`/`[/SELF_AUDIT]` 标签内，并包裹一个 `[BODY]`/`[/BODY]` 块（当 `--variants > 1` 时则是 `[VARIANT n]` 块）。patina 会在展示给用户前移除审计内容，因此原始输出保持干净 — 早期版本有时会把 “남아 있는 AI 티” 或 “Phase 3” 之类的前言泄漏到用户可见文本中。
+
+### Machine-readable output and exit codes
+
+`--format json` 会把所有模式包进稳定 envelope，包含 `overall`、`categories[]`、`tone`、`mps`、`gateResult` 和清理后的 `output` 正文。`--format markdown` 是默认值；`--format text` 保留无 YAML tone footer 的用户可见正文。退出码见 [EXIT-CODES.md](docs/EXIT-CODES.md)：`0` 成功，`1` runtime/backend，`2` input/usage，`3` score gate 超限，`4` MAX MPS fallback/all-candidates-failed。
+
+### 分数权重漂移检测 (v3.11)
+
+`--score` 运行会把模型输出的 Weight 列与配置中的 `category-weights` 交叉检查。如果模型凭空创造类别（例如 `discord`）或替换成不同数字，stderr 会出现 `[patina]` 警告 — 这只用于可观测性，不会改变分数本身。
+
+## 语调
+
+`--tone` 是叠加在模式改写之上的具名声音轴。优先级：`--tone` CLI > `tone:` 配置 > `profile:` 配置。
+
+| 语调 | 适用 | 主要特征 |
+|------|------|----------|
+| `casual` | 博客、社交内容、个人笔记 | 缩略、第一人称、表情符号可用、低正式度 |
+| `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 门槛后，AI 分数最低（最像人写）的结果胜出：
+
+```
+/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)** — 预期用途、禁止用途和披露立场
+- **[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) 的插件架构（模式即插件，profile 即主题）、[Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)、[blader/humanizer](https://github.com/blader/humanizer)。
+
+## 许可证
+
+MIT