docs: consolidate documentation and reduce redundancy

AGENTS.md

@@ -1,51 +1,38 @@
 # AGENTS.md
 
-The following rules apply to coding agent collaboration and delivery workflows in this repository.
+The following rules apply to coding agent collaboration in this repository. These complement the general [CONTRIBUTING.md](CONTRIBUTING.md) workflow.
 
 ## 1. Core Principles
 
-- Move tasks forward under secure and traceable conditions, while avoiding unnecessary process blockers.
-- Stay consistent with the existing repository structure, implementation style, and engineering conventions.
+- Move tasks forward under secure and traceable conditions.
+- Adhere to the existing repository structure and engineering conventions.
 
-## 2. Git Workflow
+## 2. Collaboration Workflow
 
-- Do not commit or push directly to protected branches: `main` / `master` / `release/*`.
-- Each development task should be implemented on an independent branch, preferably cut from the latest mainline.
-- Prefer `git fetch` + `git merge --ff-only` to sync mainline and avoid implicit merges.
-- It is allowed to push development branches to remote branches with the same name for collaboration and backup.
-- Do not rewrite shared history: no `git push --force`, `git push --force-with-lease`, or arbitrary `rebase`.
-- Commit only files related to the current task; do not clean up or roll back unrelated local changes.
+- Follow the Git, Issue, and PR workflow defined in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Use `gh` CLI for all issue/PR operations (reading, writing, and comments). Do not edit through the web UI.
+- Create a new tracking issue for any development task that does not already have one.
+- Link the issue explicitly in PR descriptions (e.g., `Closes #xx`).
+- Keep status updates synchronized to the relevant issue/PR to avoid duplicate manual work.
 
-## 3. Issue and PR Collaboration
+## 3. Tooling and Text Conventions
 
-- Before starting a development task, check whether a related open issue already exists (for example, `gh issue list --state open`).
-- If no related issue exists, create a new issue for tracking. The issue should include background, reproduction steps, expected vs. actual behavior, acceptance criteria, and a `git rev-parse HEAD` snapshot.
-- Only collaboration-process documentation changes (such as `AGENTS.md`) can be modified directly without creating an additional issue.
-- Recommended issue title prefixes: `[feat]`, `[bug]`, `[docs]`, `[ops]`, `[chore]`.
-- If a commit serves a specific issue, include the corresponding `#issue` in the commit message.
-- PRs are recommended to be created as Draft by default, and should explicitly indicate linkage in the description (for example, `Closes #xx` / `Relates to #xx`).
-- When key progress, solution changes, or new risks appear, sync updates to the corresponding issue/PR in time and avoid duplicate comments.
+- **Language**: Use Simplified Chinese for issues, PRs, and comments. Technical terms may remain in English.
+- **PR Body**: For multi-line bodies, write to a temporary file first and pass it via `gh pr create --body-file`.
+- **References**: Use `#123` for same-repo references; use full URLs for cross-repo links.
 
-## 4. Tooling and Text Conventions
+## 4. Regression and Validation
 
-- Use `gh` CLI to read and write issues/PRs; do not edit through the web UI manually.
-- Use Simplified Chinese for issues, PRs, and comments; technical terms may remain in English.
-- For multi-line bodies, write to a temporary file first and pass it with `--body-file`; do not concatenate `\\n` in `--body`.
-- Use `#123` for same-repo references (auto-linking); use full URLs for cross-repo references.
+- Use the primary validation entrypoint for all changes:
+  ```bash
+  ./scripts/doctor.sh
+  ```
+- If `pre-commit` (via `doctor.sh`) auto-fixes files, review the changes before committing.
+- For documentation-only changes, you may skip tests but must self-check all commands and paths.
+- If environment limits prevent full validation, explicitly report what was skipped and why.
 
-## 5. Regression and Validation
+## 5. Security and Configuration
 
-- Choose regression strategy based on change type. Default baseline:
-  - `uv run pre-commit run --all-files`
-  - `uv run pytest`
-- If `pre-commit` auto-fixes files (such as `ruff --fix`), review the changes before committing.
-- For shell/deployment script changes, in addition to baseline checks, run at least `bash -n` for syntax validation on modified scripts.
-- For documentation-only changes, tests may be skipped, but commands and path examples must be self-checked for usability.
-- `uv sync --all-extras` is required only for first-time setup or dependency changes; it is not mandatory for every change.
-- If any validation cannot be completed due to environment limits, explicitly state the skipped item and reason in the report.
-
-## 6. Security and Configuration
-
-- Never commit keys, tokens, credentials, or other sensitive information (including `.env` content).
-- Logs and debug output must not leak access tokens or private data.
-- Changes related to deployment, authentication, or secret injection must include synchronized documentation updates and minimal acceptance steps.
+- **Secrets**: Never commit keys, tokens, or `.env` content.
+- **Logs**: Ensure debug output does not leak access tokens.
+- **Documentation**: Synchronize documentation updates for all deployment or auth-related changes.

README.md

@@ -8,22 +8,36 @@ deployment boundary.
 
 ## What This Is
 
