> 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/phase13-session01-astro-scaffold-and-workspace-wiring/spec.md).

# Session Specification

**Session ID**: `phase13-session01-astro-scaffold-and-workspace-wiring` **Phase**: 13 - Public Website Foundation **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript

***

## 1. Session Overview

This session creates the static Astro workspace for the main `faction-os.com` website and wires it into the existing npm workspace. It is the first session of Phase 13, so it establishes the package, build scripts, TypeScript defaults, Astro static output mode, and dependency posture that later design, metadata, content, and asset sessions will depend on.

The current `public-website/` directory already contains planning and UX source files. Implementation must preserve those files before scaffolding from the official Astro blog starter, preferably by generating the starter in a temporary directory and merging the generated project files back into `public-website/`.

This session deliberately avoids final marketing page implementation. The goal is a clean, buildable static website foundation named `@factionos/public-website`, not a finished visual design or content launch.

***

## 2. Objectives

1. Create a buildable Astro static site workspace under `public-website/`.
2. Register `@factionos/public-website` in the root npm workspace without disturbing existing packages.
3. Configure Astro, TypeScript, and package scripts for static output, typechecking, build, preview, and development.
4. Preserve existing `public-website/` planning files and keep deployment independent from the existing public demo.

***

## 3. Prerequisites

### Required Sessions

* None - this is the first session in Phase 13.

### Required Tools/Knowledge

* Node.js `26.2.0+` and npm `11.16.0`, matching the repository baseline.
* npm workspaces and root package script conventions.
* Astro static site scaffolding from the official blog starter.
* Biome formatting and linting coverage from the root workspace.

### Environment Requirements

* The current shell observed during planning reports Node.js `v24.14.0` and npm `10.5.1`, below the repository baseline. Implementation must switch to Node.js `26.2.0+` and npm `11.16.0`, or record the exact blocker before any scaffold claim is made.
* Network access is required if the Astro scaffold or dependency install needs to fetch packages.
* Existing files in `public-website/` must be preserved before starter files are merged.

***

## 4. Scope

### In Scope (MVP)

* Visitors can eventually reach the main static `faction-os.com` website - create the Astro workspace foundation required for later route work.
* Maintainers can run website package scripts through npm workspaces - add package metadata, scripts, and root workspace registration.
* Maintainers can build and typecheck the website package - add Astro config, TypeScript config, and dependency lockfile updates.
* Maintainers can keep the website separate from the public demo - avoid demo deployment coupling, server adapters, analytics, forms, auth, CMS, React, Tailwind, shadcn/ui, and third-party marketing templates.
* Future Phase 13 sessions can rely on starter content collections and static plumbing - scaffold from the official Astro blog starter and retain MDX, sitemap, RSS, Astro-generated types plus TypeScript checking, and sharp image processing posture.

### Out of Scope (Deferred)

* Final Cyber-Tactical design implementation - Reason: Session 02 owns design tokens, shared layout, shell, navigation, footer, and primitives.
* SEO metadata, robots, manifest, and structured data polish - Reason: Session 03 owns static metadata and SEO plumbing.
* Blog/news collection schema and publishing templates - Reason: Session 04 owns typed content collections and seed content.
* Brand/showcase asset promotion and Open Graph fallback media - Reason: Session 05 owns asset provenance, optimization, and press media prep.
* Cloudflare Pages workflow and launch hardening - Reason: Phase 16 owns deployment and launch evidence.

***

## 5. Technical Approach

### Architecture

Create `public-website/` as an npm workspace package named `@factionos/public-website`. The package will use Astro in static output mode, with the official blog starter as a lightweight foundation for source layout, content-ready structure, and baseline build behavior. Root `package.json` needs to include `public-website` in workspaces and root format/lint path coverage so the package participates in existing quality gates.

Because the repository is a monorepo, most work stays under `public-website/`. The root `package.json` and `package-lock.json` are intentional exceptions for workspace registration, script coverage, and dependency resolution.

### Design Patterns

* Temporary scaffold merge: prevents accidental overwrite of existing website planning files.
* Static-first Astro: keeps the first website release deployable as generated static output without server adapters or runtime hosted dependencies.
* Workspace-local package scripts: lets root build/typecheck include the website without custom orchestration.
* No-claim dependency review: verifies that excluded stacks and hosted behaviors are not introduced by scaffold drift.

### Technology Stack

* Node.js `26.2.0+`.
* npm `11.16.0`.
* Astro starter-compatible version, expected around `6.4.2` from the project planning snapshot.
* `@astrojs/mdx`, `@astrojs/sitemap`, `@astrojs/rss`, and `sharp` using starter-compatible versions.
* TypeScript checking through a package-local `astro sync && tsc --noEmit` script. Do not add `@astrojs/check` while its current language server dependency path resolves the vulnerable `yaml-language-server` subtree.
* Biome through root formatting and linting scripts.

***

## 6. Deliverables

### Files to Create

| File                                   | Purpose                                                | Est. Lines |
| -------------------------------------- | ------------------------------------------------------ | ---------- |
| `public-website/package.json`          | Website package metadata, scripts, and dependencies.   | \~45       |
| `public-website/astro.config.mjs`      | Astro static site config for `https://faction-os.com`. | \~25       |
| `public-website/tsconfig.json`         | Astro TypeScript defaults.                             | \~10       |
| `public-website/src/env.d.ts`          | Astro environment type declarations.                   | \~3        |
| `public-website/src/pages/index.astro` | Starter-safe static landing route placeholder.         | \~80       |
| `public-website/public/favicon.svg`    | Starter or temporary favicon foundation.               | \~20       |

