> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geckovision.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Recorded mode ($0)

> One code path, two modes. Recorded mode synthesizes responses from the spec so you can prove the comprehension offline, for free, before going live.

Gecko runs **one code path in two modes**. `recorded` and `live` differ *only at
the transport edge* — same discovery, same tool selection, same request building. The
only difference is where the response comes from.

| Mode       | Network | Cost        | Response source                                  |
| ---------- | ------- | ----------- | ------------------------------------------------ |
| `recorded` | none    | \$0         | synthesized from the operation's response schema |
| `live`     | yes     | per the API | the real upstream API                            |

## Why recorded mode exists

The first deliverable for any wire integration is a **free local simulation that can
falsify it offline**. Live smoke is the final check, never the primary debugger. If
the agent picks the wrong endpoint or builds a malformed request, recorded mode catches
it before a single network call — or a single cent — is spent.

<Note>
  Recorded mode proves the agent **selected the right call and built a well-formed
  request**. It does not prove the upstream returns that exact data — for that, run
  `live`. Recorded responses are schema-shaped samples, not real data.
</Note>

## How the sample is built

For each operation, Gecko finds the success response schema (`200` / `201` /
`default`, JSON content) and synthesizes a minimal valid instance from it. The
generator is **deterministic** — the same schema always yields the same sample — and
walks the schema sensibly:

* honors `example`, then `default`, then the first `enum` value
* follows `anyOf` / `oneOf` (first branch) and merges `allOf`
* builds objects from `properties`, arrays from `items`
* emits typed placeholders for primitives (e.g. an ISO timestamp for a
  `date-time` string), with a bounded recursion depth

This is what powers the `$0` demo: many real specs ship almost no response examples, so
to demo and validate without live calls, Gecko synthesizes from the schema.

## Running it

```bash theme={null}
uv run python -m surfcall.demo      # E2E recorded demo, $0
```

Or programmatically:

```python theme={null}
result = client.call(tool_name, args, mode="recorded")
# {
#   "status": 200,
#   "request": "https://.../api/odds/snapshot/123",
#   "method": "GET",
#   "data": { ... schema-shaped sample ... },
#   "mode": "recorded"
# }
```

Switching to live is a one-word change once you have a [session](/access-and-auth):

```python theme={null}
result = client.call(tool_name, args, mode="live")
```

Because the path is identical, a green recorded run is a strong signal the live call
will be well-formed too — the remaining unknowns are purely network and credentials.