veratown-prototype

Scoped & Permission-Aware Help Generation — Feature Proposal

Status: Implemented 2026-10-17. This archived proposal records the design; current behavior and contracts are documented in the command and runtime architecture guides.

Purpose and scope

Propose one shared help-generation capability for /bot help, !help, and /bot <feature> help. Generate help from structured command metadata and the requester’s current context, rather than exposing every registered command or maintaining separate, potentially inconsistent command lists.

Help must answer: What can this player do here, with their current permissions? A non-admin must never see admin-only command names, syntax, descriptions, examples, aliases, or navigation hints in bot-generated help. An administrator sees administrative help only for scopes where their actual permissions apply; being an admin in one room grants nothing in another.

This is a shared command-system capability, not an independent game. It does not grant permissions, enable disabled features, perform command actions, or replace authorization at execution time. All types and components introduced below are proposed contracts, not claims about existing implementation.

Product rules

/bot help and !help produce the same permission-filtered global overview. List available feature summaries and safe navigation to feature help rather than dumping every nested command. Preserve the existing empty native /bot help path, subject to the same filtering.
/bot <feature> help and !<feature> help show only visible commands within that feature. Support nested command scopes, such as /bot world map help, only where declared by the command suite. Do not use raw string-prefix matching that mixes unrelated feature names.
Filter by validated sender identity, current room membership, room-specific permissions, registered/running feature state, effective configuration, applicable observed location, and declared channel restrictions.
Non-admins receive no administrative entries, including entries described as “room admins only”. Labelling a forbidden command is not sufficient: omit it.
A feature containing no visible commands has no global-help entry. A mixed feature may remain visible, but its summary and examples must describe only its visible capabilities.
Unknown scopes and scopes entirely hidden from the requester return the same neutral private response: “No help is available for that scope.” Do not reveal whether a hidden feature or administrative subcommand exists.
All help replies are private, including responses to !help sent publicly. Never fall back to room chat when private delivery fails.
Unknown-command replies, usage errors, suggestions, guided-session hints, and feature-specific fallback help use the same filtered descriptors. No legacy fallback may append an unfiltered help string.
Help evaluation is read-only. It must not execute handlers, submit access codes, grant credits, reserve game sessions, or modify configuration.
Directly typing a hidden command must still fail its normal authorization checks. Help visibility is not a security boundary by itself.

Scope and permission examples

These are intended outcomes, not a new list of enabled commands.

Request / context	Proposed result
Non-admin requests `/bot help`	Available player-facing feature summaries; no world, Bunny, or door administrative command details.
Room admin requests `!help`	Player summaries plus administrative scopes they may access in this room; private reply only.
Non-admin requests `/bot door help`	Only authorized player-facing door/keypad guidance; no management, group, or access-management syntax.
Non-admin requests `/bot world help`	Neutral unavailable-scope response, without admin syntax or hints.
Player requests `/bot casino help` outside a configured game location	Available wallet/general information; no location-restricted game commands.
Player requests casino help at an authorized game location	Only enabled, configured games available to that player at that location.
Admin loses room-admin status before requesting another page	Recomputed player-only help; no reuse of a previously privileged page.

Administrative management help may remain available to an authorized admin when the corresponding player feature is disabled, if the management command itself is available. Conversely, public informational commands such as wallet or fairness help need not disappear merely because wagering is unavailable. Availability belongs to individual capabilities, not a blanket feature gate.

Command metadata and policy ownership

Command suites declare bounded, typed help descriptors alongside their registrations. Use one authoritative descriptor for each documented command path, including subcommands handled internally by a parent handler. A parser registration alone is not a complete catalog of such subcommands.

