PLAN.md:24:- TVs runtime now exposes on-screen diagnostics for cache/object-URL/manual parity verification on real devices.
PLAN.md:32:- That admin QR surface is now positioned as a provider test/debug harness; production vending-machine payments should integrate through the TCN machine protocol and let the machine render the buyer-facing QR.
PLAN.md:33:- Repo docs now include `docs/vending-machine-setup-day-manual.md`, a Ballbox-owned setup-day runbook for first TCN machine arrival covering receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
PLAN.md:34:- Club revenue share is currently handled with scheduled manual settlements/bookkeeping; Mercado Pago native split stays deferred until the machine flow and club count justify it.
PLAN.md:36:- `/admin/payments` now exposes Ballbox-local CRUD/reconciliation for approved payment sessions plus correlation checks against canonical `payment-vm_{vendingMachineId}-txn_{machineTxnId}` references.
PLAN.md:38:- Network core now has DB-backed admin CRUD for ATC-linked clubs, venues, and vending machines inside Ballbox.
PLAN.md:44:- Network vending-machine route callers now import `lib/network-backend-vending-machines.ts` directly and read unique-constraint classification from `lib/prisma-errors.ts`.
PLAN.md:46:- Network route handlers now share `lib/http/network-route-helpers.ts` for JSON parsing plus success/error envelopes across club, venue, and vending-machine contract routes.
PLAN.md:57:- Post-`pnpm db:push` plus `pnpm db:seed` verification confirms physical DB columns stay canonical as `vendingMachineId` and `tvDeviceId`, with no `machineId`, `deviceId`, `/devices`, or `PaymentSessionRef` persistence aliases reintroduced.
PLAN.md:86:- `/clubs/coaches` now lands on a club workspace with top-level `Calendar`, `Analytics`, `Sedes`, and `Profesores` sections: calendar shows the current week's coach availability and reservations with sede/coach/court filters plus in-place manual class loading, analytics shows professor/reservation money splits and review placeholders, `Sedes` groups venue creation plus venue quick settings, and `Profesores` groups invite links plus the club coach table.
PLAN.md:88:- `/clubs/coaches` now lands on a club workspace with top-level `Calendar`, `Analytics`, `Sedes`, and `Profesores` sections: calendar now works one sede at a time, switches between `Disponibilidad` and `Reservas`, uses clickable tag filters for sede/day/club-owned coaches instead of dropdowns, assigns a persistent color to each coach-enabled court, and shows the selected day with all coach-enabled courts as columns so clubs can see coverage or reservation gaps per court without selecting a court filter; coaches assigned with `Asignar todas las canchas` are treated as flexible coverage and occupy one free court per half-hour, not every court at once; manual class loading and pending requests open from dedicated action buttons above the calendar, and manual class creation now requires selecting an active coach package so clubs cannot create classes for coaches without packages; analytics shows professor/reservation money splits and review placeholders, `Sedes` now starts from a large `Agregar sede` CTA, keeps venue creation behind that action, and lists every venue in an editable table with a deep edit action, and `Profesores` groups invite links plus the club coach table.
PLAN.md:94:- `/api/clubs/players` now lets a club create its own students and auto-membership them into that club before assigning them to a professor from the club workspace manual class flow.
PLAN.md:120:- `/admin/network`: clubs, venues, vending machines
PLAN.md:133:- coach workspace now also includes student follow-up and manually occupied-hour management using existing `Player` records, including coach-editable WhatsApp and Telegram contact data
PLAN.md:207:  - no manual real-device verification yet proves CacheStorage/object-URL playback outside local browser automation
PLAN.md:215:- Club revenue share is currently handled with scheduled manual settlements; `PAY-4` stays behind the TCN machine-facing adapter work as a future Mercado Pago split option.
PLAN.md:219:1. Finish provider-level Mercado Pago proof without TCN hardware.
PLAN.md:222:2. Ask TCN sales to confirm the remaining machine-contract questions with their engineers.
PLAN.md:225:3. Freeze the Ballbox <-> TCN adapter contract once those answers come back.
PLAN.md:235:6. Keep club settlements informal/manual for Ballbox-collected machines until the machine path is stable and settlement pain is real.
PLAN.md:245:- TCN direction and target flow: `docs/tcn-payments-integration-plan.md`
PLAN.md:250:- TCN protocol evidence artifact: `test-results/tcn-payment-protocol/findings-2026-04-23.md`
PLAN.md:300:- TVs runtime must support local cached playback for video creatives instead of relying only on remote streaming.
PLAN.md:302:- Production vending-machine payments should target a TCN adapter over that native MercadoPago layer; see `docs/tcn-payments-integration-plan.md`.
PLAN.md:316:  - vendingMachines: 4
README.md:130:- Callback inbound endurecido con bearer shared secret + validación de `payment:{vendingMachineId}:{machineTxnId}`
README.md:131:- Mapping `vendingMachine/slot/club/venue` pendiente
README.md:133:- Falta validación manual end-to-end con configuración real de MercadoPago y webhook público
README.md:137:- CRUD administrativo para clubs, venues y vending machines
docs/domain-model-target.md:23:  - optional: `vendingMachineId`
docs/domain-model-target.md:35:  - required: `vendingMachineId`
docs/coaches-jtbd-workflow-map.md:19:- I want to: keep classes coordinated without constant manual follow-up and chaos
docs/coaches-jtbd-workflow-map.md:29:2. Step 2: coordinate timing and logistics manually
docs/coaches-jtbd-workflow-map.md:39:- Notes/manual work: likely common
docs/coaches-jtbd-workflow-map.md:43:- Friction 1: too much manual coordination across people and tools
docs/coaches-jtbd-workflow-map.md:56:- Workaround 2: calendar/sheet tracking plus memory/manual notes
docs/tcn-payments-open-questions.md:1:# TCN payments open questions
docs/tcn-payments-open-questions.md:4:Close the remaining machine-integration unknowns before Ballbox implements the full TCN adapter.
docs/tcn-payments-open-questions.md:6:## Questions for TCN sales / engineering
docs/tcn-payments-open-questions.md:14:   - machine polls another TCN endpoint
docs/tcn-payments-open-questions.md:24:6. Does the stock TCN app render the QR natively after a successful `8000` response, or is any machine-side UI configuration required?
docs/tcn-payments-open-questions.md:31:1. Which returned value from Ballbox should be safest to map into TCN `CodeUrl` for dynamic QR display?
docs/vending-machine-setup-day-manual.md:1:# Vending machine setup day manual
docs/vending-machine-setup-day-manual.md:4:- One Ballbox-owned setup manual for arrival day.
docs/vending-machine-setup-day-manual.md:6:- Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.
docs/vending-machine-setup-day-manual.md:8:## Inputs saved for this manual
docs/vending-machine-setup-day-manual.md:10:- Video reference: `https://www.youtube.com/watch?v=Qwbp3muM7gA` (`How to upload videos to the vending machine`)
docs/vending-machine-setup-day-manual.md:11:- Test cloud: `https://dnymer.ourvend.com/#/login`
docs/vending-machine-setup-day-manual.md:18:- Ask TCN/supplier for exact package matched to serial number, mainboard revision, screen family, and payment-module BOM.
docs/vending-machine-setup-day-manual.md:25:- Have Ethernet available on-site.
docs/vending-machine-setup-day-manual.md:73:   - escalate to TCN for exact touch/display package if still broken
docs/vending-machine-setup-day-manual.md:77:- URL: `https://dnymer.ourvend.com/#/login`
docs/vending-machine-setup-day-manual.md:99:8. Push one safe remote change:
docs/vending-machine-setup-day-manual.md:103:## Media upload to the vending machine
docs/vending-machine-setup-day-manual.md:104:Source: public video `How to upload videos to the vending machine`.
docs/vending-machine-setup-day-manual.md:126:- whether manual sync/reboot is needed after publish
docs/vending-machine-setup-day-manual.md:131:- Production vending flow should go through TCN machine protocol.
docs/vending-machine-setup-day-manual.md:136:- Current research still supports OurVend/TCN as cloud + device-control layer, not the owner of Ballbox business logic.
docs/vending-machine-setup-day-manual.md:141:### What still needs real-world confirmation on setup day
docs/vending-machine-setup-day-manual.md:156:8. Confirm TCN side receives success/notify signal.
docs/vending-machine-setup-day-manual.md:172:## Escalation packet for supplier / TCN
docs/implemented-payments.md:9:- The admin QR generator should now be treated as an operator test/debug harness for Mercado Pago and webhook validation, not as the final buyer-facing vending-machine payment UX.
docs/implemented-payments.md:26:- Post-`pnpm db:push` plus `pnpm db:seed` verification confirms Ballbox Postgres keeps canonical `PaymentSession.vendingMachineId` and does not expose a `PaymentSessionRef` table or `machineId` compatibility column.
docs/implemented-payments.md:38:- Native payment correlation requires canonical `externalReference` values shaped as `payment-vm_{vendingMachineId}-txn_{machineTxnId}`.
docs/implemented-payments.md:43:- Remaining gap is operational/manual: one real public webhook + one real approved payment persisted and visible in `/admin/payments`.
docs/implemented-payments.md:44:- Club revenue share is currently handled through scheduled manual settlements/bookkeeping for Ballbox-collected machines; no provider-native split payout path is live.
docs/implemented-payments.md:46:- The admin surface includes a live QR generator preview for provider-level scan-and-pay validation, but production vending flow should move behind the TCN machine protocol instead of relying on that admin page.
docs/implemented-payments.md:48:- TCN protocol review indicates the `additional hardware devices` warning applies to machine-side QR scanning, while the payment flow (`FunCode=8000`) returns `CodeUrl` for machine-screen QR display; see `docs/tcn-payments-integration-plan.md` and `test-results/tcn-payment-protocol/findings-2026-04-23.md`.
docs/implemented-payments.md:58:- Acceptance for the manual check:
docs/implemented-tvs.md:48:- Stock demo seed scheduling now keeps `screen_001` and `screen_002` on active campaign windows after `pnpm db:seed`, so local parity/e2e runs no longer depend on manually refreshing fixture dates first.
docs/implemented-tvs.md:65:- Post-`pnpm db:push` plus `pnpm db:seed` verification confirms Ballbox Postgres keeps canonical `Screen.vendingMachineId` and `Impression.tvDeviceId`, with no legacy `deviceId` column reintroduced.
docs/tcn-payments-execution-plan.md:1:# TCN payments execution plan
docs/tcn-payments-execution-plan.md:4:Ordered execution plan for getting from current Ballbox native Mercado Pago support to real TCN machine payments.
docs/tcn-payments-execution-plan.md:7:- Goal: prove Ballbox native Mercado Pago flow works end to end without TCN hardware.
docs/tcn-payments-execution-plan.md:19:## Step 2. Ask TCN the machine-contract questions
docs/tcn-payments-execution-plan.md:26:  - send the question list to the TCN sales contact
docs/tcn-payments-execution-plan.md:32:## Step 3. Freeze Ballbox-TCN contract
docs/tcn-payments-execution-plan.md:38:  - define request/response schema for TCN `8000`
docs/tcn-payments-execution-plan.md:46:- Goal: add the TCN-facing Ballbox endpoints over existing Mercado Pago primitives.
docs/tcn-payments-execution-plan.md:51:  - map TCN requests to Ballbox/Mercado Pago order creation
docs/tcn-payments-execution-plan.md:52:  - map approved-payment state back into TCN success flow
docs/tcn-payments-execution-plan.md:55:  - local/manual adapter flow works without real machine hardware
docs/tcn-payments-execution-plan.md:58:- Goal: verify actual stock TCN machine behavior.
docs/tcn-payments-execution-plan.md:69:  - scheduled manual settlements / bookkeeping
docs/coaches-opportunity-brief.md:24:- Main pain: coordinating recurring classes creates manual admin overhead, missed communications, and avoidable schedule friction
docs/coaches-opportunity-brief.md:25:- Current workaround: WhatsApp, spreadsheets, calendar tools, manual follow-up, club coordination by message or phone
docs/coaches-opportunity-brief.md:54:- Desired outcome: keep classes organized with less manual back-and-forth and fewer avoidable failures
docs/coaches-opportunity-brief.md:71:  - users describe manual workarounds and costly failures
docs/implemented-sports.md:14:- `/coaches/settings` now opens on a coach workspace split into `Calendar`, `Performance`, `Alumnos`, and `Horarios y Clases`: calendar shows the current week in an hour-by-hour class matrix, groups simultaneous reservations into one individual or group class, surfaces each student's basic profile data (name, sexo, edad, categoria), marks which reservations are paid vs pending, and starts with a large `Agregar clase` CTA that takes the coach into `Alumnos`; `Performance` shows club-level results plus weekly earnings and student consistency rows, while `Horarios y Clases` auto-saves club selection, availability, packages, and Mercado Pago setup without manual save buttons and no longer shows the club's court-fee pricing to the coach. Pending autosave writes are also flushed if the coach leaves the page before the debounce finishes.
docs/implemented-sports.md:17:- `/clubs/coaches` now opens on a club workspace with top-level `Calendar`, `Analytics`, `Sedes`, and `Profesores` sections: calendar shows the current week's coach availability/reservations with sede/coach/court filters plus quick manual class loading, analytics shows professor/reservation money splits, `Sedes` handles venue creation and quick venue reservation settings, and `Profesores` handles invite links plus the club coach table.
docs/implemented-sports.md:19:- `/clubs/coaches` now opens on a club workspace with top-level `Calendar`, `Analytics`, `Sedes`, and `Profesores` sections: calendar now focuses on one sede at a time, switches between `Disponibilidad` and `Reservas`, uses clickable sede/day/club-coach tags instead of dropdowns, assigns each coach-enabled court its own color, and shows the selected day with all coach-enabled courts as columns so clubs can see half-hour gaps per court without selecting a court filter; coaches assigned with `Asignar todas las canchas` are treated as flexible coverage and occupy one free court per half-hour, not every court at once; quick manual class loading and pending requests open from dedicated action buttons above the calendar, and manual class creation now requires selecting an active coach package while still allowing inline student creation and weekly repeats; analytics shows professor/reservation money splits, `Sedes` now starts with a large `Agregar sede` action, keeps the creation form behind that CTA, and lists all venues in a simpler table with a deep-link into full venue editing, and `Profesores` handles invite links plus the club coach table.
docs/implemented-sports.md:72:- `/api/clubs/manual-classes`
docs/implemented-host-app.md:23:- Native payment persistence validates canonical `payment-vm_{vendingMachineId}-txn_{machineTxnId}` references before writing local approved sessions.
docs/implemented-host-app.md:30:- Local development now also ships with a tracked Docker Postgres setup plus `.env.local` defaults, so Ballbox can run against `ballbox_local` without depending on the remote database.
docs/implemented-host-app.md:39:- Network now has DB-backed admin CRUD for ATC-linked clubs, venues, and vending machines.
docs/index.md:14:- `docs/vending-machine-setup-day-manual.md`: operator setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness
docs/index.md:49:- `docs/vending-machine-setup-day-manual.md`
docs/classes-mvp-rfc.md:13:- The real problem is not that coaches reserve courts manually in chat.
docs/next-steps-queue.md:74:- Progress (2026-04-23): TCN protocol review shows the `additional hardware devices` note is about machine-side QR scanning, while the machine payment flow (`FunCode=8000`) already returns `CodeUrl` for machine-screen QR display. This means the admin QR page should be treated as a provider test harness, and production integration should move to a TCN adapter layer.
docs/next-steps-queue.md:82:  - manually verify real-device CacheStorage/object-URL behavior on `/player/[screenId]`
docs/next-steps-queue.md:158:### PAY-3 TCN vending-machine adapter over native MercadoPago
docs/next-steps-queue.md:163:  - define the Ballbox machine-facing adapter for TCN payment init (`FunCode=8000`) over the existing MercadoPago order-create route
docs/next-steps-queue.md:164:  - map TCN `MachineID`, `TradeNo`, `SlotNo`, `Price`, `NotityUrl`, and response `CodeUrl` to Ballbox-native payment fields
docs/next-steps-queue.md:165:  - define the payment-success handshake back to TCN so approved payments can unlock dispense
docs/next-steps-queue.md:169:  - keep `/admin/payments` positioned as an operator test/debug harness rather than the production vending UX
docs/next-steps-queue.md:170:  - document the exact adapter contract and remaining TCN unknowns before implementation
docs/next-steps-queue.md:172:  - TCN protocol evidence is documented in `docs/tcn-payments-integration-plan.md`
docs/next-steps-queue.md:176:  - club settlement automation can be revisited after the machine-facing flow is stable; manual bookkeeping is the current default
docs/next-steps-queue.md:186:  - keep scheduled manual settlements as the current operating default for Ballbox-collected club machines
docs/next-steps-queue.md:189:  - capture the trigger conditions that justify leaving manual bookkeeping behind
docs/next-steps-queue.md:191:  - Ballbox currently runs QR vending payments through the native Mercado Pago order/webhook flow, so split automation is a separate future decision
docs/next-steps-queue.md:193:  - keep this behind real-world payments validation first (`OPS-1`) and machine-facing TCN adapter definition (`PAY-3`)
docs/next-steps-queue.md:194:- Expected payoff: a clear path from manual settlements to a future Mercado Pago split if the machine flow and business volume justify it
docs/payments-machine-rollout-rfc.md:4:- Proposed operating plan for the first vending rollout.
docs/payments-machine-rollout-rfc.md:5:- Use this as the master document for payment ownership modes, TCN integration, onboarding, and rollout sequencing.
docs/payments-machine-rollout-rfc.md:8:- Use one Ballbox-controlled technical flow for all vending machines.
docs/payments-machine-rollout-rfc.md:15:- For `BALLBOX` collection, club revenue share is handled by informal/manual settlement at first.
docs/payments-machine-rollout-rfc.md:21:- TCN machine integration and Mercado Pago webhook persistence are still the highest-risk technical pieces.
docs/payments-machine-rollout-rfc.md:29:- TCN machine payment adapter
docs/payments-machine-rollout-rfc.md:35:- manual settlement guidance for Ballbox-collected club machines
docs/payments-machine-rollout-rfc.md:55:6. Ballbox later settles the club share manually
docs/payments-machine-rollout-rfc.md:60:- informal manual settlement is enough at this stage
docs/payments-machine-rollout-rfc.md:80:- unified TCN adapter behavior
docs/payments-machine-rollout-rfc.md:99:- vending machine identity
docs/payments-machine-rollout-rfc.md:111:- provider order / external reference -> vending machine -> payment owner mode -> MP config
docs/payments-machine-rollout-rfc.md:113:## TCN integration direction
docs/payments-machine-rollout-rfc.md:114:- TCN remains the machine-facing protocol.
docs/payments-machine-rollout-rfc.md:116:- Ballbox should implement the TCN payment adapter over the native Mercado Pago provider layer.
docs/payments-machine-rollout-rfc.md:137:### Phase 1. TCN contract closure
docs/payments-machine-rollout-rfc.md:139:- confirm TCN `CodeUrl` and approval/dispense handshake details with sales/engineering
docs/payments-machine-rollout-rfc.md:154:- machine-facing TCN adapter over provider layer
docs/payments-machine-rollout-rfc.md:172:- lightweight manual ledger/export/notes process
docs/payments-machine-rollout-rfc.md:188:3. map machine identifier between TCN and Ballbox
docs/payments-machine-rollout-rfc.md:219:- TCN approval/dispense handshake still needs confirmation
docs/payments-machine-rollout-rfc.md:225:- manual club settlements can become messy if volume rises fast
docs/payments-machine-rollout-rfc.md:237:- TCN machine-facing contract is documented and implemented without guessing
docs/atc-integration-discovery.md:83:- To actually hit ATC endpoints and inspect live/beta data, Ballbox will need valid credentials and likely some manual setup from ATC.
docs/ballbox-db-plan.md:55:4. Payments now persist canonical `vendingMachineId` and `productId` foreign keys.
docs/ballbox-db-plan.md:56:5. Post-`pnpm db:push` plus `pnpm db:seed` verification against Ballbox Postgres confirms physical tables still expose canonical `Screen.vendingMachineId`, `Impression.tvDeviceId`, and `PaymentSession.vendingMachineId`.
docs/implemented-network.md:5:- Ballbox owns the canonical shared `network` model for venues, vending machines, screens, and tv devices; clubs are now ATC-sourced via `atcSportclubId` and hydrated at runtime.
docs/implemented-network.md:7:- Current network CRUD covers clubs, venues, and vending machines.
docs/implemented-network.md:14:- Vending-machine route handlers now call `lib/network-backend-vending-machines.ts` directly and use `lib/prisma-errors.ts` for unique-constraint classification.
docs/tcn-payments-integration-plan.md:1:# TCN payments integration plan
docs/tcn-payments-integration-plan.md:4:- Treat the current `/admin/payments` QR generator as an operator test harness, not the final production payment UX for vending machines.
docs/tcn-payments-integration-plan.md:5:- Production vending flow should integrate with the TCN machine protocol and let the machine render the buyer-facing QR on its own screen.
docs/tcn-payments-integration-plan.md:8:- TCN protocol `2.5V` states: `to scan QR codes additional hardware devices are necessary.`
docs/tcn-payments-integration-plan.md:17:1. Buyer selects product on TCN machine.
docs/tcn-payments-integration-plan.md:18:2. TCN machine requests Ballbox payment session using the TCN payment contract.
docs/tcn-payments-integration-plan.md:20:4. Ballbox maps the Mercado Pago output into the TCN response shape and returns `CodeUrl`.
docs/tcn-payments-integration-plan.md:21:5. TCN machine renders the QR on its screen.
docs/tcn-payments-integration-plan.md:25:9. TCN machine receives the success signal through the TCN-side notify/result path and dispenses product.
docs/tcn-payments-integration-plan.md:29:- Define a Ballbox route for TCN `8000` payment-init requests.
docs/tcn-payments-integration-plan.md:31:  - `MachineID` -> Ballbox `vendingMachineId` or external machine identifier
docs/tcn-payments-integration-plan.md:37:- Confirm whether TCN expects raw payment URL, QR payload string, or a specific provider deep link in `CodeUrl`.
docs/tcn-payments-integration-plan.md:40:- Map how Ballbox should signal payment success back into the TCN flow.
docs/tcn-payments-integration-plan.md:41:- Verify whether Ballbox must call `NotityUrl`, expose a callback endpoint, or rely on a polling/result interface in the broader TCN protocol set.
docs/tcn-payments-integration-plan.md:42:- Confirm how TCN links approved payment to dispense using `TradeNo` and/or `SlotNo`.
docs/tcn-payments-integration-plan.md:45:- Decide the canonical mapping between TCN `MachineID` and Ballbox `VendingMachine`.
docs/tcn-payments-integration-plan.md:53:  - manual provider debugging
docs/tcn-payments-integration-plan.md:54:- Do not frame it as the final vending-machine payment UX.
docs/tcn-payments-integration-plan.md:57:- Exact payload expected inside TCN `CodeUrl`.
docs/tcn-payments-integration-plan.md:58:- Exact success callback / notify shape between Ballbox and TCN after payment approval.
docs/tcn-payments-integration-plan.md:60:- Whether TCN needs additional payment-status endpoints beyond `8000` for a full dispense flow.
docs/tcn-payments-integration-plan.md:63:- Next implementation slice should be a TCN adapter spec + stub endpoints, not more work on the standalone admin QR page.
docs/coaches-solution-thesis.md:12:- If Ballbox helps a coach or coordinator handle a recurring class workflow with less manual coordination and fewer failures, then Ballbox can become the operational layer above scheduling, classes, and later availability-aware automation.
docs/coaches-solution-thesis.md:58:- Job: find a viable option and submit a class request without messaging the coach manually
docs/payments-club-settlement-strategy.md:4:- Use scheduled settlements and manual bookkeeping for now.
docs/payments-club-settlement-strategy.md:5:- Do not force Mercado Pago split payments into the current vending QR flow.
docs/payments-club-settlement-strategy.md:15:- Each vending machine belongs to one club/venue or tenant contract.
docs/payments-club-settlement-strategy.md:17:  - `BALLBOX`: Ballbox collects and later settles the club share manually.
docs/payments-club-settlement-strategy.md:24:- For the current pilot phase, manual bookkeeping is acceptable because we expect at most 5 machines in the first wave.
docs/payments-club-settlement-strategy.md:32:- vendingMachineId
docs/payments-club-settlement-strategy.md:50:- never let manual edits overwrite raw sales totals
docs/payments-club-settlement-strategy.md:59:- less manual payout work
docs/payments-club-settlement-strategy.md:63:- current QR vending flow does not map cleanly
docs/payments-club-settlement-strategy.md:74:- manual settlement becomes error-prone
docs/payments-club-settlement-strategy.md:80:- Keep manual scheduled settlements now for `BALLBOX` machines.
docs/streetcast-parity.md:26:- Stock seed data now provides active TV programming for `screen_001` after `pnpm db:seed`, so local cached-blob playback, first impression write, queued-impression recovery, and manifest-refresh-failure continuity can be validated without manual TV fixture repair first.
docs/coach-availability-rfc.md:63:- Default selection is all clubs (opt-out to a manual list).
docs/coach-availability-rfc.md:196:- Current UI opens on a dashboard with per-club metrics plus a strip of days with booked classes, then shows affiliation, assigned sede when present, editable weekly availability inside allowed venue/club hours, reusable sales packages, and a Mercado Pago placeholder field inside `Mi Perfil`. A third `Alumnos` section now handles the student roster, contacts, and manually occupied slots.
docs/payments-machine-implementation-rfc.md:9:- serves TCN machines
docs/payments-machine-implementation-rfc.md:33:- machine-facing TCN adapter does not exist yet
docs/payments-machine-implementation-rfc.md:82:- temporary in-code or env-backed mapping by `vendingMachineId`
docs/payments-machine-implementation-rfc.md:89:- `payment-vm_{vendingMachineId}-txn_{machineTxnId}`
docs/payments-machine-implementation-rfc.md:95:- `vendingMachineId`
docs/payments-machine-implementation-rfc.md:116:- `vendingMachineId`
docs/payments-machine-implementation-rfc.md:156:- return Ballbox-normalized result for either admin or TCN routes
docs/payments-machine-implementation-rfc.md:161:  vendingMachineId,
docs/payments-machine-implementation-rfc.md:168:resolvePaymentOwnerForMachine(vendingMachineId)
docs/payments-machine-implementation-rfc.md:173:## 7. TCN route should sit on top of the machine-payment service
docs/payments-machine-implementation-rfc.md:175:- do not embed MP logic directly in TCN route handlers
docs/payments-machine-implementation-rfc.md:176:- TCN route should translate between TCN contract and Ballbox machine-payment service only
docs/payments-machine-implementation-rfc.md:182:- parse TCN request
docs/payments-machine-implementation-rfc.md:185:- return TCN response shape including `CodeUrl`
docs/payments-machine-implementation-rfc.md:193:- TCN adapter becomes the real machine entrypoint
docs/payments-machine-implementation-rfc.md:208:- machine owner config stored in a local mapping module keyed by `vendingMachineId`
docs/payments-machine-implementation-rfc.md:227:2. derive `vendingMachineId`
docs/payments-machine-implementation-rfc.md:257:Add TCN adapter route using the same service.
docs/payments-machine-implementation-rfc.md:266:- TCN init route returns expected TCN response shape
docs/payments-machine-implementation-rfc.md:281:- exact TCN `CodeUrl` payload expectation
docs/payments-machine-implementation-rfc.md:282:- exact TCN payment-success / dispense handshake
docs/coaches-wedges-matrix.md:12:| Reprogramming | Last-minute changes create manual chaos | Save time and preserve revenue | Medium to high | Medium | High | Pain may be episodic, not constant |
docs/coaches-interview-script.md:52:- Workaround is manual and annoying.


