chore: crush git history - reborn from consolidation on 2026-03-10
This commit is contained in:
John Dvorak
@@ -0,0 +1,258 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user