docs: clarify Agent Trace install limitation

README.md

@@ -9,21 +9,30 @@ session without giving the plugin control over that session.
 
 Plugin ID: `agent-trace-showcase`. Current release: `0.1.1`.
 
-The CordisX Community Marketplace feed is not a trust root and must already be
-configured and enabled before `--source` can select it:
+Release `v0.1.1` is a documentation and source package. Its archive does not
+contain the standard `cordisx-package.json` manifest required by the current
+CordisX CLI artifact installer, so it cannot be installed with `plugin install`.
+Adding an artifact record to the Marketplace alone does not fix that package
+format gap.
+
+The published archive and `SHA256SUMS` remain available from the
+[GitHub release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1)
+for source inspection. Do not unpack it into a CordisX profile as a substitute
+for an installable package.
+
+After a future release provides the standard package manifest and compatible
+runtime bundle, the CLI syntax will be:
 
 ```sh
 FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json
 npx cordisx@beta source add "$FEED_URL" --yes
-npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version 0.1.1
+npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version <installable-version>
 ```
 
-Skip `source add` when that exact feed is already enabled. For another profile,
-add the same `--profile <profile>` argument to both commands. `--yes` confirms
-the source change only; it does not approve plugin permissions. The install
-command becomes available after the Marketplace entry lists the `0.1.1`
-artifact. Until then, download the release archive and `SHA256SUMS` from the
-[GitHub release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1).
+For another profile, add the same `--profile <profile>` argument to both future
+commands. `--source` selects an already configured and enabled source; it does
+not register one. `--yes` confirms the source change only and does not approve
+plugin permissions. A discovery source is not a trust root.
 
 ## Use
 
@@ -51,9 +60,9 @@ entity state, or reconstruct missing history.
 
 ## Troubleshooting
 
-- **Install cannot find version `0.1.1`:** confirm the Marketplace feed entry
-  has been updated with the release artifact; `--source` does not register or
-  repair a feed.
+- **`plugin install` rejects `0.1.1`:** this release is not an installable CLI
+  artifact because its archive lacks `cordisx-package.json`. Use the release
+  only for source inspection and wait for an explicitly installable version.
 - **Timeline is empty:** open it from a concrete Agent session and review the
   three session permissions in CordisX plugin settings.
 - **Timeline stops updating:** reopen the session route. A terminal subscription

README.zh-Hans.md

@@ -8,20 +8,25 @@ Agent Trace Showcase 为单个 Agent 会话提供只读 Timeline。它适合查
 
 插件 ID：`agent-trace-showcase`。当前版本：`0.1.1`。
 
-CordisX Community Marketplace feed 不是 trust root，且必须先配置并启用，
-`--source` 才能选择它：
+`v0.1.1` 是文档与源码包。其压缩包不包含当前 CordisX CLI artifact installer
+要求的标准 `cordisx-package.json` manifest，因此不能通过 `plugin install` 安装。
+只在 Marketplace 中添加 artifact 记录无法修复这个包格式缺口。
+
+已发布的压缩包和 `SHA256SUMS` 仍可从
+[GitHub Release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1)
+下载并检查源码。请勿将其解压到 CordisX profile 来替代正式安装包。
+
+未来版本同时提供标准 package manifest 和兼容 runtime bundle 后，CLI 语法将是：
 
 ```sh
 FEED_URL=https://raw.githubusercontent.com/cordisx/marketplace/main/marketplace.json
 npx cordisx@beta source add "$FEED_URL" --yes
-npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version 0.1.1
+npx cordisx@beta plugin install agent-trace-showcase --source "$FEED_URL" --version <installable-version>
 ```
 
-若该 feed 已启用，可跳过 `source add`。使用其他 profile 时，两条命令都要添加
-相同的 `--profile <profile>`。`--yes` 只确认来源变更，不会批准插件权限。
-Marketplace 条目列出 `0.1.1` artifact 后，安装命令才可用；在此之前，可从
-[GitHub Release](https://github.com/cordisx/plugin-agent-trace/releases/tag/v0.1.1)
-下载压缩包与 `SHA256SUMS`。
+使用其他 profile 时，未来的两条命令都要添加相同的 `--profile <profile>`。
+`--source` 只能选择已配置并启用的来源，不会注册来源；`--yes` 只确认来源变更，
+不会批准插件权限。发现来源也不等同于 trust root。
 
 ## 使用
 
@@ -44,8 +49,8 @@ Host 服务、精确路由权限、Session、读取或订阅不可用时，Timel
 
 ## 排错
 
-- **找不到 `0.1.1`：**确认 Marketplace feed 已加入该版本 artifact；`--source`
-  不会注册或修复 feed。
+- **`plugin install` 拒绝 `0.1.1`：**该版本压缩包缺少 `cordisx-package.json`，不是
+  CLI 可安装 artifact。它仅供源码检查，请等待明确标记为可安装的后续版本。
 - **Timeline 为空：**从具体 Agent 会话打开 Timeline，并在插件设置中检查三项
   Session 权限。
 - **Timeline 停止更新：**重新打开会话路由。插件会显示终止原因，不会静默切换