docs: keep llmdoc outside project dependencies

.agents/skills/llmdoc/SKILL.md

@@ -12,10 +12,12 @@ This skill is the operating protocol for V3 `llmdoc` projects.
 
 ## Retrieval Gate
 
-Require the local `@tokenroll/llmdoc` package and invoke it as
-`npx --no-install @tokenroll/llmdoc ...`. If it is unavailable, do not install
-it implicitly; report the degraded path and continue with narrowly scoped
-native tools.
+Treat `@tokenroll/llmdoc` as external tooling and invoke it as
+`npx -y @tokenroll/llmdoc ...`. A missing package may be fetched into the npm
+cache, but it must never be added to the consumer repository's `package.json`
+or lockfile. Pin the version in the npx package spec when reproducibility
+requires it. If the CLI remains unavailable, report the degraded path and
+continue with narrowly scoped native tools.
 
 Before the first discovery action for a task—and again whenever the
 investigation expands into a new subsystem—choose the matching entry point:

README.md

@@ -7,18 +7,27 @@
 ## Requirements
 
 - Node.js 18 or newer
-- install `@tokenroll/llmdoc` before running `npx @tokenroll/llmdoc`
+- run `@tokenroll/llmdoc` as external tooling through npx
 - git for validity, delta, and rollback semantics
 
-Recommended project-local install:
+Start without adding anything to the project's dependencies:
 
 ```bash
-npm install --save-dev @tokenroll/llmdoc
+npx -y @tokenroll/llmdoc tree
 ```
 
+If you prefer to download the CLI to your machine explicitly, install it globally rather than adding it to a project:
+
+```bash
+npm install --global @tokenroll/llmdoc
+llmdoc tree
+```
+
+This optional machine-wide install does not modify the consumer repository's `package.json` or lockfile. Append an exact version to the package name when needed, for example `npm install --global @tokenroll/llmdoc@3.1.1`.
+
 V3 assumes the CLI is always present. Navigation, search, validation, delta detection, hook signals, and workflow entrypoints come from `npx @tokenroll/llmdoc`.
 
-> Always invoke with the full scoped name `npx @tokenroll/llmdoc <cmd>` — never a bare `npx llmdoc`, which would resolve to an unrelated third-party npm package in environments where this package is not installed. With the scoped name there is no wrong-package risk: npx runs the locally installed copy, or fetches the correct package if missing. Hooks use `npx -y @tokenroll/llmdoc` so a missing package can be fetched without an interactive prompt. Install the CLI locally for deterministic, offline-capable runs.
+> Always invoke with the full scoped name `npx @tokenroll/llmdoc <cmd>` — never a bare `npx llmdoc`, which would resolve to an unrelated third-party npm package. `npx -y` fetches a missing CLI into the npm cache without modifying the consumer repository's `package.json` or lockfile. When a workflow needs a fixed version, pin it in the package spec, for example `npx -y @tokenroll/llmdoc@3.1.1 tree`; do not install llmdoc as a project dependency.
 
 
 ## Public Surface
@@ -208,15 +217,16 @@ Install from the repository root so the local `llmdoc` bin is linked before vali
 
 ## Other Platforms
 
-Claude Code and Codex users get all of this from the plugin (hooks, operating skill, workflow commands). For tools without a native plugin system, install `@tokenroll/llmdoc` and paste this recipe into the project's `AGENTS.md`:
+Claude Code and Codex users get all of this from the plugin (hooks, operating skill, workflow commands). For tools without a native plugin system, invoke `@tokenroll/llmdoc` on demand through npx and paste this recipe into the project's `AGENTS.md`:
 
 ```markdown
 # llmdoc
 
 This project uses llmdoc V3 as persistent engineering context.
 
-- `@tokenroll/llmdoc` must be installed locally; call it as
-  `npx --no-install @tokenroll/llmdoc ...`. Do not install it implicitly.
+- Treat `@tokenroll/llmdoc` as external tooling: call it as
+  `npx -y @tokenroll/llmdoc ...`; never add it to this project's `package.json`
+  or lockfile. Pin the version in the npx package spec when needed.
 - Before the first discovery action, and again when entering a new subsystem,
   choose the matching entry point: concept/contract/“where is X?” → `search`;
   concrete source files → `context --files`; unclear scope → `tree`; known

README.zh-CN.md

@@ -4,21 +4,30 @@
 
 `llmdoc` 是代码仓库的持久化外置上下文：把 AI 不该每次会话都重新恢复的架构、约束和工作知识放进可检索、可验证、可演进的文档层。
 
-## 强制依赖
+## 运行要求
 
 - Node.js 18 或更新版本
-- 先安装 `@tokenroll/llmdoc`，再运行 `npx @tokenroll/llmdoc`
+- 通过 npx 把 `@tokenroll/llmdoc` 作为项目外部工具运行
 - git 作为有效性、delta 与回滚语义的基础
 
-推荐把 CLI 装进项目依赖，例如：
+无需向项目添加任何依赖，直接运行：
 
 ```bash
