docs(readme): rewrite for v2 with progressive disclosure

Andrew Dunnrequested to merge
docs/readme-v2 into main

The v0.3.0 README had real drift in places where new users land:

  • Supported sources table listed azure/gcp/cloudevents (pre-rename names) and omitted aws.sqs + kafka entirely. A reader copying from it hit "unknown type" on validate.
  • auth.token_env references survived the schema flatten.
  • Subcommand CLI (run / validate / fire / version) wasn't surfaced as a contract; only visible in scattered code blocks. postern fire was completely undocumented.
  • version: 1 requirement appeared in code blocks but the schema-versioning story was never stated.
  • "Adding a new source" -- the central pluggability win of v2 -- was absent. Contributors had to read the source tree to find it.
  • Base image listed by floating tag while the Dockerfile pins by @sha256:... digest.

Restructured for progressive disclosure -- reader gets value at every depth and can stop at any level.

New shape

Section Why
Hero + tagline Broadened beyond push-only framing
How it works Diagram lists all 5 adapter types
Supported sources Correct table with mode + auth columns
The 30-second example Minimal config + one container run
Commands Subcommand surface as a contract
Schema versioning Explicit version: 1 callout
Per-source configuration One section per adapter (azure.eventgrid, gcp.pubsub, aws.sqs, kafka, cloudevents) with YAML, behavior, auth model
Routing Match patterns, envelope shortcuts vs gjson paths, variable injection
Configuration reference Top-level keys + rate_limit semantics
Getting started end-to-end Pull, write, validate, fire, run
Kubernetes deployment Updated probe paths
Developer binaries Already current
Observability 4 endpoints + OTel; metric names enumerated
Config reload Same
GitLab project setup Same
Prescriptive errors Same
Adding a new source Layout, 3 steps, discipline rules, worked examples -- the contributor onboarding @graysongordon-gl asked for in his original decomp issue
Security model Now includes SQS + Kafka rows
Image details Mentions digest pinning, coverage, smoke test, byte-parity binary

What did NOT change

  • All the technically-accurate sections from the prior README are preserved verbatim (observability, GitLab project setup, prescriptive errors, config reload).
  • The badge row, hero, license footer.

Verification

  • postern.yml.example already aligned with the new schema; no change needed.
  • examples/*.cloudevent.json exercised by the postern-fire CI job; consistent with the README's fire examples.
  • chart/templates/deployment.yaml already had /livez + /readyz probes from v2 work.

For @graysongordon-gl

The "Adding a new source" section is the answer to the docs follow-up you mentioned in !9 (closed). If the section gives you what you need to land a sixth adapter, I'd love that signal -- if anything's missing, that's a real gap I want to close.

Merge request reports