acpkit 0.4.2__tar.gz → 0.5.0__tar.gz

acpkit-0.5.0/.agents/skills/acpkit-sdk/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: acpkit-sdk
+description: Use for ACP Kit SDK work that turns an existing agent surface into a truthful ACP server through acpkit, pydantic-acp, and the maintained docs/examples.
+---
+
+# ACP Kit SDK
+
+Use this skill when the task is about ACP Kit’s actual SDK surface rather than generic ACP theory.
+
+ACP Kit’s primary job is to take an existing agent surface, usually a `pydantic_ai.Agent`, and expose it as an ACP server boundary without fabricating runtime state the source agent cannot really honor.
+
+This file is the lightweight orchestration entrypoint. The repo-root `SKILL.md` is the longform one-file reference.
+
+Typical triggers:
+
+- `acpkit` CLI target resolution or launch behavior
+- `pydantic-acp` runtime behavior, extension seams, or examples
+- `codex-auth-helper`
+- SDK documentation, examples, and guides that must match the current implementation
+
+## Start Here
+
+Read [resources/intro.md](resources/intro.md) first.
+
+When you need the docs map or the full docs corpus in one place, read `https://vcoderun.github.io/acpkit/llms.txt` or `https://vcoderun.github.io/acpkit/llms-full.txt`.
+
+That file explains:
+
+- what ACP Kit currently ships
+- which seam to use (`run_acp`, `create_acp_agent`, providers, bridges, `AgentSource`)
+- what the adapter can actually do today
+- the current guardrails that often matter in real tasks
+
+## Load Only The References You Need
+
+- Public imports, package map, and canonical names:
+  [references/package-surface.md](references/package-surface.md)
+- Runtime semantics, session behavior, plans, approvals, slash commands, MCP, projections:
+  [references/runtime-capabilities.md](references/runtime-capabilities.md)
+- Docs pages, maintained examples, and showcase mapping:
+  [references/docs-examples-map.md](references/docs-examples-map.md)
+
+## Utility Scripts
+
+Use the bundled scripts instead of guessing:
+
+- `python3.11 .agents/skills/acpkit-sdk/scripts/list_public_exports.py`
+- `python3.11 .agents/skills/acpkit-sdk/scripts/list_examples.py`
+
+## Working Rules
+
+- Prefer current code over stale memory.
+- If docs and code disagree, trust code first and update docs.
+- Do not invent ACP surface the runtime cannot actually honor.
+- Keep examples runnable, explicit, and strongly typed.
+- `FileSessionStore` uses `root=Path(...)`.
+- Mode slash commands are dynamic, and mode ids must not collide with reserved names such as `model`, `thinking`, `tools`, `hooks`, or `mcp-servers`.

acpkit-0.5.0/.agents/skills/acpkit-sdk/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "ACP Kit SDK"
+  short_description: "Turn agent surfaces into ACP servers"
+  default_prompt: "Use $acpkit-sdk to update ACP Kit code, examples, or docs for turning an existing agent surface into a truthful ACP server."
+
+policy:
+  allow_implicit_invocation: true

acpkit-0.5.0/.agents/skills/acpkit-sdk/resources/intro.md

