> 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/public-demo/readme_public-demo.md).

# FactionOS - Zero-Install Demo

A single-file React + Tailwind showcase of the FactionOS UI with a generated 2D battlefield. **No build step, no install, no server.** Open `index.html` in any modern browser.

## What's running

`index.html` pulls React 19 and Tailwind browser v4 from CDNs and runs a synthetic event loop entirely client-side. Demo art is bundled inside this directory so the deployed artifact is self-contained. Heroes spawn, missions start and complete, tool uses fire, notices post, scrolls drop, and achievements unlock from browser-only data. The demo mirrors the cockpit vocabulary, but it does not read real hooks, connect to the local server, call LLM endpoints, open the plan workpad, persist server state, host replay data, or federate through War Room.

The battlefield uses the same approved six generated 2D runtime assets as the full app. App and demo copies are verified by `npm run battlefield:check`, which compares hashes, byte budgets, service-worker cache coverage, and workspace-import boundaries. The current runtime battlefield set is 668,358 bytes in `public-demo/assets/battlefield/`, below the documented 3 MB budget. The broader public-demo inventory is verified by `npm run media:demo:check`, which also checks speech, music, showcase art, icons, manifest entries, service-worker cache policy, catalog blockers, and standalone runtime boundaries. The cross-surface release gate is `npm run media:gates:check`. It verifies the approved catalog records `media.battlefield.background` and `media.battlefield.heroStandees`, including `public-demo/assets/battlefield/background.webp` and the five `public-demo/assets/battlefield/heroes/*.webp` mirrors.

The seeded orc, human Engineer, elf, and delayed undead reinforcement have click voice lines. Clicking one of those heroes on the battlefield or in the roster randomly plays one of that faction's four local voice-line MP3s from `assets/speech/`.

The header includes a single icon background-music toggle. Music starts after entering the demo, loops through the local MP3 playlist in `assets/music/`, and resumes from the same track position after being stopped.

`sw.js` precaches the static shell, icons, manifest, portraits, speech clips, and all six battlefield assets. The current shell cache is `factionos-demo-v9`. Background music tracks are intentionally loaded on demand rather than precached because they are larger optional media. The current lazy playlist paths are `public-demo/assets/music/01_mythic_battle_theme_take_1.mp3`, `public-demo/assets/music/02_mythic_battle_theme_take_2.mp3`, `public-demo/assets/music/03_noble_heroic_oath_take_1.mp3`, `public-demo/assets/music/04_noble_heroic_oath_take_2.mp3`, `public-demo/assets/music/05_dark_tribal_war_march_take_1.mp3`, `public-demo/assets/music/06_dark_tribal_war_march_take_2.mp3`, `public-demo/assets/music/07_elven_moonlit_overture_take.mp3`, `public-demo/assets/music/08_elven_guardian_hymn_take.mp3`, `public-demo/assets/music/09_elven_blades_dance_take.mp3`, `public-demo/assets/music/10_undead_necropolis_theme_take.mp3`, `public-demo/assets/music/11_undead_lament_of_the_hollow_crown_take.mp3`, and `public-demo/assets/music/12_undead_graveborn_war_march_take.mp3`.

Phase 04 closeout on 2026-05-29 validated the public demo desktop/mobile Playwright projects. Evidence covers splash/cockpit rendering, battlefield media loading, failed-art fallback copy, reduced motion, visible audio fallbacks, duplicate speech prevention, background music stop/resume behavior, desktop visual overlays, browser guards, and desktop offline shell reload after one online visit. Retained screenshots live under `test-results/e2e/`.

Phase 04 media provenance and routing live in `../.spec_system/archive/phases/phase_04/media_gap_matrix.md`. The current demo media is artifact-local and conditionally tracked where provenance, attribution, metadata, duration, loudness, fallback, and size fields still need catalog coverage. Do not import workspace packages or promote `EXAMPLES/` media into this artifact. Run `npm run media:visual:check` after changing visual demo assets, mirrored app assets, `public-demo/sw.js`, or visual media docs. Run `npm run media:demo:check` after changing any public-demo media path, manifest entry, service-worker cache rule, media catalog record, or public-demo validation doc. Run `npm run media:gates:check` before release claims. Speech and music must keep visible equivalents, and optional music must remain lazy-loaded unless a reviewed budget exception changes the policy.