docs/atc-access-request-checklist.md
docs/atc-integration-discovery.md
docs/atc-integration-spec-skeleton.md
docs/atc-mock-integration-plan.md
docs/ballbox-db-plan.md
docs/classes-implementation-notes.md
docs/classes-mvp-rfc.md
docs/classes-subroute-plan.md
docs/coach-availability-rfc.md
docs/coaches-coordination-gap-analysis.md
docs/coaches-design-partner-outreach.md
docs/coaches-discovery-execution-plan.md
docs/coaches-discovery-stage.md
docs/coaches-form-current.md
docs/coaches-icp-segmentation.md
docs/coaches-interview-script.md
docs/coaches-jtbd-workflow-map.md
docs/coaches-opportunity-brief.md
docs/coaches-research-repository.md
docs/coaches-solution-thesis.md
docs/coaches-validation-checklist-2-weeks.md
docs/coaches-wedges-matrix.md
docs/demo-iteration-mode.md
docs/domain-model-target.md
docs/implemented-host-app.md
docs/implemented-network.md
docs/implemented-payments.md
docs/implemented-players.md
docs/implemented-sports.md
docs/implemented-tvs.md
docs/index.md
docs/maintainability-priorities-2026-03.md
docs/mercadopago-webhook-replay-notes-2026-04-23.md
docs/next-steps-queue.md
docs/payments-club-settlement-strategy.md
docs/payments-machine-implementation-rfc.md
docs/payments-machine-rollout-rfc.md
docs/repo-map.md
docs/screen-runtime-delivery-investigation.md
docs/streetcast-parity.md
docs/tcn-payments-execution-plan.md
docs/tcn-payments-integration-plan.md
docs/tcn-payments-open-questions.md
docs/vending-machine-setup-day-manual.md


