docs: make every docs read easy

Signed-off-by: Chojan Shang <[email protected]>

Author: Chojan Shang

AGENTS.md

@@ -1,35 +1,47 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- `src/acp/`: runtime package exposing agent/client abstractions, transports, and the generated `schema.py`.
-- `schema/`: upstream JSON schema sources; regenerate Python bindings with `make gen-all`.
-- `examples/`: runnable scripts (`echo_agent.py`, `client.py`, `gemini.py`, etc.) demonstrating stdio orchestration patterns.
-- `tests/`: pytest suite, including opt-in Gemini smoke checks under `tests/test_gemini_example.py`.
-- `docs/`: MkDocs content powering the hosted documentation.
-
-## Build, Test, and Development Commands
-- `make install` — provision the `uv` virtualenv and install pre-commit hooks.
-- `make check` — run Ruff linting/formatting, type analysis, dependency hygiene, and lock verification.
-- `make test` — execute `pytest` (with doctests) inside the managed environment.
-- `make gen-all` — refresh protocol artifacts when the ACP schema version advances (`ACP_SCHEMA_VERSION=<ref>` to pin an upstream tag).
-
-## Coding Style & Naming Conventions
-- Target Python 3.10+ with four-space indentation and type hints on public APIs.
-- Ruff enforces formatting and lint rules (`uv run ruff check`, `uv run ruff format`); keep both clean before publishing.
-- Prefer dataclasses or generated Pydantic models from `acp.schema` over ad-hoc dicts. Place shared utilities in `_`-prefixed internal modules.
-- Prefer the builders in `acp.helpers` (for example `text_block`, `start_tool_call`) when constructing ACP payloads. The helpers instantiate the generated Pydantic models for you, keep literal discriminator fields out of call sites, and stay in lockstep with the schema thanks to the golden tests (`tests/test_golden.py`).
-
-## Testing Guidelines
-- Tests live in `tests/` and must be named `test_*.py`. Use `pytest.mark.asyncio` for coroutine coverage.
-- Run `make test` (or `uv run python -m pytest`) prior to commits; include reproducing steps for any added fixtures.
-- Gemini CLI coverage is disabled by default. Set `ACP_ENABLE_GEMINI_TESTS=1` (and `ACP_GEMINI_BIN=/path/to/gemini`) to exercise `tests/test_gemini_example.py`.
-
-## Commit & Pull Request Guidelines
-- Follow Conventional Commits (`feat:`, `fix:`, `docs:`, etc.) with succinct scopes, noting schema regenerations when applicable.
-- PRs should describe exercised agent behaviours, link relevant issues, and include output from `make check` or focused pytest runs.
-- Update documentation and examples whenever public APIs or transport behaviours change, and call out environment prerequisites for new integrations.
+# Repository Handbook
+
+Use this page as the quick orientation for the Python SDK repo. It mirrors the tone of the main README/index and surfaces what you need without hunting through multiple docs.
+
+## Repo Map
+
+| Path | Why it exists |
+| --- | --- |
+| `src/acp/` | Runtime package: agent/client bases, transports, helpers, schema bindings, contrib utilities |
+| `schema/` | Upstream JSON schema sources (regenerate with `make gen-all`) |
+| `examples/` | Runnable scripts such as `echo_agent.py`, `client.py`, `gemini.py`, `duet.py` |
+| `tests/` | Pytest suite, including optional Gemini smoke tests in `tests/test_gemini_example.py` |
+| `docs/` | MkDocs content published at `agentclientprotocol.github.io/python-sdk/` |
+
+## Daily Commands
+
+| Need | Command |
+| --- | --- |
+| Bootstrap env + pre-commit | `make install` |
+| Format, lint, types, deps | `make check` |
+| Test suite (pytest + doctest) | `make test` |
+| Regenerate schema + bindings | `ACP_SCHEMA_VERSION=<tag> make gen-all` |
+
+## Style Guardrails
+
+- Target Python 3.10+ and keep public APIs typed.
+- Ruff handles formatting + linting (`uv run ruff format` / `check`)—keep both clean before pushing.
+- Reach for the generated Pydantic models and helpers (e.g. `text_block`, `start_tool_call`) instead of hand-crafting dicts; helpers stay aligned with the schema via `tests/test_golden.py`.
+- Place reusable internals in `_`-prefixed modules.
+
+## Testing Expectations
+
+- Tests live under `tests/` and follow the `test_*.py` naming. Mark async tests with `pytest.mark.asyncio`.
+- Run `make test` (or `uv run python -m pytest`) before committing and include reproduction steps for new fixtures.
+- Gemini CLI checks are opt-in: set `ACP_ENABLE_GEMINI_TESTS=1` and optionally `ACP_GEMINI_BIN=/path/to/gemini` to exercise `tests/test_gemini_example.py`.
+
+## PR Checklist
+
+- Use Conventional Commit prefixes (`feat:`, `fix:`, `docs:`, etc.) and call out schema regenerations explicitly.
+- Summarise exercised behaviours, link related issues, and attach `make check` / targeted pytest output in PR descriptions.
+- Update docs/examples when user-visible APIs or transports change, and document any new environment requirements.
 
 ## Agent Integration Tips
