knowy-cli 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowy-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Give your AI a structured project brain",
   "type": "module",
   "bin": {

package/src/constants.js

@@ -16,7 +16,7 @@ export const CORE_FILES = ['principles.md', 'vision.md', 'experience.md'];
 export const SUBDIRS = ['research', 'design', 'history', TEMPLATES_DIR];
 
 export const SKILLS_SOURCE = join(PACKAGE_ROOT, 'skills');
-export const SKILLS_TARGET = '.claude/skills/knowy';
+export const SKILLS_TARGET = '.claude/skills';
 export const SKILL_NAMES = ['knowy-init', 'knowy-update', 'knowy-judge', 'knowy-next'];
 
 export const MARKER_START = '<!-- Knowy: Project Knowledge -->';

package/src/i18n.js

@@ -73,7 +73,7 @@ const messages = {
     '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.skills': (n) => `  ✓ Installed ${n} skills to .claude/skills/`,
     '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:',

package/src/scaffold.js

@@ -2,9 +2,16 @@ 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
+  PACKAGE_ROOT, VERSION, TEMPLATES_DIR
 } from './constants.js';
 
+// Subdirectories that get a README (excludes .templates)
+const SUBDIR_READMES = {
+  research: 'research-README.md',
+  design: 'design-README.md',
+  history: 'history-README.md',
+};
+
 async function exists(p) {
   try { await access(p); return true; } catch { return false; }
 }
@@ -35,6 +42,21 @@ export async function scaffoldKnowledge(projectRoot, language = 'en') {
     }
   }
 