**Exploring document sources**

I need to consider that I might be missing relevant documents due to naming issues. Maybe they're located remotely or in the Downloads folder? I'll search a wider range in the repository instead of focusing on just the docs. There's a chance that looking beyond the usual parameters could lead me to the right documents. It's all about broadening my search to ensure I find what I need!

bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && find . -maxdepth 3 -type f | rg "setup|manual|runbook|remote|onsite|on-site|vending|ourvend|operator" | sed -n '1,260p'

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && rg -n "remoto|fisico|físico|remote|on-site|onsite|site lead|operator|setup" . | sed -n '1,260p'


./docs/vending-machine-setup-day-manual.md
./lib/network-backend-vending-machines.ts


./README.md:41:- `DATABASE_URL`: Postgres local de desarrollo o Postgres remoto de Ballbox
./PLAN.md:33:- Repo docs now include `docs/vending-machine-setup-day-manual.md`, a Ballbox-owned setup-day runbook for first TCN machine arrival covering receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
./PLAN.md:84:- `/coaches/settings` now lands on a coach workspace split into `Calendar`, `Performance`, `Alumnos`, and `Horarios y Clases`: calendar shows the current week in an hour-by-hour matrix centered on the coach's real student classes, grouping simultaneous reservations into one class card, surfacing participant basics (name, sexo, edad, categoria), and marking paid vs pending reservations, and now starts with a large `Agregar clase` CTA that jumps into `Alumnos`; `Performance` shows per-club performance plus weekly earnings and student consistency/review rows, `Alumnos` keeps roster + taken-hour management with the student table visible by default and `Agregar clase` opening a wide inline composer instead of a right-side summary panel, and `Horarios y Clases` now auto-saves club selection, availability, packages, and Mercado Pago setup without explicit save buttons while no longer exposing the club's court-fee pricing to the coach; pending autosave writes are now also flushed if the user leaves the page before the debounce finishes.
./PLAN.md:102:- Coaches now also persist a Mercado Pago placeholder handle plus reusable sales-package rows for pricing, duration, class format, and max-student setup.
./PLAN.md:111:- On `ballbox-first`, repo Playwright now uses a stable production-style `webServer` path for e2e (`pnpm build:e2e && pnpm start:e2e` on port `3020`), replacing the unstable Next 16 dev-server setup previously used on this Pi.
./PLAN.md:134:- `/clubs/venues/[venueId]`: dedicated venue setup and venue roster
./PLAN.md:187:- Club accounts now have a dedicated workspace at `/clubs/coaches` split into `Calendar`, `Analytics`, `Sedes`, and `Profesores`, while venue-by-venue deep setup still lives at `/clubs/venues/[venueId]`, all under the same shared navbar/profile chrome.
./PLAN.md:188:- Venue setup now uses two simple fields for opening and closing time plus a collapsible weekly half-hour grid for coach hours, shows closed periods in red while editing coach availability, lets clubs mark whether external coaches are allowed, keeps coach-enabled courts in a dedicated selection panel, and includes reservation pricing/cancellation settings both in the venue detail and as quick settings on `/clubs/coaches`, including a discount that applies only to coaches assigned to that club.
./PLAN.md:254:- Next sports expansion after `/classes/me`: lightweight operator review for incoming requests.
./PLAN.md:300:- TVs runtime must support local cached playback for video creatives instead of relying only on remote streaming.
./public/player-runtime.js:83:        : "remote";
./docs/coaches-discovery-stage.md:34:   - freelance coach vs academy vs club coordinator vs premium clinic operator
./docs/vending-machine-setup-day-manual.md:1:# Vending machine setup day manual
./docs/vending-machine-setup-day-manual.md:4:- One Ballbox-owned setup manual for arrival day.
./docs/vending-machine-setup-day-manual.md:25:- Have Ethernet available on-site.
./docs/vending-machine-setup-day-manual.md:99:8. Push one safe remote change:
./docs/vending-machine-setup-day-manual.md:105:- Treat this section as an operator checklist, not as a verified exact click-path yet.
./docs/vending-machine-setup-day-manual.md:107:Use this as the operator checklist once inside tenant UI:
./docs/vending-machine-setup-day-manual.md:130:- `/admin/payments` stays a Ballbox operator test/debug harness.
./docs/vending-machine-setup-day-manual.md:141:### What still needs real-world confirmation on setup day
./docs/vending-machine-setup-day-manual.md:173:If something blocks setup, send all of this together:
./docs/implemented-payments.md:9:- The admin QR generator should now be treated as an operator test/debug harness for Mercado Pago and webhook validation, not as the final buyer-facing vending-machine payment UX.
./docs/implemented-payments.md:25:- Admin operators can now create, update, and delete local `PaymentSession` rows for reconciliation.
./docs/implemented-payments.md:45:- First rollout planning now assumes one shared technical flow with two payment-owner modes: `BALLBOX` for club machines Ballbox collects on, and `TENANT` for client-owned collection setups such as Adidas rental machines; see `docs/payments-machine-rollout-rfc.md`.
./docs/coaches-research-repository.md:48:| Premium clinic operator |  |  |  |
./docs/screen-runtime-delivery-investigation.md:42:  - shared tooling and test setup
./docs/implemented-tvs.md:46:- Runtime now exposes operator-facing diagnostics for playback source, Cache API support, cached creative count, network state, and manifest refresh status to support real-device parity checks.
./docs/implemented-tvs.md:49:- TVs admin and `/admin/screens` link operators to the lightweight player path.
./lib/platform.ts:54:    summary: "Clubes, venues y vending machines como core fisico compartido de Ballbox.",
./lib/tvs-player-runtime-core.ts:250:          // keep remote fallback when prefetch fails
./docs/classes-mvp-rfc.md:23:  - `/coaches` for operator workflows
./docs/classes-mvp-rfc.md:138:- add lightweight operator review surface
./docs/classes-mvp-rfc.md:139:- expand toward coach/operator workflows under `/coaches`
./docs/maintainability-priorities-2026-03.md:42:  - It weakens the whole payments integration if env setup drifts.
./docs/coaches-icp-segmentation.md:14:| Club sports manager | Internal operator managing classes and occupancy | High | High | Lower as buyer may already have tools | Low | Could prefer club-wide solution over coach tool |
./docs/tcn-payments-integration-plan.md:4:- Treat the current `/admin/payments` QR generator as an operator test harness, not the final production payment UX for vending machines.
./docs/coaches-solution-thesis.md:16:- Keep coach/operator coordination as the strongest adjacent wedge.
./docs/coaches-solution-thesis.md:23:- Ballbox already has admin/operator surfaces that can evolve into operational tooling.
./docs/coaches-solution-thesis.md:30:- It creates a clear path to future coach/operator tooling once student requests exist inside Ballbox.
./docs/coaches-solution-thesis.md:41:2. coach/operator coordination workspace
./docs/coaches-solution-thesis.md:46:- Coach/operator coordination is the natural next internal surface once requests flow into Ballbox.
./docs/coaches-solution-thesis.md:65:  - next: coach/operator workspace under `/coaches`
./docs/atc-integration-discovery.md:83:- To actually hit ATC endpoints and inspect live/beta data, Ballbox will need valid credentials and likely some manual setup from ATC.
./docs/atc-integration-discovery.md:94:- Best next step is to ask ATC for a minimal beta sandbox setup:
./docs/coaches-coordination-gap-analysis.md:103:3. optimize around one weekly operator workflow, not generic form editing
./docs/payments-machine-rollout-rfc.md:24:- Adidas-style rental machines need easy setup more than Ballbox ownership of the funds.
./docs/payments-machine-rollout-rfc.md:42:- long-term tenant MP support beyond guided setup
./docs/payments-machine-rollout-rfc.md:59:- Ballbox controls setup and debugging
./docs/payments-machine-rollout-rfc.md:76:- Ballbox should provide guided setup, not heavy day-to-day support
./docs/payments-machine-rollout-rfc.md:164:- setup checklist followed per machine
./docs/payments-machine-rollout-rfc.md:189:4. confirm product/pricing setup
./docs/payments-machine-rollout-rfc.md:205:- guide them through MP setup only enough to make the machine flow work
./docs/payments-machine-rollout-rfc.md:206:- confirm they configure Ballbox webhook endpoint in their MP account if required by the final provider setup
./docs/payments-machine-rollout-rfc.md:213:- For tenant-collected machines, Ballbox is facilitating setup, not owning their payout operations.
./docs/payments-machine-rollout-rfc.md:224:- guided Adidas setup may still stall on account/POS/webhook details
./docs/coach-availability-rfc.md:16:- `/clubs/venues/[venueId]` now gives each venue a dedicated setup screen with opening/closing time, weekly coach hours, external-coach availability, reservation settings including a club-only discount, courts, and venue-specific coach assignment.
./docs/coach-availability-rfc.md:153:  - now also keeps reusable sales-package rows for its commercial setup
./docs/payments-machine-implementation-rfc.md:192:- `/api/integrations/payments/orders` becomes a Ballbox test/operator entrypoint
./docs/payments-machine-implementation-rfc.md:205:- tenant setup does not need route-local hacks or env naming tricks
./docs/payments-machine-implementation-rfc.md:283:- whether tenant webhook/POS setup needs any special MP product variation
./docs/index.md:14:- `docs/vending-machine-setup-day-manual.md`: operator setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness
./docs/index.md:49:- `docs/vending-machine-setup-day-manual.md`
./docs/classes-subroute-plan.md:10:- Reserve future operator area under `/coaches`
./docs/next-steps-queue.md:85:- Progress (2026-04-19): machine-local Playwright setup is now standardized outside the repo at `/mnt/rpi/repos/browser-harness`; repo Playwright now uses a stable production-style e2e server path on this Pi, and stock TV seed data now keeps `screen_001` actively programmed after `pnpm db:seed`.
./docs/next-steps-queue.md:168:    - `TENANT` for customer-owned collection setups such as Adidas rental machines
./docs/next-steps-queue.md:169:  - keep `/admin/payments` positioned as an operator test/debug harness rather than the production vending UX
./docs/implemented-host-app.md:30:- Local development now also ships with a tracked Docker Postgres setup plus `.env.local` defaults, so Ballbox can run against `ballbox_local` without depending on the remote database.
./docs/implemented-sports.md:14:- `/coaches/settings` now opens on a coach workspace split into `Calendar`, `Performance`, `Alumnos`, and `Horarios y Clases`: calendar shows the current week in an hour-by-hour class matrix, groups simultaneous reservations into one individual or group class, surfaces each student's basic profile data (name, sexo, edad, categoria), marks which reservations are paid vs pending, and starts with a large `Agregar clase` CTA that takes the coach into `Alumnos`; `Performance` shows club-level results plus weekly earnings and student consistency rows, while `Horarios y Clases` auto-saves club selection, availability, packages, and Mercado Pago setup without manual save buttons and no longer shows the club's court-fee pricing to the coach. Pending autosave writes are also flushed if the coach leaves the page before the debounce finishes.
./docs/implemented-sports.md:32:- `Coach` now also stores a Mercado Pago placeholder handle and reusable `CoachSalesPackage` rows for price, duration, class type, and max-student setup.
./docs/implemented-sports.md:40:- `VenueCourt` persists the per-court setup for covered/open courts plus whether coaches can teach on that court.
./docs/implemented-sports.md:93:- No operator request inbox yet.
./components/screen-player.tsx:115:      : "remote";
./components/tvs-admin-client.tsx:451:              <p className={`mt-1 text-sm ${secondaryTextClass}`}>Dispositivos físicos, manifest override y salud de conexión.

