rodo-spec 2.3.0 → 2.4.0

package/README.md

@@ -170,6 +170,7 @@ The CLI executable is `rodo`. Global flags `--project <slug>`, `--lang <fa|en>`,
 | :--- | :--- | :--- |
 | `rodo init` | `[--method-only] [--project <slug>] [--name <name>] [--lang <fa\|en>] [--connect <code>] [--board <id>] [--create-board] [--server <url>] [--no-kit-update] [--dry-run] [--yes-files]` | Installs or updates the RODO kit, scaffolds `rodo/<project>/`, and optionally binds & syncs with a board. |
 | `rodo new` | `"<title>" [--slug <kebab-slug>] [--major] [--dry-run] [--project <slug>]` | Creates the next `rodo/<project>/cycles/NNN-slug/` folder with `card.rodo.md`, `simple.md`, and `spec.md`. |
+| `rodo explain` | `[card] [--project <slug>]` | Describes a card in plain, non-technical words (what you get, state, steps left). |
 | `rodo resume` | `[card] [--full] [--project <slug>]` | Prints compact context of the active or specified card for an AI session (`--full` includes architecture & `simple.md`). |
 | `rodo validate` | `[paths...] [--strict] [--project <slug>]` | Validates card files and cycle references (`--strict` exits with code `1` on errors for CI). |
 | `rodo test` | `[card] [--adapter <web\|api\|cli\|mobile\|iot\|other>] [--project <slug>]` | Runs the card's test command and tracks repeated failure signatures (`RODO_STUCK`). |

package/dist/index.js

