@yottameta/yotta-logs 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## v0.3.1 (2026-09-13)
+
+- 修复本机专属路径硬编码：移除本机自定义数据目录候选；opencode 只认 `XDG_DATA_HOME` / `OPENCODE_DATA` / 官方默认路径，Codex notes 只认 `$CODEX_HOME/memories` 或 `~/.codex/memories`。
+- 配置路径改为平台无关：`$YOTTA_LOGS_CONFIG` > Windows `%APPDATA%` > Unix `$XDG_CONFIG_HOME` / `~/.config`。
+- 新增便携覆盖回归：`YOTTA_MEMORY_HOME`、`CODEX_HOME`、`YOTTA_LOGS_CONFIG`；并加本机自定义目录反向断言。
+
+## v0.3.0 (2026-09-08)
+
+**评测驱动完善**：新增 FAQ，安装器错误处理与测试补齐。
+
+- 新增 references/faq.md，覆盖格式、范围、脱敏、只读边界与安装排障。
+- 安装器支持 --help、参数校验、统一退出码与人话错误提示。
+
 # 更新日志
 
 ## v0.2.2 (2026-08-29)
@@ -8,7 +21,7 @@
 
 ## v0.2.1 (2026-08-27)
 
-文档中英双版（老张拍板「英文门面 + 中文全档」）：
+文档中英双版：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，继续服务中文用户，顶部加语言切换链接。
@@ -18,7 +31,7 @@
 
 ## v0.2.0 (2026-08-27)
 
-多格式通用化：不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式（老张拍板三点：方向认可 / 版本 v0.2.0 / 默认检索范围动作工时定）：
+多格式通用化：不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式：
 
 - **五大格式族 reader**：JSONL（支持嵌套子目录与 Codex rollout payload 形态）/ 单文件 JSON（数组、dict-of-lists）/ SQLite（opencode schema 实测 + 通用列映射兜底，只读 mode=ro）/ Markdown（YAML frontmatter 结构化记忆 + 自由笔记）/ 二进制（只降级读标题不崩）。
 - **统一 Record 模型**：{source, format, kind, session, time, role, text, path, meta}；字段别名归一（time / role / text / session / title），秒 / 毫秒自动推断，JSON 字符串解包。
@@ -30,9 +43,9 @@
 
 ## v0.1.0 (2026-08-27)
 
-YottaMeta 自有实现首版（历史会话日志检索方向参考开源社区 session-logs 类技能思路，已完全重写，无上游代码）：
+YottaMeta 自有实现首版（历史会话日志检索方向参考开源社区 session-logs 类技能思路，已完全重写）：
 
 - 元史（yotta-logs）—— 零依赖跨智能体会话日志检索引擎（Python 3.8+ 标准库）。
 - 能力：locate / scan / search / session / stats / tools / version；关键词 / 正则 / 日期 / 会话 ID / 别名 / 角色过滤；默认脱敏（--no-redact 关闭）；--json 结构化输出；只读安全；容错 JSONL 解析（含 sessions.json 索引别名）。
 - 测试：scripts/test_yotta_logs.py 75 项全绿。
-- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明；README 一行上游致谢。
+- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 YottaMeta
-
-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
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+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/README.md

@@ -162,12 +162,19 @@ bash install.sh --list           # list agents -> default directories
 
 ## Changelog
 
+- v0.3.1 (2026-09-13): Removed machine-specific hardcoded paths; discovery and config now follow environment variables and platform defaults, with regression coverage.
+- v0.3.0 (2026-09-08): Evaluation-driven refinement — added FAQ, hardened installer error handling and exit codes, and added installer tests.
+
 - v0.2.2 (2026-08-29): Install docs alignment — unified four install methods (npx -y @yottameta/yotta-logs --agent/--dir, git clone, GitHub Download ZIP, install.sh --agent/--dir/--list), removed the legacy GitHub-clone installer and global-install (-g) recommendations; bilingual README install section synced to 发布规范 §3.3.1. No functional change.
 
 - v0.2.1 (2026-08-27): Bilingual documentation — English README as the GitHub / npm / ClawHub homepage, full Chinese doc moved to README.zh-CN.md, English npm description.
 - v0.2.0 (2026-08-27): Multi-format generalization — JSONL / single-file JSON / SQLite (opencode etc.) / Markdown (memory + free notes) / binary; unified Record + field-alias normalization + config fallback; discover; new --source / --kind / --format filters and default search scope (session + structured memory on, free notes / binary logs off). See CHANGELOG.md.
 - v0.1.0 (2026-08-27): Initial release — zero-dependency JSONL session log search engine (locate / scan / search / session / stats / tools / version + default redaction + sessions.json alias + read-only).
 
