> 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-website/docs/archive-docs_public-website/development.md). # Public Website Development Use this guide for local development, validation, and routine edits in `public-website/`. ## Prerequisites * Node.js `26.2.0` or newer. * npm `11.16.0` or compatible with the root `packageManager`. * Root workspace dependencies installed from `package-lock.json`. From the repository root: ```bash npm ci --no-audit --no-fund ``` For ordinary local work, `npm install` is also acceptable when you are updating dependencies intentionally. ## Local Commands Run from the repository root unless noted. | Command | Purpose | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `npm --workspace @factionos/public-website run dev` | Start Astro dev server. | | `npm --workspace @factionos/public-website run preview` | Preview the built site. | | `npm --workspace @factionos/public-website run typecheck` | Run `astro sync && tsc --noEmit`. | | `npm --workspace @factionos/public-website run build` | Build static output into `public-website/dist`. | | `npm --workspace @factionos/public-website run check:links` | Validate built output, links, metadata, drafts, RSS, sitemap, robots, and static privacy boundary. | | `npm run format:check` | Root formatting gate. | | `npm run lint` | Root lint gate. | | `npm run typecheck` | Root workspace typecheck. | | `npm run build` | Root workspace build. | | `npm run security:secrets` | Tracked-file secret scan. | | `git diff --check` | Whitespace check for current diff. | ## Quick Edit Loop ```bash npm --workspace @factionos/public-website run dev ``` In another shell: ```bash npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links ``` The checker expects a fresh `public-website/dist`, so run `build` before `check:links`. ## Full Website Launch Gate Use this gate before launch handoff, deploy attempts, or broad docs changes: ```bash npm --workspace @factionos/public-website run typecheck npm --workspace @factionos/public-website run build npm --workspace @factionos/public-website run check:links npm run format:check npm run lint npm run typecheck npm run build npm run security:secrets git diff --check ``` The 2026-06-02 launch handoff recorded all of these as passing under Node `26.2.0` and npm `11.16.0`. ## Editing Pages Most page copy lives in data files: | Page family | Edit here | | ----------------------------------- | ---------------------------------------------------------------------------------- | | Home | `src/data/homepage.ts` and `src/pages/index.astro` | | Product | `src/data/product.ts` and `src/pages/product.astro` | | Features / How It Works | `src/data/features.ts`, `src/pages/features.astro`, `src/pages/how-it-works.astro` | | Use cases | `src/data/use-cases.ts`, `src/pages/use-cases/` | | Security | `src/data/security.ts`, `src/pages/security.astro` | | Investors / About / Contact / Press | `src/data/company.ts`, corresponding pages | | Roadmap | `src/data/roadmap.ts`, `src/pages/roadmap.astro` | | FAQ | `src/data/faq.ts`, `src/pages/faq.astro` | | Legal | `src/pages/legal/` and `src/layouts/LegalLayout.astro` | Route labels, external destinations, contact mailboxes, metadata defaults, and copy guardrails belong in `src/data/site.ts`. Keep that file synchronized with the built-site checker when route contracts change. ## Adding A Fixed Route 1. Add the route path and route metadata to `src/data/site.ts`. 2. Add or update navigation groups if needed. 3. Create the Astro page under `src/pages/`. 4. Use `BaseLayout`, `ContentLayout`, or `LegalLayout`. 5. Add a single visible `h1`. 6. Add canonical and social metadata through layout props if defaults are not sufficient. 7. Update `../../scripts/check-public-website-links.mjs` route expectations. 8. Update [Routes And IA](/faction-os-docs/public-website/docs/archive-docs_public-website/routes-and-information-architecture.md). 9. Run the full website launch gate. ## Adding Blog Or News Content Add Markdown or MDX under: ``` src/content/blog/ src/content/news/ ``` Use the frontmatter documented in [Content Authoring](/faction-os-docs/public-website/docs/archive-docs_public-website/content-authoring.md). Drafts are allowed during development, but production output must exclude them. The checker validates draft exclusion after build. ## Adding Media Use `src/assets/` and `src/lib/media.ts` for page images that Astro should optimize. Use `OptimizedMedia.astro` for rendered media where possible. Do not add downloads to `public/press/` unless [Media Assets](/faction-os-docs/public-website/docs/archive-docs_public-website/media-assets.md) has been updated with source, hash, rights, attribution, metadata, accessibility, privacy, byte budget, and release status. ## Client-Side Code The first-release site is static. Current client behavior is limited and should stay narrowly scoped. Before adding JavaScript that runs in the browser, document: * why static HTML/CSS is insufficient * whether it reads or writes storage * whether it makes runtime network calls * whether it affects keyboard use, focus, or reduced motion * how the built-site checker should validate it Adding analytics, runtime `fetch`, `WebSocket`, `EventSource`, beacon calls, storage writes, cookies, hosted forms, or CRM embeds changes the launch privacy boundary and requires a scoped docs/security update. ## Legal And Claim Review Legal and privacy pages are pre-review. Keep visible pre-review markers until owner/legal approval exists. Do not introduce copy that claims: * production-hosted validation * formal accessibility, VPAT, security, SOC 2, ISO, HIPAA, or GDPR certification * hosted identity or SSO * hosted storage * trusted erasure * customer adoption, revenue, funding, market sizing, or ROI * real user telemetry in the public demo ## Troubleshooting | Symptom | Likely issue | Fix | | ------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `check:links` fails before routes are found | `public-website/dist` is stale or absent. | Run `npm --workspace @factionos/public-website run build`. | | New page does not appear in sitemap | Route not generated or build failed. | Run typecheck/build and inspect `dist/sitemap-index.xml`. | | RSS omits a post | Frontmatter invalid, draft true, or collection path wrong. | Check `src/content.config.ts` schema and rebuild. | | Checker rejects external link | Origin is not approved. | Add a documented decision, update `src/data/site.ts`, then update checker allowlist. | | Checker rejects privacy boundary | Built output contains a blocked pattern. | Remove the runtime behavior or document and scope a boundary 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/public-website/docs/archive-docs_public-website/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.