@punk6529/playbook 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## 0.3.0
+
+**BREAKING**: 移除项目级知识存储，简化为全局单一作用域
+
+- 移除 `promote` 命令及 `playbook-promote` skill
+- 移除 `--scope` 参数（query/show/hit/reindex 全部只操作 `~/.playbook/repo/`）
+- `playbook init` 不再创建 `docs/playbook/` 目录，仅安装 AI skill 模板
+- `playbook update` 仅刷新 skill 模板
+- `playbook reindex` 直接重建全局 INDEX，无需 `--scope global`
+- `playbook root` 直接输出全局路径，无需 `--scope`
+- `playbook-case` skill 直接写入全局知识库，不再询问 scope
+- Skills 从 4 个减为 3 个（advisor、query、case）
+- query 输出不再包含 `[scope]` 前缀和 scope 字段
+
+## 0.2.8
+
+- 新增 `playbook root [--scope project|global]` 命令，输出 playbook 目录绝对路径
+- playbook-case skill 写入文件前通过 `playbook root` 获取路径，避免相对路径问题
+- playbook-case skill 新增 Write Procedure 段，明确写入步骤
+
+## 0.2.7
+
+- `playbook query --tags-only` 合并 tags.yml 注册表，即使 INDEX 为空也能显示完整 tag 列表
+- playbook-case skill 改用 `playbook query --tags-only` 获取 tag 建议
+
+## 0.2.6
+
+- 内容文件新增 YAML front matter（title, tags, created），作为元数据主真相源
+- 新增 `playbook reindex [--scope project|global]` 命令，从文件 front matter 重建 INDEX.json
+- reindex 保留已有 hits 统计，跳过无效 front matter 的文件
+- playbook-case skill 模板更新：生成的 case 文件包含 front matter
+
+## 0.2.5
+
+- 新增 `playbook show <entry-id>` 命令，输出案例文件完整内容
+- playbook-advisor 和 playbook-query skill 的 L2 改为调用 `playbook show`，不再要求 AI 猜测文件路径
+
+## 0.2.4
+
+- 移除 init 时创建的 example 文件，INDEX.json 初始为空对象
+
+## 0.2.3
+
+- 新增 `playbook hit <entry-id>` 命令，记录案例阅读次数
+- `playbook query` 输出增加 `hits:N` 字段
+- playbook-advisor skill 阅读案例后自动调用 hit，并优先推荐高 hits 案例
+
+## 0.2.2
+
+- 新增 `playbook promote` 命令，将项目案例移动到全局知识库
+- 支持单个、多个、`--all` 批量提升，`--force` 覆盖冲突
+- 新增 playbook-promote skill 模板
+
+## 0.2.1
+
+- README，补充命令使用场景说明
+- 区分用户命令与内部命令
+
+## 0.2.0
+
+- 新增 `playbook query` 命令（按 tag 检索、`--json`、`--tags-only`）
+- 新增 playbook-advisor skill（主动顾问模式）
+- 新增 playbook-query、playbook-case skill 模板
+
+## 0.1.0
+
+- 初始版本
+- `playbook init`、`playbook global init`、`playbook update`

package/README.md

@@ -1,38 +1,37 @@
 # @punk6529/playbook
 
-把团队踩过的坑，沉淀成 AI 可读、可查、可复用的工程记忆。
+把踩过的坑，沉淀成 AI 可读、可查、可复用的工程记忆。
 
-`@punk6529/playbook` 是一个结构化工程知识库 CLI，用于在项目中快速建立并维护 Playbook 资产（cases / patterns / checklists + INDEX）。
+`@punk6529/playbook` 是一个结构化工程知识库 CLI，用于建立并维护全局 Playbook 资产（cases / patterns / checklists + INDEX）。
 
-它不只是“记笔记工具”，而是把“个人经验”变成“团队可复用资产”的最小基础设施：
+它不只是"记笔记工具"，而是把"个人经验"变成"可复用资产"的最小基础设施：
 
 - 解决问题后可立即沉淀为 case，避免同类问题反复排查
 - AI 可以按 tag 精准检索历史经验，而不是每次从零猜测
-- 支持项目级和全局级知识库，单项目沉淀可逐步升级为跨项目最佳实践
+- 全局知识库跨项目共享，所有经验统一管理
 - 通过结构化索引 + 按需读取，控制上下文体积，降低 token 浪费
 
 ## 这个工具适合谁
 
 - 希望减少重复踩坑的个人开发者
-- 需要把故障处置经验标准化的技术团队
-- 在 Codex / Claude 工作流中，希望让 AI“带着历史经验工作”的团队
+- 在 Codex / Claude 工作流中，希望让 AI"带着历史经验工作"的用户
 
 ## 你会获得什么
 
-- 一套开箱即用的知识库目录结构（项目级 + 全局级）
+- 一套全局知识库目录结构（`~/.playbook/repo/`）
 - 三个可直接使用的 AI skills：
   - `/playbook-advisor`：会话内主动顾问，自动按需查询知识库
   - `/playbook-query`：手动按标签检索经验
   - `/playbook-case`：引导式记录新 case，并更新索引
-- 一套稳定的 CLI 工作流（init / global init / update / query / promote / show / hit / reindex），便于持续演进而不破坏现有内容
+- 一套稳定的 CLI 工作流（global init / init / update / query / show / hit / reindex），便于持续演进而不破坏现有内容
 
 ## 典型工作流
 
