> 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/phase15-session01-use-cases-hub-and-role-pages/spec.md). # Session Specification **Session ID**: `phase15-session01-use-cases-hub-and-role-pages` **Phase**: 15 - Trust, Content, And Conversion Pages **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session builds the `/use-cases` hub and four role-specific use-case pages for the static FactionOS public website. The work turns the completed homepage, product overview, features page, and how-it-works page into role-based paths for engineering teams, AI platform teams, founders, and power users. The hub should route visitors by problem and audience. Each role page should make the relevant pain points concrete, compare the workflow before and after FactionOS, show the product surfaces that matter for that audience, and point to demo/docs CTAs without implying hosted accounts, team management, analytics, runtime personalization, or unsupported execution behavior. The implementation remains inside the `public-website` Astro static output boundary. It should use typed package-local data, existing shell/layout/CTA primitives, scoped Astro styles, and conservative copy that keeps local-first behavior, optional integrations, static demo separation, and no-claim posture visible. *** ## 2. Objectives 1. Create `/use-cases` with role cards, shared pain points, and demo/docs conversion paths. 2. Create four role pages for engineering teams, AI platform teams, founders, and power users with problem, before/after workflow, surfaces, examples, and CTAs. 3. Add typed use-case data and reusable use-case components so copy, routes, surface mapping, and guardrails are centralized. 4. Validate the static routes with package typecheck, build output review, responsive/accessibility smoke checks, and ASCII/LF scans. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session02-design-tokens-and-layout-shell` - shared shell, navigation, layout primitives, tokens, and responsive baseline exist. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - metadata, canonical URL, sitemap, robots, RSS, and structured data helpers exist. * [x] `phase14-session01-hero-cockpit-and-primary-ctas` - homepage hero and demo/docs CTA patterns exist. * [x] `phase14-session03-homepage-narrative-sections` - local-first narrative and trust-boundary copy patterns exist. * [x] `phase14-session04-product-overview-page` - product surface map, internal links, and optional capability guardrails exist. * [x] `phase14-session05-features-and-how-it-works-pages` - feature inventory, hook-to-cockpit flow, and docs/security handoff patterns exist. ### Required Tools/Knowledge * Astro 6 static routes, scoped component CSS, and package-local layouts. * TypeScript literal unions and `satisfies` for typed static data. * Existing `BaseLayout`, `Shell`, `Section`, `Badge`, `ButtonLink`, `Panel`, and marketing component patterns. * Website copy guardrails for local-first defaults, optional War Room, outbound-only adapters, static demo separation, and hosted-service no-claim boundaries. ### 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 `/use-cases` and choose between engineering teams, AI platform teams, founders, and power users. * Visitors can see shared pain points for blind agent work, risky actions without review context, multi-agent coordination, and privacy or credential concerns. * Engineering teams can read a role page focused on shared visibility, review context, mission status, and local privacy boundaries. * AI platform teams can read a role page focused on provider-neutral hooks, protocol boundaries, event visibility, diagnostics, and guardrail-friendly integration. * Founders can read a role page focused on running multiple agents without losing control, demo/docs exploration, and product wedge clarity without unverifiable metrics. * Power users can read a role page focused on local control, replay, prompt lifecycle visibility, approvals, diagnostics, and zero-install demo exploration. * Maintainers can update use-case routes, metadata, pain points, workflow panels, surface mapping, proof examples, and CTAs from a typed data module. * Header or mobile navigation and footer navigation can reach the use-case hub without breaking existing product/features/how-it-works/security links. ### Out of Scope (Deferred) * Persona research beyond the current role model - *Reason: the session is scoped to PRD-provided roles and first-release website copy.* * Metrics, ROI claims, traction claims, or quantified productivity promises - *Reason: the PRD explicitly excludes unverifiable claims.* * Hosted team account features, hosted identity, hosted storage, or team-management UX - *Reason: hosted services remain disabled/default no-claim without a separate scoped implementation.* * Dynamic personalization, analytics, tracking, CMS adapters, auth, forms, or server-rendered routes - *Reason: first-release website remains static Astro output.* * Security/privacy deep dive, legal pages, roadmap, FAQ, contact, press, or investors pages - *Reason: later Phase 15 sessions own those surfaces.* *** ## 5. Technical Approach ### Architecture Create `public-website/src/data/use-cases.ts` as the typed source of truth for use-case metadata, routes, role summaries, shared pain points, before/after workflow rows, relevant surfaces, proof examples, CTA targets, and boundary copy. Route files should compose that data through existing layout primitives and focused marketing components rather than duplicating long role copy across pages. Create `UseCaseGrid.astro` for the hub card grid and a reusable role-page section component for the repeated problem, workflow, surface, proof, and CTA structure. Add five static Astro routes under `src/pages/use-cases/` and route metadata through `BaseLayout`, `Shell`, `siteStructuredData`, and `sitePaths` where appropriate. Navigation should use existing `src/data/navigation.ts` patterns. If route constants are missing, add them to `src/data/site.ts` before using them in navigation, metadata, links, or CTA data. All pages should remain static and should not add runtime fetches, client-side tracking, forms, or new dependencies. ### Design Patterns * Typed data module: Keeps role copy, route slugs, CTA targets, product surfaces, proof examples, and guardrail language centralized and reviewable. * Reusable route sections: Keeps role pages consistent while allowing each audience to have distinct problem statements and workflows. * Accessible card grid: Uses semantic links, descriptive headings, clear focus states, and text labels rather than relying on color or decorative styling. * Boundary callouts: Places local-first, optional integration, static website, no analytics, and no hosted account copy near conversion paths. * Static route composition: Uses Astro pages and scoped CSS with no server adapter, no runtime data fetch, and no client personalization. ### 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/use-cases.ts` | Typed route metadata, role content, shared pain points, workflow rows, surface mapping, examples, and CTAs | \~320 | | `public-website/src/components/marketing/UseCaseGrid.astro` | Accessible use-case hub grid with role cards, pain point summaries, and route links | \~220 | | `public-website/src/components/marketing/UseCaseRolePage.astro` | Reusable role page sections for problem, workflow, surfaces, proof examples, boundaries, and CTAs | \~280 | | `public-website/src/pages/use-cases/index.astro` | Use-case hub route with metadata, hero, grid, shared pain points, and CTAs | \~170 | | `public-website/src/pages/use-cases/engineering-teams.astro` | Engineering teams role page wired to typed use-case data | \~70 | | `public-website/src/pages/use-cases/ai-platform-teams.astro` | AI platform teams role page wired to typed use-case data | \~70 | | `public-website/src/pages/use-cases/founders.astro` | Founders role page wired to typed use-case data | \~70 | | `public-website/src/pages/use-cases/power-users.astro` | Power users role page wired to typed use-case data | \~70 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------- | ------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/site.ts` | Add use-case route constants and canonical URLs for the hub and role pages | \~20 | | `public-website/src/data/navigation.ts` | Add primary/mobile reachability for Use Cases and confirm footer link remains aligned | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/use-cases` renders with title, description, canonical metadata, shared pain points, four role cards, and demo/docs CTAs. * [ ] `/use-cases/engineering-teams` renders with problem statement, before/after workflow, relevant surfaces, proof examples, and CTAs. * [ ] `/use-cases/ai-platform-teams` renders with problem statement, before/after workflow, relevant surfaces, proof examples, and CTAs. * [ ] `/use-cases/founders` renders with problem statement, before/after workflow, relevant surfaces, proof examples, and CTAs. * [ ] `/use-cases/power-users` renders with problem statement, before/after workflow, relevant surfaces, proof examples, and CTAs. * [ ] Role pages do not duplicate homepage copy verbatim and do not imply hosted accounts, team-management features, analytics, or unverifiable metrics. * [ ] Navigation and footer can reach the use-case hub. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Built `/use-cases` and all four role routes include expected metadata, route links, external demo/docs links, and boundary copy. * [ ] Manual responsive smoke checks cover desktop, tablet, and mobile widths for hub cards, workflow panels, surface lists, CTA rows, and navigation. ### Non-Functional Requirements * [ ] Static website boundary is preserved: no analytics, trackers, forms, auth, CMS, server adapter, hosted persistence, runtime personalization, or command execution. * [ ] Copy does not imply prompts, local paths, terminal output, credentials, replay data, exports, transcripts, scans, or user-provided code leave the machine by default. * [ ] Optional War Room, outbound adapters, public demo, and public docs remain visually and textually distinct from local source-of-truth product behavior. * [ ] Use-case cards, workflows, and surface lists expose text equivalents and do not depend on color alone. * [ ] Text wraps without overlapping controls or cards 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 * Reuse `siteExternalDestinations`, `sitePaths`, `siteStructuredData`, `ButtonLink`, `Badge`, `Section`, and existing route metadata conventions. * Add route constants before reusing them in data or navigation to avoid scattering literal paths. * Keep role pages specific to audience jobs. Avoid copying the homepage, product overview, or features page wholesale. * Make demo and docs links explicit external destinations. The demo remains a separate synthetic public demo, not a live hosted workspace. * Keep AI platform copy focused on hooks, protocol boundaries, event visibility, diagnostics, and integration guardrails; do not imply inbound commands or hosted control. * Keep engineering team copy focused on shared review context and local boundaries; do not imply hosted team accounts or organization management. * Keep founder copy concrete and avoid traction, ROI, or productivity metrics. * Keep power user copy focused on local control, replay, prompt lifecycle, approvals, diagnostics, and exploration paths. ### Potential Challenges * Role copy can drift into broad marketing promises. Mitigation: tie each claim to a visible FactionOS surface or documented boundary. * Use-case cards can become dense on mobile. Mitigation: use stable grid tracks, text wrapping, and simple hierarchy with no nested card shells. * Navigation may become crowded on desktop. Mitigation: keep one concise Use Cases primary item and rely on footer/supporting links for deeper routes. * Surface examples can imply live telemetry. Mitigation: label static examples and keep local runtime versus static website separation visible. ### Relevant Considerations * \[P14-public-website] **Public site page depth is still upcoming**: This session starts Phase 15 page depth by adding role-based conversion routes. * \[P13-public-website] **Static Astro boundary is intentional**: The pages must remain static Astro output with no server adapter, analytics, hosted forms, CMS, auth, or runtime personalization. * \[P13-public-website] **Public website external links are explicit**: Demo and docs CTAs may link out, but no third-party tracking or hosted form behavior should be introduced. * \[P14-public-website] **Typed marketing data modules**: Use a typed `use-cases.ts` data module so route copy, metadata, CTA targets, and boundary language stay centralized. * \[P14-public-website] **Do not let sample panels read like live systems**: Any proof examples or static panels must identify the static/demo boundary. * \[P06-S07-HOSTED-IDENTITY] **Hosted identity remains no-claim**: Role pages must not imply hosted accounts, organization membership, SSO, or production auditability. * \[P06-S07-ERASURE] **Trusted unified erasure remains no-claim**: Use-case copy must not claim full trusted deletion across all local, hosted, backup, log, archive, or future surfaces. * \[P06-S07-HOSTED-VALIDATION] **Production-hosted validation remains no-claim**: Public website copy must not imply deployed app-shell validation beyond proven static website and demo/docs destinations. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Role cards or CTA links without clear accessible names, focus states, or external destination treatment. * Dense responsive grids causing card text, CTA rows, or navigation labels to overlap on mobile. * Static proof examples, team-oriented copy, or platform-team language implying live hosted telemetry, hosted accounts, inbound command control, or production-hosted validation. *** ## 9. Testing Strategy ### Unit Tests * Use TypeScript typecheck to validate the `use-cases.ts` route keys, role unions, link keys, and component props. * Use Astro build output as static route coverage for all five pages. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Inspect generated HTML for `/use-cases`, all four role routes, canonical metadata, primary/secondary CTA links, and no-claim boundary copy. ### Manual Testing * Smoke the hub and role pages at desktop, tablet, and 360px mobile widths. * Verify keyboard focus reaches role cards, CTA links, header links, footer links, and external demo/docs links in a sensible order. * Check that long role titles, workflow rows, and surface labels wrap without overlap. ### Edge Cases * Missing or mistyped role key should fail typecheck rather than producing a broken route. * External links must include external destination affordance through existing `ButtonLink` or navigation patterns. * Static examples must not look like live telemetry or imply the public website is connected to a local workspace. * Role-specific copy must avoid hosted account, team-management, analytics, ROI, certification, trusted erasure, or production-hosted validation claims. *** ## 10. Dependencies ### External Libraries * Astro: 6.4.2 * TypeScript: 5.9.3 * `@astrojs/mdx`: 6.0.1 * `@astrojs/rss`: 4.0.18 * `@astrojs/sitemap`: 3.7.3 * `sharp`: 0.34.5 ### Other Sessions * **Depends on**: `phase13-session02-design-tokens-and-layout-shell`, `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase14-session01-hero-cockpit-and-primary-ctas`, `phase14-session03-homepage-narrative-sections`, `phase14-session04-product-overview-page`, `phase14-session05-features-and-how-it-works-pages` * **Depended by**: `phase15-session02-security-and-privacy-vault`, `phase15-session06-cross-linking-and-copy-consistency-pass` *** ## 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/phase15-session01-use-cases-hub-and-role-pages/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.