From be42a3c01eb723cae46106051936260cb248bfd0 Mon Sep 17 00:00:00 2001 From: veil-chow-fyaic <247294299+veil-chow-fyaic@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:30:48 +0800 Subject: [PATCH] docs: lead with user outcomes and clarify first-use paths --- README.md | 115 ++++++++++-------- README.zh-CN.md | 94 ++++++++------ .../community-followup-2026-09-07.md | 54 ++++++++ 3 files changed, 173 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 21dcb80..0269afc 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@
@@ -19,20 +18,23 @@ 简体中文 -One conversation changes the API. Another is still building against the old contract. -You shouldn't have to notice, switch chats, and explain the change again. -You don't need two different products: two sessions of the same agent can collaborate. +You approved a decision in one chat. Another chat is still working from the old +version. ThreadMesh helps related agent sessions share useful changes without +making you explain them again—even when both sessions use the same product. -**You choose which sessions join. The models choose when a message is useful.** -The workspace supplies discovery, advisory messages, a persistent inbox and portable -checkpoints—not a new model or shared chat history. The optional Codex desktop -skill instead uses **Codex's native task tools**; it does not add that transport. +**You choose the collaborators. The models decide what is worth sharing.** -**Doesn't Codex already do this? Yes, on the tested host.** If its native task -tools meet your needs, use them directly. The skill adds reusable collaboration -guidance; the workspace adds coordination for supported integrations. We have -not proved the skill outperforms native Codex alone. -[What is native, what we add, and when not to install →](docs/00-overview/native-capabilities-and-value.md) +| The repeated chore | What ThreadMesh offers | +|---|---| +| “Tell the other session what changed.” | Selected peer goals and advisory handoffs; a model chooses whether to contact a peer. | +| “Remember what we already agreed.” | Each receiver keeps its own task context and checks advice against earlier decisions. | +| “Was it received—or actually done?” | Workspace inbox/disposition records plus examples that verify the receiver's own artifact, not just delivery. | + +Two ways to use it: an optional **Codex desktop skill** over native task tools, +or a **local workspace** with a persistent inbox, supported harness adapters +and explicit portable checkpoints. These are different integration paths, not +one universal desktop connector. Codex supplies the skill route's transport. +[What we add—and when native Codex is enough →](docs/00-overview/native-capabilities-and-value.md)
@@ -41,44 +43,56 @@ not proved the skill outperforms native Codex alone.
## A real handoff without the copy-paste
-[Read the actual desktop exchange and B's own diff →](docs/evidence/codex-native-2026-09-07/README.md)
-Retained native records, with busy/stop checks; not a screenshot or reenactment.
-The separate installed-package example below is also retained.
+**A knows the new product facts. B remembers your earlier website decision.**
+
+In one controlled Codex desktop run, both tasks completed their initial work
+before adopting the skill. B already knew to keep the signup button unchanged.
+After explicit pairing, the only business request went to A:
-**Two Codex sessions. One remembers your earlier decision; the other changes the
-product facts. You don't relay the change.**
+> Rename the product to Member Portal and limit the free plan to five projects.
+> Use US spelling. Keep the paid-plan price unchanged. Update the approved product facts.
-In a real installed-package run, the website session first volunteered its
-dependency. The brand session then chose to send the relevant update. After
-that actual message, the runner continued the **same native website session**;
-its model edited the landing copy itself.
+No “send this to B.” A chose to check B's status and send the relevant facts.
+**Original B then continued and edited its own website copy.** The manager did
+not relay the change, resume B manually or write B's file.
| Website copy | Before | After |
|---|---|---|
| Product and spelling | Organise work with Team Hub | Organize work with Member Portal |
-| Free allowance | Unlimited free projects | Free tier includes up to 5 projects |
+| Free allowance | Unlimited free projects | Up to five projects on the free tier |
| Earlier button decision | Create my workspace | **Unchanged** |
| Paid price | $12/month | **Unchanged** |
-These compact descriptions summarize the checked artifact, not a screenshot.
-Each model received an ordinary task with generic opt-in collaboration guidance,
-not an instruction naming the recipient or requiring a send. The runner checks
-the receiver's own edit, complete business meaning and retained constraints.
-
-Two maintainer runs passed from installed packages: about **273 seconds** with
-the default 300-second limit, and **184 seconds** in an earlier extended-budget
-diagnostic. Neither changed the configured model or account. These are two
-observations, not a reliability rate or a time-to-success promise.
-[Exact prompts, artifacts and timing →](docs/09-reviews/2026-09-07-codex-first-use-release.md)
+The ordinary request to B's completed result took about **49 seconds, excluding
+setup**. In separate controls, A held its advice while B was busy and made no
+further send after collaboration was stopped.
+[Actual messages, B's diff and audit →](docs/evidence/codex-native-2026-09-07/README.md)
-**The boundary:** these are two new disposable Codex sessions. The runner
-triggers continuation after delivery; this is not native desktop background wake
-or attachment to old chats. Earlier [Codex connection failures](docs/09-reviews/2026-09-07-codex-first-use-candidate.md)
-and [cross-product business failures](docs/09-reviews/2026-09-05-workspace-awareness.md)
-remain recorded. Delivered still does not mean done correctly.
+This is one maintainer-operated pair with prior context, not a speed guarantee
+or independent-user onboarding result. Codex provided native messaging and
+continuation; the skill provided guidance. The table summarizes checked files,
+not a screenshot. Simultaneous typing races and plugin hot-loading remain unverified.
## Try it
+| Your starting point | Choose this path |
+|---|---|
+| I use existing Codex desktop tasks | [Native-task workflow](#want-to-connect-your-existing-desktop-tasks): no Node/MCP/hook setup, but explicit pairing and available host tools are required. |
+| I want a self-contained real example | [Codex package example](#already-use-codex-keep-your-account): one terminal, two new disposable sessions, existing account and quota. |
+| I want to connect my project sessions | [Workspace guide](docs/06-guides/first-workspace.md#advanced-connect-your-own-project-sessions): more setup; persistent inbox and supported harness integration. |
+
+### Want to connect your existing desktop tasks?
+
+[Follow the native-task guide](docs/06-guides/codex-native-tasks.md) to give each
+chosen task the workflow and its peer's reference, authorize a narrow scope,
+then work normally. No terminal setup is needed for that route.
+
+**Experimental:** the successful case used manager-supplied task references and
+a local skill path. Novice pair selection, remote-link retrieval and normal
+plugin onboarding remain open. The skill cannot add absent host tools or enforce
+privacy and race-free sending. If native Codex already meets your needs, use it
+directly; no measured advantage over native-only use is claimed.
+
### Already use Codex? Keep your account
Requires **Node 22+** and a working, authenticated Codex installation.
@@ -104,16 +118,11 @@ Omit `--live` to read instructions without a model call. Processes stop at the
end; private results remain for inspection.
[Permissions, results and failures →](docs/06-guides/first-workspace.md)
-### Want to connect your existing desktop tasks?
-
-There is an [experimental no-terminal workflow](docs/06-guides/codex-native-tasks.md)
-using a skill and Codex's already-exposed native task tools—no Node, MCP or hook
-setup for that route. **One controlled desktop pair passed:** both tasks had
-completed prior work before activation; A chose to send advice and original B
-edited its own copy, preserving earlier decisions. Busy-target and stop checks
-also passed. [Native evidence and setup limits →](docs/09-reviews/2026-09-07-native-desktop-acceptance.md)
-This is not plugin hot-loading or independent-user onboarding. The skill cannot
-create missing host tools, enforce privacy boundaries or eliminate input races.
+Separate from the desktop case above, this installed-package Codex example
+passed in about **273 seconds** under its default limit. An earlier diagnostic
+passed in 184 seconds with an extended budget. The runner continues its own
+receiver after actual delivery; it does not attach existing desktop chats.
+[Packaged-run evidence and retained failures →](docs/09-reviews/2026-09-07-codex-first-use-release.md)
### Already use Pi instead?
@@ -142,7 +151,8 @@ they are not evidence of model initiative. For your own projects, use the
| Harness | How it connects | Automatic idle follow-up |
|---|---|---|
-| **Codex** | `try`: native App Server pair; project launcher: scoped MCP + hooks | `try` runner continues its own idle receiver after delivery; no general native idle wake |
+| **Codex desktop** | Optional skill over host-provided native task tools | One controlled pair passed; Codex supplies continuation; availability varies by host |
+| **Codex package / projects** | `try`: native App Server pair; project launcher: scoped MCP + hooks | `try` runner continues its own receiver; not arbitrary old-chat attachment |
| **Pi** | Native extension; four tools and turn-start context | Opt-in `--wake-idle`; busy-turn guard, not universal typing-race proof |
| **Kimi Code** | Project MCP configuration; other servers retained | No |
| **DeepSeek Harness** | Official `dsh` MCP plugin via a Cordis patch | Not claimed |
@@ -169,6 +179,9 @@ These are practical uses, not a promise that every scenario succeeds.
### Continue from a saved checkpoint
+For an already configured workspace—not the disposable `try` sample—run from
+its directory, or supply `--workspace /path/to/your/room`:
+
```sh
npx threadmesh status
npx threadmesh continue backend --agent kimi --name recovery
@@ -184,13 +197,15 @@ recovery is still unverified.
## Your sessions stay yours
-Joining shares published goals and advice, not all private chats. Inbox reads
+In the workspace route, joining shares published goals and advice, not all private chats. Inbox reads
do not consume messages; acceptance does not prove completion. Pi idle wake is
opt-in. Use `npx threadmesh status` to inspect or `npx threadmesh mute client` to mute.
This is an **experimental, same-owner local workspace**, not a multi-tenant
security boundary. It does not automatically attach arbitrary old tabs, wake
every agent product or guarantee correct work. Host tool permissions still apply.
+The desktop skill uses Codex's native history and model-followed rules instead;
+workspace inbox and mute commands do not control that separate route.
[Safety model](docs/04-safety/threat-model.md) · [Security policy](SECURITY.md)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index a716f1a..3d46a1e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -7,7 +7,6 @@
@@ -39,13 +41,16 @@ Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时
## 一次不用你转述的真实协作
-[查看实际桌面消息与 B 自己的修改 →](docs/zh-CN/native-evidence.md)
-保留的原生记录,含忙碌/停止检查;不是截图或重演。下面另保留安装包案例。
+**A 掌握新的产品事实,B 记着你之前的网站约定。**
+
+一次受控 Codex 桌面实测中,两个任务先完成原工作,再启用 Skill。
+B 早已知道按钮名称不能改。明确配对后,只向 A 提出普通业务修改,意思是:
-**两个 Codex session:一个记着你之前的约定,另一个修改产品事实。你不用转述变化。**
+> 产品更名为 Member Portal,免费方案最多五个项目,使用美式拼写。
+> 付费价格不变,更新批准的产品事实。
-在安装包真实运行中,网站 session 先自主说明了依赖,品牌 session 随后自行决定发送相关变化。
-实际收到消息后,运行器续接**同一个原生网站 session**,由它自己的模型修改注册页文案。
+没有要求“把这条消息发给 B”。A 自行检查 B 的状态、发送相关事实,
+**原来的 B 接着自己修改了网站文案。** 管理任务没有转述变化、手动续跑 B 或代写文件。
| 网站内容 | 修改前 | 修改后 |
|---|---|---|
@@ -54,23 +59,32 @@ Skill 比原生 Codex 更有效。[哪些是原生、我们增加什么、何时
| 之前约定的按钮 | Create my workspace | **保持不变** |
| 付费价格 | $12/月 | **保持不变** |
-上表是已验收文件的紧凑摘要,不是界面截图。每个模型收到普通业务任务和通用协作提示,
-没有在任务里指定接收者或要求必须发消息。验收检查接收方自己修改文件、完整业务含义,
-以及此前约定是否保留。
-
-安装包上保留了两次维护者通过记录:默认 300 秒上限内约 **273 秒**完成;
-较早一次扩展时间预算的诊断约 **184 秒**完成。两次都没有改用其他模型或账户。
-这是两次观察,不是可靠性统计,也不保证固定时间成功。
-[真实任务、文件与时间线 →](docs/09-reviews/2026-09-07-codex-first-use-release.md)
+普通业务请求到 B 完成约 **49 秒,不含设置时间**。另做对照时,B 忙碌则 A 暂缓发送;
+停止协作后再修改产品,A 也没有继续发消息。
+[实际消息、B 的 diff 与审计 →](docs/zh-CN/native-evidence.md)
-**边界明确:** 这里是两个新的临时 Codex session,由运行器在实际投递后触发续接;
-不是原生桌面后台唤醒,也不是接入已有聊天。
-此前的 [Codex 连接失败](docs/09-reviews/2026-09-07-codex-first-use-candidate.md)
-和[跨产品业务失败](docs/09-reviews/2026-09-05-workspace-awareness.md)继续保留。
-消息送达仍然不等于工作做对。
+这是一组维护者操作、保留原上下文的专用任务,不是速度保证或独立用户上手结果。
+原生消息与续跑来自 Codex,Skill 提供协作规则。上表概括已核验文件,不是界面截图。
+同时输入的竞争和插件热加载仍未验证。
## 开始体验
+| 你现在想做什么 | 选择这条路径 |
+|---|---|
+| 连接已有 Codex 桌面任务 | [原生任务流程](#想连接已有的桌面任务):不用配置 Node/MCP/hook,但需明确配对且宿主已有工具。 |
+| 先跑一个自包含的真实例子 | [Codex 安装包案例](#已经在用-codex沿用你的账户):一个终端、两个新临时任务、沿用账户和额度。 |
+| 接入自己项目里的 session | [Workspace 指南](docs/zh-CN/first-workspace.md#进阶两个终端接入自己的项目):设置更多,提供持久收件箱和已支持的 harness 接入。 |
+
+### 想连接已有的桌面任务?
+
+按[原生任务指南](docs/zh-CN/codex-native-tasks.md),在选中的任务里提供工作流和对方引用,
+授权限定的协作范围,然后正常工作。这条路径不需要终端设置。
+
+**实验入口:** 成功案例由管理任务提供引用和本地 Skill 路径;普通用户如何选择任务、
+远程链接读取和常规插件上手仍有缺口。Skill 不能补出缺失的宿主工具,也不能强制
+保证隐私隔离或无竞争发送。如果原生 Codex 已满足需求,直接使用即可;
+目前不声称比原生用法更有效。
+
### 已经在用 Codex?沿用你的账户
需要 **Node 22+**,以及已经登录、可以正常使用的 Codex。
@@ -91,15 +105,9 @@ macOS 下可以自动选择比 PATH 版本更新的桌面自带运行时,不
不带 `--live` 只显示说明,不调用模型。结束后停止进程,私有结果保留供检查。
[权限、结果和失败处理 →](docs/zh-CN/first-workspace.md)
-### 想连接已有的桌面任务?
-
-另有[实验性无终端工作流](docs/zh-CN/codex-native-tasks.md),通过 skill 使用 Codex
-已经提供的原生任务工具;这条路径不用配置 Node、MCP 或 hook。
-**一组受控桌面双任务已通过实测:** 两边先完成原任务,再启用协作;A 自行发出建议,
-原来的 B 自己改对文案,并保留之前的约定。忙碌时不发送、停止后不再发送也通过。
-[原生证据与设置边界 →](docs/09-reviews/2026-09-07-native-desktop-acceptance.md)
-这不是插件热加载或独立新用户上手验收。Skill 不能补出宿主缺失的工具,也不能强制
-保证隐私边界或消除用户输入竞争。
+与上方桌面实测分开,这个 Codex 安装包例子在默认上限内约 **273 秒**通过;
+更早一次扩展时间预算的诊断约 184 秒通过。运行器在实际投递后续接自己的接收方,
+不是接入已有桌面聊天。[安装包证据与保留的失败 →](docs/09-reviews/2026-09-07-codex-first-use-release.md)
### 已经在用 Pi?
@@ -127,7 +135,8 @@ npx threadmesh preview preferences
| Harness | 接入方式 | 空闲时自动续接 |
|---|---|---|
-| **Codex** | `try` 使用原生 App Server 双 session;项目 launcher 使用限定范围的 MCP 与 hook | `try` 在投递后由运行器续接自身空闲接收方;不是通用原生空闲唤醒 |
+| **Codex 桌面** | 宿主原生任务工具之上的可选 Skill | 一组受控双任务通过;Codex 提供续跑,工具可用性取决于宿主 |
+| **Codex 安装包 / 项目** | `try` 使用 App Server 双 session;项目 launcher 使用限定范围的 MCP 与 hook | `try` 运行器续接自己的接收方;不是任意旧聊天接入 |
| **Pi** | 原生扩展,四个工具与任务起始上下文 | 显式 `--wake-idle`;有忙碌保护,但不是所有输入竞争都已实测 |
| **Kimi Code** | 项目 MCP 配置,保留其他 server | 未提供 |
| **DeepSeek Harness** | 官方 `dsh` 的 Cordis MCP 插件 | 未声称支持 |
@@ -154,6 +163,9 @@ Pi→Kimi 成功记录采用约束更强的 adapter 路径。
### 从已保存的 checkpoint 继续
+仅用于已经配置好的 workspace,不是 `try` 的临时样例。在该目录执行,
+或显式提供 `--workspace /path/to/your/room`:
+
```sh
npx threadmesh status
npx threadmesh continue backend --agent kimi --name recovery
@@ -167,12 +179,14 @@ npx threadmesh continue backend --agent kimi --name recovery
## Session 仍由你掌控
-加入只共享公布的目标和建议,不扫描全部私聊。读收件箱不会消耗消息,接受建议
+在 workspace 路径,加入只共享公布的目标和建议,不扫描全部私聊。读收件箱不会消耗消息,接受建议
不等于任务完成。Pi 的空闲续接需要明确开启。使用 `npx threadmesh status` 查看,
或用 `npx threadmesh mute client` 静音。
当前是**同一所有者的本地实验版**,不是多租户安全边界。它不会自动接入任意旧 tab、
唤醒所有 Agent 产品,也不保证工作一定正确。宿主原有的工具权限仍然适用。
+桌面 Skill 则使用 Codex 原生历史和模型遵循的规则;workspace 的收件箱与静音命令
+不能控制这条独立路径。
[安全模型](docs/04-safety/threat-model.md) · [安全报告](SECURITY.md)
diff --git a/docs/10-planning/community-followup-2026-09-07.md b/docs/10-planning/community-followup-2026-09-07.md
index 735c875..bde83bd 100644
--- a/docs/10-planning/community-followup-2026-09-07.md
+++ b/docs/10-planning/community-followup-2026-09-07.md
@@ -67,6 +67,60 @@ goal because the smaller new-session example is easier to validate.
## Deferred reply and execution discipline
+### Latest review and reply gate
+
+Rechecked #158 and recent repository comments on September 7. The latest external
+comment remains `hlinor-systems` at 08:12:18 UTC, linked above; no newer demand
+was found. Do not describe a fresh inspection as a new comment. #158 and #79
+remain open.
+
+The current README now leads with user chores, one complete native desktop case
+and three distinct entry paths. It separates the 49-second desktop observation
+from the 273-second packaged example and removes the global Node badge: Node is
+a package requirement, not a requirement of the native skill workflow. Native
+attribution and the absence of measured incremental benefit remain explicit.
+
+**Decision: draft only; do not post this turn.** The three requested maintainer
+example/progress/receiver-evidence improvements have shipped. Another README
+rearrangement is not a new functional release. The next useful increment is the
+remaining Codex desktop pairing/activation friction: test a publicly retrievable
+workflow with supported task references, without maintainer-local paths or manual
+ID hunting. Record the first failure and actual setup steps. After that bounded
+increment, recheck the comment and send one consolidated update; do not wait for
+every adapter, perfect reliability or a marketing video. No automatic posting or
+scheduled follow-up is configured by this document.
+
+### Proposed reply to #158 — not sent
+
+> Thank you, Andrei. We followed the three concrete priorities in your report.
+>
+> [v0.1.0-alpha.3](https://github.com/fyaic/threadmesh/releases/tag/v0.1.0-alpha.3)
+> now defaults to a self-contained Codex → Codex example using the existing login
+> and model. `threadmesh try --live` prepares the sample and runs both sessions;
+> no custom harness, application fixture, Pi installation or second subscription
+> is required. The [install/run guide](https://github.com/fyaic/threadmesh/blob/main/docs/06-guides/first-workspace.md)
+> shows installation progress and explains quota, runtime and timeout failures.
+> We do not bypass exhausted quota or silently switch products.
+>
+> The installed-package default run completed in 272.604 seconds within its
+> 300-second cap. The original receiver made its own checked edit, preserving
+> the earlier button decision and paid price. We retained the failed attempts
+> as well as the [passing evidence](https://github.com/fyaic/threadmesh/blob/main/docs/09-reviews/2026-09-07-codex-first-use-release.md).
+>
+> Separately, a controlled desktop pair with completed prior context produced
+> native advice and the original receiver's own edit; the [actual exchange and diff](https://github.com/fyaic/threadmesh/blob/main/docs/evidence/codex-native-2026-09-07/README.md)
+> are public. Codex supplies that route's native transport. Its synthetic busy
+> and stop checks are not proof of race-free delivery or general desktop onboarding.
+>
+> These are maintainer results, not an independent live pass or a reliability
+> rate. We are keeping this issue open for the remaining onboarding gaps. No need
+> to retry with exhausted quota or share private transcripts. Your report changed
+> the first-use path and what we require before calling a handoff useful.
+
+Before posting, add only the actual outcome of the next entry-path increment,
+recheck release links and claims, and remove anything superseded by a new comment.
+Do not copy an unverified planned result into this draft.
+
Subsequent native desktop evidence is now retained as [actual excerpts and diff](../evidence/codex-native-2026-09-07/README.md).
That controlled prior-context pair passed; it is not this contributor's independent
live result. The [native-value correction](../00-overview/native-capabilities-and-value.md)