docs: rebuild the site as a complete Mintlify suite reference

.gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+*.mdx text eol=lf
+*.json text eol=lf
+*.mjs text eol=lf
+*.sh text eol=lf
+*.svg text eol=lf

.github/workflows/ci.yml

@@ -20,7 +20,9 @@ jobs:
         with:
           node-version: 22
       - run: node scripts/check-docs-site.mjs
+      - run: node scripts/check-docs-content.mjs
       - run: bash scripts/tests/check-docs-site.test.sh
+      - run: bash scripts/tests/check-docs-content.test.sh
       - run: node scripts/tests/docs-ui.test.mjs
       - name: Validate the Mintlify build
         run: npm exec --yes --package=mint@4.2.876 -- mint validate

AGENTS.md

@@ -1,31 +1,38 @@
 # Cortex public documentation
 
 This is the Mintlify site for `docs.cortex.foundation`. Edit the site at the
-repository root, not in `apps/docs`. Preview and validation commands are in
-`README.md`.
+repository root. Preview and validation commands are in `README.md`.
 
-- Keep product copy in English and use the Cortex product names and domains.
-- Do not publish authentication/session internals, credentials, private API
-  routes, farm details, or backend operator runbooks.
-- Preserve the Home + Documentation navbar and ink-on-cream CTAs.
-- Keep navigation a flat list of top-level groups (`navigation.groups`).
-  `navigation.tabs` renders a product dropdown in the navbar; the hubs already
-  are that second level, so a tab makes the reader pick Chat twice.
-- 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
+- Keep product copy in English and use the Cortex product names and domains:
+  Cortex Chat, Cortex Code, Cortex Bot, Cortex Design, Cortex Security, the
+  Cortex CLI, Cortex Bounty; `cortex.foundation`, `docs.cortex.foundation`,
+  `status.cortex.foundation`, `software.cortex.foundation`.
+- The site is end-user documentation. Do not publish sign-in wire protocols,
+  session or token internals, credentials, private API routes, infrastructure
+  details, vendor names, or backend operator runbooks. Competitor product
+  names never appear in copy, titles, or `docs.json`.
+- The site carries **no images**. Every page has an `icon` in its frontmatter
+  and every `<Card>` has an `icon`; icons are Font Awesome names (the Mintlify
+  starter default, so `icons.library` stays unset). Do not add `<img>`,
+  `<Frame>`, markdown images, or an `image:` field.
+- Navigation is `navigation.tabs`: one tab per application (Get started, Chat,
+  Code, Bot, CLI, Design, Security, Reference), each tab a list of groups, each
+  tab and group with an icon. Every product tab opens on its hub page
+  (`<product>/index.mdx`). Do not add a second overview page beside a hub.
+- Every page has a unique `title`, a `description` under 160 characters, and a
+  closing **Related** section. Where a sidebar label differs from the title,
+  set `sidebarTitle` and add the alternative name to `keywords`.
+- Keep every navigation slug, footer link, redirect destination, and internal
+  href backed by a page, and every problem page's `type` URL on
+  `https://docs.cortex.foundation/problems/{code}`.
+- Only document API paths on `reference/errors`, `bounty/public-api`, and the
+  problem pages, and only paths the backend router registers.
+- Run `node scripts/check-docs-site.mjs`,
+  `bash scripts/tests/check-docs-site.test.sh`,
+  `node scripts/tests/docs-ui.test.mjs`, then
   `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
-  the API contract and checks this repository in its CI.
+  checkout as its first argument. Coordinate the two PRs; the backend owns the
+  API contract and checks this repository in its CI.
 - Do not change the Mintlify integration, custom domain, or DNS without an
   explicit request.

README.md

@@ -1,14 +1,16 @@
 # Cortex docs (`docs.cortex.foundation`)
 
-Public product documentation for **Cortex Chat**, **Cortex Code**, **Cortex Bot**, the **Cortex CLI**,
-and **Cortex Design**. This site is **end-user visible**. It does **not** document
-login, sessions, refresh tokens, OAuth wire protocol, or other non-public APIs.
-
-This repository is a [Mintlify](https://mintlify.com) site, migrated from
-`CortexLM/backend` at `782b054` (the former `apps/docs` directory).
-Engineering / operator documentation stays in
-[`CortexLM/backend/docs`](https://github.com/CortexLM/backend/tree/main/docs)
-(runbooks, SOC 2 notes, farm internals). Do not merge the two trees.
+Public documentation for the Cortex applications: **Cortex Chat**, **Cortex
+Code**, **Cortex Bot**, the **Cortex CLI**, **Cortex Design**, and **Cortex
+Security**, plus a Reference tab (errors, models, limits, privacy, status,
+the Bounty program, and the changelog). The site is **end-user visible**. It
+does not document sign-in internals, private API routes, or infrastructure.
+
+This repository is a [Mintlify](https://mintlify.com) site built from the
+Mintlify starter kit (`mint` theme, Font Awesome icons, tabs in the navbar).
+Engineering and operator documentation stays in
+[`CortexLM/backend/docs`](https://github.com/CortexLM/backend/tree/main/docs).
+Do not merge the two trees.
 
 ## Preview
 
@@ -18,69 +20,45 @@ cd docs
 npx mint dev --no-open
 ```
 
