knowy-cli 0.1.2

package/src/i18n.js

@@ -0,0 +1,172 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWY_CONFIG } from './constants.js';
+
+/**
+ * Detect the user's language from system environment.
+ * Returns a BCP-47 language tag like 'en', 'zh-TW', 'ja', etc.
+ */
+export function detectLanguage() {
+  // Try LANG, LC_ALL, LC_MESSAGES
+  const raw = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+  // e.g. "zh_TW.UTF-8" → "zh-TW", "en_US.UTF-8" → "en"
+  const match = raw.match(/^([a-z]{2})(?:_([A-Z]{2}))?/);
+  if (match) {
+    const lang = match[1];
+    const region = match[2];
+    if (region) return `${lang}-${region}`;
+    return lang;
+  }
+
+  // Fallback: try Intl
+  try {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (locale) return locale;
+  } catch { /* ignore */ }
+
+  return 'en';
+}
+
+/**
+ * Resolve language: .knowy.json override > detected system language.
+ * Normalizes to a supported language key.
+ */
+export async function resolveLanguage(projectRoot) {
+  // Check .knowy.json override
+  try {
+    const config = JSON.parse(await readFile(join(projectRoot, KNOWY_CONFIG), 'utf-8'));
+    if (config.language) return normalizeLanguage(config.language);
+  } catch { /* no config yet */ }
+
+  return normalizeLanguage(detectLanguage());
+}
+
+/**
+ * Normalize a locale string to a supported language key.
+ * Supported: 'en', 'zh-TW'
+ * Add more as needed.
+ */
+export function normalizeLanguage(locale) {
+  if (!locale) return 'en';
+  const lower = locale.toLowerCase();
+  if (lower.startsWith('zh')) return 'zh-TW';
+  // Add more mappings here:
+  // if (lower.startsWith('ja')) return 'ja';
+  // if (lower.startsWith('ko')) return 'ko';
+  return 'en';
+}
+
+// ── Message Catalog ────────────────────────────────────────────────
+
+const messages = {
+  en: {
+    // CLI
+    'cli.init.exists': '.knowledge/ already exists.',
+    'cli.init.continue': 'Continue? (Knowledge files will not be overwritten)',
+    'cli.init.aborted': 'Aborted.',
+    'cli.init.created': (f) => `  ✓ Created ${f}`,
+    'cli.init.skipped': (f) => `  · Skipped ${f} (already exists)`,
+    'cli.init.templates': (n) => `  ✓ Installed ${n} templates to .knowledge/.templates/`,
+    'cli.init.detected': (names) => `  Detected: ${names}`,
+    'cli.init.selectTools': 'Select tools to connect:',
+    'cli.init.selectHint': '  Enter numbers to toggle, then press Enter to confirm.',
+    'cli.init.handshake.created': (file, tool) => `  ✓ Created ${file} (${tool})`,
+    'cli.init.handshake.updated': (file, tool) => `  ✓ Updated ${file} (${tool})`,
+    'cli.init.handshake.appended': (file, tool) => `  ✓ Added to ${file} (${tool})`,
+    'cli.init.skills': (n) => `  ✓ Installed ${n} skills to .claude/skills/knowy/`,
+    'cli.init.done': '✅ Done!',
+    'cli.init.nextStep': 'Next step: run /knowy init in your AI tool to populate your knowledge files.',
+    'cli.init.selectLanguage': 'Select language for templates:',
+    'cli.init.langDetected': (lang) => `  Detected language: ${lang}`,
+
+    'cli.update.title': 'update',
+    'cli.update.noConfig': '.knowy.json not found. Run "knowy init" first.',
+    'cli.update.badConfig': 'Failed to read .knowy.json. Run "knowy init" to re-initialize.',
+    'cli.update.templates': (n) => `  ✓ Updated ${n} templates`,
+    'cli.update.skills': (n) => `  ✓ Updated ${n} skills`,
+    'cli.update.newTools': (names) => `  New tools detected: ${names}`,
+    'cli.update.addTools': '  Add knowledge references to these tools?',
+    'cli.update.refreshed': (n) => `  ✓ Refreshed ${n} tool connection(s)`,
+    'cli.update.done': '✅ Update complete.',
+
+    'cli.mcp.title': 'MCP setup',
+    'cli.mcp.selectTools': 'Which tools should use the Knowy MCP server?',
+    'cli.mcp.noSelection': 'No tools selected. Aborted.',
+    'cli.mcp.alreadyConfigured': (name) => `  · ${name}: already configured`,
+    'cli.mcp.added': (name) => `  ✓ ${name}: added Knowy MCP server`,
+    'cli.mcp.done': '✅ MCP setup complete.',
+    'cli.mcp.restart': '   Restart your AI tool to activate the Knowy MCP server.',
+
+    'ui.toggle': 'Toggle (e.g., 1,3,5) or press Enter to confirm: ',
+
+    'cli.help.tagline': 'Give your AI a structured project brain',
+    'cli.help.usage': 'Usage',
+    'cli.help.commands': 'Commands',
+    'cli.help.options': 'Options',
+    'cli.help.init': 'Scaffold .knowledge/ structure and connect AI tools',
+    'cli.help.update': 'Update skills, templates, and tool connections',
+    'cli.help.setupMcp': 'Configure MCP server for your AI tool',
+    'cli.help.help': 'Show this help message',
+    'cli.help.version': 'Show version number',
+    'cli.unknownCommand': (cmd) => `Unknown command: ${cmd}`,
+  },
+
+  'zh-TW': {
+    'cli.init.exists': '.knowledge/ 已存在。',
+    'cli.init.continue': '繼續？（知識文件不會被覆蓋）',
+    'cli.init.aborted': '已取消。',
+    'cli.init.created': (f) => `  ✓ 已建立 ${f}`,
+    'cli.init.skipped': (f) => `  · 已跳過 ${f}（已存在）`,
+    'cli.init.templates': (n) => `  ✓ 已安裝 ${n} 個模板到 .knowledge/.templates/`,
+    'cli.init.detected': (names) => `  偵測到：${names}`,
+    'cli.init.selectTools': '選擇要連結的工具：',
+    'cli.init.selectHint': '  輸入編號切換選擇，按 Enter 確認。',
+    'cli.init.handshake.created': (file, tool) => `  ✓ 已建立 ${file}（${tool}）`,
+    'cli.init.handshake.updated': (file, tool) => `  ✓ 已更新 ${file}（${tool}）`,
+    'cli.init.handshake.appended': (file, tool) => `  ✓ 已加入 ${file}（${tool}）`,
+    'cli.init.skills': (n) => `  ✓ 已安裝 ${n} 個 skills 到 .claude/skills/knowy/`,
+    'cli.init.done': '✅ 完成！',
+    'cli.init.nextStep': '下一步：在你的 AI 工具中執行 /knowy init 來填寫知識文件。',
+    'cli.init.selectLanguage': '選擇模板語言：',
+    'cli.init.langDetected': (lang) => `  偵測到語言：${lang}`,
+
+    'cli.update.title': '更新',
+    'cli.update.noConfig': '找不到 .knowy.json。請先執行 "knowy init"。',
+    'cli.update.badConfig': '無法讀取 .knowy.json。請執行 "knowy init" 重新初始化。',
+    'cli.update.templates': (n) => `  ✓ 已更新 ${n} 個模板`,
+    'cli.update.skills': (n) => `  ✓ 已更新 ${n} 個 skills`,
+    'cli.update.newTools': (names) => `  偵測到新工具：${names}`,
+    'cli.update.addTools': '  要為這些工具加入知識引用嗎？',
+    'cli.update.refreshed': (n) => `  ✓ 已刷新 ${n} 個工具連結`,
+    'cli.update.done': '✅ 更新完成。',
+
+    'cli.mcp.title': 'MCP 設定',
+    'cli.mcp.selectTools': '哪些工具要使用 Knowy MCP server？',
+    'cli.mcp.noSelection': '未選擇任何工具。已取消。',
+    'cli.mcp.alreadyConfigured': (name) => `  · ${name}：已設定`,
+    'cli.mcp.added': (name) => `  ✓ ${name}：已加入 Knowy MCP server`,
+    'cli.mcp.done': '✅ MCP 設定完成。',
+    'cli.mcp.restart': '   請重啟你的 AI 工具以啟用 Knowy MCP server。',
+
+    'ui.toggle': '切換（例如 1,3,5）或按 Enter 確認：',
+
+    'cli.help.tagline': '給你的 AI 一個結構化的專案大腦',
+    'cli.help.usage': '用法',
+    'cli.help.commands': '指令',
+    'cli.help.options': '選項',
+    'cli.help.init': '建立 .knowledge/ 結構並連結 AI 工具',
+    'cli.help.update': '更新 skills、模板和工具連結',
+    'cli.help.setupMcp': '為你的 AI 工具設定 MCP server',
+    'cli.help.help': '顯示此說明',
+    'cli.help.version': '顯示版本號',
+    'cli.unknownCommand': (cmd) => `未知的指令：${cmd}`,
+  },
+};
+
+/**
+ * Get a message function/string for the given language and key.
+ */
+export function t(lang, key) {
+  const catalog = messages[lang] || messages['en'];
+  return catalog[key] || messages['en'][key] || key;
+}

