docs: restructure the public IA and fix duplicate page titles

.github/workflows/ci.yml

@@ -21,7 +21,6 @@ jobs:
           node-version: 22
       - run: node scripts/check-docs-site.mjs
       - run: bash scripts/tests/check-docs-site.test.sh
-      - name: Check the FernDesk write-path retry policy
-        run: python3 scripts/tests/ferndesk-sync-retry.test.py
+      - run: node scripts/tests/docs-ui.test.mjs
       - name: Validate the Mintlify build
         run: npm exec --yes --package=mint@4.2.876 -- mint validate

.gitignore

@@ -2,9 +2,5 @@
 .mintlify/
 node_modules/
 
-# Python bytecode from scripts/tests
+# Python bytecode from scripts
 __pycache__/
-
-# FernDesk sync local caches (never commit API-derived IDs casually)
-.ferndesk-slug-cache*.json
-ferndesk-sync-summary.json

AGENTS.md

@@ -10,8 +10,16 @@ repository root, not in `apps/docs`. Preview and validation commands are in
 - Preserve the Home + Documentation navbar and ink-on-cream CTAs.
 - Keep every navigation slug backed by a page and every problem page's
   `type` URL on `https://docs.cortex.foundation/problems/{code}`.
+- One hub page per product (`<product>/index.mdx`). Do not add a second
+  overview page beside it, and give every page a `title`, a `description`,
+  and a closing **Related** or **Next** section.
+- Keep `description` under 160 characters so it is not truncated in search
+  results and link previews. Where the product's sidebar label differs from
+  the page title (the sidebar says **Artifacts**, the page is **Library**),
+  add the label to `keywords` so either term finds the page.
 - Run `node scripts/check-docs-site.mjs` and
   `bash scripts/tests/check-docs-site.test.sh`, then
+  `node scripts/tests/docs-ui.test.mjs` and
   `npm exec --yes --package=mint@4.2.876 -- mint validate` before committing.
 - For error-code or endpoint changes, also run the checker with a backend
   checkout as its first argument. Coordinate the two PRs; the backend owns

README.md

@@ -27,20 +27,57 @@ the content directory set to the repository root (not `apps/docs`).
 
 Every Cortex custom domain that CNAMEs to a third-party hostname is a
 **Direct CNAME (DNS only)** — `docs.cortex.foundation` (Mintlify),
