> 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/public-website/docs/archive-docs_public-website/readme_docs_public-website.md).

# Public Website Documentation

This directory is the standalone documentation set for `public-website/`. It is written so the public website can be maintained without relying on `.spec_system` records.

## Current Status

`public-website/` is the static Astro site for `https://faction-os.com/`. It is a commercial and product website, not the runtime cockpit, not the synthetic demo, and not the public GitBook documentation site.

Current launch posture:

* Static Astro output from `public-website/dist`.
* Package name: `@factionos/public-website`.
* Node baseline: `26.2.0` or newer.
* Current package version: `0.0.28`.
* Build stack: Astro 6, MDX, sitemap, RSS, Sharp, TypeScript.
* Shipped static build evidence: 31 pages, 26 optimized images, RSS, sitemap, robots, manifest, and canonical/social metadata.
* Local launch gates passed on 2026-06-02.
* Cloudflare Pages workflow is configured.
* Live deploy and production HTTPS smoke remain no-claim until run from an authorized Cloudflare environment.
* Legal and privacy policy pages are visibly pre-review until owner/legal approval is recorded.

External destinations:

* Main website: `https://faction-os.com/`
* Synthetic demo: `https://demo.faction-os.com/`
* Public docs: `https://faction-os.gitbook.io/faction-os-docs`

## Start Here

| Need                                            | Document                                                                                                                                      |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| System shape, source of truth, dependencies     | [Architecture](/faction-os-docs/public-website/docs/archive-docs_public-website/architecture.md)                                              |
| Local commands and editing workflow             | [Development](/faction-os-docs/public-website/docs/archive-docs_public-website/development.md)                                                |
| Routes, navigation, page ownership              | [Routes And IA](/faction-os-docs/public-website/docs/archive-docs_public-website/routes-and-information-architecture.md)                      |
| UX, visual system, motion, accessibility intent | [Website UX](/faction-os-docs/public-website/docs/archive-docs_public-website/website_ux.md)                                                  |
| Blog/news authoring and frontmatter             | [Content Authoring](/faction-os-docs/public-website/docs/archive-docs_public-website/content-authoring.md)                                    |
| Metadata, RSS, sitemap, structured data         | [SEO And Metadata](/faction-os-docs/public-website/docs/archive-docs_public-website/seo-and-metadata.md)                                      |
| Asset provenance and media rules                | [Media Assets](/faction-os-docs/public-website/docs/archive-docs_public-website/media-assets.md)                                              |
| Static privacy and claim boundaries             | [Security And Privacy](/faction-os-docs/public-website/docs/archive-docs_public-website/security-privacy-and-claim-boundaries.md)             |
| Responsive, accessibility, performance gates    | [Accessibility And Performance](/faction-os-docs/public-website/docs/archive-docs_public-website/accessibility-responsive-and-performance.md) |
| Cloudflare Pages deploy path                    | [Deployment](/faction-os-docs/public-website/docs/archive-docs_public-website/deployment.md)                                                  |
| Launch evidence and no-claim status             | [Launch Readiness](/faction-os-docs/public-website/docs/archive-docs_public-website/launch-readiness.md)                                      |
| Deferred work                                   | [Post-Launch Backlog](/faction-os-docs/public-website/docs/archive-docs_public-website/post-launch-backlog.md)                                |
| Validation commands and manual QA               | [Validation](/faction-os-docs/public-website/docs/archive-docs_public-website/validation.md)                                                  |
| Documentation coverage and deletion readiness   | [Documentation Audit](/faction-os-docs/public-website/docs/archive-docs_public-website/documentation-audit.md)                                |
| Completed phase/session history                 | [Build Site Plan](/faction-os-docs/public-website/docs/archive-docs_public-website/build-site-plan.md)                                        |

## Source Of Truth

Use the code below as the authoritative source before changing docs:

* `../package.json`: package scripts, version, dependencies, Node engine.
* `../astro.config.mjs`: static Astro site configuration.
* `../src/data/site.ts`: site identity, routes, external destinations, contact targets, copy guardrails, metadata defaults, structured data.
* `../src/data/navigation.ts`: primary, footer, mobile, and external nav.
* `../src/data/*.ts`: page-specific content data.
* `../src/content.config.ts`: blog/news collection schemas.
* `../src/lib/content.ts`: publishing helpers, draft filtering, RSS mapping.
* `../src/lib/media.ts`: media registry, provenance, release status, image performance defaults.
* `../src/components/media/OptimizedMedia.astro`: optimized image rendering and reduced-motion fallback behavior.
* `../../scripts/check-public-website-links.mjs`: deterministic built-site checker and static privacy validator.
* `../../.github/workflows/public-website-deploy.yml`: Cloudflare Pages deploy workflow.

## Documentation Policy

* Do not add a dependency on `.spec_system` from these docs.
* Document shipped behavior separately from planned or no-claim behavior.
* Keep legal/privacy pages marked pre-review until approval exists.
* Keep production-hosted validation no-claim until an authorized Pages deploy and HTTPS smoke pass.
* Keep the site static unless a later scoped decision adds server rendering, forms, analytics, CMS, auth, hosted identity, or hosted storage.
* When adding public routes or approved external destinations, update `../src/data/site.ts`, the route docs, and the built-site checker together.


---

# 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/public-website/docs/archive-docs_public-website/readme_docs_public-website.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.