> 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/implementation-plan-2026-07-05.md).

# FactionOS Public Website Implementation Plan

Date: 2026-07-05

Status: ready for implementation. No `sites/factionos-public-website/` workspace exists yet; this plan creates it.

## 1. Sources Of Truth

| Input                    | Path                                                                                                                                                                             | Role                                                                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Design intelligence      | [design/design-intelligence-2026-07-05.md](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-website/docs/design/design-intelligence-2026-07-05.md)                 | Brand system, tokens, page blueprint, motion system, copy matrix, QA checklist.                                                                          |
| Extraction note          | [content/static-to-astro-extraction-2026-07-05.md](https://github.com/AI-with-Apex-VIP/factionos/tree/main/public-website/docs/content/static-to-astro-extraction-2026-07-05.md) | Route contract, content model, privacy posture, parity evidence.                                                                                         |
| Rendered route snapshots | `content/extracted/rendered-routes/` (31 files)                                                                                                                                  | Canonical page copy to preserve or deliberately rewrite.                                                                                                 |
| Raw source archive       | `content/raw/source/public-website/` (158 files)                                                                                                                                 | Rebuild input: `src/content/`, `src/data/`, pages, components, layouts, media.                                                                           |
| Manifests and reports    | `content/manifests/`, `content/reports/`                                                                                                                                         | Route/asset/SEO parity checks during and after the build.                                                                                                |
| Acquired asset manifest  | [acquired-media-asset-manifest-2026-07-05.md](/faction-os-docs/public-website/docs/acquired-media-asset-manifest-2026-07-05.md)                                                  | Staged asset provenance and checksums.                                                                                                                   |
| Live asset staging       | `tmp/factionos-public-website-assets/` (repo root)                                                                                                                               | Implementation source of truth for brand, fonts, HUD icons, hero video, social, synthetic data. Verify hero files against the delivery `SHA256SUMS.txt`. |

Where documents disagree on staged file counts (117 vs 83 vs 128), the live staging folder plus the Veo delivery `SHA256SUMS.txt` win.

## 2. Goals

1. Rebuild the FactionOS public website as a fresh, self-contained Astro 7 static site in `sites/factionos-public-website/`, deployable to Cloudflare Pages.
2. Preserve the full route contract: 31 HTML routes (22 fixed, 5 blog, 4 news) plus 7 static endpoints, canonical `https://faction-os.com`, no-trailing-slash canonicals, homepage canonical `/`.
3. Deliver the "cinematic strategy HUD" redesign: Mission Boot Sequence hero on the approved Veo 3.1 Fast plate, mission board product proof, hook-to-cockpit flow, capability deck, rules of engagement, role routes, adapter surface, field notes, final command CTA.
4. Hold the documented privacy posture: no hosted forms, no analytics/trackers, no runtime fetch/WebSocket/EventSource/beacon, no storage or cookie writes, synthetic data always labeled.
5. Green Core Web Vitals with poster-first paint, disciplined hydration, and complete `prefers-reduced-motion` fallbacks.

### Non-Goals

* No new commercial packaging, pricing pages, customer logos, or metrics (none are verified).
* No live telemetry, demo hosting, or account behavior on the public site.
* No Seedance hero variant, Orbitron promotion, or grounded-v2 alternates in this pass (future A/B options only).
* No API Catalog, OAuth/OIDC, MCP/A2A, WebMCP, or payment-discovery stubs; publish those only if the public site later exposes real backing capabilities.
* No redirects needed: source and final route contracts match; `redirects.csv` is header-only.

## 3. Stack Decisions (Motion & UI Ladder)

Framework baseline: Astro 7 static output, strict TypeScript, MDX/content collections, `@astrojs/sitemap`, RSS, Sharp image processing. Styling: Tailwind v4 via **`@tailwindcss/vite`** (not `@astrojs/tailwind`) layered over the design-token CSS variables from the design doc. Astro 7 is intentional here: `astro@latest` is now 7.x, and the archived source already drifted to an Astro 7 beta pin. Do not leave the framework version to an unrecorded scaffold default.

```bash
pnpm create astro@latest . -- --template minimal --typescript strict
pnpm add -E astro@7.0.6 @astrojs/mdx@7.0.2 @astrojs/sitemap@3.7.3 @astrojs/rss@4.0.19 sharp@0.35.3
pnpm add -E tailwindcss@4.3.2 @tailwindcss/vite@4.3.2 motion@12.42.2
pnpm add -D -E typescript@6.0.3 @astrojs/check@0.9.9 @playwright/test@1.61.1
```

Version snapshot verified on 2026-07-05. If implementation happens later, re-run `pnpm view` for the same package set, pin exact stable versions in `package.json`, and record any version drift in this plan.

**No React. No GSAP/Lenis. No `<ClientRouter />`. No `framer-motion`, `@studio-freight/lenis`, or `@astrojs/tailwind`.** Every motion requirement in the design doc is achievable at rungs 1–5 of the ladder; descending further is not earned. `<ClientRouter />` is deliberately excluded because Astro's client router turns navigation into SPA-mode client-side routing and enables prefetch behavior, which conflicts with the documented zero runtime-fetch privacy gate.

| Motion requirement (design doc)           | Chosen rung                               | Implementation                                                                                                                                                                                                                              |
| ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hero cinematic plate                      | Pre-rendered video (off-ladder, approved) | Veo AV1/VP9/H.264 `<video>`, AVIF poster first paint, in-view playback only.                                                                                                                                                                |
| Mission Boot Sequence (900–1400ms)        | CSS keyframes + one small vanilla script  | Staggered CSS animations sequenced by `animation-delay` tokens; a tiny idle-hydrated script flips `data-boot="ready"` and enables the CTA-active state.                                                                                     |
| Route trace / line draw                   | CSS/SVG                                   | `stroke-dashoffset` transitions on inline SVG routes.                                                                                                                                                                                       |
| State pulse, scan sweep, holographic edge | CSS only                                  | Keyframes on `transform`/`opacity`/mask; `--motion-*` and `--effect-*` tokens.                                                                                                                                                              |
| Section entrances ("command deck loads")  | CSS scroll-driven animations              | `animation-timeline: view()` inside `@supports`, IntersectionObserver fallback (one shared \~1 KB script).                                                                                                                                  |
| Operator doctrine character reveal        | CSS scroll-driven per-glyph opacity       | Build-time word/glyph spans (Astro component), `aria-label` with full text, plain text under reduced motion.                                                                                                                                |
| Signal relay counter-panning rails        | CSS scroll-driven `scroll()` timeline     | Two rows translating in opposite directions; semantic list content; static when unsupported or reduced motion.                                                                                                                              |
| Mission stack sticky-scaling cards        | CSS `position: sticky` + `view()` scale   | Collapses to plain ordered stack on mobile.                                                                                                                                                                                                 |
| Replay scrub, lane hover/focus highlight  | Vanilla Motion / small vanilla JS island  | One `client:visible` script on the mission board; `import { animate } from "motion"`.                                                                                                                                                       |
| Magnetic hover (hero command core only)   | Small vanilla JS                          | Pointer-tracked transform, capped px, disabled under reduced motion and coarse pointers.                                                                                                                                                    |
| Route transitions                         | Native MPA navigation only                | No Astro client router in this pass. If browser-native cross-document view transitions are later used, keep them progressive and JS-free; any `<ClientRouter />` adoption requires a documented privacy-boundary change and checker update. |

UI component layer: Astro-native zero-JS components throughout (marketing/content site). No component library dependency; the HUD component system is bespoke per the design doc.

Client JS budget: three small scripts total — (a) boot/hero controller (idle), (b) mission board interactivity (visible), (c) shared IO fallback + off-screen pause utility. Everything else ships as HTML/CSS/SVG; there is no router, prefetcher, analytics, or hidden app shell.

## 4. Workspace Layout

```
sites/factionos-public-website/
├── astro.config.mjs            # site: 'https://faction-os.com', trailingSlash: 'never', sitemap
├── package.json                # dev/build/preview/quality/test:e2e scripts
├── public/
│   ├── fonts/factionos/        # promoted woff2 (Oxanium, Outfit, Rajdhani 600/700, JetBrains Mono)
│   ├── hero/                   # factionos-grounded-hero-02-room-cockpit.{av1.mp4,vp9.webm,h264.mp4}
│   ├── icons/factionos-app-icon.svg + derived favicons/PWA rasters
│   ├── og/                     # final regenerated social rasters
│   └── robots.txt, _headers    # crawl policy, Link headers, cache/security headers
├── src/
│   ├── assets/
│   │   ├── brand/              # factionos-lockup.svg, factionos-mark.svg, factionos-mark-mono.svg
│   │   ├── hero/               # poster.avif, poster.webp (imported via astro:assets, preloaded)
│   │   └── social/             # og source SVGs
│   ├── components/
│   │   ├── hud/                # MissionMap, AgentLaneCard, EventTimeline, ReplayRail, RulePanel,
│   │   │                       # StatusRing, BoundaryChip, CapabilityTile, RoleRouteCard, CtaButton…
│   │   ├── motion/             # BootSequence, SectionReveal, DoctrineReveal, SignalRelay, MissionStack
│   │   └── site/               # Header, Footer, Nav, FaqAccordion, PostureBadges
│   ├── content/                # blog/ + news/ collections (from raw/source archive)
│   ├── content.config.ts
│   ├── data/                   # migrated src/data/*.ts durable copy + factionos/mission-state.json
│   ├── icons/hud/              # 10 promoted HUD SVGs as inline components
│   ├── layouts/BaseLayout.astro  # fonts, tokens, SEO head; no ClientRouter
│   ├── pages/                  # 22 fixed routes + collection routes + generated endpoints
│   ├── scripts/                # boot-controller.ts, mission-board.ts, motion-utils.ts
│   └── styles/
│       ├── global.css          # @import "tailwindcss"; token variables; @font-face
│       └── tokens.css          # Section 10 design tokens as CSS custom properties
└── tests/e2e/                  # Playwright: routes, reduced motion, a11y smoke
```

Site README: `README_factionos-public-website.md` (never bare `README.md` in a nested directory).

Do not create a nested repo-authored file literally named `README.md`. The legacy public endpoint `/press/README.md` is still part of the route contract, but implement it as a generated endpoint such as `src/pages/press/README.md.ts`, not as `public/press/README.md`.

Package scripts:

```json
{
  "dev": "astro dev",
  "build": "astro build",
  "preview": "astro preview",
  "typecheck": "astro check && tsc --noEmit",
  "check:links": "node ./scripts/check-links-and-privacy.mjs",
  "quality": "pnpm typecheck && pnpm build && pnpm check:links",
  "test:e2e": "playwright test"
}
```

## 5. Asset Promotion Plan

Promote **only** the production rows from the design doc's asset usage map. Verify every hero delivery file against `delivery/veo31-fast/SHA256SUMS.txt` after copying. The built site must contain zero references to `tmp/` paths.

| Staging source                                                                              | Destination                                             | Notes                                                                                                                                        |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand/factionos-lockup.svg`, `factionos-mark.svg`, `factionos-mark-mono.svg`               | `src/assets/brand/` (or inline components)              | Mono mark also derives `public/favicon.svg`.                                                                                                 |
| `brand/factionos-app-icon.svg`                                                              | `public/icons/` + derived raster favicon/PWA sizes      | Generate rasters during implementation.                                                                                                      |
| `fonts/woff2/oxanium-latin-wght-normal.woff2`, `outfit-latin-wght-normal.woff2`             | `public/fonts/factionos/`                               | The two preloaded critical faces.                                                                                                            |
| `fonts/woff2/rajdhani-latin-600/700-normal.woff2`, `jetbrains-mono-latin-wght-normal.woff2` | `public/fonts/factionos/`                               | Not preloaded unless measured first-viewport critical.                                                                                       |
| `fonts/font-face.css`, `preload-snippet.html`                                               | Merged into `global.css` / layout head                  | Do not ship standalone.                                                                                                                      |
| Veo delivery `public/hero/*.{mp4,webm}`                                                     | `public/hero/factionos-grounded-hero-02-room-cockpit.*` | \~3.25 MB combined; AV1 → VP9 → H.264 source order.                                                                                          |
| Veo delivery `src/assets/hero/*poster.{avif,webp}`                                          | `src/assets/hero/`                                      | AVIF preloaded; WebP fallback; reduced-motion still.                                                                                         |
| `hud-icons/*.svg` (10)                                                                      | `src/icons/hud/` as currentColor inline components      | Placement per the design doc's HUD icon table.                                                                                               |
| `synthetic-data/mission-state.json`                                                         | `src/data/factionos/mission-state.json`                 | One typed data source drives animated UI **and** accessible list/table fallbacks. Always render "Synthetic demo data. No visitor telemetry." |
| `social/og-{default,product,security,docs}.svg`                                             | `src/assets/social/`; final rasters → `public/og/`      | Regenerate rasters **after** the font pipeline is wired.                                                                                     |

Never promote: Orbitron (default decision), Seedance set, raw/processed/metadata/QA/preview files, checksums, licenses, manifests, staging READMEs, grounded-v2 PNGs. Keep licenses/provenance in docs.

## 6. Foundations: Tokens, Typography, Base Layout

1. **Tokens** — transcribe Section 10 of the design doc verbatim into `src/styles/tokens.css` (`:root` custom properties: colors, fonts, radii, shadows, motion durations/easings, effect values, breakpoints) and map them into Tailwind v4 `@theme` so utilities resolve to tokens. No hardcoded hex in components.
2. **Fonts** — hand-authored `@font-face` (from `fonts/font-face.css`), `font-display: swap`, self-hosted. Preload exactly two files: Oxanium variable + Outfit variable. Roles: Oxanium 700–800 display (never request 900), Rajdhani 600/700 HUD/UI, Outfit 400–650 body, JetBrains Mono 500–800 data. Fallback stacks per token block.
3. **BaseLayout** — dark `color-scheme`, canonical/SEO head component fed by `seo-surfaces.csv` values, skip link, font preloads, poster preload on the homepage only. Do not add `<ClientRouter />`, `prefetch: true`, or any SPA navigation layer unless the privacy gate is intentionally re-scoped.
4. **Type scale** — clamp-based sizes from the token block; H1 gets the single custom hero treatment (stacked words + bracket/coordinate framing). Sentence case defaults; uppercase only for compact HUD/mono labels with `--tracking-hud`.
5. **Layout primitives** — 1180px standard / 1440px wide containers, 12-col desktop grid, section padding 80–112px desktop scaling down, 4–8px panel radii, 1px gunmetal borders, restrained state glows.
6. **Astro 7 template discipline** — fix unclosed tags and adjacent inline-element whitespace explicitly during the port; Astro 7's Rust compiler and JSX-style whitespace handling can surface bugs the old compiler corrected silently. Add a rendered-text snapshot diff against `content/extracted/rendered-routes/` so copy parity catches accidental word joins.

## 7. Routes And Content Model

Rebuild all routes from the archive, preserving copy unless the blueprint deliberately rewrites it (homepage is the major rewrite; interior pages are restyled with preserved content).

| Route family                                                                                                                                                            | Source                                                      | Disposition                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/` homepage                                                                                                                                                            | Blueprint Sections 1–10 + `rendered-routes/index.md` claims | Full redesign (Section 8 below). Preserve all boundary/synthetic-label claims.                                                         |
| Fixed pages: about, product, features, how-it-works, security, faq, roadmap, press, investors, contact, use-cases index + 4 use-case pages, legal ×3, blog/news indexes | `raw/source/.../src/pages/` + `src/data/*.ts`               | Port copy and data modules; restyle with new token/component system; keep titles/descriptions/canonicals per `seo-surfaces.csv`.       |
| Blog (5) and news (4) articles                                                                                                                                          | `raw/source/.../src/content/`                               | Content collections, schemas from archived `content.config.ts`; styled article layout in new system.                                   |
| RSS + 6 other static endpoints                                                                                                                                          | `raw/source` + `source-routes.csv`                          | Preserve final URLs; regenerate RSS/sitemaps; implement `/press/README.md` as a generated endpoint to avoid a nested `README.md` file. |

Parity gate: generated route list must match `reports/parity.json` (31 HTML routes, no duplicates); `manifests/source-routes.csv` is the checklist.

Static endpoint checklist:

| Endpoint                               | Implementation                                                                                |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `/favicon.svg`                         | Generated from the mono/app icon source into `public/favicon.svg`.                            |
| `/robots.txt`                          | Authored in `public/robots.txt`; SEO/AEO and agent-readiness policies live here.              |
| `/site.webmanifest`                    | `public/site.webmanifest`, regenerated from final favicon/PWA icon outputs.                   |
| `/press/README.md`                     | `src/pages/press/README.md.ts` or equivalent static endpoint; no physical nested `README.md`. |
| `/rss.xml`                             | Collection-driven endpoint from blog + news, draft-safe.                                      |
| `/sitemap-index.xml`, `/sitemap-0.xml` | Generated by `@astrojs/sitemap`; included in parity and robots checks.                        |

## 8. Homepage Build Plan (Section By Section)

Each section lists: components, motion rung, assets, accessibility.

### S1 — Cinematic Command Hero (must-have)

* **Components:** CommandHero, PostureBadges (Local-first / Synthetic demo / No website telemetry), CtaButton pair (Open Demo primary cyan, Read Docs secondary), brand lockup.
* **Media:** poster-first — AVIF poster renders at first paint (preloaded, `astro:assets`); `<video>` sources AV1/VP9/H.264 from `public/hero/`, muted, loop, `playsinline`, **no autoplay attribute** — playback starts via IO only when in view *and* `prefers-reduced-motion: no-preference`; paused off-screen.
* **Copy:** H1 "Mission control for AI coding agents." over the dark left copy-safe zone; all copy/CTAs/badges are semantic HTML over the plate, never baked in.
* **Motion:** Mission Boot Sequence — CSS-staggered grid resolve, mark edge-light, lane node entry, event-rail populate; total 900–1400ms (`--motion-boot`), CTAs readable immediately; subtle state loop every 10–16s. Magnetic hover on the command core only. Idle-hydrated boot controller flips ready state.
* **A11y/fallback:** reduced motion = static poster + full information; mission state has a text-list equivalent; focus states as intentional as hover.

### S2 — The Operator Problem

* Three "before" strips (terminal scrollback, session drift, hidden risk) resolving to FactionOS state labels on hover/focus. JetBrains Mono log fragments, `risk-marker` + `hook-event` icons.
* Motion: CSS scroll-driven section entrance; the **operator doctrine character reveal** lives here (one paragraph, glyph spans, `aria-label`, reduced-motion plain text).

### S3 — Mission Board Product Proof (must-have)

* Wide unframed command surface: agent roster, mission objective, status rings, trace rail, event stream (ordered list), approval checkpoint, replay marker — all driven by `mission-state.json`, visibly labeled synthetic.
* Motion: the one `client:visible` vanilla-Motion island — replay scrub highlights related lane/objective; lane hover/focus highlights route + latest event. Optional **mission stack** sticky-scaling panels if sequencing needs it.
* A11y: full table/list equivalent from the same JSON; ordered-list semantics on the timeline.
* Between S1/S3 (optional): one **signal relay** counter-panning rail of hook events/adapter names/status chips — semantic, synthetic-labeled, static tiles, CSS `scroll()` timeline.

### S4 — Hook-To-Cockpit Flow (must-have)

* Horizontal pipeline (vertical on mobile): Claude Code hooks → Codex CLI hooks → compatible producers → protocol JSON → local `/event` → server snapshot → WebSocket cockpit → optional adapters → optional War Room. Each node: input/output/boundary on focus/hover; optional exits gated amber/violet, never green.
* Copy from the existing how-it-works page; must not imply the website itself runs hooks. CTA: Read Docs.
* Motion: SVG stroke-dashoffset route traces on entrance (`--motion-route-trace`).

### S5 — Capability Deck (must-have)

* Five tactical loadout tiles: Observe, Coordinate, Review, Contain, Export — icon, state color, operator job, boundary chip. No nested cards. Tile hover shifts a map overlay behind the deck (CSS only). CTA: Inspect Features.

### S6 — Rules Of Engagement (must-have)

* Mission-contract RulePanel: Default / Optional / Blocked / No-claim columns; expandable sensitive data classes (prompts, paths, terminal output, credentials, replay, code); color-coded chips **always** paired with text labels.
* Proof line cites the static-scan posture (zero forms/fetch/socket/beacon/storage/cookie/tracker matches). CTA: Review Security. No compliance/certification claims.

### S7 — Role Routes

* Squad-selection cards for engineering teams, AI platform teams, founders, power users → existing use-case pages. Keyboard-accessible cards/segmented control.

### S8 — Provider And Adapter Surface

* Equipment bay: sources left, local core center, optional exits (Discord, Telegram, HTTPS, War Room) right. Contract language: "compatible producers can follow the event contract" — never "works with every agent." Source toggle reveals event-type examples (small vanilla JS or CSS-only details).

### S9 — Field Notes And Roadmap

* Mission-log strip: latest blog + news from collections with dates, roadmap themes. CTA: Read Field Notes. No traction claims.

### S10 — Final Command CTA (must-have)

* Command console: Open Demo + Read Docs large actions with destination/posture labels (demo and docs are separate external destinations, labeled as such), Contact tertiary.

## 9. Motion System Implementation Notes

* One orchestrated cinematic language; do **not** apply the same reveal preset to every card. Staggered reveals only where order matters (pipeline, event rows, rules, role routes).
* All animation on `transform`/`opacity`/SVG stroke/mask only; motion never changes layout, panel size, or grid dimensions (no CLS).
* CSS scroll-driven animations are progressive enhancement, not required content delivery. Wrap `view()`/`scroll()` timelines in `@supports`, keep content visible by default, and use one shared IntersectionObserver fallback for unsupported browsers.
* Shared `motion-utils.ts`: IO fallback registrar for `@supports (animation-timeline: view())` misses + off-screen pause for the hero video and any loop.
* Global reduced-motion gate: CSS `@media (prefers-reduced-motion: reduce)` disables all non-essential animation with complete static renders; JS scripts check `matchMedia` before attaching.
* No `<ClientRouter />`, route prefetcher, smooth-scroll hijacking, GSAP ticker, or global animation loop in this pass.
* Forbidden: particle fields, noise shaders, constant throbbing, CRT noise filters, decorative background loops, magnetized nav/cards/CTAs.
* Record any deviation from this motion approach back into the design docs.

## 10. SEO, Social, Endpoints

* `site`, `trailingSlash: 'never'`, canonical component; per-page title/description/OG/Twitter reproduced from `reports/seo-surfaces.csv` (homepage may get updated copy — record changes).
* JSON-LD types per current surfaces report; sitemap via `@astrojs/sitemap`; static endpoints preserved per Section 7.
* OG images: wire `og-default` (home + fallback), `og-product` (product/features/how-it-works/demo), `og-security` (security/legal/boundary), `og-docs` (blog/news/roadmap/press). Regenerate final rasters after fonts are live in the build.
* Add `llms.txt` and, if useful, `llms-full.txt` from the same content sources as the HTML. Keep core indexable text in static HTML, not islands.
* robots.txt policy: keep sitemap pointer, preserve legal route noindex behavior via page meta, and add explicit AI-bot / Content-Signal directives. Owner policy recorded on 2026-07-05: AI access is fully allowed for crawling, search, answer-engine citation, AI input, and model training. Do not block AI bots in `robots.txt` or Content-Signal unless owner policy changes.
* `public/_headers`: add cache headers for `/hero/*`, `/fonts/*`, `/og/*`, and immutable hashed assets; add homepage `Link` headers only for resources that exist and return `200` (`/sitemap-index.xml`, `/llms.txt`, optional markdown alternate).
* Markdown negotiation: prefer Cloudflare's zone-level "Markdown for Agents" if available after deploy. Do not add a Pages Function for negotiation unless the static-only/privacy architecture is deliberately updated.
* Agent-readiness exclusions: skip DNS-AID, Web Bot Auth, API Catalog, MCP/A2A, and commerce/payment signals because this public website has no agent endpoint, outbound bot, API, auth flow, or checkout surface.

## 11. Phased Milestones

**Phase 0 — Scaffold + foundations.** Create workspace, install latest stable Astro at implementation time + MDX + sitemap + RSS + Sharp, Tailwind v4 Vite plugin, tokens.css, fonts promoted + @font-face, BaseLayout with SEO head and no client router, Header/Footer/Nav. Gate: `pnpm quality` clean, fonts swap correctly, typecheck passes.

**Phase 1 — Content and route parity.** Port collections, data modules, all 22 fixed pages (restyled skeletons), RSS + static endpoints including generated `/press/README.md`. Gate: route list matches `parity.json` (31 routes + 7 endpoints), link check clean, rendered text snapshots catch Astro 7 whitespace regressions, SEO surfaces match `seo-surfaces.csv`.

**Phase 2 — Component system.** Build `hud/` components (map, lane card, timeline/replay rail, rule panel, status ring, boundary chip, capability tile, role route card, CTA buttons, FAQ accordion) as zero-JS Astro components with all states + a11y semantics, driven by `mission-state.json` types.

**Phase 3 — Homepage assembly.** Sections 1–10 static-first (poster hero, no motion yet). Gate: homepage complete and correct with JS disabled; reduced-motion render is the default render.

**Phase 4 — Motion pass.** Boot sequence, video wiring (IO playback + pause), scroll-driven entrances + IO fallback, doctrine reveal, signal relay, route traces, mission-board island, magnetic core. Gate: QA gates below.

**Phase 5 — Interior page polish + social.** Restyle interior pages fully in the new system; regenerate OG rasters; favicon/PWA derivations; add `llms.txt` / optional `llms-full.txt`.

**Phase 6 — SEO/AEO, agent-readiness, QA + staging.** Run the astro-seo-aeo and agent-ready-content-site checklist items that apply to a pure content site: sitemap/robots/meta/schema validation, AI-bot policy, Content-Signal, `_headers` Link targets, optional Cloudflare Markdown for Agents. Skip API/MCP/payment/Web Bot Auth/DNS-AID checks unless backing capabilities exist. Then run full gate (Section 12), Playwright e2e, Lighthouse/CWV evidence, staging deploy to Cloudflare Pages preview, and follow the documented launch/DNS plan for cutover. Production claims stay no-claim until an authorized deploy + HTTPS smoke check is recorded.

## 12. QA Gates (Evidence Required Before Sign-Off)

From the skill and the design doc's final checklist — blocking items:

1. **Route parity:** 31 HTML routes + 7 endpoints, canonicals exact, 0 unresolved links, 0 missing media (re-run extraction-style checks or `check:links` equivalent). `/press/README.md` is served, but no physical nested `README.md` file exists.
2. **Privacy posture:** built output re-scanned — zero matches for forms, fetch/XHR, WebSocket, EventSource, beacon, storage/cookie writes, tracker hosts; no `tmp/` path references; no ClientRouter/prefetch runtime.
3. **Right rung:** every motion section uses the lightest layer clearing its visual bar; no React/GSAP/Lenis/router present; packages are `motion` and `@tailwindcss/vite` with no stale package names.
4. **Hydration discipline:** hero controller idle, board island visible; nothing heavy on `client:load`; video and loops pause off-screen; poster-first first paint verified.
5. **CWV:** green LCP/INP/CLS on homepage + one article page (Lighthouse + throttled run); no main-thread jank; no layout shift from motion or font swap; only two font preloads.
6. **Reduced motion:** complete, intentional static render everywhere; doctrine reveal exposes full text; hero shows poster; mission board fully readable.
7. **Accessibility:** WCAG 2.2 AA — state colors always text-labeled, visible focus, external links labeled, map has list/table equivalent, timeline is an ordered list, FAQ uses button + `aria-expanded`, keyboard paths through role routes and board.
8. **Brand fit:** Oxanium/Rajdhani/Outfit/JetBrains Mono applied per role; semantic state colors (cyan active, green ready/local, amber warning/static, violet review/queued, red risk); no nested cards, no generic neon, no militarized/violent language, no invented metrics; synthetic labels visible wherever sample data renders.
9. **Boundary copy:** no claim of live telemetry, hosted runtime, universal provider support, certification, or trusted erasure; hero/demo labels say synthetic; external destinations labeled.
10. **SEO/AEO:** canonical equals `og:url` on every route; `sitemap-index.xml` + `sitemap-0.xml` resolve; titles/descriptions/robots match or intentionally update `seo-surfaces.csv`; JSON-LD validates; `llms.txt` resolves; AI-bot/Content-Signal policy is recorded.
11. **Agent-readiness:** homepage `Link` headers target only existing resources; markdown negotiation is either verified through Cloudflare's zone feature or explicitly deferred; DNS-AID/Web Bot Auth/API/MCP/payment checks are skipped with rationale because no backing capability exists.
12. **Latest Astro parity:** no strict-compiler markup errors; rendered text snapshot diff catches inline whitespace regressions; any rendering, whitespace, layout, visual, animation, or interaction issue is a launch-blocking bug until fixed; no reserved `src/fetch.ts` or Cloudflare cache-provider feature is added for this static site.
13. **Code quality:** `pnpm quality`, `pnpm test:e2e`, and `git diff --check` pass; tokens used (no hardcoded colors/durations); no secrets; no dead motion code; hero files match `SHA256SUMS.txt`.

## 13. Recorded Decisions And Remaining Risks

* **Primary CTA destinations are final for now:** "Open Demo" points to `https://demo.faction-os.com/`; "Read Docs" points to `https://faction-os.gitbook.io/faction-os-docs`. These are already present in `src/data/site.ts` and the archived route docs.
* **Astro target:** use the latest stable Astro available at implementation/upgrade time. Any rendering, whitespace, layout, visual, animation, or interaction defect is a launch-blocking bug until fixed.
* **Navigation approach:** keep normal static Astro page navigation with targeted cinematic motion, CSS transitions, and small focused scripts. Do not add Astro `ClientRouter`; it is not needed for a premium-looking site and would weaken the no-runtime-fetch/privacy posture.
* **AI-bot policy:** fully allowed. Configure `robots.txt` and Content-Signal to allow AI crawling, search, answer-engine citation, AI input, and model training. Still skip DNS-AID, Web Bot Auth, API/MCP, and payment discovery unless real backing services exist.
* **Brand-kit export:** no public brand-kit download in this pass, so outlining live SVG text in `factionos-lockup.svg` is not required for launch.
* **Font scope:** use the staged font weights as-is for now: Oxanium up to 800, Rajdhani 600/700, Outfit variable, and JetBrains Mono variable. Do not request unstaged heavier cuts.
* **Production quality bar:** do not compromise the premium design, animation, motion, assets, hero plate, or boot sequence. Performance work should optimize encoding, loading, hydration timing, CSS, asset weight, and caching while preserving the intended spectacle.
* **CTA priority:** current homepage CTA order is final for now; continue with the existing demo/docs/contact priorities.
* **Motion and asset plan:** full production motion, animation, and asset promotion remain required. Any accidental deviation from the approved motion or asset plan should be fixed or recorded as a dated implementation note with owner approval.

## 14. Implementation Progress Log (live)

Running log so an interrupted session can resume cleanly. Newest phase status on top. Workspace: `sites/factionos-public-website/`. Toolchain: Node 24 / pnpm 10.22 (repo is a `sites/*` pnpm workspace).

### Status board

| Phase                        | State                | Notes                                                                                                                                                             |
| ---------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 — Scaffold + foundations   | ✅ DONE               | typecheck + build clean; chrome + tokens + fonts live.                                                                                                            |
| 1 — Content & route parity   | ✅ DONE               | 31 routes exact; SEO/links/privacy/sitemap all pass.                                                                                                              |
| 2 — Component system (HUD)   | ✅ DONE               | mission-state loader + HUD components, typecheck clean.                                                                                                           |
| 3 — Homepage assembly        | ✅ DONE               | S1–S10 static-first; JS-disabled complete; reduced-motion = default.                                                                                              |
| 4 — Motion pass              | ✅ DONE               | Browser QA passed; H1 text-join bug fixed; optional signal relay not needed.                                                                                      |
| 5 — Interior polish + social | ✅ DONE               | OG/PWA rasters, manifest/head links, llms.txt, llms-full.txt, and OG route-family wiring validated.                                                               |
| 6 — SEO/AEO + QA + staging   | ✅ LOCAL/PREVIEW DONE | robots AI policy, Content-Signal, \_headers, e2e, Lighthouse, Wrangler header check, and non-production Pages preview deploy passed. Production remains no-claim. |

### Completion checkpoint — 2026-07-05

Final local/preview evidence for this implementation pass:

* `pnpm quality`: passed from `sites/factionos-public-website/`.
  * `pnpm typecheck`: 82 files, 0 errors, 1 existing Zod `.url()` deprecation hint.
  * `pnpm build`: 31 pages built; `sitemap-index.xml` and `sitemap-0.xml` generated.
  * `pnpm check:links`: 31 HTML routes, 0 issues; privacy scan stayed green for forms, fetch/XHR, WebSocket, EventSource, beacon, storage/cookie writes, trackers, ClientRouter/prefetch, and `tmp/` leakage.
* `pnpm test:e2e`: passed, 45 Playwright tests. Coverage includes all 31 HTML routes, 9 static endpoints including `llms.txt`/`llms-full.txt`, canonical/`og:url` parity, reduced-motion static render, no hero `autoplay`, mission-board keyboard focus state, robots/Content-Signal, `_headers` Link declarations, Link target existence, and route-family OG raster mapping.
* Lighthouse via `pnpm dlx lighthouse@latest` with Playwright Chromium:
  * Homepage: performance 96, accessibility 92, best-practices 100, SEO 100; FCP 1.7s, LCP 2.6s (2557ms lab), TBT 0ms, CLS 0, Speed Index 1.7s.
  * Article `/blog/introducing-factionos`: performance 99, accessibility 96, best-practices 100, SEO 100; FCP 1.6s, LCP 1.7s, TBT 0ms, CLS 0, Speed Index 1.6s.
  * Note: homepage lab LCP is 57ms over the 2.5s target while the overall performance score is green and no jank/CLS/TBT issue is present. Keep monitoring and optimize the hero video path further before production if the strict metric threshold is treated as blocking.
* Wrangler Pages local header verification: `wrangler pages dev dist --compatibility-date=2026-06-10` parsed 13 valid header rules. Homepage emitted `Link` headers for `/sitemap-index.xml` and `/llms.txt`, CSP/security headers were applied, and `/sitemap-index.xml`, `/llms.txt`, `/hero/*`, `/fonts/*`, and `/og/*` returned `200` with expected cache headers.
* Non-production Cloudflare Pages preview deploy: passed with Wrangler to branch `codex-preview-2026-07-05`.
  * Alias: `https://codex-preview-2026-07-05.factionos-public-website.pages.dev`
  * Final deploy id URL observed: `https://ced66922.factionos-public-website.pages.dev`
  * HTTPS smoke: homepage `200`, Link header present, CSP present, `/sitemap-index.xml`, `/llms.txt`, `/robots.txt`, `/og/og-default.png`, and the AV1 hero video returned `200`.
  * Production `https://faction-os.com/` and DNS remain untouched/no-claim.
* Agent-readiness scope: AI crawling/search/answer input/model training are explicitly allowed in `robots.txt` via named bot groups and `Content-Signal: search=yes, ai-input=yes, ai-train=yes`. DNS-AID, Web Bot Auth, API/MCP, and payment discovery remain intentionally skipped because this static public site exposes no backing capability. Markdown negotiation is explicitly deferred to Cloudflare's zone-level "Markdown for Agents" feature; no Pages Function was added.

Final implementation changes in this checkpoint:

* Added `README_factionos-public-website.md`; no nested repo-authored `README.md` exists. The public `/press/README.md` route remains generated by `src/pages/press/README.md.ts`.
* Added `public/_headers` with homepage Link headers, security headers, and cache headers for hero, fonts, icons, OG assets, `_astro`, sitemap/feed/LLM resources.
* Replaced placeholder `public/robots.txt` with the recorded full-allow AI-bot and Content-Signal policy.
* Added `playwright.config.ts`, `tests/e2e/site-readiness.spec.ts`, and `tests/e2e/reduced-motion.spec.ts`.
* Added route-family OG selection in `src/lib/media.ts` and wired it through `src/components/seo/Seo.astro`: product/features/how-it-works use `og-product`, security/legal use `og-security`, blog/news/roadmap/press use `og-docs`, and home/fallback use `og-default`.
* Adjusted `src/components/home/CommandHero.astro` so the AVIF poster remains preloaded and rendered as the poster-first CSS media plate, the idle video does not duplicate the poster, and the mobile decorative plate is constrained to the first hero viewport while the lower hero uses the dark command surface. The video fade now uses `--motion-standard`, and the decorative grid overlay is skipped on mobile first paint.

### Pause checkpoint — 2026-07-05, full pause requested

Paused immediately on user request. **Do not continue work until resumed.**

Latest completed evidence:

* Phase 4 browser QA passed against `astro preview` at `http://127.0.0.1:4327/` with repo-local Playwright via `@playwright/test`.
* Screenshots written to `/tmp/factionos-phase4-qa/`: `desktop-hero.png`, `desktop-mission-board.png`, `mobile-hero.png`, `reduced-motion-hero.png`.
* QA assertions passed: desktop hero `data-boot="ready"`, video plays in view with no `autoplay` attribute, mobile has 0 horizontal overflow, reduced-motion hero `data-boot="reduced"` with paused/hidden video, doctrine glyph opacity = 1, mission-board keyboard focus activates matching lane/event/map node, no browser console/page errors.
* `pnpm build` after the H1 fix: green, 31 pages built, sitemap generated.
* `pnpm typecheck` after the H1 fix: green, 78 files, 0 errors, 1 existing Zod `.url()` hint.

Phase 4 fix made during this resumed session:

* `src/components/home/CommandHero.astro`: added a visually hidden space before the second H1 line so DOM/rendered text reads "Mission control for AI coding agents." instead of "Mission controlfor AI coding agents."

Phase 5 partial work completed before pause:

* Generated rasters:
  * `public/og/og-default.png`
  * `public/og/og-product.png`
  * `public/og/og-security.png`
  * `public/og/og-docs.png`
  * `public/icons/factionos-app-icon-32.png`
  * `public/icons/factionos-app-icon-192.png`
  * `public/icons/factionos-app-icon-512.png`
  * `public/apple-touch-icon.png`
* Visual spot-check: OG and icon rasters are thumbnail-readable. They were generated with `sharp`; font rendering uses the rasterization environment rather than a browser-embedded font pipeline.
* `public/site.webmanifest`: added 192 and 512 PNG icon entries.
* `src/components/seo/Seo.astro`: added PNG favicon and Apple touch icon links.
* `public/llms.txt`: added concise static LLM site map.
* `src/pages/llms-full.txt.ts`: added collection-driven full LLM bundle endpoint with `x-markdown-tokens`. A typecheck failure on `entry.body` being possibly undefined was fixed by using `entry.body ?? ""`, but no post-fix typecheck/build has been run yet due to the pause.

Latest validation caveat:

* After adding `llms-full.txt.ts`, `pnpm build` succeeded and emitted `/llms-full.txt`, but the concurrent `pnpm typecheck` failed on `entry.body` optionality. That code was fixed, but the fixed state is **not yet revalidated**. Resume by running: `pnpm typecheck && pnpm build && pnpm check:links` from `sites/factionos-public-website/`.

Next resume steps:

1. Re-run `pnpm typecheck`, `pnpm build`, and `pnpm check:links`.
2. Verify `dist/llms.txt`, `dist/llms-full.txt`, `dist/og/*.png`, manifest icons, and head links.
3. Implement Phase 6 `public/robots.txt` policy and `public/_headers` only after confirming the generated resources resolve.
4. Add Playwright e2e/CWV checks and final plan update.

### Pause checkpoint — 2026-07-05

Paused after Phase 4 implementation, before Phase 5. Do **not** assume final launch readiness: browser visual QA, reduced-motion QA in Playwright/Chrome, OG/PWA raster generation, `llms.txt`, full robots/\_headers policy, e2e, Lighthouse/CWV, and staging deploy remain open.

Current validation evidence from this checkpoint:

* `pnpm typecheck`: 78 files, 0 errors, 1 existing Zod `.url()` deprecation hint.
* `pnpm build`: 31 pages built successfully; sitemap generated.
* `pnpm check:links`: 31 HTML routes, 0 issues. This re-verified the built JS after adding the dynamic `motion` import; no `fetch`, XHR, WebSocket, storage/cookie, tracker, router/prefetch, or `tmp/` leakage was detected.

Phase 4 files changed/added:

* `src/scripts/motion-utils.ts`: reduced-motion gate, `animation-timeline` support check, idle scheduling helper, shared IO fallback for `[data-reveal]`, and in-view video play/pause helper.
* `src/scripts/boot-controller.ts`: idle hero boot state (`idle` → `booting` → `ready`), in-view hero video control, document-visibility pause, and single-object magnetic command-core hover.
* `src/scripts/mission-board.ts`: one visible mission-board enhancement that dynamically imports `motion` only after the board nears the viewport; lane hover/focus/click highlights matching lane cards, event rows, and map nodes.
* `src/components/motion/DoctrineReveal.astro`: build-time word/glyph spans with full `aria-label`, CSS scroll-driven glyph reveal, IO fallback, and complete reduced-motion static text.
* `src/components/home/CommandHero.astro`: boot scan CSS, boot-item sequencing, video fade on `[data-video="playing"]`, magnetic transform tokens, and reduced-motion poster-only fallback.
* `src/components/site/Section.astro` + `src/styles/global.css`: visible-by-default section reveal hooks, CSS scroll-driven reveal, IO fallback, and removal of the one negative heading tracking value so headings comply with the frontend-design rule.
* `src/components/hud/MissionMap.astro` + `src/pages/index.astro`: route-trace hooks, map active states, S4 connector trace animation, doctrine replacement, and board-level hydration root.

Known-open after Phase 4 implementation:

* Run real browser QA before calling Phase 4 fully green: desktop/mobile screenshots, reduced motion emulation, keyboard through mission-board lane buttons, verify hero video starts only in view and pauses off-screen, verify no layout shift from boot/reveal/trace motion.
* Optional signal relay was intentionally not added yet; it remains optional. Do not add it unless screenshots show the S1 → S3 transition needs continuity.
* Phase 5 is next: generate `public/og/og-{default,product,security,docs}.png`, favicon/PWA rasters from `public/icons/factionos-app-icon.svg`, and `public/llms.txt` / optional `llms-full.txt`.
* Phase 6 remains untouched: final robots AI-bot/Content-Signal policy, `public/_headers`, Playwright e2e, Lighthouse/CWV evidence, and Cloudflare Pages staging deploy.
* The site workspace is ignored by `.git/info/exclude` (`sites/factionos-public-website/`), so ordinary `git status` currently surfaces only tracked repo changes such as `pnpm-lock.yaml`. Use explicit filesystem inspection or ignored-status commands when resuming.

### Phase 0 — DONE (2026-07-05)

Scaffolded **manually** (not `pnpm create astro`) for determinism. All pinned versions from §3 verified on npm and installed **exactly** (astro 7.0.6, @astrojs/mdx 7.0.2, sitemap 3.7.3, rss 4.0.19, sharp 0.35.3, tailwindcss + @tailwindcss/vite 4.3.2, motion 12.42.2, typescript 6.0.3, @astrojs/check 0.9.9, @playwright/test 1.61.1).

Done:

* `package.json` (dev/build/preview/typecheck/check:links/quality/test:e2e), `astro.config.mjs` (`site`, `trailingSlash:'never'`, **`build.format:'file'`** for CF-Pages no-trailing-slash canonicals, sitemap filter excludes `/legal/*`, `@tailwindcss/vite`), `tsconfig.json`.
* Assets promoted per §5 and **hero checksums verified against `SHA256SUMS.txt` (5/5 match)**. Fonts (5 faces, no Orbitron), hero video+poster, brand SVGs, 10 HUD icon SVGs, 4 OG source SVGs, `mission-state.json`, app icon.
* `src/styles/tokens.css` = design §10 tokens inside a Tailwind v4 `@theme` block (single source of truth: emits `:root` vars AND generates utilities; `--color-*: initial` resets the default palette). `global.css` = `@import tailwindcss` + tokens + 5 `@font-face` (swap) + base layer + component utilities (`.container-shell`, `.section-pad`, `.hud-label`, `.panel`, `.grid-backdrop`) + global reduced-motion gate.
* Ported **verbatim** (asset-independent, clean): `lib/metadata.ts`, `lib/content.ts`, `data/navigation.ts`, `content.config.ts`, `components/seo/Seo.astro`, `components/seo/JsonLd.astro`.
* New `lib/media.ts`: exposes brand SVGs (astro:assets) + OG descriptors pointing at `public/og/og-*.png`. Adapted `data/site.ts` to use it (dropped legacy raster import); `themeColor` → `#18e8ff`, `colorScheme` → `dark`, social image → `/og/og-default.png`.
* New chrome in `components/site/`: `BrandMarkMono.astro` (inline currentColor mark), `SkipLink.astro`, `MobileNavigation.astro`, `Header.astro`, `Footer.astro` (with posture badges) — source vanilla scripts preserved, restyled to new tokens. `layouts/BaseLayout.astro` wires head (2 font preloads + optional hero-poster preload) + SkipLink + Header + `main` + Footer.
* `public/`: `favicon.svg` (redesigned to new palette), `site.webmanifest`, `robots.txt` (basic; full AI-bot/Content-Signal policy deferred to Phase 6), plus `scripts/check-links-and-privacy.mjs`.
* Placeholder `src/pages/index.astro` (replaced in Phase 3).

Fixes applied for TS 6 / Astro 7 strictness (vs. the source's TS 5): `Seo.astro` `structuredPayloads` uses `.flat()` (Array.isArray won't narrow readonly arrays); removed `tsconfig` `baseUrl` (TS6 deprecation TS5101); `JsonLd` script marked `is:inline`.

**Deviations from plan (recorded):**

1. Legacy battlefield/showcase rasters + legacy raster wordmarks (`media.ts` `websiteMediaByKey`, `factionos-logo*.webp`, `og-default.png`, `showcase/*`) are **not** promoted — the design doc §6 asset map drops the battlefield theme. New `media.ts` covers brand SVG + OG only. The press page's `pressAssets` (in the to-be-ported `company.ts`) must be re-pointed from showcase keys to brand/OG previews in Phase 1/5.
2. Tokens authored directly in `@theme` (not a plain `:root` in tokens.css) so Tailwind utilities resolve to tokens with zero duplication — satisfies the plan's "map into @theme" intent.

**Known-open at Phase 0 close:** `pnpm check:links` reports 38 unresolved internal links — these are the nav targets (product/features/... /legal/\*) not built yet. Expected; clears in Phase 1 once all 22 routes + collections exist. OG rasters under `public/og/` not generated yet (Phase 5); metadata already points at their final paths.

### Phase 1 — DONE (2026-07-05)

All 31 HTML routes + 7 static endpoints built and verified. **Gates all green:**

* Route parity: built route set == `parity.json.htmlRoutes` exactly (31/31, 0 missing, 0 extra).
* `pnpm check:links`: 31 routes, 0 issues (no unresolved links, no privacy violations, no `tmp/` leaks, no trackers/forms/fetch/WebSocket/storage/cookie/router).
* SEO surfaces vs `seo-surfaces.csv`: title, robots, canonical, and JSON-LD types match on all 31 routes; `og:url == canonical` on all 31.
* Sitemap: 27 URLs (excludes the 4 noindex `/legal*` routes); legal robots = `noindex, nofollow`.
* Article pages render markdown body + `BlogPosting`/`NewsArticle` JSON-LD; reading time, dates, tags, prev/next, related all work.

What was built:

* **Data port:** all 8 remaining data modules copied verbatim except `company.ts` (re-pointed `pressAssets` from dropped battlefield showcase keys to a new `pressPreviewMedia` registry in `lib/media.ts`: wordmark lockup, command mark, OG default source). `content.config.ts`, collections (5 blog + 4 news md), `lib/content.ts` all verbatim.
* **Shared UI primitives** (`components/site/`): Badge, ButtonLink, Section, Panel, PageHero, Prose, MetricStrip, FaqAccordion (native `<details>` disclosure, zero-JS), CalloutCta, CtaBlock, CompanyHeroBlock, CompanyPanelGrid, PostCard, LegalDoc + `lib/tone.ts` (tone→color) and `lib/links.ts` (`toActionLink` — normalizes the `as const` route-link union so components read `.externalLabel` safely; this resolved 18 TS6 union errors).
* **Pages:** 22 fixed routes (home placeholder, about, investors, contact, press, product, features, how-it-works, security, faq, roadmap, use-cases hub + `[role].astro` for the 4 role pages via getStaticPaths, legal hub + 3 policies) + blog/news indexes + `[...slug]` article routes (shared `PostLayout`) + `rss.xml.js` + `press/README.md.ts` endpoint.
* **Canonical fix:** `build.format:'file'` makes `Astro.url.pathname` carry `.html`; centralized a `canonicalizeSegment` in `metadata.ts` `normalizeSitePath` to strip `.html`/`/index`/trailing slash so canonicals/og:url/sitemap are clean no-trailing-slash. Verified.

**Deviations/decisions (recorded):**

* FAQ uses native `<details>/<summary>` (zero-JS, accessible disclosure) rather than a JS `button + aria-expanded`. Satisfies WCAG disclosure; revisit in Phase 6 if the literal gate wording requires the button pattern.
* Interior pages are already restyled in the new token/component system (not raw skeletons), so Phase 5 interior work is mostly OG/social + final polish, not a re-style.
* Homepage `/` is still the Phase 0 placeholder (title "FactionOS" — matches CSV). The redesigned H1 ("Mission control for AI coding agents.") lands in Phase 3 and is an intentional, recorded copy change from the old homepage H1 ("FactionOS").

### Phase 2 — DONE (2026-07-05)

HUD component system, all zero-JS, all states, a11y, driven by `mission-state.json`.

* `src/data/factionos/mission-state.ts`: typed loader over the JSON (types Lane/MissionEvent/ Boundary/MissionRoute/Mission/Meta) + helpers `getLane`/`getBoundary`/`laneCallSign`/ `severityColor` + `SYNTHETIC_LABEL`.
* `components/hud/`: `HudIcon.astro` (inlines the 10 currentColor SVGs via `?raw`, strips outer `<svg>`, sized/aria-controlled wrapper), `StatusRing` (SVG stroke-dashoffset ring, role=img), `BoundaryChip` (color + always text label), `AgentLaneCard` (lane roster card; `interactive` prop renders a `<button>` with `data-lane`/`data-state` for the Phase 4 board island), `EventTimeline` (`<ol>`, `data-event`/`data-lane`), `MissionMap` (SVG command surface: grid + route trace threading lane coords + nodes; `role=img` + `.sr-only` lane list = the accessible equivalent; `animated` prop reserved for Phase 4), `CapabilityTile` (icon + job + boundary chip).
* Typecheck clean (73 files, 0 errors). Not yet exercised until Phase 3 used them.

### Phase 3 — DONE (2026-07-05, static-first)

Full homepage redesign, S1–S10, **static-first (no motion yet)**. `pnpm build` 31 pages, `astro check` 0 errors, `check:links` 31 routes / 0 issues, SEO surfaces still match CSV (title "FactionOS", canonical/robots/jsonLd unchanged; h1 intentionally now the redesign H1).

* `components/home/CommandHero.astro` (S1): poster-first — real `<img>` AVIF poster (`heroPoster.src`, matches BaseLayout preload) as base layer + layered `<video data-hero-video muted loop playsinline preload="none" poster=...>` at `opacity:0` (Phase 4 fades in on `[data-video="playing"]`), AV1→VP9→H.264 sources from `/hero/`. Left copy-safe zone: brand lockup, eyebrow, bracket-framed H1 "Mission control for AI coding agents.", body, 3 posture badges (Local-first/Synthetic demo/No website telemetry), Open Demo (primary) + Read Docs (secondary) CTAs, boundary line. Right: command-core panel with `StatusRing` (mission 68%), `data-magnetic` hook + `data-boot`/`data-boot-item` hooks for Phase 4 boot sequence.
* `src/pages/index.astro` replaced placeholder; sections use the HUD components + `homepage.ts` copy + `mission-state`:
  * S2 Operator Problem: doctrine paragraph (`data-doctrine`, full text in `aria-label`, plain text now) + 3 before→after strips (mono log → FactionOS state).
  * S3 Mission Board: `MissionMap` + mission objective panel + `StatusRing`; roster = `AgentLaneCard` list (`data-mission-board`, interactive buttons) + `EventTimeline`; synthetic label rendered. Map `.sr-only` list is the accessible equivalent of the visual board.
  * S4 Hook-to-Cockpit: `homepageLoopSteps` 4-node pipeline (connectors, in/out, boundary).
  * S5 Capability Deck: 5 `CapabilityTile`s (Observe/Coordinate/Review/Contain/Export) — authored inline (homepage.ts only ships 3 pillars; design wants 5).
  * S6 Rules of Engagement: 4 `mission-state` boundary columns + `homepageSecurityBoundary` sensitive-data classes (badges) + guardrails.
  * S7 Role Routes: `useCaseRoleList` → 4 route cards linking to the use-case role pages.
  * S8 Provider/Adapter: sources → local core → optional exits (Discord/Telegram/HTTPS/War Room), contract language, no inbound control.
  * S9 Field Notes: latest blog + latest news (collections) + roadmap current-focus items.
  * S10 Final Command CTA: `homepageFinalCta` via `CalloutCta`.

**Motion hooks created during Phase 3 and consumed during Phase 4:** hero `data-boot`, `data-boot-item="0..6"`, `data-hero-video`, `[data-video="playing"]`, `data-magnetic`, lane/event `data-lane` attributes, `MissionMap(animated)` route hooks, S4 connector hooks, and board root `data-mission-board`. The old plain `data-doctrine` paragraph was replaced by `components/motion/DoctrineReveal.astro`.

## Phase 4 — IMPLEMENTED / QA PARTIAL (motion pass)

Implementation status:

1. ✅ `src/scripts/motion-utils.ts` (shared): `matchMedia('(prefers-reduced-motion: reduce)')` gate, `animation-timeline` support check, IntersectionObserver fallback registrar, idle helper, and off-screen pause utility for hero video.
2. ✅ `src/scripts/boot-controller.ts`: idle boot controller flips hero `data-boot="idle" → "booting" → "ready"`; boot CSS staggers `[data-boot-item]` over about 1180ms; reduced motion bails to static.
3. ✅ Hero video: plays only when hero is in view and motion is allowed; sets `[data-video="playing"]` to fade video over poster; pauses off-screen and on document hide; no `autoplay` attribute.
4. ✅ CSS scroll-driven section entrances: `@supports (animation-timeline: view())` with transform/opacity only, visible by default, IO fallback via motion-utils.
5. ✅ S2 doctrine: build-time word/glyph spans in `components/motion/DoctrineReveal.astro`, full `aria-label`, CSS scroll-driven glyph opacity, IO fallback, reduced-motion static text.
6. ✅ SVG route traces: `MissionMap .map__route` and S4 connectors animate via `stroke-dashoffset` / `scaleX` on entrance; content visible by default.
7. ✅ Mission-board island: `src/scripts/mission-board.ts` dynamically imports `motion` after the board is near viewport; lane hover/focus/click highlights matching `.tevent[data-lane]`, lane card, and map node. Privacy scanner stayed green after the `motion` bundle was added.
8. ✅ Magnetic hover: reserved for hero `[data-magnetic]` command core only; pointer-fine only, capped at 8px, disabled under reduced motion and coarse pointers.
9. ⬜ Optional signal relay: not added. Keep optional unless visual QA shows the S1 → S3 transition needs an extra continuity device.
10. ⚠️ Gate partial: typecheck/build/check-links passed, but browser QA is still required for reduced-motion render, poster-first first paint, hero video in-view/off-screen behavior, keyboard lane highlights, and no CLS.

### Phases 5 & 6 — still TODO (unchanged from §11)

* **Phase 5:** regenerate OG rasters into `public/og/og-{default,product,security,docs}.png` (1200×630) from `src/assets/social/og-*.svg` — metadata already points at these paths but the files DO NOT EXIST YET (so social previews 404 until generated). Use `sharp`; brand fonts render via fallback unless a fontconfig/@font-face-embed pipeline is set up (document if fallback). Also: favicon/PWA raster derivations from `public/icons/factionos-app-icon.svg`; add `public/llms.txt` (+ optional `llms-full.txt`). Interior pages are ALREADY restyled (Phase 1), so this phase is mostly social/OG + final polish, not a re-style.
* **Phase 6:** full robots.txt AI-bot/Content-Signal policy (owner policy recorded: AI access fully allowed), `public/_headers` (cache for /hero /fonts /og + homepage Link headers only to existing 200 resources: /sitemap-index.xml, /llms.txt), Playwright e2e (`tests/e2e/`: routes, reduced-motion, a11y smoke), Lighthouse/CWV evidence, staging deploy to Cloudflare Pages preview. Skip API/MCP/payment/Web-Bot-Auth/DNS-AID.

### Resume checklist (fast context rebuild)

* Workspace: `sites/factionos-public-website/` (pnpm workspace member). Commands from there: `pnpm build`, `pnpm typecheck` (astro check + tsc), `pnpm check:links`, `pnpm quality`, `pnpm test:e2e`.
* Gates currently GREEN as of the Phase 4 pause: build (31 pages), typecheck (0 err, 1 zod `.url()` deprecation hint — harmless), check:links/privacy (0 issues after dynamic `motion` import), route parity (31/31 vs parity.json), SEO surfaces match CSV. Browser QA is not yet run.
* Verify scripts live in scratchpad: `check-seo.mjs`, `parse-seo.mjs` under `/tmp/claude-*/.../scratchpad/` (re-creatable; compare dist HTML to seo-surfaces.csv).
* NOT committed to git yet. In this workspace, `sites/factionos-public-website/` is ignored via `.git/info/exclude`, so ordinary `git status` currently shows only tracked changes such as `pnpm-lock.yaml`. Inspect the site directory directly when resuming.
* Nothing deployed. Production/DNS untouched.


---

# 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/implementation-plan-2026-07-05.md?ask=<question>&goal=<endgoal>
```

`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.