docs: Mintlify nav and fixed flow visuals

README.md

@@ -21,8 +21,8 @@ Open http://localhost:3000.
 ## Edit
 
 - Page content lives in `*.mdx` files.
-- Navigation is configured in [`mint.json`](./mint.json).
-- Add a new page by creating the `.mdx` file and listing it under the right group in `mint.json`.
+- Navigation is configured in [`docs.json`](./docs.json).
+- Add a new page by creating the `.mdx` file and listing it under the right group in `docs.json`.
 
 ## Deploy
 

api-reference/account/api-keys.mdx

@@ -1,11 +1,11 @@
 ---
-title: "Manage API keys"
-description: "List, mint, and revoke API keys."
+title: "List, create, and revoke API keys"
+description: "List, create, and revoke long-lived API keys for your org."
 ---
 
 ## `GET /me/api-keys`
 
-Lists keys for the current **org** (sorted by `created_at` desc). Same shape as `GET /me`'s `api_keys` field.
+Lists keys for the current **org**, sorted by `created_at` descending. The response matches the `api_keys` field in `GET /me`.
 
 ```http
 GET /me/api-keys[?include_revoked=true]
@@ -18,7 +18,7 @@ Authorization: Bearer <access_token>
 
 ## `POST /me/api-keys`
 
-Mints a new key. Returns the plaintext value **once.**
+Creates a new key. The plaintext value is returned **once**.
 
 ```http
 POST /me/api-keys
@@ -50,7 +50,7 @@ Content-Type: application/json
 </ResponseField>
 
 <ResponseField name="key" type="object">
