patina-cli 3.11.0

package/docs/FAQ_KR.md

@@ -0,0 +1,65 @@
+# FAQ
+
+용어가 낯설다면 먼저 [Glossary](GLOSSARY.md)를 보세요. MPS, fidelity, burstiness, MATTR, 모드 등 반복해서 나오는 용어를 짧게 설명합니다.
+
+## patina는 AI detector 우회 도구인가요?
+
+아닙니다. patina는 편집과 audit을 위한 도구입니다.
+
+AI detector는 잡음이 많습니다. patina는 어떤 score도 텍스트가 사람이나 AI가 썼다는 증거로 보지 않습니다. 유용한 산출물은 audit, diff, meaning-preservation check입니다. 무엇이 바뀌었는지, 왜 바뀌었는지, 원래 주장이 살아남았는지를 보는 데 씁니다.
+
+## "Strip the AI packaging"은 무슨 뜻인가요?
+
+모델 출력에는 비슷한 겉습관이 자주 나타납니다. 부풀린 중요도, 흐릿한 균형감, 장점 나열, 기업식 추상어, 박자감이 일정한 문단, filler transition 같은 것들입니다. patina는 이런 패턴을 찾아 해당 구간을 더 담백한 문장으로 바꿉니다.
+
+목표는 텍스트를 속이기 좋게 만드는 것이 아닙니다. 실제 메시지는 유지하면서 일반적인 모델 말투를 걷어내는 것입니다.
+
+## patina는 의미를 어떻게 보존하나요?
+
+patina는 rewrite 전에 semantic anchor를 뽑습니다. 주장, 극성, 인과, 숫자, 부정, 그 밖의 위험도가 높은 세부 정보를 추적합니다. 각 rewrite 단계 뒤에는 그 anchor가 여전히 있는지, 극성이 그대로인지 확인합니다.
+
+rewrite가 anchor를 약화하거나 삭제하거나 뒤집으면, patina는 해당 구간을 다시 시도하거나 되돌립니다.
+
+## MPS가 무엇인가요?
+
+MPS는 Meaning Preservation Score입니다. rewrite 쪽 안전 신호로, 추출한 anchor 중 얼마나 많이 편집 후에도 살아남았는지 추정합니다.
+
+MPS가 높다고 해서 문장이 완벽하다는 뜻은 아닙니다. patina가 추적하던 주장을 rewrite가 명백히 떨어뜨리거나 뒤집지 않았다는 뜻입니다.
+
+## AI-likeness score는 무엇을 뜻하나요?
+
+score는 0부터 100까지의 대략적인 편집 신호입니다. 낮을수록 AI처럼 덜 들립니다.
+
+이 값은 진실 판정기가 아닙니다. scoring formula는 deterministic이지만 severity assignment는 모델 실행 사이에 대략 8-10점 정도 달라질 수 있습니다. 정확한 숫자보다 범위와 하이라이트된 패턴을 더 중요하게 보세요.
+
+## 정확도는 어느 정도인가요?
+
+현재 calibration은 한국어 AI 텍스트에서 91% editing-hotspot recall [84.0-95.4%], HC3 English ChatGPT 샘플에서 76% [66.7-83.3%]를 보고합니다. 각각 n=100, binomial 95% CI입니다. 사람 글 오탐은 문체별 13-25% point-estimate range로 따로 추적합니다.
+
+오탐은 예상되는 일입니다. 특히 백과사전식, 기업 문서, 학술 문서, 강하게 편집된 글에서 그렇습니다. patina는 수상한 구간을 편집하는 데 쓰는 도구이지, 작성자를 비난하는 도구가 아닙니다.
+
+의도한 사용 입장은 [ETHICS.md](ETHICS.md)를 참고하세요.
+
+## API key 없이도 동작하나요?
+
+네. 이미 Codex CLI를 설치하고 로그인했다면 가능합니다. installer는 patina를 Codex CLI backend에 연결할 수 있으므로 이 경로에서는 별도 API key가 필요하지 않습니다.
+
+다른 provider는 문서화된 backend/provider 설정으로 구성할 수 있습니다.
+
+## Claude Code에서만 동작하나요?
+
+아닙니다. patina는 Claude Code, Codex CLI, Cursor, OpenCode용 skill로 동작하고, standalone Node.js CLI로도 사용할 수 있습니다.
+
+## 어떤 언어를 지원하나요?
+
+한국어, 영어, 중국어, 일본어를 지원합니다. 패턴 팩은 언어 접두사로 자동 탐색되므로 새 언어는 새 패턴 파일을 기여해 추가할 수 있습니다.
+
+## 내 문체나 패턴을 추가할 수 있나요?
+
+네. voice preference에는 custom profile을, 로컬 규칙에는 custom pattern pack을 사용하세요. repo는 built-in pattern과 사용자 custom 설정을 분리합니다.
+
+## 기여자는 무엇부터 시작하면 좋나요?
+
+가장 쉬운 기여는 근거가 있는 작은 예시입니다. before/after 쌍, 오탐 사례, 빠진 AI-writing pattern, 모델 출력에 반복해서 보이는 언어별 표현이 좋습니다.
+
+좋은 패턴 기여에는 실패 예시와 성공적인 rewrite가 둘 다 있어야 합니다.

