Start here

Most of this guide reads like a manual for a 109-bot system we own end to end. That describes your first month of code; it does not describe the product. Somebody else's bot is the thing that trades. Our bots exist to constrain it, inform it, and explain it — which is why user code is sandboxed, why guardrails are a chain rather than a class, and why an LLM response can never become an order on its own.

• The platform never holds user funds. Keys stay in the user's wallet. No omnibus account, no platform signer.
• A user bot never reaches the venue directly. It produces a proposal. Exactly one component signs, and it is ours.
• Guardrails cannot be configured away. Users tune thresholds inside bounds we set. They cannot remove or reorder the chain.
• AI never holds Trade authority. Model output is advisory and enters the same RiskGate as any other intent.

A high-fidelity re-skin of the eight live operator pages (Dashboard, Strategies, Risks, Bots, Decisions, Orders, Portfolios, Wallets) plus a new Pipeline page, showing exactly how the four-state promotion ladder, reason codes, envelope viewer, and V2-only rails surface to the operator. Each page is annotated with what changes vs. today.

Each step is one reviewable PR. Do not skip ahead. Do not start a strategy PR before the rails it depends on are merged. PRs 1–5 are the shared rails and are largely shipped. PRs 6–8 are what turn those rails into the actual product — they are the ones currently missing, and they are the reason the earlier five exist.

1. PR 1 — Contracts. Land MarketSnapshot, OrderBookSnapshot, OrderIntent, ReportEnvelope, and the ReasonCode registry as TypeScript types in packages/contracts. No bot code yet. See typed schemas →
2. PR 2 — First risk bot. Implement risk.killswitch against the contracts from PR 1. KillSwitch is the smallest, most important bot. Use the Risk template. Add a fixtures/risk.killswitch/{normal,warning,hard,failure}.json pack. See KillSwitch spec →
3. PR 3 — Fixture pack format. Land the four-file fixture-pack convention used by verify.js. Document it in Test pack. From this PR forward, every bot PR ships its fixtures in the same shape.
4. PR 4 — Reporting envelope. Wire ReportEnvelope into the runner so every decide() emit lands a structured event. Free-text console.log is forbidden after this PR. See envelope spec →
5. PR 5 — Demo wiring. Add the bot to wired_bots.json and to the synthetic browser demo. The synthetic feed is the only feed; production data does not exist yet. Open the demo →
6. PR 6 — RiskGate, as the single write path. Collapse every route to the venue into one function that no other code can bypass. Move the guardrail chain behind it in a fixed order, make the hard guardrails non-disableable in config, and make the exposure reserve atomic over filled + pending + partial. Done when a grep for venue-client imports outside the gate returns nothing, and a test that tries to submit around the gate fails to compile. RiskGate standard →
7. PR 7 — rules.yaml parser and the user sandbox. Land the Tier-1 schema, the bounds check that clamps user risk values to the platform floor (loudly, never silently), and signal-name resolution against the registry at save time. Then the isolate with its CPU, memory, and rate budgets, and the strike-to-quarantine path. Done when a user bot can be authored, backtested, shadowed, and paused without any of its code holding a key, a client, or a socket. User-bot standard →
8. PR 8 — AI suggestion envelope. Land TradeSuggestion with mandatory evidence and registry-validated market ids, and route accepted suggestions through the same RiskGate as any bot proposal. Start with surface C (monitoring) — it is read-only, it is the highest-value surface for users, and it cannot lose money if it is wrong. Done when there is no code path from a model response to a signature. AI-assist standard →