> 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/scripts/readme_scripts.md).

# Scripts

This folder contains small Node.js helpers used by root package scripts, Playwright setup, and local static-demo workflows. Keep scripts dependency-light and runnable from the repository root.

## Current Scripts

* `dev.mjs`: used by `npm run dev`. Starts the local server, waits for `/health`, then starts the web app workspace dev process so Vite does not proxy browser requests into a backend that is still booting. It stops both processes when either exits. Child processes run without stdin shortcuts so Ctrl+C can cleanly stop the whole server/web process tree from the parent runner. It loads local env files before resolving ports/auth and checks the Quest Board suggestion routes before starting Vite, so Phase 18 services must be mounted for the local app to launch.
* `dev-watch.mjs`: used by `npm run dev:watch`. Runs a focused monitoring pass against an already-running local dev stack: server and web ports, authenticated `/health`, direct WebSocket hydration and payload sizes, browser console/page errors plus app-socket counts for the first 10 seconds, and server warning/error log entries since the latest server start. It loads local env files, requires the Phase 18 `suggestion_update` hydration frame, and uses `FACTIONOS_AUTH_TOKEN` when present. Use `npm run dev:watch -- --json` for machine-readable evidence and `--no-browser` when only HTTP/WebSocket/log probes are needed.
* `relaunch.mjs`: used by `npm run relaunch`. One-shot local relaunch pipeline: gracefully stops any running dev servers (server `:2468`, web `:5193`), cleans stale build artifacts (`dist/`, `*.tsbuildinfo`, `.vite` caches), then runs `typecheck`, `lint` (with `--error-on-warnings`), `test`, and `build` before refreshing Codex live-session hooks, starting local Umami from the external Docker Compose checkout when present, and bringing the full local app up via `npm run dev`. It is fail-fast and strict: any error - or any warning from lint or build - aborts before the app starts. Use `npm run relaunch -- --no-up` to run every gate without serving, `npm run relaunch -- --skip-codex-init` to leave Codex hook config untouched, and `npm run relaunch -- --skip-umami` to leave local Umami untouched. It loads root, web, and server local env files before reading relaunch controls, service settings, and app startup values; exported shell variables still win and blank placeholders are ignored. Supports `FOS_SERVER_PORT`, `FOS_WEB_PORT`, `FOS_WEB_FALLBACK_PORT`, `FOS_ALLOW_BUILD_WARNINGS`, `FOS_RELAUNCH_SKIP_CODEX_INIT`, `FOS_RELAUNCH_SKIP_UMAMI`, `FOS_UMAMI_DIR`, `FOS_UMAMI_PORT`, `FOS_UMAMI_REQUIRED`, and `FOS_UMAMI_READY_TIMEOUT_MS`. Stop the running app with Ctrl+C. The test gate neutralizes provider transfer, startup session imports, browser auth defaults, analytics, Umami, Wrangler dev opt-in, and War Room Worker defaults; build and startup still receive the loaded local env.
* `local-demo.mjs`: used by `npm run local-demo`. Starts the standalone `public-demo/` static artifact locally at `http://127.0.0.1:8101/factionos/` by default. Supports `--port`, `--prefix`, `--root`, `FACTIONOS_DEMO_PORT`, and `FACTIONOS_DEMO_PREFIX`.
* `check-media-tooling.mjs`: used by `npm run media:check`. Verifies the installed media-processing packages and local/host binaries needed for generated image, audio, music, video, metadata, and atlas workflows.
* `check-public-demo-media.mjs`: used by `npm run media:demo:check`. Validates public-demo media inventory, catalog coverage, manifest entries, service-worker cache policy, lazy music exclusions, docs references, MP3 durations, byte budgets, and standalone runtime boundaries.
* `generate-media-drafts.mjs`: used by `npm run media:drafts`. Runs the Phase 04 generated-draft workflow in dry-run mode by default, validates selected manifest targets, checks provider credential presence without printing values, enforces budget caps, writes redacted summaries under ignored `tmp/media-generation/phase04-session03/`, and only calls providers when `--provider-run` is explicitly supplied.
* `check-media-generation-manifest.mjs`: used by `npm run media:drafts:check`. Validates the Phase 04 draft manifest for required fields, safe repository or staging paths, non-runtime blockers, provider redaction flags, and secret-sensitive strings.
* `check-media-release-gates.mjs`: used by `npm run media:gates:check`. Validates Session 07 media release readiness across typed catalog records, release blockers, docs references, sensitive output patterns, browser evidence tokens, draft blockers, visual media gate output, public-demo media gate output, service-worker cache version, and lazy media policy.
* `check-production-hosted-smoke.mjs`: used by `npm run release:hosted-smoke`. Validates production-hosted release targets with sanitized output: public demo Pages shell and service-worker evidence, War Room Worker custom-domain and workers.dev `/health` metadata, and an optional app shell when an explicit host is configured. Use `--no-network` for credential-free no-claim summaries and `--json` for evidence capture. Output is limited to target ids, labels, safe hostnames, docs paths, statuses, booleans, timing buckets, and issue codes.
* `check-visual-media-promotion.mjs`: used by `npm run media:visual:check`. Validates Session 04 visual promotion readiness for explicit repository-relative paths, image dimensions, byte budgets, metadata policy, public-demo mirrors, service-worker cache entries, stable docs references, generated-draft blockers, and quarantined path rejection.
* `check-battlefield-assets.mjs`: used by `npm run battlefield:check`. Verifies the approved six-asset 2D battlefield set across `apps/web/public/battlefield/`, `public-demo/assets/battlefield/`, and `assets/battlefield-2d/reference/`. The check compares app/demo hashes, enforces the documented byte budgets, verifies public demo service-worker precache coverage, scans runtime public-demo files for workspace imports, and warns when stable battlefield or media docs stop mentioning runtime paths.
* `backup-factionos-state.mjs`: used by `npm run backup:factionos` and `npm run backup:factionos:verify`. Archives the persistent local `FACTIONOS_HOME` state surface to `~/.factionos/backups/` by default and prunes archives outside the configured retention window.
* `serve-static-prefix.mjs`: used by `local-demo.mjs` and Playwright `webServer`. Serves a static directory under a configurable URL prefix, with no-store responses, so the public demo can be tested under the GitHub Pages-style `/factionos/` path.

