> 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-session04-product-overview-page/spec.md). # Session Specification **Session ID**: `phase14-session04-product-overview-page` **Phase**: 14 - Homepage And Core Product Story **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session builds the `/product` route for the static FactionOS public website. The page must give technical visitors a complete, accurate map of the product surface: the web cockpit, hook ingest, CLI, protocol, optional War Room, outbound adapters, and static demo. The work extends the Phase 13 Astro foundation and the Phase 14 homepage story. The homepage now introduces the product; this session turns that first impression into a concrete product overview that routes visitors toward the demo, public docs, `/features`, `/how-it-works`, and `/security`. The page remains static output. It must not add forms, analytics, auth, hosted storage, server rendering, runtime personalization, or active hosted-service claims. Optional capabilities need clear boundary language, especially War Room collaboration and outbound adapters. *** ## 2. Objectives 1. Create `/product` as a complete static overview of the shipped and optional FactionOS surfaces. 2. Add typed product data and reusable Astro components for product promise, surface cards, proof panels, local-first operating model, and CTAs. 3. Keep product copy concrete, source-backed, and conservative about optional hosted, adapter, and collaboration boundaries. 4. Validate the route with package typecheck, static build, metadata checks, responsive smoke coverage, and ASCII/LF scans. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session02-design-tokens-and-layout-shell` - shared shell, navigation, tokens, and layout primitives exist. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - metadata, canonical URL, sitemap, RSS, robots, and structured data helpers exist. * [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - registry-backed website media and `OptimizedMedia.astro` exist. * [x] `phase14-session02-battlefield-preview-and-product-mockups` - product-like static mockup language and battlefield proof panels exist. * [x] `phase14-session03-homepage-narrative-sections` - homepage narrative, local-first boundary copy, and final CTA patterns exist. ### Required Tools/Knowledge * Astro 6 static output and scoped component CSS. * TypeScript literal unions and `satisfies` for typed data modules. * Existing `BaseLayout`, `Shell`, `Section`, `Panel`, `Badge`, `ButtonLink`, `MetricStrip`, and `OptimizedMedia` components. * Website copy guardrails for local-first behavior, optional War Room, outbound-only adapters, and static demo separation. ### Environment Requirements * Node.js 26.2.0 or newer. * npm workspace commands available from the repository root. * No new production dependencies unless a separate review justifies them. *** ## 4. Scope ### In Scope (MVP) * Visitors can open `/product` and understand the complete FactionOS product surface through a static Astro page. * Visitors can compare Web cockpit, hook ingest, CLI, protocol, optional War Room, outbound adapters, and static demo as concrete product surfaces. * Visitors can see the local-first operating model with clear boundaries for prompts, local paths, terminal output, replay data, credentials, and user-provided code. * Visitors can reach demo/docs CTAs and related internal routes from the product page. * Maintainers can keep product-page copy in typed data instead of scattering source-of-truth strings across components. ### Out of Scope (Deferred) * Full feature matrix - *Reason: owned by Session 05 `/features`.* * Deep setup or architecture guide - *Reason: owned by Session 05 `/how-it-works` and public docs.* * Full security/privacy page - *Reason: owned by Phase 15 trust work.* * Investor, press, contact, roadmap, FAQ, or legal pages - *Reason: owned by later Phase 15 sessions.* * Hosted accounts, hosted storage, analytics capture, form handling, CMS, runtime personalization, server rendering, or public replay hosting - *Reason: outside static website boundary and active no-claim guardrails.* *** ## 5. Technical Approach ### Architecture Create a static `/product` Astro route that composes package-local data and section components under the existing site shell. Product copy lives in `public-website/src/data/product.ts` as typed arrays and objects. Components consume that data and render accessible, responsive sections with scoped CSS. The page should avoid duplicating the full homepage or synthetic demo. It should reuse shared primitives, external destination data, metadata helpers, and registry-backed media when visuals are needed. Conditional showcase media must be labelled through provenance-aware UI and must not imply broad media readiness. ### Design Patterns * Typed data module: Keeps product surface copy reviewable and prevents enum drift in components. * Section components: Keeps product page structure readable while preserving scoped CSS and package-local ownership. * Static proof panels: Shows the product concept without runtime calls, analytics, or hosted state. * Boundary badges: Makes optional, local-first, synthetic, outbound-only, and no-claim states visible at the point of copy. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3. * Scoped Astro component styles plus `public-website/src/styles/global.css` tokens. * Existing npm workspace scripts for typecheck and build. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/product.ts` | Typed product-page copy, surface data, proof panels, operating model, and CTA definitions | \~220 | | `public-website/src/components/marketing/ProductHero.astro` | Product promise, local-first posture badges, and primary demo/docs actions | \~170 | | `public-website/src/components/marketing/ProductSurfaceGrid.astro` | Cards for seven product surfaces with status, role, and route links | \~230 | | `public-website/src/components/marketing/ProductProofPanels.astro` | Product mockup/proof panels with static sample and provenance boundaries | \~220 | | `public-website/src/components/marketing/ProductOperatingModel.astro` | Local-first operating model and no-upload/default boundary explanation | \~200 | | `public-website/src/components/marketing/ProductOverviewCta.astro` | Final product-page CTA with demo/docs and internal route links | \~170 | | `public-website/src/pages/product.astro` | Product overview route with metadata, shell, and composed sections | \~80 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------- | ------------------------------------------------------------------------- | ---------- | | `public-website/src/data/site.ts` | Add typed product path and URL constants if needed for canonical metadata | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/product` renders a complete overview of all required product surfaces. * [ ] Product surface copy distinguishes shipped local surfaces, optional War Room, outbound notification adapters, and the separate static demo. * [ ] Product page links to `/features`, `/how-it-works`, `/security`, the external demo, and the external docs. * [ ] Product visuals use static, product-like panels or registry-backed media without live runtime calls. * [ ] Demo/docs CTAs are accessible and visible in both the hero and final CTA sections. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Built `/product` output includes expected metadata and canonical URL. * [ ] Manual responsive smoke checks cover desktop, tablet, and mobile widths. ### Non-Functional Requirements * [ ] Static website boundary is preserved: no analytics, forms, auth, CMS, server adapter, hosted persistence, or runtime personalization. * [ ] Copy does not imply prompts, local paths, terminal output, credentials, replay data, exports, or user-provided code leave the machine by default. * [ ] Conditional showcase media is labelled or avoided so broad media readiness is not implied. * [ ] Text wraps without overlapping controls at common mobile widths. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] No new production dependency is added. *** ## 8. Implementation Notes ### Key Considerations * Use `siteExternalDestinations` for demo/docs actions so external labels and `rel` behavior remain centralized. * Prefer internal links to `/features`, `/how-it-works`, and `/security` over duplicating deep content. * Keep copy tactical and product-specific. Avoid vague productivity claims and unverifiable adoption, revenue, performance, or security claims. * If using showcase images, route through `OptimizedMedia.astro` and surface provenance or conditional status in nearby copy. ### Potential Challenges * State-source mismatch: Session 03 has validation artifacts and PRD closure evidence, while the analyzer state does not list it as completed. Mitigation: plan Session 04 because Session 03 artifacts are complete, and avoid overwriting completed Session 03 specs. * Overclaim risk for optional surfaces: War Room, hosted services, public replay, and adapters can read like active hosted control. Mitigation: label War Room as optional/redacted, adapters as outbound notifications only, and hosted services as no-claim unless separately proven. * Product page scope creep: `/product` can easily become `/features` or `/how-it-works`. Mitigation: keep surface descriptions compact and link deeper routes. ### Relevant Considerations * \[P13-public-website] **Public site page depth is still upcoming**: This session advances the Phase 14 page-depth work by adding the product overview without treating it as launch completion. * \[P13-public-website] **Static Astro boundary is intentional**: The page must stay Astro static output with no server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics by default. * \[P13-public-website] **Registry-backed media is the website pattern**: Any optimized product image should use `public-website/src/lib/media.ts` and `OptimizedMedia.astro`. * \[P13-public-website] **Public website external links are explicit**: Demo and docs may be linked, but no third-party analytics, hosted forms, or runtime personalization should be introduced. * \[P13-public-website] **Do not promote conditional media by implication**: Conditional showcase images require visible provenance posture or should be avoided in favor of static CSS mockups. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Product copy accidentally implies hosted account, hosted storage, inbound adapter commands, or production-hosted validation. * External and internal CTAs lose accessible names, focus behavior, or mobile-safe wrapping. * Static proof panels look like live telemetry or real user data instead of deterministic product examples. *** ## 9. Testing Strategy ### Unit Tests * No new unit tests are expected for this static Astro page unless helper logic becomes complex. Typed data and component contracts are covered through the package typecheck. ### Integration Tests * Run the package typecheck and static build. * Inspect built output for `/product`, canonical metadata, and expected route links. ### Manual Testing * Open `/product` in the Astro dev server or built preview. * Check desktop, tablet, and 360px mobile widths for overlap, wrapping, readable CTAs, and reachable internal/external links. * Check keyboard focus movement through hero actions, surface links, and final CTA links. ### Edge Cases * Long surface labels and status text wrap inside badges/cards. * Conditional media fallback remains visible under reduced-motion preference. * External links preserve `target="_blank"` with `rel="noopener noreferrer"`. * Optional/no-claim copy remains visible near War Room, adapters, and demo descriptions. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: `phase13-session02-design-tokens-and-layout-shell`, `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase13-session05-asset-pipeline-and-brand-media-prep`, `phase14-session02-battlefield-preview-and-product-mockups`, `phase14-session03-homepage-narrative-sections` * **Depended by**: `phase14-session05-features-and-how-it-works-pages`, Phase 15 trust/content/conversion pages, and Phase 16 launch hardening. *** ## 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-session04-product-overview-page/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.