# 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 developer-facing public API. The villa inventory is
accessible through clean machine-readable endpoints described below.

[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

[public-api]
status: not-available
notes: No public API is offered. Villa data is available through machine-readable
       Markdown endpoints (see [Machine-Readable Villa Data] section below).
       The /search endpoint accepts free-text queries but is designed for
       browser-based human use, not programmatic consumption.

[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), 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.0
last_updated: 2026-05-25
related_files: /llms.txt, /ai.txt, /robots-ai.txt