[codex] add SDK integration guide pages

[calvin-archastro]

What Changed

Adds higher-level Python SDK guide pages alongside the generated pdoc API reference so readers do not land directly in the module index. The docs build now renders authored guide markdown into static pages, and the root README links to the hosted docs and guide entry points.

The guide content covers authentication, sync and async client setup, common integration scenarios, and where to pivot into the generated method reference.

Diagrams

sequenceDiagram
  participant Reader as SDK user
  participant Guides as Guide pages
  participant SDK as Python SDK
  participant API as ArchAstro Platform API
  participant Ref as Generated API reference
  Reader->>Guides: Choose auth or scenario guide
  Guides->>SDK: Copy verified snippet
  SDK->>API: Call users teams or agents
  API-->>SDK: Return typed response
  SDK-->>Reader: Expose typed object
  Reader->>Ref: Look up exact methods and fields

Loading

No class diagram is included because this is a docs-only PR and does not add or restructure runtime types.

Scope Indicator

Documentation-only for the Python SDK docs site, README, and docs build script.

Risk Assessment

Low risk. The change does not touch generated SDK source or runtime behavior. The main risk is broken static docs rendering, which was checked with the docs build.

User Impact

SDK users get guide pages for authentication and common integration scenarios before diving into the generated API reference.

Testing

• bash scripts/build_docs.sh
• git diff --check
• Verified no generated SDK source changes under src/archastro
• Ran local scenario smokes against http://localhost:4005 using the dev harness token flow:
  • token-only users.me()
  • with_token sync and async users.me() and teams.list()
  • create, get, and delete an agent

Follow-ups and Known Issues

The existing pdoc warnings for generated functional TypedDict fields with reserved keys are still present and should be fixed in the generator rather than hand-edited in this SDK repo.

[archastro]

✅ Clean PR, @calvin-archastro! No blocking findings on 94c5d0f — a few nice things I clocked:

• Companioned the docs build cleanly — render_docs_pages.py reads only trusted committed docs/*.md and HTML-escapes title/nav labels, no untrusted input in the render path. 🎯
• Nice update of the README/guide snippets to attribute access (user.id, me.email) — matches the SDK's Pydantic response contract per response-type-typeadapter-deserialization. ✨

---

_{Reply @archastro <verb>: review · do <pattern> · don't <pattern> · forget <slug> · list}