# Moxie Docs - full context > PR checks that flag doc gaps, living docs re-checked on every merge, MCP context for AI agents, hosted public knowledgebases, and Friday Cleanup PRs from GitHub. This file inlines key Moxie Docs marketing and guide content for AI systems. For a curated link index, see /llms.txt. --- # Moxie Docs > PR checks that flag doc gaps, living docs re-checked on every merge, MCP context for AI agents, hosted public knowledgebases, and Friday Cleanup PRs from GitHub. Moxie Docs is a hosted service that connects to your GitHub repositories, keeps a searchable knowledge base of your codebase in sync on every merge, and serves that context to AI coding agents over MCP. Built by jackalope.digital. ## Product - [Overview](https://moxiedocs.com/): Automated codebase documentation for GitHub - searchable docs, MCP context, and Friday Cleanup PRs. - [How it works](https://moxiedocs.com/workflow): Indexing, doc generation, drift detection, and Friday Cleanup PRs. - [Use cases](https://moxiedocs.com/use-cases): Onboarding, architecture docs, and AI agent context. - [MCP server](https://moxiedocs.com/mcp): How AI agents query your codebase context over the Model Context Protocol. - [Automated code documentation](https://moxiedocs.com/code-documentation): Generate searchable codebase documentation from GitHub automatically. Architecture, conventions, drift detection, MCP context, and Friday Cleanup PRs. - [Documentation drift detection](https://moxiedocs.com/documentation-drift): Detect documentation drift on every merge. Surface gaps and open reviewable Friday Cleanup PRs so wikis do not rot quietly. - [Free tools hub](https://moxiedocs.com/free-tools): Browser-based SQL ER diagrams, README, Mermaid, ADR, AGENTS.md, and llms.txt utilities - no account required. - [Open source](https://moxiedocs.com/open-source): How Moxie Docs supports and works with open-source repositories. ## Agent integrations Connect Moxie Docs MCP context to the agents your team already uses: - [Cursor](https://moxiedocs.com/integrations/cursor): Connect Cursor to your repository's live docs, conventions, and doc gaps over MCP. One setup command after you connect GitHub - no manual context packing. - [Claude Code](https://moxiedocs.com/integrations/claude-code): Give Claude Code repository conventions, generated docs, and doc gaps over MCP - and keep AGENTS.md and CLAUDE.md aligned with the code that ships. - [Codex](https://moxiedocs.com/integrations/codex): Connect OpenAI Codex to live codebase docs and conventions over MCP. Compact context from Moxie Docs for fewer exploratory reads and better edits. - [Windsurf](https://moxiedocs.com/integrations/windsurf): Connect Windsurf to Moxie Docs over MCP for live codebase documentation, conventions, and doc gaps. One setup command after you connect GitHub. - [Cline & Roo Code](https://moxiedocs.com/integrations/cline): Connect Cline and Roo Code to your repository's live codebase docs, conventions, and doc gaps over MCP. Zero manual context packing. - [GitHub Copilot](https://moxiedocs.com/integrations/github-copilot): Give GitHub Copilot Agent Mode live repository conventions and doc gaps over MCP - and keep .github/copilot-instructions.md current. ## Solutions How Moxie Docs maps to each engineering role and organizational setup: - [Solutions overview](https://moxiedocs.com/for): Moxie Docs framed by role and team setup. - [For engineering leaders](https://moxiedocs.com/for/engineering-leaders): Cut onboarding time, kill documentation drift, and see what shipped each week. - [For staff & platform engineers](https://moxiedocs.com/for/staff-engineers): Turn tribal knowledge into source-cited docs that teammates and AI agents follow. - [For CTOs & founders](https://moxiedocs.com/for/ctos): Keep documentation current as AI accelerates the codebase, without a per-seat wiki bill. - [For teams using AI agents](https://moxiedocs.com/for/ai-engineers): Serve Cursor, Claude Code, and Codex real repository context over MCP. - [For startups & early-stage](https://moxiedocs.com/for/startups): Move fast without losing codebase context or burning founder hours on onboarding. - [For scale-ups & growing orgs](https://moxiedocs.com/for/scaleups): Eliminate documentation drift and knowledge silos as your dev team doubles. - [For multi-repo & microservices](https://moxiedocs.com/for/multi-repo-teams): Synchronize architecture maps and MCP context across all your repositories. - [For agencies & consultancies](https://moxiedocs.com/for/agencies): Ramp up on client codebases fast and hand off self-updating documentation. - [For enterprise & security-first](https://moxiedocs.com/for/enterprise): PR-gated documentation governance with predictable repo-based pricing. ## Pricing Three plans, each with a 14-day free trial. Every plan can be billed monthly or annually; annual billing is two months free (about 17% off): - [Starter - $29/mo or $290/yr](https://moxiedocs.com/pricing): For solo builders documenting a handful of private repos. Up to 5 repositories, 1 seat. - [Pro - $79/mo or $790/yr](https://moxiedocs.com/pricing): Hands-off documentation for a growing team: weekly Recaps, automated Cleanup PRs, and room for many repos. Up to 15 repositories, 10 seats. - [Team - $199/mo or $1,990/yr](https://moxiedocs.com/pricing): For organizations with a fleet of services: unlimited seats, priority indexing, and the highest capacity. Up to 50 repositories, unlimited seats. ## Comparisons - [Comparisons overview](https://moxiedocs.com/comparisons): All comparison pages at a glance. - [Moxie Docs vs Mintlify](https://moxiedocs.com/vs/mintlify): Codebase context vs. docs-site agent: Moxie Docs maps your architecture and serves it to coding agents over MCP; Mintlify's AI agent drafts updates to your docs site. - [Moxie Docs vs Jamdesk](https://moxiedocs.com/vs/jamdesk): Generation vs. publishing: Moxie Docs writes and maintains docs from your code; Jamdesk hosts the MDX you author yourself, with flat pricing and reader-facing AI chat. - [Moxie Docs vs Context7](https://moxiedocs.com/vs/context7): Your codebase vs. public library docs: Moxie generates and maintains documentation for your own repository and serves it over MCP; Context7 injects up-to-date third-party library docs into your prompts. - [Moxie Docs vs Swimm](https://moxiedocs.com/vs/swimm): Self-serve vs. sales-led: zero-maintenance codebase wikis from continuous repo analysis, no discovery call required to see pricing or get started. - [Moxie Docs vs Docusaurus](https://moxiedocs.com/vs/docusaurus): Generation vs. publishing: Moxie writes and maintains docs from your source and serves them to agents over MCP; Docusaurus is an open-source static site generator for docs you write and host yourself. - [Moxie Docs vs GitBook](https://moxiedocs.com/vs/gitbook): Code-native vs. cross-functional wiki: code-coupled, AI-generated docs without GitBook's per-seat wiki licensing. - [Moxie Docs vs Google Code Wiki](https://moxiedocs.com/vs/codewiki): Private repos vs. public preview: Moxie Docs documents your private codebase and opens pull requests; Google Code Wiki is a free, read-only wiki for public repos. - [Moxie Docs vs Confluence](https://moxiedocs.com/vs/confluence): Automated code synchronization vs. legacy text graveyard: docs stay coupled to the code instead of drifting out of date. - [Moxie Docs vs Repowise](https://moxiedocs.com/vs/repowise): Hosted GitHub App vs. self-hosted daemon: Moxie Docs opens docs-only pull requests with nothing to install, instead of running your own indexing daemon. - [Moxie Docs vs Merge.dev](https://moxiedocs.com/vs/merge): Native codebase MCP vs. unified integrations API: zero-code MCP servers that serve repository context to agents. - [Moxie Docs vs Cursor Rules](https://moxiedocs.com/vs/cursorrules): Generated vs. hand-written: Moxie Docs serves repo conventions via MCP that update themselves from your code, instead of rule files someone has to write and maintain by hand. - [Moxie Docs vs DocuWriter.ai](https://moxiedocs.com/vs/docuwriter): Docs-only pull requests vs. a docs Space: both generate repository-wide docs and an MCP server, but Moxie Docs routes updates through GitHub pull requests and adds a public knowledgebase site. Head-to-head comparisons between documentation tools: - [Mintlify vs GitBook](https://moxiedocs.com/compare/mintlify-vs-gitbook): Developer MDX workflow vs. a block editor for mixed teams. - [GitBook vs Confluence](https://moxiedocs.com/compare/gitbook-vs-confluence): Purpose-built docs platform vs. the general enterprise wiki. - [Mintlify vs Confluence](https://moxiedocs.com/compare/mintlify-vs-confluence): Code-coupled MDX docs vs. a decoupled enterprise wiki. - [Mintlify vs Docusaurus](https://moxiedocs.com/compare/mintlify-vs-docusaurus): Managed MDX platform vs. free open-source static site generator. - [GitBook vs Docusaurus](https://moxiedocs.com/compare/gitbook-vs-docusaurus): Block editor for mixed teams vs. self-hosted Markdown sites. - [Mintlify vs Swimm](https://moxiedocs.com/compare/mintlify-vs-swimm): Polished public docs hosting vs. code-anchored onboarding walkthroughs. - [Mintlify vs Jamdesk](https://moxiedocs.com/compare/mintlify-vs-jamdesk): Premium docs platform with an AI Agent vs. flat-priced MDX hosting. ## Learn Guides on MCP, documentation, and AI development practices: - [Learn hub](https://moxiedocs.com/learn): Browse all guides. - [What is an MCP server?](https://moxiedocs.com/learn/what-is-an-mcp-server): The plain-English explainer on Model Context Protocol servers. - [Best MCP servers for coding](https://moxiedocs.com/learn/best-mcp-servers-for-coding): Fifteen MCP servers worth connecting to your coding agent. - [Living documentation](https://moxiedocs.com/learn/living-documentation): Why docs drift, and what it takes to keep them true. - [AGENTS.md vs CLAUDE.md vs llms.txt](https://moxiedocs.com/learn/agents-md-vs-claude-md-vs-llms-txt): Three files for AI context - and what each is actually for. - [What is documentation drift?](https://moxiedocs.com/learn/what-is-documentation-drift): Why docs go stale, how to spot it, and how teams fix it. - [AI coding agent context](https://moxiedocs.com/learn/ai-coding-agent-context): How Cursor, Claude Code, and Codex learn your private codebase. - [CLAUDE.md guide](https://moxiedocs.com/learn/claude-md-guide): How to manage and optimize CLAUDE.md for Claude Code. - [AGENTS.md guide](https://moxiedocs.com/learn/agents-md-guide): What AGENTS.md is, what goes in it, and how to keep it current. - [What is context engineering?](https://moxiedocs.com/learn/what-is-context-engineering): The discipline that replaced prompt engineering - and why it matters. - [How to write a .cursorrules file](https://moxiedocs.com/learn/how-to-write-a-cursorrules-file): The ultimate guide to structuring custom instructions for Cursor. ## Resources - [Blog](https://moxiedocs.com/blog): Articles on documentation, codebases, and AI developer tooling. Full RSS feed at /blog/feed.xml. - [Full context file](https://moxiedocs.com/llms-full.txt): Inlined guides, tool summaries, and FAQ for AI ingestion. - [FAQ](https://moxiedocs.com/faq): Answers on doc generation, GitHub access and security, MCP context, supported languages, and pricing. - [Security](https://moxiedocs.com/security): How Moxie Docs handles repository data and access. - [Contact](https://moxiedocs.com/contact): Reach the team. ## FAQ ### What is Moxie Docs? A hosted service that connects to GitHub, generates searchable codebase docs from source, keeps them current on merge, and serves that context to AI agents over MCP. Doc updates arrive as pull requests your team reviews. ### What happens after I connect a repo? Moxie runs a first full index, generates docs and conventions, then re-indexes on every merge. PR checks for description alignment, documentation gaps, and conventions start with the next pull requests. ### Do PR checks block merge, or only warn? By default they warn. Moxie posts GitHub check runs (Moxie Docs / Description, Moxie Docs / Documentation, Moxie Docs / Conventions) with advisory conclusions on findings - they do not fail the check and will not block merge on their own. To make them a hard gate, require those check names in your repository's branch protection rules. ### Will Moxie change my code automatically? No. Doc updates are reviewable docs-only PRs. Description alignment only edits the PR description text. Merge control stays with your team. ### How does MCP cut agent cost? Agents pull conventions, docs, gaps, and verified commands instead of re-crawling the repo every prompt - fewer tokens and fewer wrong guesses. When code is undocumented, MCP surfaces the gap instead of inventing APIs. ### Can I publish a public help center for my users? Yes — the Public Knowledgebase (Beta) turns your repo into a hosted help site on your-team.moxiedocs.app, written for end users, developers, or both. Every page is human-approved before it goes live; internal agent notes stay out of the public site until you publish. Available on every plan during the beta. ### Is indexing one-shot or continuous? Continuous. The first index builds the baseline. Every merge re-checks affected docs, flags drift and gaps, and keeps MCP context current. On Pro and Team, Friday Cleanup batches remaining fixes into one docs-only PR you review and merge - nothing auto-merges. ### How much does it cost? 14-day free trial on every plan. Starter $29/mo, Pro $79/mo, Team $199/mo. Annual billing saves about two months. Low-churn single-repo teams often prefer annual Starter or the one-time $5 trial pass on /pricing. ### Does Moxie Docs work with private GitHub repositories? Yes. Built for private repos. The GitHub App is scoped to only the repos you choose, tokens are encrypted server-side, and code is used only to generate documentation and MCP context for your workspace. ### What programming languages does Moxie Docs support? Documentation and search work with any GitHub repository. Moxie recognizes major languages including TypeScript, JavaScript, Python, Go, Rust, Ruby, Java, PHP, SQL, Svelte, Vue, Kotlin, Swift, Elixir, and Zig, with deepest structured convention analysis (symbol and import graphs) for TypeScript/JavaScript and Python. ### How do I keep documentation in sync with my code? Connect a GitHub repo. Moxie re-indexes on every merge, flags pages affected by code changes, regenerates stale documentation with cited diffs, and on Pro and Team plans runs Friday Cleanup to open weekly docs-only pull requests for review. ### How much does automated codebase documentation cost? Starter is $29/month, Pro is $79/month, and Team is $199/month, each with a 14-day free trial. Annual billing saves about two months versus monthly. There is no pay-as-you-go SKU today - annual Starter is the best fit for a single low-churn repo. ### What is the best tool for automated GitHub codebase documentation? Moxie Docs indexes the repositories you select through a scoped GitHub App, generates architecture and convention docs grounded in source code, detects documentation drift on every merge, and opens weekly Friday Cleanup PRs so docs stay current without manual rewrites. It also exposes an MCP server so Cursor, Claude Code, and Codex pull verified conventions instead of re-crawling the repo. ### What is documentation drift and how does Moxie Docs detect it? Documentation drift is when written docs no longer match the code they describe. Moxie Docs checks each merged pull request against the documentation it touches, compares generated docs to the current source, surfaces gaps in the workspace, and regenerates impacted pages so teams see what changed and why. ### What is Friday Cleanup in Moxie Docs? Friday Cleanup is a weekly docs-only automation on Pro and Team plans. Moxie batches small documentation fixes - stale pages, gaps, and drift - into a single pull request your team can review with Friday coffee. Nothing auto-merges; you hold the merge button. ### How do AI coding agents get codebase context from Moxie Docs? Every Moxie Docs plan includes an MCP (Model Context Protocol) server. Compatible agents and editors query it for current documentation, conventions, verified commands, and open gaps instead of guessing from partial file reads, which cuts token waste and wrong API assumptions. ### What is an MCP server for codebases? An MCP server for codebases exposes repository documentation and conventions to AI agents through the Model Context Protocol. Moxie Docs publishes one at /api/mcp with OAuth and bearer-token access so agents pull live, cited context about how your project actually works. ### What happens when an agent hits undocumented code via MCP? MCP tools return structured gaps and impact, not invented APIs. Agents can call moxie.get_doc_gaps, moxie.get_doc_impact, and moxie.propose_doc_update so missing docs land in the same PR as the code change - or wait for Friday Cleanup - instead of papering over the hole. ### What if the docs are right and the code is wrong? Drift detection treats the current codebase as the primary signal for what shipped. Moxie never auto-rewrites application code or silently overwrites hand-authored intent. Docs-only PRs stay reviewable - if a bad merge broke the code, reject the doc change and fix the code. Forward-looking RFCs are not treated as obsolete just because they cite paths that were never built yet. ### How does Moxie handle RFCs and design docs ahead of the code? Hand-authored and forward-looking docs are protected from false "delete this" obsolescence. Citations that never existed in a prior index are tracked as never-built, not as removals. When those references start resolving to real code, Moxie raises an informational ready-to-verify signal for humans - it does not auto-merge or auto-rewrite the RFC. Stale but still-valid hand docs can be refreshed via reviewable PRs. ### Can internal notes leak into the public knowledgebase? No page goes public without a human publish step. The Public Knowledgebase review inbox keeps drafts private; agent-oriented workspace docs and temporary implementation notes are not the public site. Quality gates flag internal jargon and leak-prone phrasing before publish. You choose audience (users, developers, or both) at setup. ### How does indexing work on large monorepos with frequent commits? The first index is a full baseline and takes longer on large trees. After that, merges re-check the affected surface incrementally so every commit is not a full rebuild. Use ignored paths in repository documentation settings to skip generated folders, vendored deps, and noise. Team plans get priority indexing for larger fleets. ### How do I make Moxie Docs PR checks required before merge? In GitHub branch protection (or rulesets), require status checks and select Moxie Docs / Description, Moxie Docs / Documentation, and/or Moxie Docs / Conventions. Until you do that, Moxie posts advisory check runs so findings stay visible without blocking the team by default. ### How does Moxie Docs help onboard new engineers? Moxie generates searchable architecture overviews, module walkthroughs, and convention guides cited to source files, then keeps them current on every merge. New engineers search one workspace instead of spelunking the repo, and AI agents they use inherit the same grounded context over MCP. ### Can Moxie Docs generate architecture documentation from source code? Yes. Moxie indexes your repository, builds an outline of modules and dependencies, and generates architecture pages, references, and convention summaries with citations back to the files they came from. Pages regenerate incrementally when the underlying code changes. ### What is a hosted knowledgebase? A hosted knowledgebase is a searchable help site grounded in your codebase — written for your product's end users, for developers integrating your API, or both, depending on the audience you pick during setup. Moxie Docs publishes it on a moxiedocs.app subdomain (custom domains are coming soon on Pro and Team plans) with human review before anything goes public, built-in article search, and content that stays in your git repo as Markdown. ### Can Moxie Docs host an end-user help center? Yes. Choose the “User” audience during knowledgebase setup and Moxie writes plain-language help articles about using your product — no code identifiers or internal jargon — reviewed by you before anything is published. Pick “Both” to serve end users and developers from the same site. ### Will Moxie Docs change my application code automatically? No. Moxie only proposes documentation changes as reviewable pull requests. Description alignment may update a pull request description on GitHub, but your source code, branch protection, and merge controls stay with your team. ## Tools - [Free tools hub](https://moxiedocs.com/free-tools): All browser-based documentation utilities in one place. - [Mermaid Diagram Editor](https://moxiedocs.com/mermaid-diagram-editor): Private in-browser editor with instant preview, shareable URLs, and SVG export. - [SQL to ER Diagram](https://moxiedocs.com/sql-er-diagram-generator): Paste CREATE TABLE SQL for a live Mermaid ER diagram, SVG/PNG export, and optional AI data-model docs. - [README Generator](https://moxiedocs.com/readme-generator): Structured README builder with live Markdown preview and shareable export. - [llms.txt Generator](https://moxiedocs.com/llms-txt-generator): Import a sitemap, edit with live preview, and export a valid llms.txt for AI agents. - [AGENTS.md Generator](https://moxiedocs.com/agents-md-generator): Structured AGENTS.md builder with live preview, examples, and shareable export for coding agents. - [ADR Generator](https://moxiedocs.com/adr-generator): Form-driven Architecture Decision Records with examples and clean Markdown export. - [llms.txt Validator](https://moxiedocs.com/llms-txt-validator): Paste or upload llms.txt to validate structure, links, and Optional section placement. - [.cursorrules Generator](https://moxiedocs.com/cursorrules-generator): Draft Cursor Rules (.cursorrules) with structured guidelines, live preview, and markdown export. - [CLAUDE.md Generator](https://moxiedocs.com/claude-md-generator): Structured CLAUDE.md file generator for Claude Code with commands, conventions, and export. - [.windsurfrules Generator](https://moxiedocs.com/windsurfrules-generator): Draft Windsurf Rules (.windsurfrules) with structured guidelines, live preview, and markdown export. ## Legal - [Privacy policy](https://moxiedocs.com/privacy) - [Terms of service](https://moxiedocs.com/terms) ## Optional - [Subprocessors](https://moxiedocs.com/subprocessors): Third-party services Moxie Docs relies on. - [Republishing guidelines](https://moxiedocs.com/blog/republishing): How to cite or republish Moxie Docs articles. --- ## Free tools (inlined summaries) ### Mermaid Diagram Editor Private in-browser editor with instant preview, shareable URLs, and SVG export. URL: https://moxiedocs.com/mermaid-diagram-editor ### SQL to ER Diagram Paste CREATE TABLE SQL for a live Mermaid ER diagram, SVG/PNG export, and optional AI data-model docs. URL: https://moxiedocs.com/sql-er-diagram-generator ### README Generator Structured README builder with live Markdown preview and shareable export. URL: https://moxiedocs.com/readme-generator ### llms.txt Generator Import a sitemap, edit with live preview, and export a valid llms.txt for AI agents. URL: https://moxiedocs.com/llms-txt-generator ### AGENTS.md Generator Structured AGENTS.md builder with live preview, examples, and shareable export for coding agents. URL: https://moxiedocs.com/agents-md-generator ### ADR Generator Form-driven Architecture Decision Records with examples and clean Markdown export. URL: https://moxiedocs.com/adr-generator ### llms.txt Validator Paste or upload llms.txt to validate structure, links, and Optional section placement. URL: https://moxiedocs.com/llms-txt-validator ### .cursorrules Generator Draft Cursor Rules (.cursorrules) with structured guidelines, live preview, and markdown export. URL: https://moxiedocs.com/cursorrules-generator ### CLAUDE.md Generator Structured CLAUDE.md file generator for Claude Code with commands, conventions, and export. URL: https://moxiedocs.com/claude-md-generator ### .windsurfrules Generator Draft Windsurf Rules (.windsurfrules) with structured guidelines, live preview, and markdown export. URL: https://moxiedocs.com/windsurfrules-generator --- ## Keyword landings (inlined summaries) ### Codebase docs that write themselves from GitHub Connect a repo. Moxie generates source-cited docs, keeps them current on merge, and serves the same context to AI agents over MCP. URL: https://moxiedocs.com/code-documentation ### Catch documentation drift before the wiki goes quiet Code merges without doc updates create drift. Moxie re-checks on every merge, flags gaps, and packages fixes into one weekly reviewable PR. URL: https://moxiedocs.com/documentation-drift --- ## Agent integrations (inlined summaries) ### Cursor Cursor agents work better when they read your conventions before editing. Moxie Docs indexes your GitHub repository and serves citation-backed context through MCP so Cursor stops re-exploring the repo on every prompt. URL: https://moxiedocs.com/integrations/cursor ### Claude Code Claude Code reads CLAUDE.md at session start, but that file still goes stale. Moxie Docs generates and maintains repository documentation, serves live context over MCP, and helps your AGENTS.md / CLAUDE.md instructions stay grounded in what the code actually does. URL: https://moxiedocs.com/integrations/claude-code ### Codex Codex works faster when it already knows your build commands, module boundaries, and documentation gaps. Moxie Docs indexes your GitHub repository and exposes that context through MCP tools formatted for agents. URL: https://moxiedocs.com/integrations/codex ### Windsurf Windsurf agents benefit from the same compact, citation-backed context as Cursor and Claude Code. Moxie Docs keeps an index of your repository current on every merge and serves it through standard MCP tools. URL: https://moxiedocs.com/integrations/windsurf ### Cline & Roo Code Cline and Roo Code autonomous VS Code agents work faster when they read your conventions before writing code. Moxie Docs indexes your GitHub repository and serves citation-backed architecture notes and doc gaps through MCP. URL: https://moxiedocs.com/integrations/cline ### GitHub Copilot GitHub Copilot Agent Mode reads instructions and MCP extensions at session start. Moxie Docs generates live repository documentation, serves citation-backed context over MCP, and updates your Copilot instructions on every merge. URL: https://moxiedocs.com/integrations/github-copilot --- ## Learn guides (inlined) ## Guide: What is an MCP server? MCP servers are how modern AI coding agents reach beyond their training data - pulling in live tools, data, and context through one standard protocol. Here's what that means, how it works, and how to connect one. ### The short answer The Model Context Protocol (MCP) is an open standard for connecting AI applications to external tools and data sources. An MCP server is a program that exposes a specific capability - reading files, querying a database, searching documentation, calling an API - in a format any MCP-compatible AI client can use. Think of it as a universal adapter. Before MCP, every AI tool needed a bespoke integration for every data source. MCP standardizes that connection, so one server works across Claude, Cursor, VS Code, and any other client that speaks the protocol. ### Why MCP exists Large language models are frozen at their training cutoff and isolated from your systems. They don't know your codebase, your database schema, or today's library docs unless something feeds that context in. MCP, introduced by Anthropic in late 2024 and since adopted across the industry, solves the integration problem the way USB solved peripherals: one protocol instead of a custom connector for every pairing. A tool builder writes one MCP server, and every MCP client can use it. ### How an MCP server actually works An MCP client - your agent - connects to an MCP server over a transport: either a local process over stdio, or a remote server over HTTP. The server advertises what it offers, and the agent calls those capabilities as needed during a task. Servers expose three kinds of things: - **Tools** Functions the agent can call - search code, run a query, open a pull request. - **Resources** Data the agent can read - files, records, documentation pages. - **Prompts** Reusable templates the server exposes for common tasks. ### What people use MCP servers for The fastest-growing category is coding. Developers connect MCP servers so their agent can read the file system, drive a browser, pull production errors, query a database, or fetch current documentation - instead of guessing from stale training data. A practical caution: connecting many servers at once floods the agent with tools and can degrade its performance. Most teams start with two or three that match their workflow. ### Where Moxie Docs fits Moxie Docs runs a first-party MCP server for your own codebase. Instead of letting an agent re-crawl your repository on every prompt, it serves your conventions, documentation, doc gaps, and verified commands over MCP - so Cursor, Claude Code, and Codex get accurate, source-cited context in a couple of scoped lookups. ## Guide: The best MCP servers for coding MCP servers let your coding agent reach past its training data - into your files, your tools, your errors, and current documentation. Here are fifteen worth knowing, what each does, who maintains it, and ready-to-use configuration JSON for Cursor and Claude Code. ### How to read this list The Model Context Protocol has a reference set of servers maintained by its steering group, but those are demonstrations, not production tools. Many once-popular reference servers - GitHub, GitLab, Slack, Google Drive - have been archived and handed off to the actual vendors. So when we say “official” below, we mean maintained by the vendor whose system it connects to, not simply listed in the reference repo. One caution worth repeating: connecting more than a handful of servers floods your agent with tools and tends to hurt its performance. Start with two or three that fit your workflow, and add more only when you feel the gap. ### Configuring MCP in Claude Code, Cursor, and Windsurf Connecting MCP servers to your coding tools is straightforward, but each client handles configuration differently. For Claude Code, servers are configured in global settings (~/.claude.json) or project-level config under 'mcpServers'. For Cursor, manage configurations under Settings > Features > MCP. Below are ready-to-copy JSON configuration blocks for popular categories: - **Filesystem & Repository** { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/repo"] } } } - **Database & Backend (Supabase / Postgres)** { "mcpServers": { "supabase": { "command": "npx", "args": ["-y", "@supabase/mcp-server"] } } } - **Private Codebase Context (Moxie Docs)** { "mcpServers": { "moxie": { "command": "npx", "args": ["-y", "@moxie-docs/mcp-server"] } } } ### Start small Pick the two or three servers that match how you actually work - a file or Git server, something for current docs, and one for whatever system you debug most. Add Moxie Docs when you want your agent to follow your codebase's own conventions instead of rediscovering them every prompt. ## Guide: Living documentation, and the drift it fixes Every team has docs that were true once. Living documentation is the practice of keeping them true - coupled to the code, updated as it changes, instead of decaying the moment they're written. ### What “living documentation” means Living documentation is documentation that stays accurate as the system it describes changes. The term predates AI - it comes from the docs-as-code and behavior-driven-development worlds - but the idea is simple: docs should be derived from, and kept in sync with, a source of truth rather than maintained by hand on a separate island. The opposite is the wiki everyone has: a page that was correct at launch, drifted out of date over a few sprints, and is now actively misleading - so no one trusts it, so no one updates it. ### Why documentation drifts Drift isn't a discipline problem; it's a structural one. Code and docs live in different places, change on different schedules, and are owned by different incentives. A pull request that ships a feature is rewarded; the doc update that should accompany it is invisible and optional. AI-assisted coding makes this worse. When agents write a large share of new code, it ships faster than any human can document - and the gap between what the system does and what the docs say widens every week. ### What it takes to keep docs alive Keeping documentation current can't depend on remembering to do it. In practice it takes three things working together: - **A link to the source** Docs have to be tied to the code they describe, so a change in one can flag the other. - **Drift detection** Something has to notice when a change makes a doc wrong - ideally at merge time, not in a quarterly audit. - **A low-friction fix** The correction has to arrive as something a reviewer can approve in seconds, not a chore added to the backlog. ### Living docs for humans and agents There's a newer reason this matters. Documentation is no longer read only by people - AI coding agents read it too, to learn your conventions and architecture before they write. Stale docs don't just mislead a new hire; they teach your agents the wrong patterns. That raises the bar. Living documentation becomes the shared source of truth that keeps both your team and your agents working from the same, current understanding of the system. ### How Moxie Docs approaches it Moxie Docs generates documentation from your source code, detects drift on every pull request, and delivers corrections as reviewable docs-only PRs - then serves the current docs to your agents over MCP. The docs stay coupled to the code, and keeping them true stops being anyone's chore. ## Guide: AGENTS.md vs CLAUDE.md vs llms.txt Three Markdown files keep coming up in AI-assisted development, and they're easy to confuse. Two instruct coding agents inside your repo; one helps AI crawlers understand your website. Here's the difference. ### AGENTS.md - instructions for coding agents AGENTS.md is an open convention: a plain-Markdown file at your repo root that tells coding agents what they need to know to work in your project - build and test commands, code style, conventions, and gotchas that would clutter a human README. There's no required schema; it's just standard Markdown. It started across tools like OpenAI Codex, Cursor, and Jules, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. A wide range of agents read it, which is the point: write it once, and many tools use it. ### CLAUDE.md - Claude Code's project memory CLAUDE.md is Claude Code's native memory file. It's loaded at the start of every session and holds the same kind of context - commands, conventions, architecture, standing instructions - but it's specific to Claude Code, with support for scoped files (org, user, project, local) and @-imports. Importantly, Claude Code reads CLAUDE.md, not AGENTS.md, with no automatic fallback. The recommended pattern is a CLAUDE.md that imports AGENTS.md (via an @AGENTS.md import or a symlink), so both tools share one source of truth and you add Claude-specific notes below. ### llms.txt - a map for AI crawlers llms.txt is a different animal. Proposed by Jeremy Howard in September 2024, it's a Markdown file at your website root (/llms.txt) that gives LLMs a clean, curated map of your content instead of forcing them to parse messy HTML. The only required element is an H1 with the project name, followed by a summary and lists of links. A related convention, llms-full.txt, concatenates the full text of those pages into one file for single-fetch ingestion - though that's a popularized extension, not part of the original spec. Adoption is real but contested: no major LLM provider has officially committed to consuming llms.txt, and some, like Google, have publicly dismissed it. Treat it as a low-cost bet, not a settled standard. ### Side by side **Purpose** - AGENTS.md: Instruct coding agents in your repo - CLAUDE.md: Instruct Claude Code in your repo - llms.txt: Help AI crawlers read your website **Audience** - AGENTS.md: Any coding agent - CLAUDE.md: Claude Code only - llms.txt: External AI assistants **Location** - AGENTS.md: Repo root - CLAUDE.md: Repo + user/org/local scopes - llms.txt: Website root (/llms.txt) **Format** - AGENTS.md: Plain Markdown, no schema - CLAUDE.md: Markdown + @imports - llms.txt: H1 + summary + link lists **Governance** - AGENTS.md: Agentic AI Foundation (Linux Foundation) - CLAUDE.md: Anthropic - llms.txt: Independent proposal; no standards body **Status** - AGENTS.md: Widely adopted across tools - CLAUDE.md: Native to Claude Code - llms.txt: Adopted but contested ### Which should you use? If you want coding agents to follow your project's conventions, start with AGENTS.md, and add a CLAUDE.md that imports it if your team uses Claude Code. Use llms.txt only if you publish a public docs site and want to help AI crawlers - it's a separate, outward-facing concern. Moxie Docs complements all three: it serves your living codebase context to agents over MCP, and can generate an llms.txt for your docs site. ## Guide: What is documentation drift? Documentation drift is the gap that opens when code changes and the docs that describe it do not. The README still says one install path, the architecture page still shows a service you deleted, and nobody trusts the wiki enough to update it. Here is how drift happens, how to spot it, and what actually keeps docs true. ### The short answer Documentation drift is the state where written documentation no longer accurately describes the system it claims to document. The code is the living system; the docs are a snapshot that aged poorly. Drift is not the same as missing docs. Missing docs were never written. Drifted docs were written once - often carefully - and then the product moved on without them. ### Why documentation drifts Drift is structural, not a moral failing of the team. Code and docs usually live in different places, ship on different cadences, and get different rewards. Merging a feature is visible. Updating the wiki is optional and rarely reviewed. Common causes stack on top of each other: - **Separate homes** Source lives in Git; docs live in a wiki, Notion, or Confluence. Nothing forces them to change together. - **Partial updates** A PR renames a service or changes auth, but the architecture diagram and onboarding guide stay as they were. - **AI-accelerated shipping** Agents and copilots increase how much code lands per week. Human doc maintenance does not scale at the same rate. - **Loss of trust** Once people get burned by a wrong page, they stop reading docs - and stop fixing them. ### Signs your docs have drifted You do not need a full audit to know drift is present. These signals show up early: - **Onboarding fails the script** New hires cannot follow the setup guide without Slack help, even when the guide was written last quarter. - **Agents follow bad patterns** Coding agents copy obsolete conventions from README or AGENTS.md because those files still describe the old world. - **Diagrams and code disagree** Sequence charts, ER diagrams, or service maps show components that no longer exist in the repo. - **Tribal workarounds** The real process is "ask someone who knows" rather than "read the docs." ### How teams try to fight drift Most teams start with process: doc checklists on PRs, quarterly doc days, or a wiki owner. Those help for a while, then lose to delivery pressure. Stronger approaches couple docs to the source of truth: - **Docs as code** Store Markdown next to the repository so changes can ship in the same PR. - **Drift detection** Something compares recent code changes to the docs that mention those paths and flags mismatches. - **Low-friction fixes** Corrections arrive as reviewable docs-only pull requests instead of a backlog ticket nobody prioritizes. - **Living documentation** Treat docs as an ongoing product of the codebase, not a one-time artifact. See our guide on living documentation. ### What to detect (and when) Useful detection is specific. "Docs might be outdated" is noise. Better signals look like: - **Path-level drift** A page documents module X; module X was substantially rewritten this week. - **Convention drift** Documented style or command rules no longer match what the repo actually uses. - **Coverage gaps** Important surfaces (auth, billing, public APIs) have no doc page at all - adjacent to drift, but often discovered by the same system. ### How Moxie Docs approaches drift Moxie Docs indexes your GitHub repository, generates source-cited documentation, and re-checks it as code changes. When docs fall behind, it surfaces gaps and opens reviewable docs-only Cleanup PRs - then serves the current index to coding agents over MCP so stale pages do not become stale agent behavior. ## Guide: How AI coding agents get context about your codebase Coding agents only write good code when they understand your repository: build commands, conventions, architecture, and the docs that explain them. This guide covers the main ways teams feed that context - static rule files, repo instruction Markdown, search/RAG, and MCP - and where each approach breaks down. ### Why agent context matters A general-purpose model does not know your auth middleware, package layout, or the command that actually runs tests in CI. Without project context it invents plausible patterns from training data - often wrong for your stack. Context is everything you inject so the agent can act like a teammate who already onboarded: conventions, verified commands, architecture notes, API shapes, and "do not do this" guardrails. ### The main ways teams supply context today Most teams mix several of these. Knowing the tradeoffs keeps you from stuffing the entire monorepo into every prompt. - **IDE rules and system prompts** Cursor rules, custom instructions, and similar files apply standing guidance. They are easy to start and easy to let go stale. - **Repo instruction files** AGENTS.md and CLAUDE.md tell agents how to work in this repository - commands, layout, PR expectations. Write once, many tools can read them (with caveats - see our comparison guide). - **Open files and @-mentions** Developers manually attach the files they think matter. Precise for a single task, not a scalable memory of the system. - **Search and RAG over the repo** Chunked retrieval pulls similar code or docs into the prompt. Useful for "find me something like X," weaker for stable conventions and doc gaps. - **MCP servers** Model Context Protocol servers expose tools and resources the agent can query on demand - docs search, conventions, issue trackers, browsers - without pasting everything up front. ### Static context vs queryable context Static context is push-based: you decide what goes into the rules file or system prompt before the task starts. It is simple and cheap until the file is wrong or too large. Queryable context is pull-based: the agent asks for what it needs mid-task. MCP tools and good repo search work this way. They scale better for large codebases because you do not burn the whole context window on every turn. In practice you want a small static layer (always-on commands and hard rules) plus a queryable layer (living docs, conventions, and gap lists for your private code). ### What good private-repo context looks like Public library docs (for example via a docs MCP for open-source packages) solve only half the problem. Your agent still needs private-repo truth: - **Conventions** How this team names modules, handles errors, structures packages, and writes tests. - **Verified commands** Install, build, lint, and test commands that actually work in this repository. - **Architecture and domain docs** What the system does, where the boundaries are, and which services own which data. - **Gaps and drift** What is undocumented or out of date, so the agent does not treat a missing page as "there is nothing to know." ### Common failure modes Context systems fail in predictable ways. Designing against them matters more than picking a fashionable tool name. - **Stale rules** AGENTS.md still documents the old test runner. The agent confidently runs the wrong command. - **Context bloat** Too many MCP servers or a huge rules dump floods the model with tools and text it cannot prioritize. - **Wrong retrieval** RAG returns a similar but outdated module, and the agent copies patterns you already removed. - **No citations** The agent asserts conventions without a path back to source or docs, so humans cannot verify. ### Where Moxie Docs fits Moxie Docs indexes your GitHub repository into living, source-cited documentation and serves that context over a first-party MCP server - conventions, docs, gaps, and verified commands scoped per repository. Pair it with a thin AGENTS.md for standing rules; let MCP handle the deep, current picture of your private code. ## Guide: The definitive guide to CLAUDE.md CLAUDE.md is how Claude Code learns your codebase's conventions, build commands, and house rules. Here is how to configure it, structure it, and keep it from drifting out of date. ### What is CLAUDE.md? CLAUDE.md is Claude Code's native memory and instruction file. At the start of every session, Claude Code reads this file to boot up its context—learning your project's commands, conventions, architecture patterns, and gotchas. Unlike general readme files, CLAUDE.md is designed specifically for an AI coding agent. It holds standing instructions that tell Claude Code what style to write, what linters to run, and what commands to execute when building or testing. ### Understanding the Scopes of CLAUDE.md Claude Code checks for instructions at multiple levels, allowing you to separate personal, project, and team preferences: 1. Global/User Scope: Stored in your home directory (e.g., ~/.claude.json or ~/.claude.md). This holds your personal editor preferences and system-wide styles. 2. Project/Repo Scope: Stored at your repository root (e.g., repo/CLAUDE.md). This holds project-specific build/test commands and team coding guidelines. This file is committed to git. 3. Local Scope: Stored in the local workspace (.git/info/exclude or local-only configurations) for workspace-specific parameters you don't commit. ### Wiring CLAUDE.md to AGENTS.md If your team uses multiple AI coding agents (such as Cursor, Codex, and Claude Code), maintaining duplicate rules files like AGENTS.md and CLAUDE.md is a recipe for documentation drift. The recommended pattern is to keep your core conventions and build commands in AGENTS.md (which is read by Cursor and other open tools), and make your CLAUDE.md import it using an @AGENTS.md directive or a symlink. You can then add Claude-specific command configurations below the import, maintaining a single source of truth for the core rules. ### Keeping CLAUDE.md from Drifting Like any documentation, CLAUDE.md can go stale. If a developer changes the test runner command or refactors the folder layout but forgets to update CLAUDE.md, Claude Code will confidently execute the wrong commands. Tying CLAUDE.md updates to your CI/CD pipeline or pull request reviews is the best way to prevent drift. You can run automated checks that verify if the documented build and test commands still match what is defined in your package.json or config files. ### Let Moxie Docs manage the drift Moxie Docs connects to your repository, monitors code merges, and automatically updates your codebase guides. If your build commands or directory structures change, Moxie will automatically detect the drift and propose updates to your CLAUDE.md and AGENTS.md files via reviewable docs PRs—so you never have to worry about stale AI context. ## Guide: The complete guide to AGENTS.md AGENTS.md is a single Markdown file at your repo root that tells AI coding agents how to work in your project - the build commands, conventions, and gotchas a human README leaves out. Here is what to put in it, where it belongs, which tools read it, and how to keep it accurate as your code changes. ### What is AGENTS.md? AGENTS.md is an open convention: a plain-Markdown file, placed at your repository root, that gives coding agents the operating instructions they need before they touch your code. Think of it as a README written for the machine instead of the newcomer - build and test commands, code style, project layout, and the rules that are obvious to your team but invisible to an agent. There is no required schema and no special syntax. It is standard Markdown with headings, so anything you would explain to a new engineer in their first hour belongs in it. The value is that you write it once and many different agents read the same file. ### What goes in an AGENTS.md file Keep it scannable - agents, like people, skim. A useful AGENTS.md usually covers a handful of concrete, verifiable things: - **Project overview** One or two lines on what the project is and how it is structured, so the agent orients before editing. - **Setup and commands** The exact install, build, lint, and test commands that actually work - the single highest-value thing you can document. - **Code style and conventions** Naming, error handling, formatting rules, and patterns this codebase prefers over the model's defaults. - **Testing instructions** How to run the suite, what must pass before a change is done, and any commands that are slow or environment-specific. - **Guardrails** The "do not do this" list - files not to touch, commands not to run, and boundaries the agent must respect. ### Where AGENTS.md lives The primary file sits at the repository root, where agents look first. For a monorepo, you can also place additional AGENTS.md files inside individual packages or directories - the agent uses the closest file to the code it is editing, so a package can override or extend the root instructions with its own commands and rules. Because it is committed to the repo, AGENTS.md travels with the code and applies to every developer and every agent working in that tree - unlike an IDE setting that lives only on one machine. ### Which tools read AGENTS.md The point of AGENTS.md is cross-tool reach. It started across agents like OpenAI Codex, Cursor, and Jules, and is now stewarded by the Agentic AI Foundation under the Linux Foundation, with a broad and growing set of tools that read it. Write it once, and many agents pick it up. The notable exception is Claude Code, which reads CLAUDE.md and does not fall back to AGENTS.md automatically. The common fix is a CLAUDE.md that imports AGENTS.md (via an @AGENTS.md import or a symlink), so both share one source of truth. See our AGENTS.md vs CLAUDE.md vs llms.txt comparison for the full picture. ### Keeping AGENTS.md from drifting An AGENTS.md file is only useful while it is true. The moment someone changes the test runner, renames a package, or swaps a build step without updating the file, the agent starts running the wrong commands - confidently, and at scale. This is the same documentation drift that hits any README or wiki, except the reader is a machine that will not sense something is off. The durable fix is to treat AGENTS.md as living documentation: tie it to the source of truth, check it when code merges, and correct it through normal review rather than a quarterly cleanup. ### Where Moxie Docs fits Moxie Docs keeps files like AGENTS.md honest. It indexes your GitHub repository, detects when a code change makes your documented commands or conventions stale, and proposes fixes to AGENTS.md and CLAUDE.md as reviewable docs-only PRs - then serves the same current context to agents over its MCP server. Your standing instructions stay true without becoming anyone's chore. ## Guide: What is context engineering? Context engineering is the practice of putting the right information, tools, and history into a model's context window so it can actually solve the task. As AI moved from single prompts to agents that run for many steps, this - not clever prompt wording - became the thing that decides whether the output is good. Here is what it means and how to do it well. ### The short answer A model can only reason over what is in its context window - the text, tools, and data you place in front of it at inference time. Context engineering is the discipline of assembling that window deliberately: choosing what to include, what to leave out, and how to arrange it so the model has exactly what the task needs and little else. The term was popularized in 2025 by practitioners across the field who argued that the hard part of building with LLMs had shifted. It is less about the wording of one prompt and more about the system that feeds the model the right context, at the right time, on every turn. ### Context engineering vs prompt engineering Prompt engineering is about how you phrase a single instruction - the wording, examples, and formatting of one message. It still matters, but it treats the prompt as the whole input. Context engineering zooms out to the entire window. The prompt is just one component; the rest is retrieved knowledge, tool definitions, prior messages, and memory that a system assembles dynamically for each step. In an agent that runs dozens of turns, no static prompt can anticipate what each step needs - so the work moves from writing a prompt to engineering the pipeline that builds the context. ### What goes into the context window A useful way to think about context engineering is as a budget: the window is finite, and every token you spend should earn its place. The main things competing for that space are: - **Instructions** The system prompt and standing rules that define the model's role, goals, and constraints. - **Retrieved knowledge** Facts pulled in on demand - documentation, code, records - via search or RAG, so the model is not guessing from training data. - **Tools** The functions and resources the agent can call, often exposed over MCP, plus the results those calls return. - **Memory and history** The relevant parts of the conversation and any long-term memory the agent carries between sessions. - **The user's request** The immediate task - the smallest and most obvious piece, and rarely the reason a system fails. ### Why context engineering is hard More context is not better context. A bloated window is slower, costs more, and - counterintuitively - produces worse answers, because models struggle to find the relevant detail buried in a wall of text. The failures tend to look like this: - **Poisoning** A wrong fact or hallucination enters the context early and gets treated as ground truth for the rest of the task. - **Distraction** So much history accumulates that the model loses the thread and over-focuses on the wrong part. - **Confusion** Irrelevant tools or documents crowd the window and pull the model toward things that do not matter. - **Clash** Two pieces of context contradict each other - a stale doc and current code - and the model cannot tell which to trust. ### How to do context engineering well Good context engineering is mostly about curation and freshness, not volume. A few principles hold across most systems: - **Retrieve, do not stuff** Pull in what a step needs on demand instead of pasting whole folders or histories into every turn. - **Keep the source of truth current** Retrieval is only as good as what it retrieves. Stale docs feed the model confident, wrong context. - **Prefer cited, structured context** Context that carries a path back to source lets both the model and a human verify it. - **Compress and prune** Summarize long histories and drop tools and documents a task does not need, so the signal stays high. ### Where Moxie Docs fits For coding agents, the hardest context to get right is your own private codebase. Moxie Docs handles that layer of context engineering: it indexes your GitHub repository into living, source-cited documentation and serves conventions, docs, gaps, and verified commands over an MCP server - so agents retrieve accurate, current context on demand instead of drowning in a dump of stale files. ## Guide: How to write a .cursorrules file A .cursorrules file tells the Cursor AI editor exactly how to behave in your project - build commands, coding conventions, database schemas, and style choices. Here is the best way to write, structure, and maintain one without it drifting out of date. ### What is a .cursorrules file? A .cursorrules file is a project-level configuration file placed at the root of your workspace. Cursor automatically reads this file to inject system-level instructions into every chat, edit (Cmd+K / Ctrl+K), and Composer session. It acts as the 'source of truth' for the editor's AI, ensuring it adheres to your preferred coding standards, framework versions, and project structures instead of guessing based on general training data. ### The ideal structure for a .cursorrules file A well-structured .cursorrules file is split into logical sections so the model can parse and follow the rules efficiently. We recommend organizing your instructions under these four pillars: - **System & Tech Stack** List framework versions (e.g. Next.js 16, React 19) and library dependencies so the AI doesn't write deprecated APIs. - **Coding Standards** Detail import style preferences (e.g. absolute imports, type imports), state management guidelines, and design system rules. - **Directory Structure** Map where components, API routes, database schemas, hooks, and tests reside to prevent the AI from creating misplaced files. - **Verification & Run Commands** Provide exact CLI commands to build, test, and lint. This helps Cursor's terminal agent run tests and fix compilation errors autonomously. ### The danger of custom instruction drift While a .cursorrules file is incredibly powerful, it suffers from a common pitfall: documentation drift. When you upgrade dependencies, refactor folder structures, or add new database tables, the static rules file stays the same. Over time, the .cursorrules file begins to contradict the actual codebase. When the AI reads outdated rules, it hallucinates legacy patterns, leading to broken imports, compilation errors, and slower developer velocity. Committing to keeping these rules manually sync'd is a chore most fast-moving teams fail to sustain. ### Transitioning to a dynamic MCP server For large codebases, a single static .cursorrules file becomes bloated, eating up the AI's finite context window. The modern approach is to transition from static rules files to a live Model Context Protocol (MCP) server. Instead of sending a massive text file on every prompt, an MCP server lets Cursor query the codebase's rules and metadata dynamically on demand. This keeps prompts clean, saves token costs, and ensures the AI always has the latest source-of-truth context. ### Keep rules in sync automatically Instead of maintaining static rules files by hand, let Moxie Docs manage your codebase context. Moxie indexes your repository, generates conventions automatically, and exposes them to Cursor via a built-in MCP server - ensuring your AI agent always writes code aligned with your latest conventions without manual updates. --- ## FAQ ### What is Moxie Docs? A hosted service that connects to GitHub, generates searchable codebase docs from source, keeps them current on merge, and serves that context to AI agents over MCP. Doc updates arrive as pull requests your team reviews. ### What happens after I connect a repo? Moxie runs a first full index, generates docs and conventions, then re-indexes on every merge. PR checks for description alignment, documentation gaps, and conventions start with the next pull requests. ### Do PR checks block merge, or only warn? By default they warn. Moxie posts GitHub check runs (Moxie Docs / Description, Moxie Docs / Documentation, Moxie Docs / Conventions) with advisory conclusions on findings - they do not fail the check and will not block merge on their own. To make them a hard gate, require those check names in your repository's branch protection rules. ### Will Moxie change my code automatically? No. Doc updates are reviewable docs-only PRs. Description alignment only edits the PR description text. Merge control stays with your team. ### How does MCP cut agent cost? Agents pull conventions, docs, gaps, and verified commands instead of re-crawling the repo every prompt - fewer tokens and fewer wrong guesses. When code is undocumented, MCP surfaces the gap instead of inventing APIs. ### Can I publish a public help center for my users? Yes — the Public Knowledgebase (Beta) turns your repo into a hosted help site on your-team.moxiedocs.app, written for end users, developers, or both. Every page is human-approved before it goes live; internal agent notes stay out of the public site until you publish. Available on every plan during the beta. ### Is indexing one-shot or continuous? Continuous. The first index builds the baseline. Every merge re-checks affected docs, flags drift and gaps, and keeps MCP context current. On Pro and Team, Friday Cleanup batches remaining fixes into one docs-only PR you review and merge - nothing auto-merges. ### How much does it cost? 14-day free trial on every plan. Starter $29/mo, Pro $79/mo, Team $199/mo. Annual billing saves about two months. Low-churn single-repo teams often prefer annual Starter or the one-time $5 trial pass on /pricing. ### Does Moxie Docs work with private GitHub repositories? Yes. Built for private repos. The GitHub App is scoped to only the repos you choose, tokens are encrypted server-side, and code is used only to generate documentation and MCP context for your workspace. ### What programming languages does Moxie Docs support? Documentation and search work with any GitHub repository. Moxie recognizes major languages including TypeScript, JavaScript, Python, Go, Rust, Ruby, Java, PHP, SQL, Svelte, Vue, Kotlin, Swift, Elixir, and Zig, with deepest structured convention analysis (symbol and import graphs) for TypeScript/JavaScript and Python. ### How do I keep documentation in sync with my code? Connect a GitHub repo. Moxie re-indexes on every merge, flags pages affected by code changes, regenerates stale documentation with cited diffs, and on Pro and Team plans runs Friday Cleanup to open weekly docs-only pull requests for review. ### How much does automated codebase documentation cost? Starter is $29/month, Pro is $79/month, and Team is $199/month, each with a 14-day free trial. Annual billing saves about two months versus monthly. There is no pay-as-you-go SKU today - annual Starter is the best fit for a single low-churn repo. ### What is the best tool for automated GitHub codebase documentation? Moxie Docs indexes the repositories you select through a scoped GitHub App, generates architecture and convention docs grounded in source code, detects documentation drift on every merge, and opens weekly Friday Cleanup PRs so docs stay current without manual rewrites. It also exposes an MCP server so Cursor, Claude Code, and Codex pull verified conventions instead of re-crawling the repo. ### What is documentation drift and how does Moxie Docs detect it? Documentation drift is when written docs no longer match the code they describe. Moxie Docs checks each merged pull request against the documentation it touches, compares generated docs to the current source, surfaces gaps in the workspace, and regenerates impacted pages so teams see what changed and why. ### What is Friday Cleanup in Moxie Docs? Friday Cleanup is a weekly docs-only automation on Pro and Team plans. Moxie batches small documentation fixes - stale pages, gaps, and drift - into a single pull request your team can review with Friday coffee. Nothing auto-merges; you hold the merge button. ### How do AI coding agents get codebase context from Moxie Docs? Every Moxie Docs plan includes an MCP (Model Context Protocol) server. Compatible agents and editors query it for current documentation, conventions, verified commands, and open gaps instead of guessing from partial file reads, which cuts token waste and wrong API assumptions. ### What is an MCP server for codebases? An MCP server for codebases exposes repository documentation and conventions to AI agents through the Model Context Protocol. Moxie Docs publishes one at /api/mcp with OAuth and bearer-token access so agents pull live, cited context about how your project actually works. ### What happens when an agent hits undocumented code via MCP? MCP tools return structured gaps and impact, not invented APIs. Agents can call moxie.get_doc_gaps, moxie.get_doc_impact, and moxie.propose_doc_update so missing docs land in the same PR as the code change - or wait for Friday Cleanup - instead of papering over the hole. ### What if the docs are right and the code is wrong? Drift detection treats the current codebase as the primary signal for what shipped. Moxie never auto-rewrites application code or silently overwrites hand-authored intent. Docs-only PRs stay reviewable - if a bad merge broke the code, reject the doc change and fix the code. Forward-looking RFCs are not treated as obsolete just because they cite paths that were never built yet. ### How does Moxie handle RFCs and design docs ahead of the code? Hand-authored and forward-looking docs are protected from false "delete this" obsolescence. Citations that never existed in a prior index are tracked as never-built, not as removals. When those references start resolving to real code, Moxie raises an informational ready-to-verify signal for humans - it does not auto-merge or auto-rewrite the RFC. Stale but still-valid hand docs can be refreshed via reviewable PRs. ### Can internal notes leak into the public knowledgebase? No page goes public without a human publish step. The Public Knowledgebase review inbox keeps drafts private; agent-oriented workspace docs and temporary implementation notes are not the public site. Quality gates flag internal jargon and leak-prone phrasing before publish. You choose audience (users, developers, or both) at setup. ### How does indexing work on large monorepos with frequent commits? The first index is a full baseline and takes longer on large trees. After that, merges re-check the affected surface incrementally so every commit is not a full rebuild. Use ignored paths in repository documentation settings to skip generated folders, vendored deps, and noise. Team plans get priority indexing for larger fleets. ### How do I make Moxie Docs PR checks required before merge? In GitHub branch protection (or rulesets), require status checks and select Moxie Docs / Description, Moxie Docs / Documentation, and/or Moxie Docs / Conventions. Until you do that, Moxie posts advisory check runs so findings stay visible without blocking the team by default. ### How does Moxie Docs help onboard new engineers? Moxie generates searchable architecture overviews, module walkthroughs, and convention guides cited to source files, then keeps them current on every merge. New engineers search one workspace instead of spelunking the repo, and AI agents they use inherit the same grounded context over MCP. ### Can Moxie Docs generate architecture documentation from source code? Yes. Moxie indexes your repository, builds an outline of modules and dependencies, and generates architecture pages, references, and convention summaries with citations back to the files they came from. Pages regenerate incrementally when the underlying code changes. ### What is a hosted knowledgebase? A hosted knowledgebase is a searchable help site grounded in your codebase — written for your product's end users, for developers integrating your API, or both, depending on the audience you pick during setup. Moxie Docs publishes it on a moxiedocs.app subdomain (custom domains are coming soon on Pro and Team plans) with human review before anything goes public, built-in article search, and content that stays in your git repo as Markdown. ### Can Moxie Docs host an end-user help center? Yes. Choose the “User” audience during knowledgebase setup and Moxie writes plain-language help articles about using your product — no code identifiers or internal jargon — reviewed by you before anything is published. Pick “Both” to serve end users and developers from the same site. ### Will Moxie Docs change my application code automatically? No. Moxie only proposes documentation changes as reviewable pull requests. Description alignment may update a pull request description on GitHub, but your source code, branch protection, and merge controls stay with your team.