Skip to main content

​
AGENTS.md — docs.arcmira.com

Rules for agents (and humans) editing this Mintlify docs app. The full standards document is docs/internal/DOCS-FRAMEWORK-by-fable-5.mdx at the repo root; the execution plan is apps/web/docs/epics/EPIC-docs-facelift-2026-07-09.mdx. This file is the short, binding subset.

​
Structure

  • Three top-bar tabs: Documentation, API Reference (OpenAPI-generated), Changelog. Capabilities (Search, Monitors, Transcripts) live in the Documentation sidebar, never as top-bar tabs.
  • A capability is two pages: a human guide and a self-contained <capability>-for-coding-agents twin. Commercial intelligence is the one standalone extra page. Do not add new pages without checking the page budget in the framework (F-2.1): every extra page is a copy-paste and discoverability cost.
  • Community Review is one catalog page (feedback.mdx, URL /feedback). Every result-bearing page carries a “Community Review” section linking to it.

​
Hard rules

  1. OpenAPI is the contract. Never show a parameter, field, or endpoint that is not in openapi/arcmira-v1.json. The static spec is generated from the backend Zod registry; it updates in the same PR as any backend route change (pnpm openapi:write in apps/backend).
  2. Badges mark exceptions only. Everything in the docs is live, shipped behavior by default; never write a “Shipped” badge. The two exception badges, used verbatim: Intended (designed, unshipped; schema + badge only, never in a runnable example, workaround documented alongside) and Roadmap (direction in prose only). Never present unshipped behavior as live.
  3. Coding-agent twins are self-contained. An agent reading only that page must succeed. Repeat operational warnings; do not defer to other pages. Required H2 skeleton: Overview, Minimal working example, Endpoints, Request parameters, Response schema, Errors, Rate limits & idempotency, Community Review, Common mistakes, Patterns and gotchas, Complete examples.
  4. Code samples: TypeScript (fetch) first, Python (httpx) second, cURL third. All runnable, env-var auth (ARCMIRA_API_KEY), realistic IDs (ent_123881, men_2049815, com_119682), never foo/bar. There is no SDK; never write import Arcmira from 'arcmira'.
  5. Examples use real entities, innocuous rows only (Ramp on TBPN, Figma on All-In style). Plausible opinion-take quotes; never fabricated scandals or specific factual claims about real people or companies.
  6. Frontmatter: every page has title plus a functional one-line description (it becomes the llms.txt line). No brand copy in descriptions. The one approved positioning line (“Arcmira is an SF-based AI company and the search engine for the spoken web.”) appears in the quickstart intro only. Repeat it verbatim; never paraphrase it in machine-readable surfaces. Exception: index.mdx carries no description; the quickstart opens with the positioning line as body copy instead of a rendered subtitle.
  7. No em dashes in docs body copy. Rewrite with periods, commas, or colons.
  8. Preserve doc_url anchors. Every error.code the API emits must keep its ### heading on /errors. Renamed or removed pages require a redirects entry in docs.json.
  9. Dangerous facts repeat at every point of use: one-time key/webhook secrets, row costs, permanent unlocks, seq consumption, auto-disable thresholds, refund-revokes-unlock.
  10. Objects are documented twice: one realistic example JSON and one field table, for anything an integrator parses.
  11. Vocabulary: Entity, Mention, Appearance (person-only), Monitor (container + delivery settings), Tracker (one watched entity), Alert, Delivery, Transcript segment, Correction, Community Review submission. Commercial intelligence is the product noun; map it to /v1/recommendations + /v1/channels/{id}/sponsors on first use. Monitors is canonical (never “watchlists”).
  12. Style register (from the 2026-07-10 style pass):
    • State prices; justify them once. Costs are stated flatly at every point of use (rule 9), but the rationale for a price lives only on usage-and-billing.mdx. Before: “bills at 10 rows, because the commercial pipeline is more expensive to run and curate.” After: “bills at 10 rows.”
    • Delete the sentence’s first four words and see if it survives. Openers whose job is to justify the sentence’s existence go. Before: “Why it matters: the index is AI-extracted…” After: “The index is AI-extracted…”
    • Imperatives over descriptions when the reader is the actor. Before: “The classification, confidence, and dispute machinery is designed to be re-exposed in your own product.” After: “Re-expose the classification, confidence, and dispute machinery in your own product.”
    • Intensifiers do not survive review. “fully interchangeable”, “inherently safe”, “simply uses”, “strongly recommended” become “interchangeable”, “safe”, “uses”, “Prefer”.
    • Vague quality claims become the mechanism. Before: “returns 403 with a clear message.” After: “returns 403; the message names the missing scope.”
    • Instructive beats terse. Second-person guidance with a stance is house voice in guides (“Treat it like a password: never ship it in browser code”, “include it whenever you contact support”). Do not compress instructions into clipped fragments; cut filler words, not teaching.
    • No callout without a footgun. Pages hold at 0-2 callouts each, all wrapping gates or footguns; keep that bar. Demote decorative callouts to prose.
    • Machine-readable descriptions carry zero positioning. The docs.json site description and frontmatter descriptions are functional one-liners: no “Build with”, no “evidence-backed”, no trailing flourish.

​
Before merging

  • cd apps/docs && pnpm validate && pnpm broken-links passes.
  • If backend routes changed: regenerate the spec (pnpm openapi:build here, which delegates to apps/backend) and confirm the drift check passes.
  • Changelog entry added for anything an integrator can observe.