docs: restructure the public IA and fix duplicate page titles

[echobt]

What this is

A structural pass over the public docs at docs.cortex.foundation: one entry point per product, navigation grouped by task, pages findable by the labels the product actually uses, and a fix for a title-rendering bug. Docs-only — no backend or product code is touched.

This PR is intentionally a draft. Do not merge.

Why

The site was complete but harder to navigate than it needed to be. Three concrete problems drove the change:

1. Every product had two competing entry points. chat/index ("Chat guides") and chat/overview ("Overview") both tried to introduce Chat, and the sidebar showed both.
2. 26 pages rendered two <h1> elements. A body heading duplicated the frontmatter title. Verified against live HTML: rate_limited emitted both <h1 id="page-title"> and a second <h1 id="rate_limited">.
3. The sidebar and the docs disagreed on names. The product says Artifacts, the page is Library. It says Planning, the page is Plans. Searching the label you see on screen did not find the page.

Chat was also the only product tab with no troubleshooting page, while Code, Bot, and CLI each had one.

IA before and after

Tab	Before	After
Get started	3 groups, no group roots	3 groups with roots; Quickstart, Downloads, Troubleshooting open their group
Chat	5 groups, hub + overview	Hub + quickstart + tasks, Models/tools, Research/media, Context, How it works, Help
Code	4 groups, hub + overview	Hub + quickstart + sessions + modes, Repositories, Where it runs, How it works, Help
Bot	4 groups, hub + overview	Hub + quickstart + computer + tools, Control and scheduling, Desktop, How it works, Help
CLI	5 groups	Unchanged shape, cli/index as the group root
Design	2 groups, hub + overview	One group: hub, canvases, desktop, library
API	Public + Problems	Unchanged, with root pages so group titles open something
Changelog	Release notes + Coming soon	Unchanged

Each product tab now reads: hub, task guides, Help. Groups carry root pages so clicking a sidebar title opens a real page instead of only expanding.

Page inventory

	Count
MDX pages before	99
MDX pages after	96
Added	1 (chat/troubleshooting)
Removed	4 (merged `chat

Removed pages keep working: /chat/overview, /code/overview, /bot/overview, and /design/overview are 301-redirected to the product hub. New redirects also cover /chat/artifacts, /code/goals, /troubleshooting, and /getting-started/desktop-app. All 20 redirects were checked to resolve to a real page with no chains.

No orphans, no dead navigation entries, no broken internal links, no duplicate titles (all checked mechanically).

Titles and search

• Removed the redundant body # heading from all 24 problem pages, platform.mdx, and status.mdx. Every title now comes from frontmatter exactly once.
• Gave Sessions and Canvases product-qualified titles, because each name covered two different pages and the pair was indistinguishable in search. sidebarTitle keeps the sidebar short, so both still read "Sessions" and "Canvases" where space is tight.
• Added keywords to every content page so the product's own label finds the page. Artifacts to Library, Planning to Plans, Agents to Cortex Bot, Customize to Connectors to Tools.
• Trimmed 19 descriptions under 160 characters, the point where search results and link previews truncate them. No claim changed.

Content

• chat/troubleshooting.mdx (new) — turns, files and images, models and research, voice, quotas and access. Grounded in behavior already documented on the other Chat pages.
• platform.mdx — was a placeholder telling contributors what not to write. Now answers the reader's question: no endpoints, no SDK, no keys, what to use instead, and how a launch would be announced.
• problems/index.mdx — added a status-family table and a note on the two different 429s (rate_limited versus quota_exceeded).
• api/overview.mdx, api/errors.mdx — practical guidance on which problem fields to branch on and which are unsafe to render.
• Cross-links — every page now ends with a Related or Next section; 27 previously ended without one. Home gained a reference grid and a product chooser.

Copy stays in English, uses Cortex product names and domains, and mentions no other vendor.

Housekeeping

• FernDesk sync removed (workflow, script, test, docs, CI step, gitignore entries). Mintlify is the source of truth, so there is no downstream mirror to keep current; leaving it would have pushed this rewrite into a second system.
• Checker gap closed. check-docs-site.mjs walked a group's pages but not its root, so a dead group title would have published as a 404. It now walks both, with a regression test. Verified the test fails without the fix.
• Image inventory fixed. images/product/README.md still pointed at the removed overview pages, and bot-public.png had gone unused. Every product screenshot is now used on exactly one page.
• README and AGENTS record the one-hub-per-product rule, the closing-section rule, the 160-character description limit, the unique-title rule, and the keyword convention.

Safety review

• No auth, OAuth, session, or identity-provider internals; no private routes, credentials, or operator runbooks.
• No compliance claim of any kind. security/overview.mdx states plainly that Cortex does not claim SOC 2, GDPR certification, or HIPAA; that is the only place those words appear.
• No competitor names anywhere in the copy, titles, or docs.json.
• Only cortex.foundation domains are referenced.
• Nothing was invented: pages are grounded in behavior already documented in this repo, and the Platform API stays explicitly unbuilt.
• The Home + Documentation navbar and ink-on-cream CTAs are untouched; docs-ui.test.mjs still passes.

Validation

All run locally and green:

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

Also checked mechanically: zero broken internal links, zero orphan pages, zero dead navigation slugs, zero duplicate titles, and every page has a title and a description within length.

The backend contract check (node scripts/check-docs-site.mjs ../backend) was not run here; it needs a backend checkout. No error codes or endpoints changed, so no coordinated backend PR is required.

Follow-ups

• Member-only surfaces still have no screenshots (Code session timeline, Bot setup form and Computer rail, Design canvas, Bot desktop app). images/product/README.md tracks them; this PR adds no fake art.
• platform.mdx will need a real reference if the inference API ships.

[mintlify]

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

Project	Status	Preview	Updated
cortex-foundation-add13747	🟢 Ready	View Preview	Sep 15, 2026, 9:49 PM

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

[echobt]

@greptileai