> 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/sessions/phase14-session01-hero-cockpit-and-primary-ctas/spec.md). # Session Specification **Session ID**: `phase14-session01-hero-cockpit-and-primary-ctas` **Phase**: 14 - Homepage And Core Product Story **Status**: Completed **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session replaces the Phase 13 homepage foundation placeholder with the first production homepage viewport for FactionOS. It creates a strong FactionOS brand signal, a simulated local terminal cockpit, concise local-first product positioning, and visible demo and docs actions without introducing runtime data collection. The work matters because Phase 14 depends on the homepage becoming a concrete commercial product story rather than an infrastructure proof. Later battlefield preview and narrative sessions will build beneath or beside this hero, so this session establishes the copy, layout, responsive behavior, and static-data guardrails for the rest of the homepage. The implementation stays inside `public-website`, reusing the Phase 13 Astro shell, Cyber-Tactical tokens, SEO plumbing, typed site data, and package-local media registry. All status values shown in the hero are synthetic and must be visibly framed as local-demo posture, not hosted telemetry or live visitor data. *** ## 2. Objectives 1. Create a homepage hero that clearly identifies FactionOS as mission control for AI coding agents. 2. Add a simulated terminal cockpit and live status panel using static data and local-first no-claim copy. 3. Wire primary demo and secondary docs CTAs from the existing site data with accessible names and focus-safe layout. 4. Preserve desktop and mobile first-viewport readability with reduced-motion handling and no text overlap. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session01-astro-scaffold-and-workspace-wiring` - Provides the static Astro workspace and package scripts. * [x] `phase13-session02-design-tokens-and-layout-shell` - Provides global CSS, shared shell, navigation, section primitives, and focus states. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - Provides site data, metadata defaults, external demo/docs destinations, and static SEO plumbing. * [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - Provides the package-local brand media registry and optimized-image pattern. ### Required Tools/Knowledge * Astro component authoring with scoped CSS. * Existing `public-website` system components: `Section`, `ButtonLink`, `Badge`, `MetricStrip`, `Panel`, and `OptimizedMedia`. * Repo validation commands: `npm --workspace @factionos/public-website run typecheck` and `npm --workspace @factionos/public-website run build`. ### Environment Requirements * Node.js 26.2.0 or newer. * npm 11.16.0 workspace install available. * No analytics, hosted form, CMS, auth, server adapter, or runtime personalization dependency added for this session. *** ## 4. Scope ### In Scope (MVP) * Website visitor can identify FactionOS immediately as mission control for AI coding agents - Implement a branded `HeroCockpit.astro` first viewport. * Website visitor can launch the synthetic demo or public docs without scrolling * Use existing external destinations from `site.ts`. * Website visitor can see product-specific local runtime hints - Build `LiveStatusPanel.astro` with simulated local server, active agents, events, and mission state values. * Website visitor can understand the privacy boundary - Include concise copy that the homepage uses static, simulated values and no runtime collection. * Keyboard and mobile users can operate the hero CTAs - Preserve accessible labels, visible focus, clean wrapping, and stable layout down to 360px. * Reduced-motion users can read equivalent static state - Disable continuous decorative motion while keeping labels, borders, and state badges visible. ### Out of Scope (Deferred) * Full battlefield visualization - Reason: Phase 14 Session 02 owns the product-like battlefield and cockpit preview. * Completing all homepage sections - Reason: Phase 14 Session 03 owns narrative decks, loop preview, latest content, and final CTA. * Real runtime calls, WebSocket data, analytics, forms, or session storage - Reason: The first-release website remains static with no hosted collection. * Product overview, features, and how-it-works pages - Reason: Phase 14 Sessions 04 and 05 own those routes. *** ## 5. Technical Approach ### Architecture Create a `public-website/src/components/marketing/` component group for homepage marketing surfaces. `HeroCockpit.astro` composes hero copy, brand treatment, terminal prompt rows, privacy badges, and CTA links. It delegates the synthetic operational readouts to `LiveStatusPanel.astro` so later homepage sections can reuse or extend the status pattern without bloating the route. The homepage route imports the new components and keeps page-specific metadata inside `index.astro`. Shared global classes remain available, but hero-specific grid, terminal, and responsive behavior should live in component-scoped CSS unless a reusable primitive is clearly needed. ### Design Patterns * Static data by default: Prevents accidental hosted telemetry or live-data claims on the public website. * Component composition: Keeps the homepage route readable and gives later sessions a stable marketing component directory. * Registry-backed media: Uses existing package-local brand media so alt text, provenance, dimensions, and optimized output stay centralized. * Progressive responsive layout: Desktop first viewport uses cockpit-style composition; mobile stacks CTAs and readouts without hiding critical actions. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3 for package-local type validation. * Scoped Astro CSS plus `public-website/src/styles/global.css` tokens. * Astro optimized images through the existing media registry where brand art is used. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/components/marketing/HeroCockpit.astro` | Homepage first-viewport cockpit with brand, copy, terminal hints, CTAs, and responsive layout. | \~220 | | `public-website/src/components/marketing/LiveStatusPanel.astro` | Static operational status panel with simulated local runtime values and no-live-data copy. | \~170 | | `public-website/src/data/homepage.ts` | Typed homepage hero copy, terminal lines, status readouts, badges, and trust notes. | \~120 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | --------------------------------------------------------------------------------- | ---------- | | `public-website/src/pages/index.astro` | Replace Phase 13 placeholder hero with the new production hero and page metadata. | \~45 | | `public-website/src/styles/global.css` | Add only reusable homepage helpers if component-scoped CSS is insufficient. | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Homepage first viewport clearly identifies FactionOS and the mission control product concept. * [ ] Demo and docs CTAs are visible without scrolling on desktop and mobile target widths. * [ ] Hero uses tactical/cockpit visual language instead of generic split text/media or card-only SaaS composition. * [ ] Status values are clearly simulated and do not imply hosted telemetry, analytics capture, or live visitor data. * [ ] Hero text, terminal rows, badges, and CTAs do not overlap at 360px, 768px, 1280px, or wide desktop viewports. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Manual responsive smoke completed for 360px, 768px, 1280px, and wide desktop viewport behavior. * [ ] Reduced-motion behavior checked for continuous hero effects. ### Non-Functional Requirements * [ ] Static output remains free of analytics, hosted forms, CMS adapters, auth, server rendering, and runtime personalization. * [ ] External demo/docs links retain `noopener noreferrer`, accessible names, and visible focus states. * [ ] Brand media usage stays registry-backed or text-first with no conditional showcase media promoted by implication. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Use `siteExternalDestinations.demo` and `siteExternalDestinations.docs` rather than hardcoding CTA URLs in components. * Use static/synthetic status data only; do not fetch from local runtime, external APIs, analytics, browser storage, or session storage. * Preserve the first-viewport requirement: brand, product concept, and demo/docs actions must be visible on mobile and desktop. * Keep scoped component CSS preferred. Add to `global.css` only for reusable helpers that should outlive the hero. ### Potential Challenges * Dense cockpit composition can overflow on mobile: Use constrained grids, `minmax(0, 1fr)`, wrapping text, full-width mobile CTAs, and stable terminal row sizing. * Status readouts could imply live hosted data: Label values as simulated local posture and include explicit no-analytics/no-hosted-collection copy. * Brand imagery could overpromote conditional media: Prefer launch-ready brand assets from `websiteMediaByKey` and avoid showcase assets in this session. ### Relevant Considerations * \[P13-public-website] **Public site page depth is still upcoming**: This session advances homepage depth while leaving later homepage sections, trust, conversion, hardening, deployment, and launch evidence to their planned sessions. * \[P13-public-website] **Static Astro boundary is intentional**: The hero must stay in static Astro with no server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics. * \[P13-public-website] **Registry-backed media is the website pattern**: Brand media should come through `public-website/src/lib/media.ts` and `OptimizedMedia.astro` when image output is needed. * \[P13-public-website] **Do not promote conditional media by implication**: Showcase assets remain conditional; this session should not present them as release-ready product screenshots. * \[P06-S07-HOSTED-VALIDATION] **Production-hosted validation remains no-claim**: Homepage copy must avoid production-hosted validation claims. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * External CTAs become inaccessible, lose focus visibility, or wrap poorly on mobile. * Simulated live readouts are mistaken for analytics, hosted telemetry, or real user/session data. * Decorative motion or terminal layout creates overlap, clipping, or unreadable content at narrow and wide viewport extremes. *** ## 9. Testing Strategy ### Unit Tests * No dedicated unit tests are required for static Astro components in this session unless implementation introduces exported TypeScript helpers with branching logic. ### Integration Tests * Run the package typecheck to validate Astro component imports and typed data. * Run the package build to verify static output, optimized images, metadata, and route rendering. ### Manual Testing * Start or build-preview the public website and inspect the homepage at 360px, 768px, 1280px, and wide desktop widths. * Keyboard-tab through the first viewport and confirm demo/docs CTAs have visible focus and accessible text. * Check reduced-motion mode and confirm continuous decorative movement is disabled while state labels remain readable. ### Edge Cases * Long CTA labels and terminal rows wrap inside their containers without horizontal scrolling. * Brand image fails or is not available; text-first FactionOS title still identifies the product. * External links remain functional and do not replace the current tab without explicit external-link semantics. * No status value uses browser storage, network state, or visitor-specific data. *** ## 10. Dependencies ### External Libraries * Astro: 6.4.2 * `@astrojs/sitemap`: 3.7.3 * `@astrojs/rss`: 4.0.18 * `@astrojs/mdx`: 6.0.1 * sharp: 0.34.5 * TypeScript: 5.9.3 ### Other Sessions * **Depends on**: `phase13-session01-astro-scaffold-and-workspace-wiring`, `phase13-session02-design-tokens-and-layout-shell`, `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase13-session05-asset-pipeline-and-brand-media-prep` * **Depended by**: `phase14-session02-battlefield-preview-and-product-mockups`, `phase14-session03-homepage-narrative-sections` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase14-session01-hero-cockpit-and-primary-ctas/spec.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.