package/docs/FLAG-PARITY.md

@@ -0,0 +1,53 @@
+# CLI / Skill Flag Parity
+
+Basis: local checkout `2e1fc04` plus `node bin/patina.js --help`, `SKILL.md`, and `patina-max/SKILL.md` reviewed on 2026-05-20. This table separates the standalone CLI surface from the prompt-based `/patina` and `/patina-max` skill surfaces; a missing check is not always a bug when the flag is backend-, auth-, or CLI-automation-only.
+
+| Flag / command | Standalone CLI | `/patina` (`SKILL.md`) | `/patina-max` | Notes |
+|---|:---:|:---:|:---:|---|
+| *(default rewrite)* | ✓ | ✓ | ✓ | CLI and `/patina` rewrite one candidate; `/patina-max` chooses the best candidate across models. |
+| `--diff` | ✓ | ✓ | — | Single-candidate pattern-by-pattern diff. |
+| `--audit` | ✓ | ✓ | — | Detection-only mode. |
+| `--score` | ✓ | ✓ | internal | MAX scores candidates internally rather than exposing score mode. |
+| `--gate <n>` | ✓ | — | — | CLI score-gate alias; automation-only. |
+| `--exit-on <n>` | ✓ | — | — | Preferred CLI score-gate spelling for CI. |
+| `--ouroboros` | ✓ | ✓ | documented compatible | `/patina-max` can feed its winner into the existing convergence loop when used with `/patina` behavior. |
+| `--format <markdown\|text\|json>` | ✓ | — | — | CLI output-envelope feature. |
+| `--json` | ✓ | — | — | CLI alias for `--format json`; `patina doctor --json` also exists. |
+| `--quiet` | ✓ | — | — | CLI stderr log suppression for scripts. |
+| `--json-logs` | ✓ | — | — | CLI structured stderr logs for automation. |
+| `--batch` | ✓ | ✓ | — | Multi-file CLI/skill rewrite flow. |
+| `--in-place` | ✓ | ✓ | — | Batch-only write mode. |
+| `--suffix <ext>` | ✓ | ✓ | — | Batch-only alternate output naming. |
+| `--outdir <dir>` | ✓ | ✓ | — | Batch-only output directory. |
+| `--save-run <dir>` | ✓ | — | — | CLI reproducibility manifest and outputs. |
+| `--no-interactive` | ✓ | — | — | CLI input safety for non-TTY automation. |
+| `--lang <code>` | ✓ | ✓ | ✓ | `ko`, `en`, `zh`, `ja`. |
+| `--profile <name>` | ✓ | ✓ | ✓ | Profile override. |
+| `--tone <name>` | ✓ | ✓ | — | `/patina-max` inherits profile/pattern behavior but does not expose tone parsing directly. |
+| `--model <id>` | ✓ | — | — | CLI single-backend model selection. |
+| `--models <list>` | ✓ | — | ✓ | CLI MAX mode and `/patina-max` model fanout. |
+| `--max-concurrency <n>` | ✓ | — | — | CLI HTTP MAX fanout cap; `/patina-max` uses tmux/direct dispatch instead. |
+| `--api-key <key>` | ✓ | — | — | Deprecated CLI auth escape hatch; prefer env/file. |
+| `--api-key-file <path>` | ✓ | — | — | CLI auth. |
+| `--base-url <url>` | ✓ | — | — | CLI provider/backend config. |
+| `--backend <name[,name]>` | ✓ | — | — | CLI backend selection and explicit fallback chains (`openai-http`, `codex-cli`, `claude-cli`, `gemini-cli`). |
+| `--list-backends` | ✓ | — | — | CLI diagnostics. |
+| `--provider <name>` | ✓ | — | — | CLI provider preset. |
+| `--list-providers` | ✓ | — | — | CLI diagnostics. |
+| `--config <path>` | ✓ | — | — | CLI config override. |
+| `--prompt-mode <strict\|minimal\|auto>` | ✓ | ✓ | — | User-visible v3.11 prompt loading control. |
+| `--variants <n>` | ✓ | ✓ | — | User-visible v3.11 rewrite variants; not supported with CLI MAX mode. |
+| `--allow-insecure-base-url` | ✓ | — | — | CLI network safety override. |
+| `--allow-private-base-url` | ✓ | — | — | CLI SSRF/metadata-address safety override. |
+| `-h`, `--help` | ✓ | — | — | CLI help. |
+| `-v`, `--version` | ✓ | — | — | CLI version. |
+| `patina init` | ✓ | — | — | CLI project config writer. |
+| `patina doctor` | ✓ | — | — | CLI environment diagnostic. |
+| `patina auth status/login` | ✓ | — | — | CLI authentication guidance. |
+| `--dispatch <omc\|direct>` | — | — | ✓ | `/patina-max` dispatch selection; not a standalone CLI flag. |
+
+## Audit notes
+
+- `--prompt-mode` and `--variants` are the main user-facing omissions that must be visible in `SKILL.md` as well as the CLI.
+- `--save-run`, `--max-concurrency`, auth/provider/base-url flags, and `doctor`/`auth` commands are CLI automation or transport controls; they do not map cleanly to prompt-only skills.
+- `/patina-max` intentionally exposes only the flags needed for local multi-model dispatch: language/profile, model list, and dispatch mode.

