cordisx · NWYLZW · Sep 19, 2026 · Sep 19, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -9,3 +9,20 @@
 - Do not add compatibility shims during the current design-validation phase.
 - The package currently keeps the existing product identifiers, but no API or
   configuration compatibility is implied by that naming.
+
+## Development and release
+
+- Requires Node.js 22 or newer. Install with `npm ci`.
+- Run `npm run check`, `npm pack --dry-run`, and `git diff --check` before a
+  checkpoint commit. `npm run check` includes typecheck, build, tests, source
+  lint, format verification, and the package dry run.
+- The public README is for installation and use. Keep architecture checkpoints,
+  source layout, build details, test commands, contribution steps, and release
+  operations here or in an indexed maintainer guide.
+- Releases use a GitHub prerelease, not npm. Build the exact merged main commit,
+  create the private package tarball with `npm pack`, publish it as
+  `cordisx-agent-trace-showcase-<version>.tgz` with `SHA256SUMS`, and verify both
+  assets by downloading and hashing them. Do not publish until the package
+  descriptor, package version, README version, tag, and archive all agree.
+- Marketplace artifact URLs and SHA-256 digests are updated by the Marketplace
+  owner after the release. Do not copy an older Official or Certified record.
diff --git a/README.md b/README.md
@@ -1,91 +1,66 @@
 # CordisX Agent Trace Showcase
 
-Agent Trace Showcase is an independent, read-only CordisX plugin repository.
-It owns the Timeline business projection and body composition; the Host owns
-session chrome, route behavior, shared controls, accessibility, permission UI,
-and native lifecycle authority.
+Agent Trace Showcase adds a read-only Timeline for one Agent session. It is
+useful when you need to inspect durable session events, lifecycle transitions,
+tool activity, approvals, and the exact entity definition recorded with the
+session without giving the plugin control over that session.
 
-The Timeline consumes the public Agent/Session Runtime contract. It reports an
-honest empty unavailable state whenever the Host does not provide the
-permission-scoped Session service.
+## Install
 
-## API checkpoint
+Plugin ID: `agent-trace-showcase`. Current release: `0.1.1`.
 
-The Agent/Session Runtime ownership model is:
+The CordisX Community Marketplace feed is not a trust root and must already be
+configured and enabled before `--source` can select it:
 
-- a Host-private Session authority owns one append-only `SessionEvent` log;
-- the public plugin seam is a permission-scoped, read-only `ctx.sessions`
-  service for immutable Session snapshots and post-commit event subscription;
-- `ctx.agents` owns create/resume/get and returns public live Agent handles;
-- `ctx.approvals` owns approval requests and decisions;
-- environment composition and transport bindings remain Host-private and do
-  not change plugin contracts, permissions, or Session facts.
-
-The contracts are `@cordisx/protocol/sessions/v1` and the additive
-`EntityDefinitionBoundSessionEvent` from `@cordisx/protocol/entities/v1` at
-Protocol main commit `c96c290697f9e802a68c6d3bb094fd27d8d00d1e`.
-The Timeline reads a fixed Session snapshot, pages through its immutable
-watermark, then follows the atomic replay/live subscription. Subscription
-termination clears the view and reports the terminal code.
-
-For an entity-backed Session, `entity/definition-bound` is the durable source
-of the exact historical definition identity, digest, and definition bytes.
-The Timeline projects that persisted binding and never queries `ctx.entities`
-or relabels prior Session history from the latest local entity revision.
-
-The plugin consumes no alternate event service, Host-private import, unsafe
-cast, raw bridge, adapter, or second ledger.
-
-The v5 runtime manifest declares optional `sessions.get`, `sessions.read`, and
-`sessions.subscribe` capabilities. Each is bound to the active
-`session.timeline` route's exact `:sessionId`; no empty or wildcard scope is
-accepted.
-
-## Host-owned UI
+```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
+```
 
-The plugin registers structured route, page, and session-header-action
-descriptors. Its React contribution renders only the Timeline business body
-using `cordisx/ui`. It does not import TDesign, copy Host chrome or tabs, query
-Host-private selectors, or mutate Host DOM.
+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).
 
-## Session facts
+## Use
 
-Agent Trace reads only `SessionEvent` facts from `ctx.sessions`. Immutable
-history and post-commit updates are two views of the same Session authority.
-If the service, exact route permission, Session, read, or subscription is
-unavailable, the Timeline shows no rows and never falls back to another source.
+Open an Agent session in CordisX, then use the session Timeline action. The page
+shows the immutable history available for the active `session.timeline` route
+and follows new committed events. It never creates, edits, resumes, or cancels
+Agent work.
 
 ## Configuration
 