-- An A2A adapter service for `opencode serve`.
-- Use it when you need a stable A2A endpoint for apps, gateways, or A2A
-  clients.
+- An A2A adapter service built on `opencode serve`, with inbound runtime
+  exposure plus outbound peer calling.
+- It supports both roles in one process: serving as an A2A Server and hosting an
+  embedded A2A Client for `a2a_call`.
+
+## Architecture
 
 ```mermaid
 flowchart TD
-    Client["a2a-client-hub / any A2A client"]
+    External["A2A Clients / a2a-client-hub / Gateways"]
 
-    subgraph ServerSide["Server-side"]
-        Adapter["opencode-a2a\nA2A adapter service"]
-        Runtime["opencode serve\nOpenCode runtime"]
+    subgraph Adapter["opencode-a2a Runtime"]
+        Ingress["Inbound A2A Surface\nREST + JSON-RPC"]
+        OpenCode["OpenCode Runtime"]
+        Outbound["Embedded A2A Client\na2a_call"]
+    end
 
-        Adapter <--> Runtime
+    subgraph Peers["Peer A2A services"]
+        PeerA2A["Peer A2A Agent"]
+        PeerRuntime["Peer OpenCode Runtime"]
+        PeerA2A --> PeerRuntime
     end
 
-    Client <--> Adapter
+    External -->|message/send,\nmessage:stream| Ingress
+    Ingress -->|tool call| OpenCode
+    OpenCode -->|model/tool result events| Ingress
+    Ingress -->|a2a_call| Outbound
+    Outbound -->|message/send,\nmessage:stream| PeerA2A
+    PeerA2A -->|tool result| Outbound
+    PeerRuntime -->|task session\nexecution| PeerA2A
 ```
 
 ## Quick Start
@@ -62,7 +76,6 @@ OPENCODE_BASE_URL=http://127.0.0.1:4096 \
 A2A_HOST=127.0.0.1 \
 A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
-A2A_STREAM_SSE_PING_SECONDS=15 \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 opencode-a2a serve
 ```
@@ -73,22 +86,19 @@ Verify that the service is up:
 curl http://127.0.0.1:8000/.well-known/agent-card.json
 ```
 
-Default local address: `http://127.0.0.1:8000`
-
-## What You Get
+## Capabilities
 
 - A2A HTTP+JSON endpoints such as `/v1/message:send` and
   `/v1/message:stream`
 - A2A JSON-RPC support on `POST /`
 - Peering capabilities: can act as a client via `opencode-a2a call`
 - Autonomous tool execution: supports `a2a_call` tool for outbound agent-to-agent communication
 - SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks
-- Explicit REST SSE keepalive configurable through `A2A_STREAM_SSE_PING_SECONDS`
 - Session continuity through `metadata.shared.session.id`
 - Request-scoped model selection through `metadata.shared.model`
 - OpenCode-oriented JSON-RPC extensions for session and model/provider queries
 
-## Peering Node
+## Peering Node / Outbound Access
 
 `opencode-a2a` supports a "Peering Node" architecture where a single process handles both inbound (Server) and outbound (Client) A2A traffic.
 
@@ -140,9 +150,8 @@ turn OpenCode into a hardened multi-tenant platform.
 - Provider auth and default model configuration remain on the OpenCode side; deployment-time
   precedence details and HOME/XDG state impact are documented in
   [docs/guide.md](docs/guide.md#troubleshooting-provider-auth-state).
-- `A2A_CLIENT_BEARER_TOKEN` is used for outbound peer calls initiated by the
-  server-side `a2a_call` tool.
-- Provider auth and default model configuration remain on the OpenCode side.
+- Use `A2A_CLIENT_BEARER_TOKEN` for server-side outbound peer calls initiated by
+  `a2a_call`.
 - Deployment supervision is intentionally BYO. Use `systemd`, Docker,
   Kubernetes, or another supervisor if you need long-running operation.
 - For mutually untrusted tenants, run separate instance pairs with isolated

docs/guide.md

@@ -188,9 +188,7 @@ comes from the `opencode-a2a` package itself.
     URI.
   - `DataPart` is currently rejected explicitly; it is not silently downgraded.
 - Task state defaults to `completed` for successful turns.
-- The deployment profile is single-tenant and shared-workspace: one server
-  instance exposes one OpenCode workspace/environment to all consumers bound to
-  that instance.
+- The deployment profile is single-tenant and shared-workspace. For detailed isolation principles and security boundaries, see [SECURITY.md](../SECURITY.md).
 
 ## Streaming Contract
 

scripts/README.md

@@ -12,7 +12,7 @@ remaining repository-maintenance helpers.
 
 ## Other Scripts
 
-- [`doctor.sh`](./doctor.sh): local development regression entrypoint (`sync`/`pip check` + lint + tests + coverage policy)
+- [`doctor.sh`](./doctor.sh): primary local development regression entrypoint (uv sync + lint + tests + coverage)
 - [`dependency_health.sh`](./dependency_health.sh): dependency review entrypoint (`sync`/`pip check` + outdated + audit)
 - [`check_coverage.py`](./check_coverage.py): enforces the overall coverage floor and per-file minimums for critical modules
 - [`lint.sh`](./lint.sh): lint helper