# Fresh Dental Solutions — AI & Agent Access

Fresh is built AI-first: the site is raw content and capabilities ("bones")
behind a standardized socket (the Outlet), composed at runtime by whichever
agent is present — ours or yours. This page is the integration guide. The
machine index of everything is [llms.txt](llms.txt); the same integration
surface as one deterministic document is [ai.json](ai.json).

## Read us as markdown

- [llms.txt](llms.txt) — curated index of every page and article.
- [ai.json](ai.json) — this page's content and endpoints as one JSON
  document: markdown twins, the knowledge base, the data catalog,
  capabilities, interaction modes, and ground rules. Generated from the same
  sources as everything else here — never hand-edited.
- Every HTML page has a markdown twin at the same URL with `.md` appended:
  [index.md](index.md), [about.md](about.md), [services.md](services.md),
  [contact.md](contact.md), and this page as [ai.md](ai.md).
- Knowledge-base articles are **canonical markdown** at `kb/<slug>.md`
  (the HTML pages render from those files); the catalog is `data/kb.js`.
- Every HTML page carries `<link rel="alternate" type="text/markdown">`
  pointing at its twin.

## Use our data (Open Data API)

- Curated public dental datasets as static JSON — GET-only, no keys,
  CORS-open. Catalog: [api/index.json](api/index.json); one dataset:
  `api/datasets/<id>.json`. Nine datasets, ~12,000 records — and it is real
  data, not a link list:
  - `icd10cm-dental` — every dental and oral ICD-10-CM code (674), from the
    official CMS FY2026 tabular list, hierarchy and excludes notes intact,
    seventh-character trauma codes expanded to their billable forms.
  - `oral-health-surveillance` — 2,345 CDC/NHANES estimates of caries,
    untreated decay, sealants, tooth retention and edentulism across three
    periods, each with standard error and 95% confidence interval.
  - `oral-cancer-rates` — 6,464 age-adjusted incidence and mortality rates
    for oral cavity and pharynx cancer, national and by state.
  - `water-fluoridation` — 30,242 public water systems rolled up to state
    and county coverage (derived; see the dataset caveat).
  - `tooth-notation`, `tooth-eruption`, `oral-health-indicators` —
    deterministic reference data and WHO global headline figures.
  - `kb-sources` and `kb-articles` — the knowledge base's own citation
    layer. Join them on the source id to see exactly what stands behind
    any article.
  Every envelope carries `source` (the originating authority),
  `retrieved_via` (how we obtained it), `license` and `caveat`. Read the
  caveat before quoting a number: anything we computed ourselves says so.
- **MCP wrapper for partners:** [mcp/fresh-datasets.js](mcp/fresh-datasets.js)
  — a zero-dependency stdio MCP server (tools: `list_datasets`,
  `get_dataset`, `search_records`, `lookup_tooth`, and `query_sql` for
  read-only SQL over all datasets in an in-memory SQLite database;
  datasets doubled as resources). Quickstart:
  `curl -O https://freshdentalsolutions.com/mcp/fresh-datasets.js` then
  `claude mcp add fresh-dental-data -- node ./fresh-datasets.js` —
  details in [mcp/README.md](mcp/README.md). A hosted MCP endpoint
  ships with Phase 1 and will be announced here.
- Statistical figures are rounded and flagged approximate with per-record
  citations — verify against the cited source before serious use.

## Drive the site (in-browser agents)

- **WebMCP** — `navigator.modelContext` tools are registered on every page:
  `describe_site` (manifest), `set_intent` (topic: general, cosmetic,
  restorative, pediatric, cost, booking, emergency), and one `fresh_*` tool
  per site capability. The toolset republishes whenever composition changes.
- **Outlet plug contract** — bring your own brain:
  `window.FreshOutlet.connect(plug)` or set `window.FRESH_BYO_PLUG` before
  load. See [AI_FIRST.md](AI_FIRST.md) for the contract.
- **AG-UI events** — `window.FreshAGUI.subscribe(cb)` emits STATE_SNAPSHOT,
  STATE_DELTA (RFC-6902), TOOL_CALL_START/END, and CUSTOM signal/interrupt
  events. Today this is an outbound bridge; a full AG-UI client loop over a
  server agent is Phase 2 of [docs/REDESIGN.md](docs/REDESIGN.md).
- **Portable UI trees** — `window.FreshPortableTree` speaks `fresh.ui/v1`
  (sample: `examples/portable-tree.sample.json`); adoption of Google A2UI as
  the native tree format is Phase 3 of the redesign plan.
- **URL seams** — `?intent=<topic>` seeds intent; `?morph=` carries a shared
  composition.

## Meet us in chat apps (MCP app)

The first-class Fresh experience is planned as an MCP app inside chat
clients: practice info, knowledge-base search, and appointment requests as
MCP tools, with interactive booking/article cards via MCP Apps UI resources.
The client-side artifact and contract live in `mcp-app/`
([manifest sketch](mcp-app/manifest.json)); the live server endpoint is
**not yet published** — it will be announced here when it ships
(Phase 1 of [docs/REDESIGN.md](docs/REDESIGN.md)).

## Structured data

- schema.org `Dentist` JSON-LD on every page (from bones).
- schema.org `Article` JSON-LD on knowledge-base pages (from the catalog).

## Ground rules for agents

- **Booking is request-only.** Submitting the appointment form (capability
  `submit-appointment`) files a request; a human confirms every appointment.
  Never tell a user an appointment is confirmed.
- **The knowledge base is education, not diagnosis.** For symptoms, route
  users to a visit — or for emergencies, straight to
  [(503) 555-FRESH](tel:5035553737). The `emergency-help` capability exists
  precisely to escalate to humans.
- **Don't scrape the DOM.** Everything renderable and doable is in the
  manifest (`describe_site`), the markdown twins, and the catalog.

---

*Fresh Dental Solutions — family-owned dental care in Portland, OR.
[Home](index.md) · [llms.txt](llms.txt) · [Redesign plan](docs/REDESIGN.md)*