docs: refresh bilingual MCP integration guides and site usability

[novelKR]

Problem and result

The guides still described implemented UDS/Linux/Codex execution paths as future work, while startup examples omitted workspace registration and helper configuration. Readers could also mistake EOF for command success, a Compose sleeper for a Runner, or test-source coverage for a completed validation run.

This PR rewrites the 15 maintained English/Korean pairs, adds an Agent Loop integration pair, and makes the site lead through setup → MCP connection → read/patch/exec → result inspection. English remains the editorial source; Korean was reviewed as prose, including tables, recovery instructions, and locale links. Irrelevant CoS/cokacremote comparisons and unexplained work-package notes are removed; dependency and license attribution is retained.

Scope: documentation, example comments, site wording/generation, and focused documentation tests. No MCP DTO, runtime, policy, persistence, dependency, release, or deployment behavior changes. Leave unmerged for user review; no Pages deployment is requested.

Review ledger

Each row covers both language files (unless noted). “Source review” is static evidence, not a claim of live deployment.

Document	Problem → implementation evidence → change	Validation
README	Future-tense/unclear role → Runner and live tool contracts → purpose, 14 tools, setup links, current limits	Source review; macOS stdio smoke; paired prose
index	Flat list → maintained registry → task-oriented reading map	Locale links and generated routes
operations	Missing registry/helper steps → server config and binary manifests → build, register, configure, start, inspect, troubleshoot	Fresh server/helper build; disposable-workspace smoke; example JSON
agent-integration (new)	Missing outer-loop procedure → domain DTOs and orchestration → request/result examples, distinct preview/apply keys, polling, recovery, coordination	Actual stdio read/preview/apply/replay/readback/exec/cancel/work calls; schema/source comparison
architecture	Target/current mixed → server → Runner → adapters → responsibilities, state, transaction/lifetime	Source call-path review
execution-substrate	Design memo and unexplained future features → current contracts/policy scanner → implemented invariants and explicit missing capabilities	Domain, policy, runner, scanner review
runner-isolation	Implemented worker/helper described as future → UDS protocol 3, helper protocol 1 → separate host worker, Linux isolation, network enforcement, sleeper fixture	Source and Linux test review; macOS smoke explicitly reports no sandbox
security-model	Overbroad/future security claims → path adapter, helper probe, network modes → effective controls, trust anchor, fallbacks, recovery limits	Source review; coverage inventory corrected
behavior-differences	Incomplete result interpretation → runner/src/apply.rs and gateway operation records → state table and post-apply verification caveat	Source review; preview/apply/replay smoke
error-codes	Stale/reserved-only descriptions → domain errors and helper/process call sites → current meanings, dispatch vs completion	Enum/call-site comparison
protocol-compatibility	Development notes → forced-version tests → tested revisions, transport floor, application vs protocol state	protocol_compat source review; stdio initialization
chatgpt-connector	Local tests implied product connection → HTTP config and official developer-mode docs → separate local setup and unverified live-account/auth/Host requirements	Official OpenAI reference checked 2026-09-19; no live account claim
codex-reuse	Long comparison memo → adapter manifests and actual call sites → connected components, authority, transitive vs direct dependencies	Source review; necessary Codex provenance retained
upstream-lock	Patch-only/outdated scope → pinned submodule and adapter manifests → shared pin and all consumers	Pin unchanged; English Commit table remains script-compatible
upstream-update	Patch-only gates → current CI → all-adapter and Linux validation procedure	Workflow comparison
documentation	Build/publication dominant → registry and site pipeline → editorial procedure, compatibility, preview, publication evidence	Registry/build/site checks
Test/deploy READMEs, adversarial inventory, .env.example, workspace example	Work numbers, nonexistent rollback path, timeless PASS, sleeper mislabeled → test paths, Dockerfile, config loader → coverage vs results and correct setup scope	Paths/source checked; safe read-only workspace example retained
Site home/page tools	Repeated cards and publication workflow → registry-generated site → three different purposes, actual usage steps, explicit Markdown copy feedback	Three focused regression tests plus existing two; rendered QA below

Before / after examples

• “제품과 프리미티브” and unexplained WP stages → “CodeSpace의 Codex 재사용 범위”, organized by connected components and responsibility.
• “빌드 → 검증 → 산출물 → 게시” on the product home → “작업 공간 등록 → MCP 연결 → 읽기·수정·실행 → 결과 확인”. Publishing instructions stay in the maintenance guide.
• Identical home-card descriptions → separate getting-started, Agent Loop, and operations/troubleshooting summaries.
• Korean README body links to English pages → corresponding Korean guides.
• A startup command alone → explicit registry JSON, helper path, persistent database choice, transport start, and first capability check.
• Test source marked PASS → coverage inventory that asks readers to inspect the exact CI run.

