patina-cli 3.11.0 → 4.0.0

package/docs/benchmarks/register-stratified-latest.json

@@ -0,0 +1,164 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-05-21T16:24:01.336Z",
+  "input": "artifacts/rebaseline-2025/human-controls.public.jsonl",
+  "targets": {
+    "protocolPerLanguageClassRegister": 25,
+    "claimPerCell": 100,
+    "claimLanguages": 2,
+    "claimGeneratorFamilies": 3
+  },
+  "totalRecords": 250,
+  "byLanguage": {
+    "ko": 250
+  },
+  "byClass": {
+    "natural-human": 250
+  },
+  "byRegister": {
+    "chat-update": 50,
+    "blog": 50,
+    "technical-how-to": 50,
+    "academic-summary": 50,
+    "product-doc": 50
+  },
+  "byModelFamily": {
+    "human-reference": 250
+  },
+  "protocolCoverage": {
+    "totalCells": 80,
+    "populatedCells": 5,
+    "emptyCells": 75,
+    "cellsMeetingTarget": 5,
+    "underfilledCells": []
+  },
+  "claimGate": {
+    "ready": false,
+    "blockers": [
+      "positive corpus has 0/2 languages with n≥100",
+      "positive corpus has 0/3 generator families with n≥100",
+      "natural/human corpus has 1/2 languages with n≥100"
+    ],
+    "qualifiedPositiveCells": [],
+    "qualifiedNaturalCells": [
+      {
+        "key": "ko",
+        "count": 250
+      }
+    ]
+  },
+  "metrics": {
+    "tp": 0,
+    "fp": 42,
+    "fn": 0,
+    "tn": 208,
+    "total": 250,
+    "accuracy": 0.832,
+    "precision": 0,
+    "recall": 0,
+    "f1": 0,
+    "falsePositiveRate": 0.168,
+    "falseNegativeRate": 0,
+    "accuracyCi": {
+      "low": 0.781,
+      "high": 0.873,
+      "method": "Wilson score interval, 95%"
+    }
+  },
+  "metricsByRegister": {
+    "academic-summary": {
+      "tp": 0,
+      "fp": 7,
+      "fn": 0,
+      "tn": 43,
+      "total": 50,
+      "accuracy": 0.86,
+      "precision": 0,
+      "recall": 0,
+      "f1": 0,
+      "falsePositiveRate": 0.14,
+      "falseNegativeRate": 0,
+      "accuracyCi": {
+        "low": 0.738,
+        "high": 0.93,
+        "method": "Wilson score interval, 95%"
+      }
+    },
+    "blog": {
+      "tp": 0,
+      "fp": 10,
+      "fn": 0,
+      "tn": 40,
+      "total": 50,
+      "accuracy": 0.8,
+      "precision": 0,
+      "recall": 0,
+      "f1": 0,
+      "falsePositiveRate": 0.2,
+      "falseNegativeRate": 0,
+      "accuracyCi": {
+        "low": 0.67,
+        "high": 0.888,
+        "method": "Wilson score interval, 95%"
+      }
+    },
+    "chat-update": {
+      "tp": 0,
+      "fp": 2,
+      "fn": 0,
+      "tn": 48,
+      "total": 50,
+      "accuracy": 0.96,
+      "precision": 0,
+      "recall": 0,
+      "f1": 0,
+      "falsePositiveRate": 0.04,
+      "falseNegativeRate": 0,
+      "accuracyCi": {
+        "low": 0.865,
+        "high": 0.989,
+        "method": "Wilson score interval, 95%"
+      }
+    },
+    "product-doc": {
+      "tp": 0,
+      "fp": 6,
+      "fn": 0,
+      "tn": 44,
+      "total": 50,
+      "accuracy": 0.88,
+      "precision": 0,
+      "recall": 0,
+      "f1": 0,
+      "falsePositiveRate": 0.12,
+      "falseNegativeRate": 0,
+      "accuracyCi": {
+        "low": 0.762,
+        "high": 0.944,
+        "method": "Wilson score interval, 95%"
+      }
+    },
+    "technical-how-to": {
+      "tp": 0,
+      "fp": 17,
+      "fn": 0,
+      "tn": 33,
+      "total": 50,
+      "accuracy": 0.66,
+      "precision": 0,
+      "recall": 0,
+      "f1": 0,
+      "falsePositiveRate": 0.34,
+      "falseNegativeRate": 0,
+      "accuracyCi": {
+        "low": 0.522,
+        "high": 0.776,
+        "method": "Wilson score interval, 95%"
+      }
+    }
+  },
+  "validation": {
+    "errors": [],
+    "warnings": []
+  }
+}