@@ -0,0 +1,79 @@
+# ACP Kit SDK Intro
+
+ACP Kit is a Python SDK and CLI for turning an existing agent surface into a truthful ACP server boundary.
+
+Today that mostly means exposing `pydantic_ai.Agent` through `pydantic-acp`, while keeping models, modes, plans, approvals, MCP metadata, host tools, and session state aligned with what the underlying runtime can actually support.
+
+This intro is intentionally short. The canonical deep references should come from the docs set in `docs/`, not from a second parallel skill-specific spec.
+
+## Core Positioning
+
+ACP Kit is not a new agent framework.
+
+It sits between:
+
+- an existing agent runtime
+- ACP clients such as editors and host applications
+
+The central contract is:
+
+> expose ACP state only when the underlying runtime can actually honor it.
+
+That rule drives model selection, mode switching, slash commands, native plan state, approval flow, MCP metadata, and host-backed tooling.
+
+## Start With The Real Docs
+
+Published docs base URL:
+
+- `https://vcoderun.github.io/acpkit/`
+
+Use these docs pages as the primary references:
+
+| Need | Local source | Published docs |
+| --- | --- | --- |
+| Product overview and package map | `docs/index.md` | `https://vcoderun.github.io/acpkit/` |
+| Construction seams and adapter overview | `docs/pydantic-acp.md` | `https://vcoderun.github.io/acpkit/pydantic-acp/` |
+| Runtime config and session ownership | `docs/pydantic-acp/adapter-config.md` | `https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config/` |
+| Models, modes, slash commands, thinking | `docs/pydantic-acp/runtime-controls.md` | `https://vcoderun.github.io/acpkit/pydantic-acp/runtime-controls/` |
+| Plans, approvals, and cancellation | `docs/pydantic-acp/plans-thinking-approvals.md` | `https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/` |
+| Host-owned state patterns | `docs/providers.md` | `https://vcoderun.github.io/acpkit/providers/` |
+| ACP-visible extension seams | `docs/bridges.md` | `https://vcoderun.github.io/acpkit/bridges/` |
+| Host-backed tools and projections | `docs/host-backends.md` | `https://vcoderun.github.io/acpkit/host-backends/` |
+| Maintained example ladder | `docs/examples/index.md` | `https://vcoderun.github.io/acpkit/examples/` |
+| Production showcase | `docs/examples/workspace-agent.md` | `https://vcoderun.github.io/acpkit/examples/workspace-agent/` |
+| API surface | `docs/api/pydantic_acp.md` | `https://vcoderun.github.io/acpkit/api/pydantic_acp/` |
+
+## Construction Seams To Reach For
+
+Use these seams intentionally:
+
+| Seam | Use it when |
+| --- | --- |
+| `run_acp(agent=...)` | you want the smallest direct path from `pydantic_ai.Agent` to a running ACP server |
+| `create_acp_agent(...)` | you need the ACP-compatible agent object before running it |
+| `agent_factory=` | session context should influence agent construction, but a full custom source is unnecessary |
+| `agent_source=` | you need full control over agent build path, host binding, and session-specific dependencies |
+| built-in `AdapterConfig` fields | the adapter can own the relevant session state cleanly |
+| providers | the host or product layer should remain the source of truth |
+| bridges | the runtime needs ACP-visible capabilities without hard-coding them into the adapter core |
+
+## High-Value Guardrails
+
+- `FileSessionStore` takes `root=Path(...)`, not `base_dir=...`
+- slash mode commands are dynamic; `ask`, `plan`, and `agent` are examples, not built-in global names
+- mode ids must not collide with reserved slash command names like `model`, `thinking`, `tools`, `hooks`, or `mcp-servers`
+- only one `PrepareToolsMode(..., plan_mode=True)` is allowed
+- `plan_tools=True` is how a non-plan execution mode keeps plan progress tools visible
+- `/thinking` only exists when `ThinkingBridge()` is configured
+- native ACP plan state and `PlanProvider` are separate ownership paths
+- `HookBridge(hide_all=True)` suppresses hook listing output, not the underlying hook capability itself
+
+## Reference Files In This Skill
+
+These skill-local references are only routing aids back into the docs:
+
+- `references/package-surface.md`
+- `references/runtime-capabilities.md`
+- `references/docs-examples-map.md`
+
+Use them to find the right docs page quickly, not as independent source-of-truth specs.

acpkit-0.5.0/.agents/skills/acpkit-sdk/scripts/list_examples.py

@@ -0,0 +1,32 @@
+from __future__ import annotations as _annotations
+
+from pathlib import Path
+
+_EXAMPLE_DESCRIPTIONS = {
+    "approvals.py": "native deferred approval flow",
+    "bridges.py": "bridge builder and ACP-visible capabilities",
+    "factory_agent.py": "session-aware factory plus session-local model selection",
+    "hook_projection.py": "hook event labels and visibility controls",
+    "host_context.py": "client-backed filesystem and terminal helpers",
+    "providers.py": "host-owned models, modes, config, plan state, and approval metadata",
+    "static_agent.py": "smallest possible run_acp(agent=...) integration",
+    "strong_agent.py": "full workspace coding-agent showcase",
+    "strong_agent_v2.py": "alternative workspace integration shape",
+}
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[4]
+
+
+def main() -> None:
+    examples_dir = _repo_root() / "examples" / "pydantic"
+    for example_path in sorted(examples_dir.glob("*.py")):
+        if example_path.name == "__init__.py":
+            continue
+        description = _EXAMPLE_DESCRIPTIONS.get(example_path.name, "no mapped description")
+        print(f"{example_path.relative_to(_repo_root())}: {description}")
+
+
+if __name__ == "__main__":
+    main()