Proposed field / contract	Validation / intent
`id`, `commandPath`	Stable unique ID and normalized tokenized command path; references a live handler or a declared branch of one.
`featureId`, `scopePath`	Explicit feature ownership and scope hierarchy; no feature inference from arbitrary strings.
`summary`, `usage`, `examples`	Bounded reviewed text; examples belong to one visible descriptor and use placeholders, never real secrets.
`aliases`	Supported aliases mapped to the same descriptor and policy; no separate weaker visibility path.
`accessPolicy`	Explicit feature-owned permission predicate, reused with execution checks where practical.
`availabilityPolicy`	Read-only predicate for effective configuration, feature gates, channel, location, or relevant session state.
`overviewSummary`	Safe player/admin summaries selected from visible capabilities; no administrative text in a shared player summary.
`displayOrder`, `localeKey`	Stable sorting and optional localization; localization must not bypass filtering.

Missing or malformed help metadata means not discoverable, with an operator validation diagnostic. It never defaults to public visibility. Migration must complete the descriptor inventory before the new renderer is enabled, so fail-closed metadata does not silently strand legitimate commands.

Feature adapters own channel-specific authorization. The shared help service calls injected policy contracts but does not implement feature permission rules or import feature services directly. The composition root wires the existing room-admin and observation capabilities into these contracts. Predicates must be bounded, side-effect-free, and deny visibility on errors or missing context.

Permission and availability predicates may be separate so an authorized admin can manage a disabled feature. Transient argument validation or insufficient wallet balance need not hide a command: help describes accessible capabilities, not a guarantee that every possible invocation will succeed.

No new MongoDB collection is required for the baseline. Static command syntax and reviewed descriptions belong with command registrations; live configuration and access observations remain owned by existing services. Optional future DB-managed explanatory text must never define permissions, add executable commands, or enable a feature. Any presentation settings must preserve private replies and mandatory permission filtering.

Generation, lifecycle, and consistency

Normalize supported native/bang input using the shared parser, preserving existing sender/target validation and longest registered-prefix dispatch.
Resolve a declared help request, without treating an arbitrary trailing help inside free-form arguments as a request. Document reserved help paths and detect collisions during registration.
Build a request context from authoritative observations: member number, room key, channel, membership, permission revision/freshness, effective configuration revision, and relevant location/session observations.
Read a consistent catalog snapshot, select the requested scope, and evaluate permission and availability for each candidate descriptor.
Remove denied descriptors before grouping, composing examples, counting entries, rendering headings, or generating suggestions/navigation. Parent headings are shown only when visible descendants remain.
Render deterministic, bounded output. Split oversized help on descriptor boundaries, with continuation links containing only visible scopes. Apply per-member rate limits and existing outbound queue limits.
Revalidate requester presence and relevant context revisions immediately before enqueueing each private chunk. Recompute or suppress stale privileged content when permissions, room, configuration, location, or catalog change.

Initial implementation should recompute filtered results per request, not cache rendered help globally. Immutable syntax/localization templates may be cached. If filtered caching is introduced later, its key and invalidation must include member, room, channel, permissions, configuration, location/session, locale, and catalog revision. Never share privileged output between users.

Registration and disposal update handler/help metadata consistently. Plugin stop removes its descriptors and prevents pending help work from emitting stale entries. Startup validates duplicate IDs, unresolved aliases, scope cycles, reserved help-path collisions, and descriptors without a dispatch owner. A help failure yields a neutral private response, not the raw catalog or a policy exception containing sensitive command details.

Delivery uses the existing communication capability. Enqueue-time checks cannot retract a whisper already dispatched; describe delivery as unconfirmed unless supported by existing communication evidence, and do not claim atomic permission checking across the external transport.

Privacy, authorization, and migration

Resolve identity and scope from server-observed context, not command arguments. A requester cannot ask for another player’s permissions or spoof an admin role or room key.
Unknown or stale authorization state fails closed for restricted entries. If current membership cannot be established, suppress room-scoped help.
Hidden entries must not leak through totals, empty admin section headings, alternate aliases, locale variants, examples, autocomplete/suggestions, or exception messages. Do not interpolate raw catalog text into denial replies.
Do not persist help requests as permission profiles. Use bounded redacted diagnostics for catalog/policy failures, consistent with existing diagnostics ownership; do not log rendered privileged help or private command arguments.
No BC packet bypass, additional socket, or cross-feature service import. Inject shared context/policy ports and CharacterCommunicationApi from src/app/start.ts.
Preserve command execution checks, including checks on every guided-session step. Recheck permissions independently when a player invokes a command after reading help.