./AGENTS.md:19:- for Playwright/e2e, prefer a stable app-like server path over dev-only watcher flows when either can satisfy the test objective; keep the repo default framed as the most repeatable cross-machine setup, not a workaround for one host
./AGENTS.md:26:- seeded demo/e2e fixtures used by operator flows should stay valid across normal near-future local runs; avoid near-term hard-coded expiry windows unless the task explicitly tests expiry behavior
./docs/coaches-opportunity-brief.md:17:- Segment: coach-first discovery, with strongest current attention on group-class operators
./docs/coaches-opportunity-brief.md:38:  - existing operator/admin surfaces


**Creating documentation guides**

I think I need to create separate remote and on-site manuals based on the general one. The user mentioned they already had a setup manual for both remote and physical setups. I should check if this documentation is in the general repository or maybe in a download file. It seems like I’ll need to craft two new documents: a setup-day-remote-guide and an on-site-guide, plus an overview that links everything. I'll also need to update the index and plan!

write

# Vending machine setup day overview

## Purpose
- One entrypoint for setup-day documentation.
- Split responsibilities between remote operator and on-site operator.
- Keep one shared checklist for evidence, escalation, and go-live acceptance.

## Read order
1. `docs/vending-machine-setup-day-overview.md`
2. `docs/vending-machine-setup-day-remote.md`
3. `docs/vending-machine-setup-day-on-site.md`
4. `docs/vending-machine-setup-day-manual.md`

