# Docs Revamp Design — 2026-07-01

**Scope:** `apps/docs/` — Astro/Starlight public documentation site at docs.reactiveagents.dev  
**Version target:** Ships alongside v0.13 "Receipts" launch  
**Inspiration:** Tailwind CSS (three-tier IA), shadcn (star CTA + trust), Supabase (framework quickstarts), Railway (competitor section), Stripe (problem-first entry points)

---

## 1. Information Architecture — Approach B

Restructure from 9 grab-bag sections to 9 semantically clear sections. No content rewrites — frontmatter `sidebar.order` + `astro.config.mjs` sidebar array only.

### New sidebar structure

```
Get Started
  Introduction
  Installation
  Quickstart
  Your First Agent
  Choosing a Stack

Build
  Reasoning Strategies
  Choosing a Strategy
  Tools
  Memory
  Typed Structured Output      [New in v0.12]
  Streaming Responses
  Chat & Sessions
  Lifecycle Hooks
  Interaction Modes
  Context Engineering
  Sub-Agents
  Agent Skills
  Local Models
  Messaging Channels
  Web Integration

Ship to Production
  Production Checklist
  Durable Execution             [New in v0.12]
  Durable Human-in-the-Loop    [New in v0.12]
  Cost Optimization
  Guardrails
  Security Hardening

How It Works                    ← replaces split Features + Concepts sections
  Architecture
  Agent Lifecycle
  Composable Kernel
  Decision Tracing
  Layer System
  Effect-TS
  Reactive Intelligence
  [remaining Features pages autogenerated into this section]

vs. Alternatives                ← pulled out of "Help & More" grab-bag
  Migrating from LangChain
  vs. LangGraph
  vs. Mastra
  vs. Vercel AI SDK
  vs. Agent SDKs (OpenAI/Claude)

Cookbook                        ← autogenerate, unchanged
API Reference                   ← autogenerate, unchanged
Rax CLI                         ← unchanged

Help & More                     ← stripped to essentials
  FAQ
  Troubleshooting
  Contributing
  What's New                    [v0.12]
  Examples Catalog
  Interactive Playground
```

### Key changes from current
- `Features` + `Concepts` → merged into `How It Works`
- Comparison/migration pages → dedicated `vs. Alternatives` section (acquisition surface)
- `Core Guides` (15 flat items) → split into `Build` + `Ship to Production` with clear job-to-be-done framing
- `Help & More` stripped from 9 items to 6 (comparisons moved out)

---

## 2. Unified Badge System

### Replaces
- `public/new-page-indicator.js` (runtime JS hack)
- `src/plugins/new-page-indicator.ts` (Astro plugin)
- Manual `window.__ra_new_pages_data__` injection

### New: `scripts/sync-page-metadata.ts`

Runs as `prebuild`. For each `.md`/`.mdx` under `src/content/docs/`:

1. `git log --follow -1 --pretty="%s|%h|%ad" --date=short -- <file>` → last commit subject, hash, date
2. Reads existing frontmatter `stability:` and `since:` fields
3. Computes age from git date vs. current date
4. Writes `badge:` + `lastCommit:` frontmatter — **never overwrites manually-set `badge:`**
5. Backfills `since: vX.Y` from nearest git tag at file's first-commit date (best-effort — skips on shallow clones, leaves field empty if no tag found)

### Badge decision table

| Condition | Sidebar badge | Variant |
|-----------|--------------|---------|
| File `< 14 days` old (first commit), no `since` yet | `New in vX.Y` | `success` |
| File changed `< 7 days`, existed before | `Updated` | `note` |
| `stability: experimental` in frontmatter | `Experimental` | `caution` |
| `stability: unstable` in frontmatter | `Unstable` | `default` |
| `stability: deprecated` in frontmatter | `Deprecated` | `danger` |
| Manual `badge:` already set | untouched | — |

All badges use native Starlight `badge:` frontmatter — renders in sidebar AND page title, works with SSG, no JS required.

### Page-level "what changed" callout

Custom `MarkdownContent` override component (`src/components/MarkdownContent.astro`) injects a collapsible `<Aside>` at top of any page with `Updated` or `New` badge:

```
ℹ Updated 3 days ago
"docs: add .withModelRouting() cost-aware model routing" · 32b7fec · 2026-06-30
```

- Collapsed by default on mobile
- Omitted on homepage (`template: splash`) and 404
- Commit hash links to `https://github.com/tylerjrbuell/reactive-agents-ts/commit/<hash>`
- Data sourced from `lastCommit` frontmatter field (set by build script)

### Version-aware design (future: `starlight-versions`)

`since: vX.Y` frontmatter on every page enables:
- Badge text `New in v0.13` rather than just `New`
- When `starlight-versions` plugin is added (v0.14+ target), version switcher reads this field — no migration needed

---

## 3. GitHub Star CTA

### Placement (3 locations)