package/docs/benchmarks/register-stratified-latest.md

@@ -0,0 +1,99 @@
+# Rebaseline Manifest Summary
+
+- Generated at: 2026-05-21T16:24:01.336Z
+- Input: `artifacts/rebaseline-2025/human-controls.public.jsonl`
+- Records: 250
+- Protocol target: 25 samples per language × class × register cell
+- Public claim target: 100 samples per claim cell, 2+ languages, 3+ generator families
+
+## Validation
+
+Validation: **PASS**
+
+## Coverage snapshot
+
+### By language
+
+| value | n |
+|---|---:|
+| ko | 250 |
+| en | 0 |
+| zh | 0 |
+| ja | 0 |
+
+### By class
+
+| value | n |
+|---|---:|
+| ai-like | 0 |
+| natural-human | 250 |
+| lightly-edited-ai | 0 |
+| heavily-edited-ai | 0 |
+
+### By register
+
+| value | n |
+|---|---:|
+| blog | 50 |
+| academic-summary | 50 |
+| product-doc | 50 |
+| chat-update | 50 |
+| technical-how-to | 50 |
+
+### By model family
+
+| value | n |
+|---|---:|
+| gpt-family | 0 |
+| claude-family | 0 |
+| gemini-family | 0 |
+| open-weight | 0 |
+| human-reference | 250 |
+
+## Protocol matrix
+
+- Populated language × class × register cells: 5/80
+- Cells meeting 25+ samples: 5
+- Empty cells: 75
+- Underfilled populated cells: 0
+
+No underfilled populated protocol cells.
+
+## Public performance claim gate
+
+Public performance claim: **BLOCKED**
+
+| blocker |
+|---|
+| positive corpus has 0/2 languages with n≥100 |
+| positive corpus has 0/3 generator families with n≥100 |
+| natural/human corpus has 1/2 languages with n≥100 |
+
+| claim-gate count | value |
+|---|---:|
+| qualified positive cells (language × generator family, n≥100) | 0 |
+| qualified natural-language cells (language, n≥100) | 1 |
+| outcome rows with expected/predicted labels | 250 |
+
+## Outcome metrics
+
+| metric | value |
+|---|---:|
+| accuracy | 83.2% |
+| accuracy CI | 78.1%–87.3% |
+| precision | 0.0% |
+| recall | 0.0% |
+| F1 | 0.000 |
+| false positive rate | 16.8% |
+| false negative rate | 0.0% |
+| TP/FP/FN/TN | 0/42/0/208 |
+
+### By register
+
+| register | n | FP rate | FN rate | TP/FP/FN/TN |
+|---|---:|---:|---:|---:|
+| blog | 50 | 20.0% | 0.0% | 0/10/0/40 |
+| academic-summary | 50 | 14.0% | 0.0% | 0/7/0/43 |
+| product-doc | 50 | 12.0% | 0.0% | 0/6/0/44 |
+| chat-update | 50 | 4.0% | 0.0% | 0/2/0/48 |
+| technical-how-to | 50 | 34.0% | 0.0% | 0/17/0/33 |

package/docs/benchmarks/register-stratified.md