-1. `playbook init` 初始化项目知识库与 AI skills (新项目一次即可) 
-2. `playbook global init` 初始化全局知识库（一次即可）  
-3. 新会话开始先调用 `/playbook-advisor`，AI 会列出现有 tags；后续遇到问题时，会按相关 tags 查询案例 summary，并选取最相关案例查看详情  
-4. 问题解决后，用 `/playbook-case` 沉淀经验并更新索引  
-5. 在多个项目间通过全局仓库复用高价值模式
+1. `playbook global init` 初始化全局知识库（一次即可）
+2. `playbook init` 在项目中安装 AI skill 模板（每个项目一次）
+3. 新会话开始先调用 `/playbook-advisor`，AI 会列出现有 tags；后续遇到问题时，会按相关 tags 查询案例 summary，并选取最相关案例查看详情，获取问题解决方案
+4. 如果遇到新问题，解决后，手动调用 `/playbook-case` 沉淀经验并更新索引
+5. 所有经验统一存储在全局知识库，自动跨项目复用
 
 ## 安装
 
@@ -50,28 +49,28 @@ npx @punk6529/playbook --help
 
 日常使用的命令：
 
-### `playbook init`
+### `playbook global init`
 
-在项目中初始化知识库。新项目首次使用时运行一次。
+初始化全局知识库。只需运行一次。
 
 ```bash
-playbook init                              # 当前目录，所有 AI 工具
-playbook init ./my-project                 # 指定目录
-playbook init --tools claude               # 仅安装 Claude skill
-playbook init --tools none                 # 不安装任何 AI skill
+playbook global init
 ```
 
-创建 `docs/playbook/{cases,patterns,checklists}`、`INDEX.json`，以及 AI skill 模板。
+创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。
 
-### `playbook global init`
+### `playbook init`
 
-初始化全局知识库（跨项目共享的经验）。只需运行一次。
+在项目中安装 AI skill 模板。每个新项目首次使用时运行一次。
 
 ```bash
-playbook global init
+playbook init                              # 当前目录，所有 AI 工具
+playbook init ./my-project                 # 指定目录
+playbook init --tools claude               # 仅安装 Claude skill
+playbook init --tools none                 # 不安装任何 AI skill
 ```
 
-创建 `~/.playbook/repo/{cases,patterns,checklists}`、`INDEX.json` 和 `tags.yml`。
+安装 AI skill 模板到 `.claude/skills/` 和 `.codex/skills/`。
 
 ### `playbook update`
 
@@ -79,10 +78,9 @@ playbook global init
 
 ```bash
 playbook update                            # 更新当前项目
-playbook update --force                    # 强制覆盖（含 INDEX.json）
 ```
 
-仅刷新 skill 模板，不修改用户业务内容（case/pattern/checklist 文件）。`INDEX.json` 默认受保护，需 `--force` 才会覆盖。
+仅刷新 skill 模板，不修改知识库内容。
 
 ## 在 AI 中使用
 
@@ -118,8 +116,8 @@ AI：根据之前的经验，这个问题是因为 Docker 默认绑定 0.0.0.0
 AI：请提供要搜索的 tag
 你：docker
 AI：找到以下条目：
-    [project] case-001-docker-bind  Docker bind address issue  docker,env
-    (1 match: 1 project)
+    case-001-docker-bind  Docker bind address issue  docker,env  hits:3
+    (1 match)
 ```
 
 ### 3. `/playbook-case` —— 记录新 case
@@ -131,35 +129,21 @@ AI：找到以下条目：
 AI：请描述遇到的问题...
 你：Next.js 部署到 Vercel 后 API 路由 404
 AI：（引导你填写 问题/原因/解决/教训 四个部分）
-AI：（生成 case 文件，更新 INDEX.json）
+AI：（生成 case 文件到 ~/.playbook/repo/，更新 INDEX.json）
 ```
 
-### `playbook promote`
-
-将项目级案例提升到全局知识库，让经验跨项目复用。
-
-```bash
-playbook promote case-001-docker-bind      # 提升单个条目
-playbook promote case-001 case-002         # 提升多个条目
-playbook promote --all                     # 提升所有项目条目
-playbook promote case-001 --force          # 强制覆盖已存在的全局条目
-```
-
-将项目 `docs/playbook/` 下的条目移动到全局 `~/.playbook/repo/`，同时更新两端的 INDEX.json。
-
 ## 内部命令
 
 以下命令主要由 AI skill 内部调用，用户一般不需要直接使用：
 
 ### `playbook query`
 
-按 tag 搜索 INDEX.json 条目（OR 逻辑），同时搜索项目和全局范围。
+按 tag 搜索全局 INDEX.json 条目（OR 逻辑）。
 
 ```bash
 playbook query docker env          # 匹配 "docker" 或 "env" 的条目
 playbook query                     # 所有条目
 playbook query --tags-only         # 仅输出 tag 概览：docker(3) env(5) ci(2)
-playbook query --scope project     # 仅项目范围
 playbook query --limit 0           # 不限数量
 playbook query docker --json       # JSON 格式输出
 ```
@@ -174,8 +158,6 @@ playbook query docker --json       # JSON 格式输出
 playbook show case-001-docker-bind         # 输出案例文件内容
 ```
 
-先查项目 INDEX，再查全局 INDEX，找到后输出对应文件内容到 stdout。
-
 ### `playbook hit`
 
 记录一次案例阅读命中，用于追踪案例的实际使用频率。
@@ -188,14 +170,13 @@ AI advisor 每次阅读案例详情后自动调用。命中次数在 `playbook q
 
 ### `playbook reindex`
 
-从文件 front matter 重建 INDEX.json。当 INDEX 被清空、损坏或需要同步时使用。
+从文件 front matter 重建全局 INDEX.json。当 INDEX 被清空、损坏或需要同步时使用。
 
 ```bash
-playbook reindex                   # 重建项目 INDEX
-playbook reindex --scope global    # 重建全局 INDEX
+playbook reindex                   # 重建全局 INDEX
 ```
 
