> 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/development.md). # Development Guide ## Required Tools | Tool | Version | Purpose | | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | Node.js | 26.2.0+ | Core server, web, hooks, CLI, adapters, War Room tooling, and tests. Root `.nvmrc` pins local policy to Node 26.2.0. | | npm | 11.16.0 | Workspace install and scripts. Root `packageManager` pins npm 11.16.0. | | Git | current | Source control. | | Wrangler | workspace package | War Room Worker dev/deploy under the repo Node 26.2.0+ runtime. | ## Ports | Service | Default | URL | | ------------------------------ | ------- | ----------------------------------------------- | | Local server and WebSocket | `2468` | `http://127.0.0.1:2468`, `ws://127.0.0.1:2468/` | | Web dev server | `5193` | `http://localhost:5193` | | Vite fallback port | `5194` | Reserved if `5193` is occupied. | | Local Umami Docker Compose app | `3024` | `http://localhost:3024` | | Public demo local server | `8101` | `http://127.0.0.1:8101/factionos/` | | Wrangler dev | `8790` | `http://localhost:8790` | ## Root Scripts | Command | Purpose | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npm run dev` | Starts the local server, waits for `/health`, then starts the web client; Ctrl+C stops the server/web process tree. | | `npm run relaunch` | Stops local dev servers, cleans build artifacts, runs quality gates, refreshes Codex live-session hooks, starts local Umami when the checkout exists, then starts `npm run dev`. Use `-- --no-up` for verify-only, `-- --skip-codex-init` to leave Codex hooks untouched, or `-- --skip-umami` to leave the external Umami Compose app untouched. | | `npm run format` | Applies Biome formatting to configured project files. | | `npm run format:check` | Checks formatting. | | `npm run lint` | Runs Biome linting. | | `npm run typecheck` | Runs workspace typecheck scripts where present. | | `npm run build` | Runs workspace build scripts where present. | | `npm run security` | Runs the checked-in secret scanner and `npm audit --audit-level=moderate`. | | `npm run security:secrets` | Runs the checked-in secret scanner only. | | `npm test` | Runs Vitest. | | `npm run test:watch` | Runs Vitest in watch mode. | | `npm run media:check` | Verifies local/package media tooling. | | `npm run media:visual:check` | Validates visual promotion config, metadata policy, mirrors, docs, and blockers. | | `npm run media:demo:check` | Validates public-demo media inventory, cache policy, lazy music, and standalone boundaries. | | `npm run media:drafts:check` | Validates Phase 04 draft generation manifest redaction and non-runtime blockers. | | `npm run media:gates:check` | Runs the root media release gate across catalog, docs, browser evidence, and dependent media gates. | | `npm run battlefield:check` | Validates approved app/demo battlefield asset parity, budgets, and cache coverage. | | `npm run test:e2e` | Runs Playwright browser tests. | ## Package Commands ```bash npm run dev npm --workspace apps/server run dev npm --workspace apps/web run dev npm --workspace @factionos/public-website run dev npm --workspace apps/warroom run dev npm --workspace apps/adapters run discord npm --workspace apps/adapters run telegram npm --workspace apps/adapters run webhook npm --workspace apps/cli link ``` For the static `public-website` workspace: ```bash npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links npm --workspace @factionos/public-website run preview ``` Root `npm run format:check` and `npm run lint` directly include `public-website`. Root `npm run typecheck` and `npm run build` include the website through workspace script delegation. Use the package `check:links` gate after a fresh website build to validate fixed routes, published blog/news routes, draft exclusion, RSS, sitemap, robots, metadata, approved links, guarded copy, and the no-tracking static-output boundary. ## Local Hook Provider Workflow `factionos init` installs Claude Code hooks by default. Use explicit provider selection when exercising Codex support: ```bash npm --workspace apps/cli link factionos init --cli claude factionos init --cli codex factionos init --cli all ``` Codex install writes FactionOS local state under `~/.factionos/` and writes managed user-level Codex hooks under `CODEX_HOME` when set, otherwise under the Codex user config directory. It backs up the first raw `hooks.json` to `hooks.backup.factionos.json` when one exists, replaces older FactionOS-managed Codex commands, preserves user-owned hooks and unknown top-level fields, and injects `FACTIONOS_CLI=codex-cli` into managed hook commands. Use these focused checks after changing CLI or hook provider behavior: ```bash factionos status --cli all factionos doctor --cli all factionos uninstall --cli codex factionos init --cli codex ``` After `factionos init --cli codex`, start a new Codex CLI process and review loaded hooks with `/hooks`. Do not document trust-bypass flags as the normal path. The CLI does not create project-local trusted `.codex/` state, change Codex auth/provider/model/profile/telemetry/account settings, or package a Codex plugin. Phase 12 Session 01 records plugin packaging as explicitly deferred for this release; do not treat plugin install, cache refresh, plugin trust review, or plugin uninstall as passing checks unless a later session creates and validates that package in isolated homes. ## Workspace Rules * Add shared event and domain contracts in `packages/protocol` before wiring app behavior. * Keep server routes small and move business logic into managers or libraries. * Keep hook handlers dependency-light and timeout-bounded. * Keep adapters outbound-only unless a future permission model is specified. * Keep optional services optional. Local core workflows must run without hosted accounts or API keys. * Treat ignored `EXAMPLES/` media as reference-only. Do not import, copy, transform, or ship files from it directly; create owned or generated replacements through the media pipeline. ## Testing Vitest projects cover protocol, server, adapters, worker, and web code. Web tests use happy-dom. ```bash npm test npx vitest run --coverage npm run typecheck --workspaces --if-present ``` CI runs quality and tests on Node 26.2.0. ## Media And Browser Validation Use this focused Phase 04 validation set after media, public-demo, app media UI, service-worker, or closeout docs changes: ```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 ``` For repository closeout or release candidates, also run: ```bash npm run format:check npm run lint npm run typecheck --workspaces --if-present npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links npm test npm run build --workspaces --if-present npm run security:secrets git diff --check ``` Changed docs and spec artifacts should remain ASCII-only with Unix LF line endings. Do not copy raw prompts, provider payloads, broad local paths, secret values, command bodies, or long `EXAMPLES/` excerpts into validation artifacts. ## Local State Runtime state can appear under: * `~/.factionos/` for local FactionOS state, logs, spool files, sessions, and memory. * `CODEX_HOME` or the Codex user config directory for Codex `hooks.json` and `hooks.backup.factionos.json` when Codex hooks are installed. * Browser localStorage for web settings, replay buffers, and derived game projection state. Settings use `factionos-settings-v1` plus the theme mirror `factionos-theme`; replay uses `factionos-replay-v1`; projection uses `factionos-game-v1`. Malformed browser settings and projection snapshots fall back to defaults, but reset settings is not a full local erasure workflow. * Cloudflare Durable Object storage when a deployed Worker room is used. Do not commit local state, `.env.local`, probe outputs, or quarantined `EXAMPLES/` content. ## Environment Files The root `.env.local.example` lists current and reserved variables. Server, adapters, CLI, and hooks load root env first, then package fallback env files such as `apps/server/.env` or `apps/adapters/.env`. Already-exported shell variables keep priority, earlier files win over later files, and blank placeholders are ignored. Vite browser values belong in `apps/web/.env.local`. The local server binds to `127.0.0.1` by default. Set `FACTIONOS_ALLOW_NON_LOOPBACK_BIND=true` only for an intentional non-loopback bind. If `FACTIONOS_AUTH_TOKEN` is set, HTTP routes and WebSocket connections require the same bearer token; set `VITE_FACTIONOS_AUTH_TOKEN` in `apps/web/.env.local` only for local browser development against that protected server. LLM provider transfer requires two explicit conditions: `ANTHROPIC_API_KEY` and `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`. Without the transfer flag, LLM routes use deterministic local fallbacks. Codebase scans are limited to the server working directory plus paths listed in `FACTIONOS_SCAN_ROOTS` using the platform path delimiter. The scan route refuses filesystem roots, skips symlinks, caps walked files and per-file content, ignores generated and historical artifact directories, and returns compact validation errors without echoing raw absolute roots. Browser notifications are local OS notifications only. Development and tests should keep the feature guarded by browser API checks and should not add push backend claims until a later phase ships a real push service. Local Umami startup is part of `npm run relaunch` when the checkout exists at `FOS_UMAMI_DIR` or the default `~/src/umami`. Relaunch runs `docker compose up -d` from that external checkout and waits for `http://localhost:3024/api/heartbeat` before starting the local app. Set `FOS_RELAUNCH_SKIP_UMAMI=1` or pass `-- --skip-umami` to leave it untouched, and set `FOS_UMAMI_REQUIRED=1` when missing local Umami should fail relaunch instead of being skipped. --- # 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/development.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.