apophis-fastify/docs/attic/GITHUB_SITE_STRATEGY.md

# GitHub Site Strategy

Status: Proposal
Audience: maintainers, docs authors, design collaborators
Purpose: define what the GitHub Pages or project homepage should say, show, and optimize for

## 1. Core Thesis

The website should not try to teach all of APOPHIS on the homepage.

The homepage should show the product value with one runnable example.

Its job is to give visitors the fastest possible answer to:

- why APOPHIS exists
- why it matters for Fastify services
- what the first behavioral signal looks like
- how to get that signal quickly

## 2. The First Behavioral Signal

The first behavioral signal is not:

- “it can parse a DSL”
- “it supports many advanced features”
- “it generates lots of tests”

The first behavioral signal is:

One route-level behavioral contract catches a retrievability bug that schema validation and ordinary happy-path tests miss.

Canonical example:

- route: `POST /users`
- contract: `response_code(GET /users/{response_body(this).id}) == 200`
- outcome: APOPHIS reports that the resource is not retrievable after creation

That example should appear on the homepage.

## 3. Audience Segments

Primary audiences:

1. Fastify app teams shipping business APIs quickly
2. platform and reliability teams hardening service quality
3. teams adopting LLM-generated Fastify services and wanting stronger safeguards

Secondary audiences:

1. protocol-heavy teams building auth, identity, billing, or workflow systems
2. library maintainers evaluating APOPHIS as part of service templates

## 4. Homepage Goals

The homepage must achieve four goals in order:

1. explain category
2. demonstrate value
3. establish trust
4. give a first step

If the page does not deliver those in sequence, it overemphasizes features before demonstrating value.

## 5. Recommended Homepage Structure

### 5.1 Hero

Headline direction:

- Behavioral confidence for Fastify services
- Catch the API regressions schema validation misses

Support copy direction:

- Write behavioral contracts next to your route schemas and verify that your API still does what it promises across operations, state changes, and protocol flows.

Primary CTA:

- Find a behavioral bug in 10 minutes

Secondary CTA:

- See the bug APOPHIS catches

### 5.2 Behavior Example

Show one tiny route snippet and one small failure output.

Left side:

```ts
'x-ensures': [
  'response_code(GET /users/{response_body(this).id}) == 200'
]
```

Right side:

```text
Contract violation
POST /users

Expected:
  response_code(GET /users/{response_body(this).id}) == 200

Actual:
  GET /users/usr-123 returned 404

Replay:
  apophis replay --seed 42 --route "POST /users"
```

The visitor should understand the product from this block alone.

### 5.3 Why It Matters

This section explains the meaning:

- JSON Schema checks shape
- APOPHIS checks behavior
- many outages happen because APIs stop behaving correctly while still returning valid shapes
- fast-moving and LLM-assisted teams need guardrails at the behavior layer

### 5.4 The Three Modes

Explain the product model clearly:

- `verify`: deterministic CI confidence
- `observe`: runtime visibility without blocking by default
- `qualify`: scenario, stateful, and chaos checks for critical flows

This section should be short and visual.

### 5.5 First-Signal Quickstart

Show exactly three commands:

```bash
npm install apophis-fastify fastify @fastify/swagger
apophis init --preset safe-ci
apophis verify --profile quick --routes "POST /users"
```

Link onward to `docs/getting-started.md`.

### 5.6 Trust and Safety

Explain why users should trust it:

- deterministic replay
- CI-safe default path
- production-safe observe path
- qualify path gated away from prod by default
- explicit environment boundaries

### 5.7 LLM-Coded Services

This section should say:

- APOPHIS gives coding agents a repeatable pattern for route behavior validation
- official templates reduce hallucinated setup
- `doctor` and policy checks catch malformed integration early

### 5.8 Advanced Cases

Short cards or links only:

- protocol flows
- stateful lifecycle testing
- outbound dependency contracts
- chaos and adversity qualification

Do not fully teach them on the homepage.

### 5.9 Final CTA

Suggested CTAs:

- Start with `verify`
- Read the 10-minute guide
- See qualification examples

## 6. The First-Signal Funnel on the Site

The site should intentionally walk visitors through this funnel:

1. This is different from schema validation.
2. This catches a real bug.
3. I can get that signal quickly.
4. I can trust it in CI and production workflows.
5. I know where to go next.

The homepage should optimize for the first three.

Docs should optimize for the last two.

## 7. Content Rules

The homepage should not:

- lead with parser internals
- lead with extension architecture
- lead with every feature or every config option
- sound like a generic testing tool
- force users to understand advanced terminology before they see value

The homepage should:

- lead with one production-shaped bug example
- use simple language
- emphasize meaning over mechanism
- reinforce the difference between shape and behavior

## 8. Recommended Information Architecture

Suggested top navigation:

- Home
- Getting Started
- Verify
- Observe
- Qualify
- LLM-Safe Adoption
- Protocols
- API Reference

Suggested footer links:

- GitHub
- Changelog
- Design proposal
- Attic / historical docs

## 9. Success Metrics for the Site

The homepage succeeds if users can quickly answer:

- what APOPHIS does
- why it matters
- what the first behavioral signal looks like
- which command to run first

Practical metrics:

- clickthrough from homepage hero to getting started
- clickthrough from behavior example to quickstart
- completion rate for first `verify` run
- time to first meaningful signal

## 10. Final Position

The website should sell the meaning of APOPHIS before the mechanics of APOPHIS.

The meaning is:

- your Fastify service may still be structurally valid while behaviorally broken
- APOPHIS helps you catch that early
- and it can do so fast enough to matter in day-to-day development