@unlaxer/dde-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unlaxer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agents-dde-section.md

@@ -0,0 +1,25 @@
+## DDE — Document Deficit Extraction
+
+When the user says "DDE", "DDE して", "ドキュメントレビュー", "用語集を作って", "図が足りない", "リンクが足りない":
+
+1. Read `.claude/skills/dde-session.md` for the full methodology
+2. Read `dde/method.md` (or `kit/method.md`) for background
+3. Read `dde/flows/*.yaml` (or `kit/flows/*.yaml`) for session structure
+4. Identify the target document (argument or README.md)
+5. Collect project context: existing `docs/glossary/` articles, directory structure
+6. Detect reader level (expert / beginner / grandma)
+7. Analyze the document for: undefined terms, missing diagrams, reader gaps
+8. Output a Gap list with 3 categories (A. terms / B. diagrams / C. gaps)
+9. Save Gap list to `dde/sessions/`
+10. Show numbered next-action choices
+
+When the user says "用語集記事を生成して" or selects action 1:
+- Generate `docs/glossary/<term>.md` for each undefined term
+- Use `dde-tool save docs/glossary/<term>.md` to save
+
+When the user says "dde-link して" or selects action 4:
+```bash
+npx dde-link <file>
+```
+
+Details: `dde/method.md`, `dde/flows/`, `.claude/skills/dde-session.md`

package/bin/dde-install.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// dde-install — DDE toolkit をプロジェクトにインストールする
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+const TARGET = process.cwd();
+
+const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+const VERSION = pkg.version;
+const lang = detectLang();
+
+function detectLang() {
+  const env = process.env.LANG || process.env.LC_ALL || '';
+  if (env.startsWith('en')) return 'en';
+  return 'ja';
+}
+
+function cp(src, dst) {
+  if (!existsSync(src)) return false;
+  mkdirSync(dirname(dst), { recursive: true });
+  copyFileSync(src, dst);
+  return true;
+}
+
+function cpDir(srcDir, dstDir) {
+  if (!existsSync(srcDir)) return;
+  mkdirSync(dstDir, { recursive: true });
+  for (const f of readdirSync(srcDir)) {
+    const src = join(srcDir, f);
+    const dst = join(dstDir, f);
+    cp(src, dst);
+  }
+}
+
+function appendSection(filePath, section, marker, label) {
+  if (existsSync(filePath)) {
+    const content = readFileSync(filePath, 'utf8');
+    if (content.includes(marker)) {
+      console.log(`  ${label} already has DDE section`);
+      return;
+    }
+    writeFileSync(filePath, content + '\n' + section);
+    console.log(`  ${label} updated`);
+  } else {
+    writeFileSync(filePath, section);
+    console.log(`  ${label} created`);
+  }
+}
+
+// --- agents セクション（agents-dde-section.md から読む）---
+const agentsSectionPath = join(PKG_ROOT, 'agents-dde-section.md');
+const AGENTS_SECTION = existsSync(agentsSectionPath)
+  ? readFileSync(agentsSectionPath, 'utf8')
+  : '';
+
+// --- .cursorrules セクション ---
+const CURSORRULES_SECTION = `
+# DDE — Document Deficit Extraction
+# https://github.com/unlaxer/dde-toolkit
+
+When the user says "DDE して", "ドキュメントレビュー", "用語集を作って":
+- Read .claude/skills/dde-session.md for instructions
+- Target document: argument or README.md
+- Output Gap list (A. terms / B. diagrams / C. reader gaps)
+- Save to dde/sessions/
+- Generate docs/glossary/<term>.md for undefined terms
+- Run: npx dde-link <file>
+`.trimStart();
+
+// =============================================================================
+console.log(`DDE toolkit — installing to ${TARGET} (lang=${lang})\n`);
+
+// 1. dde/ ディレクトリをプロジェクトに展開（DGE の dge/ と同じ構造）
+const ddeDir = join(TARGET, 'dde');
+mkdirSync(ddeDir, { recursive: true });
+console.log(`  dde/ created`);
+
+// method.md
+if (cp(join(PKG_ROOT, 'method.md'), join(ddeDir, 'method.md'))) {
+  console.log(`  dde/method.md created`);
+}
+
+// flows/
+const flowsSrc = join(PKG_ROOT, 'flows');
+const flowsDst = join(ddeDir, 'flows');
+if (existsSync(flowsSrc)) {
+  cpDir(flowsSrc, flowsDst);
+  console.log(`  dde/flows/ created`);
+}
+
+// templates/
+const tmplSrc = join(PKG_ROOT, 'templates');
+const tmplDst = join(ddeDir, 'templates');
+if (existsSync(tmplSrc) && readdirSync(tmplSrc).length > 0) {
+  cpDir(tmplSrc, tmplDst);
+  console.log(`  dde/templates/ created`);
+}
+
+// bin/
+const binSrc = join(PKG_ROOT, 'bin');
+const binDst = join(ddeDir, 'bin');
+mkdirSync(binDst, { recursive: true });
+if (cp(join(binSrc, 'dde-tool.js'), join(binDst, 'dde-tool.js'))) {
+  console.log(`  dde/bin/dde-tool.js created`);
+}
+
+// sessions/ (空ディレクトリ)
+const sessionsDir = join(ddeDir, 'sessions');
+if (!existsSync(sessionsDir)) {
+  mkdirSync(sessionsDir, { recursive: true });
+  writeFileSync(join(sessionsDir, '.gitkeep'), '');
+  console.log(`  dde/sessions/ created`);
+}
+
+// version.txt
+writeFileSync(join(ddeDir, 'version.txt'), VERSION + '\n');
+console.log(`  dde/version.txt created (v${VERSION})`);
+
+// 2. docs/glossary/
+const glossaryDir = join(TARGET, 'docs', 'glossary');
+if (!existsSync(glossaryDir)) {
+  mkdirSync(glossaryDir, { recursive: true });
+  console.log(`  docs/glossary/ created`);
+} else {
+  console.log(`  docs/glossary/ already exists`);
+}
+
+// 3. .claude/skills/
+const skillsTarget = join(TARGET, '.claude', 'skills');
+mkdirSync(skillsTarget, { recursive: true });
+
+for (const file of ['dde-session.md', 'dde-update.md']) {
+  const src = join(PKG_ROOT, 'skills', file);
+  const dst = join(skillsTarget, file);
+  if (cp(src, dst)) {
+    console.log(`  .claude/skills/${file} created`);
+  }
+}
+
+// 4. AGENTS.md
+if (AGENTS_SECTION) {
+  appendSection(join(TARGET, 'AGENTS.md'), AGENTS_SECTION, '## DDE —', 'AGENTS.md');
+}
+
+// 5. GEMINI.md
+if (AGENTS_SECTION) {
+  appendSection(join(TARGET, 'GEMINI.md'), AGENTS_SECTION, '## DDE —', 'GEMINI.md');
+}
+
+// 6. .cursorrules
+appendSection(join(TARGET, '.cursorrules'), CURSORRULES_SECTION, '# DDE —', '.cursorrules');
+
+// =============================================================================
+console.log(`\nDone! DDE toolkit is ready. (v${VERSION}, lang=${lang})`);
+console.log(`\n  Claude Code で「DDE して」と言えば起動します。`);
+console.log(`  Codex (AGENTS.md), Gemini CLI (GEMINI.md), Cursor (.cursorrules) にも対応。`);
+console.log(`  Try: "README.md を DDE して"`);
+console.log(`\nMIT License.`);

