docs: clarify the CodeStable usage model

README.en.md

@@ -24,23 +24,28 @@ proportionate verification + necessary review / owner gates
    ↓ code results + the project's canonical knowledge
 ```
 
-Explicit actions dispatch in the same turn by default; they do not acquire a discussion gate first.
+For team workflows, combine them by responsibility:
 
-Task type determines the engineering method; actual risk determines assurance strength:
+- **Stable coding**: use CodeStable to make task boundaries, assurance, evidence, and project memory explicit.
+- **Team context sharing**: use [Threadshare](https://github.com/team-harness/threadshare) to turn Codex,
+  Claude Code, and other agent conversations into read-only links for teammates and later agents.
+- **Multi-agent coding collaboration**: use [cs-agent](https://github.com/codestable/cs-agent-mcp) to create,
+  invoke, and manage Codex, Claude, and other subagents during implementation, including independent review.
 
-```text
-Execution flow = minimum complete loop + the least assurance required by each unexcluded risk
-```
+The three complement one another: CodeStable does not publish conversations or orchestrate agents, while
+Threadshare and cs-agent do not replace CodeStable's engineering contracts.
 
-Independent review is not a default step. Each risk adds only the assurance directly required by that risk.
+You only need to tell `cs` what you want to accomplish:
 
-Requests to discuss first converge in the current session and hand off in the same turn.
+- **When the request is clear**: it starts directly and delivers the result with enough verification.
+- **When it finds a concrete risk**: it adds only the confirmation, tests, or review needed for that risk; it
+  does not enable the whole workflow.
+- **When you want to discuss first**: it aligns goals, terms, and boundaries with you. It will not change code
+  without execution authorization.
+- **When terminology could cause misunderstanding**: it aligns the meaning as the shared language for this task;
+  otherwise it reuses the project's existing language.
 
-`cs` aligns facts, language, and boundaries; with existing execution authorization it enters `cs-feat`, `cs-issue`, or `cs-epic`. Discussion itself grants no authorization.
-
-Discussion creates no work cursor or transcript. Unresolved discussion is not recoverable across sessions. Advice requests only advise, and an overview writes no files.
-
-A shared language activates only for material ambiguity: ordinary changes reuse existing terms with zero new artifacts, Features align local semantics, and Epics align cross-concept relationships as part of Route Clear.
+Pure discussion, advice, and overview requests write no project files by default. CodeStable does not persist unfinished discussions or guarantee automatic recovery in a later session.
 
 ## Start in 5 Minutes
 

README.md

@@ -24,21 +24,24 @@ feat · issue · refactor · epic
    ↓ 代码结果 + 项目已有的 canonical knowledge
 ```
 
-明确行动默认同轮直转，不先增加讨论 gate。
+团队使用时，可以按职责组合：
 
