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

# Public Demo Code Sharing

`public-demo/` should be understood as a standalone static artifact, not a second build of `apps/web`.

Detailed artifact documentation lives in [`../public-demo/docs_public-demo/`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-demo/docs_public-demo/README.md).

## Direct Sharing

There is no direct runtime code sharing between `public-demo/` and the main application packages.

`public-demo/index.html` imports browser dependencies from CDNs and keeps the demo implementation inline. It does not import:

* `@factionos/protocol`
* `apps/web`
* `apps/server`
* `apps/hooks`
* `apps/cli`
* `apps/warroom`
* `apps/adapters`
* `packages/*`

The Pages artifact also carries its own local demo art under `public-demo/assets/`, so public demo image rendering does not depend on main repo paths at runtime.

## Indirect Sharing

The demo shares product meaning with the main project in four indirect ways:

1. Concepts: heroes, missions, tool uses, notices, scrolls, achievements, heatmaps, standings, and command palette actions match the product vocabulary.
2. Data shape discipline: generated demo objects intentionally resemble the protocol and app state concepts, even though no protocol package is imported.
3. Mirrored helpers: selected helper behavior is manually ported into `public-demo/index.html`, including heatmap bucketing, standings math, session rollups, and command ranking.
4. Copied or demo-local assets: showcase art, faction portraits, approved battlefield runtime art, click speech, and background music live under `public-demo/assets/` so the static artifact is self-contained.

This means the demo is manually kept in sync. A main app change does not automatically update the public demo.

## Maintenance Implication

When changing the main app surfaces that the demo mirrors, check whether `public-demo/index.html` also needs an update. High-signal triggers include:

* protocol event shape changes that affect visible hero or mission behavior
* changes to `apps/web/src/lib` helpers mirrored by the demo
* UI changes to heatmap, standings, command palette, achievements, mission log, or replay concepts
* faction identity or asset changes
* deployment or PWA behavior changes

Keep the boundary explicit: shared behavior may be mirrored, but direct imports from workspace packages would turn the artifact into a build product and break the current zero-install static-hosting model.

Phase 04 media ownership is routed by `.spec_system/archive/phases/phase_04/media_gap_matrix.md`. Public demo media can mirror product meaning, but it remains artifact-local. Speech, music, images, icons, manifest entries, and service-worker cache rules need provenance, attribution, metadata, size, fallback, accessibility, privacy, and cache decisions before release expansion.

For battlefield assets, run the repository-root parity gate after any app asset, demo asset, service-worker, or stable-doc change:

```bash
npm run battlefield:check
```

The check verifies the explicit six-asset battlefield manifest, app/demo SHA-256 parity, byte budgets, public demo service-worker precache coverage, same-origin shell asset existence, runtime public-demo workspace import exclusions, and stable docs path references. If the public demo service-worker precache list changes, bump `CACHE_VERSION`; if already-precached shell content must be forced into a fresh offline cache, bump it as well.

Phase 04 closeout validates the current cache version `factionos-demo-v9` and the path-prefixed offline reload after one online visit.


---

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