**Location 1 — Homepage hero (primary)**  
Second action button alongside "Get Started":
```
[→ Get Started]  [⭐ Star on GitHub]
```
Fires existing `hero_cta` Umami event with `label: "star_github"`.

**Location 2 — Sidebar header**  
Static count updated at build time via GitHub API fetch in `prebuild`:
```
⭐ Star on GitHub · 16
```
Rendered as a custom Starlight sidebar header component override.

**Location 3 — Right-hand page sidebar (PageSidebar)**  
Persistent widget below TOC on every non-splash page:
```
┌──────────────────────────────┐
│ ⭐ Star Reactive Agents       │
│ Help others find the project  │
│ [Star on GitHub →]           │
└──────────────────────────────┘
```
Fires new `github_star_cta` Umami event with `location: "sidebar"`.

### Star count strategy
- Build script fetches `https://api.github.com/repos/tylerjrbuell/reactive-agents-ts` → `stargazers_count`
- Written to `src/data/github-stats.json` at build time
- Displayed as static number (honest, no fake-loading spinner)
- Falls back to empty if API unavailable

### Trust signals (no "trusted by" — too early)
- npm version + weekly downloads badge in sidebar or hero area
- CI passing badge (already in README, pull into docs)
- Benchmark panels on homepage remain the primary credibility anchor

---

## 4. Umami — New Events

Added to `public/umami-deep.js`. All follow existing naming convention (`lowercase_snake_case`).

| Event | Trigger | Data |
|-------|---------|------|
| `github_star_cta` | Star CTA click (any location) | `{ location: "hero"\|"sidebar"\|"page", from: pathname }` |
| `sidebar_nav` | Sidebar `<a>` click | `{ label, section, to, from: pathname }` |
| `version_badge_hover` | Pointerenter on stability badge | `{ badge, path }` |
| `changelog_link` | "Updated" callout hash click | `{ hash, path }` |
| `toc_click` | TOC anchor link click | `{ heading, path }` |
| `404_hit` | Page load on `/404/` path | `{ referrer: document.referrer }` |
| `time_on_page` | `visibilitychange` → hidden | `{ path, seconds }` — capped 600s |
| `search_result_click` | Pagefind result click | `{ q, result_title, result_path, rank }` |

**Sidebar nav tracking note:** Use event delegation on `nav.sidebar` — avoids attaching listeners to 90+ individual links.

---

## 5. Starlight Plugins & DX Upgrades

### Add now
- `starlight-scroll-to-top` — persistent back-to-top on long pages (reference, cookbook)
- Expressive-code `terminal` frame theme — visual distinction between shell commands and TypeScript snippets
- Numbered step counters in Installation + Quickstart pages (Tailwind pattern) — CSS `counter-reset` on `ol`, renders `01 →` prefixes; no new component needed

### Defer to v0.14+
- `starlight-versions` — version switcher; requires `since:` frontmatter populated first (done in this revamp, so unblocked after)
- `starlight-giscus` — GitHub-backed comments; empty comment sections hurt trust more than no comments; add when star count > 100

### Keep unchanged
- `starlight-image-zoom` ✓
- `starlight-links-validator` ✓
- `starlight-llms-txt` ✓
- `astro-skills` ✓
- Context7 widget ✓
- `new-page-indicator` plugin → **removed** (replaced by badge system)

---

## 6. Code Accuracy Audit

Separate pass over all guides + cookbook pages:

1. Grep all code blocks for `.withLeanHarness()` → update to `.withProfile(HarnessProfile.lean())`
2. Check `guides/structured-output.mdx`, `guides/durable-execution.md`, `guides/durable-hitl.md` — these are newest, most likely correct
3. Verify `guides/reasoning.mdx` strategy list matches actual 7 strategies (reactive, reflexion, plan-execute, tree-of-thought, code-action, direct, adaptive + blueprint)
4. Add `.withModelRouting()` to `guides/cost-optimization.md` (new in v0.13, just landed)
5. Verify all `import` paths use `reactive-agents` (not `@reactive-agents/core` etc.) in public-facing examples

---

## 7. Out of Scope (this revamp)

- Framework quickstart cards (Supabase/Resend pattern) — content investment, defer to v0.13 Show-HN push
- "Trusted by" social proof — too early, no notable users yet
- `starlight-versions` version switcher — implementation deferred; schema is future-ready
- Full content rewrites of any guide pages
- A2A protocol docs expansion
- Cortex docs restructure

---

## Implementation Order

1. **IA restructure** — `astro.config.mjs` sidebar, frontmatter `sidebar.section` on migrated pages
2. **Badge system** — `scripts/sync-page-metadata.ts`, remove `new-page-indicator`, `MarkdownContent` override
3. **GitHub star CTA** — build script GitHub API fetch, `PageSidebar` widget, hero button
4. **Umami additions** — `umami-deep.js` new events
5. **Starlight plugins** — `starlight-scroll-to-top`, expressive-code terminal theme, numbered steps CSS
6. **Code accuracy audit** — grep + fix pass across all guides
