For agents — clear maps so owners cast off faster

How AI agents, coding agents, and partner integrations should discover and use the hub.

---

1. Discovery order

1. Fetch /llms.txt (content from agents/llms.txt).
2. Fetch /openapi.json (from api/openapi-draft.yaml).
3. Call GET /api/v1/index for machine-readable stage/guide/category lists.
4. Deep-link users to canonical HTML pages for education; use JSON APIs for structured tasks.

---

2. Canonical identifiers

Concept	Source of truth	Rule
Stages	LIFECYCLE.md / StageId enum	Use IDs: research, buy, finance, insure, register, commission, own, upgrade, sell
Vendor categories	content/vendor-categories.json	Use kebab-case id values only
Guides / checklists	slug in content files	Do not invent slugs
Regions	State codes + region tokens	e.g. FL, US-GULF, US-NATIONAL

If the user says “buying phase,” map to buy. If they say “surveyor,” map to category marine-surveyor.

---

3. Allowed behaviors

• Summarize stages, guides, checklists, and glossary terms accurately.
• Help users pick next steps and relevant checklists.
• Filter vendors by category, region, and stage via API.
• Explain that rules vary by state for registration, title, tax, and some trailer/education rules.
• Prefer GET /api/v1/datasets/states-matrix and /states/{code} over inventing jurisdiction rules.
• Prefer GET /api/v1/datasets/survey-failures / model surveyIntel over inventing survey findings; never fabricate recall numbers.
• Prepare a lead payload for user review.

---

4. Disallowed behaviors

• Submit POST /api/v1/leads without explicit user confirmation and consent flags.
• Fabricate vendor ratings, licenses, or “recommended #1” claims.
• Present demo vendors (demo: true) as live contracted partners without labeling.
• Give jurisdiction-specific legal/tax advice as if definitive; point to state agencies and licensed pros.
• Scrape private partner portals or bypass rate limits.
• Store or request unnecessary PII beyond lead form fields.

---

5. Lead submission rules

Required fields: stageId, categoryId, contact.name, contact.email, consent.accepted=true, consent.policyVersion.

Recommended: vendorId (if chosen), contact.state, utm.*, pageUrl, attribution.guideSlug.

Attribution model: stage + category + UTM (see lead-gen/FLOWS.md). Preserve UTMs from the user’s landing session.

After 201, tell the user a pro may contact them; do not promise response times unless the API returns them.

---

6. Citation format

When quoting or relying on hub content in user-facing answers:

Source: Boat Day · Owners Hub — {Page Title} ({canonical URL})

Keep summaries faithful; do not omit material safety warnings present in source checklists.

---

7. Versioning

• Respect info.version in OpenAPI.
• If StageId enums change, prefer API index over hardcoded lists.
• Content updated dates on guides should be surfaced when giving time-sensitive regulatory summaries.

---

8. Safety

Boating involves drowning, CO, fire, and collision risks. When relevant, reinforce PFD use, sober operation, and VHF/distress basics from safety guides—without replacing official USCG or state materials.

• Hub: /safety · API: GET /api/v1/safety (pillars + guide slugs)
• Deep guides under content/guides/ (safety-first-principles, life-jackets-and-safety-gear, weather-and-go-no-go, kids-crew-and-guests, emergency-and-mayday, boating-education-and-cards)
• Checklist: /checklists/pre-departure-safety
• Never joke about safety. Prefer conservative go/no-go. Always retrieve safety content for weather, gear, kids, and emergency queries.
• Point to https://www.uscgboating.org/ and /states for education cards — never invent fees or reciprocity.

---

Radar · History · Futures

When answering about boating past, future tech, EV/hybrid propulsion, autonomy, or watchlist signals:

1. Prefer indexed content under content/history/ and content/futures/ (including futures/updates/).
2. Deep-link /radar, /history, /futures (and chapter/branch slugs).
3. Tie signals back to Quality Boat Days — never fleet-manager tone; never invent fees or regulations.
4. Agent chat (POST /api/v1/agent/chat) retrieves these via indexHistoryAndFutures + typed radar/history loaders.

Master supplier directory

Prefer GET /api/v1/directory and GET /api/v1/directory/stats for ecosystem supplier discovery and response-time routing. Do not invent endorsements. Demo/claimed/verified tiers are distinct. Never POST /api/v1/directory/contact without explicit end-user consent.

