*: polish docs with real use case and add a maker file for typing hint

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,69 @@
+name: Bug Report
+description: Tell us about a regression or defect in the ACP Python SDK.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thanks for filing a detailed bug. Fill out every section so we can
+        reproduce the issue quickly and keep the SDK solid.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong? Keep it short but specific.
+      placeholder: "Streaming updates stop after the second prompt…"
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: >
+        Commands, code, or payloads that trigger the bug. Include any relevant
+        input files or snippets (redact secrets).
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result
+      placeholder: "Tool call should finish and emit a completed status…"
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual result
+      placeholder: "Agent hangs and no further session/update payloads arrive…"
+    validations:
+      required: true
+
+  - type: input
+    id: versions
+    attributes:
+      label: Versions / environment
+      description: >
+        Include SDK version, ACP schema tag (if pinned), Python version, and OS.
+      placeholder: "sdk 0.5.1 (schema v0.4.7), Python 3.12.2 on macOS 14.4"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs & screenshots
+      description: Paste relevant stack traces, JSON snippets, or console output.
+      render: shell
+
+  - type: checkboxes
+    id: willing-to-pr
+    attributes:
+      label: Open to submitting a fix?
+      options:
+        - label: I’m willing to open a PR for this bug.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question
+    url: https://github.com/agentclientprotocol/python-sdk/discussions/new?category=q-a
+    about: Usage questions, architecture ideas, and doc clarifications live best in Discussions.
+  - name: Read the docs
+    url: https://agentclientprotocol.github.io/python-sdk/
+    about: The published docs cover quickstart steps, contrib helpers, and release workflows.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,50 @@
+name: Feature Request
+description: Pitch an improvement for the ACP Python SDK docs, runtime, or tooling.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Feature requests work best when they focus on the problem first. Tell us
+        what you’re trying to achieve and why existing APIs aren’t enough.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: >
+        What use case is blocked? Include relevant transports, helpers, or user
+        journeys.
+      placeholder: "Need a helper to batch tool call updates when streaming…"
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: >
+        Sketch the API or behaviour you’d like to see. Code snippets welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: >
+        Mention workarounds you’ve tried or other approaches we should weigh.
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Links, screenshots, related issues, etc.
+
+  - type: checkboxes
+    id: willing-to-help
+    attributes:
+      label: Can you help build it?
+      options:
+        - label: I can contribute code or docs for this request.

.github/pull_request_template.md

@@ -0,0 +1,35 @@
+## Summary
+
+<!-- What does this change do? Keep it short. -->
+
+
+## Related issues
+
+<!--
+Link the tracked issue(s) using the GitHub syntax, e.g. "Closes #123".
+If the work only partially addresses an issue, use "Relates to #123".
+-->
+
+
+## Testing
+
+<!--
+List the checks you ran (e.g. `make check`, `make test`, targeted pytest files, manual CLI steps).
+Include output snippets when helpful.
+-->
+
+
+## Docs & screenshots
+
+<!--
+Note any documentation or example updates included (or explain why none are needed).
+Attach screenshots/GIFs when the change affects UX.
+-->
+
+
+## Checklist
+
+- [ ] Conventional Commit title (e.g. `feat:`, `fix:`).
+- [ ] Tests cover the change or are not required (explain above).
+- [ ] Docs/examples updated when behaviour is user-facing.
+- [ ] Schema regenerations (`make gen-all`) are called out if applicable.

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.