[bobleer]

Summary

Docs only. Brings the agent guides and two architecture documents back in line with the current workspace.

• Root guide (AGENTS.md, AGENTS-CN.md): reorganised to hold only cross-cutting rules and stable entry points, 384 → 193 lines. The Chinese guide now mirrors the English one line for line.
• Hook ownership: engine, registry, hook-source and dispatch ownership moves from the root guide into the agent-runtime and core guides.
• Layer guides: crate tables completed — one row in the English adapters guide, twelve rows across the Chinese adapters, services and contracts guides.
• product-architecture.md: the Level 0 development-view diagram and module inventory cover every Cargo and pnpm workspace member.
• computer-use-control.md: "Ownership and execution" no longer contradicts "Native provider ownership".
• CONTRIBUTING.md, CONTRIBUTING_CN.md: stale references to AGENTS.md corrected.

Type and Areas

Type: docs

Areas: repository contributor and agent guidance, architecture docs

Motivation / Impact

The root guide is loaded into every agent conversation, and parts of it and of the documents it points to had drifted from the code:

• Its layer table carried a per-layer crate list that named 9 of 14 adapter crates, 7 of 10 service crates, 8 of 9 execution crates and 4 of 5 contract crates. The layer guides it delegates to were incomplete as well, mostly on the Chinese side.
• computer-use-control.md stated in "Native provider ownership" that services/computer-use owns the native implementation and tool-contracts owns the host port, while "Ownership and execution" still said Desktop owns the native resources and Core owns the port.
• CONTRIBUTING.md referred to a verification matrix and an i18n row in AGENTS.md that the guide does not have.

No direct user-facing change.

Verification

• pnpm run check:repo-hygiene — passed.
• pnpm run check:github-config — passed.
• node --test --test-name-pattern="Rust build dependency boundary policy stays discoverable" scripts/check-core-boundaries.test.mjs — passed. This is the only test that reads the changed documents.
• git diff --check — clean. node scripts/check-git-object-sizes.mjs — passed.
• Scripted checks against the tree (scripts not committed):
  • all 179 relative links in the 13 changed files resolve;
  • the crate table of each of the six layer guides, English and Chinese, equals the crates on disk;
  • the product-architecture.md inventory names all 56 Cargo workspace members and all 16 pnpm workspace packages;
  • AGENTS.md and AGENTS-CN.md have the same line-by-line structure.
• Every identifier and path named in the rewritten Computer Use section was checked against the code.
• The 16 Mermaid diagrams in product-architecture.md parse with the repository's Mermaid version, and the changed Level 0 diagram was rendered in a browser.
• No Rust or frontend source changed, so no build or runtime test was run and no remote scenario was exercised.

Reviewer Notes

The four commits are split by topic and can be reviewed one at a time.

Root guide: rules are regrouped and reworded, not relaxed. Content that leaves the file:

• The per-layer crate lists. Layer guides own the crate tables.
• Hook engine and registry ownership, now in the agent-runtime and core guides. Those guides name the actual RuntimeHookRegistry type and describe the separate remote-workspace registry; the root guide said HookRegistry.
• The Web UI i18n namespace rule, which src/web-ui/AGENTS.md and docs/architecture/i18n.md already own.
• "Read README.md and CONTRIBUTING.md before architecture-sensitive changes". The guide now points to CONTRIBUTING.md for commit and PR conventions.
• The statement that the OpenCode P0 adapter remains a static-preview path. The adapter has live providers today; the rule against extending the legacy managed-package path stays.

Content that is new in the root guide:

• "Update AGENTS.md and AGENTS-CN.md in the same change."
• A "Must not" column in the layer table, which replaces the separate boundary-rule list.
• src/*-market-web in the layer 1 paths, and pnpm run capabilities:generate after editing the Product Operation Registry.

Computer Use: dated evidence records that mention Desktop test suites are left as written; they describe what was run at the time.

AI-assisted with Cursor. Testing level: lightly tested (the documentation checks listed above).

Checklist

• This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
• Relevant verification is recorded above, or skipped checks are explained.
• User-facing strings, docs, and locales are updated where applicable.