-任务类型只决定工程方法，实际风险决定保障强度：
+- **稳定编码**：使用 CodeStable 明确任务边界、保障、证据和项目记忆；
+- **团队上下文共享**：推荐使用 [Threadshare](https://github.com/team-harness/threadshare)，把 Codex、Claude Code
+  等 Agent 会话转换成只读链接，供团队成员和后续 Agent 阅读、交接；
+- **多 Agent 编码协同**：推荐使用 [cs-agent](https://github.com/codestable/cs-agent-mcp)，在编码过程中统一创建、
+  调用和管理 Codex、Claude 等子 Agent，也可承担异构独立 review。
 
-```text
-执行流程 = 最小闭环 + 每个未排除风险所要求的最少保障
-```
+三者互补：CodeStable 不负责发布会话或编排 Agent，Threadshare 和 cs-agent 也不替代 CodeStable 的工程契约。
 
-独立 review 不是默认步骤。一个风险只增加与它直接对应的保障，不自动打开整套流程。
+你只需要告诉 `cs` 想完成什么：
 
-先讨论的请求在当前会话收敛后同轮移交。`cs` 对齐事实、术语和边界；已有执行授权时进入 `cs-feat`、`cs-issue` 或 `cs-epic`，讨论本身不产生授权。
+- **需求清楚时**：它直接开始，并用足够的验证交付结果；
+- **遇到具体风险时**：它只增加与风险对应的确认、测试或 review，不自动启用整套流程；
+- **你想先讨论时**：它先和你对齐目标、术语和边界；未经明确授权，不会修改代码；
+- **名词可能影响理解时**：它先对齐含义，形成当前任务的共享语言；没有歧义时，直接沿用项目已有说法。
 
-讨论不创建 work 游标或 transcript，未收敛讨论不承诺跨会话恢复。咨询请求只给建议，体系导览不写文件。
-
-共享语言按歧义触发：普通改动沿用已有术语时零新增产物；Feature 对齐局部语义，Epic 对齐跨概念关系并纳入 Route Clear。
+纯讨论、咨询和体系导览默认不写项目文件。还没讨论清楚的内容，CodeStable 不会专门保存，也不保证下次会话自动恢复。
 
 ## 5 分钟开始
 

tests/test_v2_documentation_contract.py

@@ -179,8 +179,8 @@ def test_readme_is_a_compact_first_evaluator_entry() -> None:
         "轻量 skill 契约",
         "不编排 Agent 团队",
         "不为项目建立第二套文档系统",
-        "明确行动默认同轮直转",
-        "未收敛讨论不承诺跨会话恢复",
+        "你只需要告诉 `cs` 想完成什么",
+        "还没讨论清楚的内容",
         "直接执行 / 当前会话讨论 / 给出建议",
         "thin harness, thick context",
         "证据先于结论",
@@ -194,8 +194,8 @@ def test_readme_is_a_compact_first_evaluator_entry() -> None:
         "lightweight skill contracts",
         "does not orchestrate agent teams",
         "does not create a second documentation system",
-        "Explicit actions dispatch in the same turn by default",
-        "Unresolved discussion is not recoverable across sessions",
+        "You only need to tell `cs` what you want to accomplish",
+        "does not persist unfinished discussions",
         "execute directly / discuss in this session / advise",
         "thin harness, thick context",
         "Evidence before conclusions",
@@ -451,9 +451,10 @@ def test_cs_session_discussion_and_handoff_contract_is_bilingual() -> None:
     en_readme = _read("README.en.md")
     zh_catalog = _read("SKILL_CATALOG.md")
     en_catalog = _read("SKILL_CATALOG.en.md")
-    assert "先讨论的请求在当前会话收敛后同轮移交" in zh_readme
+    assert "未经明确授权，不会修改代码" in zh_readme
     assert "先讨论的请求在当前会话收敛后同轮移交" in zh_catalog
-    assert "Requests to discuss first converge in the current session and hand off in the same turn" in en_readme
+    assert "It will not change code" in en_readme
+    assert "without execution authorization" in en_readme
     assert "Requests to discuss first converge in the current session and hand off in the same turn" in en_catalog
     assert "稳定资产由 owning skill 按 canonical 归宿毕业" in zh_catalog
     assert "stable assets graduate through the owning skill into their canonical homes" in en_catalog
@@ -494,14 +495,31 @@ def test_issue_diagnosis_and_authorized_fix_contract_is_bilingual() -> None:
 
 
 def test_minimum_sufficient_assurance_contract_is_bilingual() -> None:
+    zh_readme = _read("README.md")
+    en_readme = _read("README.en.md")
+    for anchor in (
+        "需求清楚时",
+        "直接开始，并用足够的验证交付结果",
+        "遇到具体风险时",
+        "只增加与风险对应的确认、测试或 review",
+        "不自动启用整套流程",
+    ):
+        assert _contains_contract(zh_readme, anchor)
+    for anchor in (
+        "When the request is clear",
+        "delivers the result with enough verification",
+        "When it finds a concrete risk",
+        "only the confirmation, tests, or review needed for that risk",
+        "does not enable the whole workflow",
+    ):
+        assert _contains_contract(en_readme, anchor)
+
     zh_docs = (
-        _read("README.md"),
         _read("WORKFLOW.md"),
         _read("SKILL_CATALOG.md"),
         _read("docs/why-codestable.md"),
     )
     en_docs = (
-        _read("README.en.md"),
         _read("WORKFLOW.en.md"),
         _read("SKILL_CATALOG.en.md"),
         _read("docs/why-codestable.en.md"),