> 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/05-progression-economy-and-collections.md).

# Progression, Economy, And Collections

**Project:** FactionOS — The War Effort **Document role:** Progression, economy, and collection spec

## 6. Heroes: Growth, Identity, Attachment

Attachment to units is the emotional engine. We already have: named heroes, archetypes, faction voices, per-hero metrics, specialization roles ("Bug Hunter", "Feature Architect", "Refactor Specialist" — heroSpecialization.ts), efficiency scores, and a leaderboard. The game layer adds:

* **XP & Levels.** XP = mission completions weighted by missionComplexity (exists) × verification bonus (plan\_verification\_complete exists) × Swift Command bonus. Levels are cosmetic + title-granting (never gate real capability — Fun Law 4).
* **Classes emerge from behavior.** The specialization role (already computed from real mission-tag history) is surfaced as the hero's **class**, with a class icon on the standee and class-flavored bark lines. Your agent *becomes* a Bug Hunter because it hunts bugs. Nothing is assigned; identity is earned. This is the purest work→fun conversion in the design.
* **Veterancy & the Hall of Banners.** Dismissed heroes with ≥N banners are enshrined (name, class, saga stats, final quote). Deletion-with-honor turns session cleanup into a ceremony instead of a loss.
* **Hero quirks (flavor drip).** Deterministic cosmetic quirks seeded from session id (a scar, a pet crab, a crooked banner) so the same hero is visually *this* hero. Cheap, huge attachment payoff.
* **Titles.** Earned strings appended ceremonially: "Grommash, Wraithbane" (cleared 10 error-spawned wraiths), "Tyrande the Swift" (avg command response < 60s), "Kel'Zhul, Tomekeeper" (collected 5 tomes).

**Existing generated asset references:** check `manifest.md` before creating new progression or collection art. Relevant assets already present: `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png` for class icons/flares, `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png` for banners/regalia/trophy pins/seals, `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png` for veteran gallery framing, `assets/generated/game-design/phase08/hero-quirks/hero-quirks-palette-sheet.png` for deterministic quirk overlays, `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png` for loot ceremony VFX, `assets/generated/game-design/phase08/tomes/tome-expansion-art-sheet.png` for behavior-keyed tome art, `assets/generated/game-design/phase08/relics/relic-set-art-sheet.png` for relic icons/displays/auras, and `assets/generated/game-design/phase08/nemesis/nemesis-presentation-sheet.png` for nemesis title/relic tie-in presentation.

## 6A. Class Advantage — The Muster Decision (fourth pass)

Objective gap in passes one–three: the player has \~11 verbs but **zero choices** — no verb ever presents options with differentiated outcomes. Interesting decisions are the irreducible core of strategy fun, and the one decision the shipped substrate already supports is *which hero to muster against which quest* (Quest Board accept already assigns to a selected idle hero). Today that choice is flavorless. Fix: make it the game's first real tactical decision.

**Affinity matrix** — hero class (heroSpecialization, earned from real mission history) × quest nature (mission tags / quest source / enemy type):

| Class (exists)       | Favored enemy                                         |
| -------------------- | ----------------------------------------------------- |
| Bug Hunter           | Blight camps from bug-type findings; wraiths          |
| Test Engineer        | Skirmishers (`test_failure` paths)                    |
| Operator             | Rams (`build_error`), config/infra camps              |
| Refactor Specialist  | **Entrenched** camps (§14.7 — old debt is their hunt) |
| Scribe               | Docs-type quests                                      |
| Quartermaster        | Chore/config quests                                   |
| Feature Architect    | Feature-type quests, campaign boss phases             |
| Wandering Generalist | Small universal bonus — never a dead pick             |

**On an affinity muster:** the hero's class icon flares at the target flag plant, linked-mission strikes gain a class-colored trim, a class-flavored bark fires, and mission XP takes a small capped bonus. That's the whole mechanic — one comparison at accept time, pure derivation, no new state.

**Guards (non-negotiable):**

1. **Advantage, never gate.** A mismatched muster is never penalized and loses nothing but the flourish — real work must never wait for "the right hero" (Fun Laws 3 & 4). The bonus is small enough to be a tiebreaker, not a scheduler.
2. **Honest by accident:** routing bug quests to the session that has been fixing bugs is genuinely good orchestration (context locality). The game nudges toward a real best practice, which is exactly what Fun Law 4 asks scoring to do.
3. **Long arc:** affinity kills accrue toward the class titles in §6 ("Wraithbane" et al.), so the decision compounds into identity.

