docs: reorganize developer documentation and fix publishing CI

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'src/acp/**'
+      - 'examples/**'
+      - 'README.md'
+      - 'mkdocs.yml'
+      - 'Makefile'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/actions/setup-python-env/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+    steps:
+      - name: Check out
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+      - name: Publish documentation to gh-pages
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin gh-pages:gh-pages --depth=1
+          uv run --frozen mkdocs gh-deploy --strict --remote-branch gh-pages
+      - name: Request a Pages build
+        run: gh api --method POST "repos/$GITHUB_REPOSITORY/pages/builds"
+        env:
+          GH_TOKEN: ${{ github.token }}

.github/workflows/main.yml

@@ -7,6 +7,9 @@ on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
 
+permissions:
+  contents: read
+
 jobs:
   quality:
     runs-on: ubuntu-latest
@@ -67,8 +70,9 @@ jobs:
       - name: Check out
         uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
 
-      - name: Link Checker
+      - name: Check local documentation links
         id: lychee
         uses: lycheeverse/lychee-action@1ef33e2493308e49729a7789ddd73e7f8bed8f45
         with:
-          fail: false
+          args: --offline --include-fragments --no-progress README.md 'docs/**/*.md'
+          fail: true

.github/workflows/on-release-main.yml

@@ -6,12 +6,6 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
 
 jobs:
   set-version:
@@ -21,7 +15,7 @@ jobs:
 
       - name: Export tag
         id: vars