acpkit-0.5.0/.agents/skills/acpkit-sdk/scripts/list_public_exports.py

@@ -0,0 +1,52 @@
+from __future__ import annotations as _annotations
+
+import ast
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[4]
+
+
+def _extract_exports(module_path: Path) -> tuple[str, ...]:
+    module = ast.parse(module_path.read_text(encoding="utf-8"))
+    for node in module.body:
+        if isinstance(node, ast.Assign):
+            if len(node.targets) != 1:
+                continue
+            target = node.targets[0]
+            if isinstance(target, ast.Name) and target.id == "__all__":
+                value = ast.literal_eval(node.value)
+                if isinstance(value, tuple | list) and all(isinstance(item, str) for item in value):
+                    return tuple(value)
+    raise ValueError(f"Could not locate __all__ in {module_path}")
+
+
+def main() -> None:
+    root = _repo_root()
+    module_paths = {
+        "acpkit": root / "src" / "acpkit" / "__init__.py",
+        "pydantic_acp": root
+        / "packages"
+        / "adapters"
+        / "pydantic-acp"
+        / "src"
+        / "pydantic_acp"
+        / "__init__.py",
+        "codex_auth_helper": root
+        / "packages"
+        / "helpers"
+        / "codex-auth-helper"
+        / "src"
+        / "codex_auth_helper"
+        / "__init__.py",
+    }
+    for package_name, module_path in module_paths.items():
+        print(f"[{package_name}]")
+        for export_name in _extract_exports(module_path):
+            print(f"- {export_name}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

{acpkit-0.4.2 → acpkit-0.5.0}/.github/workflows/docs.yml

@@ -25,9 +25,9 @@ jobs:
       - name: Install dependencies
         run: |
           uv venv
-          uv pip install -e ".[docs]"
+          uv pip install -e ".[docs,pydantic,codex]"
 
       - name: Deploy MkDocs
         run: |
           source .venv/bin/activate
-          mkdocs gh-deploy --force
+          mkdocs gh-deploy --force --strict

{acpkit-0.4.2 → acpkit-0.5.0}/.gitignore

@@ -54,6 +54,7 @@ htmlcov/
 .Python
 build/
 dist/
+site/
 *.egg-info/
 tmp/
 
@@ -65,15 +66,17 @@ uv.lock
 
 # Specs
 references
-pydantic-acp.md
+/pydantic-acp.md
 AGENTS.md
 SPEC.md
-AGENTS.md
-AGENTS.md
-AGENTS.md
+
+# Sessions
+.acp-sessions/
+.demo-sessions/
 
 # Temporary
 tmp
 *.snapshot
 bump.sh
 local.sh
+coverage.json

acpkit-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+default_install_hook_types: [pre-commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+        args: [--unsafe]
+        stages: [pre-commit, pre-push]
+      - id: check-toml
+        stages: [pre-commit, pre-push]
+
+  - repo: local
+    hooks:
+      - id: check-coverage
+        name: check coverage thresholds for major changes
+        entry: python3.11 scripts/run_if_major_change.py --stage pre-commit -- make check-coverage
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+      - id: make-prod
+        name: verify build for major changes
+        entry: python3.11 scripts/run_if_major_change.py --stage pre-commit -- make prod
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]

acpkit-0.5.0/COVERAGE

@@ -0,0 +1,2 @@
+Line coverage: 97.89% (3519 / 3566)
+Branch coverage: 95.55% (1160 / 1214)

{acpkit-0.4.2 → acpkit-0.5.0}/Makefile

@@ -3,7 +3,7 @@ GREEN := \033[1;32m
 RESET := \033[0m
 PYTHON_VERSIONS := 3.11.13 3.12.10 3.13.9
 
-.PHONY: tests format check-formatted check check-matrix all prod rename serve
+.PHONY: tests coverage-branch check-coverage save-coverage format check-formatted check check-matrix all prod rename serve
 
 # Hack to allow passing arguments to make commands (e.g. make rename my_project)
 ifeq (rename,$(firstword $(MAKECMDGOALS)))
@@ -47,7 +47,7 @@ check-matrix:
 		printf "$(BLUE)==>$(RESET) Running validation matrix for Python $$version...\n"; \
 		uv run --extra dev --python $$version ruff check src/acpkit tests || exit $$?; \
 		uv run --extra dev --python $$version ty check --python-version $$short_version || exit $$?; \
-		uv run --extra dev --python $$version basedpyright --pythonversion $$short_version || exit $$?; \
+		uv run --extra dev --python $$version python -m basedpyright --pythonversion $$short_version src packages tests || exit $$?; \
 	done
 	@printf "$(GREEN)✔ Matrix checking complete.$(RESET)\n"
 
@@ -56,10 +56,36 @@ tests:
 	@uv run --extra dev pytest
 	@printf "$(GREEN)✔ Tests complete.$(RESET)\n"
 
+coverage-branch:
+	@printf "$(BLUE)==>$(RESET) Running branch coverage for pydantic-acp...\n"
+	@uv run --extra dev pytest -p pytest_cov tests/pydantic tests/test_acpkit_cli.py tests/test_native_pydantic_agent.py --cov=packages/adapters/pydantic-acp/src/pydantic_acp --cov-branch --cov-report=json -q
+	@printf "$(GREEN)✔ Branch coverage complete. See coverage.json.$(RESET)\n"
+
+check-coverage:
+	@printf "$(BLUE)==>$(RESET) Checking line and branch coverage thresholds for pydantic-acp...\n"
+	@set -e; \
+		tmp_file=$$(mktemp -t acpkit-coverage); \
+		trap 'rm -f "$$tmp_file"' EXIT; \
+		uv run --extra dev pytest -p pytest_cov tests/pydantic tests/test_acpkit_cli.py tests/test_native_pydantic_agent.py --cov=packages/adapters/pydantic-acp/src/pydantic_acp --cov-branch --cov-report=json:$$tmp_file -q; \
+		uv run --extra dev python scripts/save_coverage_summary.py --input "$$tmp_file" --check-only
+	@printf "$(GREEN)✔ Coverage thresholds satisfied.$(RESET)\n"
+
+save-coverage:
+	@printf "$(BLUE)==>$(RESET) Running line and branch coverage for pydantic-acp...\n"
+	@uv run --extra dev pytest -p pytest_cov tests/pydantic tests/test_acpkit_cli.py tests/test_native_pydantic_agent.py --cov=packages/adapters/pydantic-acp/src/pydantic_acp --cov-branch --cov-report=json -q
+	@printf "$(BLUE)==>$(RESET) Saving coverage summary to COVERAGE...\n"
+	@uv run --extra dev python scripts/save_coverage_summary.py
+	@printf "$(GREEN)✔ Coverage summary written to COVERAGE.$(RESET)\n"
+
 serve:
 	@printf "$(BLUE)==>$(RESET) Serving docs with mkdocs...\n"
-	@uv run --extra docs mkdocs serve --dev-addr 127.0.0.1:8080
+	@uv run --extra docs --extra pydantic --extra codex mkdocs serve --dev-addr 127.0.0.1:8080
 
 all: format check
 
 prod: tests format check-matrix
+
+pre-commit:
+	@printf "$(BLUE)==>$(RESET) Running pre-commit checks...\n"
+	@uv run --extra dev pre-commit
+	@printf "$(GREEN)✔ Pre-commit checks complete.$(RESET)\n"

{acpkit-0.4.2 → acpkit-0.5.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: acpkit
-Version: 0.4.2
+Version: 0.5.0
 Summary: ACP Kit provides a common adapter for Agent Frameworks.
 Project-URL: Homepage, https://github.com/vcoderun/acpkit
 Project-URL: Issues, https://github.com/vcoderun/acpkit/issues
 Project-URL: Repository, https://github.com/vcoderun/acpkit
-License: MIT
+License: Apache 2.0
 License-File: LICENSE
 Keywords: acp,agents,protocol,pydantic-ai
 Classifier: Development Status :: 3 - Alpha
@@ -65,12 +65,18 @@ Description-Content-Type: text/markdown
 
 # ACP Kit
 
-ACP Kit is a monorepo for ACP-facing agent runtime packages.
+ACP Kit is a Python SDK and CLI for turning an existing agent surface into a truthful ACP server.
 
 - `acpkit` is the root CLI and target resolver
 - `pydantic-acp` adapts `pydantic_ai.Agent` instances to ACP
 - `codex-auth-helper` turns a local Codex login into a `pydantic-ai` Responses model
 
+ACP Kit is not a new agent framework. The core use case is:
+
+1. keep your current agent surface
+2. expose it through ACP without rewriting the agent
+3. only publish models, modes, plans, approvals, MCP metadata, and host tools that the runtime can actually honor
+
 The core workflow is simple:
 
 1. build a normal `pydantic_ai.Agent`
@@ -79,36 +85,45 @@ The core workflow is simple:
 
 ## Installation
 
-Production:
-
 ```bash
+# production
 uv pip install "acpkit[pydantic]"
-```
 
-```bash
-pip install "acpkit[pydantic]"
+# production with acpkit launch support
+uv pip install "acpkit[pydantic,launch]"
+
+# development
+uv pip install -e ".[dev,docs,pydantic]"
 ```
 
-To use `acpkit launch ...`, install the optional launch extra:
+## ACP Kit Skill
 
-```bash
-uv pip install "acpkit[launch]"
-```
+This repo also ships an `acpkit-sdk` skill package for Codex.
 
-```bash
-pip install "acpkit[launch]"
-```
+Use it when you want Codex to help integrate ACP into an existing agent surface, especially for:
 
-Development:
+- exposing an existing `pydantic_ai.Agent` through ACP
+- choosing between `run_acp(...)`, `create_acp_agent(...)`, providers, bridges, and `AgentSource`
+- wiring plans, approvals, session stores, thinking, MCP metadata, and host-backed tools
+- keeping docs and examples aligned with the real SDK surface
 
-```bash
-uv sync --extra dev --extra docs --extra pydantic
-```
+From a checkout of this repo, install the skill with Unix commands:
 
 ```bash
-pip install -e ".[dev,docs,pydantic]"
+mkdir -p "$HOME/.codex/skills/acpkit-sdk" \
+  && cp -R .agents/skills/acpkit-sdk/. "$HOME/.codex/skills/acpkit-sdk/"
 ```
 
+The repo keeps two forms of the skill:
+
+- [`SKILL.md`](https://github.com/vcoderun/acpkit/blob/main/SKILL.md): longform, one-file SDK reference
+- [`.agents/skills/acpkit-sdk/`](https://github.com/vcoderun/acpkit/tree/main/.agents/skills/acpkit-sdk): packaged orchestration skill for Codex
+
+Example prompts:
+
+- `Use $acpkit-sdk to expose my existing pydantic_ai.Agent through ACP.`
+- `Use $acpkit-sdk to add ACP plans, approvals, and slash-command mode switching to this agent.`
+
 ## CLI
 
 Run a supported agent target through ACP:
@@ -241,7 +256,7 @@ config = AdapterConfig(
             override="openai:gpt-5",
         ),
     ],
-    session_store=FileSessionStore(base_dir=Path(".acp-sessions")),
+    session_store=FileSessionStore(root=Path(".acp-sessions")),
     approval_bridge=NativeApprovalBridge(enable_persistent_choices=True),
 )
 
@@ -313,7 +328,7 @@ When the session is in `plan` mode, the adapter:
 - `plan_md: str` — optional markdown representation
 
 Native plan state and `plan_provider` are mutually exclusive. See
-[docs/providers.md](https://github.com/vcoderun/acpkit/blob/main/docs/providers.md) for full
+[Providers](https://vcoderun.github.io/acpkit/providers/) for full
 details.
 
 ## Agent Factories
@@ -368,7 +383,7 @@ agent = Agent("openai:gpt-5", name="persistent-agent")
 run_acp(
     agent=agent,
     config=AdapterConfig(
-        session_store=FileSessionStore(base_dir=Path(".acp-sessions")),
+        session_store=FileSessionStore(root=Path(".acp-sessions")),
     ),
 )
 ```
@@ -491,7 +506,7 @@ Built-in bridges cover:
 - `McpBridge`
 - `AgentBridgeBuilder`
 
-See [docs/bridges.md](https://github.com/vcoderun/acpkit/blob/main/docs/bridges.md) for the full bridge model.
+See [Bridges](https://vcoderun.github.io/acpkit/bridges/) for the full bridge model.
 
 ## Providers
 
@@ -503,7 +518,7 @@ Providers let the host own session state while the adapter exposes it through AC
 - `PlanProvider`
 - `ApprovalStateProvider`
 
-See [docs/providers.md](https://github.com/vcoderun/acpkit/blob/main/docs/providers.md) for full details.
+See [Providers](https://vcoderun.github.io/acpkit/providers/) for full details.
 
 ## Host Backends
 
@@ -528,8 +543,8 @@ def build_agent(client: AcpClient, session: AcpSessionContext) -> Agent[None, st
     return agent
 ```
 
-See [docs/host-backends.md](https://github.com/vcoderun/acpkit/blob/main/docs/host-backends.md) for the filesystem
-and terminal API surface.
+See [Host Backends And Projections](https://vcoderun.github.io/acpkit/host-backends/) for the
+filesystem and terminal API surface.
 
 ## Codex Auth Helper
 
@@ -543,7 +558,7 @@ from codex_auth_helper import create_codex_responses_model
 agent = Agent(create_codex_responses_model("gpt-5.4"))
 ```
 
-See [docs/helpers.md](https://github.com/vcoderun/acpkit/blob/main/docs/helpers.md) for helper package details.
+See [Helpers](https://vcoderun.github.io/acpkit/helpers/) for helper package details.
 
 ## Examples
 
@@ -571,11 +586,9 @@ Runnable and focused examples live under [examples/pydantic](https://github.com/
 Canonical local checks:
 
 ```bash
-uv run ruff check
-uv run ty check
-uv run basedpyright
 make tests
 make check
+make save-coverage
 ```
 
 Preview the docs locally:
@@ -586,14 +599,20 @@ make serve
 
 ## Documentation Map
 
-- [docs/index.md](https://github.com/vcoderun/acpkit/blob/main/docs/index.md): workspace overview and package map
-- [docs/cli.md](https://github.com/vcoderun/acpkit/blob/main/docs/cli.md): root `acpkit` CLI behavior
-- [docs/pydantic-acp.md](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp.md): adapter API, runtime controls, approvals, projection maps, providers, and host backends
-- [docs/bridges.md](https://github.com/vcoderun/acpkit/blob/main/docs/bridges.md): capability bridges and hook rendering
-- [docs/providers.md](https://github.com/vcoderun/acpkit/blob/main/docs/providers.md): provider seams and host-owned state
-- [docs/host-backends.md](https://github.com/vcoderun/acpkit/blob/main/docs/host-backends.md): client filesystem and terminal helpers
-- [docs/helpers.md](https://github.com/vcoderun/acpkit/blob/main/docs/helpers.md): helper packages including `codex-auth-helper`
-- [docs/testing.md](https://github.com/vcoderun/acpkit/blob/main/docs/testing.md): behavioral test surface and validation commands
+- [ACP Kit](https://vcoderun.github.io/acpkit/): landing page and package overview
+- [Installation](https://vcoderun.github.io/acpkit/getting-started/installation/): install paths and validation workflow
+- [Quickstart](https://vcoderun.github.io/acpkit/getting-started/quickstart/): first ACP server in a few steps
+- [CLI](https://vcoderun.github.io/acpkit/cli/): root `acpkit` CLI behavior
+- [Pydantic ACP Overview](https://vcoderun.github.io/acpkit/pydantic-acp/): adapter architecture and entry points
+- [AdapterConfig](https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config/): full `AdapterConfig` guide
+- [Models, Modes, and Slash Commands](https://vcoderun.github.io/acpkit/pydantic-acp/runtime-controls/): models, modes, slash commands, and thinking
+- [Plans, Thinking, and Approvals](https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/): ACP planning, reasoning effort, and approval flow
+- [Providers](https://vcoderun.github.io/acpkit/providers/): provider seams and host-owned state
+- [Bridges](https://vcoderun.github.io/acpkit/bridges/): capability bridges and bridge builder usage
+- [Host Backends And Projections](https://vcoderun.github.io/acpkit/host-backends/): client filesystem, terminal helpers, and projections
+- [Helpers](https://vcoderun.github.io/acpkit/helpers/): helper packages including `codex-auth-helper`
+- [Workspace Agent](https://vcoderun.github.io/acpkit/examples/workspace-agent/): full coding-agent walkthrough
+- [Testing](https://vcoderun.github.io/acpkit/testing/): behavioral test surface and validation commands
 - [examples/pydantic/README.md](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/README.md): runnable demos and focused SDK examples
 
 ## License