> 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/archive/phases/phase_13/prd_phase_13.md).
# PRD Phase 13: Public Website Foundation
**Status**: Complete **Sessions**: 5 **Estimated Duration**: 10-20 hours
**Progress**: 5/5 sessions (100%)
***
## Overview
Create the production foundation for the main `https://faction-os.com/` website. The website is the commercial and product front door for FactionOS: a static Astro site that explains the local-first AI coding agent cockpit, routes visitors to the zero-install demo, and routes builders to the public documentation without duplicating either surface.
The site must be separate from the synthetic demo hosted at `https://demo.faction-os.com/` and the public documentation hosted at `https://faction-os.gitbook.io/faction-os-docs`. It must not duplicate exhaustive API documentation, implementation runbooks, phase history, or the synthetic demo experience.
Research snapshot for the initial stack: 2026-06-01.
If the generated visual landing page mockup at `assets/showcase/factionos-website-mockup.png` is committed, treat it as the official design blueprint for implementation. If that exact asset is not committed, add the intended mockup or replace it with the actual committed asset path before using it as canonical design input.
***
## Progress Tracker
| Session | Name | Status | Est. Tasks | Validated |
| ------- | -------------------------------------------- | -------- | ---------- | ---------- |
| 01 | Astro Scaffold And Workspace Wiring | Complete | \~16-22 | 2026-06-01 |
| 02 | Design Tokens And Layout Shell | Complete | \~18-24 | 2026-06-01 |
| 03 | SEO Metadata And Static Site Plumbing | Complete | \~14-20 | 2026-06-01 |
| 04 | Content Collections And Publishing Templates | Complete | \~18-24 | 2026-06-01 |
| 05 | Asset Pipeline And Brand Media Prep | Complete | \~12-18 | 2026-06-01 |
***
## Completed Sessions
1. Session 01: Astro Scaffold And Workspace Wiring - Complete on 2026-06-01.
2. Session 02: Design Tokens And Layout Shell - Complete on 2026-06-01.
3. Session 03: SEO Metadata And Static Site Plumbing - Complete on 2026-06-01.
4. Session 04: Content Collections And Publishing Templates - Complete on 2026-06-01.
5. Session 05: Asset Pipeline And Brand Media Prep - Complete on 2026-06-01.
***
## Upcoming Sessions
None.
***
## Apex Workflow And Split Rules
Each session must be expanded with `plansession` before implementation, then follow `plansession -> implement -> validate -> updateprd`.
After all sessions in this phase complete, follow the Apex phase-transition cadence: `audit -> pipeline -> infra -> carryforward -> documents`, followed by manual QA and LLM audit before creating or starting the next phase.
Split a planned session before implementation if:
* The task checklist exceeds 25 tasks.
* The objective includes two unrelated outcomes.
* The session touches more than 2-3 packages.
* The work needs both broad page creation and deep QA in the same session.
* Legal/privacy owner review blocks completion inside the same 2-4 hour window.
***
## Objectives
1. Scaffold a static Astro workspace named `@factionos/public-website`.
2. Wire the website into root npm workspaces, scripts, typecheck, and build expectations without coupling it to the existing app shell.
3. Establish a Cyber-Tactical visual system, shared layout primitives, content collections, metadata plumbing, asset handling, and first-release privacy boundaries that later page-building phases can reuse.
***
## Product Boundary
The first release must include a static public website with durable publishing surfaces and all required route foundations. Planned website areas are:
* Home / landing page.
* Product overview.
* Use cases.
* Features.
* How it works.
* Security and privacy.
* Demo call to action linking to `https://demo.faction-os.com/`.
* Docs call to action linking to `https://faction-os.gitbook.io/faction-os-docs`.
* Blog.
* News / changelog.
* Investors.
* About.
* Contact.
* Media / press kit.
* Roadmap.
* FAQ.
* Legal / policy pages.
First-release non-goals:
* No server rendering.
* No Astro Cloudflare adapter.
* No CMS adapter.
* No auth, accounts, hosted persistence, public replay, or dashboard login.
* No runtime analytics by default.
* No React, Tailwind, shadcn/ui, or third-party marketing template dependency.
* No hosted contact form.
* No duplicate exhaustive API docs, raw implementation notes, phase history, runbooks, or synthetic demo behavior.
***
## Technical Considerations
### Architecture
The website should use Astro as a static content site scaffolded from the official Astro blog starter and reshaped into a product website. The blog starter is the right base because the site needs both commercial pages and durable publishing surfaces, and the starter already demonstrates Markdown/MDX, content collections, RSS, sitemap, canonical/Open Graph metadata, and minimal CSS without importing a SaaS theme dependency tree. Treat the starter as scaffolding, not visual direction.
Do not use a third-party Astro marketing template as the base. Templates such as AstroWind, Astroplate, and similar SaaS starters usually bring opinionated navigation, Tailwind/plugin assumptions, component catalogs, CMS hooks, or decorative content that would take longer to remove than building the FactionOS site directly.
### Technologies
* Package name: `@factionos/public-website`.
* Runtime/build baseline: repository Node.js policy, currently Node.js `26.2.0` or newer.
* Astro mode: static output, with no server adapter for the first release.
* Package manager: npm workspace.
* Scaffold command, run safely from repo root or a temporary directory: `npm create astro@latest public-website -- --template blog`.
* Initial integrations: `@astrojs/mdx`, `@astrojs/sitemap`, `@astrojs/rss`.
* Image processing: `sharp` with Astro `` and ``.
* Type validation: run `astro sync && tsc --noEmit` through a workspace `typecheck` script. Do not add `@astrojs/check` while its current language server dependency path resolves the vulnerable `yaml-language-server` subtree.
* UI stack: Astro components, scoped CSS, global CSS variables, and small browser scripts only where interaction is needed.
* Styling: vanilla Astro styling and scoped component CSS, plus `src/styles/global.css` for reset, tokens, typography, layout primitives, accessible focus states, and shared motion.
* Tailwind is not part of the first release. The old `@astrojs/tailwind` integration is deprecated; if utility classes are needed later, use Tailwind 4 through Astro's current Tailwind/Vite plugin path with `npx astro add tailwind`, keep it local to `public-website`, and do not mix the commercial website into the existing `apps/web` Tailwind 4 cockpit design system.
Package snapshot on 2026-06-01:
| Package | Version |
| ------------------ | -------- |
| `astro` | `6.4.2` |
| `@astrojs/mdx` | `6.0.1` |
| `@astrojs/sitemap` | `3.7.3` |
| `@astrojs/rss` | `4.0.18` |
| `sharp` | `0.34.5` |
| `typescript` | `5.9.3` |
| `vite` | `7.3.5` |
Let `npm create astro@latest -- --template blog` provide the initial compatible dependency set, then keep type validation on the `astro sync && tsc --noEmit` path until the Astro checker stack no longer pulls a vulnerable YAML language server dependency chain.
Astro 6 requires Node.js `22.12.0` or newer. The repository baseline is higher than that through `.nvmrc`, root `package.json` engines, README badges, development docs, and CI, so the website must join the repository's Node.js `26.2.0+` baseline instead of pinning to an older line.
### Repository Integration
* Add `public-website` to root `package.json` workspaces.
* Add `public-website` to root format/lint script paths.
* Ensure root `npm run typecheck` and `npm run build` include the website workspace through npm workspaces.
* Keep website dependencies local to `public-website/package.json` unless they are already root-level tooling shared by the repo.
* Keep public demo deployment and public website deployment independent.
* Preserve existing files already present in `public-website/` during scaffolding. If direct scaffolding would overwrite them, scaffold in a temporary directory and merge generated files back.
### Expected Folder Structure
```
public-website/
|-- package.json
|-- astro.config.mjs
|-- tsconfig.json
|-- public/
| |-- favicon.svg
| |-- robots.txt
| |-- site.webmanifest
| |-- press/
|-- src/
| |-- assets/
| | |-- brand/
| | |-- showcase/
| | |-- pages/
| |-- components/
| | |-- brand/
| | |-- content/
| | |-- layout/
| | |-- marketing/
| | |-- navigation/
| | |-- seo/
| | |-- system/
| |-- content/
| | |-- blog/
| | |-- news/
| |-- content.config.ts
| |-- data/
| | |-- navigation.ts
| | |-- site.ts
| | |-- features.ts
| | |-- use-cases.ts
| | |-- faq.ts
| | |-- roadmap.ts
| |-- layouts/
| | |-- BaseLayout.astro
| | |-- ContentLayout.astro
| | |-- LegalLayout.astro
| |-- pages/
| | |-- index.astro
| | |-- product.astro
| | |-- features.astro
| | |-- how-it-works.astro
| | |-- security.astro
| | |-- investors.astro
| | |-- about.astro
| | |-- contact.astro
| | |-- press.astro
| | |-- roadmap.astro
| | |-- faq.astro
| | |-- use-cases/
| | | |-- index.astro
| | | |-- engineering-teams.astro
| | | |-- ai-platform-teams.astro
| | | |-- founders.astro
| | | |-- power-users.astro
| | |-- blog/
| | | |-- index.astro
| | | |-- [...slug].astro
| | |-- news/
| | | |-- index.astro
| | | |-- [...slug].astro
| | |-- legal/
| | | |-- index.astro
| | | |-- privacy.astro
| | | |-- terms.astro
| | | |-- acceptable-use.astro
| | |-- rss.xml.js
| |-- styles/
| |-- global.css
```
### Design Direction
Implement a Cyber-Tactical Dark System inspired by military radar, high-end developer terminals, and the FactionOS cockpit. The website should feel like stepping into a terminal cockpit: premium, technical, tactical, fast, and specific. It should wow developers quickly without becoming generic SaaS marketing.
Core UX pillars:
* Premium dev-console aesthetic with sleek dark modes, HSL neon-glow accents, crisp borders, and tactical grid patterns.
* Show concrete product states instead of aspirational labels: battlefield mockups, active subagent lineage nodes, and live terminal pipelines.
* Treat privacy as a design feature by visibly explaining the local-first security boundary and protecting developer workspaces and LLM credentials.
* Make navigation frictionless with visible high-contrast paths to the demo and public docs.
Color and token requirements:
```css
:root {
--color-bg: hsl(224 25% 6%);
--color-bg-elevated: hsl(224 20% 9%);
--color-surface: hsl(224 20% 12% / 0.75);
--color-border: hsl(180 100% 50% / 0.22);
--color-accent: hsl(180 100% 50%);
--color-accent-2: hsl(270 95% 65%);
--color-success: hsl(145 80% 45%);
--color-danger: hsl(355 90% 55%);
--color-text: hsl(210 40% 98%);
--color-muted: hsl(215 15% 70%);
--font-display: "Orbitron", "Rajdhani", system-ui, sans-serif;
--font-body: "Outfit", system-ui, sans-serif;
--font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
}
```
Token meanings:
* Background: Space Black `hsl(224, 25%, 6%)` and Navy Obsidian `hsl(224, 20%, 9%)`.
* Surface/cards: transparent Obsidian glassmorphism `hsla(224, 20%, 12%, 0.75)` with `backdrop-filter: blur(12px)` where performance and readability allow.
* Accent primary: Cyber Cyan `hsl(180, 100%, 50%)`.
* Accent secondary: Hyper Purple `hsl(270, 95%, 65%)`.
* Positive state: Matrix Green `hsl(145, 80%, 45%)`.
* Critical state: Crimson Laser `hsl(355, 90%, 55%)`.
* Primary text: Ice White `hsl(210, 40%, 98%)`.
* Muted text: Tactical Slate `hsl(215, 15%, 70%)`.
Typography requirements:
* Headings/readouts: `Orbitron` and `Rajdhani`.
* Body: `Outfit`.
* Code: `JetBrains Mono`.
* Use local font files or a privacy-conscious loading plan. If Google Fonts is used temporarily, document it as a third-party request and be ready to self-host before production if privacy review requires it.
Interactive accents:
* Soft radial glows behind active elements, for example `box-shadow: 0 0 20px hsla(180, 100%, 50%, 0.15)`.
* Tactical CSS background patterns for radar rings, coordinate maps, and horizontal sweep lines.
* Button cyber-sweep hover transitions.
* Status pulse rings.
* Lightweight scroll reveal only if safe.
* Battlefield preview micro-motion using CSS transforms.
Motion implementation examples:
* Primary button hover timing: `transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1)`.
* Scanline animation: `@keyframes scanline { 0% { transform: translateY(-100%); } 100% { transform: translateY(100%); } }`.
* Pulse ring animation: `@keyframes pulse-ring { 0% { box-shadow: 0 0 0 0 rgba(23, 206, 82, 0.7); } 70% { box-shadow: 0 0 0 10px rgba(23, 206, 82, 0); } }`.
* Scroll reveal starting state: `opacity: 0; transform: translateY(15px); transition: opacity 0.6s, transform 0.6s`.
Reduced-motion layer:
```css
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.001ms !important;
animation-iteration-count: 1 !important;
scroll-behavior: auto !important;
transition-duration: 0.001ms !important;
}
}
```
Continuous background scanner animations must stop for reduced-motion users. Static neon borders and state indicators should remain visible.
### Shared Layout And Component Inventory
Phase 13 should establish these primitives or prepare their homes:
Layout:
* `Shell.astro` or equivalent page chrome wrapper for background layers, skip link, header, and footer.
* `Section.astro` for consistent full-width sections with constrained inner content.
* `BaseLayout.astro`
* `ContentLayout.astro`
* `LegalLayout.astro`
* `Header.astro`
* `MobileNav.astro`
* `Footer.astro`
* `SkipLink.astro`
SEO:
* `Seo.astro`
* `OpenGraphImage.astro` if generated images become necessary later.
* `JsonLd.astro`
Marketing/product:
* `HeroCockpit.astro`
* `BattlefieldPreview.astro`
* `LiveStatusPanel.astro`
* `ThreePillarDeck.astro`
* `FeatureMatrix.astro`
* `FeatureBand.astro`
* `UseCaseGrid.astro`
* `PipelineDiagram.astro`
* `TerminalWindow.astro`
* `SecurityBoundary.astro`
* `RoadmapTimeline.astro`
* `FaqList.astro`
* `PressAssetGrid.astro`
* `ExternalCta.astro`
Content:
* `PostCard.astro`
* `PostMeta.astro`
* `TagList.astro`
* `CollectionHero.astro`
* `RelatedPosts.astro`
System:
* `ButtonLink.astro`
* `Panel.astro`
* `MetricStrip.astro`
* `Badge.astro`
* `Icon.astro` or small inline icon components.
Use icon-only controls only when there is a familiar symbol and a clear accessible name. Otherwise use text or icon plus text. Do not put page sections inside decorative cards. Use cards only for repeated items, content previews, modals, or genuinely framed product panels.
### Asset Requirements
Existing assets to review and reuse:
* `assets/brand/factionos-logo.png`
* `assets/brand/factionos-logo.webp`
* `assets/brand/factionos-logo-square.png`
* `assets/brand/factionos-logo-square.webp`
* `assets/showcase/factionos-strip.webp`
* `assets/showcase/factionos-strip-cover.jpg`
* `assets/showcase/heroes-banner.jpg`
* `assets/showcase/strip-frames/*.jpg`
Asset work:
* Copy or import needed brand/showcase assets into `public-website/src/assets/` so Astro can optimize them.
* Add a committed website mockup image if `assets/showcase/factionos-website-mockup.png` is intended to become the canonical visual blueprint.
* Create favicon and social preview assets:
* `public/favicon.svg`
* `public/site.webmanifest`
* `src/assets/brand/og-default.png`
* page-specific Open Graph images where helpful.
* Generate responsive image usages with Astro `` and ``.
* Keep `public/` for files that intentionally bypass processing, such as favicons, robots, and downloadable press files.
### Content Collections
Create `src/content.config.ts` with `blog` and `news` collections.
Shared schema:
* `title`: string.
* `description`: string.
* `pubDate`: date.
* `updatedDate`: optional date.
* `draft`: boolean default false.
* `tags`: string array default empty.
* `heroImage`: optional image.
* `canonicalUrl`: optional URL.
* `author`: optional string.
News-specific optional fields:
* `category`: enum `release`, `changelog`, `company`, `press`.
* `version`: optional string.
Draft handling:
* Exclude drafts from production builds.
* Permit drafts during local development if useful.
* Add a visible draft badge in development templates.
* Product and legal pages can remain `.astro` pages until they need collection-driven metadata.
Seed content:
* Blog:
* `introducing-factionos.md`
* `local-first-agent-observability.md`
* `why-agent-work-needs-a-cockpit.md`
* News:
* `initial-public-website.md`
* `public-demo-available.md`
Seed content can be short but must be realistic enough to validate templates, RSS, sitemap, tags, and metadata.
### SEO, Metadata, And Static Plumbing
`astro.config.mjs` requirements:
* Set `site: "https://faction-os.com"`.
* Add sitemap integration.
* Add MDX integration.
* Keep static output default.
Every indexable page needs:
* Title.
* Description.
* Canonical URL.
* Open Graph title.
* Open Graph description.
* Open Graph image.
* Twitter card metadata.
* Robots behavior.
Structured data candidates:
* Organization.
* WebSite.
* SoftwareApplication.
* BlogPosting for blog entries.
* NewsArticle for news entries where appropriate.
* FAQPage for FAQ if content is stable.
RSS requirements:
* Generate RSS for blog and news, or a combined feed if simpler.
* Include only non-draft posts.
* Use absolute URLs.
* Include descriptions without overloading the feed with huge content.
* Expose `/rss.xml` or the chosen generated RSS path.
Robots requirements:
* `public/robots.txt` should allow normal crawl.
* Reference the sitemap.
* Do not expose private or non-existent paths.
* Sitemap output may be `/sitemap-index.xml` or the generated path provided by the Astro sitemap integration.
### Accessibility Baseline
* Valid semantic landmarks: `header`, `nav`, `main`, and `footer`.
* Skip link to main content.
* One `h1` per page.
* Heading levels in order.
* Keyboard-visible focus for all links and controls.
* Accessible names for external links, icon buttons, and preview controls.
* Color contrast minimum `4.5:1` for body text.
* Do not rely on color alone for state.
* Respect `prefers-reduced-motion`.
* Ensure product mockups are semantic HTML or have useful alt text and nearby explanatory text.
* Ensure responsive text wraps cleanly and never overlaps at mobile widths.
### Privacy And Security
* No analytics by default.
* No trackers.
* No hosted form submission.
* No client-side code that sends page data to third parties.
* External links to demo and public docs must be explicit.
* Contact flows should use `mailto:` or owner-approved external destinations.
* Do not collect prompts, local paths, replay data, demo session payloads, terminal output, credentials, or user-provided code.
* Security page copy must clearly distinguish core local workflow, optional integrations, and future hosted surfaces.
### Relevant Considerations
* \[P04] Asset provenance gates remain active. Non-release assets need source, rights, attribution, metadata, fallback, accessibility, privacy, and budget evidence before promotion.
* \[P07] Hosted services and analytics remain disabled-default guardrails only. Do not imply active hosted auth, hosted storage, analytics capture, push, or remote access.
* \[P07] Redaction is boundary-specific. Marketing copy must not imply prompts, local paths, commands, terminal output, replay buffers, exports, diagnostics, logs, or backups leave the local machine by default.
* \[P08] Release evidence is claim-scoped. Local build success is not proof of production-hosted validation, formal certification, trusted erasure, broad media readiness, or active hosted services.
* \[P02] Responsive and accessibility debt must be handled before launch: mobile, focus, dialog/navigation semantics, reduced motion, contrast, and full validation matter for public site quality.
### Risks
* Website copy could overclaim hosted services or security posture. Mitigation: use conservative local-first language and copy guardrail review in later sessions.
* Third-party font loading could create an unnecessary external request. Mitigation: prefer self-hosted fonts before launch or explicitly document any temporary third-party font request.
* Asset promotion could accidentally use non-release media. Mitigation: use known brand/showcase assets only after provenance review and keep generated or unknown media out of launch surfaces.
* Astro scaffold could overwrite planning or existing files. Mitigation: scaffold in a temporary directory or preserve existing files before running the wizard.
***
## Success Criteria
Phase complete when:
* [x] All 5 sessions completed.
* [x] `npm --workspace @factionos/public-website run build` succeeds.
* [x] `npm --workspace @factionos/public-website run typecheck` succeeds.
* [x] Base routes render with shared layout, metadata, navigation, and footer.
* [x] Blog/news content collections validate frontmatter and exclude production drafts.
* [x] No analytics, hosted forms, server-rendering dependencies, CMS adapter, auth flow, or dashboard login are introduced.
* [x] Brand/showcase asset usage stays within provenance and optimization expectations.
***
## Dependencies
### Depends On
* Phase 12: Codex Packaging and Release Readiness.
* Repository Node.js `26.2.0+` baseline.
* Existing FactionOS local-first product and privacy boundaries.
### Enables
* Phase 14: Homepage And Core Product Story.
* Phase 15: Trust, Content, And Conversion Pages.
* Phase 16: Quality, Deployment, And Launch Handoff.
---
# 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/archive/phases/phase_13/prd_phase_13.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.