docs: Mintlify documentation site + API reference

docs-site/README.md

@@ -0,0 +1,64 @@
+# IdentArk Docs (Mintlify)
+
+Public documentation and API reference for the IdentArk control plane.
+
+## Structure
+
+```
+docs-site/
+├── docs.json                     # Mintlify config (nav, theme, tabs)
+├── introduction.mdx              # Landing
+├── quickstart.mdx
+├── concepts.mdx
+├── authentication.mdx
+├── sdks/{python,typescript}.mdx
+├── guides/                       # production, mcp-hitl, acs, limits-and-errors, security
+├── api-reference/
+│   ├── introduction.mdx
+│   └── openapi.json              # Generated from the FastAPI app — see below
+└── images/                       # logo + favicon
+```
+
+## Develop locally
+
+```bash
+npm i -g mint     # Mintlify CLI
+cd docs-site
+mint dev          # http://localhost:3000
+```
+
+The **API Reference → Endpoints** group is auto-generated from
+`api-reference/openapi.json`; no per-endpoint MDX to maintain.
+
+## Regenerate the OpenAPI spec
+
+The spec is the FastAPI app's own schema, post-processed to add the production server
+and a bearer-auth scheme. From the repo root:
+
+```bash
+cloud/.venv/bin/python - <<'PY'
+import os, json
+os.environ.setdefault("DATABASE_URL", "postgresql+asyncpg://u:p@localhost/db")
+os.environ.setdefault("REDIS_URL", "redis://localhost:6379/0")
+os.environ.setdefault("SECRET_KEY", "dev-secret")
+os.environ.setdefault("FIREBASE_API_KEY", "x")
+import sys; sys.path.insert(0, "cloud")
+from app.main import app
+spec = app.openapi()
+spec["servers"] = [{"url": "https://api.identark.io", "description": "Production"}]
+spec["components"].setdefault("securitySchemes", {})["bearerAuth"] = {
+    "type": "http", "scheme": "bearer",
+}
+spec["security"] = [{"bearerAuth": []}]
+json.dump(spec, open("docs-site/api-reference/openapi.json", "w"), indent=2)
+print("paths:", len(spec["paths"]))
+PY
+```
+
+> Keep `docs.json`'s navigation in sync only when you add new **guide** pages —
+> endpoint pages come from the spec automatically.
+
+## Deploy
+
+Connect this repo to Mintlify (mintlify.com) and set the docs root to `docs-site/`.
+Pushes to the default branch publish automatically.

docs-site/api-reference/introduction.mdx

@@ -0,0 +1,73 @@
+---
+title: "API reference"
+description: "Every /v1 endpoint on the IdentArk control plane."
+---
+
+The reference in this section is generated from the control plane's OpenAPI schema —
+each endpoint has a live request builder and real response shapes. This page covers the
+conventions that apply across all of them.
+
+## Base URL
+
+<CodeGroup>
+```text Production
+https://api.identark.io
+```
+
+```text Local
+http://localhost:8000
+```
+</CodeGroup>
+
+All application endpoints are versioned under `/v1`. `GET /health` (unversioned) is a
+liveness probe.
+
+## Authentication
+
+Send a scoped `csk_` key as a bearer token on every request:
+
+```http
+Authorization: Bearer csk_…
+```
+
+The required scope is listed on each endpoint. `org:admin` covers all of them. See
+[Authentication & scopes](/authentication) for the full model. A handful of
+endpoints are public: `POST /v1/orgs/signup`, `POST /v1/auth/signup`,
+`POST /v1/auth/login`, `GET /v1/config/public`, and `GET /health`.
+
+## Conventions
+
+<CardGroup cols={2}>
+  <Card title="Content type" icon="code">
+    Request and response bodies are JSON. Send `Content-Type: application/json`.
+  </Card>
+  <Card title="Timestamps" icon="clock">
+    ISO 8601 strings, UTC (e.g. `2026-08-13T09:00:00Z`).
+  </Card>
+  <Card title="IDs" icon="hashtag">
+    Opaque strings. Don't parse them; store and echo them back.
+  </Card>
+  <Card title="Errors" icon="triangle-exclamation">
+    JSON with a stable `error_code` and human `message`. See
+    <a href="/guides/limits-and-errors">Limits & errors</a>.
+  </Card>
+</CardGroup>
+
+## The endpoints you'll use most
+
+<CardGroup cols={2}>
+  <Card title="POST /v1/keys" icon="key">
+    Mint a scoped API key.
+  </Card>
+  <Card title="POST /v1/credentials" icon="vault">
+    Store a provider secret, get a `credential_ref`.
+  </Card>
+  <Card title="POST /v1/sessions" icon="play">
+    Open a bounded, cost-capped session.
+  </Card>
+  <Card title="POST /v1/llm/invoke" icon="robot">
+    Run a governed completion.
+  </Card>
+</CardGroup>
+
+Browse the full surface in the **Endpoints** group in the sidebar.