docs: rebuild the site as a complete Mintlify suite reference

[echobt]

Rebuilds this repository as a complete Mintlify documentation site for the Cortex suite, derived from CortexLM/backend and the desktop, CLI, bot and design clients rather than from the previous copy. The reader picks an application from the navbar and stays inside it; every product gets a full section instead of a single overview page.

main was force-rolled-back to 8a077c7 first, so the French commit is no longer reachable there. This branch builds on that commit.

---

What this is

• 173 pages, all new or rewritten, across 8 navbar tabs and 37 sidebar groups.
• Built on the default Mintlify starter ("theme": "mint"), extended rather than replaced: starter colours, top navbar, global anchors and footer are intact.
• No images anywhere. Every visual is a Font Awesome icon on a <Card>, a tab, a group or a page's frontmatter. There is no /images/ directory and a CI check fails the build if an image tag or asset path reappears.
• Every page carries an icon; every <Card> carries icon=; every page ends in a ## Related block so no page is a dead end.

Navigation

The navbar is the product switcher. One tab per application, then a shared reference tab.

Tab	Icon	Pages	Groups
Get started	rocket	18	Welcome (4), Your account (7), Apps and downloads (2), Help (5)
Chat	comments	27	Overview (3), Conversations (7), Organize your work (6), Research and creation (6), Connected apps (3), Reference (2)
Code	code	23	Overview (3), Sessions (5), Where code runs (5), Repositories (2), Automate and monitor (3), Configure (2), Reference (3)
Bot	robot	19	Overview (3), Your bots (11), Collaborate (3), Apps (1), Reference (1)
CLI	terminal	28	Get started (4), Use the CLI (10), Automate (2), Configure (4), Extend (6), Reference (2)
Design	pen-ruler	12	Overview (2), Work with designs (7), App and settings (3)
Security	shield-halved	9	Overview (3), Reviews and scans (4), Configure (2)
Reference	book-open	37	Errors (26), Platform (5), Bounty program (5), Updates (1)

Each of the 173 pages belongs to exactly one tab, so a page never appears twice in the sidebar and the tab you are in always tells you which product you are reading about.

Also in the chrome: global anchors for Changelog, System status and cortex.foundation; navbar links for Website and Status; a Open Cortex primary button; a three-column footer (Products, Resources, Cortex).

29 redirects keep the old URLs alive, including the whole retired /api/* tree, /security/overview, /platform, /status, /troubleshooting, and the */overview pages that flattened into hub pages.

Error reference

/problems/<code> carries one page per ErrorCode variant in crates/cortex-core/src/error.rs — 24 codes, plus an index and the RFC 9457 explainer. Each page states what the code means, whether it is retryable, which extension members the problem document carries, and what to do about it.

The seven Cortex Security review failure codes deliberately have no /problems/ page and are never linked as though they did: they are review verdicts, not transport problems. A CI check enforces the distinction.

How the content was sourced

Every product claim traces to the shipping code: the backend crates and the api-types package for the service surface, and the desktop, CLI, bot and design clients for what a user actually sees and clicks. Product strings are quoted as the product spells them, including punctuation.

Where a value could not be traced, the page says so instead of guessing. That shows up as "Not published" in a table cell, or a sentence telling you where in the product to look — for example the Go plan's image, export, attachment and Library figures on Plans and quotas and Limits, and the Design window's install and sign-in story, which is not published yet and is written as such rather than as installation instructions for something you cannot download.

Things the product displays but does not enforce are labelled. Parallel agents is a plan attribute the plan cards show and nothing currently enforces, so the table says that and tells you to handle the matching error code anyway. Bot Rooms controls are drawn in the desktop window but nothing behind them is served on this deployment, so the desktop page documents the controls and then says starting one answers This deployment does not host bot rooms yet. Nothing was started., pointing at Channels as the multi-bot surface that works today.

Nothing in these pages describes sign-in wire protocols, cookies, tokens, session internals, operator configuration keys or named infrastructure. Where a capability needs explaining without those details — account erasure, for instance — the page states what the product's own privacy copy states and stops there.

Checks

All seven gates green on this branch:

node scripts/check-docs-content.mjs             ok (173 page(s))
node scripts/check-docs-site.mjs                ok (24 problem pages; site-only)
node scripts/check-docs-site.mjs ../backend     ok (24 problem pages; 300 router paths)
bash scripts/tests/check-docs-content.test.sh   ok
bash scripts/tests/check-docs-site.test.sh      ok
node scripts/tests/docs-ui.test.mjs             starter theme, product tabs, icons, anchors and footer passed
npx mint@4.2.876 validate                       build validation passed

check-docs-site.mjs validates docs.json against the tree both ways (every nav entry, group root, navbar link and internal href resolves to a real MDX file; no file is orphaned), checks the problem-page contract against error.rs and errors.ts, checks documented /v1/ paths against router.rs, and fails on images, sign-in internals and missing frontmatter. check-docs-content.mjs is new here and checks what is inside a page: the forbidden-vocabulary list, the 160-character description ceiling Mintlify renders into meta tags, titles unique across the site, API paths appearing off the API pages, internal links resolving and external ones staying inside the allowlist, the closing ## Related section, a 250-word minimum, balanced MDX components, icon= on every card and a <CardGroup> on every hub.

Each checker has a test beside it that seeds a throwaway site and proves every rule it claims actually fires, rather than passing because a rule went quietly dead. The content checker's test also pins its two deliberate exemptions: the card-suit block stays outside the emoji range, and the 24 problem pages stay exempt from the icon, closing-section and length rules. Both exemptions are the kind a later edit breaks by accident, and one of them, the hub rule, did go dead once while this script was being written and was caught by counting its own derived hub set against the eight pages it was meant to cover.