package/bin/dde-link.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// dde-link CLI — Markdown ファイルに用語リンクを自動付与する
+
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { link } from '../lib/linker.js';
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    check:      { type: 'boolean', default: false },
+    fix:        { type: 'boolean', default: false },
+    'dry-run':  { type: 'boolean', default: false },
+    glossary:   { type: 'string' },
+    lang:       { type: 'string', default: 'auto' },
+    dictionary: { type: 'string' },
+    help:       { type: 'boolean', short: 'h', default: false },
+  },
+  allowPositionals: true,
+});
+
+if (values.help || positionals.length === 0) {
+  console.log(`
+Usage: dde-link <file> [options]
+
+Options:
+  --check       リンク漏れを検出（exit code 1 で失敗）
+  --fix         ファイルを上書き（デフォルト動作）
+  --dry-run     変更プレビュー（stdout に diff 出力）
+  --glossary    用語集ディレクトリ（デフォルト: docs/glossary/）
+  --lang        言語: auto / en / ja（デフォルト: auto）
+  --dictionary  辞書ファイルパス（デフォルト: docs/glossary/dictionary.yaml）
+  -h, --help    このヘルプを表示
+  `.trim());
+  process.exit(0);
+}
+
+const filePath = resolve(positionals[0]);
+
+try {
+  const result = link(filePath, {
+    glossaryDir:    values.glossary   ? resolve(values.glossary) : undefined,
+    dictionaryPath: values.dictionary ? resolve(values.dictionary) : undefined,
+    lang:           values.lang,
+    check:          values.check,
+    dryRun:         values['dry-run'],
+  });
+
+  if (values.check) {
+    if (result.unlinked.length === 0) {
+      console.log('✓ リンク漏れなし');
+      process.exit(0);
+    } else {
+      console.log(`リンク漏れ: ${result.unlinked.length} 件`);
+      for (const u of result.unlinked) {
+        console.log(`  "${u.term}" (${u.count} 箇所)`);
+      }
+      process.exit(1);
+    }
+  }
+
+  if (values['dry-run']) {
+    if (result.changeCount === 0) {
+      console.log('変更なし');
+    } else {
+      console.log(`変更予定: ${result.changeCount} 件\n`);
+      console.log(result.diff);
+    }
+    process.exit(0);
+  }
+
+  // --fix or default
+  if (result.changeCount === 0) {
+    console.log('変更なし');
+  } else {
+    console.log(`${result.changeCount} 件のリンクを追加しました: ${filePath}`);
+  }
+  process.exit(0);
+
+} catch (err) {
+  console.error(`エラー: ${err.message}`);
+  process.exit(1);
+}

