# Codex App Builder Instructions for Guido

This directory is the live Guido app root:

`/www/vims/bled.net/app/Guido/`

Public URL:

`https://bled.net/Guido/`

## Ownership Boundary

- This folder belongs to the Guido app, not to the bled.net Astro site build.
- Do not delete, overwrite, clean, or rsync over this directory from the bled.net
  Astro project.
- Do not create `public/Guido/` in the bled.net Astro source tree unless the
  ownership model is deliberately changed.
- The bled.net deploy protection file must continue to exclude `Guido/`.
- New Guido app releases may publish into this folder, but only from a
  Guido-owned source/release workspace or by copying explicit build artifacts.

## Safe Deployment Rule

When deploying Guido, treat this folder as an application root with persistent
state. Prefer these patterns:

- Build the app elsewhere.
- Review the generated files.
- Sync only the intended app bundle into this directory.
- Keep backups before replacing existing files.
- Never use a broad delete sync unless the user explicitly approves it for the
  Guido app release.

## bled.net Site Relationship

The main bled.net site lives separately:

- Source/build tree: `/www/vims/bled.net/src-base`
- Public app root: `/www/vims/bled.net/app`
- Guido live root: `/www/vims/bled.net/app/Guido`

The bled.net Astro workflow is allowed to update the main site, `/api/`, and
`/data/`, but must preserve:

- `/Guido/`
- `/uploads/`
- `.env`
- `.creditentials`

## Tour Data Contract

The Guido app should read public tour/package data at runtime from:

`https://bled.net/data/tours.json`

Use a no-cache fetch when online, and keep the last successful response as an
offline fallback.

Important fields:

- `slug`: stable tour identifier.
- `title`, `short_description`, `description`: display text.
- `route_variants`, `highlights`, `includes`: route metadata.
- `full_price_eur`: regular full ownership price.
- `ownership_intro_price_eur`: introductory full ownership price.
- `day_pass_price_eur`: 1-day pass price.
- `pay_link`: bled.net purchase URL for full ownership.
- `pay_target`: card-payment target page on `idz.si`.
- `video_url`: public route/preview MP4.
- `srt_url`: raw route telemetry SRT for app parsing only.

Resolve relative URLs against `https://bled.net`.

## Protected Guide API

Use the guide API for app-ready tour variants, language choices, voice choices,
and protected media manifests.

Public catalog:

`https://bled.net/api/guido-guide.php?mode=catalog`

The catalog returns:

- stable `guide_id`
- `tour_slug`
- route `variants`
- selectable `audio_streams` with `audio_id`, `language`, `voice_id`, and
  `guide_persona`

The catalog deliberately does not return protected audio/media URLs.

Protected manifest:

`https://bled.net/api/guido-guide.php?mode=manifest&guide_id=<guide_id>&variant_id=<variant_id>&audio_id=<audio_id>&request_ref=<request_ref>&email=<email>`

The manifest endpoint requires a paid `tour_purchases` row matching
`request_ref`, `email`, and the guide's `tour_slug`. It returns `403` when no
paid access is found. Paid statuses currently accepted by the API are:

- `paid`
- `completed`
- `captured`
- `authorized`
- `settled`

Do not build the app from public `/data/tours.json` alone for unlockable guide
content. Use `/data/tours.json` for shop/catalog display, then use
`/api/guido-guide.php` for app playback.

Current guide IDs:

- Island: `gd_isl_20260530_8f3c1a`
- Castle: `gd_cas_20260530_5b9e2d`
- Vintgar: `gd_vin_20260530_d61b90`

Island variants already prepared include Mlino pletna, Mlino rowing boat,
Camping Zaka rowing boat, Toplice pletna, Kurpark pletna, and Grajska boat.

## Published Media

Guido route media is currently published outside this directory under:

`https://bled.net/uploads/virtual-tour/`

Current route assets:

- `guido-route-1232-480p.mp4`
- `guido-route-1232.srt`
- `guido-route-1234-480p.mp4`
- `guido-route-1234.srt`

The SRT files are telemetry data for app code. Do not expose them as
customer-facing download links.

## Payment Flow

Public purchase flow starts on bled.net:

`/pay/?type=tour&tour=<slug>&amount=<amount>&product=<ownership|day-pass>&target=<payGTI.html|payGTC.html|payGTV.html>`

The bled.net payment page creates a purchase record through:

`/api/tour-purchase.php`

Then card payments post to:

`https://idz.si/bn/paymentEntry.php`

Allowed Guido card targets on `idz.si`:

- `payGTI.html`
- `payGTC.html`
- `payGTV.html`

## Admin / Backoffice

Tour descriptions, prices, pay targets, and video URLs are edited at:

`https://bled.net/menace/`

The admin API is:

`https://bled.net/api/tour-admin.php`

Do not hard-code tour content inside the Guido app if it can be read from
`/data/tours.json`.

## Customer UX Rules

- Customers should see clear actions such as `Start Tour`, `Buy Full Ownership`,
  and `Buy 1-Day Pass`.
- Do not show implementation details such as SRT telemetry links.
- On mobile, the expected flow is: open bled.net/Guido, choose or continue the
  selected tour, and start the guided experience.

## If Unsure

Before changing this directory, inspect existing files and make a backup of any
file you would replace. The safest default is to add new versioned files or
build artifacts, then switch the entry point deliberately.