The existing parser’s private helpText() renders all registrations without a requester context and is also appended to unknown-command responses. Existing feature suites additionally own local help strings; casino help already filters some game entries by member/location. Door administration’s service currently returns help before its admin check. These are migration surfaces, not a claim that every existing execution path lacks authorization.

Inventory parser-level help, nested feature help, bare-feature fallbacks, usage errors, guided-session prompts, and legacy message listeners. Replace or guard all bot-facing help paths with the shared visibility policy. Preserve existing casino location/configuration restrictions and do not infer admin permission from descriptive text. Operator-only CLI documentation is outside player help.

UML

Component diagram

flowchart LR
    Root["src/app/start.ts"] --> Parser["BotCommandParser"]
    Root --> Help["ScopedHelpService"]
    Suites["Feature command suites"] --> Parser
    Suites --> Catalog["CommandHelpCatalog"]
    Suites --> Policies["Feature-owned access and availability policies"]
    Parser --> Help
    Help --> Catalog
    Help --> Context["Injected HelpContextPort"]
    Help --> Policies
    Help --> Renderer["HelpRenderer"]
    Help --> Comms["Injected CharacterCommunicationApi"]
    Context --> Observations["Room membership / permissions / configuration / location"]
    Comms --> BC["Existing BcClient actions"]

Class diagram

classDiagram
    class CommandHelpDescriptor {
        +id
        +commandPath
        +scopePath
        +usage
        +examples
        +accessPolicy
        +availabilityPolicy
    }
    class CommandHelpCatalog {
        +register(descriptor) Dispose
        +snapshot()
        +validate()
    }
    class ScopedHelpService {
        +request(sender, scope, source)
        +visibleDescriptors(context, scope)
        +stop()
    }
    class HelpContextPort {
        <<injected contract>>
        +current(sender, source)
        +isCurrent(context)
    }
    class HelpPolicy {
        <<feature-owned contract>>
        +isAllowed(context)
        +isAvailable(context)
    }
    class HelpRenderer {
        +overview(visibleDescriptors)
        +scope(visibleDescriptors)
        +chunks(renderedHelp)
    }
    CommandHelpCatalog o-- CommandHelpDescriptor
    ScopedHelpService --> CommandHelpCatalog
    ScopedHelpService --> HelpContextPort
    ScopedHelpService --> HelpPolicy
    ScopedHelpService --> HelpRenderer

Use-case diagram

flowchart LR
    Player((Player)) --> Global([Request global help])
    Player --> Scoped([Request feature help])
    Admin((Authorized room admin)) --> AdminHelp([See permitted administrative help])
    Owner((Feature maintainer)) --> Register([Declare metadata and policies])
    Global --> Filter([Filter using current context])
    Scoped --> Filter
    AdminHelp --> Filter
    Register --> Catalog[(Live command catalog)]
    Catalog --> Filter
    Filter --> Private([Privately show visible capabilities only])

Activity diagram: scoped help request

flowchart TD
    Start([Help requested]) --> Validate{Valid sender and target?}
    Validate -->|No| Ignore([Ignore])
    Validate -->|Yes| Context[Load current requester context]
    Context --> Select[Select declared scope from catalog snapshot]
    Select --> Filter[Evaluate access and availability; omit denied entries]
    Filter --> Any{Visible entries?}
    Any -->|No| Neutral[Prepare neutral unavailable-scope reply]
    Any -->|Yes| Render[Build safe headings, usage, examples and chunks]
    Neutral --> Fresh{Context still current?}
    Render --> Fresh
    Fresh -->|No| Recompute[Recompute or suppress stale response]
    Recompute --> Context
    Fresh -->|Yes| Send[Enqueue private reply only]
    Send --> End([Dispatch unconfirmed; no public fallback])

