[codex] add SDK integration guide pages

README.md

@@ -6,6 +6,8 @@ Python SDK for the ArchAstro Platform API and ArchAgents runtime APIs.
 
 API reference documentation is published at
 [archastro.github.io/archastro-python](https://archastro.github.io/archastro-python/).
+Start with the guide pages for authentication and integration scenarios, then
+use the generated API reference for exact modules, classes, and fields.
 
 ```bash
 uv add archastro-sdk
@@ -70,7 +72,7 @@ from archastro.platform import PlatformClient
 with PlatformClient(access_token=os.environ["ARCHASTRO_ACCESS_TOKEN"]) as client:
     user = client.users.me()
 
-print(user["id"], user.get("is_system_user"))
+print(user.id, user.is_system_user)
 ```
 
 Use the async client inside async services or workers:
@@ -88,7 +90,7 @@ async def main() -> None:
     ) as client:
         user = await client.users.me()
 
-    print(user["id"], user.get("is_system_user"))
+    print(user.id, user.is_system_user)
 
 
 asyncio.run(main())
@@ -151,6 +153,9 @@ asyncio.run(main())
 - [`examples/thread_chat_tui`](examples/thread_chat_tui) — chat in an existing
   thread from a terminal UI using the async websocket helpers.
 
+The hosted documentation also includes scenario-oriented guide pages for
+authentication, listing teams, and creating agents.
+
 ## Packages
 
 All public code lives under the single top-level `archastro` package:

docs/authentication.md

@@ -0,0 +1,78 @@
+# Authentication
+
+The SDK supports two common runtime shapes. Pick the one that matches who the
+Python process is acting as.
+
+## User Session In An App
+
+Use this when your application already has a publishable API key and a user
+access token from an app login flow.
+
+```python
+import os
+
+from archastro.platform import PlatformClient
+
+client = PlatformClient.with_token(
+    os.environ["ARCHASTRO_API_KEY"],
+    os.environ["ARCHASTRO_ACCESS_TOKEN"],
+)
+
+with client:
+    me = client.users.me()
+
+print(me.id, me.email)
+```
+
+## Org Bot Or Worker
+
+Use this when a backend process should act as an org-owned system user. The
+token should be an app-scoped user token created for that bot or worker.
+
+```python
+import os
+
+from archastro.platform import PlatformClient
+
+with PlatformClient(access_token=os.environ["ARCHASTRO_ACCESS_TOKEN"]) as client:
+    me = client.users.me()
+
+print(me.id)
+```
+
+## Async Services
+
+Use `AsyncPlatformClient` inside async services and workers.
+
+```python
+import asyncio
+import os
+
+from archastro.platform import AsyncPlatformClient
+
+
+async def main() -> None:
+    async with AsyncPlatformClient.with_token(
+        os.environ["ARCHASTRO_API_KEY"],
+        os.environ["ARCHASTRO_ACCESS_TOKEN"],
+    ) as client:
+        me = await client.users.me()
+        print(me.id, me.email)
+
+
+asyncio.run(main())
+```
+
+## Local Or Staging Targets
+
+The SDK defaults to `https://platform.archastro.ai`. Override `base_url` only
+when targeting local development, staging, or another non-production gateway.
+
+```python
+client = PlatformClient.with_token(
+    os.environ["ARCHASTRO_API_KEY"],
+    os.environ["ARCHASTRO_ACCESS_TOKEN"],
+    base_url=os.environ["ARCHASTRO_PLATFORM_BASE_URL"],
+)
+```
+

docs/index.md

@@ -0,0 +1,46 @@
+# ArchAstro Python SDK
+
+Use the Python SDK to call the ArchAstro Platform API from scripts, CLIs,
+workers, and async services.
+
+## Start Here
+
+1. Install the package.
+2. Choose the authentication mode for your process.
+3. Verify the token with `users.me()`.
+4. Move to the resource-specific API reference when you know the method you
+   need.
+
+```bash
+uv add archastro-sdk
+# or
+pip install archastro-sdk
+```
+
+## Documentation Map
+
+- [Authentication](authentication.html): choose between app user sessions,
+  org-worker tokens, and local/staging base URLs.
+- [Integration scenarios](scenarios.html): smoke-tested snippets for reading the
+  current user, listing teams, and creating an agent.
+- [Platform API reference](archastro/platform.html): generated reference for the
+  REST client, models, and channel wrappers.
+- [Phoenix channel reference](archastro/phx_channel.html): lower-level realtime
+  channel client.
+
+## Minimal Example
+
+```python
+import os
+
+from archastro.platform import PlatformClient
+
+with PlatformClient.with_token(
+    os.environ["ARCHASTRO_API_KEY"],
+    os.environ["ARCHASTRO_ACCESS_TOKEN"],
+) as client:
+    me = client.users.me()
+
+print(me.id, me.email)
+```
+

docs/scenarios.md

