# 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`.

## 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.