+## References
+
+- references/faq.md
+
 ## License
 
 MIT © YottaMeta — see [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -162,11 +162,18 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 
 ## 更新日志
 
+- v0.3.1（2026-09-13）：移除本机专属硬编码路径；discovery 与配置统一走环境变量和平台默认位置，并补回归覆盖。
+- v0.3.0（2026-09-08）：评测驱动完善——新增常见问题，安装器错误处理与退出码加固，并补齐安装器测试。
+
 - v0.2.2（2026-08-29）：安装方式统一为四方式（对齐发布规范 §3.3.1）——方式一 npx -y @yottameta/yotta-logs --agent / --dir（推荐，走 npm 源）；方式二 git clone；方式三 GitHub Download ZIP；方式四 bash install.sh --agent/--dir/--list。移除旧式 GitHub 克隆安装器与全局安装（-g）推荐；中英 README 安装节同步。无功能变更。
 
 - v0.2.0（2026-08-27）：多格式通用化——JSONL / 单文件 JSON / SQLite（opencode 等）/ Markdown（记忆 + 自由笔记）/ 二进制五大格式族，统一 Record + 字段别名归一 + 配置兜底，discover 全源登记，新增 --source / --kind / --format 过滤与默认检索范围（会话 + 结构化记忆开、自由笔记 / 二进制日志关）。详见 CHANGELOG.md。
 - v0.1.0（2026-08-27）：首版——零依赖 JSONL 会话日志检索引擎（locate / scan / search / session / stats / tools / version + 默认脱敏 + sessions.json 别名 + 只读）。
 
+## 参考文档
+
+- references/faq.md
+
 ## 许可证
 
 MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-logs
-version: 0.2.2
+version: 0.3.1
 description: 元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、不删除；只查本地不联网上传。
 license: MIT
 ---
@@ -84,6 +84,7 @@ python3 scripts/yotta_logs.py tools --dir /path/to/logs --format sqlite
 - references/format.md — 统一 Record 模型与各格式族读取规则
 - references/cli.md — CLI 子命令 / 参数 / 退出码 / JSON schema / 配置详解
 - references/security.md — 安全边界 / 脱敏规则 / 与元忆的差异化
+- references/faq.md — 常见问题与安装排障
 
 ## 责任声明
 

package/bin/install.js

@@ -1,163 +1,245 @@
-#!/usr/bin/env node
-/**
- * yotta-logs 跨平台安装器（YottaSkills）
- * 用法:
- *   npx -y @yottameta/yotta-logs --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-logs --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-logs -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-logs                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-logs --list          # 列出智能体 -> 默认目录
- */
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const SKILL_NAME = 'yotta-logs';
-const PKG_ROOT = path.join(__dirname, '..');
-
-// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
-// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
-// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
-const AGENT_DIRS = {
-  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
-  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
-  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
-  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
-  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
-  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
-  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
-  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
-  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
-  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
-  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
-  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
-  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
-  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
-  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
-  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
-};
-
-// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
-function codexUserDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'skills');
-}
-
-// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
-function opencodeUserDir() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(base, 'opencode', 'skills');
-}
-
-function resolveUserDir(rel) {
-  if (rel === '.codex/skills') return codexUserDir();
-  if (rel === '.config/opencode/skills') return opencodeUserDir();
-  return path.join(os.homedir(), rel);
-}
-
-function installTo(dest) {
-  const target = path.join(dest, SKILL_NAME);
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
-  console.log('installed -> ' + target);
-}
-
-function copyDir(src, dst, skip) {
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (skip.has(entry.name)) continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(d, { recursive: true });
-      copyDir(s, d, skip);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(s, d);
-    }
-  }
-}
-
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const isGlobal = args.includes('-g') || args.includes('--global');
-  const list = args.includes('--list') || args.includes('-l');
-  let explicitDir = null;
-  const di = args.indexOf('--dir');
-  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
-  let agent = null;
-  const ai = args.indexOf('--agent');
-  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
-
-  if (list) {
-    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
-    for (const [key, v] of Object.entries(AGENT_DIRS)) {
-      const resolved = v.dirs.map(displayDir);
-      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
-    }
-    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
-    return;
-  }
-
-  if (explicitDir) { installTo(explicitDir); return; }
-
-  if (agent) {
-    const info = AGENT_DIRS[agent];
-    if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
-    }
-    installTo(resolveUserDir(info.dirs[0]));
-    console.log('完成。');
-    return;
-  }
-
-  if (isGlobal) {
-    const seen = new Set();
-    for (const v of Object.values(AGENT_DIRS)) {
-      for (const d of v.dirs) {
-        if (seen.has(d)) continue;
-        seen.add(d);
-        installTo(resolveUserDir(d));
-      }
-    }
-    console.log('完成。');
-    return;
-  }
-
-  const PROJECT_DIRS = [
-    '.claude/skills',
-    '.cursor/skills',
-    '.codex/skills',
-    '.config/goose/skills',
-    '.config/agents/skills',
-    '.opencode/skills',
-    '.codeium/windsurf/skills',
-    '.workbuddy/skills',
-    '.kiro/skills',
-    '.traecli/skills',
-    '.gemini/skills',
-    '.trae-cn/skills',
-    '.qwen/skills',
-    '.comate/skills',
-    '.codebuddy/skills',
-    '.kimi/skills',
-    '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
-  }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
-  }
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * @yottameta/yotta-logs cross-platform installer.
+ *
+ * Usage:
+ *   npx -y @yottameta/yotta-logs --agent <name>
+ *   npx -y @yottameta/yotta-logs --dir <path>
+ *   npx -y @yottameta/yotta-logs -g
+ *   npx -y @yottameta/yotta-logs
+ *   npx -y @yottameta/yotta-logs --list
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-logs';
+const PKG_ROOT = path.join(__dirname, '..');
+const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '.github', 'test']);
+
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] },
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] },
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE',         dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate',           dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+function usage() {
+  console.log('yotta-logs installer');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx -y @yottameta/yotta-logs --agent <name>  Install to an agent default directory');
+  console.log('  npx -y @yottameta/yotta-logs --dir <path>     Install to a custom directory');
+  console.log('  npx -y @yottameta/yotta-logs -g               Install to all known agent directories');
+  console.log('  npx -y @yottameta/yotta-logs                  Auto-detect project-level directories');
+  console.log('  npx -y @yottameta/yotta-logs --list           List supported agent directories');
+  console.log('');
+  console.log('Options:');
+  console.log('  --agent <name>  Agent key, see --list');
+  console.log('  --dir <path>    Custom skills directory');
+  console.log('  -g, --global    Install to all known user-level directories');
+  console.log('  --list, -l      List supported agents');
+  console.log('  -h, --help      Show this help');
+}
+
+function parseArgs(argv) {
+  const opts = { help: false, list: false, global: false, dir: null, agent: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--list' || arg === '-l') opts.list = true;
+    else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dir') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--dir requires a non-empty path');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent requires a non-empty name');
+      opts.agent = value.toLowerCase();
+    } else {
+      throw new UsageError('Unknown argument: ' + arg);
+    }
+  }
+  if (!opts.help) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('Use only one of --dir, --agent, or -g');
+  }
+  return opts;
+}
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function printList() {
+  console.log('Agent -> default skill directory:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    console.log('  ' + key.padEnd(12) + value.label.padEnd(20) + value.dirs.map(displayDir).join(', '));
+  }
+  console.log('');
+  console.log('Use --dir <path> for agents not listed. CODEX_HOME and XDG_CONFIG_HOME are respected.');
+}
+
+function assertSafeTarget(target) {
+  const rel = path.relative(PKG_ROOT, target);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    throw new UsageError('Target directory must be outside the skill source directory');
+  }
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    try {
+      if (entry.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        copyDir(from, to, skip);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(from, to);
+      }
+    } catch (err) {
+      throw new InstallError('Failed to copy ' + from + ' -> ' + to + ': ' + err.message);
+    }
+  }
+}
+
+function installTo(dest) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('Destination directory is required');
+  const target = path.resolve(dest, SKILL_NAME);
+  assertSafeTarget(target);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(PKG_ROOT, target, COPY_SKIP);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('Installed directory is missing SKILL.md');
+    }
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof InstallError) throw err;
+    throw new InstallError('Cannot install to ' + target + ': ' + err.message);
+  }
+  console.log('installed -> ' + target);
+  return target;
+}
+
+function projectDirs() {
+  return [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ].filter((dir) => fs.existsSync(dir));
+}
+
+function run() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { usage(); return; }
+  if (opts.list) { printList(); return; }
+
+  if (opts.dir) { installTo(opts.dir); return; }
+
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
+    if (!info) {
+      throw new UsageError('Unknown agent: ' + opts.agent + '. Available: ' + Object.keys(AGENT_DIRS).join(', ') + '. Use --dir for a custom directory.');
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    return;
+  }
+
+  if (opts.global) {
+    const seen = new Set();
+    let count = 0;
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const dir of value.dirs) {
+        if (seen.has(dir)) continue;
+        seen.add(dir);
+        installTo(resolveUserDir(dir));
+        count++;
+      }
+    }
+    console.log('Installed to ' + count + ' directories.');
+    return;
+  }
+
+  const dirs = projectDirs();
+  if (!dirs.length) {
+    throw new TargetError('No project-level agent directory detected. Use --agent <name> or --dir <path>.');
+  }
+  for (const dir of dirs) installTo(dir);
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('Usage error: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('Target error: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('Install failed: ' + err.message);
+      console.error('Fix: check directory permissions and free space, then retry. Use --dir to choose another directory.');
+      process.exitCode = 1;
+    } else {
+      console.error('Unexpected error: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
+  }
+}
+
+main();