-  Metadata (id, prefix, display_id, name, …).
+  Metadata for the key, including id, prefix, display_id, name, scopes, and timestamps.
 </ResponseField>
 
 ```json
@@ -84,13 +84,13 @@ Authorization: Bearer <access_token>
 </ParamField>
 
 <Warning>
-  Revocation is **irreversible.** Existing JWTs minted from a revoked key keep working until they expire (max 24h after revocation).
+  Revocation is **irreversible.** Existing JWTs created from a revoked key keep working until they expire, up to 24h after revocation.
 </Warning>
 
 ## Examples
 
 <CodeGroup>
-```bash cURL — list, mint, revoke
+```bash cURL - list, mint, revoke
 # List active keys
 curl -H "Authorization: Bearer $JWT" \
   https://api.getmetacognition.com/me/api-keys
@@ -126,6 +126,6 @@ httpx.delete(f"{api}/me/api-keys/{key_id}", headers=H)
 
 ## Operational tips
 
-- One key per environment. Mint `production`, `staging`, `local-dev-sauhard` separately.
-- Set `last_used_at` thresholds in your monitoring — alert if a key hasn't been used in 30 days (probably abandoned).
-- Don't share keys across services — each service gets its own so revocation has surgical blast radius.
+- One key per environment. Mint `production`, `staging`, and `local-dev` separately.
+- Alert if a key has not been used in 30 days. It may be abandoned.
+- Do not share keys across services. Give each service its own key so revocation is narrow.

api-reference/account/me.mdx

@@ -1,10 +1,10 @@
 ---
-title: "Current org"
-description: "Read your org, user, and active API keys."
+title: "Get current organization"
+description: "Read the authenticated org, user, and visible API keys."
 api: "GET https://api.getmetacognition.com/me"
 ---
 
-Returns the authenticated org and user, plus all API keys for that **org** (not just the calling user).
+Returns the authenticated org and user, plus all API keys visible to that **org**.
 
 ## Headers
 
@@ -23,7 +23,7 @@ Authorization: Bearer <access_token>
 </ResponseField>
 
 <ResponseField name="api_keys" type="array">
-  Array of API key metadata for the org (sorted by `created_at` desc). Plaintext keys are **not** included — only metadata. To get the plaintext value, mint a new key via [`POST /me/api-keys`](/api-reference/account/api-keys).
+  API key metadata for the org, sorted by `created_at` descending. Plaintext keys are **not** included. To get a plaintext key, create a new one with [`POST /me/api-keys`](/api-reference/account/api-keys).
 </ResponseField>
 
 ## Example
@@ -68,6 +68,6 @@ print(me["org_id"], "→", len(me["api_keys"]), "keys")
 
 ## When to use
 
-- Build a "logged-in as…" UI in your own product.
+- Build a "logged-in as" UI in your own product.
 - Audit which keys are still active before a rotation.
-- Verify that `last_used_at` advances after a deploy (sanity check).
+- Verify that `last_used_at` advances after a deploy.

api-reference/auth/refresh.mdx

@@ -1,10 +1,13 @@
 ---
-title: "Refresh token"
-description: "Mint a new access token using a refresh token."
+title: "Refresh access token"
+description: "Use a refresh token to get a new access token."
 api: "POST https://api.getmetacognition.com/auth/refresh"
+icon: "arrows-rotate"
 ---
 
-Use this when an `access_token` has expired but the `refresh_token` is still valid. The SDK does this automatically on 401.
+import { TokenRetryVisual } from "/snippets/flow-visuals.mdx";
+
+Use this when an `access_token` has expired and the `refresh_token` is still valid. The SDK does this automatically after a 401.
 
 ## Body
 
@@ -25,7 +28,7 @@ Use this when an `access_token` has expired but the `refresh_token` is still val
 </ResponseField>
 
 <ResponseField name="refresh_token" type="string">
-  Possibly rotated; persist whichever the response returns.
+  May be rotated. Store the value returned by the response.
 </ResponseField>
 
 <ResponseField name="token_type" type="string">
@@ -58,15 +61,10 @@ tokens = resp.json()
 
 ## When refresh fails
 
-If the refresh token is itself expired (>7d old) or revoked (the underlying API key was revoked), `/auth/refresh` returns `401`. Fall back to `/auth/token-exchange` with the original API key — or, if the API key is also gone, surface a re-login flow.
+If the refresh token is expired (more than 7 days old) or revoked, `/auth/refresh` returns `401`. At that point, call `/auth/token-exchange` with the original API key. If the API key is also gone, ask the user or service to authenticate again.
 
-```mermaid
-flowchart TD
-    A[401 on a normal call] --> B[Try POST /auth/refresh]
-    B -->|200| C[Retry original call]
-    B -->|401| D[Try POST /auth/token-exchange]
-    D -->|200| C
-    D -->|401| E[Surface AuthenticationError to user]
-```
+### After 401
+
+<TokenRetryVisual />
 
-The Python SDK runs this entire flow internally on a single 401 response — you only see `AuthenticationError` if the whole chain fails.
+Without the SDK, implement this sequence in your HTTP client. With the SDK, `AuthenticationError` usually means refresh **and** exchange both failed.

api-reference/auth/signup.mdx

@@ -1,10 +1,10 @@
 ---
-title: "Create account"
-description: "Create a new org and mint the first API key."
+title: "Sign up"
+description: "Create an org and receive the first API key."
 api: "POST https://api.getmetacognition.com/signup"
 ---
 
-Creates a new organization, a default user inside it, and the first API key for that user. The plaintext API key appears in the response **once and only once**.
+Creates a new organization, a default user, and the first API key. The plaintext API key appears in the response **once**.
 
 ## Body
 
@@ -16,7 +16,7 @@ Creates a new organization, a default user inside it, and the first API key for
 ```
 
 <ParamField body="org_id" type="string">
-  Optional org id. Auto-generated as `org_<10-char base62>` when omitted. Must be **alphanumeric** (with `-` or `_` allowed) and **≤ 64 chars**. Server returns `409 Conflict` if the id already exists.
+  Optional org id. If omitted, the server generates `org_<10-char base62>`. Must be alphanumeric, with `-` or `_` allowed, and at most 64 chars. Returns `409 Conflict` if the id already exists.
 </ParamField>
 
 <ParamField body="name" type="string">
