patina-cli 3.11.0

package/docs/COOKBOOK.md

@@ -0,0 +1,173 @@
+# Cookbook
+
+Practical recipes for plugging patina into existing writing and CI workflows. Each recipe is self-contained — copy, adapt, run.
+
+For the full flag list see `patina --help` and [`CLI.md`](CLI.md). For tone / profile background see [`README.md`](../README.md#modes).
+
+---
+
+## 1. Batch-score a Hugo content folder
+
+You have a Hugo site with many drafts under `content/posts/`. You want a quick AI-likeness scan over the whole folder before publishing.
+
+```bash
+# from your Hugo project root
+patina --lang en --score --batch content/posts/*.md
+```
+
+`--batch` treats every positional arg as an input file, so any glob your shell expands works. `--score` per file prints `overall` plus the category breakdown.
+
+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
+```
+
+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.
+
+---
+
+## 2. GitHub Actions integration (minimal workflow YAML)
+
+Run patina as a non-blocking quality check on every PR that touches markdown.
+
+```yaml
+# .github/workflows/patina.yml
+name: Patina score
+on:
+  pull_request:
+    paths: ["**/*.md"]
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: |
+          git clone --depth 1 https://github.com/devswha/patina.git /tmp/patina
+          cd /tmp/patina && npm install --omit=dev && npm link
+      - name: Score changed markdown
+        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
+        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.
+
+---
+
+## 3. Compare Claude vs Gemini output via MAX mode
+
+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]
+```
+
+```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.
+
+---
+
+## 4. Investigate a false positive with `--diff --audit`
+
+A sentence got rewritten when you wanted it preserved. To see exactly which pattern fired, run audit and diff against the same input:
+
+```bash
+patina --lang en --audit draft.md          # which patterns the scanner thinks fired
+patina --lang en --diff draft.md           # pattern-by-pattern before/after
+```
+
+Cross-reference the firing pattern IDs against [`PATTERNS.md`](PATTERNS.md). If a pattern is consistently mis-firing on your domain (e.g. legal boilerplate that legitimately uses "fundamentally"), add it to `skip-patterns` in your config:
+
+```yaml
+# .patina.yaml
+skip-patterns:
+  - en:7    # AI vocabulary words — too aggressive for legal prose
+```
+
+`skip-patterns` is a list key that merges additively across default / global / project configs, so the project-level skip doesn't lose the defaults.
+
+---
+
+## 5. Create a custom profile (copy `blog.md`, edit voice-overrides)
+
+When the built-in 12 profiles don't match your house style, fork the closest one:
+
+```bash
+cp profiles/blog.md profiles/my-newsletter.md
+```
+
+Edit the frontmatter — at minimum change `profile:`, then tune `voice-overrides` and `pattern-overrides` to match the voice you want:
+
+```yaml
+---
+profile: my-newsletter            # must match the filename without .md
+name: Internal newsletter profile
+version: 1.0.0
+scope: weekly engineering newsletter
+voice-overrides:
+  first-person: amplify           # we sign every post
+  opinions: amplify               # opinionated framing is the point
+  humor: allow                    # dry humor ok
+  messiness: reduce               # cleaner than personal blog
+pattern-overrides:
+  en:
+    14: suppress                  # bold is allowed for scannable sections
+    7:  amplify                   # AI-vocab cleanup stays strict
+---
+```
+
+Then opt-in per run:
+
+```bash
+patina --lang en --profile my-newsletter post.md
+```
+
+Voice-override values are `amplify` / `allow` / `reduce` / `suppress`; pattern IDs and their meanings are in [`PATTERNS.md`](PATTERNS.md).
+
+---
+
+## 6. Pre-commit hook wrapper *(optional)*
+
+Block commits that introduce too-AI-sounding markdown. Drop this into `.git/hooks/pre-commit` (or wire it up through `pre-commit`/`husky` if you already use them):
+
+```bash
+#!/usr/bin/env bash
+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
+```
+
+`--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`.
+
+---
+
+## Where to go next
+
+- Tone reference: [`README.md`](../README.md#tones)
+- Free-tier setup (no API key): [`AUTHENTICATION.md`](AUTHENTICATION.md)
+- MPS and other terms: [`GLOSSARY.md`](GLOSSARY.md)
+- Adding patterns or false-positive triage: [`CONTRIBUTING.md`](../CONTRIBUTING.md)

package/docs/DEMO.md

@@ -0,0 +1,40 @@
+# Demo
+
+A copy/paste demo for showing what patina does: remove AI packaging while keeping the claims intact.
+
+## 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.
+
+```bash
+$ cat examples/short/marketing-launch.md
+새롭게 출시된 노션 템플릿 팩은 생산성 향상을 위한 혁신적인 솔루션입니다. 다양한 워크플로우에 최적화된 30개의 템플릿을 제공하며, 사용자 친화적인 디자인으로 누구나 손쉽게 활용 가능합니다. 본 제품은 업무 효율성을 극대화하는 새로운 패러다임을 제시합니다.
+
+$ patina --lang ko --tone marketing examples/short/marketing-launch.md
+새로 나온 노션 템플릿 팩에는 업무 흐름별로 바로 쓸 수 있는 템플릿 30개가 들어 있습니다. 복잡한 설정 없이 복제해서 쓰고, 팀이나 개인 작업 방식에 맞게 손보면 됩니다.
+
+노션을 매번 빈 페이지에서 시작했다면, 이제 그 시간부터 줄이세요.
+```
+
+Full source/expected pair:
+[`examples/short/marketing-launch.md`](../examples/short/marketing-launch.md) →
+[`examples/short/marketing-launch-rewritten.md`](../examples/short/marketing-launch-rewritten.md).
+
+## Before/after snapshots
+
+| Genre | Before | After |
+|---|---|---|
+| Korean marketing | “생산성 향상을 위한 혁신적인 솔루션… 업무 효율성을 극대화하는 새로운 패러다임” | “업무 흐름별로 바로 쓸 수 있는 템플릿 30개… 빈 페이지에서 시작했다면, 이제 그 시간부터 줄이세요.” |
+| Academic | “획기적인 성과가 관찰되었으며… 중요한 역할을 수행할 수 있음을 시사한다” | “평균 구축 시간은 72시간에서 10분 이내로 줄었다… 일반화하기에는 주의가 필요하다.” |
+| Technical | “핵심적인 역할을 수행… 차세대 AI 인프라 환경의 표준” | “GPU 자원 관리는 배포 속도와 운영 비용에 직접 영향을 준다… 검토할 만한 선택지다.” |
+
+Reference files:
+
+- Academic: [`examples/genres/academic.md`](../examples/genres/academic.md) → [`examples/genres/academic-rewritten.md`](../examples/genres/academic-rewritten.md)
+- Technical: [`examples/genres/technical.md`](../examples/genres/technical.md) → [`examples/genres/technical-rewritten.md`](../examples/genres/technical-rewritten.md)
+
+## What to point out in a live demo
+
+1. The output removes inflated claims like “혁신적인 솔루션” and “새로운 패러다임.”
+2. Concrete facts survive: 30 templates, workflow fit, setup simplicity, and the user action.
+3. The rewrite is auditable because the source fixture, expected rewrite, and pattern catalog all live in the repo.

package/docs/ETHICS.md

@@ -0,0 +1,27 @@
+# Ethics and Intended Use
+
+Patina removes generic AI-writing packaging while preserving the author's intended meaning. It is an editing aid, not a provenance oracle.
+
+## Patina is for
+
+- **Post-AI editing:** cleaning drafts that the author is permitted to create with AI assistance.
+- **Audit trails:** showing which patterns were flagged and why a rewrite changed them.
+- **Voice preservation:** making prose sound less templated without changing claims, numbers, polarity, or causation.
+- **False-positive review:** helping maintainers and editors discuss suspicious passages without accusing a writer.
+- **Contributor research:** improving pattern packs, fixtures, and benchmark methodology in public.
+
+## Patina is not for
+
+- **Academic honor-code evasion.** If a school, journal, or publisher requires disclosure, patina does not remove that obligation.
+- **Publisher or workplace AI-disclosure circumvention.** A cleaner sentence is not evidence that AI was not used.
+- **Plagiarism laundering.** Rewriting copied text does not make it yours.
+- **Detector-bypass guarantees.** Scores are editing signals with false positives and false negatives, not guarantees against Turnitin, GPTZero, Originality, or any other detector.
+- **Authorship accusation.** Do not use patina output or score reports as proof that a person used AI.
+
+## What the score means
+
+The AI-likeness score estimates how many known surface patterns appear in a text. It is useful for editing prioritization. It is not a moral judgment, authorship proof, or policy-compliance certificate.
+
+## Disclosure stance
+
+If a policy asks whether AI assisted the writing, answer that policy honestly. Patina can help make allowed AI-assisted drafts clearer and more faithful to the author's intent, but it cannot convert AI-assisted work into “originally human” work under policies that define originality by process.

package/docs/EXAMPLES.md

@@ -0,0 +1,130 @@
+# Before/After Gallery
+
+patina is easiest to understand with examples: the claims stay, the AI packaging goes.
+
+## English: inflated product copy
+
+**Before**
+
+> AI coding tools represent a transformative leap forward in the software development lifecycle, enabling teams to streamline workflows, enhance collaboration, and unlock unprecedented levels of productivity across the organization.
+
+**After**
+
+> AI coding tools are useful for the boring parts: test stubs, config files, small refactors. They do not fix a messy codebase, but they can save time when someone still checks the output.
+
+**Patterns removed**: inflated stakes, corporate abstractions, three-part benefit stack.
+
+## Korean: benefit stacking
+
+**Before**
+
+> 본 솔루션은 사용자의 업무 효율성을 극대화하고, 생산성 향상을 도모하며, 더 나은 협업 경험을 제공하는 혁신적인 도구입니다.
+
+**After**
+
+> 이 도구는 반복 작업을 줄여준다. 문서 정리, 초안 작성, 간단한 협업 흐름처럼 사람이 굳이 매번 손으로 할 필요 없는 일에 잘 맞는다.
+
+**Patterns removed**: `혁신적인`, `도모`, abstract benefit stacking, stiff noun-heavy phrasing.
+
+## English: vague balance
+
+**Before**
+
+> While there are challenges to consider, it is important to recognize that this technology has the potential to create meaningful value when implemented thoughtfully.
+
+**After**
+
+> The tool is useful, but only if someone checks the output. Without tests or review, it just makes wrong answers arrive faster.
+
+**Patterns removed**: generic caveat, vague upside, empty balance.
+
+## Technical: architecture claims
+
+**Before**
+
+> This architecture provides a robust and scalable foundation for future enhancements, ensuring that teams can effectively adapt to evolving requirements while maintaining operational excellence.
+
+**After**
+
+> The architecture leaves room for new backends without touching the CLI entry point. That is the useful part. The tradeoff is more config surface, so the defaults need to stay boring and safe.
+
+**Patterns removed**: `robust and scalable foundation`, future-proofing claims, operational-excellence filler.
+
+## Korean: instructional / tutorial register
+
+**Before**
+
+> Git stash는 작업 중인 변경사항을 임시로 저장할 수 있는 매우 유용한 기능입니다. 본 명령어를 활용함으로써 사용자는 현재 작업 내용을 손실 없이 다른 브랜치로 신속하게 전환할 수 있게 됩니다.
+
+**After**
+
+> Git stash로 작업 중인 변경사항을 잠시 보관하세요. 커밋하기 애매한 수정이 있을 때 유용합니다. stash에 넣어두면 변경사항을 잃지 않고 다른 브랜치로 이동할 수 있습니다.
+
+**Patterns removed**: `매우 유용한` (ko-content #4 promotional adjective), `본 명령어를 활용함으로써` (ko-style noun-heavy formal connector), `~할 수 있게 됩니다` (ko-structure #25 inflated future-tense). Use-context ("커밋하기 애매한 수정이 있을 때") added so the tutorial actually teaches *when* to use the command.
+
+## Korean: 1인칭 회고 — abstract metaphor → sensory detail
+
+**Before**
+
+> 처음 코드 리뷰를 받았던 날을 떠올리면 여전히 마음 한구석이 묘해지는 것을 느낀다. 선배의 피드백 한 줄 한 줄이 마치 거대한 산처럼 다가왔으며, 그 순간은 개발자로서의 성장에 있어 잊을 수 없는 의미 있는 전환점이었다고 표현할 수 있을 것이다.
+
+**After**
+
+> 처음 코드 리뷰를 받던 날이 아직도 가끔 떠오른다. 선배가 남긴 피드백은 한 줄씩 읽을 때마다 이상하게 크게 느껴졌다. 모니터 앞에서 댓글을 하나씩 열어보던 장면이 선명하다. 손은 마우스 위에 있었고, 머릿속은 자꾸 하얘졌다. 지금 생각하면 그날은 대단한 사건이라기보다, 내가 처음으로 내 코드를 남의 눈으로 본 날에 가까웠다.
+
+**Patterns removed**: `마치 거대한 산처럼` (ko-content abstract metaphor), `의미 있는 전환점이었다고 표현할 수 있을 것이다` (ko-structure #25 hedge stack + ko-content inflated significance). Replaced with concrete physical detail (`손은 마우스 위에`, `머릿속은 자꾸 하얘졌다`) — the narrative profile's `concrete-emotions: amplify` setting.
+
+## Korean: SNS marketing — viral-hook signals
+
+**Before**
+
+> GitHub 역사상 이런 속도는 없었다. 단 60일 만에 별 25만 개. OpenClaw라는 도구가 세운 기록임. 광고 한 번 안 하고 전 세계 개발자들이 미친 듯이 달려든 이유가 뭘까.
+
+**After**
+
+> GitHub에서 이런 속도는 거의 못 봤다. 60일 만에 별 25만 개. OpenClaw가 만든 기록이다. 광고로 뜬 게 아니다. 개발자들이 새벽 3시에 버그 잡다가 짜증 나던 부분을 정확히 긁었다.
+
+**Patterns removed**: `역사상 ... 없었다` (ko-viral-hook #3 source-skipping authority claim), `미친 듯이 달려든` (ko-viral-hook #5 hyperbolic engagement lexicon), `이유가 뭘까` (ko-viral-hook #2 clickbait mystery close → resolved into concrete explanation). The viral-hook pack is **score-only**, but the model still re-frames these signals during a regular rewrite once the content/style packs are applied.
+
+## English: chatbot register
+
+**Before**
+
+> I'd be happy to help you understand Git stash! That's a great question. Git stash is a very useful command that allows you to temporarily save your changes. Let me know if you have any other questions!
+
+**After**
+
+> Git stash temporarily saves your in-progress changes so you can switch branches without committing or losing them. It's most useful when a fix or quick task pulls you off the work you're already doing.
+
+**Patterns removed**: `I'd be happy to help` + `That's a great question` (en-communication #19 chatbot expressions, #21 sycophancy), `very useful` (en-content promotional adjective), `Let me know if you have any other questions` (en-communication closing politeness). Replaces the chat affect with the actual answer.
+
+## English: viral-hook authority claim
+
+**Before**
+
+> The fastest growth GitHub has ever seen — devs around the world are absolutely losing their minds. Why is everyone flocking to OpenClaw without any marketing?
+
+**After**
+
+> OpenClaw hit 250K stars in 60 days with no paid promotion. The popularity didn't come from marketing — it came from one shipped command that replaces a few hours of cluster setup. NVIDIA has since picked it up, which makes the timing easier to read.
+
+**Patterns removed**: `the fastest GitHub has ever seen` (en-viral-hook #3 source-skipping authority claim), `absolutely losing their minds` (en-viral-hook #5 hyperbolic lexicon), `Why is everyone ... without any marketing?` (en-viral-hook #2 clickbait mystery close). Concrete numbers + a verifiable corroborating fact replace the unsupported absolutes. Like the Korean SNS example above, viral-hook is score-only — the rewrite drives this through neighboring content/style patterns.
+
+## More gallery material
+
+This page shows the canonical short examples. The repo also ships longer fixtures and full case studies you can copy from:
+
+- **`examples/short/`** — four short Korean fixtures (marketing, tutorial, essay, email) with paired `*-rewritten.md` files.
+- **`examples/genres/`** — three longer Korean genres (technical, academic, narrative) with paired rewrites.
+- **`examples/tones/`** — the same input rewritten in six tones (`casual`, `professional`, `academic`, `narrative`, `marketing`, `instructional`) plus `auto`. See `examples/tones/RESULTS.md` for the side-by-side.
+- **`examples/viral-hook/`** — case studies (`case-01` through `case-09`) covering the iterative improvement workflow: viral-hook detection, codex/claude/gemini comparisons, voice profiles, multi-genre validation.
+- **`examples/sample-rewritten-*.md`** — the same long-form Korean SNS marketing post rewritten by Codex / Claude / Gemini-3, used in `case-03` for cross-model comparison.
+
+## What patina is checking
+
+- Did the rewrite remove AI-writing patterns?
+- Did the rewrite keep the original claims?
+- Did the rewrite introduce anything that was not in the source?
+- Can the change be inspected through `--audit`, `--diff`, or `--score`?
+
+The goal is editing quality, not detector evasion. AI detectors are noisy; patina treats the score as a rough signal and the diff as the useful artifact.

package/docs/EXAMPLES_KR.md

@@ -0,0 +1,130 @@
+# Before/After Gallery
+
+patina는 예시로 보는 편이 가장 쉽습니다. 주장은 남고, AI 포장은 사라집니다.
+
+## English: 부풀린 제품 카피
+
+**Before**
+
+> AI coding tools represent a transformative leap forward in the software development lifecycle, enabling teams to streamline workflows, enhance collaboration, and unlock unprecedented levels of productivity across the organization.
+
+**After**
+
+> AI coding tools are useful for the boring parts: test stubs, config files, small refactors. They do not fix a messy codebase, but they can save time when someone still checks the output.
+
+**제거한 패턴**: 부풀린 중요도, 기업식 추상어, 세 갈래 장점 나열.
+
+## Korean: 장점 나열
+
+**Before**
+
+> 본 솔루션은 사용자의 업무 효율성을 극대화하고, 생산성 향상을 도모하며, 더 나은 협업 경험을 제공하는 혁신적인 도구입니다.
+
+**After**
+
+> 이 도구는 반복 작업을 줄여준다. 문서 정리, 초안 작성, 간단한 협업 흐름처럼 사람이 굳이 매번 손으로 할 필요 없는 일에 잘 맞는다.
+
+**제거한 패턴**: `혁신적인`, `도모`, 추상적인 장점 나열, 딱딱한 명사형 문장.
+
+## English: 흐릿한 균형감
+
+**Before**
+
+> While there are challenges to consider, it is important to recognize that this technology has the potential to create meaningful value when implemented thoughtfully.
+
+**After**
+
+> The tool is useful, but only if someone checks the output. Without tests or review, it just makes wrong answers arrive faster.
+
+**제거한 패턴**: 일반적인 caveat, 흐릿한 upside, 빈 균형감.
+
+## Technical: 아키텍처 주장
+
+**Before**
+
+> This architecture provides a robust and scalable foundation for future enhancements, ensuring that teams can effectively adapt to evolving requirements while maintaining operational excellence.
+
+**After**
+
+> The architecture leaves room for new backends without touching the CLI entry point. That is the useful part. The tradeoff is more config surface, so the defaults need to stay boring and safe.
+
+**제거한 패턴**: `robust and scalable foundation`, future-proofing 주장, operational-excellence filler.
+
+## Korean: instructional / tutorial register
+
+**Before**
+
+> Git stash는 작업 중인 변경사항을 임시로 저장할 수 있는 매우 유용한 기능입니다. 본 명령어를 활용함으로써 사용자는 현재 작업 내용을 손실 없이 다른 브랜치로 신속하게 전환할 수 있게 됩니다.
+
+**After**
+
+> Git stash로 작업 중인 변경사항을 잠시 보관하세요. 커밋하기 애매한 수정이 있을 때 유용합니다. stash에 넣어두면 변경사항을 잃지 않고 다른 브랜치로 이동할 수 있습니다.
+
+**제거한 패턴**: `매우 유용한` (ko-content #4 promotional adjective), `본 명령어를 활용함으로써` (ko-style noun-heavy formal connector), `~할 수 있게 됩니다` (ko-structure #25 inflated future-tense). 튜토리얼이 명령을 *언제* 쓰는지 알려 주도록 사용 맥락("커밋하기 애매한 수정이 있을 때")을 추가했습니다.
+
+## Korean: 1인칭 회고 — abstract metaphor → sensory detail
+
+**Before**
+
+> 처음 코드 리뷰를 받았던 날을 떠올리면 여전히 마음 한구석이 묘해지는 것을 느낀다. 선배의 피드백 한 줄 한 줄이 마치 거대한 산처럼 다가왔으며, 그 순간은 개발자로서의 성장에 있어 잊을 수 없는 의미 있는 전환점이었다고 표현할 수 있을 것이다.
+
+**After**
+
+> 처음 코드 리뷰를 받던 날이 아직도 가끔 떠오른다. 선배가 남긴 피드백은 한 줄씩 읽을 때마다 이상하게 크게 느껴졌다. 모니터 앞에서 댓글을 하나씩 열어보던 장면이 선명하다. 손은 마우스 위에 있었고, 머릿속은 자꾸 하얘졌다. 지금 생각하면 그날은 대단한 사건이라기보다, 내가 처음으로 내 코드를 남의 눈으로 본 날에 가까웠다.
+
+**제거한 패턴**: `마치 거대한 산처럼` (ko-content abstract metaphor), `의미 있는 전환점이었다고 표현할 수 있을 것이다` (ko-structure #25 hedge stack + ko-content inflated significance). 구체적인 신체 디테일(`손은 마우스 위에`, `머릿속은 자꾸 하얘졌다`)로 바꿨습니다. narrative profile의 `concrete-emotions: amplify` 설정입니다.
+
+## Korean: SNS marketing — viral-hook signals
+
+**Before**
+
+> GitHub 역사상 이런 속도는 없었다. 단 60일 만에 별 25만 개. OpenClaw라는 도구가 세운 기록임. 광고 한 번 안 하고 전 세계 개발자들이 미친 듯이 달려든 이유가 뭘까.
+
+**After**
+
+> GitHub에서 이런 속도는 거의 못 봤다. 60일 만에 별 25만 개. OpenClaw가 만든 기록이다. 광고로 뜬 게 아니다. 개발자들이 새벽 3시에 버그 잡다가 짜증 나던 부분을 정확히 긁었다.
+
+**제거한 패턴**: `역사상 ... 없었다` (ko-viral-hook #3 source-skipping authority claim), `미친 듯이 달려든` (ko-viral-hook #5 hyperbolic engagement lexicon), `이유가 뭘까` (ko-viral-hook #2 clickbait mystery close → 구체적 설명으로 해결). viral-hook pack은 **score-only**지만, content/style pack이 적용된 regular rewrite에서도 모델이 이런 신호를 다시 잡아냅니다.
+
+## English: chatbot register
+
+**Before**
+
+> I'd be happy to help you understand Git stash! That's a great question. Git stash is a very useful command that allows you to temporarily save your changes. Let me know if you have any other questions!
+
+**After**
+
+> Git stash temporarily saves your in-progress changes so you can switch branches without committing or losing them. It's most useful when a fix or quick task pulls you off the work you're already doing.
+
+**제거한 패턴**: `I'd be happy to help` + `That's a great question` (en-communication #19 chatbot expressions, #21 sycophancy), `very useful` (en-content promotional adjective), `Let me know if you have any other questions` (en-communication closing politeness). chat affect를 걷어내고 실제 답변만 남겼습니다.
+
+## English: viral-hook authority claim
+
+**Before**
+
+> The fastest growth GitHub has ever seen — devs around the world are absolutely losing their minds. Why is everyone flocking to OpenClaw without any marketing?
+
+**After**
+
+> OpenClaw hit 250K stars in 60 days with no paid promotion. The popularity didn't come from marketing — it came from one shipped command that replaces a few hours of cluster setup. NVIDIA has since picked it up, which makes the timing easier to read.
+
+**제거한 패턴**: `the fastest GitHub has ever seen` (en-viral-hook #3 source-skipping authority claim), `absolutely losing their minds` (en-viral-hook #5 hyperbolic lexicon), `Why is everyone ... without any marketing?` (en-viral-hook #2 clickbait mystery close). 근거 없는 절대 표현을 구체적인 숫자와 확인 가능한 보강 사실로 바꿨습니다. 위 Korean SNS 예시처럼 viral-hook은 score-only이며, rewrite는 인접한 content/style pattern을 통해 이를 줄입니다.
+
+## 갤러리 추가 자료
+
+이 페이지는 표준 짧은 예시를 보여 줍니다. repo에는 복사해서 볼 수 있는 더 긴 fixture와 case study도 있습니다.
+
+- **`examples/short/`** — 네 개의 짧은 Korean fixture(marketing, tutorial, essay, email)와 짝을 이루는 `*-rewritten.md` 파일.
+- **`examples/genres/`** — 세 개의 긴 Korean genre(technical, academic, narrative)와 짝을 이루는 rewrite.
+- **`examples/tones/`** — 같은 입력을 여섯 tone(`casual`, `professional`, `academic`, `narrative`, `marketing`, `instructional`)과 `auto`로 rewrite한 결과. 나란히 보려면 `examples/tones/RESULTS.md`를 참고하세요.
+- **`examples/viral-hook/`** — iterative improvement workflow를 다루는 case study(`case-01`부터 `case-09`): viral-hook detection, codex/claude/gemini comparison, voice profile, multi-genre validation.
+- **`examples/sample-rewritten-*.md`** — 같은 장문의 Korean SNS marketing post를 Codex / Claude / Gemini-3로 rewrite한 결과. `case-03`에서 cross-model comparison에 사용합니다.
+
+## patina가 확인하는 것
+
+- rewrite가 AI-writing pattern을 제거했나요?
+- rewrite가 원래 주장을 유지했나요?
+- rewrite가 source에 없던 내용을 추가했나요?
+- 변경을 `--audit`, `--diff`, `--score`로 검토할 수 있나요?
+
+목표는 editing quality이지 detector evasion이 아닙니다. AI detector는 잡음이 많습니다. patina는 score를 대략적인 신호로 보고, diff를 실제로 유용한 산출물로 봅니다.

package/docs/EXIT-CODES.md

@@ -0,0 +1,25 @@
+# Exit Codes
+
+patina uses stable exit codes so CI and editor integrations can distinguish content gates from setup failures.
+
+| Code | Meaning |
+|---:|---|
+| `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. |
+
+## Score gates
+
+```bash
+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.
+
+## Empty input
+
+- Piped empty or whitespace-only stdin exits `2` and prints a three-line `[patina] Error:` message.
+- In an interactive TTY, patina prompts for one-shot stdin and waits until Ctrl-D.
+- `--no-interactive` restores script-safe no-input behavior: no prompt, exit `2`.

package/docs/FAQ.md

@@ -0,0 +1,67 @@
+# FAQ
+
+New to the vocabulary? Start with the [Glossary](GLOSSARY.md) for short
+definitions of MPS, fidelity, burstiness, MATTR, modes, and other recurring
+terms.
+
+## Is patina an AI detector bypass tool?
+
+No. patina is an editing and audit tool.
+
+AI detectors are noisy, and patina does not treat any score as proof that a text was written by a human or by AI. The useful artifacts are the audit, the diff, and the meaning-preservation checks: what changed, why it changed, and whether the original claims survived.
+
+## What does "Strip the AI packaging" mean?
+
+Many model outputs use the same surface habits: inflated stakes, vague balance, benefit stacking, corporate abstractions, metronomic paragraph rhythm, and filler transitions. patina looks for those patterns and rewrites the affected passages into plainer prose.
+
+The goal is not to make a text deceptive. The goal is to remove generic model voice while keeping the actual message intact.
+
+## How does patina preserve meaning?
+
+patina extracts semantic anchors before rewriting: claims, polarity, causation, numbers, negation, and other high-risk details. After each rewrite phase, it checks whether those anchors are still present and whether their polarity stayed the same.
+
+If a rewrite weakens, deletes, or reverses an anchor, patina retries the section or rolls it back.
+
+## What is MPS?
+
+MPS means Meaning Preservation Score. It is a rewrite-side safety signal that estimates how many extracted anchors survived the edit.
+
+A high MPS does not mean the prose is perfect. It means the rewrite did not obviously drop or flip the claims patina was tracking.
+
+## What does the AI-likeness score mean?
+
+The score is a rough editing signal from 0 to 100. Lower is less AI-sounding.
+
+It is not a truth machine. The scoring formula is deterministic, but severity assignment can vary by roughly 8-10 points between model runs. Treat the range and the highlighted patterns as more important than the exact number.
+
+## How accurate is it?
+
+Current calibration reports 91% editing-hotspot recall on Korean AI text [84.0-95.4%] and 76% on HC3 English ChatGPT samples [66.7-83.3%], each with n=100 and binomial 95% CI. Human-prose false positives are tracked separately as a 13-25% point-estimate range across registers.
+
+False positives are expected, especially for encyclopedic, corporate, academic, or heavily edited prose. patina is meant to help edit suspicious passages, not to accuse a writer.
+
+See [ETHICS.md](ETHICS.md) for the intended-use position statement.
+
+## Does it work without an API key?
+
+Yes, if you already have the Codex CLI installed and logged in. The installer can wire patina into Codex CLI as a backend, so no separate API key is required for that path.
+
+Other providers can be configured through the documented backend and provider settings.
+
+## Does it only work in Claude Code?
+
+No. patina runs as a skill for Claude Code, Codex CLI, Cursor, and OpenCode, and it also works as a standalone Node.js CLI.
+
+## Which languages are supported?
+
+Korean, English, Chinese, and Japanese are supported. Pattern packs are auto-discovered by language prefix, so new languages can be added by contributing new pattern files.
+
+## Can I add my own writing style or patterns?
+
+Yes. Use custom profiles for voice preferences and custom pattern packs for local rules. The repo keeps built-in patterns separate from user customizations.
+
+## What should contributors start with?
+
+The easiest contributions are small, evidence-backed examples: a before/after pair, a false positive case, a missing AI-writing pattern, or a language-specific phrase that keeps appearing in model output.
+
+Good pattern contributions should include both a failing example and a successful rewrite.