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

# STYLE

# customer-docs Style Guide

This file defines conventions for content in `customer-docs/`. It is internal - Mintlify only publishes pages listed in `docs.json` navigation, so this file does not ship.

See also: `QUALITY-AUDIT.md` (historical audit scoring log, separate artifact).

## Q\&A Sections

### Required component

Every Q\&A section uses the `<FAQ>` / `<FAQItem>` component from `/snippets/FAQ.jsx`:

```mdx theme={null}
import { FAQ, FAQItem } from '/snippets/FAQ.jsx'

<FAQ>
  <FAQItem question="How do I rotate my API key?">
    Go to Settings, API Keys, and click **Rotate**. The old key keeps working for 24 hours.
  </FAQItem>
  <FAQItem question="What happens to running jobs when I rotate?">
    They continue on the old key until it expires. New jobs use the new key immediately.
  </FAQItem>
</FAQ>
```

The import goes at the top of the file, directly below frontmatter. Place the `<FAQ>` block near the bottom of the page, above any "Related Pages" section.

### Banned patterns

* **`<AccordionGroup>` / `<Accordion>` for Q\&A content.** The question text lives in a `title` attribute that renders as a button label, not a heading element. It hurts Google featured-snippet extraction, and `build-markdown.js` strips it from `.md` mirrors (making the Q\&A invisible to LLMs that fetch the markdown).
* **Raw `### Q?` Markdown Q\&A blocks.** No structured data, no single source of truth. If you need Q\&A on a page, use `<FAQ>`.
* **Empty `<FAQ>` blocks or placeholder `<FAQItem>` entries.** Ship real answers or skip the section entirely.

Accordions are still fine for non-Q\&A content (e.g., long configuration detail that benefits from collapse). The ban is specific to question-answer content.

### Rubric (per-question gate)

Every `<FAQItem>` must pass all four tests. A reviewer rejects any Q that fails.

1. **Deletion test (uniqueness)**: if this page is deleted, does the answer become wrong or missing? If the answer lives equally on three other pages, it belongs on the most canonical one, not here.
2. **Volume test (traffic)**: do real people search for or ask an LLM this question? Cite at least one seeding source - Google Search Console impressions, "People Also Ask" accordion, Google auto-complete, AnswerThePublic, support ticket, or LLM query log. A Q without a volume source is a red flag in review.
3. **User phrasing, not doc phrasing**: the question starts with Who/What/When/Where/Why/How/Is/Does/Can/Should and ends with `?`. Good: "How do I rotate my API key?" Bad: "API key rotation."
4. **Short answers, link out for depth**: 2-4 sentences. Answer the question directly, then link to the canonical page or section if the reader needs more. Long explanations go in the prose of the page, not in the Q\&A.

### Per-page Q count

0 to \~6 questions per page. No template, no quota. A reference page listing enum values may have 0 Qs; a concept page on freshness thresholds may have 6. Pages with 0 Qs don't need justification in code - reviewer notes it in the PR if unclear.

## Skip List - Pages That Don't Get Q\&A

The governing principle: **if a prospect would not organically land on this page from a search result or LLM answer, skip it.** These pages cannot drive acquisition traffic, so Q\&A work on them is wasted effort.

Skip the following:

* `releases/**` - release notes / changelog. Version-specific, churns every release.
* Anything with a version number in the filename or frontmatter.
* `api-reference/**` auto-generated endpoint pages - the endpoint spec is the answer.
* Deep internal reference (API error code tables, low-level config reference).
* Pure reference tables (enum lists, status code charts) where every row is already a pseudo-answer.
* Landing / nav pages with no real content (section index pages that are just a list of links).
* **Post-auth / logged-in-only pages** - user settings, admin config, billing management that only existing authenticated users can reach. Apply **per-page, not per-folder**: `security/`, `billing/`, and `account/` each contain prospect-facing pages that are still in scope.
* **App-only pages** - anything only reachable from inside the product UI (in-app help flyouts, admin panels, internal tools surfaced as docs). If the URL isn't indexed by Google and isn't quoted by LLMs, it's out of scope here.

## Toolchain

When you add or edit `<FAQ>` content:

1. Run `node customer-docs/build-markdown.js` locally. This regenerates the `.md` mirror for the page via the FAQ conversion rule (see `build-markdown.js`, `conversions.faq`).
2. Confirm the Q\&A content appears in the regenerated `.md` file. If it doesn't, the toolchain regressed - investigate before merging.
3. Optionally run `node customer-docs/scripts/generate-llms-txt.js` to update `llms.txt` (typically unchanged since it only reads frontmatter descriptions).

The FAQ component renders to plain `<h2>` / `<h3>` HTML in the live Mintlify page plus a `<script type="application/ld+json">` FAQPage block for Google structured data. Everything comes from a single source: the `<FAQItem question="..."/>` props and children.

## References

* `/snippets/FAQ.jsx` - the FAQ / FAQItem component implementation.
* `build-markdown.js` - Node build-time script that generates `.md` mirrors. The `conversions.faq` rule (patterned on `conversions.tabs`) handles `<FAQ>` → H2 + H3 Q\&A markdown.
* `mdx-to-markdown.js` - browser-side script that converts the live rendered DOM to markdown for copy-as-markdown. No FAQ-specific handling needed; the component's plain HTML output flows through the generic HTML-to-Markdown converter.
* `docs/tasks/backlog/TECH-980-customer-docs-qa-backfill.md` - the full PRD behind this convention.