## Role split
### Remote operator
Owns:
- cloud login and tenant checks
- product/catalog and remote sync checks
- media upload and assignment
- Ballbox payment checks
- evidence log and escalation packet
- final go/no-go coordination

Primary doc:
- `docs/vending-machine-setup-day-remote.md`

### On-site operator
Owns:
- receiving and physical inspection
- power, network, and touchscreen checks
- machine-side photos/videos
- local reboot/service actions
- product load and physical vend checks
- confirming screen/media/payment behavior on hardware

Primary doc:
- `docs/vending-machine-setup-day-on-site.md`

## Shared source doc
- `docs/vending-machine-setup-day-manual.md`
- Use as the full combined runbook.
- If any role-specific doc conflicts with it, update all three together.

## Shared evidence to capture
- crate and label photos
- serial number
- model label
- screen family
- payment module model
- firmware/build version
- cloud tenant url/name
- machine online screenshot
- product/price sync screenshot
- media upload/assignment screenshot
- payment QR screenshot
- successful vend evidence
- timestamps with timezone

## Shared go-live gates
- machine online and stable
- correct timezone
- touch OK
- product sync OK
- media sync OK
- payment test OK
- physical vend OK
- reconciliation OK

## Escalation rule
If blocked, collect one packet with:
- what step failed
- exact timestamp
- screenshot/video
- serial/model/build
- network path used
- last successful action
- whether issue is Ballbox, cloud, or machine-side


Successfully wrote 1990 bytes to /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/vending-machine-setup-day-overview.md


# Vending machine setup day remote operator guide

## Mission
- Drive setup remotely while the on-site operator handles hardware.
- Keep one clean timeline, one evidence log, and one escalation packet.

## Access and inputs
- OurVend test cloud: `https://dnymer.ourvend.com/#/login`
- Test user: `cc`
- Test password: `ys123456`
- Production note: real cloud + production creds arrive on machine-delivery day.
- Full reference: `docs/vending-machine-setup-day-manual.md`

## Before setup starts
- Open Chrome.
- Confirm Ballbox payment test environment is reachable.
- Prepare a live note with:
  - machine nickname
  - venue
  - serial
  - model
  - timestamps
  - issues
  - evidence links
- Have supplier/TCN escalation contacts ready.

## During receiving
Ask on-site operator to send:
- crate photos
- model label photo
- serial photo
- screen/payment bay photos
- any shipping damage

Decisions:
- if model mismatch: pause setup and escalate
- if visible screen/door/payment-bay damage: document before power-on

## During first power-on
Have on-site operator confirm:
- voltage and grounding checked
- Ethernet connected first if available
- date/time/timezone set correctly
- touch passes corner/button check
- machine reaches internet

If network fails:
- verify site Ethernet first
- use hotspot only as fallback
- record exact path used

## Cloud onboarding sequence
1. Login to tenant.
2. Confirm tenant, timezone, currency, and roles.
3. Create/confirm device-group hierarchy.
4. Create/bind machine record.
5. Confirm machine appears online.
6. Confirm heartbeat/last-seen updates.
7. Load initial catalog.
8. Push one safe price/product change.
9. Confirm machine syncs it.

## Media workflow
1. Find media/advertising section.
2. Upload one short test video first.
3. Assign to exact machine or group.
4. Publish/sync.
5. Ask on-site operator to confirm playback.
6. If good, upload final pack.

Log:
- file type
- file size
- assignment target
- whether sync or reboot was needed

## Payment workflow
Current direction stays:
- `/admin/payments` = Ballbox test/debug harness
- production machine flow = TCN protocol
- machine displays QR
- Ballbox owns payment create + webhook + approval persistence + reconciliation

Remote steps:
1. Confirm vendable product mapping.
2. Confirm Ballbox can still create QR orders.
3. Confirm machine/cloud can hit Ballbox adapter or stub.
4. Scan/pay test from phone if available.
5. Confirm provider webhook arrives.
6. Confirm approved payment persists with canonical correlation.
7. Confirm TCN side gets success/notify path.
8. Ask on-site operator to run vend confirmation.

## What you must verify live
- exact payment-init payload if visible
- exact `CodeUrl` shape if visible
- whether notify/callback/polling is used
- auth/signature requirements surfaced by tenant docs or errors

## Escalation packet
Send one packet with:
- failing step
- screenshot/video
- timestamps
- tenant url/name
- serial/model/build
- network path
- last successful action
- whether Ballbox-side, cloud-side, or machine-side

## Done criteria
- cloud online OK
- catalog sync OK
- media sync OK
- payment test OK
- physical vend OK
- evidence log complete


Successfully wrote 3196 bytes to /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/vending-machine-setup-day-remote.md


# Vending machine setup day on-site operator guide

## Mission
- Handle the physical machine.
- Feed the remote operator exact evidence fast.
- Do not guess on firmware or hidden service changes.

## What to bring
- phone with camera
- Ethernet cable
- power extension if needed
- hotspot fallback
- cleaning cloth for screen
- note app for ids if signal is weak

## Rules
- Photograph before changing things.
- Ethernet first.
- Set correct date/time/timezone before cloud/payment tests.
- Do not blind-flash firmware.
- If model/serial/damage looks wrong, pause and escalate.

## Arrival and receiving
1. Photograph crate before opening.
2. Photograph labels and serial stickers.
3. Check for damage.
4. Confirm model label matches expected family.
5. Remove all transport foam, tape, tray locks, fillers.
6. Photograph:
   - full front
   - screen
   - payment bay
   - pickup box
   - lock/door
   - any damage
7. Level machine before vend tests.
8. Send photos and ids to remote operator.

## First power-on
1. Verify local voltage and grounding.
2. Connect Ethernet if available.
3. Power on.
4. Set:
   - date
   - time
   - timezone
   - language/locale
5. Confirm internet works.
6. Test touch on:
   - four corners
   - lane buttons
   - payment/confirm buttons
7. Record firmware/build version if visible.

If touch drifts:
- clean glass
- remove temporary protector
- retry
- use built-in diagnostics if present
- stop and escalate if still bad

## Work with remote operator during cloud setup
Be ready to provide:
- serial
- model
- screen family
- payment module model
- cloud device id / barcode / qr if visible
- online/offline screen state
- any error messages on machine

## Media test on hardware
When remote operator publishes media:
1. Wait for sync.
2. Reboot only if asked or clearly needed.
3. Confirm:
   - media appears
   - full-screen playback works
   - touch flow still works
4. Record short video as proof.

## Payment and vend test
1. Confirm vendable product is loaded and mapped.
2. Trigger test flow with remote operator.
3. When QR appears, record photo/video.
4. After payment approval, confirm:
   - machine updates state
   - vend starts
   - product actually drops
   - pickup path is clear
5. Record result video.
6. Report any mismatch between payment success and vend outcome immediately.

## Red flags
- model mismatch
- screen crack or touch dead zones
- no internet on Ethernet
- cloud never shows online
- media assigned but never appears
- payment approved but no vend
- vend triggers but product jams

## Escalation packet to send remote operator
- photos/videos
- serial/model/build
- network used
- exact screen error text
- timestamp with timezone
- last successful action

## Done criteria
- machine stable
- touch OK
- online OK
- media visible
- QR visible
- vend successful
- evidence sent


Successfully wrote 2846 bytes to /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/vending-machine-setup-day-on-site.md


edit

# Vending machine setup day manual

## Purpose
- One Ballbox-owned setup manual for arrival day.
- Focus: first power-on, cloud onboarding, media upload, payment readiness, and go-live checks.
- Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.

# Vending machine setup day manual

## Role-specific companion docs
- Overview: `docs/vending-machine-setup-day-overview.md`
- Remote operator: `docs/vending-machine-setup-day-remote.md`
- On-site operator: `docs/vending-machine-setup-day-on-site.md`

## Purpose
- One Ballbox-owned combined setup manual for arrival day.
- Focus: first power-on, cloud onboarding, media upload, payment readiness, and go-live checks.
- Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.


Successfully replaced 1 block(s) in /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/vending-machine-setup-day-manual.md.

   1 # Vending machine setup day manual
   2
+  3 ## Role-specific companion docs
+  4 - Overview: `docs/vending-machine-setup-day-overview.md`
+  5 - Remote operator: `docs/vending-machine-setup-day-remote.md`
+  6 - On-site operator: `docs/vending-machine-setup-day-on-site.md`
+  7
   3 ## Purpose
-  4 - One Ballbox-owned setup manual for arrival day.
+  9 - One Ballbox-owned combined setup manual for arrival day.
   5 - Focus: first power-on, cloud onboarding, media upload, payment readiness, and go-live checks.
   6 - Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.
   7
   8 ## Inputs saved for this manual
     ...


- `docs/vending-machine-setup-day-manual.md`: operator setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness

- `docs/vending-machine-setup-day-overview.md`: setup-day docs entrypoint and role split for first TCN vending-machine arrival
- `docs/vending-machine-setup-day-remote.md`: remote operator checklist for setup day
- `docs/vending-machine-setup-day-on-site.md`: on-site operator checklist for setup day
- `docs/vending-machine-setup-day-manual.md`: combined setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness

## Setup And Operations
- `docs/vending-machine-setup-day-manual.md`

## Setup And Operations
- `docs/vending-machine-setup-day-overview.md`
- `docs/vending-machine-setup-day-remote.md`
- `docs/vending-machine-setup-day-on-site.md`
- `docs/vending-machine-setup-day-manual.md`


Successfully replaced 2 block(s) in /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/index.md.

    ...
 10 - `docs/*-discovery*.md`: validation and research framing
 11 - `docs/*-gap-analysis.md`: what Ballbox still needs to build
 12 - `docs/maintainability-priorities-2026-03.md`: prioritized frontend/backend maintainability work for the next refactor cycle
 13 - `docs/demo-iteration-mode.md`: rapid demo delivery model with anti-debt guardrails
-14 - `docs/vending-machine-setup-day-manual.md`: operator setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness
+14 - `docs/vending-machine-setup-day-overview.md`: setup-day docs entrypoint and role split for first TCN vending-machine arrival
+15 - `docs/vending-machine-setup-day-remote.md`: remote operator checklist for setup day
+16 - `docs/vending-machine-setup-day-on-site.md`: on-site operator checklist for setup day
+17 - `docs/vending-machine-setup-day-manual.md`: combined setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness
 15
 16 ## Operator Priority Path
 17 1. `PLAN.md`
 18 2. `docs/next-steps-queue.md`
    ...
 45 - `docs/coaches-validation-checklist-2-weeks.md`
 46 - `docs/coaches-solution-thesis.md`
 47
 48 ## Setup And Operations
+52 - `docs/vending-machine-setup-day-overview.md`
+53 - `docs/vending-machine-setup-day-remote.md`
+54 - `docs/vending-machine-setup-day-on-site.md`
 49 - `docs/vending-machine-setup-day-manual.md`
 50
 51 ## Current Build Docs
 52 - `docs/classes-subroute-plan.md`
    ...


