> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/contributing.md).

# Contributing

## Setup

```bash
bun install
bun run dev        # http://localhost:8080
```

See [Quickstart](/bubblegum-reality-docs/getting-started/quickstart.md) and [Environment](/bubblegum-reality-docs/getting-started/environment.md).

## Before you open a PR

```bash
bun run test
bun run lint
bun run build
```

All three must pass. Read output in full — a `0` exit code with `Error` text in the output is a failed check.

## Non-negotiable invariants

These are the rules a reviewer will reject a PR over, because breaking them produces a wrong number or a leaked secret rather than a visible crash.

1. **No mock or fallback data.** A failed upstream renders degraded with a reason. Never substitute a plausible value.
2. **No float math on token amounts.** Base-unit `bigint` or `Decimal` only, through `src/lib/money.ts`.
3. **No hardcoded colors.** Semantic tokens from `src/styles.css` only — never `text-white`, `bg-black`, or `bg-[#…]`.
4. **No unlimited approvals.** Exact amount, to the quote's `issues.allowance.spender`.
5. **Secrets stay server-side.** Read `process.env` inside `.handler()`. Never `VITE_`-prefix a secret.
6. **`*.functions.ts` stay thin.** Imports, erased types, exported server-function declarations. Nothing else at module scope.
7. **Validate every server input** with Zod, including the chain pin and token allowlist.
8. **Fail closed** on eligibility, allowance reads, and status determination.
9. **`null`, not `0`,** for undefined metrics. `0 bps` is a claim; `—` is not.
10. **Never edit `src/routeTree.gen.ts`.**

## Adding a live surface

Every live component needs loading, empty, stale, offline, upstream-error, retry, and last-updated states. Use TanStack Query for caching and dedup. Dialogs need focus management; controls need labels; motion respects `prefers-reduced-motion`.

## Adding a route

Create the file under `src/routes` before linking to it. Give it a `head()` with a unique title, description, `og:title`, and `og:description`. Parent and pathless layout routes must render `<Outlet />`.

## Adding a server function

Put the Zod-validated wrapper in a `*.functions.ts` module and the logic in a `*.server.ts` helper. Add a rate limit for anything that spends an upstream key. Sanitize errors before returning them, and document the function in [Server Functions](/bubblegum-reality-docs/reference/server-functions.md).

## Tests

Pure logic belongs in `src/lib` with a matching test in `src/lib/__tests__`. Anything touching `process.env` must set and restore it inside the test.

## Commits and docs

Small, focused commits with imperative subjects. Update the affected docs page in the same PR — this documentation is GitBook-synced from `docs/`, so a stale page ships as published truth.

## Compliance-adjacent changes

Changes to the eligibility gate, restricted regions, risk disclosures, or the independence notice require explicit review. Do not weaken a gate to make a flow smoother.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/contributing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.