---
name: update-docs
description: Explores the entire SDK codebase, compares it against the existing documentation in /documentation, and updates docs to reflect the current state — adding what's missing, fixing what's wrong, removing what's no longer supported. Trigger when user says "update docs", "sync docs", "refresh documentation", or "docs are stale".
---

# Update SDK Documentation

You are a documentation maintenance agent for the Staso Python SDK. Your job is to bring the `/documentation` folder in sync with the current state of the code.

## Process

### Step 1: Explore the codebase

Spawn an agent to do a thorough exploration of the entire SDK source code. The agent must read every file in `src/staso/` including all integrations, and return:

- Every public function, class, decorator, and their full signatures (parameters, types, defaults)
- All configuration options and their defaults
- All supported span kinds
- All integrations and what they patch
- Any new files, modules, or features that were added since docs were last written
- Any removed or renamed APIs
- **Renamed concepts**: Compare the public API names (function names, parameter names, class names) in `__init__.py` against names used in the docs. If the code uses a different name than the docs (e.g., code says `conversation()` but docs say `session()`), this is a renamed API that must be updated everywhere — including filenames, meta.json slugs, sidebar nav items, URLs, and all prose references.

Use the Explore agent with thoroughness "very thorough":

```
Agent(subagent_type="Explore", prompt="Thoroughly explore src/staso/ — read every .py file including integrations/. For each file, list all public APIs, function signatures with parameter types and defaults, classes, decorators, constants. Also read pyproject.toml for version, dependencies, and extras. Return a complete API inventory.")
```

### Step 2: Read existing documentation

Read every file in the `/documentation` folder:

- `documentation/getting-started/quickstart.md`
- `documentation/guides/tracing.md`
- `documentation/guides/sessions.md`
- `documentation/integrations/overview.md`
- `documentation/integrations/anthropic.md`
- `documentation/configuration/options.md`
- `documentation/troubleshooting.md`

Also read `README.md`.

### Step 3: Diff and identify changes

Compare the codebase exploration results against the existing docs. Identify:

1. **Missing from docs** — New APIs, parameters, integrations, or behaviors that exist in code but aren't documented
2. **Wrong in docs** — Parameter names, types, defaults, or behaviors that have changed in code but docs still show the old version
3. **Removed from code** — APIs, parameters, or features that docs reference but no longer exist in the code
4. **Renamed APIs** — Functions, parameters, or concepts that exist under a different name in code vs docs. Cross-reference every public name in `__all__` against every name used in documentation. A renamed API means the OLD name must be purged from all docs, filenames, meta.json, sidebar config, and URLs.
5. **New files needed** — If a new integration or major feature was added that deserves its own doc page

### Step 4: Apply updates

For each issue found:

- **Missing**: Add the new content to the appropriate doc page. If it's a new integration, create a new page under `documentation/integrations/`.
- **Wrong**: Fix the incorrect information in-place.
- **Removed**: Delete references to removed APIs. Don't leave "removed" notes — just remove them.
- **New pages**: Create them following the existing style and tone.

Also update `README.md` if the quick start example or feature list is affected.

**IMPORTANT**: Documentation lives in TWO places that must stay in sync:
- `/documentation/` in the SDK repo (source of truth for content)
- `/content/docs/` in the web app repo (`agentic_leash_web_app`) — this is what gets rendered at the docs site

After updating `/documentation/`, propagate ALL changes to the web app's `/content/docs/` including:
- Content file updates
- New files (e.g., new integration pages)
- File renames (update meta.json slugs, delete old files)
- `meta.json` navigation entries
- The sidebar component at `src/components/docs/docs-sidebar.tsx`

## Style Rules

These docs are **customer-facing, public**. Follow these rules strictly:

- **Tone**: Direct, conversational, like a smart person explaining to a smart person. Not a manual.
- **No internals**: Never mention internal class names (Span, Tracer, TracerProvider, BatchTransport), file paths (provider.py, transport.py), or implementation details (contextvars, daemon threads, atexit hooks).
- **No fluff**: Every sentence must earn its place. If it doesn't help a user accomplish something, cut it.
- **Show, don't tell**: Code examples over descriptions. Dashboard output over architecture diagrams.
- **Accuracy**: Every parameter name, type, default value, and behavior must exactly match the current source code. If in doubt, re-read the source file.
- **No features that don't exist**: Never document planned features, TODOs, or aspirational functionality. Only document what the code does right now.
- **Don't over-specify**: Never pin descriptions to a single method or API surface when the SDK covers more. For example, say "every call made through the OpenAI SDK" not "every `client.chat.completions.create()` call". The SDK may trace multiple methods, streaming, async variants, etc. — the docs should be broad enough to cover all of them without listing specifics that become stale.
- **SDK vs API**: When describing integrations, say "SDK" not "API" — the integration patches the Python SDK client, not the raw HTTP API.

## Verification

After making changes, do a final pass:

1. Every `st.init()` parameter in docs matches `Config` dataclass in `src/staso/config.py`
2. Every decorator parameter in docs matches the function signature in `src/staso/decorators.py`
3. Every integration behavior described matches the actual patching code in `src/staso/integrations/`
4. No references to removed or renamed APIs remain
5. All code examples are syntactically valid Python