@@ -0,0 +1,56 @@
+# Integration Scenarios
+
+These examples show common SDK workflows. They were smoke-tested against the
+local platform dev harness with org-user tokens.
+
+## Read The Current User
+
+Use `users.me()` to validate a token and discover the current actor.
+
+```python
+import os
+
+from archastro.platform import PlatformClient
+
+with PlatformClient.with_token(
+    os.environ["ARCHASTRO_API_KEY"],
+    os.environ["ARCHASTRO_ACCESS_TOKEN"],
+) as client:
+    me = client.users.me()
+
+print(me.id, me.email)
+```
+
+## List Teams
+
+List responses are Pydantic models. Access known fields as attributes, or call
+`model_dump()` when you need a plain dictionary.
+
+```python
+teams = client.teams.list()
+
+print(teams.model_dump(mode="json"))
+```
+
+## Create An Agent
+
+Use `agents.create()` to provision an agent owned by the current user, org, or
+team context. Store the returned `id` if you need to fetch or update it later.
+
+```python
+agent = client.agents.create(
+    {
+        "name": "Support triage",
+        "identity": "You triage support requests and keep replies concise.",
+    }
+)
+
+print(agent.id, agent.name)
+```
+
+For cleanup in tests and scripts:
+
+```python
+client.agents.delete(agent.id)
+```
+

scripts/build_docs.sh

@@ -11,3 +11,5 @@ uv run pdoc \
   --output-directory site \
   --docformat google \
   --footer-text "ArchAstro Python SDK"
+
+uv run python scripts/render_docs_pages.py

scripts/render_docs_pages.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from html import escape
+from pathlib import Path
+
+import markdown2
+
+ROOT = Path(__file__).resolve().parents[1]
+DOCS = ROOT / "docs"
+SITE = ROOT / "site"
+
+PAGES = [
+    ("index.md", "index.html", "Overview"),
+    ("authentication.md", "authentication.html", "Authentication"),
+    ("scenarios.md", "scenarios.html", "Scenarios"),
+]
+
+
+def main() -> None:
+    SITE.mkdir(exist_ok=True)
+    for source_name, output_name, title in PAGES:
+        markdown = (DOCS / source_name).read_text(encoding="utf-8")
+        body = markdown2.markdown(
+            markdown,
+            extras=["fenced-code-blocks", "header-ids", "tables"],
+        )
+        (SITE / output_name).write_text(render_page(title, body), encoding="utf-8")
+
+
+def render_page(title: str, body: str) -> str:
+    nav_items = "\n".join(
+        f'<li><a href="{escape(output)}">{escape(label)}</a></li>' for _, output, label in PAGES
+    )
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{escape(title)} - ArchAstro Python SDK</title>
+  <style>
+    :root {{
+      color-scheme: light;
+      --bg: #ffffff;
+      --fg: #1f2933;
+      --muted: #5c6f82;
+      --line: #d8dee5;
+      --panel: #f7f9fb;
+      --accent: #176c5f;
+      --code: #0f1720;
+    }}
+    * {{ box-sizing: border-box; }}
+    body {{
+      margin: 0;
+      color: var(--fg);
+      background: var(--bg);
+      font: 16px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }}
+    .layout {{
+      display: grid;
+      grid-template-columns: minmax(220px, 280px) minmax(0, 880px);
+      min-height: 100vh;
+    }}
+    nav {{
+      border-right: 1px solid var(--line);
+      background: var(--panel);
+      padding: 28px 24px;
+    }}
+    nav h2 {{ margin: 0 0 16px; font-size: 18px; }}
+    nav ul {{ list-style: none; margin: 0 0 28px; padding: 0; }}
+    nav li {{ margin: 10px 0; }}
+    nav a {{ color: var(--fg); text-decoration: none; }}
+    nav a:hover {{ color: var(--accent); }}
+    main {{ padding: 44px 56px 72px; }}
+    h1 {{ margin-top: 0; font-size: 40px; line-height: 1.1; }}
+    h2 {{ margin-top: 40px; border-top: 1px solid var(--line); padding-top: 28px; }}
+    a {{ color: var(--accent); }}
+    p, li {{ color: var(--fg); }}
+    code {{
+      color: var(--code);
+      background: #eef2f5;
+      border-radius: 4px;
+      padding: 0.1em 0.3em;
+    }}
+    pre {{
+      overflow-x: auto;
+      background: #101820;
+      color: #f8fafc;
+      border-radius: 6px;
+      padding: 18px;
+    }}
+    pre code {{ background: transparent; color: inherit; padding: 0; }}
+    @media (max-width: 760px) {{
+      .layout {{ display: block; }}
+      nav {{ border-right: 0; border-bottom: 1px solid var(--line); }}
+      main {{ padding: 32px 24px 56px; }}
+      h1 {{ font-size: 32px; }}
+    }}
+  </style>
+</head>
+<body>
+  <div class="layout">
+    <nav>
+      <h2>Guides</h2>
+      <ul>{nav_items}</ul>
+      <h2>API Reference</h2>
+      <ul>
+        <li><a href="archastro/platform.html">Platform API</a></li>
+        <li><a href="archastro/phx_channel.html">Phoenix Channels</a></li>
+      </ul>
+    </nav>
+    <main>{body}</main>
+  </div>
+</body>
+</html>
+"""
+
+
+if __name__ == "__main__":
+    main()