> 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/build-site-plan.md). # Public Website Build History This document preserves the completed build plan for `public-website/` without depending on `.spec_system`. It records what was built, why it exists, and what evidence closed the first launch handoff. ## Outcome The public website was created across four completed build phases: | Phase | Name | Status | Outcome | | ----- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | 13 | Public Website Foundation | Complete | Astro workspace, layout shell, metadata, publishing collections, media registry. | | 14 | Homepage And Core Product Story | Complete | Homepage, product overview, features, how-it-works, cockpit/battlefield mockups. | | 15 | Trust, Content, And Conversion Pages | Complete | Use cases, security, blog/news polish, company/contact/press, roadmap, FAQ, legal pages. | | 16 | Quality, Deployment, And Launch Handoff | Complete | Responsive/a11y hardening, performance, built-site checker, Cloudflare Pages workflow, launch evidence. | The shipped package is `@factionos/public-website`, a static Astro workspace under `public-website/`. ## Product Boundary The website is the main public product surface at `https://faction-os.com/`. It explains FactionOS and routes visitors to separate destinations: * Synthetic demo: `https://demo.faction-os.com/` * Public docs: `https://faction-os.gitbook.io/faction-os-docs` The website must not duplicate: * Runtime cockpit behavior from `apps/web`. * Synthetic demo behavior from `public-demo`. * Exhaustive API documentation from the public docs site. * Internal implementation notes, raw runbooks, or historical spec workflow records. First-release non-goals: * No server rendering. * No `@astrojs/cloudflare` adapter. * No CMS adapter. * No auth, accounts, hosted persistence, public replay, or dashboard login. * No runtime analytics by default. * No hosted contact form. * No React, Tailwind, shadcn/ui, or third-party marketing template dependency. ## Phase 13: Foundation Completed 2026-06-01. | Session | Completed Deliverables | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Astro scaffold and workspace wiring | `public-website/package.json`, `astro.config.mjs`, `tsconfig.json`, `src/env.d.ts`, initial page route, package workspace registration. | | Design tokens and layout shell | `src/styles/global.css`, shared base/content/legal layouts, shell, section primitive, header, mobile nav, footer, skip link, button, badge, panel, metric strip. | | SEO metadata and static plumbing | Central site data, metadata helpers, SEO and JSON-LD components, robots, manifest, RSS scaffold, sitemap integration. | | Content collections and publishing templates | Typed blog/news collections, content helpers, post layout, list/detail routes, seed blog/news entries, RSS backed by non-draft content. | | Asset pipeline and brand media prep | Package-local brand/showcase media, media registry, optimized media component, Open Graph fallback, press pass-through policy. | Key decisions: * The site remains static Astro output. * Typecheck uses `astro sync && tsc --noEmit`; `@astrojs/check` was not added. * Website dependencies stay local to `public-website/package.json`. * Route, metadata, external destination, and claim-boundary data are centralized in `src/data/site.ts`. * Page media lives under `src/assets/` for Astro optimization; `public/` is reserved for pass-through assets such as favicon, robots, manifest, and future approved press downloads. ## Phase 14: Core Product Story Completed 2026-06-01. | Session | Completed Deliverables | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Hero cockpit and primary CTAs | Homepage hero, terminal sample, live status panel, demo/docs CTAs, static boundary copy. | | Battlefield preview and product mockups | Responsive battlefield/cockpit visual previews, event stream, status rings, reduced-motion behavior. | | Homepage narrative sections | Value pillars, hook-to-cockpit loop, security boundary, latest content preview, final CTA. | | Product overview page | Product surface map for web cockpit, hook ingest, CLI, protocol, optional War Room, outbound adapters, static demo. | | Features and how-it-works pages | Feature matrix, pipeline diagram, setup command panels, trust boundary links. | Positioning that must remain intact: * FactionOS is local-first mission control for AI coding agents. * Claude Code, Codex CLI, and compatible producer events are part of the product story. * External adapters are optional outbound notification paths, not inbound command channels. * The demo is synthetic and separate from real local sessions. * The static website does not inspect workspaces, collect prompts, or open runtime sockets. ## Phase 15: Trust, Content, And Conversion Completed 2026-06-02. | Session | Completed Deliverables | | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | | Use cases hub and role pages | `/use-cases` plus engineering teams, AI platform teams, founders, and power users. | | Security and privacy vault | Trust manifesto, local data lifecycle, optional integration boundaries, analytics posture, security FAQ. | | Blog and news editorial polish | Featured posts, category groups, related posts, additional launch content, RSS and route validation. | | Company and contact pages | `/investors`, `/about`, `/contact`, `/press`; mailto routing; press preview policy. | | Roadmap, FAQ, and legal pages | `/roadmap`, `/faq`, `/legal`, `/legal/privacy`, `/legal/terms`, `/legal/acceptable-use`. | | Cross-linking and copy consistency | Route contract alignment, CTA normalization, copy guardrail pass, deterministic built-site checker. | Trust and copy guardrails: * Legal and privacy pages remain pre-review until owner/legal approval exists. * No unverifiable revenue, adoption, funding, market-size, performance, or security certification claims. * No hosted identity, hosted storage, trusted erasure, production-hosted validation, or formal certification claim unless later evidence exists. * Contact remains mailto-based; no hosted form or CRM embed. ## Phase 16: Quality, Deployment, And Launch Handoff Completed 2026-06-02. | Session | Completed Deliverables | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Responsive and accessibility hardening | Shared responsive fixes, keyboard/focus checks, route/viewport QA, contrast cleanup. | | Performance and image optimization | Optimized media metadata, generated hero preview derivative, motion cost reduction, image loading defaults. | | Automated checks and build gates | Built-site checker coverage for routes, drafts, feed, sitemap, robots, metadata, approved links, guarded copy, static privacy. | | Cloudflare Pages deployment path | Dedicated workflow `.github/workflows/public-website-deploy.yml`, manual Wrangler fallback, credential-safe deploy skipping, bounded homepage smoke. | | Launch review and documentation handoff | Launch readiness evidence, handoff summary, security/compliance review, post-launch backlog. | Launch evidence from 2026-06-02: * `npm --workspace @factionos/public-website run typecheck`: passed. * `npm --workspace @factionos/public-website run build`: passed with 31 pages. * `npm --workspace @factionos/public-website run check:links`: passed with 31 routes and 2185 links. * Root format, lint, typecheck, build, secret scan, and `git diff --check`: passed. * Manual local browser QA: passed for 19 critical routes at 360px, 768px, 1280px, and 1600px, including nav, CTAs, focus, images, reduced motion, and overflow checks. * Static privacy boundary: passed for no analytics, no hosted forms, no storage writes, no cookies, no beacon, no `fetch`, no `WebSocket`, and no `EventSource` patterns in built output. * Cloudflare Pages workflow readiness: passed. * Authorized live deploy and production HTTPS smoke: no-claim until run from an authorized environment. * Formal legal/privacy approval: pending. ## Current Route Count The first launch builds 31 routes: * 22 fixed routes from `src/data/site.ts`. * 5 blog routes from `src/content/blog/`. * 4 news routes from `src/content/news/`. Keep the built-site checker in `../../scripts/check-public-website-links.mjs` aligned with route additions, removed routes, or new approved destinations. ## Future Split Rules Use a new scoped effort when future work touches one of these areas: * Production deploy and HTTPS smoke evidence. * Owner/legal approval. * Hosted forms, analytics, CMS, search, auth, hosted identity, hosted storage, server rendering, or Cloudflare adapter work. * Public press downloads. * Formal accessibility certification or physical device QA. * Broad media promotion beyond the current package-local media registry. Each future effort should update the stable docs in this directory at the same time it changes source code or deployment posture. --- # 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/build-site-plan.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.