Publish the user guides at t3.codes/docs through the existing Astro site

[voltcrash]

Problem

T3 Code already has user guides for installation, permissions, multiple provider accounts, and remote access in docs/user. Reading and navigating them currently means going through GitHub. t3.codes/docs returns a 404, and the upstream README says there is no docs site yet.

#6913 raises the same discoverability problem. One commenter missed the guides because they were looking on the website. This proposal puts forward a specific approach using the existing marketing site.

Proposed approach

Publish the existing user guides at t3.codes/docs, using Astro Starlight within apps/marketing.

• Read the Markdown directly from docs/user, so GitHub and the website share one source and contributors keep editing the same files.
• Provide search, a grouped sidebar, and a table of contents, with navigation that works on phones as well as desktop.
• Build and deploy the docs with the existing marketing site, using its current hosting setup.
• Add a Docs link to the site's navigation and footer, and update the README to point to the published guides.
• Match the site's existing visual style, keeping the docs styling scoped to /docs pages.

The initial scope would cover the existing user guides, a docs landing page, and the metadata and link handling needed to render those guides on both GitHub and the website. Maintainer documentation would stay in the repository.

Alternatives and tradeoffs

Starlight provides routing, navigation, and search, but it adds a dependency to the marketing build. The prototype also needed a compatible Astro version, link adaptation, and styling overrides that would need maintaining.

Rendering the guides with plain Astro would reduce the framework integration, though navigation and search would need their own implementation. Linking directly to the GitHub guides from the website would be a smaller first step if maintainers prefer that scope.

Prototype and approval

I opened PR #13573 before getting approval of the direction and scope. It was closed pending that agreement. The PR contains a prototype and desktop/mobile screenshots for context.

Would maintainers approve publishing the existing guides within the current marketing site using Starlight, with the scope above? I'm happy to adjust the approach or narrow the first version. If approved, I'd link the approval and request reconsideration of the PR, or submit a focused replacement reflecting the agreed scope.

[joshka]

I use the app all day, and when I want to know what something in it does, I'd like to look it up from the app itself: a Help → Documentation item, plus a matching command palette entry so web and mobile get it too.

My example was Settle in the thread sidebar. The answer is already written down in docs/user/thread-sidebar.md, but nothing in the app points there. So my options were reading source, reading release notes, or asking an agent and getting a model's reading of the code instead of the intended behavior. Today the desktop Help menu only has "Check for Updates...", and web and mobile have no help entry.

This doesn't have to wait for t3.codes/docs. The menu item can open the docs/user guides for the running version (GitHub at the release tag, or bundled into the build), and switch to the site if it ships.

Future work: this only stays useful if the guides stay current. AGENTS.md already asks for docs/user updates in the same PR as the change; making that a firmer part of opening a PR would keep the docs behind the Help menu accurate.

🤖 Claude Opus 5.5