diff --git a/AGENTS.md b/AGENTS.md
index 04915a5..13e11e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,8 @@
 Cross-platform support is required (Windows, macOS, Linux).
 Architecture, directory routing, and template ownership live in
 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Adding support for a new Coding Agent host starts with
+[docs/adapters/contributing-new-coding-agent.md](docs/adapters/contributing-new-coding-agent.md).
 
 ## Plan & Spec
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0aab8c3..3200282 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,6 +17,8 @@ it and agree that it may be distributed under the repository's [MIT License](LIC
 - Read [Architecture Principles](docs/ARCHITECTURE.md) and the root
   [agent instructions](AGENTS.md) before changing ownership boundaries or
   runtime behavior.
+- Follow [Contributing a New Coding Agent Host](docs/adapters/contributing-new-coding-agent.md)
+  before adding or widening host support.
 
 Small, focused fixes can go directly to a pull request. Open an issue first when
 the change affects public behavior, schemas, report contracts, packaging,
@@ -67,6 +69,11 @@ Executable behavior, host adapters, models, hooks, packaging, and report
 contracts have additional owner and evidence requirements. Follow the complete
 extensibility matrix instead of adding a parallel implementation.
 
+For a Coding Agent host, use the dedicated
+[host contribution guide](docs/adapters/contributing-new-coding-agent.md). It
+separates shell, configured-asset, session, output, and packaging claims so a
+host can land partial support without overstating its coverage.
+
 ## Plan the Change
 
 For non-trivial behavior, hook, Skill, template, adapter, report, or review-flow
diff --git a/README.md b/README.md
index 598e96d..b86c702 100644
--- a/README.md
+++ b/README.md
@@ -351,7 +351,7 @@ smallest surface that matches the improvement you want to make:
 | --- | --- | --- |
 | Workflow guidance and engineering practices | [`skills/`](skills/) or [`references/`](references/) | Add sourced guidance for a language, framework, review pattern, or recurring agent workflow. |
 | Review models and executable analysis | [`models/`](models/) or [`scripts/`](scripts/) | Add an evidence-backed review lens, detector, or agent-friendly analysis command with fixtures and tests. |
-| Delivery controls and host support | [`hooks/`](hooks/) or the [host adapter matrix](docs/adapters/README.md) | Add a narrow lifecycle check or document and validate evidence support for another coding-agent host. |
+| Delivery controls and host support | [`hooks/`](hooks/) or the [new Coding Agent guide](docs/adapters/contributing-new-coding-agent.md) | Add a narrow lifecycle check or document and validate evidence support for another Coding Agent host. |
 | Reports and visual language | [`templates/reporting/`](templates/reporting/) or [`templates/style/`](templates/style/) | Add a report mode, reusable reporting contract, or directive-only visual style with validation evidence. |
 | Examples and operating models | [`case-studies/`](case-studies/) | Share a redacted, evidence-bounded example of how a team applies agent review and delivery practices. |
 
@@ -361,9 +361,12 @@ To get started:
    owner and understand its contract.
 2. Follow the [contribution guide](CONTRIBUTING.md) to set up the project and
    scope the change.
-3. Add tests, fixtures, or preview evidence when the contribution changes
+3. For host support, follow the
+   [new Coding Agent contribution guide](docs/adapters/contributing-new-coding-agent.md)
+   and update the [host adapter matrix](docs/adapters/README.md).
+4. Add tests, fixtures, or preview evidence when the contribution changes
    runtime behavior or rendered output.