@@ -11057,7 +11057,7 @@ function ensureBlock(path, block, kit20Hashes, importsAgents, dryRun = false) {
 // package.json
 var package_default = {
   name: "rodo-spec",
-  version: "2.3.0",
+  version: "2.4.0",
   description: "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
   license: "MIT",
   type: "module",
@@ -11470,8 +11470,8 @@ function parseHours(v) {
 function readFields(data, keyLine, order) {
   const m = emptyModel();
   const out = [];
-  const L = (k) => keyLine[k] ?? null;
-  const add = (code, k, args = {}) => out.push(finding(code, L(k), args));
+  const L2 = (k) => keyLine[k] ?? null;
+  const add = (code, k, args = {}) => out.push(finding(code, L2(k), args));
   for (const k of order) {
     if (KNOWN.has(k) || k.startsWith("x-"))
       continue;
@@ -13088,6 +13088,129 @@ async function runDoctor(ctx) {
   return 0;
 }
 
+// src/core/i18n.ts
+var T = {
+  "resume.none": { fa: "\u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644\u06CC \u067E\u06CC\u062F\u0627 \u0646\u0634\u062F", en: "no active card found" },
+  "resume.several": { fa: "\u0686\u0646\u062F \u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644 \u0647\u0633\u062A\u061B \u06CC\u06A9\u06CC \u0631\u0627 \u0645\u0634\u062E\u0635 \u06A9\u0646\u06CC\u062F", en: "several active cards; name one" },
+  "resume.never": { fa: "\u0627\u06CC\u0646 \u067E\u0631\u0648\u0698\u0647 \u0647\u0646\u0648\u0632 \u0647\u06CC\u0686\u200C\u0648\u0642\u062A sync \u0646\u0634\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "this project has never been synced; run rodo sync" },
+  "resume.stale": { fa: "\u0622\u062E\u0631\u06CC\u0646 sync \u0628\u06CC\u0634 \u0627\u0632 \u06CC\u06A9 \u0633\u0627\u0639\u062A \u067E\u06CC\u0634 \u0628\u0648\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "last sync is older than 1 hour; run rodo sync" },
+  "status.waitingDecision": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0635\u0645\u06CC\u0645 \u0634\u0645\u0627", en: "waiting for your decision" },
+  "status.waitingApproval": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0623\u06CC\u06CC\u062F \u0634\u0645\u0627", en: "waiting for approval" },
+  "test.none": { fa: "\u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u062F\u0633\u062A\u0648\u0631 \u062A\u0633\u062A \u062A\u0639\u0631\u06CC\u0641 \u0646\u0634\u062F\u0647 (\u062A\u0633\u062A \u0627\u062E\u062A\u06CC\u0627\u0631\u06CC \u0627\u0633\u062A)", en: "no test command for this card (tests are optional)" },
+  "offline.note": { fa: "\u062D\u0627\u0644\u062A \u0622\u0641\u0644\u0627\u06CC\u0646: \u0641\u0642\u0637 \u0628\u0631\u0631\u0633\u06CC \u06A9\u0627\u0631\u062A\u200C\u0647\u0627 \u0627\u0646\u062C\u0627\u0645 \u0634\u062F", en: "offline: cards were validated only" }
+};
+function pickLang(flag, projectLang) {
+  return flag === "fa" || flag === "en" ? flag : projectLang === "en" ? "en" : "fa";
+}
+var t = (lang, key2) => T[key2]?.[lang] ?? key2;
+
+// src/commands/shared.ts
+var LEGACY_MSG = "LEGACY_LAYOUT: run rodo init to move rodo/ into rodo/<project>/";
+function load(ctx, defaultToCwd) {
+  const d = discover(ctx.cwd);
+  const refs = selectProjects(d, ctx.opts.project ?? [], defaultToCwd);
+  const broken = refs.find((r) => r.problem);
+  if (broken) throw new CliError("PROJECT_INVALID", `rodo/${broken.slug}: ${broken.problem}`, 3);
+  if (!refs.length) throw notRepo("no RODO project found: run rodo init --method-only");
+  return { d, refs };
+}
+var fmt = (c, f, icon) => `  ${icon} ${c.path}${f.line ? `:${f.line}` : ""}  ${f.message}`;
+function printFindings(ctx, cards) {
+  for (const c of cards) {
+    for (const f of c.errors) ctx.out.line(fmt(c, f, mark.err));
+    for (const f of c.warnings) ctx.out.line(fmt(c, f, mark.warn));
+  }
+}
+var sum = (cards) => ({
+  files: cards.length,
+  errors: cards.reduce((n, c) => n + c.errors.length, 0),
+  warnings: cards.reduce((n, c) => n + c.warnings.length, 0)
+});
+var slim = (f) => ({ code: f.code, line: f.line, message: f.message });
+
+// src/commands/select.ts
+function oneProject(ctx) {
+  const { d, refs } = load(ctx, true);
+  if (refs.length !== 1) throw usage(`several projects (${refs.map((r) => r.slug).join(", ")}): use --project <slug>`);
+  return { d, ref: refs[0] };
+}
+function pickCard(cards, query) {
+  if (query) {
+    const c = findCard(cards, query);
+    if (!c) throw usage(`no card matches "${query}"`);
+    return c;
+  }
+  for (const status of ["in_progress", "blocked"]) {
+    const list = cards.filter((c) => c.model?.status === status);
+    if (list.length === 1) return list[0];
+    if (list.length > 1) throw usage(`several ${status} cards, name one:
+${list.map((c) => `  ${c.number ?? c.key}  ${c.model?.title}`).join("\n")}`);
+  }
+  throw new CliError("NO_ACTIVE_CARD", "no in_progress or blocked card; name one (rodo resume <card>)", 2);
+}
+function projectCards(ctx) {
+  const { d, ref } = oneProject(ctx);
+  return { d, ref, cards: scanCards(d.root, ref) };
+}
+
+// src/commands/explain.ts
+var L = {
+  status_todo: { fa: "\u0628\u0631\u0646\u0627\u0645\u0647\u200C\u0631\u06CC\u0632\u06CC \u0634\u062F\u0647\u060C \u0647\u0646\u0648\u0632 \u0634\u0631\u0648\u0639 \u0646\u0634\u062F\u0647", en: "planned, not started yet" },
+  status_in_progress: { fa: "\u062F\u0631 \u062D\u0627\u0644 \u0627\u0646\u062C\u0627\u0645", en: "in progress" },
+  status_blocked: { fa: "\u0645\u062A\u0648\u0642\u0641 \u0634\u062F\u0647", en: "stopped" },
+  status_cancelled: { fa: "\u0644\u063A\u0648 \u0634\u062F\u0647", en: "cancelled" },
+  status_done: { fa: "\u062A\u0645\u0627\u0645 \u0634\u062F\u0647", en: "finished" },
+  what: { fa: "\u0686\u0647 \u0686\u06CC\u0632\u06CC \u0645\u06CC\u200C\u06AF\u06CC\u0631\u06CC\u062F", en: "What you get" },
+  state: { fa: "\u0648\u0636\u0639\u06CC\u062A", en: "State" },
+  steps: { fa: "\u0642\u062F\u0645\u200C\u0647\u0627", en: "Steps" },
+  left: { fa: "\u0628\u0627\u0642\u06CC\u200C\u0645\u0627\u0646\u062F\u0647", en: "Still to do" },
+  why: { fa: "\u062F\u0644\u06CC\u0644 \u062A\u0648\u0642\u0641", en: "Why it stopped" },
+  noText: { fa: "\u0647\u0646\u0648\u0632 \u062A\u0648\u0636\u06CC\u062D \u0633\u0627\u062F\u0647\u200C\u0627\u06CC \u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u0646\u0648\u0634\u062A\u0647 \u0646\u0634\u062F\u0647", en: "no plain description has been written for this card yet" }
+};
+function intro(body) {
+  const out = [];
+  for (const raw of body.split(/\r?\n/)) {
+    if (raw.startsWith("## ")) break;
+    const l = raw.trim();
+    if (l && !/\{\{.*\}\}/.test(l)) out.push(l);
+  }
+  return out;
+}
+async function runExplain(ctx, query) {
+  const { ref, cards } = projectCards(ctx);
+  const card = pickCard(cards, query);
+  const m = card.model;
+  if (!m) {
+    ctx.out.line(`${card.path} is not a readable card:`);
+    for (const e2 of card.errors) ctx.out.line(`  ${e2.message}`);
+    ctx.out.flush({ version: 1, card: card.key, errors: card.errors });
+    return 2;
+  }
+  const lang = pickLang(ctx.opts.lang, ref.project?.language.simple);
+  const tr = (k) => L[k][lang];
+  const items = m.checklists.flatMap((c) => c.items);
+  const done = items.filter((i) => i.isDone).length;
+  const left = items.filter((i) => !i.isDone).map((i) => i.title).slice(0, 5);
+  const text = intro(m.description);
+  const title = card.number ? cardLabel(card.number, m.title, " \u2014 ") : m.title;
+  ctx.out.line(title);
+  ctx.out.line(`${tr("state")}: ${tr(`status_${m.status}`)}`);
+  if (m.statusReason) ctx.out.line(`${tr("why")}: ${m.statusReason}`);
+  ctx.out.line("");
+  ctx.out.line(`${tr("what")}:`);
+  (text.length ? text : [tr("noText")]).forEach((l) => ctx.out.line(`  ${l}`));
+  if (items.length) {
+    ctx.out.line("");
+    ctx.out.line(`${tr("steps")}: ${done}/${items.length}`);
+    if (left.length) {
+      ctx.out.line(`${tr("left")}:`);
+      left.forEach((l) => ctx.out.line(`  - ${l}`));
+    }
+  }
+  ctx.out.flush({ version: 1, card: card.key, title: m.title, status: m.status, statusReason: m.statusReason ?? null, plain: text, steps: { done, total: items.length }, remaining: left });
+  return 0;
+}
+
 // src/commands/init.ts
 import { existsSync as existsSync14 } from "fs";
 import { basename as basename2, join as join14 } from "path";
@@ -13259,13 +13382,13 @@ function withMarker(raw, marker) {
   const next = bom + (marker ? marker + eol : "") + rest;
   return next === raw ? null : next;
 }
-var slim = (f) => ({ code: f.code, line: f.line, message: f.message });
+var slim2 = (f) => ({ code: f.code, line: f.line, message: f.message });
 function buildReport(slug2, cards, startedAt, over = {}, extra = /* @__PURE__ */ new Map()) {
   const merged = cards.map((c) => {
     const x = extra.get(c.path);
     return { c, errors: [...c.errors, ...x?.errors ?? []], warnings: [...c.warnings, ...x?.warnings ?? []] };
   });
-  const files = merged.filter((m) => m.errors.length || m.warnings.length).map((m) => ({ path: m.c.path, cardId: m.c.model?.id ?? null, errors: m.errors.map(slim), warnings: m.warnings.map(slim) }));
+  const files = merged.filter((m) => m.errors.length || m.warnings.length).map((m) => ({ path: m.c.path, cardId: m.c.model?.id ?? null, errors: m.errors.map(slim2), warnings: m.warnings.map(slim2) }));
   return {
     version: 1,
     project: slug2,
@@ -14022,7 +14145,7 @@ async function runInit(ctx, a) {
     out.line(`project rodo/${slug2}/: ${existsSync14(join14(projectDir, "project.json")) ? "exists (missing files would be added)" : "would be created"}`);
   } else {
     const isNew = !existsSync14(join14(projectDir, "project.json"));
-    const lang = isNew ? await chooseLanguage(ctx) : readProject(projectDir, slug2).project?.language.simple ?? "fa";
+    const lang = isNew ? await chooseLanguage(ctx) : "fa";
     const created = scaffoldProject(root, slug2, a.name ?? slug2, lang);
     if (isNew) data.language = lang;
     out.line(created.length ? `rodo/${slug2}/: created ${created.length} file(s)` : `rodo/${slug2}/: nothing to add`);
@@ -14069,32 +14192,6 @@ async function chooseLanguage(ctx, env = process.env) {
 // src/commands/new.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync10, readdirSync as readdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync3 } from "fs";
 import { join as join15, relative as relative5, sep as sep2 } from "path";
-
-// src/commands/shared.ts
-var LEGACY_MSG = "LEGACY_LAYOUT: run rodo init to move rodo/ into rodo/<project>/";
-function load(ctx, defaultToCwd) {
-  const d = discover(ctx.cwd);
-  const refs = selectProjects(d, ctx.opts.project ?? [], defaultToCwd);
-  const broken = refs.find((r) => r.problem);
-  if (broken) throw new CliError("PROJECT_INVALID", `rodo/${broken.slug}: ${broken.problem}`, 3);
-  if (!refs.length) throw notRepo("no RODO project found: run rodo init --method-only");
-  return { d, refs };
-}
-var fmt = (c, f, icon) => `  ${icon} ${c.path}${f.line ? `:${f.line}` : ""}  ${f.message}`;
-function printFindings(ctx, cards) {
-  for (const c of cards) {
-    for (const f of c.errors) ctx.out.line(fmt(c, f, mark.err));
-    for (const f of c.warnings) ctx.out.line(fmt(c, f, mark.warn));
-  }
-}
-var sum = (cards) => ({
-  files: cards.length,
-  errors: cards.reduce((n, c) => n + c.errors.length, 0),
-  warnings: cards.reduce((n, c) => n + c.warnings.length, 0)
-});
-var slim2 = (f) => ({ code: f.code, line: f.line, message: f.message });
-
-// src/commands/new.ts
 function slugify2(title) {
   return title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").split("-").slice(0, 6).join("-");
 }
@@ -14159,22 +14256,6 @@ async function runNew(ctx, title, o) {
 import { existsSync as existsSync17, readFileSync as readFileSync14 } from "fs";
 import { dirname as dirname8, join as join17 } from "path";
 
-// src/core/i18n.ts
-var T = {
-  "resume.none": { fa: "\u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644\u06CC \u067E\u06CC\u062F\u0627 \u0646\u0634\u062F", en: "no active card found" },
-  "resume.several": { fa: "\u0686\u0646\u062F \u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644 \u0647\u0633\u062A\u061B \u06CC\u06A9\u06CC \u0631\u0627 \u0645\u0634\u062E\u0635 \u06A9\u0646\u06CC\u062F", en: "several active cards; name one" },
-  "resume.never": { fa: "\u0627\u06CC\u0646 \u067E\u0631\u0648\u0698\u0647 \u0647\u0646\u0648\u0632 \u0647\u06CC\u0686\u200C\u0648\u0642\u062A sync \u0646\u0634\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "this project has never been synced; run rodo sync" },
-  "resume.stale": { fa: "\u0622\u062E\u0631\u06CC\u0646 sync \u0628\u06CC\u0634 \u0627\u0632 \u06CC\u06A9 \u0633\u0627\u0639\u062A \u067E\u06CC\u0634 \u0628\u0648\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "last sync is older than 1 hour; run rodo sync" },
-  "status.waitingDecision": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0635\u0645\u06CC\u0645 \u0634\u0645\u0627", en: "waiting for your decision" },
-  "status.waitingApproval": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0623\u06CC\u06CC\u062F \u0634\u0645\u0627", en: "waiting for approval" },
-  "test.none": { fa: "\u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u062F\u0633\u062A\u0648\u0631 \u062A\u0633\u062A \u062A\u0639\u0631\u06CC\u0641 \u0646\u0634\u062F\u0647 (\u062A\u0633\u062A \u0627\u062E\u062A\u06CC\u0627\u0631\u06CC \u0627\u0633\u062A)", en: "no test command for this card (tests are optional)" },
-  "offline.note": { fa: "\u062D\u0627\u0644\u062A \u0622\u0641\u0644\u0627\u06CC\u0646: \u0641\u0642\u0637 \u0628\u0631\u0631\u0633\u06CC \u06A9\u0627\u0631\u062A\u200C\u0647\u0627 \u0627\u0646\u062C\u0627\u0645 \u0634\u062F", en: "offline: cards were validated only" }
-};
-function pickLang(flag, projectLang) {
-  return flag === "fa" || flag === "en" ? flag : projectLang === "en" ? "en" : "fa";
-}
-var t = (lang, key2) => T[key2]?.[lang] ?? key2;
-
 // src/core/time.ts
 var fmtFor = (timeZone) => new Intl.DateTimeFormat("sv-SE", {
   timeZone,
@@ -14431,31 +14512,6 @@ function streak(previous, sig) {
 }
 var STUCK_MESSAGE = (sig) => `RODO_STUCK: the same failure happened twice (${sig}). Per the RODO method: set status: blocked, blockerType: test or technical, write the reason in statusReason, and ask the user.`;
 
-// src/commands/select.ts
-function oneProject(ctx) {
-  const { d, refs } = load(ctx, true);
-  if (refs.length !== 1) throw usage(`several projects (${refs.map((r) => r.slug).join(", ")}): use --project <slug>`);
-  return { d, ref: refs[0] };
-}
-function pickCard(cards, query) {
-  if (query) {
-    const c = findCard(cards, query);
-    if (!c) throw usage(`no card matches "${query}"`);
-    return c;
-  }
-  for (const status of ["in_progress", "blocked"]) {
-    const list = cards.filter((c) => c.model?.status === status);
-    if (list.length === 1) return list[0];
-    if (list.length > 1) throw usage(`several ${status} cards, name one:
-${list.map((c) => `  ${c.number ?? c.key}  ${c.model?.title}`).join("\n")}`);
-  }
-  throw new CliError("NO_ACTIVE_CARD", "no in_progress or blocked card; name one (rodo resume <card>)", 2);
-}
-function projectCards(ctx) {
-  const { d, ref } = oneProject(ctx);
-  return { d, ref, cards: scanCards(d.root, ref) };
-}
-
 // src/commands/resume.ts
 var MAP_WHAT = /^##\s*(این پروژه چیست|What this project is)/i;
 var MAP_WHERE = /^##\s*(الان کجاییم|Where we are)/i;
@@ -14769,18 +14825,7 @@ async function runTest(ctx, query, a) {
 }
 
 // src/commands/validate.ts
-import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
-import { join as join19, resolve as resolve3 } from "path";
-var PROJECT_DOC_LIMITS = { "project/project-overview.md": 500, "project/how-it-works.md": 900 };
-var wordCount = (text) => text.replace(/<!--[\s\S]*?-->/g, " ").split(/\s+/).filter(Boolean).length;
-function longProjectDocs(dir) {
-  return Object.entries(PROJECT_DOC_LIMITS).flatMap(([path, limit]) => {
-    const abs = join19(dir, path);
-    if (!existsSync18(abs)) return [];
-    const words = wordCount(readFileSync17(abs, "utf8"));
-    return words > limit ? [{ path, code: "PROJECT_DOC_TOO_LONG", line: null, message: `PROJECT_DOC_TOO_LONG: ${words} words, the limit is ${limit}; shorten it` }] : [];
-  });
-}
+import { resolve as resolve3 } from "path";
 async function runValidate(ctx, paths, o = {}) {
   const { d, refs } = load(ctx, false);
   const only = paths.map((p) => resolve3(ctx.cwd, p));
@@ -14789,19 +14834,13 @@ async function runValidate(ctx, paths, o = {}) {
   for (const ref of refs) {
     const cards = scanCards(d.root, ref, only);
     const s = sum(cards);
-    const docs = only.length || ref.legacy ? [] : longProjectDocs(ref.dir);
-    s.warnings += docs.length;
     total.files += s.files;
     total.errors += s.errors;
     total.warnings += s.warnings;
     if (ref.legacy) ctx.out.line(LEGACY_MSG);
     ctx.out.line(`rodo/${ref.legacy ? "" : ref.slug}  \u25B8 ${s.files} files \xB7 errors ${s.errors} \xB7 warnings ${s.warnings}`);
     printFindings(ctx, cards);
-    for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim2), warnings: c.warnings.map(slim2) });
-    for (const f of docs) {
-      ctx.out.line(`  ${mark.warn} ${f.path}  ${f.message}`);
-      files.push({ project: ref.slug, path: f.path, errors: [], warnings: [{ code: f.code, line: f.line, message: f.message }] });
-    }
+    for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim), warnings: c.warnings.map(slim) });
   }
   ctx.out.flush({ version: 2, files, summary: total });
   return o.strict && total.errors > 0 ? 1 : 0;
@@ -14816,6 +14855,7 @@ Getting started:
   rodo new "Delete a note"                   start the next cycle (card, simple.md, spec.md)
   rodo validate --strict                     check the cards (exit 1 on errors)
   rodo resume <card>                         context for an AI session
+  rodo explain <card>                        the card in plain words, for you
   rodo test <card>                           run the card test and catch repeated failures
   rodo init --project <slug> --create-board  later: connect a board, then rodo sync`);
   program2.command("init").description("install or update the method kit and create a project folder").option("--name <name>", "display name").option("--server <url>", "board server (default: RODO_SERVER, else the built-in server)").option("--connect <code>", "one-time connect code from the board website (skips the device code)").option("--board <id>", "bind to an existing board").option("--create-board", "create a new board for this project").option("--method-only", "no server: install the kit and create the project folder only").option("--no-kit-update", "skip the kit step").option("--dry-run", "print the plan, write nothing").option("--yes-files", "answer yes to the .gitignore question").addHelpText("after", `
@@ -14832,6 +14872,7 @@ Examples:
   program2.command("status").description("cards and their state").option("--local").action((o) => run((ctx) => runStatus(ctx, o)));
   program2.command("doctor").description("read-only health checks").action(() => run((ctx) => runDoctor(ctx)));
   program2.command("resume [card]").description("print the context of a card for an AI session").option("--full").action((card, o) => run((ctx) => runResume(ctx, card, o)));
+  program2.command("explain [card]").description("describe a card in plain words for the user (read-only)").action((card) => run((ctx) => runExplain(ctx, card)));
   program2.command("test [card]").description("run the card test command and track failure signatures").option("--adapter <adapter>", "web|api|cli|mobile|iot|other").action((card, o) => run((ctx) => runTest(ctx, card, o)));
   program2.command("version").description("versions").action(() => run((ctx) => runVersion(ctx)));
   return program2;

package/dist/kit/.agents/skills/rodo/SKILL.md

@@ -5,7 +5,7 @@ description: RODO project method. Use whenever the repo has a rodo/ folder or *.
 
 > یادداشت فارسی: این مهارت برای AI است. نسخهٔ انسانی همین قواعد در `rodo/<project>/RULES.md` است. RODO فقط «روش کار» است: هیچ ابزاری جلوی commit، تست یا کار را نمی‌گیرد.
 
-# RODO method (kit 2.3.0)
+# RODO method (kit 2.4.0)
 
 RODO is a way of working, not a gate. Nothing blocks a commit, a test or a status. You follow it because it keeps the project understandable for the user, for teammates and for the next AI session.
 
@@ -86,7 +86,8 @@ A card may have `scope: {allowed: [...], forbidden: [...]}`. Stay inside `allowe
 | The repo has code but no `rodo/<project>/` yet | `onboarding.md` |
 | Typo, style, refactor or a fix that does not change described behaviour | `small-change.md` |
 | You write or fix tests (optional, recommended) | `testing.md` |
-| You write or update `project/project-overview.md` or `project/how-it-works.md` | `project-docs.md` |
+| Before closing any card: keep the code small and clean | `clean.md` |
+| Review before closing a MAJOR card, or on request | `review.md` |
 
 ## Workflow levels
 
@@ -123,7 +124,7 @@ Do not turn ordinary clarification questions into `## Decision:` sections, and d
 
 | Kind | Files | Rule |
 |---|---|---|
-| **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. One exception: a planned part in `project-overview.md` (unticked) or `how-it-works.md` (marked `(planned)`) may describe work not built yet (`project-docs.md`). |
+| **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. |
 | **ACTIVE CYCLE** | the docs of the card you are working on (`simple.md`, `spec.md`, `design.md`, `acceptance.feature`) | Must match the code when the card is done. |
 | **HISTORICAL** | docs of `done` and `cancelled` cycles | Never rewritten. A later card refers to them; a new decision goes into the new card and `MEMORY.md`. |
 
@@ -143,8 +144,6 @@ Run the checks that fit this change with the project's own tools; RODO runs noth
         project.json                  board binding and settings (no secrets)
         MAP.md  MEMORY.md  RULES.md  CHANGELOG.md
         project/{brief,architecture,glossary}.md
-        project/project-overview.md   the project for a client, parts with ticks
-        project/how-it-works.md       how each part works, for a beginner
         cycles/NNN-slug/
           card.rodo.md                the card (synced with the board, not in git)
           simple.md                   plain explanation (shown read-only on the web)
@@ -162,6 +161,7 @@ Card format details: the comments in `templates/card.rodo.md` and `rodo validate
 | `rodo sync` | start and end of every session |
 | `rodo resume [card] [--full]` | context for a new session |
 | `rodo status` | board vs local, side by side |
+| `rodo explain [card]` | the card in plain words, for the user |
 | `rodo test [card]` | run the card's test command, record the failure signature |
 | `rodo new "<title>"` | create the next cycle folder with `card.rodo.md`, `simple.md`, `spec.md` (`--major` adds `design.md` and `acceptance.feature`) |
 | `rodo validate` | check card files (never blocks; `--strict` exits 1 on errors, for CI) |

package/dist/kit/.agents/skills/rodo/clean.md

@@ -0,0 +1,33 @@
+# Clean code formulas
+
+Short rules for code you write or touch in a card. They keep the project small and easy to extend. Apply them to the files of this card only; never start a repo-wide cleanup without a card of its own.
+
+## The formulas
+
+| Rule | Limit |
+|---|---|
+| One function does one thing | about 30 lines |
+| One file has one reason to change | about 300 lines; split by responsibility, not by size alone |
+| Parameters | 3 or fewer; more → pass one object |
+| Nesting | 3 levels or fewer; use early `return` |
+| Repetition | the third copy becomes a shared function; two copies stay (do not guess early) |
+| Names | say what, not how (`overdueInvoices`, not `list2`); no abbreviations the glossary does not know |
+| Comments | only the *why*; delete comments that repeat the code |
+| Dead code | delete it (git remembers); never comment code out |
+| New dependency | only if it replaces more than ~50 lines you would write and keep; mention it in `spec.md` `## Decisions` |
+| Extension | add a new file or a new entry in a list, not a new `if` inside a long function |
+
+## Order of work (every card)
+
+1. Make it work (R-rules pass).
+2. Read your own diff once. Apply the formulas above to what you changed.
+3. Remove what is now unused: imports, variables, files, docs that describe the removed behaviour.
+4. Match the surrounding style (naming, comment density, error handling). Do not reformat code you did not change.
+5. Re-run the checks. Cleaning must not change behaviour.
+6. Tick the card's `Cleanup done` step and write `- Cleaned: <what you simplified, or "nothing needed">` in Progress notes.
+
+## Boundaries
+
+- A cleanup that touches files outside the card's `scope.allowed` is a new card (SKILL.md "Scope").
+- If a formula forces a large rewrite, do not do it silently: write `- Out of scope: <refactor> → new card` and tell the user.
+- Prefer deleting over adding. The best change is the one with fewer lines for the same behaviour.

package/dist/kit/.agents/skills/rodo/coder.md

@@ -1,83 +1,86 @@
-> یادداشت فارسی: دستورالعمل کدنویس. از روی کارت کار کن، فقط ارجاع‌ها را بخوان، قدم‌به‌قدم جلو برو، سندها را درست نگه دار، و آخر هر جلسه «Progress notes» را به‌روز کن. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
-
-# Coder playbook
-
-You implement one card. Any model may do this; the user chooses.
-
-## Before you start (every session)
-
-Follow "Session start" in SKILL.md (git check without pulling → rodo sync → rodo resume → refs only → approval check → answered decisions). Then set `status: in_progress`.
-
-## Doing the steps
-
-For each unticked step, in order:
-1. Do only what the step says.
-2. Check it (unit test, build, or the command the step names).
-3. Tick it `- [x]`; add `[hours: H:MM]` only if you know the real time.
-4. Commit with the card number in the message, e.g. `feat: discount code input [cycle 002]`, so people can find the work later.
-
-If your change makes a project doc wrong (`project/*`, the card's `spec.md`), fix the doc in the same commit.
-
-## Tests (if the card has scenarios)
-
-- Step definitions go in the folder from `project.json` `stepsDirs`. They must really drive the app (browser, API or CLI) and really assert. See `testing.md`.
-- Run the card's tests with `rodo test` (it uses the card's `test.command`, or `testCommand` from `project.json`). Tick `تست پذیرش پاس شد` only after a real passing run.
-- **Never weaken a scenario or test to make code pass:** no deleting scenarios, loosening assertions, `@skip`/`.only`/`test.fixme`, or changing an expected value to match buggy output. If a scenario looks wrong, explain why to the user; change it only if they agree.
-
-## Scope changes while coding
-
-- Out of the card's `scope` or a new requirement: do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes and tell the user.
-- Small change in the same feature: update the scenario/spec/steps of this card, tell the user, continue (wait if there is an unticked approval item).
-- Big new feature: do not add it. Write it under `- Remaining:` as "needs a new card" and tell the user.
-
-## Stuck
-
-Use the stuck rule in SKILL.md: same failure signature twice → `status: blocked`, `blockerType: test` or `technical`, a plain `statusReason:`, ask the user. Waiting for an answer, a key or another card → `status: blocked` with the matching `blockerType` (`decision`, `permission`, `external`). If only the user can choose, write a `## Decision:` section (SKILL.md). When solved: `status: in_progress`, remove `statusReason` and `blockerType`. Never set `cancelled` yourself; only with the user's OK.
-
-## Verify and fix
-
-**VERIFY** — pick the checks that fit this change and run them with the project's own tools (RODO runs nothing itself):
-- build, typecheck, lint;
-- unit, integration, e2e;
-- architecture rules, security checks;
-- acceptance (the card's `test` command via `rodo test`, or the acceptance criteria checked one by one);
-- documentation consistency (below).
-
-Write the result in Progress notes as `- Verified: <check> ✓/✗, …`.
-
-**Documentation Consistency** (part of VERIFY):
-- Check that every file listed under Documentation Impact was updated.
-- Check that the CURRENT docs and the active cycle docs still describe the code.
-- If something does not match: FIX, then VERIFY again.
-- If a current doc contradicts a `MEMORY.md` decision, stop and ask the user (as small-change.md already says).
-
-**REVIEW (optional; recommended for MAJOR)** — an independent AI session or model reads the change and checks:
-- requirement coverage; acceptance criteria;
-- regressions; architecture fit;
-- missing tests; maintainability;
-- unintended changes.
-
-A review never replaces tests. Its findings go back to FIX.
-
-**FIX loop** — FIX → VERIFY until everything passes (→ DONE) or the stuck rule applies: the **same failure twice** (same failure signature, or the same error at the same place) → `status: blocked` with `blockerType: test` or `technical` (SKILL.md "Stuck rule"). Different failures do not count.
-
-## End of every session
-
-Follow "Session close" in SKILL.md. Always finish with `rodo sync`.
-
-## Close (all steps ticked)
-
-The folder does not move.
-1. Card: `status: done`.
-2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
-3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
-4. `project/project-overview.md` and `project/how-it-works.md`: make them match what was built and tick the part if all of it is finished (`project-docs.md`).
-5. Commit the MAP, MEMORY and project docs change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
-
-## Rules
-
-- Never tick an approval item or change its text. Only a person can approve, in the web app. Never answer a `## Decision:` yourself.
-- Never edit `id:` lines or `<!-- rodo:... -->` comments.
-- Do not change `members`, `startAt`, `dueAt`, `priority` unless the user asks: the team owns them.
-- Never delete files you did not create in this card without asking.
-- Keep changes inside the steps. Unrelated fixes go to `small-change.md` or a new card.
+> یادداشت فارسی: دستورالعمل کدنویس. از روی کارت کار کن، فقط ارجاع‌ها را بخوان، قدم‌به‌قدم جلو برو، سندها را درست نگه دار، و آخر هر جلسه «Progress notes» را به‌روز کن. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
+
+# Coder playbook
+
+You implement one card. Any model may do this; the user chooses.
+
+## Before you start (every session)
+
+Follow "Session start" in SKILL.md (git check without pulling → rodo sync → rodo resume → refs only → approval check → answered decisions). Then set `status: in_progress`.
+
+## Doing the steps
+
+For each unticked step, in order:
+1. Do only what the step says.
+2. Check it (unit test, build, or the command the step names).
+3. Tick it `- [x]`; add `[hours: H:MM]` only if you know the real time.
+4. Commit with the card number in the message, e.g. `feat: discount code input [cycle 002]`, so people can find the work later.
+
+If your change makes a project doc wrong (`project/*`, the card's `spec.md`), fix the doc in the same commit.
+
+## Tests (if the card has scenarios)
+
+- Step definitions go in the folder from `project.json` `stepsDirs`. They must really drive the app (browser, API or CLI) and really assert. See `testing.md`.
+- Run the card's tests with `rodo test` (it uses the card's `test.command`, or `testCommand` from `project.json`). Tick `تست پذیرش پاس شد` only after a real passing run.
+- **Never weaken a scenario or test to make code pass:** no deleting scenarios, loosening assertions, `@skip`/`.only`/`test.fixme`, or changing an expected value to match buggy output. If a scenario looks wrong, explain why to the user; change it only if they agree.
+
+## Scope changes while coding
+
+- Out of the card's `scope` or a new requirement: do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes and tell the user.
+- Small change in the same feature: update the scenario/spec/steps of this card, tell the user, continue (wait if there is an unticked approval item).
+- Big new feature: do not add it. Write it under `- Remaining:` as "needs a new card" and tell the user.
+
+## Stuck
+
+Use the stuck rule in SKILL.md: same failure signature twice → `status: blocked`, `blockerType: test` or `technical`, a plain `statusReason:`, ask the user. Waiting for an answer, a key or another card → `status: blocked` with the matching `blockerType` (`decision`, `permission`, `external`). If only the user can choose, write a `## Decision:` section (SKILL.md). When solved: `status: in_progress`, remove `statusReason` and `blockerType`. Never set `cancelled` yourself; only with the user's OK.
+
+## Verify and fix
+
+**VERIFY** — pick the checks that fit this change and run them with the project's own tools (RODO runs nothing itself):
+- build, typecheck, lint;
+- unit, integration, e2e;
+- architecture rules, security checks;
+- acceptance (the card's `test` command via `rodo test`, or the acceptance criteria checked one by one);
+- documentation consistency (below).
+
+Write the result in Progress notes as `- Verified: <check> ✓/✗, …`.
+
+**Documentation Consistency** (part of VERIFY):
+- Check that every file listed under Documentation Impact was updated.
+- Check that the CURRENT docs and the active cycle docs still describe the code.
+- If something does not match: FIX, then VERIFY again.
+- If a current doc contradicts a `MEMORY.md` decision, stop and ask the user (as small-change.md already says).
+
+**REVIEW (optional; recommended for MAJOR)** — an independent AI session or model reads the change and checks:
+- requirement coverage; acceptance criteria;
+- regressions; architecture fit;
+- missing tests; maintainability;
+- unintended changes.
+
+A review never replaces tests. Its findings go back to FIX.
+
+**FIX loop** — FIX → VERIFY until everything passes (→ DONE) or the stuck rule applies: the **same failure twice** (same failure signature, or the same error at the same place) → `status: blocked` with `blockerType: test` or `technical` (SKILL.md "Stuck rule"). Different failures do not count.
+
+## Clean before you close
+
+When the steps are done and verified, follow `clean.md` (and `review.md` for MAJOR), then tick `Cleanup done`.
+
+## End of every session
+
+Follow "Session close" in SKILL.md. Always finish with `rodo sync`.
+
+## Close (all steps ticked)
+
+The folder does not move.
+1. Card: `status: done`.
+2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
+3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
+4. Commit the MAP and MEMORY change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
+
+## Rules
+
+- Never tick an approval item or change its text. Only a person can approve, in the web app. Never answer a `## Decision:` yourself.
+- Never edit `id:` lines or `<!-- rodo:... -->` comments.
+- Do not change `members`, `startAt`, `dueAt`, `priority` unless the user asks: the team owns them.
+- Never delete files you did not create in this card without asking.
+- Keep changes inside the steps. Unrelated fixes go to `small-change.md` or a new card.

package/dist/kit/.agents/skills/rodo/onboarding.md

@@ -8,7 +8,7 @@ Goal: create `rodo/<project>/` so the project can follow the method, without cha
 
 1. **Read, do not write.** Read README, existing docs, package files, folder structure, git log (last ~100 commits), and TODO/FIXME comments. Skim code by folder; do not read every file.
 2. **Create the skeleton**: run `rodo init --method-only --project <slug>` (if the CLI is installed), or copy `project-template/` into `rodo/<slug>/` yourself. It never overwrites an existing file. Set `language` in `project.json` if the user wants other languages.
-3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm. Then write `project/project-overview.md` and `project/how-it-works.md` the same way (`project-docs.md`), ticking only parts that already work.
+3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm.
 4. **MEMORY.md**: decisions visible in the code or docs (framework, database, auth method...). One line each with the reason if known, else `چون: نامعلوم`.
 5. **Finished work → done cycles.** For each finished feature a user can see, create `rodo/<project>/cycles/NNN-slug/` with:
    - `simple.md` whose FIRST line is `<!-- rodo:onboarded -->`, then 3-6 simple lines;

package/dist/kit/.agents/skills/rodo/planner.md

@@ -24,7 +24,6 @@ Yes, for every new feature, change or improvement, and for every change to behav
 - List the current documents this change will make wrong or must extend.
 - Use `MAP.md`, `MEMORY.md`, `project/*`, the active cycle, the card's refs, and a code search (Graphify or similar, if available in the project).
 - Write the list in `spec.md` `## Documentation Impact` (`- <path> — <what changes>`, or `- none — <why>`).
-- **Project docs first:** if a new feature or major change does not fit `project/project-overview.md` or `project/how-it-works.md`, update them before BUILD, following `project-docs.md`. If they are still templates, fill them first.
 - QUICK: do this in your head and fix any doc you made wrong (small-change.md).
 
 ## Classify

package/dist/kit/.agents/skills/rodo/review.md

@@ -0,0 +1,30 @@
+# Review checklists
+
+Use before closing a MAJOR card (recommended) or whenever the user asks for a review. A review reads the diff; it never replaces tests. Report findings in plain words, most serious first, and fix them (FIX → VERIFY).
+
+## 1. Simplify (always)
+
+- Anything duplicated, over-built, or unused in the diff?
+- Could a simpler existing function or library call replace new code?
+- Follow `clean.md`.
+
+## 2. Correctness
+
+- Does each R-rule of `spec.md` have code and, if tests are used, a test?
+- Edge cases: empty input, missing value, very large input, two things happening at once.
+- Errors: are they handled or reported, never swallowed?
+
+## 3. Security (quick pass)
+
+- No secrets in code, config, logs, cards or commit messages.
+- Input from outside (forms, URLs, files, env) is checked before use; no string-built SQL, shell commands or HTML.
+- Access: every new route or action checks who is calling.
+- New dependencies: known, maintained, and necessary.
+
+## 4. Plain words
+
+- Does the card's opening text (what the user gets) and `simple.md` still describe what the code now does? Run `rodo explain <card>` and read it as if you were not a developer.
+
+## Optional external skills
+
+If the project or the user's tools already provide them, you may use `simplify`, `code-review`, `security-review` or Graphify (code map). Never install them yourself; RODO works without them. Treat their output as advice and verify it before acting.

package/dist/kit/.agents/skills/rodo/templates/card.rodo.md

@@ -11,7 +11,7 @@ scope:
   forbidden: []
 ---
 
-{{دو تا پنج خط ساده: کاربر چه چیزی می‌گیرد. جزئیات در spec.md است.}}
+{{دو تا پنج خط ساده و بدون اصطلاح فنی: کاربر چه چیزی می‌گیرد. دستور rodo explain همین را به کاربر نشان می‌دهد. جزئیات در spec.md است.}}
 
 ## Progress notes
 
@@ -30,4 +30,5 @@ scope:
 <!-- - [ ] تأیید کاربر: simple.md و سناریوها [approval] — add only when the user asked for a human approval (D5) -->
 - [ ] {{قدم ۱: کار مشخص + نشانهٔ انجام شدن}}
 - [ ] {{قدم ۲}}
+- [ ] تمیزکاری انجام شد (clean.md)
 - [ ] تست پذیرش پاس شد

package/dist/kit/.agents/skills/rodo/templates/en/card.rodo.md

@@ -1,32 +1,33 @@
----
-schemaVersion: 2
-title: "{{short title}}"
-status: todo
-# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
-priority: medium
-# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
-members: []
-scope:
-  allowed: []
-  forbidden: []
----
-
-{{two to five plain lines: what the user gets. Details are in spec.md.}}
-
-## Progress notes
-
-- Updated: {{YYYY-MM-DD}}
-- Done: not started yet
-- Remaining: all steps
-
-## Refs
-
-- [Plain explanation](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
-- [Technical spec](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
-<!-- [Acceptance scenarios](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
-
-## Checklist: Steps
-
-<!-- - [ ] User approval: simple.md and scenarios [approval] — add only when the user asked for a human approval -->
-- [ ] {{step 1: a concrete task + how you know it is done}}
-- [ ] {{step 2}}
+---
+schemaVersion: 2
+title: "{{short title}}"
+status: todo
+# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
+priority: medium
+# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
+members: []
+scope:
+  allowed: []
+  forbidden: []
+---
+
+{{two to five plain lines: what the user gets, with no technical terms. `rodo explain` shows exactly this to the user. Details are in spec.md.}}
+
+## Progress notes
+
+- Updated: {{YYYY-MM-DD}}
+- Done: not started yet
+- Remaining: all steps
+
+## Refs
+
+- [Plain explanation](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
+- [Technical spec](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
+<!-- [Acceptance scenarios](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
+
+## Checklist: Steps
+
+<!-- - [ ] User approval: simple.md and scenarios [approval] — add only when the user asked for a human approval -->
+- [ ] {{step 1: a concrete task + how you know it is done}}
+- [ ] {{step 2}}
+- [ ] Cleanup done (clean.md)

package/dist/kit/KIT_VERSION

@@ -1 +1 @@
-2.3.0
+2.4.0

package/dist/kit/MIGRATION.md

@@ -2,15 +2,11 @@
 
 Kit 2.1+ is installed and updated by `rodo init` (the 2.0 scripts `rodo-install.cjs` and `rodo-update.cjs` are replaced by it). Do the steps for every version you skipped.
 
-## 2.2.1 → 2.3.0 (two plain project docs)
+## 2.2.1 → 2.4.0 (clean code, review, plain words)
 
-What changes:
-- **New files.** `project/project-overview.md` (for a client, parts with ticks) and `project/how-it-works.md` (for a beginner). The writing rules are in the new skill file `project-docs.md`.
-- **Planner and coder.** The planner updates these files before work starts when a new feature or major change does not fit them; the coder makes them true and ticks the part when a card closes.
-- **`rodo validate`** warns `PROJECT_DOC_TOO_LONG` when one of them passes its word limit. It never blocks anything.
-- **`rodo init`** uses the project's own language when it adds missing files to an existing project.
-
-Steps: run `rodo init`. It adds the two files without touching existing ones. The next planner session fills them in. `RULES.md` is never replaced: compare it with the kit's new one (new section on the two docs). Commit: `git commit -am "chore: RODO kit 2.3.0"`.
+- New kit files: `clean.md` (clean-code formulas) and `review.md` (review checklists). `rodo init` adds them; nothing is removed.
+- Card templates: plain-words hint on the opening text and a `Cleanup done` checklist step. Existing cards need no change.
+- New command: `rodo explain [card]` prints a card in plain words.
 
 ## 2.1.0 → 2.2.0 (English templates, rodo new, safer sync)
 

package/dist/kit/agents-block.md

@@ -1,5 +1,5 @@
 <!-- rodo:start -->
-This repo uses the RODO method (kit 2.3.0). Before any work: read `.agents/skills/rodo/SKILL.md`,
+This repo uses the RODO method (kit 2.4.0). Before any work: read `.agents/skills/rodo/SKILL.md`,
 run `rodo sync`, then `rodo resume`. At the end of every session run `rodo sync`.
 RODO projects: see `rodo/*/project.json`. Never write secrets into rodo files. Never create boards.
 Never run `git pull`, `git fetch`, `git merge` or `git rebase`. If the repo is behind, tell the user once.

package/dist/kit/kit-manifest.json

@@ -1,11 +1,16 @@
 {
-  "version": "2.3.0",
+  "version": "2.4.0",
   "files": [
     {
       "src": ".agents/skills/rodo/SKILL.md",
       "dest": ".agents/skills/rodo/SKILL.md",
       "owner": "kit"
     },
+    {
+      "src": ".agents/skills/rodo/clean.md",
+      "dest": ".agents/skills/rodo/clean.md",
+      "owner": "kit"
+    },
     {
       "src": ".agents/skills/rodo/coder.md",
       "dest": ".agents/skills/rodo/coder.md",
@@ -22,8 +27,8 @@
       "owner": "kit"
     },
     {
-      "src": ".agents/skills/rodo/project-docs.md",
-      "dest": ".agents/skills/rodo/project-docs.md",
+      "src": ".agents/skills/rodo/review.md",
+      "dest": ".agents/skills/rodo/review.md",
       "owner": "kit"
     },
     {
@@ -186,16 +191,6 @@
       "src": "project-template/project/glossary.md",
       "dest": "project/glossary.md",
       "owner": "project"
-    },
-    {
-      "src": "project-template/project/how-it-works.md",
-      "dest": "project/how-it-works.md",
-      "owner": "project"
-    },
-    {
-      "src": "project-template/project/project-overview.md",
-      "dest": "project/project-overview.md",
-      "owner": "project"
     }
   ],
   "projectTemplateEn": [
@@ -238,16 +233,6 @@
       "src": "project-template-en/project/glossary.md",
       "dest": "project/glossary.md",
       "owner": "project"
-    },
-    {
-      "src": "project-template-en/project/how-it-works.md",
-      "dest": "project/how-it-works.md",
-      "owner": "project"
-    },
-    {
-      "src": "project-template-en/project/project-overview.md",
-      "dest": "project/project-overview.md",
-      "owner": "project"
     }
   ]
 }

package/dist/kit/project-template/RULES.md

@@ -1,4 +1,4 @@
-# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۳.۰)
+# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۱)
 
 > این فایل برای شماست، نه برای AI. AI همین قواعد را از `.agents/skills/rodo/` می‌خواند.
 > اگر فقط ۲ دقیقه وقت دارید، «شروع سریع» و بخش ۱، ۳ و ۴ را بخوانید.
@@ -54,9 +54,7 @@ rodo/
     ├── project/
     │   ├── brief.md           پروژه به زبان ساده
     │   ├── architecture.md    بخش‌ها و فناوری‌ها، و چرا
-    │   ├── glossary.md        واژه‌های پروژه و معنی‌شان
-    │   ├── project-overview.md  طرح کلی برای کارفرما: بخش‌ها با تیک انجام‌شده‌ها
-    │   └── how-it-works.md    هر بخش چطور کار می‌کند، به زبان ساده برای مبتدی
+    │   └── glossary.md        واژه‌های پروژه و معنی‌شان
     ├── inbox/                 کارت‌هایی که در وب ساخته شده‌اند (در Git نیست)
     └── cycles/
         └── 002-discount-code/    یک کارت و سندهایش (هیچ‌وقت جابه‌جا نمی‌شود)
@@ -234,12 +232,6 @@ AI قبل از هر تغییر این سؤال را از خودش می‌پرس
 - سندهای کارهای تمام‌شده یا لغوشده هرگز بازنویسی نمی‌شوند؛ تصمیم تازه در کارت تازه و در `MEMORY.md` نوشته می‌شود.
 - RODO خودش چیزی را اجرا نمی‌کند؛ فقط می‌گوید کدام بررسی‌ها برای این کار مناسب است و ابزارهای خود پروژه آن‌ها را اجرا می‌کنند.
 
-## دو سند سادهٔ پروژه
-- `project-overview.md` طرح کلی برای کارفرماست: پروژه چیست، چه بخش‌هایی دارد و کنار بخش‌های تمام‌شده تیک خورده است.
-- `how-it-works.md` برای شماست: پروژه از چه ساخته شده، هر بخش چطور کار می‌کند و کجای کار را راحت می‌کند.
-- اگر قابلیت تازه یا تغییر بزرگ با این دو سند نخواند، AI پیش از شروع کار آن‌ها را به‌روز می‌کند و بخش تازه بدون تیک اضافه می‌شود. موقع بستن کارت، متن با واقعیت یکی و تیک زده می‌شود.
-- این دو سند هیچ‌وقت از یکی دو صفحه بیشتر نمی‌شوند. `rodo validate` اگر طولانی شوند هشدار می‌دهد.
-
 ---
 
 ## ۹. مثال کوتاه: فروشگاه گل مریم

package/dist/kit/project-template-en/RULES.md

@@ -1,4 +1,4 @@
-# The RODO method: guide for people (kit 2.3.0)
+# The RODO method: guide for people (kit 2.4.0)
 
 > This file is for you, not for the AI. The AI reads the same rules from `.agents/skills/rodo/`.
 
@@ -38,7 +38,7 @@ rodo/
     ├── MEMORY.md              important decisions, one line each with "because"
     ├── CHANGELOG.md           small changes without a card, one line each
     ├── RULES.md               this file
-    ├── project/               brief, architecture, glossary, project-overview, how-it-works (always current)
+    ├── project/               brief, architecture, glossary (always current)
     └── cycles/NNN-slug/       one folder per card: card.rodo.md, simple.md, spec.md, design.md, acceptance.feature
 ```
 
@@ -63,14 +63,7 @@ For every new feature, change or improvement, and for every change to behaviour
 - With a board, card files live on the board and arrive through `rodo sync`; `rodo init` adds them to `.gitignore`.
 - `rodo sync` never loses your text: when the board wins a conflict, your file is saved in `rodo/<project>/.rodo/conflicts/`.
 
-## 7. The two plain project docs
-
-- `project-overview.md` is the plan for a client: what the project is, its parts, and a tick beside the finished ones.
-- `how-it-works.md` is for you: what the project is built from, how each part works and what it makes easier.
-- If a new feature or major change does not fit them, the AI updates them before work starts and a new part goes in unticked. When the card closes, the text is made true and the part is ticked.
-- They never grow past one or two pages; `rodo validate` warns if they do.
-
-## 8. Never
+## 7. Never
 
 - No secrets (passwords, keys, tokens) in any file under `rodo/`, in cards or in commit messages.
 - The AI never deletes files without your OK, never creates boards, and never answers decisions or ticks approvals.

package/package.json

@@ -1,50 +1,49 @@
-{
-  "name": "rodo-spec",
-  "version": "2.3.0",
-  "description": "RODO method CLI — install the kit, manage cards, sync with the board",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/alishafiee1/rodo-spec.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://github.com/alishafiee1/rodo-spec#readme",
-  "keywords": [
-    "rodo",
-    "rodo-spec",
-    "kanban",
-    "cli",
-    "spec",
-    "ai-agent"
-  ],
-  "bin": {
-    "rodo": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup",
-    "prepack": "pnpm run build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "@rodo/card-format": "workspace:*",
-    "@rodo/protocol": "workspace:*",
-    "@rodo/rodo-kit": "workspace:*",
-    "@types/node": "^22.0.0",
-    "commander": "^12.1.0",
-    "picocolors": "^1.1.1",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
-    "yaml": "^2.7.0"
-  }
-}
+{
+  "name": "rodo-spec",
+  "version": "2.4.0",
+  "description": "RODO method CLI — install the kit, manage cards, sync with the board",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alishafiee1/rodo-spec.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/alishafiee1/rodo-spec#readme",
+  "keywords": [
+    "rodo",
+    "rodo-spec",
+    "kanban",
+    "cli",
+    "spec",
+    "ai-agent"
+  ],
+  "bin": {
+    "rodo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "yaml": "^2.7.0",
+    "@rodo/card-format": "2.4.0",
+    "@rodo/protocol": "2.4.0",
+    "@rodo/rodo-kit": "2.4.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/dist/kit/.agents/skills/rodo/project-docs.md

@@ -1,41 +0,0 @@
-> یادداشت فارسی: قانون نگارش دو سند سادهٔ پروژه: `project-overview.md` برای کارفرما و `how-it-works.md` برای یک مبتدی. این سندها همیشه کوتاه می‌مانند و پیش از شروع کار با طرح تازه هماهنگ می‌شوند. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
-
-# Project docs playbook
-
-Two short documents explain the whole project to people. Write them in the language of `language.simple` in `project.json`. They do not replace `brief.md` or `architecture.md`; those stay as they are.
-
-| File | Reader | Answers | Limit |
-|---|---|---|---|
-| `project/project-overview.md` | the client | what is this project, what parts does it have, which are finished | 500 words |
-| `project/how-it-works.md` | the owner, a beginner who builds with AI | what is it built from, how does each part work, what does each part make easier | 900 words |
-
-## project-overview.md
-
-- Write it like a plan you hand to a client. Short sentences, no jargon.
-- **No technology names** (no framework, database or service names). Describe what the user gets.
-- Sections: what this project is, goals, parts of the project.
-- One line per part: `- [ ] **Name**: two or three sentences`. Name parts the way a client would, not after cycles or folders.
-- Planned parts stay visible, unticked. Cancelled parts are removed.
-- `[x]` means the part is finished and works. Never tick a part that is only planned, half done or untested when it has tests.
-
-## how-it-works.md
-
-- Write like an experienced engineer explaining to an intern, in plain words. Technology names are welcome; explain each one the first time it appears.
-- Start with the big picture: a few sentences on what happens when a user does something, and which part talks to which.
-- One `##` section per part or piece of infrastructure, each answering: what is it and how does it work, and what does it make easier (what would be hard without it).
-- Use one example from this project in place of a general definition.
-- Depth follows importance: a main part may get a paragraph, a small helper one or two sentences.
-- Never write secrets, passwords, keys or server addresses that are not public.
-
-## When to update them
-
-1. **Planning (before work starts).** In Documentation Impact, ask: does this new feature or major change fit what these two files say? If not, update them before BUILD. A new part goes in the overview unticked. In `how-it-works.md` mark a part that does not exist yet with `(planned)`. List both files in `spec.md` `## Documentation Impact`.
-2. **Closing a card.** Make the text match what was really built, remove `(planned)`, and tick the part in the overview if all of it is finished. A part that needs more cards stays unticked.
-3. **QUICK changes** do not touch these files, unless a sentence in them became false.
-4. **Empty or template files** (they still contain `{{`): the next planner fills them from the code and the current docs before planning its card. Mark anything you could not confirm with `(guess)`, or `(حدس)` in Persian.
-
-## Staying short
-
-- Never let a file grow past its limit. `rodo validate` warns with `PROJECT_DOC_TOO_LONG`; it never blocks anything.
-- To add something when a file is full, shorten or merge what is there. Do not add a second file or an appendix.
-- These files describe the project as a whole. History belongs in `MAP.md`, decisions in `MEMORY.md`, details in `architecture.md` and `spec.md`.

package/dist/kit/project-template/project/how-it-works.md

@@ -1,13 +0,0 @@
-# {{نام پروژه}}: چطور کار می‌کند
-
-<!-- برای یک مبتدی. مثل یک متخصص باتجربه که به کارآموز توضیح می‌دهد. حداکثر ۹۰۰ کلمه. طول هر بخش به اهمیت آن بستگی دارد. قانون کامل: .agents/skills/rodo/project-docs.md -->
-
-## نمای کلی
-
-{{چند جمله: وقتی کاربر کاری می‌کند، درخواست از کدام بخش‌ها می‌گذرد و کدام بخش با کدام حرف می‌زند}}
-
-## {{نام بخش یا زیرساخت، مثلاً پایگاه داده}}
-
-**چیست و چطور کار می‌کند:** {{به زبان ساده، با یک مثال از همین پروژه}}
-
-**کجای کار را راحت می‌کند:** {{اگر این بخش نبود چه کاری سخت می‌شد}}

package/dist/kit/project-template/project/project-overview.md

@@ -1,15 +0,0 @@
-# {{نام پروژه}}: طرح کلی
-
-<!-- برای کارفرما. زبان ساده، بدون نام فناوری، حداکثر ۵۰۰ کلمه. تیک فقط وقتی زده می‌شود که آن بخش واقعاً تمام شده باشد. قانون کامل: .agents/skills/rodo/project-docs.md -->
-
-## این پروژه چیست
-
-{{دو یا سه جمله: این پروژه چیست، برای چه کسی است و چه مشکلی را حل می‌کند}}
-
-## هدف‌ها
-
-- {{چیزی که با تمام شدن پروژه به دست می‌آید}}
-
-## بخش‌های پروژه
-
-- [ ] **{{نام بخش}}**: {{دو یا سه جمله دربارهٔ اینکه این بخش برای کاربر چه کاری می‌کند}}

package/dist/kit/project-template-en/project/how-it-works.md

@@ -1,13 +0,0 @@
-# {{name}}: how it works
-
-<!-- For a beginner. Written like an experienced engineer explaining to an intern. At most 900 words. Each part is as long as its importance needs. Full rules: .agents/skills/rodo/project-docs.md -->
-
-## The big picture
-
-{{a few sentences: when a user does something, which parts the request passes through and which part talks to which}}
-
-## {{part or infrastructure name, for example the database}}
-
-**What it is and how it works:** {{in plain words, with an example from this project}}
-
-**What it makes easier:** {{what would be hard without it}}

package/dist/kit/project-template-en/project/project-overview.md

@@ -1,15 +0,0 @@
-# {{name}}: overview
-
-<!-- For the client. Plain words, no technology names, at most 500 words. Tick a part only when it is really finished. Full rules: .agents/skills/rodo/project-docs.md -->
-
-## What this project is
-
-{{two or three sentences: what it is, who it is for and what problem it solves}}
-
-## Goals
-
-- {{what the project delivers when it is finished}}
-
-## Parts of the project
-
-- [ ] **{{part name}}**: {{two or three sentences on what this part does for the user}}