Prefer adding a root `package.json` script for user-facing commands. Lower-level helpers can stay callable by path when they are mainly orchestration internals.

Run `npm run battlefield:check` after any app battlefield asset, public demo asset, public demo service-worker, or battlefield documentation change. The command must pass before release validation so missing files, copied-asset drift, stale cache lists, and accidental public-demo workspace imports are caught without browser inspection.

Run `npm run media:visual:check` after changing visual media under `assets/`, `apps/web/public/`, `public-demo/`, the public-demo service worker, or stable media docs. The command is intentionally stricter than broad filesystem scans: new visual files must be added to `scripts/media-visual-promotion-config.mjs` with source path, expected format, dimensions, byte budget, metadata policy, docs references, mirror/cache rules when applicable, and explicit blockers for conditional or non-release states.

Common remediation:

* `PATH_*`: keep paths repository-relative, use forward slashes, and never add `EXAMPLES/` files as promotable visual media.
* `FILE_MISSING`, `FORMAT_MISMATCH`, `DIMENSION_MISMATCH`, or `BYTE_SIZE_DRIFT`: verify the file was intentionally changed, then update the config and docs in the same change.
* `BUDGET_EXCEEDED`: optimize or resize the asset before raising the budget.
* `METADATA_PRESENT`: strip runtime metadata before promotion. `METADATA_PENDING` warnings are allowed only for blocked conditional records.
* `MIRROR_DRIFT` or `CACHE_ENTRY_MISSING`: copy the reviewed source to the public-demo mirror path, update `public-demo/sw.js`, and bump `CACHE_VERSION` when the precache list or forced shell content changes.
* `DOC_REFERENCE`: update `docs/media/media-assets.md`, `assets/README_assets.md`, or other listed docs so maintainers can find the current path and blocker context.

Run `npm run media:demo:check` after changing any public-demo media path, `public-demo/index.html`, `public-demo/manifest.webmanifest`, `public-demo/sw.js`, the app media catalog, public-demo docs, or script-level media policy. This gate uses explicit inventory in `scripts/public-demo-media-config.mjs`; it does not scan arbitrary directories or promote `EXAMPLES/` media.