- Repo docs now include `docs/vending-machine-setup-day-manual.md`, a Ballbox-owned setup-day runbook for first TCN machine arrival covering receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.

- Repo docs now include a setup-day doc set for first TCN machine arrival: `docs/vending-machine-setup-day-overview.md`, `docs/vending-machine-setup-day-remote.md`, `docs/vending-machine-setup-day-on-site.md`, and `docs/vending-machine-setup-day-manual.md`, covering role split, receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.


Successfully replaced 1 block(s) in /mnt/rpi/worktrees/ballbox/docs-vending-manual/PLAN.md.

     ...
  29 - Payments are now owned inside Ballbox host app: native MercadoPago webhook intake exists under `/notification/mercadopago` and resolves QR notifications by fetching the upstream order.
  30 - Payments host app now also exposes native QR order creation under `/api/integrations/payments/orders`, generating canonical `externalReference` values required for approved-session persistence correlation.
  31 - `/admin/payments` now also generates live MercadoPago QR orders for arbitrary amounts or per-product prices, with money inputs expressed in major units (for example `15.00` or `1000.00`), then shows the QR preview/order id for scan-and-pay validation.
  32 - That admin QR surface is now positioned as a provider test/debug harness; production vending-machine payments should integrate through the TCN machine protocol and let the machine render the buyer-facing QR.
- 33 - Repo docs now include `docs/vending-machine-setup-day-manual.md`, a Ballbox-owned setup-day runbook for first TCN machine arrival covering receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
+ 33 - Repo docs now include a setup-day doc set for first TCN machine arrival: `docs/vending-machine-setup-day-overview.md`, `docs/vending-machine-setup-day-remote.md`, `docs/vending-machine-setup-day-on-site.md`, and `docs/vending-machine-setup-day-manual.md`, covering role split, receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
  34 - Club revenue share is currently handled with scheduled manual settlements/bookkeeping; Mercado Pago native split stays deferred until the machine flow and club count justify it.
  35 - Legacy approved-callback compatibility has been removed from operations; `/api/integrations/payments/approved` now returns `410` so only the native MercadoPago path remains active.
  36 - `/admin/payments` now exposes Ballbox-local CRUD/reconciliation for approved payment sessions plus correlation checks against canonical `payment-vm_{vendingMachineId}-txn_{machineTxnId}` references.
  37 - Payments admin session routes now read Prisma error helpers from `lib/prisma-errors.ts` instead of importing them via `lib/ballbox-store.ts`.
     ...


bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && git diff -- docs/index.md PLAN.md docs/vending-machine-setup-day-*.md | sed -n '1,320p'

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && git status --short


diff --git a/PLAN.md b/PLAN.md
index 78aef33..87ac2c4 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -30,7 +30,7 @@
 - Payments host app now also exposes native QR order creation under `/api/integrations/payments/orders`, generating canonical `externalReference` values required for approved-session persistence correlation.
 - `/admin/payments` now also generates live MercadoPago QR orders for arbitrary amounts or per-product prices, with money inputs expressed in major units (for example `15.00` or `1000.00`), then shows the QR preview/order id for scan-and-pay validation.
 - That admin QR surface is now positioned as a provider test/debug harness; production vending-machine payments should integrate through the TCN machine protocol and let the machine render the buyer-facing QR.
-- Repo docs now include `docs/vending-machine-setup-day-manual.md`, a Ballbox-owned setup-day runbook for first TCN machine arrival covering receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
+- Repo docs now include a setup-day doc set for first TCN machine arrival: `docs/vending-machine-setup-day-overview.md`, `docs/vending-machine-setup-day-remote.md`, `docs/vending-machine-setup-day-on-site.md`, and `docs/vending-machine-setup-day-manual.md`, covering role split, receiving, first power-on, OurVend tenant onboarding, media-upload checks, and payment go-live readiness.
 - Club revenue share is currently handled with scheduled manual settlements/bookkeeping; Mercado Pago native split stays deferred until the machine flow and club count justify it.
 - Legacy approved-callback compatibility has been removed from operations; `/api/integrations/payments/approved` now returns `410` so only the native MercadoPago path remains active.
 - `/admin/payments` now exposes Ballbox-local CRUD/reconciliation for approved payment sessions plus correlation checks against canonical `payment-vm_{vendingMachineId}-txn_{machineTxnId}` references.
diff --git a/docs/index.md b/docs/index.md
index 0a36683..b76ca67 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,7 +11,10 @@
 - `docs/*-gap-analysis.md`: what Ballbox still needs to build
 - `docs/maintainability-priorities-2026-03.md`: prioritized frontend/backend maintainability work for the next refactor cycle
 - `docs/demo-iteration-mode.md`: rapid demo delivery model with anti-debt guardrails
-- `docs/vending-machine-setup-day-manual.md`: operator setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness
+- `docs/vending-machine-setup-day-overview.md`: setup-day docs entrypoint and role split for first TCN vending-machine arrival
+- `docs/vending-machine-setup-day-remote.md`: remote operator checklist for setup day
+- `docs/vending-machine-setup-day-on-site.md`: on-site operator checklist for setup day
+- `docs/vending-machine-setup-day-manual.md`: combined setup-day manual for first TCN vending-machine arrival, cloud onboarding, media upload, and payment readiness

 ## Operator Priority Path
 1. `PLAN.md`
@@ -46,6 +49,9 @@
 - `docs/coaches-solution-thesis.md`

 ## Setup And Operations
+- `docs/vending-machine-setup-day-overview.md`
+- `docs/vending-machine-setup-day-remote.md`
+- `docs/vending-machine-setup-day-on-site.md`
 - `docs/vending-machine-setup-day-manual.md`

 ## Current Build Docs
diff --git a/docs/vending-machine-setup-day-manual.md b/docs/vending-machine-setup-day-manual.md
index bc342d8..1d817aa 100644
--- a/docs/vending-machine-setup-day-manual.md
+++ b/docs/vending-machine-setup-day-manual.md
@@ -1,7 +1,12 @@
 # Vending machine setup day manual

+## Role-specific companion docs
+- Overview: `docs/vending-machine-setup-day-overview.md`
+- Remote operator: `docs/vending-machine-setup-day-remote.md`
+- On-site operator: `docs/vending-machine-setup-day-on-site.md`
+
 ## Purpose
-- One Ballbox-owned setup manual for arrival day.
+- One Ballbox-owned combined setup manual for arrival day.
 - Focus: first power-on, cloud onboarding, media upload, payment readiness, and go-live checks.
 - Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.


 M PLAN.md
 M docs/index.md
 M docs/vending-machine-setup-day-manual.md
?? docs/vending-machine-setup-day-on-site.md
?? docs/vending-machine-setup-day-overview.md
?? docs/vending-machine-setup-day-remote.md


cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && git add PLAN.md docs/index.md docs/vending-machine-setup-day-manual.md docs/vending-machine-setup-day-overview.md docs/vending-machine-setup-day-remote.md docs/vending-machine-setup-day-on-site.md && git commit -m "docs: split vending setup day guides by role"


[docs-vending-manual 825b89f] docs: split vending setup day guides by role
 6 files changed, 326 insertions(+), 3 deletions(-)
 create mode 100644 docs/vending-machine-setup-day-on-site.md
 create mode 100644 docs/vending-machine-setup-day-overview.md
 create mode 100644 docs/vending-machine-setup-day-remote.md


Updated #2 (pending → completed)

Build vending machine setup manual from provided sources in isolated worktree

Create/update docs in a dedicated worktree using the provided links and local research file, then review whether the Payments Integration section still looks valid.

Audit existing setup-day docs and align vending manuals

Review repo documentation for existing setup-day manuals, especially remote vs on-site roles, then consolidate/index/update docs so all relevant manuals remain visible and non-duplicative.


Sí. Había quedado demasiado condensado en un solo manual.

Revisé la doc del repo y dejé el set completo, separado por rol:

- `docs/vending-machine-setup-day-overview.md`
- `docs/vending-machine-setup-day-remote.md`
- `docs/vending-machine-setup-day-on-site.md`
- `docs/vending-machine-setup-day-manual.md` — combinado / fuente común

También actualicé:
- `docs/index.md`
- `PLAN.md`

Qué hice:
- dejé un entrypoint claro
- separé remoto vs físico
- mantuve el manual largo como referencia completa
- alineé la indexación para que no quede perdido

Commits en el worktree:
- `3239857` `docs: add vending machine setup day manual`
- `825b89f` `docs: split vending setup day guides by role`

Worktree:
- `/mnt/rpi/worktrees/ballbox/docs-vending-manual`

Observación:
- no encontré en el repo otros dos manuales previos explícitos; por eso armé el split ahora dentro de `docs/` y lo dejé visible.
- si esos manuales viejos viven fuera del repo, pasamelos y los incorporo/mergeo sin perder nada.

Siguiente paso posible:
1. llevar estos docs a `main` localmente, o
2. seguir revisando la sección de Payments Integration contra el material nuevo.


Si los documentos remote y on-site son una duplicación exacta de manual, no los quiero. Prefiero tener todo dentro de uno y que la persona correspondiente vaya a su sección.


**Considering document editing**

I need to decide whether to comply with editing requests by removing or splitting documents while keeping an overview in mind. It's important to consider the user's preferences since they're explicit about what they want. So, I should take action accordingly and ensure their needs are prioritized. I wonder what specific changes the user is looking for, as that would guide my next steps. Let's clarify that!

todo

Collapse setup-day docs into one manual with role sections

Remove redundant remote/on-site split docs if they duplicate the combined manual, and keep a single setup-day manual with clearly labeled role sections plus updated indexing.


Created #3: Collapse setup-day docs into one manual with role sections (pending)


bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && sed -n '1,260p' docs/vending-machine-setup-day-manual.md

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && printf '\n--- OVERVIEW ---\n' && sed -n '1,220p' docs/vending-machine-setup-day-overview.md && printf '\n--- REMOTE ---\n' && sed -n '1,260p' docs/vending-machine-setup-day-remote.md && printf '\n--- ONSITE ---\n' && sed -n '1,260p' docs/vending-machine-setup-day-on-site.md


# Vending machine setup day manual

## Role-specific companion docs
- Overview: `docs/vending-machine-setup-day-overview.md`
- Remote operator: `docs/vending-machine-setup-day-remote.md`
- On-site operator: `docs/vending-machine-setup-day-on-site.md`

## Purpose
- One Ballbox-owned combined setup manual for arrival day.
- Focus: first power-on, cloud onboarding, media upload, payment readiness, and go-live checks.
- Target machine family from current research: TCN CSC-8C(V49) or closest 8C/49-inch equivalent delivered by supplier.