@@ -34,7 +34,7 @@ Creates a new organization, a default user inside it, and the first API key for
 </ResponseField>
 
 <ResponseField name="api_key" type="string">
-  The plaintext API key. **Save it now — there's no recovery.**
+  The plaintext API key. **Save it now. It cannot be recovered later.**
 </ResponseField>
 
 <ResponseField name="key" type="object">
@@ -82,11 +82,11 @@ api_key = data["api_key"]   # store this securely
 ```
 
 <Warning>
-  The `api_key` field appears only in this response. Persist it server-side. We can't recover or re-display it.
+  The `api_key` field appears only in this response. Store it server-side. We cannot recover or re-display it.
 </Warning>
 
 <Note>
-  This endpoint is unauthenticated by design — anyone can create an org. To gate it (e.g. private launch), put your existing auth provider in front (Auth0, Clerk) and only forward to `/signup` after their checks pass.
+  This endpoint is unauthenticated by design. Anyone can create an org. For a private launch, put your existing auth provider in front and only forward to `/signup` after your checks pass.
 </Note>
 
 ## Errors

api-reference/auth/token-exchange.mdx

@@ -1,10 +1,12 @@
 ---
-title: "Exchange API key"
-description: "Exchange an API key for a short-lived JWT pair."
+title: "Exchange API key for tokens"
+description: "Exchange an API key for short-lived access and refresh JWTs."
 api: "POST https://api.getmetacognition.com/auth/token-exchange"
 ---
 
-Trades an API key for a JWT access/refresh pair. The Python SDK does this automatically — call this directly only if you're integrating from another language or brokering tokens in a separate service.
+Exchange your API key for an access token and refresh token. This is the HTTP version of what the SDK does on first use. See [Authentication](/authentication) for the full flow.
+
+Call this directly only when you are not using the Python SDK, or when another service brokers tokens for your app.
 
 ## Body
 
@@ -80,7 +82,7 @@ const tokens = await resp.json();
 
 ## JWT contents
 
-Decode the access token (don't *trust* the contents — verify with the [JWKS endpoint](https://api.getmetacognition.com/.well-known/jwks.json) if you need to):
+Decode the access token if you want to inspect its claims. If you need to trust those claims, verify the token with the [JWKS endpoint](https://api.getmetacognition.com/.well-known/jwks.json).
 
 ```json
 {

api-reference/memory/ingest-memory.mdx

@@ -1,10 +1,10 @@
 ---
-title: "Remember conversation"
-description: "Persist conversation turns into memory."
+title: "Ingest conversation memory"
+description: "Write turns under a scope. Active memory is saved first; enrichment continues in the background."
 api: "POST https://api.getmetacognition.com/ingestion/memory"
 ---
 
-The REST equivalent of `tex.conversations.remember(...)`. Active write completes synchronously; passive enrichment runs in the background.
+This is the REST version of **`tex.conversations.remember`**. Use it to write turns under a scope. Tex saves active memory first, then continues enrichment in the background.
 
 ## Headers
 
@@ -40,7 +40,7 @@ Content-Type: application/json
 ```
 
 <ParamField body="scope.org_id" type="string" required>
-  Your org id (≥ 1 char). Server uses the JWT's `org_id` claim for tenancy regardless — this field is required for Pydantic validation only.
+  Your org id. Minimum length is 1 character. The server still uses the JWT's `org_id` claim for tenancy; this field is required for request validation.
 </ParamField>
 
 <ParamField body="scope.user_id" type="string">
@@ -52,15 +52,15 @@ Content-Type: application/json
 </ParamField>
 
 <ParamField body="turns" type="array" required>
-  At least one turn (`min_length=1`). Each turn: `{role, text, timestamp, observations?}`. See [memory model](/concepts/memory-model).
+  At least one turn (`min_length=1`). Each turn: `{role, text, timestamp, observations?}`. See [How memory works](/concepts/memory-model).
 </ParamField>
 
 <ParamField body="options" type="object">
-  Optional dual-write toggles: `{ write_active: bool = true, write_passive: bool = true }`. Disabling either lets advanced callers bypass one of the storage tiers.
+  Optional write toggles: `{ write_active: bool = true, write_passive: bool = true }`. Advanced callers can disable one storage tier.
 </ParamField>
 
 <ParamField body="metadata" type="object">
-  Free-form metadata. **Currently stored but not surfaced** in retrieval — reserved for future filters.
+  Free-form metadata. It is stored today and reserved for future filters.
 </ParamField>
 
 ## Response — `202 Accepted`
@@ -70,7 +70,7 @@ Content-Type: application/json
 </ResponseField>
 
 <ResponseField name="active_fragment_ids" type="array[string]">
-  Active-memory fragment ids — already recallable.
+  Active-memory fragment ids. These are already recallable.
 </ResponseField>
 
 <ResponseField name="passive_job_id" type="string | null">
@@ -127,4 +127,4 @@ resp.raise_for_status()
 
 ## Idempotency
 
-Tex computes a stable hash per turn (`role + text + timestamp`). Re-sending the same turn is a no-op — no duplicate fragments, no double-billing. Safe to retry on network failure.
+Tex computes a stable hash per turn from `role`, `text`, and `timestamp`. Re-sending the same turn is a no-op. It does not create duplicate fragments or double bill the turn. It is safe to retry after a network failure.

api-reference/memory/recall.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Recall memory"
-description: "Retrieve the most relevant slice of memory."
+description: "Search memory with a natural-language query and get ranked hits, confidence, and usage."
 api: "POST https://api.getmetacognition.com/recall"
 ---
 
-REST equivalent of `tex.recall(...)`.
+This is the REST version of **`tex.recall`**. Use it before generation to get the memory your model should read. For **`mode`**, **`top_k`**, and confidence, see [Recall and ranking](/concepts/retrieval).
 
 ## Headers
 
@@ -29,23 +29,23 @@ Content-Type: application/json
 ```
 
 <ParamField body="scope.org_id" type="string" required>
-  Your org id (≥ 1 char). Server uses the JWT's `org_id` claim for tenancy regardless — this field is required for Pydantic validation only.
+  Your org id. Minimum length is 1 character. The server still uses the JWT's `org_id` claim for tenancy; this field is required for request validation.
 </ParamField>
 
 <ParamField body="scope.session_id" type="string">
-  Session to search. Optional — falls back to the JWT's `session_id`.
+  Session to search. Optional. Falls back to the JWT's `session_id`.
 </ParamField>
 
 <ParamField body="q" type="string" required>
   Natural-language query. `min_length=1`.
 </ParamField>
 
 <ParamField body="mode" type='"active" | "deep"' default='"active"'>
-  Retrieval depth. See [retrieval](/concepts/retrieval).
+  Retrieval depth. See [Recall and ranking](/concepts/retrieval).
 </ParamField>
 
 <ParamField body="top_k" type="integer">
-  Hits to return across all kinds. **Defaults to 15 (active) / 25 (deep).** Pydantic validates `1 ≤ top_k ≤ 50`; the runtime then caps at **30**, so values above 30 are silently clamped.
+  Hits to return across all kinds. **Defaults to 15 (active) / 25 (deep).** Request validation accepts `1 <= top_k <= 50`; runtime caps the final value at **30**.
 </ParamField>
 
 <ParamField body="include_timeline" type="boolean" default="false">
@@ -63,7 +63,7 @@ Content-Type: application/json
 </ResponseField>
 
 <ResponseField name="hits.entities" type="array">
-  Linked entities. Each entity has `{id?, label, score}` — **not** the same shape as turns/observations.
+  Linked entities. Each entity has `{id?, label, score}`. This is different from turns and observations.
 </ResponseField>
 
 <ResponseField name="confidence" type="number">
@@ -82,7 +82,7 @@ Content-Type: application/json
   `{tokens_in, tokens_out}` for this call.
 </ResponseField>
 
-### Hit shape
+### Hit fields
 
 ```json
 {