@@ -0,0 +1,43 @@
+# Korean register-stratified false-positive plan
+
+Status: KO diagnostic bands calibrated; public performance claims still blocked on the wider rebaseline gate.
+Related issues: #157, #303, #155.
+
+Korean registers do not share one false-positive profile. This page keeps threshold work tied to both register false positives and positive AI-like catch rates.
+
+## Current tracked pilot
+
+`artifacts/rebaseline-2025/human-controls.public.jsonl` currently contains 250 metadata/hash-only Korean human-control rows. The generated snapshot lives at `docs/benchmarks/register-stratified-latest.md`.
+
+| register | current rows | target rows |
+|---|---:|---:|
+| academic / 종결-다 | 50 | 50 |
+| product / technical docs | 50 | 50 |
+| policy / notice / chat update | 50 | 50 |
+| blog / community | 50 | 50 |
+| technical how-to | 50 | 50 |
+
+The current pilot has 42 predicted-hot rows and 208 predicted-cold rows, for a 16.8% point false-positive rate on the hash-only human-control sample. The split is uneven by register: chat/update is 4.0%, product-doc is 12.0%, academic-summary is 14.0%, blog is 20.0%, and technical-how-to is 34.0%.
+
+That register spread is the main threshold-drift finding: a single Korean threshold would mostly be tuned by technical how-to false positives, while chat/update already looks conservative. Treat this as false-positive evidence for #157, not as a public performance claim.
+
+## Gate before threshold changes
+
+Do not loosen or tighten Korean scoring thresholds until all gates below pass.
+
+| gate | requirement | status |
+|---|---|---|
+| coverage | at least five registers have n≥50 reviewed human-control rows each | met: 5/5 registers have n=50 |
+| privacy | no raw private or no-redistribution text is committed | met: public rows are hash-only |
+| review | each row has source review notes or a license field | met: rows carry source/license notes |
+| reporting | the report shows false positives by register, not only in aggregate | met: see `register-stratified-latest.md` |
+| positive controls | threshold change is checked against AI-like and edited-AI rows | met for KO diagnostics via private KatFish aggregate; edited-AI still belongs to #155 |
+| verification | any changed threshold is tested against `npm run benchmark` and `npm run benchmark:rebaseline` | met for the KO diagnostic band update |
+
+## Recommendation
+
+The KO diagnostic band update uses the KatFish aggregate report, not a public headline claim. It improves KatFish catch rate by +15.9 pp versus Patina without KO diagnostics while keeping the 250-row public-web human-control FP count unchanged at 42/250. Keep broader 2025+ public claims under #155 until multilingual, multi-family claim cells exist.
+
+## Why this matters
+
+The Korean diagnostic layer already adds spacing, comma, and suffix-class proxies. Those signals can help with generated boilerplate, but they can also flag formal Korean if the register mix is wrong. Register splits protect person-written formal prose before a threshold change ships.

package/docs/integrations/github-action.md

@@ -2,8 +2,6 @@
 
 Patina's standalone Action repository is [`devswha/patina-action`](https://github.com/devswha/patina-action). It runs pull request prose review without a live model call, leaves a sticky comment with file-level hotspot scores, and can fail above an optional score threshold.
 
-> The Action defaults to `patina-cli@latest`, so the `@v1` tag should be cut after the npm publish in #203. Until then, pre-release workflows can use `@main` with `patina-package: github:devswha/patina`.
-
 ```yaml
 name: Patina prose score
 
@@ -23,24 +21,58 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: devswha/patina-action@main # replace with @v1 after npm publish + action tag
+      - uses: devswha/patina-action@v1
         with:
-          patina-package: github:devswha/patina # remove after patina-cli@latest is on npm
-          report-threshold: 30
+          score-threshold: 30
           lang: auto
           comment: true
 ```
 