-- Bootstrap agents from `examples/echo_agent.py` or `examples/agent.py`; pair with `examples/client.py` for round-trip validation.
-- Use `spawn_agent_process` / `spawn_client_process` to embed ACP parties directly in Python applications.
-- Validate new transports against `tests/test_rpc.py` and, when applicable, the Gemini example to ensure streaming updates and permission flows stay compliant.
+
+- Start new agents from `examples/echo_agent.py` or `examples/agent.py`; pair them with `examples/client.py` for loopback validation.
+- `spawn_agent_process` / `spawn_client_process` embed ACP parties inside Python apps without hand-wiring stdio.
+- Validate new transports against `tests/test_rpc.py` and (when relevant) the Gemini example to ensure streaming + permission flows stay compliant.

CONTRIBUTING.md

@@ -1,126 +1,47 @@
-# Contributing to `agentclientprotocol/python-sdk`
+# Contributing
 
-Contributions are welcome, and they are greatly appreciated!
-Every little bit helps, and credit will always be given.
+Thanks for helping improve the Agent Client Protocol Python SDK! This guide mirrors the concise tone of the README/index so you can skim it quickly and get back to building.
 
-You can contribute in many ways:
+## Ways to help
 
-# Types of Contributions
+- **Report bugs** — file an issue with repro steps, OS + Python versions, and any environment toggles.
+- **Improve docs/examples** — clarify workflows, add integration notes, or document a new transport.
+- **Fix issues** — search for `bug` / `help wanted` labels or tackle anything that affects your integration.
+- **Propose features** — describe the use case, API shape, and constraints so we can scope the work together.
 
-## Report Bugs
+## Filing great issues
 
-Report bugs at https://github.com/agentclientprotocol/python-sdk/issues
+When reporting a bug or requesting a feature, include:
 
-If you are reporting a bug, please include:
+- The ACP schema / SDK version you’re using.
+- How to reproduce the behaviour (commands, inputs, expected vs. actual).
+- Logs or payload snippets when available (scrub secrets).
 
-- Your operating system name and version.
-- Any details about your local setup that might be helpful in troubleshooting.
-- Detailed steps to reproduce the bug.
+## Local workflow
 
-## Fix Bugs
+1. **Fork & clone** your GitHub fork: `git clone [email protected]:<you>/python-sdk.git`.
+2. **Bootstrap tooling** inside the repo root: `make install`. This provisions `uv`, syncs deps, and installs pre-commit hooks.
+3. **Create a topic branch:** `git checkout -b feat-my-improvement`.
+4. **Develop + document:**
+   - Keep code typed (Python 3.10+), prefer generated models/helpers over dicts.
+   - Update docs/examples when user-facing behaviour shifts.
+5. **Run the test gauntlet:**
+   ```bash
+   make check   # formatting, lint, type analysis, deps
+   make test    # pytest + doctests
+   ```
+   Optional: `ACP_ENABLE_GEMINI_TESTS=1 make test` when you have the Gemini CLI available.
+6. **(Optional) Cross-Python smoke:** `tox` if you want the same matrix CI runs.
+7. **Commit + push:** `git commit -m "feat: add better tool call helper"` followed by `git push origin <branch>`.
 
