# developer-ai.txt for Premium Island Vacations
# https://www.premiumislandvacations.com/developer-ai.txt
# Specification: https://www.ai-visibility.org.uk/specifications/developer-ai-txt/ (v1.8.0)
# Last updated: 2026-05-25

Lang: en-GB

[overview]
Premium Island Vacations operates a single public-facing website at
www.premiumislandvacations.com. The site is a statically generated and
selectively server-side rendered Astro 5 application, hosted on Vercel.
An image CDN operates separately at images.premiumislandvacations.com
(Cloudflare R2 with Cloudflare Image Resizing).

The site aggregates ~565 villa listings sourced from two suppliers,
enriched with AI-generated descriptions and photo analysis. Villa data
is stored as JSON files (a content collection) and served statically
or via SSR depending on the page type.

There is no general developer-facing REST API. The villa inventory is
accessible through clean machine-readable endpoints described below, plus
one read-only selection endpoint for explicit villa IDs and dates.

[public-areas]
- All pages under /st-barts-villas/ — public, no authentication
- /search — public natural-language search (SSR, POST-based)
- /about-st-barts, /christmas-in-st-barts, /new-years-eve-st-barts — public destination content
- /st-barts-concierge — public concierge information
- /contact-us, /about-us — public
- /llms.txt, /ai.txt, /ai.json, /identity.json, /brand.txt, /faq-ai.txt,
  /developer-ai.txt, /robots-ai.txt, /llms.html, /villas.md — all public
- /st-barts-villas/{slug}.md — public per-villa Markdown (one per live villa)
- /st-barts-villas/llms-full.txt — public full corpus Markdown
- /st-barts-villas/llms.txt — public section-level discovery
- GET /api/villa-selection — public JSON selection rows (see [villa-selection])

[public-api]
status: limited
notes: No general CRUD or inventory API. Villa data is available through machine-readable
       Markdown endpoints (see [Machine-Readable Villa Data] below) and through
       GET /api/villa-selection when explicit villa doc_ids and travel dates are known.
       The /search endpoint (AI smart search) accepts free-text natural-language
       queries and is suitable for agents forwarding a user's free-text request:
       it resolves intent, matches villas with availability for the requested
       dates, and quotes them. It is SSR/POST-based, rate-limited, and consumes
       PIV's LLM budget, so for deterministic programmatic filtering prefer
       constructing /st-barts-villas URLs with the documented parameters.

[villa-selection]
endpoint: GET https://www.premiumislandvacations.com/api/villa-selection
auth: none (public read)
purpose: Priced proposal rows for explicit villa IDs and a date range — used by
         the proposal bridge and available to agents with known villa doc_ids.
query: Standard listing filters and/or repeated id= parameters with from, to,
       bedrooms (see /st-barts-villas filter parameters in llms.txt). The
       twins=true filter restricts matches to villas offering twin beds
       (twin rooms, or king/queen rooms convertible to twins).
response: JSON object with checkedAt, qualification, items[], excluded[], total,
          truncated, plus rendered html and text fragments for email-style display.
item fields (structured JSON): id, name, url, thumbnail, location,
          propertyBedrooms, maxOccupancy, beds, twins, quote, currency, dates,
          availability, requestedBedrooms, childPolicy, petPolicy, and related
          display context. beds is a semicolon-separated summary of bed
          types/phrases (max 200 characters), derived from published villa room
          data — not raw room arrays. twins is true/false when bed data exists.
          childPolicy is {restricted: boolean|null, minAge: number|null};
          petPolicy is "unauthorized"|null.
null semantics: null or absent means the supplier is SILENT on that fact —
          never read it as "no" or "not allowed". Coverage today: beds ~95% of
          enabled villas, twin signal ~28%, sunset_view answerable for ~180
          enabled villas (corpus-wide ~200), child minimum age ~80, pet policy
          can only ever state "unauthorized" (banned) — no positive
          "pets welcome" signal exists in any feed. Morning/afternoon sun
          orientation has no data source.