-npm install --save-dev @tokenroll/llmdoc
+npx -y @tokenroll/llmdoc tree
 ```
 
+如果希望把 CLI 明确下载到本机，请安装到全局环境，而不是加入某个业务项目：
+
+```bash
+npm install --global @tokenroll/llmdoc
+llmdoc tree
+```
+
+这个可选的本机安装方式不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接追加版本号，例如 `npm install --global @tokenroll/llmdoc@3.1.1`。
+
 V3 假定 CLI 始终存在。导航、检索、校验、delta 检测、hook 信号和工作流入口都来自 `npx @tokenroll/llmdoc`。
 
-> 一律使用完整 scoped 名调用：`npx @tokenroll/llmdoc <cmd>`，永远不要用裸的 `npx llmdoc`——在未安装本包的环境里，裸名会解析到 npm 上一个无关的第三方包。使用 scoped 名则不存在任何错包风险：npx 会运行本地已安装副本，缺失时自动获取正确的包。hooks 使用 `npx -y @tokenroll/llmdoc`，缺包时无需交互确认即可获取；若要保证版本确定且离线可用，仍应把 CLI 安装为项目本地依赖。
+> 一律使用完整 scoped 名调用：`npx @tokenroll/llmdoc <cmd>`，永远不要用裸的 `npx llmdoc`——后者会解析到 npm 上一个无关的第三方包。`npx -y` 会把缺失的 CLI 获取到 npm 缓存，不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接写在包名后，例如 `npx -y @tokenroll/llmdoc@3.1.1 tree`；不要把 llmdoc 安装为项目依赖。
 
 
 ## 公开接口
@@ -208,15 +217,16 @@ npm run check:prompts
 
 ## 其他平台
 
-Claude Code 与 Codex 用户由插件承担这一切（hooks、operating skill、工作流命令）。没有原生插件系统的工具，安装 `@tokenroll/llmdoc` 后把下面这份配方贴进项目的 `AGENTS.md` 即可：
+Claude Code 与 Codex 用户由插件承担这一切（hooks、operating skill、工作流命令）。没有原生插件系统的工具，通过 npx 按需调用 `@tokenroll/llmdoc`，并把下面这份配方贴进项目的 `AGENTS.md` 即可：
 
 ```markdown
 # llmdoc
 
 本项目使用 llmdoc V3 作为持久化工程上下文。
 
-- 必须在本地安装 `@tokenroll/llmdoc`；一律以
-  `npx --no-install @tokenroll/llmdoc ...` 调用，不要隐式安装。
+- 把 `@tokenroll/llmdoc` 当作项目外部工具，以
+  `npx -y @tokenroll/llmdoc ...` 调用；绝不将它写入本项目的 `package.json`
+  或 lockfile。需要时在 npx 包名中固定版本。
 - 第一次发现式检索前，以及每次进入新子系统时，按意图选择入口：概念、
   契约或“X 在哪里”→ `search`；具体源码文件 → `context --files`；范围不明 →
   `tree`；已知 topic/kind → `index`；已定位的文档正文 → `show`。

docs/v3-design/01-knowledge-model.md

@@ -15,7 +15,7 @@ llmdoc/
 规则:
 
 - 层级固定两层:根单例 + topic folder。**topic folder 内不允许再建子目录**;需要嵌套说明应该拆一个新 topic。
-- **没有任何静态 index**:全局地图由 `llmdoc tree` 动态生成,topic 摘要由 CLI 从文档 front matter 聚合(CLI 是强制依赖,见 03)。手写的目录/清单必然腐烂,V3 不维护任何一份;`index.mdx` 文件名在任何位置都被 validate 拒绝。
+- **没有任何静态 index**:全局地图由 `llmdoc tree` 动态生成,topic 摘要由 CLI 从文档 front matter 聚合(CLI 是强制外部工具,见 03)。手写的目录/清单必然腐烂,V3 不维护任何一份;`index.mdx` 文件名在任何位置都被 validate 拒绝。
 - topic 的 purpose/boundary 需要成文时,写进该 topic 的 `architecture.mdx` 推荐槽位;只有零散短事实的 topic 直接靠文档 description route。
 - 根单例(如 `architecture.mdx`)是 init 模板的推荐槽位,schema 不强制——小项目不被逼着写空文件。
 - kind 只在 front matter 表达,目录不承载 kind 语义(topic 内平铺)。

