> 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/game-design/02-core-gameplay-and-player-verbs.md).

# Core Gameplay And Player Verbs

**Project:** FactionOS — The War Effort **Document role:** Core gameplay spec / interaction model

## 3. The Work→Fun Exchange Table

The heart of the design. Left column already exists in the protocol (`packages/protocol/src/events.ts`); right column is the game meaning.

| Real event (existing)                                            | Game consequence                                                                                                                                        | Juice (existing assets)                          |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `internal_hero_spawn` / hero spawn                               | Hero standee walks onto battlefield, banner raised                                                                                                      | Spawn entrance CSS treatment, `active` bark      |
| `tool_use: Bash`                                                 | **Fire essence** +N; War Mill/Salt Forge smoke puff                                                                                                     | SFX cue (25-cue map exists)                      |
| `tool_use: Read/Grep/Glob`                                       | **Lore essence** +N; fog-of-war pushback around hero                                                                                                    | subtle glint                                     |
| `tool_use: Edit/Write`                                           | **Forge essence** +N; hammer-strike flash on hero                                                                                                       | forge SFX                                        |
| `tool_use: Task` (subagent)                                      | Hero **summons a peon** — child standee mini-unit tethered to parent (subagent lineage already tracked)                                                 | summoning shimmer                                |
| `mission_start`                                                  | War horn; hero marches to a map sector (see §5 territory)                                                                                               | faction `active` bark                            |
| `mission_complete`                                               | **Victory banner** plants at the sector; XP award; loot roll (§7)                                                                                       | celebration burst (exists), `complete` bark      |
| `mission failed / error`                                         | Wraith spawns; hero kneels (dimmed state exists)                                                                                                        | `error` bark                                     |
| `awaiting_input`                                                 | Hero raises a **signal flare** — the single most urgent visual in the game                                                                              | dashed ping treatment (exists) + attention sting |
| `plan_generated` → approved → completed                          | **Battle plan ritual**: plan steps render as a war-table overlay; completion = coordinated strike animation                                             | Strategist achievement (exists)                  |
| `permission_request` / guarded action                            | **Gate challenge**: the hero stands at a gate awaiting the Warchief's seal                                                                              | horn sting                                       |
| `scroll_collected`                                               | Tome flies to the **Library** building; collection UI tick                                                                                              | scroll shimmer                                   |
| `achievement_unlocked`                                           | Tiered fanfare (bronze→platinum styling exists)                                                                                                         | radial burst (exists)                            |
| `file_conflict_prevented`                                        | **Shield block** flash — two heroes' collision parried                                                                                                  | shield clang                                     |
| Notice Board post/resolve                                        | Courier raven flies between hero standees                                                                                                               | wing flap                                        |
| Inbound channel command received (channelCommandManager, exists) | **An emissary arrives** — a courier walks to the keep gate bearing a missive from distant lands; local approval converts it to a queued task (a muster) | gate horn + missive unfurl                       |
| War Room peer joins                                              | Allied army appears on the shared front (§8)                                                                                                            | "Banners Unite" (exists)                         |
| Tokens in/out                                                    | **Mana** flow meter per hero (already in HeroMetrics)                                                                                                   | ambient                                          |
| Cost estimate USD                                                | **War chest** drain — spend framing, feeds efficiency score                                                                                             | none (deliberately quiet)                        |
| `test_failure` / `test_pass` (live events, exist)                | **Skirmisher** spawns instantly at the sector owning that test's path — dies the moment the test passes again                                           | red slash sting                                  |
| `build_error` → `build_fix` (live events, exist)                 | **Ram at the gate** → the fix kills it *on the spot*. The tightest feedback loop in the game — seconds, not scan-cycles                                 | crash → triumphant sting                         |
| `ts_errors` / `lint_error` (live events, exist)                  | **Gremlins** — tiny scuttling nuisance units with a count badge; never blocking, purely ambient pressure                                                | faint skitter                                    |
| `loop_update` (recurring loops, exists)                          | Hero walks a visible **patrol route** — a circuit traced on the map; loop health = patrol posture                                                       | rhythmic footsteps                               |
| `plan_budget_warning` / `plan_budget_exhausted` (exist)          | Hero's **supply line thins** — mana bar flickers; exhausted = hero plants a *resupply flag* (real meaning: plan needs re-scoping)                       | low horn                                         |
| `hero_evidence_update` (exists)                                  | **Trophy pinned to the hero's banner** — verified proof of work becomes visible regalia                                                                 | pin tap                                          |
| `idle_suggestion` / `suggestion_update` (exist)                  | **Scout reports** — rumor markers on the map hinting at the next quest; clicking one opens the suggestion                                               | whisper                                          |
| `file_intent_declare` / `clear` (exist)                          | Hero **plants a claim pennant** on the sector — visible "dibs" that pairs with the shield-block row above                                               | flag flutter                                     |
| `task_verification` (exists)                                     | **Inspector's seal** — verified banners glow gold; unverified banners stay plain cloth                                                                  | wax-stamp                                        |

