# GAVEL docs

- [GAVEL documentation](/docs): Every bid is a PayPal hold; only the winner pays. What it does, what is proven on the PayPal sandbox, and what is not.
- Learn: What GAVEL is and how it works
  - Start here
    - [Start here (judge path)](/docs/start): A short path through GAVEL for judges, with the status stated plainly.
    - [The guided tour](/docs/start/guided-tour): Ten steps through the docs, from what GAVEL is to what is not done yet, with the process of one auction in a single diagram.
    - [Beginner path](/docs/start/beginner-path): What an auction hold is, in plain words, and a six step route through the docs for someone new to all of it.
    - [Real, simulated, recorded](/docs/start/status): One table that says what is real PayPal sandbox, what is the fake PayPal, what is simulated and what is recorded.
    - [Demo guide](/docs/start/demo): What you can try today, what needs a hosted server, and what is not built yet.
    - [Concepts in one page](/docs/start/concepts): Hold, ceiling, capture, void, hammer and soft close.
  - How it works
    - [How it works](/docs/how-it-works): Three steps, then the five mechanisms behind them.
    - [System architecture, end to end](/docs/how-it-works/system-architecture): Every part of GAVEL from the browser to PayPal and the disk, and how a bid, a hold, a voice bid and a webhook travel through them.
    - [Bid lifecycle](/docs/how-it-works/bid-lifecycle): From a tap or a spoken bid to an accepted or rejected bid, with the confirm gate in the middle.
    - [Auction states and soft close](/docs/how-it-works/auction-states): The states a lot moves through, who can hammer it, and how the soft-close clock extends the end.
    - [Registration and holds](/docs/how-it-works/registration-and-holds): How a buyer joins an auction, what a hold is in plain words, and every step from choosing a ceiling to HELD.
    - [Money flow](/docs/how-it-works/money-flow): Holds, capture and void: where the money is at each moment.
    - [Settlement saga](/docs/how-it-works/settlement-saga): The state machine, the journal and idempotency.
    - [Settlement walkthrough](/docs/how-it-works/settlement-walkthrough): One winner, three holds, in integer cents. Capture, remainder release, voids and the runner-up fallback, step by step.
    - [Idempotency and request ids](/docs/how-it-works/idempotency): How GAVEL can repeat a money call after a timeout or a crash without charging twice.
    - [Retries and unknown outcomes](/docs/how-it-works/retries-and-unknown-outcomes): What the saga does when a capture is refused, rate limited, times out or never gets an answer.
    - [Honor period and reauthorization](/docs/how-it-works/honor-period): How long a hold can be captured, what GAVEL does about it, and exactly what gate G3 is testing on the real sandbox.
    - [Crash recovery](/docs/how-it-works/crash-recovery): What happens when the process dies in the middle of a capture.
    - [Voice and the confirm gate](/docs/how-it-works/voice-and-confirm): Speech never becomes a bid by itself. The pipeline, the gate and where the accuracy gate stands.
    - [Engine and ledger](/docs/how-it-works/engine-and-ledger): A deterministic auction core and a hash-chained audit trail.
  - Next steps and changelog
    - [Roadmap](/docs/roadmap): The next steps, in order, and what the G3 readings decide.
    - [Limits and next steps](/docs/roadmap/limits): What is built and measured today, and the next step for each open item, with owners and dates where they are known.
    - [Changelog](/docs/roadmap/changelog): What changed in GAVEL, day by day, with a link to every merged pull request.