-4. Open a focused pull request that explains what changed, why, and how it was
+5. Open a focused pull request that explains what changed, why, and how it was
    validated.
 
 Not sure where an idea belongs? [Open an issue](https://github.com/QoderAI/better-harness/issues)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index cc19e34..33d3406 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -338,7 +338,7 @@ Canvas 预览需要已安装的 Qoder 运行时，或显式指定 `--sdk-media`/
 | --- | --- | --- |
 | 工作流指导与工程实践 | [`skills/`](skills/) 或 [`references/`](references/) | 为某种语言、框架、审查模式或重复出现的智能体工作流添加有来源支撑的指南。 |
 | 审查模型与可执行分析 | [`models/`](models/) 或 [`scripts/`](scripts/) | 添加由证据支持的审查视角、检测器，或带 fixture 和测试的智能体友好分析命令。 |
-| 交付控制与宿主支持 | [`hooks/`](hooks/) 或[宿主适配器矩阵](docs/adapters/README.md) | 添加范围明确的生命周期检查，或记录并验证另一种编码智能体宿主的证据支持情况。 |
+| 交付控制与宿主支持 | [`hooks/`](hooks/) 或[新增 Coding Agent 指南](docs/adapters/contributing-new-coding-agent.md) | 添加范围明确的生命周期检查，或记录并验证另一种 Coding Agent 宿主的证据支持情况。 |
 | 报告与视觉语言 | [`templates/reporting/`](templates/reporting/) 或 [`templates/style/`](templates/style/) | 添加报告模式、可复用的报告契约，或带验证证据的纯指令式视觉样式。 |
 | 示例与运行模型 | [`case-studies/`](case-studies/) | 分享经过脱敏且以证据为边界的示例，展示团队如何应用智能体审查与交付实践。 |
 
@@ -346,8 +346,10 @@ Canvas 预览需要已安装的 Qoder 运行时，或显式指定 `--sdk-media`/
 
 1. 阅读[社区扩展地图](docs/community.md)，找到规范的归属位置并了解相应契约。
 2. 按照[贡献指南](CONTRIBUTING.md)设置项目并确定变更范围。
-3. 当贡献会改变运行时行为或渲染输出时，添加测试、fixture 或预览证据。
-4. 提交一个聚焦的 Pull Request，说明改了什么、为什么修改以及如何验证。
+3. 如需新增宿主支持，请遵循[新增 Coding Agent 贡献指南](docs/adapters/contributing-new-coding-agent.md)，
+   并更新[宿主适配器矩阵](docs/adapters/README.md)。
+4. 当贡献会改变运行时行为或渲染输出时，添加测试、fixture 或预览证据。
+5. 提交一个聚焦的 Pull Request，说明改了什么、为什么修改以及如何验证。
 
 不确定某个想法应该放在哪里？在创建新的顶层功能区，或修改公共报告、schema、打包或兼容性契约之前，
 请先[创建 issue](https://github.com/QoderAI/better-harness/issues)。
diff --git a/docs/adapters/README.md b/docs/adapters/README.md
index cbc48d5..ee6884d 100644
--- a/docs/adapters/README.md
+++ b/docs/adapters/README.md
@@ -5,6 +5,12 @@ host boundaries. Do not create `docs/adapters/claude-code.md`,
 `docs/adapters/codex.md`, `docs/adapters/qoder.md`, `docs/adapters/cursor.md`,
 or `docs/adapters/qwen.md` by default.
 
+Adding another host? Follow
+[Contributing a New Coding Agent Host](contributing-new-coding-agent.md) before
+editing the matrix. The guide separates shell, configured-asset, session,
+output, and packaging claims and links reviewed Qwen Code and GitHub Copilot
+pull requests as worked examples.
+
 Host differences enter only this matrix, capability-local configured-asset
 providers, real session-evidence adapters, and output modes. Canonical product
 judgment stays in `skills/`, `models/`, `references/`, `templates/`, and
diff --git a/docs/adapters/contributing-new-coding-agent.md b/docs/adapters/contributing-new-coding-agent.md
new file mode 100644
index 0000000..da682c0
--- /dev/null
+++ b/docs/adapters/contributing-new-coding-agent.md
@@ -0,0 +1,233 @@
+# Contributing a New Coding Agent Host
+
+Adding a Coding Agent is not one manifest or one transcript parser. It is a set
+of independently evidenced support claims: native discovery, configured assets,
+session evidence, shared workflow activation, output routing, and packaging.
+Implement only the slices the host can support, and mark every other slice as
+partial or unavailable.
+
+This guide is the canonical contribution workflow for a new host. Before editing,
+read the repository [agent instructions](../../AGENTS.md),
+[contribution guide](../../CONTRIBUTING.md),
+[architecture principles](../ARCHITECTURE.md),
+[directory ownership ADR](../adrs/directory-structure.md),
+[community extension map](../community.md), and
+[host adapter matrix](README.md). Current repository contracts take precedence
+over the worked pull requests at the end of this guide.
+
+## 1. Define the Support Claim
+
+Start with a dated spec under `docs/specs/` as required by `AGENTS.md`. Give each
+claimed slice a stable acceptance id and an evidence route. Use
+`[NEEDS CLARIFICATION: ...]` instead of guessing a host contract.
+
+| Slice | Decide explicitly | Canonical owner | Minimum evidence |
+| --- | --- | --- | --- |
+| Native contract | Host/version, primary source, supported lifecycle | Spec and PR evidence | Versioned official docs or host source |
+| Shell and discovery | Native manifest, source-local shell, generated shell, or none | Thin host metadata root; generated artifacts under `scripts/packaging/` | Native install/link/discovery smoke or unavailable note |
+| Configured assets | Available, partial, or unavailable scopes | `scripts/agent-customize/providers/<host>.mjs` | Sanitized fixtures plus bounded real-host inventory smoke |
+| Session evidence | Available, partial, or unavailable fields/events | `scripts/session-analysis/platforms/<host>.mjs` | Deterministic fixtures plus workspace-qualified source/facts smoke |
+| Shared registration | Which public commands accept the host | Capability-owned registries and CLIs | Help, unknown-host, delegation, and bundle tests |
+| Output | Existing Canvas, HTML, Markdown, or a justified new mode | `templates/reporting/` and report routing | Validated render for the claimed mode |
+| Packaging | npm metadata root, runtime bundle, source-only, or none | `package.json` and `scripts/npm-package/` | `npm run pack:verify` when shipped files change |
+| Documentation | Positioning, paths, coverage, smoke, limitations | [host adapter matrix](README.md) and capability references | Link checks and commands matching observed behavior |
+
+A shell does not prove configured-asset or session support. A session parser does
+not prove the Skill is natively discoverable. Do not register one slice merely
+to make another slice appear complete.
+
+## 2. Verify the Native Host Contract
+
+Do not derive a new host contract by renaming another adapter. Record the host
+version and primary evidence in the spec or pull request, then verify the parts
+that affect the proposed support:
+
+- the native manifest filename, schema, discovery order, install/link command,
+  and version rules;
+- configuration, runtime, cache, and session roots, including environment and
+  CLI override precedence;
+- workspace identity and path normalization for spaces, Unicode, punctuation,
+  Windows drive letters, case differences, symlinks, and case-insensitive file
+  systems;
+- trust, extension enablement, configuration precedence, and inline settings
+  that can add Skills, hooks, MCP servers, rules, or commands;
+- session event shape, call/result correlation, terminal statuses, unknown
+  event handling, compaction, subagent, permission, and usage fields;
+- privacy boundaries: which fields are required for evidence, which may contain
+  credentials or user content, and which must never leave the local machine.
+
+Use real host data only for a bounded local smoke. Commit deterministic,
+synthetic, and redacted fixtures; never commit raw transcripts, prompts,
+credentials, tokens, or machine-specific absolute paths.
+
+## 3. Keep the Host Shell Thin
+
+Add a host metadata root only when the native host needs one. The shell may own
+install and discovery metadata and pointers to canonical root Skills. It must
+not copy product judgment, scoring, evidence rules, or report contracts out of
+`skills/`, `models/`, `references/`, `templates/`, or capability-owned scripts.
+
+When the shell ships in the public package, align its version with the package,
+add it to the package whitelist and verifier, and prove native discovery with
+the actual host CLI. Generated host artifacts remain validation/install output;
+their canonical source belongs under `scripts/packaging/` after the matrix split
+triggers justify a builder.
+
+## 4. Add Configured-Asset Evidence
+
+A provider under `scripts/agent-customize/providers/` should:
+
+- keep Plugin, user, project, and inherited scopes distinct;
+- follow native precedence and effective enablement rather than only checking
+  whether a file or directory exists;
+- include native inline configuration sources when the host supports them;
+- honor documented CLI and environment overrides, including empty and malformed
+  values, without silently falling back to unrelated data;
+- emit metadata needed for review without serializing secret values or private
+  file contents;
+- remain deterministic and fail closed when identity, trust, or ownership is
+  ambiguous.
+
+Register the provider through its capability-owned index. Then trace the host id
+through every public inventory, lint, evidence-bundle, help, and report path that
+claims configured-asset support.
+
+## 5. Add Session Evidence Only When It Is Defensible
+
+A platform adapter under `scripts/session-analysis/platforms/` should qualify a
+session to the requested workspace before it can influence a report. Normalize
+only observed fields into the existing session contracts:
+
+- preserve or explicitly account for unknown events instead of silently
+  dropping them;
+- represent missing token usage or lifecycle fields as unobserved, not zero;
+- map cancelled, rejected, failed, and successful operations according to the
+  host's native states;
+- correlate calls and results with native ids and deterministic fallbacks;
+- deduplicate canonical paths and session identities without double-reading the
+  same file on a case-insensitive filesystem;
+- keep partial transcript, metadata, and audit coverage visible in output.
+
+If local sessions are unavailable, unstable, encrypted, or cannot be matched to
+the workspace safely, document session evidence as unavailable. Shell or asset
+support can still land independently.
+
+## 6. Propagate the Host Identity Deliberately
+
+Host ids currently appear in more than one capability because configured assets,
+sessions, reports, and packaging have different owners. Search for the existing
+host set before editing:
+
+```bash
+rg -n "qoder|codex|claude|cursor|qwen" scripts test references templates docs package.json
+```
+
+Use the results as an inventory, not a replacement template. Typical registration
+surfaces include:
+
+- `scripts/agent-customize/providers/index.mjs` and its public inventory CLI;
+- `scripts/session-analysis/analyzer.mjs` and the platform loader/help contract;
+- `scripts/harness-analysis/evidence-bundle/` provider validation and routing;
+- report, quality, lint, baseline, integrity, and root CLI help contracts that
+  explicitly enumerate supported hosts;
+- package whitelists and manifest-version checks, when a shell ships;
+- deterministic help snapshots and tests that intentionally lock the public
+  host list.
+
+Do not add the host to a registry unless the corresponding capability and its
+tests are present. Prefer a visible unsupported error over a host id that falls
+through to another provider.
+
+## 7. Build an Evidence Ladder
+
+Map tests to the spec acceptance ids. At minimum, cover the risks that apply to
+the host:
+
+| Risk | Fixture or check |
+| --- | --- |
+| Invented native contract | Pinned source/doc reference plus native CLI smoke |
+| Path mismatch | POSIX and Windows paths, spaces, Unicode, punctuation, case, symlink/canonical identity |
+| Wrong home or precedence | CLI override, environment override, default, empty, and malformed cases |
+| Foreign workspace evidence | Positive and negative workspace qualification fixtures |
+| Lost or inflated events | Unknown events, missing fields, call/result correlation, every terminal status |
+| Duplicate evidence | Canonical-path and case-insensitive deduplication fixture |
+| Secret leakage | Credential-shaped fixture with value-level non-disclosure assertions |
+| Packaging drift | Manifest presence/version assertions and `npm run pack:verify` |
+
+During development, run focused provider, session, manifest, bundle, and CLI
+tests. Before review, run the full repository suite. When Markdown is added or
+moved, regenerate and verify the link graph:
+
+```bash
+node scripts/doc-link-graph/cli.mjs skills/better-harness
+node --test test/doc-link-graph.test.mjs
+npm test
+npm run pack:verify
+git diff --check
+```
+
+Run `npm ci` and `npm run build` from `docs/` when the published site changes.
+CI must cover Windows, macOS, and Linux for cross-platform paths or filesystem
+behavior. A real-host smoke should separately prove native discovery, configured
+assets, session source/facts when claimed, evidence-bundle propagation, and a
+validated report render. Record unavailable checks honestly.
+
+## 8. Document and Review the Delivered Boundary
+
+Update the [host adapter matrix](README.md) with positioning, shell, configured
+assets, session evidence, default output, rules/prompts, and a reproducible smoke
+route. Add or update capability references for host-specific paths and evidence
+limits. Add README installation instructions only after the native command has
+been verified. Use a host-specific adapter page only when the matrix's split
+triggers are met.
+
+Before commit or review, use the
+[Change Traceability Review](../../.agents/skills/change-traceability-review/SKILL.md)
+in Review Readiness Check mode. The pull request should state:
+
+- the host/version and primary contract evidence;
+- the claimed and unavailable support slices;
+- spec and acceptance ids, changed canonical owners, and explicit non-goals;
+- exact focused, full-suite, native-smoke, cross-platform, and packaging results;
+- privacy, compatibility, generated-file, rollback, and residual risks;
+- AI involvement and the human verification performed.
+
+Use the repository [pull request template](../../.github/pull_request_template.md).
+Do not infer Story ids, AI involvement, CI status, or native compatibility from
+branch names, prose, passing synthetic tests, or similarity to another host.
+
+## Worked Pull Request Examples
+
+These examples are review material, not templates to copy verbatim. Re-check
+their latest diff and status before citing them.
+
+- [PR #6: Qwen Code host adapter](https://github.com/QoderAI/better-harness/pull/6)
+  shows why native source verification matters. Its review and follow-ups cover
+  manifest identity, config/runtime roots, path sanitization, effective
+  enablement, inline MCP/hooks, terminal statuses, environment precedence,
+  credential boundaries, and case-insensitive filesystem deduplication. The key
+  lesson is that a green suite can consistently encode the wrong host contract.
+- [PR #22: GitHub Copilot as a first-class host](https://github.com/QoderAI/better-harness/pull/22)
+  shows a spec-led decomposition across shell, configured assets, sessions,
+  shared registries, docs, and fixtures. Its evidence model keeps missing usage
+  fields explicit, rejects foreign-workspace sessions, and accounts for unknown
+  event types. Because review can change the PR, treat it as an evolving example,
+  not proof that a capability is merged or released.
+
+## Definition of Done
+
+- [ ] The spec names each claimed, partial, and unavailable support slice.
+- [ ] Native host/version evidence backs every discovery and data-layout claim.
+- [ ] Shell metadata is thin and independently smoke-tested when present.
+- [ ] Configured assets and sessions keep scopes, workspace identity, and private
+  data boundaries explicit.
+- [ ] Registration matches implemented capabilities; no unrelated host fallback
+  is possible.
+- [ ] Deterministic fixtures cover applicable path, precedence, status, dedupe,
+  foreign-workspace, unknown-event, and secret-boundary risks.
+- [ ] Focused, full-suite, cross-platform, native-smoke, documentation, and
+  packaging results are recorded accurately.
+- [ ] The matrix, capability references, installation docs, and published site
+  match the behavior actually delivered.
+- [ ] The Review Readiness Check finds a coherent Story/Spec/Test/Risk chain and
+  a clean staged/unstaged split.
diff --git a/docs/community.md b/docs/community.md
index c71051a..96a8d8e 100644
--- a/docs/community.md
+++ b/docs/community.md
@@ -15,6 +15,11 @@ matrix below:
 Reach for the full surface matrix only when you add executable behavior (scripts,
 hooks), a maturity model or detector, a host adapter, or packaging.
 
+To add a Coding Agent host, start with
+[Contributing a New Coding Agent Host](adapters/contributing-new-coding-agent.md).
+It turns the matrix row into an evidence, implementation, cross-platform, and
+review workflow without making every support slice mandatory.
+
 ## Extensible Surfaces
 
 This is the complete reference. For the common cases, see Start Here above.
@@ -56,7 +61,7 @@ Do not use community extensibility as a reason to:
 | "Add a new maturity lens" | `models/` | Model id, levels, dimensions, evidence and confidence rules, index entry | It mutates built-in defaults without saying so |
 | "Add a new detector signal" | Owning model, executable capability, or skill-local reference | Signal id, source evidence, false-positive boundary, projection target, and visible consumer | It has no evidence field, runtime or workflow owner, or consumer |
 | "Add language/framework knowledge" | `references/` first; `knowledge-base/` only with schema and fixtures | Source boundary, examples, fixture expectations | It is docs-only but tries to become runtime-active |
-| "Add host support" | `docs/adapters/README.md` matrix row | Discovery paths, evidence sources, smoke command, packaging status, split trigger if needed | It mixes host evidence collection with package generation |
+| "Add host support" | [new Coding Agent guide](adapters/contributing-new-coding-agent.md), then `docs/adapters/README.md` matrix row | Native host/version evidence, supported slices, discovery paths, evidence sources, smoke command, packaging status, split trigger if needed | It copies another adapter, mixes host evidence collection with package generation, or overstates partial support |
 | "Add a script" | `scripts/<business-capability>/` | CLI contract, JSON shape, fixtures, tests | It is ad-hoc debugging that belongs in `dev/` |
 | "Add an enforcement rule" | `hooks/` | Lifecycle event, expected blocking behavior, dry-run or fixture proof | A prompt reminder would be enough |
 | "Add a report or visual mode" | `templates/reporting/` | Parser contract, consumer path, preview or static check | It duplicates runtime rules into the base report template |
diff --git a/docs/docs/hosts/adapter-matrix.md b/docs/docs/hosts/adapter-matrix.md
index cdbb8f6..273f395 100644
--- a/docs/docs/hosts/adapter-matrix.md
+++ b/docs/docs/hosts/adapter-matrix.md
@@ -45,3 +45,9 @@ table, TODO list, and definition of done live in the repository
 
 The canonical matrix, discovery rules, and split triggers live in
 [`docs/adapters/README.md`](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md).
+
+## Contributing another host
+
+Start with [Contributing a Coding Agent Host](./contributing-new-coding-agent).
+It separates native shell, configured-asset, session, output, and packaging
+claims and links Qwen Code and GitHub Copilot pull requests as worked examples.
diff --git a/docs/docs/hosts/contributing-new-coding-agent.md b/docs/docs/hosts/contributing-new-coding-agent.md
new file mode 100644
index 0000000..bf05485
--- /dev/null
+++ b/docs/docs/hosts/contributing-new-coding-agent.md
@@ -0,0 +1,62 @@
+---
+id: contributing-new-coding-agent
+title: Contributing a Coding Agent Host
+sidebar_position: 2
+---
+
+# Contributing a New Coding Agent Host
+
+Host support is an evidence-backed set of claims, not one manifest or one
+transcript parser. A contribution can support only the slices the host exposes,
+as long as partial and unavailable coverage stays explicit.
+
+The complete, canonical workflow lives in the repository:
+
+- [New Coding Agent contribution guide](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/contributing-new-coding-agent.md)
+- [Repository agent instructions](https://github.com/QoderAI/better-harness/blob/main/AGENTS.md)
+- [Community extension map](https://github.com/QoderAI/better-harness/blob/main/docs/community.md)
+- [Architecture principles](https://github.com/QoderAI/better-harness/blob/main/docs/ARCHITECTURE.md)
+
+## Define the support boundary first
+
+| Slice | Required decision |
+| --- | --- |
+| Native contract | Host/version and primary source verified |
+| Shell | Native, source-local, generated, or none |
+| Configured assets | Available, partial, or unavailable scopes |
+| Session evidence | Available, partial, or unavailable fields and events |
+| Shared registration | Only capabilities that are actually implemented |
+| Output | Existing Canvas, HTML, Markdown, or a justified new mode |
+| Packaging | Public npm, runtime bundle, source-only, or none |
+
+A shell does not establish session support, and a parser does not establish
+native Skill discovery. Record each claim in a dated spec with stable acceptance
+ids and an evidence route.
+
+## Contribution workflow
+
+1. Read the host's versioned, primary contract for manifests, paths,
+   configuration precedence, workspace identity, events, and privacy boundaries.
+2. Keep any host shell thin; canonical judgment remains in shared Skills,
+   models, references, templates, and capability-owned scripts.
+3. Add configured-asset and session adapters independently. Use sanitized
+   fixtures, reject foreign-workspace evidence, and represent missing fields as
+   unobserved rather than zero.
+4. Propagate the host id only through registries whose capabilities exist.
+   Prefer an explicit unsupported error to fallback through another host.
+5. Verify focused tests, the full suite, native-host smoke paths, package
+   boundaries, and Windows/macOS/Linux behavior proportional to the change.
+6. Update the [adapter matrix](./adapter-matrix) and submit Story/Spec/Test/Risk
+   evidence through the repository pull request template.
+
+## Worked examples
+
+- [PR #6 — Qwen Code](https://github.com/QoderAI/better-harness/pull/6)
+  demonstrates why native source checks, environment precedence, privacy, and
+  case-insensitive filesystem coverage must supplement synthetic tests.
+- [PR #22 — GitHub Copilot](https://github.com/QoderAI/better-harness/pull/22)
+  demonstrates spec-led separation of shell, assets, sessions, registries,
+  documentation, and evidence-honesty boundaries.
+
+Pull requests can change during review. Use them as worked examples, then defer
+to the current repository instructions and canonical guide.
diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md
index 7d331ba..0f93004 100644
--- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md
+++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md
@@ -42,3 +42,9 @@ TODO 列表和完成定义维护在仓库
 
 规范矩阵、发现规则和拆分触发条件见
 [`docs/adapters/README.md`](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)。
+
+## 贡献新的宿主
+
+请从[贡献新的 Coding Agent 宿主](./contributing-new-coding-agent)开始。
+该指南会分别处理原生 Shell、已配置资产、会话、输出和打包声明，并链接
+Qwen Code 与 GitHub Copilot PR 作为复盘示例。
diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/contributing-new-coding-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/contributing-new-coding-agent.md
new file mode 100644
index 0000000..ddf89f4
--- /dev/null
+++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/contributing-new-coding-agent.md
@@ -0,0 +1,58 @@
+---
+id: contributing-new-coding-agent
+title: 贡献新的 Coding Agent 宿主
+sidebar_position: 2
+---
+
+# 贡献新的 Coding Agent 宿主
+
+宿主支持是一组由证据支撑的能力声明，不是单个 manifest 或会话解析器。
+贡献可以只实现宿主确实具备的部分，但必须明确标注部分支持和不可用能力。
+
+完整且规范的流程位于仓库中：
+
+- [新增 Coding Agent 贡献指南](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/contributing-new-coding-agent.md)
+- [仓库 Agent 指令](https://github.com/QoderAI/better-harness/blob/main/AGENTS.md)
+- [社区扩展地图](https://github.com/QoderAI/better-harness/blob/main/docs/community.md)
+- [架构原则](https://github.com/QoderAI/better-harness/blob/main/docs/ARCHITECTURE.md)
+
+## 先确定支持边界
+
+| 能力切片 | 必须明确的决定 |
+| --- | --- |
+| 原生契约 | 已验证的宿主版本与第一手来源 |
+| Shell | 原生、源码本地、生成产物或不提供 |
+| 已配置资产 | 可用、部分可用或不可用的作用域 |
+| 会话证据 | 可用、部分可用或不可用的字段与事件 |
+| 公共注册 | 只注册实际实现的能力 |
+| 输出 | 现有 Canvas、HTML、Markdown，或理由充分的新模式 |
+| 打包 | 公共 npm、运行时 bundle、仅源码或不打包 |
+
+Shell 不代表已经支持会话证据，解析器也不代表 Skill 能被宿主原生发现。
+请在带日期的 spec 中为每项声明设置稳定的验收 id 和证据路径。
+
+## 贡献流程
+
+1. 阅读宿主带版本的第一手契约，核对 manifest、路径、配置优先级、
+   工作区身份、事件和隐私边界。
+2. 保持宿主 Shell 轻量；规范的判断继续归属于共享 Skill、模型、参考资料、
+   模板和能力自有脚本。
+3. 分别实现已配置资产和会话适配器。使用脱敏 fixture，拒绝其他工作区的
+   证据，并把缺失字段标为未观测，而不是记为零。
+4. 只在已实现相应能力的注册表中加入宿主 id。遇到不支持的能力时应明确
+   报错，不能回退到其他宿主。
+5. 按风险验证聚焦测试、完整测试、真实宿主 smoke、打包边界，以及
+   Windows、macOS、Linux 行为。
+6. 更新[适配矩阵](./adapter-matrix)，并通过仓库 PR 模板提交
+   Story/Spec/Test/Risk 证据。
+
+## PR 示例
+
+- [PR #6 — Qwen Code](https://github.com/QoderAI/better-harness/pull/6)
+  展示了为什么除合成测试外，还需要原生源码核对、环境变量优先级、隐私边界
+  和大小写不敏感文件系统测试。
+- [PR #22 — GitHub Copilot](https://github.com/QoderAI/better-harness/pull/22)
+  展示了如何用 spec 把 Shell、资产、会话、注册、文档和证据诚实性拆成
+  可审查的部分。
+
+PR 会在审查中变化。请把它们当作复盘示例，并以仓库当前指令和规范指南为准。
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 15b5b92..98afca9 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -22,7 +22,10 @@ const sidebars = {
     {
       type: "category",
       label: "Hosts",
-      items: ["hosts/adapter-matrix"],
+      items: [
+        "hosts/adapter-matrix",
+        "hosts/contributing-new-coding-agent",
+      ],
     },
     {
       type: "category",
diff --git a/docs/specs/2026-07-30-new-coding-agent-contribution-guide.md b/docs/specs/2026-07-30-new-coding-agent-contribution-guide.md
new file mode 100644
index 0000000..93a05f4
--- /dev/null
+++ b/docs/specs/2026-07-30-new-coding-agent-contribution-guide.md
@@ -0,0 +1,110 @@
+# New Coding Agent Contribution Guide
+
+## Traceability
+
+- Spec ID: `new-coding-agent-contribution-guide`
+- Status: Implemented
+
+## Intent
+
+Give contributors one evidence-first route for adding a Coding Agent host to
+Better Harness. The guide should turn the lessons visible in the Qwen Code and
+GitHub Copilot contributions into a reusable contract without making either
+pull request the source of truth.
+
+## Acceptance Scenarios
+
+- **NCAG-AC-1 (discoverable route):** A contributor starting from the root
+  `AGENTS.md`, root README, `CONTRIBUTING.md`, community extension map,
+  canonical host matrix, or published Hosts documentation can reach the new
+  guide.
+- **NCAG-AC-2 (complete host slices):** The guide distinguishes native host
+  research, thin shell metadata, configured-asset collection, session evidence,
+  shared registration, documentation, packaging, and output routing, while
+  allowing unsupported slices to remain explicitly unavailable.
+- **NCAG-AC-3 (evidence and safety):** The guide requires native-contract
+  evidence, workspace qualification, privacy-safe normalization, deterministic
+  fixtures, real-host smoke evidence or an explicit unavailable note, and
+  Windows/macOS/Linux validation proportional to the changed behavior.
+- **NCAG-AC-4 (traceable workflow):** The guide routes contributors through a
+  spec, stable acceptance ids, scoped commits, Review Readiness Check evidence,
+  and the repository's pull request template without inventing Story, AI, CI,
+  or host-support claims.
+- **NCAG-AC-5 (worked examples):** The guide links
+  [PR #6](https://github.com/QoderAI/better-harness/pull/6) and
+  [PR #22](https://github.com/QoderAI/better-harness/pull/22) as contrasting
+  worked examples and states what lesson to inspect in each, without treating
+  their descriptions or current states as timeless contracts.
+- **NCAG-AC-6 (publication integrity):** English canonical guidance and the
+  English/zh-Hans curated site pages remain consistent, all relative Markdown
+  links resolve, and the Docusaurus site builds with zero broken links.
+
+## Non-goals
+
+- Adding, repairing, approving, merging, or otherwise changing PR #6 or PR #22.
+- Adding a new host adapter, provider enum, manifest, session parser, report
+  mode, or packaging target.
+- Declaring every host capable of session evidence or every shell publishable.
+- Replacing `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/community.md`, or the
+  canonical host matrix as their respective sources of truth.
+- Freezing third-party host internals in this guide; contributors must cite the
+  host version and primary source they actually verified.
+
+## Plan and Tasks
+
+1. Add `docs/adapters/contributing-new-coding-agent.md` as the canonical
+   contribution workflow beside the host matrix.
+2. Structure it as a sequence from research and support-scope decisions through
+   implementation slices, evidence, packaging, documentation, and review.
+3. Link the two pull requests in a bounded worked-examples section and link the
+   repository instructions and architecture owners throughout the route.
+4. Add an English curated page under `docs/docs/hosts/`, a matching zh-Hans
+   translation, and sidebar routing without duplicating canonical judgment.
+5. Add navigation from `AGENTS.md`, `CONTRIBUTING.md`, `README.md`,
+   `README.zh-CN.md`, `docs/community.md`, `docs/adapters/README.md`, and the
+   published adapter matrix pages.
+6. Run the link graph, site build, focused tests, full repository tests, and a
+   final diff/readiness review; update this status only when evidence supports
+   it.
+
+## Test and Review Evidence
+
+- **NCAG-AC-1/5:** inspect the final diff and follow every guide/PR/instruction
+  link from each named entry page.
+- **NCAG-AC-6:** regenerate the Better Harness Markdown graph with
+  `node scripts/doc-link-graph/cli.mjs skills/better-harness`, then run
+  `node --test test/doc-link-graph.test.mjs test/docs-site.test.mjs`.
+- **NCAG-AC-6:** run `npm ci && npm run build` from `docs/`; both locales must
+  build with zero broken links.
+- **NCAG-AC-2/3/4:** run `npm test` because repository tests enforce some
+  provider and documentation contracts; no runtime behavior should change.
+- **All ACs:** run `git diff --check`, inspect staged/unstaged scope separately,
+  and apply the Change Traceability Review Readiness Check before handoff.
+
+Observed on 2026-07-30:
+
+- `node scripts/doc-link-graph/cli.mjs skills/better-harness` regenerated the
+  34-file / 50-link graph with no tracked drift.
+- `node --test test/doc-link-graph.test.mjs test/docs-site.test.mjs` passed 7/7.
+- `npm ci && npm run build` from `docs/` built English and zh-Hans with zero
+  broken links.
+- `npm test` passed 867/867 after preserving the tested canonical-owner phrase
+  in the community intake matrix.
+- `npm run pack:verify` passed with 311 npm entries and 337 runtime ZIP entries.
+- `git diff --check` passed; the final readiness review found documentation and
+  site-source changes only, with no staged files or generated graph drift.
+
+## Risks
+
+- **Guide drift:** concrete path lists can become stale as new hosts arrive.
+  Mitigation: point to registry/search commands and canonical owners, and use
+  the PRs only as examples.
+- **False parity:** contributors may copy another adapter and overclaim support.
+  Mitigation: require a per-slice support decision, source-backed host contract,
+  and explicit unavailable/partial states.
+- **Credential or transcript exposure:** real-host validation can leak private
+  data. Mitigation: require sanitized fixtures, bounded smoke output, and no raw
+  transcripts or secrets in commits or PR text.
+- **Published-doc duplication:** the curated website can diverge from repository
+  guidance. Mitigation: keep the repository guide canonical and make the site
+  page a concise route back to it.