hanlint 0.0.17 → 0.0.19

package/src/cli/main.js

@@ -1,21 +1,21 @@
 // @ts-check
 /**
- * 명령줄 진입점. 파이썬 CLI 와 같은 인자, 같은 출력, 같은 종료 코드다 (0 지적 없음, 1 error 있음, 2 파일이나 설정 문제).
+ * 명령줄 진입점. 파이썬 CLI와 같은 인자, 같은 출력, 같은 종료 코드다 (0 지적 없음, 1 error 있음, 2 파일이나 설정 문제).
  *
  * ```
  * hanlint                       인자가 없으면 첫 화면. 무엇을 칠 수 있는지 보인다
- * hanlint 글.md [다른.md ...]   검사. 서브커맨드 없이 파일이나 폴더만 주면 lint 다. `-` 는 stdin
+ * hanlint 글.md [다른.md ...]   검사. 서브커맨드 없이 파일이나 폴더만 주면 lint다. `-`는 stdin
  * hanlint fix 글.md             기계가 고칠 수 있는 지적을 원문에 적용
- * hanlint print 글.md           지문 계층 JSON
- * hanlint rules                 규칙 목록을 부류로 묶어서
+ * hanlint print 글.md           분석표 계층 JSON
+ * hanlint rules                 규칙 목록을 묶음로 묶어서
  * hanlint explain <규칙>        규칙의 기술서
- * hanlint patterns             문장 틀. --rule 로 그 규칙을 피하는 것만
- * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 켜진 규칙의 고치는 법과 본보기 전후
- * hanlint hook                  Claude Code가 쓴 마크다운을 같은 턴에 비차단 검사
+ * hanlint patterns             문장 틀. --rule로 그 규칙을 피하는 것만
+ * hanlint primer --preset <종류> 쓰기 전에 읽는 한 장. 글쓰기 지침 일곱 줄과 켜진 규칙의 고치는 법, 예시 전후
+ * hanlint hook                  에이전트 훅. --prime은 쓰기 전 글쓰기 지침, 나머지는 쓴 마크다운의 비차단 검사
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint baseline 글들/        지금 있는 지적을 잠근다. 그다음부터 새것만 막힌다
  * hanlint doctor                설정과 꺼진 규칙
- * hanlint init                  주석 달린 hanlint.toml. --output 과 --preset blog|report|docs
+ * hanlint init                  주석 달린 hanlint.toml. --output과 --preset blog|report|docs
  * hanlint contract init 글.md   원문에서 최소 Reader Contract 초안
  * ```
  * audit, guard, arena, blueprint, evidence, entailment 같은 확장 명령은 파이썬 패키지에 있다.
@@ -43,12 +43,22 @@ import { loadConfig } from "../config/loadConfig.js";
 import { defaultConfig, offRules, PRESET_NAMES, PRESETS } from "../config/settings.js";
 import { applyFixes } from "../edit/applyFixes.js";
 import { exemplarFor } from "../data/exemplars.js";
+import { proseGuide, proseSections } from "../data/prose.js";
 import { patterns, patternsAvoiding } from "../data/patterns.js";
 import { HAPNIDA, REGISTERS } from "../analysis/grammar/index.js";
 import { CATEGORY_TITLES, MECHANISMS, ruleCategory, ruleFix, ruleMechanism, runAll } from "../rules/registry.js";
 import { MARKDOWN, SKIPPED_FOLDERS, isSkipped, markdownUnder } from "./walk.js";
-import { SOURCE_SUFFIXES, replaceLiteral, sourceLiterals } from "../document/sourceText.js";
-import { parseSheet, renderSheet, renderSheetJson } from "../report/sheet.js";
+import { SOURCE_SUFFIXES } from "../document/sourceText.js";
+import { applyRows, parseSheet, renderSheet, renderSheetJson, sheetRows } from "../report/sheet.js";
+import {
+  buildIndex as buildUsageIndex,
+  defaultRoot as defaultUsageRoot,
+  listIndexes as listUsageIndexes,
+  loadIndex as loadUsageIndex,
+  queryCores as usageQueryCores,
+  readDocuments as readUsageDocuments,
+} from "../usage/sentences.js";
+import { USAGE_KINDS } from "../config/settings.js";
 import { welcome } from "./welcome.js";
 import { rootHelp } from "./help.js";
 import { renderCompact } from "../report/compactReport.js";
@@ -59,7 +69,7 @@ import { renderText } from "../report/textReport.js";
 import { renderWritingSpec, writingSpec } from "../report/writingSpec.js";
 import { exemplarInRegister, patternInRegister } from "../report/registerMatch.js";
 
-const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch", "sheet"];
+const COMMANDS = ["lint", "fix", "print", "rules", "explain", "patterns", "primer", "spec", "hook", "baseline", "doctor", "init", "contract", "check", "verify-patch", "sheet", "usage"];
 const PYTHON_ONLY = [
   "audit",
   "map",
@@ -78,11 +88,11 @@ const PYTHON_ONLY = [
 ];
 const FORMATS = ["text", "compact", "json", "github"];
 const SEVERITIES = ["all", "error", "notice"];
-/** 오탐과 미탐을 받는 자리. 뜻은 파이썬 cli/commands/explain.py 가 소유한다. */
+/** 오탐과 미탐을 받는 자리. 뜻은 파이썬 cli/commands/explain.py가 소유한다. */
 const ISSUES = "github.com/eddmpython/hanlint/issues";
 const STDIN = "-";
 const STDIN_NAME = "<stdin>";