- Prove: Gates, evidence and limits
  - Proof
    - [Proof](/docs/proof): What has been proven, against what, and what has not.
    - [Gates G0 to G5](/docs/proof/gates): Each sandbox gate, its result and the caveat that goes with it.
    - [Gate G0: sandbox connectivity](/docs/proof/gate-g0): Does the sandbox app authenticate, and can it create an AUTHORIZE order? Method, evidence and limits.
    - [Gate G1: partial capture and remainder](/docs/proof/gate-g1): Authorize 500.00, capture 350.00 with final_capture, then look at the 150.00 remainder. Method, evidence and limits.
    - [Gate G2: card and guest AUTHORIZE](/docs/proof/gate-g2): Does an Orders v2 AUTHORIZE flow work for wallet and guest card buyers in SDK v6? Method, evidence and limits.
    - [Gate G3: honor period and reauthorize](/docs/proof/gate-g3): How long an authorization stays capturable, and whether reauthorize extends it. In progress, with a simulation beside it.
    - [Gate G4: webhook signatures](/docs/proof/gate-g4): Does signature verification accept real PayPal events and reject tampered ones? Method, evidence and limits.
    - [Gate G5: speech accuracy](/docs/proof/gate-g5): Is speech-to-text accurate enough to accept bids without confirmation? Not proven. On synthetic audio the numbers now meet the limit, but they were tuned on the same clips. Real numbers, method and limits.
    - [The 30 day simulation](/docs/proof/simulation): Eight scenarios on a fake PayPal and a fake clock. Labelled SIMULATED.
    - [Latency](/docs/proof/latency): Measured PayPal sandbox latency and the targets it does not meet.
    - [Evidence map](/docs/proof/evidence-map): Every claim on this site, the status it holds, what it ran on, and the file or workflow behind it.
    - [Quality checks](/docs/proof/quality-checks): What CI runs on every change.
    - [Accessibility](/docs/proof/accessibility): The automated checks that run, and the manual pass that nobody has done yet.
- For judges: Paths, rubric map, evidence index
  - For judges
    - [For judges](/docs/judges): Two paths, a rubric map, an evidence index and honest answers. Everything is PayPal sandbox only.
    - [Two-minute path](/docs/judges/two-minute-path): Five clicks on this site that show what GAVEL claims, what is proven and what is not.
    - [Ten-minute path](/docs/judges/ten-minute-path): The deep path. Read the raw evidence, verify the ledger, run the fake-PayPal demo and check the quality gates.
    - [Rubric map](/docs/judges/rubric-map): The five Stage Two judging criteria, each mapped to concrete pages and committed evidence.
    - [Evidence index](/docs/judges/evidence-index): Every claim made on this site, its status, and the committed file or run that backs it.
    - [Findings that mattered](/docs/judges/findings-that-mattered): The six critical red-team findings with their fixes and tests, the high findings by theme, and what is still open.
    - [Tough questions](/docs/judges/tough-questions): Straight answers about voice accuracy, gate G3, the fake PayPal, the road to production and the security review.
    - [Trust and FAQ](/docs/judges/trust-and-faq): What happens to your login, your money and your data when you try a GAVEL room, and what to do when something goes wrong.
    - [Sandbox buyers](/docs/judges/sandbox-buyers): How to approve a hold with a PayPal sandbox buyer, and what to try when the PayPal window gives trouble.
    - [Real, simulated, recorded](/docs/judges/real-vs-simulated): What each claim in the video and on this site is backed by. Mirrors the video label sheet.
    - [Open data](/docs/judges/open-data): Five small datasets and an Evidence Explorer Space, live on Hugging Face, each labelled for what it is.
    - [Data engineering](/docs/judges/data-engineering): How the open datasets are built, validated, versioned and verified. Published on Hugging Face.
    - [Demo script](/docs/judges/demo-script): The three-minute video, shot by shot, with the on-screen label and the truth behind each shot.
    - [Call the API as a judge](/docs/judges/call-the-api): Use the key you were given to open a sandbox room, bid, hammer and read the ledger with curl, or try each call on this page.
