The complete plan so no room sits empty

🏨 The system that comes out of the plan

Room types and numbered rooms, per-night availability (check-in inclusive, check-out exclusive) with no overbooking, minimum stay, closures and blocks. Seasonal rates with a low-season package (for example, 3 nights pay 2) and a direct-booking discount. Python 3 with only the standard library and SQLite, one inn per installation.

📦 The kit

A 20-section specification, 98 black-box tests, 17 decisions already proposed, a map to Raio-X, prompts for /goal and for the headless loop, and the guardrails that freeze the contract. An adversarial validator already went through everything and fixed 13 problems, 3 of which would have blocked the run.

📈 The rules of Raio-X de Margem

A guest who books direct pays no OTA commission, and the low season gets its own price and package. The system returns receita_ota, retorno_atual_pct, ocupacao_baixa_pct and other figures for the Raio-X de Margem panel, which is the source of the business rules.

Guest

Through chat or WhatsApp the guest checks availability and price, books, views and cancels their own booking according to the policy (free until 7 days before, in the example), gets answers from the FAQ, asks for a human agent and sends "PARAR" (stop) when they want no more messages.

Staff on Telegram

Notices of new and cancelled bookings, and the commands /chegadas (arrivals), /ocupacao (occupancy), /fila (queue), /responder (reply) and /encerrar (close), also as a direct reply to the guest's message.

The /equipe page

With a token: the day's arrivals and departures, the month's occupancy map, check-in, check-out and no-show, deposit paid, records for types, rooms, seasons and FAQ, blocks and the human queue.

Rates and seasons

Base rate per type, seasons (high, low, holiday) with a price per night, extra guest, low-season package and an own-channel discount (direct or front desk), never for the OTA. The deposit is a written policy, marked as paid by the staff. Cents rounded half up.

iCal with Booking and Airbnb

Export per type and per room, to block the dates on the OTAs. Import of the .ics downloaded from the OTA, sent as a file: it becomes a booking with source booking or airbnb. No external URL is fetched in v1.

Stay cycle

A reminder with pre-check-in a few days ahead, check-in and check-out by the staff, no-show, a post-stay message inviting the guest to book direct (only with consent) and a waitlist for full dates.

Python 3.10+ and pytest

The tests use pytest (a development tool). The application itself will have no dependencies.

# check
python3 --version
python3 -m pip install pytest

Claude Code or Codex

Through the subscription, no paid API. For the headless loop, clone execucao-longa into ~/projetos.

# check
codex --version   # or: claude --version

Docker, Evolution and Telegram

Docker does the final build and the VPS deploy. An Evolution instance and a Telegram bot only if you want the channels; the credentials live in .env.

# check
docker --version

98 acceptance tests

Black-box, over HTTP and the command line, in 10 files.

test_inventario.py            17
test_integracoes.py           16
test_conversa.py              14
test_ciclo.py                 11
test_tarifas.py               10
test_cadastros.py              9
test_ical.py                   7
test_basico.py                 6
test_docker.py                 4
test_lgpd_raiox.py             4

A 20-section specification

docs/ESPECIFICACAO.md: execution, pousada.json, nights and availability, rate calculation, authentication, HTTP API, conversation, waitlist, stay cycle, cancellation, iCal, export to Raio-X, privacy law (LGPD), what stays out of v1, pages, records, database, Evolution, Telegram and Docker. Payment (Pix and cards), iCal sync by URL, selling extras, dynamic pricing and multiple inns are explicitly out.

Guardrails against shortcuts

A frozen hash of tests/, pytest.ini, the specification and the two verifiers. File scope: the agent only touches the code and its own records. No external dependency, no API key, no external URL and no 0.0.0.0 in the code. verificar-limites.sh checks all of this and prints LIMITES OK.

Independent verification

Level 4, hidden from the agent: it looks for fixture values in the code, brings up an inn nobody has seen, with every argument explicit, and runs docker build and a container healthcheck. Only then does "98 passed" prove general logic.

17 decisions already proposed

Language, channels, the direct-booking discount and Booking parity, per-type inventory, OTAs through iCal only, deposit and cancellation, rates, the stay cycle, what goes to Raio-X, one inn per installation and PT only in v1. Only the items marked ⚠ change the contract.

Validated by an adversarial agent

A validator that never saw the planning checked tests against the specification, redid 70 calculations and tried to get around the guardrails. It found and fixed 13 problems, 3 of which would have blocked the run. The full account is in docs/VALIDACAO.md.

The business rules come from Raio-X

Direct booking versus OTA commission, a low season with a package, and the guest who comes back: docs/MAPA-RAIO-X.md ties each leak of the hotel pack to a piece of v1 or to the reason it stays out. Details in the Raio-X de Margem guide.

Built-in rules are Brazilian

LGPD (Brazil's privacy law: the reminder as contract performance, the post-stay message only with consent, export and anonymize) and the care around price parity in Booking's contract in Brazil: no public page shows a price, and the direct discount only appears in the 1:1 conversation. The inn's owner validates this point. Outside Brazil, adapt them to local law.