package/bin/dde-tool.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// dde-tool — DDE MUST enforcement CLI
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version;
+
+const command = process.argv[2];
+const arg = process.argv[3];
+
+function cmdSave() {
+  const file = arg;
+  if (!file) {
+    console.error('ERROR: file path required. Usage: echo "content" | dde-tool save <file>');
+    process.exit(1);
+  }
+
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+
+  let content = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { content += chunk; });
+  process.stdin.on('end', () => {
+    writeFileSync(file, content);
+    const bytes = Buffer.byteLength(content);
+    console.log(`SAVED: ${file} (${bytes} bytes)`);
+  });
+}
+
+function cmdPrompt() {
+  const flow = arg || 'quick';
+
+  // dde/flows/ → kit/flows/ の順で探す
+  const candidates = [
+    join(process.cwd(), 'dde', 'flows', `${flow}.yaml`),
+    join(process.cwd(), 'kit', 'flows', `${flow}.yaml`),
+  ];
+
+  for (const yamlFile of candidates) {
+    if (existsSync(yamlFile)) {
+      const content = readFileSync(yamlFile, 'utf8');
+      const lines = content.split('\n');
+      let inPostActions = false;
+      const actions = [];
+
+      for (const line of lines) {
+        if (line.match(/^post_actions:/)) { inPostActions = true; continue; }
+        if (inPostActions && line.match(/^\S/) && !line.match(/^\s/)) break;
+        if (inPostActions) {
+          const match = line.match(/display_name:\s*"(.+?)"/);
+          if (match) actions.push(match[1]);
+        }
+      }
+
+      if (actions.length > 0) {
+        actions.forEach((a, i) => console.log(`  ${i + 1}. ${a}`));
+        return;
+      }
+    }
+  }
+
+  // デフォルト選択肢
+  console.log('  1. 用語集記事を全部生成する');
+  console.log('  2. mermaid 図を生成する');
+  console.log('  3. 読者ギャップを修正提案する');
+  console.log('  4. dde-link でリンクを付ける');
+  console.log('  5. 後で');
+}
+
+function cmdVersion() {
+  console.log(`dde-tool v${VERSION}`);
+}
+
+function cmdHelp() {
+  console.log(`dde-tool v${VERSION} — DDE MUST enforcement CLI
+
+Commands:
+  save <file>       Save stdin to file (MUST: always save Gap list)
+  prompt [flow]     Show numbered choices from flow YAML (MUST: show choices)
+  version           Show version
+  help              Show this help
+
+Examples:
+  echo "gap content" | dde-tool save dde/sessions/2026-01-01-readme.md
+  dde-tool prompt quick`);
+}
+
+switch (command) {
+  case 'save':    cmdSave();    break;
+  case 'prompt':  cmdPrompt();  break;
+  case 'version':
+  case '-v':
+  case '--version': cmdVersion(); break;
+  case 'help':
+  case '-h':
+  case '--help':
+  case undefined: cmdHelp(); break;
+  default:
+    console.error(`ERROR: unknown command "${command}". Run "dde-tool help" for usage.`);
+    process.exit(1);
+}

package/flows/quick.yaml

@@ -0,0 +1,78 @@
+name: quick
+display_name: "⚡ クイック — 用語を抽出して単語帳を作る"
+
+trigger_keywords: ["DDE して", "DDE", "ドキュメントレビュー", "用語集を作って", "単語帳を作って", "リンクが足りない"]
+
+defaults:
+  exclude_dirs: ["dde", "dge", "node_modules", ".git", ".claude"]
+  reader_level: beginner
+  article_length: medium   # short / medium / long / custom
+
+workflow:
+  steps:
+    - id: select_docs
+      display_name: "対象ドキュメント群を選択"
+      mode: confirm
+      note: "md 一覧（多い場合はフォルダ一覧）を出してユーザーが除外指定"
+    - id: level
+      display_name: "読者レベル設定"
+      mode: confirm
+      note: "LLM がドキュメントから推定して提案、ユーザーが確認"
+    - id: article_length
+      display_name: "記事の分量設定"
+      mode: confirm
+      note: "short（〜200字）/ medium（〜500字）/ long（〜1000字）/ 文字数直指定"
+    - id: extract
+      display_name: "用語抽出（LLM）"
+      actor: llm
+      note: "対象ドキュメント群から一括抽出。既存 docs/glossary/ は除外"
+    - id: confirm_terms
+      display_name: "用語一覧を確認"
+      mode: confirm
+    - id: articleize
+      display_name: "記事生成（LLM）"
+      actor: llm
+    - id: save
+      display_name: "単語帳保存"
+    - id: link
+      display_name: "dde-link 実行（CLI）"
+      actor: cli
+      note: "対象ドキュメント群と同じファイルセットに適用"
+
+must_rules:
+  - id: save
+    text: "生成した記事は保存（無条件）"
+  - id: output_table
+    text: "抽出した用語を一覧テーブルで出力してからユーザーに確認"
+  - id: choices
+    text: "記事生成後に番号付き選択肢を提示（省略しない）"
+
+extract:
+  actor: llm
+  scope: document_group    # 1ファイルではなく選択されたドキュメント群全体
+  filter: "選択した読者レベルで分からない用語のみ（docs/glossary/ に既存記事があれば除外）"
+  output: "用語一覧テーブル（用語 / 出現ドキュメント / 重要度）"
+
+articleize:
+  actor: llm
+  per: term
+  output_dir: docs/glossary/
+  filename_rule: "<slug>.md（英語）, <slug>.ja.md（日本語）"
+  length:
+    short:  "〜200字。定義1文 + 例1文"
+    medium: "〜500字。定義 + 説明 + 例。デフォルト"
+    long:   "〜1000字。定義 + 詳細 + コード例 + 関連用語"
+
+output_dir: dde/sessions/
+
+post_actions:
+  - id: more_docs
+    display_name: "別のドキュメント群も処理する"
+  - id: another_level
+    display_name: "別の読者レベルで再実行する"
+  - id: run_link
+    display_name: "dde-link でリンクを付ける（まだの場合）"
+  - id: diagrams
+    display_name: "図が必要な箇所を検出する"
+  - id: later
+    display_name: "後で"

package/lib/dictionary.js