Phase 02 browser closeout validates the demo on desktop and mobile Playwright projects with splash, cockpit, battlefield board, overlay, service-worker, and offline-shell evidence. The mobile header hides the `demo v2` badge so the brand and top controls do not overlap on narrow viewports.

Phase 04 media closeout extends that evidence for the current service-worker cache version `factionos-demo-v9`. Background music stays lazy-loaded and is not part of the shell precache.

Phase 08 Session 08 reran the public-demo desktop/mobile Playwright release projects locally with 14 passed and 2 skipped. This is local browser evidence for the static artifact only. The deployed Pages URL still requires `npm run release:hosted-smoke -- --target public-demo`; the latest live hosted smoke reported `SENSITIVE_OUTPUT`, so deployed public-demo release validation remains no-claim until the public artifact is updated and smoke passes.

## When to use this instead of the full app

| Use the demo when...                                     | Use the full app when...                                            |
| -------------------------------------------------------- | ------------------------------------------------------------------- |
| You want to see the UI immediately without `npm install` | You want to wire real Claude Code / Cursor / OpenCode hooks         |
| You're embedding FactionOS in a landing page or talk     | You want server-backed LLM routes or the plan workpad               |
| You're sharing the look with a non-developer             | You want War Room federation, persistent state, or real replay data |

## Deploying

Cloudflare Pages is the official public host for this demo.

Current production deploys upload `public-demo/` directly to the Cloudflare Pages project `factionos-public-demo` with Wrangler. The stable public URL is:

```
https://demo.faction-os.com/
```

See `docs_public-demo/deployment.md` for the exact deploy command and validation checklist.

If the Pages project is later connected to Git, use these settings:

| Setting                | Value                   |
| ---------------------- | ----------------------- |
| Production branch      | `main`                  |
| Root directory         | repository root / blank |
| Build command          | `exit 0`                |
| Build output directory | `public-demo`           |

The directory can still be served by any static host for fallback or local testing, including GitHub Pages, Netlify, nginx, Caddy, or `python3 -m http.server 8101`.

## Project docs

Standalone project documentation lives in `docs_public-demo/`. Start with `docs_public-demo/README_docs_public-demo.md`.

## How the loop works

`useDemoLoop()` is the synthetic event engine. It:

1. Seeds three heroes (orc / human / elf) plus an undead reinforcement after 12 s.
2. Every 3.5 s picks an idle hero to start a mission, or completes an active one.
3. Appends fake tool uses + streamed assistant text to active missions.
4. Posts the occasional notice (\~18% per tick) and drops scrolls (\~12% per tick).
5. Surfaces achievements as toast notifications.

The objects are shaped to resemble the product concepts, but they are local demo objects. `public-demo/` does not import `@factionos/protocol` or any workspace package.

## Limitations

* No real CLI hooks or local server connection.
* No LLM endpoint calls, provider transfer, permission flow, or plan workpad.
* No War Room federation, hosted replay, hosted account, or persistent server state.
* Only orc, human, elf, and undead click voice-line paths are exposed here; broader voice synth, remaining faction voices, and full audio settings still live in the full app.
* Demo speech and music remain conditionally tracked, not release-ready media. Source, rights, attribution, metadata, duration/loudness, fallback, accessibility, privacy, and budget blockers remain open until later reviewed promotion work closes them.
* Production Pages smoke is separate from local static-demo Playwright and media gates. Do not describe local browser evidence or no-network smoke as deployed Pages validation.

For the full UI surface, run `apps/web` with `npm run dev`.


---

# 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/public-demo/readme_public-demo.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.