-扫描 `cases/`、`patterns/`、`checklists/` 下的 `.md` 文件，解析 YAML front matter（title, tags, created），重建 INDEX.json。保留已有的 hits 统计。
+扫描 `~/.playbook/repo/` 下 `cases/`、`patterns/`、`checklists/` 的 `.md` 文件，解析 YAML front matter（title, tags, created），重建 INDEX.json。保留已有的 hits 统计。
 
 ## 错误处理
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punk6529/playbook",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "CLI for initializing and updating Playbook & Case workflows.",
   "main": "src/index.js",
   "bin": {
@@ -21,6 +21,7 @@
   "files": [
     "bin",
     "src",
-    "templates"
+    "templates",
+    "CHANGELOG.md"
   ]
 }

package/src/cli.js

@@ -2,12 +2,11 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { CliError } = require("./errors");
-const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parsePromoteArgs, parseHitArgs, parseShowArgs, parseReindexArgs } = require("./options");
+const { parseProjectCommandArgs, parseGlobalInitArgs, parseQueryArgs, parseHitArgs, parseShowArgs, parseReindexArgs } = require("./options");
 const { initProject } = require("./commands/init-project");
 const { initGlobal } = require("./commands/global-init");
 const { updateProject } = require("./commands/update-project");
 const { queryIndex, aggregateTags, formatPlainText, formatJson, formatTagsOnly } = require("./commands/query");
-const { promoteEntries } = require("./commands/promote");
 const { hitEntry } = require("./commands/hit");
 const { showEntry } = require("./commands/show");
 const { reindexPlaybook } = require("./commands/reindex");
@@ -19,19 +18,16 @@ function usageText() {
     "  playbook init [path] [--tools all|none|codex,claude] [--force]",
     "  playbook global init [--force]",
     "  playbook update [path] [--tools all|none|codex,claude] [--force]",
-    "  playbook query [tags...] [--limit N] [--scope project|global|both] [--json] [--tags-only]",
-    "  playbook promote <entry-id...> [--force]",
-    "  playbook promote --all [--force]",
+    "  playbook query [tags...] [--limit N] [--json] [--tags-only]",
     "  playbook hit <entry-id>",
     "  playbook show <entry-id>",
-    "  playbook reindex [--scope project|global]",
-    "  playbook root [--scope project|global]",
+    "  playbook reindex",
+    "  playbook root",
     "",
     "Notes:",
-    "  - `init` and `update` are project-scoped commands.",
-    "  - `global init` initializes ~/.playbook/repo and does not support --tools.",
-    "  - `query` searches INDEX.json by tags and returns matching entries.",
-    "  - V1 does not support `playbook global update`.",
+    "  - `global init` initializes ~/.playbook/repo (knowledge storage).",
+    "  - `init` installs AI skill templates into the current project.",
+    "  - `query` searches global INDEX.json by tags and returns matching entries.",
   ].join("\n");
 }
 
