Getting started

This is the five-minute path. Pick the tab that matches how you work. Each one is end-to-end: install, send a report, and confirm it landed.

Here is the whole loop in about a minute — an agent hits a stale doc, fixes its own code, files a structured report, and that report opens a GitHub issue on the maintainer’s repo:

There are two milestones:

1. Send a report against our live demo doc and watch it land as a public GitHub Issue. This proves the protocol path works end-to-end — it takes a minute and needs no setup on your side.
2. Receive reports as GitHub Issues on your own repo. This needs a one-time Hub setup (connect the GitHub App, verify you own your docs). It’s covered at the end and links to the Hub guide.

These examples file a real, public Issue

The examples below report against demo-libraryx.com/payments, a live demo doc. Its domain is already verified, so your report doesn’t just return a 201 — it opens a public GitHub Issue at fyd-demo-maintainer/demo-libraryx. That demo exists for exactly this, so go ahead and run one — just tweak the summary so the Hub doesn’t de-duplicate it against an identical report that’s already on file.

Python

1. Install the SDK.

   pip install fixyourdocs

   Requires Python 3.9+.

2. Send your first report.

   from fixyourdocs import Client, Report
   
   report = Report.create(
       doc_url="https://demo-libraryx.com/payments",
       summary="The payments guide still shows the v1 charge flow; the API now needs a PaymentIntent.",
       kind="outdated",
       agent_name="my-agent",
   )
   
   with Client(api_url="https://hub.fixyourdocs.io") as client:
       result = client.send(report)
   
   print(result.id, result.is_duplicate)

   A successful call prints a report id (a ULID). That’s the Hub confirming it accepted your report (201 Created).

   Prefer the command line? The same thing without writing code:

   pipx run fixyourdocs report \
     --doc-url https://demo-libraryx.com/payments \
     --summary "The payments guide still shows the v1 charge flow; the API now needs a PaymentIntent." \
     --agent my-agent \
     --kind outdated

TypeScript

1. Install the SDK.

   npm install @fixyourdocs/sdk

   Requires Node.js 20+ (the SDK uses the built-in global fetch; no runtime dependencies).

2. Send your first report.

   import { Client, buildReport } from "@fixyourdocs/sdk";
   
   const client = new Client({ apiUrl: "https://hub.fixyourdocs.io" });
   
   const report = buildReport({
     docUrl: "https://demo-libraryx.com/payments",
     summary: "The payments guide still shows the v1 charge flow; the API now needs a PaymentIntent.",
     kind: "outdated",
     agentName: "my-agent",
   });
   
   const result = await client.send(report);
   console.log(result.id, result.isDuplicate ? "(duplicate)" : "(new)");

   A successful call logs a report id (a ULID) — the Hub confirming it accepted your report (201 Created).

   No code? The CLI ships with the SDK:

   npx @fixyourdocs/sdk report \
     --doc-url https://demo-libraryx.com/payments \
     --summary "The payments guide still shows the v1 charge flow; the API now needs a PaymentIntent." \
     --agent my-agent \
     --kind outdated

Agent

You’re wiring an AI coding agent so it files reports on its own when it hits broken docs. There are two adoption modes, and you can use either or both.

1. Mode A — wire a single repo (first-party).

   npx @fixyourdocs/sdk init

   This appends the canonical Docs Feedback Protocol block to that repo’s AGENTS.md (or CLAUDE.md, .cursor/rules, or .github/copilot-instructions.md). The block is repo-scoped on purpose — it tells any agent working in this repo to offer to report this repo’s docs, and send only once you confirm. See the AGENTS.md snippet page for what the block contains.

2. Mode B — init your global config, report anywhere (consumer-side).

   npx @fixyourdocs/sdk init --global   # TypeScript SDK
   pipx run fixyourdocs init --global   # Python equivalent

   Same init, but --global writes the consumer-side block to your global agent config — ~/.claude/CLAUDE.md by default; pass --file <path> to target another (e.g. ~/.codex/AGENTS.md). Now your agent — across every project you work in — offers to report the third-party docs it consults: with your OK, on public docs only, never your own private code or internal pages. Re-running is a no-op once the block is present. Background on the safety guards is on Reporting third-party docs.

3. Add the MCP server for MCP-aware clients (Claude Desktop, Cursor, Codex). It’s the recommended carrier for Mode B — it enforces the consent and public-docs-only guards for you. Add this to your client’s MCP config:

   {
     "mcpServers": {
       "fixyourdocs": {
         "command": "npx",
         "args": ["-y", "@fixyourdocs/mcp-server"]
       }
     }
   }

   The agent gets one tool, file_doc_feedback. Full per-client config is on the MCP server page.

4. Confirm the path works by sending a report by hand. Your agent won’t issue this exact command — via the MCP server it calls the file_doc_feedback tool, and via the snippet it composes its own request — but every path ends in this same POST /v1/reports, so running it once proves the Hub accepts what they send:

   curl -X POST https://hub.fixyourdocs.io/v1/reports \
     -H 'Content-Type: application/json' \
     -d '{
       "protocol_version": "0",
       "doc_url": "https://demo-libraryx.com/payments",
       "agent":   { "name": "claude-code" },
       "report":  {
         "kind":    "outdated",
         "summary": "The payments guide still shows the v1 charge flow; the API now needs a PaymentIntent."
       }
     }'

   You get back { "id": "...", ... } with HTTP 201 — the Hub accepted it.

Make reports show up as GitHub Issues — on your repo

The report you just sent forwarded to a public Issue because demo-libraryx.com is a verified demo domain. Your own docs aren’t verified yet, so a report against them would get a 201 and be de-duplicated, but not forwarded. The Hub only forwards a report when the report’s doc_url host matches a domain you have verified you own and bound to a GitHub integration — that’s what keeps anyone from filing issues against a repo that isn’t theirs.

Forwarding requires a verified domain

The demo forwarded because its domain is verified. A report against a domain nobody has verified is accepted and de-duplicated, but it is not forwarded — no Issue is created. To close the loop on your own docs, connect your repo and verify your domain. This is a one-time setup.

The one-time setup, in three moves:

1. Sign in at fixyourdocs.io and install the FixYourDocs GitHub App on the repo that should receive issues.

2. Verify you own your docs. For a domain, add a single DNS TXT record the Hub gives you. For docs on GitHub Pages (<user>.github.io), there’s no DNS step — claim the Pages URL and the Hub verifies it through the GitHub App on the repo that publishes the site.

3. Point the integration at your repo and an Issue body template.

The Hub guide walks through each method — the exact DNS record for a domain, and the GitHub Pages claim. Once it’s done, the next report against a doc you’ve verified shows up at https://github.com/<your-org>/<your-repo>/issues.

Connect the Hub to your repo The GitHub App, domain verification, and issue routing — step by step.

What’s next

• Understand the wire format and the four report fields → Protocol primer
• Browse the full SDK API → Python · TypeScript
• Wire every agent run in a repo → AGENTS.md snippet