> 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-session05-features-and-how-it-works-pages/spec.md).

# Session Specification

**Session ID**: `phase14-session05-features-and-how-it-works-pages` **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 `/features` and `/how-it-works` routes for the static FactionOS public website. The pages turn the homepage and product overview story into concrete capability groups, a reviewable technical pipeline, setup example panels, and clear trust-boundary handoffs.

The features page should help visitors compare the cockpit, mission, replay, approval, file/tool timeline, orchestration, adapter, and export capabilities without drifting into vague marketing claims. The how-it-works page should explain the path from Claude Code hooks, Codex CLI hooks, and compatible event producers into the local runtime, WebSocket stream, cockpit, optional outbound adapters, and optional War Room.

The work remains inside the static Astro website boundary. It must not add runtime analytics, hosted forms, auth, a CMS, server rendering, real command execution from the website, inbound adapter commands, remote execution, or hosted product claims. Setup commands are examples only and deeper setup detail belongs in the public docs.

***

## 2. Objectives

1. Create `/features` with grouped, workflow-specific feature copy and route metadata.
2. Create `/how-it-works` with an accurate, accessible pipeline diagram and example setup command panels.
3. Add typed feature and pipeline data that keeps adapter, War Room, demo, docs, and trust-boundary copy centralized and reviewable.
4. Validate the two static routes with package typecheck, build output review, responsive/accessibility 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 media guardrails exist.
* [x] `phase14-session01-hero-cockpit-and-primary-ctas` - homepage hero and primary demo/docs CTA patterns exist.
* [x] `phase14-session02-battlefield-preview-and-product-mockups` - battlefield and product-like visual proof patterns exist.
* [x] `phase14-session03-homepage-narrative-sections` - local-first homepage narrative and trust-boundary copy patterns exist.
* [x] `phase14-session04-product-overview-page` - product surface map, product internal links, and optional capability guardrails 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`, and product marketing component patterns.
* Website copy guardrails for local-first behavior, optional War Room, outbound-only adapters, static demo separation, and setup docs handoff.

### 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 `/features` and compare cockpit navigation, live roster, mission feed, battlefield map, mission detail, replay, approvals, file/tool timelines, prompt lifecycle visibility, diagnostics, settings, orchestration deck, subagent lineage, outbound adapters, export, and audit trail.
* Visitors can open `/how-it-works` and follow the technical flow from hooks and compatible event producers into JSON payloads, local `/event` ingest, `apps/server`, WebSocket stream, `apps/web` cockpit, optional adapters, and optional War Room.
* Visitors can read example setup command panels that are explicitly marked as examples and link to public docs for full setup detail.
* Visitors can reach demo, docs, product, and security routes from both pages.
* Maintainers can update feature groups, pipeline steps, setup commands, and page metadata from typed package-local data.

### Out of Scope (Deferred)

* Exhaustive API reference - *Reason: public docs own full setup and API details.*
* Real command execution or interactive terminal input from the website - *Reason: static website boundary and no hosted execution model.*
* Inbound adapter command support - *Reason: inbound commands remain deferred until a permission and audit model exists.*
* Real file, git, terminal, Docker, remote, or hosted executors - *Reason: executor behavior remains intentionally unimplemented without a separate threat model.*
* Security/privacy deep dive page - *Reason: Phase 15 owns `/security`, legal, FAQ, and trust/conversion pages.*
* Analytics, hosted forms, auth, CMS, runtime personalization, server adapter, hosted identity, hosted storage, public replay hosting, or trusted erasure claims - *Reason: outside first-release static website boundaries and active no-claim guardrails.*

***

## 5. Technical Approach

### Architecture

Create a package-local typed data module at `public-website/src/data/features.ts` that holds page metadata, feature groups, matrix rows, pipeline steps, setup command groups, trust-boundary copy, and CTA links. The two new routes compose this data through focused Astro marketing components and existing layout primitives.

The feature page should use a feature matrix for quick scanning plus grouped feature bands for workflow context. The how-it-works page should use a responsive ordered pipeline diagram and static terminal-style panels for setup examples. Components should render accessible text summaries so color, diagram geometry, or command styling are not the only information channel.

### Design Patterns

* Typed data module: Keeps feature inventory, pipeline order, command examples, and guardrail copy centralized.
* Section components: Keeps route files small while preserving scoped CSS and package-local ownership.
* Accessible static diagrams: Uses ordered lists, labels, summaries, and keyboard-reachable links instead of canvas-only or color-only diagrams.
* Example-only command panels: Presents setup commands as static examples with docs handoff and no execution affordance.
* Boundary callouts: Places outbound-only, optional, local-first, and no-claim language near the relevant feature or pipeline 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/features.ts`                           | Typed feature groups, page metadata, pipeline steps, setup command panels, trust boundary copy, and CTAs | \~280      |
| `public-website/src/components/marketing/FeatureMatrix.astro`   | Scan-friendly feature inventory with workflow-specific labels and route handoffs                         | \~230      |
| `public-website/src/components/marketing/FeatureBand.astro`     | Grouped feature sections with capability lists, boundaries, and docs/security links                      | \~230      |
| `public-website/src/components/marketing/PipelineDiagram.astro` | Accessible responsive ordered pipeline from hooks to cockpit and optional outputs                        | \~260      |
| `public-website/src/components/marketing/TerminalWindow.astro`  | Static terminal-style example command panels with example-only labels                                    | \~180      |
| `public-website/src/pages/features.astro`                       | Features route with metadata, shell, matrix, feature bands, and CTAs                                     | \~110      |
| `public-website/src/pages/how-it-works.astro`                   | How-it-works route with metadata, shell, pipeline diagram, command panels, and CTAs                      | \~130      |