docs/v3-design/03-cli.md

@@ -4,8 +4,8 @@
 
 CLI 是 V3 的 Runtime 实体:所有确定性、可测试、重复出现的工作从 prompt 移入 CLI。模型只负责判断(读什么、写什么知识),CLI 负责机械(扫描、索引、校验、diff、检索、hook 信号)。
 
-- **技术栈**:TypeScript,Node ≥ 18,npm 包名 `@tokenroll/llmdoc`,唯一 bin 名 `llmdoc`;使用环境安装该包后,默认以 `npx @tokenroll/llmdoc <cmd>` 调用(MDX/remark 生态只有 JS 是一等公民)。
-- **强制依赖**:所有使用 llmdoc 的环境必须先安装 `@tokenroll/llmdoc`,并确保 `npx @tokenroll/llmdoc` 解析到其本地 bin。这是硬性要求——正因为 CLI 必定在场,V3 才能砍掉手写的根 index,把全局地图交给 `tree` 动态生成。单份文档仍是纯粹的 Markdown(`cat` 可读),但导航、检索、校验不为无 CLI 环境做设计妥协。
+- **技术栈**:TypeScript,Node ≥ 18,npm 包名 `@tokenroll/llmdoc`,唯一 bin 名 `llmdoc`;使用环境默认以 `npx -y @tokenroll/llmdoc <cmd>` 按需调用这个项目外部工具(MDX/remark 生态只有 JS 是一等公民)。
+- **强制工具**:所有使用 llmdoc 的环境必须能运行 `npx -y @tokenroll/llmdoc`,但不得因此把包加入业务项目的 `package.json` 或 lockfile。这是硬性要求——正因为 CLI 必定可调用,V3 才能砍掉手写的根 index,把全局地图交给 `tree` 动态生成。单份文档仍是纯粹的 Markdown(`cat` 可读),但导航、检索、校验不为无 CLI 环境做设计妥协。
 - **双输出**:默认输出面向 agent 的 token 精简文本;`--json` 输出机器可读结构。
 - **预算与分页**:批量输出带条数与预估 token 预算,超限返回 continuation cursor,**不静默截断**。
 - **安全**:只接受仓库内规范化相对路径,拒绝 `..` 越界与逃逸 symlink;结构化输出过 schema 校验。

docs/v3-design/04-workflows.md

