Licence
This repository is licensed under FSL-1.1-Apache-2.0. After 2 years (2028-05-22) each release automatically converts to Apache 2.0 per the FSL transition clause. See LICENSE for the full text and https://fsl.software for background.
FixYourDocs
A structured feedback channel between the AI agents that read your documentation and the humans who maintain it.
AI agents read documentation to help their users follow procedures. When they hit a gap, outdated section, contradiction, or dead end, today the signal is dropped: the user gets a worse answer and you never hear about it. FixYourDocs gives those agents a place to put the signal: they file a structured report through an open protocol, and the hub routes it — by the report's doc URL — to the repo of the maintainer who has verified that they own those docs (a domain, or a GitHub Pages site), opening a GitHub Issue so maintainers triage it with the tools they already use.
This repository contains the reference implementation of the hosted product running at fixyourdocs.io — SPA, REST API, and the MCP client package — alongside the docsfeedback.org Starlight site that hosts the open spec. The production CDK pipeline lives in a separate private infrastructure repository. The wire protocol it implements is specified in the open at docsfeedback.org.
Project layout (across the fixyourdocs/ org)
If you want to understand the protocol, start at fixyourdocs/protocol. If you want to emit reports from an agent, use one of the SDKs or drop in the AGENTS.md snippet. If you want to run your own backend, read on.
What's in this repo
- frontend/ — Vite + React + Tailwind v4 SPA: landing page, sign-up / sign-in, GitHub App install + target-repo setup.
- backend/ — REST API Lambdas (Node.js 20 / TypeScript). Public rate-limited
/v1/reports*plus Cognito-protected/v1/orgs/*and/v1/integrations/*; an async-invoked forwarder Lambda turns each accepted report into a GitHub Issue. - mcp-server/ — Client-side npm package (
@fixyourdocs/mcp-server, run vianpx -y @fixyourdocs/mcp-serverover stdio) exposing a singlefile_doc_feedbacktool. CallsPOST https://hub.fixyourdocs.io/v1/reportsto file a v0 report; the hub routes it to a GitHub Issue on the repo of the maintainer who has verified ownership of the doc's domain. - docsfeedback-site/ — Starlight site for docsfeedback.org. Spec markdown and JSON schemas are synced from the protocol repo at build time.
- e2e/ — Playwright forwarder smoke test.
- SPEC.md — V1 product specification for this implementation. (For the protocol spec, see the protocol repo.)
Quickstart (local dev)
Requires Node.js 20 and pnpm 10.
pnpm install
pnpm -r typecheck
pnpm --filter @fyd/frontend dev # SPA on http://localhost:5173
pnpm --filter @fyd/docsfeedback-site dev # docs site on http://localhost:4321
pnpm --filter @fyd/e2e test # Playwright suite
The frontend points at whatever API_BASE_URL you configure at runtime via frontend/public/env.js (not committed — generate it at deploy time from your stack outputs).
Self-hosting
The production hosted variant runs on AWS Lambda + API Gateway HTTP API + DynamoDB + Cognito + CloudFront, deployed via AWS CDK v2. The CDK app itself is operated from a separate private infrastructure repository; a public reference template will follow once the hosted variant is stable.
Self-hosters writing their own CDK app today can match the contract by passing the following env vars through to the backend Lambdas:
Using FixYourDocs from an agent
The agent-facing surface is the hub's POST https://hub.fixyourdocs.io/v1/reports endpoint. Reports are anonymous (rate-limited by IP) and conform to the v0 schema specified at docsfeedback.org/spec/v0 and in the protocol repo.
There are two adoption modes:
- Mode A — first-party (paste into your repo). Paste the snippet from fixyourdocs/agents-md-snippet into your project's
AGENTS.md/CLAUDE.md/.cursorrules. Agents working in your repo offer to report your repo's broken docs — showing you the report and sending it only once you confirm. Works with any agent that reads those files; no MCP client required. - Mode B — consumer-side (install into your own agent). Install
@fixyourdocs/mcp-serverinto your own, global agent/client config (Claude Desktop, Cursor, Codex, …). While you work on something unrelated, your agent can offer — with your confirmation, and on public docs only — to report the third-party docs it consulted that turned out to be broken, even if that project never added the snippet. The MCP server is the primary Mode B carrier; the consent prompt and the privacy/opt-out guards (refuse non-publicdoc_urls; honour a doc host's/.well-known/docs-feedback.jsonopt-out before anything leaves your machine) are enforced by the SDK client it builds on.
In both modes the receiver (the docs owner) still has to claim and verify the docs they own — a domain (via DNS-TXT) or a GitHub Pages site (via the GitHub App on the publishing repo) — and install the hub integration to receive anything — Mode B only removes the reporting-side install requirement. The SDKs (Python, TypeScript) and the helper in mcp-server/ implement the file_doc_feedback path for both.
Contributing
PRs welcome. We use the standard Developer Certificate of Origin — sign your commits with git commit -s. Issues against this repo should be about the implementation; issues against the protocol repo should be about the wire format.
A CLA is required for non-trivial contributions (see fixyourdocs/.github for the text); the CLA-assistant bot will post a sign-off link on your first PR.
Licence
FSL-1.1-Apache-2.0. The Functional Source License keeps the code source-available with a non-compete carve-out for two years, then automatically converts each release to Apache 2.0. See LICENSE and fsl.software.
The protocol itself, the SDKs, and the AGENTS.md snippet ship under permissive licences (Apache 2.0 / CC-BY 4.0) so the open spec stays unencumbered regardless of what this repo does. See each repo's own LICENSE.