> 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-session03-blog-and-news-editorial-polish/spec.md).

# Session Specification

**Session ID**: `phase15-session03-blog-and-news-editorial-polish` **Phase**: 15 - Trust, Content, And Conversion Pages **Status**: Not Started **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript

***

## 1. Session Overview

This session polishes the blog and news publishing surfaces for the static FactionOS public website. Phase 13 established content collections, RSS, sitemap output, draft filtering, metadata helpers, and baseline blog/news routes. This work turns those functional publishing routes into launch-ready editorial pages with featured content, category/tag presentation, article navigation, credible seed entries, and validation coverage for feed and sitemap behavior.

The session matters because Phase 15 is expanding the trust, content, and conversion surface beyond core product pages. Blog and news content must be specific enough to validate templates, metadata, RSS, sitemap, category labels, and cross-links, while staying honest about product boundaries. The publishing surface should explain FactionOS as local-first mission control without adding analytics, hosted forms, a CMS, account behavior, or unproven hosted claims.

Implementation stays inside `public-website` as static Astro output. The work should reuse the existing content helpers, post layout, content components, metadata pipeline, and package-local build/typecheck commands. The result should be ready for the following Phase 15 sessions to cross-link company, contact, roadmap, FAQ, and legal pages without another publishing rewrite.

***

## 2. Objectives