-Requires Node 20.17+. The site is intended to publish at
-`https://docs.cortex.foundation`. Connecting the custom domain is an operator
-step in the Mintlify dashboard. Connect `CortexLM/docs`, branch `main`, with
-the content directory set to the repository root (not `apps/docs`).
+Requires Node 20.17+. The site publishes at `https://docs.cortex.foundation`
+from branch `main`, with the content directory set to the repository root.
 
 ### Custom-domain DNS
 
 Every Cortex custom domain that CNAMEs to a third-party hostname is a
-**Direct CNAME (DNS only)** — `docs.cortex.foundation` (Mintlify),
+**Direct CNAME (DNS only)**: `docs.cortex.foundation` (Mintlify),
 `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`).
+`software.cortex.foundation` / `releases.cortex.foundation` download hosts
+owned by [`CortexLM/backend`](https://github.com/CortexLM/backend).
 
-> **Use a Direct CNAME (DNS only). Do not enable orange-cloud Proxied** — that
-> causes Cloudflare **Cross-User Banned** (Error 1014).
+> **Use a Direct CNAME (DNS only). Do not enable proxying** on these records.
 
 ## 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.
+`docs.json` is the whole navigation. It uses `navigation.tabs`, one tab per
+application, so a reader picks the product from the navbar:
 
-| Tab | Holds | Entry point |
+| Tab | Holds | Opens on |
 | --- | --- | --- |
-| 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` |
-
-Navigation is **one flat list of top-level groups** — `navigation.groups`, not
-`navigation.tabs`. A tab renders a second-level switcher in the navbar, and the
-product hubs already are that second level; the sidebar would otherwise ask a
-reader to pick Chat twice. `docs-ui.test.mjs` fails if `tabs`, `dropdowns`, or
-`products` come back, or if a product group stops opening its hub.
-
-Each product group is flat: the hub, then every page of that product in reading
-order, then its troubleshooting page. Nested groups inside a product group are
-for reference material only — the problem catalog is the one that remains.
-
-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
+| Get started | Home, quickstart, what Cortex is, choosing a product, accounts and sign-in, two-factor, plans and quotas, settings, data and privacy, notifications, interface language, ways to run Cortex, the desktop app, troubleshooting, shortcuts, bug reports, FAQ, glossary | `index` |
+| Chat | Conversations, models and thinking, attachments, streaming and reconnects, voice, canvases, document export, projects, Library, file sharing, memory, Planning, scheduled tasks, built-in tools, Deep Research, image generation, origin check, Cortex Data, skills, Connectors, MCP servers, page tools, sharing and teams, troubleshooting | `chat/index` |
+| Code | Sessions, Ask / Plan / Agent, approvals, changes and diffs, tickets, cloud runtimes, environments and images, machines, SSH hosts, desktop, GitHub, repositories and branches, automations, notifications, usage, settings, integrations, CLI pointer, review pointer, troubleshooting | `code/index` |
+| Bot | Create a bot, talking to a bot, computer, tools, approvals and tool policy, memory, skills, routines, tasks and subagents, connected apps and secrets, inbox, channels, sharing, teach from a demonstration, Bot desktop app, troubleshooting | `bot/index` |
+| CLI | Install, sign in, quickstart, the TUI, modes and permissions, Plan and Spec modes, sessions, goals, slash commands, shortcuts, tools, cloud / this PC / SSH, editor integration, headless runs, CI cookbook, configuration, environment variables, data locations, permission policy, MCP, skills, agents and subagents, hooks, plugins, themes, command reference, troubleshooting | `cli/index` |
+| Design | Quickstart, canvases, generate and edit, versions, library, export, Bot jobs, Connectors, Design desktop app, settings, troubleshooting | `design/index` |
+| Security | Quickstart, how a review works, checks and comments, review policy, repository scans, Cortex Agent runs, installation and repositories, troubleshooting | `security/index` |
+| Reference | Errors and the problem catalog, models, limits and quotas, security and privacy, system status, Platform API, the Bounty program (pair a hotkey, file a report, verdicts and scoring, Transparency API), changelog | `reference/errors` |
+
+Each product tab opens on a single hub page (`<product>/index.mdx`) with a card
+per page of the tab. Every page carries a `title`, a `description` under 160
+characters, an `icon`, and ends with a **Related** section so a reader is
+never at a dead end. Titles are unique across the site; where two pages would
+otherwise collide (`Sessions` in Code and in the CLI, `Skills` in Chat, Bot,
+and the CLI) 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).
+The site has **no images**. Every visual is an icon (Font Awesome, the Mintlify
+starter default).
 
 ## Checks
 
@@ -91,8 +69,9 @@ node scripts/tests/docs-ui.test.mjs
 npm exec --yes --package=mint@4.2.876 -- mint validate
 ```
 
-The **Docs site** CI job checks navigation, problem-page URLs and the public
-content rules without needing access to the backend.
+The **Docs site** CI job checks navigation, problem-page URLs, frontmatter,
+internal links, and the public content rules without needing access to the
+backend.
 
 To also validate against the real API, pass a backend checkout:
 
@@ -106,41 +85,13 @@ merge the docs page first, then update the backend's checkout pin in the PR
 that adds the code. The full check fails when:
 
 - `PROBLEM_TYPE_BASE` is not `https://docs.cortex.foundation/problems`
-- an `ErrorCode` is missing its `/problems/{code}` page
-- a `docs.json` navigation slug or internal href has no matching MDX page
+- an `ErrorCode` is missing its `/problems/{code}` page, or a page documents a code the API does not emit
+- a `docs.json` navigation slug, group root, navbar or footer href, redirect destination, or internal link has no matching MDX page
 - a documented `/v1/…` path is not registered in `crates/cortex-api/src/router.rs`
-- this tree names a problem-docs host other than `docs.cortex.foundation`
-- the top navbar is not Home + Documentation, or it carries Chat | Code | Bot chrome / `navbar.primary`
-- the home page uses Mintlify Cards as brand-green Install CTAs instead of `.ink-btn`
-- public MDX documents `/auth/`, `/oauth/`, `refresh_token`, WorkOS, or `cortex_rt`
-- `api/authentication.mdx` or `api/oauth.mdx` exist, or the API group lists them
-
-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
-window frames — not hero CTAs. Home and card actions use **ink on cream**
-(`.ink-btn` in `custom.css`) — filled ink, quiet outline; dark mode inverts
-to cream ink. Do not add a brand-green Install / `navbar.primary` button.
-
-Guide heroes that depict the product are **live Cortex screenshots** in
-`images/product/` plus CLI canon in `images/cli/` (vendored from
-CortexLM/cli `docs/media/`). **Every page shows a distinct capture** — no
-product frame is reused on two pages; `images/product/README.md` maps each
-file to the page that uses it, and lists member-only surfaces still to be
-captured. Do not add abstract product-window SVGs. `images/frames/` is
-retired. Banner card art (`images/banners/`) belongs inside `CardGroup`
-grids on Home and the hubs — never as a lone full-width `Card`. Cream, ink,
-`#1F4945` focus — no violet.
-
-Top navbar is Mintlify **Home + Documentation**, not the Chat | Code | Bot
-product switcher. Get started / Chat / Code / Bot / CLI / Design stay as
-top-level **sidebar groups**, not navbar tabs: a tab would put the product
-switcher back in the navbar as a dropdown. Competitor product names never
-appear in copy, titles, or `docs.json`.
+- a page carries an image, lacks a title, description, or icon, repeats another page's title, or has a description over 160 characters
+- navigation is not `navigation.tabs` with a tab for each of Chat, Code, Bot, CLI, Design, and Security, each tab and group carrying an icon
+- public MDX documents `/auth/`, `/oauth/`, `refresh_token`, the identity vendor, or the session cookie
+- `api/authentication.mdx` or `api/oauth.mdx` exist, or the navigation lists them
+
+Do not invent endpoints. There is no inference Platform API section here; see
+`reference/platform-api.mdx`. Sign in via the app; this tree has no auth stack.