# Documentation Index Documentation is grouped by the question it answers: | Area | Contents | | ------------------------------- | ------------------------------------------------------------------------------------------ | | [Architecture](./architecture/) | Runtime composition, BC interfaces and acknowledgements, shared plugin/command conventions | | [Features](./features/) | Feature behavior, operator guidance, diagrams, and feature-specific plans | | [Operations](./operations/) | Environment setup, database isolation, deployment, and runbooks | | [Proposals](./proposals/) | Pending designs and plans; completed implementation proposals are kept in a dated archive | | [Testing](./testing/) | Test-specific investigations and temporal/qualification notes | ## Architecture - [Bot runtime architecture](./architecture/BOT-ARCHITECTURE.md) - [Condition facts and rules](./architecture/CONDITION-FACTS.md) - [Feature configuration and startup defaults](./architecture/FEATURE-CONFIGURATION.md) - [BC API plane](./architecture/BC-API-PLANE.md) - [BC socket API acknowledgements](./architecture/BC-SOCKET-API-ACKNOWLEDGEMENTS.md) - [Commands and plug-ins](./architecture/FEATURE_COMMANDS_AND_PLUGINS.md) - [Feature configuration and startup defaults](./architecture/FEATURE-CONFIGURATION.md) ## Features - [Veratown User Guide](../USER_GUIDE.md) — player and room-administrator overview of available features and command entry points - [Appearance foundation](./features/appearance/README.md) — pinned-catalog itemsets, observed prerequisite evaluation, and conditional variants - [Shared economy](./features/economy/README.md) - [Shop region](./features/shop/README.md) — region-gated drinks, recipient-consented gifting/releases, self-service favors, and optional helper-a shopkeeper flavor - [Hot Seat](./features/hot-seat/README.md) — opt-in room-scoped bluffing game, disabled by default - [Staged Table](./features/staged-table/README.md) — opt-in five-card-draw game with simulated solo opponents, pinned avatar stages, and recoverable release - [Trick-or-Treat](./features/trick-or-treat/README.md) — configurable map-location game with participant-only emote door unlocks, observed-costume reward doubling, and opt-in timed consequences - [Dilemma prediction game](./features/dilemma/README.md) — disabled-by-default fictional choice game with per-round opt-in and idempotent rewards - [Location Entry Behavior guide](./features/location-entry-behavior/README.md) - [Location Entry Behavior implementation](./features/location-entry-behavior/IMPLEMENTATION_PLAN.md) - [Casino wallet and revised games](./features/casino/README.md) — rolling entry funding and approved slots/roulette with fail-closed location-based access - [Casino games and rewards implementation plan](./features/casino/IMPLEMENTATION_PLAN.md) — approvals, release gates, and later phases - [Roulette wheel helper presentation](./features/casino/README.md#roulette-wheel-helper-presentation) — optional helper-avatar Chat/Emote stages with supervisor-owned wagering, settlement, and private reports - [Truth or Dare](./features/truth-dare/README.md) — operator-approved gameplay gate; each room config remains disabled by default - [Communication and social features](./features/communications/README.md) - [Anonymous Whisperer](./features/anonymous-whisperer/README.md) — Variant B implementation; disabled by default - [Veratown map and doors](./features/map-doors/README.md) - [Location entry messages](./features/location-messages/README.md) — configurable private messages with observed player and room context - [Delayed location appearance](./features/location-appearance/README.md) — apply an existing appearance itemset after a player stays in a location for a configured delay - [Emergency release](./features/emergency-release/README.md) — native-only self-service application of the configured appearance set - [Shower system](./features/shower/README.md) — opt-in, disabled by default; accepts BC room observations and requires wardrobe permission - [Shower system implementation plan](./features/shower/IMPLEMENTATION_PLAN.md) — implementation and remaining qualification status - [Prototype status](./features/status/README.md) - [Helper Bots](./features/helper-bots/README.md) — leased, location-scoped public communications from separately deployed BC accounts - [ABCL Region Feature](./features/abcl/README.md) — separate runtime, database-required active region, helper-only communication, and participant opt-in; see the [player guide](./features/abcl/USER_GUIDE.md) for in-room consent and gameplay - [World administration](./features/world-admin/README.md) ### Feature-specific user guides - [Appearance](./features/appearance/USER_GUIDE.md) - [Shared economy](./features/economy/USER_GUIDE.md) - [Shop](./features/shop/USER_GUIDE.md) - [Hot Seat](./features/hot-seat/USER_GUIDE.md) - [Staged Table](./features/staged-table/USER_GUIDE.md) - [Trick-or-Treat](./features/trick-or-treat/USER_GUIDE.md) - [Dilemma](./features/dilemma/USER_GUIDE.md) - [Location Entry Behavior](./features/location-entry-behavior/USER_GUIDE.md) - [Casino](./features/casino/USER_GUIDE.md) - [Truth or Dare](./features/truth-dare/USER_GUIDE.md) - [Communication and social features](./features/communications/USER_GUIDE.md) - [Anonymous Whisperer](./features/anonymous-whisperer/USER_GUIDE.md) - [Map and doors](./features/map-doors/USER_GUIDE.md) - [Location entry messages](./features/location-messages/USER_GUIDE.md) - [Delayed location appearance](./features/location-appearance/USER_GUIDE.md) - [Emergency release](./features/emergency-release/USER_GUIDE.md) - [Shower](./features/shower/USER_GUIDE.md) - [Prototype status](./features/status/USER_GUIDE.md) - [Helper Bots](./features/helper-bots/USER_GUIDE.md) - [ABCL](./features/abcl/USER_GUIDE.md) - [World administration](./features/world-admin/USER_GUIDE.md) Each feature has a directory. Use `README.md` for the detailed behavior and operator reference, and `USER_GUIDE.md` for its player or room-administrator guide. Keep related design or implementation plans beside these guides using a descriptive name such as `IMPLEMENTATION_PLAN.md`. ## Operations - [Configuration management web service](./operations/ADMIN_WEB.md) — versioned BC room settings and bot-instance profiles, visual stored-map editing, MOTD scheduling, recovery, database-backed operator accounts, and FIDO2 passkeys - [BC source compatibility review, 2026-10-22](./operations/BC_SOURCE_SYNC_2026-10-22.md) — R133 source repin, teleport-pad preservation, refreshed catalogs, and qualification limits - [BC source compatibility review, 2026-10-29](./operations/BC_SOURCE_SYNC_2026-10-29.md) — R133 item color schema, refreshed asset/map catalogs, protocol type updates, and qualification limits - [BC source compatibility review, 2026-11-03](./operations/BC_SOURCE_SYNC_2026-11-03.md) — R133 tether declarations and map metadata, refreshed appearance catalog, and qualification limits - [Offline map analysis and isometric images](./operations/MAP_ANALYSIS.md) - [Standalone local map-draft review GUI](./operations/MAP_ANALYSIS.md#standalone-browser-review-gui) - [Standalone Railway map analysis service](./operations/MAP_ANALYSIS.md#hosted-railway-map-analyzer) - [Runtime environments](./operations/RUNTIME_ENVIRONMENTS.md) - [Railway deployment](./operations/RAILWAY.md) - [HOWTO: Configure Railway supervisor and helper bots](./operations/RAILWAY_HELPER_BOTS_HOWTO.md) - [HOWTO: Enable supervisor-managed ABCL](./operations/RAILWAY_ABCL_HOWTO.md) ## Proposals - [ABDL bot Veratown adapter](./proposals/ABDL_BOT_VERATOWN_ADAPTER_PROPOSAL.md) — proposed pinned-source integration through a narrow Veratown compatibility facade, region and consent gates, and a reviewed upstream update workflow - [ABDL bot as a separate Veratown runtime](./proposals/ABDL_BOT_SEPARATE_RUNTIME_PROPOSAL.md) — proposed native behavior port in an isolated runtime role with region/consent enforcement and cross-process mutation safeguards - [Admin web improvements](./proposals/ADMIN_WEB_IMPROVEMENTS_PROPOSAL.md) — proposed UX, visual consistency, and maintainability improvements - [Shared tile and region geometry](./proposals/MAP_REGION_GEOMETRY_PROPOSAL.md) — implemented; production rollout remains explicitly reviewed and qualified - [Dilemma & Blackmail proposal](./proposals/archive/DILEMMA_AND_BLACKMAIL_PROPOSAL.md) — implemented; archived 2026-10-16 - [Lock management proposal](./proposals/LOCK_MANAGEMENT_PROPOSAL.md) — partially implemented; five lock types supported, further policy expansion pending - [Runtime naming cleanup plan](./proposals/NAMING_CLEANUP_PLAN.md) - [Map position observation sharing](./proposals/MAP_POSITION_OBSERVATION_PROPOSAL.md) — optional Railway-private helper observation MVP implemented; sharing is off by default and historical persistence is deferred - [Map character movement and pathfinding](./proposals/MAP_CHARACTER_MOVEMENT_PROPOSAL_2026-10-29.md) — proposed room-admin-targeted teleports and clearly labeled stepped-teleport routes, validated against the pinned BC client source - [Staged table game](./proposals/STAGED_TABLE_GAME_PROPOSAL.md) — implemented chat and separately consented avatar progression; operator activation remains disabled by default Completed proposals are retained as design history in [the dated archive](./proposals/archive/): - [BC Beta2 alignment and map sign preservation](./proposals/archive/BC_BETA2_AND_MAP_SIGN_PRESERVATION_PROPOSAL.md) — implemented and operator-qualified - [Shared economy and wallet](./proposals/archive/SHARED_ECONOMY_PROPOSAL.md) — implemented - [Hot Seat](./proposals/archive/HOT_SEAT_PROPOSAL.md) — implemented; room config remains independently gated - [Truth or Dare](./proposals/archive/TRUTH_OR_DARE_PROPOSAL.md) — implemented and activation-approved - [Anonymous Whisperer](./proposals/archive/ANONYMOUS_WHISPERER_PROPOSAL.md) — Variant B implemented; disabled pending room-specific decision - [Scoped and permission-aware help generation](./proposals/archive/SCOPED_HELP_GENERATION_PROPOSAL_2026-10-17.md) — implemented; retained as design history - [Command aliases](./proposals/archive/COMMAND_ALIAS_PROPOSAL_2026-10-18.md) — implemented; room-scoped shortcuts with permission-preserving routing - [Hierarchical helper bots](./proposals/HELPER_BOTS_PROPOSAL.md) — location-scoped communication tasks and optional observed startup teleport implemented; graph movement remains deferred - [Earlier map movement and pathfinding design](./proposals/MAP_MOVEMENT_AND_PATHFINDING_PROPOSAL.md) — superseded; retained as design history - [Shop region](./proposals/archive/SHOP_REGION_PROPOSAL.md) — implemented; archived 2026-10-18 - [Roulette wheel helper](./proposals/archive/ROULETTE_WHEEL_HELPER_PROPOSAL_2026-10-27.md) — implemented; archived 2026-10-27 ## Testing - [Temporal test answer notes](./testing/TEST_ANSWER_TEMPORAL.md) - [Bunny timer qualification proposal](./testing/LOCK_QUALIFICATION_TEST_PROPOSAL.md) — superseded; Bunny has no prototype-side timer gate - [Location Entry Behavior BC-native timer observation](./testing/LOCATION_ENTRY_BEHAVIOR_MANUAL_OBSERVATION.md) — optional operator observation; not an activation gate ## Adding or moving documentation - Put shared runtime and protocol contracts in `architecture/`. - Put feature-owned behavior and plans in `features//`. - Put deployment, environment, and operator runbooks in `operations/`. - Put unadopted cross-cutting designs in `proposals/`; keep a feature-specific proposal in that feature's directory. - Move completed proposal records to `proposals/archive/` with an explicit archive date; keep current runtime behavior in the feature or architecture guide and link back to the archived design record where useful. - Put test investigations and test workflow notes in `testing/`. - Preserve concise existing filenames unless a feature guide is being made the directory's `README.md` or a plan is being normalized to `IMPLEMENTATION_PLAN.md`. - Update links in the root `README.md`, this index, affected docs, and `.github/instructions/` whenever a document moves. Prefer relative links between docs and verify their targets after reorganizing.