docs(mcp): add agentic guidance docs and integrator FAQ

content/docs/documentation/agentic-guidance/capability-map.mdx

@@ -0,0 +1,67 @@
+---
+title: Capability Map
+description: Map a user's intent to the exact endpoint and parameters that answer it.
+icon: Compass
+lifecycle: current
+topic: getting-started
+keywords:
+  - "capability map"
+  - "which endpoint do I use"
+  - "what endpoint for"
+  - "intent to endpoint"
+  - "reverse phone lookup"
+  - "who lives at this address"
+  - "who owns this property"
+  - "how do I find a person"
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Start here. This table maps what you are trying to do to the endpoint and parameters that do it. Match the intent, copy the parameters, then read the [type document](/references) for that endpoint before writing your types.
+
+<Callout type="warn">
+  **Person search is one endpoint.** Reverse phone lookup, address lookup, and
+  name search are all the same `GET /v2/person/` call with different parameters.
+  There is no separate "phone lookup" endpoint — pass `phone=` to person search.
+</Callout>
+
+## People
+
+| You want to…                             | Endpoint              | Key parameters                                                                            |
+| ---------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
+| Reverse phone lookup (who owns a number) | `GET /v2/person/`     | `phone=`                                                                                  |
+| Find who lives at an address             | `GET /v2/person/`     | `street`, `city`, `state_code`, `zipcode`                                                 |
+| Find a person by name                    | `GET /v2/person/`     | `name`, or `first_name` / `middle_name` / `last_name` (+ location)                        |
+| Narrow a person search                   | `GET /v2/person/`     | `min_age` / `max_age`, `include_fuzzy_matching`, `include_historical_locations`, `radius` |
+| Page through person results              | `GET /v2/person/`     | `page`, `page_size`                                                                       |
+| Get full detail for a known person       | `GET /v2/person/{id}` | path `id` (the `id` from any person object)                                               |
+
+A person search returns results scored by `match_score` (1–99). See [Entity Shapes](/documentation/agentic-guidance/entity-shapes) for how a person's shape differs by context.
+
+## Property
+
+| You want to…                         | Endpoint                | Key parameters                                                    |
+| ------------------------------------ | ----------------------- | ----------------------------------------------------------------- |
+| Find who owns a property             | `GET /v2/property/`     | `street`, `city`, `state_code`, `zipcode` → read `ownership_info` |
+| Find current residents of a property | `GET /v2/property/`     | same address params → read `residents`                            |
+| Get property detail by id            | `GET /v2/property/{id}` | path id (`R`-prefixed property id or `A`-prefixed address id)     |
+
+<Callout type="info">
+  Owners and residents come back as **summary** person objects that carry an
+  `id`. To get full detail (date of birth, relatives, historic addresses), call
+  `GET /v2/person/{id}` with that `id` — see [Entity
+  Shapes](/documentation/agentic-guidance/entity-shapes).
+</Callout>
+
+## Events and account
+
+| You want to…                             | Endpoint                 | Key parameters                             |
+| ---------------------------------------- | ------------------------ | ------------------------------------------ |
+| Find deed events / property transactions | `GET /v1/events/deed`    | see [Events reference](/references/events) |
+| Check usage / remaining quota            | `GET /v1/account/usage/` | date range                                 |
+
+## What's next
+
+- [Integration Guide](/documentation/agentic-guidance/integration-guide) — the workflow to follow before writing integration code.
+- [Entity Shapes](/documentation/agentic-guidance/entity-shapes) — the shapes you get back and how to hydrate summaries.
+- [FAQ](/documentation/faq) — trial limits, rate limits, and breaking changes.

content/docs/documentation/agentic-guidance/entity-shapes.mdx

@@ -0,0 +1,42 @@
+---
+title: Entity Shapes by Context
+description: The same entity comes back in different shapes depending on the endpoint. Do not assume one shape.
+icon: Boxes
+lifecycle: current
+topic: person
+keywords:
+  - "person shape"
+  - "response shape"
+  - "owner summary"
+  - "resident summary"
+  - "hydrate person"
+  - "person by id"
+  - "different shapes"
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+The same entity does not come back the same way everywhere. A person from one endpoint and a person from another are **different shapes** — and so are addresses. This page exists to make that one caveat unmistakable; for the exact fields, read the [type document](/references) for the endpoint you are calling.
+
+<Callout type="warn">
+  **Do not assume one shape.** A type you build from one endpoint's response
+  will not fit another's. Always read the endpoint's type document for the shape
+  it actually returns.
+</Callout>
+
+## A person comes back in three kinds
+
+- **Fetched by id** — `GET /v2/person/{id}` returns the full person record.
+- **As a search result** — `GET /v2/person/` returns persons as scored, paginated results. Same entity, presented with relevance and list context.
+- **Embedded in a property** — owners and residents inside a property response are a **reduced** form of a person, not the full record.
+
+These are not interchangeable. The embedded form in particular carries far less than the full record.
+
+<Callout type="info">
+  **Reduced forms carry an `id`.** When you get a person embedded in a property
+  response and need the full record, hydrate it with `GET /v2/person/{id}`.
+</Callout>
+
+## Addresses also differ by context
+
+An address is not one shape either: a person's address and a property's own address carry different fields. As with persons, do not reuse one address type across endpoints — check the type document for the endpoint you are calling.

content/docs/documentation/agentic-guidance/integration-guide.mdx