### Files to Modify

| File                                                                                               | Changes                                                                                    | Est. Lines |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `package.json`                                                                                     | Add `public-website` workspace and include website path in format/lint scripts.            | \~8        |
| `package-lock.json`                                                                                | Lock Astro workspace dependencies from install.                                            | varies     |
| `public-website/README_public-website.md`                                                          | Preserve as source guidance; modify only if scaffold requires metadata alignment.          | \~0        |
| `.spec_system/specs/phase13-session01-astro-scaffold-and-workspace-wiring/implementation-notes.md` | Record environment, scaffold, preservation, and validation evidence during implementation. | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `public-website/package.json` is named `@factionos/public-website`.
* [ ] `astro.config.mjs` sets `site: "https://faction-os.com"` and keeps static output with no server adapter.
* [ ] Root npm workspaces recognize `public-website`.
* [ ] Root format/lint path coverage includes `public-website`.
* [ ] Existing `public-website/` planning files are still present after the scaffold merge.
* [ ] No analytics, hosted forms, auth, CMS adapter, React, Tailwind, shadcn/ui, third-party marketing template, or Astro server adapter is introduced.

### Testing Requirements

* [ ] `npm --workspace @factionos/public-website run build` succeeds, or the exact Node/npm blocker is recorded.
* [ ] `npm --workspace @factionos/public-website run typecheck` succeeds, or the exact Node/npm blocker is recorded.
* [ ] Root workspace package recognition is verified.
* [ ] Manual dev server start is attempted with `npm --workspace @factionos/public-website run dev`, or the exact environment blocker is recorded.

### Non-Functional Requirements

* [ ] Website remains static-output only for the first release.
* [ ] Deployment remains independent from the existing `public-demo` artifact.
* [ ] Sensitive local developer data, prompts, paths, replay data, analytics, and hosted identity claims are not added to website code or copy.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.

***

## 8. Implementation Notes

### Key Considerations

* The root workspace currently uses `apps/*` and `packages/*`; this session must add `public-website` explicitly because it is not under either pattern.
* The existing `public-website/` files are requirements and planning sources, not disposable starter content.
* The local shell version observed during planning is below baseline, so the implementation preflight must happen before scaffold, install, build, or typecheck results are treated as authoritative.

### Potential Challenges

* Scaffold overwrite risk: Use a temporary scaffold directory and copy files back intentionally.
* Dependency drift: Let the Astro wizard choose compatible versions first, then review the lockfile and package metadata for excluded stacks.
* Environment mismatch: Switch Node/npm to the repo baseline or record a clear blocker in implementation notes.
* Root script coverage drift: Keep format and lint script updates narrow and consistent with existing Biome command style.

### Relevant Considerations

* \[P03] **Stable docs are the current contract**: Use README files, docs, and current PRD sources for website scope instead of historical or example artifacts.
* \[P07] **Hosted services ship as disabled-default guardrails only**: Do not add analytics, hosted identity, hosted persistence, public replay, push, or remote access claims while creating the website scaffold.
* \[P08] **Release-candidate evidence is claim-scoped**: A passing local static build is not production-hosted validation.
* \[P04] **Asset provenance gate remains active**: Do not promote unknown, generated draft, historical, or conditional media through starter assets.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Existing planning files in `public-website/` could be overwritten by a starter scaffold.
* A starter or dependency could accidentally imply analytics, hosted behavior, server rendering, or a third-party marketing template.
* Build or typecheck evidence could be misleading if collected under the wrong Node/npm baseline.

***

## 9. Testing Strategy

### Unit Tests

* No new unit tests are expected for this scaffold-only session.

### Integration Tests

* Verify npm workspace discovery recognizes `@factionos/public-website`.
* Run website build and typecheck through package-local workspace scripts when the Node/npm baseline is satisfied.

### Manual Testing

* Start the Astro dev server with the package workspace script and confirm the starter route renders, or record the exact environment blocker.
* Inspect package metadata and dependencies for excluded stacks and hosted behavior.

### Edge Cases

* Existing files in `public-website/` must remain present after scaffold merge.
* Root workspace registration must not remove or rewrite existing `apps/*` and `packages/*` package coverage.
* If Astro installation requires network access and fails, record the package fetch error without making a successful scaffold claim.
* If Node/npm remains below baseline, record the blocker instead of treating build or typecheck failures as product failures.

***

## 10. Dependencies

### External Libraries

* `astro`: starter-compatible version, expected around `6.4.2`.
* `@astrojs/mdx`: starter-compatible version, expected around `6.0.1`.
* `@astrojs/sitemap`: starter-compatible version, expected around `3.7.3`.
* `@astrojs/rss`: starter-compatible version, expected around `4.0.18`.
* `sharp`: starter-compatible version, expected around `0.34.5`.
* `typescript`: starter-compatible version, expected around `5.9.3`.
* `vite`: Astro 6-compatible version, expected around `7.3.5`.

`@astrojs/check` is intentionally absent while its current language server dependency path resolves the vulnerable `yaml-language-server` subtree.

### Other Sessions

* **Depends on**: None.
* **Depended by**:
  * `phase13-session02-design-tokens-and-layout-shell`
  * `phase13-session03-seo-metadata-and-static-site-plumbing`
  * `phase13-session04-content-collections-and-publishing-templates`
  * `phase13-session05-asset-pipeline-and-brand-media-prep`

***

## 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/phase13-session01-astro-scaffold-and-workspace-wiring/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.