-`status.cortex.foundation` (status page), the FernDesk **Connect domain**, and
-the `software.cortex.foundation` / `releases.cortex.foundation` R2 custom
+`status.cortex.foundation` (status page), and the
+`software.cortex.foundation` / `releases.cortex.foundation` R2 custom
 domains owned by
 [`CortexLM/backend`](https://github.com/CortexLM/backend)
 (`docs/software-cdn.md`).
 
 > **Use a Direct CNAME (DNS only). Do not enable orange-cloud Proxied** — that
 > causes Cloudflare **Cross-User Banned** (Error 1014).
 
+## Structure
+
+Mintlify is the single source of truth for the public docs. There is no
+downstream mirror to sync: the site publishes from this repository, branch
+`main`, and `docs.json` is the whole navigation.
+
+| Tab | Holds | Entry point |
+| --- | --- | --- |
+| Get started | Quickstart, what Cortex is, accounts, plans, settings, downloads, help | `getting-started/quickstart` |
+| Chat | The conversation product — projects, Library, plans, models, tools, research, media | `chat/index` |
+| Code | The coding agent — sessions, modes, GitHub, runtimes, review | `code/index` |
+| Bot | The computer-using agent — computer, tools, approvals, routines, skills | `bot/index` |
+| CLI | The terminal front-end to Code — install, TUI, slash commands, sessions, headless, extend | `cli/index` |
+| Design | Canvases and the Design library | `design/index` |
+| API | The RFC 9457 problem format and the catalog of error codes | `api/overview` |
+| Changelog | Dated release notes, and the deferred Platform API | `changelog` |
+
+Each product tab opens on a single hub page (`<product>/index.mdx`). Do not
+re-introduce a second overview page beside it — one entry point per product,
+with the task guides beneath it in the sidebar.
+
+Every page ends with a **Related** or **Next** section so a reader is never at
+a dead end, and every page carries a `title` and a `description` in its
+frontmatter. Product pages also carry an `image` for link previews.
+
+Keep `description` under 160 characters — longer text is truncated in search
+results and link previews. Titles are unique across the site; where two pages
+would otherwise collide (`Sessions` in Code and in the CLI, `Canvases` in Chat
+and in Design) the title carries the product and `sidebarTitle` keeps the
+sidebar short.
+
+Where the product's sidebar label differs from the page title, list the label
+in `keywords` so either term finds the page. The sidebar says **Artifacts**;
+the page is [Library](/chat/library). It says **Planning**; the page is
+[Plans](/chat/plans). It says **Agents**; the page is [Cortex Bot](/bot).
+
 ## Checks
 
 ```bash
 node scripts/check-docs-site.mjs
 bash scripts/tests/check-docs-site.test.sh
+node scripts/tests/docs-ui.test.mjs
 npm exec --yes --package=mint@4.2.876 -- mint validate
 ```
 
@@ -71,6 +108,10 @@ that adds the code. The full check fails when:
 Do not invent endpoints. There is no inference Platform API section here — see
 `platform.mdx`. Sign in via the app; this tree has no auth stack.
 
+`scripts/check-docs-site.mjs` enforces all of the above, including that every
+`docs.json` navigation slug resolves to a page. Run it before pushing; a
+sidebar link with no MDX behind it would otherwise publish as a 404.
+
 ## Visuals
 
 Brand green `#1F4945` is for doodle accents, illustration focus rings, and

api/errors.mdx

@@ -1,9 +1,10 @@
 ---
 title: "Errors"
-description: "RFC 9457 problem+json. Branch on code. type URIs live on this site."
+description: "Every Cortex failure is an RFC 9457 problem document. Branch on code, read request_id, and know which fields are safe to render."
+keywords: ["problem json", "error handling", "status codes"]
 ---
 
-Every failure is `application/problem+json`:
+Every failure Cortex returns is an `application/problem+json` document:
 
 ```json
 {
@@ -16,14 +17,39 @@ Every failure is `application/problem+json`:
 }
 ```
 
-- **`code`** is the contract. Mirror: `@cortex/api-types` `ErrorCode`.
-- **`title` / `detail`** are English, for logs and humans reading raw JSON.
-  The web app renders catalog copy. Three codes may show `detail` as a
-  secondary line: `validation_failed`, `bad_request`, `invalid_state`.
-- **`type`** is dereferenceable: [Problem catalog](/problems).
-- **`request_id`** is always present and safe to show.
+## Fields
 
-User-facing `detail` names a product surface, never a vendor ("The audio
-service is temporarily unavailable.", not a subprocessor's name).
+| Field | Always present | What to do with it |
+| --- | --- | --- |
+| **`code`** | Yes | **This is the contract.** Branch on `code`, never on `title` or `detail`. The same code means the same thing on every surface. |
+| **`type`** | Yes | A dereferenceable URL for the code — [Problem catalog](/problems). Stable; safe to link. |
+| **`status`** | Yes | The HTTP status. Present in the body as well so a logged document is self-describing. |
+| **`request_id`** | Yes | Always present, always safe to show or log. Quote it when reporting a problem. |
+| **`title`** | Yes | English, for logs and humans reading raw JSON. Do not render it to end users. |
+| **`detail`** | Sometimes | English, for logs and humans reading raw JSON. Do not render it to end users. |
 
-Full catalog: [Problems](/problems).
+## Rendering rules
+
+The web app renders catalog copy for a code rather than the wire text. If you are building a client against these documents, do the same.
+
+- **Render your own copy** for `code`. The catalog page for each code explains the situation in product language.
+- **Do not render `detail`.** It is diagnostic text, and it may name an internal component or a specific resource id.
+- **Three codes may show `detail` as a secondary line**: `validation_failed`, `bad_request`, and `invalid_state`. Even there it is supplementary, not the message.
+- **User-facing text never names a vendor.** `detail` names a Cortex surface — *The audio service is temporarily unavailable.* — never a subprocessor.
+
+## Handling a code
+
+| Situation | What to do |
+| --- | --- |
+| The catalog marks the code **Retryable: yes** | Retry after the delay the response suggests, then back off. |
+| The catalog marks it **Retryable: no** | Retrying the same request will fail the same way. Change the request, the plan, or the state. |
+| You see `rate_limited` or `quota_exceeded` | Both are HTTP 429 but mean different things — transport throttling versus a plan window. See [Plans and quotas](/getting-started/plans). |
+| You see `internal` or an upstream code | Keep the `request_id`. Check [status.cortex.foundation](https://status.cortex.foundation) if it repeats. |
+
+Full list with statuses and retry guidance: [Problem catalog](/problems).
+
+## Related
+
+- [Problem catalog](/problems) — every code, status, and retry answer.
+- [Public API](/api/overview) — what this tab covers.
+- [Troubleshooting](/getting-started/troubleshooting) — what to do about a message you see in the product.

api/overview.mdx

@@ -1,22 +1,37 @@
 ---
 title: "Public API"
-description: "Problem type URIs. Sign in via the app. The inference Platform API is coming soon."
+description: "What this site documents about the Cortex API — the RFC 9457 problem format and its type URIs. Sign in via the app."
+keywords: ["reference", "error format", "RFC 9457"]
 ---
 
-This site is **end-user product documentation** for Cortex Chat, Code, Bot, and Design.
+Cortex is used through its apps, not through a public API you write against. This tab documents the one part of the wire contract that is public and stable: the shape of an error.
 
-**Sign in at [cortex.foundation](https://cortex.foundation).** The CLI and desktop app use the same account. This site does not document login, sessions, or identity-provider wire protocol.
+**Sign in at [cortex.foundation](https://cortex.foundation).** The CLI and the desktop apps use the same account. This site does not document login, sessions, or identity-provider wire protocol.
 
 ## What is public here
 
-- [Problem catalog](/problems) — RFC 9457 `type` URIs (`https://docs.cortex.foundation/problems/{code}`)
-- [Errors](/api/errors) — how a problem document is shaped
-- Product guides: [Chat](/chat), [Code](/code), [Bot](/bot), [Design](/design)
+| Page | What it covers |
+| --- | --- |
+| [Problem catalog](/problems) | Every `type` URI — `https://docs.cortex.foundation/problems/{code}` — with its HTTP status and whether retrying helps |
+| [Errors](/api/errors) | How a problem document is shaped and which fields you can rely on |
+| [Platform API](/platform) | Why there is no inference API yet |
+
+Product guides live under their own tabs: [Chat](/chat), [Code](/code), [Bot](/bot), [CLI](/cli), [Design](/design).
+
+## Why the error format is public
+
+Every Cortex surface — the web app, the desktop apps, and the CLI — reads the same problem documents. When something fails, the message you see names a Cortex surface and carries a stable `code`. Publishing the codes means the message in the product, the message in the terminal, and this catalog all say the same thing.
 
 Connect apps and GitHub from **Settings** and **Customize** in the product. There is no public plugin webhook catalog on this site.
 
 ## What is not here
 
-- Authentication, session cookies, device codes, or identity-provider internals
-- The app's private session API
-- An inference Platform API — [Coming soon](/platform), with **no endpoints**
+- Authentication, session cookies, device codes, or identity-provider internals.
+- The app's private session API. It is not a supported integration surface.
+- An inference Platform API. See [Platform API](/platform) — no endpoints, SDKs, or keys exist.
+
+## Related
+
+- [Errors](/api/errors) — the problem document format.
+- [Problem catalog](/problems) — all codes in one table.
+- [Troubleshooting](/getting-started/troubleshooting) — what to do when you see one.

bot/approvals.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Approvals"
 description: "Allow / Deny / Always. A bot parks consequential steps — connected-app changes and dangerous computer actions — and nothing runs until you choose."
+keywords: ["permissions", "Allow", "Deny", "Always", "parked step"]
 ---
 
 A bot can act, so it asks first. When it reaches a step that changes something in a connected app or could damage its computer, it **parks** the action and shows an approval widget in the conversation. The widget names the tool and what it is about to do.

bot/computer.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Computer"
-description: "The Computer rail is a live desktop on a Cloud guest — screen, browser, shell — not a slideshow of screenshots. Web is Cloud-only; This PC lives on the Bot desktop app."
+description: "The Computer rail is a live desktop on a Cloud guest — screen, browser, shell — not a slideshow of screenshots. Web is Cloud-only."
+keywords: ["desktop", "guest", "This PC", "SSH", "sleep"]
 ---
 
 Every bot can have a computer. In the web app it is an isolated Cloud guest with a desktop, and the **Computer rail** on the right of the open bot shows that desktop live while the bot works.

bot/desktop.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Bot desktop"
 description: "The Cortex Bot desktop app — a home for your agents, routines, and channels, with This PC as a host for a bot's computer. It has no Chat or Code sidebar."
+keywords: ["app", "download", "channels"]
 ---
 
 Cortex ships two desktop apps because the two jobs are different. The [Cortex desktop app](/getting-started/desktop) carries **Chat and Code**. The **Cortex Bot desktop app** is built around bots: its sidebar is **agents, routines, and channels**, and it adds **This PC** as a host for a bot's computer. It does not carry Chat or Code.
@@ -59,5 +60,5 @@ There is no Chat or Code entry in this sidebar. For those, use the web app or th
 
 ## Related
 
-- [Bot overview](/bot/overview)
+- [Cortex Bot](/bot) — what a bot is and how to create your first one.
 - [Downloads](/getting-started/downloads) — every way to run Cortex.

bot/how-it-works.mdx

@@ -1,6 +1,7 @@
 ---
 title: "How Bot works"
-description: "What you see is a few short bubbles, not the inner loop. No round counter; a 15-minute turn deadline; six identical tool calls stop a turn. An active turn wakes a hibernated guest first."
+description: "You see a few short bubbles, not the inner loop. No round counter; a 15-minute turn deadline; six identical tool calls stop a turn."
+keywords: ["loop", "deadline", "guard", "hibernation"]
 ---
 
 A bot's turn is a tool loop on a computer. Most of it is invisible by design: the conversation shows only the messages the bot chose to send you, the questions it asked, the notifications it raised, and the credentials it requested. The screen on the Computer rail shows the rest.
@@ -53,3 +54,10 @@ The planner describes the control it wants — *the Save button in the dialog* 
 | Machine | Snippet sandbox | Headless guest | Guest **with** a desktop |
 
 See [How Chat works](/chat/how-it-works) and [How Code works](/code/how-it-works).
+
+## Related
+
+- [Tools](/bot/tools) — the catalog behind the loop.
+- [Approvals](/bot/approvals) — what parks, and what does not.
+- [Computer](/bot/computer) — the guest the loop runs on.
+- [Bot troubleshooting](/bot/troubleshooting) — turns that stop, and why.