> 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-session06-cross-linking-and-copy-consistency-pass/spec.md). # Session Specification **Session ID**: `phase15-session06-cross-linking-and-copy-consistency-pass` **Phase**: 15 - Trust, Content, And Conversion Pages **Status**: Complete **Created**: 2026-06-02 **Completed**: 2026-06-02 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session performs the final Phase 15 consistency pass across the static FactionOS public website. Sessions 01-05 created the use-case, security, publishing, company, contact, press, roadmap, FAQ, and legal routes. The next step is to make the full first-release site feel intentional as one product surface: every planned route should be discoverable, every CTA should use the same demo/docs destinations, and every recurring proof point should stay source-backed and conservative. The work matters because Phase 16 will focus on hardening, performance, deployment, and launch handoff. Phase 16 should not inherit mismatched header labels, stale footer IA, hidden launch routes, route-label drift, dead static links, or copy that accidentally converts open no-claims into product claims. This session closes the content and navigation gap before quality gates begin. Implementation stays within `public-website` and the root script surface used to validate it. It should update existing Astro data modules, shared navigation components, page/body links, content collection links, and package validation scripts. It must not add analytics, hosted forms, CMS behavior, auth, runtime personalization, server adapters, third-party embeds, or unsupported hosted service claims. *** ## 2. Objectives 1. Align header navigation, mobile navigation, footer navigation, route labels, metadata labels, and page-body cross-links with the first-release website IA. 2. Normalize demo/docs CTAs and approved external destinations across home, product, features, how-it-works, security, use cases, blog, news, company, contact, press, roadmap, FAQ, and legal pages. 3. Preserve required product proof points while removing or softening copy that implies hosted collaboration is required, inbound adapter control exists, real user data powers demo content, prompts/paths upload by default, or unverifiable performance, revenue, adoption, security, certification, hosted identity, trusted erasure, or production-hosted validation claims. 4. Add deterministic static-site checks for route coverage, internal links, approved external links, legal review markers, metadata labels, and guarded copy so future edits can catch drift before launch hardening. *** ## 3. Prerequisites ### Required Sessions * [x] `phase15-session01-use-cases-hub-and-role-pages` - role routes and use-case data exist. * [x] `phase15-session02-security-and-privacy-vault` - local-first security, privacy, analytics, hosted-service, erasure, and identity boundary copy exists. * [x] `phase15-session03-blog-and-news-editorial-polish` - blog/news routes and launch content exist. * [x] `phase15-session04-company-and-contact-pages` - investors, about, contact, and press routes exist. * [x] `phase15-session05-roadmap-faq-and-legal-pages` - roadmap, FAQ, legal hub, privacy, terms, and acceptable-use routes exist. ### Required Tools/Knowledge * Astro 6 static routes and scoped component styles. * Existing `BaseLayout`, `Shell`, navigation, SEO, content collection, and marketing data patterns. * Existing `public-website/src/data/site.ts` route constants, external destination definitions, and metadata defaults. * Current no-claim boundaries from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`. * Package validation path: `npm --workspace @factionos/public-website run typecheck` and `npm --workspace @factionos/public-website run build`. ### Environment Requirements * Node.js 26.2.0 or newer. * npm workspace commands available from the repository root. * Built Astro output available under `public-website/dist` for static link and metadata inspection. * No network dependency is required for validation. External demo/docs URLs should be checked as approved destinations, not fetched. *** ## 4. Scope ### In Scope (MVP) * Visitors can discover Product, Use Cases, Features, How It Works, Security, Blog, and News from the header or mobile primary navigation. * Visitors can discover Investors, About, Contact, Press, Roadmap, FAQ, and Legal from the footer, with legal subpages reachable from the legal hub or footer. * Every planned Phase 15 route is reachable from the header, footer, page body, or a sensible index route. * Demo CTAs consistently target the separate synthetic demo destination. * Docs CTAs consistently target the public GitBook documentation destination. * Internal links use existing `sitePaths`, typed route-link maps, or verified static paths instead of ad hoc stale strings where practical. * Recurring proof points are preserved: local-first by default, no hosted account required for core workflow, Claude Code and Codex CLI support, generic event API for compatible producers, web cockpit surfaces, optional War Room collaboration, optional outbound Discord/Telegram/generic HTTPS adapters, and synthetic zero-install demo separation. * Copy guardrails are enforced across data modules, Astro pages, and content markdown: no hosted-collaboration-required claim, no inbound external adapter control claim, no real-user-data demo implication, no default prompt/path upload claim drift, and no unverifiable performance, revenue, adoption, market-size, fundraising, security, certification, trusted-erasure, hosted identity, or production-hosted validation claim. * Legal review markers remain visible where required. * A deterministic static-site validation script catches route, link, external destination, metadata, legal marker, and guarded-copy drift. ### Out of Scope (Deferred) * Deep accessibility audit - *Reason: Phase 16 owns responsive and accessibility hardening.* * Full performance optimization - *Reason: Phase 16 owns performance and image optimization.* * Deployment configuration - *Reason: Phase 16 owns Cloudflare Pages deployment path and launch handoff.* * Large copy rewrites unrelated to consistency - *Reason: this session aligns already-created pages rather than changing the product narrative.* * Live external link fetching - *Reason: validation should be deterministic and no-network; production-hosted validation remains no-claim until separately proven.* * New analytics, trackers, hosted forms, CRM embeds, CMS behavior, auth, cookies, localStorage, runtime personalization, server-rendered website routes, or third-party scripts - *Reason: the public website remains static and privacy-preserving by default.* *** ## 5. Technical Approach ### Architecture Start from the existing typed data modules because most Phase 14 and Phase 15 routes source copy, metadata, CTA keys, and route links from TypeScript. Add or extend shared site-level constants only when they prevent repeated string drift across pages. Keep route-specific copy in route-specific modules when the copy is only used by that surface. Update navigation in `public-website/src/data/navigation.ts` and adjust `Header.astro`, `MobileNavigation.astro`, or `Footer.astro` only where the expanded IA needs stable layout, wrapping, focus, or external-link treatment. Header navigation must include the required first-release primary routes without relying on tiny brand text or a footer-only path. Add a root Node validation script that reads the built static output and source data files deterministically. The script should check that expected routes exist, internal hrefs resolve to built pages or known assets, external hrefs are restricted to approved demo/docs/mailto destinations, legal review markers remain present, and banned or risky claim patterns are absent. The script should emit explicit failure messages and exit nonzero on drift. ### Design Patterns * Typed marketing data: Keep reviewable copy in package-local data modules. * Shared route constants: Prefer `sitePaths`, `siteUrls`, and typed link maps over duplicated string hrefs. * Static build inspection: Validate generated HTML links and metadata rather than guessing from source strings alone. * No-network link policy: Treat external URLs as approved destinations without making live requests. * Conservative claim language: Prefer "optional", "separate", "synthetic", "local", "static", "no-claim", and "pre-review" labels where they describe actual product boundaries. * Accessible navigation controls: Keep expanded header, mobile navigation, and footer links reachable with keyboard, visible focus, labels, and stable wrapping. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3. * Node.js 26.2.0 or newer for validation scripts. * npm workspaces. * Existing Biome, Astro typecheck, and package build commands. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/check-public-website-links.mjs` | Deterministic built-site route, link, metadata, legal marker, external destination, and copy guardrail checker | \~260 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- | | `public-website/package.json` | Add a package-local validation script for the static link/copy checker | \~5 | | `public-website/src/data/site.ts` | Add or align shared proof-point, CTA, approved destination, and guardrail constants where useful | \~80 | | `public-website/src/data/navigation.ts` | Align header and footer IA with required first-release routes and labels | \~90 | | `public-website/src/components/navigation/Header.astro` | Support expanded primary navigation with stable wrapping, labels, and focus behavior if needed | \~80 | | `public-website/src/components/navigation/MobileNavigation.astro` | Keep expanded primary/utility links reachable and accessible on small viewports if needed | \~80 | | `public-website/src/components/navigation/Footer.astro` | Keep company, trust, resource, legal, demo, and docs footer links clear and stable | \~60 | | `public-website/src/data/homepage.ts` | Align homepage proof points, CTA labels, synthetic-demo wording, and no-claim copy | \~60 | | `public-website/src/data/product.ts` | Align product proof points, surface labels, CTAs, and optional boundary copy | \~60 | | `public-website/src/data/features.ts` | Align features and how-it-works proof points, pipeline labels, CTAs, and optional output copy | \~80 | | `public-website/src/data/security.ts` | Align trust boundary, analytics, hosted identity, erasure, demo/docs, and legal links | \~60 | | `public-website/src/data/use-cases.ts` | Align role-specific CTAs, proof examples, demo/docs labels, and local-first boundaries | \~80 | | `public-website/src/data/company.ts` | Align investors, about, contact, and press CTAs, external labels, and no-metrics copy | \~70 | | `public-website/src/data/roadmap.ts` | Align roadmap labels, shipped links, no-date wording, and CTAs | \~45 | | `public-website/src/data/faq.ts` | Align FAQ route links, hosted-options answers, legal links, and demo/docs language | \~70 | | `public-website/src/content/blog/*.md` | Clean stale cross-links, demo/docs labels, and guarded product claims in blog content | \~80 | | `public-website/src/content/news/*.md` | Clean stale cross-links, release/news labels, and guarded product claims in news content | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Header or mobile primary navigation exposes Product, Use Cases, Features, How It Works, Security, Blog, and News. * [ ] Footer navigation exposes Investors, About, Contact, Press, Roadmap, FAQ, Legal, demo, and docs with route labels matching the site IA. * [ ] Every planned first-release route resolves in built static output and is reachable from header, footer, page body, or a sensible index route. * [ ] Demo and docs CTAs use the approved external destinations consistently. * [ ] Blog and news content use valid internal links or approved external destinations. * [ ] Legal pages retain visible pre-review or owner/legal review markers. * [ ] Metadata titles, canonical paths, social descriptions, and visible route labels do not conflict with the page IA. * [ ] Copy guardrails are enforced across source data, pages, and built output. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Static route/link/copy checker passes against `public-website/dist`. * [ ] Manual desktop and 360px mobile smoke confirms expanded navigation, footer density, CTAs, long labels, legal markers, blog/news links, and external labels remain reachable without overlap. ### Non-Functional Requirements * [ ] Public website remains static Astro output with no server adapter. * [ ] No new production dependencies are added. * [ ] No client-side data collection, analytics, trackers, cookies, localStorage writes, hosted forms, WebSockets, EventSource, runtime fetches, CRM embeds, auth, or CMS behavior is introduced. * [ ] Static checker emits deterministic, actionable failures without network access. * [ ] All files are ASCII-encoded with Unix LF line endings. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Legal review boundaries remain visible. * [ ] Static website no-claim boundaries remain conservative. *** ## 8. Implementation Notes ### Key Considerations * Session 06 should not invent new product promises. It should reconcile the pages already created in Phase 14 and Phase 15. * Header expansion may require careful responsive treatment because Blog and News must join the primary IA without making navigation overlap or wrap poorly. * External destinations should stay explicit and separate: the synthetic demo and GitBook docs are public destinations, not this static website. * The validation script should inspect generated HTML after build so it catches routing and metadata issues that source-only scans can miss. ### Potential Challenges * Expanded primary navigation may become cramped: Use stable wrapping, condensed spacing, or responsive menu behavior while preserving accessible names and visible focus. * Claim scanning can produce false positives: Keep the checker focused on risky phrases and require explicit allowlist context only where the source is intentionally discussing a no-claim. * Content markdown may contain route strings outside typed data modules: Build output link inspection should catch stale rendered hrefs even when source strings are spread across Markdown files. * Legal pages may look final after polish: Preserve pre-review labels and review boundary copy in both rendered pages and validation expectations. ### 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. * \[P14-public-website] **Static proof panels need explicit labels**: Synthetic cockpit, battlefield, and product proof content must stay labeled as sample or static content. * \[P13-public-website] **Press downloads are policy-only**: Do not add downloadable media without source, rights, attribution, metadata, accessibility, privacy, and size evidence. * \[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, legal placeholder pages, or static copy 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. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Expanded navigation hides required routes or creates inaccessible links on small screens. * Static links pass source review but fail after Astro build output. * Copy polish accidentally removes no-claim context or makes synthetic/static examples read like live hosted behavior. *** ## 9. Testing Strategy ### Unit Tests * Prefer deterministic Node script checks for static build output, route coverage, approved external destinations, legal marker presence, metadata labels, and guarded copy. * Add focused helper tests only if the validation script grows nontrivial parsing or normalization helpers that need isolated coverage. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Run the new package-local link/copy checker against `public-website/dist`. * Run focused Biome format/lint checks on changed website and script files if implementation edits JavaScript, TypeScript, Astro, CSS, JSON, or Markdown. ### Manual Testing * Open or preview the built site and check the header, mobile navigation, footer, legal hub, blog/news lists, role pages, demo/docs CTAs, and first-release route links. * Smoke desktop and 360px mobile widths for wrapping, non-overlap, heading scale, visible focus, and footer reachability. * Verify legal pages still show review status and cannot be mistaken for final legal approval. ### Edge Cases * A content markdown link points to a removed route: the built-site checker should fail with the source HTML file and href. * A legal page keeps its route but loses review markers: the checker should fail with the route and missing marker. * A primary route exists but is footer-only: route inventory should flag discoverability drift for required header routes. * A risky claim appears inside no-claim explanatory copy: the checker should allow only explicit no-claim context or require implementation to reword the copy. * A `mailto:` link includes malformed or unexpected contact targets: the checker should report it without attempting to send or fetch anything. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: `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`, `phase15-session05-roadmap-faq-and-legal-pages` * **Depended by**: 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-session06-cross-linking-and-copy-consistency-pass/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.