fapony 0.1.1 → 0.1.3

package/README.md

@@ -4,6 +4,8 @@
 
 # fapony
 
+[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony)
+
 **Where did your tokens go?** fapony reads the session logs Claude Code, Codex, OpenCode and ZCode
 already write, and puts them all on one yardstick — tokens, cost and time per model, per client,
 per workflow. Nothing to instrument, no per-project setup, no waiting for data to accumulate: it
@@ -41,8 +43,8 @@ which kind of task" becomes a data question instead of a vibe. On top of measure
 claims against git facts: handoff conformance, allowlisted evidence, a 6-grade verdict — with
 everything the agent claimed but couldn't prove marked as such.
 
-**What that question looks like answered, from one project's own ledger (52 graded `code`-regime
-runs, `fapony stats --mode verdict --regime code`):**
+**What that question looks like answered, from one project's own ledger — the top of the `n≥5`
+frontier (`fapony stats --mode verdict --regime code`):**
 
 | model | tokens/pass | quality | n |
 |---|---|---|---|
@@ -56,7 +58,7 @@ on you to hold: work isn't randomly assigned to models, so a gap this size is a
 controlled trial — you likely route easy tasks to the cheap model already. `n≥5` is fapony's own
 floor before a model counts toward the frontier at all; below that it's a data point, not a pick.
 
-**The reason to keep it running is the third layer: knowledge accumulation.** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: which model earns its keep on which kind of work **in this project**, at what token cost, graded by whoever reviewed it. Every verdict carries a `regime` (`code` / `fix` / `review` / `plan` / `inquiry` / `test`), and runs split by whether there was a plan at all — so "does planning beat diving in, and for which model" is a table, not an argument. Session logs have the tokens but no grades; benchmarks have grades but not your codebase. fapony is the one layer that holds both, because it's the one every client reports into.
+**The reason to keep it running is the third layer: knowledge accumulation.** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: which model earns its keep on which kind of work **in this project**, at what token cost, graded by whoever reviewed it. Every verdict carries a `regime` (`code` / `fix` / `review` / `plan` / `inquiry` / `test`), and runs split by whether there was a plan at all — so "does planning beat diving in, and for which model" is a table, not an argument.
 
 Three tiers, deliberately: **measurement ships today** and needs no per-project setup — raw facts nobody can call unfair. **Verification is the sharper edge** but stays beta until its evidence layer is hardened; fapony doesn't control your agent's flow, so it never promises "verified" as a headline. **Knowledge accumulation is the compounding one** — it's worthless on run 1 and gets more useful every run after, which is exactly why it's the layer competitors can't clone by copying a feature list.
 
@@ -67,8 +69,7 @@ Adopting it doesn't change your workflow. There is no loop to join and no framew
 Stated up front, because the gap between these two things is where most tooling oversells:
 
 - **It does not run your test suite.** The evidence collector runs an allowlist *you* write in
-  `.fapony/evidence.json`, and never a command an agent proposes. No allowlist, no evidence — and
-  the report says `not_run` rather than staying quiet.
+  `.fapony/evidence.json`, and never a command an agent proposes. No allowlist, no evidence.
 - **It does not judge your code.** `verdict_submit` *stores* a verdict; a human or a reviewing
   agent supplies it. fapony is the ledger, not the judge.
 - **`handoff_check` checks conformance, not correctness.** It verifies that what the agent claimed
@@ -81,15 +82,15 @@ Stated up front, because the gap between these two things is where most tooling
   reviews and files the verdict, the grade lands on the reviewer. Reports label it `inferred`;
   read it as such.
 - **The knowledge layer is empty on run 1.** It is worth something around run 5 and more every run