### Files to Modify

| File                                    | Changes                                                                              | Est. Lines |
| --------------------------------------- | ------------------------------------------------------------------------------------ | ---------- |
| `public-website/src/data/site.ts`       | Add or adjust route constants only if implementation finds a missing canonical path  | \~5        |
| `public-website/src/data/navigation.ts` | Adjust navigation only if route labels or descriptions need source-backed correction | \~5        |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `/features` renders with title, description, canonical metadata, and the complete required feature inventory.
* [ ] `/how-it-works` renders with title, description, canonical metadata, pipeline diagram, and setup example panels.
* [ ] Feature copy is tied to product workflows and avoids vague productivity, hosted-service, or security certification claims.
* [ ] Pipeline copy includes Claude Code hooks, Codex CLI hooks, compatible producers, JSON payloads, local `/event`, `apps/server`, WebSocket stream, `apps/web`, optional adapters, and optional War Room.
* [ ] Adapter copy remains outbound-only and does not imply inbound commands.
* [ ] Setup commands are visibly marked as examples and link to public docs for full setup details.
* [ ] Both pages link to demo, docs, product, and security context.

### Testing Requirements

* [ ] `npm --workspace @factionos/public-website run typecheck` passes.
* [ ] `npm --workspace @factionos/public-website run build` passes.
* [ ] Built `/features` and `/how-it-works` output includes expected metadata, route links, external docs/demo links, and example-only command labels.
* [ ] Manual responsive smoke checks cover desktop, tablet, and mobile widths for the matrix, bands, pipeline, and terminal panels.

### Non-Functional Requirements

* [ ] Static website boundary is preserved: no analytics, 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, and demo are visually and textually distinct from local source-of-truth product behavior.
* [ ] Pipeline and feature visuals expose text equivalents and do not depend on color alone.
* [ ] 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

