# Integrating with a coding agent

Most R3CKON integrations are now wired in by a coding agent (Claude Code,
Cursor, Codex, or similar) rather than typed by hand. This page is written
for that arrangement: it tells you, the human, exactly which steps only
you can do, and it gives your agent everything else in one block.

Nothing here requires you to be technical. If you can create an account
and paste a key into an environment variable, your agent can do the rest.

## The three steps only a human can do

1. **Create the account.** Sign in at [r3ckon.com/login](/login) with your
   email. There is no password; a magic link signs you in.
2. **Copy your API key.** Your admin key (`aiok_admin_…`) is revealed once
   at signup. For production code, create an ingest key (`aiok_ingest_…`)
   in the console instead: it can push usage but cannot read your account
   or manage anything.
3. **Hand the key to your codebase safely.** Put it in your deployment's
   environment as `R3CKON_KEY`. Never paste a key into the chat with your
   agent, never let it be committed, and never put it in client-side code.

Everything else is the agent's job.

## The instruction block

Paste this to your agent, in the repository you want wired up:

```text
Integrate R3CKON usage reporting into this codebase.

1. Read https://r3ckon.com/llms-full.txt (the complete documentation)
   before writing any code.
2. Pick the ingestion path using the decision tree at
   https://r3ckon.com/md/agents. Tell me which path you chose and why
   before implementing it.
3. The API key lives in the R3CKON_KEY environment variable. I will set
   it myself: tell me where to set it for this deployment, then treat it
   as opaque. Never print it, log it, or commit it.
4. Implement the path. Reporting must never block or break my AI calls:
   a failed report is dropped, never retried in the request path, and
   never thrown.
5. Verify end to end: send one real usage event (use --dry-run first
   where available), then confirm it landed by calling
   GET https://r3ckon.com/api/admin/overview with the admin key I run
   manually, or by asking me to check the console at r3ckon.com.
6. If you generate any user-facing sustainability copy for this product,
   follow https://r3ckon.com/md/claims exactly. Never write neutrality
   language (neutral-style, net-style, or zero-style status claims, or
   "100% offset"), never use "offset" as a verb, and always present
   estimates as estimates with their range.
```

## The decision tree your agent will use

- **The codebase calls a provider SDK directly** (OpenAI, Anthropic, or
  an OpenAI-compatible gateway such as OpenRouter): use
  [`@r3ckon/sdk`](https://www.npmjs.com/package/@r3ckon/sdk). One
  install, one wrap of the existing client. Most accurate path: exact
  cache and reasoning token counts.
- **The stack already emits OpenTelemetry GenAI metrics**: point an OTLP
  exporter at `/api/v1/otlp/v1/metrics`. No code changes.
- **Usage happens through a provider account, not this codebase** (or the
  history matters): run the [anthropic.mjs](/sync/anthropic.mjs) or
  [openai.mjs](/sync/openai.mjs) sync script on a schedule. The provider
  key never leaves your machine; only token counts travel.
- **Google Cloud (Vertex)**: a managed connection with a service account
  scoped to `roles/monitoring.viewer`, set up in the console.
- **A custom pipeline or internal gateway**: POST daily aggregates to the
  [metering API](/docs/metering-api) directly.

Paths combine; each source appears separately in the ledger. Full
trade-offs are on [Connecting usage](/docs/connecting-usage).

## How the agent verifies its work

A finished integration demonstrates all three:

1. **A dry run**: the sync scripts accept `--dry-run` and print the exact
   payload without sending. For SDK integrations, one test call with the
   reporter's debug logging on.
2. **A real event lands**: `GET /api/admin/overview` (admin key) returns
   the ledger as JSON; the new source and its token counts appear there,
   and estimation runs as usage arrives, so figures appear without
   waiting for a close.
3. **Failure is safe**: kill the network or unset `R3CKON_KEY` and
   confirm the application's AI calls still succeed. Reporting is
   fire-and-forget by design; an integration that can break your product
   is wrong even if it reports perfectly.

## Rules for generated copy

Agents wiring in a sustainability ledger are often asked, in the same
session, to write the sustainability page. The [claims playbook](/docs/claims)
is the contract for that copy, and the same rules are enforced by the
platform on certificate-bearing surfaces. The short form your agent
should honor:

- Say what was done, never what it cancels. Activity claims only.
- No neutrality vocabulary: no neutral-style, net-style, or zero-style
  status claims, and no completeness claims such as "100% offset".
- "Offset" is never a verb, and never describes water or renewable
  energy instruments.
- Estimates are always presented as estimates, with their 90 percent
  range and methodology version.
- Retirement statements name the real instrument: project, registry
  reference, vintage, supplier.

## Connect the MCP server

Once wired in, agents can also read the live ledger over MCP: estimates
with their ranges, connection health, retirements, certificates, and the
exact approved claim sentences (`get_claim_language`), filled with the
account's real figures. The server is read-only by design: no tool can
push usage or change the account, which is why the read key is the only
key that belongs in a client config.

```bash
claude mcp add --transport http r3ckon https://r3ckon.com/api/mcp \
  --header "Authorization: Bearer $R3CKON_READ_KEY"
```

Generate a read key (`aiok_read_…`) in the console. Any MCP client works
with the equivalent config: URL `https://r3ckon.com/api/mcp`, header
`Authorization: Bearer <key>`.

## Install as a skill

If your agent supports the skills format, the whole procedure above is
installable as a skill it will load whenever R3CKON work comes up:

```bash
npx skills add TahosaSystems/agent-skills
```

The skill teaches the same decision tree, verification loop, and copy
rules, and pins the documentation URLs, so a fresh session does not need
this page pasted in.