-  after. That is the trade for it being the layer nobody can clone from a feature list.
+  after.
 
 ## Quick start (MCP)
 
 ```bash
 # 1. Install (needs Bun — https://bun.sh)
-git clone https://github.com/kire21b/fapony.git && cd fapony
-bun install
-bun link            # puts `fapony` on your PATH; or run via `bun fapony.ts`
+npm install -g fapony       # or: bun add -g fapony
+#    from source instead:
+#    git clone https://github.com/kire21b/fapony.git && cd fapony && bun install && bun link
 #    note: `bun link` claims the global `fapony` bin by package name, not path — running it
 #    from a second checkout silently repoints the command there. Re-run it in the one you want.
 
@@ -112,14 +113,7 @@ fapony usage-web                          # dashboard; re-run the scans to refre
 
 # 4. Verify (optional, per project) — scaffold the evidence allowlist
 fapony init /path/to/your-worktree
-#    .fapony/evidence.json lists the commands the evidence collector may run —
-#    edit the placeholder cmds to your real test/typecheck commands
-#    commit it: the allowlist is a security boundary your whole team shares.
-#    If your .gitignore ignores .fapony/ wholesale, re-include it (dir before file):
-#      **/.fapony/*
-#      !**/.fapony/evidence.json
-#    Monorepo: give an app its own apps/<app>/.fapony/evidence.json and reports whose
-#    changed files all sit under that app use it; anything else uses the root one.
+#    edit .fapony/evidence.json to your real test/typecheck commands, then commit it
 ```
 
 With `.fapony/evidence.json` in place, any graded run can be replayed as a report. This one is