@@ -34,7 +34,7 @@ SessionStart hook → 一行状态信号
 → llmdoc show <少量文档>                            # 只读确有价值的正文
 ```
 
-每一层都允许停止。没有固定 startup pack;读多少由任务决定。CLI 是强制依赖,`tree` 就是根入口——不存在"先找 index.md"这一步。
+每一层都允许停止。没有固定 startup pack;读多少由任务决定。CLI 是强制外部工具,`tree` 就是根入口——不存在"先找 index.md"这一步。
 
 ### 3.2 Compact continuation
 

docs/v3-design/05-packaging.md

@@ -47,7 +47,7 @@ llmdoc-repository/                  # 根 = 标准 Claude Code plugin
 2. Codex 表面(`.codex-plugin/` + skills 化包装)由 **ACPlugin**(插件互转项目)从 Claude 表面转换生成,本仓库不自建 generate/verify 管线;
 3. 配一份 parity checklist(命令集、授权语义、hook 行为逐条对照),转换结果按 checklist 抽验,防行为漂移;
 4. Codex 当前支持 project-scoped custom agents；保留 ACPlugin 从两个 Claude 角色契约生成的 `.codex/agents/*.toml`,但不手工维护第二份角色文本,也不在安装后另行改写用户项目;
-5. 其他平台(Cursor、Gemini CLI 等)不做插件:README 提供一段 AGENTS.md 配方 + `npx @tokenroll/llmdoc`(CLI 是强制依赖也是跨平台契约,插件只是发行渠道)。
+5. 其他平台(Cursor、Gemini CLI 等)不做插件:README 提供一段 AGENTS.md 配方 + `npx -y @tokenroll/llmdoc`(CLI 是项目外部工具和跨平台契约,不得加入业务项目依赖;插件只是发行渠道)。
 
 共同约束:
 

docs/v3-design/README.md

@@ -11,7 +11,7 @@ llmdoc 是工程的**持久化外置上下文**:把代码里无法低成本恢
 ## 设计原则
 
 1. **轻量优先**:不引入重机械。Markdown + YAML front matter 是基座,MDX 只作最小增强;事务靠 git,不自建 snapshot/journal;检索靠词法,必要时 grep 也能用。
-2. **CLI 即 Runtime,且是强制依赖**:所有确定性工作(索引、校验、delta、检索、hook 信号)由 npm 包 `@tokenroll/llmdoc` 承担,该包暴露可执行文件 `llmdoc`;判断性工作(写什么知识、怎么组织)留给模型;prompt 只描述"什么时候调哪个命令"。使用环境必须先安装 `@tokenroll/llmdoc`,并能运行解析到该本地 bin 的 `npx @tokenroll/llmdoc`——正因如此,全局地图可以由 `llmdoc tree` 动态生成,不再需要手工维护的根 index。
+2. **CLI 即 Runtime,且是强制工具**:所有确定性工作(索引、校验、delta、检索、hook 信号)由 npm 包 `@tokenroll/llmdoc` 承担,该包暴露可执行文件 `llmdoc`;判断性工作(写什么知识、怎么组织)留给模型;prompt 只描述"什么时候调哪个命令"。使用环境通过 `npx -y @tokenroll/llmdoc` 按需运行这个项目外部工具,不得把它加入业务项目的 `package.json` 或 lockfile——正因 CLI 始终可调用,全局地图可以由 `llmdoc tree` 动态生成,不再需要手工维护的根 index。
 3. **结构即知识**:目录层级本身承载分类学,固定两层(根单例 + topic folder);topic 是纯目录,没有任何静态入口节点——全局与 topic 级摘要都由 CLI 动态聚合。
 4. **文档本身仍是纯粹的 Markdown**:MDX 只作最小增强,`cat` 单份文档依然完全可读;但导航、检索、校验依赖 CLI,不为无 CLI 环境做设计妥协。
 5. **git-native**:路径即文档 ID,变更检测锚定 git revision,回滚就是 `git checkout`。
@@ -43,7 +43,7 @@ llmdoc 是工程的**持久化外置上下文**:把代码里无法低成本恢
 
 ## 已拍板的关键决策
 
-- **`@tokenroll/llmdoc` 是强制依赖**:npm 包名是 `@tokenroll/llmdoc`,bin 名是 `llmdoc`;所有使用环境必须先安装该包,再运行 `npx @tokenroll/llmdoc`(Node ≥ 18)。
+- **`@tokenroll/llmdoc` 是强制外部工具**:npm 包名是 `@tokenroll/llmdoc`,bin 名是 `llmdoc`;所有使用环境通过 `npx -y @tokenroll/llmdoc` 调用(Node ≥ 18),不向业务项目写入包依赖。
 - Markdown + YAML front matter 为基座;使用标准 MDX 语法但组件白名单仅 `<CodeRef>`,且为可选增强。
 - 路径即文档 ID。
 - `meta.json` 单文件,只存有效性台账(方案 A);聚合索引(方案 B)留待后续 benchmark。

llmdoc/architecture.mdx

@@ -20,6 +20,7 @@ code:
     - package.json
     - README.md
     - README.zh-CN.md
+    - docs/v3-design/*.md
 ---
 
 # llmdoc 仓库整体架构
@@ -37,7 +38,7 @@ V3 的重要分工是“提示词只做判断，CLI 负责机械”。命令文
 
 operating skill 与 README 内嵌配方用 Retrieval Gate 落实这个分工：第一次发现式检索及调查进入新子系统时，按意图从 `search`（概念或契约）、`context --files`（具体源码文件）、`tree`（范围不明）、`index`（已知 topic/kind）或 `show`（已定位文档正文）中选择入口，而不是把命令跑成固定序列。CLI 圈定工作集后，原生工具负责源码、行号、测试、计数和 git 状态等实时精确事实。
 
-当前仓库已经按 V3 的公开接口改写：README（含给无插件平台的内嵌 AGENTS.md 配方）、命令面、hook 面与 CI/release 都以 `@tokenroll/llmdoc` CLI 为共同 runtime；operating skill 与 README 检索配方要求本地包并使用 `npx --no-install @tokenroll/llmdoc`，避免隐式安装。这个调用约束只描述这些检索提示面，不代表 hook 或所有 workflow 命令都使用相同参数。V2 的根 `index.md`、`startup.md`、`sync.md`、`worker`、`reflector` 不再是有效契约。
+当前仓库已经按 V3 的公开接口改写：README（含给无插件平台的内嵌 AGENTS.md 配方）、命令面、hook 面与 CI/release 都以 `@tokenroll/llmdoc` CLI 为共同 runtime。operating skill 与 README 检索配方通过 `npx -y @tokenroll/llmdoc` 按需调用这个项目外部工具；缺包时只写入 npm 缓存，不得改写被服务项目的 `package.json` 或 lockfile，需要固定版本时在 npx 包名中 pin 即可。V2 的根 `index.md`、`startup.md`、`sync.md`、`worker`、`reflector` 不再是有效契约。
 
 按主题继续阅读（topic 无入口节点，用 `llmdoc index --topic <t>` 看各文档描述）：
 

llmdoc/meta.json

@@ -6,7 +6,7 @@
   },
   "documents": {
     "architecture.mdx": {
-      "validatedRevision": "2d593e2a45f0a29896ed4b0893be54621de68ace"
+      "validatedRevision": "8ea14be248547b296158119176459d0e4b31b654"
     },
     "cli-runtime/state-and-validation.mdx": {
       "validatedRevision": "49ea44d8a5b7ab1bd21579c8ef481057e272f747"
@@ -15,10 +15,10 @@
       "validatedRevision": "a982208863b2c9a3e0495eee88e28b99ecf79a2e"
     },
     "plugin-packaging/claude-and-codex.mdx": {
-      "validatedRevision": "2d593e2a45f0a29896ed4b0893be54621de68ace"
+      "validatedRevision": "8ea14be248547b296158119176459d0e4b31b654"
     },
     "plugin-packaging/development-and-release.mdx": {
-      "validatedRevision": "49ea44d8a5b7ab1bd21579c8ef481057e272f747"
+      "validatedRevision": "8ea14be248547b296158119176459d0e4b31b654"
     },
     "workflows/init-and-update.mdx": {
       "validatedRevision": "a982208863b2c9a3e0495eee88e28b99ecf79a2e"

llmdoc/plugin-packaging/claude-and-codex.mdx

@@ -45,7 +45,7 @@ code:
 
 因此包装层变更时，先检查命令文档是否只保留判断性内容；不要把 diff、schema 校验或 git 逻辑重新写进 prompt。
 
-Retrieval Gate 是需要跨宿主保持语义一致的判断性契约：第一次发现式检索与进入新子系统时按意图选择 CLI 入口，圈定工作集后允许原生工具核对实时精确事实，并且不把检索命令跑成固定序列。Claude canonical skill、生成的 `.agents/skills/llmdoc/SKILL.md` 与面向无插件平台的中英文 README 配方应保持这些边界及本地 `npx --no-install` 调用语义一致；宿主 front matter 和具体措辞可以不同。
+Retrieval Gate 是需要跨宿主保持语义一致的判断性契约：第一次发现式检索与进入新子系统时按意图选择 CLI 入口，圈定工作集后允许原生工具核对实时精确事实，并且不把检索命令跑成固定序列。Claude canonical skill、生成的 `.agents/skills/llmdoc/SKILL.md` 与面向无插件平台的中英文 README 配方应保持这些边界及外部 `npx -y @tokenroll/llmdoc` 调用语义一致；不得为了满足 gate 而改写业务项目依赖。宿主 front matter 和具体措辞可以不同。
 
 ## Codex 兼容面的实际要求
 
@@ -62,7 +62,7 @@ acplugin 转换注意（重生成后需人工核对）：`model: inherit` 硬编
 
 `scripts/check-codex-surface.mjs` 会自动拒绝任一 marketplace 名不是 `llmdoc-plugin` 或两侧名称不一致；`tests/parity-checklist.md` 则要求发布前人工确认两侧 marketplace 名与插件名分别为 `llmdoc-plugin` 和 `llmdoc`。
 
-根 `hooks/hooks.json` 不靠 ACPlugin 复制；Claude 与 Codex 都直接共用这份根 hook 壳，并统一通过 `npx -y @tokenroll/llmdoc` 调用 CLI hook 子命令。`-y` 允许缺包时非交互获取正确的 scoped 包；本地安装仍是确定版本和离线运行的首选。
+根 `hooks/hooks.json` 不靠 ACPlugin 复制；Claude 与 Codex 都直接共用这份根 hook 壳，并统一通过 `npx -y @tokenroll/llmdoc` 调用 CLI hook 子命令。`-y` 允许缺包时非交互获取正确的 scoped 包到 npm 缓存，且不触碰业务项目的依赖清单；需要确定版本时应在 npx 包名中 pin，而不是执行会改写项目 `package.json` 或 lockfile 的安装命令。
 
 维护时要遵守两点：