package/src/mcp-server.js

@@ -0,0 +1,471 @@
+import { createInterface } from 'node:readline';
+import { VERSION, PACKAGE_ROOT } from './constants.js';
+
+const PROTOCOL_VERSION = '2025-03-26';
+
+// ── Tool Definitions ───────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'knowy_init',
+    description: 'Scaffold .knowledge/ structure, detect AI tools, inject references, and install skills. Returns a report of what was created.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_path: {
+          type: 'string',
+          description: 'Absolute path to the project root. Defaults to current working directory.',
+        },
+        tools: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Tool IDs to connect (e.g., ["agents-md", "claude-code"]). If omitted, auto-detects and connects all detected tools plus AGENTS.md.',
+        },
+      },
+    },
+  },
+  {
+    name: 'knowy_update',
+    description: 'Update Knowy skills and templates (managed files), re-detect tools, and refresh handshakes. Never overwrites knowledge files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_path: {
+          type: 'string',
+          description: 'Absolute path to the project root. Defaults to current working directory.',
+        },
+      },
+    },
+  },
+  {
+    name: 'knowy_judge',
+    description: 'Cross-check .knowledge/ files for consistency and coherence. Returns a structured health check report with traffic-light indicators.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_path: {
+          type: 'string',
+          description: 'Absolute path to the project root.',
+        },
+        scope: {
+          type: 'string',
+          description: 'What to check: empty for full check, a file name (e.g., "experience"), a pair (e.g., "principles vision"), or an event description.',
+        },
+      },
+    },
+  },
+  {
+    name: 'knowy_next',
+    description: 'Suggest what to work on next based on .knowledge/ files. Returns a feature brief grounded in principles, vision, and experience.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_path: {
+          type: 'string',
+          description: 'Absolute path to the project root.',
+        },
+        direction: {
+          type: 'string',
+          description: 'Optional direction or feature area to explore. If omitted, suggests the next logical step from the roadmap.',
+        },
+      },
+    },
+  },
+];
+
+// ── Tool Handlers ──────────────────────────────────────────────────
+
+async function handleKnowyInit(args) {
+  const projectPath = args.project_path || process.cwd();
+  const { scaffoldKnowledge } = await import('./scaffold.js');
+  const { installTemplates } = await import('./templates.js');
+  const { installSkills } = await import('./skills.js');
+  const { detectTools } = await import('./adapters/detect.js');
+  const { getToolById } = await import('./adapters/registry.js');
+  const { injectHandshake } = await import('./adapters/handshake.js');
+  const { readFile, writeFile } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { KNOWY_CONFIG } = await import('./constants.js');
+  const { resolveLanguage } = await import('./i18n.js');
+
+  const lang = await resolveLanguage(projectPath);
+  const report = [];
+
+  // Scaffold
+  const scaffoldResult = await scaffoldKnowledge(projectPath, lang);
+  for (const f of scaffoldResult.created) report.push(`✓ Created ${f}`);
+  for (const f of scaffoldResult.skipped) report.push(`· Skipped ${f} (already exists)`);
+
+  // Templates
+  const templates = await installTemplates(projectPath, lang);
+  report.push(`✓ Installed ${templates.length} templates`);
+
+  // Detect & handshake
+  const { detected } = await detectTools(projectPath);
+  let toolIds = args.tools;
+  if (!toolIds || toolIds.length === 0) {
+    toolIds = ['agents-md', ...detected];
+  }
+
+  const writtenFiles = new Set();
+  for (const id of toolIds) {
+    const tool = getToolById(id);
+    if (!tool) continue;
+    for (const target of tool.targets) {
+      if (writtenFiles.has(target.file)) continue;
+      const result = await injectHandshake(projectPath, target);
+      writtenFiles.add(target.file);
+      report.push(`✓ ${result.action} ${result.file} (${tool.name})`);
+    }
+  }
+
+  // Skills
+  const skills = await installSkills(projectPath);
+  report.push(`✓ Installed ${skills.length} skills`);
+
+  // Update config
+  const configPath = join(projectPath, KNOWY_CONFIG);
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf-8'));
+  } catch {
+    config = { version: VERSION, createdAt: new Date().toISOString() };
+  }
+  config.version = VERSION;
+  config.language = config.language || lang;
+  config.tools = [...new Set(toolIds)];
+  config.updatedAt = new Date().toISOString();
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  report.push('');
+  report.push('Done! Run /knowy init in your AI tool to populate knowledge files.');
+
+  return report.join('\n');
+}
+
+async function handleKnowyUpdate(args) {
+  const projectPath = args.project_path || process.cwd();
+  const { installTemplates } = await import('./templates.js');
+  const { installSkills } = await import('./skills.js');
+  const { detectTools } = await import('./adapters/detect.js');
+  const { getToolById } = await import('./adapters/registry.js');
+  const { injectHandshake } = await import('./adapters/handshake.js');
+  const { readFile, writeFile, access } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { KNOWY_CONFIG } = await import('./constants.js');
+
+  const configPath = join(projectPath, KNOWY_CONFIG);
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf-8'));
+  } catch {
+    return 'Error: .knowy.json not found. Run knowy_init first.';
+  }
+
+  const report = [];
+
+  // Update managed files
+  const templates = await installTemplates(projectPath);
+  report.push(`✓ Updated ${templates.length} templates`);
+
+  const skills = await installSkills(projectPath);
+  report.push(`✓ Updated ${skills.length} skills`);
+
+  // Re-detect and handshake
+  const { detected } = await detectTools(projectPath);
+  const existingTools = new Set(config.tools || []);
+  const newTools = detected.filter(id => !existingTools.has(id));
+
+  if (newTools.length > 0) {
+    const names = newTools.map(id => getToolById(id)?.name).filter(Boolean);
+    report.push(`New tools detected: ${names.join(', ')}`);
+    for (const id of newTools) {
+      existingTools.add(id);
+    }
+  }
+
+  // Refresh all handshakes
+  const writtenFiles = new Set();
+  for (const id of existingTools) {
+    const tool = getToolById(id);
+    if (!tool) continue;
+    for (const target of tool.targets) {
+      if (writtenFiles.has(target.file)) continue;
+      await injectHandshake(projectPath, target);
+      writtenFiles.add(target.file);
+    }
+  }
+  report.push(`✓ Refreshed ${writtenFiles.size} tool connection(s)`);
+
+  // Update config
+  config.version = VERSION;
+  config.tools = [...existingTools];
+  config.updatedAt = new Date().toISOString();
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  report.push('\nUpdate complete.');
+  return report.join('\n');
+}
+
+async function handleKnowyJudge(args) {
+  const projectPath = args.project_path || process.cwd();
+  const { readFile } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { KNOWLEDGE_DIR } = await import('./constants.js');
+
+  // Read knowledge files
+  const files = {};
+  for (const name of ['principles.md', 'vision.md', 'experience.md']) {
+    try {
+      files[name] = await readFile(join(projectPath, KNOWLEDGE_DIR, name), 'utf-8');
+    } catch {
+      files[name] = null;
+    }
+  }
+
+  const missing = Object.entries(files).filter(([, v]) => v === null).map(([k]) => k);
+  if (missing.length > 0) {
+    return `Cannot run judge — missing files: ${missing.join(', ')}\nRun knowy_init first.`;
+  }
+
+  // Return files content for AI to analyze
+  const scope = args.scope || 'full';
+  const lines = [
+    `## Knowy Judge — Scope: ${scope}`,
+    '',
+    'Below are the current knowledge files. Please perform the cross-check analysis.',
+    '',
+    '### principles.md',
+    '```markdown',
+    files['principles.md'],
+    '```',
+    '',
+    '### vision.md',
+    '```markdown',
+    files['vision.md'],
+    '```',
+    '',
+    '### experience.md',
+    '```markdown',
+    files['experience.md'],
+    '```',
+    '',
+    '### Instructions',
+    '',
+  ];
+
+  if (scope === 'full') {
+    lines.push('Perform a **full check** with all 11 sections:');
+    lines.push('1. Internal Coherence (3): check each file for self-contradictions');
+    lines.push('2. Cross-references (6 directional):');
+    lines.push('   - Principles → Vision: can vision be derived from principles?');
+    lines.push('   - Vision → Principles: does vision require unstated principles?');
+    lines.push('   - Principles → Experience: do principles predict observed patterns?');
+    lines.push('   - Experience → Principles: does experience challenge principles?');
+    lines.push('   - Vision → Experience: does experience support the planned direction?');
+    lines.push('   - Experience → Vision: are there lessons suggesting new opportunities?');
+    lines.push('3. Overall (1): synthesize — where is the most pressure?');
+    lines.push('4. Beyond Scope (1): content that doesn\'t belong');
+    lines.push('5. Suggested Actions: numbered, prioritized');
+  } else {
+    lines.push(`Perform a **scoped check** for: "${scope}"`);
+    lines.push('Show only the relevant sections from the full 11-section check.');
+  }
+
+  lines.push('');
+  lines.push('Use 🟢 (one line) for healthy, 🟡 (expanded) for tensions, 🔴 (expanded) for conflicts.');
+  lines.push('Always quote specific text from the files to support findings.');
+
+  return lines.join('\n');
+}
+
+async function handleKnowyNext(args) {
+  const projectPath = args.project_path || process.cwd();
+  const { readFile, readdir } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { KNOWLEDGE_DIR } = await import('./constants.js');
+
+  // Read knowledge files
+  const files = {};
+  for (const name of ['principles.md', 'vision.md', 'experience.md']) {
+    try {
+      files[name] = await readFile(join(projectPath, KNOWLEDGE_DIR, name), 'utf-8');
+    } catch {
+      files[name] = null;
+    }
+  }
+
+  const missing = Object.entries(files).filter(([, v]) => v === null).map(([k]) => k);
+  if (missing.length > 0) {
+    return `Cannot plan next step — missing files: ${missing.join(', ')}\nRun knowy_init first.`;
+  }
+
+  // Scan for spec tools
+  let specTools = [];
+  try {
+    const skillsDir = join(projectPath, '.claude', 'skills');
+    const skills = await readdir(skillsDir);
+    specTools = skills.filter(s =>
+      s.startsWith('speckit') || s.startsWith('openspec') || s.includes('spec')
+    );
+  } catch { /* no skills dir */ }
+
+  const direction = args.direction || '';
+  const lines = [
+    `## Knowy Next${direction ? ` — Direction: ${direction}` : ''}`,
+    '',
+    'Below are the current knowledge files. Help the user plan their next step.',
+    '',
+    '### principles.md',
+    '```markdown',
+    files['principles.md'],
+    '```',
+    '',
+    '### vision.md',
+    '```markdown',
+    files['vision.md'],
+    '```',
+    '',
+    '### experience.md',
+    '```markdown',
+    files['experience.md'],
+    '```',
+    '',
+    '### Instructions',
+    '',
+  ];
+
+  if (direction) {
+    lines.push(`The user wants to explore: "${direction}"`);
+    lines.push('1. Locate this direction in the vision roadmap');
+    lines.push('2. Check prerequisites');
+    lines.push('3. Find relevant experience lessons');
+  } else {
+    lines.push('The user has no specific direction. Suggest the next logical step:');
+    lines.push('1. Find the next incomplete milestone in the roadmap');
+    lines.push('2. Consider experience lessons that affect priority');
+  }
+
+  lines.push('');
+  lines.push('Converge on a feature brief: name, description, scope, grounding in principles, informed by experience, risks.');
+
+  if (specTools.length > 0) {
+    lines.push('');
+    lines.push(`Spec tools detected in this project: ${specTools.join(', ')}`);
+    lines.push('Suggest the user invoke the appropriate spec tool to flesh out the details.');
+  } else {
+    lines.push('');
+    lines.push('No spec tools detected. Suggest: "You can now use your preferred specification tool to flesh out the details, or start implementing directly."');
+  }
+
+  return lines.join('\n');
+}
+
+// ── MCP Protocol Handler ───────────────────────────────────────────
+
+function makeResponse(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function makeError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  // Notifications (no id) — just acknowledge silently
+  if (id === undefined) return null;
+
+  switch (method) {
+    case 'initialize':
+      return makeResponse(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'knowy', version: VERSION },
+      });
+
+    case 'ping':
+      return makeResponse(id, {});
+
+    case 'tools/list':
+      return makeResponse(id, { tools: TOOLS });
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const args = params?.arguments || {};
+
+      try {
+        let result;
+        switch (toolName) {
+          case 'knowy_init':
+            result = await handleKnowyInit(args);
+            break;
+          case 'knowy_update':
+            result = await handleKnowyUpdate(args);
+            break;
+          case 'knowy_judge':
+            result = await handleKnowyJudge(args);
+            break;
+          case 'knowy_next':
+            result = await handleKnowyNext(args);
+            break;
+          default:
+            return makeError(id, -32602, `Unknown tool: ${toolName}`);
+        }
+        return makeResponse(id, {
+          content: [{ type: 'text', text: result }],
+          isError: false,
+        });
+      } catch (err) {
+        return makeResponse(id, {
+          content: [{ type: 'text', text: `Error: ${err.message}` }],
+          isError: true,
+        });
+      }
+    }
+
+    default:
+      return makeError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+// ── Entry Point ────────────────────────────────────────────────────
+
+export async function startMcpServer() {
+  const rl = createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  const pending = [];
+
+  rl.on('line', (line) => {
+    if (!line.trim()) return;
+
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      const err = makeError(null, -32700, 'Parse error');
+      process.stdout.write(err + '\n');
+      return;
+    }
+
+    const task = handleMessage(msg).then((response) => {
+      if (response) {
+        process.stdout.write(response + '\n');
+      }
+    }).catch((err) => {
+      process.stderr.write(`Error: ${err.message}\n`);
+    });
+    pending.push(task);
+  });
+
+  rl.on('close', async () => {
+    await Promise.all(pending);
+    process.exit(0);
+  });
+
+  process.stderr.write(`knowy MCP server v${VERSION} started\n`);
+}