Two sweeps ran over the finished tree beyond the gates:

• Product-string fidelity. A sweep extracts every backticked or bolded string in the source notes that contains an em dash, 180 of them, and searches every page for a hyphenised copy. Five damaged strings were found and restored, in chat/deep-research.mdx, chat/models.mdx (two), chat/streaming.mdx and design/desktop.mdx; the sweep now returns zero. It extracted only backticked strings at first, which left the notes' bolded strings outside it; widening it to both and re-running found no further damage. It still cannot catch an em dash replaced by a comma rather than a hyphen. One of those was found by reading, in security/troubleshooting.mdx, so the class is not hypothetical and a reviewer who spots another is doing the sweep a favour.
• Cross-page figures. The recurring numbers were checked for agreement across every page that prints them: the 10 MB per-file attachment ceiling, the separate 10 MiB sandbox-output collection cap, the 4 MB bug-report screenshot limit, the 25 MiB dictated-clip limit, the 262,144 / 32,768 / 16,384 model context and output figures, and the 35-day backup window. All agree, and MB / MiB are used as the source uses them.

Judgement calls worth a reviewer's eye

1. api.cortex.foundation is named on six pages. The public bounty API paths are printed relative, but five CLI and getting-started pages name the host directly. The note covering that host asks for a docs-owner confirmation before publishing it. It is either right everywhere or wrong everywhere, so please confirm the host and I will leave it or strip it from all six in one change.
2. /bot/desktop keeps the window's own "Agents" vocabulary. The rest of the Bot tab says "bot". The desktop window's rail is labelled Agents, and renaming it on the page would invent a label that does not exist in the product, so the page uses the window's words and the surrounding pages use ours.
3. The bot idle timeout is published as 30 minutes on /bot/desktop only. The desktop notes source that figure to a service code path; the bot notes could not find it and asked for it to be left out. /bot/computer therefore describes the behaviour without a figure and /bot/desktop prints the sourced one. If you would rather have one answer in both places, say which.
4. reference/limits.mdx publishes the 48 tool-round ceiling but withholds the transport rate-limit internals. The tool-round number is a ceiling a user can actually hit while working; the rate-limiter configuration is operator material.
5. Attachment ceiling mismatch, for escalation. Two sources disagree on the per-plan attachment ceiling: one records a flat 10 MB wherever attachments are allowed at all, the other implies a plan-varying limit. The pages publish the flat 10 MB because that is what the composer enforces in the browser and what the refusal string says, and they note that a plan that permits no attachments refuses every upload with a separate message. Worth resolving at the source.
6. /cli/hooks documents the hook surface that runs, not the one the notes describe. The source notes describe a shell-hook configuration file. The shipping tree disagrees: the hooks crate is compiled and is an engine dependency, but it is only re-exported, never called, and no code path loads such a file. A session asked for the matching command answers that the command is unsupported and that no operation was performed. So the page documents the hook surface plugins actually subscribe to, and the notes' version is not published. Wherever the notes and the code disagreed, the code won.
7. The in-session model command is documented under its canonical name. The notes call it /models. The command table registers model as canonical, with models, m, lm and list-models as aliases, so the reference table leads with /model, lists the aliases, and says in as many words that either spelling works. Pages that describe the picker in passing keep the plural, because that is what most people type.
8. One lint rule was narrowed instead of the content being changed. The repository linter forbids emoji by codepoint range, and its range swallowed the card-suit block. The terminal interface genuinely prints the diamond as a row marker, in a string the source itself documents as ♦ Thought for Xs. The range now excludes that block, with a comment saying why, so the quoted product string stands. The alternative was to damage a real product glyph, which is exactly the class of defect the two sweeps exist to catch.
9. Declared-but-refused CLI flags are documented as refused, not omitted. The CLI tab was reconciled against the shipping code a second time, and the headless surface was the worst offender: cortex exec and cortex run each declare a set of flags that their own runtime-contract check rejects before a turn is submitted, and the pages had published ten of them as working table rows plus three runnable examples. Sampling, --max-tokens, --retry, --no-cache, --share, --add-dir, --attach, --skip-permissions-unsafe and --auto low/--auto medium are all in that category. Silence was the other option, since --help still lists them; the pages instead name each one and quote the refusal, on the grounds that a reader who has just read --help needs to be told which half of it runs. Two smaller cases follow the same rule: trusted_directories is parsed and merged from both config layers and then never read by anything, so the tables say so instead of describing a behaviour it does not have, and --system is documented as its own help text describes it, additional user context rather than a system-prompt override, which is the opposite of what the page previously said. Three invented cortex config subcommands were replaced with the real surface, the credential resolution order was corrected on two pages where it was printed backwards, and three of the ten values in the execution-defaults block were wrong.

Not included

No images, by design. No public inference API reference: there is no public inference API to document yet, and reference/platform-api says so rather than describing one that does not exist. No operator or deployment guide.

Test plan

• node scripts/check-docs-content.mjs and both scripts/check-docs-site.mjs runs pass from a clean checkout
• bash scripts/tests/check-docs-content.test.sh and bash scripts/tests/check-docs-site.test.sh pass
• node scripts/tests/docs-ui.test.mjs passes
• npx mint@4.2.876 validate passes, and mint dev renders eight tabs with the navbar working as the product switcher
• Click one page per tab and confirm the sidebar never shows a page belonging to another product
• Spot-check the 29 redirects, in particular the retired /api/* tree and the */overview pages that flattened into hubs
• Decide the nine judgement calls above, starting with whether api.cortex.foundation should be published at all

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cortex-foundation-add13747	🟢 Ready	View Preview	Sep 16, 2026, 5:46 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[echobt]

@greptileai