1. Polish `/blog` and `/news` list pages with featured/latest entries, readable metadata, tags/categories, empty states, and reciprocal cross-links.
2. Improve blog/news detail pages with canonical metadata, Open Graph fallback, attribution, related entries, previous/next navigation, and draft-safe route generation.
3. Seed credible FactionOS-specific blog and news content that validates frontmatter, tags, categories, metadata, RSS, sitemap, and internal/external links.
4. Verify non-draft RSS and sitemap output, draft exclusion, package typecheck/build, ASCII/LF encoding, and no-overclaim editorial language.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - metadata, canonical URL, sitemap, robots, RSS, and structured data helpers exist.
* [x] `phase13-session04-content-collections-and-publishing-templates` - typed blog/news collections, draft filtering, feed helpers, and publishing routes exist.
* [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - package-local social image fallback and optimized website media patterns exist.
* [x] `phase14-session03-homepage-narrative-sections` - homepage narrative sections and local-first copy are available for cross-links.
* [x] `phase14-session05-features-and-how-it-works-pages` - feature and how-it-works routes provide product explanation targets for editorial links.
* [x] `phase15-session01-use-cases-hub-and-role-pages` - use-case routes provide role-specific internal link targets.
* [x] `phase15-session02-security-and-privacy-vault` - security and privacy route provides trust-boundary internal link targets.

### Required Tools/Knowledge

* Astro 6 static routes, content collections, `getStaticPaths`, and collection rendering.
* Existing `BaseLayout`, `Shell`, `Section`, `PostLayout`, `PostCard`, `PostMeta`, `TagList`, `RelatedPosts`, and publishing helpers.
* Markdown/MDX frontmatter validation through `public-website/src/content.config.ts`.
* Current no-claim boundaries from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`.
* Public website boundary: static output, no server adapter, no analytics by default, no hosted forms, no auth, no CMS, and no runtime personalization.

### 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 `/blog` and see a polished editorial index with a featured post, date, reading time, tags, category, summary, and cross-link to `/news`.
* Visitors can open `/blog/[slug]` and see title, description, dates, author, category, reading time, tags, canonical metadata, Open Graph fallback, attribution, related entries, and previous/next navigation where useful.
* Visitors can open `/news` and see a polished updates index with latest item, category grouping, RSS affordance, version/category metadata, and cross-link to `/blog`.
* Visitors can open `/news/[slug]` and see release/changelog announcement presentation with version, category, dates, author, tags, canonical metadata, related entries, and previous/next navigation where useful.
* Maintainers can rely on deterministic helper functions for visible entries, featured entries, grouped categories, related entries, previous/next entries, and feed items.
* Maintainers can review credible seed blog content covering agent observability, local-first architecture decisions, gamification design, product launch notes, and technical explainers.
* Maintainers can review credible seed news content covering release, changelog, company, and press-style categories without creating legal or investor claims.
* Non-draft entries feed RSS and sitemap output; drafts stay excluded from production output.
* Editorial links point to product, features, how-it-works, use-cases, security, demo, and docs as appropriate, using existing static link semantics.

### Out of Scope (Deferred)

* Search - *Reason: not needed for the initial editorial polish and would add separate indexing, interaction, and accessibility scope.*
* CMS - *Reason: first-release public website remains static Astro output with repository-owned Markdown/MDX content.*
* Large editorial backlog - *Reason: this session seeds enough content to validate templates and production posture, not a full publication calendar.*
* Tag archive pages - *Reason: tags should render on cards and posts; archive routes are deferred unless a later session explicitly scopes them.*
* Generated social image pipeline - *Reason: the existing default Open Graph image is sufficient for this session.*
* Runtime analytics, trackers, hosted forms, auth, CMS adapters, server rendering, runtime personalization, or cookies - *Reason: the public website boundary 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 commands - *Reason: these remain open, no-claim, or deferred outside the current public website publishing scope.*

***

## 5. Technical Approach

### Architecture

Build on the existing content collection architecture in `public-website/src/content.config.ts` and `public-website/src/lib/content.ts`. Extend the helper layer only where it removes duplication from list/detail routes: deterministic featured/latest selection, category grouping, category summary data, and previous/next entry navigation. Keep helper output typed to the existing collection contracts and preserve draft filtering as the default production posture.

Create small Astro components for reusable editorial presentation instead of embedding all markup in route files. A featured article component can share the same metadata/tag helpers as cards. A category/grouping component can present blog/news clusters without adding client-side filters. A previous/next or publishing navigation component can make detail pages easier to traverse while remaining fully static and accessible.

Route files should compose these primitives through `BaseLayout`, `Shell`, and `Section`. Detail pages should keep `PostLayout` as the shared article shell and pass in related and neighbor entries. RSS should continue to use non-draft, newest-first feed items with deterministic categories. Sitemap behavior should remain owned by Astro sitemap output.

### Design Patterns

* Typed content helpers: Centralize visible entries, grouping, related entries, and neighbor navigation so list and detail routes do not duplicate sorting or draft rules.
* Static editorial components: Use Astro components and scoped CSS with no client state, runtime fetches, or hosted dependencies.
* Shared metadata primitives: Reuse `PostMeta`, `TagList`, and `PostCard` variants for consistent dates, reading time, category, version, and tag rendering.
* Explicit boundary copy: Editorial seed content can describe product direction, but must label no-claim boundaries and avoid unsupported hosted or analytics claims.
* Deterministic empty states: Blog/news lists and category groups should render useful static empty states rather than blank regions.

### Technology Stack

* Astro 6.4.2 static output.
* TypeScript 5.9.3.
* Markdown/MDX content collections with `astro/zod` frontmatter validation.
* `@astrojs/rss` and `@astrojs/sitemap`.
* Scoped Astro component styles plus `public-website/src/styles/global.css` tokens.

***

## 6. Deliverables

### Files to Create

| File                                                               | Purpose                                                                                       | Est. Lines |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ---------- |
| `public-website/src/components/content/FeaturedPost.astro`         | Featured/latest post presentation with metadata, tags, summary, and accessible link treatment | \~220      |
| `public-website/src/components/content/CategoryGroup.astro`        | Static category grouping for blog/news entries with deterministic empty states                | \~180      |
| `public-website/src/components/content/PublishingNav.astro`        | Blog/news cross-link and previous/next article navigation component                           | \~160      |
| `public-website/src/content/blog/battlefield-cockpit-design.md`    | Gamification and cockpit/battlefield editorial seed post                                      | \~120      |
| `public-website/src/content/blog/hook-events-to-cockpit.md`        | Technical explainer seed post for hook events and local cockpit flow                          | \~130      |
| `public-website/src/content/news/website-publishing-polish.md`     | Changelog/release seed update for the polished publishing surface                             | \~90       |
| `public-website/src/content/news/factionos-public-site-expands.md` | Company/press-style seed update for expanded public site routes                               | \~90       |

### Files to Modify

| File                                                                 | Changes                                                                                                  | Est. Lines |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- |
| `public-website/src/lib/content.ts`                                  | Add typed featured/latest, grouped category, previous/next, and feed category helper functions           | \~140      |
| `public-website/src/components/content/PostCard.astro`               | Add optional featured/compact variants and metadata layout refinements                                   | \~90       |
| `public-website/src/components/content/PostMeta.astro`               | Refine category/version/reading-time display for card, hero, and detail contexts                         | \~50       |
| `public-website/src/components/content/RelatedPosts.astro`           | Support blog/news-specific headings and resilient empty handling                                         | \~35       |
| `public-website/src/layouts/PostLayout.astro`                        | Add attribution, neighbor navigation slot/props, social fallback verification, and article footer polish | \~120      |
| `public-website/src/pages/blog/index.astro`                          | Add featured post, category/tag presentation, reciprocal news link, and polished empty state             | \~130      |
| `public-website/src/pages/blog/[...slug].astro`                      | Pass related and neighbor entries while preserving draft-safe static paths                               | \~45       |
| `public-website/src/pages/news/index.astro`                          | Add latest update, category grouping, RSS affordance, reciprocal blog link, and polished empty state     | \~140      |
| `public-website/src/pages/news/[...slug].astro`                      | Pass release/changelog related and neighbor entries while preserving draft-safe static paths             | \~45       |
| `public-website/src/pages/rss.xml.js`                                | Confirm feed item ordering/categories and non-draft behavior for both collections                        | \~25       |
| `public-website/src/content/blog/introducing-factionos.md`           | Enrich launch seed content and frontmatter for template validation                                       | \~60       |
| `public-website/src/content/blog/local-first-agent-observability.md` | Enrich architecture seed content and cross-links                                                         | \~55       |
| `public-website/src/content/blog/why-agent-work-needs-a-cockpit.md`  | Enrich field-notes seed content and cross-links                                                          | \~55       |
| `public-website/src/content/news/initial-public-website.md`          | Enrich release seed content and metadata validation                                                      | \~45       |
| `public-website/src/content/news/public-demo-available.md`           | Enrich demo/news seed content and cross-links                                                            | \~45       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `/blog` renders a launch-ready index with featured post, cards, date, reading time, category, tags, and a visible cross-link to `/news`.
* [ ] `/blog/[slug]` renders canonical article metadata, Open Graph fallback, author attribution, updated date when present, tags, category, related entries, and previous/next article navigation.
* [ ] `/news` renders a launch-ready index with latest update, category grouping, version/category metadata, RSS affordance, and a visible cross-link to `/blog`.
* [ ] `/news/[slug]` renders release/changelog metadata, version where present, author attribution, tags, related entries, and previous/next update navigation.
* [ ] Blog seed content covers agent observability, local-first architecture, gamification design, product launch, and technical explainers.
* [ ] News seed content covers release, changelog, company, and press-style categories without making legal, investor, hosted identity, or production validation claims.
* [ ] Non-draft entries appear in RSS and sitemap output.
* [ ] Draft entries are excluded from production RSS, sitemap, and static detail routes.
* [ ] Internal links route to product, features, how-it-works, use-cases, security, blog, and news pages; external demo/docs links keep existing external destination treatment.

### Testing Requirements

* [ ] `npm --workspace @factionos/public-website run typecheck` passes.
* [ ] `npm --workspace @factionos/public-website run build` passes.
* [ ] Built `/blog`, `/news`, article pages, `rss.xml`, and sitemap output are inspected for metadata, non-draft entries, draft exclusion, route links, and no-overclaim copy.
* [ ] Manual responsive smoke checks cover desktop, tablet, and 360px mobile widths for featured posts, cards, category groups, detail metadata, related entries, previous/next navigation, and CTA/cross-link rows.
* [ ] Manual keyboard/focus review confirms article links, RSS link, previous/next links, and external demo/docs links expose clear names and focus treatment.

### Non-Functional Requirements

* [ ] Static website boundary is preserved: no analytics, trackers, forms, auth, CMS, server adapter, hosted persistence, runtime personalization, or command execution.
* [ ] Editorial copy avoids hosted identity, SSO, org membership, public collaboration safety, production auditability, formal certification, full trusted erasure, production-hosted validation, broad media readiness, real executor, remote execution, inbound command, and hidden telemetry claims.
* [ ] List/detail pages expose metadata and category information through text, not color alone.
* [ ] Text wraps without overlapping cards, headings, metadata, tags, RSS links, previous/next links, or CTA rows at common mobile widths.
* [ ] RSS and sitemap behavior remains deterministic across repeated builds.
* [ ] No new production dependency is added.

### Quality Gates

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

***

## 8. Implementation Notes

### Key Considerations

* The existing `filterVisibleEntries` and `getVisibleSortedEntries` helpers already encode the core draft behavior. Preserve that path and extend it rather than adding route-local filtering.
* Detail pages currently pass related entries only. Add neighbor navigation through helper output so sorting and draft rules remain consistent.
* Seed content should be credible but bounded. It can describe current product direction and static website progress, but must not imply hosted identity, active analytics, certification, production-hosted validation, or broad erasure guarantees.
* The `public-website` package has no tests directory today; validation for this session should emphasize package typecheck/build, built output review, and manual responsive/accessibility smoke checks.

### Potential Challenges

* Category grouping could duplicate sort logic: mitigate by adding typed helper functions in `public-website/src/lib/content.ts`.
* Seed content could drift into unsupported claims: mitigate by reviewing every new or edited article against `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`.
* Featured and card variants could create text overflow on mobile: mitigate with stable grid tracks, `min-width: 0`, wrapping metadata, and manual 360px review.
* Draft exclusion can be easy to break when adding helper paths: mitigate by inspecting production `dist/rss.xml`, sitemap output, and generated article routes after build.

### Relevant Considerations

* \[P14-public-website] **Public site page depth is still upcoming**: This session adds launch-ready publishing depth for Phase 15 without claiming the full public site is launch-complete.
* \[P13-public-website] **Public website external links are explicit**: Demo and GitBook links may appear in editorial content, but analytics, hosted forms, third-party fonts, CMS adapters, auth, and runtime personalization remain out of scope.
* \[P13-public-website] **Static Astro boundary is intentional**: Keep the blog and news surfaces static, package-local, and separate from `apps/web`, `public-demo`, and GitBook docs.
* \[P13-public-website] **Content collections fit publishing**: Typed blog/news collections, helper functions, static routes, RSS, sitemap, draft filtering, tags, and article metadata are the intended pattern.
* \[P14-public-website] **Typed marketing data modules**: Apply the same reviewable data discipline to publishing helpers and seed content.
* \[P13-public-website] **Website media claims are scoped**: Use existing social fallback/media records; do not promote conditional showcase assets by implication.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Draft entries accidentally appearing in production RSS, sitemap, or static detail routes.
* Editorial links or seed copy implying hosted identity, analytics capture, production-hosted validation, certification, or full trusted erasure.
* Featured/card/detail metadata overflowing, overlapping, or depending on color alone at mobile widths.
* Previous/next and related-entry helpers choosing unstable or draft-including results across builds.

***

## 9. Testing Strategy

### Unit Tests

* No package-local unit test suite exists for `public-website`. Use TypeScript typechecking for helper contracts and deterministic build output inspection for route/feed behavior.

### Integration Tests

* Run `npm --workspace @factionos/public-website run typecheck`.
* Run `npm --workspace @factionos/public-website run build`.
* Inspect `public-website/dist/blog/index.html`, `public-website/dist/news/index.html`, generated article pages, `public-website/dist/rss.xml`, and sitemap XML for expected entries and draft exclusion.

### Manual Testing

* Review `/blog`, `/news`, representative blog detail pages, and representative news detail pages in desktop, tablet, and 360px mobile viewport widths.
* Tab through article links, RSS link, previous/next links, cross-links, and external demo/docs links.
* Confirm tag/category rows, date metadata, reading time, author attribution, and version labels remain readable and do not overlap.

### Edge Cases

* Empty blog/news collections render explicit empty states.
* Draft posts render in dev preview but do not appear in production build output.
* Entries with identical dates sort deterministically by title and path.
* Entries without `updatedDate`, `version`, or `heroImage` still render stable metadata and social fallback.
* Tags with long words or many entries wrap without breaking layout.
* Previous/next navigation is omitted or disabled cleanly for first/last entries.

***

## 10. Dependencies

### External Libraries

* `astro`: 6.4.2
* `@astrojs/mdx`: 6.0.1
* `@astrojs/rss`: 4.0.18
* `@astrojs/sitemap`: 3.7.3
* `sharp`: 0.34.5
* `typescript`: 5.9.3

### Internal Dependencies

* `public-website/src/content.config.ts` collection schemas.
* `public-website/src/lib/content.ts` publishing helpers.
* `public-website/src/lib/metadata.ts` metadata helpers.
* `public-website/src/data/site.ts` route, metadata, demo, and docs constants.
* `public-website/src/layouts/BaseLayout.astro` and `public-website/src/layouts/PostLayout.astro`.
* `public-website/src/components/content/*` publishing components.
* `public-website/src/components/layout/Section.astro` and `public-website/src/components/layout/Shell.astro`.

### Other Sessions

* **Depends on**: Phase 13 Session 03, Phase 13 Session 04, Phase 13 Session 05, Phase 14 Session 03, Phase 14 Session 05, Phase 15 Session 01, Phase 15 Session 02.
* **Depended by**: Phase 15 Session 04 company/contact pages, Phase 15 Session 05 roadmap/FAQ/legal pages, Phase 15 Session 06 cross-linking and copy consistency pass, and Phase 16 launch validation.

***

## 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-session03-blog-and-news-editorial-polish/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.