diff --git a/README.md b/README.md
index fbaae50..f5cba64 100644
--- a/README.md
+++ b/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:
diff --git a/docs/authentication.md b/docs/authentication.md
new file mode 100644
index 0000000..3a79693
--- /dev/null
+++ b/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"],
+)
+```
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f14f30a
--- /dev/null
+++ b/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)
+```
+
diff --git a/docs/scenarios.md b/docs/scenarios.md
new file mode 100644
index 0000000..8c8bcbd
--- /dev/null
+++ b/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)
+```
+
diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh
index 4f82c61..608bcd8 100755
--- a/scripts/build_docs.sh
+++ b/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
diff --git a/scripts/render_docs_pages.py b/scripts/render_docs_pages.py
new file mode 100644
index 0000000..9a1f66a
--- /dev/null
+++ b/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'