> 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/local-development.md).

# Local Development

The public demo is edited directly. There is no compile step.

## Run From The Demo Root

From the repository root:

```bash
python3 -m http.server 8101 --directory public-demo
```

Open:

```
http://127.0.0.1:8101/
```

This is enough for normal visual and interaction checks.

## Run With A Path Prefix

Cloudflare Pages normally serves the official demo at a domain root. The demo still supports fallback static hosts that serve under a path such as `/factionos/`. Test that shape locally before publishing:

```bash
rm -rf /tmp/factionos-pages-sim
mkdir -p /tmp/factionos-pages-sim/factionos
rsync -a --delete public-demo/ /tmp/factionos-pages-sim/factionos/
python3 -m http.server 8101 --bind 127.0.0.1 --directory /tmp/factionos-pages-sim
```

Open:

```
http://127.0.0.1:8101/factionos/
```

This catches mistakes with absolute paths, service worker scope, manifest paths, and asset URLs.

## Editing Rules

* Keep `index.html` directly runnable.
* Use relative URLs for same-origin files.
* Keep the service worker registration scope at `./`.
* Do not import workspace packages unless the project deliberately stops being a no-build static artifact.
* Keep copied/mirrored helper logic documented in [Maintenance](/faction-os-docs/public-demo/docs_public-demo/maintenance.md).
* Keep shipped image and audio assets local to `public-demo/assets/`.

## Service Worker During Development

The service worker registers on HTTPS and local hosts. This means stale cached files can survive reloads while testing.

Useful cleanup options:

* open DevTools and unregister the service worker
* clear site data for the local origin
* bump `CACHE_VERSION` in `sw.js` after changing the precache list
* test in a fresh browser context

When debugging plain rendering issues, use a fresh port or browser profile to avoid reading an old cached shell.

## Repository Checks

The root scripts include `public-demo/` in formatting and lint checks:

```bash
npm run format:check -- public-demo
npm run lint -- public-demo
```

Markdown files in this docs folder may be ignored by Biome depending on repo configuration. Always run:

```bash
git diff --check -- public-demo/docs_public-demo
```


---

# 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/local-development.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.