## Inputs saved for this manual
- Research base: `/Users/sebas/Downloads/deep-research-report.md`
- Video reference: `https://www.youtube.com/watch?v=Qwbp3muM7gA` (`How to upload videos to the vending machine`)
- Test cloud: `https://dnymer.ourvend.com/#/login`
- Test user: `cc`
- Test password: `ys123456`
- Production note: real cloud + production creds arrive on machine-delivery day.

## Non-negotiables
- Do not blind-flash firmware from another model family.
- Ask TCN/supplier for exact package matched to serial number, mainboard revision, screen family, and payment-module BOM.
- Prefer Ethernet first.
- Set correct date, time, timezone before any cloud or payment test.
- Do not enable live payments until cloud status, product sync, and vend tests are clean.

## Day-before checklist
- Have Chrome ready.
- Have Ethernet available on-site.
- Have extension cable / stable power / grounding verified.
- Have phone hotspot as fallback only.
- Have Ballbox test payment account ready.
- Prepare a shared note with:
  - machine serial
  - model label
  - screen family
  - payment module model
  - cloud device id / qr / barcode if shown
  - venue / club / machine nickname
- Ask supplier in advance for:
  - tenant invite or confirmed cloud login
  - exact firmware/build package
  - service PIN/password
  - open-device / payment API docs
  - device ids / serial mapping

## Arrival and receiving
1. Photograph crate before opening.
2. Record damage, pallet status, labels, serial stickers.
3. Confirm actual machine label.
4. Remove all transport foam, tape, tray locks, pickup-box fillers.
5. Check:
   - screen glass
   - bezel alignment
   - lock / door
   - pickup box flap
   - payment bay
   - leveling feet
6. Level machine before vend tests.
7. Record all ids in shared note.

## First power-on
1. Verify local voltage and grounding.
2. Power on with Ethernet connected if possible.
3. Set:
   - date
   - time
   - timezone
   - language / locale
4. Confirm internet reachability.
5. Test touch on corners, lane buttons, payment buttons.
6. If touch drifts:
   - clean glass
   - remove temporary protector
   - retry
   - use built-in diagnostics if present
   - escalate to TCN for exact touch/display package if still broken

## Cloud onboarding in OurVend
Portal:
- URL: `https://dnymer.ourvend.com/#/login`
- Browser: Chrome preferred
- Current test creds:
  - user: `cc`
  - pass: `ys123456`

Suggested order:
1. Login.
2. Confirm tenant, timezone, currency, and role permissions.
3. Create or confirm device-group hierarchy:
   - Country > Region > Club > Machine
4. Create/bind machine record with:
   - serial number
   - model family
   - location
   - timezone
   - language
   - temperature profile
   - currency
5. Confirm machine appears online.
6. Confirm heartbeat / last-seen timestamps move.
7. Load initial catalog.
8. Push one safe remote change:
   - product name or price
9. Confirm device receives sync.

## Media upload to the vending machine
Source: public video `How to upload videos to the vending machine`.
- Treat this section as an operator checklist, not as a verified exact click-path yet.

Use this as the operator checklist once inside tenant UI:
1. Find device-management / media / advertising section.
2. Upload one short test video first.
3. Assign video to the correct machine or machine group.
4. Publish/sync.
5. Confirm playback on the machine screen.
6. Then upload final production media pack.

Day-of validation points:
- supported format accepted by portal
- upload completes without silent failure
- media can be assigned to the specific machine
- machine pulls new media after sync/reboot
- playback is full-screen and touch flow still works

Open items to confirm in tenant UI:
- exact menu path for media upload
- supported file types / size limits
- whether media binds per machine, per group, or per playlist
- whether manual sync/reboot is needed after publish

## Payment integration status
### Current Ballbox position
- `/admin/payments` stays a Ballbox operator test/debug harness.
- Production vending flow should go through TCN machine protocol.
- The machine should show the buyer-facing QR on its own screen.
- Ballbox should own payment creation, webhook validation, approval persistence, and reconciliation.

### Why this still looks valid
- Current research still supports OurVend/TCN as cloud + device-control layer, not the owner of Ballbox business logic.
- Public evidence still points to secret/signature-based device-open access on the vendor side.
- The deep research report still supports backend-owned dynamic QR plus vendor-side vend authorization as the safest default architecture before exact tenant docs arrive.
- Nothing in the supplied test cloud login changes that direction by itself.

### What still needs real-world confirmation on setup day
- exact payment-init payload from machine/cloud
- exact vend-success callback / notify path
- exact `CodeUrl` expectation: qr payload vs link vs provider-specific deep link
- whether payment completion relies on callback, polling, or both
- exact auth/signature shape for production tenant endpoints

### Setup-day payment test sequence
1. Confirm machine online in cloud.
2. Confirm one vendable product exists and is mapped correctly.
3. Confirm Ballbox test payment flow can still create QR orders.
4. Confirm machine/cloud can request payment init against Ballbox adapter or stub.
5. Scan QR from phone.
6. Confirm Ballbox receives provider webhook.
7. Confirm approved payment persists with canonical machine correlation.
8. Confirm TCN side receives success/notify signal.
9. Confirm physical vend succeeds.
10. Reconcile payment, vend result, and inventory change.

## Go-live acceptance
- machine online and stable
- correct timezone
- touch OK across screen
- at least one product sync OK
- price sync OK
- media sync OK
- payment test OK
- vend test OK
- retry/error path observed at least once
- all ids and creds archived in internal ops note

## Escalation packet for supplier / TCN
If something blocks setup, send all of this together:
- machine serial
- model label
- screen family
- payment module model
- current firmware/build version
- cloud tenant name/url
- screenshots/video of issue
- timestamps with timezone
- whether Ethernet or Wi-Fi
- last successful action

## Related repo docs
- `docs/tcn-payments-integration-plan.md`
- `docs/tcn-payments-open-questions.md`
- `docs/tcn-payments-execution-plan.md`
- `docs/payments-machine-rollout-rfc.md`


--- OVERVIEW ---
# Vending machine setup day overview

## Purpose
- One entrypoint for setup-day documentation.
- Split responsibilities between remote operator and on-site operator.
- Keep one shared checklist for evidence, escalation, and go-live acceptance.

## Read order
1. `docs/vending-machine-setup-day-overview.md`
2. `docs/vending-machine-setup-day-remote.md`
3. `docs/vending-machine-setup-day-on-site.md`
4. `docs/vending-machine-setup-day-manual.md`

## Role split
### Remote operator
Owns:
- cloud login and tenant checks
- product/catalog and remote sync checks
- media upload and assignment
- Ballbox payment checks
- evidence log and escalation packet
- final go/no-go coordination

Primary doc:
- `docs/vending-machine-setup-day-remote.md`

### On-site operator
Owns:
- receiving and physical inspection
- power, network, and touchscreen checks
- machine-side photos/videos
- local reboot/service actions
- product load and physical vend checks
- confirming screen/media/payment behavior on hardware

Primary doc:
- `docs/vending-machine-setup-day-on-site.md`

## Shared source doc
- `docs/vending-machine-setup-day-manual.md`
- Use as the full combined runbook.
- If any role-specific doc conflicts with it, update all three together.

## Shared evidence to capture
- crate and label photos
- serial number
- model label
- screen family
- payment module model
- firmware/build version
- cloud tenant url/name
- machine online screenshot
- product/price sync screenshot
- media upload/assignment screenshot
- payment QR screenshot
- successful vend evidence
- timestamps with timezone

## Shared go-live gates
- machine online and stable
- correct timezone
- touch OK
- product sync OK
- media sync OK
- payment test OK
- physical vend OK
- reconciliation OK

## Escalation rule
If blocked, collect one packet with:
- what step failed
- exact timestamp
- screenshot/video
- serial/model/build
- network path used
- last successful action
- whether issue is Ballbox, cloud, or machine-side

--- REMOTE ---
# Vending machine setup day remote operator guide

## Mission
- Drive setup remotely while the on-site operator handles hardware.
- Keep one clean timeline, one evidence log, and one escalation packet.

## Access and inputs
- OurVend test cloud: `https://dnymer.ourvend.com/#/login`
- Test user: `cc`
- Test password: `ys123456`
- Production note: real cloud + production creds arrive on machine-delivery day.
- Full reference: `docs/vending-machine-setup-day-manual.md`

## Before setup starts
- Open Chrome.
- Confirm Ballbox payment test environment is reachable.
- Prepare a live note with:
  - machine nickname
  - venue
  - serial
  - model
  - timestamps
  - issues
  - evidence links
- Have supplier/TCN escalation contacts ready.

## During receiving
Ask on-site operator to send:
- crate photos
- model label photo
- serial photo
- screen/payment bay photos
- any shipping damage

Decisions:
- if model mismatch: pause setup and escalate
- if visible screen/door/payment-bay damage: document before power-on

## During first power-on
Have on-site operator confirm:
- voltage and grounding checked
- Ethernet connected first if available
- date/time/timezone set correctly
- touch passes corner/button check
- machine reaches internet

If network fails:
- verify site Ethernet first
- use hotspot only as fallback
- record exact path used

## Cloud onboarding sequence
1. Login to tenant.
2. Confirm tenant, timezone, currency, and roles.
3. Create/confirm device-group hierarchy.
4. Create/bind machine record.
5. Confirm machine appears online.
6. Confirm heartbeat/last-seen updates.
7. Load initial catalog.
8. Push one safe price/product change.
9. Confirm machine syncs it.

## Media workflow
1. Find media/advertising section.
2. Upload one short test video first.
3. Assign to exact machine or group.
4. Publish/sync.
5. Ask on-site operator to confirm playback.
6. If good, upload final pack.

Log:
- file type
- file size
- assignment target
- whether sync or reboot was needed

## Payment workflow
Current direction stays:
- `/admin/payments` = Ballbox test/debug harness
- production machine flow = TCN protocol
- machine displays QR
- Ballbox owns payment create + webhook + approval persistence + reconciliation

Remote steps:
1. Confirm vendable product mapping.
2. Confirm Ballbox can still create QR orders.
3. Confirm machine/cloud can hit Ballbox adapter or stub.
4. Scan/pay test from phone if available.
5. Confirm provider webhook arrives.
6. Confirm approved payment persists with canonical correlation.
7. Confirm TCN side gets success/notify path.
8. Ask on-site operator to run vend confirmation.

## What you must verify live
- exact payment-init payload if visible
- exact `CodeUrl` shape if visible
- whether notify/callback/polling is used
- auth/signature requirements surfaced by tenant docs or errors

## Escalation packet
Send one packet with:
- failing step
- screenshot/video
- timestamps
- tenant url/name
- serial/model/build
- network path
- last successful action
- whether Ballbox-side, cloud-side, or machine-side