@@ -82,12 +78,11 @@ function queryHelpText() {
   return [
     "Usage: playbook query [tags...] [options]",
     "",
-    "Search INDEX.json entries by tags (OR logic).",
+    "Search global INDEX.json entries by tags (OR logic).",
     "Without tags, returns all entries.",
     "",
     "Options:",
     "  --limit N     Max results to return (default: 7, 0 = unlimited)",
-    "  --scope X     Search scope: project, global, or both (default: both)",
     "  --json        Output results as JSON array",
     "  --tags-only   Output only tag names with case counts",
     "  -h, --help    Show this help",
@@ -113,61 +108,11 @@ function runQuery(args, io) {
   return 0;
 }
 
-function promoteHelpText() {
-  return [
-    "Usage: playbook promote <entry-id...> [options]",
-    "       playbook promote --all [options]",
-    "",
-    "Move project entries to global knowledge base.",
-    "",
-    "Options:",
-    "  --all         Promote all project entries",
-    "  --force       Overwrite if entry already exists in global",
-    "  -h, --help    Show this help",
-  ].join("\n");
-}
-
-function runPromote(args, io) {
-  const options = parsePromoteArgs(args);
-  if (options.help) {
-    writeStdout(io, promoteHelpText());
-    return 0;
-  }
-
-  const result = promoteEntries(options);
-
-  if (result.message) {
-    writeStdout(io, result.message);
-    return 0;
-  }
-
-  let hasError = false;
-  for (const r of result.results) {
-    if (r.action === "promoted") {
-      writeStdout(io, `[promoted] ${r.entryId}\t${r.title}`);
-    } else if (r.action === "conflict") {
-      writeStderr(io, `[conflict] ${r.entryId}\t${r.reason}`);
-      hasError = true;
-    } else if (r.action === "error") {
-      writeStderr(io, `[error] ${r.entryId}\t${r.reason}`);
-      hasError = true;
-    }
-  }
-
-  const promoted = result.results.filter((r) => r.action === "promoted").length;
-  if (promoted > 0) {
-    writeStdout(io, `(${promoted} ${promoted === 1 ? "entry" : "entries"} promoted to global)`);
-  }
-
-  return hasError ? 1 : 0;
-}
-
 function hitHelpText() {
   return [
     "Usage: playbook hit <entry-id>",
     "",
-    "Record a read hit on a playbook entry.",
-    "Searches project INDEX first, then global INDEX.",
+    "Record a read hit on a playbook entry in global INDEX.",
     "",
     "Options:",
     "  -h, --help    Show this help",
@@ -182,7 +127,7 @@ function runHit(args, io) {
   }
 
   const result = hitEntry(options);
-  writeStdout(io, `[${result.scope}] ${result.entryId} hits:${result.hits}`);
+  writeStdout(io, `${result.entryId} hits:${result.hits}`);
   return 0;
 }
 
@@ -190,8 +135,7 @@ function showHelpText() {
   return [
     "Usage: playbook show <entry-id>",
     "",
-    "Display the full content of a playbook entry.",
-    "Searches project INDEX first, then global INDEX.",
+    "Display the full content of a playbook entry from global INDEX.",
     "",
     "Options:",
     "  -h, --help    Show this help",
@@ -212,12 +156,11 @@ function runShow(args, io) {
 
 function reindexHelpText() {
   return [
-    "Usage: playbook reindex [options]",
+    "Usage: playbook reindex",
     "",
-    "Rebuild INDEX.json by scanning playbook files and reading front matter.",
+    "Rebuild global INDEX.json by scanning playbook files and reading front matter.",
     "",
     "Options:",
-    "  --scope X     Scope: project or global (default: project)",
     "  -h, --help    Show this help",
   ].join("\n");
 }
@@ -230,36 +173,23 @@ function runReindex(args, io) {
   }
 
   const result = reindexPlaybook(options);
-  writeStdout(io, `Reindexed ${result.scope}: ${result.count} ${result.count === 1 ? "entry" : "entries"} found.`);
+  writeStdout(io, `Reindexed: ${result.count} ${result.count === 1 ? "entry" : "entries"} found.`);
   return 0;
 }
 
 function runRoot(args, io) {
-  let scope = "project";
   for (const arg of args) {
     if (arg === "-h" || arg === "--help") {
-      writeStdout(io, "Usage: playbook root [--scope project|global]\n\nOutput the absolute path of the playbook directory.");
+      writeStdout(io, "Usage: playbook root\n\nOutput the absolute path of the global playbook directory.");
       return 0;
     }
-    if (arg === "--scope" || arg.startsWith("--scope=")) {
-      const value = arg === "--scope" ? args[args.indexOf(arg) + 1] : arg.slice("--scope=".length);
-      if (value === "global" || value === "project") scope = value;
-    }
   }
 
-  if (scope === "global") {
-    const globalRoot = path.join(os.homedir(), ".playbook/repo");
-    if (!fs.existsSync(globalRoot)) {
-      throw new CliError("Global playbook not found. Run 'playbook global init' first.");
-    }
-    writeStdout(io, globalRoot);
-  } else {
-    const projectRoot = path.resolve("docs/playbook");
-    if (!fs.existsSync(projectRoot)) {
-      throw new CliError("Project playbook not found. Run 'playbook init' first.");
-    }
-    writeStdout(io, projectRoot);
+  const globalRoot = path.join(os.homedir(), ".playbook/repo");
+  if (!fs.existsSync(globalRoot)) {
+    throw new CliError("Global playbook not found. Run 'playbook global init' first.");
   }
+  writeStdout(io, globalRoot);
   return 0;
 }
 
@@ -288,7 +218,7 @@ function runGlobal(args, io) {
   printSummary("playbook global init completed", result.globalRoot, result.results, (line) =>
     writeStdout(io, line)
   );
-  writeStdout(io, "Next: run `playbook init` inside a project to scaffold project assets.");
+  writeStdout(io, "Next: run `playbook init` inside a project to install AI skill templates.");
   return 0;
 }
 
@@ -312,10 +242,6 @@ async function runCli(argv, io = process) {
       return runQuery(argv.slice(1), io);
     }
 
-    if (command === "promote") {
-      return runPromote(argv.slice(1), io);
-    }
-
     if (command === "hit") {
       return runHit(argv.slice(1), io);
     }
@@ -336,7 +262,7 @@ async function runCli(argv, io = process) {
       return runGlobal(argv.slice(1), io);
     }
 
-    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, promote, hit, show, reindex, root`);
+    throw new CliError(`Unknown command: ${command}. Supported: init, global, update, query, hit, show, reindex, root`);
   } catch (error) {
     if (error instanceof CliError) {
       writeStderr(io, `Error: ${error.message}`);

package/src/commands/hit.js

@@ -17,33 +17,22 @@ function writeIndex(indexPath, data) {
 }
 
 function hitEntry(options) {
-  const { entryId, targetPath = "." } = options;
+  const { entryId } = options;
 
-  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
   const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
-
-  // Try project first
-  const projectIndex = readIndex(projectIndexPath);
-  if (projectIndex && projectIndex[entryId]) {
-    projectIndex[entryId].hits = (projectIndex[entryId].hits || 0) + 1;
-    writeIndex(projectIndexPath, projectIndex);
-    return { entryId, scope: "project", hits: projectIndex[entryId].hits };
-  }
-
-  // Fall back to global
   const globalIndex = readIndex(globalIndexPath);
-  if (globalIndex && globalIndex[entryId]) {
-    globalIndex[entryId].hits = (globalIndex[entryId].hits || 0) + 1;
-    writeIndex(globalIndexPath, globalIndex);
-    return { entryId, scope: "global", hits: globalIndex[entryId].hits };
+
+  if (!globalIndex) {
+    throw new CliError("No INDEX.json found. Run 'playbook global init' first.");
   }
 
-  // Not found
-  if (!projectIndex && !globalIndex) {
-    throw new CliError("No INDEX.json found. Run 'playbook init' or 'playbook global init' first.");
+  if (!globalIndex[entryId]) {
+    throw new CliError(`Entry '${entryId}' not found in INDEX.`);
   }
 
-  throw new CliError(`Entry '${entryId}' not found in project or global INDEX.`);
+  globalIndex[entryId].hits = (globalIndex[entryId].hits || 0) + 1;
+  writeIndex(globalIndexPath, globalIndex);
+  return { entryId, hits: globalIndex[entryId].hits };
 }
 
 module.exports = {

package/src/commands/query.js

@@ -24,37 +24,16 @@ function filterByTags(index, tags) {
 }
 
 function queryIndex(options) {
-  const { tags = [], limit = DEFAULT_LIMIT, scope = "both", targetPath = "." } = options;
+  const { tags = [], limit = DEFAULT_LIMIT } = options;
 
-  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
   const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
+  const globalIndex = readIndex(globalIndexPath);
 
-  let projectEntries = [];
-  let globalEntries = [];
-  let anyIndexFound = false;
-
-  if (scope === "both" || scope === "project") {
-    const projectIndex = readIndex(projectIndexPath);
-    if (projectIndex) {
-      anyIndexFound = true;
-      projectEntries = filterByTags(projectIndex, tags).map((e) => ({ ...e, scope: "project" }));
-    }
-  }
-
-  if (scope === "both" || scope === "global") {
-    const globalIndex = readIndex(globalIndexPath);
-    if (globalIndex) {
-      anyIndexFound = true;
-      globalEntries = filterByTags(globalIndex, tags).map((e) => ({ ...e, scope: "global" }));
-    }
-  }
-
-  const all = [...projectEntries, ...globalEntries];
-
-  if (!anyIndexFound) {
+  if (!globalIndex) {
     return { entries: [], found: false };
   }
 
+  const all = filterByTags(globalIndex, tags);
   const limited = limit > 0 ? all.slice(0, limit) : all;
 
   return { entries: limited, total: all.length, found: true };
@@ -70,23 +49,17 @@ function formatPlainText(result) {
   }
 
   const lines = result.entries.map(
-    (e) => `[${e.scope}]\t${e.id}\t${e.title}\t${e.tags.join(",")}\thits:${e.hits || 0}`
+    (e) => `${e.id}\t${e.title}\t${e.tags.join(",")}\thits:${e.hits || 0}`
   );
 
   const displayed = result.entries.length;
   const total = result.total;
-  const projectCount = result.entries.filter((e) => e.scope === "project").length;
-  const globalCount = result.entries.filter((e) => e.scope === "global").length;
-
-  const parts = [];
-  if (projectCount > 0) parts.push(`${projectCount} project`);
-  if (globalCount > 0) parts.push(`${globalCount} global`);
 
   let summary = `(${total} match${total === 1 ? "" : "es"}`;
   if (displayed < total) {
     summary += `, showing ${displayed}`;
   }
-  summary += `: ${parts.join(", ")})`;
+  summary += ")";
 
   lines.push(summary);
   return lines.join("\n");
@@ -108,40 +81,23 @@ function readTagsRegistry(tagsYmlPath) {
   }
 }
 
-function aggregateTags(options) {
-  const { scope = "both", targetPath = "." } = options;
-
-  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
+function aggregateTags() {
   const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
   const tagsYmlPath = path.join(os.homedir(), ".playbook/repo/tags.yml");
 
   const tagCounts = {};
   let anyIndexFound = false;
 
-  function countTags(index) {
-    for (const entry of Object.values(index)) {
+  const globalIndex = readIndex(globalIndexPath);
+  if (globalIndex) {
+    anyIndexFound = true;
+    for (const entry of Object.values(globalIndex)) {
       for (const tag of entry.tags) {
         tagCounts[tag] = (tagCounts[tag] || 0) + 1;
       }
     }
   }
 
-  if (scope === "both" || scope === "project") {
-    const projectIndex = readIndex(projectIndexPath);
-    if (projectIndex) {
-      anyIndexFound = true;
-      countTags(projectIndex);
-    }
-  }
-
-  if (scope === "both" || scope === "global") {
-    const globalIndex = readIndex(globalIndexPath);
-    if (globalIndex) {
-      anyIndexFound = true;
-      countTags(globalIndex);
-    }
-  }
-
   // Merge tags.yml registry — ensures registered tags appear even with count 0
   const registryTags = readTagsRegistry(tagsYmlPath);
   if (registryTags) {
@@ -180,7 +136,6 @@ function formatJson(result) {
 
   const output = result.entries.map((e) => ({
     id: e.id,
-    scope: e.scope,
     type: e.type,
     title: e.title,
     tags: e.tags,

package/src/commands/reindex.js

@@ -50,26 +50,12 @@ function scanDir(baseDir) {
   return entries;
 }
 
-function reindexPlaybook(options) {
-  const { scope = "project", targetPath = "." } = options;
-
-  let baseDir;
-  let indexPath;
-
-  if (scope === "global") {
-    baseDir = path.join(os.homedir(), ".playbook/repo");
-    indexPath = path.join(baseDir, "INDEX.json");
-  } else {
-    baseDir = path.resolve(targetPath, "docs/playbook");
-    indexPath = path.join(baseDir, "INDEX.json");
-  }
+function reindexPlaybook() {
+  const baseDir = path.join(os.homedir(), ".playbook/repo");
+  const indexPath = path.join(baseDir, "INDEX.json");
 
   if (!fs.existsSync(baseDir)) {
-    throw new CliError(
-      scope === "global"
-        ? "Global playbook not found. Run 'playbook global init' first."
-        : "Project playbook not found. Run 'playbook init' first."
-    );
+    throw new CliError("Global playbook not found. Run 'playbook global init' first.");
   }
 
   // Read existing index to preserve hits
@@ -89,7 +75,6 @@ function reindexPlaybook(options) {
   fs.writeFileSync(indexPath, JSON.stringify(newEntries, null, 2) + "\n", "utf8");
 
   return {
-    scope,
     count: Object.keys(newEntries).length,
     entries: newEntries,
   };

package/src/commands/show.js

@@ -13,35 +13,23 @@ function readIndex(indexPath) {
 }
 
 function showEntry(options) {
-  const { entryId, targetPath = "." } = options;
+  const { entryId } = options;
 
-  const projectIndexPath = path.resolve(targetPath, "docs/playbook/INDEX.json");
   const globalIndexPath = path.join(os.homedir(), ".playbook/repo/INDEX.json");
-
-  // Try project first
-  const projectIndex = readIndex(projectIndexPath);
-  if (projectIndex && projectIndex[entryId]) {
-    const entryPath = projectIndex[entryId].path;
-    const fullPath = path.resolve(targetPath, "docs/playbook", entryPath);
-    const content = readFile(fullPath, entryId);
-    return { entryId, scope: "project", content };
-  }
-
-  // Fall back to global
   const globalIndex = readIndex(globalIndexPath);
-  if (globalIndex && globalIndex[entryId]) {
-    const entryPath = globalIndex[entryId].path;
-    const fullPath = path.join(os.homedir(), ".playbook/repo", entryPath);
-    const content = readFile(fullPath, entryId);
-    return { entryId, scope: "global", content };
+
+  if (!globalIndex) {
+    throw new CliError("No INDEX.json found. Run 'playbook global init' first.");
   }
 
-  // Not found
-  if (!projectIndex && !globalIndex) {
-    throw new CliError("No INDEX.json found. Run 'playbook init' or 'playbook global init' first.");
+  if (!globalIndex[entryId]) {
+    throw new CliError(`Entry '${entryId}' not found in INDEX.`);
   }
 
-  throw new CliError(`Entry '${entryId}' not found in project or global INDEX.`);
+  const entryPath = globalIndex[entryId].path;
+  const fullPath = path.join(os.homedir(), ".playbook/repo", entryPath);
+  const content = readFile(fullPath, entryId);
+  return { entryId, content };
 }
 
 function readFile(fullPath, entryId) {

package/src/core/context.js

@@ -11,14 +11,6 @@ function resolveGlobalRoot() {
   return path.join(home, ".playbook", "repo");
 }
 
-function resolveRuntimeContext(projectRoot = ".") {
-  return {
-    projectRoot: path.resolve(projectRoot),
-    globalRoot: resolveGlobalRoot(),
-  };
-}
-
 module.exports = {
-  resolveRuntimeContext,
   resolveGlobalRoot,
 };

package/src/manifest.js

@@ -1,14 +1,6 @@
-const PROJECT_SKELETON_DIRS = [
-  "docs/playbook/cases",
-  "docs/playbook/patterns",
-  "docs/playbook/checklists",
-];
+const PROJECT_SKELETON_DIRS = [];
 
 const PROJECT_MANAGED_FILES = [
-  {
-    relativePath: "docs/playbook/INDEX.json",
-    templatePath: "project/docs/playbook/INDEX.json",
-  },
   {
     relativePath: ".codex/skills/playbook-query/SKILL.md",
     templatePath: "project/skills/playbook-query/SKILL.md",
@@ -45,18 +37,6 @@ const PROJECT_MANAGED_FILES = [
     tool: "claude",
     overwriteOnUpdate: true,
   },
-  {
-    relativePath: ".codex/skills/playbook-promote/SKILL.md",
-    templatePath: "project/skills/playbook-promote/SKILL.md",
-    tool: "codex",
-    overwriteOnUpdate: true,
-  },
-  {
-    relativePath: ".claude/skills/playbook-promote/SKILL.md",
-    templatePath: "project/skills/playbook-promote/SKILL.md",
-    tool: "claude",
-    overwriteOnUpdate: true,
-  },
 ];
 
 const GLOBAL_SKELETON_DIRS = ["cases", "patterns", "checklists"];

package/src/options.js

@@ -108,7 +108,6 @@ function parseGlobalInitArgs(args) {
 
 function parseQueryArgs(args) {
   let limit = 7;
-  let scope = "both";
   let json = false;
   let tagsOnly = false;
   const tags = [];
@@ -152,25 +151,6 @@ function parseQueryArgs(args) {
       continue;
     }
 
-    if (arg === "--scope") {
-      const next = args[i + 1];
-      if (!next || !["project", "global", "both"].includes(next)) {
-        throw new CliError("--scope must be one of: project, global, both");
-      }
-      scope = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--scope=")) {
-      const value = arg.slice("--scope=".length);
-      if (!["project", "global", "both"].includes(value)) {
-        throw new CliError("--scope must be one of: project, global, both");
-      }
-      scope = value;
-      continue;
-    }
-
     if (arg.startsWith("-")) {
       throw new CliError(`Unknown option for playbook query: ${arg}`);
     }
@@ -178,47 +158,7 @@ function parseQueryArgs(args) {
     tags.push(arg);
   }
 
-  return { help: false, tags, limit, scope, json, tagsOnly };
-}
-
-function parsePromoteArgs(args) {
-  let force = false;
-  let all = false;
-  const entryIds = [];
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-
-    if (arg === "-h" || arg === "--help") {
-      return { help: true };
-    }
-
-    if (arg === "--force") {
-      force = true;
-      continue;
-    }
-
-    if (arg === "--all") {
-      all = true;
-      continue;
-    }
-
-    if (arg.startsWith("-")) {
-      throw new CliError(`Unknown option for playbook promote: ${arg}`);
-    }
-
-    entryIds.push(arg);
-  }
-
-  if (!all && entryIds.length === 0) {
-    throw new CliError("playbook promote requires entry IDs or --all");
-  }
-
-  if (all && entryIds.length > 0) {
-    throw new CliError("Cannot use --all with specific entry IDs");
-  }
-
-  return { help: false, force, all, entryIds };
+  return { help: false, tags, limit, json, tagsOnly };
 }
 
 function parseHitArgs(args) {
@@ -260,47 +200,23 @@ function parseShowArgs(args) {
 }
 
 function parseReindexArgs(args) {
-  let scope = "project";
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-
+  for (const arg of args) {
     if (arg === "-h" || arg === "--help") {
       return { help: true };
     }
 
-    if (arg === "--scope") {
-      const next = args[i + 1];
-      if (!next || !["project", "global"].includes(next)) {
-        throw new CliError("--scope must be one of: project, global");
-      }
-      scope = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg.startsWith("--scope=")) {
-      const value = arg.slice("--scope=".length);
-      if (!["project", "global"].includes(value)) {
-        throw new CliError("--scope must be one of: project, global");
-      }
-      scope = value;
-      continue;
-    }
-
     if (arg.startsWith("-")) {
       throw new CliError(`Unknown option for playbook reindex: ${arg}`);
     }
   }
 
-  return { help: false, scope };
+  return { help: false };
 }
 
 module.exports = {
   parseProjectCommandArgs,
   parseGlobalInitArgs,
   parseQueryArgs,
-  parsePromoteArgs,
   parseHitArgs,
   parseShowArgs,
   parseReindexArgs,

package/templates/project/skills/playbook-advisor/SKILL.md

@@ -17,7 +17,7 @@ This outputs all available tags with their case counts, e.g.: `docker(3) react(2
 
 Internalize this tag list. It tells you what domains have recorded experience.
 
-If the output is "No playbook INDEX found." — inform the user that no playbook knowledge is available and suggest running `playbook init` to get started. Stop here.
+If the output is "No playbook INDEX found." — inform the user that no playbook knowledge is available and suggest running `playbook global init` to get started. Stop here.
 
 ## When to Query
 

package/templates/project/skills/playbook-case/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playbook-case
-description: Draft and inspect playbook case entries with explicit scope and tags.
+description: Draft and inspect playbook case entries in global knowledge base.
 license: MIT
 ---
 
@@ -8,7 +8,7 @@ Use this skill when the user asks to create, review, or inspect case entries.
 
 ## Behavior
 
-- Keep scope explicit (`project` or `global`).
+- All entries are stored in the global knowledge base (`~/.playbook/repo/`).
 - Keep draft generation non-destructive by default.
 - For new cases, enforce this guided flow:
   1. If the user has not provided a concrete problem statement, ask first:
@@ -18,14 +18,10 @@ Use this skill when the user asks to create, review, or inspect case entries.
      playbook query --tags-only
      ```
      Suggest relevant existing tags from the output. Ask user to choose existing tags or explicitly confirm a new tag.
-  3. If scope is not confirmed, ask for scope confirmation:
-     - default is `project`
-     - use `global` only when user explicitly confirms
-  4. Only after required inputs are complete, produce the draft package.
+  3. Only after required inputs are complete, produce the draft package.
 - Required inputs before any draft output:
   - problem statement
   - tag decision (existing tags or confirmed new tag)
-  - scope confirmation
 - Hard gate: while any required input is missing, do not output case ID, suggested path, markdown draft, or INDEX update suggestion.
 - For new cases, once inputs are complete, produce a complete draft package:
   - case ID (format: `{type}-{NNN}-{slug}`, e.g. `case-001-oauth-token-race`)
@@ -94,20 +90,16 @@ The front matter is the source of truth for metadata. INDEX.json is rebuilt from
 
 ### File Paths
 
-Write files to the correct location based on scope:
-
-- **Project scope:** case file → `<project-root>/docs/playbook/<path>`, INDEX → `<project-root>/docs/playbook/INDEX.json`
-- **Global scope:** case file → `~/.playbook/repo/<path>`, INDEX → `~/.playbook/repo/INDEX.json`
-
-**IMPORTANT:** Always use absolute paths when writing files. Do NOT use relative paths — the current working directory may not be the project root.
+All files are stored in the global playbook directory.
 
 Get the playbook directory first:
 ```bash
-playbook root                   # project scope
-playbook root --scope global    # global scope
+playbook root
 ```
 Then use the output to construct absolute paths, e.g. `<root>/cases/case-001-xxx.md` and `<root>/INDEX.json`.
 
+**IMPORTANT:** Always use absolute paths when writing files. Do NOT use relative paths — the current working directory may not be the project root.
+
 ### Draft Package Output
 
 When producing the draft package, output:
@@ -132,6 +124,6 @@ Add this entry to INDEX.json:
 
 After user confirms the draft:
 
-1. Write the case file to the scope-specific path
-2. Read the current INDEX.json, merge the new entry, write back
+1. Write the case file to `~/.playbook/repo/<path>`
+2. Read the current INDEX.json at `~/.playbook/repo/INDEX.json`, merge the new entry, write back
 3. Run `playbook hit <entry-id>` is NOT needed — hit is only for reads

package/templates/project/skills/playbook-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playbook-query
-description: Query project and global playbook knowledge using CLI for token-efficient discovery.
+description: Query global playbook knowledge using CLI for token-efficient discovery.
 license: MIT
 ---
 
@@ -17,17 +17,16 @@ Run:
 playbook query <tag1> <tag2> ...
 ```
 
-This searches both project and global INDEX.json, returns matching entries (max 7 by default), with project results first.
+This searches the global INDEX.json and returns matching entries (max 7 by default).
 
 Options:
 - `--limit N` — change max results (0 = unlimited)
-- `--scope project|global|both` — restrict search scope
 - `--json` — output as JSON array
 
 Output format (one line per match):
 ```
-[scope]  entry-id  title  tags
-(N matches: X project, Y global)
+entry-id  title  tags  hits:N
+(N matches)
 ```
 
 ### Expansion (L2): Show entry content
@@ -42,6 +41,6 @@ This outputs the full content of the entry file. Only expand entries that are ac
 
 ### Edge Cases
 
-- If query returns "No playbook INDEX found." — tell the user: "No playbook initialized. Run `playbook init` to get started."
+- If query returns "No playbook INDEX found." — tell the user: "No playbook initialized. Run `playbook global init` to get started."
 - If query returns "No matching entries." — suggest trying different tags or running without tags to see all entries
 - If user query is vague, run `playbook query` without tags to list everything

package/src/commands/promote.js

@@ -1,96 +0,0 @@
-const fs = require("fs");
-const path = require("path");
-const os = require("os");
-const { CliError } = require("../errors");
-
-function readIndex(indexPath) {
-  try {
-    const content = fs.readFileSync(indexPath, "utf8");
-    return JSON.parse(content);
-  } catch {
-    return null;
-  }
-}
-
-function writeIndex(indexPath, data) {
-  fs.writeFileSync(indexPath, JSON.stringify(data, null, 2) + "\n", "utf8");
-}
-
-function promoteEntry(entryId, projectIndex, globalIndex, projectBase, globalBase, force) {
-  const entry = projectIndex[entryId];
-  if (!entry) {
-    return { action: "error", entryId, reason: `Entry '${entryId}' not found in project INDEX` };
-  }
-
-  if (globalIndex[entryId] && !force) {
-    return {
-      action: "conflict",
-      entryId,
-      reason: `Entry '${entryId}' already exists in global INDEX (use --force to overwrite)`,
-    };
-  }
-
-  const srcFile = path.join(projectBase, entry.path);
-  const destFile = path.join(globalBase, entry.path);
-
-  // Write to global first (safety: write before delete)
-  try {
-    fs.mkdirSync(path.dirname(destFile), { recursive: true });
-    fs.copyFileSync(srcFile, destFile);
-  } catch (err) {
-    return { action: "error", entryId, reason: `Failed to copy file to global: ${err.message}` };
-  }
-
-  globalIndex[entryId] = entry;
-
-  // Now safe to remove from project
-  delete projectIndex[entryId];
-  try {
-    fs.unlinkSync(srcFile);
-  } catch {
-    // File may not exist, that's ok — INDEX entry already removed
-  }
-
-  return { action: "promoted", entryId, title: entry.title };
-}
-
-function promoteEntries(options) {
-  const { entryIds = [], all = false, force = false, targetPath = "." } = options;
-
-  const projectBase = path.resolve(targetPath, "docs/playbook");
-  const globalBase = path.join(os.homedir(), ".playbook/repo");
-
-  const projectIndexPath = path.join(projectBase, "INDEX.json");
-  const globalIndexPath = path.join(globalBase, "INDEX.json");
-
-  const projectIndex = readIndex(projectIndexPath);
-  if (!projectIndex) {
-    throw new CliError("Project INDEX.json not found. Run 'playbook init' first.");
-  }
-
-  const globalIndex = readIndex(globalIndexPath);
-  if (!globalIndex) {
-    throw new CliError("Global INDEX.json not found. Run 'playbook global init' first.");
-  }
-
-  const ids = all ? Object.keys(projectIndex) : entryIds;
-
-  if (all && ids.length === 0) {
-    return { results: [], message: "No entries in project INDEX to promote." };
-  }
-
-  const results = [];
-  for (const id of ids) {
-    results.push(promoteEntry(id, projectIndex, globalIndex, projectBase, globalBase, force));
-  }
-
-  // Write updated indices
-  writeIndex(projectIndexPath, projectIndex);
-  writeIndex(globalIndexPath, globalIndex);
-
-  return { results };
-}
-
-module.exports = {
-  promoteEntries,
-};

package/templates/project/docs/playbook/INDEX.json

@@ -1 +0,0 @@
-{}

package/templates/project/skills/playbook-promote/SKILL.md

@@ -1,32 +0,0 @@
----
-name: playbook-promote
-description: Guide when to promote project-level playbook entries to global knowledge base.
-license: MIT
----
-
-Use this skill to suggest promoting valuable project experiences to the global knowledge base for cross-project reuse.
-
-## When to Suggest Promote
-
-Suggest `playbook promote <entry-id>` to the user when:
-- A project case was successfully used to resolve a problem and the lesson is not project-specific
-- A pattern or checklist has proven useful and would benefit other projects
-- The user explicitly asks about sharing knowledge across projects
-
-## When NOT to Suggest
-
-Do not suggest promote when:
-- The entry references project-specific configuration, paths, or dependencies
-- The entry is still being refined or hasn't been validated
-- The user is focused on other work (don't interrupt)
-
-## How to Promote
-
-```bash
-playbook promote <entry-id>              # promote a single entry
-playbook promote <id1> <id2>             # promote multiple entries
-playbook promote --all                   # promote all project entries
-playbook promote <entry-id> --force      # overwrite if already exists in global
-```
-
-The command moves entries from project to global: copies the file, updates both INDEX.json files, and removes the project copy.