-Once `patina-cli` is on npm and `devswha/patina-action@v1` is tagged, the stable form is:
+## README score badge
+
+Patina can also produce a [Shields.io endpoint](https://shields.io/endpoint) JSON file from the same deterministic prose score used by the PR comment. The endpoint reports the highest scored file (`maxScore`) as an editing-hotspot percentage, not an authorship verdict.
+
+Generate the JSON locally:
+
+```bash
+npm run badge -- README.md docs/FAQ.md > patina-badge.json
+```
+
+Payload shape:
+
+```json
+{ "schemaVersion": 1, "label": "patina", "message": "25% · human-ish", "color": "brightgreen" }
+```
+
+Use it from a README once `patina-badge.json` is published on a stable branch:
+
+```md
+[![patina](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<owner>/<repo>/<badge-branch>/patina-badge.json)](https://github.com/devswha/patina)
+```
+
+For the standalone Action, set `badge-branch` to publish `patina-badge.json` after scoring:
 
 ```yaml
-- uses: actions/checkout@v6
-- uses: devswha/patina-action@v1
-  with:
-    score-threshold: 30
-    comment: true
+permissions:
+  contents: write
+  pull-requests: read
+  issues: write
+
+steps:
+  - uses: actions/checkout@v6
+  - uses: devswha/patina-action@v1
+    with:
+      badge-branch: patina-badge
 ```
 
+If you do not want a live score endpoint, use the static brand fallback instead:
+
+```md
+[![patina](https://raw.githubusercontent.com/devswha/patina/main/assets/brand/patina-badge.svg)](https://github.com/devswha/patina)
+```
+
+No badge mode performs per-visitor tracking; Shields reads a repository-owned JSON file or a static SVG.
+
 ## Inputs
 
 | Input | Default | Meaning |
@@ -52,6 +84,7 @@ Once `patina-cli` is on npm and `devswha/patina-action@v1` is tagged, the stable
 | `report-threshold` | `30` | Advisory report gate when `score-threshold` is unset. |
 | `max-files` | `50` | Maximum Markdown files to score. |
 | `comment` | `true` | Create/update a sticky PR comment. |
+| `badge-branch` | unset | Optional branch where the Action publishes `patina-badge.json` for Shields.io. Requires `contents: write`. |
 | `patina-package` | `patina-cli@latest` | npm package spec used by `npx`. |
 
 ## What it measures

package/docs/integrations/playground.md

@@ -0,0 +1,58 @@
+# Web Playground
+
+The hosted playground is the lowest-friction way to try patina before installing anything:
+
+```text
+https://patina.vibetip.help/
+```
+
+It is intentionally audit-only. The page runs deterministic string operations in the browser and shows:
+
+- a 0-100 editing-hotspot score;
+- paragraph-level burstiness, MATTR, lexicon, and Korean rhythm diagnostic signals;
+- a suspect-zone diff that highlights review zones and lexicon hits;
+- an **Open in CLI** command that copies the pasted input plus `npx patina-cli --score` / `--audit` commands.
+
+It does not rewrite text, call an LLM, proxy user API keys, or send pasted text off the page. The hosted Vercel deployment records page-view metadata with Web Analytics so maintainers can watch traffic.
+
+## Source files
+
+- App shell: [`playground/index.html`](../../playground/index.html)
+- Browser analyzer: [`playground/analyzer.js`](../../playground/analyzer.js)
+- DOM wiring: [`playground/app.js`](../../playground/app.js)
+- Generated lexicons: [`playground/data/lexicons.js`](../../playground/data/lexicons.js)
+- Vercel routes: [`vercel.json`](../../vercel.json)
+- Analytics shim: [`playground/analytics.js`](../../playground/analytics.js)
+- OG image: [`assets/social/patina-og.svg`](../../assets/social/patina-og.svg)
+
+## Refreshing lexicon data
+
+When `lexicon/ai-*.md` changes, regenerate and check the browser bundle:
+
+```bash
+npm run playground:data
+node scripts/generate-playground-data.mjs --check
+```
+
+## Deploy notes
+
+Deploy the repository root on Vercel so the root `vercel.json` can rewrite `/` to the playground while keeping brand and social assets under `/assets/`.
+
+After a production deploy, verify that the custom domain points at the latest
+deployment and not an older manual alias:
+
+```bash
+vercel --prod --yes --scope team_66lsrwOyA36bLnIH2eoEXqry
+vercel alias set <latest-patina-*.vercel.app> patina.vibetip.help --scope team_66lsrwOyA36bLnIH2eoEXqry
+vercel inspect https://patina.vibetip.help --scope team_66lsrwOyA36bLnIH2eoEXqry
+```
+
+Smoke the live deterministic payloads:
+
+```bash
+curl -fsSL https://patina.vibetip.help/docs/benchmarks/latest.json \
+  | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{const j=JSON.parse(d); console.log(j.fixtureCount, !!j.perLanguage?.ko?.byDetector?.koDiagnostics)})"
+
+curl -fsSL https://patina.vibetip.help/analyzer.js \
+  | grep -E "DEFAULT_KO_DIAGNOSTIC_BANDS|Korean rhythm composite"
+```

package/docs/integrations/pre-commit.md

@@ -13,7 +13,7 @@ repos:
     rev: main # replace with a release tag after v1 is cut
     hooks:
       - id: patina-score
-        args: [--gate, "30", --lang, auto]
+        args: [--score-threshold, "30", --lang, auto]
 ```
 
 Run it locally:
@@ -33,7 +33,7 @@ npx husky init
 // package.json
 {
   "lint-staged": {
-    "*.{md,mdx}": "patina-score --gate 30 --lang auto"
+    "*.{md,mdx}": "patina-score --score-threshold 30 --lang auto"
   }
 }
 ```
@@ -57,7 +57,7 @@ pre-commit:
   commands:
     patina-score:
       glob: "*.{md,mdx}"
-      run: npx patina-score --gate 30 --lang auto {staged_files}
+      run: npx patina-score --score-threshold 30 --lang auto {staged_files}
 ```
 
 A repo-local Lefthook command if this repository is vendored or checked out:
@@ -67,11 +67,11 @@ pre-commit:
   commands:
     patina-score:
       glob: "*.{md,mdx}"
-      run: node scripts/precommit-score.mjs --gate 30 --lang auto {staged_files}
+      run: node scripts/precommit-score.mjs --score-threshold 30 --lang auto {staged_files}
 ```
 
 ## Tuning
 
-- `--gate 30` means fail when more than 30% of prose paragraphs in a file trip a hot signal.
+- `--score-threshold 30` means fail when more than 30% of prose paragraphs in a file trip a hot signal.
 - `--lang auto` infers language from filename and Unicode ranges; pass `ko`, `en`, `zh`, or `ja` when a repo is single-language.
 - Use this as a discussion prompt, not as an accusation. See [ETHICS.md](../ETHICS.md).

package/docs/integrations/release.md

@@ -21,8 +21,9 @@ The dry run verifies:
 Publishing the npm packages is intended for `v*.*.*` tags:
 
 ```bash
-git tag v3.11.0
-git push origin v3.11.0
+VERSION=v4.0.0
+git tag "$VERSION"
+git push origin "$VERSION"
 ```
 
 Required secret:
@@ -39,5 +40,6 @@ the container distribution issue is still open. Maintainers can run the
 experimental image path manually after npm verification:
 
 ```bash
-gh workflow run release.yml --ref v3.11.0 -f publish=false -f publish_ghcr=true
+VERSION=v4.0.0
+gh workflow run release.yml --ref "$VERSION" -f publish=false -f publish_ghcr=true
 ```

package/docs/integrations/static-sites.md

@@ -0,0 +1,83 @@
+# Static-site Generator Stencils
+
+These recipes wire Patina into build-time checks for Markdown sites. They are intentionally in-repo examples, not standalone npm packages.
+
+All examples assume one of these authentication paths:
+
+```bash
+export PATINA_API_KEY=...
+# or tell the example scripts to use a logged-in local CLI backend:
+export PATINA_BACKEND=codex-cli
+# optional: use an installed binary instead of `npx --yes patina-cli`
+export PATINA_BIN=patina
+```
+
+For CI, prefer score gates over automatic rewrites:
+
+```bash
+patina --lang en --backend codex-cli --score --exit-on 30 docs/**/*.md
+```
+
+## Hosted playground
+
+The public audit-only playground is documented in [playground.md](playground.md) and targets [patina.vibetip.help](https://patina.vibetip.help/). It is a no-build static Vercel app, not a rewrite service.
+
+## Hugo: JSON data + shortcode
+
+Use a small Node helper to score content and write a Hugo data file:
+
+```bash
+node examples/integrations/hugo/scripts/patina-scores.mjs content/posts data/patina-scores.json
+```
+
+Then render a badge in a template or post body:
+
+```go-html-template
+{{</* patina-score path="content/posts/launch.md" */>}}
+```
+
+Files:
+
+- [`examples/integrations/hugo/scripts/patina-scores.mjs`](../../examples/integrations/hugo/scripts/patina-scores.mjs)
+- [`examples/integrations/hugo/layouts/shortcodes/patina-score.html`](../../examples/integrations/hugo/layouts/shortcodes/patina-score.html)
+
+## Astro: `astro:build:start` hook
+
+Astro integrations can fail the build before pages render. The example integration scans Markdown under `src/content` and runs `patina --score --exit-on 30`.
+
+```js
+// astro.config.mjs
+import patinaAudit from './examples/integrations/astro/patina-audit-integration.mjs';
+
+export default {
+  integrations: [patinaAudit({ contentDir: 'src/content', lang: 'en', threshold: 30 })],
+};
+```
+
+File: [`examples/integrations/astro/patina-audit-integration.mjs`](../../examples/integrations/astro/patina-audit-integration.mjs)
+
+## Next.js MDX: remark warning plugin
+
+The Next.js example exports a remark plugin that scores the Markdown text during MDX compilation and emits a VFile warning when the threshold is exceeded. Teams can decide whether warnings fail CI.
+
+```js
+// next.config.mjs
+import createMDX from '@next/mdx';
+import patinaRemark from './examples/integrations/nextjs/remark-patina-score.mjs';
+
+const withMDX = createMDX({
+  options: {
+    remarkPlugins: [[patinaRemark, { lang: 'en', threshold: 30 }]],
+  },
+});
+
+export default withMDX({ pageExtensions: ['js', 'jsx', 'md', 'mdx'] });
+```
+
+File: [`examples/integrations/nextjs/remark-patina-score.mjs`](../../examples/integrations/nextjs/remark-patina-score.mjs)
+
+## Guardrails
+
+- Keep v1 in-repo; do not publish a package until at least one real site uses the stencil.
+- Do not send private drafts to third-party backends from CI unless the project owner opted in.
+- Use `--exit-on` for gating and leave rewrites as a local author action.