Public-demo media check remediation:

* `PATH_*`: use repository-relative paths, forward slashes, and allowlisted public-demo, docs, scripts, tests, or catalog paths only.
* `FILE_MISSING`, `BYTE_SIZE_DRIFT`, `BUDGET_EXCEEDED`, `FORMAT_UNSUPPORTED`, or `DURATION_DRIFT`: verify the media change is intentional, then update the config, catalog, docs, and tests in the same session.
* `CACHE_ENTRY_MISSING` or `CACHE_ENTRY_STALE`: align `SHELL_ASSETS` with the declared precached media and bump `CACHE_VERSION` if the precache list changed or forced shell refresh is required.
* `LAZY_MEDIA_PRECACHED`: remove background music from `SHELL_ASSETS`. Music is optional and lazy-loaded unless a reviewed cache-budget exception is recorded.
* `MANIFEST_*`: update `public-demo/manifest.webmanifest`, icon files, or the config so install metadata, icon paths, scope, and start URL stay aligned.
* `CATALOG_*`: add or update app-facing catalog records with blockers. Do not mark public-demo speech, music, showcase, portraits, or install icons `approved` until their release gates close.
* `PUBLIC_DEMO_*`: remove workspace imports, local endpoints, or remote repository media URLs from runtime demo files.
* `DOC_REFERENCE`: update `docs/media/media-assets.md`, `public-demo/README_public-demo.md`, `public-demo/docs_public-demo/`, or this file so current media paths and cache policy are discoverable.

Run `npm run media:drafts:check` after changing `assets/generated/phase04/draft-generation-manifest.json`. Run `npm run media:drafts -- --dry-run` before provider-backed generation to verify target selection, budget caps, staging paths, and credential presence without network calls. Provider-backed runs should be selected by target and paired with reviewed budget approval; generated outputs remain ignored staging artifacts until later promotion sessions approve them.

Run `npm run media:gates:check` before release claims or Phase 04 closeout. The gate should run after `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check` when media files, catalog records, public-demo cache policy, docs, or browser evidence changes.

Run `npm run release:hosted-smoke -- --no-network` during local release checks to verify sanitized no-claim behavior without Cloudflare credentials or public network dependency. Run `npm run release:hosted-smoke -- --json` in a safe release environment when recording deployed public demo or Worker evidence. Do not paste raw response bodies, Cloudflare account ids, zone ids, API tokens, request bodies, room payloads, prompts, local paths, exports, logs, backups, or replay buffers into evidence. If `app-shell` is unavailable because no production app URL is configured, record the no-claim state rather than treating local browser evidence as deployed app validation.

Phase 04 closeout command order:

```bash
npm run media:check
npm run media:visual:check
npm run media:demo:check
npm run media:drafts:check
npm run battlefield:check
npm run media:gates:check
npm run test:e2e -- --project=app-desktop --project=app-mobile tests/e2e/app.e2e.ts
npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts
npm run format:check
npm run lint
npm run typecheck --workspaces --if-present
npm test
npm run build --workspaces --if-present
npm run security:secrets
git diff --check
```

Also run an ASCII/LF scan on changed docs and spec artifacts before closeout. Validation notes should summarize counts and pass/fail state rather than raw logs, provider payloads, raw prompts, broad local paths, or long historical excerpts.

Media release gate remediation:

* `APPROVED_*`: fix the approved catalog record, docs evidence, fallback, accessibility, privacy, metadata, browser support, or byte budget before claiming release readiness.
* `NON_APPROVED_*` or `DRAFT_*`: restore explicit blockers and keep draft or conditional media out of runtime outputs, service-worker precache, and release-ready docs.
* `DOCS_*` or `BROWSER_EVIDENCE`: update the stable docs or Playwright evidence listed by the issue.
* `SENSITIVE_OUTPUT`: remove raw prompts, provider prompts, command bodies, secret assignments, broad local paths, raw request bodies, or long `EXAMPLES/` excerpts.
* `DEPENDENCY_FAILED`: run the named lower-level media gate directly and fix its output first.

The gate has no required `MEDIA_GATE_` environment variables. Future `MEDIA_GATE_` variables must default to local, credential-free validation and must not suppress errors without a reviewed spec change.


---

# 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/scripts/readme_scripts.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.