* Reuse `siteExternalDestinations`, `sitePaths`, `siteStructuredData`, and product internal link patterns rather than duplicating URL constants.
* Keep `/features` focused on capability groups and `/how-it-works` focused on flow. Avoid turning either route into full docs or legal/security pages.
* Mark setup command panels as examples and avoid copy buttons unless the implementation also handles accessible names and clear non-execution copy.
* Include outbound adapters as outbound notification behavior only: Discord, Telegram, and generic HTTPS webhooks do not become inbound command channels.
* Use static CSS diagrams or DOM structures. Do not add canvas, runtime data fetching, animation dependency, or third-party diagram packages.

### Potential Challenges

* Feature list scope creep: The required inventory is broad. Mitigation: group features by workflow and keep each item specific to a product job.
* Overclaim risk in architecture copy: Pipeline diagrams can imply hosted transfer or production validation. Mitigation: label local runtime, optional external transfer, and no-claim surfaces directly in the diagram.
* Terminal affordance ambiguity: A styled terminal can look executable. Mitigation: visibly mark panels as examples, use static code blocks, and link to public docs for full setup instructions.
* Responsive diagram density: Pipeline steps can become cramped on mobile. Mitigation: render as an ordered list that stacks cleanly and keeps labels readable without overlapping.

### Relevant Considerations

* \[P13-public-website] **Public site page depth is still upcoming**: This session completes the Phase 14 page-depth work for features and how-it-works without treating the website as launch-complete.
* \[P13-public-website] **Static Astro boundary is intentional**: The routes must stay Astro static output with no server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics by default.
* \[P13-public-website] **Public website external links are explicit**: Demo and docs may be linked, but analytics, hosted forms, third-party fonts, CMS adapters, auth, or runtime personalization require separate review.
* \[P03] **Real executors remain unimplemented by design**: Setup and pipeline copy must not imply file, git, terminal, Docker, remote, or hosted execution.
* \[P07] **Redaction is boundary-specific**: Pipeline and adapter copy should keep prompts, file contents, command bodies, terminal output, transcripts, tokens, broad paths, exports, replay buffers, scans, diagnostics, and logs out of external-transfer claims.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Feature or pipeline copy accidentally implies hosted identity, hosted storage, inbound adapter commands, real executors, analytics, production hosted validation, or trusted erasure.
* Diagram, matrix, terminal panels, or CTA links lose text equivalents, accessible labels, visible focus, or mobile-safe wrapping.
* Setup command panels look interactive or executable instead of static examples.

***

## 9. Testing Strategy

### Unit Tests

* No new unit tests are expected for static Astro composition unless helper logic becomes complex.
* Use TypeScript typecheck as the primary contract test for typed feature and pipeline data.

### Integration Tests

* Run `npm --workspace @factionos/public-website run typecheck`.
* Run `npm --workspace @factionos/public-website run build`.
* Inspect built `/features` and `/how-it-works` HTML for canonical metadata, expected route links, external demo/docs links, and example-only labels.

### Manual Testing

* Open `/features` and `/how-it-works` in the Astro dev server or built preview.
* Check desktop, tablet, and 360px mobile widths for overlap, wrapping, readable cards, readable pipeline steps, and reachable links.
* Check keyboard focus movement through page links and CTA controls.
* Check reduced-motion preference if any decorative motion is added.

### Edge Cases

* Long feature labels and badge text wrap inside cards without resizing the layout.
* Pipeline steps remain understandable when stacked on mobile.
* External links preserve `target="_blank"` with `rel="noopener noreferrer"` through shared link components.
* Setup commands stay static examples and do not expose click handlers or form controls that imply execution.

***

## 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-session01-hero-cockpit-and-primary-ctas`, `phase14-session02-battlefield-preview-and-product-mockups`, `phase14-session03-homepage-narrative-sections`, `phase14-session04-product-overview-page`
* **Depended by**: Phase 15 trust/content/conversion pages and Phase 16 quality, deployment, and launch handoff.

***

## 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-session05-features-and-how-it-works-pages/spec.md?ask=<question>&goal=<endgoal>
```

`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.