docs: consolidate design documentation and standardize crate English

crates/client/README.md

@@ -1,30 +1,10 @@
 # client
 
-## Role
+Shared client for Backend Workspace/Runtime APIs and the Worker protocol. Provides authenticated communication and typed connection targets for CLI/TUI. The standalone crate owns Standalone execution, Runtime and the controller own Worker state and input admission, and higher-level crates own presentation and product commands.
 
-`client` contains reusable socket-client and runtime-command mechanics for talking to Workers from CLI/TUI code.
+## Implementation entry points
 
-## Boundaries
-
-Owns:
-
-- one-shot Worker socket client behavior
-- request/reply delivery mechanics
-- runtime command construction below the product façade
-- shared attach/status probing helpers used by higher layers
-
-Does not own:
-
-- product command names (`yoi`)
-- Worker state authority (`worker`, `session-store` worker metadata)
-- UI rendering (`tui`)
-- Engine turn semantics (`agen`)
-
-## Design notes
-
-The client boundary lets `tui` and `yoi` share Worker communication without making library crates depend on the product binary. Socket clients should drain connect-time snapshot/alert traffic before sending a method or deciding status.
-
-## See also
-
-- [`../../docs/design/worker-session-state.md`](../../docs/design/worker-session-state.md)
-- [`../../docs/design/overview.md`](../../docs/design/overview.md)
+- [`BackendApiClient`] — Authenticated HTTP/WS requests bound to an origin
+- [`backend_runtime`] / [`backend_workspace`] — Backend resource retrieval and operations
+- [`Client`] / [`transport`] — Method/Event encoding and message transport
+- [`target`] — Distinct Backend and Standalone targets and operation intents

crates/client/src/backend_api.rs

@@ -1,3 +1,14 @@
+//! Credentials and HTTP/WS requests bound to a Backend origin.
+//!
+//! BackendOrigin normalizes scheme/host/port and rejects inputs with a path, query, fragment,
+//! or userinfo. Stored tokens are selected by origin; cross-origin redirects are rejected
+//! to prevent credential leaks. WS requests use the same origin and bearer token.
+//!
+//! This client uses human Backend API tokens, not Workspace signing capabilities or Runtime
+//! source proofs. It returns 401/403 as authentication/authorization failures without falling
+//! back to a local Runtime or another token. Callers interpret typed results; transport success
+//! does not imply completion of a domain operation.
+
 use chrono::{DateTime, Utc};
 use reqwest::{Method, StatusCode, Url, redirect};
 use serde::{Deserialize, Serialize};

crates/client/src/backend_runtime.rs

@@ -1,3 +1,13 @@
+//! Runtime Worker operations and observation through the Backend.
+//!
+//! Targets are Workspace/Runtime/Worker tuples sent to scoped Backend APIs. Runtime endpoints
+//! and display names do not confer execution authority on the client. HTTP management reuses
+//! server-api DTOs; protocol connections carry Method/Event messages over Backend WS.
+//!
+//! Restore sends the caller's fixed observation token/request ID unchanged. Response loss does
+//! not imply rollback; there is no token replacement, automatic Restore, or reconnection to
+//! the next execution. Initial snapshots and notices are observations, not input admission.
+
 use crate::transport::websocket::{Socket as WebSocket, SocketError as WebSocketError};
 use crate::{BackendApiClient, BackendApiClientError, Client};
 pub use server_api::{

crates/client/src/backend_workspace.rs

@@ -1,3 +1,11 @@
+//! Generated client adapter for the Backend Workspace catalog.
+//!
+//! Workspace creation passes an operation key and optional initial Repository to the Server,
+//! without local Git discovery or repository initialization. Empty Repository lists are valid.
+//! The Server determines creation idempotency, ownership, and current-state replay; this client
+//! keeps no separate creation ledger. It classifies 401/403 as shared Backend authentication
+//! errors, distinct from other domain errors.
+
 use crate::{BackendApiClient, BackendApiClientError};
 use server_api::{
     InitialRepositoryIntent, RepositorySummary, WorkspaceCreateRequest, WorkspaceCreateResponse,

crates/client/src/client.rs

@@ -6,7 +6,12 @@ use protocol::{Event, Method};
 
 use crate::transport::Socket;
 
-/// Typed Worker protocol client over an injected message transport.
+/// Typed Worker protocol client over a message transport.
+///
+/// Encodes and sends Methods and decodes received messages into Events. Successful sends
+/// indicate transport delivery, not controller command acknowledgments or durable Submit/Notify
+/// receipts. Callers interpret events; connection snapshots are not consumed automatically
+/// and state is not inferred.
 pub struct Client<T> {
     socket: T,
 }

crates/client/src/lib.rs

@@ -1,7 +1,4 @@
-//! Backend Workspace/Runtime と既存 Worker protocol へ接続するクライアント。
-//!
-//! Standalone execution is owned by the `standalone` crate and does not spawn
-//! a Worker subprocess through this crate.
+#![doc = include_str!("../README.md")]
 
 pub mod backend_api;
 mod backend_auth;

crates/client/src/target.rs

@@ -1,3 +1,10 @@
+//! Distinct Backend and Standalone targets and product operation intents.
+//!
+//! Backend targets resolve an origin and Workspace and identify Workers by Runtime/Worker pairs.
+//! Standalone spawn/list/resume are intents passed to higher-level crates, not execution;
+//! this module starts no subprocesses. Target identity is separate from product commands
+//! and Worker state authority.
+
 use std::{fmt, path::PathBuf};
 
 use crate::{

crates/client/src/transport/mod.rs

@@ -1,3 +1,8 @@
+//! Message transport for one Worker connection.
+//!
+//! Separates in-process, Unix socket, and WS framing from protocol Method/Event encoding.
+//! Changing transports does not change ownership of Worker execution, input admission, or receipts.
+
 use std::error::Error;
 
 use async_trait::async_trait;
@@ -6,10 +11,9 @@ pub mod in_process;
 pub mod unix_socket;
 pub mod websocket;
 
-/// Message-oriented transport for one Worker protocol connection.
+/// UTF-8 message transport for a Worker protocol connection.
 ///
-/// Implementations own physical framing. `client::Client` owns the typed
-/// Method/Event protocol encoding layered on top of these UTF-8 messages.
+/// Implementations own physical framing; the higher-level Client encodes and decodes Method/Event.
 #[async_trait]
 pub trait Socket {
     type Error: Error + Send + Sync + 'static;