Add an agent primer, AGENTS.md and skill.md, and correct API docs against live behaviour

[methodofaction]

Why

Coding agents are now a large share of the audience for these docs, and they kept falling into the same traps: building GOBL documents by hand, guessing tax rate keys, misreading job responses, and never finding the right page. This PR gives them a dedicated entry point and, while verifying it, fixes the places where the existing docs disagreed with what the API actually does.

What's new

• /llms primer (llms.mdx, in Get Started after Quickstart; /api-ref/llms redirects here). Mental model with a diagram, "GOBL in ten rules", "Invopop in ten rules", a seven-call curl walkthrough, five copyable prompts, a "where to look" URL router and a vocabulary map. Every JSON example builds with gobl.dev v0.500.15 (core v0.504.0), and the "what build returns" block is byte-for-byte the CLI's output.
• AGENTS.md at the repo root. Mintlify serves root Markdown verbatim (CLAUDE.md is already live), so this publishes at docs.invopop.com/AGENTS.md as the condensed version integrators paste into their own agent instructions.
• skill.md at the repo root, overriding Mintlify's auto-generated skill for npx skills add https://docs.invopop.com.
• <Prompt> cards on nine pages: quickstart, GOBL overview, workflows, correct invoices, webhooks, authentication, white label, Peppol and VERI*FACTU invoicing. The idiom is documented in CLAUDE.md and the country-guide skill.
• Home page card linking the primer.

Docs corrected against the live API

Every claim on the new pages was run against a real workspace. Where existing pages disagreed with observed behaviour they were fixed too:

• Repeated PUTs and repeated POST keys return 409 even for identical bodies (idempotency page).
• Job creation returns 202 with a stub, or 200 with the full job when wait completes in time. The transform spec listed 202 only.
• Entry responses omit signed and state until set; the silo spec no longer claims the envelope comes back only "when specifically requested" (it is included on fetch, create, update and in lists).
• Console Empty and Invalid labels have no counterpart in the entry state field (states page).
• correct requires type; the spec example used the rejected credit: true.
• List endpoints need limit between 10 and 100 (being relaxed in invopop/silo#242; wording to revert once deployed).
• Series Start Number maps to start, not last_index. The dead last_index / last_entry_id fields are removed from the spec and reference pages, matching invopop/api#125.
• The gobl CLI installs from github.com/invopop/gobl.dev (old path is gone; docs.gobl.org fixed in Point the CLI quick start at gobl.dev and drop the removed --draft flag gobl.docs#69).
• Cloudflare rejects Python urllib's default User-Agent with 403 error code: 1010.

Removed

• api-ref/llms.mdx (redirected to /llms).
• example.json, unreferenced and failing to build.

Reviewer notes

• mint broken-links passes; mint openapi-check passes for the silo, transform and sequence specs; pages were rendered locally with mint dev.
• skill.md replaces the generated skill. Deleting the file restores Mintlify's version if preferred.
• Related PRs: invopop/api#125 (drop series counters), invopop/silo#242 (list limit minimum), Point the CLI quick start at gobl.dev and drop the removed --draft flag gobl.docs#69 (CLI install path).

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
invopop	🟡 Building	–	Sep 3, 2026, 10:53 AM

💡 Tip: Enable Automations to automatically generate PRs for you.