> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/ongoing-projects/phase-4-verbs-and-ceremony-plan.md). # Phase 4 Implementation Plan - Verbs And Ceremony **Date:** 2026-07-08 **Status:** Draft implementation plan **Primary package:** `apps/web` **Scope:** Presentation, audio cues, reduced-motion twins, and user-facing ceremony for existing player verbs. This is a standalone implementation plan. It includes the Phase 4 product constraints, inherited runtime facts, verb inventory, media posture, code touch points, test plan, dogfood script, and exit criteria needed to implement this phase without opening any other planning file. *** ## Purpose Phase 4 makes the existing user verbs feel deliberate and physical. The app already has real local actions: spawning heroes, sending work to heroes, accepting and assigning quests, answering permission gates, approving plans, collecting tomes, receiving notices, joining War Rooms, dispatching scans, and converting inbound channel commands. This phase adds ceremony around those actions without changing their semantics. The product outcome is simple: every supported verb should read as a distinct command in the cockpit, not as another generic button click or toast. The player fantasy is "Warchief commanding real work." Ceremony must strengthen that fantasy while staying honest: no fake progress, no fake urgency, no hidden automation claim, and no reward for wasting tokens or clicking decorative controls. *** ## Phase Principles These rules govern every implementation decision in this plan. 1. **Real work only.** Ceremony can only wrap an action or event that already exists. It must never create resource income, XP, loot, enemy kills, map progress, task execution, hosted persistence, or collaboration guarantees. 2. **One-second legibility.** A user glancing at the cockpit should know which command just happened and whether it needs attention, without reading a log. 3. **Work urgency equals game urgency.** `awaiting_input`, permission gates, guarded actions, plan approvals, quest assignment, and inbound commands are high-ceremony because they unblock real work. Decorative or admin controls stay quiet. 4. **No rewarded waste.** Phase 4 does not score tool volume, mission count, token spend, retries, or busywork. It does not add any numeric reward. 5. **Motion and audio are optional.** Every animated or audible treatment must have a static, visible, and screen-reader equivalent. 6. **Runtime UI remains inspectable.** All user-facing text must be bounded and sanitized. No ceremony may expose raw prompts, transcripts, terminal output, provider payloads, broad local paths, secrets, tokens, headers, cookies, signatures, diffs, or file contents. *** ## Implemented Baseline To Inherit Phase 4 starts after the projection, scanner camp, live enemy, combat playback, scrying, alert focus, world cue, and generated asset handoff work has shipped and passed validation. The following facts are assumed by this plan and should not be rebuilt. ### Projection And Attention * `apps/web/src/lib/gameProjection.ts` is the single browser-local derived game-state authority. * `apps/web/src/store/useGameStore.ts` folds events through the projection and exports selectors such as `selectGameProjection`, `selectGameAlertFocus`, and `selectGameLegion`. * `GameProjection` already includes `attention.flares`, `attention.gates`, `alertFocus`, and `flareCeremony`. * `alertFocus` is the single-pulse authority. The priority ladder is flare, gate, siege, ram, skirmisher, then new camp. Phase 4 must not introduce a second pulse authority in individual components. * `flareCeremony` tracks recent flares. Phase 4 uses it to reduce repeated flare fanfare while preserving full priority and answerability. * Projection persistence remains `localStorage["factionos-game-v1"]`. Phase 4 must not add a new storage key or persist prompt-bearing transient ceremony state. * Replay, reconnect, and mock guards already prevent progress farming. Phase 4 audio and animation must respect the same posture. ### Quest, Camp, And Scan Baseline * Quest Board scanner issue snapshots reconcile into aggregate Null Legion camps through the existing `suggestion_update` path. * The battlefield already renders scanner camp buttons, Dispatch Scouts, Golden Age, failed-scan, mock drill, and reduced-motion static scan states. * Camp inspection opens the real Quest Board issue set. * Dry Banish dismisses current issue cards through the existing Quest Board dismissal path and grants no XP, loot, achievement, camp kill, or progress. * Codebase, analysis, and project scan triggers already exist. Phase 4 may present them as Dispatch Scouts but must not invent a new scan engine. ### Live Tier, Combat, And World Cue Baseline * Linked Quest Board accept and assign actions already record projection-owned pending links; `mission_start` binds `campLinks`. * Linked missions already render strike, counterattack, combo, stage, display HP, and verified burn-down presentation. * The battlefield already renders live skirmishers, rams, gremlins, stacked wraiths, siege pressure, scrying, alert focus, and reduced-motion static twins. * `apps/web/src/lib/worldCues.ts` and `apps/web/src/store/useWorldCues.ts` already route typed world cues through the opt-in audio runtime and synthetic fallback. * Existing world-cue work added no recorded audio files, storage keys, server routes, reward paths, or diagnostic UI. Phase 4 should follow the same restraint. ### Generated Asset Posture * Previously shipped generated sheets are implementation references and media catalog records. They are not browser-loaded directly from source asset folders. * Any Phase 4 visual asset promotion must go through app catalog records, browser-served paths, fallback labels, reduced-motion parity, accessibility copy, cache or mirror notes when relevant, and provenance records. * DOM/CSS remains the default runtime treatment. Generated sheets are crop or reference sources only after promotion is explicitly recorded. *** ## Non-Goals * No new server route. * No new protocol event. * No new persistent browser storage key. * No new persisted `GameProjection` field. * No XP, loot, title, banner, relic, class advantage, scoring, season, or progression grant. * No territory-map, War Tide, War Council, Dawn Report, Battle Report, season, saga, boss, dynamic music stem, or War Games implementation. * No trusted erasure, hosted persistence, hosted identity, remote execution, or production-hosted claim. * No runtime dependency on unpublished planning material. * No audio-only signal. Every audio cue must have a visible and screen-reader equivalent. * No new map-level "send prompt" command. Existing work intake may be decorated; new command verbs are out of scope. * No conversion of low-level diagnostics, export, erasure, provider health, reset, validator cap, or redaction plumbing into game ceremony or rewards. Allowed state is limited to component-local transient UI state such as "button is sealing for 900 ms" or "show this pulse until timeout". That state must not be persisted and must not change any domain outcome. *** ## Existing Inputs To Reuse Phase 4 should compose existing contracts instead of inventing a second action model. | Input | Existing owner | Phase 4 use | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | Projection attention | `apps/web/src/lib/gameProjection.ts` | Read `attention.flares`, `attention.gates`, `alertFocus`, and `flareCeremony` for flare and gate intensity. | | Toast list | `apps/web/src/store/useGameStore.ts` | Town Crier visual treatment and priority framing. | | Audio runtime | `apps/web/src/lib/audioRuntime.ts`, `apps/web/src/store/useAudioRuntimeStore.ts` | Route ceremony audio through existing mute, volume, unlock, fallback, duplicate-guard, and status behavior. | | Hero barks | `apps/web/src/store/useVoiceBarks.ts`, `apps/web/src/store/useFactionVoiceLine.ts` | Reuse faction and hero barks for hero-centered ceremonies. | | World cues | `apps/web/src/lib/worldCues.ts`, `apps/web/src/store/useWorldCues.ts` | Reuse rate-limited world cues for battlefield or attention moments. | | Settings | `apps/web/src/store/useSettingsStore.ts` | Honor `audioEnabled`, `audioVolume`, severity filters, `reduceMotion`, and `mockEnabled` no-persist posture. | | Quest Board state | `apps/web/src/lib/questBoard.ts`, `apps/web/src/lib/questBoardModel.ts`, `apps/web/src/lib/questBoardActions.ts`, `apps/web/src/store/useGameStore.ts` | Decorate accept, assign, dismiss, Banish, and scan actions. | | Battlefield ceremony layers | `apps/web/src/components/battlefield/ScryingAndAlertFocusLayer.tsx`, `apps/web/src/lib/scryingAndAlertFocus.ts` | Add Counsel and reduced flare fanfare without changing alert authority. | | Plan decisions | `apps/web/src/components/PlanWorkpad.tsx` | Decorate approve and reject while preserving in-flight duplicate guards. | | Permission decisions | `apps/web/src/components/PermissionModal.tsx` | Decorate approve and deny while preserving expiry and duplicate guards. | | Channel commands | `apps/web/src/components/orchestration/ChannelCommandPanel.tsx`, command-center channel collection in `useGameStore.ts` | Present inbound commands as Receive the Emissary without changing intake, replay, validation, or conversion. | | Notices | `apps/web/src/components/NoticeBoard.tsx`, notice store paths in `useGameStore.ts` | Present notices as tavern contracts or Warchief decrees while keeping detail displays bounded. | | War Room state | `apps/web/src/store/useWarRoomStore.ts`, `apps/web/src/components/WarRoomPanel.tsx` | Decorate room creation, join, approval, notices, and Banners Unite moments. | | Scroll state | `packages/protocol/src/scrolls.ts`, `apps/web/src/components/ScrollShelf.tsx` | Polish `collect_scroll` and `scroll_collected` moments. | | Achievements display | `apps/web/src/components/AchievementsGallery.tsx`, `apps/web/src/components/battlefield/achievementCelebration.ts` | Keep existing achievement celebrations intact; do not confuse them with tome ceremony. | *** ## Verb Inventory Each verb below must receive a distinct visual treatment, a reduced-motion static twin, bounded accessible copy, and optional audio routed through the existing audio runtime. | Verb ID | User-facing verb | Existing trigger | Primary surfaces | Ceremony outcome | Guardrail | | --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `summon_banner_raise` | Summon | `internal_hero_spawn`, new roster entry, spawning hero state | `HeroRoster`, `HeroCard`, battlefield token | A new hero arrives with a banner-rise frame and faction identity. | No new spawn path and no extra achievement grant. | | `rally_horn` | Rally | `mission_start`, Quest Board accept, existing task or command intake that already sends work | `QuestBoard`, `HeroRoster`, battlefield token, command-center action summaries where already present | Work begins with a compact rally pulse and short cue. | No new map-level send-prompt action. | | `counsel_flare_douse` | Counsel | `awaiting_input` flare and `input_received` clear | `ScryingAndAlertFocusLayer`, `HeroRoster`, `ToastTray`, `NoticeBoard` | Attention flares become a readable call for counsel, then visibly douse when answered. | Repeated flares reduce fanfare only; priority and answerability remain. | | `wax_seal_plan` | Wax-seal plan | `plan_approval` approve or reject and `plan_approval_response` status | `PlanWorkpad`, `ToastTray`, command-center attention rows when already rendering plan approval | Plan decisions feel signed and sealed while preserving duplicate-submit guards. | No hosted orchestration or auto-execution claim. | | `portcullis_gate` | Raise or lower gate | `permission_response`, `guarded_action_decision`, permission gate open or clear | `PermissionModal`, `ScryingAndAlertFocusLayer`, command-center attention rows | Permission and guarded-action requests read as gates; decisions visibly open or close the gate. | Expired and duplicate decision guards remain authoritative. | | `muster_flag` | Muster | Quest assignment to an idle hero, Quest Board accept with selected hero | `QuestBoard`, `HeroRoster`, camp focus banner | Assignment plants a small flag on the chosen hero and source card. | Class advantage is a future hook only; no bonus or penalty in this phase. | | `tavern_contract` | Contract | Quest accept, assign, dismiss, Notice Board post or resolve | `QuestBoard`, `NoticeBoard`, `ToastTray` | Quest and notice cards look like contracts with accept, assign, resolve, and dismiss ceremony states. | Dismissal and resolve semantics stay unchanged. | | `honorable_discharge` | Honorable discharge | `hero_dismissed`, dismissed hero context, dry camp Banish, dismissed quest issue | `HeroRoster`, `HeroCard`, `QuestBoard` | Removal reads as a formal dismissal, never a reward grant. | No Hall of Banners, title, XP, loot, or victory language. | | `banners_unite` | Banners Unite | War Room join, participant approval, connected collaboration state, existing War Room achievement unlock | `WarRoomPanel`, `ToastTray`, `AchievementsGallery`, battlefield remote participant overlay where already mounted | Joining or approving collaboration gets a shared-banner flourish. | No remote execution, hosted identity, or redaction guarantee beyond existing War Room contracts. | | `warchiefs_decree` | Warchief's Decree | `hero_state_override`, high-priority notice, critical local decision, Command Center review action | `NoticeBoard`, `ToastTray`, command-center attention surfaces, hero state controls where already present | Decisive local commands receive senior priority framing. | No new override control and no bypass of local safety copy. | | `receive_emissary` | Receive the Emissary | `command_center_channel_command_update`, local approval or conversion of stored inbound channel command | `ChannelCommandPanel`, `NoticeBoard`, `ToastTray`, command-center attention surfaces | Inbound channel commands arrive as sealed messages, not raw webhook rows. | No raw payload exposure and no implicit trust in providers. | | `dispatch_scouts` | Dispatch Scouts | Quest Board codebase, analysis, or project scan trigger; scanning and done states | `QuestBoard`, `ScannerStateLayer`, battlefield | Scan starts read as scout dispatch with visible static scout state when motion is reduced. | Scan errors and reset controls stay utility/admin, not game progress. | | `collect_scroll` | Collect tome | `collect_scroll`, `scroll_collected` | `ScrollShelf`, `ToastTray`, `AchievementsGallery` | Collected tomes get arcs, rarity beams, shelf fill, and a static rarity twin. | Preserve existing scroll idempotency and Lobster unlock logic; no new loot system. | *** ## Adjacent Rows Kept Out Of Phase 4 The app contains many event-to-game presentation rows that are not Phase 4 player verbs. They may appear in toasts or existing battlefield effects, but this phase must not create new behavior for them. * Tool-use essence and strike vocabulary are already part of combat playback or later progression/economy work. * Mission completion victory banners, XP, titles, loot rolls, and Battle Report presentation are later progression or report work. * File conflict shield blocks, file intent claim pennants, inspector seals, trophy pins, supply-line warnings, low supply horns, and patrol routes remain outside this phase unless they are only being categorized for Town Crier copy. * War Tide, War Council objectives, Dawn Report, First Ten Minutes onboarding, seasons, saga, bosses, named nemeses, dynamic music stems, and War Games are not implemented here. * Low-level admin controls remain quiet: export, local erasure, readiness probes, provider health, reset actions, validation caps, terminal diagnostics, channel replay plumbing, and raw redaction safeguards. *** ## Visual Asset And Media Handoff Phase 4 should be DOM/CSS-first. The generated assets below are available as approved production source material, but are not delivery-ready until promoted through app runtime paths and tests. | Asset ID | Source path | Dimensions | Phase 4 use | Visible equivalent | | -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `war-effort.town-crier.toast-chrome-sheet.v1` | `assets/generated/game-design/phase04/town-crier/town-crier-toast-chrome-sheet.png` | 1672x941 PNG | Town Crier toast chrome, priority ribbons, event icons, work-critical versus game-event distinction. | Herald panel with bounded live DOM copy, priority label, icon well, and screen-reader summary. | | `war-effort.command-ceremony.props-sheet.v1` | `assets/generated/game-design/phase04/command-ceremony/command-ceremony-props-sheet.png` | 1536x1024 PNG | War-table plans, portcullis gates, command tent orders, tavern contracts, emissary envelopes, scout tokens, approval and denial seals, flags, scrolls, route markers. | DOM/CSS props using borders, labels, badges, and static glyphs. | | `war-effort.banners-regalia.sheet.v1` | `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png` | 1536x1024 PNG | Banner-rise, Banners Unite, claim pennant visual hook, wax seals, flare mounts, formal dismissal frames. | Faction-colored banner frame, seal badge, or static regalia chip. | | `war-effort.class-icons.flares-sheet.v1` | `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png` | 1537x1023 PNG | Future class-affinity flare hook on Muster. | Neutral "affinity reserved" data hook only; no class bonus in Phase 4. | | `war-effort.loot.roll-visuals-sheet.v1` | `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png` | 1672x941 PNG | Tome arc, rarity beams, shelf-fill polish for `collect_scroll`. | Static rarity chip and shelf-fill label for reduced motion or failed media. | | `war-effort.reduced-motion.static-badges-sheet.v1` | `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png` | 1672x941 PNG | Static twin vocabulary for alert, rally, disabled, fallback, and loot states. | Typed DOM labels and data attributes; no direct source-path runtime load. | | `war-effort.alliance-war.visuals-sheet.v1` | `assets/generated/game-design/phase10/alliance-war/alliance-war-visuals-sheet.png` | 1672x941 PNG | Banners Unite polish, cooperative ribbons, rally beacons, shared-front markers if promoted. | Existing War Room copy plus static shared-banner badge. | Runtime promotion requirements for any visual asset used by Phase 4: * Add or update an app catalog entry in `apps/web/src/data/mediaCatalog.ts` or document the replacement catalog path in the implementation notes. * Record source, ownership, rights, attribution, and credits updates. * Optimize the asset, strip unnecessary metadata, and record dimensions and byte-size budget. * Serve from an app runtime path; mirror to public-demo assets only when demo parity is explicitly in scope. * Add fallback labels for failed image load and blocked media. * Add reduced-motion static twins and screen-reader copy. * Confirm no embedded media or captions contain raw prompts, transcripts, terminal output, absolute paths, secrets, tokens, or unredacted local data. * Add focused catalog or consuming-surface tests. ### Current Audio Baseline * Background music exists as twelve full MP3 tracks in `apps/web/public/music/`; Phase 4 does not add dynamic stems. * Click voice lines exist for Orc, Human, Elf, and Undead in `apps/web/public/speech/`. * The Lobster faction has no app click voice-line entry in `FACTION_CLICK_VOICE_LINES`. Public-demo `claw-*` clips are not app runtime assets unless rights, catalog, parity, and credits are recorded. * Bark SFX exists for Orc, Undead, and Lobster under `apps/web/public/sfx/`. Human and Elf non-error bark SFX are absent. * Human, Elf, Orc, and Undead error barks currently reuse speech-backed behavior; Lobster error is file-backed. * World cues can play through existing typed cue routing and synthetic fallback. * File-backed world cues for camp hit, camp collapse, ram crash, ram-break triumph, skirmisher red slash, and flare attention are not yet recorded. ### Phase 4 Audio Decisions Session 7 must record a clear decision for each audio gap: * Human bark SFX: promote files if they exist and are approved, otherwise keep visible ceremony with no new file claim. * Elf bark SFX: same policy as Human. * Error bark policy: decide whether speech-backed error barks remain acceptable for Phase 4 or whether dedicated SFX are required before mapping errors to new ceremony cues. * Lobster click lines: promote public-demo clips only with rights, catalog, public-demo parity, credits, and tests; otherwise explicitly defer. * Full verb ceremony cue pack: short cues may include rally horn, summon/banner raise, flare douse, wax seal, plan scroll tear, portcullis raise/drop, target flag, class flare, contract stamp, tome pickup, salute/banner fold, decree gavel, scouts, report unfurl, missive unfurl, shield block, forge hit, lore glint, summon shimmer, low supply horn, trophy pin, scout report, flag flutter, and inspector seal. Only cues with approved files or supported synth fallback may be wired. Audio is never a blocker for visual ceremony. If an audio asset is missing, the app must show the same ceremony visually and accessibly. *** ## Technical Shape ### New Pure Registry Create `apps/web/src/lib/verbCeremony.ts`. Responsibilities: * Define `Phase4VerbId` as the 13 verb IDs in this plan. * Define `VerbCeremonyTone` as `command`, `attention`, `success`, `warning`, `danger`, `collaboration`, `mystic`, and `neutral`. * Define `VerbCeremonySpec` with: * `id` * `label` * `shortLabel` * `tone` * `surface` * `audio` * `motionClass` * `staticClass` * `ariaLabel` * `srSummary` * `dataAttributes` * `privacyLevel` * `assetRefs` * Export `VERB_CEREMONY_SPECS`. * Export selector helpers for common inputs: * `ceremonyForToast(kind, title, severity)` * `ceremonyForQuestAction(action, cardSource, severity)` * `ceremonyForPlanDecision(approved)` * `ceremonyForPermissionDecision(approved, expired)` * `ceremonyForAttentionFocus(alertFocus, flareCeremony)` * `ceremonyForNotice(type, priority, severity)` * `ceremonyForScroll(scroll)` * `ceremonyForWarRoomState(state)` * `ceremonyForChannelCommand(command)` * `ceremonyForHeroState(hero, previousState)` * `ceremonyForScanState(scanState)` * Export safety helpers: * `safeCeremonyText(value, fallback)` * `safeCeremonyTitle(value, fallback)` * `ceremonyDataAttributes(spec)` * `isPhase4VerbId(value)` * `isCeremonyAudioCueSupported(cue)` The registry must be pure TypeScript. No DOM, no audio playback, no React imports, no Zustand store imports, no timers, and no direct reads of browser state. ### Data Attribute Contract Every surface using ceremony should expose stable test attributes: * `data-verb-ceremony-id` * `data-ceremony-tone` * `data-ceremony-surface` * `data-reduced-motion-safe="true"` * `data-ceremony-audio="optional"` or `data-ceremony-audio="none"` * `data-ceremony-privacy="bounded"` For future hooks that must not create Phase 4 behavior, use inert attributes: * `data-ceremony-affinity-hook="reserved"` for `muster_flag`. * `data-ceremony-reward="none"` for Banish, dismissal, and dry discharge. * `data-ceremony-execution="local-existing-action"` for Command Center and Emissary controls. ### Reusable React Pieces Create `apps/web/src/components/VerbCeremony.tsx`. Responsibilities: * `CeremonyFrame`: wraps a surface or card with verb-specific data attributes, static styling, and optional motion classes. * `CeremonyActionButton`: wraps existing buttons while preserving disabled, pending, aria, and click contracts. * `CeremonyPulse`: transient component for non-blocking animation, with a static label when `reduceMotion` is true. * `CeremonyGlyph`: DOM/CSS glyph built from text-safe shapes, borders, and existing color tokens. * `CeremonySrSummary`: hidden screen-reader text for audio and motion equivalents. * `CeremonyAudioStatus`: visible-equivalent label for muted, blocked, unsupported, failed, unavailable, or rate-limited audio. The component must not own business decisions. It receives a spec and renders presentation. ### Optional Audio Hook Create `apps/web/src/store/useVerbCeremonyAudio.ts`. Responsibilities: * Read `audioEnabled` and `audioVolume` from settings. * Use `useAudioRuntimeStore` for cue playback. * Use `buildHeroBarkRequest` where a ceremony has a hero or faction context. * Use `playWorldCue` for world cues only when the cue kind already exists or is added through the app-owned SFX manifest. * Generate stable cue IDs such as `phase4:verb::`. * Rate-limit repeated ceremony cues by verb and source. * Never play during replay unless the existing replay path explicitly allows that cue. * Return visible-equivalent status to callers when audio is muted, blocked, unsupported, failed, unavailable, or rate-limited. No surface should call raw `Audio`, `HTMLAudioElement`, or Web Audio APIs directly. ### CSS Extend `apps/web/src/index.css`. Add ceremony classes under `@layer components`: * `.ceremony-frame` * `.ceremony-frame-command` * `.ceremony-frame-attention` * `.ceremony-frame-success` * `.ceremony-frame-warning` * `.ceremony-frame-danger` * `.ceremony-frame-collaboration` * `.ceremony-frame-mystic` * `.ceremony-frame-neutral` * `.ceremony-action` * `.ceremony-pulse` * `.ceremony-static` * `.ceremony-town-crier` * `.ceremony-scroll-rarity-common` * `.ceremony-scroll-rarity-uncommon` * `.ceremony-scroll-rarity-rare` * `.ceremony-scroll-rarity-epic` * `.ceremony-scroll-rarity-legendary` * `.ceremony-gate-open` * `.ceremony-gate-closed` * `.ceremony-scout-dispatch` * `.ceremony-banner-raise` * `.ceremony-wax-seal` * `.ceremony-contract` * `.ceremony-emissary` * `.ceremony-banners-unite` Rules: * Respect the existing `html[data-reduce-motion="true"]` kill switch. * Never rely on viewport-width font scaling. * Keep labels inside their parent. * Keep cards at the existing radius scale. * Do not introduce decorative orb or one-hue background treatments. * Use DOM/CSS static equivalents for every motion treatment. * Keep compact bottom-rail panels stable; hover, pending, and alert labels must not resize their parent layout. *** ## Surface Requirements ### Town Crier Toasts Touch `apps/web/src/components/ToastTray.tsx`. Requirements: * Resolve a `VerbCeremonySpec` for each toast without changing the toast store. * Preserve severity filtering, max visible count, dismiss behavior, and `role="status"`. * Work-critical toasts stay visually senior to game-event toasts. Game chrome may be richer, but work-critical messages must never look less important. * Add bounded title and body copy. Long text must wrap or truncate without layout overlap. * Add tone, verb label, priority ribbon, icon well, and screen-reader summary. * Do not surface raw payloads or provider details that the original toast did not already expose. Tests: * `apps/web/tests/ToastTray.test.tsx` * Add mapping tests for achievement, warning, error, success, info, permission, plan, scan, War Room, scroll, and channel-command toasts. ### Counsel Flares Touch `apps/web/src/components/battlefield/ScryingAndAlertFocusLayer.tsx` only if the existing layer needs presentation hooks. Keep pure derivation in `apps/web/src/lib/scryingAndAlertFocus.ts` unless no logic changes are needed. Requirements: * Use `alertFocus` and `attention.flares` as the source of truth. * Use `flareCeremony.recentFlares` to reduce repeated fanfare after frequent flares. * The first rare flare can receive full pulse and optional attention sting. * Repeated flares keep full priority but use reduced ceremony. * `input_received` should visibly douse the flare when the existing state clears. * Reduced-motion mode must show a static "Counsel needed" or "Counsel answered" state without pulsing. Tests: * `apps/web/tests/scryingAndAlertFocus.test.ts` * `apps/web/tests/ScryingAndAlertFocusLayer.test.tsx` * Existing battlefield alert tests where layer integration changes. ### Plan Seals Touch `apps/web/src/components/PlanWorkpad.tsx`. Requirements: * Wrap approve and reject buttons with `CeremonyActionButton`. * Approve maps to a wax-seal slam treatment. * Reject maps to a refusal or torn-plan treatment. * Preserve `planDecisionIds` behavior and all duplicate-submit guards. * Preserve disabled, pending, rejected, approved, completed, paused, failed, and cancelled states. * Preserve copy explaining that this does not start hosted orchestration. * Keep plan task and budget details inspectable and unchanged. Tests: * `apps/web/tests/PlanWorkpad.test.tsx` * Duplicate-click protection. * Pending label and aria copy. * Reduced-motion static seal. ### Permission Gates Touch `apps/web/src/components/PermissionModal.tsx`. Requirements: * Wrap approve and deny buttons with `CeremonyActionButton`. * Approve maps to `ceremony-gate-open`. * Deny maps to `ceremony-gate-closed`. * Preserve expired-request disabling. * Preserve requester, action, boundary, rationale, tool detail, expiry, and local runtime decision copy. * Do not hide the existing permission details behind game chrome. Tests: * `apps/web/tests/PermissionModal.test.tsx` * Expired gate disabling. * Duplicate guard or in-flight state if currently covered. * Reduced-motion open/closed static treatment. ### Quest Contracts, Muster Flags, Banish, And Scouts Touch `apps/web/src/components/QuestBoard.tsx`, `apps/web/src/lib/questBoard.ts`, `apps/web/src/lib/questBoardModel.ts`, or `apps/web/src/lib/questBoardActions.ts` only where presentation selectors or testable action labels require it. Requirements: * Codebase, analysis, and project scan buttons map to `dispatch_scouts`. * Scan running state shows scouts in field with a static equivalent. * Accept and assign map to `muster_flag` or `rally_horn` depending on whether a hero assignment is already known. * Quest cards use `tavern_contract` framing without changing their source data, availability, sorting, caps, or filters. * Dismiss maps to `tavern_contract` or `honorable_discharge` only as dry removal, not reward. * Camp focus Banish uses formal dry-discharge ceremony and must preserve the no-reward behavior. * The class-affinity hook is reserved only. Do not add XP, class bonus, recommendation ranking, or penalties in Phase 4. * Keep select accessibility and default idle-hero behavior. * Compact and focused bottom-rail modes must both remain usable. Tests: * `apps/web/tests/QuestBoard.test.tsx` * `apps/web/tests/questBoardActions.test.ts` * `apps/web/tests/questBoardStore.test.ts` * Add reduced-motion and no-reward assertions for Banish. ### Hero Roster And Cards Touch `apps/web/src/components/HeroRoster.tsx` and `apps/web/src/components/HeroCard.tsx`. Requirements: * New or spawning heroes show `summon_banner_raise`. * Active hero transition or newly started work may show `rally_horn`. * Awaiting input heroes may show a compact Counsel badge if the board focus is on their flare. * Dismissed hero context uses `honorable_discharge`. * Preserve roster sort modes, selected hero behavior, capped visible window, forced selected-hero visibility, and existing click voice behavior. * Do not add Hall of Banners, title, XP, or veteran gallery behavior. Tests: * `apps/web/tests/HeroRosterSort.test.tsx` * `apps/web/tests/HeroCard.test.tsx` * Existing hero detail tests if labels or drawer links change. ### Tome Collection Touch `apps/web/src/components/ScrollShelf.tsx`. Requirements: * `collect_scroll` and `scroll_collected` map to `collect_scroll`. * Add rarity-specific visual treatment for common, uncommon, rare, epic, and legendary. * Add shelf-fill polish to collected count. * Preserve collection idempotency, collected-at timestamps, collected-by-hero attribution, detail modal, portal behavior, Escape close, backdrop close, and metadata table. * Preserve the existing five fundamental tomes and existing Lobster unlock logic. Do not create new tomes. * Keep tome ceremony distinct from generic achievement toast presentation. Tests: * `apps/web/tests/ScrollShelf.test.tsx` * Rarity classes and reduced-motion static chips. * Modal behavior remains unchanged. ### Notices And Warchief Decrees Touch `apps/web/src/components/NoticeBoard.tsx`. Requirements: * Notice create, receive, and resolve rows can use `tavern_contract`. * Critical or high-priority local decisions can use `warchiefs_decree`. * Preserve Notice Board detail modal behavior, selected hero/mission filters, canonical payload normalization, caps, and deduplication. * War Room notice convergence must keep existing redaction posture. * Do not promote unresolved notice count into enemy spawns or score. Tests: * `apps/web/tests/NoticeBoard.test.tsx` * Notice store tests if selector behavior changes. ### Emissary Channel Commands Touch `apps/web/src/components/orchestration/ChannelCommandPanel.tsx` and pure command-center view helpers only as needed. Requirements: * Inbound channel command arrival maps to `receive_emissary`. * Local approval, queue conversion, attention conversion, or guarded conversion may show a wax stamp or missive movement if the existing action succeeds. * Preserve provider health, replay metadata, scope labels, state labels, validation status, blocked-category copy, and detail opening. * Do not expose raw headers, cookies, auth payloads, webhook secrets, raw bodies, signatures, prompts, file contents, diffs, logs, terminal output, or broad paths. * Do not imply remote trust, provider correctness, or automatic execution. Tests: * `apps/web/tests/ChannelCommandPanel.test.tsx` * `apps/web/tests/commandCenterUi.test.ts` if view helpers change. * Privacy tests where any copy path changes. ### War Room Banners Unite Touch `apps/web/src/components/WarRoomPanel.tsx`. Requirements: * Successful room join, participant approval, connected collaboration summary, and existing War Room achievement toast can use `banners_unite`. * Preserve local-only, unavailable, create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, and left states. * Preserve optional Worker boundary copy. * Preserve participant limit, six-character join code behavior, in-flight decisions, redacted federation, and room notice handling. * Do not imply remote execution, hosted identity, shared score, or trusted collaboration beyond existing safe outbound frames. Tests: * `apps/web/tests/WarRoomPanel.test.tsx` * `apps/web/tests/WarRoomBattlefieldOverlay.test.tsx` if remote markers change. *** ## Implementation Sessions ### Session 1 - Ceremony Registry And Test Harness Objective: create the pure verb registry and prove every verb has a complete ceremony contract. Tasks: * [ ] Add `apps/web/src/lib/verbCeremony.ts`. * [ ] Add `apps/web/tests/verbCeremony.test.ts`. * [ ] Encode all 13 verb IDs and reject unknown IDs. * [ ] Define tone vocabulary: `command`, `attention`, `success`, `warning`, `danger`, `collaboration`, `mystic`, and `neutral`. * [ ] Add selector helpers for toast, quest, plan, permission, alert focus, notice, scroll, War Room, channel command, hero state, and scan inputs. * [ ] Add data-attribute helpers. * [ ] Add text safety tests for secrets, tokens, empty strings, very long strings, broad paths, raw command text, raw prompt text, file contents, diffs, terminal output, provider payloads, and non-ASCII input. * [ ] Add completeness tests that every verb has labels, aria copy, screen-reader summary, tone, static class, and data attributes. * [ ] Add tests proving selectors do not emit raw command text, prompt text, file contents, broad paths, tokens, provider payloads, or raw channel bodies. Exit criteria: * `verbCeremony.test.ts` passes. * No React component has been changed yet. * Registry exports are safe for use by any surface. ### Session 2 - Town Crier Toasts Objective: convert generic toasts into senior, filtered, accessible Town Crier cards without changing the toast store contract. Tasks: * [ ] Update `ToastTray.tsx` to resolve a `VerbCeremonySpec` for each toast. * [ ] Preserve severity filtering, max visible count, dismiss behavior, and `role="status"`. * [ ] Add a Town Crier header treatment with priority ribbon, verb label, icon well, and bounded body copy. * [ ] Preserve work-critical seniority over game-event presentation. * [ ] Add `data-verb-ceremony-id`, `data-ceremony-tone`, and `data-reduced-motion-safe="true"` attributes. * [ ] Add CSS for `.ceremony-town-crier` and tone variants. * [ ] Extend `ToastTray.test.tsx` for ceremony attributes, unchanged filtering, unchanged cap, dismissal, and screen-reader copy. * [ ] Add mapping tests for achievement, warning, error, success, info, scroll, War Room, permission, plan, scan, and channel-command toasts. Exit criteria: * Existing toast behavior is unchanged except presentation. * Work toasts and game toasts are visibly distinct but share one component path. ### Session 3 - Counsel Flares, Plan Seals, And Permission Gates Objective: make direct attention and decision moments feel decisive while preserving local safety boundaries. Tasks: * [ ] Add Counsel presentation for `awaiting_input` flare focus and `input_received` douse state. * [ ] Use `flareCeremony.recentFlares` to reduce repeated fanfare without suppressing alert priority. * [ ] Keep `alertFocus` as the only pulse authority. * [ ] Wrap `PlanWorkpad` approve and reject buttons with `CeremonyActionButton`. * [ ] Add wax-seal pending state for approve and reject. * [ ] Preserve duplicate-click protection and `planDecisionIds` behavior. * [ ] Preserve "does not start hosted orchestration" boundary copy. * [ ] Wrap `PermissionModal` approve and deny buttons with `CeremonyActionButton`. * [ ] Add portcullis open/closed static treatment to the permission card. * [ ] Preserve expired-request disabling. * [ ] Preserve bounded detail rendering and local runtime decision copy. * [ ] Extend `ScryingAndAlertFocusLayer`, `PlanWorkpad`, and `PermissionModal` tests for ceremony attributes, pending labels, duplicate guards, expired gates, fanfare reduction, and static twins. Exit criteria: * Flares, plan decisions, and permission outcomes are still driven only by existing state and store actions. * Ceremony is visible with motion disabled. ### Session 4 - Quest Contracts, Muster Flags, Banish, And Scouts Objective: give the Quest Board action loop distinct contract, muster, Banish, and scout treatments. Tasks: * [ ] Update `QuestBoardActionBar` trigger buttons so codebase, analysis, and project scans use `dispatch_scouts`. * [ ] Keep existing disabled states for in-flight scans. * [ ] Add scout dispatch static copy to scan-in-progress banners. * [ ] Wrap Quest Card accept, assign, and dismiss actions with ceremony specs. * [ ] Style Quest Cards as tavern contracts without changing card data, caps, filters, sorting, or action availability. * [ ] Add muster flag treatment after a valid hero assignment selection. * [ ] Add inert `data-ceremony-affinity-hook="reserved"` where class-affinity visuals will later attach. * [ ] Preserve select accessibility and default idle-hero behavior. * [ ] Update camp focus Banish to use formal dry-discharge ceremony while preserving current no-reward behavior. * [ ] Extend `QuestBoard.test.tsx`, `questBoardActions.test.ts`, and `questBoardStore.test.ts` only where behavior or selectors are affected. Exit criteria: * Quest actions feel distinct. * Scan dispatch is readable in compact and focused bottom-rail modes. * Banish remains dry and does not imply XP, loot, score, camp kill, or victory. ### Session 5 - Hero Roster, Summon, Discharge, And Tomes Objective: polish the right rail and hero/tome ceremony path. Tasks: * [ ] Add summon banner-rise presentation for newly spawned or spawning heroes. * [ ] Add rally treatment for active transition where the existing state already proves work has begun. * [ ] Add honorable-discharge treatment for dismissed hero evidence where the current UI still shows dismissal context. * [ ] Keep `HeroRoster` sort modes unchanged. * [ ] Keep `HeroCard` selection and audio click behavior unchanged. * [ ] Add `collect_scroll` treatment to `ScrollShelf` rows when a scroll is collected. * [ ] Add rarity beam/static rarity chip for common, uncommon, rare, epic, and legendary tomes. * [ ] Add shelf-fill treatment to the compact Tomes count. * [ ] Preserve the Tomes detail modal, portal behavior, Escape close, backdrop close, and detailed metadata table. * [ ] Extend `HeroRosterSort.test.tsx`, `HeroCard.test.tsx`, and `ScrollShelf.test.tsx` for ceremony attributes and reduced-motion static fallback. Exit criteria: * The right rail shows arrival, active rally, dismissal, and tome collection as deliberate events without disrupting selection, sorting, or details. ### Session 6 - Emissary, Notices, Decrees, And Banners Unite Objective: make inbound collaboration and channel-intake moments read as ceremonial messages while preserving existing safety boundaries. Tasks: * [ ] Update `NoticeBoard.tsx` rows to resolve notice ceremony specs. * [ ] Add Warchief's Decree treatment for critical or high-priority local notices and existing manual override surfaces if present. * [ ] Preserve Notice Board detail modal behavior and canonical payload display rules. * [ ] Update `ChannelCommandPanel.tsx` to use `receive_emissary` for inbound command rows. * [ ] Preserve channel safety copy: no raw headers, cookies, auth payloads, webhook secrets, raw bodies, signatures, prompts, file contents, diffs, logs, terminal output, or broad paths. * [ ] Update `WarRoomPanel.tsx` to use Banners Unite treatment for successful room join, participant approval, and connected collaboration summary. * [ ] Preserve War Room local-only and optional Worker boundary copy. * [ ] Extend `NoticeBoard.test.tsx`, `ChannelCommandPanel.test.tsx`, and `WarRoomPanel.test.tsx`. Exit criteria: * Inbound commands feel like received emissary messages. * Collaboration ceremonies do not imply remote execution, hosted identity, shared scoring, or trusted collaboration guarantees. ### Session 7 - Audio Routing, Media Decisions, And Fatigue Control Objective: add optional ceremony audio while keeping visible state authoritative. Tasks: * [ ] Add `useVerbCeremonyAudio.ts`. * [ ] Map hero-centered ceremonies to existing faction bark kinds where a hero or faction is known. * [ ] Map world-centered ceremonies only to supported world cue kinds or app SFX manifest entries. * [ ] Add per-verb and per-source rate limiting. * [ ] Ensure audio is skipped or downgraded during replay unless explicitly allowed by existing replay behavior. * [ ] Add visible-equivalent feedback for muted, blocked, unsupported, failed, unavailable, and rate-limited audio statuses. * [ ] Record Human bark, Elf bark, error bark, Lobster click-line, and full cue pack decisions in the closeout notes for this plan. * [ ] If any audio file is promoted, add catalog, credits, rights, public-demo parity where needed, and tests. * [ ] Extend `audioRuntime.test.ts`, `worldCues.test.ts`, and add `useVerbCeremonyAudio.test.tsx`. * [ ] Run a simulated high-frequency cue stream and prove no repeated ceremony cue exceeds the rate limit. Exit criteria: * Audio enhances the verbs but never becomes the source of truth. * The app remains quiet under bursts. * Missing media assets are visible, documented decisions rather than hidden assumptions. ### Session 8 - Integration, Reduced Motion, And Dogfood Closeout Objective: prove every verb works once, with audio on, audio off, and motion reduced. Tasks: * [ ] Add or update focused integration tests for all changed components. * [ ] Add a phase-specific dogfood closeout note in this folder or append a dated closeout section to this file. * [ ] Run targeted tests for every touched component and pure helper. * [ ] Run `npm --workspace @factionos/web run typecheck`. * [ ] Run `npm run format:check`. * [ ] Run `npm run lint`. * [ ] If CSS or layout changed substantially, run browser verification on desktop and mobile viewports. * [ ] Record any residual gaps as explicit future work, not hidden assumptions. Exit criteria: * Every verb in the inventory has been triggered once. * With audio enabled, a user can distinguish the major verb families without watching the screen. * With motion reduced, the same verbs remain distinguishable from static labels, tone, layout, and accessible names. *** ## Acceptance Criteria Phase 4 is complete when all of the following are true: * [ ] All 13 verb IDs are represented in `VERB_CEREMONY_SPECS`. * [ ] Every verb has a visual treatment, a static reduced-motion treatment, and accessible copy. * [ ] Every animated or audible treatment has a visible and screen-reader equivalent. * [ ] Toasts use Town Crier framing while preserving severity filtering, dismissal, work-critical seniority, and max-visible cap. * [ ] Counsel flare presentation uses `alertFocus` and `flareCeremony` without creating a second pulse authority. * [ ] Plan approvals and permission decisions retain their current duplicate submission and expiry guards. * [ ] Quest Board accept, assign, dismiss, scan, and Banish actions retain their current state and network behavior. * [ ] War Room, Notice Board, and channel command ceremonies preserve current redaction, local-only, and no-overclaim boundaries. * [ ] `collect_scroll` and `scroll_collected` are visually distinct from generic achievement toasts. * [ ] Audio is optional, rate-limited, and visible-equivalent. * [ ] No ceremony introduces XP, loot, rewards, class advantage, progression, new protocol events, new server routes, or new storage keys. * [ ] Reduced-motion mode still communicates every ceremony with static DOM. * [ ] Generated assets, if promoted, have app catalog records, fallbacks, source/rights records, accessibility labels, and tests. * [ ] Tests cover the registry, key surfaces, audio routing, privacy safety, and reduced-motion static states. *** ## Verification Commands Targeted commands: ```bash npm test -- apps/web/tests/verbCeremony.test.ts npm test -- apps/web/tests/ToastTray.test.tsx apps/web/tests/PlanWorkpad.test.tsx apps/web/tests/PermissionModal.test.tsx npm test -- apps/web/tests/scryingAndAlertFocus.test.ts apps/web/tests/ScryingAndAlertFocusLayer.test.tsx npm test -- apps/web/tests/QuestBoard.test.tsx apps/web/tests/questBoardActions.test.ts apps/web/tests/questBoardStore.test.ts npm test -- apps/web/tests/ScrollShelf.test.tsx apps/web/tests/HeroCard.test.tsx apps/web/tests/HeroRosterSort.test.tsx npm test -- apps/web/tests/NoticeBoard.test.tsx apps/web/tests/ChannelCommandPanel.test.tsx apps/web/tests/WarRoomPanel.test.tsx npm test -- apps/web/tests/audioRuntime.test.ts apps/web/tests/worldCues.test.ts apps/web/tests/useVerbCeremonyAudio.test.tsx npm --workspace @factionos/web run typecheck npm run format:check npm run lint ``` Full regression command: ```bash npm test ``` Browser verification, when layout or CSS changed enough to justify it: ```bash npm --workspace @factionos/web run dev npm run test:e2e ``` *** ## Dogfood Script Run the app in normal mode, then again with audio disabled and reduced motion enabled. 1. Spawn or observe a newly spawned hero and confirm Summon is visible. 2. Start work or accept a Quest Board card and confirm Rally is visible. 3. Assign a Quest Board card to an idle hero and confirm Muster is visible. 4. Trigger a codebase, analysis, or project scan and confirm Dispatch Scouts is visible. 5. Approve and reject a generated plan and confirm Wax-Seal Plan is visible. 6. Approve and deny a permission request and confirm Portcullis Gate is visible. 7. Create an awaiting-input flare and answer it; confirm Counsel and Douse are both visible. 8. Collect a tome and confirm Collect Tome is distinct from a generic toast. 9. Join or approve a War Room participant and confirm Banners Unite is visible. 10. Receive an inbound channel command and confirm Receive the Emissary is visible without raw payload exposure. 11. Post or receive a high-priority notice and confirm Warchief's Decree is visible. 12. Dismiss a hero or dry-Banish focused camp issues and confirm Honorable Discharge is visible without reward language. 13. Confirm Town Crier toasts remain dismissible, filtered, and capped. 14. Repeat the pass with reduced motion and verify each verb still has a static twin. 15. Repeat the pass with audio disabled and verify no meaning is lost. *** ## Risk Register | Risk | Mitigation | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Ceremony implies fake progress. | Use data from existing actions only; add `data-ceremony-reward="none"` where helpful; ban reward wording. | | Audio becomes noisy. | Route through existing runtime and add per-verb/source rate limits. | | Reduced-motion users lose meaning. | Every motion class needs a static label, data attribute, and screen-reader summary. | | Redaction boundary regresses. | Registry helpers sanitize labels; tests include secrets, tokens, broad paths, raw payload shapes, prompts, diffs, terminal output, and file contents. | | Bottom rail forks state. | Reuse mounted compact/focused panel implementations; ceremony wrappers must not duplicate stores. | | CSS causes overflow in compact rails. | Use stable dimensions, wrapping, and component tests for long labels. | | Scope creeps into rewards or progression. | Keep XP, loot, banners, class advantage, Battle Report, War Tide, War Council, Dawn Report, and seasons out of this phase. | | Generated source assets leak into runtime directly. | Promote only through app catalog paths with fallback, accessibility, provenance, and source-path scans. | | Emissary framing overstates trust. | Keep provider health and validation copy; never render raw payloads; label conversion as local approval only. | | Flare fanfare trains blindness. | Use `flareCeremony` to reduce repeated fanfare while keeping priority unchanged. | *** ## Implementation Order 1. Build the pure registry. 2. Update ToastTray first because it exercises copy, tone, privacy, and accessibility without touching action semantics. 3. Update attention and decision surfaces next: Counsel flares, PlanWorkpad, and PermissionModal. 4. Update Quest Board, Banish, and scout dispatch. 5. Update right-rail hero and tome surfaces. 6. Update Notice Board, channel command, and War Room ceremonies. 7. Add optional audio routing and record media decisions once visual/static behavior is stable. 8. Close with dogfood, reduced-motion verification, privacy checks, and regression tests. This order keeps the riskiest action surfaces behind a tested pure registry and lets every later session reuse the same ceremony vocabulary. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/docs/ongoing-projects/phase-4-verbs-and-ceremony-plan.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.