Make Marfa's docs and command line work better for AI agents #573

Summary

Most people reach Marfa through an AI agent that runs the marfa command and reads the docs. A review of the docs site (commit aeb5162), the docs MCP server and marfa v0.0.25 found the basics in place and a short list of gaps. After these sub-issues, an agent finds the right page when it searches by the name an outsider would use, can ask for Markdown the standard way, reads a smaller index, gets typed results from the MCP server, and meets clearer installer output. The maintainers can also see whether agents read the docs at all.

Context

In place and worth keeping as they are: a Markdown copy of every page, llms.txt, a docs MCP server with search, fetch and list tools, marfa docs, and --json with one JSON error object and exit codes on every command.

Gaps, each with its own sub-issue: search misses concepts and often returns a heading as the snippet; a request with Accept: text/markdown gets HTML; llms-full.txt is 754,448 bytes; the MCP tools return JSON inside a text block with no structuredContent; the installer never says which port a tunnel must point at; background folder sync cannot run without the login keychain; no request to the agent addresses is counted; documented commands and flags are not checked against the command reference.

Acceptance criteria

• Every sub-issue is closed.
• --json output, error codes and exit codes of every command are unchanged.

Out of scope

• A hosted service that writes answers. The calling agent writes the answer from the passages the search returns.
• Moving the docs to another documentation platform.
• Embeddings or hybrid search, until the test queries from the search sub-issue show misses that tuning and page wording cannot fix.
• A --plain output mode, --json by default when piped, a full-screen terminal interface.

Notes

The findings come from running marfa v0.0.25, the live docs site and its MCP server on 22 October 2026, and from reading core/marfa-cli and the docs repository.