- Builders: Architecture, packages, tests
  - Builders
    - [Builders](/docs/builders): How the repository is organised, the one rule that keeps it honest, and where to start reading.
    - [Repository layout](/docs/builders/repo-layout): What is in the repository, folder by folder, and which area owns it.
    - [Run and test](/docs/builders/run-and-test): Every package script, what runs in CI, and where heavy work belongs.
    - [AG Grid tables](/docs/builders/ag-grid): How the ledger, bid history and holds tables are built with AG Grid Community.
    - [Contributing](/docs/builders/contributing): Branch and pull request naming, commit rules, labels, ownership and the checks a change must pass.
    - Packages
      - [shared](/docs/builders/packages/shared): The vocabulary every package agrees on: money, ids, wire messages, ports, config schema.
      - [engine](/docs/builders/packages/engine): The pure auction core: decide, evolve, the hash-chained ledger and the redacted public export.
      - [payments](/docs/builders/packages/payments): PayPal holds, the settlement saga, webhooks, reconciliation and the fake PayPal.
      - [server](/docs/builders/packages/server): The single process that hosts the rooms, the HTTP API, the WebSocket gateway and settlement.
      - [@gavel/voice](/docs/builders/packages/voice): Audio framing, speech-to-text providers, the bid parser and the decision step that turns speech into a confirm prompt or a bid.
      - [@gavel/web](/docs/builders/packages/web): The browser client: routes, the transport seam, the payment approval port, the copy rules and the bundle gate.
      - [@gavel/e2e](/docs/builders/packages/e2e): The scenario language and runner, property tests, load harness, browser specs and the real-sandbox specs.
      - [Infra and tooling](/docs/builders/packages/infra): Workflows, deploy configuration, repository scripts and the root tooling that enforce the rules.
- Operators: Deploy, secrets, runbooks, incidents
  - Run it yourself
    - [Run it locally](/docs/run): Run GAVEL on your machine with the built-in fake PayPal. No PayPal account needed.
    - [Operator runbook](/docs/run/operator-runbook): Deploy, set secrets by name, check the result, and what to do when something goes wrong. Names only, never values.
    - [Use the real PayPal sandbox](/docs/run/sandbox): The settings that switch GAVEL from the fake PayPal to the sandbox.
    - [Deploy staging](/docs/run/deploy): Hosting the server on Render and the web client on Cloudflare.
    - [Hosting on Render](/docs/run/hosting-on-render): How GAVEL uses Render for its API and WebSocket host, why one instance with a persistent disk, how deploys and checks work, and what we would change to scale out.
    - [Re-running a gate](/docs/run/gate-runbook): What to do when a gate fails, stays NOT RUN, or reads stale.
    - [CI and deployment map](/docs/run/ci-pipeline): Every workflow that checks, proves, deploys or watches GAVEL, when it runs, what it needs by name and what it leaves behind.
    - [Incident response](/docs/run/incident-response): What to do, in order, when money state looks wrong. Built only from what the repository documents.
  - Safety
    - [Sandbox-only safety](/docs/safety): The rules that keep GAVEL on the PayPal sandbox and keep secrets out of the repository.
    - [Threat model](/docs/safety/threat-model): Who can do what, where the trust boundaries are, and what each secret protects. Names only, never values.
    - [Security review](/docs/safety/security-review): The checklist and where it stands: all eight P0 items pass, and the log scan plus the two judge-room items are next.
    - [Webhooks](/docs/safety/webhooks): How a PayPal webhook is verified, stored once, matched to a hold and merged, and why a lost or repeated one does no harm.
    - [Ledger backup](/docs/safety/backup): The daily encrypted snapshot, and a restore procedure that is documented but not exercised.
- Reference: Protocol, data model, config
  - Reference
    - [Architecture](/docs/reference/architecture): Seven packages in one strict TypeScript monorepo, and the dependency rule between them.
    - [Data and ledger model](/docs/reference/data-model): The four stores, the order they are written in, what each record holds and which view hides which field.
    - [WebSocket protocol](/docs/reference/websocket-protocol): Every frame a client may send, every frame the room sends, the sequence numbers and the close codes.
    - [API reference](/docs/reference/api-reference): The HTTP API of the GAVEL host as an OpenAPI 3.1 document, with authentication, errors, rate limits and the WebSocket note.
    - [Saga states and events](/docs/reference/saga-states): Every state and every legal move of the settlement saga, from the transition table in the code.
    - [Event catalogue](/docs/reference/events): The event names of the auction engine.
    - [Configuration](/docs/reference/configuration): The settings of the server, by name. Values never appear here.
    - [Decisions](/docs/reference/decisions): Where the design decisions are recorded.
    - [Glossary](/docs/reference/glossary): Every term used across these docs, with a short definition and the pages that use it.
    - [Keyboard shortcuts](/docs/reference/keyboard-shortcuts): Every keyboard shortcut on this site, including the diagram controls, and how to use the site without a mouse.