@c4a/context-cli 0.7.17 → 0.7.23

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 --agent auto-detect
 ```
 
-Restart or refresh the Agent host after installation. One install creates the
+`--local` requires explicit `--agent`: `claude`, `cursor`, `codex`, `all`, `auto-detect`, or `standalone`. The path is a repository root: explicit hosts install into `.claude`, `.cursor`, or `.agents` without detection. `all` installs all three. Only `auto-detect` checks existing `.claude`, `.cursor`, and `.agents` directories in the target repository, never PATH or installed desktop applications; it falls back to `.agents/skills` when none exist. `standalone` instead writes all skills directly to `<path>/skills`, with no commands or host subdirectory. All modes support `--dry-run` and preserve global configuration.
+
+Migration from 0.7.20: add `--agent auto-detect` to bare `--local`; for explicit hosts pass the repository root, not its host directory. Global installation is unchanged. Host detection does not verify runtime loading.
+
+| Command | Local layout |
+| --- | --- |
+| `context plugin install --local /path/to/repo --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 --agent cursor` | Bundled `c4a-*` commands plus other skills; hiding Providers from the command menu is not guaranteed |
+| `context plugin install --local /path/to/repo --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 auto-detect
 ```
 
-安装后重启或刷新 Agent 宿主。一次安装会生成一个带宿主命名空间的 Context 主入口，
+`--local` 必须显式搭配 `--agent`：`claude`、`cursor`、`codex`、`all`、`auto-detect` 或 `standalone`。路径为仓库根；指定宿主直接写入对应 `.claude`、`.cursor`、`.agents` 子目录，不检测是否安装宿主。`all` 全装；只有 `auto-detect` 检测目标仓库已有的 `.claude`、`.cursor`、`.agents` 目录，不检测 PATH 或桌面应用；均不存在时兜底 `.agents/skills`。`standalone` 则直接写入 `<path>/skills`，不生成 commands 或宿主子目录。均支持 `--dry-run`，不改全局配置。
+
+从 0.7.20 迁移：裸 `--local` 补充 `--agent auto-detect`；指定宿主时传仓库根，不再传宿主目录。全局安装不变。自动探测不代表宿主已加载，安装后需刷新宿主。
+
+| 命令 | 局部目录与行为 |
+| --- | --- |
+| `context plugin install --local /path/to/repo --agent claude` | `commands/` 放公开入口；`skills/` 放其他技能，内部技能设置 `user-invocable: false`，不重复安装入口 Skill |
+| `context plugin install --local /path/to/repo --agent cursor` | `commands/` 使用随包的 `c4a-*` 命令；`skills/` 放其他技能，不保证隐藏 Provider 的菜单入口 |
+| `context plugin install --local /path/to/repo --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 的用户技能目录。