## 7. Loot: Tomes, Relics, and the Collection Game

Scrolls exist (8 tomes: 5 fundamental + Planweaving, Summoning, legendary Ouroboros). Expand into a full **collection layer** — the retention backbone:

* **Tome expansion packs** keyed to real behaviors we already observe: web research (WebFetch/WebSearch), test running, git ceremonies, MCP tool first-uses ("Tome of Strange Machinery" — first custom MCP tool), long-run endurance, multi-front play, War Room diplomacy.
* **Relics (new, rarer than tomes):** dropped by *boss kills* (§10) and legendary real events (a 100-mission day; a zero-error week; Ouroboros-tier self-improvement proposals). Relics are displayed in the keep and grant **cosmetic auras** on heroes.
* **Loot rolls stay honest:** a mission-complete triggers a *visible* roll (small wheel-of-fortune flourish) but rarity odds are driven by the real rarity of the underlying behavior — no RNG frustration on real work; commons drop often, and the roll is celebration choreography more than gambling.

## 7A. The Essence Economy — Sources Need Sinks (second pass)

Objective flaw in pass one: it minted three essences (Fire/Lore/Forge) from tool events and gave them **nowhere to go**. A resource with no sink is a number with no meaning, and dead numbers rot the whole fun thesis. The fix, kept strictly inside Fun Laws 1 & 4 (nothing bought may affect real capability or scoring):

* **Primary sink is automatic — the tithe.** Essences flow daily into the matching building's XP (Fire→War Mill line, Lore→Sanctum line, Forge→ workshop line, per §5). The player never *has* to spend; buildings grow because the army worked. This preserves fun-per-glance with zero decisions.
* **Secondary sink is discretionary — the treasury.** A small held balance the player may spend on **ceremony only**: hero war paint / banner styling, building dressings, a naming-ceremony re-roll, commissioning an *illuminated saga page* (a decorated chronicle entry of a chosen victory), rally-horn flourishes. Spending feels like patronage, not power.
* **Prices are flavor-stable** (no inflation treadmill), and the treasury is capped — overflow tithes automatically. This prevents hoarding-anxiety and keeps essence primarily a *pulse* (income ticks = army heartbeat) rather than a wallet.
* **Anti-Goodhart hook (extends §9):** essence income already has the burst-window diminishing rule; because sinks are cosmetic-only, even a player who games essence gains nothing but a fancier banner on work that wasn't real. The economy is a dead end for cheaters by construction.

## 7B. Implemented Progression And Collection Substrate

### Heroes

Code references: `packages/protocol/src/heroes.ts`, `apps/server/src/managers/heroRoster.ts`, `apps/web/src/store/useGameStore.ts`, `apps/web/src/components/HeroRoster.tsx`, `apps/web/src/components/HeroCard.tsx`, `apps/web/src/components/HeroDetailDrawer.tsx`, `apps/web/src/lib/battlefieldHeroes.ts`, `apps/web/src/lib/heroCli.ts`. Focused tests: `packages/protocol/tests/heroes.test.ts`, `apps/web/tests/heroCli.test.ts`, `apps/web/tests/HeroRosterSort.test.tsx`, `apps/web/tests/HeroDetailDrawer.test.tsx`.

* Hero spawning already records name, archetype, faction, CLI, session id, model, working directory, TTY flag, tint, metrics, and battlefield position.
* Faction-themed names and archetypes, model-tier detection, and session-id aliasing make each live agent a stable hero rather than a duplicate row.
* Hero states cover spawning, idle, active, awaiting input, verifying, error, and dismissed; dismissal folds the hero out after a delay.
* Per-hero metrics cover missions, tool calls, token totals, estimated cost, last activity, active mission, and free-position assignment on spawn.
* Hero selection links roster, battlefield, leaderboard, mission detail, notice visibility, and analytics surfaces.
* The hero detail drawer already exposes identity, state, active mission, metrics, specialization, recent five-mission history, full 24-hour mission timeline, contribution chips, and one-off faction voice barks.
* The roster excludes dismissed heroes, caps visible heroes at 12, sorts by state or activity, and forces the selected hero into the visible window.

