Demo room provisioning
Provision a neutral test Room from trusted server code when you want to prove the full PokerDeck operator setup loop: room identity, custom blind and payout structures, scheduled SNG and MTT tournaments, durable recurring schedules, occurrence previews, result webhooks, support evidence, and readbacks for widgets.
Status: beta dogfood. Public-clean example:
examples/developer-platform/demo-room-provisioning.
What you build
- A server-side provisioning script that creates or selects a test Room.
- Room-owned custom blind and payout structures.
- One scheduled and published six-max NLHE Sit & Go from the beta preset catalog.
- One scheduled and published NLHE MTT from the beta preset catalog.
- Optional durable tournament schedules for prompts such as "daily for a week", "every weekday at
noon", or "every Friday night", plus public occurrence previews with explicit
not_materializedstatus. - PokerDeck room lobby/dashboard URLs, plus tournament join URLs for published tournaments.
- Optional
tournament.completedwebhook endpoint. - Test result/proof attachment through the playground fixture, including trust-mode and declared bot-seat integrity evidence from the public result read.
- Pending player invitations when the prompt asks for members, plus room summary, members, and leaderboard readbacks for widgets and support.
Requirements
- A Console project.
- A test-environment
pw_mgmt_...service-account token stored server-side. - Management scopes:
rooms:create,rooms:read,tournament_structures:create,tournament_structures:read,tournament_schedules:create,tournament_schedules:read,tournaments:create,tournaments:publish,tournaments:update,tournaments:cancel,tournaments:archive,ring_games:read,playground:write, andtournament_results:read. - Add
room_invitations:createwhen the prompt asks for members, invites, or a roster. - Add
rooms:archivewhenPOKERWORKS_DEMO_ARCHIVE_AFTER_RUN=true. - Add
webhook_endpoints:createandwebhook_endpoints:readif you setPOKERWORKS_DEMO_WEBHOOK_URL.
1. Configure the example
Code
Use neutral demo labels. If a prompt says "like ReplayPoker" or "like PokerStars", translate that into capabilities such as scheduled tournaments, leaderboards, or result pages. Do not copy names, copy, schedules, visual identity, or protected trade dress.
Optional capability prompt:
Code
or:
Code
The prompt mapper is deterministic local planning. It does not call an AI model, does not echo the
raw prompt, and does not copy competitor names into generated Room names, slugs, tournament labels,
or API payloads. It returns neutral capabilityProfile details plus explicit gaps when a prompt
asks for reserved surfaces such as ring games, recurring schedules, member writes, public-room
admission, or bot/table-protocol participation. Pending player invitations are admitted; member role
updates and removals remain reserved. Recurrence-shaped prompts are projected into durable
tournament schedule resources and occurrence previews; occurrence materialization remains reserved.
POKERWORKS_DEMO_ROOM_NAME,
POKERWORKS_DEMO_ROOM_SLUG, and POKERWORKS_DEMO_ROOM_ACCENT are explicit overrides; leave them
blank when you want the prompt profile to choose the neutral Room identity.
2. Run the provisioning proof
Code
For PR evidence, CI, or agent handoff, write a durable proof bundle:
Code
The script calls only public Management API routes:
Code
Set POKERWORKS_DEMO_WEBHOOK_URL when you also want:
Code
3. Inspect the support bundle
The output includes the Room id, PokerDeck room lobby/dashboard URLs, SNG/MTT tournament ids,
optional durable schedule ids, occurrence preview ids, custom structure ids, neutral capability profile,
requested-but-reserved gaps, pending invitation ids/redacted contact hints, optional webhook
endpoint id, PokerDeck tournament join URLs, result/proof evidence for the SNG, result integrity
evidence (trustMode, bot allowance, declared bot-seat count, and policy doc ref), summary evidence
id, member count, leaderboard count, and cleanup status. schedulePlan records recurrence,
occurrence preview count, not_materialized posture, and the result/webhook attachment gap for
generated runs.
When POKERWORKS_DEMO_PROOF_OUTPUT or --proof-output is set, the script also writes
pokerworks.demo_room_provisioning.proof.v1 JSON. The proof bundle is the handoff artifact for
agents and CI: it records the exercised public Management API surfaces, room/tournament identifiers,
support-safe evidence ids, cleanup/revoke guidance, viewability status, security posture, and
reserved gaps. It does not include management tokens, prompt text, gameplay mechanics, private
cards, RNG state, or raw action transcripts.
Each gap entry is machine-readable: capability, admissionStatus, currentState, followUp,
taskRef, and docRef. Use those fields to route follow-up endpoint work for recurrence, member
role management/removal, ring games, public rooms, or declared bot participation instead of treating
the demo as silently complete.
The script marks returned PokerDeck room lobby URLs as candidate_viewable. Finish the proof by
opening viewability.roomUrl in the actual PokerDeck UI and capturing browser evidence. A returned
/j/{code} tournament join URL is useful, but it is not sufficient proof that the room lobby is
viewable. A JSON response from the Management API is not sufficient.
When the organization has a human owner, room creation grants that human owner membership in the
PokerDeck room. The developer signs in through ordinary PokerDeck auth. A pw_mgmt_... token is
server-side control-plane authority only and must never be exposed to the browser or exchanged for a
browser session. Local/staging proofs can use seeded auth bootstrap tooling, but production demos
should use normal sign-in, invitation, or member flows.
Use POKERWORKS_DEMO_ARCHIVE_AFTER_RUN=true for disposable CI-style runs. Existing Rooms supplied
with POKERWORKS_ROOM_ID are never archived by the script.
Current limitations
- The beta public preset catalog admits
six_max_nlhe_sng_v1andscheduled_mtt_nlhe_v1. - Durable recurrence is admitted for daily and weekly public schedule projections. Monthly or richer recurrence remains reserved. Occurrence materialization is also reserved: the recipe reads deterministic occurrence previews, but does not yet generate runtime tournaments from those occurrences or attach schedule/occurrence ids to tournament result webhooks.
- Public schedule pause/archive lifecycle is still reserved. Disposable proofs should use fresh test Rooms or archive the whole Room when appropriate until schedules can be cleaned up independently.
- Custom blind/payout structures can be authored and attached directly at tournament creation; reusable custom tournament-template authoring remains reserved.
- PokerDeck room lobby URLs are returned after room creation; local proofs must run the API with the PokerDeck origin and primary domain that the browser will open.
- Authenticated PokerDeck room lobbies should hydrate from the room-scoped
tenant:<brand>:<tenantId>partition, not the default dev tenant or the quick-game/j/{code}funnel. - Room ring-game catalog reads are admitted; ring-game creation, publish/archive lifecycle, waitlists, seats, live stacks, bot seats, real-money economy, and Table Protocol remain reserved.
- Pending player invitations are part of this example when requested; role changes, removals, bulk invites, email delivery, and invite acceptance remain reserved.
- Trust-mode integrity evidence is read-only support/proof metadata. Public beta rooms remain
human_only; bot seats,bot_only,mixed_declared, and Table Protocol are still reserved until Developer Integrity Rules are fully admitted. - Room analytics are read-first: summary, members, and leaderboards are available; richer stats stay behind Data / Intelligence admission.
Security notes
- Keep the management token in server-side env or Secret Manager.
- Do not paste reveal-once tokens into prompts, browser code, screenshots, or logs.
- Do not use this recipe to create a live public community Room unless moderation, integrity, privacy, and responsible social gaming policy have been admitted.
- Do not expose raw gameplay mechanics, private cards, RNG, action submission, or settlement.