package/src/scaffold.js

@@ -0,0 +1,53 @@
+import { mkdir, copyFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  KNOWLEDGE_DIR, KNOWY_CONFIG, CORE_FILES, SUBDIRS,
+  PACKAGE_ROOT, VERSION
+} from './constants.js';
+
+async function exists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function scaffoldKnowledge(projectRoot, language = 'en') {
+  const knowledgeDir = join(projectRoot, KNOWLEDGE_DIR);
+  const report = { created: [], skipped: [] };
+
+  // Create .knowledge/ and subdirectories
+  await mkdir(knowledgeDir, { recursive: true });
+  for (const sub of SUBDIRS) {
+    await mkdir(join(knowledgeDir, sub), { recursive: true });
+  }
+
+  // Copy core files from language-specific templates (never overwrite)
+  for (const file of CORE_FILES) {
+    const dest = join(knowledgeDir, file);
+    if (await exists(dest)) {
+      report.skipped.push(file);
+    } else {
+      // Try language-specific template first, fallback to English
+      let src = join(PACKAGE_ROOT, 'templates', language, `${file}.tmpl`);
+      if (!await exists(src)) {
+        src = join(PACKAGE_ROOT, 'templates', 'en', `${file}.tmpl`);
+      }
+      await copyFile(src, dest);
+      report.created.push(file);
+    }
+  }
+
+  // Create .knowy.json
+  const configPath = join(projectRoot, KNOWY_CONFIG);
+  if (await exists(configPath)) {
+    report.skipped.push(KNOWY_CONFIG);
+  } else {
+    await writeFile(configPath, JSON.stringify({
+      version: VERSION,
+      language,
+      createdAt: new Date().toISOString(),
+      tools: []
+    }, null, 2) + '\n');
+    report.created.push(KNOWY_CONFIG);
+  }
+
+  return report;
+}