> 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-session05-roadmap-faq-and-legal-pages/spec.md). # Session Specification **Session ID**: `phase15-session05-roadmap-faq-and-legal-pages` **Phase**: 15 - Trust, Content, And Conversion Pages **Status**: Not Started **Created**: 2026-06-02 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session builds the roadmap, FAQ, and legal/policy routes for the static FactionOS public website. Phase 13 created the Astro site foundation, Phase 14 shipped the core product story, and Phase 15 has already added use-case, security, publishing, company, contact, and press pages. This work fills the last planned trust and conversion routes before the final cross-linking and copy consistency pass. The session matters because visitors need clear answers about direction, product fit, setup, privacy, integrations, teams, and policy boundaries before launch hardening. The content must stay conservative: roadmap items cannot read like delivery commitments, FAQ answers cannot imply unsupported hosted services, and legal/policy pages must not look final unless owner/legal review text is provided. Implementation stays inside `public-website` as static Astro output. The plan uses typed package-local data modules, existing layout and SEO primitives, `LegalLayout.astro` for policy pages, accessible static components, and explicit review markers. It does not add analytics, trackers, hosted forms, policy acceptance workflows, cookies, client-side storage, server adapters, runtime personalization, dynamic FAQ search, CMS behavior, or new production dependencies. *** ## 2. Objectives 1. Create `/roadmap` with current focus, near-term themes, later themes, recently shipped links, and an explicit change/no-date guardrail. 2. Create `/faq` with categorized product, setup, privacy/security, demo/docs, integrations, teams, and hosted-options answers. 3. Create `/legal`, `/legal/privacy`, `/legal/terms`, and `/legal/acceptable-use` with clear pre-review markers unless owner-approved final text is available. 4. Wire metadata, route constants, internal links, review labels, and validation checks so the routes are discoverable without adding unsupported claims. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session02-design-tokens-and-layout-shell` - shared shell, section, system, and navigation primitives exist. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - metadata, canonical URL, sitemap, robots, and JSON-LD helpers exist. * [x] `phase14-session04-product-overview-page` - product route and local-first positioning exist for FAQ and roadmap links. * [x] `phase14-session05-features-and-how-it-works-pages` - feature and setup explanation targets exist. * [x] `phase15-session01-use-cases-hub-and-role-pages` - role-specific routes exist for teams and product-fit FAQ links. * [x] `phase15-session02-security-and-privacy-vault` - privacy, hosted-service, analytics, erasure, and identity claim boundaries are reviewed. * [x] `phase15-session03-blog-and-news-editorial-polish` - news routes exist for recently shipped roadmap links. * [x] `phase15-session04-company-and-contact-pages` - contact destinations and static no-form contact boundaries exist. ### Required Tools/Knowledge * Astro 6 static routes and scoped component styles. * Existing `BaseLayout`, `Shell`, `Section`, `ButtonLink`, `Badge`, `Panel`, `LegalLayout`, `Seo`, and JSON-LD primitives. * Existing package-local site, navigation, security, company, content, and metadata data patterns. * Current no-claim boundaries from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`. ### 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. * Legal/policy pages remain marked as draft or pre-review if owner-approved legal copy is not supplied during implementation. *** ## 4. Scope ### In Scope (MVP) * Visitors can open `/roadmap` and review current focus, near-term themes, later themes, recently shipped items, and a visible no-exact-date roadmap guardrail. * Visitors can open `/faq` and browse categorized questions for product, setup, privacy/security, demo/docs, integrations, teams, and hosted options. * Visitors can open `/legal` and see a policy index with review status, policy scope, and links to each policy page. * Visitors can open `/legal/privacy`, `/legal/terms`, and `/legal/acceptable-use` and see policy copy or clear pre-review placeholders that cannot be mistaken for final legal approval. * Maintainers can update roadmap groups, FAQ entries, policy review labels, and route metadata from typed package-local data or route-local props. * Roadmap and FAQ routes include canonical metadata, social metadata, internal links, and accessible static presentation. * Legal pages use the existing legal layout review boundary and do not claim analytics, hosted forms, account handling, policy acceptance, or personal data collection that the static site does not implement. * All routes remain static Astro output with no runtime data collection, client-side form submission, analytics, tracker, cookie, localStorage, WebSocket, EventSource, dynamic search, or server adapter behavior. ### Out of Scope (Deferred) * Binding roadmap items to exact dates - *Reason: Session 05 requires direction without delivery commitments unless owner-approved dates are supplied.* * Formal legal review completion - *Reason: owner/legal-approved text is outside this implementation session unless the owner provides it.* * Dynamic FAQ search - *Reason: the MVP is categorized static answers; search would add interaction and test scope without being required.* * Hosted policy acceptance, cookie consent, account terms acceptance, or privacy center workflows - *Reason: the website has no hosted account, analytics, cookie, form, or persistence path in this phase.* * New analytics, trackers, CRM embeds, CMS behavior, auth, server-rendered website routes, runtime personalization, external fonts, or external service loads - *Reason: the public website remains static and privacy-preserving by default.* * Hosted identity, production-hosted validation, formal certification, trusted unified erasure, broad media readiness, real executors, remote execution, or inbound adapter control - *Reason: these remain open, no-claim, or deferred outside this public website scope.* *** ## 5. Technical Approach ### Architecture Add typed roadmap and FAQ data modules under `public-website/src/data/` to own metadata, categories, labels, supporting links, review boundaries, and copy-guardrail text. Extend `site.ts` only for stable route constants and URLs that are reused by navigation, pages, structured data, and future Phase 15 work. Create `RoadmapTimeline.astro` for grouped roadmap sections and `FaqList.astro` for categorized FAQ rendering. Both components should use semantic headings, lists, links, and accessible labels; route-level CSS can handle layout while long copy stays in data modules for review. The FAQ route may emit `FAQPage` JSON-LD from the typed FAQ data, but answers must remain conservative and match rendered content. Create legal routes with the existing `LegalLayout.astro` so review markers, draft labels, `noindex` defaults, and static-site boundary copy stay consistent. Policy pages should make it obvious when text is a pre-review placeholder and should avoid unsupported data-collection, hosted-service, account, analytics, cookie, or acceptance-workflow claims. ### Design Patterns * Typed marketing data: Centralize roadmap and FAQ copy for reviewability and exhaustive type checks. * Static Astro composition: Build pages from existing layout and system primitives with no client scripts or runtime fetches. * Explicit review markers: Mark legal/policy copy as pre-review unless final owner/legal approval is provided. * No-commitment roadmap language: Use status/theme labels instead of dates, quarters, SLA-style promises, or delivery guarantees. * Categorized static FAQ: Use native headings/lists or accessible disclosure controls without dynamic search. * Conservative metadata: Keep SEO/social metadata useful while avoiding claims stronger than the page body supports. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3. * `@astrojs/sitemap` and existing metadata/structured-data helpers. * Scoped Astro component styles plus `public-website/src/styles/global.css` tokens. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/roadmap.ts` | Typed roadmap metadata, current/near/later/shipped groups, supporting links, and guardrails | \~220 | | `public-website/src/data/faq.ts` | Typed FAQ metadata, categories, entries, links, JSON-LD source data, and boundary copy | \~260 | | `public-website/src/components/marketing/RoadmapTimeline.astro` | Accessible grouped roadmap timeline with no-date guardrail and shipped/news links | \~210 | | `public-website/src/components/marketing/FaqList.astro` | Categorized FAQ list or disclosure component with accessible controls and static answers | \~220 | | `public-website/src/pages/roadmap.astro` | Static roadmap route with metadata, timeline, shipped links, and CTAs | \~220 | | `public-website/src/pages/faq.astro` | Static FAQ route with categories, structured data, related links, and no dynamic search | \~220 | | `public-website/src/pages/legal/index.astro` | Static legal hub with policy list, review statuses, and links to policy pages | \~180 | | `public-website/src/pages/legal/privacy.astro` | Privacy policy route or clear pre-review placeholder using LegalLayout | \~180 | | `public-website/src/pages/legal/terms.astro` | Terms route or clear pre-review placeholder using LegalLayout | \~170 | | `public-website/src/pages/legal/acceptable-use.astro` | Acceptable-use route or clear pre-review placeholder using LegalLayout | \~170 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/site.ts` | Add roadmap, FAQ, and legal subpage route constants/URLs plus reusable link targets as needed | \~80 | | `public-website/src/data/navigation.ts` | Align footer link hrefs/descriptions with route constants and legal hub/subpages | \~45 | | `public-website/src/components/navigation/Footer.astro` | Adjust footer presentation only if new legal/resource link data requires it | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/roadmap`, `/faq`, `/legal`, `/legal/privacy`, `/legal/terms`, and `/legal/acceptable-use` render as static Astro routes. * [ ] `/roadmap` includes current focus, near-term themes, later themes, recently shipped links to `/news`, and a visible note that roadmap items may change. * [ ] `/roadmap` contains no exact delivery dates, quarters, SLA promises, or guaranteed sequencing unless owner-approved text is supplied. * [ ] `/faq` covers product, setup, privacy/security, demo/docs, integrations, teams, and hosted options. * [ ] `/faq` includes accessible categorized navigation or disclosure behavior and does not add dynamic search. * [ ] `/legal` lists policy routes with review status and clear policy scope. * [ ] `/legal/privacy`, `/legal/terms`, and `/legal/acceptable-use` are owner-reviewed or clearly marked as pre-review placeholders. * [ ] Legal pages introduce no unsupported data-collection, hosted form, analytics, account, cookie, policy-acceptance, hosted-service, or erasure claims. * [ ] Footer/navigation and page-body links make roadmap, FAQ, and legal routes discoverable without breaking existing product, company, demo, docs, blog, or news links. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Built HTML for all six routes includes expected metadata, canonical paths, route content, legal review markers, internal links, and no-date or pre-review boundary copy. * [ ] Manual desktop, tablet, 360px mobile, keyboard focus, long text wrapping, FAQ disclosure/category navigation, legal review marker, footer navigation, and external demo/docs/mailto link smoke checks are completed. * [ ] Copy scan confirms no hosted identity, trusted erasure, production-hosted validation, formal certification, broad media readiness, analytics capture, hosted form, CRM, exact roadmap delivery, customer, traction, revenue, market-size, or fundraising claims are introduced. ### Non-Functional Requirements * [ ] The public website remains static Astro output with no server adapter. * [ ] No new production dependencies are added. * [ ] No client-side data collection, cookies, localStorage writes, trackers, analytics, hosted forms, WebSockets, EventSource, or runtime fetches are introduced. * [ ] All files are ASCII-encoded with Unix LF line endings. * [ ] Code follows project conventions and the existing public website data, component, and route composition patterns. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Legal review boundaries remain visible. * [ ] Roadmap copy avoids exact delivery promises. *** ## 8. Implementation Notes ### Key Considerations * Session 06 depends on these routes existing before the final cross-linking and copy consistency pass can audit the full first-release site. * Legal pages should prefer obvious pre-review language over polished final-sounding policy copy if no approved text is available. * FAQ answers should reuse the security page's conservative posture and keep optional hosted services, War Room collaboration, analytics, docs, and demo surfaces separated. * Roadmap shipped links should point to existing `/news` content or index routes rather than inventing unsupported release announcements. ### Potential Challenges * Legal content may look final without review: Use `LegalLayout`, review badges, draft labels, and explicit pre-review copy on every policy route. * Roadmap language may imply delivery commitments: Use themes, focus areas, and shipped history instead of dates, quarters, or guaranteed sequences. * FAQ answers may drift into hosted-service claims: Tie hosted answers to optional/disabled-default boundaries and link to security/docs where useful. * Static pages may become visually dense: Use existing section, panel, badge, and responsive wrapping patterns with long text smoke checks. ### Relevant Considerations * \[P13-public-website] **Static Astro boundary is intentional**: Keep the public website static; do not add server adapters, React, Tailwind, CMS, auth, hosted forms, or analytics. * \[P13-public-website] **Public website external links are explicit**: The site may link to demo and GitBook docs, but analytics, hosted forms, CMS adapters, auth, or runtime personalization require separate review. * \[P14-public-website] **Typed marketing data modules**: Keep route copy, metadata, CTA targets, and boundary language in data files where useful for review. * \[P06-S07-HOSTED-IDENTITY] **Hosted identity remains no-claim**: Do not imply War Room room authority is hosted account identity, SSO, organization membership, public collaboration safety, or production auditability. * \[P06-S07-ERASURE] **Trusted unified erasure remains no-claim**: Do not imply the website or legal placeholder pages prove broad deletion across hosted, logs, archives, backups, or future surfaces. * \[P06-S07-HOSTED-VALIDATION] **Production-hosted validation remains no-claim**: Avoid copy that implies deployed app-shell, demo, Worker, or website production validation beyond evidence already recorded. * \[P07] **Hosted services ship as disabled-default guardrails only**: Hosted storage, analytics, public replay, push, tunnels, and remote access remain disabled or unclaimed unless separate scoped work ships them. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Legal/policy routes sounding launch-approved without owner/legal review. * Roadmap route implying exact delivery dates or guaranteed sequencing. * FAQ copy implying hosted identity, analytics capture, production validation, trusted erasure, or inbound/executor capabilities that are not shipped. *** ## 9. Testing Strategy ### Unit Tests * Rely on TypeScript type checking for roadmap and FAQ data shapes, link keys, metadata props, and structured-data generation. * Add focused tests only if implementation introduces helper functions with nontrivial branching. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Inspect generated HTML in `public-website/dist/roadmap/index.html`, `public-website/dist/faq/index.html`, and `public-website/dist/legal/` for metadata, content, review markers, and links. ### Manual Testing * Open the built pages or dev server routes for `/roadmap`, `/faq`, `/legal`, `/legal/privacy`, `/legal/terms`, and `/legal/acceptable-use`. * Check desktop, tablet, and 360px mobile widths for wrapping, non-overlap, heading scale, footer reachability, and CTA/link accessibility. * Keyboard through FAQ controls if disclosures are used, policy links, roadmap links, demo/docs CTAs, and footer navigation. ### Edge Cases * No approved legal text is available: render pre-review placeholders with review labels instead of final-sounding policies. * No exact roadmap dates are available: render theme/status labels only. * Recently shipped entries cannot map to exact articles: link to `/news` or safe existing entries without inventing releases. * Long legal and FAQ answers wrap on narrow screens without overlapping buttons or adjacent content. * External demo/docs links remain clearly external and separate from this static website. *** ## 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`, `phase14-session04-product-overview-page`, `phase14-session05-features-and-how-it-works-pages`, `phase15-session01-use-cases-hub-and-role-pages`, `phase15-session02-security-and-privacy-vault`, `phase15-session03-blog-and-news-editorial-polish`, `phase15-session04-company-and-contact-pages` * **Depended by**: `phase15-session06-cross-linking-and-copy-consistency-pass`, Phase 16 quality, deployment, and launch handoff sessions *** ## 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-session05-roadmap-faq-and-legal-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.