> 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/.spec_system/conventions.md). # Conventions ## Stack * Monorepo managed with npm workspaces. * Runtime baseline is Node 26.2.0+ with npm 11.16.0. * TypeScript packages: `apps/adapters`, `apps/server`, `apps/warroom`, `apps/web`, `packages/protocol`. * JavaScript packages: `apps/cli`, `apps/hooks`. * Root formatting and linting use Biome. * Type checking uses `tsc` in package-local scripts plus the root workspace typecheck pass. * Tests use Vitest for the TypeScript packages and Node-based test runners in the JavaScript packages. ## Local Dev Tools | Category | Tool | Config | | ------------- | --------------------------------------------------------------- | ------------------------------------ | | Formatter | Biome | `biome.jsonc` | | Linter | Biome | `biome.jsonc` | | Type Checker | TypeScript `tsc` | package `tsconfig.json` files | | Test Runner | Vitest | `vitest.config.ts` | | Dev Server | `npm run dev` | `scripts/dev.mjs` | | Public Demo | `npm run local-demo` | `scripts/local-demo.mjs` | | Backup | `npm run backup:factionos` | `scripts/backup-factionos-state.mjs` | | Observability | `apps/server/src/lib/logging.ts`, `apps/cli/src/lib/logging.js` | root `logs/` | | Git Hooks | Husky + lint-staged | `.husky/pre-commit`, `package.json` | | Database | not configured | - | ## CI/CD Workflows | Bundle | Status | Workflow | Strategy | | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Code Quality | configured | `.github/workflows/quality.yml` | Biome format, lint, and workspace typecheck on Node 26.2.0 | | Build & Test | configured | `.github/workflows/test.yml` | Workspace typecheck plus Vitest coverage on Node 26.2.0 | | Security | configured | `.github/workflows/security.yml` | Secret scan, `npm audit`, dependency review, and CodeQL | | Integration | configured | `.github/workflows/e2e.yml` | Playwright app and public-demo coverage with local web servers | | Operations | configured | `.github/workflows/release.yml`, `.github/workflows/deploy.yml`, `.github/workflows/warroom-deploy.yml`, `.github/workflows/public-demo-deploy.yml`, `.github/workflows/public-website-deploy.yml`, `.github/workflows/pages.yml`, `.github/dependabot.yml` | Release tagging, repo-wide deploy placeholder, War Room Worker deploy, official Cloudflare Pages public-demo deploy, static public website Pages deploy, GitHub Pages fallback deploy, and weekly dependency updates | ## Workspace Structure | Package | Path | Stack | Formatter | Linter | Typecheck | Dev | | -------------- | ------------------- | ---------------- | --------- | ------ | ---------------------------- | -------------------------- | | adapters | `apps/adapters` | TypeScript | Biome | Biome | `tsc --noEmit` | `tsx watch src/index.ts` | | cli | `apps/cli` | JavaScript | Biome | Biome | - | n/a | | hooks | `apps/hooks` | JavaScript | Biome | Biome | - | n/a | | server | `apps/server` | TypeScript | Biome | Biome | `tsc --noEmit` | `tsx watch src/index.ts` | | warroom | `apps/warroom` | TypeScript | Biome | Biome | `tsc --noEmit` | `wrangler dev --port 8790` | | web | `apps/web` | TypeScript | Biome | Biome | `tsc -b --noEmit` | `vite` | | protocol | `packages/protocol` | TypeScript | Biome | Biome | `tsc --noEmit` | n/a | | public-website | `public-website` | Astro/TypeScript | Biome | Biome | `astro sync && tsc --noEmit` | `astro dev` | ## Audit Notes * Root validation command set: `npm run format:check`, `npm run lint`, `npm run typecheck --workspaces --if-present`, `npm test`. * Root dev startup launches the server and web workspace dev servers together. * The web dev server may fall back to the next available port if `5193` is already in use. ## Infrastructure | Component | Package | Provider | Details | | --------- | -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CDN/DNS | (shared) | Cloudflare | Public DNS and zone-level WAF are managed in the dashboard. | | Health | apps/server | Node/Express | `GET /health`; local probe `curl http://127.0.0.1:2468/health`. | | Health | apps/warroom | Cloudflare Workers | `GET /health`; validate after deploy with `curl https://YOUR-WORKER.workers.dev/health`. | | Security | apps/server | Express middleware | In-process rate limiting defaults to 240 requests per 60 seconds. | | Security | apps/warroom | Cloudflare + middleware | App-level rate limiting is enabled; Cloudflare WAF rules are manual/dashboard-managed and documented in `docs/runbooks/cloudflare-waf.md`. | | Backup | (shared) | Local tarball | `~/.factionos/{memory.jsonl,settings.json,lifecycle.json,project-root.json,sessions/}` -> `~/.factionos/backups/`; run `npm run backup:factionos` from cron or a system scheduler; retention defaults to 30 days via `FACTIONOS_BACKUP_RETENTION_DAYS`. | | Deploy | apps/warroom | GitHub Actions + Wrangler | `.github/workflows/warroom-deploy.yml`, with manual `wrangler deploy` fallback. | | Deploy | public-demo | GitHub Actions + Cloudflare Pages | `.github/workflows/public-demo-deploy.yml`; Wrangler Pages deploy on `public-demo/` changes after static media gates, with manual Wrangler fallback in `docs/deployment.md`. | | Deploy | public-website | GitHub Actions + Cloudflare Pages | `.github/workflows/public-website-deploy.yml`; static Astro output from `public-website/dist` after package typecheck, build, and built-site checker gates, with credential-safe skip and manual Wrangler fallback in `docs/deployment.md`. | | Local Dev | root | Node process + Vite | `npm run dev` starts the server and web workspace together, then `curl http://127.0.0.1:2468/health` verifies the local server probe. | ## Infrastructure Validation Last infra run: 2026-07-08, validated the configured Health, Security, Backup, and Deploy bundles without adding a new bundle. Validation ran on Node v26.2.0 and npm 11.16.0 after loading NVM with `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0`. Local server and Worker health/security checks passed, a fresh backup archive was created and verified, deploy source gates and Worker dry-run passed, live hosted smoke passed for the public demo, War Room custom domain, and War Room workers.dev URL, and the main public website returned 200 with expected homepage content. | Component | Package | Validation | | --------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Health | apps/server | `PORT=2634 FACTIONOS_AUTH_TOKEN=infra-local-token FACTIONOS_MOCK=false FACTIONOS_RATE_LIMIT_MAX=2 FACTIONOS_RATE_LIMIT_WINDOW_MS=60000 npm --workspace @factionos/server run dev`; `curl --fail --show-error --max-time 2 -H 'Authorization: Bearer infra-local-token' http://127.0.0.1:2634/health` returned 200 JSON with `ok: true`, `mock: false`, and `time`. | | Security | apps/server | The same local run confirmed fixed-window limiting with three subsequent authenticated `/health` requests returning `200`, `429`, and `429` under the temporary low cap. | | Health | apps/warroom | `npm --workspace @factionos/warroom run typecheck` passed; `npx wrangler dev --config apps/warroom/wrangler.toml --port 8794 --ip 127.0.0.1` and `curl --fail --show-error --max-time 3 http://127.0.0.1:8794/health` returned 200 JSON with `service: "factionos-warroom"`, `rateLimit.max: 240`, and `deployment.urlType: "local-wrangler"`. | | Security | apps/warroom | The same local Worker run confirmed fixed-window limiting with the documented 240 request window; after readiness, a 242-request `/health` probe returned counts `{"200":239,"429":3}`. | | Deploy | apps/warroom | `npm --workspace @factionos/warroom run typecheck` passed; `npx wrangler deploy --dry-run --config apps/warroom/wrangler.toml` packaged 164.37 KiB upload / 32.13 KiB gzip with Durable Object and rate-limit bindings. | | Backup | (shared) | `npm --silent run backup:factionos -- --retention-days 30` created `/home/aiwithapex/.factionos/backups/factionos-state-20260708T191459Z.tar.gz` with `settings.json` and `sessions`, retention `30`; `npm --silent run backup:factionos:verify -- /home/aiwithapex/.factionos/backups/factionos-state-20260708T191459Z.tar.gz` returned `verified: true`. | | Deploy | public-demo | `npm run media:gates:check`, `npm run media:demo:check`, and `npm run battlefield:check` passed; `npm run release:hosted-smoke -- --json` validated the public demo target with `status: "passed"` and `claim: "validated"`. | | Deploy | public-website | `npm --workspace @factionos/public-website run quality` passed: `astro check` reported 0 errors, `astro build` produced 31 static routes, and `check-links-and-privacy` reported 31 HTML routes with 0 issues; `node -e "const url=\"https://faction-os.com/\"; const res=await fetch(url); const text=await res.text(); console.log(JSON.stringify({status:res.status, bytes:text.length, hasFactionOS:text.includes(\"FactionOS\"), hasMissionControl:text.includes(\"Mission control\")}));"` returned `{"status":200,"bytes":138219,"hasFactionOS":true,"hasMissionControl":true}`. | | Deploy | deployed Worker surfaces | `npm run release:hosted-smoke -- --json` passed with `ok: true`, 3 passed targets, 0 failed targets, and 1 unavailable optional app-shell target; War Room custom domain and workers.dev targets validated, and optional app shell remained `TARGET_UNAVAILABLE` / `no_claim` as expected. | --- # 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/.spec_system/conventions.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.