> 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/readme_game-design.md).

# Game Design Documentation

This folder is the standalone game design document set for FactionOS: **The War Effort**. Each document is intended to be readable on its own while remaining part of the same product, systems, and production design package.

## Document Map

| Document                                     | Industry-standard role                           | Contains                                                                                                                           |
| -------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `01-product-vision-brief.md`                 | Product vision brief / creative pillars          | Pitch, fun thesis, genre, fun laws, core fantasy, antagonist                                                                       |
| `02-core-gameplay-and-player-verbs.md`       | Core gameplay spec / interaction model           | Work-to-fun exchange table, player verbs, ceremony rules                                                                           |
| `03-game-loops-and-onboarding.md`            | Player experience spec / onboarding flow         | Core loops, return loop, war loop, first ten minutes                                                                               |
| `04-world-map-and-combat-systems.md`         | World systems spec / combat model                | Territory map, combat playback, shipped surface constraints                                                                        |
| `05-progression-economy-and-collections.md`  | Progression, economy, and collection spec        | Heroes, XP, titles, tomes, relics, essence economy                                                                                 |
| `06-social-and-scoring-systems.md`           | Social systems and scoring spec                  | Alliance War, War Room reskin, anti-Goodhart scoring                                                                               |
| `07-content-audio-and-feature-inventory.md`  | Content, presentation, and asset brief           | Bosses, set pieces, sensory design, exists-vs-adds inventory                                                                       |
| `08-production-roadmap-and-phase-a-spec.md`  | Production roadmap / vertical-slice feature spec | Build order and Phase A buildable detail                                                                                           |
| `09-risk-boredom-and-integrity-audit.md`     | Design risk audit / integrity constraints        | Boredom Audit and adopted failure-mode fixes                                                                                       |
| `10-technical-design-and-game-projection.md` | Technical design document                        | Systems wiring, module mapping, `gameProjection.ts` shape                                                                          |
| `11-open-questions-and-change-log.md`        | Decision log / open questions / change log       | Open questions and update log                                                                                                      |
| `12-utility-admin-holdout-inventory.md`      | Hold-out implementation inventory                | Existing utility/admin mechanics not currently promoted into the game design                                                       |
| `13-implementation-phase-outline.md`         | Implementation phasing plan                      | Twelve session-sized (\~800k-token) build phases covering the full design, with dependencies and exit criteria                     |
| `14-implemented-phases.md`                   | Implemented phase ledger                         | Completed game-design phases with spec-system phase mapping, evidence anchors, validation status, and explicit no-claim boundaries |
| `15-phases-yet-to-be-implemented.md`         | Pending implementation phase backlog             | Remaining game-design Phase 3-12 backlog after Phases 1-2 shipped as spec-system Phases 22-23                                      |
| `manifest.md`                                | Generated asset manifest                         | Production-owned generated game-design visual assets, source paths, runtime posture, dimensions, and visible equivalents           |

## Usage

Use these documents as the canonical game-design package. When changing a specific game system, update the relevant standalone document directly.

Generated game-design assets are tracked in `manifest.md`. Before commissioning or generating art for a game-design phase, check the owning design doc and that manifest first. Runtime promotion still needs the consuming app path, any public-demo mirror/cache behavior, fallback, accessibility, and source-rights notes recorded by the implementation phase. The runtime media baseline and remaining audio backlog live in `07-content-audio-and-feature-inventory.md`; phase-specific asset and content handoffs live in `15-phases-yet-to-be-implemented.md`; unresolved media and asset-policy decisions live in `11-open-questions-and-change-log.md`.

The shipped battlefield visual/interaction contract lives in `docs/battlefield.md`.


---

# 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/readme_game-design.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.