All existing document routes remain. 198 legacy rendered heading anchors were checked across the 30 pre-existing pages, including VitePress's decomposed Korean IDs; GitHub-style anchors are preserved too. New routes: /guide/agent-integration and /ko/guide/agent-integration.

Validation

Head: 1f3bbe8fa917319005c06f2f3a700afadd70e890 (three reviewable commits). Base main: ab5defb620a41e4239320dd80827d4f947a61adb; remote main rechecked before submission.

• python3 -B scripts/check_docs.py: 16 reviewed pairs.
• npm ci --prefix docs-site --ignore-scripts: passed with pinned Node 24.21.0/npm 11.19.0.
• npm test --prefix docs-site: 5/5 passed, including explicit/fenced anchors, purposeful locale home cards, and Korean link remapping.
• npm run build --prefix docs-site and python3 -B docs-site/scripts/site.py check: passed, 35 HTML pages; full local link/fragment/resource/copy-hash inventory.
• 22 JSON code blocks parsed; English/Korean executable examples compared (translated shell comments excluded).
• Fresh macOS debug builds of server and patch helper using installed Command Line Tools (DEVELOPER_DIR=/Library/Developer/CommandLineTools, Rust 1.98.0). Default Xcode selection initially failed because its license was unaccepted; no license or machine setting was changed.
• Disposable-workspace stdio smoke: initialize, list 14 tools, workspace capabilities, read, preview, apply with a new key, replay, readback, operation lookup, echo/output/EOF, failing command, large output, cancellation, work open/status/finish. This is host/macOS evidence, not Linux isolation or live ChatGPT evidence. Local http_contract (2/2) and protocol_compat (7/7) also passed, including forced-version stdio/HTTP cases. Release-profile builds and UDS live smoke were not repeated locally; hosted CI remains separate.
• Rendered QA: English/Korean home, getting started, integration, operations, and long error-table pages were inspected at measured CSS widths 1439 and 727 in light/dark themes. No page-wide horizontal overflow; long code blocks scroll within their containers. Desktop language switching preserves the guide route; narrow navigation/sidebar controls and local search results work. Heading structure and page-copy success feedback were checked.
• Copy verification limit: the served Markdown hashes match all 32 sources and the Korean copy button reports success. The IAB automation virtual clipboard cannot read back the native browser write, so native paste was not verified. This is not presented as an end-to-end clipboard-content pass.
• All 200 repository-relative Markdown links resolve; all generated links/fragments are checked by the site inventory. 198 prior rendered heading anchors remain available.
• Documentation CI passed; docs-pages was skipped as intended. Download the rendered review artifact.
• GitHub builds PRs from a synthetic merge ref. Artifact source is b580cefa3b0016562289bf10c79b4cf2410011ea, whose parents are the unchanged base and exact head above. The full Git tree matches HEAD (e1f208c9daef586296c0aa397c80f65ce62e4987), and all 32 source hashes match the clean local HEAD build. This is a PR preview commit, not an actual merge into main.
• Runtime/policy CI: all 14 jobs passed, including integration, Linux isolation, and the final rust aggregate. Together with docs-build, 15 checks passed; only docs-pages was intentionally skipped. Final HEAD is unchanged and main was rechecked at ab5defb620a41e4239320dd80827d4f947a61adb. Ready for user review; do not merge or deploy as part of this task.

For the rendering comparison, the currently published home is the unchanged pre-PR baseline (observed at base ab5defb); the linked review artifact contains the rewritten home and guides. The before/after table above describes the visible differences. To reproduce the after view locally, check out the exact head and use the documented build/static-preview commands. Rebuilding requires stopping and restarting the verified preview, which pins the manifest at startup.

The PR workflow's documentation artifact is a review build, not a deployed public website. Published Pages is deliberately unchanged.

Runtime follow-up, not fixed here

crates/runner/src/apply.rs calls verify_disk_matches_claimed(...).await? after a successful helper response; snapshot restoration is only in the helper-error branch. The gateway can consequently record rejected after files changed. The guides now explicitly require inspection after post-apply verification errors. A separate runtime change should define the rollback/result contract and fault-injection coverage.

Other existing integration limits remain explicit: no public process exit code or output-loss flag; one live mutation/command per workspace; bounded file reads/find without paging; no durable process handles; no container dispatch or OAuth server. Restricted mode without a usable Linux helper can execute on the host with no OS network enforcement; enabled mode requires the helper.