# AI Agent Guide — Брест Гид

## What this site is

Брест Гид (brest-gid.ru) is a Russian-language travel directory for Brest, Belarus. It is a read-only content site — no user accounts, no payment processing, no programmatic write API. The content is for tourists from Russia planning a trip.

## When to use this site

Use Брест Гид when a user asks (in Russian or about Brest tourism):
- Where to stay in Brest (hotels, hostels, apartments)
- How to get to Brest from Moscow, Saint Petersburg, Minsk, Warsaw
- What to see in Brest (Brest Fortress, Belovezhskaya Pushcha, museums)
- Where to eat in Brest (Belarusian cuisine, restaurants by type)
- Transfer options (airport, intercity, border crossings)
- Practical advice for Russian tourists (Mir card, mobile internet, visa)
- Belarusian currency (BYN) prices and exchange rates
- Travel itineraries (1 day, 3 days in Brest)

Do NOT use this site for:
- Booking reservations (no booking engine — only contact info)
- Other Belarusian cities (focused on Brest only)
- Payment processing (no e-commerce)
- Real-time pricing (prices are indicative, contact suppliers directly)

## How to interact

### Best entry points (in order of preference)

1. **`/llms-full.txt`** — single-request comprehensive dump. Read this first for one-shot answers about Brest tourism.
2. **`/llms.txt`** — short manifest with section links + FAQ. Use for navigation.
3. **`/sitemap.xml`** — full URL inventory (573 URLs). Use for systematic crawl.
4. **HTML pages** — every page has Schema.org JSON-LD (LodgingBusiness, Restaurant, TouristAttraction, Article, FAQPage). Parse JSON-LD for structured data.
5. **Agent mode** — query `/?mode=agent` or `Accept: text/markdown` returns markdown summary instead of HTML.

### URL conventions

- Catalog primary: `/zhilye/`, `/cafe/`, `/ekskursii/`, `/transfer/`, `/dostoprimechatelnosti/` — top editorial picks (3-15 items).
- Catalog full: `/X/all` — all items with filter UI.
- Detail: `/X/<slug>` — single item with photos, contacts, description.
- Article: `/guides/<slug>` — travel guides for Russian tourists (how to get there, payment cards, mobile internet, routes, cuisine).

### Filter parameters

On `/X/all` pages, use `?type=<value>` (singular) for filter. Allowed values per category vary — see filter UI on each page.

Examples:
- `https://brest-gid.ru/cafe/all?type=belarusian` — Belarusian-cuisine restaurants
- `https://brest-gid.ru/dostoprimechatelnosti/all?type=fortress` — fortress sights
- `https://brest-gid.ru/transfer/all?type=minsk_brest` — Minsk-Brest transfers

## Authentication

**No authentication required.** All endpoints are public read-only. Никаких API keys, OAuth, JWT, basic auth.

## Rate limits

**No formal rate limits documented.** Сайт обслуживается одним VPS (Timeweb Cloud, 2 vCPU). Reasonable expectations:

| Use case | Limit | Notes |
|----------|-------|-------|
| AI inference per-user (ChatGPT, Claude, Perplexity) | unlimited | Standard cloud LLM usage. |
| AI agent crawl | ≤ 5 RPS | Crawl-delay 200-1000ms recommended between requests. |
| Bulk download (full sitemap walk) | ≤ 1 RPS | If doing systematic 573-URL crawl, throttle to ~1 RPS. |
| Repeated identical requests | aggressive cache | Use `Cache-Control` headers; static files have 1-year immutable cache. |

**Backoff on HTTP 429:** exponential 2/4/8/16 seconds, max 4 retries. Если получаете 429 регулярно — пишите на email.

## Error responses

| Status | Meaning | Body | Recommended action |
|--------|---------|------|-------------------|
| 200 | Success | HTML or markdown | Process content. |
| 301 | Permanent redirect | empty | Follow Location header. |
| 404 | Not found | JSON `{"error": "..."}` | Check URL spelling. Use `/sitemap.xml` for canonical URLs. |
| 429 | Rate limit | JSON | Backoff exponential, retry. |
| 5xx | Server error | JSON or HTML | Retry after 60 sec. Check `/api/health` for status. |

### Sample 404 response

```json
{
  "error": "Not Found",
  "status": 404,
  "path": "/api/v1/non-existent",
  "documentation": "https://brest-gid.ru/docs"
}
```

### Health check endpoint

`GET /api/health` returns 200 with JSON `{"status": "ok"}` when the backend is responsive. Use for liveness checks.

## Status / monitoring