-| Setting              | Default | Values | Meaning                                           |
-| -------------------- | ------- | ------ | ------------------------------------------------- |
-| `timelineWindowSize` | `500`   | 50-500 | Bound the in-memory and rendered Timeline window. |
+`timelineWindowSize` limits the in-memory and rendered event window. The default
+is `500`; accepted values are `50` through `500`. Configuration applies after a
+plugin restart.
 
-Configuration applies on restart so the owning Cordis fiber replaces page
-state cleanly. Page unmount and plugin deactivation own their disposers.
+## Permissions and limits
 
-## Development and packaging
+The plugin requests optional, route-scoped `sessions.get`, `sessions.read`, and
+`sessions.subscribe` access for the exact active session ID. Data is retained
+only for the current runtime and is not transferred externally.
 
-The plugin-owned brand artwork is `assets/agent-trace.png` (256 × 256). The
-module exports the public `CordisXPluginBrandIcon` declaration as `icon`; Host
-plugin lists render its inline PNG without a network request. Run
-`npm run icon:generate` after replacing the asset; `npm run check` verifies that
-the generated declaration still matches. The package includes both the source
-PNG and its compiled declaration. Session actions keep their Host semantic icons.
+If the Host service, exact route permission, session, read operation, or
+subscription is unavailable, the Timeline stays empty and reports the
+unavailable state. It does not fall back to another event source, query mutable
+entity state, or reconstruct missing history.
 
-Distribution remains source-based `explicit-local-v1` at the canonical GitHub
-repository; this private package has no npm publication or release-tag workflow.
-The tracked PNG can be referenced by a commit-pinned raw GitHub URL for catalogs.
+## Troubleshooting
 
-```sh
-npm ci
-npm run check
-```
+- **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.
+- **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
+  code is shown instead of silently switching data sources.
+
+## License
 
-`npm run check` runs typecheck, build, focused tests, and
-`npm pack --dry-run`. `cordisx.plugin.json` is the immutable package manifest.
-The Protocol dependency is pinned to an exact remotely resolvable main commit.
-The entity-backed Host runtime is formally available at CordisX main commit
-`ff9cf8b1ba4e4caffa23abbd767dbba0b8884c8a`; Chatroom's entity-backed consumer
-is at `dc1d672b93e6b6a3a29961561546957d66955a1a`. The package remains private
-until real-App integration verification is complete.
+See [LICENSE](LICENSE) and [legal](legal/) for the package and dependency terms.
+Maintainer setup, checks, packaging, and release instructions are in
+[AGENTS.md](AGENTS.md).
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
@@ -1,75 +1,57 @@
 # CordisX Agent Trace Showcase
 
-插件品牌图为 `assets/agent-trace.png`（256 × 256），通过公开的
-`CordisXPluginBrandIcon` 顶层 `icon` 导出供 Host 插件列表使用，运行时无需请求网络。
-替换图片后运行 `npm run icon:generate`；`npm run check` 会检查生成声明与 PNG
-是否一致。包内同时保留原始 PNG 和编译后的声明，会话操作继续使用 Host 语义图标。
+Agent Trace Showcase 为单个 Agent 会话提供只读 Timeline。它适合查看持久化的
+会话事件、生命周期变化、工具活动、审批，以及会话记录的精确 Entity 定义；插件
+不会获得控制该会话的能力。
 
-分发方式保持为正式 GitHub 仓库上的 `explicit-local-v1` 源码安装；当前私有包没有 npm
-发布或 release-tag 工作流。商店可引用固定 commit 的原始 PNG URL。
+## 安装
 
-Agent Trace Showcase 是独立、只读的 CordisX 插件仓库。插件只负责 Timeline
-业务投影与正文组合；会话 chrome、路由行为、共享控件、无障碍、权限 UI 与
-native lifecycle authority 均由 Host 负责。
+插件 ID：`agent-trace-showcase`。当前版本：`0.1.1`。
 
-Timeline 只消费公开 Agent/Session Runtime 契约。Host 未提供受权限约束的
-Session 服务时，Timeline 会保持空数据并明确显示 unavailable。
+CordisX Community Marketplace feed 不是 trust root，且必须先配置并启用，
+`--source` 才能选择它：
 
-## API checkpoint
-
-Agent/Session Runtime 的 ownership model 如下：
+```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
+```
 
