> 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/docs_public-demo/maintenance.md). # Maintenance The public demo is manually maintained. It mirrors selected product behavior, but it is not generated from the main app. ## Keep The Boundary Clear Do not add direct imports from workspace packages unless the project decision is to stop treating `public-demo/` as a standalone static artifact. Avoid imports from: * `apps/web` * `apps/server` * `apps/hooks` * `apps/cli` * `apps/warroom` * `apps/adapters` * `packages/protocol` The current model is standalone HTML plus CDN browser dependencies. ## When To Review The Demo Review `public-demo/` when the main project changes: * faction identities * hero or mission vocabulary * achievement behavior * heatmap logic * faction standings logic * command palette ranking * battlefield coordinate mapping and 2D state rings * click-triggered unit voice lines * background music playlist or player behavior * replay concepts * major cockpit layout * public screenshots or showcase art * PWA or notification behavior * protocol-visible event concepts For battlefield-specific changes, always run: ```bash npm run battlefield:check ``` Run it whenever any of these change: * `apps/web/public/battlefield/` * `public-demo/assets/battlefield/` * `assets/battlefield-2d/reference/` * `public-demo/sw.js` * `docs/battlefield.md` * `docs/media-assets.md` * public demo runtime files that could add workspace imports ## Mirrored Helpers These helpers are inlined in `index.html` and should be reviewed when matching main app logic changes: * `buildHeatmapBuckets` * `tileOpacity` * `computeStandings` * `metricValue` * `formatStandingsValue` * `metricLabel` * `sessionStats` * `rankCommands` * `mapHeroPositionToBattlefield` When updating mirrored helper behavior: 1. Identify the source behavior in the main app. 2. Port only the behavior needed by the standalone demo. 3. Keep the implementation plain browser JavaScript. 4. Avoid new build steps. 5. Run path-prefixed desktop and mobile smoke checks. ## Asset Maintenance Demo assets live under `public-demo/assets/`. The approved 2D battlefield runtime set has six files: * `assets/battlefield/background.webp` * `assets/battlefield/heroes/orc.webp` * `assets/battlefield/heroes/human.webp` * `assets/battlefield/heroes/elf.webp` * `assets/battlefield/heroes/undead.webp` * `assets/battlefield/heroes/lobster.webp` Keep these copied from the matching app runtime files under `apps/web/public/battlefield/`. The parity check fails if app and demo copies drift by byte size or SHA-256 hash, if the documented budgets are exceeded, or if the service worker stops precaching a battlefield asset. Current click-audio scope: seeded orc, human Engineer, elf, and delayed undead reinforcement heroes are wired. Map-token and roster-card clicks both choose randomly from the matching faction's four MP3s in `assets/speech/`. Background music is wired from the explicit playlist in `index.html` and local MP3 files in `assets/music/`. Static browsers cannot enumerate a directory, so adding or removing background tracks requires updating that playlist. Music is cached only after the browser requests it; add tracks to `SHELL_ASSETS` in `sw.js` only if they should be precached despite the larger service-worker install. When adding or replacing assets: * verify license and provenance * optimize size * keep filenames stable when possible * update references in `index.html` * update `SHELL_ASSETS` in `sw.js` if the asset should be precached * bump `CACHE_VERSION` if the precache list changes, or if content changes to an already-precached shell file need to be forced into a fresh offline cache * verify first-load requests are same-origin ## Service Worker Maintenance The service worker has two cache types: * shell cache for same-origin artifact files * runtime cache for allowed CDN origins Rules: * cache only GET requests * do not cache local APIs or user-specific data * keep runtime origins explicit * bump `CACHE_VERSION` when shell assets or forced shell-cache content updates change * preserve old-cache cleanup during activation * verify offline reload after changes ## Documentation Maintenance Update this docs folder when: * deployment shape changes * first-load dependencies change * service worker behavior changes * new files become part of the artifact * validation steps change * direct or indirect sharing boundaries change The repo-level sharing summary is [`../../docs/public-demo-code-sharing.md`](/faction-os-docs/docs/public-demo-code-sharing.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/public-demo/docs_public-demo/maintenance.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.