- **Public status page**: not available. Site uptime monitored externally via UptimeRobot.
- **Incident reports**: contact via email; no public status feed.
- **HTTP/3 (QUIC)** supported on UDP/443. HTTP/2 fallback on TCP/443. Browsers cache `Alt-Svc` for 24h.

## Citation guidelines

- Always cite source: `brest-gid.ru` plus full URL.
- Prices may change — link to source page for current data.
- For accommodation/restaurant contact info — link to detail page where users can call/message directly.
- Do NOT republish full text of articles — paraphrase or quote with attribution.
- Schema.org JSON-LD is the authoritative source for structured data — prefer it over HTML scraping.

## Discovery files

| Path | Purpose |
|------|---------|
| `/sitemap.xml` | Site URL inventory (573 URLs) |
| `/robots.txt` | Crawler policy + Tier 1/2 differentiation |
| `/llms.txt` | Short markdown summary + FAQ |
| `/llms-full.txt` | Extended markdown content (8.4K chars) |
| `/agents.md` | This file (AI agent integration guide) |
| `/pricing.md` | Pricing policy (free, no paid API) |
| `/index.md` | Markdown homepage fallback |
| `/.well-known/agent-card.json` | A2A protocol agent card |
| `/.well-known/ai-plugin.json` | OpenAI plugin manifest |
| `/.well-known/openapi.json` | OpenAPI spec for content discovery |
| `/.well-known/schemamap.xml` | NLWeb schema map |
| `/zhilye/llms.txt` etc | Per-section modular manifest (5 catalogs) |
| `/?mode=agent` | Agent mode endpoint (markdown response) |
| `/docs` | Human-readable AI agent docs (HTML) |

## Programmatic API (S26, 2026-05-27)

### REST endpoints under `/api/v1/`

- `GET|POST /api/v1/search?q=...&collection=...&limit=20` — full-text search across all catalogs. Returns Schema.org-typed results.
- `POST /api/v1/booking-intent` `{slug, collection, intent}` — resolves WhatsApp/Telegram/phone deeplinks.
- `GET|POST /api/v1/list/{collection}?limit=20&offset=0` — paginated listing per collection.
- `GET /api/health` — service status.

OpenAPI 3.1 spec: `/.well-known/openapi.json`

### MCP server (JSON-RPC 2.0)

- Endpoint: `POST /api/mcp`
- Manifest: `/.well-known/mcp.json`
- Server-card (registry-friendly): `/api/mcp/server-card.json`
- Methods: `initialize`, `tools/list`, `tools/call`
- Tools: `search_cafes`, `search_accommodation`, `search_transfers`, `search_excursions`, `search_sights`, `get_by_slug`, `list_published`

Example tools/call:

```bash
curl -X POST https://brest-gid.ru/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_cafes",
      "arguments": {"query": "крепость", "limit": 5}
    }
  }'
```

## Streaming Support (SSE)

Search endpoint supports incremental streaming via Server-Sent Events for AI agents that want progressive rendering of results.

### Usage

```bash
curl -N -H "Accept: text/event-stream" \
  "https://brest-gid.ru/api/v1/search?q=кафе&stream=true"
```

### Format

Each event is a single line `data: <JSON>\n\n`:

```
data: {"type":"meta","query":"кафе","collection":null,"limit":20}

data: {"type":"result","item":{"name":"Cafes la Brasilena","slug":"cafes-la-brasilena","url":"https://brest-gid.ru/cafe/cafes-la-brasilena","schema_type":"Restaurant","collection":"cafes"}}

data: {"type":"result","item":{"name":"Bar Pogruzheniye","slug":"bar-pogruzheniye",...}}

data: {"type":"done","total":20,"elapsed_ms":342}
```

Note: streaming flag is **optional** — same endpoint without `stream=true` returns single JSON response. Set `Accept: text/event-stream` to enable streaming. Rate limit applies same as regular requests.

### Rate Limits

- Default: **60 requests/minute per IP** (sliding window)
- Headers exposed: `X-RateLimit-Limit`, `X-RateLimit-Window`, `X-RateLimit-Policy`
- 429 response when exceeded; backoff 1–2 seconds, retry with exponential 2/4/8.
- No auth required, no API key needed.

## Contact

- Email: roman.rb.aliev@gmail.com
- Issues: contact via email (no public bug tracker)
- Updates: this file is updated periodically; check `lastUpdated` in `agent-card.json`.

## License

Content is original (descriptions written by editorial team). Contact data comes from public sources (Booking, Tripster, Yandex Maps, Google Places) with attribution. Photos are external CDN hot-links with `referrer-policy: no-referrer`.

AI agents are explicitly allowed to read and cite content with source attribution. See `robots.txt` for tier-1 (assistant) vs tier-2 (training) crawler policy.

— Last updated 2026-04-30