diff --git a/content/docs/documentation/agentic-guidance/capability-map.mdx b/content/docs/documentation/agentic-guidance/capability-map.mdx
new file mode 100644
index 0000000..9e11648
--- /dev/null
+++ b/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.
+
+
+ **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.
+
+
+## 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) |
+
+
+ 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).
+
+
+## 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.
diff --git a/content/docs/documentation/agentic-guidance/entity-shapes.mdx b/content/docs/documentation/agentic-guidance/entity-shapes.mdx
new file mode 100644
index 0000000..6eda430
--- /dev/null
+++ b/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.
+
+
+ **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.
+
+
+## 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.
+
+
+ **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}`.
+
+
+## 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.
diff --git a/content/docs/documentation/agentic-guidance/integration-guide.mdx b/content/docs/documentation/agentic-guidance/integration-guide.mdx
new file mode 100644
index 0000000..fcfcc67
--- /dev/null
+++ b/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
+
+
+ **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.
+
+
+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).
diff --git a/content/docs/documentation/agentic-guidance/meta.json b/content/docs/documentation/agentic-guidance/meta.json
new file mode 100644
index 0000000..26887dd
--- /dev/null
+++ b/content/docs/documentation/agentic-guidance/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Agentic Guidance",
+ "icon": "Bot",
+ "pages": ["capability-map", "integration-guide", "entity-shapes"]
+}
diff --git a/content/docs/documentation/faq.mdx b/content/docs/documentation/faq.mdx
new file mode 100644
index 0000000..49f249a
--- /dev/null
+++ b/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).
+
+
+ Not seeing your question? Use `search_documentation` over the MCP server, or
+ email `api@whitepages.com`.
+
diff --git a/content/docs/documentation/meta.json b/content/docs/documentation/meta.json
index 5637e55..28b39d9 100644
--- a/content/docs/documentation/meta.json
+++ b/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)"