-- Host-private Session authority 唯一拥有 append-only `SessionEvent` log；
-- 插件只通过受权限约束、只读的 `ctx.sessions` 获取不可变 Session snapshot
-  与 post-commit event subscription；
-- `ctx.agents` 负责 create/resume/get，并返回公开 live Agent handle；
-- `ctx.approvals` 负责 approval request 与 decision；
-- 环境组合和 transport binding 均为 Host-private，不改变插件契约、权限或
-  Session 事实。
+若该 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`。
 
-正式契约是 Protocol main commit
-`c96c290697f9e802a68c6d3bb094fd27d8d00d1e` 的
-`@cordisx/protocol/sessions/v1`，以及
-`@cordisx/protocol/entities/v1` 中增量定义的
-`EntityDefinitionBoundSessionEvent`。Timeline 先读取固定 Session snapshot，
-分页读取 immutable watermark，再接续 atomic replay/live subscription；订阅
-终止时会清空视图并报告 terminal code。
+## 使用
 
-对 entity-backed Session，`entity/definition-bound` 是历史定义 identity、
-digest 与 definition bytes 的唯一持久事实。Timeline 只投影该 Session 事件中
-持久化的 binding，绝不查询 `ctx.entities`，也不按最新 local entity revision
-重标历史。
+在 CordisX 中打开一个 Agent 会话，然后使用会话 Timeline 操作。页面读取当前
+`session.timeline` 路由允许访问的不可变历史，并跟随新提交的事件。它不会创建、
+修改、恢复或取消 Agent 工作。
 
-插件不消费替代 event service，也不使用 Host-private import、unsafe cast、
-raw bridge、额外 adapter 或第二 ledger。
+## 配置
 
-v5 runtime manifest 对 `sessions.get`、`sessions.read`、
-`sessions.subscribe` 分别声明 optional capability，并全部绑定到当前
-`session.timeline` 路由的精确 `:sessionId`；空 scope 和 wildcard 均不允许。
+`timelineWindowSize` 限制内存中和页面上保留的事件数量，默认值为 `500`，可选范围
+为 `50` 到 `500`。配置在插件重启后生效。
 
-## Host-owned UI
+## 权限与限制
 
-插件注册结构化 route、page 与 session-header action 描述，并仅用 `cordisx/ui`
-渲染 Timeline 业务正文。它不导入 TDesign，不复制 Host chrome/tab，不查询
-Host-private selector，也不修改 Host DOM。
+插件为当前路由中的精确 Session ID 请求可选的 `sessions.get`、`sessions.read` 和
+`sessions.subscribe` 权限。数据只在当前运行期内使用，不会传输到外部。
 
-## Session 事实
+Host 服务、精确路由权限、Session、读取或订阅不可用时，Timeline 会保持为空并
+显示不可用原因，不会切换到其他事件来源、查询可变 Entity 状态或补造缺失历史。
 
-Agent Trace 只读取 `ctx.sessions` 的 `SessionEvent` 事实。immutable history 与
-post-commit update 是同一 Session authority 的两个视图。service、精确路由
-权限、Session、read 或 subscription 任一不可用时都保持空数据，且不
-fallback 到其他来源。
+## 排错
 
-## 验证与打包
+- **找不到 `0.1.1`：**确认 Marketplace feed 已加入该版本 artifact；`--source`
+  不会注册或修复 feed。
+- **Timeline 为空：**从具体 Agent 会话打开 Timeline，并在插件设置中检查三项
+  Session 权限。
+- **Timeline 停止更新：**重新打开会话路由。插件会显示终止原因，不会静默切换
+  数据源。
 
-```sh
-npm ci
-npm run check
-```
+## 许可证
 
-`npm run check` 包含 typecheck、build、focused tests 与
-`npm pack --dry-run`。Protocol dependency 精确 pin 到可从远端解析的 main
-commit。entity-backed Host Runtime 已在 CordisX main commit
-`ff9cf8b1ba4e4caffa23abbd767dbba0b8884c8a` 正式提供；Chatroom 的 entity-backed
-消费已在 main commit `dc1d672b93e6b6a3a29961561546957d66955a1a`
-落地。真实 App 集成验证闭合前，package 保持 private。
+包与依赖条款见 [LICENSE](LICENSE) 和 [legal](legal/)。维护者的环境、检查、打包与
+发布说明见 [AGENTS.md](AGENTS.md)。
diff --git a/cordisx.plugin.json b/cordisx.plugin.json
@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/schemas/plugin-package.v4.schema.json",
   "schemaVersion": 4,
   "id": "agent-trace-showcase",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "entry": "./dist/index.js",
   "readme": "./README.md",
   "canonicalSource": "https://github.com/cordisx/plugin-agent-trace",

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cordisx/agent-trace-showcase",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "description": "Read-only CordisX Agent Trace Timeline plugin",
   "license": "AGPL-3.0-or-later",