@@ -0,0 +1,117 @@
+// dictionary.js — 用語辞書の構築
+// docs/glossary/ の .md ファイル名から用語を自動推定し、
+// dictionary.yaml があれば上書きする
+
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * ファイル名（拡張子なし）から英語用語バリエーションを生成
+ * jwt       → ["JWT", "jwt"]
+ * multi-tenant → ["multi-tenant", "Multi-tenant", "multi tenant", "Multi tenant"]
+ * session-management → ["session management", "Session management", "Session Management", "session-management", "Session-management"]
+ */
+export function inferTerms(slug) {
+  const withSpaces = slug.replace(/-/g, ' ');
+  const withHyphens = slug;
+
+  const variants = new Set();
+
+  // 3文字以下はすべて大文字バリエーション追加（JWT, XSS, SQL など）
+  if (slug.replace(/-/g, '').length <= 3) {
+    variants.add(slug.toUpperCase());
+    variants.add(slug.toLowerCase());
+  }
+
+  // スペース版
+  variants.add(withSpaces);
+  variants.add(capitalize(withSpaces));
+  variants.add(titleCase(withSpaces));
+
+  // ハイフン版（元のまま）
+  if (withHyphens !== withSpaces) {
+    variants.add(withHyphens);
+    variants.add(capitalize(withHyphens));
+  }
+
+  return [...variants].filter(Boolean);
+}
+
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function titleCase(str) {
+  return str.replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * 用語辞書を構築して返す
+ * @param {string} glossaryDir - 用語集ディレクトリ（docs/glossary/ など）
+ * @param {string|null} dictionaryPath - dictionary.yaml のパス
+ * @param {string} lang - 'en' | 'ja'
+ * @returns {{ term: string, file: string, lang: string }[]}
+ */
+export function buildDictionary(glossaryDir, dictionaryPath, lang = 'en') {
+  const entries = [];
+
+  // 1. glossaryDir の .md ファイルを収集（.ja.md は除外）
+  if (existsSync(glossaryDir)) {
+    const files = readdirSync(glossaryDir).filter(f => {
+      return f.endsWith('.md') && !f.endsWith('.ja.md') && f !== 'README.md';
+    });
+
+    for (const file of files) {
+      const slug = basename(file, '.md');
+      const filePath = join(glossaryDir, file);
+      const terms = inferTerms(slug);
+      for (const term of terms) {
+        entries.push({ term, file: filePath, lang: 'en' });
+      }
+    }
+  }
+
+  // 2. dictionary.yaml で上書き・追加
+  const dictPath = dictionaryPath || join(glossaryDir, 'dictionary.yaml');
+  if (existsSync(dictPath)) {
+    const raw = readFileSync(dictPath, 'utf8');
+    const dict = parseYaml(raw);
+
+    for (const [filename, config] of Object.entries(dict || {})) {
+      if (!config || filename === 'README.md') continue;
+      const filePath = join(glossaryDir, filename);
+
+      // 既存エントリを削除して上書き
+      const idx = entries.findIndex(e => e.file === filePath);
+      if (idx !== -1) {
+        // そのファイルの全エントリを削除
+        const toRemove = entries.filter(e => e.file === filePath);
+        for (const r of toRemove) {
+          entries.splice(entries.indexOf(r), 1);
+        }
+      }
+
+      const enTerms = config.en || [];
+      for (const term of enTerms) {
+        entries.push({ term, file: filePath, lang: 'en' });
+      }
+
+      if (lang === 'ja') {
+        const jaTerms = config.ja || [];
+        for (const term of jaTerms) {
+          // .ja.md があればそちらにリンク、なければ .md にリンク
+          const jaFile = filePath.replace(/\.md$/, '.ja.md');
+          const targetFile = existsSync(jaFile) ? jaFile : filePath;
+          entries.push({ term, file: targetFile, lang: 'ja' });
+        }
+      }
+    }
+  }
+
+  // 3. 文字数降順ソート（最長一致のため）
+  entries.sort((a, b) => b.term.length - a.term.length);
+
+  return entries;
+}

package/lib/linker.js

@@ -0,0 +1,104 @@
+// linker.js — dde-link のオーケストレーター
+// dictionary + markdown を組み合わせてリンク処理を実行する
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { buildDictionary } from './dictionary.js';
+import { processMarkdown, findUnlinked } from './markdown.js';
+
+/**
+ * ファイルの言語を検出する
+ * .ja.md → 'ja', それ以外 → 'en'
+ */
+export function detectLang(filePath, forceLang = 'auto') {
+  if (forceLang && forceLang !== 'auto') return forceLang;
+  return filePath.endsWith('.ja.md') ? 'ja' : 'en';
+}
+
+/**
+ * テキスト diff を生成（シンプルな行単位）
+ */
+function createDiff(original, modified) {
+  const origLines = original.split('\n');
+  const modLines = modified.split('\n');
+  const lines = [];
+  const maxLen = Math.max(origLines.length, modLines.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const o = origLines[i];
+    const m = modLines[i];
+    if (o === m) {
+      lines.push(`  ${o ?? ''}`);
+    } else {
+      if (o !== undefined) lines.push(`- ${o}`);
+      if (m !== undefined) lines.push(`+ ${m}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * メイン処理
+ * @param {string} filePath - 対象 Markdown ファイルのパス
+ * @param {object} options
+ * @param {string} [options.glossaryDir] - 用語集ディレクトリ
+ * @param {string} [options.dictionaryPath] - dictionary.yaml のパス
+ * @param {string} [options.lang] - 'auto' | 'en' | 'ja'
+ * @param {boolean} [options.check] - リンク漏れ検出モード
+ * @param {boolean} [options.dryRun] - diff プレビューモード
+ * @returns {{ changeCount: number, unlinked?: any[], diff?: string }}
+ */
+export function link(filePath, options = {}) {
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const lang = detectLang(filePath, options.lang);
+
+  // glossaryDir のデフォルト: ファイルから見て docs/glossary/
+  // または CWD からの docs/glossary/
+  const glossaryDir = options.glossaryDir
+    || findGlossaryDir(filePath)
+    || join(process.cwd(), 'docs', 'glossary');
+
+  const dictionaryPath = options.dictionaryPath
+    || join(glossaryDir, 'dictionary.yaml');
+
+  const dict = buildDictionary(glossaryDir, dictionaryPath, lang);
+  const original = readFileSync(filePath, 'utf8');
+
+  if (options.check) {
+    const unlinked = findUnlinked(original, dict, lang);
+    return { changeCount: unlinked.length, unlinked };
+  }
+
+  const { content, changeCount } = processMarkdown(original, dict, lang, filePath);
+
+  if (options.dryRun) {
+    const diff = createDiff(original, content);
+    return { changeCount, diff };
+  }
+
+  // ファイル上書き
+  if (content !== original) {
+    writeFileSync(filePath, content, 'utf8');
+  }
+
+  return { changeCount };
+}
+
+/**
+ * ファイルパスから docs/glossary/ を探す
+ * 親ディレクトリを辿って docs/glossary/ が見つかれば返す
+ */
+function findGlossaryDir(filePath) {
+  let dir = dirname(filePath);
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, 'docs', 'glossary');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/lib/markdown.js

@@ -0,0 +1,199 @@
+// markdown.js — Markdown のパースと用語リンク化
+// unified + remark を使って AST を操作する
+
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkStringify from 'remark-stringify';
+import { visit } from 'unist-util-visit';
+import { relative, dirname, resolve } from 'path';
+
+/**
+ * テキストノードに対して用語マッチングを行い、リンクノードに置換する
+ * @param {string} content - Markdown テキスト
+ * @param {{ term: string, file: string, lang: string }[]} dictionary - ソート済み辞書
+ * @param {string} lang - 'en' | 'ja'
+ * @param {string} [sourceFile] - リンクを埋め込むファイルのパス（相対パス計算用）
+ * @returns {{ content: string, changeCount: number }}
+ */
+export function processMarkdown(content, dictionary, lang = 'en', sourceFile = null) {
+  if (!dictionary || dictionary.length === 0) {
+    return { content, changeCount: 0 };
+  }
+
+  const tree = unified().use(remarkParse).parse(content);
+  let changeCount = 0;
+
+  // 段落ごとにマッチ済み用語を追跡
+  // { paragraphNode → Set<term> }
+  const matchedPerParagraph = new Map();
+
+  // リンク化をスキップするノード種別
+  const skipTypes = new Set(['code', 'inlineCode', 'heading', 'link', 'image']);
+
+  // スキップ対象の祖先を持つか判定するため、祖先スタックを管理
+  visit(tree, (node, index, parent) => {
+    if (node.type !== 'text') return;
+
+    // 祖先にスキップ対象があるか確認
+    // unist-util-visit は祖先を直接渡さないので、
+    // parent の type をチェック（link の子テキストはスキップ）
+    if (parent && skipTypes.has(parent.type)) return;
+
+    // 段落の親を特定（マッチカウント用）
+    // 段落内のテキストノードは同じ paragraph 祖先を持つ
+    // ここでは parent が paragraph または tableCell などを想定
+    const paragraphKey = findParagraphAncestor(tree, node);
+
+    if (!matchedPerParagraph.has(paragraphKey)) {
+      matchedPerParagraph.set(paragraphKey, new Set());
+    }
+    const matched = matchedPerParagraph.get(paragraphKey);
+
+    // 辞書の各用語でマッチング（最長一致順にソート済み）
+    const text = node.value;
+    const replacements = findReplacements(text, dictionary, matched, lang);
+
+    if (replacements.length === 0) return;
+
+    // テキストノードを複数ノード（text + link）に分割
+    const newNodes = buildNodes(text, replacements, dictionary, sourceFile);
+    if (newNodes.length === 0) return;
+
+    // parent の children 内で node を newNodes に置換
+    if (parent && Array.isArray(parent.children)) {
+      const idx = parent.children.indexOf(node);
+      if (idx !== -1) {
+        parent.children.splice(idx, 1, ...newNodes);
+        changeCount += replacements.length;
+        // マッチした用語を記録
+        for (const r of replacements) {
+          matched.add(r.term);
+        }
+      }
+    }
+  });
+
+  const result = unified().use(remarkStringify, {
+    bullet: '-',
+    fences: true,
+  }).stringify(tree);
+
+  return { content: result, changeCount };
+}
+
+/**
+ * テキスト内で用語の置換箇所を検出する
+ * - 段落ごとに 1 用語 1 回まで
+ * - 最長一致（辞書はすでに降順ソート済み）
+ */
+function findReplacements(text, dictionary, alreadyMatched, lang) {
+  // 使用済み範囲を追跡（重複マッチ防止）
+  const usedRanges = [];
+  const replacements = [];
+
+  for (const entry of dictionary) {
+    if (entry.lang !== lang && entry.lang !== 'en') continue;
+    if (alreadyMatched.has(entry.term)) continue;
+
+    const idx = text.indexOf(entry.term);
+    if (idx === -1) continue;
+
+    // 重複範囲チェック
+    const start = idx;
+    const end = idx + entry.term.length;
+    const overlaps = usedRanges.some(r => start < r.end && end > r.start);
+    if (overlaps) continue;
+
+    usedRanges.push({ start, end });
+    replacements.push({ term: entry.term, file: entry.file, start, end });
+  }
+
+  // 位置順にソート
+  replacements.sort((a, b) => a.start - b.start);
+  return replacements;
+}
+
+/**
+ * テキストと置換リストから AST ノード配列を生成
+ * @param {string} sourceFile - リンクを埋め込むファイルのパス（相対パス計算用）
+ */
+function buildNodes(text, replacements, dictionary, sourceFile = null) {
+  const nodes = [];
+  let cursor = 0;
+
+  for (const r of replacements) {
+    // 置換前のテキスト
+    if (r.start > cursor) {
+      nodes.push({ type: 'text', value: text.slice(cursor, r.start) });
+    }
+    // リンクURL: sourceFile がある場合は相対パスに変換
+    let url = r.file;
+    if (sourceFile) {
+      const from = dirname(resolve(sourceFile));
+      const to = resolve(r.file);
+      url = relative(from, to);
+      // Windows パス区切りを / に統一
+      url = url.replace(/\\/g, '/');
+    }
+    // リンクノード
+    nodes.push({
+      type: 'link',
+      url,
+      children: [{ type: 'text', value: r.term }],
+    });
+    cursor = r.end;
+  }
+
+  // 残りのテキスト
+  if (cursor < text.length) {
+    nodes.push({ type: 'text', value: text.slice(cursor) });
+  }
+
+  return nodes;
+}
+
+/**
+ * ノードが属する段落（または親ブロック）を探して識別子として返す
+ * 単純に node への参照をキーとして使う
+ */
+function findParagraphAncestor(tree, targetNode) {
+  // 段落を特定するために tree を走査
+  let found = null;
+  visit(tree, ['paragraph', 'tableCell', 'listItem'], (node) => {
+    if (found) return;
+    // このノードの子孫に targetNode があるか
+    let has = false;
+    visit(node, 'text', (t) => {
+      if (t === targetNode) has = true;
+    });
+    if (has) found = node;
+  });
+  return found || targetNode;
+}
+
+/**
+ * Markdown 内でリンクされていない用語を検出する（--check 用）
+ * @returns {{ term: string, file: string, count: number }[]}
+ */
+export function findUnlinked(content, dictionary, lang = 'en') {
+  const tree = unified().use(remarkParse).parse(content);
+  const skipTypes = new Set(['code', 'inlineCode', 'heading', 'link', 'image']);
+  const unlinked = new Map(); // term → { file, count }
+
+  visit(tree, 'text', (node, index, parent) => {
+    if (parent && skipTypes.has(parent.type)) return;
+
+    for (const entry of dictionary) {
+      if (entry.lang !== lang && entry.lang !== 'en') continue;
+      if (node.value.includes(entry.term)) {
+        const key = entry.term;
+        if (!unlinked.has(key)) {
+          unlinked.set(key, { term: entry.term, file: entry.file, count: 0 });
+        }
+        unlinked.get(key).count++;
+      }
+    }
+  });
+
+  return [...unlinked.values()];
+}

package/method.md

@@ -0,0 +1,93 @@
+# DDE Method — Document Deficit Extraction
+
+## 前提条件
+
+- **必要なもの**: LLM（Claude, GPT-4, Gemini 等）へのアクセス
+- **推奨**: Claude Code（skills/ で自動発動）
+- **入力**: レビュー対象のドキュメント（README, API 仕様, 設計書など）
+- **出力**: 用語集記事 + 単語帳（dictionary.yaml）+ クリッカブルリンク
+
+---
+
+## 最低限これだけ読め（3分版）
+
+> **TL;DR** — 以下を読めば DDE を始められる。
+
+**DDE とは**: 読者レベルを決めて、ドキュメントの用語を抜き出して、記事化する。それを単語帳にして、ドキュメントをクリッカブルにする。
+
+**4 ステップ**:
+1. **Level** — 想定読者のレベルを決める（expert / beginner / grandma）
+2. **Extract** — そのレベルで「分からない用語」をドキュメントから抽出する
+3. **Articleize** — 用語ごとに glossary 記事を生成する
+4. **Link** — dde-link で用語をクリッカブルにする
+
+**最初にやること**:
+1. ドキュメントを用意する（README.md など）
+2. 「DDE して」と Claude Code に言う
+3. 読者レベルを確認または指定する
+4. 生成された記事をレビューして承認する
+
+---
+
+## 原理
+
+普通のドキュメントレビューは「書いてあることの検証」。
+DDE は「読者には分からない用語の洗い出し」。
+
+書いた側には自明な用語が、読者には不透明なまま残っている。
+この「前提の非対称」を、読者レベルを明示して LLM に検出させる。
+
+---
+
+## DDE の 4 ステップ
+
+```
+Step 1: Level — 想定読者を決める
+  「beginner」「expert」「grandma」のどれか。
+  曖昧なら beginner をデフォルトにする。
+
+Step 2: Extract — 用語を抽出する
+  LLM がドキュメントを読んで、
+  そのレベルの読者が分からない用語を列挙する。
+  docs/glossary/ に既存記事があれば除外する。
+
+Step 3: Articleize — 記事を生成する
+  用語ごとに docs/glossary/<slug>.md を生成する。
+  レベルに応じてトーンを変える。
+
+Step 4: Link — dde-link を実行する
+  npx dde-link <file>
+  用語を [term](docs/glossary/xxx.md) に自動置換する。
+```
+
+---
+
+## 3 段階の読者レベル
+
+```
+expert   — 同分野の開発者（定義 + 技術詳細 + コード例）
+beginner — 初学者（やさしい説明 + 具体例）
+grandma  — 技術ゼロ（身近な例えだけ）
+```
+
+同じ用語でも、レベルによって抽出される用語も記事のトーンも変わる。
+
+---
+
+## dde-link の動作
+
+```
+1. docs/glossary/ の .md ファイル名から用語を自動推定
+2. dictionary.yaml があれば上書き（日本語用語・別名対応）
+3. 最長一致、段落ごとに 1 回 → [用語](docs/glossary/xxx.md) に置換
+スキップ: コードブロック / インラインコード / 見出し / 既存リンク
+```
+
+---
+
+## 実績（volta-auth-proxy）
+
+- 241 の用語集記事（120 EN + 121 JA）
+- README に 334 のクリッカブルリンク
+- 11 の mermaid フロー図
+- 3 段階の読者レベル対応

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@unlaxer/dde-toolkit",
+  "version": "0.1.0",
+  "description": "Document Deficit Extraction — find what's not understood in your docs",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "dde-install": "bin/dde-install.js",
+    "dde-link": "bin/dde-link.js",
+    "dde-tool": "bin/dde-tool.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "flows/",
+    "skills/",
+    "templates/",
+    "method.md",
+    "agents-dde-section.md",
+    "version.txt",
+    "LICENSE"
+  ],
+  "keywords": [
+    "documentation",
+    "glossary",
+    "auto-link",
+    "mermaid",
+    "llm",
+    "claude-code",
+    "dde",
+    "dge"
+  ],
+  "dependencies": {
+    "unified": "^11.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "unist-util-visit": "^5.0.0",
+    "yaml": "^2.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skills/dde-session.md

@@ -0,0 +1,223 @@
+<!-- DDE-toolkit (MIT License) -->
+
+# Skill: DDE Session
+
+## Trigger
+「DDE して」「用語集を作って」「単語帳を作って」「ドキュメントレビューして」「リンクが足りない」「<ファイル名> を DDE して」
+
+## MUST（3 個。これだけ守れ）
+1. **生成した記事は無条件で保存。** ユーザーに聞かない。
+2. **抽出した用語を一覧テーブルで出力してからユーザーに確認。**
+3. **記事生成後に番号付き選択肢を提示。省略するな。**
+
+---
+
+## 初回オンボーディング
+テーマなしで「DDE」「DDE って何」と呼ばれたとき:
+
+```
+DDE toolkit v0.1.0 — Document Deficit Extraction
+
+読者レベルを決めて → 用語を抽出して → 記事化 → 単語帳 → クリッカブルなドキュメント
+
+📖 フロー:
+  1. ドキュメント群を選択（対象ファイル・除外フォルダを確認）
+  2. 読者レベルを設定（LLM が推定して提案）
+  3. 記事の分量を設定（short / medium / long）
+  4. 用語を LLM が一括抽出 → 一覧確認
+  5. 用語ごとに glossary 記事を生成 → docs/glossary/
+  6. dde-link が対象ドキュメント群にリンクを埋め込む
+
+👥 3 段階の読者レベル:
+  expert   — 同分野の開発者
+  beginner — 初学者（デフォルト）
+  grandma  — 技術ゼロ
+
+🔗 dde-link（LLM 不要）:
+  npx dde-link README.md            # 自動リンク実行
+  npx dde-link README.md --check    # リンク漏れチェック（CI 用）
+  npx dde-link README.md --dry-run  # プレビュー
+
+詳しくは: dde/method.md
+```
+
+---
+
+## 手順
+
+### Step 0: flow 読み込み
+`dde/flows/` の YAML、なければ `kit/flows/` の YAML を読む。
+`defaults.exclude_dirs` を確認する（デフォルト: `dde/`, `dge/`, `node_modules/`, `.git/`, `.claude/`）。
+
+### Step 1: 対象ドキュメント群の選択（MUST: ユーザーに確認）
+
+プロジェクト内の `.md` ファイルを列挙する。
+- **50 ファイル未満**: ファイル一覧を表示
+- **50 ファイル以上**: フォルダ一覧を表示
+
+```
+対象ドキュメントを選択してください。
+
+フォルダ一覧（dde/, dge/, node_modules/ は除外済み）:
+  ✅ docs/          (12 ファイル)
+  ✅ README.md
+  ✅ CONTRIBUTING.md
+  ⬜ docs/internal/ (除外候補)
+
+除外したいファイル・フォルダがあれば指定してください。
+なければそのまま進みます。
+```
+
+確定したファイルセットが「抽出元 = リンク適用先」になる。
+
+### Step 2: 読者レベルの設定（MUST: LLM が推定してから確認）
+
+対象ドキュメントの語彙・トーンを見て LLM がレベルを推定し、ユーザーに提案する。
+
+```
+ドキュメントを読みました。推定: beginner
+
+根拠: 専門用語が多いが説明がない。初学者には伝わらない箇所が目立つ。
+
+読者レベルを確認してください:
+1. expert   — 同分野の開発者
+2. beginner — 初学者 ← 推定
+3. grandma  — 技術ゼロ
+
+このまま beginner で進めますか？
+```
+
+### Step 3: 記事の分量設定
+
+```
+記事の分量を選んでください:
+1. short  — 〜200字（定義1文 + 例1文）
+2. medium — 〜500字（定義 + 説明 + 例）← デフォルト
+3. long   — 〜1000字（定義 + 詳細 + コード例 + 関連用語）
+4. カスタム — 文字数を直接指定
+
+このまま medium で進めますか？
+```
+
+### Step 4: 用語抽出（LLM）
+
+対象ドキュメント群を読んで、選択した読者レベルで「分からない可能性がある用語」を一括抽出する。
+
+**ルール:**
+- `docs/glossary/` に既存記事があるものは除外（スラッグが一致するもの）
+- 固有名詞（プロダクト名・企業名など）は除外
+- コードブロック内の識別子は除外
+- 重要度: その用語なしでは内容が理解できない → 🔴 High / 補足があると助かる → 🟡 Medium
+
+**出力（MUST: ユーザーに確認してから記事生成へ進む）:**
+
+```
+## 抽出した用語一覧（beginner 視点）
+
+| # | 用語 | 出現ドキュメント | 既存記事 | 重要度 |
+|---|------|----------------|---------|--------|
+| 1 | JWT  | README.md, docs/auth.md | なし | 🔴 High |
+| 2 | OAuth 2.0 | docs/auth.md | なし | 🔴 High |
+| 3 | リフレッシュトークン | docs/auth.md | なし | 🟡 Medium |
+
+N 件抽出しました。記事を生成しますか？
+除外したい用語があれば番号で指定してください（例: 3,5）。
+```
+
+### Step 5: 記事生成（LLM）
+
+確認後、用語ごとに `docs/glossary/<slug>.md` を生成して保存する。
+
+**スラッグ規則:** 小文字、スペース → ハイフン（`json-web-token.md`）
+
+**テンプレート（expert）:**
+```markdown
+# <Term>
+
+## 定義
+<1-2 文で核心を定義>
+
+## 技術詳細
+<実装・仕様の詳細>
+
+## コード例
+\`\`\`<lang>
+<example>
+\`\`\`
+
+## 関連用語
+- [<term>](../glossary/<slug>.md)
+```
+
+**テンプレート（beginner）:**
+```markdown
+# <Term>
+
+## ひとことで言うと
+<1 文でやさしく>
+
+## もう少し詳しく
+<例えを使って 3-5 文>
+
+## 使われる場面
+<具体的なシナリオ>
+
+## 関連用語
+- [<term>](../glossary/<slug>.md)
+```
+
+**テンプレート（grandma）:**
+```markdown
+# <Term>
+
+## 身近な例えで言うと
+<日常の例え 1-3 文>
+```
+
+`dde-tool save docs/glossary/<slug>.md` で保存。
+
+### Step 6: 単語帳（dictionary.yaml）更新
+
+日本語ドキュメントが対象の場合、または日本語用語・別名を追加したい場合、
+`docs/glossary/dictionary.yaml` を生成・更新する。
+
+```yaml
+# docs/glossary/dictionary.yaml
+jwt.md:
+  en: ["JWT", "JSON Web Token"]
+  ja: ["JWT"]
+
+oauth.md:
+  en: ["OAuth", "OAuth 2.0"]
+  ja: ["OAuth"]
+```
+
+### Step 7: dde-link の実行（CLI）
+
+**適用先は Step 1 で選択したドキュメント群と同じ。** ユーザーに再確認は不要。
+
+```bash
+# 選択したファイルに対して順番に実行
+npx dde-link README.md
+npx dde-link docs/auth.md
+# ...
+```
+
+初回は `--dry-run` で差分を表示してから `--fix` を推奨する。
+
+### Step 8: 次アクション提示（MUST: 省略しない）
+
+```
+1. 別のドキュメント群も処理する
+2. 別の読者レベルで再実行する
+3. dde-link を実行する（まだの場合）
+4. 図が必要な箇所を検出する
+5. 後で
+```
+
+---
+
+## 注意
+- `docs/glossary/` に既存記事がある場合は上書きしない（差分のみ提案）
+- dde-link の `--fix` は上書き。事前に `--dry-run` を推奨
+- 将来フェーズ: HTML からの用語抽出 + ホバー表示（v0.2.0 予定）

package/skills/dde-update.md

@@ -0,0 +1,64 @@
+<!-- DDE-toolkit (MIT License) -->
+
+# Skill: DDE toolkit アップデート
+
+## Trigger
+ユーザーが以下のいずれかを言ったとき:
+- 「DDE を更新して」
+- 「DDE をアップデートして」
+- 「dde update」
+
+## 手順
+
+### Step 1: 現在のバージョンを確認
+`dde/version.txt` を読んでローカルバージョンを表示する。
+ファイルがなければ「バージョン情報がありません（古いインストールです）」と表示。
+
+### Step 2: 更新元を特定
+
+`node_modules/@unlaxer/dde-toolkit/package.json` の version と `dde/version.txt` を比較:
+
+```
+現在: v0.1.0
+更新元: v0.2.0
+```
+
+npm install されていなければ `npm update @unlaxer/dde-toolkit` の手順を案内する。
+
+### Step 3: 更新内容を説明してユーザーに確認
+
+```
+以下の toolkit ファイルが上書きされます:
+- dde/method.md
+- dde/flows/*.yaml
+- dde/templates/*.md
+- dde/bin/*
+- dde/version.txt
+- .claude/skills/dde-session.md
+- .claude/skills/dde-update.md
+
+以下は触りません:
+- docs/glossary/（あなたの用語集記事）
+- dde/sessions/（あなたの DDE session 出力）
+
+更新しますか？
+```
+
+**ユーザーの確認を待つ。勝手に上書きしない。**
+
+### Step 4: 更新を実行
+
+```bash
+npx dde-install
+```
+
+### Step 5: 結果を報告
+
+```
+DDE toolkit を v<新バージョン> に更新しました。
+docs/glossary/ と dde/sessions/ は変更されていません。
+```
+
+## MUST ルール
+1. **更新前に必ずユーザーの確認を得る。**
+2. **docs/glossary/ と dde/sessions/ には絶対に触らない。**

package/version.txt

@@ -0,0 +1 @@
+0.1.0