Docs site

WhatCopy Anchor Link

apps/docs is a small Next.js app built with Fumadocs. It renders the docs/ folder at the repo root: the plan, the architecture page, the guides and the anecdotes. Nothing is copied; the Markdown you read on GitHub is the same file the site serves.

Besides pages, it exposes the docs in three ways that are meant for agents:

Search for humans is the dialog behind ⌘K; it calls /api/search (Orama, built at compile time, no external service).

WhyCopy Anchor Link

Contributor docs are only useful if they are easy to find and easy to feed to an agent. GitHub gives us neither search across pages nor a Markdown feed. Fumadocs gives both for little code, and its MCP server is the same kind of tool Vektos measures: "what happens when an agent has a search tool over the project docs?"

The MCP server here is a dogfooding step. When the rag package exists (week 3), the Ask AI chat will use it, and we will be able to compare the two.

Try itCopy Anchor Link

bun run docs                  # http://localhost:3001 opens the architecture page

Then, in another terminal:

curl -s localhost:3001/llms.txt
curl -s "localhost:3001/api/search?query=preflight"

Connect an agent to the MCP server with:

{ "mcpServers": { "vektos-docs": { "url": "http://localhost:3001/api/mcp" } } }

and ask it to search the docs for "escape hatch". You should see a search call, then a get_page call on /docs/guides/03-graders.

Extend itCopy Anchor Link

• New page. Add a .md file under docs/ with a frontmatter title: and description:. Do not repeat the title as an # H1; the layout renders it. Add the file name to the pages array of the folder's meta.json to control its position.
• New folder. Create it with a meta.json (title, pages) and list the folder in docs/meta.json.
• Links. Relative links between files (./02-lint.md, ../anecdotes/01-token-table.md) work on GitHub and on the site: createRelativeLink rewrites them at build time.
• Diagrams. A ```mermaid block is rendered to SVG on the server by Pele (src/components/mermaid.tsx), so no client-side Mermaid is shipped. Colors follow the site theme through CSS variables in global.css.
• MDX options live in apps/docs/source.config.ts. Collections live in src/lib/source.ts through the macro API.

Known gapsCopy Anchor Link

• Content changes outside apps/docs are not always noticed by the build cache. If a page looks stale after next build, delete apps/docs/.next and apps/docs/.source.
• Tailwind is a dependency of Fumadocs UI and is used only inside apps/docs. The design system stays on Panda; nothing from Tailwind leaks into packages/ds.
• PLAN.md is long and written as a working document. It is served as is.
• next-themes@0.4.6 renders its theme <script> on the client too, and React 19.2+ warns about it in dev. src/components/provider.tsx gives that client copy a non-JS type so the warning goes away; the server copy still applies the theme before first paint. Remove the wrapper once next-themes#385 ships a fix.
• No Ask AI yet. It comes with the rag package so it can use our own retrieval.
• The site is not deployed. bun run docs:build produces a standard Next.js output.