### Mission Tags, Specialization, And Complexity

Code references: `apps/web/src/lib/missionTags.ts`, `apps/web/src/lib/heroSpecialization.ts`, `apps/web/src/lib/missionComplexity.ts`, `apps/web/src/components/MissionLog.tsx`, `apps/web/src/components/MissionComplexityOverlay.tsx`, `apps/web/src/components/HeroDetailDrawer.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `apps/web/tests/missionTags.test.ts`, `apps/web/tests/heroSpecialization.test.ts`, `apps/web/tests/MissionLogTags.test.tsx`, `apps/web/tests/missionComplexity.test.ts`, `apps/web/tests/MissionComplexityOverlay.test.tsx`, `apps/web/tests/HeroDetailDrawerComplexity.test.tsx`.

* Mission tags infer feature, bug, refactor, test, docs, config, chore, and unknown work from prompt, summary, and assistant text.
* Multi-tag mission classification, counts, filtering, grouping, labels, and accent colors already ship.
* Hero specialization derives from completed mission tag history, with roles for Feature Architect, Bug Hunter, Refactor Specialist, Test Engineer, Scribe, Operator, Quartermaster, and Wandering Generalist.
* Specialization includes generalist fallback, sample-size/dominance confidence levels, and fleet-level grouping.
* Mission complexity already classifies work into quick, routine, heavy, and epic tiers from tool count, token count, and duration.
* Complexity handles in-flight and failed missions, aggregates by fleet, hero, and faction, selects the dominant heavy tier, and reports count, share, tokens, duration, tools, average score, and failures.

### Scrolls And Collections

Code references: `packages/protocol/src/scrolls.ts`, `packages/protocol/src/events.ts`, `apps/server/src/managers/scrolls.ts`, `apps/web/src/components/ScrollShelf.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `packages/protocol/tests/scrolls.test.ts`, `apps/web/tests/ScrollShelf.test.tsx`.

* Scroll collection state synchronizes from the server and applies collected and spawned events to the local shelf.
* Manual collection ships through both REST and WebSocket actions, with idempotent collection, collected-at timestamps, and collected-by-hero attribution.
* Rarity tiers already cover common, uncommon, rare, epic, and legendary.
* The fundamental tome set is Tome of Subprocess, Tome of Traversal, Tome of Scripture, Tome of Emendation, and Tome of Arrival; completing it unlocks the Lobster faction.
* Tome triggers already map to first Bash command, first Glob/Grep tool use, first Read tool use, first Edit/Write tool use, first completed mission, first user-approved plan, first Task subagent spawn, and an auto-improver proposal.
* The scroll shelf reports collected/total count, compact rows with rarity, description, unlock hint or collected time, a detail modal, and rarity-specific colors and glyphs.

### Achievements

Code references: `packages/protocol/src/achievements.ts`, `apps/server/src/managers/achievementEngine.ts`, `apps/server/src/managers/achievements.ts`, `apps/web/src/components/AchievementsGallery.tsx`, `apps/web/src/components/battlefield/achievementCelebration.ts`, `apps/web/src/components/battlefield/Battlefield.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `packages/protocol/tests/achievements.test.ts`, `apps/server/tests/achievementEngine.test.ts`, `apps/web/tests/AchievementsGallery.test.tsx`, `apps/web/tests/AchievementsGalleryGrouping.test.tsx`, `apps/web/tests/achievementCelebration.test.ts`.

* Achievement state synchronizes from the server, applies unlocked events locally, and treats unlocks idempotently.
* Hero and faction attribution snapshots already exist.
* Existing achievements cover first hero spawn, first mission completion, fully completed plan, all fundamental tomes, joining a War Room alliance, the 100th completed mission, and an auto-improver proposal.
* Achievement tiers cover bronze, silver, gold, and platinum.
* Attribution rules already select oldest spawned hero, earliest completed mission, one-hundredth completed mission, last plan hero, last scroll hero, or authorless attribution where appropriate.
* The gallery includes progress ring, unlocked/total count, recent unlocks, tier grouping, locked redaction with trigger hints, unlocked details, collapsible sections, unlock toast, and battlefield celebration bursts.
* Celebration anchors to an attributed visible hero when possible, centers otherwise, varies tone by tier, caps concurrency, and has reduced-motion treatment.


---

# 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/05-progression-economy-and-collections.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.