fapony 0.1.1 → 0.1.2

package/templates/mem/commands/write.ts

@@ -7,17 +7,17 @@ import { KINDS, memCmd, nextId, put, root, rows } from "../store.js";
 export const cmdAdd = async (a: string[]) => {
   // mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [path/to/SPEC.md]
   // mem add <kind> --stdin --files f1,f2 [spec.md]  ← read text from stdin (avoids shell metachar issues)
-  // ponytail: kind ผิด = แถวนั้นหายจาก view เงียบๆ — ตายตั้งแต่ตรงนี้ดีกว่า
+  // ponytail: a wrong kind = that row silently vanishes from the view — better to die right here
   if (!KINDS.includes(a[0] as WorkKind)) {
     console.error(
       `kind must be one of ${KINDS.join("|")} — got "${a[0] ?? ""}"`,
     );
     process.exit(1);
   }
-  // hold บังคับ spec — ตรวจหลัง parse (spec อยู่ก่อน --files ได้)
-  // PLAN-convention-debt chunk 3: files[] เป็น required — optional field ที่วัดแล้ว
-  // fill rate = 0 (required+enum = 50/50) และ recall ของ log เก่าที่ไม่มี files[] จับได้แค่
-  // 48.1% — แก้ที่ขาเขียน ไม่ใช่ขาอ่าน: แถวไหนไม่บอกไฟล์ = ค้นไม่เจอตอนแตะไฟล์นั้น
+  // hold requires a spec — checked after parse (the spec may come before --files)
+  // PLAN-convention-debt chunk 3: files[] is required — a measured optional field
+  // had fill rate 0 (required+enum = 50/50) and recall on old logs without files[] caught only
+  // 48.1% — fix the write side, not the read side: a row that does not name the file = unfindable when you touch that file
   const filesFlagIdx = a.indexOf("--files");
   const filesVal = filesFlagIdx >= 0 ? a[filesFlagIdx + 1] : undefined;
   if (!filesVal || filesVal.startsWith("--")) {
@@ -56,7 +56,7 @@ export const cmdAdd = async (a: string[]) => {
       process.exit(1);
     }
   } else {
-    // ต้องมีข้อความ
+    // text is required
     if (!filtered.length || (filtered.length === 0 && !spec)) {
       console.error(
         `text is required — usage: ${memCmd} add <kind> "<text>" --files f1,f2 [spec.md]`,
@@ -67,7 +67,7 @@ export const cmdAdd = async (a: string[]) => {
   }
   // read once — cap check + id collision
   const all = rows();
-  // ponytail: เพดาน open next/hold กันสะสมไม่มีที่สิ้นสุด — บังคับ triage ของเก่าก่อนเปิดใหม่
+  // ponytail: a cap on open next/hold stops endless accumulation — forces triage of the old before opening new
   const CAP = 15;
   const CAP_HOLD = 10;
   if (a[0] === "next" && !process.env.MEM_FORCE) {
@@ -88,14 +88,14 @@ export const cmdAdd = async (a: string[]) => {
       process.exit(1);
     }
   }
-  // ponytail: กัน id ชน — logic รวมไว้ที่ nextId (store.ts)
+  // ponytail: prevent id collisions — logic centralized in nextId (store.ts)
   const id = nextId(all);
   put({ id, kind: a[0] as WorkKind, text, spec, files });
   console.log(id);
 };
 
 export const cmdClose = async (a: string[]) => {
-  // mem close <id> "<ทำอะไร / commit>" — tombstone ทำให้ claim void เอง
+  // mem close <id> "<what was done / commit>" — the tombstone voids the claim by itself
   // mem close <id> --stdin ← read text from stdin
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} close <id> "<text>"`);
@@ -117,7 +117,7 @@ export const cmdClose = async (a: string[]) => {
 };
 
 export const cmdClaim = (a: string[]) => {
-  // mem claim <id> — ต้องมี id จริง, open, kind=next|bug, ไม่มี active claim ค้าง
+  // mem claim <id> — id must be real, open, kind=next|bug, with no active claim pending
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} claim <id>`);
     process.exit(1);
@@ -153,7 +153,7 @@ export const cmdClaim = (a: string[]) => {
 };
 
 export const cmdRelease = async (a: string[]) => {
-  // mem release <id> "<เหตุผล>?"
+  // mem release <id> "<reason>?"
   // mem release <id> --stdin ← read text from stdin
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} release <id> [reason]`);
@@ -179,7 +179,7 @@ export const cmdRelease = async (a: string[]) => {
 };
 
 export const cmdSynced = (a: string[]) => {
-  // mem synced [path.md ...] — ประกาศว่า spec ตรงกับ log แล้ว (ไม่ระบุ = ทุก spec ที่ log อ้างถึง)
+  // mem synced [path.md ...] — declare the spec now matches the log (none given = every spec the log mentions)
   const specs = a.length
     ? a
     : [
@@ -195,7 +195,7 @@ export const cmdSynced = (a: string[]) => {
 };
 
 export const cmdHook = async () => {
-  // PostToolUse: stdin = {tool_input:{file_path}} → แก้ spec ของ app นี้เสร็จ = synced ให้เอง
+  // PostToolUse: stdin = {tool_input:{file_path}} → editing this app's spec is done = mark synced automatically
   const j = (await Bun.stdin.json().catch(() => null)) as Record<
     string,
     unknown

package/templates/mem/mem.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
 
-// append-only memory log. ห้ามแก้บรรทัดเก่า — ปิดงาน = close (tombstone), git = ประวัติ
-// log อยู่ข้างไฟล์นี้เสมอเมื่อถูกวางโดย `fapony init` (<project>/.fapony/.memory/log.jsonl);
-// สำเนากลางใน monorepo (โค้ดชุดเดียวที่ root) ยังแยก log ราย app: apps/<app>/.fapony/.memory/log.jsonl
-// (repo ที่ยังไม่ย้ายซึ่งมี log เก่าที่ apps/<app>/.memory/log.jsonl จะอ่านที่เดิมต่อ)
+// append-only memory log. Never edit old lines — close a task = close (tombstone), git = history
+// the log always sits beside this file when placed by `fapony init` (<project>/.fapony/.memory/log.jsonl);
+// the central copy in a monorepo (single code copy at the root) still splits logs per app: apps/<app>/.fapony/.memory/log.jsonl
+// (a repo not yet migrated with an old log at apps/<app>/.memory/log.jsonl keeps reading that location)
 //
 // CLI entry point — all logic lives in:
 //   store.ts       (types + config + rows/put)
@@ -63,6 +63,6 @@ if (cmd === "add") {
 } else if (cmd === "rotate") {
   cmdRotate(a);
 } else {
-  // mem now (default) — next+bug+hold. decision/note ไม่ใช่งานค้าง → ค้นด้วย find แทน
+  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
   cmdNow();
 }

package/templates/mem/selectors.ts

@@ -8,8 +8,8 @@ import type {
   WorkRow,
 } from "./store.js";
 
-// ponytail: reducer = filter + tombstone set. 50k บรรทัด = 9.6MB/26ms — ไฟล์ไม่ใช่คอขวด
-// เพดานจริง = แถวที่ยังเปิดเยอะจน view อ่านไม่รู้เรื่อง → ตอนนั้นค่อย rotate: git mv + append openRows(เก่า) ลงไฟล์ใหม่
+// ponytail: reducer = filter + tombstone set. 50k lines = 9.6MB/26ms — the file is not the bottleneck
+// the real ceiling = too many open rows for the view to make sense → rotate then: git mv + append openRows(old) into a new file
 export const openRows = (all: LogRow[]): WorkRow[] => {
   const dead = new Set(
     all.filter((r): r is CloseRow => r.kind === "close").map((r) => r.ref),
@@ -25,8 +25,8 @@ export const openRows = (all: LogRow[]): WorkRow[] => {
   );
 };
 
-// C) claimsOf: คืน Map ref → latest claim row ที่ยัง active
-// active = แถวล่าสุดของ claim|release เป็น claim และ ref ไม่อยู่ใน dead (close)
+// C) claimsOf: returns Map ref → latest claim row still active
+// active = the latest claim|release row is a claim and ref is not in dead (close)
 export const claimsOf = (all: LogRow[]): Map<string, ClaimRow> => {
   const dead = new Set(
     all.filter((r): r is CloseRow => r.kind === "close").map((r) => r.ref),
@@ -46,9 +46,9 @@ export const claimsOf = (all: LogRow[]): Map<string, ClaimRow> => {
   return active;
 };
 
-// decision ที่ใหม่กว่าทั้ง commit ล่าสุดของ spec และ synced marker = spec ยังไม่ได้อัปเดตตาม
-// + next/hold ที่มี spec ถูกแก้หลังสร้าง = อาจปิดไปแล้วแต่ไม่มีใคร close — เคสจริง: msbnndmt
-// + active claim ที่อายุเกิน 4 ชม. = agent อาจตายกลางงาน
+// a decision newer than both the spec's latest commit and the synced marker = spec not updated to match
+// + next/hold whose spec was edited after creation = may be done already but nobody closed it — real case: msbnndmt
+// + an active claim older than 4h = the agent may have died mid-task
 export const staleReport = (all: LogRow[]): string[] => {
   const out: string[] = [];
   const mark: Record<string, number> = {};
@@ -67,7 +67,7 @@ export const staleReport = (all: LogRow[]): string[] => {
   }
   const gitDates = new Map<string, number>();
   for (const spec of specPaths) {
-    // --follow: spec path ที่ถูก git mv (เช่น ย้ายเข้า plan/done/) ยังตามประวัติต่อได้
+    // --follow: a spec path that was git mv'd (e.g. moved into plan/done/) can still follow its history
     const git = Bun.spawnSync([
       "git",
       "log",
@@ -94,9 +94,9 @@ export const staleReport = (all: LogRow[]): string[] => {
   for (const r of openRows(all)) {
     if ((r.kind === "next" || r.kind === "hold") && r.spec) {
       const gitDate = gitDates.get(r.spec);
-      // ponytail: grace 24 ชม. — "log next แล้วเขียน/commit plan ต่อในวันเดียวกัน" คือ workflow ปกติ
-      // ไม่ใช่สัญญาณว่างานจบแล้วลืมปิด (เคสจริงที่ต้องจับอย่าง msbnndmt ห่างกันเป็นวัน) —
-      // ไม่มี grace = SUSPECT ขึ้นทุกแผนที่เพิ่งเขียน แล้วทุกคนเรียนรู้ที่จะเลื่อนผ่าน stale ทั้งบล็อก
+      // ponytail: 24h grace — "log next then write/commit the plan the same day" is normal workflow
+      // not a signal that the work finished and was forgotten (the real case to catch, msbnndmt, is days apart) —
+      // without grace = SUSPECT fires on every freshly written plan, and everyone learns to skim past the whole stale block
       if (gitDate && gitDate > Date.parse(r.ts) + 86_400_000)
         out.push(
           `SUSPECT [${r.id}] ${r.spec} changed after this ${r.kind} (${r.ts.slice(0, 10)}) — check whether it is already done`,
@@ -115,13 +115,13 @@ export const staleReport = (all: LogRow[]): string[] => {
   return out;
 };
 
-// rotate: แถวที่ต้องแบกต่อในไฟล์ log ใหม่หลัง archive
-// - next/bug/hold ที่ยังเปิด + claim ที่ยัง active อยู่บนแถวนั้น (close/claim ของ ref ที่ปิดแล้ว = ทิ้งได้)
-// - decision/note ยังไม่มี "close" ของตัวเอง (ประวัติถาวรตามดีไซน์) แต่ resolved ได้ทางอ้อมผ่าน synced:
-//   spec ถูก synced *หลัง* แถวนี้แล้ว = ข้อมูลเข้า spec แล้วจริง เก็บใน archive (git) พอ ไม่ต้องแบกในไฟล์ hot
-//   (logic เดียวกับ staleReport's decision check — ไม่มี spec หรือยังไม่ synced ทันแถวนี้ = ยังถือว่า relevant, เก็บไว้)
-// ponytail: decision/note ที่ไม่มี spec ไม่มีทางรู้ว่า resolved แล้วหรือยัง — เก็บไว้ตลอด (เพดานจริงคือ
-// ต้อง attach spec ตั้งแต่ log ถ้าอยากให้ rotate ออกได้ในอนาคต ไม่ใช่ปัญหาของ rotate เอง)
+// rotate: rows that must carry over into the new log file after archiving
+// - open next/bug/hold + still-active claims on those rows (close/claim of already-closed refs = discardable)
+// - decision/note has no "close" of its own (permanent history by design) but resolves indirectly via synced:
+//   spec was synced *after* this row = the info really made it into the spec, archive (git) is enough, no need to carry it in the hot file
+//   (same logic as staleReport's decision check — no spec or not yet synced by this row = still considered relevant, keep it)
+// ponytail: a decision/note with no spec gives no way to know if it is resolved — keep it forever (the real ceiling is
+// attaching a spec at log time if you want rotate to be able to drop it later, not rotate's own problem)
 export const rotateKeep = (all: LogRow[]): LogRow[] => {
   const open = openRows(all);
   const workOpen = open.filter(

package/templates/mem/store.ts

@@ -60,43 +60,43 @@ type LogRow = WorkRow | CloseRow | ClaimRow | ReleaseRow | SyncedRow;
 const root = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"])
   .stdout.toString()
   .trim();
-// ponytail: worktree ชื่อ wt-<app> = monorepo scope (apps/<app>/.fapony/.memory).
-// fapony template: repo เดี่ยว (ไม่มี apps/) → fallback ไป .fapony/.memory ที่ root ตรงๆ
-// ไม่ต้อง config/flag ทั้งสองแบบ
+// ponytail: worktree named wt-<app> = monorepo scope (apps/<app>/.fapony/.memory).
+// fapony template: single repo (no apps/) → fallback straight to .fapony/.memory at root
+// no config/flag needed for either shape
 const app = process.env.MEM_APP ?? basename(root).replace(/^wt-/, "");
-// โฟลเดอร์รวม app หาจาก {apps,packages,services}/<app> ตัวแรกที่มีจริง — ลำดับคงที่
-// apps → packages → services ตัวแรกที่เจอชนะ (ลำดับคือสัญญา ไม่ใช่บังเอิญ)
-// guard `unknown app` ข้างล่างยังผูกกับ apps/ เหมือนเดิม — ไม่ขยายในรอบนี้
+// app container folder found from {apps,packages,services}/<app>, first that exists — fixed order
+// apps → packages → services, first hit wins (the order is the contract, not an accident)
+// the `unknown app` guard below is still tied to apps/ as before — not widened this round
 const appBase: string | undefined = ["apps", "packages", "services"]
   .map((d) => `${root}/${d}/${app}`)
   .find((p) => existsSync(p));
 const monorepo = appBase !== undefined;
 
-// สำเนาที่ `fapony init` วางไว้ อยู่ใน <project>/.fapony/.memory/ — log กับ plan ของมัน
-// ต้องอิงโฟลเดอร์ตัวเอง ไม่ใช่ git root: เคสที่พังจริงคือ apps/<x>/.fapony/.memory/ ใน monorepo
-// ซึ่ง heuristic ด้านล่างจะชี้ไป apps/<ชื่อ worktree>/.fapony/.memory = เขียน log ปนโปรเจกต์อื่น
-// แต่สำเนากลางที่ย้ายเข้า .fapony/.memory ที่ root ของ monorepo เอง (โค้ดชุดเดียว, log แยกราย
-// app — เช่น vela) ต้อง "ไม่" ถือเป็น scaffolded แม้ path จะแมตช์เหมือนกัน เพราะยังต้องเดา app
-// จาก monorepo อยู่ — ตัวแยกคือ "เดา app ได้ไหม" (`monorepo`) ไม่ใช่ "มีโฟลเดอร์รวม app ไหม":
-// แค่มี apps/ อยู่ที่ root ไม่ได้แปลว่าสำเนานี้เป็นสำเนากลาง — `fapony init <monorepo root>` ก็วาง
-// .fapony/.memory ที่ root เหมือนกัน แล้วมันต้องอิงโฟลเดอร์ตัวเอง ไม่งั้นตายที่ guard ข้างล่าง
-// ตั้งแต่คำสั่งแรกทั้งที่ plan ของมันอยู่ข้าง ๆ นั่นเอง
+// The copy `fapony init` places lives in <project>/.fapony/.memory/ — its log and plan
+// must key off their own folder, not the git root: the real broken case is apps/<x>/.fapony/.memory/ in a monorepo,
+// where the heuristic below would point at apps/<worktree name>/.fapony/.memory = writing a log mixed into another project.
+// But the central copy that was moved into .fapony/.memory at the monorepo root itself (single code copy, logs split per
+// app — e.g. vela) must "not" count as scaffolded even though the path matches, because it still has to guess the app
+// from the monorepo — the discriminator is "can the app be guessed" (`monorepo`), not "is there an app container folder":
+// just having apps/ at the root does not make this copy the central one — `fapony init <monorepo root>` also places
+// .fapony/.memory at the root, and it must key off its own folder, or it dies at the guard below
+// from the very first command even though its plan sits right next to it.
 const centralAtMonorepoRoot =
   import.meta.dir === `${root}/.fapony/.memory` && monorepo;
 const scaffolded =
   import.meta.dir.includes("/.fapony/.memory") && !centralAtMonorepoRoot;
 
-// มี apps/ แต่ไม่มี apps/<app> = เดา app ผิด (worktree ชื่อไม่ตรง / typo ใน MEM_APP) — ตายตรงนี้
-// ดีกว่า fallback เงียบ ๆ ไปเขียน log ที่ root ซึ่งจะกลายเป็น log กำพร้าที่ไม่มีใครอ่าน
-// (สำเนาที่ scaffold ไว้ใต้ apps/<x>/.fapony/.memory/ อิงโฟลเดอร์ตัวเอง ไม่ต้องเดา จึงไม่เข้าเงื่อนไขนี้)
+// apps/ exists but apps/<app> does not = guessed the app wrong (worktree name mismatch / typo in MEM_APP) — die here
+// rather than fall back silently and write a log at the root that becomes an orphan nobody reads
+// (a copy scaffolded under apps/<x>/.fapony/.memory/ keys off its own folder, needs no guess, so it does not hit this)
 if (!scaffolded && !monorepo && existsSync(`${root}/apps`)) {
   console.error(
     `unknown app (guessed "${app}" from ${basename(root)}) — pass MEM_APP=<app>`,
   );
   process.exit(1);
 }
-// default ใหม่: log อยู่ใต้ .fapony/.memory — fallback ไป .memory/ เดิมเมื่อมี log เก่าอยู่จริง
-// เช็ค log.jsonl ไม่ใช่ dir: โฟลเดอร์ว่างที่ใครเผลอ mkdir ทิ้งไว้ต้องไม่ล็อก repo ไว้กับ layout เก่า
+// new default: log lives under .fapony/.memory — fall back to the old .memory/ only when an old log actually exists
+// check for log.jsonl, not the dir: an empty folder someone accidentally mkdir'd must not lock the repo to the old layout
 const newDir = appBase
   ? `${appBase}/.fapony/.memory`
   : `${root}/.fapony/.memory`;
@@ -106,12 +106,12 @@ const dir = scaffolded
   : existsSync(`${legacyDir}/log.jsonl`)
     ? legacyDir
     : newDir;
-// ใครเขียนแถวนี้ — client ตั้ง MEM_AGENT ทับได้ ("claude-code", "opencode")
+// who wrote this row — the client can override with MEM_AGENT ("claude-code", "opencode")
 const agent = process.env.MEM_AGENT || process.env.USER || "unknown";
 
-// ชื่อไฟล์ = *คน* ไม่ใช่ client ตั้งใจให้ต่างจาก agent ข้างบน: ถ้าใช้ MEM_AGENT ตั้งชื่อไฟล์
-// สองคนที่เปิด Claude Code จะกลับไปเขียน log.claude-code.jsonl ใบเดียวกัน = ชนเหมือนเดิม
-// git user.name มีอยู่แล้วทุกเครื่องที่ commit ได้ จึงไม่ต้องตั้ง env และไม่ต้องเพิ่ม config
+// filename = *person*, not client, deliberately different from agent above: naming files by MEM_AGENT
+// would put two people running Claude Code back into the same log.claude-code.jsonl = same collision as before
+// git user.name exists on every machine that can commit, so no env to set and no config to add
 const person = (
   Bun.spawnSync(["git", "config", "user.name"]).stdout.toString().trim() ||
   process.env.USER ||
@@ -121,12 +121,12 @@ const person = (
   .replace(/[^a-z0-9._-]+/g, "-")
   .replace(/^-+|-+$/g, "");
 
-// เขียนไฟล์ของตัวเอง อ่านของทุกคน — สองคนไม่เคยแตะไฟล์เดียวกัน = merge conflict
-// เป็นศูนย์โดยโครงสร้าง ไม่ต้องพึ่ง merge=union หรือให้ GitHub ทำตัวดีตอน merge PR
+// write your own file, read everyone's — two people never touch the same file = merge conflicts
+// are structurally zero, no need for merge=union or GitHub behaving itself on PR merge
 const LOG = `${dir}/log.${person || "unknown"}.jsonl`;
 
-// log.jsonl = ของเดิมก่อนแยกไฟล์ (ยังอ่านตลอดไป ไม่ต้อง migrate)
-// ข้าม log.YYYY-MM-DD.jsonl ที่ rotate สร้าง ไม่งั้น rotate จะไม่ลดอะไรเลยเพราะอ่านกลับเข้ามา
+// log.jsonl = the pre-split original (still read forever, no migration needed)
+// skip the log.YYYY-MM-DD.jsonl that rotate creates, or rotate reduces nothing because they get read back in
 const isLogFile = (f: string): boolean =>
   f === "log.jsonl" ||
   (/^log\.[A-Za-z0-9._-]+\.jsonl$/.test(f) &&
@@ -140,17 +140,17 @@ const logFiles = (): string[] =>
         .map((f) => join(dir, f))
     : [];
 
-// โฟลเดอร์ที่ plan/ กับ done/ ของโปรเจกต์นี้อยู่ใต้มัน — จุดเดียวที่ประกอบ path เหล่านี้
-// (ก่อนหน้านี้ commands/plan.ts hardcode `apps/<app>/plan` 10 จุด = ตายสนิทกับ repo เดี่ยว)
+// the folder this project's plan/ and done/ live under — the single place these paths are assembled
+// (previously commands/plan.ts hardcoded `apps/<app>/plan` in 10 places = dead on arrival for a single repo)
 const planBase = scaffolded
   ? dirname(import.meta.dir) // <project>/.fapony
   : (appBase ?? root);
 
-// fapony.config.json คือ *ข้อตกลง* ว่า plan อยู่ไหน ส่วน planBase ข้างบนเป็นแค่การเดา —
-// มีไฟล์เมื่อไหร่ต้องชนะการเดาเสมอ (vela ประกาศ `apps/vela/plan` ไว้ตรง ๆ บังเอิญตรงกับที่เดาได้
-// แต่ repo ที่วาง plan ไว้ที่อื่นจะพังเงียบ ๆ ถ้าไม่อ่าน)
-// อ่านที่ระดับโปรเจกต์เท่านั้น: สำเนาที่ scaffold ใน apps/<x>/.fapony/ ต้องไม่หยิบ config ของ
-// monorepo ที่ root มาใช้ เพราะนั่นเป็น path ของอีกโปรเจกต์หนึ่ง
+// fapony.config.json is the *agreement* on where plan lives; planBase above is only a guess —
+// whenever the file exists it must beat the guess (vela declares `apps/vela/plan` outright, which happens to match the guess
+// but a repo that puts plan elsewhere breaks silently if this is not read)
+// read only at the project level: a copy scaffolded in apps/<x>/.fapony/ must not pick up the root
+// monorepo's config, because that is another project's path
 const configDir = scaffolded ? dirname(planBase) : root;
 
 const configPaths = ((): Record<string, string> => {
@@ -158,7 +158,7 @@ const configPaths = ((): Record<string, string> => {
     const raw = readFileSync(`${configDir}/fapony.config.json`, "utf8");
     return (JSON.parse(raw)?.paths ?? {}) as Record<string, string>;
   } catch {
-    // ไม่มีไฟล์ / JSON เสีย → ใช้ค่าที่เดาได้ ไม่ใช่ error: memory ต้องทำงานได้โดยไม่มี fapony
+    // no file / broken JSON → use the guessed values, not an error: memory must work without fapony
     return {};
   }
 })();
@@ -168,27 +168,27 @@ const fromConfig = (key: string): string | null =>
     ? join(configDir, configPaths[key])
     : null;
 
-// app ที่ย้าย plan เข้า .fapony/ แล้วให้ใช้ของใหม่ ที่ยังไม่ย้ายใช้ของเดิม — โมโนเรโปจึงย้ายทีละ app ได้
-// โดยไม่ต้องแตะ config (config มี planDir ค่าเดียว ประกาศเมื่อไหร่ app อื่นก็ชี้ผิดตามไปด้วย)
+// an app that moved plan into .fapony/ uses the new location; one that has not uses the old — so a monorepo migrates app by app
+// without touching config (config has a single planDir, so declaring it points the other apps wrong too)
 const base = existsSync(`${planBase}/.fapony`)
   ? `${planBase}/.fapony`
   : planBase;
 
 const planDir = fromConfig("planDir") ?? `${base}/plan`;
 
-// done/ อยู่ข้าง plan/ (ย้ายแล้วลึกเท่าเดิม ลิงก์ relative ในไฟล์รอด) — repo ที่ยัง layout เก่า
-// เก็บ plan/done/ ไว้ ก็ใช้ของเดิมต่อ ไม่ต้องย้ายก่อนถึงจะ sweep ได้
+// done/ sits beside plan/ (same depth after the move, relative links in files survive) — a repo still on the old layout
+// with plan/done/ keeps using it, no need to move before sweeping
 const doneDir =
   fromConfig("doneDir") ??
   (!existsSync(`${base}/done`) && existsSync(`${planDir}/done`)
     ? `${planDir}/done`
     : `${base}/done`);
 
-// path ที่เอาไว้โชว์/บันทึกลง log — อิง repo root เสมอ (`apps/vela/plan`, `.fapony/plan`)
+// path used for display/logging — always relative to repo root (`apps/vela/plan`, `.fapony/plan`)
 const rel = (p: string) => relative(root, p) || ".";
 
-// คำสั่งที่บอกให้ผู้ใช้พิมพ์ ต้องเป็น path ของ mem.ts ตัวที่กำลังรันอยู่จริง ไม่ใช่ค่าคงที่ —
-// สำเนาที่ `fapony init` วางไว้อยู่ที่ .fapony/.memory/ ไม่ใช่ .memory/ ที่ help text เดิม hardcode
+// the command we tell the user to type must be the path of the mem.ts actually running, not a constant —
+// the copy `fapony init` places lives in .fapony/.memory/, not the .memory/ the old help text hardcoded
 const memCmd = `bun ${rel(dir)}/mem.ts`;
 
 const KINDS: WorkKind[] = ["next", "bug", "decision", "note", "hold"];
@@ -205,7 +205,7 @@ const rows = (): LogRow[] =>
           try {
             return [JSON.parse(l) as LogRow];
           } catch {
-            // ponytail: 1 บรรทัดพัง (escape เสีย) ไม่ควรทำให้ทั้ง log อ่านไม่ได้ — ข้ามแล้วเตือน
+            // ponytail: one broken line (bad escape) must not make the whole log unreadable — skip it and warn
             console.error(
               `[mem] skipped ${basename(f)} line ${i + 1} (bad JSON)`,
             );
@@ -213,7 +213,7 @@ const rows = (): LogRow[] =>
           }
         }),
     )
-    // หลายไฟล์ต่อกันแล้วลำดับเวลาสลับ — ทุก selector อ่านจากบนลงล่างโดยถือว่าเรียงตาม ts
+    // concatenating several files scrambles the time order — every selector reads top-down assuming ts order
     .sort((a, b) => a.ts.localeCompare(b.ts));
 
 function put(r: Omit<WorkRow, "ts" | "agent">): void;
@@ -236,9 +236,9 @@ function put(
   );
 }
 
-// ponytail: กัน id ชน — base36 + increment ต่อ retry + random suffix
-// ใช้ร่วมกันทุกที่ที่ต้อง generate WorkRow.id (cmdAdd, ship-log ใน cmdPlanSweep)
-// ห้าม copy loop นี้ไปวางที่ใหม่ — แก้ scheme ที่นี่ที่เดียว
+// ponytail: prevent id collisions — base36 + increment per retry + random suffix
+// shared everywhere a WorkRow.id must be generated (cmdAdd, ship-log in cmdPlanSweep)
+// do not copy this loop elsewhere — change the scheme here only
 function nextId(all: LogRow[]): string {
   const used = new Set(all.map((r) => ("id" in r ? r.id : "")));
   let base = Date.now();
@@ -250,8 +250,8 @@ function nextId(all: LogRow[]): string {
   return id;
 }
 
-// เขียนแถวดิบ (ts/agent เดิม ไม่ generate ใหม่) — ใช้ตอน rotate ย้าย row เก่าไปไฟล์ใหม่
-// ปกติเขียน log ต้องผ่าน put() เท่านั้น อันนี้ทางเดียวที่ยกเว้น
+// write a raw row (original ts/agent, no regeneration) — used when rotate moves old rows to a new file
+// normally writing to the log must go through put(); this is the only exception
 const appendRaw = (path: string, r: LogRow): void =>
   appendFileSync(path, `${JSON.stringify(r)}\n`);