knowy-cli 0.1.2

package/src/skills.js

@@ -0,0 +1,23 @@
+import { readdir, copyFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SKILLS_SOURCE, SKILLS_TARGET, SKILL_NAMES } from './constants.js';
+
+/**
+ * Install Claude Code skills into the project.
+ * Always overwrites (managed files).
+ */
+export async function installSkills(projectRoot) {
+  const installed = [];
+
+  for (const name of SKILL_NAMES) {
+    const srcDir = join(SKILLS_SOURCE, name);
+    const destDir = join(projectRoot, SKILLS_TARGET, name);
+    await mkdir(destDir, { recursive: true });
+
+    const skillFile = 'SKILL.md';
+    await copyFile(join(srcDir, skillFile), join(destDir, skillFile));
+    installed.push(name);
+  }
+
+  return installed;
+}

package/src/templates.js

@@ -0,0 +1,29 @@
+import { readdir, copyFile, mkdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWLEDGE_DIR, TEMPLATES_DIR, PACKAGE_ROOT } from './constants.js';
+
+async function exists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function installTemplates(projectRoot, language = 'en') {
+  const destDir = join(projectRoot, KNOWLEDGE_DIR, TEMPLATES_DIR);
+  await mkdir(destDir, { recursive: true });
+
+  const installed = [];
+
+  // Install language-specific templates, fallback to English
+  let srcDir = join(PACKAGE_ROOT, 'templates', language);
+  if (!await exists(srcDir)) {
+    srcDir = join(PACKAGE_ROOT, 'templates', 'en');
+  }
+
+  const files = await readdir(srcDir);
+  for (const file of files) {
+    if (!file.endsWith('.tmpl')) continue;
+    await copyFile(join(srcDir, file), join(destDir, file));
+    installed.push(file);
+  }
+
+  return installed;
+}

package/src/ui.js

