` and render client-side in `components/docs/docs-article.tsx`.
4. **REST API reference** - `src/lib/docs/openapi.ts` reads the snapshot and groups operations by
   tag; `components/docs/api-reference.tsx` renders the overview (`/docs/api`: auth schemes, base URL,
   conventions, groups) and one page per tag (parameters, request body, responses, curl and JSON
   examples). Example bodies come from `exampleBodyFor()`; add a hint there for a new request model.
5. **Versions** - `src/lib/docs/versions.ts` parses `## [x.y.z] - date` headings from `CHANGELOG.md`;
   `components/docs/docs-topbar.tsx` shows the current release and a menu that links each release (and
   the unreleased section) to `/docs/changelog#`. A release needs no code change here.
6. **Pages** - `src/app/(docs)/docs/page.tsx` (index: intro, install, entry points per audience, one
   list per section), `[...slug]/page.tsx`
   (`generateStaticParams` from the catalogue, `dynamicParams = false`, breadcrumb, reading time, edit
   link, prev/next; API pages branch on `kind === "api"`), `search.json/route.ts` (static index; API
   pages index their operations) consumed by `components/layout/search-command.tsx`. `sitemap.ts`
   lists every catalogue entry.

To publish a new user-facing document: add the Markdown under `docs/`, add a `STATIC_SECTIONS` entry
in `catalogue.ts` (slug, file, title, description, icon), link it from `README.md`
(`tests/test_docs.py` requires every `docs/*.md` to be linked), run `npm run build` and open
`/docs/`. Internal documents are linked from `README.md` only. A new
`.claude/skills//SKILL.md` needs no code change. When a heading is renamed, search for the old
anchor across `docs/`, `README.md` and `platform/web/src`.

Style: the docs pages are plain reference pages - headings, paragraphs, tables and code blocks. No
icon cards, badges, pills, uppercase eyebrow labels, hover animations or drop shadows; no reading
time or page counts; copy states what an endpoint or option does, without marketing adjectives.

## Deploy

```
azd provision            # infra/main.bicep: Container Apps osr-api + osr-web, Azure OpenAI, ACR, Files share, DNS zone
azd deploy api           # platform/api/Dockerfile, context = repo root
azd deploy web           # platform/web/Dockerfile, context = platform/web (prepackage hook syncs content/)
azd deploy platform      # same Dockerfile -> osr-platform (serves /platform; osr-web forwards to it)
.\scripts\domains.ps1    # custom domain: dns (zone + name servers) -> bind (certs) -> verify; -Phase clean retires osr-platform
.\scripts\sso.ps1        # sign-in providers: microsoft (az app registration + secret) | google | github | gitlab | show | push | apply
```

JSON-valued deployment inputs (`OSR_PLATFORM_SSO_PROVIDERS_B64`, `OSR_PLATFORM_STRIPE_PRICES_B64`) travel
base64-encoded: azd substitutes `${VAR}` textually into `infra/main.parameters.json`, so raw JSON breaks every
provision ("invalid character after object key:value pair"); `infra/main.bicep` decodes with `base64ToString`.
`sso.ps1` is the only writer of the SSO map (local azd env -> `gh secret set` -> `azd provision`); every provider
uses the single redirect `/auth/callback` (kept without the `/platform` prefix on purpose - the web app
308s it to `/platform/auth/callback`, so the URI registered at every provider never changes). Google and GitHub have no API for OAuth clients, so those
commands print the console steps and prompt for the id and hidden secret.

`.github/workflows/platform.yml` runs API tests and the OpenAPI snapshot check, `npm run check && npm
run build`, a two-container smoke (`/`, `/docs`, `/docs/GUIDE`, `/docs/PLATFORM`, `/docs/api`,
`/docs/api/routing`, `/docs/skills/osr-contributing`, `/docs/search.json`, `/pricing`, `/api/v1/info`;
`/docs/sales/*` must 404) and then `azd up` on `main`. After deploying, verify `/docs/api` and
`/api/v1/info` (`edition`, `sdk_version`). `NEXT_PUBLIC_SITE_URL` is baked at build time via
`buildArgs` in `azure.yaml`; SQLite on Azure Files needs `nobrl` mount options and a single API replica.
The public domain is an Azure DNS zone (`infra/dns.bicep`, azd `OSR_DNS_ZONE=opensmartroute.ai`): apex A to the
environment static IP, `www`/`api` CNAMEs, `asuid.*` TXT; the registrar delegates to the zone's name servers.
`www` redirects come from `platform/web/src/proxy.ts` (`OSR_WEB_REDIRECT_HOSTS`), not from an edge proxy.
Apex managed certificates use `HTTP` domain-control validation, subdomains `CNAME` (`TXT` never completes for an
apex). The `azd up` job signs in with an OIDC federated credential whose subject is
`repo:isathish/OpenSmartRoute:environment:production` (repository variables `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`,
`AZURE_SUBSCRIPTION_ID`, custom-domain `OSR_*` vars; secret `OSR_PLATFORM_ADMIN_TOKEN`) and seeds
`SERVICE_*_IMAGE_NAME` from the running apps before `azd provision`; setup in `platform/README.md`
("Continuous deployment").