whitepages · trichardswp · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,129 @@
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+
+// import .css files directly and it works
+import './index.css';
+
+import { createRoot } from "react-dom/client";
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
+
+## Code Style
+
+- Don't abbreviate names in code (e.g., use 'navigation' instead of 'nav')
+- Avoid comments in code. If code needs a comment to be understood, refactor it to be more readable instead.
+
+## Documentation Pages
+
+When adding a new page under `content/docs/`:
+
+- Add frontmatter with `title` and `description`, plus the facets that apply (`lifecycle`, `topic`, `keywords`).
+- Include a `related:` list of the most relevant other pages, as site-relative URLs — the further reading a reader (or agent) would want next:
+
+  ```yaml
+  related:
+    - /references/authentication
+    - /documentation/agentic-guidance/capability-map
+  ```
+
+  This is required, not optional polish. `related` drives two things: the "Related" cards rendered at the bottom of the page on the docs site, and the per-document `edges` in the generated corpus that power related-content discovery for the MCP documentation tools. A page with no `related` links is a dead end in that graph.
+
+- Keep the list curated — a few genuinely relevant neighbors, not every page in the section. Point at sibling guides, the matching endpoint reference, and the operational pages (authentication, billing, rate limits) a reader will need next.
+- Use URLs (e.g. `/references/billing`), never corpus ids. The generator resolves each URL to its corpus slug; the docs site links it directly. An unresolvable URL fails the corpus build.
+- For generated endpoint pages under `content/docs/references/`, curate related links in `scripts/generators/openapi/openapi.facets.ts` (`FILE_RELATED`), not in the generated `.mdx` files — `bun run generate:openapi` overwrites those.
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/content/docs/changelog/index.mdx b/content/docs/changelog/index.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /references/versioning/change-notifications
+  - /references/versioning/breaking-changes-policy
+  - /references/migration
 title: Changelog
 description: Notable changes to the Whitepages API, newest first.
 ---

diff --git a/content/docs/documentation/agentic-guidance/capability-map.mdx b/content/docs/documentation/agentic-guidance/capability-map.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/agentic-guidance/integration-guide
+  - /documentation/agentic-guidance/entity-shapes
+  - /references/person-v2/search_person_by_name_phone_or_address_v2
+  - /references/property-v2/search_property_v2
 title: Capability Map
 description: Map a user's intent to the exact endpoint and parameters that answer it.
 icon: Compass

diff --git a/content/docs/documentation/agentic-guidance/entity-shapes.mdx b/content/docs/documentation/agentic-guidance/entity-shapes.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/agentic-guidance/capability-map
+  - /documentation/agentic-guidance/integration-guide
+  - /references/person-v2/get_person_by_id_v2
+  - /references/property-v2/get_property_by_id_v2
 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

diff --git a/content/docs/documentation/agentic-guidance/integration-guide.mdx b/content/docs/documentation/agentic-guidance/integration-guide.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/agentic-guidance/capability-map
+  - /documentation/agentic-guidance/entity-shapes
+  - /references/versioning/breaking-changes-policy
+  - /documentation/mcp
 title: Integration Guide
 description: The workflow to follow when integrating the Whitepages API, by hand or with an agent.
 icon: Workflow

diff --git a/content/docs/documentation/events/event-payload.mdx b/content/docs/documentation/events/event-payload.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/events/event-types
+  - /documentation/events/get-event
+  - /references/events/get_event
 title: Event Payload
 description: Explore the full structure of an event object
 ---

diff --git a/content/docs/documentation/events/event-types.mdx b/content/docs/documentation/events/event-types.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/events
+  - /documentation/webhooks/create-webhook
+  - /documentation/events/event-payload
 title: Event Types
 description: Understand the different types of property deed events
 ---

diff --git a/content/docs/documentation/events/get-event.mdx b/content/docs/documentation/events/get-event.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /references/events/get_event
+  - /documentation/events/event-payload
+  - /documentation/events
 title: Get an Event
 description: Retrieve a specific property deed event by its unique identifier
 ---

diff --git a/content/docs/documentation/events/index.mdx b/content/docs/documentation/events/index.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/webhooks
+  - /references/events/search_deed_events
+  - /documentation/regions
 title: Events
 description: Retrieve and understand property deed events from the Whitepages API
 ---

diff --git a/content/docs/documentation/events/search-events.mdx b/content/docs/documentation/events/search-events.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /references/events/search_deed_events
+  - /documentation/events/event-payload
+  - /documentation/regions
 title: Search Deed Events
 description: Query historical property deed events by region, date range, and property identifier
 ---

diff --git a/content/docs/documentation/faq.mdx b/content/docs/documentation/faq.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/agentic-guidance/capability-map
+  - /references/rate-limits
+  - /documentation/purchasing-api
+  - /references/versioning/breaking-changes-policy
 title: FAQ
 description: Answers to the questions integrators hit most often.
 icon: CircleQuestionMark

diff --git a/content/docs/documentation/getting-started.mdx b/content/docs/documentation/getting-started.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/making-your-first-request
+  - /documentation/getting-trial-api-key
+  - /documentation/person-search
+  - /documentation/property-search
 title: Getting Started
 description: Get started with the Whitepages API
 icon: Rocket

diff --git a/content/docs/documentation/getting-trial-api-key.mdx b/content/docs/documentation/getting-trial-api-key.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/making-your-first-request
+  - /documentation/purchasing-api
+  - /references/authentication
 title: Getting a Trial API Key
 description: Step-by-step guide to signing up for a free Whitepages API trial
 icon: Key

diff --git a/content/docs/documentation/making-your-first-request.mdx b/content/docs/documentation/making-your-first-request.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/getting-trial-api-key
+  - /documentation/person-search
+  - /documentation/agentic-guidance/capability-map
 title: Making Your First Request
 description: A beginner-friendly guide to making your first Whitepages API request
 icon: Play

diff --git a/content/docs/documentation/mcp/index.mdx b/content/docs/documentation/mcp/index.mdx
@@ -1,4 +1,9 @@
 ---
+related:
+  - /documentation/getting-trial-api-key
+  - /documentation/agentic-guidance/capability-map
+  - /documentation/agentic-guidance/integration-guide
+  - /references/rate-limits
 title: MCP Server
 description: Connect to Whitepages API via Model Context Protocol for AI assistants
 icon: Plug

diff --git a/content/docs/documentation/person-search/confidence-scores.mdx b/content/docs/documentation/person-search/confidence-scores.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/person-search/fuzzy-matching
+  - /documentation/person-search
+  - /references/person-v2/search_person_by_name_phone_or_address_v2
 title: Confidence Scores
 description: How to interpret person, phone, and email confidence scores
 lifecycle: current

diff --git a/content/docs/documentation/person-search/filter-by-age-range.mdx b/content/docs/documentation/person-search/filter-by-age-range.mdx
@@ -1,4 +1,8 @@
 ---
+related:
+  - /documentation/person-search
+  - /documentation/person-search/partial-name-search
+  - /references/person-v2/search_person_by_name_phone_or_address_v2
 title: Filter by Age Range
 description: Narrow person search results using minimum and maximum age filters
 lifecycle: current