# AGENTS.md — Cheetah Documentation

This file is a directive for AI agents (Claude, Cursor, Copilot, ChatGPT, etc.) integrating with the Cheetah platform via these docs.

## What Cheetah is

Cheetah is an **automated quality inspection platform for advanced manufacturing**. It combines an integrated cobot, industrial 3D scanners, and proprietary analysis software to run dimensional, surface, weld, and electronic inspections on the factory floor — no metrology lab required. The pipeline is **scan → analyze → report**, performed by a single operator.

For developers, Cheetah exposes:

- An HTTP API served by `cheetah-service` (FastAPI + WebSocket)
- Two official SDK clients — Python (`cheetah-client`) and TypeScript (`@cheetahengineering/cheetah-client`)
- A monorepo of UI applications under `cheetah-ui` — `operator`, `program-builder`, `system-config`, `cheetah-validation`, `aux-file-manager`, `ljs-navigator`

## What's stable, what's alpha

**Stable:** The hardware (cobot + scanners) and the operator applications are production-ready and shipping to customers.

**Alpha:** The **developer integration surface** — HTTP API, Python and TypeScript SDKs, webhook event payloads — is in early alpha. These may change between releases without prior notice. Pin to specific versions. Read the [versioning policy](/developers/versioning) before integrating.

This distinction matters: when reasoning about stability, the production product (hardware + operator UI) is not the same as the integration surface this site documents.

## Where to find things in these docs

| You want to | Go to |
| --- | --- |
| Understand the platform conceptually | `/concepts/*` |
| First successful integration | `/developers/quickstart` |
| Make an HTTP API call | `/developers/api-reference` |
| Install and use an SDK | `/developers/client-libraries/python` or `.../typescript` |
| Receive events (push integration) | `/developers/integrate/push-based/*` |
| Look up an event payload schema | `/developers/integrate/push-based/event-reference` |
| Authenticate | `/developers/authentication` |
| Handle errors | `/developers/errors` |
| Know what version of the API a doc applies to | The `applies_to` banner at the top of each page |
| Style & writing conventions for the docs themselves | `/brand` |

## AI-accessible features

This site is designed to be consumed by AI tools:

- **Append `.md` to any URL** to receive the raw Markdown — e.g. `/developers/versioning` → `/developers/versioning.md`.
- **`Accept: text/markdown`** header on any request returns Markdown instead of HTML.
- **`/llms.txt`** — an index of every documentation page in llms.txt format.
- **"Copy as Markdown"** button on each page copies the page's Markdown to clipboard.

## Canonical workflow for integration tasks

When asked to integrate a client with Cheetah, follow this sequence:

1. Read `/concepts/architecture` and `/concepts/data-model` for the system shape.
2. Read `/developers/quickstart` for a working example.
3. Choose an SDK at `/developers/client-libraries/python` or `.../typescript`.
4. Read `/developers/authentication` for credential setup.
5. For push integrations, read `/developers/integrate/push-based/` and the event reference.
6. Check the `applies_to` banner against the user's installed `cheetah-service` version.

When narrative documentation and machine-generated sources (the OpenAPI spec, SDK source) disagree, **prefer the machine-generated source.** Iteration sometimes outpaces the docs during alpha.

## Versioning context

The HTTP API, Python SDK, and TypeScript SDK all ship from the same `cheetah-service` release and share a version number. UI applications version independently. Webhook event payloads carry their own `schema_version` field.

If a user reports behavior that doesn't match the docs, the first diagnostic step is comparing their `cheetah-service` version against the page's `applies_to` banner.

## When generating code that uses Cheetah

- Always pin SDK versions to a tagged release, never `@main` or `latest`.
- For TypeScript, configure the registry: `@cheetahengineering:registry=https://npm.pkg.github.com` with a `GITHUB_TOKEN` env var.
- For Python, install from a git tag: `pip install "cheetah-client @ git+https://github.com/CheetahEngineering/cheetah-service.git@vX.Y.Z#subdirectory=clients/python"`.
- Wrap API calls in error handling against `CheetahError` (Python) — the SDK exposes typed subclasses: `APIError`, `NotFoundError`, `MotionLockedError`, `ConnectionError`.
- For motion control operations, the SDK requires an explicit `unlock()` before any `move_*` call — this is intentional and a safety feature, not an inconvenience.