## Done criteria
- cloud online OK
- catalog sync OK
- media sync OK
- payment test OK
- physical vend OK
- evidence log complete

--- ONSITE ---
# Vending machine setup day on-site operator guide

## Mission
- Handle the physical machine.
- Feed the remote operator exact evidence fast.
- Do not guess on firmware or hidden service changes.

## What to bring
- phone with camera
- Ethernet cable
- power extension if needed
- hotspot fallback
- cleaning cloth for screen
- note app for ids if signal is weak

## Rules
- Photograph before changing things.
- Ethernet first.
- Set correct date/time/timezone before cloud/payment tests.
- Do not blind-flash firmware.
- If model/serial/damage looks wrong, pause and escalate.

## Arrival and receiving
1. Photograph crate before opening.
2. Photograph labels and serial stickers.
3. Check for damage.
4. Confirm model label matches expected family.
5. Remove all transport foam, tape, tray locks, fillers.
6. Photograph:
   - full front
   - screen
   - payment bay
   - pickup box
   - lock/door
   - any damage
7. Level machine before vend tests.
8. Send photos and ids to remote operator.

## First power-on
1. Verify local voltage and grounding.
2. Connect Ethernet if available.
3. Power on.
4. Set:
   - date
   - time
   - timezone
   - language/locale
5. Confirm internet works.
6. Test touch on:
   - four corners
   - lane buttons
   - payment/confirm buttons
7. Record firmware/build version if visible.

If touch drifts:
- clean glass
- remove temporary protector
- retry
- use built-in diagnostics if present
- stop and escalate if still bad

## Work with remote operator during cloud setup
Be ready to provide:
- serial
- model
- screen family
- payment module model
- cloud device id / barcode / qr if visible
- online/offline screen state
- any error messages on machine

## Media test on hardware
When remote operator publishes media:
1. Wait for sync.
2. Reboot only if asked or clearly needed.
3. Confirm:
   - media appears
   - full-screen playback works
   - touch flow still works
4. Record short video as proof.

## Payment and vend test
1. Confirm vendable product is loaded and mapped.
2. Trigger test flow with remote operator.
3. When QR appears, record photo/video.
4. After payment approval, confirm:
   - machine updates state
   - vend starts
   - product actually drops
   - pickup path is clear
5. Record result video.
6. Report any mismatch between payment success and vend outcome immediately.

## Red flags
- model mismatch
- screen crack or touch dead zones
- no internet on Ethernet
- cloud never shows online
- media assigned but never appears
- payment approved but no vend
- vend triggers but product jams

## Escalation packet to send remote operator
- photos/videos
- serial/model/build
- network used
- exact screen error text
- timestamp with timezone
- last successful action

## Done criteria
- machine stable
- touch OK
- online OK
- media visible
- QR visible
- vend successful
- evidence sent


**Integrating documentation**

I need to streamline the documentation by removing redundant materials and integrating various sections into the main manual. It's also important for me to update the index and overall plan to reflect these changes. This will help improve organization and make it easier for others to navigate the manual. I want to ensure everything is clear and useful, so I'll take my time to get this right!

edit

## Role-specific companion docs
- Overview: `docs/vending-machine-setup-day-overview.md`
- Remote operator: `docs/vending-machine-setup-day-remote.md`
- On-site operator: `docs/vending-machine-setup-day-on-site.md`

## Purpose

## Role split
### Remote operator owns
- cloud login and tenant checks
- product/catalog and remote sync checks
- media upload and assignment
- Ballbox payment checks
- evidence log and escalation packet
- final go/no-go coordination

### On-site operator owns
- receiving and physical inspection
- power, network, and touchscreen checks
- machine-side photos/videos
- local reboot/service actions
- product load and physical vend checks
- confirming screen/media/payment behavior on hardware

## Inputs saved for this manual

## Shared evidence to capture
- crate and label photos
- serial number
- model label
- screen family
- payment module model
- firmware/build version
- cloud tenant url/name
- machine online screenshot
- product/price sync screenshot
- media upload/assignment screenshot
- payment QR screenshot
- successful vend evidence
- timestamps with timezone

## Day-before checklist

## Arrival and receiving
1. Photograph crate before opening.
2. Record damage, pallet status, labels, serial stickers.
3. Confirm actual machine label.
4. Remove all transport foam, tape, tray locks, pickup-box fillers.
5. Check:
   - screen glass
   - bezel alignment
   - lock / door
   - pickup box flap
   - payment bay
   - leveling feet
6. Level machine before vend tests.
7. Record all ids in shared note.

## Arrival and receiving
### On-site
1. Photograph crate before opening.
2. Record damage, pallet status, labels, serial stickers.
3. Confirm actual machine label.
4. Remove all transport foam, tape, tray locks, pickup-box fillers.
5. Check:
   - screen glass
   - bezel alignment
   - lock / door
   - pickup box flap
   - payment bay
   - leveling feet
6. Level machine before vend tests.
7. Record all ids in shared note.
8. Send photos and ids to remote operator.

### Remote
- Check for model mismatch before proceeding.
- If there is visible shipping damage, document it before power-on and decide whether to pause setup.

## First power-on
1. Verify local voltage and grounding.
2. Power on with Ethernet connected if possible.
3. Set:
   - date
   - time
   - timezone
   - language / locale
4. Confirm internet reachability.
5. Test touch on corners, lane buttons, payment buttons.
6. If touch drifts:
   - clean glass
   - remove temporary protector
   - retry
   - use built-in diagnostics if present
   - escalate to TCN for exact touch/display package if still broken

## First power-on
### On-site
1. Verify local voltage and grounding.
2. Power on with Ethernet connected if possible.
3. Set:
   - date
   - time
   - timezone
   - language / locale
4. Confirm internet reachability.
5. Test touch on corners, lane buttons, payment buttons.
6. Record firmware/build version if visible.
7. If touch drifts:
   - clean glass
   - remove temporary protector
   - retry
   - use built-in diagnostics if present
   - escalate to TCN for exact touch/display package if still broken

### Remote
- Confirm the on-site operator used Ethernet first if available.
- If network fails, verify site Ethernet first and use hotspot only as fallback.
- Record the exact network path used.

Suggested order:
1. Login.
2. Confirm tenant, timezone, currency, and role permissions.
3. Create or confirm device-group hierarchy:
   - Country > Region > Club > Machine
4. Create/bind machine record with:
   - serial number
   - model family
   - location
   - timezone
   - language
   - temperature profile
   - currency
5. Confirm machine appears online.
6. Confirm heartbeat / last-seen timestamps move.
7. Load initial catalog.
8. Push one safe remote change:
   - product name or price
9. Confirm device receives sync.

### Remote
1. Login.
2. Confirm tenant, timezone, currency, and role permissions.
3. Create or confirm device-group hierarchy:
   - Country > Region > Club > Machine
4. Create/bind machine record with:
   - serial number
   - model family
   - location
   - timezone
   - language
   - temperature profile
   - currency
5. Confirm machine appears online.
6. Confirm heartbeat / last-seen timestamps move.
7. Load initial catalog.
8. Push one safe remote change:
   - product name or price
9. Confirm device receives sync.

### On-site
- Be ready to provide serial, model, screen family, payment module model, cloud device id, and any machine-side errors.
- Confirm online/offline state on the machine if visible.

## Media upload to the vending machine
Source: public video `How to upload videos to the vending machine`.
- Treat this section as an operator checklist, not as a verified exact click-path yet.

Use this as the operator checklist once inside tenant UI:
1. Find device-management / media / advertising section.
2. Upload one short test video first.
3. Assign video to the correct machine or machine group.
4. Publish/sync.
5. Confirm playback on the machine screen.
6. Then upload final production media pack.

Day-of validation points:
- supported format accepted by portal
- upload completes without silent failure
- media can be assigned to the specific machine
- machine pulls new media after sync/reboot
- playback is full-screen and touch flow still works

Open items to confirm in tenant UI:
- exact menu path for media upload
- supported file types / size limits
- whether media binds per machine, per group, or per playlist
- whether manual sync/reboot is needed after publish

## Media upload to the vending machine
Source: public video `How to upload videos to the vending machine`.
- Treat this section as an operator checklist, not as a verified exact click-path yet.

### Remote
1. Find device-management / media / advertising section.
2. Upload one short test video first.
3. Assign video to the correct machine or machine group.
4. Publish/sync.
5. If successful, upload final production media pack.

Track:
- file type
- file size
- assignment target
- whether sync or reboot was needed

### On-site
1. Confirm the machine receives the updated media.
2. Reboot only if needed or requested.
3. Confirm playback on the machine screen.
4. Confirm playback is full-screen and touch flow still works.
5. Record short proof video.

Open items to confirm in tenant UI:
- exact menu path for media upload
- supported file types / size limits
- whether media binds per machine, per group, or per playlist
- whether manual sync/reboot is needed after publish

### Setup-day payment test sequence
1. Confirm machine online in cloud.
2. Confirm one vendable product exists and is mapped correctly.
3. Confirm Ballbox test payment flow can still create QR orders.
4. Confirm machine/cloud can request payment init against Ballbox adapter or stub.
5. Scan QR from phone.
6. Confirm Ballbox receives provider webhook.
7. Confirm approved payment persists with canonical machine correlation.
8. Confirm TCN side receives success/notify signal.
9. Confirm physical vend succeeds.
10. Reconcile payment, vend result, and inventory change.

### Setup-day payment test sequence
#### Remote
1. Confirm machine online in cloud.
2. Confirm one vendable product exists and is mapped correctly.
3. Confirm Ballbox test payment flow can still create QR orders.
4. Confirm machine/cloud can request payment init against Ballbox adapter or stub.
5. Scan QR from phone.
6. Confirm Ballbox receives provider webhook.
7. Confirm approved payment persists with canonical machine correlation.
8. Confirm TCN side receives success/notify signal.
9. Reconcile payment, vend result, and inventory change.

#### On-site
1. Confirm vendable product is physically loaded.
2. Record QR display on machine.
3. After approval, confirm machine state changes.
4. Confirm physical vend succeeds.
5. Record proof video.
6. Report any mismatch between payment success and vend outcome immediately.

## Go-live acceptance
- machine online and stable
- correct timezone
- touch OK across screen
- at least one product sync OK
- price sync OK
- media sync OK
- payment test OK
- vend test OK
- retry/error path observed at least once
- all ids and creds archived in internal ops note

## Escalation packet for supplier / TCN
If something blocks setup, send all of this together:
- machine serial
- model label
- screen family
- payment module model
- current firmware/build version
- cloud tenant name/url
- screenshots/video of issue
- timestamps with timezone
- whether Ethernet or Wi-Fi
- last successful action
- whether issue is Ballbox-side, cloud-side, or machine-side