bzl

self-hosted ephemeral community engine
Log | Files | Refs | README | LICENSE

ONBOARDING_AND_MOD_MESSAGE_IMPLEMENTATION_SPEC.md (8056B)

      1 # Onboarding + Mod Message Implementation Spec (v1)
      2 
      3 ## Purpose
      4 Define a shippable implementation for:
      5 - Mod-to-user priority messaging (`MOD` sender identity in client UI)
      6 - Server-configurable onboarding panes (`About`, `Rules`, `Role Select`)
      7 - Rule reference shortcuts in chat (`&X`)
      8 - Guided tutorial overlays
      9 - A default layout preset that prioritizes onboarding UX on first run
     10 
     11 This spec is implementation-focused and aligned with current panel/rack + mobile screen architecture.
     12 
     13 ## Product goals
     14 - New users understand the community quickly before posting.
     15 - Moderators can communicate urgent guidance without DM friction.
     16 - UX remains usable on small mobile screens first, then scales up.
     17 - Onboarding is the default first-run layout preset on all devices.
     18 
     19 ## Non-goals (v1)
     20 - Full learning management / quizzes.
     21 - Rich workflow automation for moderation.
     22 - End-to-end plugin onboarding integration.
     23 - Cross-instance federated onboarding sync.
     24 
     25 ## Feature scope
     26 
     27 ### 1) Mod Message
     28 **Behavior**
     29 - Moderators/owner can send a direct message as `MOD`.
     30 - Message bypasses DM request acceptance.
     31 - Recipient gets a high-priority notification.
     32 - On open clients, UI focuses the mod thread in the primary view.
     33 
     34 **Identity model**
     35 - Client renders sender as `MOD`.
     36 - Server stores `senderUserId` for audit.
     37 - Non-mod recipients never see the underlying mod username.
     38 
     39 **Controls**
     40 - Rate limit per moderator (anti-spam).
     41 - Recipient can mute future mod messages from the same instance for a time window (except critical notices flag).
     42 - Full moderation log entries are mandatory.
     43 
     44 ### 2) Onboarding Panes
     45 Three admin-configured panes:
     46 
     47 1. **About**
     48    - Rich text content (sanitized HTML subset / markdown-rendered).
     49    - Optional media blocks.
     50 
     51 2. **Rules**
     52    - Ordered list of rules:
     53      - `name`
     54      - `shortDescription`
     55      - `description`
     56    - Optional `requireAcceptance` gate.
     57    - If gate is enabled, users cannot post/chat until accepted.
     58    - Optional read-gate for viewing posts (configurable).
     59 
     60 3. **Custom Role Select**
     61    - Displays selectable self-assignable custom roles.
     62    - Hidden when no self-assignable roles exist.
     63 
     64 ### 3) Rule shortcut in chat (`&X`)
     65 - Typing `&3` expands to a highlighted rule reference chip/card.
     66 - Expansion occurs client-side preview + server-side validation on send.
     67 - If rule index invalid, send is rejected with actionable error.
     68 - Hover/tap on rendered reference opens Rules pane anchored to that rule.
     69 
     70 ### 4) Tutorial overlays
     71 - Entry point: Account panel button (`Show tutorial`).
     72 - Device-specific walkthrough variants:
     73   - Mobile: bottom-nav + screen switching + compose/chat flow.
     74   - Desktop/tablet: panel layout, rack visibility, profile/people/chat flow.
     75 - Supports replay anytime.
     76 - Tracks completion per user/device.
     77 
     78 ### 5) Default layout preset: `onboardingDefault`
     79 - New default preset for first-run sessions.
     80 - Prioritizes onboarding surfaces before advanced layout customization.
     81 - Applies once per user/device, then user customizations persist.
     82 
     83 ## UX per device
     84 
     85 ### Mobile (primary target)
     86 - Bottom nav order: `Account`, `Hives`, `Chat`, `People`, `Profile`, `More`.
     87 - `Maps` hidden by default on mobile.
     88 - Onboarding appears as top-level flow when acceptance required.
     89 - Rules gate CTA stays sticky at bottom: `Accept and continue`.
     90 - Chat composer:
     91   - Hide advanced formatting/emoji reaction controls by default.
     92   - Keep quick actions: `Link`, `GIF/Image`, `Audio`.
     93   - `Send` button full-width and never obscured by nav/safe-area.
     94 - People screen must always render a visible list state:
     95   - loading, empty, or populated.
     96 
     97 ### Tablet
     98 - Same onboarding flow as mobile, with split-pane where width allows:
     99   - left: rules/about list
    100   - right: selected detail.
    101 - Chat list + active chat can coexist in landscape.
    102 
    103 ### Desktop
    104 - Onboarding is a guided preset, not a hard gate unless `requireAcceptance`.
    105 - If side rack is hidden, remaining panels reflow without orphan floating panes.
    106 - Mod message interrupt focuses chat panel but does not destroy current layout.
    107 
    108 ## Data model changes
    109 
    110 ### `instanceConfig.onboarding`
    111 ```json
    112 {
    113   "enabled": true,
    114   "about": {
    115     "content": "sanitized-rich-text",
    116     "updatedAt": 0,
    117     "updatedBy": ""
    118   },
    119   "rules": {
    120     "requireAcceptance": false,
    121     "blockReadUntilAccepted": false,
    122     "items": [
    123       { "id": "r1", "order": 1, "name": "", "shortDescription": "", "description": "" }
    124     ]
    125   },
    126   "roleSelect": {
    127     "enabled": true,
    128     "selfAssignableRoleIds": []
    129   },
    130   "tutorial": {
    131     "enabled": true,
    132     "version": 1
    133   }
    134 }
    135 ```
    136 
    137 ### `users.onboardingState[instanceId]`
    138 ```json
    139 {
    140   "acceptedRulesVersion": 1,
    141   "acceptedAt": 0,
    142   "tutorialCompletedVersion": 1,
    143   "selectedRoleIds": []
    144 }
    145 ```
    146 
    147 ### `messages` additions
    148 ```json
    149 {
    150   "isModMessage": true,
    151   "senderLabel": "MOD",
    152   "auditSenderUserId": "u123",
    153   "priority": "high"
    154 }
    155 ```
    156 
    157 ## API / WebSocket changes
    158 
    159 ### Admin/Mod config
    160 - `onboarding:get`
    161 - `onboarding:updateAbout`
    162 - `onboarding:updateRules`
    163 - `onboarding:updateRoleSelect`
    164 - `onboarding:publish` (increments rules/tutorial version where needed)
    165 
    166 ### User actions
    167 - `onboarding:getState`
    168 - `onboarding:acceptRules`
    169 - `onboarding:selectRoles`
    170 - `tutorial:markComplete`
    171 
    172 ### Mod messaging
    173 - `dm:sendModMessage`
    174 - `dm:modMessageReceived` (high-priority client event)
    175 - `dm:openThread` should accept mod thread ids identically to regular DMs
    176 
    177 ### Rule references
    178 - `chat:resolveRuleRef` (optional helper)
    179 - Server validates final message payload contains valid rule IDs.
    180 
    181 ## Permission rules
    182 - Owner/moderator can manage onboarding content and send mod messages.
    183 - Only owner can toggle `blockReadUntilAccepted`.
    184 - Rule acceptance is per user per instance.
    185 - Server enforces acceptance gate for read/post endpoints and WS events.
    186 
    187 ## Layout preset definition
    188 
    189 Add preset to layout catalog:
    190 
    191 ```json
    192 {
    193   "id": "onboardingDefault",
    194   "label": "Onboarding",
    195   "deviceProfiles": {
    196     "mobile": { "pinned": ["account", "hives", "chat", "people", "profile"] },
    197     "tablet": { "racks": { "left": ["onboarding"], "main": ["hives", "chat"], "right": ["people", "profile"] } },
    198     "desktop": { "racks": { "left": ["onboarding", "hives"], "main": ["chat"], "right": ["people", "profile"] } }
    199   },
    200   "firstRunOnly": true
    201 }
    202 ```
    203 
    204 Preset application rules:
    205 - Applied when no prior user layout exists.
    206 - If onboarding disabled, preset gracefully degrades to existing default.
    207 - User edits override preset immediately and persist.
    208 
    209 ## Rollout plan
    210 
    211 ### Phase 1: Data + gating foundation
    212 - Add onboarding config/state schemas.
    213 - Implement rules acceptance gate checks server-side.
    214 - Add migration defaults for existing instances/users.
    215 
    216 ### Phase 2: Mobile-first onboarding UX
    217 - Build About/Rules/Role Select screens.
    218 - Implement `onboardingDefault` first-run preset.
    219 - Ensure safe-area/nav spacing for chat composer and send button.
    220 
    221 ### Phase 3: Mod message + rule refs
    222 - Add mod message send/receive path and audit logging.
    223 - Add `&X` parsing, validation, and rendering.
    224 - Add notification + focus behavior.
    225 
    226 ### Phase 4: Tutorial overlays + polish
    227 - Implement per-device tutorial flows.
    228 - Add replay entry point in Account.
    229 - Add analytics counters (started/completed/skipped).
    230 
    231 ## Acceptance criteria
    232 - People pane always renders on mobile (no blank screen state).
    233 - DM/mod thread open action always routes to a visible chat context.
    234 - Send button never overlaps bottom nav on supported mobile sizes.
    235 - With rules gate enabled, blocked actions return clear errors and CTA to rules.
    236 - `&X` references resolve correctly and render consistently in chat history.
    237 - First-run users see onboarding preset by default on each device class.
    238 
    239 ## UX ideas for later polish
    240 - Rule chips in chat show color-coded severity (info/warn/critical).
    241 - “Why this rule exists” collapsible rationale to reduce moderation friction.
    242 - Progressive disclosure in composer: reveal rich tools only after tapping `+`.
    243 - Smart onboarding resume: return user to last incomplete pane.
    244 - Contextual tutorial nudges when user fails an action repeatedly.