-Look through the GitHub issues for bugs.
-Anything tagged with "bug" and "help wanted" is open to whoever wants to implement a fix for it.
+## Pull request checklist
 
-## Implement Features
+- [ ] PR title follows Conventional Commits.
+- [ ] Tests cover the new behaviour (or the reason they’re not needed is documented).
+- [ ] `make check` / `make test` output is attached or referenced.
+- [ ] Docs and examples reflect user-visible changes.
+- [ ] Any schema regeneration (`make gen-all`) is called out explicitly.
 
-Look through the GitHub issues for features.
-Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
+## Need help?
 
-## Write Documentation
-
-This project could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
-
-## Submit Feedback
-
-The best way to send feedback is to file an issue at https://github.com/agentclientprotocol/python-sdk/issues.
-
-If you are proposing a new feature:
-
-- Explain in detail how it would work.
-- Keep the scope as narrow as possible, to make it easier to implement.
-- Remember that this is a volunteer-driven project, and that contributions
-  are welcome :)
-
-# Get Started!
-
-Ready to contribute? Here's how to set up the project for local development.
-Please note this documentation assumes you already have `uv` and `Git` installed and ready to go.
-
-1. Fork the `agentclientprotocol/python-sdk` repo on GitHub.
-
-2. Clone your fork locally:
-
-```bash
-cd <directory_in_which_repo_should_be_created>
-git clone [email protected]:YOUR_NAME/python-sdk.git
-```
-
-3. Now we need to install the environment. Navigate into the directory
-
-```bash
-cd python-sdk
-```
-
-Then, install and activate the environment with:
-
-```bash
-uv sync
-```
-
-4. Install pre-commit to run linters/formatters at commit time:
-
-```bash
-uv run pre-commit install
-```
-
-5. Create a branch for local development:
-
-```bash
-git checkout -b name-of-your-bugfix-or-feature
-```
-
-Now you can make your changes locally.
-
-6. Don't forget to add test cases for your added functionality to the `tests` directory.
-
-7. When you're done making changes, check that your changes pass the formatting tests.
-
-```bash
-make check
-```
-
-Now, validate that all unit tests are passing:
-
-```bash
-make test
-```
-
-9. Before raising a pull request you should also run tox.
-   This will run the tests across different versions of Python:
-
-```bash
-tox
-```
-
-This requires you to have multiple versions of python installed.
-This step is also triggered in the CI/CD pipeline, so you could also choose to skip this step locally.
-
-10. Commit your changes and push your branch to GitHub:
-
-```bash
-git add .
-git commit -m "Your detailed description of your changes."
-git push origin name-of-your-bugfix-or-feature
-```
-
-11. Submit a pull request through the GitHub website.
-
-# Pull Request Guidelines
-
-Before you submit a pull request, check that it meets these guidelines:
-
-1. The pull request should include tests.
-
-2. If the pull request adds functionality, the docs should be updated.
-   Put your new functionality into a function with a docstring, and add the feature to the list in `README.md`.
+Open a discussion or ping us in the ACP Zulip if you’re stuck on design decisions, transport quirks, or schema questions. We’d rather collaborate early than rework later.

README.md

