docs: rebuild the documentation skill and standards (#2983)

packages/code-runtime/README.md

@@ -1,14 +1,52 @@
+---
+description: "Package map for the code-execution capability family: what program execution does for you, and which package owns each part."
+kind: "package-group"
+---
+
 # code-runtime/ — code-execution capability family
 
 English | [中文](README.zh.md)
 
-The code-execution capability seam (see [capability seams](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): a runtime Service Definition for executing one model-written program against host-provided async bindings, capturing what it printed and returned; replaceable providers; and the tool registry's [Code Mode](../core/tools/README.md) Consumer (`tools: { mode: code }` — the `run_code` tool and the SDK generated in the loaded runtime's `language`). Design is in the [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md). **Product** packages.
+## Summary
+
+The `code-runtime/` group provides program execution: a model writes one program that calls host-provided functions as ordinary async calls, and a runtime executes it in isolation and returns only what the program printed and returned. One package defines the shared capability (`ctx.codeRuntime`), a second executes TypeScript programs in a fresh Node worker thread, and a third owns the wire protocol between a Node host and a CPython subprocess for the Python backend. Every run is independent — no state carries from one program to the next — and failures come back as part of the result, so the caller can see why a program failed and feed that back to the model.
+
+## Table of Contents
+
+- [Packages](#packages)
+- [Related documentation](#related-documentation)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="packages"></a>
+## Packages
+
+These three packages together provide program execution; each README describes what its part does.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`code-runtime/`](code-runtime/README.md) | Service Definition and shared vocabulary | `ctx.codeRuntime` |
-| [`code-runtime-worker/`](code-runtime-worker-thread/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
+| [`code-runtime/`](code-runtime/README.md) | Defines what a code runtime does: run one program against host-provided bindings and report what it printed and returned | `ctx.codeRuntime` |
+| [`code-runtime-worker-thread/`](code-runtime-worker-thread/README.md) | Executes TypeScript programs, each in a fresh Node worker thread | registers `ctx.codeRuntime` |
+| [`code-runtime-python/`](code-runtime-python/README.md) | Owns the fd-3 wire protocol between a Node host and a CPython subprocess, the Python backend's protocol layer | — |
 
-Providers register the service without changing its Consumer. The child READMEs own language, isolation, and execution-budget details.
+-----
 
-The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).
+<a id="related-documentation"></a>
+## Related documentation
+
+Start with the subsystem reference for the service contract, then the Code Mode design that consumes this capability and the capability-seam model it follows.
+
+- [Code runtime subsystem reference](../../docs/subsystems/code-runtime.md) — request/result vocabulary, bindings, and the `ctx.codeRuntime` cordis surface.
+- [Code Mode Agent Note](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) — how the tool registry presents `run_code` to the model.
+- [Capability seams](../../docs/capability-seams.md) — the Service Definition / Service Provider / Consumer split this family follows.
+
+<a id="dev-note"></a>
+## Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>