@@ -135,6 +129,8 @@ You get one report: git facts (files, commits, branch), handoff conformance (cla
 
 Sections that have nothing to report say so (`not_run`, `unavailable`) rather than disappearing — a report with no evidence must not read like a report that passed.
 
+Two details for the allowlist once it is under version control. If your `.gitignore` ignores `.fapony/` wholesale, re-include the file (dir before file): `**/.fapony/*`, then `!**/.fapony/evidence.json`. In a monorepo, give an app its own `apps/<app>/.fapony/evidence.json` — reports whose changed files all sit under that app use it; anything else uses the root one.
+
 Two things worth knowing about the report header and budget:
 
 - **`server_sha`** — every report is stamped with the git SHA of the fapony code that produced it, read once at server start. MCP servers are long-lived: after you edit fapony and don't restart the client, reports keep coming from the old build. Compare the stamp against `git log -1` in the fapony repo; if they differ, reconnect the server before trusting the result.
@@ -199,14 +195,6 @@ ungraded. It never picks the grade; it cannot see whether the work held up.
 
 ### The 6 tools
 
-```
-discover: plan_list (plans grouped by state, joined with their run history)
-measure:  fapony_stats ── fapony_usage
-verify:   verdict_submit
-recall:   project_health_context (what failed in these files before — optional, never required)
-          mem_find (what was ever decided about these files — reads the project's mem log)
-```
-
 | Tool | Tier | Purpose |
 |------|------|---------|
 | `plan_list` | discover | Plan files grouped by state — active / blocked / untouched / superseded / trackers — with a progress tally and each one's run history. Not a raw `ls`; see [Plans your agent can answer questions about](#plans-your-agent-can-answer-questions-about) |
@@ -218,7 +206,7 @@ recall:   project_health_context (what failed in these files before — optional
 
 The handoff/report family is CLI-only — the schemas cost every session of every client and no skill called them. `fapony report <run-id>` prints the full report for a run (facts + handoff conformance + evidence + verdict); `fapony report-web [file]` renders it as a static HTML page (overwrites `file` on every call — safe to reuse the same path). Run `bun run overview` for a one-shot shortcut that writes it to `/tmp/fapony-overview.html` and opens it. `fapony usage-scan` scans session logs and writes a cache file; `fapony usage-web [port]` serves a static HTML dashboard from that cache (no live scanning). Run `fapony usage-scan` periodically to keep data fresh.
 
-Full protocol, adapter examples (bash, Python), and safety rules: [docs/mcp-handcheck.md](docs/mcp-handcheck.md).
+Full protocol, adapter examples (bash, Python), and safety rules: [docs/mcp-handcheck.md](https://github.com/kire21b/fapony/blob/main/docs/mcp-handcheck.md).
 
 ### Verdict grades
 
@@ -304,9 +292,7 @@ flowchart TD
 **The fork at the top is load-bearing.** A plan file is an artifact for work the next session has
 to pick up. Wiring, refactors and UI passes finish in one sitting and the PLAN.md gets archived
 unread — so `/plan-with-pony` declines those itself and hands over the two seed commands instead.
-`fapony review-seed --files` takes a directory as well as file names, and answers "what is in
-here, who imports it, what is untested" for about a thirtieth of the tokens reading those files
-costs. Both arms meet at the same review and the same ledger.
+Both arms meet at the same review and the same ledger.
 
 **The dotted edges are the whole point.** Verdicts carry `regime` and `reason_code`, so the
 ledger can answer the one question no single client can: *in this project, which model is worth
@@ -345,7 +331,7 @@ cat skill/plan-with-pony/SKILL.md | opencode run  # OpenCode
 cat skill/plan-with-pony/SKILL.md | <your-agent>  # anything that reads stdin
 ```
 
-Example plans produced by it live in [examples/](examples/).
+Example plans produced by it live in [examples/](https://github.com/kire21b/fapony/tree/main/examples).
 
 ### Plans your agent can answer questions about
 
@@ -404,7 +390,7 @@ The layout, and why archiving is a plain `git mv`:
 Ship dates live in the plan's own header (`> ✅ **shipped 2026-09-13** (a1b2c3)`), not in the
 filename — `grep -h shipped .fapony/done/*.md | sort` answers "what landed when" without paying
 to rewrite every inbound link on every ship. Example plans, including an un-annotated one and an
-archived one: [examples/](examples/).
+archived one: [examples/](https://github.com/kire21b/fapony/tree/main/examples).
 
 ## CLI
 
@@ -430,13 +416,13 @@ fapony install --platform <name>          # force a specific client (bypasses de
 fapony install --dry-run                  # show what would happen without writing files
 fapony setup                             # interactive wizard: config + scaffold in one step
 fapony update                            # self-update via git pull
-fapony telemetry show|send               # opt-in only, default off — see TELEMETRY.md
+fapony telemetry show|send               # opt-in only, default off — see https://github.com/kire21b/fapony/blob/main/TELEMETRY.md
 fapony test                              # self-check
 ```
 
 ## Config
 
-`fapony.config.json` lives in the fapony checkout and is gitignored (it's per-machine). Copy [fapony.config.example.json](fapony.config.example.json) for a complete working reference; every section is optional with sane defaults. Key fields:
+`fapony.config.json` lives in the fapony checkout and is gitignored (it's per-machine). Copy [fapony.config.example.json](https://github.com/kire21b/fapony/blob/main/fapony.config.example.json) for a complete working reference; every section is optional with sane defaults. Key fields:
 
 - `worktrees` — name → absolute path mapping
 - `review.maxRounds` — round cap enforced by the gate
@@ -444,7 +430,7 @@ fapony test                              # self-check
 - `paths` (`planDir`/`doneDir`/`specDir`/`memoryEntry`/`stateDir`) / `safety` — directory layout and the dangerous-command deny-list
 - `usageWeb` — optional `{ port, hostname }` for `fapony usage-web` server defaults. Run `fapony usage-scan` first to populate the cache.
 
-Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB location; default `~/.config/fapony/`). Full schema, design decisions, and edge cases are documented in [CLAUDE.md](CLAUDE.md) — this README intentionally doesn't duplicate them.
+Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB location; default `~/.config/fapony/`). Full schema, design decisions, and edge cases live with the code in the repo — this README intentionally doesn't duplicate them.
 
 ## Scope
 
@@ -453,10 +439,10 @@ Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB locat
 - Measurement: cross-run KPIs by model/grade/value, per-file risk (graded touches vs. fails) + passive usage (tokens, cost)
 - Model attribution across clients — resolved from the session log that was live when the verdict landed, so a verdict carries a model without the caller declaring one
 - Zero setup beyond install: the two habits fapony depends on ship in the MCP `initialize` response, not in your rules file
-- Verification (beta): handoff conformance, 6-grade verdicts, allowlisted evidence collector (`.fapony/evidence.json` — agent-proposed commands are never executed); reports stamped with the producing build's `server_sha`
+- Verification (beta): handoff conformance, 6-grade verdicts, allowlisted evidence collector (`.fapony/evidence.json`); reports stamped with the producing build's `server_sha`
 - Vendor-neutral executor/reviewer roles — anything that reads stdin
 - Memory integration via shell adapter, per project (configurable or default-wired)
-- Opt-in telemetry, off by default ([TELEMETRY.md](TELEMETRY.md) lists exactly what leaves the machine)
+- Opt-in telemetry, off by default ([TELEMETRY.md](https://github.com/kire21b/fapony/blob/main/TELEMETRY.md) lists exactly what leaves the machine)
 - Bun-only; run state in SQLite via `bun:sqlite` (WAL mode)
 
 **Not supported (yet):**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Measurement layer for coding agents — measure what agents do, verify what they claim. 6 MCP tools, any agent, no loop required",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
@@ -24,19 +24,21 @@
     "fapony.ts",
     "src/",
     "templates/",
-    "skill/"
+    "skill/",
+    "images/"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.12",
-    "bun-types": "^1.4.0",
-    "typescript": "^5.9.3"
-  },
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
     "test": "bun fapony.ts test",
     "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
     "check": "bun run lint && bun run typecheck && bun fapony.ts test",
+    "prepublishOnly": "bash scripts/smoke-publish.sh",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "bun-types": "^1.4.0",
+    "typescript": "^5.9.3"
   }
-}
+}

package/skill/plan-with-pony/SKILL.md

@@ -102,7 +102,7 @@ the real scope instead.
 So the seed buys you structure; the draft budget goes on judgment:
 
 - **Read the Context block, then skip to filling** — everything else is the empty template.
-- **Fill every section yourself** — §1–§6 and the TL;DR start as `_agent เติม_` slots.
+- **Fill every section yourself** — §1–§6 and the TL;DR start as `_agent fills in_` slots.
 - **Run the Phase −1 commands for facts** when the idea needs them, and put the numbers in the
   section they answer — a number you measured beats a number the seed guessed at.
 - **Signatures live in the SPEC chunks only.** Never paste them into plan §7 — link to the spec.

package/src/analyze.ts

@@ -376,7 +376,7 @@ export function diagnose(
     findings.push({
       kind: "cycle",
       file: cycle.join(" ↔ "),
-      detail: "import วนกลับหากัน — refactor ฝั่งไหนก่อนก็พังอีกฝั่ง",
+      detail: "circular imports — refactoring either side breaks the other",
       evidence: [...cycle, cycle[0]].join(" → "),
     });
   }
@@ -389,7 +389,8 @@ export function diagnose(
         findings.push({
           kind: "orphan",
           file: f,
-          detail: "ไม่มีใคร import และไม่ใช่ entry point — dead code candidate",
+          detail:
+            "no one imports it and it is not an entry point — dead code candidate",
           evidence: "0 dependents",
         });
       }
@@ -405,8 +406,8 @@ export function diagnose(
     findings.push({
       kind: "hub-untested",
       file,
-      detail: `${n} ไฟล์พึ่งอยู่ ไม่มีเทสไหน import มันเลย — แก้ตรงนี้ไม่มีอะไรจับตอนพัง`,
-      evidence: `พึ่งอยู่: ${shown}${rest}`,
+      detail: `${n} files depend on it; no test imports it — edit here and nothing catches the break`,
+      evidence: `dependents: ${shown}${rest}`,
     });
   }
 
@@ -417,10 +418,10 @@ export function diagnose(
       findings.push({
         kind: "changed-untested",
         file: c,
-        detail: `เพิ่งแก้แต่ไม่มีเทสไหนพึ่งอยู่ (${deps.size} dependent) — พังแล้วไม่มีอะไรจับ`,
+        detail: `recently changed but no test depends on it (${deps.size} dependent) — nothing catches it if it breaks`,
         evidence:
           deps.size > 0
-            ? `พึ่งอยู่: ${[...deps].sort().join(", ")}`
+            ? `dependents: ${[...deps].sort().join(", ")}`
             : "0 dependents",
       });
     }
@@ -475,7 +476,7 @@ export function formatAnalyze(graph: ImportGraph, findings: Finding[]): string {
   lines.push("");
 
   if (findings.length === 0) {
-    lines.push("no findings — โครงสร้างไม่มีอะไรน่าห่วง");
+    lines.push("no findings — structure looks healthy");
   } else {
     for (const f of findings.slice(0, 5)) {
       const icon = f.kind === "orphan" ? "·" : "⚠";
@@ -488,7 +489,7 @@ export function formatAnalyze(graph: ImportGraph, findings: Finding[]): string {
     if (rest > 0) lines.push(`… and ${rest} more`);
     lines.push(
       graph.unresolved > 0
-        ? `${findings.length} findings. ${graph.unresolved} unresolved imports (path alias / package name) — ตัวเลข dependent อาจต่ำกว่าจริง`
+        ? `${findings.length} findings. ${graph.unresolved} unresolved imports (path alias / package name) — dependent counts may be lower than reality`
         : `${findings.length} findings.`,
     );
   }

package/src/conventions-seed.ts

@@ -1,15 +1,15 @@
 // src/conventions-seed.ts — `fapony init` fill-signal (PLAN-convention-debt chunk 2).
 //
-// คำถาม: "การ fill signal ตอน init ทำได้แค่ไหน" (SPEC-convention-debt §2.2) —
-// วัดสองรอบ คำตอบรอบแรกผิด: eslint คือของที่ทีมส่วนใหญ่ปล่อย default ตอนติดตั้ง,
-// pair-mining พังกับ commit ก้อนใหญ่และ cap ผ่อนไม่ได้ (วัดแล้ว) — ของที่**ทุกรีโปมี**
-// คือโค้ดตัวเอง ฐานจึงเป็น wrapper detector (อ่าน snapshot อย่างเดียว ไม่แตะ history),
-// eslint เป็น bonus เมื่อมี, pair-mining ยังไม่ทำ (chunk 7 วัด precision ก่อน)
+// Question: "how far can signal-filling at init go" (SPEC-convention-debt §2.2) —
+// Measured twice; the first answer was wrong: eslint is what most teams leave at default on install,
+// pair-mining breaks on large commits and the cap cannot be relaxed (measured) — what **every repo has**
+// is its own code, so the base is a wrapper detector (reads the snapshot only, never touches history),
+// eslint is a bonus when present, pair-mining is not done yet (chunk 7 measures precision first)
 //
-// เขียนได้ที่เดียว: <target>/.fapony/conventions.json — นิยาม convention อยู่ในรีโปที่
-// ถูกวัด (SPEC §2.1), commit ได้เพราะทุก field เป็น repo-relative · มีอยู่แล้ว = ไม่แตะ
-// (rule 5c) · fapony ไม่เดา convention ที่ไม่มีร่องรอย — อันที่ยังไม่เคย migrate และ
-// ไม่มี wrapper ไม่มีร่องรอยทั้งใน snapshot และ history ช่องนั้นเหลือให้คนเติม (stale)
+// Written to one place: <target>/.fapony/conventions.json — the convention definition lives in the repo being
+// measured (SPEC §2.1), committable because every field is repo-relative · already exists = leave untouched
+// (rule 5c) · fapony does not guess a convention with no trace — one never migrated and
+// with no wrapper has no trace in either snapshot or history, that slot is left for a human to fill (stale)
 
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -108,7 +108,7 @@ function rowsFromBlock(block: Block, whereBase: string): SeedRow[] {
     whereGlob && whereGlob !== "." ? `${dir}${whereGlob}` : whereBase || ".";
   const push = (message: unknown, stale: string | null, ruleId: string) => {
     const text = flatText(message);
-    if (!text) return; // checker โดยไม่มีข้อความ = ไม่รู้ว่ากฎคืออะไร
+    if (!text) return; // a checker without a message = the rule is unknown
     out.push({ id: "", rule: text, where, stale, checker: ruleId });
   };
   for (const [ruleId, value] of Object.entries(block.rules ?? {})) {

package/src/db/index.ts

@@ -1,4 +1,4 @@
-// barrel — re-export ทุกอย่างจาก db/* ให้ import เดิมจาก "./db/index.js" ใช้ได้
+// barrel — re-export everything from db/* so existing imports from "./db/index.js" keep working
 
 export * from "./defaults.js";
 export * from "./getters.js";

package/src/db/store.ts

@@ -80,7 +80,11 @@ export function openDb(config?: Config): Database {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
   const db = new Database(`${dir}/state.db`);
+  // bun default busy_timeout=0 = no retry on SQLITE_BUSY; multiple agent
+  // processes share this db, so concurrent writers throw immediately without this.
+  db.run("PRAGMA busy_timeout=5000");
   db.run("PRAGMA journal_mode=WAL");
+  db.run("PRAGMA synchronous=NORMAL");
 
   migrateDb(db);
 

package/src/debt.ts

@@ -1,18 +1,20 @@
 // src/debt.ts — `fapony debt`: which files have not moved to a shipped convention yet.
 //
-// คำถามที่ไม่มีใครตอบได้: "ไฟล์ไหนยังไม่ย้าย" — rules files (CLAUDE.md, Cursor rules)
-// บอกได้แค่ว่า "กฎคืออะไร" (ชั้น 2) และ "ก๊อปไฟล์ไหน" (ชั้น 1) — ตำแหน่งของหนี้
-// (ชั้น 3) อยู่ในหัวเจ้าของ และหายเมื่อลืม (SPEC-convention-debt §1)
+// The question nobody can answer: "which files have not moved" — rules files
+// (CLAUDE.md, Cursor rules) can only say "what the rule is" (layer 2) and
+// "which files were copied" (layer 1) — where the debt is (layer 3) lives in
+// the owner's head and vanishes when forgotten (SPEC-convention-debt §1)
 //
-// นิยามของ convention อยู่ในรีโปที่ถูกวัด (<repo>/.fapony/conventions.json — ผ่าน
-// resolver เดียวกับ mem log, SPEC §2.1) — fapony ไม่รู้จัก React หรือ Hono และ
-// ต้องไม่รู้จัก · หนึ่ง convention = pattern ที่ควรใช้ (ok) + pattern ที่แปลว่า
-// ยังไม่ย้าย (stale) + ขอบเขต (where) + เงื่อนไขของไฟล์ (guard, เช่น extends Base)
+// The convention definition lives in the measured repo (<repo>/.fapony/conventions.json
+// — via the same resolver as the mem log, SPEC §2.1) — fapony does not know React
+// or Hono and must not · one convention = pattern to use (ok) + pattern meaning
+// not-yet-migrated (stale) + scope (where) + file condition (guard, e.g. extends Base)
 //
-// หนี้ถูกคำนวณสดทุกครั้ง ไม่เขียนลงที่ใดเลย (แบบเดียวกับ analyze: cache คือหนี้ล้วน —
-// ลิสต์ที่ freeze ไว้ตกรุ่นเงียบ ๆ เหมือน MASTER.md) · กฎเหล็ก: checker ไม่ null =
-// fapony ไม่รายงานหนี้ข้อนั้น — การรายงานซ้ำกับ eslint คือ abstraction ที่มี
-// implementation เดียว (กฎ 1) และสอนให้ agent ข้ามทั้งคู่ (SPEC §2)
+// Debt is computed live every time, never written anywhere (same as analyze:
+// a cache is pure debt — a frozen list goes stale silently like MASTER.md) ·
+// Iron rule: checker not null = fapony does not report that debt item — reporting
+// twice with eslint is an abstraction with one implementation (rule 1) and
+// teaches the agent to skip both (SPEC §2)
 //
 // Read-only stdout: no file writes, no state.db, no cache (rule 5b).
 
@@ -242,12 +244,12 @@ export function debtScan(
   const compiled: Compiled[] = [];
   for (const conv of loaded.convs) {
     if (conv.checker) {
-      // กฎเหล็ก — fapony เงียบ ปล่อยให้ checker ทำงาน (SPEC §2)
+      // Iron rule — fapony stays silent, leave it to the checker (SPEC §2)
       checkedCount++;
       continue;
     }
     if (!conv.stale) {
-      // ช่องเดียวที่คนเติม (SPEC §2.2) — โชว์ว่าค้าง ไม่เดาแทน
+      // The one slot a human fills (SPEC §2.2) — show it as pending, don't guess
       declared.push(conv);
       continue;
     }
@@ -352,16 +354,18 @@ export function debtForFile(
   return out;
 }
 
-// --- Promotion signal (chunk 5) — "เรื่องนี้ซ้ำครั้งที่ N แล้ว ทำ checker ไหม" ---
+// --- Promotion signal (chunk 5) — "this recurred N times, time for a checker?" ---
 //
-// "ผมจะทำ eslint ตอนที่คิดได้" — จังหวะ "คิดได้" คือสิ่งที่หายไป (SPEC §3) fapony
-// เห็นประวัติข้าม session (mem + verdicts) จึงนับได้ว่าเรื่องเดียวกันถูกแก้ซ้ำกี่ครั้ง
-// แล้วยื่นคำถามให้คนตัดสิน — ไม่ตัดสินเอง ไม่เขียน eslint rule เอง (SPEC §6 fail list)
+// "I'll write eslint when I think of it" — the "think of it" moment is what goes
+// missing (SPEC §3) · fapony sees history across sessions (mem + verdicts), so it
+// can count how often the same thing was fixed, then put the question to a human —
+// it does not decide, does not write the eslint rule itself (SPEC §6 fail list)
 //
-// การ match "เรื่องเดียวกัน" — แม่นยำเท่าที่ข้อมูลให้ (SPEC §7: แถวเก่าไม่มี files[]
-// ยังไม่ตัดสิน): แถวที่มี files[] ต้อง intersect กับ debt list · ข้อความต้องเอ่ยถึง
-// สัญลักษณ์ของ convention (ok เช่น fmtMoney, หรือ identifier ≥ 6 ตัวจาก stale เช่น
-// toLocaleString/useMutation — "throw"/"Error" สั้นเกินจึงไม่นับ กัน over-match)
+// Matching "the same thing" — only as precise as the data allows (SPEC §7: old rows
+// lack files[], still undecided): a row with files[] must intersect the debt list ·
+// the text must mention a convention symbol (ok such as fmtMoney, or an identifier
+// ≥ 6 chars from stale such as toLocaleString/useMutation — "throw"/"Error" are too
+// short and don't count, to avoid over-matching)
 
 export const PROMOTION_THRESHOLD = 3;
 const PROMOTION_MAX = 3;
@@ -642,7 +646,7 @@ export function cmdDebt(args: string[]): void {
   }
 
   if (loaded.path === null) {
-    // SPEC §6: ไม่มี conventions.json = เงียบสนิท ไม่ error ไม่ชวนสร้าง
+    // SPEC §6: no conventions.json = completely silent, no error, no prompt to create one
     console.log(
       `fapony debt — no conventions.json in ${worktree} (nothing tracked yet)`,
     );

package/src/digest/collect.ts

@@ -1,6 +1,6 @@
-// src/digest/collect.ts — รวมข้อมูลจาก 4 แหล่งเป็น DigestData ก้อนเดียว
+// src/digest/collect.ts — merge data from 4 sources into a single DigestData
 //
-// ไม่ render อะไรเลย — แค่อ่าน + จัดรูป struct
+// Renders nothing — just reads + shapes into structs
 
 import { execSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
@@ -144,7 +144,7 @@ function parseFrontmatter(text: string): { status?: string; kind?: string } {
 }
 
 function countCheckboxes(text: string): { done: number; total: number } {
-  // นับ checkbox ใน section ## แรกเท่านั้น (same logic as plans.ts)
+  // Count checkboxes in the first ## section only (same logic as plans.ts)
   const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
   const start = body.search(/^##\s+/m);
   if (start < 0) return { done: 0, total: 0 };
@@ -216,7 +216,7 @@ function readUsageAndCost(_worktree: string): {
   detail: string;
 } {
   const cache = readCache();
-  // หา global entry (worktree=null) หรือรวมทุก entry
+  // Find a global entry (worktree=null), otherwise merge every entry
   const globalEntries = cache.filter((e) => !e.worktree);
   if (globalEntries.length === 0 && cache.length === 0) {
     return {
@@ -232,11 +232,11 @@ function readUsageAndCost(_worktree: string): {
     };
   }
 
-  // ใช้ global entries ถ้ามี ไม่งั้นรวมทุก entry
+  // Use global entries if present, otherwise merge every entry
   const entries = globalEntries.length > 0 ? globalEntries : cache;
   const usage = entriesToUsage(entries);
 
-  // คำนวณราคา
+  // Compute the price
   const prices = loadPrices();
   if (!prices) {
     return {
@@ -271,7 +271,7 @@ function readUsageAndCost(_worktree: string): {
     imputed: m.imputed_cost,
   }));
 
-  // เพิ่ม cost จริงจาก cache
+  // Attach the real cost from the cache
   const cacheByKey = new Map(
     entries.flatMap((e) =>
       e.by_model.map((m) => [`${m.provider}\0${m.model}`, m]),

package/src/digest/html.ts

@@ -1,7 +1,7 @@
 // src/digest/html.ts — render digest as a single HTML page
 //
-// คอลัมน์เดียว max-width: 68rem · ไม่มี tab ไม่มีปุ่มพับ ไม่มี JS
-// ใช้ DARK_THEME_CSS + TABLE_CSS จาก src/web/html.ts
+// single column max-width: 68rem · no tabs, no collapse buttons, no JS
+// uses DARK_THEME_CSS + TABLE_CSS from src/web/html.ts
 
 import { DARK_THEME_CSS, esc, TABLE_CSS } from "../web/html.js";
 import type {

package/src/digest/text.ts

@@ -1,6 +1,6 @@
 // src/digest/text.ts — render digest as terminal text
 //
-// ลำดับ section ตาม SPEC §3 (เล่าเรื่อง ไม่ใช่ dashboard)
+// Section order per SPEC §3 (tells a story, not a dashboard)
 
 import type { CostRow, DigestData, MemRow, PlanRow } from "./collect.js";
 

package/src/gate.ts

@@ -53,9 +53,9 @@ export function gateOnce(
   }
 
   const config = loadConfig();
-  // runs.worktree เก็บ absolute path (SERVER_INSTRUCTIONS บังคับ) — ไม่ใช่ key ของ config.worktrees
-  // การ lookup จึงพลาดเสมอ และ fallback เดิม "." ทำให้คำสั่ง memory ของโปรเจกต์ไปรันใน cwd ของ
-  // MCP server แทนที่จะเป็นโปรเจกต์นั้น · lookup ยังอยู่เผื่อ row เก่าที่เคยเก็บเป็น key
+  // runs.worktree stores an absolute path (SERVER_INSTRUCTIONS mandates it) — not a key in config.worktrees
+  // so the lookup always misses, and the old "." fallback ran the project's memory commands in the cwd of
+  // the MCP server instead of that project · the lookup stays in case an old row was stored as a key
   const worktree = config.worktrees[run.worktree] ?? run.worktree;
 
   // --- pass family (4 grades) ---