@c4a/context-cli 0.7.16 → 0.7.20

package/README.md

@@ -18,10 +18,24 @@ an LLM itself.
 
 ```bash
 npm install -g @c4a/context-cli@latest
-context plugin install
+context plugin install # global installation
+# Alternatively, install only in a repository:
+context plugin install --local /path/to/repo
 ```
 
-Restart or refresh the Agent host after installation. One install creates the
+`--local <path>` requires an explicit path without global configuration changes. Omit `--agent` to detect Claude Code, Cursor and Codex executables on PATH (including `cursor-agent`), plus Cursor/Codex in standard macOS Applications directories. Only detected hosts are installed under the repository's `.claude`, `.cursor`, or `.agents`. If none are detected, only `.agents/skills` is installed with a user hint. Stale configuration directories are not detection evidence; discovery does not verify runtime loading. Omitting `--local` keeps global installation.
+
+Automatic mode accepts a repository root; paths ending in `.claude`, `.cursor`, or `.agents` use their parent as the root. Explicit `--agent` still uses the exact supplied host directory below; `--agent all` is not accepted with `--local`.
+
+| Command | Local layout |
+| --- | --- |
+| `context plugin install --local /path/to/repo/.claude --agent claude` | Public entries in `commands/`, other skills in `skills/`; internal skills receive `user-invocable: false`, without duplicate entry skills |
+| `context plugin install --local /path/to/repo/.cursor --agent cursor` | Bundled `c4a-*` commands plus other skills; hiding Providers from the command menu is not guaranteed |
+| `context plugin install --local /path/to/repo/.agents --agent codex` | All entries remain skills; bundled `agents/openai.yaml` policies are preserved; no unsupported `commands/` directory |
+
+Local entries have no plugin namespace; the host must discover the destination. Use `--dry-run` to preview. Refresh only replaces unmodified managed content; unrelated files remain and conflicting/customized entries are rejected. Choose a fresh host directory when switching from a standalone installation to command entries, to avoid duplicates. `plugin status` still inspects global hosts only. Invocation metadata is not a CLI permission or security boundary.
+
+Restart or refresh the Agent host after installation. Global installation creates the
 host-namespaced Context entry and projects `context-code-indexer` and
 `context-markdown-indexer`, `context-note-indexer` and
 `context-sessions-indexer` as unnamespaced lifecycle Provider Skills for

package/README.zh-CN.md

@@ -14,10 +14,24 @@
 
 ```bash
 npm install -g @c4a/context-cli@latest
-context plugin install
+context plugin install # 全局安装
+# 或者，只安装到仓库：
+context plugin install --local /path/to/repo
 ```
 
-安装后重启或刷新 Agent 宿主。一次安装会生成一个带宿主命名空间的 Context 主入口，
+`--local <路径>` 必须显式指定路径，不注册全局插件、不修改用户级配置。省略 `--agent` 时探测 PATH 中的 Claude Code、Cursor、Codex（Cursor 也检查 `cursor-agent`；macOS 另检查标准 Applications 目录中的 Cursor/Codex），安装检测到的宿主到仓库下的 `.claude`、`.cursor`、`.agents`。均未检测到时，仅安装 `.agents/skills` 并输出提示。不根据遗留配置目录判断已安装；探测不代表已验证宿主加载技能。
+
+自动模式传仓库根路径；若末尾为 `.claude`、`.cursor` 或 `.agents`，以其父目录为根，不嵌套宿主目录。显式指定单一 `--agent` 时仍以传入路径为精确目标，见下表（不接受 `--agent all`）。不传 `--local` 保持全局安装。
+
+| 命令 | 局部目录与行为 |
+| --- | --- |
+| `context plugin install --local /path/to/repo/.claude --agent claude` | `commands/` 放公开入口；`skills/` 放其他技能，内部技能设置 `user-invocable: false`，不重复安装入口 Skill |
+| `context plugin install --local /path/to/repo/.cursor --agent cursor` | `commands/` 使用随包的 `c4a-*` 命令；`skills/` 放其他技能，不保证隐藏 Provider 的菜单入口 |
+| `context plugin install --local /path/to/repo/.agents --agent codex` | 全部入口保留为 skills，保留随包的 `agents/openai.yaml` 调用策略，不生成无效的 `commands/` |
+
+宿主必须支持发现目标位置。局部入口没有插件命名空间。`--dry-run` 只预览；重复安装仅刷新本命令管理且未被修改的内容，保留无关文件；同名自定义内容或本地修改会报冲突。已有通用 skills 目录切换为 command 宿主时，请选择新目录，避免重复入口。`plugin status` 仍只检查全局宿主状态。调用元数据控制宿主入口展示/自动调用，不是 CLI 权限或安全隔离。
+
+安装后重启或刷新 Agent 宿主。全局安装会生成一个带宿主命名空间的 Context 主入口，
 并把 `context-code-indexer`、`context-markdown-indexer` 作为无命名空间的生命周期
 Provider Skill 投影到 Claude、Codex 和 Cursor 的用户技能目录。