fapony 0.1.1 → 0.1.2

package/src/install/opencode.ts

@@ -112,6 +112,7 @@ export function cmdInstallOpencode(
     const skillsDir = claudeSkillsDir(getHome);
     reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
     installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
     return;
   }
 
@@ -134,6 +135,7 @@ export function cmdInstallOpencode(
     }
     console.log(computeDiff(before, after));
     installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
     return;
   }
 
@@ -154,6 +156,7 @@ export function cmdInstallOpencode(
   const skillsDir = claudeSkillsDir(getHome);
   reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
   installReadHintPlugin(dryRun, getHome);
+  installCommitHintPlugin(dryRun, getHome);
 }
 
 /**
@@ -164,35 +167,86 @@ export function cmdInstallOpencode(
  * throws, never dedupes ("you already read this" goes false after context
  * compaction — a hook that guesses wrong must never trap the agent).
  *
- * Logic lives in src/hook.ts (readHintFor) — the plugin imports it from the
- * install root (path baked at install time), same one-copy-per-client shape
- * as the skills symlinks: a git pull in INSTALL_ROOT updates every client.
- * Best-effort, same policy as the claude hooks: an existing file that isn't
- * fapony's is never overwritten, and a failure never fails the install.
+ * Logic lives in src/hook.ts (readHintFor + readContextLines) — the plugin
+ * imports it from the install root (path baked at install time), same
+ * one-copy-per-client shape as the skills symlinks: a git pull in
+ * INSTALL_ROOT updates every client. Mirrors Claude's cmdHookReadHint
+ * (PreToolUse), which appends both the size hint and the debt/mem context —
+ * OpenCode was missing the second half until now (only the size hint was
+ * wired), so a convention debt on the file you just opened, or a mem-log
+ * row about it, never reached OpenCode even though the detector already
+ * runs on every read. Best-effort, same policy as the claude hooks: an
+ * existing file that isn't fapony's is never overwritten, and a failure
+ * never fails the install.
  */
 export function readHintPluginSource(root: string): string {
   const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
   return `// fapony read hint — annotates full-file reads of large source files with a
-// factual review-seed pointer. Annotate only: never blocks, never dedupes.
+// factual review-seed pointer, plus any convention debt or mem-log row about
+// the file. Annotate only: never blocks, never dedupes.
 // Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
-import { readHintFor } from ${hookModule};
+import { readHintFor, readContextLines } from ${hookModule};
 
 export const FaponyReadHint = async ({ directory }) => {
   return {
     "tool.execute.after": async (input, output) => {
       try {
         if (input.tool !== "read") return;
+        const parts = [];
         const hint = readHintFor({
           filePath: input.args?.filePath,
           offset: input.args?.offset,
           limit: input.args?.limit,
           cwd: directory,
         });
+        if (hint) parts.push(hint);
+        for (const line of readContextLines(input.args?.filePath, directory)) {
+          parts.push(line);
+        }
+        if (parts.length > 0 && typeof output.output === "string") {
+          output.output = output.output + "\\n" + parts.join("\\n");
+        }
+      } catch {
+        // a hint must never break a read
+      }
+    },
+  };
+};
+`;
+}
+
+/**
+ * OpenCode plugin — the commit hint's in-process shape. `tool.execute.after`
+ * on the bash tool: when the command contains `git commit` and the worktree
+ * has ungraded commits, appends a nudge to the command output. Annotate only
+ * (no decision:block — OpenCode has no stop-hook equivalent).
+ *
+ * Logic lives in src/hook.ts (commitHintFor) — same one-copy-per-client shape
+ * as the read hint: a git pull in INSTALL_ROOT updates every client.
+ */
+export function commitHintPluginSource(root: string): string {
+  const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
+  return `// fapony commit hint — annotates git commit bash commands with a
+// verdict reminder when commits have no verdict filed yet.
+// Annotate only: never blocks, never dedupes.
+// Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
+import { commitHintFor } from ${hookModule};
+
+export const FaponyCommitHint = async ({ directory }) => {
+  return {
+    "tool.execute.after": async (input, output) => {
+      try {
+        if (input.tool !== "bash") return;
+        const command = input.args?.command;
+        const hint = commitHintFor({
+          command,
+          cwd: directory,
+        });
         if (hint && typeof output.output === "string") {
           output.output = output.output + "\\n" + hint;
         }
       } catch {
-        // a hint must never break a read
+        // a hint must never break a bash command
       }
     },
   };
@@ -232,3 +286,36 @@ function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
     `  read hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
   );
 }