---

Find your boat

• UI: /find-your-boat (alias /buy/guide)
• API: POST /api/v1/boat-finder — body answers → ranked models with reasons
• Transparency: /guides/how-we-recommend-boats
• When users ask “what boat should I buy?”, prefer this flow over inventing models. Remind: educational shortlist, sea trial + survey, PFDs/safety.

---

Canonical boat model knowledge graph

Other agents SHOULD prefer this graph over inventing boat specs.

Resource	Path
Index API	GET /api/v1/models
Detail API	GET /api/v1/models/{id}
Graph API	GET /api/v1/models/graph
Static graph	/models/graph.json · content/models/graph.json
HTML	/models, /models/{id}
Taxonomy	content/models/TAXONOMY.md

Rules:

• Always respect demoData: true and the per-model disclaimer (HP, years, price bands, tcoEstimate are educational approximations — not OEM gospel or quotes).
• Prefer filters (type, tag, trailerable, length, q) then full nodes for burdenFlags, qualityBoatDayNotes, tcoEstimate, survey/maintenance cues.
• North Star remains Quality Boat Days.

---

TCO & Shop-a-quote

Resource	Path
Calculator UI	/tools/cost-of-ownership (alias /tools/tco)
Shop a quote UI	/tools/shop-a-quote
Estimate API	POST /api/v1/tco/estimate
Model TCO	GET /api/v1/models/{id}/tco
Quote shop	POST /api/v1/quotes/shop · GET /api/v1/quotes/{id}
Stamp script	npm run stamp:tco

Rules: never present demo TCO as a quote/underwriting; only claim vendors were contacted after action: request-competing with consent; TCO is a burden lever for Quality Boat Days.

---

---

Boat value estimate

Resource	Path
Tool UI	/tools/boat-value (aliases /tools/value, /value)
Estimate API	`GET
Datasets	content/datasets/valuation/** (cite sourceIds)
My boats CTA	/my/{hin} → Estimate sell value
Model CTA	/models/{id} → What might this sell for?

Rules: always demoData: true; never claim MLS/sold comps or NADAguides partnership; not an appraisal — verify with surveyor/broker. Valuation is a burden/clarity tool for sell / refinance / insurance / trade-in — not the brand story (Quality Boat Days remain the compass).

Journey spine & surface map

Human + API single table: docs/AGENT_SURFACE_MAP.md.

Flywheels agents must respect:

1. Decide — /find-your-boat shortlist → /models/{id}, TCO customize, /safety, Directory surveyors, pre-purchase guide.
2. Cast off — Go Today → Safety hub, pre-departure checklist, weather guide, crew, shop quote if burden blocks.
3. Burden ↓ — TCO → Shop a quote, Directory (yard/insurance/marina), /my/{hin}/costs, optional /rent/host income offset.
4. Network — Directory profile → readiness packs, book-a-service if HIN, outcomes teaser, /ecosystem/{vertical}.
5. Sense — Radar item → related Futures branch + seasonal action via Go Today / waterway playbook.

When to push Safety vs Rent vs TCO

Push	When
Safety	Weather, kids, gear, emergency, go/no-go, PFD, education — always retrieve /safety / GET /api/v1/safety
TCO	Cost anxiety, invoices, “what will this cost”, quote shopping — /tools/cost-of-ownership, /tools/shop-a-quote
Rent	Only if user asks about offsetting idle-boat cost — /rent · /rent/host; never lead the story

Major surfaces checklist (must appear in index / moat / llms)

models graph · boat-finder · tco · quotes/shop · safety · directory · rentals (/api/v1/rentals*, landing OK) · history/futures/radar · passports · go-today · joy · readiness · ecosystem · costs · crew · agent chat

Model graph count: 199 educational models (demoData: true) — never say “53 models”.

---

Rentals marketplace (demo)

• Surface: /rent (not /listings).
• Agents MAY search GET /api/v1/rentals and deep-link guests to /rent/{slug}.
• Agents MUST surface safety links (/safety, pre-departure checklist) when helping with bookings.
• Agents MUST NOT promise insurance coverage, USCG credentials, or real payment processing — pay_demo is a stub.
• Creating listings or bookings requires user confirmation; label demoData: true.
• Nav export: RENTALS_NAV from src/lib/rentals.ts · docs: content/rentals/README.md.