+  // Copy subdirectory READMEs (never overwrite)
+  for (const [sub, tmplName] of Object.entries(SUBDIR_READMES)) {
+    const dest = join(knowledgeDir, sub, 'README.md');
+    if (await exists(dest)) {
+      report.skipped.push(`${sub}/README.md`);
+    } else {
+      let src = join(PACKAGE_ROOT, 'templates', language, tmplName);
+      if (!await exists(src)) {
+        src = join(PACKAGE_ROOT, 'templates', 'en', tmplName);
+      }
+      await copyFile(src, dest);
+      report.created.push(`${sub}/README.md`);
+    }
+  }
+
   // Create .knowy.json
   const configPath = join(projectRoot, KNOWY_CONFIG);
   if (await exists(configPath)) {

package/templates/en/design-README.md

@@ -0,0 +1,47 @@
+# Design
+
+This directory holds architecture designs, technical decision records (ADRs), system designs, and interface specifications.
+
+## When to add a file here
+
+- You're making an architectural decision that affects multiple parts of the system
+- You're designing a new component, API, or data model
+- You're choosing between approaches and want to document the reasoning
+- You're proposing a significant change to existing architecture
+
+## Suggested format
+
+```markdown
+# [Design Title]
+
+**Date**: YYYY-MM-DD
+**Status**: draft | accepted | superseded
+
+## Context
+
+What situation or need prompted this design?
+
+## Decision
+
+What approach did we choose?
+
+## Rationale
+
+Why this approach over alternatives?
+
+## Consequences
+
+What are the trade-offs? What becomes easier or harder?
+
+## Alternatives Considered
+
+- ...
+```
+
+## File naming
+
+Use descriptive topic names: `auth-system.md`, `database-migration-strategy.md`
+
+## Relationship to core files
+
+Key architectural decisions should be reflected in **vision.md** (Architecture section). The design file has the full reasoning; vision.md has the summary. When a design is superseded, update vision.md accordingly.

package/templates/en/history-README.md

@@ -0,0 +1,38 @@
+# History
+
+This directory holds event records — what happened, when, and why it mattered. These are the raw material that gets distilled into experience.md.
+
+## When to add a file here
+
+- You just completed a significant milestone or feature
+- Something unexpected happened during development
+- You made a decision you might need to revisit later
+- A debugging session revealed something important about the system
+
+## Suggested format
+
+```markdown
+# [Event Title]
+
+**Date**: YYYY-MM-DD
+
+## What Happened
+
+Describe the event — what was built, what broke, what changed.
+
+## Impact
+
+How did this affect the project? What changed as a result?
+
+## Follow-up Actions
+
+- [ ] ...
+```
+
+## File naming
+
+Use numbered prefixes to maintain chronological order: `001-initial-setup.md`, `002-auth-migration.md`, `015-performance-crisis.md`
+
+## Relationship to core files
+
+History entries are the raw events. The lessons they teach should be distilled into **experience.md** using the four-part format (Theory said → Actually happened → Resolved by → Lesson). The history file stays here as the detailed record; experience.md has the actionable pattern.

package/templates/en/research-README.md

@@ -0,0 +1,43 @@
+# Research
+
+This directory holds exploratory notes, literature surveys, technical research, and prototype experiments.
+
+## When to add a file here
+
+- You're investigating a technology, library, or approach
+- You're reading papers or documentation and want to capture findings
+- You're running experiments or prototypes to test an idea
+- You have open questions that need exploration before making a decision
+
+## Suggested format
+
+```markdown
+# [Research Topic]
+
+**Date**: YYYY-MM-DD
+**Status**: exploring | concluded
+
+## Question
+
+What are we trying to find out?
+
+## Findings
+
+- ...
+
+## Conclusion
+
+What did we learn? What decision does this inform?
+
+## Next Steps
+
+- [ ] ...
+```
+
+## File naming
+
+Use descriptive topic names: `caching-strategies.md`, `auth-library-comparison.md`
+
+## Relationship to core files
+
+When research reaches a conclusion that reveals a fundamental truth about your project, consider distilling it into **principles.md**. The research file stays here as the detailed record; the principle is the distilled essence.

package/templates/zh-TW/design-README.md

@@ -0,0 +1,47 @@
+# 設計
+
+這個目錄放架構設計、技術決策記錄（ADR）、系統設計和介面規格。
+
+## 什麼時候在這裡新增檔案
+
+- 你在做一個影響系統多個部分的架構決策
+- 你在設計新的元件、API 或資料模型
+- 你在幾個方案之間抉擇，想記錄推理過程
+- 你在提議對既有架構的重大變更
+
+## 建議格式
+
+```markdown
+# [設計標題]
+
+**日期**：YYYY-MM-DD
+**狀態**：草稿 | 已採納 | 已取代
+
+## 脈絡
+
+什麼情況或需求促成了這個設計？
+
+## 決策
+
+我們選擇了什麼方案？
+
+## 理由
+
+為什麼選這個方案而不是其他的？
+
+## 後果
+
+有什麼取捨？什麼變容易了、什麼變難了？
+
+## 考慮過的替代方案
+
+- ...
+```
+
+## 檔案命名
+
+使用描述性的主題名稱：`auth-system.md`、`資料庫遷移策略.md`
+
+## 與核心文件的關係
+
+關鍵的架構決策應該反映到 **vision.md**（架構區塊）。設計檔案有完整的推理過程；vision.md 有摘要。當設計被取代時，同步更新 vision.md。

package/templates/zh-TW/history-README.md

@@ -0,0 +1,38 @@
+# 歷史
+
+這個目錄放事件記錄——發生了什麼、什麼時候、為什麼重要。這些是蒸餾成 experience.md 的原始素材。
+
+## 什麼時候在這裡新增檔案
+
+- 你剛完成一個重要的里程碑或功能
+- 開發過程中發生了意料之外的事
+- 你做了一個之後可能需要回顧的決定
+- 一次除錯過程揭示了系統的重要特性
+
+## 建議格式
+
+```markdown
+# [事件標題]
+
+**日期**：YYYY-MM-DD
+
+## 發生了什麼
+
+描述事件——建了什麼、壞了什麼、改了什麼。
+
+## 影響
+
+這對專案有什麼影響？因此改變了什麼？
+
+## 後續行動
+
+- [ ] ...
+```
+
+## 檔案命名
+
+使用編號前綴保持時間順序：`001-初始建置.md`、`002-auth-migration.md`、`015-效能危機.md`
+
+## 與核心文件的關係
+
+歷史記錄是原始事件。從中學到的教訓應該蒸餾進 **experience.md**，使用四段式格式（理論說 → 實際發生 → 解決方式 → 教訓）。歷史檔案留在這裡作為詳細記錄；experience.md 是可操作的模式。

package/templates/zh-TW/research-README.md

@@ -0,0 +1,43 @@
+# 研究
+
+這個目錄放探索性筆記、文獻調查、技術研究和原型實驗記錄。
+
+## 什麼時候在這裡新增檔案
+
+- 你正在調查某個技術、函式庫或方法
+- 你在閱讀論文或文件，想記錄發現
+- 你在跑實驗或原型來測試想法
+- 你有開放性的問題需要在做決定前先探索
+
+## 建議格式
+
+```markdown
+# [研究主題]
+
+**日期**：YYYY-MM-DD
+**狀態**：探索中 | 已結論
+
+## 問題
+
+我們想弄清楚什麼？
+
+## 發現
+
+- ...
+
+## 結論
+
+我們學到了什麼？這個結論影響什麼決策？
+
+## 下一步
+
+- [ ] ...
+```
+
+## 檔案命名
+
+使用描述性的主題名稱：`快取策略.md`、`auth-library-comparison.md`
+
+## 與核心文件的關係
+
+當研究得出的結論揭示了專案的根本真理時，考慮蒸餾進 **principles.md**。研究檔案留在這裡作為詳細記錄；原則是蒸餾後的精華。