@@ -16,13 +16,13 @@ pip install agent-client-protocol
 uv add agent-client-protocol
 ```
 
-## Why teams adopt this SDK
+## At a glance
 
-- **Schema parity:** Generated Pydantic models in `acp.schema` stay pinned to the official ACP specification so payloads stay valid as the protocol evolves.
-- **Runtime ergonomics:** Async base classes, stdio JSON-RPC plumbing, and lifecycle helpers keep custom agents focused on behaviour, not wiring.
-- **Batteries included:** `examples/` cover streaming, permission flows, file access, Gemini CLI bridging, and embedded agent/client launches.
-- **Helper builders:** `acp.helpers` mirrors the Go/TS SDK convenience APIs for content blocks, tool calls, and session updates.
-- **Contrib patterns:** `acp.contrib` packages in-progress utilities (session accumulators, permission brokers, tool call trackers) harvested from reference integrations.
+- **Spec parity:** Generated Pydantic models in `acp.schema` track every ACP release so payloads stay valid.
+- **Runtime ergonomics:** Async base classes, stdio JSON-RPC plumbing, and lifecycle helpers keep custom agents tiny.
+- **Examples ready:** Streaming, permissions, Gemini bridge, and duet demos live under `examples/`.
+- **Helper builders:** `acp.helpers` mirrors the Go/TS SDK APIs for content blocks, tool calls, and session updates.
+- **Contrib utilities:** Session accumulators, tool call trackers, and permission brokers share patterns from real deployments.
 
 ## Who benefits
 
@@ -37,26 +37,28 @@ See real adopters like kimi-cli in the [Use Cases list](https://agentclientproto
 - Browse the [example gallery](https://github.com/agentclientprotocol/python-sdk/tree/main/examples) to see progressively richer integrations you can copy or extend.
 - Skim the [docs hub](https://agentclientprotocol.github.io/python-sdk/) for focused references on contrib helpers, releasing, and transport details.
 
-## Resource map
+## Quick links
 
-- Docs hub: https://agentclientprotocol.github.io/python-sdk/
-- PyPI package: https://pypi.org/project/agent-client-protocol/
-- Quickstart: https://agentclientprotocol.github.io/python-sdk/quickstart/
-- Use Cases: https://agentclientprotocol.github.io/python-sdk/use-cases/
-- Contrib overview: https://agentclientprotocol.github.io/python-sdk/experimental-contrib/
-- Releasing workflow: https://agentclientprotocol.github.io/python-sdk/releasing/
-- Examples: https://github.com/agentclientprotocol/python-sdk/tree/main/examples (echo agent, richer agent, duet, client, Gemini bridge)
-- Tests: https://github.com/agentclientprotocol/python-sdk/tree/main/tests with pytest coverage and opt-in Gemini smoke checks (`ACP_ENABLE_GEMINI_TESTS=1`)
+| Need | Link |
+| --- | --- |
+| Docs hub | https://agentclientprotocol.github.io/python-sdk/ |
+| Quickstart | https://agentclientprotocol.github.io/python-sdk/quickstart/ |
+| Use cases | https://agentclientprotocol.github.io/python-sdk/use-cases/ |
+| Contrib helpers | https://agentclientprotocol.github.io/python-sdk/experimental-contrib/ |
+| Releasing workflow | https://agentclientprotocol.github.io/python-sdk/releasing/ |
+| Examples | https://github.com/agentclientprotocol/python-sdk/tree/main/examples |
+| Tests | https://github.com/agentclientprotocol/python-sdk/tree/main/tests |
+| PyPI | https://pypi.org/project/agent-client-protocol/ |
 
-## Repository tour
+## Project layout
 
 - `src/acp/`: runtime package (agents, clients, transports, helpers, schema bindings, contrib utilities)
 - `schema/`: upstream JSON schema sources (regenerate via `make gen-all`)
 - `docs/`: MkDocs content backing the published documentation
 - `examples/`: runnable scripts covering stdio orchestration patterns
 - `tests/`: pytest suite with golden fixtures and optional Gemini coverage
 
-## Development workflow
+## Developer commands
 
 - `make install` provisions the `uv` virtualenv and installs pre-commit hooks.
 - `make check` runs Ruff formatting/linting, type analysis, dependency hygiene, and lock verification.