@@ -0,0 +1,87 @@
+import { createInterface } from 'node:readline';
+import { t } from './i18n.js';
+
+function createRL() {
+  return createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function question(rl, prompt) {
+  return new Promise(resolve => rl.question(prompt, resolve));
+}
+
+/**
+ * Ask a yes/no question. Returns true for yes.
+ */
+export async function confirm(message, defaultYes = true) {
+  const rl = createRL();
+  const hint = defaultYes ? '(Y/n)' : '(y/N)';
+  const answer = await question(rl, `${message} ${hint} `);
+  rl.close();
+  const a = answer.trim().toLowerCase();
+  if (a === '') return defaultYes;
+  return a === 'y' || a === 'yes';
+}
+
+/**
+ * Multi-select from a list of choices.
+ * choices: [{ id, name, checked }]
+ * Returns array of selected ids.
+ */
+export async function multiSelect(message, choices, lang = 'en') {
+  const rl = createRL();
+  const selected = new Set(choices.filter(c => c.checked).map(c => c.id));
+
+  console.log(`\n${message}`);
+
+  for (let i = 0; i < choices.length; i++) {
+    const mark = selected.has(choices[i].id) ? '◉' : '◯';
+    console.log(`  ${mark} ${i + 1}. ${choices[i].name}`);
+  }
+
+  const togglePrompt = t(lang, 'ui.toggle');
+  const answer = await question(rl, `\n${togglePrompt}`);
+  rl.close();
+
+  const input = answer.trim();
+  if (input === '') return [...selected];
+
+  const nums = input.split(/[,\s]+/).map(Number).filter(n => !isNaN(n));
+  for (const n of nums) {
+    const idx = n - 1;
+    if (idx >= 0 && idx < choices.length) {
+      const id = choices[idx].id;
+      if (selected.has(id)) selected.delete(id);
+      else selected.add(id);
+    }
+  }
+
+  return [...selected];
+}
+
+/**
+ * Single-select from a list of choices. Returns selected id.
+ */
+export async function select(message, choices) {
+  const rl = createRL();
+
+  console.log(`\n${message}`);
+  for (let i = 0; i < choices.length; i++) {
+    const marker = choices[i].checked ? '→' : ' ';
+    console.log(`  ${marker} ${i + 1}. ${choices[i].name}`);
+  }
+
+  const answer = await question(rl, `\n> `);
+  rl.close();
+
+  const num = parseInt(answer.trim(), 10);
+  if (num >= 1 && num <= choices.length) {
+    return choices[num - 1].id;
+  }
+
+  // Default to checked item or first item
+  const defaultChoice = choices.find(c => c.checked) || choices[0];
+  return defaultChoice.id;
+}

package/templates/en/experience.md.tmpl

@@ -0,0 +1,47 @@
+# Experience
+
+<!--
+  This file captures distilled lessons from development — not a changelog,
+  but patterns that should influence future decisions.
+
+  Each lesson records the gap between theory and reality.
+  Keep entries short and actionable. Detailed event records belong in
+  .knowledge/history/.
+-->
+
+## Lessons
+
+<!--
+  Add a new section for each significant lesson. Use the four-part format:
+  1. What theory/expectation said
+  2. What actually happened
+  3. How you resolved it
+  4. The distilled lesson
+
+  This format forces you to articulate *why* something was surprising,
+  not just *what* happened.
+-->
+
+### [Lesson Title]
+
+- **Theory said**: [What you expected based on design, principles, or assumptions]
+- **Actually happened**: [What really occurred — be specific]
+- **Resolved by**: [How the gap was bridged — the fix, workaround, or insight]
+- **Lesson**: [One-sentence reusable pattern for next time]
+- **Source**: [Link to history/ entry or PR/commit, if available]
+
+<!--
+  Example:
+
+  ### Verify before reimplementing
+
+  - **Theory said**: The core module only handles evaluation, so we need
+    to build a type checker from scratch.
+  - **Actually happened**: After two days of building, discovered the core
+    module already included full type checking — it just wasn't documented.
+  - **Resolved by**: Deleted the duplicate implementation and documented
+    the existing one.
+  - **Lesson**: Always search existing code before building. The answer
+    may already be there, undocumented.
+  - **Source**: history/010-duplicate-checker.md
+-->

package/templates/en/principles.md.tmpl

@@ -0,0 +1,42 @@
+# Principles
+
+<!--
+  This file captures the core beliefs and rules that guide your project.
+  Start with a root axiom — the single non-negotiable truth — then derive
+  specific principles from it.
+
+  Principles should rarely change. If you find yourself editing this file
+  often, the entries might be decisions (which belong in design/) rather
+  than principles.
+-->
+
+## Root Axiom
+
+<!--
+  What is the one fundamental belief behind this project?
+  Example: "User data belongs to the user, not the platform."
+  Example: "Programs are semantic structures — code is just one projection."
+-->
+
+## Derived Principles
+
+<!--
+  Each principle should trace back to the root axiom or another principle.
+  Explain what it means in practice so your team (and your AI) can apply it.
+-->
+
+### 1. [Principle Name]
+
+<!--
+  Derived from: [Root Axiom / another principle]
+  What it means: ...
+  How to apply: ...
+-->
+
+### 2. [Principle Name]
+
+<!--
+  Derived from: ...
+  What it means: ...
+  How to apply: ...
+-->

package/templates/en/vision.md.tmpl

@@ -0,0 +1,76 @@
+# Vision
+
+<!--
+  This file describes where your project is going. It evolves as your
+  understanding deepens. Update it after each milestone or when priorities
+  shift.
+-->
+
+## Problem Statement
+
+<!--
+  What problem does this project solve? Who has this problem?
+  Why do existing solutions fall short?
+-->
+
+## Core Idea
+
+<!--
+  Your solution in one or two sentences.
+  Example: "A single semantic tree that projects into code, blocks, and
+  flowcharts — edit any view, all stay in sync."
+-->
+
+## Current State
+
+<!--
+  Where is the project right now? What works and what doesn't?
+  Be honest — this helps your AI give realistic suggestions.
+-->
+
+## Architecture
+
+<!--
+  Key technical decisions and why they were made.
+  Link to .knowledge/design/ for detailed design documents.
+-->
+
+## Roadmap
+
+<!--
+  Milestones in order. Use checkboxes to track completion status.
+  For each milestone:
+  - Name + checkbox ([ ] pending, [x] complete)
+  - What it delivers
+  - Prerequisites (which milestones must be done first)
+  - Success criteria (concrete, verifiable)
+
+  Update checkboxes as milestones are completed. /knowy judge will
+  verify that checked items match the actual project state.
+-->
+
+### Phase 1: [Name]
+
+- [ ] Complete
+
+<!--
+  Delivers: ...
+  Prerequisites: none
+-->
+
+**Success criteria:**
+- [ ] [Concrete criterion 1]
+- [ ] [Concrete criterion 2]
+
+### Phase 2: [Name]
+
+- [ ] Complete
+
+<!--
+  Delivers: ...
+  Prerequisites: Phase 1
+-->
+
+**Success criteria:**
+- [ ] [Concrete criterion 1]
+- [ ] [Concrete criterion 2]

package/templates/zh-TW/experience.md.tmpl

@@ -0,0 +1,45 @@
+# 經驗
+
+<!--
+  這份文件記錄從開發過程中蒸餾出的教訓——不是 changelog，
+  而是應該影響未來決策的模式。
+
+  每個教訓記錄「理論」和「現實」之間的落差。
+  保持簡短、可操作。詳細的事件記錄放在 .knowledge/history/。
+-->
+
+## 教訓
+
+<!--
+  每個重要的教訓加一個小節，使用四段式格式：
+  1. 理論/預期怎麼說
+  2. 實際發生了什麼
+  3. 如何解決
+  4. 蒸餾出的教訓
+
+  這個格式迫使你清楚說明「為什麼」令人意外，
+  而不只是「發生了什麼」。
+-->
+
+### [教訓標題]
+
+- **理論說**：[基於設計、原則或假設，你預期會發生什麼]
+- **實際發生**：[真正發生了什麼——要具體]
+- **解決方式**：[如何彌合落差——修復、替代方案或洞察]
+- **教訓**：[一句話的可複用模式]
+- **來源**：[history/ 中的記錄或 PR/commit 連結]
+
+<!--
+  範例：
+
+  ### 實作前先確認功能是否已存在
+
+  - **理論說**：核心模組只處理求值，所以我們需要從頭建一個
+    type checker。
+  - **實際發生**：花了兩天在建，結果發現核心模組已經有完整的
+    型別檢查功能——只是沒有文件記錄。
+  - **解決方式**：刪除重複的實作，為既有功能補上文件。
+  - **教訓**：動手之前先搜尋既有程式碼。答案可能已經在那裡，
+    只是沒被記錄。
+  - **來源**：history/010-duplicate-checker.md
+-->

package/templates/zh-TW/principles.md.tmpl

@@ -0,0 +1,41 @@
+# 原則
+
+<!--
+  這份文件記錄驅動你專案的核心信念和規則。
+  從一個根公理開始——那個唯一不可妥協的真理——
+  然後從中推導出具體的原則。
+
+  原則應該很少修改。如果你經常編輯這份文件，
+  那些內容可能是設計決策（應該放在 design/），而不是原則。
+-->
+
+## 根公理
+
+<!--
+  這個專案背後最根本的信念是什麼？
+  範例：「使用者的資料屬於使用者，不屬於平台。」
+  範例：「程式是語義結構——程式碼只是其中一種投影。」
+-->
+
+## 衍生原則
+
+<!--
+  每個原則都應該能追溯到根公理或另一個原則。
+  說明它在實務上代表什麼，讓團隊（和你的 AI）能夠應用它。
+-->
+
+### 1. [原則名稱]
+
+<!--
+  推導自：[根公理 / 另一個原則]
+  意義：...
+  如何應用：...
+-->
+
+### 2. [原則名稱]
+
+<!--
+  推導自：...
+  意義：...
+  如何應用：...
+-->

package/templates/zh-TW/vision.md.tmpl

@@ -0,0 +1,75 @@
+# 願景
+
+<!--
+  這份文件描述你的專案要往哪裡走。它會隨著理解的加深而演進。
+  在每個里程碑完成後，或是優先順序改變時更新它。
+-->
+
+## 問題陳述
+
+<!--
+  這個專案要解決什麼問題？誰有這個問題？
+  為什麼現有的方案不夠好？
+-->
+
+## 核心想法
+
+<!--
+  用一兩句話描述你的解決方案。
+  範例：「一棵語義樹，可以投影成程式碼、積木和流程圖
+  ——編輯任何視圖，全部保持同步。」
+-->
+
+## 現狀
+
+<!--
+  專案目前在什麼狀態？什麼能用、什麼不能用？
+  誠實描述——這能幫助你的 AI 給出務實的建議。
+-->
+
+## 架構
+
+<!--
+  關鍵的技術決策，以及為什麼這樣決定。
+  詳細的設計文件連結到 .knowledge/design/。
+-->
+
+## 路線圖
+
+<!--
+  按順序列出里程碑。用勾選框追蹤完成狀態。
+  每個里程碑包含：
+  - 名稱 + 勾選框（[ ] 待完成、[x] 已完成）
+  - 交付什麼
+  - 前置條件（哪些里程碑必須先完成）
+  - 成功標準（具體、可驗證）
+
+  完成里程碑時更新勾選框。/knowy judge 會驗證打勾的項目
+  是否與專案實際狀態一致。
+-->
+
+### 階段 1：[名稱]
+
+- [ ] 完成
+
+<!--
+  交付：...
+  前置條件：無
+-->
+
+**成功標準：**
+- [ ] [具體標準 1]
+- [ ] [具體標準 2]
+
+### 階段 2：[名稱]
+
+- [ ] 完成
+
+<!--
+  交付：...
+  前置條件：階段 1
+-->
+
+**成功標準：**
+- [ ] [具體標準 1]
+- [ ] [具體標準 2]