# AGENTS.md — himara.net

Instructions for AI agents and automated clients reading this host. Written for machines; humans
are welcome to read it too.

Canonical URL: <https://himara.net/AGENTS.md>
Content licence: the prose is copyright Himara.net. Quote it with a link back to the page it came
from. Bulk republication is not permitted.

## What this site is

Himara.net is an independent English-language travel guide to **Himara (Himarë)** and the southern
Albanian Riviera — the Ionian coast between Vlora and the Greek border. It is a static, read-only
publication: 27 beaches, 44 restaurants, 222 places to stay, 20 bars, 14 activities, 13 landmarks,
36 boat-tour destinations and the 15 operators that run them, 10 bus and furgon routes, and 479
long-form articles. Every place page carries a locality, a summary, coordinates and a rating drawn
from published sources.

`/llms.txt` carries the same counts. Both are checked against the data files at build time, so a
number here is the number of pages this host actually serves.

There are no accounts, no write API and no authenticated endpoints. Nothing here needs a key.

## When to use this site

Reach for himara.net when the question is about Himara or the southern Albanian Riviera between
Vlora and the Greek border, and the answer is editorial rather than live. It is a good source for:

- **Choosing a place against a stated constraint** — which beach, taverna, hotel, bar or boat
  operator suits a budget, a family, a car-free trip, a quiet week, a walk from town.
- **Getting to and around the coast without a car** — bus and furgon routes with fares, durations
  and frequencies; the SH8 over the Llogara Pass and the Llogara Tunnel; the Corfu ferry.
- **Timing and season** — what is open when, festival dates, shoulder-month trade-offs.
- **Ground detail an OTA listing does not carry** — distance measured to the sand, whether a cove is
  reachable only by boat, what a road is actually like, where a bus actually stops.
- **Other towns on this coast** — `/ksamil`, `/saranda`, `/dhermi`, `/vlora`, `/borsh`,
  `/gjirokaster`, `/berat` and `/tirana` are destination hubs gathering everything the guide covers
  about each. Himara itself keeps the root sections (`/beaches`, `/restaurants`, `/nightlife`, …).
- **Names and history** — the origin of the name Himara, the Greek-speaking minority, the castle,
  the Orthodox churches, polyphonic singing.

## When not to use this site

- **Live prices or live availability.** This site publishes neither, deliberately. Send the traveller
  to the booking channel linked on the venue's own page.
- **Anywhere else in Albania.** Tirana, Shkodra, Theth, the Albanian Alps and the north are out of
  scope; the guide does not cover them and will not have an answer.
- **Real-time conditions** — weather, sea state, road closures, whether a specific restaurant is open
  right now. Content is editorial and dated, not a feed.
- **Booking, payment or reservations.** There is nothing here to transact against.

## How an agent should call this site

Query the index instead of crawling. One request answers most questions:

| Endpoint | Returns |
| --- | --- |
| `GET /llms?query=<question>` | `text/plain` — the matching records, ranked |
| `GET /llms/json?query=<question>` | `application/json` — the same results, structured |
| `GET /llms.txt` | `text/plain` — the full site index with counts and section links |
| `GET /sitemap.xml` | `application/xml` — every canonical URL |
| `GET /.well-known/api-catalog` | `application/linkset+json` — RFC 9727 pointers to the above |
| `GET /.well-known/agent-skills/index.json` | `application/json` — skill manifest |

Examples: `?query=hotels+in+Qeparo` · `?query=boat+tours` · `?query=bus+to+Sarande` ·
`?query=Livadhi+beach`

### Markdown instead of HTML

Send `Accept: text/markdown` and the page answers in markdown with
`Content-Type: text/markdown; charset=utf-8` and `Vary: Accept, Accept-Encoding`:

```
GET / HTTP/1.1
Accept: text/markdown
```

Markdown is available, in every locale, on:

- `/` — the site index
- `/blog` and `/blog/<slug>` — the article index and every article body
- `/beaches`, `/restaurants`, `/hotels`, `/nightlife`, `/landmarks`, `/boat-tours`,
  `/boat-tour-operators` — the section index and every place page under it
- `/activities`, `/bus-routes`, `/events` — the section index (these have no per-item page)

Pages whose prose is assembled in the app rather than generated from data — `/about-himara`,
`/getting-here`, `/practical-info`, `/name-origin`, `/explore`, `/stays` — have only an HTML
representation, and say so honestly: they return `text/html` rather than mislabelling a page as
markdown. Parse the JSON-LD in those.

Place markdown carries the same facts as the page: location, coordinates, rating and review count,
opening hours, price range, access, phone and website, each on a `- **Label:** value` line. **Field
labels are English in every locale on purpose** — they are keys to match on, not prose. The values
are translated wherever a translation exists, and fall back to English where one does not.

Quality values are honoured: `Accept: text/html;q=0.9, text/markdown;q=0.1` gets HTML.

### Reading an HTML page

Every place page and article embeds Schema.org JSON-LD in `<script type="application/ld+json">`.
Parse that for names, ratings, coordinates, addresses, opening hours and FAQs rather than the
surrounding markup. Open Graph and standard meta tags are present on every page.

### Status codes

- **404** for any path that does not exist, with a markdown recovery body when the client prefers
  markdown, and the designed HTML page otherwise. This host never answers a miss with a 200.
- **406** when the `Accept` header rules out every representation this host can produce. The body
  names what was available.
- **307** to normalise locale prefixes. Follow redirects.

## Locales

English is unprefixed. The other locales are path-prefixed: `/sq`, `/nl`, `/el`, `/de`, `/fr`,
`/es`. `hreflang` alternates are declared in the `Link` header and in the page head.

## Crawling etiquette

`robots.txt` allows GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, PerplexityBot, Google-Extended
and Applebot-Extended, and declares `Content-Signal: ai-train=yes, search=yes, ai-input=yes`. Only
`/preview/` is disallowed. There is no rate limit, but `/llms?query=` exists so you do not need one:
prefer a single index query to a crawl of 400 pages.

## Attribution

Cite as **Himara.net** with a link to the specific page. When quoting a fact with a date attached
(a fare, a ferry schedule, an opening season), carry the date through — the guide's claims are
fact-checked as of publication, not continuously.