+
+function installCommitHintPlugin(dryRun: boolean, getHome: () => string): void {
+  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
+  const pluginPath = join(pluginsDir, "fapony-commit-hint.ts");
+  if (existsSync(pluginPath)) {
+    let current = "";
+    try {
+      current = readFileSync(pluginPath, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (current.includes("commitHintFor")) {
+      console.error(`  commit hint: already installed — no change`);
+      return;
+    }
+    console.error(
+      `  commit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+    );
+    return;
+  }
+  if (!dryRun) {
+    try {
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(pluginPath, commitHintPluginSource(INSTALL_ROOT), "utf-8");
+    } catch (e) {
+      console.error(`  commit hint: failed to write — ${(e as Error).message}`);
+      return;
+    }
+  }
+  console.error(
+    `  commit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  );
+}

package/src/install/types.ts

@@ -11,7 +11,7 @@ export const MCP_KEY = "fapony";
 
 export const MCP_CONFIG = {
   type: "local",
-  command: ["bun", "run", "fapony.ts", "mcp"],
+  command: ["bun", "run", join(INSTALL_ROOT, "fapony.ts"), "mcp"],
 };
 
 /** ZCode uses the stdio MCP shape: command is a string, args is an array.

package/src/install.ts

@@ -31,7 +31,11 @@ export {
 export { cmdInstallCodex } from "./install/codex.js";
 export { cmdInstallCursor } from "./install/cursor.js";
 export { detectClients } from "./install/detect.js";
-export { cmdInstallOpencode } from "./install/opencode.js";
+export {
+  cmdInstallOpencode,
+  commitHintPluginSource,
+  readHintPluginSource,
+} from "./install/opencode.js";
 export {
   agentsSkillsDir,
   claudeSkillsDir,

package/src/lint-baseline.ts

@@ -1,15 +1,15 @@
 // src/lint-baseline.ts — `fapony lint-baseline`: separate "was red before" from "I made it red".
 //
-// warning กับ error ที่แดงอยู่ก่อนหน้า agent เข้ามา ทำให้ agent ต้อง `fix all` ก่อน
-// แล้วงานจริงถูกกลบใน diff ก้อนเดียว (SPEC-convention-debt §4 — จากปากเจ้าของ:
-// "138 จุดใน ~40 ไฟล์ที่ไม่เกี่ยวกับงาน") ตัวเลขของรีโปที่แดงอยู่แล้ว 212 จุด —
-// agent ที่ไม่ได้ทำอะไรผิดต้องเห็น **0**
+// warnings and errors already red before the agent arrived force the agent to `fix all` first
+// and then the real work is buried in one large diff (SPEC-convention-debt §4 — from the owner:
+// "138 spots across ~40 files unrelated to the work") the repo's own red count is 212 —
+// an agent that did nothing wrong must see **0**
 //
-// กลไก — ไม่รู้จัก eslint: รันคำสั่งที่รีโปบอก (--cmd หรือ evidence.json ชื่อ "lint"),
-// parse เป็นชุด `path:rule-id` (**ไม่ใช่เลขบรรทัด** — บรรทัดขยับทุกครั้งที่แก้ไฟล์),
-// เก็บ baseline ไว้ที่ base_sha · ผลลัพธ์ไม่เข้า state.db (2 ตารางห้ามเพิ่ม) —
-// เป็นไฟล์ชั่วคราวใต้ state dir และถูกทิ้งเมื่อ --diff รายงานแล้ว · รายงานอย่างเดียว
-// ไม่ block — agent ตัดสินเองว่าจะแก้ของเก่าด้วยไหม
+// Mechanism — does not know eslint: runs the command the repo declares (--cmd or evidence.json named "lint"),
+// parses into a set of `path:rule-id` (**not line numbers** — lines shift every time a file is edited),
+// stores the baseline at base_sha · results never enter state.db (2 tables, no additions) —
+// it is a temporary file under the state dir and is discarded once --diff reports · report only
+// never blocks — the agent decides whether to fix the old issues too
 
 import { execSync } from "node:child_process";
 import {

package/src/mcp/tools/mem.ts

@@ -1,6 +1,6 @@
 // src/mcp/tools/mem.ts — mem_find: read-only search over the project's mem log
 //
-// "เขียนได้ ≠ อ่านกลับได้" — the write side works from the CLI with no MCP
+// "writable ≠ readable back" — the write side works from the CLI with no MCP
 // (vela: 2,920 rows / 49 days); what was missing is "which rows are about the
 // files I am about to touch". Read-only over readMemLog (PLAN-mem-mcp chunk 2).
 //

package/src/mcp/tools/stats.ts

@@ -86,11 +86,11 @@ export function toolFaponyStats(args: Record<string, unknown>): ToolResult {
     };
   }
 
-  // json:true → StatsData ล้วน (SPEC-verdict-stats) — ห้ามแทรก text อื่น
+  // json:true → pure StatsData (SPEC-verdict-stats) — no other text may be inserted
   if (args.json === true) {
     return jsonResult(data);
   }
 
-  // json:false → text เดียวกับ `fapony stats` — same formatter, raw (not JSON-wrapped)
+  // json:false → the same text as `fapony stats` — same formatter, raw (not JSON-wrapped)
   return { content: [{ type: "text", text: formatStatsText(data) }] };
 }

package/src/mcp/tools/usage.ts

@@ -13,7 +13,7 @@ import {
 } from "../../session/index.js";
 import { jsonResult, type ToolResult } from "../types.js";
 
-/** สรุป list-price ต่อ client — additive ไม่แตะบรรทัดเดิม */
+/** list-price summary per client — additive, leaves existing lines untouched */
 function imputationOf(
   result: PassiveUsageResult,
   prices: PriceTable | null,
@@ -45,7 +45,7 @@ function imputedTextLines(
   return [`  ${label}list-price equivalent: ${parts.join(" · ")}`];
 }
 
-/** ราคา list ราย model ต่อท้ายชื่อรุ่น — เฉพาะแถวที่ client ไม่บันทึก cost */
+/** list price per model appended to the model name — only rows where the client records no cost */
 function imputedSuffix(
   provider: string,
   model: string,
@@ -78,7 +78,7 @@ export function toolPassiveUsage(args: Record<string, unknown>): ToolResult {
     result: client.read(worktree, since, until, detail),
   }));
 
-  // ราคา list จาก cache อย่างเดียว — อ่านครั้งเดียวต่อ call ไม่ใช่ต่อ section
+  // list prices from the cache only — read once per call, not per section
   const prices = loadPrices();
 
   if (args.json === true) {

package/src/mcp/tools/verdict.ts

@@ -79,22 +79,35 @@ export function toolVerdictSubmit(args: Record<string, unknown>): ToolResult {
         : "mcp-external";
     const resolvedPlan =
       typeof plan === "string" && plan ? plan.trim().toLowerCase() : null;
-    let open = resolvedPlan
-      ? findOpenRun(db, resolvedWorktree, resolvedPlan)
-      : null;
-    // Fallback: if no exact match and plan is non-null, try any open run with
-    // plan=null.  This lets a verdict with free-text intent bind to a run that
-    // was created without a plan (the common "no PLAN file" flow).
-    if (!open && resolvedPlan) {
-      open = findOpenRunWithNullPlan(db, resolvedWorktree);
-    }
-    if (open) {
-      resolvedRunId = open.id;
-    } else {
-      // worktree/plan let callers (e.g. move-to-done) attribute the verdict
-      // so byReasonCode/bestPassing aggregate correctly instead of collapsing
-      // into "mcp-external".
-      resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
+    // BEGIN IMMEDIATE makes the find-then-create below atomic across
+    // concurrent MCP processes: without it, two agents closing the same
+    // worktree+plan at once can both see "no open run" and each insert a
+    // row. The write lock taken here blocks (busy_timeout, not throws) the
+    // second caller until the first commits, so it re-reads and finds the
+    // row already there instead of duplicating it.
+    db.run("BEGIN IMMEDIATE");
+    try {
+      let open = resolvedPlan
+        ? findOpenRun(db, resolvedWorktree, resolvedPlan)
+        : null;
+      // Fallback: if no exact match and plan is non-null, try any open run with
+      // plan=null.  This lets a verdict with free-text intent bind to a run that
+      // was created without a plan (the common "no PLAN file" flow).
+      if (!open && resolvedPlan) {
+        open = findOpenRunWithNullPlan(db, resolvedWorktree);
+      }
+      if (open) {
+        resolvedRunId = open.id;
+      } else {
+        // worktree/plan let callers (e.g. move-to-done) attribute the verdict
+        // so byReasonCode/bestPassing aggregate correctly instead of collapsing
+        // into "mcp-external".
+        resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
+      }
+      db.run("COMMIT");
+    } catch (e) {
+      db.run("ROLLBACK");
+      throw e;
     }
   }
 

package/src/mcp/transport.ts

@@ -112,7 +112,7 @@ function writeStatuslineCache(toolResult: ToolResult): void {
 
 const MCP_PROTOCOL_VERSION = "2025-03-26";
 const SERVER_NAME = "fapony-handcheck";
-const SERVER_VERSION = "0.1.0";
+const SERVER_VERSION = "0.1.2";
 
 // --- JSON-RPC dispatch ---
 

package/src/plan-seed.ts

@@ -88,7 +88,7 @@ function scopeSourceFiles(root: string): string[] {
 // is about to plan. Headers only (title + shipped date) — pulling the bodies
 // in would recreate the reading task the plan exists to avoid.
 function renderPriorArt(cwd: string, config: Config, roots: string[]): string {
-  const placeholder = "- _(agent เติม)_";
+  const placeholder = "- _(agent fills in)_";
   const keys = roots
     .map((r) => relative(cwd, r))
     .filter((r) => r !== "" && r !== ".");
@@ -124,7 +124,7 @@ function renderPriorArt(cwd: string, config: Config, roots: string[]): string {
       const shipped = content.match(/shipped\s+(\d{4}-\d{2}-\d{2})/)?.[1] ?? "";
       hits.push({
         shipped,
-        line: `- ✅ ตัดสินไปแล้ว: [${n}](../${label}/${n}) — ${title}${shipped ? ` (shipped ${shipped})` : ""} \`(fapony plan-seed)\``,
+        line: `- ✅ Already decided: [${n}](../${label}/${n}) — ${title}${shipped ? ` (shipped ${shipped})` : ""} \`(fapony plan-seed)\``,
       });
     }
   }
@@ -137,7 +137,9 @@ function renderPriorArt(cwd: string, config: Config, roots: string[]): string {
   );
   const shown = hits.slice(0, MAX_PRIOR_ART).map((h) => h.line);
   if (hits.length > MAX_PRIOR_ART) {
-    shown.push(`- … +${hits.length - MAX_PRIOR_ART} more ที่แตะ scope เดียวกัน`);
+    shown.push(
+      `- … +${hits.length - MAX_PRIOR_ART} more touching the same scope`,
+    );
   }
   shown.push(placeholder);
   return shown.join("\n");
@@ -185,49 +187,49 @@ kind: unit
 status: active
 ---
 
-# PLAN-${name} — (agent เติมชื่อเรื่อง)
+# PLAN-${name} — (agent fills in a title)
 
-> **Status:** 🚧 in-progress · **Created:** (agent เติมวันที่)
+> **Status:** 🚧 in-progress · **Created:** (agent fills in the date)
 
 ## TL;DR
-- **What:** (agent เติม) · **Why:** (agent เติม) · **Done when:** (agent เติม)
-- **Order:** (agent เติม)
+- **What:** (agent fills in) · **Why:** (agent fills in) · **Done when:** (agent fills in)
+- **Order:** (agent fills in)
 - **Progress:**
-  - [ ] chunk 1 — (agent เติม)
+  - [ ] chunk 1 — (agent fills in)
 
 ## Context (fapony)
 ${contextFapony}
 
 ## 1. Goal (why)
-_(agent เติม)_
+_(agent fills in)_
 
 ## 2. Scope (do / don't do)
-_(agent เติม)_
+_(agent fills in)_
 
 ## 3. Done criteria (how we know it's finished)
-_(agent เติม — ต้อง verify ได้)_
+_(agent fills in — must be verifiable)_
 
 ## 4. Constraints / Hard rules (must not violate)
-_(agent เติม)_
+_(agent fills in)_
 
 ## 5. Risks & Escape hatches (if it fails)
-_(agent เติม)_
+_(agent fills in)_
 
 ## 6. Steps (what in which order)
-1. _(agent เติม — แต่ละขั้น verify ได้)_
+1. _(agent fills in — each step must be verifiable)_
 
 ## 7. Examples
 ${
   specLink
-    ? `→ ${specLink}  (signature อยู่ spec ไม่ใช่ plan)`
-    : "_(agent เติม — หรือเพิ่ม SPEC ด้วย plan-seed --spec)_"
+    ? `→ ${specLink}  (signatures live in the spec, not the plan)`
+    : "_(agent fills in — or add a SPEC with plan-seed --spec)_"
 }
 
 ## 8. References
 ${priorArt}
 
 ## Context (agent)
-_(slot ว่าง — agent dump graph/code-summary ของตัวเอง)_
+_(empty slot — the agent dumps its own graph/code-summary)_
 `;
 }
 
@@ -437,7 +439,7 @@ function specTemplate(
   // undershot the cap by that many lines (the 18k-SPEC failure mode). Cap the
   // index separately so the body's capLines has a bounded head to work with.
   const fixedHead = [
-    `# SPEC-${name} — (agent เติมชื่อเรื่อง)`,
+    `# SPEC-${name} — (agent fills in a title)`,
     "",
     `> **Used by:** PLAN-${name} — signatures below come from a live source scan — re-seed after structural changes.`,
     ...(scopeEcho ? [`> **Scope:** ${scopeEcho}`] : []),
@@ -456,7 +458,7 @@ function specTemplate(
   );
   const head = [...fixedHead, ...cappedIndex, ""];
   const tail = [
-    "## (agent เติม — wireframes / edge cases / API shapes ที่ plan อ้างถึง)",
+    "## (agent fills in — wireframes / edge cases / API shapes the plan references)",
   ];
   const bodyLines = chunks.flatMap((c) => [
     `## <a id="${c.slug}"></a>${c.title}`,
@@ -557,7 +559,7 @@ export function cmdPlanSeed(args: string[]): void {
   const planPath = join(planDirAbs, `PLAN-${name}.md`);
   if (existsSync(planPath)) {
     console.error(
-      `${planPath} already exists — not overwriting. ใช้ชื่อใหม่ เช่น PLAN-${name}-v2`,
+      `${planPath} already exists — not overwriting. Use a new name, e.g. PLAN-${name}-v2`,
     );
     process.exit(1);
   }
@@ -571,7 +573,7 @@ export function cmdPlanSeed(args: string[]): void {
     const specPath = join(specDirAbs, `SPEC-${name}.md`);
     if (existsSync(specPath)) {
       console.error(
-        `${specPath} already exists — not overwriting. ใช้ชื่อใหม่ เช่น SPEC-${name}-v2`,
+        `${specPath} already exists — not overwriting. Use a new name, e.g. SPEC-${name}-v2`,
       );
       process.exit(1);
     }

package/src/price/fetch.ts

@@ -1,9 +1,9 @@
-// src/price/fetch.ts — ดึงตารางราคา OpenRouter + cache เป็น prices.json
+// src/price/fetch.ts — fetch OpenRouter's price table + cache it as prices.json
 //
-// ราคาเป็น cache ไม่ใช่ state: เก็บที่ ~/.config/fapony/prices.json (เคารพ
-// FAPONY_STATE_DIR) ห้ามเพิ่มตาราง SQLite (กฎ DB Schema: 2 ตารางเท่านั้น)
-// refresh เกิดตอนคนสั่ง `fapony price-scan` เท่านั้น — query ไม่ fetch เอง
-// (วินัยเดียวกับ usage-scan) offline แล้วอ่าน cache เดิม
+// prices are cache, not state: stored at ~/.config/fapony/prices.json (honors
+// FAPONY_STATE_DIR) no new SQLite tables (DB Schema rule: 2 tables only)
+// refresh happens only when someone runs `fapony price-scan` — a query never fetches on its own
+// (same discipline as usage-scan) offline, read the existing cache
 
 import {
   existsSync,
@@ -19,12 +19,12 @@ import type { Config } from "../db/types.js";
 const PRICES_FILENAME = "prices.json";
 const MODELS_URL = "https://openrouter.ai/api/v1/models";
 
-/** เรตราย token (ดอลลาร์) — ทุกเรตมาจาก OpenRouter ตรง ๆ ไม่เดา */
+/** per-token rates (dollars) — every rate comes straight from OpenRouter, no guessing */
 export interface ModelRates {
   input: number;
   output: number;
   cacheRead: number;
-  /** null = ตารางไม่ให้มา → ใช้เรต input แทน (ดู calcCost) */
+  /** null = the table does not provide it → use the input rate instead (see calcCost) */
   cacheWrite: number | null;
 }
 
@@ -37,7 +37,7 @@ export function pricesPath(config?: Config): string {
   return join(faponyDir(config), PRICES_FILENAME);
 }
 
-/** อ่าน cache — คืน null เมื่อไม่มีไฟล์หรือพัง (caller แสดง — + hint) */
+/** Read the cache — null when the file is missing or broken (caller shows "—" + hint) */
 export function loadPrices(config?: Config): PriceTable | null {
   const p = pricesPath(config);
   if (!existsSync(p)) return null;
@@ -53,7 +53,7 @@ export function loadPrices(config?: Config): PriceTable | null {
   }
 }
 
-/** เขียนแบบ atomic (tmp + rename) สร้าง state dir เมื่อยังไม่มี */
+/** Write atomically (tmp + rename), create the state dir when absent */
 export function writePrices(table: PriceTable, config?: Config): void {
   const p = pricesPath(config);
   mkdirSync(dirname(p), { recursive: true });
@@ -72,14 +72,14 @@ function toRate(v: unknown): number | null {
 }
 
 /**
- * แปลง response ดิบของ OpenRouter เป็นตารางเรต (pure — เทสต์ได้โดยไม่ยิงเน็ต)
+ * Turn OpenRouter's raw response into a rate table (pure — testable without hitting the network)
  *
- * ฟิลด์จริง (ยืนยัน 2026-09-14, 445 models): pricing.prompt / .completion /
+ * Real fields (confirmed 2026-09-14, 445 models): pricing.prompt / .completion /
  * .input_cache_read / .input_cache_write (optional) / .input_cache_write_1h
- * (เรต 1h TTL ของบางรุ่น — ใช้เรต 5m มาตรฐานพอ เพราะ log ไม่บอก TTL)
- * เมิน pricing.web_search / pricing.overrides (tier ตาม min_prompt_tokens /
- * utc_days — ใช้ base rate แล้วประกาศข้อจำกัด) · id ขึ้นต้น ~ (alias) ตัดทิ้ง
- * id ลงท้าย :free / :batch เก็บตามนั้น (เป็นแถวราคาของมันเอง)
+ * (the 1h TTL rate of some models — the standard 5m rate suffices because logs do not report TTL)
+ * ignore pricing.web_search / pricing.overrides (tiers based on min_prompt_tokens /
+ * utc_days — use the base rate and state the limitation) · ids starting with ~ (alias) are dropped
+ * ids ending :free / :batch are kept as-is (they are their own price rows)
  */
 export function parsePricesResponse(json: unknown): Record<string, ModelRates> {
   const out: Record<string, ModelRates> = {};
@@ -102,8 +102,8 @@ export function parsePricesResponse(json: unknown): Record<string, ModelRates> {
 }
 
 /**
- * รวมตารางใหม่เข้ากับ cache เดิม — merge ไม่ replace: id ที่หายไปจาก
- * response รอบนี้ (รุ่นเก่าหลุดตาราง) ต้องยังคิดราคาได้ด้วยเรตเดิม
+ * Merge the new table into the old cache — merge, not replace: an id missing from
+ * this response (an old model dropped from the table) must still be priced with its old rate
  */
 export function mergePriceTables(
   old: PriceTable | null,
@@ -115,7 +115,7 @@ export function mergePriceTables(
   };
 }
 
-/** ดึงตารางจาก OpenRouter (public, ไม่ต้อง auth) — fetcher แทรกได้ไว้เทสต์ */
+/** Fetch the table from OpenRouter (public, no auth) — fetcher is injectable for tests */
 export async function fetchPriceTable(
   fetcher: typeof fetch = fetch,
 ): Promise<Record<string, ModelRates>> {
@@ -134,7 +134,7 @@ export async function cmdPriceScan(rawArgs: string[]): Promise<void> {
     fresh = await fetchPriceTable();
   } catch (err) {
     console.error(
-      `fapony price-scan: fetch failed (${String(err)}) — cache เดิมยังอยู่ ใช้ราคาที่มีได้`,
+      `fapony price-scan: fetch failed (${String(err)}) — the existing cache is still here, use the prices you have`,
     );
     process.exit(1);
   }