-        run: echo tag=${GITHUB_REF#refs/*/} >> $GITHUB_OUTPUT
+        run: echo "tag=${GITHUB_REF#refs/*/}" >> "$GITHUB_OUTPUT"
         if: ${{ github.event_name == 'release' }}
 
       - name: Update project version
@@ -59,32 +53,3 @@ jobs:
         run: uv publish
         env:
           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
-
-  build-docs:
-    needs: publish
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
-
-      - name: Set up the environment
-        uses: ./.github/actions/setup-python-env
-
-      - name: Build site
-        run: uv run mkdocs build -f mkdocs.yml --clean
-
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
-        with:
-          path: site
-
-  deploy-docs:
-    needs: build-docs
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -214,5 +214,5 @@ __marimo__/
 .zed/
 
 # others
-reference/
+/reference/
 .DS_Store

README.md

@@ -2,74 +2,66 @@
   <img alt="Agent Client Protocol" src="https://zed.dev/img/acp/banner-dark.webp">
 </a>
 
-# Agent Client Protocol (Python)
+# Agent Client Protocol SDK for Python
 
-Build ACP-compliant agents and clients in Python with generated schema models, asyncio transports, and runnable demos.
+Implement ACP agent and client integrations in Python. The SDK provides typed protocol models, asynchronous handler interfaces, and connection helpers. Your application supplies the agent runtime, client callbacks, and session state.
 
-> Releases track the upstream ACP schema; contributions that tighten coverage or tooling are always welcome.
+Requires Python 3.10 through 3.14.
 
 ## Install
 
 ```bash
 pip install agent-client-protocol
-# or
-uv add agent-client-protocol
 ```
 
-## At a glance
+For a project managed with uv:
+
+```bash
+uv add agent-client-protocol
+```
 
-- **Spec parity:** Generated Pydantic models in `acp.schema` track every ACP release so payloads stay valid.
-- **Direct construction:** Generated discriminator fields have defaults, so models can be instantiated directly.
-- **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/`.
-- **Contrib utilities:** Session accumulators, tool call trackers, and permission brokers share patterns from real deployments.
+Import the package as `acp`:
 
-## Who benefits
+```python
+from acp.schema import TextContentBlock
 
-- Agent authors who need typed models and event-stream ergonomics for ACP-compatible assistants.
-- Client integrators embedding ACP parties inside Python applications or wrapping existing CLIs via stdio.
-- Tooling teams experimenting with permission flows, streaming UX, or Gemini bridges without re-implementing transports.
-See real adopters like kimi-cli in the [Use Cases list](https://agentclientprotocol.github.io/python-sdk/use-cases/).
+message = TextContentBlock(text="Hello ACP")
+```
 
-## How to get started
+## Run an agent and client
 
-- Follow the [Quickstart guide](https://agentclientprotocol.github.io/python-sdk/quickstart/) for installation, echo-agent validation, editor wiring (e.g. Zed), and programmatic launch recipes.
-- 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.
+The example client starts the echo agent, sends your message, and prints the streamed reply. Install Git and uv, then run:
 
-## Quick links
+```bash
+git clone https://github.com/agentclientprotocol/python-sdk.git
+cd python-sdk
+uv sync --frozen
+uv run --frozen python examples/client.py python examples/echo_agent.py
+```
 
-| 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/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/>                      |
+Type `Hello ACP` at the prompt. The client starts the agent and prints `| Agent: Hello ACP`. See the [quickstart](https://agentclientprotocol.github.io/python-sdk/tutorials/quickstart/) for the initialization and session calls behind this exchange.
 
-## Project layout
+This runs the checked-out SDK and examples. Installing the package alone does not create an `examples/` directory. The documentation follows `main`, which can include features beyond the latest stable PyPI release.
 
-- `src/acp/`: runtime package (agents, clients, transports, 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
+## Build your integration
 
-## Developer commands
+| Task | Guide |
+| --- | --- |
+| Implement an agent | [Build an agent](https://agentclientprotocol.github.io/python-sdk/tutorials/agent/) |
+| Implement client callbacks and manage an agent process | [Build a client](https://agentclientprotocol.github.io/python-sdk/tutorials/client/) |
+| Handle tool calls and permissions | [Permission guide](https://agentclientprotocol.github.io/python-sdk/how-to/permissions/) |
+| Look up signatures and models | [Core API reference](https://agentclientprotocol.github.io/python-sdk/reference/api/) |
+| Study adapters built with this SDK | [Integration patterns](https://agentclientprotocol.github.io/python-sdk/integrations/) |
 
-- `make install` provisions the `uv` virtualenv and installs pre-commit hooks.
-- `make check` runs Ruff formatting/linting, type analysis, dependency hygiene, and lock verification.
-- `make test` executes `pytest` (with doctests) inside the managed environment.
-- `ACP_SCHEMA_VERSION=<ref> make gen-all` refreshes protocol artifacts when the schema advances.
+Protocol v2, remote transports, and `acp.contrib` are experimental. Check their documentation before depending on their APIs.
 
-Keep docs and examples current whenever you ship public API or transport changes, and prefer Conventional Commits (`feat:`, `fix:`, etc.) when submitting patches.
+## Contribute
 
-## Community & support
+```bash
+make install
+make check
+make test
+make docs-test
+```
 
-- File issues or feature requests at <https://github.com/agentclientprotocol/python-sdk>.
-- Discuss ideas or get help via GitHub Discussions: <https://github.com/agentclientprotocol/python-sdk/discussions>.
-- Join the broader ACP conversations at <https://agentclientprotocol.com/>, the Zed community channels, or the community Zulip: <https://agentclientprotocol.zulipchat.com/>.
-- Shared learnings, integrations, or third-party transports are welcome additions to the documentation—open a PR!
+Report bugs in [GitHub Issues](https://github.com/agentclientprotocol/python-sdk/issues). Include the SDK version, the agent or client you used, and a minimal reproduction. See the [release guide](https://agentclientprotocol.github.io/python-sdk/maintainers/releasing/) for schema regeneration and package publishing.

docs/explanation/lifecycle.md

@@ -0,0 +1,47 @@
+# Roles and session lifecycle
+
+An ACP client starts or connects to an agent, creates sessions, sends prompts, and handles callbacks. The agent owns the work performed for each prompt. An editor is one kind of client; a Python application can be another.
+
+`Agent` and `Client` are typed Protocol interfaces describing handler methods. You may subclass them or provide an object with the corresponding methods. The SDK's connections translate JSON-RPC requests into these handler calls and validate protocol models.
+
+## A v1 exchange
+
+```text
+Client                                    Agent
+  |--- initialize ------------------------->|
+  |<-- protocol version and capabilities ---|
+  |--- session/new ------------------------>|
+  |<-- session ID --------------------------|
+  |--- session/prompt ---------------------->|
+  |<-- session/update (text, tools, ...) ----|
+  |<-- more session/update notifications ----|
+  |<-- prompt response with stop_reason -----|
+```
+
+The client sends its latest supported major protocol version. The agent returns that version if supported, or its latest supported version. A client that cannot use the selected version closes the connection. Omitted optional capabilities mean unsupported. These are application obligations in the v1 runtime; the connection helpers do not choose capabilities or reject a negotiated version for you. See the protocol's [initialization contract](https://agentclientprotocol.com/protocol/v1/initialization).
+
+The client may need to authenticate before creating a session. A session has an ID and an absolute working directory; prompts and updates refer to that ID. Agents support text and resource links as baseline prompt content. Images, audio, and embedded resources depend on the agent's advertised prompt capabilities.
+
+In v1, `prompt()` waits for the turn's response. Text and tool activity arrive separately through `session_update()`. Register callbacks before opening a session, and use the update's type to decide how to display it. The final `PromptResponse` reports why the turn stopped; it does not contain the streamed answer text.
+
+A session can contain several prompt turns. Keeping a connection open does not automatically provide conversation storage or support for loading a previous session. Implement those behaviors in the agent and advertise the corresponding capabilities.
+
+Updates can also arrive outside a prompt turn, for example when the agent advertises commands or replays a loaded session. Install update handlers before opening sessions and allow the first update for a session ID to create its state entry. See [prompt turns](https://agentclientprotocol.com/protocol/v1/prompt-turn) and [session setup](https://agentclientprotocol.com/protocol/v1/session-setup).
+
+## Requests can travel in both directions
+
+While processing a prompt, an agent can ask the client to read a file, run a terminal command, or request user approval. The client advertises the filesystem and terminal services it implements. Tool call notifications describe activity; permission requests ask for a decision. Those are separate messages.
+
+The client and agent each need handlers for the methods their peer will call. Implement every capability your application advertises. The [API reference](../reference/api.md) gives the signatures, and the [permission guide](../how-to/permissions.md) shows how to interpret a decision.
+
+## Cancel a turn
+
+`await connection.cancel(session_id=session_id)` sends `session/cancel`, a notification with no response. Your agent's `cancel` handler stops the session's active work. The original `prompt` request still completes with `stop_reason="cancelled"`, after cleanup and any final updates. The client continues accepting updates until that response and resolves pending permission requests with a cancellation outcome. This differs from [cancelling an individual JSON-RPC request](../reference/protocol.md#request-cancellation).
+
+## Process and transport lifetime
+
+For stdio, the client normally starts an agent process and connects its stdin/stdout pipes. Agent diagnostics go to stderr. `spawn_agent_process` manages the connection and child-process shutdown inside an async context manager.
+
+HTTP and WebSocket move protocol messages across a network transport while retaining the v1 connection API. Their [transport architecture](transports.md) explains how routing differs from stdio.
+
+The [experimental v2 runtime](../reference/experimental/protocol-v2.md) has a different prompt contract: a response acknowledges the user message rather than waiting for processing to finish. Use its own models and handlers; the v1 flow above does not describe v2 completion.