**Second-pass finding (2026-07-03):** the first pass under-used the *live* dev-health events above — it assumed test/lint/build signals only arrived via the Quest Board scanners. They stream in real time (`events.ts`), which means the Null Legion can *react within seconds* of the codebase breaking and die within seconds of it being fixed. Slow scanner camps (strategic layer) + live skirmishers (twitch layer) = two tempos of enemy, one data source each, both already shipped.

**Rule:** every row must be legible at the fun-per-glance level *and* deepen on click (existing drawers: HeroDetailDrawer, MissionDetailDrawer already provide the deep layer).

### Existing Generated Asset References

Before making new ceremony artwork, check `manifest.md`. Relevant production-generated assets already present for this verb layer:

* `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png` covers victory banners, claim pennants, resupply flags, trophy pins, inspector seals, flare mounts, and title/regalia frames.
* `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png` covers class icons, affinity flares, and class-colored trims.
* `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png` covers scroll arcs, rarity beams, shelf-fill polish, relic reveals, and aura effects for the `collect_scroll` ceremony.
* `assets/generated/game-design/phase04/town-crier/town-crier-toast-chrome-sheet.png` covers herald toast chrome for game-event ceremony. Work-critical toasts still stay visually senior per section 11.
* `assets/generated/game-design/phase04/command-ceremony/command-ceremony-props-sheet.png` covers command-plan, gate, order, contract, missive, scout, route marker, approval, and denial props for the command verb ceremonies below.
* `assets/generated/game-design/phase03/strike-vocabulary/strike-vocabulary-effects-sheet.png` covers tool-family strike effects for mission-event command playback.
* `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png` covers static badge equivalents for command playback, urgency, and ceremony effects when motion is reduced.

***

## 3A. The Player's Verbs (second pass — the first pass watched; this one *commands*)

Objective flaw in pass one: it designed a great *spectator* layer but never enumerated what the player actually **does**. Fun requires verbs. Every verb below already exists in the protocol (client→server messages in `events.ts`) or in shipped UI flows — the game layer's job is to give each one **ceremony** (sound + animation + visible consequence), because a verb without ceremony is a form submission:

| Real verb (exists)                                           | Game framing                                                                                                                                            | Ceremony on use                                                                                              |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Spawn hero                                                   | **Summon a champion**                                                                                                                                   | banner-raise + faction pick bark (exists)                                                                    |
| Send prompt / orders (orchestration intake)                  | **Rally order** from the command tent                                                                                                                   | war horn, hero salutes and marches                                                                           |
| Answer `awaiting_input`                                      | **Counsel** — the flare is doused                                                                                                                       | flare extinguish + Swift Command timer visibly banked                                                        |
| `plan_approval` approve/reject                               | **Seal or refuse the battle plan**                                                                                                                      | wax-seal slam / plan scroll torn                                                                             |
| `permission_response` / `guarded_action_decision`            | **Open the gate / hold the gate**                                                                                                                       | portcullis raise or drop                                                                                     |
| Accept quest (Quest Board)                                   | **Muster against a Blight camp**                                                                                                                        | target flag plants on the camp; class-advantage flare when the mustered hero's class favors the target (§6A) |
| Post / resolve notice                                        | **Tavern contract** posted / fulfilled                                                                                                                  | raven departs / contract stamp                                                                               |
| `collect_scroll`                                             | **Loot the tome** — *the one pure-game click we have; make it delicious*                                                                                | scroll arcs into the Library, rarity-tiered shimmer                                                          |
| Dismiss hero                                                 | **Honorable discharge** → Hall of Banners (§6)                                                                                                          | slow salute, banner folds                                                                                    |
| Join War Room                                                | **March to the shared front**                                                                                                                           | "Banners Unite" fanfare (exists)                                                                             |
| `hero_state_override`                                        | **Warchief's decree** (manual state correction)                                                                                                         | brief gavel                                                                                                  |
| Trigger codebase/analysis/project scan (Quest Board, exists) | **Dispatch scouts** — riders leave the keep; while the scan runs, scouts are visibly in the field; completion is the patrol report (new camps revealed) | scout horn, hoofbeats fading; report unfurls on done                                                         |
| Approve/convert inbound channel command (exists)             | **Receive the emissary** — accept the missive into the war effort                                                                                       | wax stamp; missive flies to the task queue                                                                   |

Two design rules fall out of this table:

1. **Verb scarcity is a feature.** The player has \~13 verbs and most fire a few times an hour. Each use must feel *senior* — thick, chunky, physical. Budget juice per-verb, not per-frame.
2. **`collect_scroll` is precious.** It is the only verb with zero real-work meaning — pure loot pickup. It is therefore the pressure valve where the game can be maximally game: arc trajectories, rarity color beams, library shelf filling visibly. Never add more zero-meaning clicks; polish this one.

*Fourth-pass hold-out graduation:* **Dispatch Scouts** and **Receive the Emissary** were promoted from `12-utility-admin-holdout-inventory.md` because both are real work actions with genuine game meaning — one reveals the Legion (fog/reveal is a core mechanic), the other is real work arriving from outside (the headless-messaging half of the product vision). Neither is an invented click; scan-error plumbing and channel provider health stay held out.

## 3B. Implemented Command Substrate

These shipped systems are the real command layer behind the verbs above. They should be framed as ceremony, urgency, and readable battle state rather than as separate dashboard widgets.

### Missions

Code references: `packages/protocol/src/missions.ts`, `packages/protocol/src/events.ts`, `apps/server/src/managers/missionManager.ts`, `apps/server/src/lib/eventIngest.ts`, `apps/web/src/store/useGameStore.ts`, `apps/web/src/components/MissionLog.tsx`, `apps/web/src/components/MissionDetailDrawer.tsx`, `apps/web/src/components/MissionTimeline.tsx`. Focused tests: `apps/server/tests/eventIngest.test.ts`, `apps/web/tests/MissionLog.test.tsx`, `apps/web/tests/MissionDetailDrawer.test.tsx`, `apps/web/tests/MissionTimeline.test.tsx`.

* Missions are created from player prompts and owned by a hero.
* Mission states already cover pending, active, awaiting approval, completed, failed, and cancelled; these map directly to march, flare/gate, victory, and enemy-spawn states.
* Mission records track prompt, assistant text, tool-use history, plan id, parent/child mission ids, subagent lineage, token totals, and summary.
* Mission start, update, completion, and hydration events keep the live list and recent mission index current.
* Streaming assistant text, tool-use starts, and tool results form the combat playback stream for linked fights.
* The mission detail drawer, mission log, and mission timeline already expose prompt, state, assigned hero, transcript, tool activity, stats, metadata, local-context status, search, filters, hero scoping, and mission-to-hero selection links.

### Tools And Activity

Code references: `packages/protocol/src/events.ts`, `apps/server/src/lib/eventIngest.ts`, `apps/web/src/store/useGameStore.ts`, `apps/web/src/lib/toolUsage.ts`, `apps/web/src/components/ToolUsageOverlay.tsx`, `apps/web/src/components/HeroDetailDrawer.tsx`. Focused tests: `apps/web/tests/toolUsage.test.ts`, `apps/web/tests/ToolUsageOverlay.test.tsx`, `apps/web/tests/HeroDetailDrawerToolUsage.test.tsx`, `apps/server/tests/eventIngest.test.ts`.

* Tool-use records include tool name, summary, path, input preview, start/end time, and result status.
* The shipped taxonomy distinguishes filesystem reads/writes, shell, search, web, planning, MCP, and other tools; this is the source for essence type, strike type, and combat readability.
* Tool success-rate and duration tracking already exclude pending calls from denominators and aggregate by tool, mission, hero, and faction.
* File access, file read, file conflict, file intent, and Bash command events are already in the game event stream.
* Display summaries are sanitized before surfacing, which matters because the game layer must not leak raw prompts, secrets, or paths more broadly than the underlying work surface already does.

### Plans, Permissions, And Guarded Actions

Code references: `packages/protocol/src/plans.ts`, `packages/protocol/src/guardedActions.ts`, `apps/server/src/routes/permission.ts`, `apps/server/src/managers/guardedActions.ts`, `apps/web/src/components/PlanWorkpad.tsx`, `apps/web/src/components/PermissionModal.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `packages/protocol/tests/guardedActions.test.ts`, `apps/server/tests/permission.test.ts`, `apps/server/tests/guardedActions.test.ts`, `apps/web/tests/PlanWorkpad.test.tsx`, `apps/web/tests/PermissionModal.test.tsx`.

* Generated plans, permission requests, and guarded action proposals already surface as pending player decisions.
* Plan approval/rejection, permission approval/denial, and guarded-action decisions already send client actions and track in-flight duplicate guards.
* The plan workpad tracks draft, awaiting approval, approved, in progress, completed, paused, failed, and cancelled states, plus task state, budget, remaining tokens, assigned hero, prompt preview, and task summary.
* The permission modal exposes requester, action, boundary, rationale, tool detail, expiry, and disabled expired states.
* The game layer should present these as battle-plan seals and gate decisions, while keeping the shipped workpad/modal as the inspectable source of truth.


---

# 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/game-design/02-core-gameplay-and-player-verbs.md?ask=<question>&goal=<endgoal>
```

`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.