> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-cookbook-generated-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# OpenHands Docs Repository (Mintlify)

This repo hosts the **unified documentation site** for the OpenHands ecosystem:

* **OpenHands Agent SDK** (SDK + REST API)
* **OpenHands CLI**
* **OpenHands Web/App** (GUI + Cloud + REST API)

The site is built with **Mintlify** and deployed automatically by Mintlify on pushes to `main`.

## Quick orientation

### Key files/directories

* `docs.json` — Mintlify site configuration (nav tabs, redirects, OpenAPI integration)
* `overview/` — high-level docs (intro, quickstart, community, skills overview)
* `openhands/usage/` — product docs for Web/Cloud/CLI/etc.
* `sdk/` — Agent SDK docs (guides, architecture, API reference pages)
* `openapi/` — OpenAPI specs consumed by Mintlify
  * `openapi/V0_openapi.json` — OpenHands V0 REST API schema (legacy)
  * `openapi/openhands-cloud.json` — OpenHands Cloud REST API schema (served by app.all-hands.dev; surfaced as a collapsible `REST API` group under the Cloud tab → Integrations)
  * `openapi/agent-sdk.json` — Agent SDK agent-server schema (synced from `software-agent-sdk`)
* `scripts/` — automation for generating SDK API reference docs
* `.github/workflows/` — CI workflows (broken link checks, sync jobs)
* `.github/scripts/` — helper scripts used by CI
* `.agents/skills/` — prompt extensions for agents editing this repo (legacy: `.openhands/skills/`; formerly `microagents`)
* `tests/` — pytest checks for docs consistency (notably LLM pricing docs)

## Cross-Repository Boundaries

This repository owns the unified documentation site and documentation-specific tooling. The documented source repositories have distinct responsibilities:

* [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI and local-stack orchestration.
* [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and canonical API.
* [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns the browser-compatible typed Agent Server client.
* [`OpenHands/automation`](https://github.com/OpenHands/automation) owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
* [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations.

Documentation should describe these boundaries accurately. If a documentation PR is opened in the wrong source repository, explicitly recommend closing and moving it to the repository that owns the change. PRs must follow this repository's applicable code-review guidance.

## llms.txt / llms-full.txt (V1-only)

Mintlify auto-generates `/llms.txt` and `/llms-full.txt`, but this repo **overrides** them by committing
`llms.txt` and `llms-full.txt` at the repo root.

We do this so LLMs get **V1-only** context while legacy V0 pages remain available for humans.

* Generator script: `scripts/generate-llms-files.py`
* Sync workflow: `.github/workflows/check-llms-files.yml` runs weekly (and on demand) to open a PR when the files drift.
* Regenerate (recommended):
  ```bash theme={null}
  make llms
  ```
  Or directly:
  ```bash theme={null}
  python3 scripts/generate-llms-files.py
  ```
* Local verify (optional):
  ```bash theme={null}
  make llms-check
  ```
* Exclusions: `openhands/usage/v0/` and any `V0*`-prefixed page files.

## Local development

### Preview the site

Mintlify uses the `mint` CLI.

```bash theme={null}
npm install -g mintlify@latest
mint dev
```

Useful checks:

```bash theme={null}
mint broken-links
```

### Python tooling (sync/generation scripts)

This repo includes Python scripts that generate or validate parts of the docs.

This repo isn’t a Python package (no `pyproject.toml`), so for one-off runs we prefer **`uv`** to create an ephemeral environment:

```bash theme={null}
# Generate SDK API reference docs
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py

# Run pytest-based checks (only this repo's tests)
uv run --with pytest --with requests pytest -q tests/
```

(You can still use `pip install ...` if you prefer a long-lived local environment.)

## Cross-repo sync automation (important)

A lot of SDK documentation is **derived from** or **kept in sync with** `OpenHands/software-agent-sdk`.

### 1) Syncing code blocks from `software-agent-sdk/examples/*`

Script: `.github/scripts/sync_code_blocks.py`

* Scans all `.mdx` files for code blocks that include a file reference (Python and YAML supported).
* Replaces the block content with the content from the referenced file in a checked-out `agent-sdk/` folder.

Expected code block format (examples):

````mdx theme={null}
```python icon="python" expandable examples/01_standalone_sdk/02_custom_tools.py
# content is auto-synced
```

```yaml icon="yaml" expandable examples/03_github_workflows/02_pr_review/workflow.yml
# content is auto-synced
```
````

Local run:

```bash theme={null}
git clone https://github.com/OpenHands/software-agent-sdk.git agent-sdk
python .github/scripts/sync_code_blocks.py
rm -rf agent-sdk
```

CI: `.github/workflows/sync-docs-code-blocks.yml`

### 2) Generating SDK API reference pages

Script: `scripts/generate-api-docs.py`

* Uses **Sphinx** + `sphinx-markdown-builder` to generate Mintlify-friendly `.mdx` pages under `sdk/api-reference/`.

Local run:

```bash theme={null}
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py
```

CI: also run by `.github/workflows/sync-docs-code-blocks.yml`

### 3) Syncing agent-sdk OpenAPI schema

Workflow: `.github/workflows/sync-agent-sdk-openapi.yml`

* Checks out `OpenHands/software-agent-sdk`
* Runs the agent-server OpenAPI generator
* Updates `openapi/agent-sdk.json` via an automated PR

### 4) Cookbook tab generated from `OpenHands/enterprise-cookbook`

Every page under `cookbook/` and the `Cookbook` tab in `docs.json` are generated from example READMEs in
`OpenHands/enterprise-cookbook` by its `tools/docs-render` converter. **Do not edit them here**; change the
example's `README.md` or `example.yaml` in that repository.

* Each enterprise-cookbook PR gets a draft `cookbook-preview/pr-<N>` PR here for its Mintlify preview. These
  are never merged and close with the source PR.
* Merged changes arrive in a single `cookbook-sync` PR, opened by `openhands-release-bot` and refreshed nightly.
* `.github/workflows/cookbook-generated.yml` fails PRs from any other branch that touch `cookbook/`, and
  `sync_code_blocks.py` skips `cookbook/` because its code-block paths are relative to each example.

## Docs writing conventions

* Most pages are `.mdx` with frontmatter:
  ```yaml theme={null}
  ---
  title: ...
  description: ...
  ---
  ```
* Follow the style rules in `openhands/DOC_STYLE_GUIDE.md`.
* Use Mintlify components (`<Note>`, `<Warning>`, `<Tabs>`, etc.) where appropriate.
* When linking internally, prefer **absolute** doc paths (e.g. `/overview/quickstart`).
* When documenting prompt/context behavior, avoid ambiguous transport phrasing like “sent with each request” unless discussing the actual API transport. Prefer precise wording such as “included in the initial system prompt” and “remains part of the conversation/LLM context for subsequent turns.”
* Cloud integration docs live under `openhands/usage/cloud/`, and pages surfaced in **Documentation → Integrations → Cloud API** must also be added to the `Cloud API` group in `docs.json`.

### Mintlify tab ownership

When the same page path appears under multiple top-level tabs in `docs.json`, Mintlify resolves the page to one tab/sidebar (effectively the first matching tab). If you want a page to show a distinct left navigation for a new tab, that page should live **exclusively** under that tab rather than being duplicated across tabs.

### SDK guide file naming

SDK guide files under `sdk/guides/` use a **category prefix** to group related pages:

| Prefix | Category | Examples |
| - | - | - |
| `llm-` | LLM features (model configuration, providers, streaming, presets) | `llm-reasoning.mdx`, `llm-gpt5-preset.mdx` |
| `agent-` | Agent features (customization, browser, settings) | `agent-custom.mdx`, `agent-settings.mdx` |
| `convo-` | Conversation features (async, persistence, pause/resume) | `convo-async.mdx`, `convo-persistence.mdx` |

When adding a new SDK guide, always use the appropriate prefix so that related files sort together and the sidebar grouping in `docs.json` stays consistent.

## LLM API Key Options

The SDK documentation maintains three ways for users to obtain LLM access:

1. **Direct Provider** - Bring your own API key from providers like Anthropic, OpenAI, etc.
2. **OpenHands Cloud** - Use OpenHands Cloud API keys (recommended for verified models)
3. **Third-party Subscription Login** - Authenticate with existing subscriptions (e.g., ChatGPT Plus/Pro via `LLM.subscription_login()`)

When documenting LLM setup or examples, ensure all three options are mentioned where appropriate:

* `sdk/getting-started.mdx` - Main getting started page with AccordionGroup
* `sdk/shared-snippets/how-to-run-example.mdx` - Shared snippet for running examples
* `sdk/guides/llm-subscriptions.mdx` - Dedicated guide for subscription login

## Documentation ownership patterns

* Keep `sdk/guides/observability.mdx` as the canonical tracing and OTEL reference for OpenHands SDK users, including Laminar links and generic backend configuration.
* Keep `enterprise/analytics.mdx` focused on OpenHands Enterprise deployment and admin-console setup, and link back to the SDK observability guide instead of duplicating OTEL reference material.

## Validation

### LLM pricing table validation

There are *two* layers of protection for `openhands/usage/llms/openhands-llms.mdx`:

* CI workflow: `.github/workflows/validate-llm-pricing.yml` runs `.github/scripts/validate_llm_pricing.py`
* Local tests: `pytest -q` (see `tests/test_pricing_documentation.py`)

Run locally:

```bash theme={null}
uv run --with pytest --with requests pytest -q tests/
```

## OpenHands/extensions — No Release Tags

`OpenHands/extensions` does **not** publish versioned release tags (no `v1`, `v2`, etc.).
All GitHub Action references to plugins in that repo must use `@main`:

```yaml theme={null}
uses: OpenHands/extensions/plugins/qa-changes@main
uses: OpenHands/extensions/plugins/pr-review@main
```

Do **not** suggest pinning to `@v1` or any other tag — they don't exist and the workflow will fail.

## Related repos (source-of-truth)

* OpenHands Agent SDK: [https://github.com/OpenHands/software-agent-sdk](https://github.com/OpenHands/software-agent-sdk)
* OpenHands CLI: [https://github.com/OpenHands/OpenHands-CLI](https://github.com/OpenHands/OpenHands-CLI)
* OpenHands (Web/App): [https://github.com/OpenHands/OpenHands](https://github.com/OpenHands/OpenHands)
* OpenHands Extensions: [https://github.com/OpenHands/extensions](https://github.com/OpenHands/extensions) (plugins, skills, actions — **no release tags**)

When updating SDK features or examples, expect to update this repo too (especially under `sdk/`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.