# 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. - [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. - Roadmap and limits - [Roadmap](/docs/roadmap): What happens next, and what the next days of the G3 probe decide. - [Limits, stated plainly](/docs/roadmap/limits): The honest list of what is not done and why. - 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): Honest answers about voice accuracy, gate G3, the fake PayPal, production readiness 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): Datasets prepared for Hugging Face. Prepared, not yet published. - [Data engineering](/docs/judges/data-engineering): How the open datasets are built, validated, versioned and verified. Prepared, not yet published. - [Demo script](/docs/judges/demo-script): The three-minute video, shot by shot, with the on-screen label and the truth behind each shot. - 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. - [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 Pages. - [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 18 item checklist and where it stands: all eight P0 items pass, three lower items are still open. - [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. - [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): Terms used across these docs. - [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.