@@ -0,0 +1,52 @@
+---
+title: Integration Guide
+description: The workflow to follow when integrating the Whitepages API, by hand or with an agent.
+icon: Workflow
+lifecycle: current
+topic: getting-started
+keywords:
+  - "integration guide"
+  - "how to integrate"
+  - "agent workflow"
+  - "writing types"
+  - "best practices"
+  - "how should I call the api"
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+This is the prescribed workflow for integrating the API. Follow it in order; each step removes a mistake we have seen integrations make.
+
+## The workflow
+
+1. **Map the intent first.** Use the [Capability Map](/documentation/agentic-guidance/capability-map) to turn what you want ("reverse phone lookup", "who owns this property") into the endpoint and parameters. Do not guess at endpoints — person search is also phone search and address search.
+2. **Read the type document before writing types.** Each endpoint has a [reference](/references) carrying its request and response schema. That schema is the authoritative source for the shapes you integrate against.
+3. **Never infer types from sample responses.** Example payloads omit `null` and optional fields and show only one variant. A type built from an example will be wrong. Build types from the schema, not the sample.
+4. **Ignore unknown fields.** Adding a new field to a response is [not a breaking change](/references/versioning/breaking-changes-policy). Parse the fields you need and tolerate fields you do not, so new fields never break you.
+5. **Hydrate summaries by id.** Nested person objects (property owners, residents) are summaries that carry an `id`. Fetch full detail with `GET /v2/person/{id}`. See [Entity Shapes](/documentation/agentic-guidance/entity-shapes).
+
+## What costs money
+
+<Callout type="info">
+  **Documentation is free; data costs money.** Reading these docs and the
+  capability map never bills your key. Data calls (person search, property
+  lookup, account usage) are billed identically whether made over REST or the
+  MCP server.
+</Callout>
+
+Billing follows the response status: successful (`2xx`) and client-error (`4xx`) responses are billed; throttling (`429`) and server errors (`5xx`) are not. A `404` on a property lookup by address id is **not** billed, so you can optimistically resolve any address id you encounter. See [Billing](/references/billing).
+
+## Authentication
+
+Pass your key in the `X-Api-Key` header on every data call. The key is a bearer secret: never log it, echo it back, or place it in a URL.
+
+## Breaking changes, in one line
+
+Breaking changes ship only in a new API version, with at least 30 days' notice; within a version, response shapes only grow. Read the full [Breaking Changes Policy](/references/versioning/breaking-changes-policy) before you depend on a shape.
+
+## Gotchas
+
+- **Person search is one endpoint** — phone, address, and name search are all `GET /v2/person/` with different parameters.
+- **Addresses differ by context** — a person's addresses and a property's address are not the same shape. See [Entity Shapes](/documentation/agentic-guidance/entity-shapes).
+- **Property addresses are not CASS-standardized** — they come from county assessor records as-received.
+- **Trial keys exhaust** — when usage runs out you get `Limit Exceeded`, distinct from a `429`. See the [FAQ](/documentation/faq).

content/docs/documentation/agentic-guidance/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Agentic Guidance",
+  "icon": "Bot",
+  "pages": ["capability-map", "integration-guide", "entity-shapes"]
+}

content/docs/documentation/faq.mdx

@@ -0,0 +1,43 @@
+---
+title: FAQ
+description: Answers to the questions integrators hit most often.
+icon: CircleQuestionMark
+lifecycle: current
+topic: getting-started
+keywords:
+  - "faq"
+  - "frequently asked questions"
+  - "trial ran out"
+  - "trial exhausted"
+  - "how are rate limits applied"
+  - "what counts as a breaking change"
+  - "is person search the same as phone lookup"
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+## What do I do when my trial usage runs out?
+
+When a trial key uses up its allowance, data calls return `Limit Exceeded` (not a `429`). The allowance does not refill — to keep going, [purchase a plan](/documentation/purchasing-api) or contact `api@whitepages.com`. Documentation calls keep working regardless; only data calls consume the allowance. See [Rate Limits](/references/rate-limits#monthly-query-limits--trial-exhaustion).
+
+## How are rate limits applied?
+
+There are two distinct limits:
+
+- **`429 Too Many Requests`** — short-term throttling. Back off and retry with exponential backoff; it clears on its own.
+- **`Limit Exceeded`** — you have used up your monthly plan limit or trial allowance. It persists until your quota resets (next month for a plan) or you upgrade.
+
+Neither a `429` nor a `5xx` is billed. See [Rate Limits](/references/rate-limits).
+
+## What counts as a breaking change?
+
+Removing or renaming an endpoint or field, changing a field's type, adding a required parameter, or changing auth or error formats. **Adding** a new optional parameter, a new field, a new endpoint, or a new enum value is **not** breaking — so always ignore unknown fields. Breaking changes ship only in a new API version with at least 30 days' notice. Full detail: [Breaking Changes Policy](/references/versioning/breaking-changes-policy).
+
+## Is person search the same as phone lookup?
+
+Yes. Reverse phone lookup, address lookup, and name search are all the same `GET /v2/person/` endpoint with different parameters — pass `phone=` for a reverse phone lookup. There is no separate phone endpoint. See the [Capability Map](/documentation/agentic-guidance/capability-map).
+
+<Callout type="info">
+  Not seeing your question? Use `search_documentation` over the MCP server, or
+  email `api@whitepages.com`.
+</Callout>

content/docs/documentation/meta.json

@@ -14,6 +14,8 @@
     "regions",
     "property-search",
     "...mcp",
+    "agentic-guidance",
+    "faq",
     "---LLMs---",
     "[Docs List](/llms.txt)",
     "[Full Docs](/llms-full.txt)"