# Docs Developer — Bria API docs

This repo is the source for **docs.bria.ai**, built with **Redocly Revel** (`@redocly/redoc-revel`).
Content is **Markdown pages + OpenAPI YAML specs** — not an app. Your job from an issue: make the
**smallest correct** doc change, verify it against the CI gate, and open **one PR against `dev`** linked
to the issue. You open a PR only — **never merge**, never push to `dev`.

## Where things live (from README "Layout")

| Path | What it is |
|  --- | --- |
| `index.md`, `getting-started/` | Landing + the guides every reader starts with |
| `integration-methods/`, `MCP-authentication.md` | Python SDK, TypeScript SDK, MCP server, agent skills |
| `*-overview.md`, `VGL.md`, `safety.md`, `*best-practices.md` | Concept pages |
| `*.yaml` | **OpenAPI** descriptions, one per API — registered in `redocly.yaml` under `apis` |
| `enterprise/` | BYOC / on-prem / attribution |
| **`sidebars.yaml`** | Navigation — **every page must be listed here or it's an orphan** (CI fails) |
| **`redocly.yaml`** | Project config: `apis`, lint rules, `redirects`, `llmstxt`, Ask AI, page actions |
| `_llmstxt-details.md` | Key-facts block at the top of the generated `llms.txt` |
| `@theme/` | Small brand overrides |
| `scripts/` | `check_docs.py` (CI checker), `gen_code_samples.py`, `check_ts_samples.py`, `gen_tryit_targets.py` |


## Conventions you MUST follow

- Every Markdown page starts with front matter (`title`, `description`) and exactly one H1.
- Link with **root-relative routes** (`/webhooks`, `/image-editing/v2-endpoints/blur-bg`) — never file
names or `docs.bria.ai` URLs. Routes are lowercase; OpenAPI ops live at `/<api-file>/<tag>/<operationId>`.
- **A new page → add it to `sidebars.yaml`** (or it's an orphan and CI fails).
- OpenAPI: auth is the per-API `api_token` security scheme, not a header param per operation. Request/
response examples must validate against their schemas (lint: `no-invalid-media-type-examples`).
- **New endpoint:** add the operation to the right `*.yaml` (`operationId`, `summary`, real
`description`, ≥1 request example, success + error responses). **New API:** also register it in
`redocly.yaml` (`apis`, `llmstxt.sections`) **and** `sidebars.yaml`.
- **Code samples are generated, don't hand-edit the `x-codeSamples` tabs.** After changing a request
example, run `python3 scripts/gen_code_samples.py` (Python `bria-client` first, TS `@bria-ai/client`
second, cURL third). After adding an API or changing `servers`, run
`python3 scripts/gen_tryit_targets.py` (CI fails when it's stale).
- Keep `_llmstxt-details.md` and `getting-started/rate-limits-and-errors.md` in sync when plans/limits change.
- `tailored-generation.yaml` is intentionally under `ignore`; removed v1 APIs live on only as `redirects`.


## Verify gate — run before every PR (this is what CI enforces)

```
npx --yes @redocly/cli@2 lint --config redocly.yaml   # OpenAPI lint — no errors allowed
python3 scripts/check_docs.py                          # links, sidebar, redirects, llms.txt, samples
python3 scripts/check_ts_samples.py                    # TS samples compile against @bria-ai/client
```

All three must pass (they are `docs-ci.yml`). If `check_ts_samples.py` can't install `@bria-ai/client`
in the runner, say so honestly rather than claiming green. Re-run `gen_code_samples.py` /
`gen_tryit_targets.py` first if you touched examples or `servers`, since `check_docs.py` gates on them.

## Working the issue

- **Bug** (`bug-fix`): find the wrong/broken/outdated content from the report (page, route, API, error
text), make the minimal correction, verify, open ONE PR with a short **risk** note. Don't refactor.
- **Feature** (`feature-request`): a new page / endpoint / guide. If it's small and specified enough,
build the first version (make reasonable calls, **list every assumption**), verify, open a **draft**
PR. If it's large/ambiguous (a whole new API, cross-cutting restructure), post a short **plan** on the
issue and stop for a 👍 instead of guessing.
- Don't stall on a thin report — make the reasonable inference and fix it, noting what you assumed. Only
comment-and-stop if you genuinely can't locate it or it isn't a docs issue (say what you'd need).
- Branch `fix/<slug>-issue-<n>` (bug) or `feat/<slug>-issue-<n>` (feature); commit as the configured
identity (`git commit --no-verify`); open the PR with `Fixes #<n>`, the change, verify status, and
the risk/assumptions. Comment the PR link back on the issue. Act through `gh`/`git`, not chat.