Align documentation with TypeScript SDK structure

[nficano]

Goal

Align this SDK's docs/ directory with the canonical layout used by the TypeScript SDK. The conceptual pages (getting-started, architecture, transports, guides, etc.) are identical across every SDK. The per-source-unit subdirectory adapts to whatever the language calls its organizational unit — and only exists if this SDK actually has multiple such units.

The TS SDK uses docs/packages/ because it is a TypeScript monorepo with multiple npm packages. Do not blindly copy that name. If this SDK has multiple .NET projects, use docs/projects/. Multiple Gradle modules → docs/modules/. Multiple SwiftPM targets → docs/targets/. One single artifact → omit the subdirectory entirely — there is nothing to mirror.

The TS docs/README.md shape (Start here / Guides / Packages / Reference / Diagrams) is the index template — replace its "Packages" section with whatever this SDK's source-unit name is, or remove it if this SDK has only one artifact.

Current state (python-sdk)

• Numbered structure with extras: 00-overview, 01-quickstart, 02-concepts, 03-features/* (10 files), 04-examples/* (20+ files — biggest collection of any SDK), 05-reference/*, 06-conformance.
• Per-feature pages need folding into spec-aligned guides.
• 04-examples/* is unique to this SDK — TS keeps a single recipes.md; recommend keeping as a docs/recipes/ subdirectory given the volume.
• This SDK ships a single PyPI package (arcp). No multi-package equivalent to mirror.
• Existing related tickets: Add docs/architecture.md #26 (docs/architecture.md).

Target structure

docs/
├── README.md                       # index, links to everything below
├── getting-started.md              # install + minimal client+runtime example
├── architecture.md                 # how the modules fit together (references docs/diagrams/architecture-*.svg)
├── transports.md                   # WebSocket, stdio, in-memory; selection guide
├── cli.md                          # the `arcp` binary (omit only if SDK ships no CLI)
├── recipes.md                      # copy-paste solutions to common problems
├── conformance.md                  # spec coverage by section
├── troubleshooting.md              # error codes + fixes
├── guides/
│   ├── sessions.md                 # spec §6
│   ├── resume.md                   # spec §6.3
│   ├── auth.md                     # spec §6.1
│   ├── jobs.md                     # spec §7
│   ├── job-events.md               # spec §8
│   ├── leases.md                   # spec §9
│   ├── delegation.md               # spec §10
│   ├── observability.md            # spec §11
│   ├── errors.md                   # spec §12
│   └── vendor-extensions.md        # spec §15
└── diagrams/                       # graphviz sources + rendered light/dark SVGs

Per-source-unit pages

N/A — no subdirectory. This SDK has one PyPI package, so there is nothing to mirror. Document the public sub-module surface (arcp.client, arcp.runtime, arcp.middleware) inside docs/architecture.md and in the relevant guides; do not invent a docs/packages/ directory just to fill a slot.

Internal underscore-prefixed modules (_auth, _messages, _runtime, etc.) are implementation detail and should not be documented as public surfaces.

Authoring rules

• Guides are spec-aligned, not feature-aligned. If the SDK currently has features/heartbeat.md, features/ack.md, etc., fold them into guides/job-events.md. If it has features/cost-budget.md, fold into guides/jobs.md (or its own guides/budgets.md only if it would otherwise be >2 screens).
• docs/README.md is the index. Four sections (or three if no multi-artifact split): Start here, Guides, (if applicable), Reference. No content lives only in the index.
• Diagrams use <picture> with prefers-color-scheme and ship both light + dark SVGs. Reference the architecture diagram from docs/README.md and docs/architecture.md.
• Spec links point at ../../spec/docs/draft-arcp-1.1.md#section so they survive renames.
• No orphan pages. Anything not linked from docs/README.md must be deleted or linked.
• CONFORMANCE.md at repo root stays authoritative; docs/conformance.md summarizes + links to it.

Migration map

• 00-overview.md → docs/README.md
• 01-quickstart.md → docs/getting-started.md
• 02-concepts.md → docs/architecture.md (closes Add docs/architecture.md #26)
• 03-features/heartbeats.md, event-ack.md, progress.md, result-chunk.md, subscribe.md, capability-negotiation.md → fold into docs/guides/job-events.md (+ architecture for capability-negotiation)
• 03-features/cost-budget.md → docs/guides/jobs.md
• 03-features/agent-versions.md → docs/architecture.md (Versioning)
• 03-features/lease-expires-at.md → docs/guides/leases.md
• 03-features/list-jobs.md → docs/guides/jobs.md
• 04-examples/* (20+ pages) → keep as docs/recipes/ subdirectory with docs/recipes.md as index (TS-style single-file recipes won't scale here)
• 05-reference/arcp-client.md, arcp-runtime.md, middleware-aiohttp.md, middleware-asgi.md, middleware-otel.md, transport.md, job-context.md → fold their content into docs/architecture.md (API tour section) and the relevant guides
• 05-reference/errors.md → docs/guides/errors.md
• 06-conformance.md → docs/conformance.md
• Create new: docs/transports.md, docs/cli.md, docs/troubleshooting.md, docs/guides/{sessions,resume,auth,jobs,delegation,observability,vendor-extensions}.md

Acceptance

• Every conceptual file in the target structure exists (except cli.md if this SDK truly has no CLI — note the omission in docs/README.md)
• docs/README.md matches the four-section shape of TS docs/README.md, substituting this SDK's source-unit term (or omitting that section entirely if single-artifact)
• Every page is linked from docs/README.md; no orphans
• Old feature-shaped pages (features/*, concepts/*, numeric NN-*.md) deleted or merged into canonical pages
• Diagrams use <picture> light/dark and render on GitHub

Closes / supersedes

• Subsumes Add docs/architecture.md #26 (docs/architecture.md)

Reference

• TS SDK docs tree: https://github.com/agentruntimecontrolprotocol/typescript-sdk/tree/main/docs
• TS docs/README.md (index shape to copy, minus the language-specific "Packages" wording): https://github.com/agentruntimecontrolprotocol/typescript-sdk/blob/main/docs/README.md
• Spec: ../spec/docs/draft-arcp-1.1.md