-/** 폴더를 주면 이 확장자만 찾는다. 파이썬 cli/commands/shared.py 의 MARKDOWN 과 같다. */
+/** 폴더를 주면 이 확장자만 찾는다. 파이썬 cli/commands/shared.py의 MARKDOWN과 같다. */
 const THRESHOLD_FIELDS = [
   "fragmentRun",
   "introMaxParagraphs",
@@ -116,12 +126,15 @@ const OPTION_KINDS = {
   "--quiet": "flag",
   "--severity": "value",
   "--errors-only": "flag",
+  "--notices": "flag",
   "--path": "value",
   "--layer": "value",
   "--dry-run": "flag",
   "--names": "flag",
   "--force": "flag",
   "--reply": "flag",
+  "--agent": "value",
+  "--prime": "flag",
   "--reader": "value",
   "--goal": "value",
   "--outline": "value",
@@ -133,6 +146,9 @@ const OPTION_KINDS = {
   "--baseline": "optional",
   "--prune": "flag",
   "--all": "flag",
+  "--kind": "value",
+  "--limit": "value",
+  "--root": "value",
 };
 
 class UsageError extends Error {}
@@ -164,13 +180,13 @@ function parseArgs(args) {
       options[arg] = true;
       continue;
     }
-    // 값을 줘도 되고 안 줘도 되는 옵션. 다음 인자가 다른 옵션이거나 없으면 true 로 둔다 (파이썬의 nargs="?").
+    // 값을 줘도 되고 안 줘도 되는 옵션. 다음 인자가 다른 옵션이거나 없으면 true로 둔다 (파이썬의 nargs="?").
     if (kind === "optional" && inlineValue === null && (args[i + 1] === undefined || args[i + 1].startsWith("--"))) {
       options[arg] = true;
       continue;
     }
     const value = inlineValue ?? args[++i];
-    if (value === undefined) throw new UsageError(`${arg} 에 값이 없다`);
+    if (value === undefined) throw new UsageError(`${arg}에 값이 없다`);
     if (kind === "list") {
       const list = /** @type {string[]} */ (options[arg] ?? []);
       list.push(value);
@@ -183,10 +199,10 @@ function parseArgs(args) {
 }
 
 /**
- * 서브커맨드 없이 파일이나 옵션만 주면 lint 로 본다. 빈 인자는 여기서 다루지 않는다. `main` 이 첫 화면으로 보낸다.
+ * 서브커맨드 없이 파일이나 옵션만 주면 lint로 본다. 빈 인자는 여기서 다루지 않는다. `main`이 첫 화면으로 보낸다.
  * @param {string[]} argv
  */
-export /** 파일 이름이 아니라 서브커맨드를 치려던 것으로 보이나. 뜻은 파이썬 cli/main.py 가 소유한다. @param {string} word */
+export /** 파일 이름이 아니라 서브커맨드를 치려던 것으로 보이나. 뜻은 파이썬 cli/main.py가 소유한다. @param {string} word */
 function looksLikeCommand(word) {
   if (!word || !/^[A-Za-z]+$/.test(word)) return false;
   return !existsSync(word);
@@ -197,15 +213,15 @@ function normalizeArgv(argv) {
   if (COMMANDS.includes(argv[0]) || PYTHON_ONLY.includes(argv[0]) || ["-h", "--help", "--version"].includes(argv[0])) return argv;
   if (looksLikeCommand(argv[0])) {
     const near = nearNames(argv[0], [...COMMANDS, ...PYTHON_ONLY]);
-    const hint = near.length ? ` 가까운 이름: ${near.join(", ")}.` : "";
-    throw new Error(`${argv[0]} 는 모르는 명령이다.${hint} 전체 목록은 hanlint --help`);
+    const hint = near.length ? ` 비슷한 이름: ${near.join(", ")}.` : "";
+    throw new Error(`없는 명령: ${argv[0]}.${hint} 전체 목록은 hanlint --help`);
   }
   return ["lint", ...argv];
 }
 
 /** @param {string} value @param {string[]} choices @param {string} option */
 function choose(value, choices, option) {
-  if (!choices.includes(value)) throw new UsageError(`${option} 는 ${choices.join(", ")} 가운데 하나다: ${value}`);
+  if (!choices.includes(value)) throw new UsageError(`${option} 값으로 쓸 수 없다: ${value}. ${choices.join(", ")} 가운데 하나를 쓴다`);
   return value;
 }
 
@@ -216,10 +232,10 @@ function emit(text, output) {
     return;
   }
   writeFileSync(output, text.endsWith("\n") ? text : `${text}\n`, "utf-8");
-  process.stderr.write(`${output} 에 썼다\n`);
+  process.stderr.write(`${output}에 썼다\n`);
 }
 
-/** 설정을 찾기 시작할 폴더. 첫 실제 파일의 폴더, 전부 stdin 이면 현재 폴더. @param {string[]} paths */
+/** 설정을 찾기 시작할 폴더. 첫 실제 파일의 폴더, 전부 stdin이면 현재 폴더. @param {string[]} paths */
 function startFolder(paths) {
   for (const path of paths) if (path !== STDIN) return dirname(resolve(path));
   return process.cwd();
@@ -231,8 +247,8 @@ function checkDisabled(config) {
   const unknown = [...config.disable].filter((rule) => !names.includes(rule)).sort();
   if (!unknown.length) return;
   const near = nearNames(unknown[0], names);
-  const hint = near.length ? ` 가까운 이름: ${near.join(", ")}.` : "";
-  throw new Error(`모르는 규칙 이름: ${unknown.join(", ")}.${hint} 목록은 hanlint rules --names`);
+  const hint = near.length ? ` 비슷한 이름: ${near.join(", ")}.` : "";
+  throw new Error(`없는 규칙 이름: ${unknown.join(", ")}.${hint} 목록은 hanlint rules --names`);
 }
 
 /** @param {Record<string, string | string[] | boolean>} options @param {string[]} paths */
@@ -249,7 +265,7 @@ function configFrom(options, paths, start = null) {
 function configLabel(config) {
   if (config.source === null) return "기본값";
   const rel = relative(process.cwd(), config.source);
-  // 경로 구분자는 언제나 /. 설정이 작업 폴더 밖일 때 두 판의 첫 줄이 갈렸다. 파이썬과 같다.
+  // 경로 구분자는 언제나 /. 설정이 작업 폴더 밖일 때 두 구현의 첫 줄이 갈렸다. 파이썬과 같다.
   const label = !rel || rel.startsWith("..") || isAbsolute(rel) ? config.source : rel;
   return label.split(sep).join("/");
 }
@@ -262,7 +278,7 @@ function header(config) {
 
 /** @param {Map<string, import("../rules/finding.js").Finding[]>} results */
 function summary(results) {
-  // 글에 실제로 있는 수. 거른 뒤가 아니라 거르기 전을 센다. 뜻은 파이썬 shared.summary 가 소유한다.
+  // 글에 실제로 있는 수. 거른 뒤가 아니라 거르기 전을 센다. 뜻은 파이썬 shared.summary가 소유한다.
   let errors = 0;
   let notices = 0;
   for (const findings of results.values()) {
@@ -271,16 +287,16 @@ function summary(results) {
       else if (f.severity === "notice") notices += 1;
     }
   }
-  return `파일 ${results.size}개, error ${errors}, notice ${notices}`;
+  return `파일 ${results.size}개, 오류 ${errors}건, 경고 ${notices}건`;
 }
 
-/** (이름, 본문). `-` 면 stdin 을 UTF-8 로 읽는다. @param {string} path @param {string} stdinName @returns {[string, string]} */
+/** (이름, 본문). `-`면 stdin을 UTF-8로 읽는다. @param {string} path @param {string} stdinName @returns {[string, string]} */
 function readInput(path, stdinName) {
   if (path === STDIN) return [stdinName, readFileSync(0, "utf-8")];
   return [path, readOne(path)];
 }
 
-/** 글 하나를 읽는다. 폴더를 주면 말로 막는다. 뜻은 파이썬 shared.readFile 이 소유한다. @param {string} path */
+/** 글 하나를 읽는다. 폴더를 주면 말로 막는다. 뜻은 파이썬 shared.readFile이 소유한다. @param {string} path */
 function readOne(path) {
   let isFolder = false;
   try {
@@ -288,11 +304,11 @@ function readOne(path) {
   } catch {
     isFolder = false;
   }
-  if (isFolder) throw new Error(`${path} 는 폴더다. 이 명령은 글 하나를 본다. 폴더는 hanlint 와 hanlint fix 가 받는다`);
+  if (isFolder) throw new Error(`폴더를 받았다: ${path}. 이 명령은 글 하나를 본다. 폴더는 hanlint와 hanlint fix가 받는다`);
   return readFileSync(path, "utf-8");
 }
 
-/** 폴더를 주면 그 아래 마크다운을 편다. 파일과 `-` 는 그대로 둔다. @param {string[]} paths */
+/** 폴더를 주면 그 아래 마크다운을 편다. 파일과 `-`는 그대로 둔다. @param {string[]} paths */
 function collectFiles(paths) {
   /** @type {string[]} */
   const found = [];
@@ -314,7 +330,7 @@ function collectFiles(paths) {
     const inside = markdownUnder(path).sort();
     if (!inside.length)
       throw new Error(
-        `${path} 안에 마크다운 파일이 없다. 점으로 시작하는 폴더와 node_modules 는 건너뛴다. 그 안을 보려면 그 폴더를 직접 준다`,
+        `${path} 안에 마크다운 파일이 없다. 점으로 시작하는 폴더와 node_modules는 건너뛴다. 그 안을 보려면 그 폴더를 직접 준다`,
       );
     found.push(...inside);
   }
@@ -330,7 +346,7 @@ function commonest(findings) {
   return [...counted.keys()].sort((a, b) => (counted.get(b) ?? 0) - (counted.get(a) ?? 0) || a.localeCompare(b))[0];
 }
 
-/** `hanlint fix` 가 실제로 고칠 error 수. 고침이 달렸다는 것과 자리를 잡을 수 있다는 것은 다르다.
+/** `hanlint fix`가 실제로 고칠 error 수. 고침이 달렸다는 것과 자리를 잡을 수 있다는 것은 다르다.
  * @param {Map<string, string>} texts @param {Map<string, import("../rules/finding.js").Finding[]>} results */
 function fixableCount(texts, results) {
   let total = 0;
@@ -342,7 +358,7 @@ function fixableCount(texts, results) {
   return total;
 }
 
-/** 검사 끝에 붙는 다음 행동 한 줄. 뜻은 파이썬 cli/commands/shared.py 가 소유한다.
+/** 검사 끝에 붙는 다음 행동 한 줄. 뜻은 파이썬 cli/commands/shared.py가 소유한다.
  * @param {Map<string, import("../rules/finding.js").Finding[]>} results @param {number} [fixable] */
 function nextStep(results, fixable = 0) {
   const findings = [...results.values()].flat();
@@ -350,17 +366,17 @@ function nextStep(results, fixable = 0) {
   const notices = findings.length - errors.length;
   if (errors.length) {
     const rule = commonest(errors);
-    if (fixable) return `다음: error ${errors.length}건 가운데 ${fixable}건은 hanlint fix 가 바로 고친다. 나머지는 손으로 고친다`;
-    if (patternsAvoiding(rule).length) return `다음: error ${errors.length}건을 고친다. 다시 쓸 틀은 hanlint patterns --rule ${rule}`;
-    return `다음: error ${errors.length}건을 고친다. 규칙이 왜 있는지는 hanlint explain ${rule}`;
+    if (fixable) return `다음: 오류 ${errors.length}건 가운데 ${fixable}건은 hanlint fix가 바로 고친다. 나머지는 손으로 고친다`;
+    if (patternsAvoiding(rule).length) return `다음: 오류 ${errors.length}건을 고친다. 다시 쓸 틀은 hanlint patterns --rule ${rule}`;
+    return `다음: 오류 ${errors.length}건을 고친다. 규칙이 왜 있는지는 hanlint explain ${rule}`;
   }
-  if (notices) return `다음: error 0. 확인할 자리 ${notices}건을 읽고 판단한 뒤 사람과 LLM 평가로 넘어간다`;
-  return "다음: 세어서 잡히는 결함이 없다. 좋은 글이라는 뜻은 아니므로 사람과 LLM 평가로 넘어간다";
+  if (notices) return `다음: 오류는 없다. 경고 ${notices}건을 읽고 고칠지 정한다`;
+  return "다음: 규칙으로 찾은 잘못이 없다. 좋은 글이라는 뜻은 아니니 사람이 읽어 본다";
 }
 
 /** @param {Baseline} baseline */
 function lockedNote(baseline) {
-  return `잠근 자리 ${baseline.count}건은 넘겼다 (${baseline.source}). 그 문장을 고치면 다시 나온다`;
+  return `baseline 파일에 든 지적 ${baseline.count}건은 보이지 않았다 (${baseline.source}). 그 문장을 고치면 다시 나온다`;
 }
 
 /** 옵션과 설정에서 잠금 파일을 연다. 둘 다 없으면 빈 잠금이다. @param {Record<string, string | string[] | boolean>} options @param {import("../config/settings.js").Config} config */
@@ -385,10 +401,10 @@ function runBaseline(args) {
   }
   const baseline = options["--prune"] ? pruneBaseline(loadBaseline(target), results) : buildBaseline(results, target);
   writeFileSync(target, `${renderBaseline(baseline)}\n`, "utf-8");
-  const what = options["--prune"] ? "잠금을 줄였다" : "지적을 잠갔다";
+  const what = options["--prune"] ? "글에 더 없는 지적을 지웠다" : "지금 있는 지적이다";
   process.stdout.write(
-    `${baseline.source} 에 ${baseline.count}건을 적었다. ${files.length}개 글의 ${what}.\n` +
-      "다음: 검사할 때 --baseline 을 붙이거나 설정에 baseline 을 적는다. 잠긴 자리를 고치면 새 지적으로 다시 나온다\n",
+    `${baseline.source}에 ${baseline.count}건을 적었다. ${files.length}개 글에서 ${what}.\n` +
+      "다음: 검사할 때 --baseline을 붙이거나 설정에 baseline을 적는다. baseline 파일에 든 문장을 고치면 새 지적으로 다시 나온다\n",
   );
   return 0;
 }
@@ -430,7 +446,7 @@ function runContract(args) {
   }
   const output = options["--output"];
   if (typeof output === "string" && existsSync(output) && !options["--force"]) {
-    throw new Error(`${output} 가 이미 있다. 덮어쓰려면 --force`);
+    throw new Error(`이미 있는 파일: ${output}. 덮어쓰려면 --force를 붙인다`);
   }
   const outline = options["--outline"];
   const facts = /** @type {string[]} */ (options["--fact"] ?? []);
@@ -528,7 +544,7 @@ function runLint(args) {
     } else {
       parts.push(
         [...shown]
-          .map(([name, findings]) => renderText(name, findings, registers.get(name), config.preset, config.exemplars))
+          .map(([name, findings]) => renderText(name, findings, registers.get(name), config.preset, config.exemplars, Boolean(options["--notices"])))
           .join("\n\n"),
       );
       if (shown.size > 1) parts.push(summary(results));
@@ -551,18 +567,18 @@ function runFix(args) {
   const lines = [];
   for (const path of files) {
     const text = readFileSync(path, "utf-8");
-    // notice 는 제안이라 손으로 정한다. 확정된 error 만 원문에 넣는다.
+    // notice는 제안이라 손으로 정한다. 확정된 error만 원문에 넣는다.
     const errors = runAll(fingerprint(text, config, path), config).filter((f) => f.severity === "error");
     const result = applyFixes(text, errors);
     for (const [line, fragment, replacement] of result.applied) lines.push(`${path}:${line}  ${fragment} → ${replacement}`);
     for (const [line, fragment, reason] of result.skipped) lines.push(`${path}:${line}  건너뜀 ${fragment}: ${reason}`);
     if (result.text !== text && !options["--dry-run"]) writeFileSync(path, result.text, "utf-8");
-    // 남은 수를 함께 말한다. `0곳 고침, 0곳 건너뜀` 만 보면 손볼 것이 없다는 뜻으로 읽힌다
+    // 남은 수를 함께 말한다. `0곳 고침, 0곳 건너뜀`만 보면 손볼 것이 없다는 뜻으로 읽힌다
     const left = errors.length - result.applied.length;
-    const rest = left ? `. 손으로 고칠 error ${left}건이 남았다 (hanlint ${path})` : "";
+    const rest = left ? `. 손으로 고칠 오류 ${left}건이 남았다 (hanlint ${path})` : "";
     lines.push(
       `${path}  ${result.applied.length}곳 고침, ${result.skipped.length}곳 건너뜀` +
-        (options["--dry-run"] ? " (미리보기, 파일은 그대로)" : "") +
+        (options["--dry-run"] ? " (미리보기라 파일은 그대로다)" : "") +
         rest,
     );
   }
@@ -573,7 +589,7 @@ function runFix(args) {
 /** @param {string[]} args */
 function runPrint(args) {
   const { options, positionals } = parseArgs(args);
-  if (positionals.length !== 1) throw new UsageError("마크다운 파일 하나가 필요하다. `-` 는 stdin");
+  if (positionals.length !== 1) throw new UsageError("마크다운 파일 하나가 필요하다. `-`는 stdin");
   const layer = choose(/** @type {string} */ (options["--layer"] ?? "all"), LAYERS, "--layer");
   const config = configFrom(options, positionals);
   const [name, text] = readInput(positionals[0], /** @type {string} */ (options["--path"] ?? STDIN_NAME));
@@ -616,15 +632,15 @@ function runRules(args) {
   let tail = `규칙 ${names.length}개`;
   if (off.size) {
     const byPreset = PRESETS[config.preset].length;
-    tail += `, 그중 ${off.size}개가 꺼져 있다 (preset ${config.preset} 이 ${byPreset}개, disable 이 ${off.size - byPreset}개)`;
+    tail += ` 가운데 ${off.size}개가 꺼져 있다 (${config.preset} 프리셋 ${byPreset}개, disable ${off.size - byPreset}개)`;
   }
   lines.push(`${tail}. 하나를 자세히 보려면 hanlint explain <규칙>`);
-  lines.push(`프리셋은 ${PRESET_NAMES.join(", ")} 이고 hanlint init --preset <이름> 이 설정에 적는다`);
+  lines.push(`프리셋: ${PRESET_NAMES.join(", ")}. hanlint init --preset <이름>이 설정 파일에 적는다`);
   emit(lines.join("\n"), output);
   return 0;
 }
 
-/** 여러 줄짜리 본보기를 첫 줄에만 표를 달고 나머지는 맞춰 들여쓴다. @param {string} text @param {string} label */
+/** 여러 줄짜리 예시를 첫 줄에만 표를 달고 나머지는 맞춰 들여쓴다. @param {string} text @param {string} label */
 function indent(text, label) {
   const pad = " ".repeat(label.length);
   return text.replace(/\n+$/, "").split("\n").map((line, index) => (index === 0 ? label : pad) + line).join("\n");
@@ -635,7 +651,7 @@ const NEAR_LIMIT = 3;
 /** 앞 몇 글자가 같으면 가까운 이름으로 보는가. */
 const NEAR_PREFIX = 3;
 
-/** 오타에 가까운 이름. 파이썬 cli/commands/explain.py 의 nearNames 와 같다. @param {string} query @param {string[]} names */
+/** 오타에 가까운 이름. 파이썬 cli/commands/explain.py의 nearNames와 같다. @param {string} query @param {string[]} names */
 function nearNames(query, names) {
   const lowered = query.toLowerCase();
   /** @type {[number, string][]} */
@@ -655,15 +671,15 @@ function runExplain(args) {
   const names = ruleNames();
   if (!positionals.length) {
     process.stdout.write("규칙 이름 하나가 필요하다. 예: hanlint explain doublePassive\n");
-    process.stdout.write(`\n규칙 ${names.length}개를 부류로 묶어 보려면 hanlint rules, 이름만 보려면 hanlint rules --names\n`);
+    process.stdout.write(`\n규칙 ${names.length}개를 카테고리별로 보려면 hanlint rules, 이름만 보려면 hanlint rules --names\n`);
     return 2;
   }
-  if (positionals.length !== 1) throw new UsageError("규칙 이름 하나가 필요하다. hanlint rules 로 목록을 본다");
+  if (positionals.length !== 1) throw new UsageError("규칙 이름 하나가 필요하다. hanlint rules로 목록을 본다");
   const wanted = positionals[0];
   if (!names.includes(wanted)) {
     const near = nearNames(wanted, names);
-    const hint = near.length ? ` 이것을 찾았나: ${near.join(", ")}` : " hanlint rules 로 목록을 본다";
-    throw new Error(`모르는 규칙: ${wanted}.${hint}`);
+    const hint = near.length ? ` 비슷한 이름: ${near.join(", ")}` : " 목록은 hanlint rules";
+    throw new Error(`없는 규칙: ${wanted}.${hint}`);
   }
   const category = ruleCategory(wanted);
   const config = configFrom(options, []);
@@ -682,18 +698,18 @@ function runExplain(args) {
     return 0;
   }
   const mechanism = ruleMechanism(wanted);
-  process.stdout.write(`${wanted}  (${CATEGORY_TITLES[category]})\n기제: ${mechanism}. ${MECHANISMS[mechanism]}\n\n${ruleDoc(wanted)}\n`);
+  process.stdout.write(`${wanted}  (${CATEGORY_TITLES[category]})\n방식: ${MECHANISMS[mechanism]} (${mechanism})\n\n${ruleDoc(wanted)}\n`);
   const exemplar = exemplarOf ? exemplarInRegister(exemplarOf, register) : undefined;
   if (exemplar) {
-    process.stdout.write("\n본보기\n");
+    process.stdout.write("\n예시\n");
     process.stdout.write(`${indent(exemplar.before, "  전  ")}\n`);
     process.stdout.write(`${indent(exemplar.after, "  후  ")}\n`);
     process.stdout.write(`  달라진 것: ${exemplar.moved}\n`);
   }
   const siblings = names.filter((name) => ruleCategory(name) === category && name !== wanted);
-  process.stdout.write(`\n같은 부류: ${siblings.join(", ")}\n`);
-  process.stdout.write(`끄려면 hanlint.toml 의 disable 에 ${wanted} 를 넣는다. 한 자리만 끄려면 <!-- hanlint-disable ${wanted} -->\n`);
-  process.stdout.write(`정당한 문장인데 잡혔으면 끄고 끝내지 말고 알려 준다: ${ISSUES}\n`);
+  process.stdout.write(`\n같은 카테고리: ${siblings.join(", ")}\n`);
+  process.stdout.write(`끄려면 hanlint.toml의 disable 목록에 넣는다: ${wanted}. 한 곳만 끄려면 <!-- hanlint-disable ${wanted} -->\n`);
+  process.stdout.write(`맞는 문장인데 잡혔다면 끄기만 하지 말고 여기에 알린다: ${ISSUES}\n`);
   return 0;
 }
 
@@ -703,7 +719,7 @@ function runPatterns(args) {
   const rule = /** @type {string | undefined} */ (options["--rule"]);
   const register = choose(/** @type {string} */ (options["--register"] ?? HAPNIDA), REGISTERS, "--register");
   const chosen = (rule ? patternsAvoiding(rule) : patterns()).map((pattern) => patternInRegister(pattern, register));
-  if (!chosen.length) throw new Error(` 을 피하는 문형이 없다. hanlint patterns 로 전부 본다`);
+  if (!chosen.length) throw new Error(`을 피하는 문형이 없다. hanlint patterns로 전부 본다`);
   const output = /** @type {string | undefined} */ (options["--output"]);
   if (options["--format"] === "json") {
     emit(JSON.stringify({ version: 1, patterns: chosen }, null, 2), output);
@@ -711,7 +727,7 @@ function runPatterns(args) {
   }
   const lines = [];
   for (const pattern of chosen) {
-    lines.push(`${pattern.name}  (${pattern.avoids.join(", ")} 를 피한다)`);
+    lines.push(`${pattern.name}  (피하는 규칙: ${pattern.avoids.join(", ")})`);
     lines.push(`  틀    ${pattern.form}`);
     lines.push(`  언제  ${pattern.when}`);
     lines.push(indent(pattern.example, "  예시  "));
@@ -719,13 +735,13 @@ function runPatterns(args) {
     lines.push(`  출처  ${pattern.source}`);
     lines.push("");
   }
-  lines.push(`문형 ${chosen.length}개. 예시는 전부 hanlint 를 error 0 으로 통과한다 (게이트가 확인한다)`);
+  lines.push(`문형 ${chosen.length}개. 예시 문장은 모두 hanlint 검사에서 오류가 없다`);
   if (!rule) lines.push("지적을 받은 자리를 다시 쓰려면 hanlint patterns --rule <규칙>");
   emit(lines.join("\n"), output);
   return 0;
 }
 
-/** 여러 줄을 한 줄로. 줄바꿈은 ¶ 다. 파이썬 cli/commands/primer.py 의 flat 과 같다. @param {string} text */
+/** 여러 줄을 한 줄로. 줄바꿈은 ¶ 다. 파이썬 cli/commands/primer.py의 flat과 같다. @param {string} text */
 function flat(text) {
   return text
     .split("\n")
@@ -735,7 +751,7 @@ function flat(text) {
 }
 
 /**
- * 설정에서 켜진 규칙마다 항목 하나. 부류 순서, 그 안은 이름 순서. 파이썬 primerEntries 와 같다.
+ * 설정에서 켜진 규칙마다 항목 하나. 묶음 순서, 그 안은 이름 순서. 파이썬 primerEntries와 같다.
  * @param {import("../config/settings.js").Config} config @param {string} register
  */
 function primerEntries(config, register) {
@@ -745,7 +761,7 @@ function primerEntries(config, register) {
     for (const name of ruleNames()) {
       if (ruleCategory(name) !== category || off.has(name)) continue;
       const exemplar = exemplarFor(name, config.preset, config.exemplars);
-      if (!exemplar) throw new Error(`본보기가 없는 규칙: ${name}`);
+      if (!exemplar) throw new Error(`예시가 없는 규칙: ${name}`);
       const shown = exemplarInRegister(exemplar, register);
       entries.push({ rule: name, category, fix: ruleFix(name), before: shown.before, after: shown.after });
     }
@@ -753,10 +769,17 @@ function primerEntries(config, register) {
   return entries;
 }
 
-/** 사람과 AI 가 읽는 한 장. 파이썬 renderPrimer 와 글자 단위로 같다. @param {ReturnType<typeof primerEntries>} entries @param {string} preset @param {string} register */
+/** 글쓰기 지침를 절마다 한 줄로. 제목 두 칸 띄고 본문이다. 파이썬 proseLines와 같다. */
+function proseLines() {
+  return proseSections().map(([title, body]) => `${title}  ${body.split(/\s+/).filter(Boolean).join(" ")}`);
+}
+
+/** 사람과 AI가 읽는 한 장. 파이썬 renderPrimer와 글자 단위로 같다. @param {ReturnType<typeof primerEntries>} entries @param {string} preset @param {string} register */
 function renderPrimer(entries, preset, register) {
   const lines = [
-    `hanlint primer  ${preset} 종류, ${register}체, 규칙 ${entries.length}개. 줄마다 규칙 이름, 고치는 법, 전 (그 규칙에 잡히는 글), 후 (같은 뜻으로 통과하는 글) 순서다. 본보기의 줄바꿈은 ¶ 다`,
+    ...proseLines(),
+    "",
+    `hanlint primer  ${preset} 종류, ${register}체, 규칙 ${entries.length}개. 줄마다 규칙 이름, 고치는 법, 전(그 규칙에 잡히는 글), 후(그 예시에서 고친 글) 순서다. 예시의 줄바꿈은 ¶로 보인다`,
   ];
   for (const [category, title] of Object.entries(CATEGORY_TITLES)) {
     const inside = entries.filter((entry) => entry.category === category);
@@ -764,7 +787,7 @@ function renderPrimer(entries, preset, register) {
     lines.push("", `${title} (${inside.length})`);
     for (const entry of inside) lines.push(`${entry.rule}  ${entry.fix}  전: ${flat(entry.before)}  후: ${flat(entry.after)}`);
   }
-  lines.push("", "후는 전부 hanlint 를 error 0 으로 통과한다 (게이트가 확인한다). 규칙 하나를 깊게 보려면 hanlint explain <규칙>");
+  lines.push("", "예시는 그 문장에만 맞는다. 용어와 사실은 그대로 두고, 바꾼 말을 다른 글에 그대로 옮겨 쓰지 않는다. 규칙을 더 보려면 hanlint explain <규칙>");
   return lines.join("\n");
 }
 
@@ -777,7 +800,7 @@ function runPrimer(args) {
   const output = /** @type {string | undefined} */ (options["--output"]);
   const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
   if (format === "json") {
-    emit(JSON.stringify({ version: 1, preset: config.preset, register, rules: entries }, null, 2), output);
+    emit(JSON.stringify({ version: 1, preset: config.preset, register, prose: proseGuide(), rules: entries }, null, 2), output);
     return 0;
   }
   emit(renderPrimer(entries, config.preset, register), output);
@@ -793,7 +816,7 @@ function runSpec(args) {
   if (options["--chars"] !== undefined) {
     const raw = /** @type {string} */ (options["--chars"]);
     targetChars = Number(raw);
-    if (!Number.isInteger(targetChars) || targetChars <= 0) throw new UsageError(`--chars 는 1 이상의 정수다: ${raw}`);
+    if (!Number.isInteger(targetChars) || targetChars <= 0) throw new UsageError(`--chars는 1 이상의 정수다: ${raw}`);
   }
   const result = writingSpec(config, register, targetChars);
   const output = /** @type {string | undefined} */ (options["--output"]);
@@ -802,66 +825,117 @@ function runSpec(args) {
   return 0;
 }
 
-/** Claude Code가 다음 모델 요청에 넣는 비차단 Finding 문맥. */
-function hookContext(eventName, name, findings) {
+/** 글쓰기 지침를 싣는 이벤트. Claude Code와 Codex 모두 이 둘의 additionalContext를 모델 문맥에 넣는다. */
+const PRIME_EVENTS = ["SessionStart", "UserPromptSubmit"];
+
+/** 에이전트가 다음 모델 요청에 넣는 비차단 문맥. @param {string} eventName @param {string} context */
+function hookContext(eventName, context) {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext: context } });
+}
+
+/** Finding을 되먹이는 문맥의 본문. 파일마다 한 덩어리다. 파이썬 findingContext와 같다. @param {string} eventName @param {[string, import("../rules/finding.js").Finding[]][]} found */
+function findingContext(eventName, found) {
   const where = eventName === "Stop" ? "마지막 답변" : "방금 쓴 마크다운";
-  return JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName,
-      additionalContext: `hanlint가 ${where}에서 센 Finding입니다.\n${renderCompact(name, findings)}`,
-    },
-  });
+  return `hanlint가 ${where}에서 찾은 지적입니다.\n${found.map(([name, items]) => renderCompact(name, items)).join("\n")}`;
+}
+
+/** Codex apply_patch 본문에서 쓴 파일을 가리키는 머리 줄 (Codex 훅 문서, 2026-09-21 확인). */
+const PATCH_HEADS = ["*** Add File: ", "*** Update File: ", "*** Move to: "];
+
+/** apply_patch 본문이 쓴 파일 경로. 나온 차례대로 한 번씩이다. @param {string} patch */
+function patchPaths(patch) {
+  /** @type {string[]} */
+  const paths = [];
+  for (const line of patch.split(/\r?\n/)) {
+    for (const head of PATCH_HEADS) {
+      if (!line.startsWith(head)) continue;
+      const path = line.slice(head.length).trim();
+      if (path && !paths.includes(path)) paths.push(path);
+    }
+  }
+  return paths;
+}
+
+/** PostToolUse 입력이 쓴 파일 경로. 모르는 도구면 빈 목록이다. @param {any} payload @returns {string[]} */
+function writtenPaths(payload) {
+  const toolInput = payload.tool_input;
+  if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) return [];
+  if (["Write", "Edit"].includes(payload.tool_name)) {
+    const path = toolInput.file_path;
+    return typeof path === "string" && path ? [path] : [];
+  }
+  if (payload.tool_name === "apply_patch") return typeof toolInput.command === "string" ? patchPaths(toolInput.command) : [];
+  return [];
+}
+
+/** 쓴 마크다운마다 [이름, Finding]. 상대 경로는 입력의 cwd에서 찾는다. @param {any} payload @param {Record<string, unknown>} options */
+function writtenFindings(payload, options) {
+  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : null;
+  /** @type {[string, import("../rules/finding.js").Finding[]][]} */
+  const found = [];
+  for (const rawPath of writtenPaths(payload)) {
+    const path = base !== null && !isAbsolute(rawPath) ? join(base, rawPath) : rawPath;
+    if (!MARKDOWN.includes(extname(path).toLowerCase())) continue;
+    try {
+      if (!statSync(path).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const config = configFrom(options, [path]);
+    let findings = lintText(readFileSync(path, "utf-8"), config, rawPath);
+    if (config.baseline) findings = loadBaseline(config.baseline).keep(rawPath, findings);
+    found.push([rawPath, findings]);
+  }
+  return found;
 }
 
 /** 명령 훅 JSON을 stdin에서 읽어 저장 파일이나 마지막 답변을 검사한다. 언제나 종료 코드 0이다. @param {string[]} args */
 function runHook(args) {
+  if (args.includes("--prime") && args.includes("--reply")) throw new UsageError("--prime과 --reply는 함께 쓰지 않는다");
+  const { options, positionals } = parseArgs(args);
+  const agent = choose(/** @type {string} */ (options["--agent"] ?? "claude"), ["claude", "codex"], "--agent");
   try {
-    const { options, positionals } = parseArgs(args);
     if (positionals.length) return 0;
     const payload = JSON.parse(readFileSync(0, "utf-8"));
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) return 0;
-    let eventName;
-    let name;
-    let findings;
+    const eventName = payload.hook_event_name;
+    if (options["--prime"]) {
+      if (PRIME_EVENTS.includes(eventName)) process.stdout.write(`${hookContext(eventName, proseGuide())}\n`);
+      return 0;
+    }
+    /** @type {[string, import("../rules/finding.js").Finding[]][]} */
+    let found;
     if (options["--reply"]) {
-      if (payload.hook_event_name !== "Stop" || payload.stop_hook_active === true) return 0;
+      if (eventName !== "Stop" || payload.stop_hook_active === true) return 0;
       const text = payload.last_assistant_message;
       if (typeof text !== "string" || !text.trim()) return 0;
       const start = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
       const config = configFrom(options, [], start);
       config.preset = "chat";
-      eventName = "Stop";
-      name = "<assistant>";
-      findings = lintText(text, config, name);
+      found = [["<assistant>", lintText(text, config, "<assistant>")]];
+    } else if (eventName === "PostToolUse") {
+      found = writtenFindings(payload, options);
     } else {
-      if (payload.hook_event_name !== "PostToolUse" || !["Write", "Edit"].includes(payload.tool_name)) return 0;
-      const rawPath = payload.tool_input?.file_path;
-      if (typeof rawPath !== "string" || !rawPath || !MARKDOWN.includes(extname(rawPath).toLowerCase())) return 0;
-      try {
-        if (!statSync(rawPath).isFile()) return 0;
-      } catch {
-        return 0;
-      }
-      const config = configFrom(options, [rawPath]);
-      eventName = "PostToolUse";
-      name = rawPath;
-      findings = lintText(readFileSync(rawPath, "utf-8"), config, name);
-      if (config.baseline) findings = loadBaseline(config.baseline).keep(name, findings);
+      return 0;
     }
-    if (findings.length) process.stdout.write(`${hookContext(eventName, name, findings)}\n`);
+    found = found.filter(([, items]) => items.length);
+    if (!found.length) return 0;
+    const context = findingContext(eventName, found);
+    if (options["--reply"] && agent === "codex") process.stdout.write(`${JSON.stringify({ systemMessage: context })}\n`);
+    else process.stdout.write(`${hookContext(eventName, context)}\n`);
   } catch {
     return 0;
   }
   return 0;
 }
 
-/** 잠근 지적이 몇 건인지. baseline 이 빚을 감추는 자리가 되지 않게 늘 보인다. @param {import("../config/settings.js").Config} config */
+/** 잠근 지적이 몇 건인지. baseline이 빚을 감추는 자리가 되지 않게 늘 보인다. @param {import("../config/settings.js").Config} config */
 function baselineState(config) {
-  if (!config.baseline) return "없다 (hanlint baseline 글들/ 로 지금 지적을 잠근다)";
+  if (!config.baseline) return "없음 (만들려면 hanlint baseline 글들/)";
   try {
-    return `${loadBaseline(config.baseline).count}건이 ${config.baseline} 에 잠겨 있다. 그 문장을 고치면 다시 나온다`;
+    return `${config.baseline}에 지적 ${loadBaseline(config.baseline).count}건이 들어 있다. 그 문장을 고치면 다시 나온다`;
   } catch (error) {
-    return `${config.baseline} 를 못 읽었다: ${/** @type {Error} */ (error).message}`;
+    return `읽지 못했다: ${config.baseline} (${/** @type {Error} */ (error).message})`;
   }
 }
 
@@ -878,22 +952,22 @@ function runDoctor(args) {
     `설정      ${configLabel(config)}`,
     `프리셋    ${config.preset} (${PRESET_NAMES.join(", ")} 가운데)`,
     `규칙      ${names.length - off.length}개 켜짐, ${off.length}개 꺼짐`,
-    `잠금      ${baselineState(config)}`,
-    `폴더      점으로 시작하는 폴더와 ${SKIPPED_FOLDERS.join(", ")} 는 건너뛴다. 직접 주면 검사한다`,
+    `baseline 파일 ${baselineState(config)}`,
+    `폴더      건너뛰는 것: 점으로 시작하는 폴더, ${SKIPPED_FOLDERS.join(", ")}. 직접 주면 검사한다`,
   ];
   if (off.length) lines.push(`꺼진 규칙  ${off.join(", ")}`);
-  lines.push("", "다음: hanlint 글.md 로 검사한다. 설정이 기본값이면 hanlint init 으로 파일을 만든다");
+  lines.push("", "다음: hanlint 글.md로 검사한다. 설정 파일이 없으면 hanlint init으로 만든다");
   process.stdout.write(`${lines.join("\n")}\n`);
   return 0;
 }
 
-/** 주석 달린 hanlint.toml. 파이썬 `hanlint init` 과 같은 글자다. @param {string} [preset] */
+/** 주석 달린 hanlint.toml. 파이썬 `hanlint init`과 같은 글자다. @param {string} [preset] */
 export function renderInit(preset = "blog") {
   const defaults = defaultConfig();
   const lines = [
-    "# hanlint 설정. 규칙을 끄려면 disable 에 이름을 넣는다. 규칙의 기술서는 hanlint explain <규칙>.",
+    "# hanlint 설정. 규칙을 끄려면 disable에 이름을 넣는다. 규칙 설명은 hanlint explain <규칙>으로 본다.",
     "",
-    "# 글의 종류. 그 종류에 안 맞는 규칙을 처음부터 끈다. disable 은 그 위에 더한다.",
+    "# 글의 종류. 그 종류에 안 맞는 규칙을 처음부터 끈다. disable은 그 위에 더한다.",
   ];
   for (const [name, off] of Object.entries(PRESETS)) lines.push(`#   ${name}: ${off.length ? off.join(", ") : "전부 켠다"}`);
   lines.push(`preset = "${preset}"`, "", "# 규칙 목록과 한 줄 설명");
@@ -907,23 +981,23 @@ export function renderInit(preset = "blog") {
     "",
     "disable = []",
     "",
-    "# 대표 검색어를 읽을 frontmatter 필드. 없으면 keywordMissing 은 돌지 않는다",
+    "# 대표 검색어를 읽을 frontmatter 필드. 없으면 keywordMissing은 돌지 않는다",
     '# keywordField = "primaryKeyword"',
     "",
-    "# 도입과 마지막 절이 담아야 하는 frontmatter 필드. 비어 있으면 fieldEcho 는 돌지 않는다",
+    "# 도입과 마지막 절이 담아야 하는 frontmatter 필드. 비어 있으면 fieldEcho는 돌지 않는다",
     '# introFields = ["readerQuestion"]',
     '# endingFields = ["readerTakeaway"]',
     "",
-    "# hanlint profile build 가 만든 파일. 있으면 종류의 프로파일 대신 그것과 견준다 (outsideProfile)",
+    "# hanlint profile build가 만든 파일. 있으면 글 종류의 기본 프로파일 대신 이 파일과 비교한다(outsideProfile)",
     '# profile = "profile.json"',
     "",
-    "# hanlint baseline 이 만든 잠금 파일. 있으면 그 안의 지적은 넘기고 새로 생긴 것만 막는다",
+    "# hanlint baseline이 만든 baseline 파일. 있으면 그 안의 지적은 보이지 않고 새로 생긴 지적만 막는다",
     '# baseline = ".hanlint-baseline.json"',
     "",
-    "# 코드도 산문도 아닌 펜스의 언어 표기. 장면 계약과 도표 원문은 코드 블록으로 세지 않고 지문에서 뺀다",
+    "# 코드도 산문도 아닌 펜스의 언어 이름. 이 펜스는 코드 블록으로 세지 않고 검사에서도 뺀다",
     '# ignoreFences = ["course-scene", "mermaid"]',
     "",
-    "# 임계. 기본값의 정본은 hanlint 의 config/settings.py 다",
+    "# 기준값. 아래 값이 기본값이다",
   );
   for (const name of THRESHOLD_FIELDS) {
     const value = /** @type {number} */ (defaults[name]);
@@ -931,38 +1005,45 @@ export function renderInit(preset = "blog") {
     lines.push(`# ${name} = ${shown}`);
   }
   lines.push(
+    "",
+    "# 용례. 그 종류의 실제 글에 흔한 명사 연쇄(nounPile)와 사전 표현은 짚지 않는다. 명사 연쇄는 usageMin편 이상의",
+    "# 문서에 나온 것, 사전 표현은 문서의 usageShare 비율 이상에 나온 것(사업보고서의 `에 대한`)이다.",
+    "# 종류는 프리셋이 정한다 (report만 있다). 빈 문자열이면 어떤 프리셋에서도 용례를 보지 않는다",
+    '# usageKind = ""',
+    "# usageMin = 3",
+    "# usageShare = 0.9",
     "",
     "# 사전에 더할 항목. 키는 cliches, translationese, redundantPair, japaneseLoan, easyWords,",
-    "# screenSentence, screenNarration, screenTone, screenWord",
+    "# screenSentence, screenNarration, screenTone, screenWord, calqueFrame",
     "# [dictionary]",
     '# cliches = ["우리의 여정"]',
     '# translationese = [{ pattern = "에 대한 이해", fix = "를 아는 것" }]',
     "",
-    "# 표면 치환이 바꾸면 안 되는 한국어 고유명사와 프로젝트 용어. 수치와 라틴 식별자는 자동으로 보호한다",
+    "# 자동 고침이 건드리지 말아야 할 한국어 고유명사와 프로젝트 용어. 숫자와 영문 식별자는 저절로 지킨다",
     '# protectedTerms = ["한린트", "김민지"]',
-    '# enforceStyle = ["noQuestion", "nounPile"]  # 선택한 문체 신호만 error로 강제한다',
+    '# enforceStyle = ["noQuestion", "nounPile"]  # 고른 문체 규칙만 오류로 낸다',
     "",
-    "# 사람이 승인한 프로젝트 본보기. 같은 규칙과 프리셋의 내장 본보기를 덮어쓴다",
+    "# 사람이 승인한 프로젝트 예시. 같은 규칙과 프리셋의 기본 예시 대신 쓴다",
     "# [[exemplars]]",
     '# rule = "translationese"',
     '# before = "설계에 대한 이해가 필요합니다."',
     '# after = "설계를 알아야 합니다."',
-    '# moved = "명사구를 서술어로 풀어 씀"',
+    '# moved = "명사구를 서술어로 풀어 썼다"',
     '# presets = ["blog"]',
     "",
-    "# 사람이 승인한 국소 고침. 원문을 포함한 모든 조건이 맞을 때만 그대로 재생한다",
+    "# 사람이 승인한 그 자리만의 고침. 원문을 포함해 조건이 모두 맞을 때만 그대로 적용한다",
     "# [[patches]]",
     '# rule = "translationese"',
     '# before = "설계에 대한 이해가 필요합니다."',
     '# after = "설계를 알아야 합니다."',
-    '# moved = "명사구를 서술어로 풀어 씀"',
+    '# moved = "명사구를 서술어로 풀어 썼다"',
     '# sourceText = "설계에 대한 이해가 필요합니다."  # before의 마크다운까지 보존한 선택용 원문',
     '# sentence = "설계에 대한 이해가 필요합니다."  # before에서 마크다운 표식을 걷은 선택용 원문',
     '# cue = "에 대한"',
     '# reader = "new"',
     '# presets = ["blog"]',
     "",
-    "# 사람이 적용 범위까지 승인한 표면 치환. 단어 경계 한 자리와 보호 원자가 맞을 때만 결과를 낸다",
+    "# 사람이 적용 범위까지 승인한 치환. 단어 경계가 맞고 숫자·링크·코드가 그대로일 때만 바꾼다",
     "# [[operations]]",
     '# before = "여러가지"',
     '# after = "여러 가지"',
@@ -977,15 +1058,15 @@ function runInit(args) {
   const { options } = parseArgs(args);
   const path = /** @type {string} */ (options["--output"] ?? "hanlint.toml");
   const preset = choose(/** @type {string} */ (options["--preset"] ?? "blog"), PRESET_NAMES, "--preset");
-  if (existsSync(path) && !options["--force"]) throw new Error(`${path} 가 이미 있다. 덮어쓰려면 --force`);
+  if (existsSync(path) && !options["--force"]) throw new Error(`이미 있는 파일: ${path}. 덮어쓰려면 --force를 붙인다`);
   writeFileSync(path, renderInit(preset), "utf-8");
   const off = PRESETS[preset];
-  const tail = off.length ? `preset ${preset} 이 ${off.length}개를 끈다` : `preset ${preset} 은 규칙을 전부 켠다`;
-  process.stdout.write(`${path} 를 만들었다. ${tail}. 더 끄려면 disable 에 이름을 넣는다\n`);
+  const tail = off.length ? `${preset} 프리셋은 규칙 ${off.length}개를 끈다` : `${preset} 프리셋은 규칙을 전부 켠다`;
+  process.stdout.write(`만들었다: ${path}. ${tail}. 더 끄려면 disable에 이름을 넣는다\n`);
   return 0;
 }
 
-/** 폴더 아래 소스 파일. 뜻은 파이썬 cli/commands/sheet.py 의 sourceUnder 가 소유한다. @param {string} folder @returns {string[]} */
+/** 폴더 아래 소스 파일. 뜻은 파이썬 cli/commands/sheet.py의 sourceUnder가 소유한다. @param {string} folder @returns {string[]} */
 function sourceUnder(folder) {
   /** @type {string[]} */
   const found = [];
@@ -995,22 +1076,24 @@ function sourceUnder(folder) {
       if (!isSkipped(name)) found.push(...sourceUnder(path));
     } else if (SOURCE_SUFFIXES.includes(extname(name).toLowerCase())) found.push(path);
   }
-  return found.sort();
+  // 구분자를 / 로 맞춘 뒤 정렬한다. 뜻은 파이썬 sourceUnder가 소유한다.
+  const posix = (item) => item.split(sep).join("/");
+  return found.sort((a, b) => (posix(a) < posix(b) ? -1 : posix(a) > posix(b) ? 1 : 0));
 }
 
-/** 작업 폴더 기준 상대 경로, 구분자는 `/`. 파이썬 relativeLabel 과 같은 글자를 낸다. @param {string} path */
+/** 작업 폴더 기준 상대 경로, 구분자는 `/`. 파이썬 relativeLabel과 같은 글자를 낸다. @param {string} path */
 function relativeLabel(path) {
   const rel = relative(process.cwd(), resolve(path));
   const label = !rel || rel.startsWith("..") || isAbsolute(rel) ? path : rel;
   return label.split(sep).join("/").replaceAll("\\", "/");
 }
 
-/** 표의 자리 글자. 뜻은 파이썬 SheetRow.place 가 소유한다. @param {import("../report/sheet.js").SheetRow} row */
+/** 표의 자리 글자. 뜻은 파이썬 SheetRow.place가 소유한다. @param {import("../report/sheet.js").SheetRow} row */
 function placeOf(row) {
   return row.column > 0 ? `${row.file}:${row.line}:${row.column}` : `${row.file}:${row.line}`;
 }
 
-/** 표의 고침을 파일에 쓴다. 뜻은 파이썬 applySheet 가 소유한다. @param {string} sheetPath @param {boolean} dryRun @returns {[string[], string[]]} */
+/** 표의 고침을 파일에 쓴다. 뜻은 파이썬 applySheet가 소유한다. @param {string} sheetPath @param {boolean} dryRun @returns {[string[], string[]]} */
 function applySheet(sheetPath, dryRun) {
   const parsed = parseSheet(readFileSync(sheetPath, "utf-8"));
   /** @type {string[]} */
@@ -1028,41 +1111,111 @@ function applySheet(sheetPath, dryRun) {
       failed.push(...rows.map((row) => `${placeOf(row)}: 파일이 없다`));
       continue;
     }
-    const lines = readFileSync(file, "utf-8").split("\n");
-    let changed = false;
-    // 한 줄에 고침이 여럿이면 뒤 칸부터. 앞 칸을 먼저 바꾸면 길이가 달라져 뒤 칸의 자리가 어긋난다.
-    for (const row of [...rows].sort((a, b) => a.line - b.line || b.column - a.column)) {
-      const place = placeOf(row);
-      if (row.line < 1 || row.line > lines.length) {
-        failed.push(`${place}: 그 줄이 없다`);
-        continue;
-      }
-      let newLine = lines[row.line - 1];
-      if (row.column > 0) {
-        const start = row.column - 1;
-        if (newLine.slice(start, start + row.text.length) !== row.text) {
-          failed.push(`${place}: 그 칸에 그 글이 없다. 표를 다시 뽑는다`);
-          continue;
-        }
-        newLine = newLine.slice(0, start) + row.fix + newLine.slice(start + row.text.length);
-      } else {
-        const [replaced, count] = replaceLiteral(newLine, row.text, row.fix);
-        if (count !== 1) {
-          failed.push(`${place}: 글이 그 줄에 ${count}번 있다. 한 번이어야 바꾼다`);
-          continue;
-        }
-        newLine = replaced;
-      }
-      lines[row.line - 1] = newLine;
-      changed = true;
-      applied.push(`${place}: ${row.text} -> ${row.fix}`);
-    }
-    if (changed && !dryRun) writeFileSync(file, lines.join("\n"), "utf-8");
+    // 되돌려 쓰는 뜻은 report/sheet.js의 applyRows가 소유한다 (브라우저의 저장소 쓰기와 같은 함수).
+    const [rewritten, done, problems] = applyRows(readFileSync(file, "utf-8"), rows);
+    applied.push(...done);
+    failed.push(...problems);
+    if (done.length && !dryRun) writeFileSync(file, rewritten, "utf-8");
   }
   return [applied, failed];
 }
 
-/** `hanlint sheet 폴더/ --preset screen` 과 `hanlint sheet apply 시트.md`. 뜻은 파이썬 cli/commands/sheet.py 가 소유한다. @param {string[]} args */
+/** 세 자리마다 쉼표를 찍은 수. 파이썬의 `f"{n:,}"`와 같은 글자다. @param {number} value */
+function comma(value) {
+  return value.toLocaleString("en-US");
+}
+
+/** 색인이 없을 때의 안내. 뜻은 파이썬 cli/commands/usage.py의 missingIndex가 소유한다. @param {string} kind @param {string} root */
+function missingIndex(kind, root) {
+  const kinds = listUsageIndexes(root).map((meta) => String(meta.kind)).join(", ") || "없음";
+  return `${kind} 색인이 없다 (있는 것: ${kinds}). hanlint usage build ${kind} <글 폴더>로 만든다 (txt, md, jsonl. 하위 폴더 포함)`;
+}
+
+/** 함께 쓰는 말 단어 수 상한. 뜻은 파이썬 QUERY_WORDS가 소유한다. */
+const USAGE_QUERY_WORDS = 3;
+
+/** @param {[string, number][]} pairs */
+function pairText(pairs) {
+  return pairs.map(([term, count]) => `${term} ${count}편`).join(", ");
+}
+
+/**
+ * `hanlint usage "단어 …" --kind report --limit 5`, `hanlint usage build <종류> <글 폴더>`, `hanlint usage kinds`. 뜻은 파이썬
+ * cli/commands/usage.py가 소유한다.
+ * @param {string[]} args
+ */
+function runUsage(args) {
+  const { options, positionals } = parseArgs(args);
+  const output = /** @type {string | undefined} */ (options["--output"]);
+  const root = /** @type {string} */ (options["--root"] ?? defaultUsageRoot());
+  const format = choose(/** @type {string} */ (options["--format"] ?? "text"), ["text", "json"], "--format");
+  if (!positionals.length) throw new UsageError('hanlint usage "단어 …" 또는 hanlint usage build <종류> <글 폴더>');
+  if (positionals[0] === "kinds") {
+    const found = listUsageIndexes(root);
+    if (format === "json") {
+      emit(JSON.stringify({ version: 1, root, kinds: found }, null, 2), output);
+      return 0;
+    }
+    if (!found.length) {
+      emit(`${root}에 색인이 없다. hanlint usage build <종류> <글 폴더>로 만든다`, output);
+      return 0;
+    }
+    const lines = [`색인 ${found.length}개 (${root})`];
+    for (const meta of found) lines.push(`  ${meta.kind}: 문서 ${comma(meta.documents)}편, 문장 ${comma(meta.sentences)}개, 단어 ${comma(meta.terms)}종`);
+    emit(lines.join("\n"), output);
+    return 0;
+  }
+  if (positionals[0] === "build") {
+    if (positionals.length !== 3) {
+      emit("hanlint usage build <종류> <글 폴더> 꼴로 준다", output);
+      return 2;
+    }
+    const [, kind, folder] = positionals;
+    if (!existsSync(folder) || !statSync(folder).isDirectory()) {
+      emit(`폴더가 아니다: ${folder}`, output);
+      return 2;
+    }
+    const result = buildUsageIndex(kind, readUsageDocuments(folder), root);
+    emit(`${join(root, kind)}: 문서 ${comma(result.documents)}편, 문장 ${comma(result.sentences)}개, 단어 ${comma(result.terms)}종. hanlint usage "단어" --kind ${kind}로 찾는다`, output);
+    return 0;
+  }
+  const kind = /** @type {string} */ (options["--kind"] ?? USAGE_KINDS[0]);
+  const limit = Math.max(Number(options["--limit"] ?? 5), 0);
+  if (!Number.isInteger(limit)) throw new UsageError("--limit은 정수다");
+  const query = positionals.join(" ");
+  const index = loadUsageIndex(kind, root);
+  if (!index) {
+    emit(missingIndex(kind, root), output);
+    return 2;
+  }
+  const words = usageQueryCores(query)
+    .slice(0, USAGE_QUERY_WORDS)
+    .map((core) => index.collocations(core))
+    .filter((item) => item !== null && (item.predicates.length || item.following.length || item.preceding.length));
+  const hits = index.search(query, limit);
+  if (format === "json") {
+    const data = { version: 2, kind, query, documents: index.documents, sentences: index.sentences, words, hits };
+    emit(JSON.stringify(data, null, 2), output);
+    return 0;
+  }
+  const lines = [`${kind} 용례 (문서 ${index.documents}편, 문장 ${index.sentences}개): ${query}`];
+  for (const item of words) {
+    if (!item) continue;
+    lines.push(`함께 쓰는 말 (${item.term}, 문장 ${item.sampled}개에서)`);
+    for (const [label, pairs] of [["뒤 용언", item.predicates], ["뒤 명사", item.following], ["앞 명사", item.preceding]]) {
+      if (pairs.length) lines.push(`   ${label}: ${pairText(/** @type {[string, number][]} */ (pairs))}`);
+    }
+  }
+  if (!hits.length && limit > 0) lines.push("쓰인 문장이 없다. 단어를 줄이거나 다른 단어로 찾는다");
+  hits.forEach((hit, index) => {
+    lines.push(`${index + 1}. ${hit.text}`);
+    lines.push(`   문서 ${hit.documents}편, 출처 ${hit.source}`);
+  });
+  emit(lines.join("\n"), output);
+  return 0;
+}
+
+/** `hanlint sheet 폴더/ --preset screen`과 `hanlint sheet apply 시트.md`. 뜻은 파이썬 cli/commands/sheet.py가 소유한다. @param {string[]} args */
 function runSheet(args) {
   const { options, positionals } = parseArgs(args);
   const output = /** @type {string | undefined} */ (options["--output"]);
@@ -1083,24 +1236,14 @@ function runSheet(args) {
   /** @type {string[]} */
   const files = [];
   for (const target of positionals) {
-    if (!existsSync(target)) throw new Error(`${target} 이 없다`);
+    if (!existsSync(target)) throw new Error(`없는 파일: ${target}`);
     if (statSync(target).isDirectory()) files.push(...sourceUnder(target));
     else files.push(target);
   }
   const config = configFrom(options, files);
   const format = choose(/** @type {string} */ (options["--format"] ?? "markdown"), ["markdown", "json"], "--format");
-  /** @type {import("../report/sheet.js").SheetRow[]} */
-  const rows = [];
-  for (const file of files) {
-    const label = relativeLabel(file);
-    for (const literal of sourceLiterals(readFileSync(file, "utf-8"), label)) {
-      const findings = runAll(fingerprint(literal.plain, config), config).filter((finding) => finding.severity === "error");
-      // 지적이 하나이고 고침이 있으면 고침 칸에 미리 적는다. 뜻은 파이썬 cli/commands/sheet.py 의 prefilledFix 가 소유한다.
-      const only = literal.plain === literal.text && findings.length === 1 ? findings[0] : null;
-      const fix = only && only.fix !== null && only.quote === literal.plain ? only.fix : "";
-      if (findings.length || options["--all"]) rows.push({ file: label, line: literal.line, text: literal.text, findings, fix, column: literal.column });
-    }
-  }
+  // 디스크의 파일을 읽어 report.sheetRows에 넘긴다. 행의 뜻은 그쪽이 소유한다.
+  const rows = sheetRows(files.map((file) => ({ label: relativeLabel(file), source: readFileSync(file, "utf-8") })), config, Boolean(options["--all"]));
   emit(format === "json" ? renderSheetJson(rows, config.preset, files.length) : renderSheet(rows, config.preset, files.length), output);
   return 0;
 }
@@ -1120,8 +1263,14 @@ function dispatch(argv) {
     process.stdout.write(`hanlint ${version}\n`);
     return 0;
   }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    // npm에는 명령마다의 도움말이 없다. 도움말을 찾은 사람에게 '모르는 옵션' 대신 전체 도움말을 보인다
+    process.stdout.write(`${USAGE}
+`);
+    return 0;
+  }
   if (PYTHON_ONLY.includes(command)) {
-    throw new Error(`${command} 는 파이썬 패키지에 있다 (pip install hanlint). npm 은 ${COMMANDS.join(", ")} 을 제공한다`);
+    throw new Error(`${command} 명령은 파이썬 hanlint에만 있다(pip install hanlint). npm hanlint의 명령: ${COMMANDS.join(", ")}`);
   }
   if (command === "lint") return runLint(rest);
   if (command === "contract") return runContract(rest);
@@ -1138,6 +1287,7 @@ function dispatch(argv) {
   if (command === "baseline") return runBaseline(rest);
   if (command === "doctor") return runDoctor(rest);
   if (command === "sheet") return runSheet(rest);
+  if (command === "usage") return runUsage(rest);
   return runInit(rest);
 }
 
@@ -1152,7 +1302,7 @@ export function main(argv) {
     }
     const failure = /** @type {NodeJS.ErrnoException} */ (error);
     if (failure.code === "ENOENT") {
-      process.stderr.write(`${failure.path} 를 찾지 못했다. 경로를 확인하거나 hanlint --help\n`);
+      process.stderr.write(`찾지 못한 파일: ${failure.path}. 경로를 확인하거나 hanlint --help를 본다\n`);
       return 2;
     }
     process.stderr.write(`${failure.message}\n`);