State machine

stateDiagram-v2
    [*] --> Requested
    Requested --> Ignored: invalid sender or target
    Requested --> Evaluating: valid help request
    Evaluating --> Rendering: visible entries
    Evaluating --> NeutralReply: unknown or inaccessible scope
    Rendering --> Revalidating
    NeutralReply --> Revalidating
    Revalidating --> Evaluating: changed context, bounded recomputation
    Revalidating --> Suppressed: departed, stopped, or retry bound reached
    Revalidating --> Dispatching: context current
    Dispatching --> Complete: private chunks enqueued
    Dispatching --> Suppressed: delivery failure or changed context
    Complete --> [*]
    Suppressed --> [*]
    Ignored --> [*]

Sequence / communication diagram

sequenceDiagram
    participant Player
    participant Parser as BotCommandParser
    participant Help as ScopedHelpService
    participant Context as HelpContextPort
    participant Catalog as CommandHelpCatalog
    participant Policy as Feature-owned policies
    participant Renderer as HelpRenderer
    participant Comms as CharacterCommunicationApi
    Player->>Parser: /bot help, !help, or /bot feature help
    Parser->>Help: validated sender, declared scope, source
    Help->>Context: current requester context
    Context-->>Help: membership, permissions and availability revisions
    Help->>Catalog: consistent scope snapshot
    Catalog-->>Help: candidate descriptors
    loop Candidate descriptors
        Help->>Policy: evaluate read-only access and availability
        Policy-->>Help: visible or denied
    end
    Help->>Renderer: visible descriptors only
    Renderer-->>Help: bounded private help chunks or neutral reply
    loop Before each chunk
        Help->>Context: revalidate relevant context
        Context-->>Help: current or changed
        alt Context current
            Help->>Comms: whisper requester only
        else Context changed
            Help->>Help: recompute or suppress; never send stale privileged text
        end
    end

Decisions and acceptance criteria

Approve the global overview/detail split, supported nested help scopes, reserved help-path conventions, command-level availability semantics, neutral inaccessible-scope wording, output/rate bounds, and the inventory/migration plan. Filtering and private-only delivery are mandatory, not configurable relaxations. Do not activate centralized generation until legacy bot-facing help routes are migrated or guarded.

Acceptance requires tests covering:

Equivalent /bot help and !help visibility, empty native /bot, supported channels, normalization, longest-prefix routing, and wrong-target rejection.
Non-admin, current-room admin, admin-of-another-room, missing membership, and unknown/stale permission contexts. Assert forbidden names, syntax, examples, aliases, navigation and administrative descriptions are absent, not merely labelled restricted.
Mixed player/admin scopes, entirely hidden features, unknown scopes, nested help, bare-feature fallbacks, usage errors, suggestions, guided-session hints, and legacy listeners. Hidden and unknown scopes use identical neutral text.
Registered nested commands and internally dispatched subcommands; missing metadata, duplicate descriptors, reserved-path collisions, alias equivalence, and unrelated scope names sharing a textual prefix.
Disabled/malformed configuration, available management of disabled features, preserved wallet/fairness help, per-member casino location gating, and session availability predicates that do not mutate game state.
Role revocation, room departure/change, location/configuration change, plugin disposal, and catalog changes between generation and each chunk’s enqueue. No previously privileged cached response may survive these changes.
All help is private, including public !help; communication failures never trigger public fallback. Bounded output, stable ordering, continuation pages, rate limits, locale variants, and denial/error paths reveal no hidden entries.
Direct execution and guided steps still independently reject unauthorized actions. Requesting help performs no wallet, session, configuration, or external action mutations beyond private communication.

The implementation adds the shared catalog, scoped visibility filtering, bounded private rendering, request-context revalidation, and command-suite metadata migration. Runtime documentation and regression tests describe the implemented contract. Existing command-time authorization remains independent of help visibility.