> 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-session03-homepage-narrative-sections/spec.md). # Session Specification **Session ID**: `phase14-session03-homepage-narrative-sections` **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 completes the remaining homepage narrative below the hero and battlefield preview. It adds the explanatory sections that make the product story concrete: the observability, gamification, and local-first value pillars; the hook-to-cockpit loop; the security boundary; latest blog and news previews; and a final tactical call to action that routes visitors to the external demo and public docs. The work is next because Phase 14 Sessions 01 and 02 already established the first viewport, primary CTAs, homepage metadata, static-data posture, and product-like battlefield preview. Session 03 turns that visual proof into a complete homepage story without duplicating the full product, security, or how-it-works pages owned by later sessions. The implementation stays inside `public-website` and preserves the Phase 13 static Astro boundary. The homepage must remain concrete and product-specific while making clear that the public website does not collect visitor analytics, read local prompts, inspect paths, host runtime state, submit forms, or query a live FactionOS installation. *** ## 2. Objectives 1. Add homepage value pillars for observability, gamification, and local-first operation with typed product-specific copy. 2. Add a hook-to-cockpit loop preview that explains local hook events, local server ingest, WebSocket cockpit updates, and optional adapter notifications. 3. Add a precise security boundary section that states local-first defaults and avoids hosted account, upload, analytics, form, or runtime collection claims. 4. Render latest blog and news previews from content collections using non-draft entries, deterministic ordering, and empty-state handling. 5. Add a final homepage CTA panel with accessible demo and docs links while preserving responsive text wrapping and static-site validation. *** ## 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 layout, design tokens, shell primitives, sections, panels, buttons, and focus styles. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - Provides metadata, canonical, sitemap, RSS, and JSON-LD plumbing. * [x] `phase13-session04-content-collections-and-publishing-templates` - Provides typed blog/news collections, draft filtering, and publishing helpers. * [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - Provides package-local media rules and registry-backed image patterns. * [x] `phase14-session01-hero-cockpit-and-primary-ctas` - Provides homepage hero, primary demo/docs CTAs, and static-data posture. * [x] `phase14-session02-battlefield-preview-and-product-mockups` - Provides the homepage battlefield preview and synthetic product visualization. ### Required Tools/Knowledge * Astro component authoring with scoped CSS and package-relative imports. * Existing `public-website` primitives: `Section`, `Panel`, `Badge`, `ButtonLink`, `PostCard`, `Shell`, and homepage data patterns. * Astro content collection APIs and the local `getVisibleSortedEntries` helper. * Static-site privacy and no-overclaim rules from the PRD, UX PRD, CONSIDERATIONS, and SECURITY-COMPLIANCE. * Responsive layout, stable grid sizing, visible focus states, and reduced-motion-safe decorative effects. ### Environment Requirements * Node.js 26.2.0 or newer. * npm 11.16.0 workspace install available. * No React, Tailwind, CMS adapter, server adapter, auth, hosted form handling, analytics, visitor storage, runtime personalization, iframe, WebSocket call, or live telemetry connection added for this session. *** ## 4. Scope ### In Scope (MVP) * Website visitor can understand the three core product values - Build an observability, gamification, and local-first pillar deck with concrete FactionOS capabilities and no generic marketing filler. * Website visitor can understand the hook-to-cockpit loop - Show how local hook events enter the local server, update the cockpit stream, and optionally notify external systems through adapters. * Website visitor can see the local-first privacy boundary - State that the website and default product posture require no hosted account, no prompt upload, no path upload, no credential upload, and no visitor analytics. * Website visitor can reach current publishing surfaces - Render latest blog and latest news/changelog previews from non-draft content collections with deterministic ordering and empty states. * Website visitor can take final action - Add a final tactical CTA panel that links to `https://demo.faction-os.com/` and `https://faction-os.gitbook.io/faction-os-docs`. * Desktop and mobile users can scan every section - Maintain responsive wrapping, stable grids, readable headings, focusable links, and no overlap. * Website maintainers can validate static output - Keep the page compatible with package-local typecheck and build commands. ### Out of Scope (Deferred) * Full `/security` page - Reason: Phase 15 owns trust and privacy pages. * Full `/how-it-works` architecture page - Reason: Phase 14 Session 05 owns the complete how-it-works route. * Full product overview page - Reason: Phase 14 Session 04 owns product route depth. * Blog/news editorial polish beyond homepage previews - Reason: Phase 15 owns publishing polish. * Forms, analytics, hosted account flows, CMS integrations, and runtime data collection - Reason: first-release public website boundaries explicitly exclude these capabilities. * Real local session data, WebSocket calls, app iframe embedding, or live demo embedding - Reason: the public website remains static and separate from the demo and app surfaces. *** ## 5. Technical Approach ### Architecture Extend `public-website/src/data/homepage.ts` with typed homepage narrative data: pillar cards, loop steps, security boundary statements, and final CTA copy. Keep content deterministic and authored in the package so component rendering does not depend on client state, visitor storage, runtime APIs, or hosted services. Create focused Astro marketing components under `public-website/src/components/marketing/`: `ThreePillarDeck.astro`, `HookToCockpitLoop.astro`, `SecurityBoundary.astro`, `LatestContentPreview.astro`, and `FinalHomepageCta.astro`. These components should compose existing primitives where useful and keep section-specific CSS scoped locally. The homepage route imports the new components below `BattlefieldPreview`, queries the latest visible blog/news entries with Astro content collections, and passes bounded entry arrays into the latest-content preview. The implementation should preserve the existing homepage metadata path and avoid new global CSS unless a reusable helper is clearly needed. The latest content preview should use existing content helpers so draft filtering, slug generation, date ordering, and collection labels stay aligned with the blog and news index pages. ### Design Patterns * Static typed narrative data: Keeps homepage copy reviewable, typed, and free of runtime or hosted-data claims. * Component composition: Reuses `Section`, `Panel`, `Badge`, `ButtonLink`, and `PostCard` before adding new primitives. * Deterministic publishing query: Uses `getVisibleSortedEntries` and explicit limits so homepage previews remain stable and drafts stay excluded from production output. * Privacy-boundary copy at point of explanation: Places no-upload and no-analytics language near the loop and security sections where users would naturally ask what leaves their machine. * Progressive responsive layout: Uses stable grids that collapse to readable stacked sections without horizontal overflow or heading overlap. * Reduced-motion equivalence: Decorative timeline or scan effects must disable under reduced motion while labels and sequence information remain visible. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3 for typed data modules and content collection types. * Scoped Astro CSS with existing global design tokens. * Existing npm workspace validation through `typecheck` and `build` scripts. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/components/marketing/ThreePillarDeck.astro` | Homepage value pillars for observability, gamification, and local-first positioning with accessible labels and responsive cards. | \~220 | | `public-website/src/components/marketing/HookToCockpitLoop.astro` | Hook-to-cockpit loop preview showing local ingest, stream updates, and optional adapter notifications. | \~260 | | `public-website/src/components/marketing/SecurityBoundary.astro` | Local-first security boundary callout with precise no-upload, no-hosted-account, and no-analytics copy. | \~220 | | `public-website/src/components/marketing/LatestContentPreview.astro` | Homepage preview for latest visible blog and news entries with deterministic ordering and empty states. | \~220 | | `public-website/src/components/marketing/FinalHomepageCta.astro` | Final tactical CTA panel with external demo and docs links and static-site boundary copy. | \~200 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/homepage.ts` | Add typed pillar, loop, boundary, and final CTA data with concrete local-first copy. | \~220 | | `public-website/src/pages/index.astro` | Query latest blog/news entries, import narrative components, and render them below the battlefield preview. | \~50 | | `public-website/src/styles/global.css` | Add only reusable helpers if component-scoped CSS cannot cover section layout safely. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Homepage includes observability, gamification, and local-first value pillars with concrete product capabilities. * [ ] Homepage includes a hook-to-cockpit loop preview covering local hook events, local server ingest, WebSocket cockpit updates, and optional adapters. * [ ] Homepage includes a security boundary section that states no hosted account, no prompt upload, no file/path upload, no credential upload, and no analytics by default. * [ ] Latest blog and latest news/changelog previews render from non-draft content collections in deterministic newest-first order. * [ ] Latest-content preview renders useful empty states if either collection has no visible entries. * [ ] Final CTA routes to the external demo and public docs with accessible labels and explicit external-link semantics. * [ ] Homepage does not duplicate the full security, product overview, how-it-works, blog, news, or synthetic demo experiences. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Manual browser smoke covers 360px, 768px, 1280px, wide desktop, keyboard focus for links, latest-content presence, empty-state behavior by code inspection or test fixture reasoning, and reduced-motion mode. * [ ] External demo/docs links and internal blog/news links are validated in rendered output. ### Non-Functional Requirements * [ ] Static output remains free of analytics, hosted forms, CMS adapters, auth, server rendering, runtime personalization, visitor storage, WebSocket calls, iframe embeds, and live telemetry calls. * [ ] Copy avoids hosted identity, production-hosted validation, broad erasure, broad media readiness, and real executor overclaims. * [ ] Section headings, cards, buttons, badges, and post previews do not overlap or clip text on supported desktop and mobile widths. * [ ] Any decorative motion is disabled or simplified for reduced-motion users while sequence labels remain visible. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Keep the homepage story concrete: hook tracking, file-touch visibility, prompt lifecycles, tool/event streams, roster building, mission completion, local REST snapshots, and local browser cockpit are the required anchors. * Use the existing external destination data for demo/docs links rather than hard-coding duplicate labels or aria text in multiple components. * Latest blog/news previews should be limited and bounded. They should not become full index-page duplicates. * The final CTA should be an action section, not a landing-page hero. ### Potential Challenges * Homepage becoming too long or repetitive: Use compact sections, clear hierarchy, and defer exhaustive details to future product and how-it-works pages. * Copy overclaiming hosted behavior: Keep hosted accounts, analytics, public replay, production validation, broad erasure, and real executors explicitly absent or deferred. * Latest content query type mismatches: Reuse `getVisibleSortedEntries`, `PublishingEntry`, and existing `PostCard` patterns from blog/news index pages. * Mobile text wrapping regressions: Use minmax grids, `min-width: 0`, overflow wrapping, and manual viewport checks. ### Relevant Considerations * \[P13-public-website] **Public site page depth is still upcoming**: This session advances homepage story only; product, trust, content, and launch pages remain owned by later sessions. * \[P13-public-website] **Public website external links are explicit**: Demo and docs links are allowed, but analytics, hosted forms, third-party fonts, CMS, auth, and personalization remain out of scope. * \[P13-public-website] **Static Astro boundary is intentional**: Keep `public-website` separate from `apps/web`, `public-demo`, and GitBook docs with no server adapter, React, Tailwind, CMS, auth, forms, or analytics. * \[P13-public-website] **Shell primitives before pages**: Reuse the package shell, sections, panels, buttons, badges, and content cards instead of duplicating chrome. * \[P13-public-website] **Content collections fit publishing**: Use typed collection helpers for homepage blog/news previews. * \[P13-public-website] **Do not promote conditional media by implication**: This session should not add or promote new downloadable media or conditional showcase claims. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Latest content previews accidentally include draft entries or reorder content nondeterministically. * Homepage copy implies analytics, hosted identity, prompt upload, file/path upload, public replay, real executors, or production-hosted validation. * Long section headings, CTA labels, badges, and post titles overlap on mobile or wide desktop. *** ## 9. Testing Strategy ### Unit Tests * No new package-level unit test file is required unless implementation adds a reusable pure helper. Type-level coverage comes from TypeScript `satisfies` data contracts and Astro typecheck. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck` to validate Astro component props, content collection types, and imports. * Run `npm --workspace @factionos/public-website run build` to validate static routes, content collection queries, RSS/sitemap integration, and rendered output. ### Manual Testing * Inspect the homepage at 360px, 768px, 1280px, and wide desktop. * Tab through demo/docs links, internal post links, and all latest-content cards to verify visible focus states and useful link text. * Check reduced-motion mode if decorative sequence motion is added. * Verify latest blog/news entries are visible, bounded, and link to their collection routes. * Review copy for no-analytics, no-hosted-account, no-upload, and local-first wording. ### Edge Cases * Blog collection has visible entries but news collection does not. * News collection has visible entries but blog collection does not. * Long post titles, category labels, CTA labels, or external-link labels wrap without clipping or horizontal overflow. * Reduced-motion users still see the hook-to-cockpit sequence order. * External demo/docs links remain explicit and do not appear to be embedded hosted functionality. *** ## 10. Dependencies ### External Libraries * Astro: 6.4.2. * TypeScript: 5.9.3. * `@astrojs/mdx`: 6.0.1 for existing content support. * `@astrojs/rss`: 4.0.18 for existing RSS support. * `@astrojs/sitemap`: 3.7.3 for existing sitemap support. * `sharp`: 0.34.5 for existing image optimization. ### 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-session04-content-collections-and-publishing-templates`, `phase13-session05-asset-pipeline-and-brand-media-prep`, `phase14-session01-hero-cockpit-and-primary-ctas`, `phase14-session02-battlefield-preview-and-product-mockups`. * **Depended by**: `phase14-session04-product-overview-page`, `phase14-session05-features-and-how-it-works-pages`, and later Phase 15 trust, content, and conversion pages. *** ## 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-session03-homepage-narrative-sections/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.