render note: The html and text fragments omit maxOccupancy, beds, twins and the
          policy fields; consume those fields from the structured items[] only.
qualifier: Availability and pricing are live but indicative — final availability
          and price are always confirmed with the villa owner before booking.

[machine-readable-villa-data]
# These are the correct surfaces for agents and automated retrieval:

- [Full villa corpus (Markdown)](https://www.premiumislandvacations.com/st-barts-villas/llms-full.txt)
  All ~565 live villas in one Markdown file. Includes name, neighbourhood, bedrooms,
  bathrooms, pool, amenities, indicative rate, and description per villa.
  Updated at each deployment (typically after the daily villa import pipeline runs).

- [Villa index (Markdown)](https://www.premiumislandvacations.com/villas.md)
  Index of all live villas: slug, neighbourhood, bedroom count, and direct link to
  the per-villa Markdown leaf. Fetch this first, then retrieve individual leaves.

- [Per-villa Markdown](https://www.premiumislandvacations.com/st-barts-villas/{slug}.md)
  Append .md to any villa URL to get a clean Markdown summary. 1–3 KB per villa.
  Includes a pricing caveat header.

- [Villa search with filters](https://www.premiumislandvacations.com/st-barts-villas)
  SSR page accepting URL parameters: bedrooms, location (repeatable), from, to
  (YYYY-MM-DD), minprice, maxprice, amenities (comma-separated flags:
  heated_pool, ac_living_room, american_tv, gas_grill, sunset_view,
  child_restrictions, beach_access, on_beach — the last four are null-heavy in
  supplier data, so an absent flag on a villa usually means unknown, not no),
  twins (true), search, order, map.

[authentication]
Public content (villa listings, destination pages, AI discovery files):
- No authentication required

Admin CMS (/keystatic/):
- Session-based authentication (Lucia)
- User roles: admin (full access), search_and_send (limited)
- Not accessible to external parties

Admin panel (/admin/):
- Session-based authentication
- Not accessible to external parties

[platforms]
www.premiumislandvacations.com
- Purpose: Main villa rental site
- Framework: Astro 5 (static + SSR)
- UI components: Svelte 5 (interactive), React (CMS only)
- Hosting: Vercel (primary), Netlify (backup config)
- CDN / Edge: Cloudflare

images.premiumislandvacations.com
- Purpose: Image CDN
- Infrastructure: Cloudflare R2 object storage + Cloudflare Image Resizing
- Image formats: WebP (three sizes per photo: thumb 640px, hero 1920px, full 2560px)
- Access: Public read, authenticated write (sync worker)

[technology-stack]
Note: Provided for context only.
- Framework: Astro 5
- Interactive UI: Svelte 5 (runes), React (Keystatic CMS only)
- Styling: Tailwind CSS 3, SCSS
- CMS: Keystatic (local dev / cloud production)
- Database: Astro DB (auth tables only; villa data is JSON files)
- Auth: Lucia (session-based)
- Images: Cloudflare R2 + Image Resizing (3 WebP sizes)
- AI: DeepSeek (search + descriptions), SiliconFlow VLM (photo analysis), OpenAI (embeddings)
- Deploy: Vercel (primary)
- Data pipeline: Node.js scripts (npm run import) pulling from two villa suppliers

[documentation]
- [Agent skills / SKILL.md](https://www.premiumislandvacations.com/.well-known/agent-skills/piv-st-barts-villas/SKILL.md) — Canonical instructions for querying the villa inventory
- [For agents (human-readable index)](https://www.premiumislandvacations.com/for-agents) — All machine-readable surfaces listed with descriptions
- [llms.txt](https://www.premiumislandvacations.com/llms.txt) — Concise site summary
- [faq-ai.txt](https://www.premiumislandvacations.com/faq-ai.txt) — Structured Q&A

[technical-contact]
general: villas@premiumislandvacations.com

[metadata]
version: 1.1
last_updated: 2026-09-23
related_files: /llms.txt, /ai.txt, /robots-ai.txt