package/docs/GLOSSARY.md

@@ -0,0 +1,123 @@
+# Glossary
+
+Short definitions for recurring patina terms. Each entry links to the
+deeper reference where the term is used in context.
+
+## AI-likeness
+
+A 0-100 editing signal for how strongly a text matches patina's AI-writing
+patterns. Lower means less AI-sounding; it is not proof of authorship. See
+[the scoring overview](../core/scoring.md#ai-likeness-scoring-algorithm) and
+[the FAQ](FAQ.md#what-does-the-ai-likeness-score-mean).
+
+## Audit mode
+
+The mode that detects and reports AI-writing patterns without rewriting the
+text. Use it when you want to inspect what patina would flag before changing
+anything. See the [mode table](../README.md#modes) and [examples guide](EXAMPLES.md).
+
+## Burstiness
+
+The variation in sentence length inside a paragraph, measured with coefficient
+of variation. Very uniform sentence lengths are one signal that a paragraph may
+need closer inspection. See [Stylometry](../core/stylometry.md#4-burstiness-metric).
+
+## Diff mode
+
+The mode that shows changes pattern by pattern, making the edit auditable
+instead of a black-box paraphrase. See the [mode table](../README.md#modes)
+and [examples checklist](EXAMPLES.md#what-patina-is-checking).
+
+## Fidelity
+
+A meaning-accuracy score comparing original text with the output. Higher is
+better: it checks whether claims, facts, tone, and length stayed faithful. See
+[Fidelity Scoring](../core/scoring.md#9-fidelity-scoring--overview).
+
+## Meaning preservation
+
+The safety goal that rewritten text should keep the original claims, polarity,
+causal links, numbers, and other high-risk details. See
+[the FAQ](FAQ.md#how-does-patina-preserve-meaning) and
+[MPS overview](../core/scoring.md#14-mps-meaning-preservation-score--overview).
+
+## MATTR
+
+Moving Average Type-Token Ratio, a lexical-diversity metric that reduces the
+length bias of simple TTR. Patina uses it as one stylometry signal, with known
+language limitations. See [Stylometry](../core/stylometry.md#5-ttr-via-mattr).
+
+## Mode
+
+A CLI output path such as rewrite, audit, score, diff, or ouroboros. Modes
+control whether patina edits text, reports findings, scores text, or loops
+until quality gates are met. See the [mode table](../README.md#modes).
+
+## MPS
+
+Meaning Preservation Score. MPS checks whether extracted semantic anchors
+survive the rewrite pipeline and whether polarity is preserved. See
+[the FAQ](FAQ.md#what-is-mps) and
+[MPS scoring](../core/scoring.md#16-mps-scoring-formula).
+
+## Ouroboros mode
+
+An iterative rewrite loop that keeps trying to lower AI-likeness while obeying
+meaning-preservation gates. It stops when the combined score is acceptable or
+when fidelity or MPS drops too far. See
+[Ouroboros Termination](../core/scoring.md#ouroboros-termination).
+
+## Pattern
+
+A named AI-writing signal with a fire condition, exclusion condition, problem
+description, and before/after example. Patterns are the unit patina audits and
+rewrites against. See [PATTERNS.md](PATTERNS.md).
+
+## Pattern pack
+
+A language and category file such as `patterns/en-style.md` or
+`patterns/ko-content.md`. Packs group related patterns and provide counts used
+by scoring. See [PATTERNS.md](PATTERNS.md#language-specific-patterns).
+
+## Profile
+
+A voice preset that can amplify, reduce, or suppress specific patterns for a
+use case such as blog, academic, technical, or legal writing. See
+[profile override adjustments](../core/scoring.md#5-profile-override-adjustments).
+
+## Rewrite mode
+
+The default mode that removes matched AI-writing patterns while checking that
+meaning survived the edit. See the [Quick Start](../README.md#quick-start) and
+[MPS integration points](../core/scoring.md#17-mps-integration-points).
+
+## Score mode
+
+The mode that returns a 0-100 AI-likeness score with category breakdowns and,
+when original text is available, fidelity and MPS signals. See
+[Score Interpretation](../core/scoring.md#7-score-interpretation).
+
+## Semantic anchor
+
+A meaning unit extracted before rewriting, such as a claim, negation, number,
+causal link, quantifier, or polarity marker. Anchors are later verified by MPS.
+See [MPS Anchor Verification Criteria](../core/scoring.md#15-mps-anchor-verification-criteria).
+
+## Suspect zone
+
+A paragraph or sentence group marked for closer inspection by stylometry,
+usually because burstiness, MATTR, or lexicon signals fired. See
+[the stylometry delivery format](../core/stylometry.md#9-llm-delivery-format).
+
+## Tone
+
+A named voice axis, such as casual, professional, academic, narrative,
+marketing, instructional, or auto. Tone is applied on top of pattern rewriting.
+See [Tones](../README.md#tones).
+
+## Viral hook
+
+A score-only pattern class for SNS and marketing signals such as shock numbers,
+clickbait closes, source-skipping authority claims, short-sentence stacking,
+and hyperbolic engagement language. See
+[Score-only viral hooks](PATTERNS.md#score-only-viral-hooks-v3110).