> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arcmira has three API capabilities: Search (entities, mentions, appearances, commercial intelligence), Monitors (trackers plus alert delivery), and Transcripts (read, generate, correct). Community Review is the cross-surface correction layer.
> Discover pages at https://docs.arcmira.com/llms.txt, then fetch the matching page's .md export. Each capability has a self-contained '<capability> for coding agents' page; prefer it.
> Auth: Authorization: Bearer arc_sk_... or x-api-key: arc_sk_... (x-api-key wins if both are sent). Never put keys in browser code. Check GET /v1/me for tier, scopes, and remaining rows before metered pulls.
> Search: resolve names with GET /v1/entities/lookup and pin ent_* IDs before pulling metered rows. Only person entities have appearances. Mention and recommendation rows carry canonical numeric timestamps in start_seconds/end_seconds (integer seconds; 0 means full episode); the MM:SS string fields are deprecated. Commercial routes need Pro+ tier AND the recommendations:read scope and bill 10 rows per row.
> Monitors: a tracker watches one entity; a monitor groups trackers with shared delivery (email, Slack, HMAC-signed webhooks). Create trackers with POST /v1/trackers, then attach by id: POST /v1/monitors/{id}/trackers { trackerIds: [...] }. Each fired alert occurrence debits 100 rows. Poll GET /v1/monitors/{id}/alerts?n= for recent deliveries. Send Idempotency-Key on every POST/PATCH.
> Transcripts: switch on the access field (unlocked, locked, premium_pending, not_transcribed, unauthenticated). Honor Retry-After when polling POST /v1/transcriptions jobs. Corrections (POST /v1/videos/{video_id}/corrections; kinds line_edit, speaker_reassign, speaker_identify, add_person, entity_tag, segment_rewrite) cost 0 rows; anchored kinds need revision + anchor.contentHash (djb2 base-36); handle 409 (re-anchor) and 412 (expectedSeq). segment_rewrite replaces an inclusive segment range with new segments (empty replacements array deletes; timestamps repaired server-side).
> Community Review is free (0 rows) and surface-typed: POST /v1/feedback with a type matching the surface you called, the reproducing query, and corrections targeting public IDs (ent_*, men_*, com_*). Nothing auto-applies. Do not send untyped notes.
> Errors: switch on error.code, follow doc_url, quote X-Request-Id to support. Honor Retry-After on 429. Retries of POST/PATCH must reuse the same Idempotency-Key; replays return Idempotency-Replayed: true.

# AGENTS

# 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.