Package edge repo as a runnable onboarding funnel

[levleontiev]

Why

The edge repo already has a strong README and useful policy samples, but it is still weaker than it should be as a hands-on onboarding funnel. The main gap is packaging, not missing ideas.

Problem

Current examples/ are mostly policy snippets plus markdown, not end-to-end runnable recipes. There is no single canonical quickstart folder that takes a user from clone to working enforcement with expected output. There is also no dedicated place for sample reject/output artifacts.

Scope

1. Add one canonical runnable quickstart path in the repo.
2. Turn the existing policy samples into a smaller set of deployable recipes.
3. Add sample response/output artifacts for the most important behaviors.
4. Link to fairvisor/benchmark as the benchmark source of truth instead of duplicating benchmark methodology in this repo.

Proposed deliverables

• examples/quickstart/ with runnable docker-compose.yml or equivalent
• expected-output section or fixture files showing success / reject behavior
• 3 canonical recipes built from existing samples:
  • team budgets
  • runaway agent guard
  • provider failover or equivalent edge-control scenario
• dedicated sample outputs for:
  • fixtures/reject_tpm_exceeded.json — 429 JSON body for TPM limit hit
  • fixtures/reject_tpd_exceeded.json — 429 JSON body for TPD (daily) limit hit
  • fixtures/reject_prompt_too_large.json — 429 JSON body for max_prompt_tokens exceeded
  • relevant headers (Retry-After, RateLimit-*, X-Fairvisor-Reason) shown in fixture comments or README
  • OpenAI-compatible reject behavior fixture
• README tightening where needed to point into the new runnable path
• README/docs pointer to fairvisor/benchmark as benchmark source of truth

Implementation constraints

• Standalone mode first: the quickstart must work without a SaaS account (standalone/local config mode). SaaS-connected mode is a follow-on step, not a prerequisite.
• Reuse the e2e compose setup: examples/quickstart/docker-compose.yml should be reusable as the base for the e2e smoke test (e2e-smoke CI check). Avoid a second parallel compose stack diverging from the example.
• Named fixture files: sample artifacts must use the specific filenames listed above so CI and docs can reference them by stable paths.

Acceptance criteria

• docker compose up -d && curl -s http://localhost:8080/v1/chat/completions -d @fixtures/over_limit_request.json returns a 429 with the body matching fixtures/reject_tpm_exceeded.json.
• docker compose up -d && curl -s http://localhost:8080/v1/chat/completions -d @fixtures/normal_request.json returns 200.
• A technical user can go from clone to first working result through one canonical repo-owned path without stitching together docs manually.
• examples/ read as deployable recipes, not just disconnected policy fragments.
• The repo contains concrete sample outputs for core enforcement behaviors (at minimum: TPM reject, TPD reject, prompt-too-large reject, allowed pass-through).
• Benchmark content in this repo links to fairvisor/benchmark instead of diverging from it.

Dependencies

• Downstream: fairvisor/documentation issue fix: avoid colliding IPs in retry-after jitter test #8 — the docs site navigation and install/deploy guidance should link into the quickstart path added here. Coordinate the fixture file paths and compose structure before the documentation PR lands.