# rails Full Documentation

> Concatenated Markdown bundle for agent retrieval.

# Overview

Source: ../docs/overview.md
URL: https://docs.rails.sh/
Markdown: https://docs.rails.sh/markdown/overview.md

# Overview

Status: current. Orientation page — see the linked pages for verified detail.

## What rails is

rails is agentic-first incentives infrastructure. Every customer signal comes
in as an event, rules resolve what happens next, and the resulting points,
tiers, and campaigns are issued through one backend. It's the same event
backbone whether the person driving it is an operator talking to the rails
agent or a developer calling the API directly.

## The Two Ways To Work

**Converse with the agent.** Operators build and change programs, rules, and
campaigns by talking to the rails agent instead of hand-filling forms. Ask it
to design a program, add an earn rule, launch a campaign, or explain why a
member's balance looks the way it does — it proposes the change, shows you
what it will do, and waits for approval before anything mutates. See the
[Agent Guide](./agent-guide.md).

**Integrate via API, CLI, or SDK.** Developers connect an existing app to
rails with server-side API calls, the `loyaltyrails` CLI, or the React SDK
components — sending events, reading balances, and wiring rules-driven
rewards into checkout, onboarding, or any other flow. See the
[Quick Start](./quick-start.md), [Authentication](./authentication.md), and
[CLI](./cli.md).

Both paths operate on the same programs, rules, and events — a program the
agent creates is the program your integration sends events to, and a rule
your API key exercises is the rule an operator can ask the agent to explain
or adjust.

## Platform Map

| Concept | What it does | Learn more |
|---------|---------------|------------|
| Programs | The loyalty program shell — name, symbol, issuer, chain, and lifecycle (pause/resume/deprecate) that everything else is scoped to | [Programs API](./api/programs.md) |
| Members | Identity resolution from your own external IDs, balances, wallet identifiers, and member lifecycle | [Members API](./api/members.md) |
| Events | Ingestion of behavioral signals (`transaction.completed` and others) with idempotency and async processing | [Events API](./api/events.md) |
| Rules | The engine that evaluates events against program conditions and resolves earn, tier, and outcome decisions — with simulation before you commit a change | [Rules API](./api/rules.md) |
| Campaigns | Audience targeting, scheduling, and budget for time-boxed promotions layered on top of programs | [Campaigns API](./api/campaigns.md) |
| Gamification | Experiences, mechanics, sessions, and prize pools — spin wheels, quizzes, and onboarding challenges connected to rewards and campaigns | [Gamification](./gamification.md) |
| Stablecoin rewards | Reward assets and settlement as a first-class outcome alongside points — **coming soon**, not available in production today | [Stablecoin Rewards](./stablecoin-rewards.md) |

## Where To Go Next

- [Quick Start](./quick-start.md) — the current onboarding path: sign up onto
  the free Developer tier, create a program, mint an API key, send an event,
  and read a member's balance, with a CLI alternative for the same steps.
- [Authentication](./authentication.md) — every credential surface (integration
  API keys, operator sessions, end-user JWTs, webhook signatures) and which
  route family expects which one.
- [Agent Guide](./agent-guide.md) — what the rails agent can do on its own
  versus what it needs approval for, and how that approval flow works.
- [CLI](./cli.md) — the full `loyaltyrails` command surface for auth, program
  setup, rules, events, members, games, and generated integration recipes.

---

# Quick Start

Source: ../docs/quick-start.md
URL: https://docs.rails.sh/quick-start
Markdown: https://docs.rails.sh/markdown/quick-start.md

# Quick Start

Status: current. This walks through today's real onboarding path — sign up,
create a program, mint an API key, send an event, and read a member's
balance — with every request verified against the current backend. One
program, one member, and one event carry through every example below.

## 1. Sign Up

Register at [`https://app.loyaltyrails.com/register`](https://app.loyaltyrails.com/register).
Registration lands your organization on the free **Developer** tier:

- 250 active members a month
- 1 loyalty program
- Production API keys and CLI
- The rails agent, included
- Unlimited seats
- No card required, no time limit

Developer has no trial expiry — it works on every surface in this guide,
subject to its active-member cap. When you outgrow the cap or need more than
one program, see [rails.sh/pricing](https://rails.sh/pricing) for the paid
tiers.

## 2. Create A Program

From the dashboard, go to Programs and select **Create your first program**
(`https://app.loyaltyrails.com/admin/programs/new`). Give it a name, symbol,
and issuer:

```json
{
  "name": "Acme Rewards",
  "symbol": "ACME",
  "issuer": "Acme Inc."
}
```

The response — visible on the program's detail page — includes the program's
ID:

```json
{
  "id": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "name": "Acme Rewards",
  "symbol": "ACME",
  "issuer": "Acme Inc.",
  "chain": "base",
  "contractAddress": null,
  "reserveRatio": 8000,
  "reserveStatus": {
    "currentReserve": 0,
    "requiredReserve": 0,
    "adequate": true
  }
}
```

Copy that program ID — every call below is scoped to it. This is also
something you can hand to the rails agent directly ("create a loyalty
program called Acme Rewards") instead of using the form; see the
[Agent Guide](./agent-guide.md).

Full field reference and lifecycle (pause/resume/deprecate) are in the
[Programs API](./api/programs.md).

## 3. Mint An API Key

Server-side integrations authenticate with an integration API key in the
`X-API-Key` header — never `Authorization: Bearer`. Mint one from the
dashboard (Settings → API Keys), or call the same endpoint directly with an
authenticated session:

```http
POST /admin/v1/api-keys
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "name": "storefront-prod",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "scopes": ["read", "write"],
  "environment": "live"
}
```

The response includes the raw key exactly once — store it server-side (for
example as `LOYALTYRAILS_API_KEY`), never in browser code or committed
config:

```json
{
  "apiKey": { "id": "...", "keyPrefix": "lr_live_...", "scopes": ["read", "write"] },
  "rawKey": "lr_live_...",
  "warning": "Store this key securely. It will not be shown again!"
}
```

Full auth model, scopes, and every credential surface are in
[Authentication](./authentication.md).

## 4. Send Your First Event

Send a `transaction.completed` event for a member, identified by your own
customer ID (`externalId` + `externalIdType`) — rails creates the member on
first sight:

```bash
curl -X POST "https://api.loyaltyrails.com/internal/v1/programs/0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd/events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lr_live_..." \
  -d '{
    "eventType": "transaction.completed",
    "idempotencyKey": "checkout_order_100045",
    "externalId": "customer_123",
    "externalIdType": "customer_id",
    "occurredAt": "2026-05-02T15:04:05Z",
    "payload": {
      "amount": 2500,
      "transactionAmountMinor": 2500,
      "currency": "USD",
      "channel": "online",
      "store_id": "web"
    }
  }'
```

A `202` means the event was accepted for asynchronous processing — not that
points have been awarded yet:

```json
{
  "eventId": "0de0ff5b-4f44-4e3f-9a27-dbeae4cb9e52",
  "status": "pending",
  "statusUrl": "/internal/v1/programs/0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd/events/0de0ff5b-4f44-4e3f-9a27-dbeae4cb9e52/status"
}
```

Use a stable, merchant-owned `idempotencyKey` — an order ID, checkout ID, or
webhook delivery ID — so retries don't double-count. See
[Events API](./api/events.md) for batch ingestion, status polling, and the
full idempotency contract.

## 5. Read The Member's Balance

The worker processes the event asynchronously, resolving or creating the
member and evaluating your program's rules. Look up the balance by the same
external ID you sent the event with:

```bash
curl -X POST "https://api.loyaltyrails.com/internal/v1/programs/0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd/members/balance/lookup" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lr_live_..." \
  -d '{
    "externalId": "customer_123",
    "externalIdType": "customer_id"
  }'
```

```json
{
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "balance": 1250,
  "settledBalance": 1000,
  "pendingSettlement": 250,
  "totalEarned": 1750,
  "totalRedeemed": 500
}
```

If the member has no rules-driven earn yet, this returns zero balances once
the member mapping exists — poll the event's `statusUrl` from step 4 to
confirm processing finished before assuming a rule didn't fire. Full member
shapes, lifecycle, and the browser-safe host-route pattern (never call this
from a browser directly) are in [Members API](./api/members.md).

For your own signed-in end users to read their own balance client-side, mint
a short-lived member JWT server-side and use `/public/v1/members/me/*` — see
[Authentication § End-User Access](./authentication.md#end-user-access).

## 6. Or Do It All With The CLI

The `loyaltyrails` CLI wraps steps 2–5 for both operator setup and
integration smoke tests. Authenticate with an operator CLI token (minted
from an active dashboard session via `POST /admin/v1/auth/cli-tokens`) to
create the program:

```bash
loyaltyrails auth login --operator-token lr_cli_... --api-url https://api.loyaltyrails.com
loyaltyrails program create \
  --name "Acme Rewards" \
  --symbol ACME \
  --issuer "Acme Inc." \
  --reserve-ratio 8000
```

Then switch to an integration API-key profile — the one from step 3 — to
smoke-test ingestion and balance reads:

```bash
loyaltyrails auth login --api-key lr_live_... --api-url https://api.loyaltyrails.com
loyaltyrails init --program 0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd --external-id-type customer_id --identity-strategy custom

loyaltyrails events send \
  --type transaction.completed \
  --external-id customer_123 \
  --external-id-type customer_id \
  --idempotency-key checkout_order_100045 \
  --payload '{"amount":2500,"currency":"USD"}'

loyaltyrails members balance \
  --external-id customer_123 \
  --external-id-type customer_id

loyaltyrails doctor
```

`loyaltyrails init` writes non-secret project metadata
(`.loyaltyrails/config.json`, `.loyaltyrails/manifest.json`) and unlocks the
`add` recipes (`award-route`, `balance-widget`, and others) that generate
server-side integration code for an existing app. See the
[CLI Guide](./cli.md) for the full command set, including rule, experience,
and campaign management, and the Shopify Hydrogen integration recipe.

## Next Steps

- [Authentication](./authentication.md) — every credential surface, header,
  and the tier/trial gating that applies to mutating requests.
- [Events API](./api/events.md) and [Members API](./api/members.md) — full
  request/response shapes, idempotency, and error handling.
- [Agent Guide](./agent-guide.md) — driving program, rule, and campaign
  setup conversationally instead of by hand.
- [CLI Guide](./cli.md) — the full `loyaltyrails` command surface, including
  generated integration recipes for existing apps.

---

# Authentication

Source: ../docs/authentication.md
URL: https://docs.rails.sh/authentication
Markdown: https://docs.rails.sh/markdown/authentication.md

# Authentication

Source-derived status: verified against `backend/src/api/mod.rs` and the
`api_key`/`agent_principal`/`admin_permissions`/`trial_gate` middleware —
every route, header, and mount below reflects the current backend.

rails has separate authentication surfaces for integrations, operators, end
users, and webhooks. Pick the credential that matches the route family; do
not reuse one credential type across surfaces.

## Agent Summary

Use this when asking an agent to add or review rails auth code:

```text
Use program-scoped, non-admin `X-API-Key` credentials only on server-side
`/internal/v1/*` integration routes — never `Authorization: Bearer` there.
Use `/admin/v1/*` only with a browser session cookie or an
`Authorization: Bearer lr_cli_...` operator CLI token. Use
`/public/v1/members/me/*` with a short-lived member JWT
(`Authorization: Bearer`) minted server-side via `/api/v1/member-tokens/issue`.
Verify webhook signatures before reading vendor or Stripe payloads. Never put
raw API keys, operator tokens, or member JWTs in browser code, generated
client bundles, or committed config.
```

## Surface Map

| Surface | Header / mechanism | Primary caller |
|---------|---------------------|----------------|
| `/internal/v1/*` | `X-API-Key: lr_live_...` / `lr_test_...` | Server-to-server integrations (ingest, mint, award, members) |
| `/admin/v1/*` | Browser session cookie (`lr_session`), or `Authorization: Bearer lr_cli_...` operator CLI token | Admin dashboard and operator CLI |
| `/public/v1/members/me/*` | `Authorization: Bearer <member-jwt>` | Browser SDK — the current end-user surface |
| `/alp/v1/*` | `Authorization: Bearer <wallet-jwt>` | Legacy end-user/wallet surface (deprecated — see below) |
| `/alp/v1/integrations/:id/webhook` | Per-connection webhook secret, verified in the handler | Vendor webhook delivery (e.g. Shopify) |
| `/webhooks/stripe` | `Stripe-Signature` header, verified in the handler | Stripe billing events |
| `/internal/v1/admin/*` | `X-API-Key` with `admin` scope | Deprecated machine-to-machine mirror of `/admin/v1/*` |

`/internal/v1/admin/*` and `/admin/v1/*` are two mounts of the same handler
set with different auth regimes — see [Deprecated: `/internal/v1/admin/*`](#deprecated-internalv1admin)
below. A request that presents both a session cookie and `X-API-Key` is
rejected outright on either mount.

## Integration API Keys

Server-side integrations call `/internal/v1/*` with a program-scoped,
non-admin API key in `X-API-Key`. This is never a Bearer token:

```bash
curl https://api.loyaltyrails.com/internal/v1/auth/introspect \
  -H "X-API-Key: lr_live_..."
```

Introspection returns the key's scopes, reach (`program_scoped` or
`all_program`), and the programs it can access — useful for confirming a key
before wiring it into a new integration.

Keys are minted from the dashboard (Settings → API Keys) or by an
authenticated operator calling `POST /admin/v1/api-keys`:

```json
{
  "name": "storefront-prod",
  "programId": "b6c1...",
  "scopes": ["read", "write"],
  "environment": "live"
}
```

The response includes the raw key exactly once — store it in a server-side
environment variable such as `LOYALTYRAILS_API_KEY`. Project metadata files
such as `.loyaltyrails/config.json` and `.loyaltyrails/manifest.json` should
contain only non-secret metadata.

Server-to-server callers also use `X-API-Key` to mint short-lived member
JWTs (`POST /api/v1/member-tokens/issue`) — see
[End-User Access](#end-user-access) below.

## Operator Access

Admin/control-plane routes live under `/admin/v1/*` and accept either:

- A browser session cookie (`lr_session`), set by the standard login flow
  under `/auth/login`, `/auth/register`, and MFA verification
  (`/auth/mfa/verify`); or
- An `Authorization: Bearer lr_cli_...` operator CLI token, minted from an
  active session via `POST /admin/v1/auth/cli-tokens` for CLI-driven setup
  and automation.

Both credential types carry the same organization-scoped permission set —
`/admin/v1/*` routes enforce a permission check (e.g. `programs:write`,
`billing:manage`) independent of which credential presented it.

Account-security routes — session listing/revocation, TOTP enrollment,
backup codes, passkey registration, password/email change, and step-up
re-authentication, all under `/admin/v1/auth/*` and `/auth/*` — accept only
the session cookie. An operator CLI token cannot manage MFA, passkeys, or
another session; keep those in the browser.

Do not write operator CLI tokens into generated host-app env files — they
are for setup and management commands (programs, API keys, rules,
experiences, campaigns), not for storefront traffic.

## End-User Access

`/public/v1/members/me/*` is the current browser-facing member surface —
balance, tier, active experiences, redemptions, and consent/receipt reads
for the signed-in member. It accepts only a short-lived member JWT in
`Authorization: Bearer`; it never accepts `X-API-Key` or a session cookie.

Your server mints that JWT on the member's behalf, using its own API key:

```bash
curl https://api.loyaltyrails.com/api/v1/member-tokens/issue \
  -H "X-API-Key: lr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"externalId": "member-42", "externalIdType": "your_user_id"}'
```

The response is `{ "token": "...", "exp": ..., "jti": "..." }`. Tokens are
short-lived by design (minutes, not hours); refresh with
`POST /api/v1/member-tokens/refresh` before expiry rather than minting a new
token on every page load. Never let a member's browser see your API key —
only the mint/refresh calls use it, and those run server-side.

`/alp/v1/*` (`/alp/v1/programs`, `/alp/v1/programs/:id`, `/alp/v1/balance`,
`/alp/v1/redeem`) is an older end-user surface authenticated by a separate
wallet-context JWT. It predates the member-token model above and uses a
different signing secret. New integrations should use
`/public/v1/members/me/*`; treat `/alp/v1/*` as legacy.

## Agent Auth

The rails conversational agent acts on an operator's behalf: the
agent service authenticates to the backend with a shared HMAC secret
(`X-Agent-Shared-Secret`) plus acting-user headers that identify the human
whose session the agent is proxying. This path exists only between the
agent service and the backend — it is not a credential type available to
integrators, and there is no external how-to for it.

## Tier & Trial Gating

Every mutating request against `/admin/v1/*`, `/internal/v1/*`, and
`/internal/v1/admin/*` is checked against the calling organization's
subscription tier. An org on an expired trial (or in a billing-lapsed
read-only state) gets mutations rejected with `402 Payment Required`; reads
still work. The free **Developer** tier has no such expiry — it works for
every surface documented on this page, subject to its active-member cap. See
[rails.sh/pricing](https://rails.sh/pricing) for tier limits and upgrade
paths.

## Webhooks

Both webhook receivers verify a signature in the handler before trusting the
request body:

- `/alp/v1/integrations/:id/webhook` checks the per-connection secret
  configured for that vendor integration (e.g. a Shopify webhook secret).
  An unconfigured connection fails closed rather than accepting an unsigned
  payload.
- `/webhooks/stripe` checks the `Stripe-Signature` header against your
  configured Stripe webhook signing secret.

Keep webhook secrets server-side (for example `SHOPIFY_WEBHOOK_SECRET` in a
generated integration). Fail closed on missing, invalid, stale, or
mismatched signatures — do not accept unsigned webhooks outside a
local-only fixture explicitly marked as such.

## Deprecated: `/internal/v1/admin/*`

`/internal/v1/admin/*` mirrors every route under `/admin/v1/*` but is
authenticated with `X-API-Key` (requiring explicit `admin` scope) instead of
a session or operator token. It exists only for machine-to-machine callers
migrating off the API-key admin model and is deprecated — do not build new
integrations against it.

New control-plane work should use `/admin/v1/*` with a browser session or an
operator CLI token, or a program-scoped API key against `/internal/v1/*`
for ordinary integration traffic.

## Security Do And Do Not

Do:

- Use the narrowest credential for the route family.
- Keep `LOYALTYRAILS_API_KEY`, operator CLI tokens, and webhook secrets
  server-side.
- Use program-scoped, non-admin keys for generated app integrations.
- Rotate or revoke credentials that appear in logs, screenshots, commits, or
  browser bundles.
- Refresh member JWTs before expiry instead of widening their TTL.

Do not:

- Send `X-API-Key` from browser-executed code.
- Use an operator CLI token for generated storefront or app integration
  routes.
- Use an integration key for `/admin/v1/*` control-plane operations.
- Build new integrations against `/internal/v1/admin/*`.
- Trust client-submitted member IDs for awards, balance lookup, or game
  sessions.
- Log raw credentials, webhook signatures, JWTs, or session cookies.

---

# Programs API

Source: ../docs/api/programs.md
URL: https://docs.rails.sh/programs-api
Markdown: https://docs.rails.sh/markdown/programs-api.md

# Programs API

Source-derived status: program creation, listing, detail, and lifecycle
(pause / resume / deprecate) are implemented, dual-mounted on `/admin/v1`
(session/operator, primary) and the deprecated `/internal/v1/admin`
API-key mirror. A separate, narrower `/internal/v1/programs` mount exists
for machine-to-machine callers (create + reserve deposit only). Program
reward-mode settings and tier ladders are also implemented, admin-only.

This page covers the merchant-facing program management surface: creating
a program, reading its status, pausing/resuming/deprecating it, adjusting
its reserve ratio, and its reward-mode and tier-ladder configuration. For
event ingestion and member management see [Events API](./events.md) and
[Members API](./members.md).

## Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `POST` | `/admin/v1/programs` | Implemented | Browser session or operator token with `programs:create`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/programs` | Implemented | Browser session or operator token with `programs:read`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/programs/{programId}/status` | Implemented | Browser session or operator token with `programs:read`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/programs/{programId}/pause` | Implemented | Browser session or operator token with `programs:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/programs/{programId}/resume` | Implemented | Browser session or operator token with `programs:update`; deprecated API-key mirror also works |
| `PATCH` | `/admin/v1/programs/{programId}/reserve-ratio` | Implemented | Browser session or operator token with `programs:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/programs/{programId}/deprecate` | Implemented | Browser session or operator token with `programs:archive`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/programs/{programId}/contract` | Implemented, dev/test only | Browser session or operator token with `programs:update`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/programs/{programId}/reward-settings` | Implemented | Browser session or operator token with `programs:read`; deprecated API-key mirror also works |
| `PATCH` | `/admin/v1/programs/{programId}/reward-settings` | Implemented | Browser session or operator token with `stablecoin_reward_settings:manage`; **not** available on the deprecated API-key mirror |
| `GET` | `/admin/v1/programs/{programId}/tier-ladder` | Implemented | Browser session or operator token with `rules:read`; deprecated API-key mirror also works |
| `PUT` | `/admin/v1/programs/{programId}/tier-ladder` | Implemented | Browser session or operator token with `rules:update`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/programs/{programId}/tier-ladder/versions` | Implemented | Browser session or operator token with `rules:read`; deprecated API-key mirror also works |
| `POST` | `/internal/v1/programs` | Implemented | `X-API-Key` with `admin` scope, or agent-proxied |
| `POST` | `/internal/v1/programs/{id}/reserve` | Implemented | `X-API-Key` with `write` or `admin` scope, program-scoped |

Every `/admin/v1/programs...` route above is also mounted, deprecated,
under `/internal/v1/admin/...` (e.g. `/internal/v1/admin/programs`) for
machine-to-machine callers still on the legacy admin API-key path, using
an `admin`-scoped `X-API-Key` — with one exception: `PATCH
.../reward-settings` explicitly rejects any API-key caller regardless of
scope, on both mounts, so it can only be changed by a session or
operator-token caller.

There is also a legacy, JWT-authed pair of routes at `GET /alp/v1/programs`
and `GET /alp/v1/programs/{id}` (see [Legacy JWT Program Reads](#legacy-jwt-program-reads)
below) — it predates the admin program-management surface above and
returns a different response shape. Prefer `/admin/v1/programs` for new
integrations.

## Auth Model

Admin program routes use the admin auth stack: browser session cookies or
operator CLI tokens on `/admin/v1`, and a deprecated admin API-key mount
under `/internal/v1/admin`. Route permissions are feature permissions
(`programs:read`, `programs:create`, `programs:update`, `programs:archive`,
`rules:read`, `rules:update`, `stablecoin_reward_settings:manage`), not API-key
scopes — see the Route Summary table above for which permission each route
requires.

For the `/internal/v1/programs` M2M mount, a direct (non-agent-proxied)
`X-API-Key` must carry `admin` scope to create a program; the reserve-deposit
route requires `write` or `admin` scope scoped to that program. An
agent-proxied API key (one carrying an acting user/org) creates the program
in its acting organization instead of the legacy platform-default
organization — see [Program Ownership](#program-ownership) below.

Program routes are tenant-scoped: a session or operator token can only see
and mutate programs owned by its organization. Platform-scope (cross-org)
access requires an explicit `X-Org-Scope-Reason` header and is restricted to
the platform-admin account; it is audit-logged on every use.

## Program Ownership

```http
POST /admin/v1/programs
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "name": "Acme Rewards",
  "symbol": "ACME",
  "issuer": "Acme Inc.",
  "reserveRatio": 8000,
  "chainId": 8453
}
```

`reserveRatio` is basis points (0–10000; defaults to `8000` = 80% if
omitted) and `chainId` defaults to `8453` (Base mainnet) if omitted.
`contractAddress` is optional — set later via the contract-address route,
below. `name`, `symbol`, and `issuer` are required.

Response (`ProgramDto`):

```json
{
  "id": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "name": "Acme Rewards",
  "symbol": "ACME",
  "issuer": "Acme Inc.",
  "chain": "base",
  "contractAddress": null,
  "reserveRatio": 8000,
  "reserveStatus": {
    "currentReserve": 0,
    "requiredReserve": 0,
    "adequate": true
  }
}
```

Ownership rule (the create endpoint): a session-authed or
operator-token caller owns the new program in their own organization. A
direct `X-API-Key` caller (not agent-proxied) must carry `admin` scope and
the program is assigned to the platform-default organization — a legacy
behavior kept for backward compatibility, planned to be replaced by
DB-backed M2M keys in a later phase. An agent-proxied `X-API-Key` (one
carrying an acting user and organization) owns the program in that acting
organization instead.

Two additional guards apply before creation: a rate limit of 5 program
creations per hour per organization, and a subscription-tier quota
(`max_programs`) checked against the organization's current program count.
Both return `429`/quota errors — see [Errors](#errors).

## List And Get Program

```http
GET /admin/v1/programs
Cookie: <admin session>
```

Response (`ListProgramsResponse`) — scoped to the caller's organization
(or every organization, for an audited platform-scope call):

```json
{
  "programs": [
    {
      "id": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
      "name": "Acme Rewards",
      "symbol": "ACME",
      "issuer": "Acme Inc.",
      "status": "active",
      "chain": "Base",
      "totalSupply": 125000,
      "totalReserve": 100000,
      "createdAt": "2026-05-01T12:00:00Z"
    }
  ],
  "total": 1
}
```

```http
GET /admin/v1/programs/{programId}/status
Cookie: <admin session>
```

Response (`ProgramStatusResponse`) — richer than the list entry above,
including chain, supply, reserve health, contract deployment, and
timestamps:

```json
{
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "name": "Acme Rewards",
  "symbol": "ACME",
  "issuer": "Acme Inc.",
  "status": "active",
  "isOperational": true,
  "chain": { "chainId": 8453, "chainName": "Base" },
  "supply": { "totalSupply": 125000, "mintableAmount": 0 },
  "reserve": {
    "currentReserve": 100000,
    "requiredReserve": 100000,
    "excessReserve": 0,
    "reserveRatioBps": 8000,
    "reserveRatioPct": "80%",
    "isAdequate": true,
    "healthPct": "100.00%"
  },
  "contract": { "deployed": false },
  "timestamps": {
    "createdAt": "2026-05-01T12:00:00Z",
    "updatedAt": "2026-05-01T12:00:00Z"
  }
}
```

`contract.address` is omitted entirely when no contract is deployed yet;
it only appears once a contract address has been set.

`isOperational` is `true` only when the program is `active` **and** has a
deployed contract address. `mintableAmount` reflects how much more can be
minted before reserves become inadequate at the current ratio.

## Program Lifecycle (Pause / Resume / Deprecate)

```http
POST /admin/v1/programs/{programId}/pause
Cookie: <admin session>
Content-Type: application/json
```

```json
{ "reason": "Investigating a reserve discrepancy" }
```

```http
POST /admin/v1/programs/{programId}/resume
Cookie: <admin session>
```

```http
POST /admin/v1/programs/{programId}/deprecate
Cookie: <admin session>
```

Response (all three; `SimpleStatusResponse`):

```json
{
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "status": "paused",
  "message": "Program paused: Investigating a reserve discrepancy"
}
```

Status is one of `active`, `paused`, or `deprecated` (`ProgramStatus`).
Confirmed transitions, from the API's behavior:

- **Pause** (`active` → `paused`): rejected with `400` if the program is
  already `paused` or already `deprecated`. Requires a `reason` string in
  the request body (no length validation is applied server-side, unlike
  the member-suspend `reason` field).
- **Resume** (`paused` → `active`): rejected with `400` if the program is
  already `active`, already `deprecated`, or does not have adequate
  reserves for its configured ratio. No request body.
- **Deprecate** (`active` or `paused` → `deprecated`): rejected with `400`
  if the program is already `deprecated`. No request body, and **this
  transition cannot be undone** — there is no un-deprecate route. Unlike
  pause/resume, deprecate does not append a domain event to the event
  store; it only updates the read-model status directly.

## Reserve Ratio And Contract Address

```http
PATCH /admin/v1/programs/{programId}/reserve-ratio
Cookie: <admin session>
Content-Type: application/json
```

```json
{ "newRatioBps": 9000, "adjustedBy": "ops@acme.example" }
```

`newRatioBps` must be `0`–`10000`. Increasing the ratio is rejected with
`400` if current reserves would be inadequate under the new, higher
requirement. Response is the same `ProgramStatusResponse` shown above,
reflecting the new ratio.

```http
POST /admin/v1/programs/{programId}/contract
Cookie: <admin session>
Content-Type: application/json
```

```json
{ "contractAddress": "0x1234567890123456789012345678901234567890" }
```

Sets the on-chain contract address for a program that doesn't have one
yet (rejected with `400` if already set, or if the address isn't
`0x`-prefixed 40 hex characters). `txHash` is optional; a placeholder hash
is generated if omitted. This is a development/testing convenience for
exercising the award/redeem flow without an actual contract deployment —
it does not deploy anything. Response is the updated
`ProgramStatusResponse`.

## Reserve Deposit (M2M)

```http
POST /internal/v1/programs/{id}/reserve
X-API-Key: lr_test_...
Content-Type: application/json
```

```json
{ "amount": 50000, "depositor": "treasury-wallet" }
```

Response is the `ProgramDto` shape shown in
[Program Ownership](#program-ownership) above, with `reserveStatus`
reflecting the new total. Requires the API key to hold `write` or `admin`
scope for the specific program.

## Reward Settings

```http
GET /admin/v1/programs/{programId}/reward-settings
Cookie: <admin session>
```

```http
PATCH /admin/v1/programs/{programId}/reward-settings
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "rewardMode": "points_only"
}
```

Response (`ProgramRewardSettingsResponse`) when nothing has been
configured yet (`isPersisted: false`, defaults apply):

```json
{
  "organizationId": "b1f6...",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "rewardMode": "points_only",
  "defaultRewardAssetCode": null,
  "stablecoinDisplayLabel": null,
  "settlementAvailabilityPolicy": "not_available",
  "status": "active",
  "metadata": {},
  "defaultRewardAsset": null,
  "availableStablecoinAssets": [],
  "isPersisted": false,
  "createdAt": null,
  "updatedAt": null
}
```

`rewardMode` is `points_only` (default) or `stablecoin_primary`. Switching
to `stablecoin_primary` requires `defaultRewardAssetCode` to reference an
active, program-scoped stablecoin provider asset mapping, and
`settlementAvailabilityPolicy` must be `setup_required` or `testnet_only`
(never `not_available`) — the API validates both server-side and
returns `400` otherwise. Switching back to `points_only` clears all
stablecoin-related fields. This endpoint only manages the reward-mode
*setting*; it does not itself move value. See
[Stablecoin Rewards](../stablecoin-rewards.md) for the reward-asset and
settlement model this setting selects between.

## Tier Ladders

```http
GET /admin/v1/programs/{programId}/tier-ladder
Cookie: <admin session>
```

```http
PUT /admin/v1/programs/{programId}/tier-ladder
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "rungs": [
    { "slug": "bronze", "minBalance": 0, "multiplier": 1.0 },
    { "slug": "silver", "minBalance": 500, "multiplier": 1.25 },
    { "slug": "gold", "minBalance": 2000, "multiplier": 1.5 }
  ],
  "expirationDaysInactive": 180
}
```

`rungs` must be strictly ascending by `minBalance` (rejected with `400`
otherwise). `expirationDaysInactive` is optional (`1`–`3650`); when set it
describes an inactivity-based demotion policy that is **persisted but not
yet enforced** — no background job currently acts on it. `PUT` appends a
new version and marks it active; `GET .../tier-ladder/versions` lists the
full history. An agent-proxied `PUT` (a request carrying
`x-acting-user-id`) additionally requires a valid `X-Agent-Plan-Approval`
envelope covering the `tier_ladder.upsert` intent.

Response (`TierLadderResponse`):

```json
{
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "organizationId": "b1f6...",
  "version": 1,
  "status": "active",
  "rungs": [
    { "slug": "bronze", "minBalance": 0, "multiplier": 1.0 },
    { "slug": "silver", "minBalance": 500, "multiplier": 1.25 },
    { "slug": "gold", "minBalance": 2000, "multiplier": 1.5 }
  ],
  "expirationDaysInactive": 180,
  "createdBy": "operator@acme.example",
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-01T12:00:00Z"
}
```

`GET .../tier-ladder` returns `null` (not `404`) when no ladder has been
configured yet.

## Legacy JWT Program Reads

`GET /alp/v1/programs` and `GET /alp/v1/programs/{id}` are a separate,
legacy pair of routes authenticated with a generic wallet-scoped JWT
(`Authorization: Bearer`, decoded with the platform's `jwt_secret` — the
same legacy claims shape used by the out-of-scope wallet-balance route
documented in [Members API](./members.md#out-of-scope-here)). They return
the `ProgramDto` shape shown in [Program Ownership](#program-ownership)
above (5-minute Redis-cached), with an optional `?issuer=` filter on the
list route. They predate the admin program-management surface and are not
tenant-scoped the way `/admin/v1/programs` is. New integrations should use
`/admin/v1/programs` instead.

## Errors

| HTTP | Notes |
| --- | --- |
| `400` | Malformed JSON, validation failure (bad reserve ratio, invalid contract address, ordering error on tier rungs, invalid reward-mode combination), or a lifecycle no-op guard (pause-when-paused, resume-when-active, deprecate-when-deprecated) |
| `401` | Missing or invalid API key/session/operator token |
| `403` | Valid credential lacks required permission/scope, tenant-scope violation, or `PATCH .../reward-settings` attempted with an `X-API-Key` |
| `404` | Program not found, or program outside credential/tenant reach |
| `429` | Program-creation rate limit (5/hour/organization) exceeded |
| — | Subscription-tier quota (`max_programs`) exceeded returns a dedicated `{quota, limit, upgradePath}` body rather than the shared error shape |
| `500` | Database or event-store failure |

## Source References

| Area | Source |
| --- | --- |
| Admin program route mounts (dual-mounted at `/admin/v1` and `/internal/v1/admin`) | `backend/src/api/mod.rs` lines 106–154, 296–313 |
| M2M program route mounts | `backend/src/api/mod.rs` lines 787–791 |
| Legacy JWT program route mounts | `backend/src/api/mod.rs` lines 764–769 |
| Route permission mapping | `backend/src/api/middleware/admin_permissions.rs` lines 120–154 |
| Create program (both mounts) and reserve deposit (M2M) | `backend/src/api/programs.rs` `create_program`, `program_creation_organization`, `deposit_reserve` |
| `ProgramDto` / `ReserveStatusDto` (legacy JWT + M2M shape) | `backend/src/api/programs.rs` lines 27–53 |
| Admin list/status/lifecycle handlers | `backend/src/api/admin/programs.rs` `list_programs`, `get_program_status`, `pause_program`, `resume_program`, `adjust_reserve_ratio`, `deprecate_program`, `set_contract_address` |
| `ProgramSummaryDto` / `ProgramStatusResponse` / `SimpleStatusResponse` | `backend/src/api/admin/programs.rs` lines 26–178 |
| Domain lifecycle methods (`create`, `pause`, `resume`, `adjust_reserve_ratio`, `deprecate`) | `backend/src/domain/program.rs` |
| `ProgramStatus` enum | `backend/src/domain/program.rs` `ProgramStatus` |
| `ReserveRatio` validation | `backend/src/domain/types.rs` `ReserveRatio` |
| Reward settings handlers and validation | `backend/src/api/admin/program_reward_settings.rs` |
| Reward settings API-key rejection | `backend/src/api/admin/program_reward_settings.rs` `reject_api_key_reward_settings` |
| Tier ladder handlers and validation | `backend/src/api/admin/tier_ladders.rs` |
| `TierRung` / `TierLadder` | `backend/src/services/rule_simulator.rs` lines 662–695 |
| Tenant scoping (`OrgScope`, `enforce_program_scope`) | `backend/src/api/admin/org_scope.rs` |
| Legacy wallet JWT claims | `backend/src/api/middleware/jwt.rs` `Claims`, `jwt_auth` |
| Program-creation rate limit and quota | `backend/src/api/programs.rs` `create_program`; `backend/src/api/middleware/quota.rs` `QuotaKind::Programs` |
| Stablecoin reward model (deep dive) | [Stablecoin Rewards](../stablecoin-rewards.md) |

---

# API Reference

Source: ../docs/api-reference.md
URL: https://docs.rails.sh/api-reference
Markdown: https://docs.rails.sh/markdown/api-reference.md

# API Reference

Status: route inventory rebuilt against `backend/src/api/mod.rs` end-to-end
(2026-08-25). This is an INDEX page — method, path, auth, and a one-line
purpose, with links out to per-area pages where one exists. Deep prose
(request/response schemas, error tables, CLI usage) belongs on those pages,
not here.

## Source Of Truth

Current route inventory comes from:

- `backend/src/api/mod.rs`
- `api-contracts/loyaltyrails-cli.v1.openapi.json`
- Handler DTOs under `backend/src/api/**`, `backend/src/games/api/**`, and
  `backend/src/intelligence/api/**`

The CLI-supported stable API surface is pinned by
`api-contracts/loyaltyrails-cli.v1.openapi.json`. Regenerate derived CLI and
backend bindings after changing that contract:

```bash
pnpm contract:generate
pnpm contract:check
```

## API Deep Dives

| Guide | Covers |
|-------|--------|
| [Authentication](./authentication.md) | Full auth-surface map, credential types, header names, tier/trial gating, webhook signature verification |
| [Events API](./api/events.md) | Event ingestion, idempotency, async processing, `transaction.completed`, and CLI smoke tests |
| [Members API](./api/members.md) | Member identity, external ID lookup, balances, wallet identifiers, and browser-safe host routes |
| [Rules API](./api/rules.md) | Rule types, conditions, lifecycle, simulation, builder metadata, and operator-auth surfaces |
| [Games API](./api/games.md) | Runtime game APIs, setup APIs, sessions, generated session tokens, experiences, and campaigns |
| [Programs API](./api/programs.md) | Program creation, lifecycle (pause/resume/deprecate), reserve ratio, reward-mode settings, and tier ladders |
| [Campaigns API](./api/campaigns.md) | Campaign CRUD, scheduling/activation lifecycle, experience attachment, personalization rules, and audience targeting |
| [Stablecoin Rewards](./stablecoin-rewards.md) | Reward assets, issuance/settlement, wallets and custody for the stablecoin admin surface below |
| [Webhook Outcomes](./integrations/webhook-outcomes.md) | Vendor webhook delivery, retries, and dead-letter handling |

## Authentication Surfaces

rails has multiple API surfaces with different credential types — see
[Authentication](./authentication.md) for the full model. Summary:

| Surface | Auth | Primary caller |
|---------|------|----------------|
| `/health`, `/ready` | None | Load balancers, local health checks |
| `/auth/*` | Public or browser session depending on route | Admin frontend |
| `/admin/v1/*` | Browser session cookie (`lr_session`) or `Authorization: Bearer lr_cli_...` operator CLI token | Admin frontend and operator CLI |
| `/internal/v1/admin/*` | `X-API-Key` with `admin` scope — deprecated mirror of `/admin/v1/*` | Legacy M2M admin callers |
| `/internal/v1/*` | Integration API key in `X-API-Key` | Server-to-server integrations |
| `/public/v1/members/me/*` | Short-lived member JWT (`Authorization: Bearer`), minted via `/api/v1/member-tokens/issue` | Browser SDK — the current end-user surface |
| `/alp/v1/*` | Wallet-context JWT (`Authorization: Bearer`) | Legacy end-user surface — do not build new integrations against it |
| `/alp/v1/integrations/:id/webhook` | Per-connection webhook secret, verified in the handler | Vendor webhooks |
| `/webhooks/stripe` | `Stripe-Signature` header, verified in the handler | Stripe billing events |
| `/commerce/v1/*` | Commerce credential (`CommercePrincipal`) — never api-key/session/agent | ADR-014 merchant commerce integrations |

Never send `X-API-Key`, operator CLI tokens, or member JWTs from browser
code. Every mutating request on `/admin/v1/*`, `/internal/v1/*`, and
`/internal/v1/admin/*` is subject to tier/trial gating (see
[Authentication § Tier & Trial Gating](./authentication.md#tier--trial-gating)).

## Health

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `GET` | `/health` | None | Liveness |
| `GET` | `/ready` | None | Readiness |

## Auth And Sessions

Public (unauthenticated) auth routes:

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/auth/login` | Login |
| `POST` | `/auth/register` | Register |
| `POST` | `/auth/verify-email` | Verify email |
| `POST` | `/auth/resend-verification` | Resend verification email (anti-enumeration, generic 200) |
| `POST` | `/auth/forgot-password` | Request password reset |
| `POST` | `/auth/reset-password` | Reset password |
| `POST` | `/auth/mfa/verify` | Complete MFA during login |
| `POST` | `/auth/mfa/enroll/totp` | Start pending-session TOTP enrollment |
| `POST` | `/auth/mfa/enroll/totp/confirm` | Confirm pending-session TOTP enrollment |
| `POST` | `/auth/mfa/enroll/passkey/challenge` | Start pending-session passkey enrollment |
| `POST` | `/auth/mfa/enroll/passkey/verify` | Verify pending-session passkey enrollment |
| `POST` | `/auth/invites/lookup` | Look up an org team invite by token |
| `POST` | `/auth/invites/accept` | Accept an org team invite |

Session-protected auth routes (browser session cookie): logout, current
user, self-service org creation (`/auth/organizations`), step-up
re-authentication, TOTP/passkey/backup-code management, session
listing/revocation, and password/email change under `/admin/v1/auth/*` and
`/auth/*`.

Operator CLI token routes:

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/admin/v1/auth/cli-tokens` | Browser session | Create operator CLI token |
| `GET` | `/admin/v1/auth/cli-tokens` | Browser session | List operator CLI tokens |
| `DELETE` | `/admin/v1/auth/cli-tokens/:token_id` | Browser session | Revoke operator CLI token |
| `GET` | `/admin/v1/auth/cli-token/introspect` | Bearer `lr_cli_...` | Introspect operator token |

### CLI Pairing

Device-flow pairing between the CLI and a browser session:

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/api/v1/cli/pair/start` | None (rate-limited per-IP) | Start a pairing request |
| `POST` | `/api/v1/cli/pair/poll` | None — requires the `pollToken` secret | Poll a pairing request |
| `GET` | `/auth/session/cli-pair` | Browser session | Inspect a pending pairing |
| `POST` | `/auth/session/cli-pair/decide` | Browser session | Approve or deny a pending pairing |
| `POST` | `/api/v1/cli/exchange` | Bearer machine token (inline) | Exchange a CLI machine token for an agent JWT |

### Organization Team Invites

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/admin/v1/organization/invites` | Session/operator, `team:invite` | Create a team invite |
| `POST` | `/auth/invites/lookup` | Public (bearer invite token) | Look up invite metadata |
| `POST` | `/auth/invites/accept` | Public (bearer invite token) | Accept invite |

### Share / Handoff Links

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/share/v1/create` | Browser session | Create a share/handoff link |
| `GET` | `/share/v1/list` | Browser session | List share links |
| `POST` | `/share/v1/revoke/:id` | Browser session | Revoke a share link |
| `POST` | `/share/v1/claim` | Bearer machine token (inline) | Claim a share link (CLI) |

### Member Token Revocation

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/admin/v1/members/:member_id/revoke-tokens` | Browser session (org must own the member's program) | Revoke all issued member JWTs for a member |

## Public Member API (Current)

`/public/v1/members/me/*` is the current end-user surface — see
[Authentication § End-User Access](./authentication.md#end-user-access).
Auth is a short-lived member JWT (`Authorization: Bearer`) only; no
`X-API-Key`, no session cookie.

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/public/v1/members/me/summary` | One-shot balance + tier aggregate |
| `GET` | `/public/v1/members/me/balance` | Balance |
| `GET` | `/public/v1/members/me/tier` | Tier |
| `GET` | `/public/v1/members/me/active-experiences` | Active game experiences |
| `GET` | `/public/v1/members/me/redemptions` | Redemption history |
| `GET` | `/public/v1/members/me/consent-grants` | List commerce consent grants |
| `POST` | `/public/v1/members/me/consent-grants/:grant_id/confirm` | Confirm a consent grant |
| `POST` | `/public/v1/members/me/consent-grants/:grant_id/revoke` | Revoke a consent grant |
| `POST` | `/public/v1/members/me/reservations/:reservation_id/confirm` | Confirm a commerce reservation |
| `POST` | `/public/v1/members/me/reservations/:reservation_id/cancel` | Cancel a commerce reservation |
| `GET` | `/public/v1/members/me/receipts` | List commerce receipts |
| `GET` | `/public/v1/members/me/receipts/:receipt_id` | Get a commerce receipt |

### Member Tokens

Server-to-server callers (holding an integration `X-API-Key`) mint and
refresh the member JWTs above:

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `POST` | `/api/v1/member-tokens/issue` | `X-API-Key` | Mint a short-lived member JWT |
| `POST` | `/api/v1/member-tokens/refresh` | `X-API-Key` | Refresh a member JWT before expiry |

## Legacy End-User ALP API

`/alp/v1/*` is an older end-user surface authenticated by a separate
wallet-context JWT. It predates the member-token model above and uses a
different signing secret. **New integrations should use
`/public/v1/members/me/*` instead — treat `/alp/v1/*` as legacy.**

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/alp/v1/programs` | List public programs |
| `GET` | `/alp/v1/programs/:id` | Get public program |
| `GET` | `/alp/v1/balance?wallet=...` | Get wallet balance |
| `POST` | `/alp/v1/redeem` | Redeem tokens |

## Internal M2M API

These routes use integration API keys through `X-API-Key`.

### Programs And Awards

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/programs` | Create program through M2M path |
| `POST` | `/internal/v1/programs/:id/reserve` | Deposit reserve |
| `POST` | `/internal/v1/mint` | Legacy/internal mint |
| `POST` | `/internal/v1/award` | Award points to member by member ID or external ID |
| `GET` | `/internal/v1/auth/introspect` | Introspect integration API key |

Award request:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "amount": 100,
  "reference": "order_456",
  "metadata": {
    "orderId": "456"
  }
}
```

Award response:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001",
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "baseAmount": 100,
  "finalAmount": 200,
  "rulesApplied": [
    {
      "ruleId": "550e8400-e29b-41d4-a716-446655440002",
      "ruleName": "Double Points Tuesday",
      "bonusApplied": 100,
      "multiplierApplied": 2
    }
  ],
  "reference": "order_456",
  "status": "awarded",
  "settled": false,
  "newMember": false
}
```

`reference` is required for idempotency.

### Members

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/members` | Create member |
| `GET` | `/internal/v1/members/:member_id` | Get member |
| `GET` | `/internal/v1/members/:member_id/balance` | Get member balance |
| `GET` | `/internal/v1/programs/:program_id/members` | List program members |
| `POST` | `/internal/v1/programs/:program_id/members/balance/lookup` | Program-scoped external-ID balance lookup |

Balance lookup request:

```json
{
  "externalId": "customer_123",
  "externalIdType": "customer_id"
}
```

### Event Ingestion

See [Events API](./api/events.md) for the full contract.

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/programs/:program_id/events` | Ingest one event |
| `POST` | `/internal/v1/programs/:program_id/events/batch` | Ingest a batch |
| `GET` | `/internal/v1/programs/:program_id/events/:event_id/status` | Read event status |

Example:

```json
{
  "eventType": "transaction.completed",
  "idempotencyKey": "order_123",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "occurredAt": "2026-05-01T12:00:00Z",
  "payload": {
    "amount": 2500,
    "currency": "USD"
  }
}
```

### Game Runtime

See [Games API](./api/games.md) for the full contract.

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/games/resolve` | Resolve playable experiences for a member |
| `POST` | `/internal/v1/games/sessions` | Start an idempotent game session |
| `POST` | `/internal/v1/games/sessions/:session_id/actions` | Submit a mechanic action |
| `POST` | `/internal/v1/games/sessions/:session_id/complete` | Complete a game session |
| `GET` | `/internal/v1/games/programs/:program_id/members/:member_id/reward-state` | Read member game reward state |

Resolve request:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001"
}
```

Start session request:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001",
  "experienceId": "550e8400-e29b-41d4-a716-446655440002",
  "campaignId": "550e8400-e29b-41d4-a716-446655440003",
  "idempotencyKey": "game_session_123",
  "surface": "web",
  "fingerprint": "optional-device-or-session-fingerprint"
}
```

### Value Decisions And Agentic Commerce

ADR-014 loyalty/value-decision substrate. Mounted as its own sub-router so
the commerce-containment layer (kill switch default-off, agent-principal
mutation rejection, unattributed-write fail-closed) wraps exactly this
surface.

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/programs/:program_id/value/consent-grants` | Create member consent grant |
| `GET` | `/internal/v1/value/consent-grants/:grant_id` | Get consent grant |
| `POST` | `/internal/v1/value/consent-grants/:grant_id/revoke` | Revoke consent grant |
| `POST` | `/internal/v1/value/consent-grants/:grant_id/expire` | Expire consent grant |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/consent-grants` | Create adapter consent grant |
| `POST` | `/internal/v1/programs/:program_id/value/agentic-sessions` | Create agentic session |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions` | Create adapter checkout session |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/complete` | Complete checkout session |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/cancel` | Cancel checkout session |
| `GET` | `/internal/v1/value/agentic-sessions/:session_id` | Get agentic session |
| `POST` | `/internal/v1/value/agentic-sessions/:session_id/complete` | Complete agentic session |
| `POST` | `/internal/v1/value/agentic-sessions/:session_id/cancel` | Cancel agentic session |
| `POST` | `/internal/v1/value/agentic-sessions/:session_id/expire` | Expire agentic session |
| `POST` | `/internal/v1/programs/:program_id/value/quotes` | Create value quote |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/quotes` | Create adapter checkout quote |
| `GET` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/quotes/:quote_id` | Get adapter checkout quote |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/quotes/:quote_id/reservations` | Create adapter reservation |
| `GET` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/reservations/:reservation_id` | Get adapter reservation |
| `POST` | `/internal/v1/programs/:program_id/agentic-commerce/:protocol/checkout-sessions/:session_id/reservations/:reservation_id/release` | Release adapter reservation |
| `GET` | `/internal/v1/value/quotes/:quote_id` | Get value quote |
| `POST` | `/internal/v1/value/quotes/:quote_id/reservations` | Create value reservation |
| `GET` | `/internal/v1/value/reservations/:reservation_id` | Get value reservation |
| `POST` | `/internal/v1/value/reservations/:reservation_id/release` | Release value reservation |
| `POST` | `/internal/v1/value/reservations/:reservation_id/commit` | Commit value reservation |

### Integration Management

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/integrations` | Create integration |
| `GET` | `/internal/v1/programs/:id/integrations` | List program integrations |
| `GET` | `/internal/v1/integrations/:id` | Get integration status |
| `POST` | `/internal/v1/integrations/:id/connect` | Connect integration |
| `POST` | `/internal/v1/integrations/:id/disconnect` | Disconnect integration |

### Batch Lineage

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/internal/v1/programs/:program_id/members/:member_address/batches` | List point batches |
| `GET` | `/internal/v1/batches/:batch_id/lineage` | Trace batch lineage |
| `GET` | `/internal/v1/programs/:program_id/liability` | Liability forecast |
| `GET` | `/internal/v1/contexts/:context_ref` | Batch context |

## Admin API

`/admin/v1/*` is the primary admin/control-plane mount (browser session or
operator CLI token). The same handler set — with the exception of the
platform-only and operator-only routes noted below — is also mounted under
`/internal/v1/admin/*` for the deprecated API-key admin transition path.

### Programs, Rules, Tier Ladders

See [Programs API](./api/programs.md) for the full program-lifecycle
contract (create, pause/resume/deprecate, reserve ratio, reward settings,
tier ladders) and [Rules API](./api/rules.md) for rule conditions,
lifecycle, and simulation detail.

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs` | List programs |
| `POST` | `/admin/v1/programs` | Create program |
| `GET` | `/admin/v1/programs/:program_id/status` | Program status |
| `POST` | `/admin/v1/programs/:program_id/pause` | Pause program |
| `POST` | `/admin/v1/programs/:program_id/resume` | Resume program |
| `PATCH` | `/admin/v1/programs/:program_id/reserve-ratio` | Adjust reserve ratio |
| `POST` | `/admin/v1/programs/:program_id/deprecate` | Deprecate program |
| `POST` | `/admin/v1/programs/:program_id/contract` | Set contract address |
| `GET`/`PATCH` | `/admin/v1/programs/:program_id/reward-settings` | Read/update program reward settings |
| `GET` | `/admin/v1/programs/:program_id/rules` | List rules |
| `POST` | `/admin/v1/programs/:program_id/rules` | Create rule |
| `POST` | `/admin/v1/programs/:program_id/rules/simulate` | Simulate a draft rule config (see [Rules API](./api/rules.md)) |
| `GET` | `/admin/v1/rules/:rule_id` | Get rule |
| `PATCH` | `/admin/v1/rules/:rule_id` | Update rule |
| `DELETE` | `/admin/v1/rules/:rule_id` | Delete rule |
| `POST` | `/admin/v1/rules/:rule_id/pause` | Pause rule |
| `POST` | `/admin/v1/rules/:rule_id/activate` | Activate rule |
| `POST` | `/admin/v1/rules/:rule_id/simulate` | Trace-simulate a stored rule against test data (see [Rules API](./api/rules.md)) |
| `GET`/`PUT` | `/admin/v1/programs/:program_id/tier-ladder` | Read/replace the active tier ladder |
| `GET` | `/admin/v1/programs/:program_id/tier-ladder/versions` | List tier ladder versions |

### Analytics

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/analytics/summary` | Summary analytics |
| `GET` | `/admin/v1/programs/:program_id/analytics/minting-trend` | Minting trend |
| `GET` | `/admin/v1/programs/:program_id/analytics/redemption-trend` | Redemption trend |
| `GET` | `/admin/v1/programs/:program_id/analytics/reserve-utilization` | Reserve utilization |
| `GET` | `/admin/v1/programs/:program_id/analytics/member-segments` | Member segments |
| `GET` | `/admin/v1/programs/:program_id/analytics/daily` | Daily analytics |

### Alerts

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/alerts` | List alerts |
| `POST` | `/admin/v1/programs/:program_id/alerts` | Create alert |
| `GET` | `/admin/v1/alerts/:alert_id` | Get alert |
| `PATCH` | `/admin/v1/alerts/:alert_id` | Update alert |
| `DELETE` | `/admin/v1/alerts/:alert_id` | Delete alert |
| `POST` | `/admin/v1/alerts/:alert_id/pause` | Pause alert |
| `POST` | `/admin/v1/alerts/:alert_id/activate` | Activate alert |
| `GET` | `/admin/v1/programs/:program_id/alerts/history` | List alert history |
| `POST` | `/admin/v1/alerts/history/:history_id/acknowledge` | Acknowledge alert history entry |
| `POST` | `/admin/v1/alerts/history/:history_id/resolve` | Resolve alert history entry |

### API Keys

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/api-keys` | List program API keys |
| `GET` | `/admin/v1/api-keys/admin` | List all-program/admin keys |
| `POST` | `/admin/v1/api-keys` | Create API key |
| `GET` | `/admin/v1/api-keys/:key_id` | Get API key |
| `POST` | `/admin/v1/api-keys/:key_id/rotate` | Rotate API key |
| `POST` | `/admin/v1/api-keys/:key_id/revoke` | Revoke API key |

### Gamification Admin

Experience and campaign setup — see [Games API](./api/games.md) for the
runtime contract these configure and [Campaigns API](./api/campaigns.md)
for campaign CRUD, scheduling, and audience-targeting detail.

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/experiences` | List experiences |
| `POST` | `/admin/v1/programs/:program_id/experiences` | Create draft experience |
| `GET` | `/admin/v1/experiences/:experience_id` | Get experience |
| `PUT` | `/admin/v1/experiences/:experience_id` | Update draft experience |
| `GET` | `/admin/v1/experiences/:experience_id/metrics` | Experience metrics |
| `POST` | `/admin/v1/experiences/:experience_id/publish` | Publish experience |
| `POST` | `/admin/v1/experiences/:experience_id/pause` | Pause experience |
| `GET` | `/admin/v1/experiences/:experience_id/prize-pool` | Get prize pool |
| `POST` | `/admin/v1/experiences/:experience_id/prize-pool` | Create prize pool |
| `GET` | `/admin/v1/experiences/:experience_id/sessions` | List experience sessions |
| `POST` | `/admin/v1/experiences/:experience_id/preview` | Cold-path game preview |
| `GET` | `/admin/v1/programs/:program_id/leaderboards` | List leaderboards |
| `POST` | `/admin/v1/programs/:program_id/leaderboards` | Create leaderboard |
| `GET` | `/admin/v1/leaderboards/:leaderboard_id` | Get leaderboard |
| `POST` | `/admin/v1/leaderboards/:leaderboard_id/rebuild-ranks` | Rebuild leaderboard ranks |
| `GET` | `/admin/v1/leaderboards/:leaderboard_id/sse` | Leaderboard event stream |
| `GET` | `/admin/v1/programs/:program_id/campaigns` | List campaigns |
| `POST` | `/admin/v1/programs/:program_id/campaigns` | Create campaign |
| `GET` | `/admin/v1/campaigns/:campaign_id` | Get campaign |
| `PUT` | `/admin/v1/campaigns/:campaign_id` | Update campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/activate` | Activate campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/schedule` | Schedule campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/pause` | Pause campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/experiences` | Attach experience |
| `DELETE` | `/admin/v1/campaigns/:campaign_id/experiences/:experience_id` | Detach experience |
| `GET` | `/admin/v1/campaigns/:campaign_id/personalization-rules` | List personalization rules |
| `POST` | `/admin/v1/campaigns/:campaign_id/personalization-rules` | Create personalization rule |
| `GET` | `/admin/v1/campaigns/:campaign_id/audience/preview` | Preview audience |
| `POST` | `/admin/v1/members/:member_id/segments` | Update member segments |

### Question Bank And Content Intelligence

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/questions` | List questions |
| `POST` | `/admin/v1/programs/:program_id/questions` | Create question |
| `GET` | `/admin/v1/questions/:question_id` | Get question |
| `DELETE` | `/admin/v1/questions/:question_id` | Delete question |
| `POST` | `/admin/v1/questions/:question_id/status` | Update question status |
| `POST` | `/admin/v1/programs/:program_id/questions/generate` | Generate question |
| `GET` | `/admin/v1/programs/:program_id/content/variants` | List content variants |
| `GET` | `/admin/v1/content/variants/:variant_id` | Get variant |
| `POST` | `/admin/v1/content/variants/:variant_id/approve` | Approve variant |
| `POST` | `/admin/v1/content/variants/:variant_id/reject` | Reject variant |
| `POST` | `/admin/v1/content/variants/:variant_id/edit` | Edit variant |
| `POST` | `/admin/v1/programs/:program_id/content/generate` | Enqueue content generation |
| `GET` | `/admin/v1/programs/:program_id/difficulty/recommendations` | List difficulty recommendations |
| `POST` | `/admin/v1/difficulty/recommendations/:recommendation_id/approve` | Approve recommendation |
| `POST` | `/admin/v1/difficulty/recommendations/:recommendation_id/reject` | Reject recommendation |

### Members And Audit

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/members` | List members |
| `POST` | `/admin/v1/members` | Create member |
| `GET` | `/admin/v1/members/:member_id` | Get member |
| `GET` | `/admin/v1/members/:member_id/balance` | Get member balance |
| `GET` | `/admin/v1/programs/:program_id/members/:external_id/balance` | Get external-ID balance |
| `POST` | `/admin/v1/members/:member_id/suspend` | Suspend member |
| `POST` | `/admin/v1/members/:member_id/reactivate` | Reactivate member |
| `GET` | `/admin/v1/audit-events` | List audit events |
| `GET` | `/admin/v1/audit-events/stream` | Audit event SSE stream |
| `GET` | `/admin/v1/audit-events/actions` | List audit action values |
| `GET` | `/admin/v1/audit-events/:id` | Get audit event |
| `GET` | `/admin/v1/programs/:program_id/activity-feed` | Human-readable activity feed |
| `GET` | `/admin/v1/programs/:program_id/activity-feed/stream` | Activity feed SSE stream |

### Outbound Delivery And Dead Letters

See [Webhook Outcomes](./integrations/webhook-outcomes.md).

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/dead-letters` | Ingest dead-letter inspection |
| `GET` | `/admin/v1/outbound/dead-letters` | List outbound (vendor delivery) dead letters |
| `GET` | `/admin/v1/outbound/health` | Outbound live-dispatch health |
| `GET`/`POST` | `/admin/v1/outbound/health/snapshots` | List/record health snapshots |
| `POST` | `/admin/v1/outbound/connections/:connection_id/credential-smoke` | Smoke-test connection credentials |
| `POST` | `/admin/v1/outbound/dead-letters/:dead_letter_id/approve` | Approve dead-letter replay |
| `POST` | `/admin/v1/outbound/dead-letters/:dead_letter_id/reject` | Reject dead-letter replay |
| `POST` | `/admin/v1/outbound/dead-letters/:dead_letter_id/replayed` | Mark dead letter replayed |
| `POST` | `/admin/v1/outbound/simulations` | Simulate outbound vendor readiness — operator/session only, not on the deprecated API-key mirror |

### Commerce And Stablecoin Admin

Condensed — see [Stablecoin Rewards](./stablecoin-rewards.md) for the
domain model. The `pilot-health` row is the one commerce read the
conversational agent may access (ADR-014); everything else on this surface
is session/operator only and never agent-reachable.

| Method | Path pattern | Auth | Purpose |
|--------|--------------|------|---------|
| `GET` | `/admin/v1/commerce/pilot-health` | Session/operator or agent (dual-mounted) | ADR-014 aggregate commerce health |
| `GET` | `/admin/v1/stablecoin/programs/:program_id/{setup-status, setup-doctor, issuance-config, issuance-funnel, liability-buckets, campaign-roi, provider-ops, game-economics}` | Session/operator only | Stablecoin setup and analytics reads |
| `PUT` | `/admin/v1/stablecoin/programs/:program_id/issuance-config` | Session/operator only | Configure stablecoin issuance |
| `PATCH` | `/admin/v1/stablecoin/programs/:program_id/setup-checklist/:item_key` | Session/operator only | Update a setup checklist item |
| `GET` | `/admin/v1/stablecoin/programs/:program_id/{reward-intents/:id/timeline, members/:id/timeline}` | Session/operator only | Reward intent / member stablecoin timelines |
| `GET` | `/admin/v1/stablecoin/programs/:program_id/reconciliation/exceptions` | Session/operator only | List reconciliation exceptions |
| `POST` | `/admin/v1/stablecoin/programs/:program_id/reconciliation/runs` | Session/operator only | Create a reconciliation run |
| `POST` | `/admin/v1/stablecoin/programs/:program_id/reconciliation/exceptions/:exception_id/{acknowledge, mark-in-review, resolve, dismiss}` | Session/operator only | Reconciliation exception state transitions |
| `GET` | `/admin/v1/programs/:program_id/stablecoin/{available-rails, rail-binding}` | Session/operator only | Program-level rail configuration reads |
| `GET` | `/admin/v1/organization/stablecoin/rails` | Session/operator (dual-mounted, also on the deprecated API-key mirror) | List org-level stablecoin rails |
| `POST` | `/admin/v1/organization/stablecoin/rails` | Session/operator only, not on the deprecated API-key mirror | Configure the Base Sepolia USDC testnet org rail |
| `GET` | `/admin/v1/organization/stablecoin/readiness` | Session/operator only | Org stablecoin readiness |
| `POST` | `/admin/v1/programs/:program_id/stablecoin/rail-binding` | Session/operator only | Attach a program rail binding |
| `GET` | `/admin/v1/platform/stablecoin/provider-capabilities` | Session/operator (platform-admin mount, not on the deprecated API-key mirror) | Provider capability catalog |
| `GET` | `/admin/v1/commerce/{grants, sessions, reservations, receipts}` | Session/operator only — never agent-reachable | ADR-014 commerce inspection (read-only, redacted) |
| `GET` | `/admin/v1/commerce/records/:resource_type/:resource_id/timeline` | Session/operator only | Commerce record timeline |
| `GET`/`POST` | `/admin/v1/commerce/credentials` | Session/operator only | List / create commerce credentials |
| `POST` | `/admin/v1/commerce/credentials/:credential_id/rotate` | Session/operator only | Rotate commerce credential |
| `POST` | `/admin/v1/commerce/credentials/:credential_id/revoke` | Session/operator only | Revoke commerce credential |
| `PATCH` | `/admin/v1/commerce/credentials/:credential_id/scopes` | Session/operator only | Update commerce credential scopes |

## Merchant Commerce API

`/commerce/v1/*` is the ADR-014 redemption-slice commerce mount for
merchant integrations. Authenticated exclusively by a commerce credential
(`CommercePrincipal`) — no API key, session, or agent-principal credential
is accepted here.

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/commerce/v1/consent-grants` | Create consent grant |
| `POST` | `/commerce/v1/consent-grants/:grant_id/revoke` | Revoke consent grant |
| `POST` | `/commerce/v1/agentic-sessions` | Create agentic session |
| `POST` | `/commerce/v1/quotes` | Create quote |
| `GET` | `/commerce/v1/quotes/:quote_id` | Get quote |
| `POST` | `/commerce/v1/quotes/:quote_id/reservations` | Create reservation |
| `GET` | `/commerce/v1/reservations/:reservation_id` | Get reservation |
| `POST` | `/commerce/v1/reservations/:reservation_id/release` | Release reservation |
| `POST` | `/commerce/v1/reservations/:reservation_id/commit` | Commit reservation |

## Agent-Internal Surfaces

The conversational agent authenticates to the backend with a shared HMAC
secret (`X-Agent-Shared-Secret`) plus acting-user headers — see
[Authentication § Agent Auth](./authentication.md#agent-auth). This is not a
credential type available to integrators. The routes it reaches privately
(tenant provisioning, agent memory, adaptive analytics queries, shadow-batch
replay, and agent-JWT minting under `/api/v1/tenants/*`, `/api/v1/agent/memory*`,
`/internal/v1/analytics/query`, `/internal/v1/shadow-batch/*`, and
`/auth/session/refresh-agent-jwt`) are not part of the public integration
surface and are not documented further here.

## Webhooks

Both webhook receivers verify a signature in the handler before trusting
the request body — see [Authentication § Webhooks](./authentication.md#webhooks).

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/alp/v1/integrations/:id/webhook` | Vendor integration webhook (per-connection secret) |
| `POST` | `/webhooks/stripe` | Stripe billing webhook (`Stripe-Signature`) |

## CLI Contract

The CLI's supported route surface is generated from
`api-contracts/loyaltyrails-cli.v1.openapi.json`, not hand-copied here — the
contract changes independently of this page and a duplicated list goes
stale immediately. Run `pnpm contract:check` after any router change to
confirm generated bindings still match; inspect the contract file directly
for the exact current endpoint list.

## Error Model

Most handlers return structured API errors with an error code and message.
Endpoint-specific error documentation should be generated from handler
behavior and tests in a later pass.

Common error categories:

- Missing or invalid credentials.
- Scope or program mismatch.
- Validation failure.
- Not found.
- Idempotency conflict.
- Insufficient balance or unreserved balance.
- Stablecoin safety gate rejection.
- Provider or settlement failure.

## Documentation TODO

- Generate per-endpoint schema pages from handler DTOs or OpenAPI.
- Add example requests and responses for every CLI-supported endpoint.
- Add exact status-code behavior from tests.
- Add scope requirements for every admin and M2M route.
- Add stablecoin and value-decision DTO references.

---

# Events API

Source: ../docs/api/events.md
URL: https://docs.rails.sh/events-api
Markdown: https://docs.rails.sh/markdown/events-api.md

# Events API

Source-derived status: event ingestion is implemented in the backend and partially declared in the CLI OpenAPI contract. The single-event route is contract-declared and CLI-backed; batch ingestion and status lookup are backend routes but are not part of the current CLI contract.

## Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `POST` | `/internal/v1/programs/{programId}/events` | Implemented, contract-declared | Integration API key with `write` or `admin` scope |
| `POST` | `/internal/v1/programs/{programId}/events/batch` | Implemented, backend-only | Integration API key with `write` or `admin` scope |
| `GET` | `/internal/v1/programs/{programId}/events/{eventId}/status` | Implemented, backend-only | Integration API key with `read`, `write`, or `admin` scope |

## Auth Model

Event routes are mounted under `/internal/v1` and use the API key middleware. Send the key in `X-API-Key`.

Program-scoped keys can only access their own program. A key scoped to another program returns `404` to avoid cross-program resource disclosure. `write` scope implies `read`; `admin` implies both. The static bootstrap key is path-allowlisted by middleware but is rejected by route-level scope checks for normal event operations.

```bash
curl -X POST "https://api.loyaltyrails.com/internal/v1/programs/$PROGRAM_ID/events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lr_live_..." \
  -d @event.json
```

## Event Envelope

`InboundEvent` uses camelCase JSON:

```json
{
  "eventType": "transaction.completed",
  "idempotencyKey": "order_123",
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "occurredAt": "2026-05-02T15:04:05Z",
  "payload": {
    "amount": 2500,
    "currency": "USD",
    "channel": "online",
    "store_id": "web"
  }
}
```

Required by the contract: `eventType`, `idempotencyKey`, `occurredAt`, and `payload`.

Required by backend validation: non-empty `eventType`, non-empty `idempotencyKey`, and either `memberId` or `externalId`. If `externalId` is present, `externalIdType` is also required. `payload` defaults to `{}` in the Rust type, but the CLI contract marks it required, so integrations should always send it.

## `transaction.completed` Shape

`transaction.completed` is not a hard-coded schema. It is a convention carried by `eventType` plus merchant-defined `payload`. Any `eventType` beginning with `transaction.` or `purchase.` (for example `transaction.refunded`, `purchase.completed`) gets this same treatment.

The rules engine and member activity path currently know these payload conventions:

| Field | Purpose |
| --- | --- |
| `amount` | Legacy points-earn basis used by amount-based rule conditions (`MinAmount`/`MaxAmount`) and bonus/promotion calculations |
| `transactionAmountMinor` | Preferred field for the monetary transaction value, in minor currency units. New integrations should send this instead of overloading `amount`. It is recorded as the transaction value independently of whatever `amount` the rules engine uses as its earn basis; if both are present, `transactionAmountMinor` wins for the recorded value |
| `currency` | ISO-4217 currency code for the transaction value. Normalized to uppercase; defaults to `USD` when absent or blank |
| `channel` | Channel condition input, such as `online`, `mobile`, or `in-store` |
| `store_id` | Location condition input |
| `items`, `payment_method` | Accepted as merchant payload data; usable by payload-attribute rules when present |

For `transaction.`/`purchase.`-prefixed events, the worker additionally appends a typed `TransactionRecorded` domain event to the event store (alongside the generic `EventIngested` event) carrying `amount_usd_cents` (from `transactionAmountMinor`, falling back to `amount`) and the normalized `currency`. This is an internal event-sourcing record, not part of this API's response bodies — other event types only produce `EventIngested`.

Illustrative request:

```json
{
  "eventType": "transaction.completed",
  "idempotencyKey": "checkout_order_100045",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "occurredAt": "2026-05-02T15:04:05Z",
  "payload": {
    "amount": 2500,
    "transactionAmountMinor": 2500,
    "currency": "USD",
    "channel": "online",
    "store_id": "web",
    "items": [
      { "sku": "shirt-001", "category": "apparel", "quantity": 1 }
    ]
  }
}
```

## Responses

Single-event ingestion returns `202` when accepted for asynchronous processing:

```json
{
  "eventId": "0de0ff5b-4f44-4e3f-9a27-dbeae4cb9e52",
  "status": "pending",
  "statusUrl": "/internal/v1/programs/0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd/events/0de0ff5b-4f44-4e3f-9a27-dbeae4cb9e52/status"
}
```

If the same idempotency key has already been durably queued for delivery — even if the worker hasn't finished processing it yet — the handler returns `200` with the original `eventId` and `status: "duplicate"`, replaying the stored response. A retry that arrives while the original request is still being claimed (not yet durably queued) instead gets `400` — see [Idempotency](#idempotency).

## Batch Ingestion

`POST /internal/v1/programs/{programId}/events/batch` accepts up to 1000 events per request:

```json
{
  "events": [
    { "eventType": "transaction.completed", "idempotencyKey": "order_1", "externalId": "customer_1", "externalIdType": "customer_id", "occurredAt": "2026-05-02T15:04:05Z", "payload": { "amount": 1000 } },
    { "eventType": "transaction.completed", "idempotencyKey": "order_2", "externalId": "customer_2", "externalIdType": "customer_id", "occurredAt": "2026-05-02T15:04:06Z", "payload": { "amount": 2000 } }
  ]
}
```

A batch over 1000 events is rejected outright with `400 bad_request` before any event in it is processed. Otherwise the endpoint always returns `202`, with one result per submitted event in input order — an individual event failing (validation error, quota rejection) does not fail the batch or the other events in it:

```json
{
  "results": [
    { "eventId": "0de0ff5b-...", "status": "pending", "statusUrl": "/internal/v1/programs/.../events/0de0ff5b-.../status" },
    { "eventId": "00000000-0000-0000-0000-000000000000", "status": "failed", "error": "order_2: Invalid event: external_id_type is required when external_id is provided" }
  ]
}
```

A failed item's `eventId` is the nil UUID (`00000000-0000-0000-0000-000000000000`) and carries no `statusUrl` — there is no queue row to look up. One audit event is emitted for the whole batch (with success/failure/duplicate counts), not one per event.

## Status Endpoint

The status endpoint returns queue or idempotency state:

```json
{
  "eventId": "0de0ff5b-4f44-4e3f-9a27-dbeae4cb9e52",
  "status": "completed",
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "outcomesApplied": [],
  "attempts": 1,
  "enqueuedAt": "2026-05-02T15:04:06Z",
  "processingStartedAt": "2026-05-02T15:04:07Z",
  "completedAt": "2026-05-02T15:04:08Z"
}
```

`status` is one of `pending`, `processing`, `completed`, or `dead`, regardless of how the platform is deployed.

## Idempotency

Idempotency is keyed by `(programId, idempotencyKey)`. Use a merchant-stable event reference such as an order ID, checkout ID, refund ID, or webhook delivery ID.

Behavior:

| Case | Result |
| --- | --- |
| First request for a new key | `202`, new `eventId`, `status: "pending"` |
| Retry once the original has been durably queued (worker may still be processing it) | `200`, same `eventId` as the original, `status: "duplicate"` |
| Retry that races the original before it's durably queued (still mid-claim) | `400`, `bad_request` |
| Retry of a key whose prior attempt failed | `202`, a **new** `eventId` reusing the same idempotency key, `status: "pending"` — poll status using this new `eventId`, not one from the earlier failed attempt |
| Delivery failure during enqueue | `500`; the idempotency slot is marked failed so the caller can retry with the same key |

Events are processed asynchronously — accepting an event does not mean it has been evaluated against rules yet; poll the status endpoint to observe completion.

## Processing Relationship

The API does not synchronously award points. It enqueues an inbound event, then the worker resolves or creates the member, records member activity, evaluates active rules, executes outcomes, persists member state, and appends an `EventIngested` domain event in the worker transaction.

This is the backend target used by integration recipes such as `award-route` and Shopify/Hydrogen webhook scaffolding. Recipe-generated server routes should hold the API key server-side and forward normalized identity plus a stable idempotency key.

## Errors

Most `AppError` responses use the shared shape:

```json
{
  "error": "bad_request",
  "message": "Invalid event: external_id_type is required when external_id is provided"
}
```

Common cases:

| HTTP | `error` | Notes |
| --- | --- | --- |
| `400` | `bad_request` | Invalid event, missing identity, batch over 1000 events, in-progress idempotency key |
| `401` | `unauthorized` or empty middleware response | Missing or invalid API key |
| `403` | `forbidden` | API key lacks required scope, or the key is the static bootstrap key |
| `404` | `not_found` | Program outside key reach or event not found |
| `429` | `quota_exceeded` | Monthly event quota or active-member capacity limit reached for the org's tier — bespoke body, not the shared shape (see below) |
| `500` | `internal_error` | Database, queue, or transport failure |

The `429` case is a bespoke body, since the frontend/agent narration layer reads `quota`/`limit`/`upgradePath` directly rather than a `message` string:

```json
{
  "error": "quota_exceeded",
  "quota": "monthly_events",
  "limit": 10000,
  "upgradePath": "/admin/settings/billing"
}
```

This applies only to the write endpoints (single and batch ingestion); the status lookup has no quota check.

## CLI Smoke Test

The CLI `events send` command is a smoke client for the single-event route. It requires an active integration API-key profile with `write` scope.

```bash
loyaltyrails events send \
  --type transaction.completed \
  --external-id customer_123 \
  --external-id-type customer_id \
  --idempotency-key order_123 \
  --payload '{"amount":2500,"currency":"USD"}'
```

Use `--member-id` instead of `--external-id` when the storefront or backend already has the member's rails UUID. `--idempotency-key` is optional on the CLI — a random one is generated if omitted.

## Source References

| Area | Source |
| --- | --- |
| Route mounts | `backend/src/api/mod.rs` lines 813-822 |
| Response/request DTOs and single-event handler | `backend/src/api/ingest.rs` lines 29-219 |
| Batch handler | `backend/src/api/ingest.rs` lines 221-411 |
| Status handler | `backend/src/api/ingest.rs` lines 413-480 |
| Core enqueue + transport dispatch | `backend/src/api/ingest.rs` lines 506-719 |
| Event envelope and validation | `backend/src/domain/event_envelope.rs` |
| Idempotency claim semantics | `backend/src/infrastructure/database/ingest_idempotency.rs` lines 56-124 |
| Worker processing core, `TransactionRecorded` gating, `transactionAmountMinor`/`currency` extraction | `backend/src/services/event_processor.rs` lines 61-258 |
| Transaction-event-type detection | `backend/src/domain/member.rs` `is_transaction_event` |
| CLI contract | `api-contracts/loyaltyrails-cli.v1.openapi.json` path `/internal/v1/programs/{programId}/events` |
| CLI smoke command | `packages/cli/src/commands.ts` `events send` |

---

# Members API

Source: ../docs/api/members.md
URL: https://docs.rails.sh/members-api
Markdown: https://docs.rails.sh/markdown/members-api.md

# Members API

Source-derived status: member creation, lookup, listing, balance, and
lifecycle (suspend/reactivate) routes are implemented in the backend. The
external-ID balance lookup route is also declared in the CLI OpenAPI
contract and used by generated browser-safe integration routes.
**Availability note:** the two admin member-lifecycle routes
(`/admin/v1/members/{memberId}/suspend` and `.../reactivate`) are currently
reachable only via the deprecated API-key mirror
(`/internal/v1/admin/members/{memberId}/suspend|reactivate`) with an
admin-scoped key; browser-session and operator-token calls to the
`/admin/v1` paths are not yet supported. See
[Member Lifecycle](#member-lifecycle-suspend--reactivate) below.

This page covers the merchant-facing member management surface: creating,
looking up, listing, and administering members. For the end-user-facing
member surface (`/public/v1/members/me/*`, member-JWT `Authorization:
Bearer` auth) and how to mint that JWT (`/api/v1/member-tokens/issue` /
`.../refresh`), see [Authentication](../authentication.md) and the
[API Reference](../api-reference.md) — those pages are the source of truth
for that surface and aren't duplicated here.

## Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `POST` | `/internal/v1/members` | Implemented | `X-API-Key` with `write` or `admin` scope |
| `GET` | `/internal/v1/members/{memberId}` | Implemented | `X-API-Key` with `read`, `write`, or `admin` scope |
| `GET` | `/internal/v1/members/{memberId}/balance` | Implemented | `X-API-Key` with `read`, `write`, or `admin` scope |
| `GET` | `/internal/v1/programs/{programId}/members` | Implemented | `X-API-Key` with `read`, `write`, or `admin` scope |
| `POST` | `/internal/v1/programs/{programId}/members/balance/lookup` | Implemented, contract-declared | `X-API-Key` with `read`, `write`, or `admin` scope |
| `GET` | `/admin/v1/programs/{programId}/members` | Implemented | Browser session or operator token with `programs:read` |
| `POST` | `/admin/v1/members` | Implemented | Browser session or operator token with `programs:update` |
| `GET` | `/admin/v1/members/{memberId}` | Implemented | Browser session or operator token with `programs:read` |
| `GET` | `/admin/v1/members/{memberId}/balance` | Implemented | Browser session or operator token with `programs:read` |
| `GET` | `/admin/v1/programs/{programId}/members/{externalId}/balance` | Implemented | Browser session or operator token with `programs:read` |
| `POST` | `/admin/v1/members/{memberId}/suspend` | Implemented | Not yet supported for browser session or operator token; use the API-key mirror below |
| `POST` | `/admin/v1/members/{memberId}/reactivate` | Implemented | Not yet supported for browser session or operator token; use the API-key mirror below |

Every route in the `/admin/v1/members...` group above is also mounted,
deprecated, under `/internal/v1/admin/...` (e.g.
`/internal/v1/admin/members`) for machine-to-machine callers still on the
legacy admin API-key path, using an `admin`-scoped `X-API-Key`. For
suspend/reactivate specifically, **this deprecated mirror is the only
currently-supported way to call these two operations** — see
[Member Lifecycle](#member-lifecycle-suspend--reactivate) below.

For public storefronts, use an app/server route that calls
`/internal/v1/...`; do not expose `X-API-Key` in browser code.

## Auth Model

Internal member routes use `X-API-Key`. Admin member routes use the admin
auth stack: browser session cookies or operator CLI tokens on `/admin/v1`,
and a deprecated admin API-key mount under `/internal/v1/admin`.

For integration keys:

| Operation | Required scope |
| --- | --- |
| Create/upsert member | `write` or `admin` |
| Lookup member, list members, read balance | `read`, `write`, or `admin` |
| Suspend/reactivate member (M2M via deprecated `/internal/v1/admin/members/...` mirror only) | `admin` |

For browser/operator admin routes, route permissions are feature
permissions rather than API-key scopes. Member list/read paths require
`programs:read`; member creation requires `programs:update`. Suspend and
reactivate are not yet available on the browser-session/operator-token
path at all — see [Member Lifecycle](#member-lifecycle-suspend--reactivate)
below for the currently-supported route.

## Member Identity

Members are identified two ways:

| ID | Meaning |
| --- | --- |
| `memberId` | rails UUID from `member_mappings.id` |
| `externalId` + `externalIdType` | Merchant/customer identifier pair, such as `customer_123` + `customer_id` or a Shopify customer ID + `shopify_id` |

Creating a member upserts by external identity and generates a deterministic wallet address from `externalIdType:externalId`. Event ingestion can also create a member when an event supplies external identity but no `memberId`.

Create/upsert request:

```json
{
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "profile": {
    "display_name": "Avery"
  }
}
```

Response:

```json
{
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "walletAddress": "0x...",
  "tier": "bronze",
  "new": true
}
```

`new` is `false` when the member already existed and the call behaved as an upsert.

## External-ID Balance Lookup

This is the browser-safe integration route target and the only member route currently declared in the CLI contract:

```http
POST /internal/v1/programs/{programId}/members/balance/lookup
X-API-Key: lr_test_...
Content-Type: application/json
```

```json
{
  "externalId": "customer_123",
  "externalIdType": "customer_id"
}
```

Response:

```json
{
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "balance": 1250,
  "settledBalance": 1000,
  "pendingSettlement": 250,
  "totalEarned": 1750,
  "totalRedeemed": 500
}
```

If the member has no balance row yet, the backend returns zeros for balance fields after finding the member mapping.

There is also an admin external-ID balance route at `GET /admin/v1/programs/{programId}/members/{externalId}/balance?externalIdType=customer_id`. It returns a richer admin shape with wallet, status, timestamps, and recent transactions. Its query parameter defaults to `crm` when omitted, so pass `externalIdType` explicitly unless the admin caller really uses CRM IDs.

## Full Member Shape

`GET /internal/v1/members/{memberId}` returns identity, wallet, status, tier/progression fields, balances, activity counters, profile JSON, badges, active offers, and timestamps:

```json
{
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "externalId": "customer_123",
  "externalIdType": "customer_id",
  "walletAddress": "0x...",
  "status": "active",
  "tier": "bronze",
  "tierPoints": 1250,
  "balance": 1250,
  "settledBalance": 1000,
  "pendingSettlement": 250,
  "totalEarned": 1750,
  "totalRedeemed": 500,
  "transactionCount": 3,
  "consecutiveDays": 2,
  "daysSinceLastActivity": 0,
  "profile": {},
  "badges": [],
  "activeOffers": [],
  "lastActivityAt": "2026-05-02T15:04:05Z",
  "createdAt": "2026-05-01T12:00:00Z"
}
```

`status` is `"active"` or `"suspended"` — see the lifecycle routes below.
The same `MemberDetailResponse` shape is also the response body of the
suspend/reactivate calls.

## Member Lifecycle (Suspend / Reactivate)

```http
POST /admin/v1/members/{memberId}/suspend
POST /admin/v1/members/{memberId}/reactivate
```

Request body (both routes):

```json
{
  "reason": "Chargebacks flagged by fraud review"
}
```

`reason` is required, 1–280 characters after trimming; empty or
whitespace-only values are rejected with `400`. It's recorded on the audit
event (`mutation.member_suspended` / `mutation.member_reactivated`) so the
activity feed shows why the status changed. Calling suspend on an
already-suspended member (or reactivate on an already-active one) is a
`400` no-op guard, not a silent success.

Response: the full `MemberDetailResponse` shape (see above), reflecting the
new `status`.

**Read this before wiring a UI to these routes.** These operations are
currently available only via the deprecated API-key mirror —
`POST /internal/v1/admin/members/{memberId}/suspend` and
`.../reactivate` — with an admin-scoped `X-API-Key`. Browser-session and
operator-CLI-token calls to the `/admin/v1/members/{memberId}/suspend` and
`.../reactivate` paths shown above are not yet supported; use the
deprecated mirror instead until that changes. The underlying behavior
(tenant scoping, plan-approval gating for agent-proxied calls, the no-op
guard, the audit event) is the same on both mounts — only the calling
convention differs.

Agent-proxied calls (requests carrying `x-acting-user-id`) additionally
require a valid `X-Agent-Plan-Approval` envelope listing the matching
`member.suspend` / `member.reactivate` intent, once the request reaches the
handler.

## Browser-Safe Host Route Pattern

Storefronts and websites should call a local server route, not rails directly from the browser. The generated Next.js App Router balance route follows this pattern:

1. Browser calls `GET /api/loyaltyrails/balance`.
2. The app route resolves the signed-in customer server-side.
3. The app route calls rails with `X-API-Key`:
   `POST /internal/v1/programs/{programId}/members/balance/lookup`.
4. The app route returns only the safe response body to the browser.

Minimal shape:

```ts
export async function GET(request: Request) {
  const identity = await resolveCustomer(request);

  const response = await fetch(
    `${process.env.LOYALTYRAILS_API_URL}/internal/v1/programs/${process.env.LOYALTYRAILS_PROGRAM_ID}/members/balance/lookup`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.LOYALTYRAILS_API_KEY!,
      },
      body: JSON.stringify({
        externalId: identity.externalId,
        externalIdType: identity.externalIdType ?? 'customer_id',
      }),
    }
  );

  return Response.json(await response.json(), { status: response.status });
}
```

None of the routes on this page are safe to call directly from a browser:
every `/internal/v1/members/...` call needs `X-API-Key` (server-only), and
every `/admin/v1/members/...` call needs an authenticated admin-frontend
session or operator token (the merchant operator's browser, not an
end-customer's). The one browser-safe, end-customer-facing member surface
is `/public/v1/members/me/*`, authenticated with a short-lived member JWT —
see [Authentication § End-User Access](../authentication.md#end-user-access)
for how to mint and use it.

## CLI Smoke Test

```bash
loyaltyrails members balance \
  --external-id customer_123 \
  --external-id-type customer_id
```

The CLI checks the active integration profile for `read` scope before calling the external-ID balance lookup route.

## Errors

| HTTP | Notes |
| --- | --- |
| `400` | Malformed JSON, validation failure, or (suspend/reactivate) a status no-op |
| `401` | Missing or invalid API key/session/operator token |
| `403` | Valid credential lacks required scope or permission (includes the suspend/reactivate gap above) |
| `404` | Member not found, program not found, or program outside credential reach |
| `500` | Database or event-store failure |

## Out Of Scope Here

`backend/src/api/balance.rs` (`GET /alp/v1/balance?wallet=...`, JWT-authed)
is a different, legacy wallet-address balance lookup on the `/alp/v1`
surface — it predates the member-identity model on this page and is not
part of the member CRUD/lifecycle surface. See
[Authentication](../authentication.md) and the
[API Reference](../api-reference.md) for its (legacy) coverage.

## Source References

| Area | Source |
| --- | --- |
| Internal (M2M) member route mounts | `backend/src/api/mod.rs` lines 799-812 |
| Admin member route mounts (dual-mounted at `/admin/v1` and `/internal/v1/admin`) | `backend/src/api/mod.rs` lines 508-535 (CRUD/list/balance/suspend/reactivate) and line 155 (external-ID balance) |
| Member request/response DTOs | `backend/src/api/members.rs` lines 49-161 |
| Create/upsert behavior | `backend/src/api/members.rs` `create_member` |
| Detail and balance behavior | `backend/src/api/members.rs` `get_member`, `get_member_balance` |
| External-ID lookup | `backend/src/api/members.rs` `lookup_member_balance` |
| Suspend/reactivate behavior | `backend/src/api/members.rs` `suspend_member`, `reactivate_member`, `change_member_status` |
| Admin external-ID balance | `backend/src/api/admin/members.rs` |
| Scope enforcement (integration keys) | `backend/src/api/members.rs` `require_member_auth` |
| Permission enforcement (session/operator token) — the suspend/reactivate gap | `backend/src/api/middleware/admin_permissions.rs` `required_admin_permission` |
| Deprecated admin API-key mount scope check | `backend/src/api/middleware/api_key.rs` `require_admin_api_key_scope` |
| Legacy wallet-balance route (out of scope here) | `backend/src/api/balance.rs` |
| Member-token mint/refresh + `/public/v1/members/me/*` | `backend/src/api/member_tokens.rs`, [Authentication](../authentication.md) |
| CLI contract | `api-contracts/loyaltyrails-cli.v1.openapi.json` path `/internal/v1/programs/{programId}/members/balance/lookup` |
| Generated browser route | `packages/cli/src/integration/next-app-router.ts` `balanceRouteContent` |

---

# Rules API

Source: ../docs/api/rules.md
URL: https://docs.rails.sh/rules-api
Markdown: https://docs.rails.sh/markdown/rules-api.md

# Rules API

Source-derived status: rules management is implemented in the backend. List/create/simulate are declared in the CLI OpenAPI contract and supported by operator-token CLI commands. Get/update/delete/pause/activate and the single-rule trace simulator are backend routes but are not all part of the current CLI contract.

## Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `GET` | `/admin/v1/programs/{programId}/rules` | Implemented, contract-declared | Browser session or operator token with `rules:read` |
| `POST` | `/admin/v1/programs/{programId}/rules` | Implemented, contract-declared | Browser session or operator token with `rules:create` |
| `POST` | `/admin/v1/programs/{programId}/rules/simulate` | Implemented, contract-declared | Browser session or operator token with `rules:read` |
| `GET` | `/admin/v1/rules/{ruleId}` | Implemented | Browser session or operator token with `rules:read` |
| `PATCH` | `/admin/v1/rules/{ruleId}` | Implemented | Browser session or operator token with `rules:update` |
| `DELETE` | `/admin/v1/rules/{ruleId}` | Implemented | Browser session or operator token with `rules:delete` |
| `POST` | `/admin/v1/rules/{ruleId}/pause` | Implemented | Browser session or operator token with `rules:update` |
| `POST` | `/admin/v1/rules/{ruleId}/activate` | Implemented | Browser session or operator token with `rules:update` |
| `POST` | `/admin/v1/rules/{ruleId}/simulate` | Implemented backend trace simulator | Browser session or operator token with `rules:read` |

Admin handlers are also mounted under deprecated `/internal/v1/admin/*` for DB-backed API keys with `admin` scope. New human/operator tooling should use `/admin/v1/*`.

## Concepts

Rules evaluate member and event context to produce outcomes. Only `active` rules enter the hot path; `draft`, `paused`, and `expired` rules are persisted and visible to admins but do not evaluate.

Rule types in backend source:

| `ruleType` | Purpose | Contract status |
| --- | --- | --- |
| `bonus` | Multiplies point amount, for example 2x points | Contract-declared; `rules create --type` accepts it |
| `promotion` | Adds a fixed bonus amount | Contract-declared; `rules create --type` accepts it |
| `decay` | Models expiration policy | Contract-declared; `rules create --type` accepts it |
| `stablecoin_mint` (alias `mint_stable` on input) | Queues a USDC-style asset reward — see [Stablecoin Rewards](../stablecoin-rewards.md) | Contract-declared; `rules create --type` does not accept it (CLI command flag is narrower than the wire schema) |
| `integration_action` (alias `vendor_action` on input) | Queues a durable third-party outbound action for async dispatch | Contract-declared; `rules create --type` does not accept it |

`ruleType` values are parsed independently from `config.type` (below) — the backend does not check that they agree. Note the one intentional naming mismatch: the `ruleType` value is `integration_action`, but the corresponding `config.type` tag is `vendor_action`.

## Rule Config Shapes

`config` is a JSON object internally tagged by a required `type` field (`#[serde(tag = "type")]`). A `config` missing `type`, or carrying an unrecognized `type`, is rejected with `400 Invalid config`. Field names are `snake_case`; some fields also accept a `camelCase` alias for the same value (noted below). This applies everywhere `config` appears: [Create Rule](#create-rule), [Update Rule](#update-rule), and [Simulate Unsaved Rule](#simulate-unsaved-rule).

| `config.type` | Fields | Notes |
| --- | --- | --- |
| `bonus` | `multiplier: number` | Multiplies the transaction amount. |
| `promotion` | `bonus_amount` (alias `bonusAmount`): integer · `max_uses` (alias `maxUses`): integer or `null` | Adds a fixed bonus. |
| `decay` | `days_until_expiry` (alias `daysUntilExpiry`): integer · `warning_days` (alias `warningDays`): integer | Point expiration policy. |
| `tier_upgrade` | `target_tier: string` · `threshold: integer` | No corresponding `ruleType` value — only reachable via `config.type` directly. |
| `badge_award` | `badge_id: string` · `badge_name: string` | No corresponding `ruleType` value. |
| `offer_unlock` | `offer_id: string` · `offer_name: string` | No corresponding `ruleType` value. |
| `stablecoin_mint` (alias `mint_stable`) | `amount_base_units` (aliases `amount`, `amountBaseUnits`): integer · `display_amount` (alias `displayAmount`): string or `null` · `currency` (aliases `asset_code`, `assetCode`, `reward_asset_code`, `rewardAssetCode`; defaults to `"USDC"`): string | See [Stablecoin Rewards](../stablecoin-rewards.md) for validation rules (for example, `display_amount` must match `amount_base_units`). |
| `vendor_action` | `vendor_namespace` (alias `vendorNamespace`): string · `action_type` (alias `actionType`): string · `runtime_adapter`/`runtimeAdapter`, `action_key`/`actionKey`, `source_event_type`/`sourceEventType`, `consent_purpose`/`consentPurpose`, `idempotency_key_template`/`idempotencyKeyTemplate`: optional strings · `payload_template`/`payloadTemplate`: object, defaults to `{}` | The corresponding `ruleType` value is `integration_action`, not `vendor_action`. |

## Rule Shape

```json
{
  "id": "6c827eba-cb56-4b6b-9c52-06f1da99af63",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "ruleType": "bonus",
  "name": "Double points on mobile orders",
  "description": "2x points for mobile checkout",
  "config": {
    "type": "bonus",
    "multiplier": 2
  },
  "conditions": [
    { "type": "event_type", "event_types": ["transaction.completed"] },
    { "type": "channel", "channels": ["mobile"] },
    { "type": "min_amount", "amount": 1000 }
  ],
  "priority": 10,
  "status": "active",
  "startsAt": "2026-05-02T00:00:00Z",
  "endsAt": "2026-06-02T00:00:00Z",
  "createdBy": "operator-token:...",
  "createdAt": "2026-05-02T15:04:05Z",
  "updatedAt": "2026-05-02T15:04:05Z",
  "builderMetadata": {
    "nodes": [],
    "edges": []
  }
}
```

`builderMetadata` is stored and returned for the visual builder. The rule engine ignores it.

## Create Rule

```http
POST /admin/v1/programs/{programId}/rules
Authorization: Bearer lr_cli_...
Content-Type: application/json
```

```json
{
  "ruleType": "promotion",
  "name": "First purchase bonus",
  "config": {
    "type": "promotion",
    "bonusAmount": 500,
    "maxUses": 1
  },
  "conditions": [
    { "type": "event_type", "event_types": ["transaction.completed"] },
    { "type": "first_purchase" }
  ],
  "priority": 20,
  "status": "draft",
  "builderMetadata": {
    "layout": "canvas-v1"
  }
}
```

`status` is optional. Missing or empty status defaults to `active` for backward compatibility. Unknown status strings return `400`; typos are not silently coerced.

## Update Rule

```http
PATCH /admin/v1/rules/{ruleId}
Authorization: Bearer lr_cli_...
Content-Type: application/json
```

```json
{
  "name": "Double points on mobile orders (updated)",
  "config": {
    "type": "bonus",
    "multiplier": 3
  },
  "priority": 15,
  "updatedBy": "operator-token:jane@acme.com"
}
```

`updatedBy` is **required** on every update, unlike `createdBy` on create (which is ignored — attribution is derived from the caller's session/token). All other fields are optional; a field that is present replaces the current value, and a field that is omitted is left unchanged. `startsAt`/`endsAt` are the exception: if either key is present in the request, both are overwritten together from the request body — sending only `startsAt` without `endsAt` clears `endsAt` to `null` rather than leaving it unchanged. The response is the updated rule (see [Rule Shape](#rule-shape)).

## Conditions

Conditions are an AND list: every condition must match.

Backend-supported condition tags:

| Condition | Shape |
| --- | --- |
| Day of week | `{ "type": "day_of_week", "days": [1, 2] }` where `0` is Sunday |
| Time range | `{ "type": "time_range", "start_hour": 9, "end_hour": 17 }` |
| Min/max amount | `{ "type": "min_amount", "amount": 1000 }`, `{ "type": "max_amount", "amount": 5000 }` |
| Segment | `{ "type": "member_segment", "segments": ["gold"] }` |
| Transaction count | `{ "type": "transaction_count", "operator": "gte", "count": 3 }` |
| First purchase | `{ "type": "first_purchase" }` |
| Event type | `{ "type": "event_type", "event_types": ["transaction.completed"] }` |
| Channel | `{ "type": "channel", "channels": ["mobile"] }` |
| Location | `{ "type": "location_id", "location_ids": ["store_12"] }` |
| Member tier | `{ "type": "member_tier", "tiers": ["gold"] }` |
| Payload attribute | `{ "type": "payload_attribute", "path": "/items/0/category", "op": "eq", "value": "apparel" }` |
| Streak/activity | `{ "type": "min_consecutive_days", "days": 3 }`, `{ "type": "max_days_since_activity", "days": 14 }` |

Supported comparison operators include `eq`, `gt`, `gte`, `lt`, `lte`, and `contains` for string/array payload checks.

## Simulate Unsaved Rule

`POST /admin/v1/programs/{programId}/rules/simulate` parses a `config` and projects its point-calculation effect against each of `testTransactions`. It does not persist a rule, and its request schema has no `conditions` field at all — this endpoint never evaluates a condition list; `matched` is derived solely from `config.type`.

`testTransactions` fields (every field is optional — an entry may be `{}`):

| Field | Type | Default |
| --- | --- | --- |
| `amount` | integer | `0` — so event-shaped fixtures with no monetary amount (for example `{"eventType": "member.registered"}`) still parse |
| `eventType` | string or `null` | `null`; echoed into the result `reason` for context, not matched against |
| `dayOfWeek` | integer or `null` | `null` |
| `hour` | integer or `null` | `null` |
| `memberSegment` | string or `null` | `null` |
| `transactionCount` | integer or `null` | `null` |
| `isFirstPurchase` | boolean or `null` | `null` |

If `testTransactions` is omitted or empty, the endpoint runs 3 built-in fixtures (amounts 100/500/1000 on Monday/Tuesday/Saturday) instead of erroring.

```json
{
  "config": {
    "type": "bonus",
    "multiplier": 2
  },
  "testTransactions": [
    {
      "amount": 2500,
      "dayOfWeek": 2,
      "hour": 14,
      "memberSegment": "gold",
      "transactionCount": 3,
      "isFirstPurchase": false
    }
  ]
}
```

Response:

```json
{
  "config": {
    "type": "bonus",
    "multiplier": 2
  },
  "results": [
    {
      "transactionIndex": 0,
      "matched": true,
      "originalAmount": 2500,
      "calculatedAmount": 5000,
      "bonusApplied": 2,
      "reason": null
    }
  ],
  "summary": {
    "totalTransactions": 1,
    "matchedCount": 1,
    "matchRatePct": "100.0%",
    "totalOriginalAmount": 2500,
    "totalCalculatedAmount": 5000,
    "totalBonusAmount": 2500
  }
}
```

## Simulate Saved Rule (Trace)

`POST /admin/v1/rules/{ruleId}/simulate` runs the saved rule's full condition list against one sample context and returns a step-by-step trace plus a dry-run outcome preview. It reads `config` and `conditions` from the stored rule identified by `ruleId` — the request body carries only the sample context, never a `config`. It is read-only: no rule state changes, no counters increment, and it never calls into the hot path.

```http
POST /admin/v1/rules/{ruleId}/simulate
Authorization: Bearer lr_cli_...
Content-Type: application/json
```

```json
{
  "sample": {
    "amount": 2500,
    "dayOfWeek": 2,
    "hour": 14,
    "memberSegment": "gold",
    "memberTier": "gold",
    "transactionCount": 3,
    "isFirstPurchase": false,
    "eventType": "transaction.completed",
    "channel": "mobile",
    "locationId": "store_12",
    "consecutiveDays": 5,
    "daysSinceLastActivity": 1,
    "payload": {}
  }
}
```

`sample.amount`, `sample.dayOfWeek`, and `sample.hour` are required. `memberSegment`, `memberTier`, `eventType`, `channel`, and `locationId` default to `null`; `transactionCount`, `consecutiveDays`, and `daysSinceLastActivity` default to `0`; `isFirstPurchase` defaults to `false`; `payload` defaults to `{}`. There is no wall-clock fallback — the caller supplies `dayOfWeek`/`hour` explicitly, so a Tuesday-only rule can be simulated on any day.

Response:

```json
{
  "matched": true,
  "trace": [
    {
      "index": 0,
      "kind": "channel",
      "passed": true,
      "detail": "channel=Some(\"mobile\") ∈ [\"mobile\"] · ok"
    }
  ],
  "outcome": {
    "kind": "bonus",
    "multiplier": 2.0,
    "baseAmount": 2500,
    "calculatedAmount": 5000,
    "bonusApplied": 2500
  },
  "ruleStatus": "active"
}
```

`trace` has one entry per condition on the saved rule, in declaration order, and always runs to completion (a failing condition does not short-circuit later entries). `outcome` is present only when every condition matched (`matched: true`) and is tagged by `kind`, mirroring the rule's `config.type` (`bonus`, `promotion`, `decay`, `tier_upgrade`, `badge_award`, `offer_unlock`, `stablecoin_mint`, `vendor_action`) with `camelCase` fields matching the corresponding entry in [Rule Config Shapes](#rule-config-shapes). `ruleStatus` echoes the saved rule's current lifecycle status — a `paused` or `draft` rule can still show `matched: true` here for preview purposes without ever firing in production.

## Lifecycle

| Status | Meaning |
| --- | --- |
| `draft` | Stored and listable; excluded from rule evaluation |
| `active` | Eligible for evaluation when time bounds match |
| `paused` | Stored but excluded from evaluation |
| `expired` | Stored but excluded from evaluation |

Lifecycle routes currently support `pause` and `activate`. Expiration is represented in the domain model and by time bounds, but there is no explicit public `expire` route in the mounted API.

## CLI Commands

Rules CLI commands use an operator token, not an integration API key:

```bash
loyaltyrails auth login --operator-token lr_cli_... --api-url http://localhost:8080

loyaltyrails rules list --program <program_uuid>

loyaltyrails rules create \
  --program <program_uuid> \
  --type bonus \
  --name "Double points" \
  --config '{"type":"bonus","multiplier":2}'

loyaltyrails rules simulate \
  --program <program_uuid> \
  --config '{"type":"promotion","bonusAmount":500}'
```

## Errors

| HTTP | Notes |
| --- | --- |
| `400` | Invalid rule type, config, condition, status, or simulation body |
| `401` | Missing or invalid session/operator token/API key |
| `403` | Missing permission such as `rules:create` or `rules:update` |
| `404` | Program or rule not found within caller scope |
| `500` | Database, event-store, or cache invalidation failure |

## Source References

| Area | Source |
| --- | --- |
| Rule route declarations | `backend/src/api/mod.rs` lines 126-143 (inside `build_admin_handler_routes`) |
| Dual mount (`/admin/v1` session + `/internal/v1/admin` API-key) and permission/auth layering | `backend/src/api/mod.rs` lines 1360-1404; permission strings in `backend/src/api/middleware/admin_permissions.rs` lines 141-160; session-or-operator-token acceptance in `backend/src/api/middleware/operator.rs` |
| Rule DTOs (`RuleDto`, `CreateRuleRequest`, `UpdateRuleRequest`) | `backend/src/api/admin/rules.rs` lines 26-108 |
| Create/list/get/update/pause/activate/delete handlers | `backend/src/api/admin/rules.rs` lines 254-763 |
| Unsaved-rule simulate (`SimulateRuleRequest`/`TestTransaction`/response) | `backend/src/api/admin/rules.rs` lines 765-1048 |
| Saved-rule trace simulate (`SimulateByIdRequest`, handler) | `backend/src/api/admin/rules.rs` lines 1370-1421 |
| `SampleContext`, `EvalStep`, `SimulatedOutcome`, `SimulationResult`, `simulate()` | `backend/src/services/rule_simulator.rs` lines 44-359 |
| Rule types, status, conditions, config (`RuleType`, `RuleStatus`, `RuleCondition`, `RuleConfig`) | `backend/src/domain/rule.rs` lines 14-302 |
| Draft status integration coverage | `backend/tests/rule_draft_status.rs` |
| CLI contract | `api-contracts/loyaltyrails-cli.v1.openapi.json` paths `/admin/v1/programs/{programId}/rules` and `/rules/simulate`, and schemas `RuleType`/`CreateRuleRequest`/`SimulateRuleRequest` |
| CLI commands | `packages/cli/src/commands.ts` `rules` command group (`parseRuleType` restricts `--type` to `bonus`/`promotion`/`decay`) |

---

# Games API

Source: ../docs/api/games.md
URL: https://docs.rails.sh/games-api
Markdown: https://docs.rails.sh/markdown/games-api.md

# Games API

Source-derived status: the game surface runtime routes are implemented and declared in the CLI OpenAPI contract. Experience and campaign setup routes are implemented under the admin API; the core list/create/publish/activate/attach routes are contract-declared, while additional admin routes such as prize pools, sessions, personalization rules, pause/schedule, audience preview, experience metrics/preview, leaderboards, and the question bank are backend-declared but not all in the CLI contract.

## Runtime Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `POST` | `/internal/v1/games/resolve` | Implemented, contract-declared | Integration API key with `read`, `write`, or `admin` scope |
| `POST` | `/internal/v1/games/sessions` | Implemented, contract-declared | Integration API key with `write` or `admin` scope |
| `POST` | `/internal/v1/games/sessions/{sessionId}/actions` | Implemented, contract-declared | Integration API key with `write` or `admin` scope |
| `POST` | `/internal/v1/games/sessions/{sessionId}/complete` | Implemented, contract-declared | Integration API key with `write` or `admin` scope |
| `GET` | `/internal/v1/games/programs/{programId}/members/{memberId}/reward-state` | Implemented, backend-only | Integration API key with `read`, `write`, or `admin` scope |

Runtime routes are server-to-server. Browser apps should call a host app route that holds the integration API key server-side.

## Setup Route Summary

| Method | Path | Status | Auth |
| --- | --- | --- | --- |
| `GET`/`POST` | `/admin/v1/programs/{programId}/experiences` | Implemented, contract-declared | `games:read` for GET, `games:create` for POST |
| `GET`/`PUT` | `/admin/v1/experiences/{experienceId}` | Implemented | `games:read` for GET, `games:update` for PUT |
| `GET` | `/admin/v1/experiences/{experienceId}/metrics` | Implemented | `games:read` |
| `POST` | `/admin/v1/experiences/{experienceId}/publish` | Implemented, contract-declared | `games:update` |
| `POST` | `/admin/v1/experiences/{experienceId}/pause` | Implemented | `games:update` |
| `GET`/`POST` | `/admin/v1/experiences/{experienceId}/prize-pool` | Implemented | `games:read` for GET, `games:update` for POST |
| `GET` | `/admin/v1/experiences/{experienceId}/sessions` | Implemented | `games:read` |
| `POST` | `/admin/v1/experiences/{experienceId}/preview` | Implemented | `games:read` (cold-path dry run; no inventory mutated) |
| `GET`/`POST` | `/admin/v1/programs/{programId}/leaderboards` | Implemented | `games:read` for GET, `games:create` for POST |
| `GET` | `/admin/v1/leaderboards/{leaderboardId}` | Implemented | `games:read` |
| `POST` | `/admin/v1/leaderboards/{leaderboardId}/rebuild-ranks` | Implemented | `games:update` |
| `GET` | `/admin/v1/leaderboards/{leaderboardId}/sse` | Implemented | `games:read` (server-sent events, polled every 5s) |
| `GET`/`POST` | `/admin/v1/programs/{programId}/campaigns` | Implemented, contract-declared | `games:read` for GET, `games:create` for POST |
| `GET`/`PUT` | `/admin/v1/campaigns/{campaignId}` | Implemented | `games:read` for GET, `games:update` for PUT |
| `POST` | `/admin/v1/campaigns/{campaignId}/activate` | Implemented, contract-declared | `games:update` |
| `POST` | `/admin/v1/campaigns/{campaignId}/schedule` | Implemented | `games:update` |
| `POST` | `/admin/v1/campaigns/{campaignId}/pause` | Implemented | `games:update` |
| `POST` | `/admin/v1/campaigns/{campaignId}/experiences` | Implemented, contract-declared | `games:update` |
| `DELETE` | `/admin/v1/campaigns/{campaignId}/experiences/{experienceId}` | Implemented | `games:update` |
| `GET`/`POST` | `/admin/v1/campaigns/{campaignId}/personalization-rules` | Implemented | `games:read` for GET, `games:update` for POST |
| `GET` | `/admin/v1/campaigns/{campaignId}/audience/preview` | Implemented | `games:read` |
| `POST` | `/admin/v1/members/{memberId}/segments` | Implemented | `games:update` |
| `GET`/`POST` | `/admin/v1/programs/{programId}/questions` | Implemented | `content:read` for GET, `content:generate` for POST |
| `GET`/`DELETE` | `/admin/v1/questions/{questionId}` | Implemented | `content:read` for GET, `content:approve` for DELETE |
| `POST` | `/admin/v1/questions/{questionId}/status` | Implemented | `content:approve` |
| `POST` | `/admin/v1/programs/{programId}/questions/generate` | Implemented | `content:generate` (LLM-backed) |

## Auth Model

Runtime APIs use `X-API-Key` on `/internal/v1/games/*`.

Setup/admin APIs use `/admin/v1/*` with browser session or operator CLI token. A deprecated `/internal/v1/admin/*` mount exists for DB-backed API keys with `admin` scope, but new tooling should use operator tokens or sessions.

Permission scopes on setup routes are `games:read` / `games:create` / `games:update` for experiences, leaderboards, campaigns, and member-segment overrides. The question bank uses a separate `content:*` permission family (`content:read`, `content:generate`, `content:approve`) shared with the intelligence/content-generation surface, not `games:*`.

## Experience vs Campaign

An experience is the game definition: mechanic, display config, visual theme, session policy, and publish status. Supported mechanics are `spin_wheel`, `onboarding_challenge`, `scratch_off`, and `quiz_trivia`.

A campaign packages one or more experiences with audience targeting, schedule, budget config, and personalization. Attaching an experience to any campaign flips its `campaign_gated` flag; at runtime, only active attached campaigns can make that experience visible through campaign resolution. Runtime `resolve` may return both standalone experiences and campaign-provided experiences; campaign-provided entries include `campaignId`.

## Leaderboards

A leaderboard is optionally scoped to one experience (`experienceId`) and ranks members by a `scoreStrategy` (for example `sum`). `GET /admin/v1/leaderboards/{id}` and the `rebuild-ranks` endpoint return the leaderboard plus ranked entries (`memberId`, `displayName`, `score`, `rank`, `tierSnapshot`, and, when the leaderboard has an `experienceId`, `streakCount` and `trajectory`). Display names are deterministically anonymized from tier + member id — no PII is exposed. The `sse` endpoint streams the same entry shape as a `leaderboard` server-sent event, polling every 5 seconds.

## Question Bank

The question bank stores reusable `onboarding_challenge` questions per program, independent of any single experience. Questions carry a `category`, `questionType`, optional `options`, a `captureField` (the member-profile field an answer is written to), a `source` (`manual` or LLM-generated), `priority`, and audience `conditions`. `POST /admin/v1/programs/{programId}/questions/generate` drafts a new question via the LLM content pipeline; `POST /admin/v1/questions/{questionId}/status` transitions a question's approval status. Question bank routes are gated by `content:*` permissions, not `games:*` — see Auth Model above.

## Resolve Playable Experiences

```http
POST /internal/v1/games/resolve
X-API-Key: lr_test_...
Content-Type: application/json
```

```json
{
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111"
}
```

Illustrative response:

```json
[
  {
    "experienceId": "4c8bcfd5-4122-4dd4-9d96-7ac066411111",
    "mechanicType": "spin_wheel",
    "playableConfig": {
      "mechanicType": "spin_wheel",
      "segments": [
        { "label": "100 points", "color": "#22c55e" },
        { "label": "Try again", "color": "#94a3b8" }
      ],
      "spinDurationMs": 3000
    },
    "displayConfig": {},
    "renderedContent": "Spin for a reward",
    "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111",
    "personalized": false,
    "visualTheme": {},
    "sessionExpirySeconds": 1800
  }
]
```

`playableConfig` is client-safe. For example, spin-wheel prize keys and weights are stripped; quiz correct answers are not included in resolve output.

## Start Session

```http
POST /internal/v1/games/sessions
X-API-Key: lr_test_...
Content-Type: application/json
```

```json
{
  "experienceId": "4c8bcfd5-4122-4dd4-9d96-7ac066411111",
  "memberId": "8d7f5f18-4a35-4c73-9c58-0e6e7d2cb111",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111",
  "idempotencyKey": "game_session_123",
  "surface": "web",
  "fingerprint": "optional-device-or-session-ref"
}
```

Response:

```json
{
  "sessionId": "11cc7691-f220-4493-9d88-655d50a11111",
  "experienceId": "4c8bcfd5-4122-4dd4-9d96-7ac066411111",
  "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111",
  "maxActions": 1,
  "expiresAt": "2026-05-02T15:34:05Z",
  "alreadyExisted": false
}
```

Session start is idempotent by `(programId, idempotencyKey)`. Reusing the key with the same member and experience returns the existing session with `alreadyExisted: true`; reusing it with a different member or experience is rejected.

Campaign-gated experiences require a `campaignId` from `resolve`. When supplied, the engine checks that the campaign is active, attached to the experience, and that the member matches the campaign audience.

## Submit Action

```http
POST /internal/v1/games/sessions/{sessionId}/actions
X-API-Key: lr_test_...
Content-Type: application/json
```

```json
{
  "sequence": 1,
  "actionType": "spin",
  "payload": {}
}
```

Illustrative response:

```json
{
  "sessionId": "11cc7691-f220-4493-9d88-655d50a11111",
  "sequence": 1,
  "mechanicState": {
    "mechanicType": "spin_wheel",
    "segment_index": 0
  },
  "prize": {
    "prizeKey": "points_100",
    "prizeLabel": "100 points",
    "prizeValueCents": 0,
    "isNoPrize": false,
    "segmentIndex": 0
  },
  "outcomesApplied": ["Awarded 100 points"],
  "sessionComplete": true
}
```

`mechanicState` is internally tagged on `mechanicType` (not `type`), and its per-mechanic fields keep their Rust snake_case names (`segment_index`, `cells_revealed`, `total_cells`, `correct_index`, `points_earned`, `correct_count`, `total_questions`, `step_completed`, `total_steps`) rather than the camelCase used elsewhere in the response — the enum's field-level serde attributes don't inherit the container's `rename_all`.

Mechanic-specific payloads:

| Mechanic | Action payload |
| --- | --- |
| `spin_wheel` | Usually `{}`; one action auto-completes |
| `onboarding_challenge` | `{ "answer": ... }`; answer is stored in member profile for the configured field |
| `scratch_off` | `{ "cellIndex": 0 }`; repeated cells and out-of-range cells are rejected |
| `quiz_trivia` | `{ "answerIndex": 1 }`; answer index is required |

Actions are sequence-numbered starting at `1`; out-of-order submissions are rejected.

## Complete Session

```http
POST /internal/v1/games/sessions/{sessionId}/complete
X-API-Key: lr_test_...
```

Explicit completion is useful for multi-step mechanics. If the session is already completed, the endpoint returns the stored outcome summary. Otherwise it applies completion rewards where relevant and writes a `GameSessionCompleted` event.

Illustrative response:

```json
{
  "completed": true,
  "actionCount": 3,
  "outcomesApplied": ["Awarded 250 points"]
}
```

## Session IDs vs Generated Session Tokens

The backend runtime API uses raw UUID `sessionId` path parameters for submit and complete.

Generated app routes should not expose raw backend session IDs to browsers. The Next.js and Hydrogen recipes call `start`, remove `sessionId` from the browser response, and return a signed `sessionToken` instead. Later browser calls send `sessionToken`; the host route verifies the HMAC, checks the token belongs to the current member, extracts the backend `sessionId`, and proxies to rails.

For generated routes, set `LOYALTYRAILS_GAME_SESSION_SECRET` server-side. It is a host-app signing secret, not a rails API credential.

## CLI Smoke Test

```bash
loyaltyrails games resolve --member-id <member_uuid>

loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --campaign-id <campaign_uuid> \
  --idempotency-key game_session_123

loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{}'

loyaltyrails games complete --session-id <session_uuid>
```

The CLI smoke commands use integration API-key profiles. Setup commands such as `experiences create`, `experiences publish`, `campaigns create`, and `campaigns activate` use operator tokens.

## Errors

| HTTP | Notes |
| --- | --- |
| `400` | Invalid mechanic config, idempotency key reused for another member/experience, invalid sequence, invalid action payload, ineligible campaign |
| `401` | Missing or invalid API key/session/operator token |
| `403` | Missing API-key scope or admin permission |
| `404` | Session, program, experience, campaign, or member not found within credential reach |
| `429` | Session start rate limit exceeded |
| `500` | Database, cache, prize pool, or outcome execution failure |

## Source References

| Area | Source |
| --- | --- |
| Runtime route mounts | `backend/src/api/mod.rs` lines 834-852 |
| Admin route mounts | `backend/src/api/mod.rs` games section in `build_admin_handler_routes` (lines ~352-469) |
| Runtime DTOs and auth checks | `backend/src/games/api/surface.rs` |
| Runtime response shapes | `backend/src/games/service/engine.rs` lines 31-85 |
| Resolve behavior | `backend/src/games/service/engine.rs` `resolve_experience` |
| Start idempotency, gating, max actions | `backend/src/games/service/engine.rs` `start_session` (lines 565-967) |
| Submit and complete behavior | `backend/src/games/service/engine.rs` `submit_action` (line 967) and `complete_session` (line 1622) |
| Experience admin DTOs | `backend/src/games/api/admin.rs` |
| Campaign admin DTOs and lifecycle | `backend/src/games/api/campaigns.rs` and `backend/src/games/domain/campaign.rs` |
| Mechanic-state wire shape | `backend/src/games/domain/types.rs` `MechanicState` |
| Leaderboard admin DTOs | `backend/src/games/api/leaderboard.rs` |
| Question bank admin DTOs | `backend/src/games/api/question_bank.rs` |
| Setup-route permission mapping | `backend/src/api/middleware/admin_permissions.rs` |
| CLI contract | `api-contracts/loyaltyrails-cli.v1.openapi.json` `/internal/v1/games/*`, experiences, and campaigns paths |
| Generated session-token route | `packages/cli/src/integration/next-app-router.ts` `gameSessionRouteContent` |

---

# Campaigns API

Source: ../docs/api/campaigns.md
URL: https://docs.rails.sh/campaigns-api
Markdown: https://docs.rails.sh/markdown/campaigns-api.md

# Campaigns API

Source-derived status: campaign create/read/list/update, the schedule /
activate / pause lifecycle, experience attachment, personalization rules,
audience preview, and manual member-segment tagging are all implemented,
dual-mounted on `/admin/v1` (session/operator, primary) and the deprecated
`/internal/v1/admin` API-key mirror — the same pattern documented in
[Programs API](./programs.md#auth-model).

This page is the deep dive on campaign CRUD, scheduling, and audience
targeting. [Games API](./games.md#experience-vs-campaign) covers how an
active campaign gates experience visibility at resolve time; read that page
for the runtime (member-facing) side of campaigns.

## Route Summary

| Method | Path | Auth |
| --- | --- | --- |
| `POST` | `/admin/v1/programs/{programId}/campaigns` | Session/operator with `games:create`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/programs/{programId}/campaigns` | Session/operator with `games:read`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/campaigns/{campaignId}` | Session/operator with `games:read`; deprecated API-key mirror also works |
| `PUT` | `/admin/v1/campaigns/{campaignId}` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/campaigns/{campaignId}/activate` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/campaigns/{campaignId}/schedule` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/campaigns/{campaignId}/pause` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/campaigns/{campaignId}/experiences` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `DELETE` | `/admin/v1/campaigns/{campaignId}/experiences/{experienceId}` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/campaigns/{campaignId}/personalization-rules` | Session/operator with `games:read`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/campaigns/{campaignId}/personalization-rules` | Session/operator with `games:update`; deprecated API-key mirror also works |
| `GET` | `/admin/v1/campaigns/{campaignId}/audience/preview` | Session/operator with `games:read`; deprecated API-key mirror also works |
| `POST` | `/admin/v1/members/{memberId}/segments` | Session/operator with `games:update`; deprecated API-key mirror also works |

There is no dedicated `resume` route — a paused campaign is resumed the
same way it is first activated, by calling `POST
.../campaigns/{campaignId}/activate` again (see
[Campaign Lifecycle](#campaign-lifecycle) below). There is also no
`complete` or `archive` route: the domain model defines `completed` and
`archived` statuses, but no handler on this surface ever sets them — a
campaign's only reachable statuses today are `draft`, `scheduled`,
`active`, and `paused`. Campaigns end in practice by setting `endsAt` (the
runtime resolve path stops surfacing the campaign once `endsAt` passes) or
by pausing it.

## Auth Model

Campaign routes use the same admin auth stack as
[Programs API](./programs.md#auth-model): browser session cookies or
operator CLI tokens on `/admin/v1`, and a deprecated API-key mount at
`/internal/v1/admin`. Route permissions are feature permissions
(`games:read`, `games:create`, `games:update`), not API-key scopes. Every
route is also tenant-scoped to the campaign's (or, for
`/members/{memberId}/segments`, the member's) owning program: the caller's
organization must own that program, verified by resolving the campaign or
member to its `program_id` and checking it against the caller's
organization scope, the same tenant-scoping check documented in
[Program Ownership](./programs.md#program-ownership). Platform-scope
(cross-org) access requires an explicit `X-Org-Scope-Reason` header and is
audit-logged.

## Create And List Campaigns

```http
POST /admin/v1/programs/{programId}/campaigns
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "name": "Summer Double Points",
  "description": "Double points on purchases for gold-tier members",
  "campaignType": "manual",
  "audienceConfig": {
    "targetAll": false,
    "conditions": [
      { "type": "member_tier", "tiers": ["gold"] }
    ]
  },
  "budgetConfig": {
    "maxPrizePerMemberCents": 5000
  },
  "startsAt": "2026-06-01T00:00:00Z",
  "endsAt": "2026-08-31T23:59:59Z"
}
```

Only `name` is required. `campaignType` defaults to `manual` if omitted and
must be one of `manual`, `scheduled`, `triggered`, `agent_assembled`
(`CampaignType`). When omitted, `audienceConfig` defaults to
`{"targetAll": false, "conditions": []}` and `budgetConfig` defaults to all
four `BudgetConfig` keys serialized as `null` (see
[Audience Targeting](#audience-targeting) and
[Budget Config](#budget-config) below). A newly created
campaign always starts in `draft` status regardless of `campaignType`,
`startsAt`, or `endsAt` — creating a campaign never auto-activates or
auto-schedules it.

Response (`CampaignDto`):

```json
{
  "id": "5c21d943-c848-4452-8ca9-654ec9c11111",
  "programId": "0a7a4b14-8a1d-4fef-8d2b-5d49cc6c55fd",
  "name": "Summer Double Points",
  "description": "Double points on purchases for gold-tier members",
  "campaignType": "manual",
  "status": "draft",
  "startsAt": "2026-06-01T00:00:00Z",
  "endsAt": "2026-08-31T23:59:59Z",
  "audienceConfig": {
    "targetAll": false,
    "conditions": [
      { "type": "member_tier", "tiers": ["gold"] }
    ]
  },
  "budgetConfig": {
    "maxTotalPrizeCents": null,
    "maxPrizePerMemberCents": 5000,
    "maxSessionsTotal": null,
    "maxSessionsPerMember": null
  },
  "createdBy": "operator:ops@acme.example",
  "version": 1,
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-01T12:00:00Z"
}
```

`createdBy` is derived server-side from the caller's identity
(`"<actor_type>:<actor_id>"`, e.g. `operator:ops@acme.example` or
`api_key:lr_live_...`) — a `createdBy` field in the request body is
accepted for backward compatibility but ignored. `CampaignDto` never
includes `agentContext` (an internal, agent-assembly-only field on the
domain model); it is not part of the public response shape.

`budgetConfig` has no field-level omit-if-unset behavior: all four
`BudgetConfig` keys are always present in the response, with unset ones
serialized as literal `null` (as shown above) rather than being left out —
unlike `description`, which is a plain `Option<String>` that also
serializes as `null` when unset, `budgetConfig` itself is never omitted or
`{}`.

```http
GET /admin/v1/programs/{programId}/campaigns?status=active&limit=20
Cookie: <admin session>
```

Response is a bare array of `CampaignDto` (same shape as above), newest
first. `status` is an optional exact-match filter (`draft`, `scheduled`,
`active`, `paused`, `completed`, or `archived`); `limit` defaults to `50`.

```http
GET /admin/v1/campaigns/{campaignId}
Cookie: <admin session>
```

Returns a single `CampaignDto`, `404` if not found or outside the
caller's tenant reach.

## Update Campaign

```http
PUT /admin/v1/campaigns/{campaignId}
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "name": "Summer Double Points (Extended)",
  "description": "Double points on purchases for gold-tier members",
  "audienceConfig": {
    "targetAll": false,
    "conditions": [
      { "type": "member_tier", "tiers": ["gold", "platinum"] }
    ]
  },
  "budgetConfig": {
    "maxPrizePerMemberCents": 5000
  },
  "startsAt": "2026-06-01T00:00:00Z",
  "endsAt": "2026-09-30T23:59:59Z"
}
```

This is a **full-replace update**: `name` is the only required field, but
every other field is replaced wholesale with whatever the request
supplies — there is no partial-patch semantics. Omitting `audienceConfig`
resets it to its empty default (`{"targetAll": false, "conditions": []}`,
wiping out existing targeting), and omitting `budgetConfig` resets every
`BudgetConfig` field to `null` (serialized as all four keys with `null`
values, per [Budget Config](#budget-config) below — not `{}`), wiping out
existing budget caps. Omitting `description`, `startsAt`, or `endsAt`
likewise clears each to `null`. Always send the full desired campaign
shape, not a diff. The update is rejected with `400` if the campaign is
not currently `draft`, `scheduled`, or `paused` — an `active` (or
`completed`/`archived`) campaign cannot be updated in place; pause it
first. Response is the updated `CampaignDto`.

## Campaign Lifecycle

```http
POST /admin/v1/campaigns/{campaignId}/schedule
Cookie: <admin session>
```

`draft` → `scheduled`. Rejected with `400` if the campaign is not
currently `draft`, or if it has no `startsAt` set (a scheduled campaign
without a start time could never be picked up by the activation worker).

```http
POST /admin/v1/campaigns/{campaignId}/activate
Cookie: <admin session>
```

`draft`, `scheduled`, **or `paused`** → `active`. This is the only way to
resume a paused campaign — there is no separate `resume` endpoint;
calling `activate` again on a `paused` campaign moves it back to `active`.
Rejected with `400` from any other status (including `active` itself —
calling activate twice is not a no-op).

```http
POST /admin/v1/campaigns/{campaignId}/pause
Cookie: <admin session>
```

`active` → `paused` only. Rejected with `400` (`"Campaign not found or not
currently active"`) if the campaign isn't currently `active`.

Response (all three; `CampaignDto`) reflects the new `status`. All three
routes take no request body.

There is no `complete` transition on this API. `CampaignStatus` includes
`completed` and `archived` variants and the domain model has an internal
`complete()` method, but no route calls it — it is unreachable dead code
today. A campaign's natural end is its `endsAt` timestamp (the runtime
resolve path in [Games API](./games.md#experience-vs-campaign) stops
surfacing it once `endsAt` passes, without changing its stored `status`),
or an operator pausing it.

## Audience Targeting

`audienceConfig` (`AudienceConfig`) has two fields:

```json
{
  "targetAll": false,
  "conditions": [
    { "type": "member_tier", "tiers": ["gold", "platinum"] }
  ]
}
```

- `targetAll: true` matches every member in the program; `conditions` must
  be empty in that case — sending both `targetAll: true` and a non-empty
  `conditions` array is rejected with `400` as ambiguous.
- With `targetAll: false`, each entry in `conditions` is a tagged object
  (`"type"` selects the variant) and **all** conditions must match a
  member for the campaign to apply (AND semantics). An empty
  `conditions` array with `targetAll: false` — the default when
  `audienceConfig` is omitted entirely — matches **every** member, not
  none; there is no "matches nobody" default. Be explicit: an
  intentionally narrow campaign needs at least one condition.
- An unrecognized `"type"` value, or a condition object missing the
  `"type"` tag, fails to deserialize and the whole create/update request
  is rejected with `400` — it does not silently drop the bad condition.

Audience-eligible condition types (usable in campaign `audienceConfig`):

| `type` | Fields | Matches when |
| --- | --- | --- |
| `member_tier` | `tiers: string[]` | member's tier is (case-insensitively) one of `tiers` |
| `member_segment` | `segments: string[]` | member has a segment matching one of `segments` (see [Member Segments](#member-segments)) |
| `transaction_count` | `operator, count` | member's transaction count compares against `count` |
| `consecutive_days` | `days: number` | member's consecutive active-days streak is `>= days` |
| `max_days_since_activity` | `days: number` | member has activity within the last `days` days (no activity ever = no match) |
| `engagement_tier` | `tiers: string[]` | member's computed engagement tier is one of `tiers` |
| `profile_attribute` | `path, op, value` | the member profile's JSON-pointer field at `path` compares against `value` |
| `member_ids` | `ids: string[]` (UUIDs) | member's id is in `ids` |

`operator`/`op` is one of `eq`, `ne`, `lt`, `lte`, `gt`, `gte`
(`ComparisonOp`). Two further condition types — `progression_level` and
`progression_xp` — exist on the same enum but are **personalization-only**;
using either in a campaign's `audienceConfig` is rejected with `400`
(they are valid in [personalization rule](#personalization-rules)
`conditions` instead, where they can reference a member's progress on the
specific experience being resolved).

### Audience Preview

```http
GET /admin/v1/campaigns/{campaignId}/audience/preview
Cookie: <admin session>
```

For `targetAll: true`, returns a count of the program's active members:

```json
{ "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111", "targetAll": true, "estimatedSize": 4820 }
```

For a conditioned audience, evaluates conditions against up to 10,000
sampled active members in the program (not the full membership for very
large programs):

```json
{
  "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111",
  "targetAll": false,
  "matchingMembers": 612,
  "sampleSize": 10000,
  "conditionCount": 1
}
```

## Budget Config

`budgetConfig` (`BudgetConfig`) is stored as-is and echoed back on every
campaign response; all fields are optional:

```json
{
  "maxTotalPrizeCents": 500000,
  "maxPrizePerMemberCents": 5000,
  "maxSessionsTotal": 10000,
  "maxSessionsPerMember": 20
}
```

Only `maxPrizePerMemberCents` is currently enforced — the reward engine
reads it at prize-award time and caps payouts per member for sessions
attributed to this campaign. `maxTotalPrizeCents`, `maxSessionsTotal`, and
`maxSessionsPerMember` are persisted and returned but not enforced by any
running code path today; treat them as reserved/advisory until a future
release wires them up.

## Experience Attachment

```http
POST /admin/v1/campaigns/{campaignId}/experiences
Cookie: <admin session>
Content-Type: application/json
```

```json
{ "experienceId": "b2e5b6e0-1111-2222-3333-444455556666", "priority": 10 }
```

Attaches an experience to the campaign (flips the experience's
`campaign_gated` flag — see [Games API](./games.md#experience-vs-campaign)).
Rejected with `400` if the experience belongs to a different program than
the campaign, or is already attached. `priority` defaults to `0`. Response:

```json
{
  "id": "9f1c...",
  "campaignId": "5c21d943-c848-4452-8ca9-654ec9c11111",
  "experienceId": "b2e5b6e0-1111-2222-3333-444455556666"
}
```

```http
DELETE /admin/v1/campaigns/{campaignId}/experiences/{experienceId}
Cookie: <admin session>
```

Detaches the experience; `404` if it wasn't attached to this campaign.
Response: `{ "status": "detached" }`.

## Personalization Rules

Personalization rules layer per-member configuration overrides on top of a
campaign (or a standalone experience) without changing audience
eligibility — they run *after* a member is already deemed eligible.

```http
POST /admin/v1/campaigns/{campaignId}/personalization-rules
Cookie: <admin session>
Content-Type: application/json
```

```json
{
  "experienceId": "b2e5b6e0-1111-2222-3333-444455556666",
  "name": "Boost VIP spin value",
  "description": "VIP segment gets a higher prize multiplier",
  "conditions": [
    { "type": "member_segment", "segments": ["vip"] }
  ],
  "configOverrides": { "prize_value_multiplier": 1.5 },
  "priority": 10
}
```

`experienceId` is optional — omit it for a campaign-wide rule, or set it
to require the experience to already be attached to this campaign
(`400` if it isn't). Unlike campaign `audienceConfig`, `conditions` here
may freely use the personalization-only `progression_level` /
`progression_xp` types alongside the audience-eligible ones.
`configOverrides` is validated to reject any key or value that looks like
it would introduce or mutate a stablecoin reward outcome (asset codes,
amounts, provider identifiers) — configure stablecoin rewards on the
experience or prize pool directly instead; see
[Stablecoin Rewards](../stablecoin-rewards.md). Response
(`PersonalizationRuleDto`) includes a server-assigned `status` of
`"active"` (a rule can later be `"paused"` or `"archived"`, though no
route on this page exposes changing it).

```http
GET /admin/v1/campaigns/{campaignId}/personalization-rules
Cookie: <admin session>
```

Returns a bare array of `PersonalizationRuleDto` for the campaign
(up to 100), ordered by priority.

## Member Segments

Manual segment tagging feeds the `member_segment` audience condition above.

```http
POST /admin/v1/members/{memberId}/segments
Cookie: <admin session>
Content-Type: application/json
```

```json
{ "action": "add", "segment": "vip" }
```

`action` is `add` or `remove` (`400` otherwise). `segment` is a bare
label — the server namespaces it with a `manual:` prefix before storing
it (so `"vip"` is stored as `"manual:vip"`), keeping manually-tagged
segments distinguishable from rule- or system-computed ones. A
`member_segment` audience condition matches on the bare label against any
namespace, so `{"type": "member_segment", "segments": ["vip"]}` matches a
member tagged `manual:vip` (or `rule:vip`, `computed:vip`). Response:

```json
{ "memberId": "c9d1...", "segments": ["manual:vip"] }
```

## Errors

| HTTP | Notes |
| --- | --- |
| `400` | Malformed JSON, invalid `campaignType`/audience condition shape, ambiguous `targetAll`+`conditions` combination, a personalization-only condition used in campaign audience targeting, a stablecoin-shaped `configOverrides` key/value, an experience from a different program, a duplicate experience attachment, or a lifecycle no-op/invalid-state guard (schedule-without-`startsAt`, activate-from-`active`, pause-when-not-`active`, update-on-non-draft/scheduled/paused) |
| `401` | Missing or invalid API key/session/operator token |
| `403` | Valid credential lacks the required `games:*` permission, or a tenant-scope violation |
| `404` | Campaign, program, experience, or member not found, or outside credential/tenant reach |
| `500` | Database or event-store failure |

## Source References

| Area | Source |
| --- | --- |
| Campaign admin route mounts (dual-mounted at `/admin/v1` and `/internal/v1/admin`) | `backend/src/api/mod.rs` lines 407–450 |
| Route permission mapping (`games:read`/`games:create`/`games:update`) | `backend/src/api/middleware/admin_permissions.rs` lines 300–322, 172 |
| Campaign handlers (`create_campaign`, `list_campaigns`, `get_campaign`, `update_campaign`) | `backend/src/games/api/campaigns.rs` lines 204–390 |
| Lifecycle handlers (`activate_campaign`, `pause_campaign`, `schedule_campaign`) | `backend/src/games/api/campaigns.rs` lines 394–626 |
| Experience attach/detach handlers | `backend/src/games/api/campaigns.rs` lines 630–773 |
| Personalization rule handlers | `backend/src/games/api/campaigns.rs` lines 777–1109 |
| Audience preview handler | `backend/src/games/api/campaigns.rs` lines 1113–1187 |
| Member segment handler | `backend/src/games/api/campaigns.rs` lines 1196–1274 |
| `CampaignDto`, `CreateCampaignRequest`, `UpdateCampaignRequest`, `PersonalizationRuleDto` | `backend/src/games/api/campaigns.rs` lines 26–193 |
| `Campaign`, `CampaignType`, `CampaignStatus`, `AudienceConfig`, `AudienceCondition`, `ComparisonOp`, `BudgetConfig` domain model and lifecycle transitions | `backend/src/games/domain/campaign.rs` |
| `AudienceConfig::matches_member` / condition evaluation (audience-matching semantics) | `backend/src/games/service/audience.rs` lines 220–234, 101–151 |
| Campaign repository (`update` status guard, `find_by_program`, `find_active_for_program`) | `backend/src/games/repository/campaigns.rs` |
| Per-member budget cap enforcement (`maxPrizePerMemberCents`) | `backend/src/games/service/engine.rs` lines 2240–2274 |
| Tenant scoping (`OrgScope`, `enforce_program_scope`) | `backend/src/api/admin/org_scope.rs` |
| Campaign-gated experience resolution (runtime/member-facing side) | [Games API](./games.md#experience-vs-campaign) |

---

# CLI

Source: ../docs/cli.md
URL: https://docs.rails.sh/cli
Markdown: https://docs.rails.sh/markdown/cli.md

# rails CLI

The rails CLI helps developers wire an existing app to rails from
inside the app repository. The MVP supports Next.js App Router projects,
Shopify Hydrogen config detection, integration API-key auth, local health
checks, event smoke requests, member balance smoke requests, operator-token
program/API-key/rule/campaign/game setup management, and generated Next.js
recipes.

## Run From The Monorepo

```bash
pnpm install
pnpm --filter @loyaltyrails/cli build
node packages/cli/dist/index.js --help
```

The package exposes both `loyaltyrails` and `lr` binaries when installed as
`@loyaltyrails/cli`.

## Authenticate

Use an integration API key, not an operator session and not the static bootstrap
key.

```bash
loyaltyrails auth login --api-key lr_test_... --api-url http://localhost:8080
loyaltyrails auth status
```

Login introspects the key and stores:

- API URL.
- Key prefix in profile metadata.
- Environment.
- Permission scopes.
- Program reach.
- Accessible program metadata when available.

The raw API key is stored separately in the local CLI credential store so later
commands can authenticate. Treat that credential store as sensitive local
machine state. Project config and command output should only contain non-secret
metadata such as the key prefix.

Generated app integrations require a program-scoped, non-admin key. All-program
or admin keys are rejected for generated app env/config writes.

## Pair This Machine (Browser Approval)

`loyaltyrails auth login --pair` binds this machine to your account without
ever typing a secret into the terminal:

```bash
loyaltyrails auth login --pair
loyaltyrails auth login --pair --no-browser
```

The CLI starts a browser-approval (device) flow: it prints a device code and
an approval URL, and opens the URL in your browser unless `--no-browser` is
passed. Confirm the device code shown in the browser matches your terminal,
then approve. The CLI polls until you decide and stores the issued machine
token locally.

This machine token is scoped narrowly to two things: `loyaltyrails chat` (the
agent JWT exchange) and `loyaltyrails join` (claiming a share/pairing code,
see [Demo Handoff](#demo-handoff)). It is never accepted on admin or
integration-key endpoints, and approving a pairing in the browser requires a
freshly stepped-up session.

## Operator Auth Gate

Control-plane commands are separate from integration API-key auth. The backend
now supports session-issued operator CLI tokens:

```txt
POST /admin/v1/auth/cli-tokens
GET /admin/v1/auth/cli-token/introspect
DELETE /admin/v1/auth/cli-tokens/:token_id
```

Tokens use the `lr_cli_` prefix, are presented as `Authorization: Bearer`, and
are accepted on `/admin/v1/*` control-plane routes that have explicit operator
permission policies. They are not accepted by generated app integrations and
must not be written to host app env files.

Store an issued operator token locally with:

```bash
loyaltyrails auth login --operator-token lr_cli_... --api-url http://localhost:8080
```

Program, API-key, rule, experience, and campaign management commands are
available for operator-token profiles. Account/MFA/session management remains
browser-session only.

## Manage Programs

These commands require an operator-token profile:

```bash
loyaltyrails program list
loyaltyrails program create \
  --name "Acme Rewards" \
  --symbol ACME \
  --issuer "Acme" \
  --reserve-ratio 8000
loyaltyrails program status <program_uuid>
```

`program list` and `program status` require `programs:read`; `program create`
requires `programs:create`. The backend also enforces tenant scope for the
operator token.

## Manage API Keys

These commands require an operator-token profile with `api_keys:manage`:

```bash
loyaltyrails keys list --program <program_uuid>
loyaltyrails keys create \
  --program <program_uuid> \
  --name "Web app" \
  --scopes read,write \
  --environment test
loyaltyrails keys rotate <key_uuid>
loyaltyrails keys revoke <key_uuid>
```

All-program key operations require platform scope and an audit reason:

```bash
loyaltyrails keys list --all-program --reason "support investigation"
loyaltyrails keys create \
  --all-program \
  --name "Platform admin" \
  --scopes admin \
  --reason "support investigation"
```

Created and rotated raw keys are shown once. Use `--save-profile <name>` on
`keys create` or `keys rotate` to immediately store the generated key as a local
integration profile.

## Manage Rules

These commands require an operator-token profile. Listing and simulation require
`rules:read`; creation requires `rules:create`. The backend stamps attribution
from the authenticated operator token and enforces tenant scope for the target
program.

```bash
loyaltyrails rules list --program <program_uuid>
loyaltyrails rules create \
  --program <program_uuid> \
  --name "Tuesday 2x" \
  --type bonus \
  --config '{"type":"bonus","multiplier":2}' \
  --conditions '[{"type":"day_of_week","days":[2]}]' \
  --status draft
loyaltyrails rules simulate \
  --program <program_uuid> \
  --config '{"type":"bonus","multiplier":2}' \
  --test-transactions '[{"amount":100}]'
```

`--config`, `--conditions`, `--builder-metadata`, and `--test-transactions`
accept inline JSON or a file path. Prefixing a file path with `@` is also
accepted.

## Manage Experiences

These commands require an operator-token profile. Listing requires
`games:read`, creation requires `games:create`, and publishing requires
`games:update`.

```bash
loyaltyrails experiences list --program <program_uuid>
loyaltyrails experiences create \
  --program <program_uuid> \
  --name "Spin to win" \
  --mechanic spin_wheel \
  --mechanic-config '{"segments":[]}'
loyaltyrails experiences publish <experience_uuid>
```

The backend derives creator attribution from the authenticated operator and
enforces tenant scope for the owning program. Config options accept inline JSON
or a file path.

## Manage Campaigns

These commands require an operator-token profile. Listing requires `games:read`,
creation requires `games:create`, and activation/experience attachment require
`games:update`.

```bash
loyaltyrails campaigns list --program <program_uuid> --status draft --limit 10
loyaltyrails campaigns create \
  --program <program_uuid> \
  --name "Spring launch" \
  --type manual \
  --audience-config '{"targetAll":true}'
loyaltyrails campaigns attach-experience <campaign_uuid> \
  --experience <experience_uuid> \
  --priority 5
loyaltyrails campaigns activate <campaign_uuid>
```

Campaign and experience setup commands are intentionally operator-auth only.
Generated storefront integrations should still use the integration-auth game
runtime commands below.

## Initialize A Next.js App Router Project

Run this inside the host app:

```bash
loyaltyrails init \
  --program <program_uuid> \
  --external-id-type customer_id \
  --identity-strategy custom
```

This writes non-secret project metadata to `.loyaltyrails/config.json` and
tracks generated files in `.loyaltyrails/manifest.json`.

By default, `init` does not write `.env.local`. To write local development env
values, use an explicit confirmation:

```bash
loyaltyrails init --write-env --yes
```

Production secrets should be configured in the host deployment platform, not by
committing generated env files.

## Agentic Integration Recipes

The CLI uses **integration recipes** for host-app code changes. A recipe is a
reviewed implementation path with project detection, dry-run output,
secret-safety scanning, idempotent manifests, and generated-file markers. It is
not the same thing as a backend vendor connection or runtime adapter.

For example:

- `shopify` is a backend/vendor namespace.
- `hydrogen` is a storefront/framework adapter detected by the CLI.
- `loyaltyrails integrate hydrogen` is the Shopify Hydrogen integration recipe.

Recipes are designed to be adapted to the customer's architecture by the CLI and
agentic apply flow. They should preserve existing routing, auth, deployment, and
identity patterns instead of assuming every third-party implementation is the
same.

## Report Recipe Next Steps

Use the integration recipe report when a developer or coding agent needs the
next safe action before live vendor credentials exist:

```bash
loyaltyrails integrate plan
loyaltyrails integrate plan --json
```

The report is read-only. It detects the local project, reads
`.loyaltyrails/config.json` and `.loyaltyrails/manifest.json` when present, and
does not read raw credentials, call the network, write files, or invoke package
managers.

The current report focuses on the MVP agentic integration layer tracks:

- Shopify/Hydrogen storefront recipe.
- Braze backend readiness recipe.
- mParticle backend readiness recipe.
- SFMC backend readiness recipe.

Structured output includes status, blockers, next commands, expected files,
credential mode, and taxonomy for each track:

- `vendorNamespace`: `shopify`, `braze`, `mparticle`, or
  `salesforce_marketing_cloud` (`sfmc` is accepted as the CLI alias).
- `frameworkAdapter`: `hydrogen` for Shopify Hydrogen, or the initialized local
  framework adapter for backend readiness recipes.
- `integrationRecipe`: the reviewed CLI recipe command, such as
  `integrate hydrogen --webhooks` or `integrate vendor mparticle`.
- `runtimeAdapter`: `none` for this workflow.

`runtimeAdapter: "none"` is intentional. These reports and readiness recipes
help plan customer-owned code and backend connection preparation; they do not
claim that LoyaltyRails owns live vendor dispatch, retries, reconciliation, or
credential resolution.

## Generate Backend Vendor Readiness Recipes

Backend vendor readiness recipes align a host application with an approved
LoyaltyRails backend integration contract. They do not create live vendor
dispatchers, call vendor networks, or store raw credentials.

Supported readiness recipes:

- `braze`
- `mparticle`
- `salesforce_marketing_cloud` (alias: `sfmc`)

Preview and apply:

```bash
loyaltyrails integrate vendor braze --dry-run
loyaltyrails integrate vendor mparticle --dry-run
loyaltyrails integrate vendor sfmc
```

The command requires an initialized project so the generated recipe can record
the current `frameworkAdapter` taxonomy. It writes
`.loyaltyrails/integrations/<vendor>-readiness.md`, updates
`.loyaltyrails/config.json` with the installed readiness recipe, and updates
`.loyaltyrails/manifest.json` with vendor-specific taxonomy:

- `vendorNamespace`: `braze`, `mparticle`, or `salesforce_marketing_cloud`
- `frameworkAdapter`: the initialized local framework adapter
- `integrationRecipe`: `integrate vendor <vendor>`
- `runtimeAdapter`: `none`

Credential fields are secret-manager references only. For example, mParticle
readiness records `MPARTICLE_API_KEY_SECRET_REF` and
`MPARTICLE_API_SECRET_SECRET_REF`; SFMC readiness records
`SFMC_CLIENT_ID_SECRET_REF` and `SFMC_CLIENT_SECRET_SECRET_REF`.

The plan-only agent scaffold can also route vendor requests to these recipes:

```bash
loyaltyrails agent "integrate mParticle Events API" --preview
loyaltyrails agent "integrate SFMC Journey Builder" --apply --yes
```

## Draft Rule Vendor Actions

Use `integrate rule-action` when a developer or coding agent needs a reviewed
starter JSON payload for a rule-driven vendor outcome. This is a read-only
surface: it does not create rules, call vendor APIs, write files, read secrets,
or require live vendor credentials.

Supported draft targets:

- `shopify-hydrogen` (aliases: `shopify`, `hydrogen`)
- `braze`
- `mparticle`
- `salesforce_marketing_cloud` (alias: `sfmc`)

Examples:

```bash
loyaltyrails integrate rule-action sfmc --json
loyaltyrails integrate rule-action mparticle --event-type member.signup_completed
loyaltyrails integrate rule-action shopify-hydrogen --action-key hydrogen_order_paid_outcome
```

The command prints a `CreateRuleRequest` draft with:

- `ruleType: "integration_action"`
- `config.type: "vendor_action"`
- vendor-specific `vendorNamespace`, `actionType`, and `actionKey`
- `status: "draft"`
- an event-type condition and a payload template using rule, member, and event
  placeholders

Shopify/Hydrogen drafts are intentionally marked draft-only until a backend
Shopify or generic outbound webhook runtime adapter exists. Braze, mParticle,
and SFMC drafts still require backend `integration_connections` metadata and
secret references before live dispatch.

## Integrate A Shopify Hydrogen Storefront

Hydrogen integration detects the storefront, writes LoyaltyRails project
metadata, and generates the storefront balance and campaign game surfaces:

```bash
loyaltyrails integrate hydrogen --dry-run
loyaltyrails integrate hydrogen
loyaltyrails integrate hydrogen --webhooks
```

Hydrogen setup defaults to:

- `framework: "hydrogen"`
- `adapter: "hydrogen"`
- `vendorNamespace: "shopify"`
- `frameworkAdapter: "hydrogen"`
- `runtimeAdapter: "none"`
- `externalIdType: "shopify_id"`
- `identityStrategy: "shopify"`

`runtimeAdapter: "none"` is intentional for the current CLI recipe: generated
Hydrogen code runs in the customer storefront. It does not imply that
LoyaltyRails owns Shopify Admin API calls, retry, reconciliation, or native
Shopify webhook ingestion. Those belong to a future backend `shopify` runtime
adapter.

Generated Hydrogen files:

- `app/lib/loyaltyrails.server.ts`
- `app/routes/api.loyaltyrails.balance.ts`
- `app/routes/api.loyaltyrails.games.ts`
- `app/components/loyaltyrails/LoyaltyRailsBalance.tsx`
- `app/components/loyaltyrails/LoyaltyRailsCampaignTiles.tsx`

When `--webhooks` is passed, the CLI also generates:

- `app/routes/api.loyaltyrails.webhooks.shopify.ts`

The generated balance route resolves the signed-in Shopify customer through
`context.customerAccount`, reads LoyaltyRails secrets from `context.env`, calls
the program-scoped member balance lookup endpoint, and returns a typed 404
empty state when the Shopify customer does not have a LoyaltyRails member yet.
The generated game route also resolves the LoyaltyRails member ID server-side,
proxies game resolve/start/submit/complete operations, signs local
`sessionToken` values with Web Crypto and `LOYALTYRAILS_GAME_SESSION_SECRET`,
and rejects mutating requests that are not JSON or same-origin. Generated
components only call host app routes and do not reference LoyaltyRails server
secrets.

The generated Shopify webhook route reads the raw request body, verifies
`X-Shopify-Hmac-SHA256` with Web Crypto and `SHOPIFY_WEBHOOK_SECRET`, maps
Shopify `orders/paid` webhooks to `transaction.completed`, and sends events
through the program-scoped `/internal/v1/programs/:program_id/events`
endpoint. Other Shopify order topics are acknowledged and skipped. The route
uses `X-Shopify-Webhook-Id` in its idempotency key, requires a Shopify customer
before emitting, and does not log raw Shopify payloads or customer PII.

The command requires a generated-app-safe integration API-key profile: program
scoped, non-admin, and write scoped for the storefront game surface. Operator
tokens, all-program keys, admin keys, under-scoped keys, and keys scoped to a
different program are rejected before project files or env files are written.

By default, `integrate hydrogen` does not write `.env`. To write local
development env values, use:

```bash
loyaltyrails integrate hydrogen --write-env --yes
```

Oxygen production values should be configured in Shopify/Oxygen environment
settings. Oxygen environment changes require a redeploy. `loyaltyrails doctor`
warns when the Hydrogen game surface is installed and
`LOYALTYRAILS_GAME_SESSION_SECRET` is missing, or when the Shopify webhook
route is installed and `SHOPIFY_WEBHOOK_SECRET` is missing.

## Check Integration Health

```bash
loyaltyrails doctor
```

`doctor` checks API health, auth profile, API-key introspection, program
context, project detection, config validity, env var presence, manifest
validity, generated file presence, and generated-file secret safety. It reports
whether required env vars are present but does not print secret values.

## Check Outbound Dispatch Health

```bash
loyaltyrails outbound health --program <program-id>
loyaltyrails outbound health --program <program-id> --vendor mparticle
loyaltyrails outbound health --program <program-id> --vendor sfmc --window-hours 12
```

The command uses operator-token auth and calls
`GET /admin/v1/outbound/health`. It prints aggregate dispatch attempts,
retry/dead-letter pressure, previous-window trends, and machine-readable alert
codes. For mParticle and Salesforce Marketing Cloud connections, it also prints
the vendor rollout stage, mapping/replay/live readiness booleans, worker
enablement, credential namespace, and non-secret rollout checks.

## Snapshot Outbound Rollout Readiness

```bash
loyaltyrails outbound snapshot --program <program-id> \
  --vendor mparticle \
  --window-hours 24 \
  --reason "daily rollout readiness capture"

loyaltyrails outbound dashboard --program <program-id> --vendor sfmc --limit 10
```

`outbound snapshot` uses operator-token auth and calls
`POST /admin/v1/outbound/health/snapshots`. It persists the same aggregate
health/readiness view returned by `outbound health`, emits alert-history rows
for warning or action-required groups, and writes an audit event with the
operator reason. `outbound dashboard` reads
`GET /admin/v1/outbound/health/snapshots` and prints recent health status,
rollout stage, readiness booleans, worker flags, alert counts, alert codes,
and rollout checks needing attention.

These commands do not require live mParticle or Salesforce Marketing Cloud
credentials. They operate on persisted connection/readiness/dispatch metadata;
credential smoke remains a separate operator gate when real secret references
are available.

## Simulate Outbound Vendor Readiness

```bash
loyaltyrails outbound simulate --program <program-id> \
  --vendor mparticle \
  --scenario accepted \
  --reason "MVP demo"

loyaltyrails outbound simulate --program <program-id> \
  --vendor sfmc \
  --scenario rate-limited \
  --reason "MVP demo"
```

The command uses operator-token auth and calls
`POST /admin/v1/outbound/simulations`. `sfmc` is accepted as an alias for
`salesforce_marketing_cloud`; CLI scenarios map to backend outcomes
`accepted`, `retryable_failure`, `rate_limited`, or `terminal_failure`. Output
includes the report status, replay reference when present, checks, message, and
recommended next commands for `outbound snapshot`, `outbound dashboard`, and
`outbound credential-smoke` when real credential references exist. It never
reads local secrets and redacts token-like values from backend-provided text.

Simulation does not write credential-smoke audit events and does not satisfy the
`credential_smoke_passed` rollout gate.

## Smoke-Test Outbound Credentials

```bash
loyaltyrails outbound credential-smoke <connection-id> \
  --reason "pre-production credential verification"
```

The command uses operator-token auth and calls
`POST /admin/v1/outbound/connections/:connection_id/credential-smoke`.
It validates the mParticle or Salesforce Marketing Cloud connection config and
resolves configured secret references through the backend secret resolver. The
response prints check names, providers, status, and error codes only; it never
prints raw secret references, locators, or resolved secret values. This action
requires `programs:update` and writes an audit event with the operator reason.
Outbound health treats a fresh successful credential smoke as a live-send
promotion gate. If the integration connection changes after the latest smoke
check, operators must rerun this command before the rollout can reach
`live_send_ready`.

## Smoke-Test Events

```bash
loyaltyrails events send \
  --type transaction.completed \
  --external-id customer_123 \
  --external-id-type customer_id \
  --idempotency-key order_123 \
  --payload '{"amount":2500,"currency":"USD"}'
```

The command sends a single event to
`/internal/v1/programs/:program_id/events`. The idempotency key should come from
a stable merchant identifier such as an order ID, checkout ID, or webhook event
ID.

## Smoke-Test Member Balances

```bash
loyaltyrails members balance \
  --external-id customer_123 \
  --external-id-type customer_id
```

The command uses the program-scoped M2M balance endpoint:
`/internal/v1/programs/:program_id/members/balance/lookup`.

## Smoke-Test Games

Use the game commands to exercise the integration-auth surface contract after a
member and published experience already exist.

```bash
loyaltyrails games resolve --member-id <member_uuid>
loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --idempotency-key game_session_123
loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{"segmentIndex":0}'
loyaltyrails games complete --session-id <session_uuid>
```

`games resolve` requires read scope. `games start`, `games submit`, and
`games complete` require write scope. These are smoke commands for existing game
runtime state; they do not create campaigns, experiences, or rules.

## Generate Recipes

Preview before writing:

```bash
loyaltyrails add award-route --dry-run
loyaltyrails add balance-widget --dry-run
loyaltyrails add member-journey --dry-run
loyaltyrails add game-session-route --dry-run
loyaltyrails add onboarding-challenge --dry-run
loyaltyrails add campaign-tiles --dry-run
```

Apply:

```bash
loyaltyrails add award-route
loyaltyrails add balance-widget
loyaltyrails add member-journey
loyaltyrails add game-session-route
loyaltyrails add onboarding-challenge
loyaltyrails add campaign-tiles
```

`add award-route` generates a server route that emits LoyaltyRails events. It
requires a stable idempotency key and includes a fail-closed TODO for verifying
the order, checkout, or webhook source.

`add balance-widget` generates a server-backed balance route and client widget.
The generated balance route derives customer identity server-side through the
identity hook and does not trust client-submitted customer identifiers.

`add member-journey` generates a server-only journey hook, a member lifecycle
event-ingestion route, and a server-backed balance route (both derive identity
through the identity hook), plus a client `MemberJourney` component that
renders the demo journey against those routes.

`add game-session-route` generates a server-backed game-session proxy for
resolve, start, submit, and complete operations. It keeps the integration API
key server-side and requires the identity hook to return a LoyaltyRails member
ID before forwarding game requests. The route returns a signed `sessionToken`
instead of exposing the raw backend session ID, and requires a server-only
`LOYALTYRAILS_GAME_SESSION_SECRET` for that token binding.

`add onboarding-challenge` generates the game-session route if needed and a
client React component for onboarding challenges. The component resolves the
member's available onboarding experience through the generated server route,
starts a session, submits each step as `payload.answer`, and completes the
session without exposing the integration API key or raw backend session ID.

`add campaign-tiles` generates the game-session route if needed and a client
React component that resolves the member's available campaign experiences. It
renders campaign tiles and can start a session through the signed
`sessionToken` flow for host code to hand off to mechanic-specific UI. The
component filters to campaign-backed experiences by default; host apps can opt
into standalone experiences through the generated `includeStandalone` prop.

All recipes generate or reuse a server-only identity hook. Until the host app
wires that hook to its real auth system, generated routes fail closed.

## Plan And Apply With The Agent Scaffold

The local CLI integration agent can plan, preview, and apply one reviewed
generated-app recipe at a time:

```bash
loyaltyrails agent "add a member balance widget"
loyaltyrails agent "wire Shopify orders paid webhooks" --json
loyaltyrails agent "integrate mParticle Events API" --preview
loyaltyrails agent "add campaign tiles" --preview
loyaltyrails agent "add a member balance widget" --apply --yes
```

Plan and preview modes are deterministic and read-only. They detect the local
project, read `.loyaltyrails/config.json` and `.loyaltyrails/manifest.json`
when present, and map the request to already-reviewed rails commands.
They do not write files, read raw credentials or env secrets, call the
rails API, invoke package managers, run shell commands, or call an LLM provider.

Apply mode is intentionally narrow. It requires `--apply --yes`, revalidates the
selected plan immediately before writing, refuses dirty git worktrees unless
`--allow-dirty` is supplied, writes a redacted run manifest under
`.loyaltyrails/agent-runs/`, and only applies one ready local recipe in a run.
It does not perform operator-auth administration or arbitrary shell work.

Generated app integration requests map to integration-auth commands such as
`loyaltyrails init --dry-run`, `loyaltyrails integrate hydrogen --dry-run`, or
`loyaltyrails add balance-widget --dry-run`. Backend vendor readiness requests
map to no-auth local recipe commands such as
`loyaltyrails integrate vendor mparticle --dry-run`. Program, API-key, rule,
experience, and campaign administration stays operator-auth only; the agent
scaffold points to the relevant command help instead of performing admin work.

Pass `--preview` to include redacted dry-run file previews from the existing
reviewed planners. Preview mode checks the active integration profile metadata
for generated-app safety, scope, and program reach, but it still does not read
the stored raw API key or write files. Use `--profile`, `--program`, and
`--force` with preview mode when you need the same context controls as the
underlying recipe command.

## Demo Handoff

Use this flow to install a demo app against the **exact** program that an
operator (or the conversational admin agent, with the operator's consent)
configured — with no program ID or API key ever typed by hand.

1. In the app, an operator generates a single-use pairing code for the
   program. The code is short-lived (15-minute expiry) and usable exactly
   once.
2. The developer's machine must already be paired — see
   [Pair This Machine](#pair-this-machine-browser-approval). `join` claims
   the code with that machine's paired credential; it does not accept an
   integration API key or operator token.
3. The developer runs, inside the target app directory or pointing at one:

   ```bash
   loyaltyrails join <pairing-code> --configure ./your-app --yes
   ```

`join` claims the code, then `--configure` writes the target app's
`.env.local` (mode 0600, non-destructive — existing keys are left alone) with
the program ID and a freshly-minted scoped API key from the claim response,
plus the API URL of the backend the CLI just claimed against:

```
LOYALTYRAILS_PROGRAM_ID=...
LOYALTYRAILS_API_KEY=...
LOYALTYRAILS_API_URL=...
```

These are server-only names — never a `NEXT_PUBLIC_`/`VITE_`/`PUBLIC_` prefix
— so the key never reaches a browser bundle. Without `--configure`, `join`
only stores the claimed credential in a local CLI profile and prints the
next-step recommendation. Without `--yes`, `--configure` fails closed instead
of writing a credential to disk:

```bash
loyaltyrails join <pairing-code> --configure ./your-app
# Configuring ./your-app writes a scoped credential to disk.
# Re-run with --yes to confirm.
```

`<pairing-code>` accepts either the bare code or a full
`.../share/v1/<code>` URL. A same-machine re-claim of an already-claimed code
is treated as success (using the locally cached config) rather than an error.

No secret is ever shown in the app UI, in chat, or in CLI terminal output —
the scoped key from the claim response is written straight to the local
credential store and `.env.local` and is never printed.

## Local Backend Smoke

For local end-to-end smoke, use an isolated database when other workstreams are
changing migrations. The smoke pass for the CLI MVP used disposable Postgres and
Redis containers on non-default ports, ran the backend on `18080`, and executed:

```bash
loyaltyrails auth login --api-key lr_test_... --api-url http://127.0.0.1:18080
loyaltyrails init --program <program_uuid>
loyaltyrails doctor --api-url http://127.0.0.1:18080
loyaltyrails events send --type transaction.completed --external-id cli-smoke-customer
loyaltyrails members balance --external-id cli-smoke-customer
```

Avoid broad Docker restarts or `docker compose down` while parallel database
workstreams are active. Use targeted, disposable containers or a coordinated
database window.

## Current MVP Boundaries

Implemented:

- Integration API-key login/status/logout/profile use.
- Program context selection.
- Next.js App Router `init`.
- Shopify Hydrogen detection, config, balance, game route, campaign tile, and
  Shopify webhook generation.
- Backend vendor readiness recipes for Braze, mParticle, and Salesforce
  Marketing Cloud.
- `doctor`.
- `events send`.
- `members balance`.
- `games resolve/start/submit/complete`.
- `program list/create/status`.
- `keys list/create/rotate/revoke`.
- `rules list/create/simulate`.
- `experiences list/create/publish`.
- `campaigns list/create/attach-experience/activate`.
- `add award-route`.
- `add balance-widget`.
- `add member-journey`.
- `add game-session-route`.
- `add onboarding-challenge`.
- `add campaign-tiles`.
- `agent` plan-only scaffold and redacted dry-run previews.
- `auth login --pair` browser-approval machine pairing.
- `join --configure` demo handoff (see [Demo Handoff](#demo-handoff)).

## API Contract

The MVP CLI API surface is pinned by
`api-contracts/loyaltyrails-cli.v1.openapi.json`.

Regenerate derived backend and CLI bindings after changing that file:

```bash
pnpm contract:generate
```

Check for drift before opening a PR:

```bash
pnpm contract:check
```

Not yet implemented:

- Official packaged gamification runtime components.
- Agentic local code modification/apply mode.

---

# CLI Reference

Source: ../docs/reference/cli.md
URL: https://docs.rails.sh/cli-reference
Markdown: https://docs.rails.sh/markdown/cli-reference.md

# CLI Reference

> Generated from rails CLI source. Do not edit by hand; run `node docs-site/scripts/generate-source-references.mjs`.

## Source Inputs

- `packages/cli/src/commands.ts`: Commander command tree for `loyaltyrails`, `lr`.
- `packages/create-loyaltyrails/src/index.ts`: scaffold command for `create-loyaltyrails`.
- `packages/cli/src/config.ts`, `packages/cli/src/program-context.ts`, integration generators, and agent planners: env/config caveats.

## Package Binaries

| Package | Version | Bins | Source |
| --- | --- | --- | --- |
| @loyaltyrails/cli | 0.1.0 | `loyaltyrails`, `lr` | packages/cli/src/commands.ts |
| create-loyaltyrails | 0.1.0 | `create-loyaltyrails` | packages/create-loyaltyrails/src/index.ts |

## Command Index

| Usage | Kind | Summary | Source |
| --- | --- | --- | --- |
| `loyaltyrails auth` | group | Manage rails credential profiles | packages/cli/src/commands.ts:514 |
| `loyaltyrails auth login` | command | Validate and store an integration API key or operator CLI token, or pair this machine via the browser (--pair) | packages/cli/src/commands.ts:517 |
| `loyaltyrails auth status` | command | Show the active authentication profile | packages/cli/src/commands.ts:568 |
| `loyaltyrails auth logout` | command | Remove a stored authentication profile | packages/cli/src/commands.ts:596 |
| `loyaltyrails auth use <profile>` | command | Switch the active credential profile | packages/cli/src/commands.ts:609 |
| `loyaltyrails init` | command | Initialize rails metadata for an existing supported project | packages/cli/src/commands.ts:619 |
| `loyaltyrails integrate` | group | Integrate rails with storefront frameworks | packages/cli/src/commands.ts:643 |
| `loyaltyrails integrate plan` | command | Report integration recipe status and next actions without credentials | packages/cli/src/commands.ts:646 |
| `loyaltyrails integrate hydrogen` | command | Initialize rails metadata for a Shopify Hydrogen storefront | packages/cli/src/commands.ts:659 |
| `loyaltyrails integrate vendor` | command | Generate a backend vendor readiness recipe for Braze, mParticle, or SFMC | packages/cli/src/commands.ts:686 |
| `loyaltyrails integrate rule-action` | command | Print a draft integration_action rule for a vendor outcome | packages/cli/src/commands.ts:695 |
| `loyaltyrails program` | group | Manage loyalty programs and local context | packages/cli/src/commands.ts:715 |
| `loyaltyrails program list` | command | List programs visible to the operator profile | packages/cli/src/commands.ts:718 |
| `loyaltyrails program create` | command | Create a loyalty program in the operator organization | packages/cli/src/commands.ts:729 |
| `loyaltyrails program status <program-id>` | command | Show detailed status for a program | packages/cli/src/commands.ts:759 |
| `loyaltyrails program use <program-id>` | command | Set the active program for the current project/profile | packages/cli/src/commands.ts:771 |
| `loyaltyrails enable-stablecoin` | command | Compatibility alias for stablecoin rails attach-program | packages/cli/src/commands.ts:800 |
| `loyaltyrails keys` | group | Manage integration API keys | packages/cli/src/commands.ts:812 |
| `loyaltyrails keys list` | command | List integration API keys | packages/cli/src/commands.ts:815 |
| `loyaltyrails keys create` | command | Create an integration API key | packages/cli/src/commands.ts:833 |
| `loyaltyrails keys rotate <key-id>` | command | Rotate an integration API key and revoke the old key | packages/cli/src/commands.ts:866 |
| `loyaltyrails keys revoke <key-id>` | command | Revoke an integration API key | packages/cli/src/commands.ts:887 |
| `loyaltyrails stablecoin` | group | Inspect stablecoin operations | packages/cli/src/commands.ts:905 |
| `loyaltyrails list` | command | List read-only stablecoin provider capabilities | packages/cli/src/commands.ts:909 |
| `loyaltyrails rails` | group | Manage organization USDC reward rails for stablecoin rewards | packages/cli/src/commands.ts:925 |
| `loyaltyrails status` | command | Show organization USDC reward rail status | packages/cli/src/commands.ts:929 |
| `loyaltyrails setup-usdc` | command | Set up the organization USDC reward rail for Base Sepolia testnet | packages/cli/src/commands.ts:945 |
| `loyaltyrails attach-program` | command | Attach a program to an organization USDC reward rail and enable stablecoin rewards | packages/cli/src/commands.ts:967 |
| `loyaltyrails status` | command | Show stablecoin launch setup status | packages/cli/src/commands.ts:982 |
| `loyaltyrails doctor` | command | Show stablecoin launch setup checks and next actions | packages/cli/src/commands.ts:997 |
| `loyaltyrails launch-checklist` | command | Show the stablecoin launch checklist | packages/cli/src/commands.ts:1012 |
| `loyaltyrails update-check` | command | Update a manual stablecoin launch checklist item | packages/cli/src/commands.ts:1027 |
| `loyaltyrails liability` | command | Summarize current stablecoin liability buckets | packages/cli/src/commands.ts:1059 |
| `loyaltyrails issuance-funnel` | command | Summarize stablecoin issuance funnel counts and value | packages/cli/src/commands.ts:1076 |
| `loyaltyrails provider-ops` | command | Summarize stablecoin provider operations | packages/cli/src/commands.ts:1093 |
| `loyaltyrails game-economics` | command | Summarize stablecoin game economics | packages/cli/src/commands.ts:1125 |
| `loyaltyrails campaign-roi` | command | Summarize stablecoin campaign ROI dimensions | packages/cli/src/commands.ts:1154 |
| `loyaltyrails reward-intent <reward-intent-id>` | command | Show the stablecoin timeline for a reward intent | packages/cli/src/commands.ts:1194 |
| `loyaltyrails member <member-id>` | command | Show the stablecoin timeline for a member | packages/cli/src/commands.ts:1212 |
| `loyaltyrails reconciliation` | group | Inspect and manage stablecoin reconciliation | packages/cli/src/commands.ts:1230 |
| `loyaltyrails run` | command | Create a scoped stablecoin reconciliation run | packages/cli/src/commands.ts:1234 |
| `loyaltyrails exceptions` | command | Inspect and transition scoped stablecoin reconciliation exceptions | packages/cli/src/commands.ts:1265 |
| `loyaltyrails list` | command | List scoped stablecoin reconciliation exceptions | packages/cli/src/commands.ts:1289 |
| `loyaltyrails acknowledge <exception-id> <exception-id>` | command | Acknowledge a scoped stablecoin reconciliation exception | packages/cli/src/commands.ts:1298 |
| `loyaltyrails outbound` | group | Manage outbound integration operations | packages/cli/src/commands.ts:1363 |
| `loyaltyrails outbound health` | command | Summarize live outbound dispatch health | packages/cli/src/commands.ts:1365 |
| `loyaltyrails outbound snapshot` | command | Persist outbound rollout readiness health and alert history | packages/cli/src/commands.ts:1385 |
| `loyaltyrails outbound dashboard` | command | Show persisted outbound rollout readiness snapshots | packages/cli/src/commands.ts:1408 |
| `loyaltyrails outbound credential-smoke <connection-id>` | command | Resolve outbound vendor credential references without printing secrets | packages/cli/src/commands.ts:1425 |
| `loyaltyrails outbound simulate` | command | Run a no-live-credentials outbound vendor readiness simulation | packages/cli/src/commands.ts:1440 |
| `loyaltyrails list` | command | List outbound dead letters for a program | packages/cli/src/commands.ts:1466 |
| `loyaltyrails approve <dead-letter-id>` | command | Approve an outbound dead letter for replay | packages/cli/src/commands.ts:1483 |
| `loyaltyrails reject <dead-letter-id>` | command | Reject outbound dead-letter replay | packages/cli/src/commands.ts:1498 |
| `loyaltyrails mark-replayed <dead-letter-id>` | command | Mark an approved outbound dead letter as replayed | packages/cli/src/commands.ts:1513 |
| `loyaltyrails rules` | group | Manage program rules | packages/cli/src/commands.ts:1529 |
| `loyaltyrails rules list` | command | List rules for a program | packages/cli/src/commands.ts:1532 |
| `loyaltyrails rules create` | command | Create a rule for a program | packages/cli/src/commands.ts:1544 |
| `loyaltyrails rules simulate` | command | Simulate a rule config without saving it | packages/cli/src/commands.ts:1567 |
| `loyaltyrails experiences` | group | Manage game experiences | packages/cli/src/commands.ts:1588 |
| `loyaltyrails experiences list` | command | List game experiences for a program | packages/cli/src/commands.ts:1591 |
| `loyaltyrails experiences create` | command | Create a draft game experience | packages/cli/src/commands.ts:1603 |
| `loyaltyrails experiences publish <experience-id>` | command | Publish a draft game experience | packages/cli/src/commands.ts:1627 |
| `loyaltyrails campaigns` | group | Manage game campaigns | packages/cli/src/commands.ts:1638 |
| `loyaltyrails campaigns list` | command | List campaigns for a program | packages/cli/src/commands.ts:1641 |
| `loyaltyrails campaigns create` | command | Create a campaign | packages/cli/src/commands.ts:1658 |
| `loyaltyrails campaigns activate <campaign-id>` | command | Activate a campaign | packages/cli/src/commands.ts:1678 |
| `loyaltyrails campaigns attach-experience <campaign-id>` | command | Attach an experience to a campaign | packages/cli/src/commands.ts:1690 |
| `loyaltyrails doctor` | command | Run local CLI and API connectivity checks | packages/cli/src/commands.ts:1712 |
| `loyaltyrails events` | group | Send event-ingestion smoke requests | packages/cli/src/commands.ts:1727 |
| `loyaltyrails events send` | command | Send a single rails event | packages/cli/src/commands.ts:1730 |
| `loyaltyrails members` | group | Read member data with integration keys | packages/cli/src/commands.ts:1770 |
| `loyaltyrails members balance` | command | Look up a member balance by external ID | packages/cli/src/commands.ts:1773 |
| `loyaltyrails games` | group | Smoke test gamification surface APIs | packages/cli/src/commands.ts:1797 |
| `loyaltyrails games resolve` | command | Resolve playable game experiences for a member | packages/cli/src/commands.ts:1800 |
| `loyaltyrails games start` | command | Start an idempotent game session | packages/cli/src/commands.ts:1824 |
| `loyaltyrails games submit` | command | Submit one action to a game session | packages/cli/src/commands.ts:1858 |
| `loyaltyrails games complete` | command | Complete a game session | packages/cli/src/commands.ts:1878 |
| `loyaltyrails chat [request...]` | command | Open an interactive conversation with the rails agent ' +<br>        '(developer mode, streams from the agent service) | packages/cli/src/commands.ts:1892 |
| `loyaltyrails join <url-or-token>` | command | Claim a rails share link (URL or bare token) and bootstrap the integration | packages/cli/src/commands.ts:1942 |
| `loyaltyrails scaffold` | command | Generate a fresh Next.js storefront wired to the program claimed by `loyaltyrails join` | packages/cli/src/commands.ts:1979 |
| `loyaltyrails agent <request...>` | command | Plan a local rails integration from a natural-language request | packages/cli/src/commands.ts:2026 |
| `loyaltyrails add` | group | Add rails integration recipes | packages/cli/src/commands.ts:2085 |
| `loyaltyrails add award-route` | command | Generate a Next.js App Router event-ingestion route | packages/cli/src/commands.ts:2088 |
| `loyaltyrails add balance-widget` | command | Generate a server-backed balance route and React widget | packages/cli/src/commands.ts:2099 |
| `loyaltyrails add member-journey` | command | Generate bounded member lifecycle event routes and a demo journey component | packages/cli/src/commands.ts:2110 |
| `loyaltyrails add game-session-route` | command | Generate a server-backed game session route | packages/cli/src/commands.ts:2121 |
| `loyaltyrails add onboarding-challenge` | command | Generate a server-backed onboarding challenge component | packages/cli/src/commands.ts:2137 |
| `loyaltyrails add campaign-tiles` | command | Generate a server-backed campaign tile component | packages/cli/src/commands.ts:2153 |
| `create-loyaltyrails [project-name]` | command | Create a new rails app with the SDK pre-configured | packages/create-loyaltyrails/src/index.ts:22 |

## Environment And Local State

- `LOYALTYRAILS_API_URL`: API base URL; defaults to `http://localhost:8080` when not supplied.
- `LOYALTYRAILS_CONFIG_HOME`: user credential profile directory; defaults to `~/.loyaltyrails`.
- `LOYALTYRAILS_PROGRAM_ID`: program context fallback for integration-key commands.
- Generated app/server code can require `LOYALTYRAILS_API_KEY`, `LOYALTYRAILS_PROGRAM_ID`, `LOYALTYRAILS_API_URL`, `LOYALTYRAILS_EXTERNAL_ID_TYPE`, `LOYALTYRAILS_GAME_SESSION_SECRET`, and for Shopify webhooks `SHOPIFY_WEBHOOK_SECRET`.
- Env vars discovered in source: `DEBUG`, `LOYALTYRAILS_API_KEY`, `LOYALTYRAILS_API_URL`, `LOYALTYRAILS_CONFIG_HOME`, `LOYALTYRAILS_EXTERNAL_ID_TYPE`, `LOYALTYRAILS_GAME_SESSION_SECRET`, `LOYALTYRAILS_PROGRAM_ID`, `SHOPIFY_WEBHOOK_SECRET`.
- Local project state is stored under `.loyaltyrails/config.json` and `.loyaltyrails/manifest.json`.
- JSON-valued CLI options accept inline JSON or a path; source also strips a leading `@` before reading the file path.

## Implementation Status Caveats

- `auth`, `program`, `keys`, `rules`, `experiences`, `campaigns`, `events`, `members`, and `games` call backend APIs and depend on the active profile scopes.
- `init`, `integrate hydrogen`, `add *`, and `agent --apply` write local files through safety planners and manifest checks.
- `agent` plan mode is deterministic and local-only; `agent --apply` is limited to a single ready local recipe and requires `--yes` plus a clean git worktree unless `--allow-dirty` is supplied.
- `create-loyaltyrails` scaffolds a Next.js starter from templates, writes `.env.local`, and attempts dependency installation with the selected package manager.

## Command Details

### `loyaltyrails auth`

- Source: `packages/cli/src/commands.ts:514`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage rails credential profiles

### `loyaltyrails auth login`

- Source: `packages/cli/src/commands.ts:517`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Validate and store an integration API key or operator CLI token, or pair this machine via the browser (--pair)
- Optional options: `--api-key <key>`, `--operator-token <token>`, `--pair`, `--no-browser`, `--profile <name>` default=default, `--api-url <url>`, `--base-url <url>`

### `loyaltyrails auth status`

- Source: `packages/cli/src/commands.ts:568`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show the active authentication profile
- Optional options: `--profile <name>`

### `loyaltyrails auth logout`

- Source: `packages/cli/src/commands.ts:596`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Remove a stored authentication profile
- Optional options: `--profile <name>`

### `loyaltyrails auth use <profile>`

- Source: `packages/cli/src/commands.ts:609`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Switch the active credential profile
- Arguments: `<profile>` (Credential profile name)

### `loyaltyrails init`

- Source: `packages/cli/src/commands.ts:619`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Initialize rails metadata for an existing supported project
- Optional options: `--profile <name>`, `--program <program-id>`, `--external-id-type <type>`, `--identity-strategy <strategy>`, `--identity-file <path>`, `--package-manager <manager>`, `--write-env` default=false, `--no-env-write`, `--dry-run` default=false, `--force` default=false, `-y, --yes` default=false

### `loyaltyrails integrate`

- Source: `packages/cli/src/commands.ts:643`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Integrate rails with storefront frameworks

### `loyaltyrails integrate plan`

- Source: `packages/cli/src/commands.ts:646`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Report integration recipe status and next actions without credentials
- Optional options: `--json` default=false

### `loyaltyrails integrate hydrogen`

- Source: `packages/cli/src/commands.ts:659`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Initialize rails metadata for a Shopify Hydrogen storefront
- Optional options: `--profile <name>`, `--program <program-id>`, `--external-id-type <type>` default=shopify_id, `--identity-strategy <strategy>` default=shopify, `--package-manager <manager>`, `--webhooks` default=false, `--write-env` default=false, `--no-env-write`, `--dry-run` default=false, `--force` default=false, `-y, --yes` default=false

### `loyaltyrails integrate vendor`

- Source: `packages/cli/src/commands.ts:686`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a backend vendor readiness recipe for Braze, mParticle, or SFMC
- Optional options: `--dry-run` default=false, `--force` default=false

### `loyaltyrails integrate rule-action`

- Source: `packages/cli/src/commands.ts:695`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Print a draft integration_action rule for a vendor outcome
- Optional options: `--json` default=false, `--name <name>`, `--action-key <key>`, `--event-type <event-type>`

### `loyaltyrails program`

- Source: `packages/cli/src/commands.ts:715`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage loyalty programs and local context

### `loyaltyrails program list`

- Source: `packages/cli/src/commands.ts:718`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List programs visible to the operator profile
- Optional options: `--profile <name>`

### `loyaltyrails program create`

- Source: `packages/cli/src/commands.ts:729`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a loyalty program in the operator organization
- Required options: `--name <name>`, `--symbol <symbol>`, `--issuer <issuer>`
- Optional options: `--reserve-ratio <bps>`, `--chain-id <id>`, `--contract-address <address>`, `--profile <name>`

### `loyaltyrails program status <program-id>`

- Source: `packages/cli/src/commands.ts:759`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show detailed status for a program
- Arguments: `<program-id>` (Program ID)
- Optional options: `--profile <name>`

### `loyaltyrails program use <program-id>`

- Source: `packages/cli/src/commands.ts:771`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Set the active program for the current project/profile
- Arguments: `<program-id>` (Program ID)
- Optional options: `--profile <name>`, `--global`

### `loyaltyrails enable-stablecoin`

- Source: `packages/cli/src/commands.ts:800`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Compatibility alias for stablecoin rails attach-program
- Required options: `--program <program-id>`, `--rail <rail-id>`
- Optional options: `--settlement-policy <policy>` default=testnet-only, `--client-mutation-id <id>`, `--yes` default=false, `--profile <name>`

### `loyaltyrails keys`

- Source: `packages/cli/src/commands.ts:812`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage integration API keys

### `loyaltyrails keys list`

- Source: `packages/cli/src/commands.ts:815`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List integration API keys
- Optional options: `--program <program-id>`, `--all-program`, `--reason <reason>`, `--profile <name>`

### `loyaltyrails keys create`

- Source: `packages/cli/src/commands.ts:833`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create an integration API key
- Required options: `--name <name>`, `--scopes <scopes>`
- Optional options: `--program <program-id>`, `--all-program`, `--environment <env>` default=test, `--expires-at <iso>`, `--reason <reason>`, `--save-profile <name>`, `--profile <name>`

### `loyaltyrails keys rotate <key-id>`

- Source: `packages/cli/src/commands.ts:866`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Rotate an integration API key and revoke the old key
- Arguments: `<key-id>` (API key ID)
- Optional options: `--reason <reason>`, `--save-profile <name>`, `--profile <name>`

### `loyaltyrails keys revoke <key-id>`

- Source: `packages/cli/src/commands.ts:887`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Revoke an integration API key
- Arguments: `<key-id>` (API key ID)
- Optional options: `--reason <reason>`, `--profile <name>`

### `loyaltyrails stablecoin`

- Source: `packages/cli/src/commands.ts:905`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Inspect stablecoin operations

### `loyaltyrails list`

- Source: `packages/cli/src/commands.ts:909`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List read-only stablecoin provider capabilities
- Optional options: `--provider <provider>`, `--mode <mode>`, `--profile <name>`

### `loyaltyrails rails`

- Source: `packages/cli/src/commands.ts:925`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage organization USDC reward rails for stablecoin rewards

### `loyaltyrails status`

- Source: `packages/cli/src/commands.ts:929`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show organization USDC reward rail status
- Optional options: `--program <program-id>`, `--profile <name>`

### `loyaltyrails setup-usdc`

- Source: `packages/cli/src/commands.ts:945`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Set up the organization USDC reward rail for Base Sepolia testnet
- Optional options: `--client-mutation-id <id>`, `--yes` default=false, `--profile <name>`

### `loyaltyrails attach-program`

- Source: `packages/cli/src/commands.ts:967`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Attach a program to an organization USDC reward rail and enable stablecoin rewards
- Required options: `--program <program-id>`, `--rail <rail-id>`
- Optional options: `--settlement-policy <policy>` default=testnet-only, `--client-mutation-id <id>`, `--yes` default=false, `--profile <name>`

### `loyaltyrails status`

- Source: `packages/cli/src/commands.ts:982`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show stablecoin launch setup status
- Required options: `--program <program-id>`
- Optional options: `--profile <name>`

### `loyaltyrails doctor`

- Source: `packages/cli/src/commands.ts:997`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show stablecoin launch setup checks and next actions
- Required options: `--program <program-id>`
- Optional options: `--profile <name>`

### `loyaltyrails launch-checklist`

- Source: `packages/cli/src/commands.ts:1012`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show the stablecoin launch checklist
- Required options: `--program <program-id>`
- Optional options: `--profile <name>`

### `loyaltyrails update-check`

- Source: `packages/cli/src/commands.ts:1027`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Update a manual stablecoin launch checklist item
- Required options: `--program <program-id>`
- Optional options: `--status <status>`, `--blocking <state>`, `--owner <label>`, `--evidence-ref <ref>`, `--next-action <text>`, `--reviewer <label>`, `--approver <label>`, `--yes` default=false, `--profile <name>`

### `loyaltyrails liability`

- Source: `packages/cli/src/commands.ts:1059`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize current stablecoin liability buckets
- Required options: `--program <program-id>`
- Optional options: `--asset-id <asset-id>`, `--asset-code <asset-code>`, `--profile <name>`

### `loyaltyrails issuance-funnel`

- Source: `packages/cli/src/commands.ts:1076`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize stablecoin issuance funnel counts and value
- Required options: `--program <program-id>`
- Optional options: `--asset-id <asset-id>`, `--asset-code <asset-code>`, `--limit <count>`, `--start <iso>`, `--end <iso>`, `--profile <name>`

### `loyaltyrails provider-ops`

- Source: `packages/cli/src/commands.ts:1093`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize stablecoin provider operations
- Required options: `--program <program-id>`
- Optional options: `--provider <provider>`, `--provider-product <product>`, `--mode <mode>`, `--network <network>`, `--chain-id <id>`, `--start <iso>`, `--end <iso>`, `--profile <name>`

### `loyaltyrails game-economics`

- Source: `packages/cli/src/commands.ts:1125`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize stablecoin game economics
- Required options: `--program <program-id>`
- Optional options: `--campaign <campaign-id>`, `--experience <experience-id>`, `--game-session <session-id>`, `--prize-award <prize-award-id>`, `--asset-id <asset-id>`, `--asset-code <asset-code>`, `--start <iso>`, `--end <iso>`, `--profile <name>`

### `loyaltyrails campaign-roi`

- Source: `packages/cli/src/commands.ts:1154`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize stablecoin campaign ROI dimensions
- Required options: `--program <program-id>`
- Optional options: `--campaign <campaign-id>`, `--rule <rule-id>`, `--rule-version <version>`, `--rule-type <type>`, `--asset-id <asset-id>`, `--asset-code <asset-code>`, `--template-slug <slug>`, `--authoring-source <source>`, `--start <iso>`, `--end <iso>`, `--profile <name>`

### `loyaltyrails reward-intent <reward-intent-id>`

- Source: `packages/cli/src/commands.ts:1194`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show the stablecoin timeline for a reward intent
- Arguments: `<reward-intent-id>` (Reward intent ID)
- Required options: `--program <program-id>`
- Optional options: `--limit <count>`, `--profile <name>`

### `loyaltyrails member <member-id>`

- Source: `packages/cli/src/commands.ts:1212`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show the stablecoin timeline for a member
- Arguments: `<member-id>` (Member ID)
- Required options: `--program <program-id>`
- Optional options: `--limit <count>`, `--profile <name>`

### `loyaltyrails reconciliation`

- Source: `packages/cli/src/commands.ts:1230`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Inspect and manage stablecoin reconciliation

### `loyaltyrails run`

- Source: `packages/cli/src/commands.ts:1234`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a scoped stablecoin reconciliation run
- Required options: `--program <program-id>`
- Optional options: `--run-type <type>`, `--limit <count>`, `--include-unscoped-evidence` default=false, `--reason <reason>`, `--confirm-unscoped-evidence` default=false, `--yes` default=false, `--profile <name>`

### `loyaltyrails exceptions`

- Source: `packages/cli/src/commands.ts:1265`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Inspect and transition scoped stablecoin reconciliation exceptions
- Optional options: `--program <program-id>`, `--status <status>`, `--limit <count>`, `--profile <name>`

### `loyaltyrails list`

- Source: `packages/cli/src/commands.ts:1289`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List scoped stablecoin reconciliation exceptions
- Optional options: `--program <program-id>`, `--status <status>`, `--limit <count>`, `--profile <name>`

### `loyaltyrails acknowledge <exception-id> <exception-id>`

- Source: `packages/cli/src/commands.ts:1298`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Acknowledge a scoped stablecoin reconciliation exception
- Arguments: `<exception-id>` (Reconciliation exception ID); `<exception-id>` (Reconciliation exception ID)
- Optional options: `--program <program-id>`, `--yes` default=false, `--profile <name>`, `--program <program-id>`, `--notes <notes>`, `--yes` default=false, `--profile <name>`

### `loyaltyrails outbound`

- Source: `packages/cli/src/commands.ts:1363`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage outbound integration operations

### `loyaltyrails outbound health`

- Source: `packages/cli/src/commands.ts:1365`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Summarize live outbound dispatch health
- Required options: `--program <program-id>`
- Optional options: `--vendor <vendor-namespace>`, `--window-hours <hours>`, `--profile <name>`

### `loyaltyrails outbound snapshot`

- Source: `packages/cli/src/commands.ts:1385`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Persist outbound rollout readiness health and alert history
- Required options: `--program <program-id>`, `--reason <reason>`
- Optional options: `--vendor <vendor-namespace>`, `--window-hours <hours>`, `--profile <name>`

### `loyaltyrails outbound dashboard`

- Source: `packages/cli/src/commands.ts:1408`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Show persisted outbound rollout readiness snapshots
- Required options: `--program <program-id>`
- Optional options: `--vendor <vendor-namespace>`, `--limit <count>`, `--profile <name>`

### `loyaltyrails outbound credential-smoke <connection-id>`

- Source: `packages/cli/src/commands.ts:1425`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Resolve outbound vendor credential references without printing secrets
- Arguments: `<connection-id>` (Outbound integration connection ID)
- Required options: `--reason <reason>`
- Optional options: `--profile <name>`

### `loyaltyrails outbound simulate`

- Source: `packages/cli/src/commands.ts:1440`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Run a no-live-credentials outbound vendor readiness simulation
- Required options: `--program <program-id>`, `--vendor <vendor-namespace>`, `--scenario <scenario>`, `--reason <reason>`
- Optional options: `--profile <name>`

### `loyaltyrails list`

- Source: `packages/cli/src/commands.ts:1466`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List outbound dead letters for a program
- Required options: `--program <program-id>`
- Optional options: `--limit <count>`, `--cursor <dead-letter-id>`, `--profile <name>`

### `loyaltyrails approve <dead-letter-id>`

- Source: `packages/cli/src/commands.ts:1483`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Approve an outbound dead letter for replay
- Arguments: `<dead-letter-id>` (Outbound dead-letter ID)
- Optional options: `--reason <reason>`, `--profile <name>`

### `loyaltyrails reject <dead-letter-id>`

- Source: `packages/cli/src/commands.ts:1498`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Reject outbound dead-letter replay
- Arguments: `<dead-letter-id>` (Outbound dead-letter ID)
- Required options: `--reason <reason>`
- Optional options: `--profile <name>`

### `loyaltyrails mark-replayed <dead-letter-id>`

- Source: `packages/cli/src/commands.ts:1513`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Mark an approved outbound dead letter as replayed
- Arguments: `<dead-letter-id>` (Outbound dead-letter ID)
- Optional options: `--reason <reason>`, `--replay-reference <reference>`, `--profile <name>`

### `loyaltyrails rules`

- Source: `packages/cli/src/commands.ts:1529`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage program rules

### `loyaltyrails rules list`

- Source: `packages/cli/src/commands.ts:1532`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List rules for a program
- Required options: `--program <program-id>`
- Optional options: `--profile <name>`

### `loyaltyrails rules create`

- Source: `packages/cli/src/commands.ts:1544`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a rule for a program
- Required options: `--program <program-id>`, `--name <name>`, `--type <type>`, `--config <json-or-path>`
- Optional options: `--description <text>`, `--conditions <json-or-path>`, `--priority <number>` default=0, `--starts-at <iso>`, `--ends-at <iso>`, `--status <status>`, `--builder-metadata <json-or-path>`, `--profile <name>`

### `loyaltyrails rules simulate`

- Source: `packages/cli/src/commands.ts:1567`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Simulate a rule config without saving it
- Required options: `--program <program-id>`, `--config <json-or-path>`
- Optional options: `--test-transactions <json-or-path>`, `--profile <name>`

### `loyaltyrails experiences`

- Source: `packages/cli/src/commands.ts:1588`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage game experiences

### `loyaltyrails experiences list`

- Source: `packages/cli/src/commands.ts:1591`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List game experiences for a program
- Required options: `--program <program-id>`
- Optional options: `--profile <name>`

### `loyaltyrails experiences create`

- Source: `packages/cli/src/commands.ts:1603`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a draft game experience
- Required options: `--program <program-id>`, `--name <name>`, `--mechanic <type>`, `--mechanic-config <json-or-path>`
- Optional options: `--description <text>`, `--display-config <json-or-path>`, `--visual-theme <json-or-path>`, `--session-expiry-seconds <seconds>`, `--max-sessions-per-member <count>`, `--cooldown-seconds <seconds>`, `--starts-at <iso>`, `--ends-at <iso>`, `--profile <name>`

### `loyaltyrails experiences publish <experience-id>`

- Source: `packages/cli/src/commands.ts:1627`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Publish a draft game experience
- Arguments: `<experience-id>` (Experience ID)
- Optional options: `--profile <name>`

### `loyaltyrails campaigns`

- Source: `packages/cli/src/commands.ts:1638`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Manage game campaigns

### `loyaltyrails campaigns list`

- Source: `packages/cli/src/commands.ts:1641`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: List campaigns for a program
- Required options: `--program <program-id>`
- Optional options: `--status <status>`, `--limit <count>`, `--profile <name>`

### `loyaltyrails campaigns create`

- Source: `packages/cli/src/commands.ts:1658`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a campaign
- Required options: `--program <program-id>`, `--name <name>`
- Optional options: `--type <type>`, `--description <text>`, `--audience-config <json-or-path>`, `--budget-config <json-or-path>`, `--starts-at <iso>`, `--ends-at <iso>`, `--profile <name>`

### `loyaltyrails campaigns activate <campaign-id>`

- Source: `packages/cli/src/commands.ts:1678`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Activate a campaign
- Arguments: `<campaign-id>` (Campaign ID)
- Optional options: `--profile <name>`

### `loyaltyrails campaigns attach-experience <campaign-id>`

- Source: `packages/cli/src/commands.ts:1690`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Attach an experience to a campaign
- Arguments: `<campaign-id>` (Campaign ID)
- Required options: `--experience <experience-id>`
- Optional options: `--priority <number>` default=0, `--profile <name>`

### `loyaltyrails doctor`

- Source: `packages/cli/src/commands.ts:1712`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Run local CLI and API connectivity checks
- Optional options: `--profile <name>`, `--api-url <url>`, `--base-url <url>`

### `loyaltyrails events`

- Source: `packages/cli/src/commands.ts:1727`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Send event-ingestion smoke requests

### `loyaltyrails events send`

- Source: `packages/cli/src/commands.ts:1730`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Send a single rails event
- Required options: `--type <event-type>`
- Optional options: `--payload <json-or-path>`, `--member-id <uuid>`, `--external-id <id>`, `--external-id-type <type>` default=customer_id, `--idempotency-key <key>`, `--occurred-at <iso>`, `--program <program-id>`, `--profile <name>`

### `loyaltyrails members`

- Source: `packages/cli/src/commands.ts:1770`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Read member data with integration keys

### `loyaltyrails members balance`

- Source: `packages/cli/src/commands.ts:1773`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Look up a member balance by external ID
- Required options: `--external-id <id>`
- Optional options: `--external-id-type <type>` default=customer_id, `--program <program-id>`, `--profile <name>`

### `loyaltyrails games`

- Source: `packages/cli/src/commands.ts:1797`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Smoke test gamification surface APIs

### `loyaltyrails games resolve`

- Source: `packages/cli/src/commands.ts:1800`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Resolve playable game experiences for a member
- Required options: `--member-id <uuid>`
- Optional options: `--program <program-id>`, `--profile <name>`

### `loyaltyrails games start`

- Source: `packages/cli/src/commands.ts:1824`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Start an idempotent game session
- Required options: `--experience-id <uuid>`, `--member-id <uuid>`, `--idempotency-key <key>`
- Optional options: `--campaign-id <uuid>`, `--surface <surface>` default=web, `--fingerprint <value>`, `--program <program-id>`, `--profile <name>`

### `loyaltyrails games submit`

- Source: `packages/cli/src/commands.ts:1858`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Submit one action to a game session
- Required options: `--session-id <uuid>`, `--sequence <number>`, `--action-type <type>`
- Optional options: `--payload <json-or-path>`, `--profile <name>`

### `loyaltyrails games complete`

- Source: `packages/cli/src/commands.ts:1878`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Complete a game session
- Required options: `--session-id <uuid>`
- Optional options: `--profile <name>`

### `loyaltyrails chat [request...]`

- Source: `packages/cli/src/commands.ts:1892`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Open an interactive conversation with the rails agent ' +
        '(developer mode, streams from the agent service)
- Arguments: `[request...]` (Optional initial request (chat continues after))
- Optional options: `--agent-url <url>`, `--api-base <url>`, `--profile <name>`, `--program <program-id>`, `--no-developer-context` default=false

### `loyaltyrails join <url-or-token>`

- Source: `packages/cli/src/commands.ts:1942`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Claim a rails share link (URL or bare token) and bootstrap the integration
- Arguments: `<url-or-token>` (Share URL like https://app/share/v1/<token> or the bare token)
- Optional options: `--api-base <url>`, `--profile <name>`, `--configure <dir>`, `--yes`

### `loyaltyrails scaffold`

- Source: `packages/cli/src/commands.ts:1979`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a fresh Next.js storefront wired to the program claimed by `loyaltyrails join`
- Optional options: `--target <dir>`, `--profile <name>`, `--port <port>` default=(value: string) =>
      Number.parseInt(value, 10), `--force` default=false, `--dep-range <range>`, `--templates-root <dir>`

### `loyaltyrails agent <request...>`

- Source: `packages/cli/src/commands.ts:2026`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Plan a local rails integration from a natural-language request
- Arguments: `<request...>` (Natural-language integration request)
- Optional options: `--json` default=false, `--preview` default=false, `--apply` default=false, `--yes` default=false, `--allow-dirty` default=false, `--profile <name>`, `--program <program-id>`, `--force` default=false

### `loyaltyrails add`

- Source: `packages/cli/src/commands.ts:2085`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Add rails integration recipes

### `loyaltyrails add award-route`

- Source: `packages/cli/src/commands.ts:2088`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a Next.js App Router event-ingestion route
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `loyaltyrails add balance-widget`

- Source: `packages/cli/src/commands.ts:2099`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a server-backed balance route and React widget
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `loyaltyrails add member-journey`

- Source: `packages/cli/src/commands.ts:2110`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate bounded member lifecycle event routes and a demo journey component
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `loyaltyrails add game-session-route`

- Source: `packages/cli/src/commands.ts:2121`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a server-backed game session route
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `loyaltyrails add onboarding-challenge`

- Source: `packages/cli/src/commands.ts:2137`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a server-backed onboarding challenge component
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `loyaltyrails add campaign-tiles`

- Source: `packages/cli/src/commands.ts:2153`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Generate a server-backed campaign tile component
- Optional options: `--profile <name>`, `--program <program-id>`, `--dry-run` default=false, `--force` default=false

### `create-loyaltyrails [project-name]`

- Source: `packages/create-loyaltyrails/src/index.ts:22`
- Status: implemented in source; backend-dependent commands require a reachable rails API and valid credentials.
- Summary: Create a new rails app with the SDK pre-configured
- Arguments: `[project-name]` (Name of the project)
- Optional options: `--pm <manager>` default=npm, `--program-id <id>`, `--api-key <key>`

---

# Integration Recipes

Source: ../docs/integrations/recipes.md
URL: https://docs.rails.sh/integration-recipes
Markdown: https://docs.rails.sh/markdown/integration-recipes.md

# Integration Recipes

Status: initial guide based on the current rails CLI recipe planners.

## What A Recipe Is

A rails integration recipe is a reviewed, repeatable code-generation
path for a host application. It is different from a backend vendor connection.

Example:

- `shopify` is a vendor/backend namespace.
- `hydrogen` is a storefront framework adapter detected by the CLI.
- `loyaltyrails integrate hydrogen` applies the Shopify Hydrogen storefront
  integration recipe.

Recipes are designed to respect host-app architecture. They should preserve
routing, auth, deployment, and identity patterns instead of assuming every app
looks the same.

Recipes also need to cooperate with the SDK component layer. The desired model
is not "CLI recipes versus SDK components"; it is backend recipe plus frontend
component wiring. Recipes should create the server-side route or loader that
keeps secrets safe, then adapt the returned data into canonical props consumed
by platform-agnostic React loyalty components.

## Safety Model

Recipes are intentionally conservative:

- Preview before writing with `--dry-run`.
- Track generated files in `.loyaltyrails/manifest.json`.
- Store non-secret metadata in `.loyaltyrails/config.json`.
- Avoid writing env files unless `--write-env --yes` is passed.
- Keep integration API keys server-side.
- Reject generated-app unsafe credentials.
- Generate identity hooks that fail closed until wired to real host auth.
- Scan generated files for secrets.
- Use idempotency keys for event and session creation flows.

Generated app integrations require a program-scoped, non-admin integration key
with the scopes required by the recipe. Operator tokens, all-program keys, admin
keys, under-scoped keys, and keys scoped to a different program are rejected
before project files or env files are written.

## Project Files

| File | Purpose |
|------|---------|
| `.loyaltyrails/config.json` | Project metadata: program, framework, adapter, identity strategy, env names |
| `.loyaltyrails/manifest.json` | Generated file ownership and installed recipes |
| `.loyaltyrails/agent-runs/*.json` | CLI agent apply manifests |

These files must not contain raw API keys.

## Authentication Profiles

The CLI supports two credential families:

| Credential | Used for |
|------------|----------|
| Integration API key | Generated app integrations, `doctor`, events, member balance, game smoke tests |
| Operator CLI token | Control-plane setup: programs, API keys, rules, experiences, campaigns |

Authenticate with an integration API key:

```bash
loyaltyrails auth login --api-key lr_test_... --api-url http://localhost:8080
```

Authenticate with an operator CLI token:

```bash
loyaltyrails auth login --operator-token lr_cli_... --api-url http://localhost:8080
```

## Current Recipes

| Command | Host app | Writes |
|---------|----------|--------|
| `loyaltyrails init` | Supported existing project | rails project metadata and optional env values |
| `loyaltyrails integrate hydrogen` | Shopify Hydrogen | Server library, balance route, game route, campaign tiles, optional Shopify webhook route |
| `loyaltyrails integrate vendor <vendor>` | Backend vendor readiness | Agentic rollout readiness artifact for Braze, mParticle, or SFMC; no live credentials or network calls |
| `loyaltyrails integrate rule-action <target>` | Rule vendor actions | Read-only draft `integration_action` JSON for Shopify/Hydrogen, webhook, Braze, mParticle, and SFMC |
| `loyaltyrails add award-route` | Next.js App Router | Event-ingestion server route and identity hook |
| `loyaltyrails add balance-widget` | Next.js App Router | Server balance route, identity hook, React balance widget |
| `loyaltyrails add member-journey` | Next.js App Router | Bounded member lifecycle event routes, identity hook, balance route, demo journey component |
| `loyaltyrails add game-session-route` | Next.js App Router | Server game session proxy and identity hook |
| `loyaltyrails add onboarding-challenge` | Next.js App Router | Game session route plus onboarding challenge component |
| `loyaltyrails add campaign-tiles` | Next.js App Router | Game session route plus campaign tiles component |

Detailed recipe pages:

- [Next.js App Router Integration](./nextjs-app-router.md)
- [Shopify Hydrogen Integration](./shopify-hydrogen.md)
- [Rule Vendor Actions](./rule-vendor-actions.md)
- [Generic Webhook Outcomes](./webhook-outcomes.md)
- [Braze Agentic Rollout Recipe](./braze/rollout-recipe.md)
- [mParticle Agentic Rollout Recipe](./mparticle/rollout-recipe.md)
- [Salesforce Marketing Cloud Agentic Rollout Recipe](./salesforce_marketing_cloud/rollout-recipe.md)

Vendor readiness recipes are planning and operator handoff artifacts. They can
prepare connection config skeletons, rule-action drafts, simulation commands,
and rollout checklists, but they do not register runtime adapters, read vendor
secrets, or enable live dispatch.

Future component-oriented recipes should include:

| Recipe intent | Backend work | Frontend component work |
|---------------|--------------|-------------------------|
| Add tier progress | Member/tier route, identity mapping, cache behavior | Install or copy `TierProgress`, map `TierStatus`, add loading/error states |
| Add points balance | Balance route and member lookup | Install or copy `PointsBalance`, map `PointsAccount` |
| Add offers | Offers route and eligibility context | Install or copy `OfferGrid` or `OfferTile`, map `Offer[]` |
| Add rewards | Rewards and redemption routes with idempotency | Install or copy `RewardCatalog` and `RedemptionFlow` |
| Add campaign tiles | Game resolve route and session proxy | Install or copy campaign/game components |

## Recommended Workflow

1. Authenticate with the correct profile.
2. Run `loyaltyrails doctor`.
3. Preview the recipe.
4. Review generated files.
5. Apply the recipe.
6. Wire the generated identity hook to host auth.
7. Set server-only env vars in local development.
8. Set production env vars in the deployment platform.
9. Run `loyaltyrails doctor` again.
10. Run a smoke command for events, balance, or games.

Example:

```bash
loyaltyrails auth login --api-key lr_test_... --api-url http://localhost:8080
loyaltyrails doctor
loyaltyrails add balance-widget --dry-run
loyaltyrails add balance-widget
loyaltyrails doctor
```

## Shopify Hydrogen

Preview:

```bash
loyaltyrails integrate hydrogen --dry-run
```

Apply:

```bash
loyaltyrails integrate hydrogen
```

Generate Shopify webhook support:

```bash
loyaltyrails integrate hydrogen --webhooks
```

Generated Hydrogen files:

| File | Purpose |
|------|---------|
| `app/lib/loyaltyrails.server.ts` | Server-only rails helpers |
| `app/routes/api.loyaltyrails.balance.ts` | Balance lookup proxy |
| `app/routes/api.loyaltyrails.games.ts` | Game resolve/start/submit/complete proxy |
| `app/components/loyaltyrails/LoyaltyRailsBalance.tsx` | Balance component |
| `app/components/loyaltyrails/LoyaltyRailsCampaignTiles.tsx` | Campaign tiles component |
| `app/routes/api.loyaltyrails.webhooks.shopify.ts` | Optional Shopify orders webhook route |

Hydrogen defaults:

| Field | Value |
|-------|-------|
| `framework` | `hydrogen` |
| `adapter` | `hydrogen` |
| `vendorNamespace` | `shopify` |
| `frameworkAdapter` | `hydrogen` |
| `runtimeAdapter` | `none` |
| `externalIdType` | `shopify_id` |
| `identityStrategy` | `shopify` |

`runtimeAdapter: "none"` means generated code runs in the customer storefront.
It does not mean rails owns Shopify Admin API calls, native Shopify
webhook ingestion, retry, or reconciliation.

### Hydrogen Plus SDK Components

Hydrogen is the strongest example of why recipe docs and SDK component docs need
to be linked. A complete Shopify integration may need both:

- Backend recipe files for Shopify identity, member lookup, tier/balance data,
  game sessions, and optional order webhooks.
- Frontend SDK components such as `TierProgress`, `PointsBalance`, and
  `CampaignTiles` adapted into Hydrogen routes and account surfaces.

For a `TierProgress` integration, the docs should show this boundary:

| Boundary | Guidance |
|----------|----------|
| Browser component | Receives canonical `TierStatus` props; no API key, no Shopify Admin secret |
| Hydrogen route/loader | Reads customer identity and calls a server-only rails helper |
| Data adapter | Maps rails and Shopify data into `currentTier`, `nextTier`, `progress`, and `pointsToNext` |
| Recipe manifest | Records backend files, component files, token/CSS files, and placement hints |

The component reference should stay framework-agnostic. The Hydrogen recipe page
should explain where the component is placed and how data reaches it.

Server-only env vars:

| Variable | Purpose |
|----------|---------|
| `LOYALTYRAILS_API_KEY` | Program-scoped integration API key |
| `LOYALTYRAILS_PROGRAM_ID` | Program ID |
| `LOYALTYRAILS_API_URL` | Backend API URL |
| `LOYALTYRAILS_GAME_SESSION_SECRET` | Local game session token signing |
| `SHOPIFY_WEBHOOK_SECRET` | Shopify webhook verification, when `--webhooks` is used |

## Next.js App Router

Initialize metadata:

```bash
loyaltyrails init \
  --program <program_uuid> \
  --external-id-type customer_id \
  --identity-strategy custom
```

Add event ingestion:

```bash
loyaltyrails add award-route --dry-run
loyaltyrails add award-route
```

Add balance:

```bash
loyaltyrails add balance-widget --dry-run
loyaltyrails add balance-widget
```

Future SDK component docs should show how this recipe can be decomposed into a
server route plus a reusable `PointsBalance` or `TierProgress` wrapper. The
component should call the host app route, not rails directly.

Add game runtime:

```bash
loyaltyrails add game-session-route
loyaltyrails add onboarding-challenge
loyaltyrails add campaign-tiles
```

Generated Next.js files vary by `app` directory location, but commonly include:

| Recipe | Files |
|--------|-------|
| `award-route` | `app/api/loyaltyrails/_identity.ts`, `app/api/loyaltyrails/award/route.ts` |
| `balance-widget` | identity hook, `app/api/loyaltyrails/balance/route.ts`, `components/loyaltyrails/BalanceWidget.tsx` |
| `game-session-route` | identity hook, `app/api/loyaltyrails/games/route.ts` |
| `onboarding-challenge` | game session route, `components/loyaltyrails/OnboardingChallenge.tsx` |
| `campaign-tiles` | game session route, `components/loyaltyrails/CampaignTiles.tsx` |

## Generated Identity Hook

Recipes generate or reuse a server-only identity hook. It exists because the
host app owns user authentication and customer identity. Until the hook is wired
to real auth, generated routes fail closed.

The hook should return the current host customer identifier and, where needed,
the rails member ID. It must not trust client-submitted customer IDs for
server-side awards, balance lookup, or game sessions.

## Recipe-Specific Smoke Tests

Event ingestion:

```bash
loyaltyrails events send \
  --type transaction.completed \
  --external-id customer_123 \
  --external-id-type customer_id \
  --idempotency-key order_123 \
  --payload '{"amount":2500,"currency":"USD"}'
```

Member balance:

```bash
loyaltyrails members balance \
  --external-id customer_123 \
  --external-id-type customer_id
```

Games:

```bash
loyaltyrails games resolve --member-id <member_uuid>
loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --idempotency-key game_session_123
loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{"segmentIndex":0}'
loyaltyrails games complete --session-id <session_uuid>
```

## CLI Agent For Recipes

The local CLI agent maps natural-language requests to reviewed recipes:

```bash
loyaltyrails agent "add a member balance widget"
loyaltyrails agent "wire Shopify orders paid webhooks" --preview
loyaltyrails agent "add campaign tiles" --apply --yes
```

The CLI agent is deterministic and bounded. It can preview and apply known local
recipes, but it does not perform arbitrary code edits or invent endpoints.

## Documentation Needed Per Recipe

Each recipe page should include:

- Supported frameworks and versions.
- Detection signals.
- Required profile and scopes.
- Required env vars.
- Generated file table.
- Server/client boundary explanation.
- Identity hook contract.
- Idempotency behavior.
- Secret handling.
- Dry-run example.
- Apply example.
- Doctor checks.
- Rollback instructions.
- Host-app customization points.

---

# Next.js App Router

Source: ../docs/integrations/nextjs-app-router.md
URL: https://docs.rails.sh/nextjs-app-router
Markdown: https://docs.rails.sh/markdown/nextjs-app-router.md

# Next.js App Router Integration

Status: source-derived recipe guide for the current rails CLI. The
implemented path is CLI recipe generation into an existing Next.js App Router
project. The older `create-loyaltyrails` scaffold is useful for demos, but it is
not the recommended production integration path yet.

## Agent Facts

Use these paths when reviewing or updating this recipe:

| Source | Purpose |
|--------|---------|
| `packages/cli/src/commands.ts` | Command names, options, auth gates, scope checks |
| `packages/cli/src/integration/init.ts` | `.loyaltyrails/config.json`, env file behavior |
| `packages/cli/src/integration/next-app-router.ts` | Generated Next.js files and route code |
| `packages/cli/src/integration/doctor.ts` | Local validation checks |
| `packages/create-loyaltyrails/*` | Demo scaffold only; not the current existing-app recipe path |
| `docs/quick-start.md` | Current high-level flow |
| `docs/integrations/recipes.md` | Recipe safety model and generated file inventory |

## Prerequisites

- Node.js 18 or newer.
- An existing Next.js App Router project with an `app/` or `src/app/`
  directory.
- A rails backend URL. Local platform development defaults to
  `http://localhost:8080`.
- A rails program ID.
- A program-scoped, non-admin integration API key.
- The active API key must have:
  - `read` scope for `init` and `add balance-widget`.
  - `write` scope for `add award-route`, `add member-journey`,
    `add game-session-route`, `add onboarding-challenge`, and
    `add campaign-tiles`.

Operator CLI tokens (`lr_cli_...`), all-program keys, and admin-scoped keys are
rejected before generated app files are written.

## Install And Authenticate

Install the CLI from the package once published, or run it from the monorepo
while developing:

```bash
pnpm install
pnpm --filter @loyaltyrails/cli build
node packages/cli/dist/index.js --help
```

The installed binary names are `loyaltyrails` and `lr`.

Authenticate from the host app repository:

```bash
loyaltyrails auth login \
  --api-key lr_test_... \
  --api-url http://localhost:8080

loyaltyrails auth status
loyaltyrails doctor
```

## Command Flow

Preview project metadata first:

```bash
loyaltyrails init \
  --program <program_uuid> \
  --external-id-type customer_id \
  --identity-strategy custom \
  --dry-run
```

Apply after review:

```bash
loyaltyrails init \
  --program <program_uuid> \
  --external-id-type customer_id \
  --identity-strategy custom
```

Add recipes with the same preview-then-apply pattern:

```bash
loyaltyrails add award-route --dry-run
loyaltyrails add award-route

loyaltyrails add balance-widget --dry-run
loyaltyrails add balance-widget

loyaltyrails add member-journey --dry-run
loyaltyrails add member-journey

loyaltyrails add game-session-route --dry-run
loyaltyrails add game-session-route

loyaltyrails add onboarding-challenge --dry-run
loyaltyrails add onboarding-challenge

loyaltyrails add campaign-tiles --dry-run
loyaltyrails add campaign-tiles
```

Use `--profile <name>` when the local machine has multiple stored CLI profiles.
Use `--program <program_uuid>` when the profile or project config does not
already select the intended program. Use `--force` only after reviewing the
dry-run; it allows replacing files that are not already managed by the rails manifest.

## Generated Files

`loyaltyrails init` writes:

| File | Purpose |
|------|---------|
| `.loyaltyrails/config.json` | Non-secret project metadata: program, framework, adapter, identity strategy, profile |
| `.loyaltyrails/manifest.json` | Generated file ownership and installed recipes |
| `.env.local` | Optional local env file, only when `--write-env --yes` is passed |

Recipe files vary with `app/` versus `src/app/`:

| Recipe | Generated files |
|--------|-----------------|
| `award-route` | `app/api/loyaltyrails/_identity.ts`, `app/api/loyaltyrails/award/route.ts` |
| `balance-widget` | identity hook, `app/api/loyaltyrails/balance/route.ts`, `components/loyaltyrails/BalanceWidget.tsx` |
| `member-journey` | identity hook, `app/api/loyaltyrails/_journey.ts`, `app/api/loyaltyrails/journey/route.ts`, `app/api/loyaltyrails/balance/route.ts`, `components/loyaltyrails/MemberJourney.tsx` |
| `game-session-route` | identity hook, `app/api/loyaltyrails/games/route.ts` |
| `onboarding-challenge` | game session route, `components/loyaltyrails/OnboardingChallenge.tsx` |
| `campaign-tiles` | game session route, `components/loyaltyrails/CampaignTiles.tsx` |

The identity hook path can be overridden during `init`:

```bash
loyaltyrails init \
  --program <program_uuid> \
  --identity-file app/api/loyaltyrails/_identity.ts
```

## Environment

Required server-only values:

```env
LOYALTYRAILS_API_URL=http://localhost:8080
LOYALTYRAILS_API_KEY=lr_test_...
LOYALTYRAILS_PROGRAM_ID=<program_uuid>
LOYALTYRAILS_EXTERNAL_ID_TYPE=customer_id
```

Game recipes also require:

```env
LOYALTYRAILS_GAME_SESSION_SECRET=<random-32-byte-secret>
```

By default, `init` does not write `.env.local`. To write missing local values,
run:

```bash
loyaltyrails init --write-env --yes
```

Do not commit raw API keys. Production values belong in the deployment
platform's secret manager.

## Server-Only Token Handling

Generated routes call rails from server code with `X-API-Key`. Browser
components call the host app's own routes, for example
`/api/loyaltyrails/balance` or `/api/loyaltyrails/games`; they do not call the
rails API directly and do not receive the integration API key.

The generated identity hook imports `server-only` and fails closed:

```ts
export async function resolveLoyaltyRailsCustomer(
  _request: Request
): Promise<LoyaltyRailsCustomerIdentity> {
  throw new Error(
    'TODO: Resolve the signed-in customer on the server before using LoyaltyRails.'
  );
}
```

Wire this hook to the host auth system. It should derive `externalId` and, for
game routes, `memberId` from the server session or trusted backend state. Do not
trust client-submitted customer IDs for awards, balances, or game sessions.

Game routes replace raw backend `sessionId` values with signed local
`sessionToken` values using `LOYALTYRAILS_GAME_SESSION_SECRET`. Submit and
complete operations validate that the token belongs to the current member.

## Route Behavior

### Award Route

`POST /api/loyaltyrails/award` emits `transaction.completed` to:

```text
/internal/v1/programs/:program_id/events
```

The generated `resolveVerifiedTransaction` function intentionally throws until
the app verifies an order, checkout, or webhook source server-side. Supply a
stable idempotency key from a merchant identifier such as an order ID or
webhook event ID.

### Balance Route

`GET /api/loyaltyrails/balance` calls:

```text
/internal/v1/programs/:program_id/members/balance/lookup
```

It uses the identity hook for `externalId` and `externalIdType`, then forwards
the rails response to the generated `BalanceWidget`.

### Game Route

`POST /api/loyaltyrails/games` supports:

```json
{ "operation": "resolve" }
```

```json
{
  "operation": "start",
  "experienceId": "<experience_uuid>",
  "campaignId": "<campaign_uuid>",
  "idempotencyKey": "campaign:<stable-id>",
  "surface": "web"
}
```

Submit and complete calls use the signed `sessionToken` returned by `start`.
The route requires the identity hook to return `memberId`.

## Webhooks And API Routes

The Next.js App Router recipe currently generates a generic award route, not a
provider-specific webhook handler. If the app awards points from Stripe,
Shopify, order-management, or custom commerce webhooks, add provider signature
verification before calling the generated rails event logic.

Recommended pattern:

1. Verify provider signature over the raw request body.
2. Resolve the merchant order and authenticated customer server-side.
3. Build `transaction.completed`.
4. Use a stable idempotency key.
5. Do not log raw payloads, API keys, signatures, session cookies, or customer
   PII.

## Local Validation

Run:

```bash
loyaltyrails doctor
```

`doctor` checks API health, auth profile, API-key introspection, program
context, framework detection, project config, required env var presence,
manifest validity, generated file presence, and generated-file secret safety.
It reports whether secrets are present but does not print secret values.

Smoke-test event ingestion:

```bash
loyaltyrails events send \
  --type transaction.completed \
  --external-id customer_123 \
  --external-id-type customer_id \
  --idempotency-key order_123 \
  --payload '{"amount":2500,"currency":"USD"}'
```

Smoke-test member balance:

```bash
loyaltyrails members balance \
  --external-id customer_123 \
  --external-id-type customer_id
```

Smoke-test game runtime after a member and published experience exist:

```bash
loyaltyrails games resolve --member-id <member_uuid>
loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --idempotency-key game_session_123
loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{"segmentIndex":0}'
loyaltyrails games complete --session-id <session_uuid>
```

## Deployment Notes

- Configure `LOYALTYRAILS_API_KEY`, `LOYALTYRAILS_PROGRAM_ID`,
  `LOYALTYRAILS_API_URL`, and any game secret in the production secret store.
- Keep generated API routes on a Node.js runtime when using the current recipe;
  generated routes set `export const runtime = 'nodejs'`.
- Re-run `loyaltyrails doctor` in the deployed environment or in CI with the
  same env keys available.
- Rotate the integration key if it appears in logs, screenshots, commits, or a
  browser bundle.

## Rollback

Recipes are tracked in `.loyaltyrails/manifest.json`. To roll back a recipe:

1. Review the manifest entry for the recipe name and generated files.
2. Remove only the files listed for that recipe.
3. Remove the recipe from `.loyaltyrails/config.json` `installedRecipes`.
4. Remove the recipe entry and file entries from `.loyaltyrails/manifest.json`.
5. Remove unused env vars from local and production secret stores.
6. Run `loyaltyrails doctor`.

If a generated file has been customized, preserve the app-owned changes before
removing manifest ownership.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| `Run loyaltyrails init before adding Next.js App Router recipes.` | The project config is missing or not `next-app-router`/`next-app-router`. Run `loyaltyrails init`. |
| `Generated application integrations require an integration API key.` | The active profile is an operator token. Log in with `--api-key`. |
| `Generated application integrations require a program-scoped API key.` | The active key has all-program reach. Create or select a program-scoped key. |
| `add <recipe> requires write scope` | Use a write-scoped integration key for award and game recipes. |
| `LOYALTYRAILS_API_KEY is required.` | Add the server-only env var locally and in production. |
| Balance route returns identity TODO | Wire `resolveLoyaltyRailsCustomer` to real server auth. |
| Game route returns member ID TODO | Return `memberId` from the identity hook before using game recipes. |
| Game submit says `sessionToken is invalid` | Ensure the browser sends the `sessionToken` from the generated start call and that `LOYALTYRAILS_GAME_SESSION_SECRET` did not change mid-session. |

## SDK Component Bridge

The generated `BalanceWidget`, `OnboardingChallenge`, and `CampaignTiles`
components are recipe-local components today. The platform-agnostic React SDK
component library is still being adapted to rails APIs.

Future component recipes should keep the same boundary:

- Server route or loader owns auth, secrets, idempotency, and rails API
  calls.
- A data adapter maps rails responses into canonical component props.
- Browser components such as `PointsBalance`, `TierProgress`, `OfferGrid`, or
  `RewardCatalog` receive props and never import server credentials.

---

# Shopify Hydrogen

Source: ../docs/integrations/shopify-hydrogen.md
URL: https://docs.rails.sh/shopify-hydrogen
Markdown: https://docs.rails.sh/markdown/shopify-hydrogen.md

# Shopify Hydrogen Integration

Status: source-derived recipe guide for the current rails CLI. The
implemented Hydrogen recipe generates storefront balance, game, campaign tile,
and optional Shopify order webhook files. A full backend Shopify runtime adapter
for Admin API ownership, retry, and reconciliation is future work.

## Agent Facts

Use these paths when reviewing or updating this recipe:

| Source | Purpose |
|--------|---------|
| `packages/cli/src/commands.ts` | `integrate hydrogen` options, auth gates, scope checks |
| `packages/cli/src/integration/hydrogen.ts` | Generated Hydrogen server helper, routes, components, Shopify webhook handler |
| `packages/cli/src/integration/init.ts` | `.env` behavior and project metadata |
| `packages/cli/src/integration/detectors.ts` | Hydrogen detection signals |
| `packages/cli/src/integration/doctor.ts` | Env, manifest, generated file, and secret-scan checks |
| `docs/sdk-components.md` | Platform-agnostic component bridge model |
| `~/Development/tolds/packages/react/src/components/TierProgress.tsx` | Legacy `TierProgress` component source material |

## What This Recipe Does

`loyaltyrails integrate hydrogen` detects a Shopify Hydrogen storefront, writes
non-secret rails project metadata, and generates server-owned storefront
routes that keep rails credentials out of browser code.

Hydrogen defaults:

| Field | Value |
|-------|-------|
| `framework` | `hydrogen` |
| `adapter` | `hydrogen` |
| `vendorNamespace` | `shopify` |
| `frameworkAdapter` | `hydrogen` |
| `runtimeAdapter` | `none` |
| `externalIdType` | `shopify_id` |
| `identityStrategy` | `shopify` |

`runtimeAdapter: "none"` is intentional. The generated code runs in the
customer storefront. It does not mean rails owns Shopify Admin API
calls, native Shopify webhook registration, retries, or reconciliation.

## Prerequisites

- Node.js 18 or newer.
- A Hydrogen storefront with `app/routes` or `src/app/routes`.
- `@shopify/hydrogen` or `@shopify/remix-oxygen`, or a Hydrogen/Oxygen config
  marker that the CLI can detect.
- Shopify Customer Account API support in the storefront. The generated helper
  resolves signed-in customers through `context.customerAccount`.
- A rails backend URL. Local platform development defaults to
  `http://localhost:8080`.
- A rails program ID.
- A program-scoped, non-admin integration API key with `write` scope. The
  Hydrogen command currently includes game surfaces, so write scope is required.
- For Shopify order webhooks, a Shopify app or admin-owned setup that can
  register `orders/paid` delivery to the generated Hydrogen route.

## Shopify Scopes And Identity

The storefront route uses the signed-in Shopify Customer Account identity and
maps the Shopify customer GID to the rails external ID:

```text
externalIdType = shopify_id
externalId = gid://shopify/Customer/<id>
```

The generated code does not call the Shopify Admin API. Admin API scopes are
therefore not consumed by the generated balance or game routes.

For the optional webhook route, Shopify must be configured to deliver
`orders/paid` webhooks and sign them with the app webhook secret. The Shopify
app or admin process that registers the webhook must have whatever order webhook
permission the store requires, commonly order read access. Keep that permission
on the Shopify app side; do not add Shopify Admin credentials to browser code.

Customer notes:

- Signed-out customers receive a 401-style JSON response from generated balance
  and game helpers.
- If a Shopify customer has no rails member yet, balance lookup returns
  a typed 404 empty state.
- Game routes resolve the rails `memberId` by performing the balance
  lookup server-side first.

## Install And Authenticate

Install the CLI from the package once published, or run it from the monorepo
while developing:

```bash
pnpm install
pnpm --filter @loyaltyrails/cli build
node packages/cli/dist/index.js --help
```

Authenticate from the Hydrogen storefront repository:

```bash
loyaltyrails auth login \
  --api-key lr_test_... \
  --api-url http://localhost:8080

loyaltyrails auth status
loyaltyrails doctor
```

Operator tokens, all-program integration keys, and admin-scoped API keys are
rejected before the recipe writes project files or local env values.

## Command Flow

Preview the storefront recipe:

```bash
loyaltyrails integrate hydrogen --dry-run
```

Apply it:

```bash
loyaltyrails integrate hydrogen
```

Generate Shopify order webhook support:

```bash
loyaltyrails integrate hydrogen --webhooks --dry-run
loyaltyrails integrate hydrogen --webhooks
```

Use `--profile <name>` for a non-default CLI profile and `--program
<program_uuid>` when the active profile or project config does not already
select the desired program. Use `--force` only after reviewing the dry-run.

## Generated Files

| File | Purpose |
|------|---------|
| `.loyaltyrails/config.json` | Non-secret project metadata |
| `.loyaltyrails/manifest.json` | Generated file ownership and installed recipes |
| `.env` | Optional local env file, only when `--write-env --yes` is passed |
| `app/lib/loyaltyrails.server.ts` | Server-only rails and Shopify customer helpers |
| `app/routes/api.loyaltyrails.balance.ts` | Private no-store balance lookup route |
| `app/routes/api.loyaltyrails.games.ts` | Private no-store game resolve/start/submit/complete route |
| `app/components/loyaltyrails/LoyaltyRailsBalance.tsx` | Storefront balance component |
| `app/components/loyaltyrails/LoyaltyRailsCampaignTiles.tsx` | Storefront campaign tile component |
| `app/routes/api.loyaltyrails.webhooks.shopify.ts` | Optional `orders/paid` webhook route |

Paths use `src/app/...` when the Hydrogen app is rooted under `src/app`.

## Environment

Required server-only values:

```env
LOYALTYRAILS_API_URL=http://localhost:8080
LOYALTYRAILS_API_KEY=lr_test_...
LOYALTYRAILS_PROGRAM_ID=<program_uuid>
LOYALTYRAILS_EXTERNAL_ID_TYPE=shopify_id
LOYALTYRAILS_GAME_SESSION_SECRET=<random-32-byte-secret>
```

When `--webhooks` is used:

```env
SHOPIFY_WEBHOOK_SECRET=<shopify-app-webhook-secret>
```

By default, the command does not write `.env`. For local development only:

```bash
loyaltyrails integrate hydrogen --write-env --yes
```

Configure production values in Shopify/Oxygen environment settings. Oxygen
environment changes require a redeploy. Do not commit `.env` with raw secrets.

## Backend Recipe Expectations

The generated server helper:

- Reads secrets from `context.env`.
- Resolves Shopify customer identity with `context.customerAccount.query`.
- Calls `/internal/v1/programs/:program_id/members/balance/lookup` for balance
  and member lookup.
- Calls `/internal/v1/games/resolve`, `/sessions`,
  `/sessions/:id/actions`, and `/sessions/:id/complete` for game flows.
- Signs local game `sessionToken` values with Web Crypto and
  `LOYALTYRAILS_GAME_SESSION_SECRET`.
- Strips raw backend `sessionId` values from game responses before returning to
  browser components.
- Requires JSON and same-origin requests for mutating game actions.

The optional Shopify webhook route:

- Reads the raw request body.
- Verifies `X-Shopify-Hmac-SHA256` with `SHOPIFY_WEBHOOK_SECRET`.
- Requires `X-Shopify-Topic`, `X-Shopify-Shop-Domain`, and
  `X-Shopify-Webhook-Id`.
- Processes only `orders/paid`.
- Maps the order to `transaction.completed`.
- Uses `shopify:<shop-domain>:<topic>:<webhook-id>` as the idempotency key.
- Skips unsupported topics and orders without a customer.
- Does not log raw payloads or customer PII.

## Storefront Usage

The generated components call host storefront routes, not the rails API
directly:

```tsx
import { LoyaltyRailsBalance } from '~/components/loyaltyrails/LoyaltyRailsBalance';
import { LoyaltyRailsCampaignTiles } from '~/components/loyaltyrails/LoyaltyRailsCampaignTiles';

export default function AccountLoyalty() {
  return (
    <>
      <LoyaltyRailsBalance />
      <LoyaltyRailsCampaignTiles />
    </>
  );
}
```

Good placement targets include account pages, account flyouts, cart-adjacent
surfaces, and campaign landing routes. Keep customer-specific routes private and
no-store, matching the generated response headers.

## SDK Component Bridge

The SDK component library is platform-agnostic React loyalty UI. It has not yet
been fully adapted to rails APIs, so the current Hydrogen recipe
generates local storefront components instead of installing `@loyaltyrails/react`
components.

The intended boundary is:

| Layer | Responsibility |
|-------|----------------|
| Hydrogen route/loader | Reads Shopify customer identity and calls server-only rails helpers |
| Backend recipe | Wires balance, games, campaigns, and optional Shopify order events |
| Data adapter | Maps rails and Shopify data into canonical component props |
| Browser component | Renders `TierProgress`, `PointsBalance`, or campaign UI without secrets |

### Adapting TierProgress

`TierProgress` currently exists as migration source in
`~/Development/tolds/packages/react/src/components/TierProgress.tsx`. It accepts
either a canonical `tier` object, a `progress` number from `0..1`, or
`currentPoints` plus `nextTierPoints`.

Until a rails tier route and packaged component bridge are finalized,
adapt it through a Hydrogen route that returns canonical props:

```ts
// app/routes/api.loyaltyrails.tier.ts
import {json} from '@shopify/remix-oxygen';
import {loadLoyaltyRailsBalance} from '~/lib/loyaltyrails.server';

export async function loader({context}) {
  const result = await loadLoyaltyRailsBalance(context);

  if (result.status !== 200 || !('found' in result.body) || !result.body.found) {
    return json({found: false}, {status: result.status});
  }

  const balance = result.body.balance;
  const nextTierPoints = 5000;

  return json({
    found: true,
    tier: {
      currentTier: 'Member',
      nextTier: 'Gold',
      progress: Math.min(balance / nextTierPoints, 1),
      pointsToNext: Math.max(nextTierPoints - balance, 0),
    },
  });
}
```

Then keep the browser component props-driven:

```tsx
import {useEffect, useState} from 'react';
// TierProgress is not exported by the current @loyaltyrails/react package —
// this import is illustrative of the target shape, not something that
// resolves today. The shipped package exports `TierBadge` (a simple tier
// pill), not this progress-bar component; see the caveat below.
import {TierProgress} from '@loyaltyrails/react';

export function AccountTierProgress() {
  const [tier, setTier] = useState(null);

  useEffect(() => {
    fetch('/api/loyaltyrails/tier')
      .then((response) => response.json())
      .then((body) => {
        if (body.found) setTier(body.tier);
      });
  }, []);

  if (!tier) return null;

  return (
    <TierProgress
      progress={tier.progress}
      showLabels
      currentLabel={tier.currentTier}
      nextLabel={tier.nextTier}
      showPercentage
    />
  );
}
```

This example is intentionally marked as an adaptation pattern, not generated
behavior. The current CLI does not generate `api.loyaltyrails.tier.ts`, and
`@loyaltyrails/react` (`packages/react`) does not yet export `TierProgress` —
it ships `TierBadge`, `PointsBalance`, `RedemptionCard`, `SpinWheel`,
`OnboardingChallenge`, and `CampaignTiles`. `TierProgress` remains legacy
source in `~/Development/tolds` until it is ported.

## Local Validation

Run:

```bash
loyaltyrails doctor
```

`doctor` checks API health, auth profile, API-key introspection, program
context, Hydrogen detection, config validity, env var presence, manifest
validity, generated file presence, and generated-file secret safety. It warns
when:

- Hydrogen game files are installed and `LOYALTYRAILS_GAME_SESSION_SECRET` is
  missing.
- Shopify webhook files are installed and `SHOPIFY_WEBHOOK_SECRET` is missing.
- Local `.env` values exist but Oxygen production env values may still need a
  redeploy.

Smoke-test member balance:

```bash
loyaltyrails members balance \
  --external-id gid://shopify/Customer/123 \
  --external-id-type shopify_id
```

Smoke-test game runtime after a member and published experience exist:

```bash
loyaltyrails games resolve --member-id <member_uuid>
loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --idempotency-key hydrogen_game_session_123 \
  --surface hydrogen
```

For webhook validation, prefer Shopify's signed webhook delivery or a local
fixture that computes a valid `X-Shopify-Hmac-SHA256` over the exact raw body.
Do not disable signature verification in the generated route.

## Deployment Notes

- Configure production env vars in Shopify/Oxygen, not in committed files.
- Redeploy after changing Oxygen env values.
- Register the Shopify `orders/paid` webhook URL only after the Hydrogen route
  is deployed with `SHOPIFY_WEBHOOK_SECRET`.
- Keep the rails integration API key program-scoped and non-admin.
- Rotate the API key or webhook secret if either appears in logs, screenshots,
  commits, or browser bundles.

## Rollback

Recipes are tracked in `.loyaltyrails/manifest.json`. To roll back:

1. Review the manifest entries for `hydrogen-balance`, `hydrogen-games`, and
   `hydrogen-shopify-webhooks`.
2. Remove only the generated files listed for the recipe being rolled back.
3. Remove the recipe names from `.loyaltyrails/config.json` `installedRecipes`.
4. Remove matching recipe and file entries from `.loyaltyrails/manifest.json`.
5. Remove unused Oxygen and local env vars.
6. Disable Shopify webhook delivery before deleting the webhook route in
   production.
7. Run `loyaltyrails doctor`.

If a generated component or route has been customized, preserve the app-owned
changes before removing manifest ownership.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| `integrate hydrogen requires a Hydrogen project. Detected <framework>.` | Confirm `@shopify/hydrogen` or `@shopify/remix-oxygen` is installed and `app/routes` or `src/app/routes` exists. |
| `Generated application integrations require an integration API key.` | Log in with `loyaltyrails auth login --api-key ...`; operator tokens cannot generate storefront integrations. |
| `integrate hydrogen requires write scope` | Use a write-scoped program integration key. |
| Balance route returns sign-in error | Confirm Customer Account API is configured and the customer is signed in. |
| Balance route returns no member | The Shopify customer GID has not been linked to a rails member for this program. |
| Game route says `Game requests must be same-origin` | Send browser game actions to the generated Hydrogen route from the same storefront origin. |
| Game route says `sessionToken is expired` | Start a new game session and confirm the session secret did not change during the session. |
| Webhook route returns invalid signature | Verify `SHOPIFY_WEBHOOK_SECRET`, raw-body handling, and the `X-Shopify-Hmac-SHA256` header. |
| Webhook route returns skipped `unsupported_topic` | The current generated handler only processes `orders/paid`. |

---

# Rule Vendor Actions

Source: ../docs/integrations/rule-vendor-actions.md
URL: https://docs.rails.sh/rule-vendor-actions
Markdown: https://docs.rails.sh/markdown/rule-vendor-actions.md

# Rule Vendor Actions

Status: first executable slice for rule-driven third-party outcomes.

## Purpose

Native rule actions award points, bonuses, offers, badges, and assets inside the
LoyaltyRails platform. Vendor actions give the same rule execution path a
durable outbound side effect for third-party systems such as Salesforce
Marketing Cloud, mParticle, Braze, or a future generic webhook runtime.

Vendor actions are not called inline from the rule engine. When a rule matches,
the outcome executor writes an `outbound_event_envelopes` record in the same
database transaction as the rest of the rule outcome. Hosted outbound workers
then dispatch, retry, dead-letter, and replay through the existing outbound
operator workflow.

## Backend Config Shape

```json
{
  "type": "vendor_action",
  "vendorNamespace": "salesforce_marketing_cloud",
  "actionType": "trigger_journey",
  "actionKey": "LR_WELCOME_BONUS",
  "consentPurpose": "marketing_export",
  "payloadTemplate": {
    "pointsAwarded": "{{event.payload.pointsAwarded}}",
    "ruleName": "{{rule.name}}",
    "memberExternalId": "{{member.externalId}}"
  },
  "idempotencyKeyTemplate": "rule:{{rule.id}}:event:{{event.id}}:sfmc:welcome"
}
```

Rules using this config should use `ruleType: "integration_action"`.

The CLI can print safe starter rule payloads:

```bash
loyaltyrails integrate rule-action sfmc --json
loyaltyrails integrate rule-action mparticle --json
loyaltyrails integrate rule-action braze --json
loyaltyrails integrate rule-action webhook --json
loyaltyrails integrate rule-action shopify-hydrogen --json
```

These commands are read-only. They do not create rules, call vendors, write
files, or read credentials. The generated `CreateRuleRequest` should remain in
`draft` status until operators review event identity, consent, mapping, and
connection metadata.

## Runtime Semantics

- `vendorNamespace` selects the outbound vendor worker.
- `actionType` describes operator intent, such as `trigger_journey`,
  `track_event`, `update_profile`, `send_payload`, or `trigger_webhook`.
- `actionKey` is vendor-specific. For SFMC it becomes the
  `EventDefinitionKey`; for mParticle and Braze it becomes the event name unless
  a vendor-specific `eventName` override is present in `vendorAction`.
- `payloadTemplate` is rendered against `program`, `member`, `rule`, `event`,
  and `txRef`.
- Consent is read from the inbound event payload's `outboundConsent`,
  `outbound_consent`, or `consent` object. Missing consent remains fail-closed.
- The durable envelope source event type is `rule.vendor_action` and the
  category is `rule_action`.

## Vendor Behavior

| Vendor | First action support |
|--------|----------------------|
| Salesforce Marketing Cloud | Trigger Journey Builder event from `actionKey` |
| mParticle | Send Events API custom event from `actionKey` |
| Braze | Send `/users/track` custom event from `actionKey` |
| Webhook | Queue a generic webhook payload where `actionKey` names a backend-configured endpoint |
| Shopify/Hydrogen | Draft-only helper for Hydrogen-emitted order events; backend Shopify/webhook outbound runtime is not implemented yet |

Generic webhook outcomes are useful for partner-specific callbacks that do not
need a named adapter yet. The rule must not contain destination URLs, signing
secrets, bearer tokens, or API keys; those belong in backend connection
metadata and secret references. See
[Generic Webhook Outcomes](./webhook-outcomes.md).

## CLI Recipe Guidance

CLI recipes should scaffold the host-app ingress and identity code, then leave
vendor action rule creation as operator-owned control-plane config. Recipes
should not write vendor credentials into generated application code. Generated
examples may include draft `integration_action` JSON payloads, but the actual
connection must come from `integration_connections` and secret references.

---

# Generic Webhook Outcomes

Source: ../docs/integrations/webhook-outcomes.md
URL: https://docs.rails.sh/webhook-outcomes
Markdown: https://docs.rails.sh/markdown/webhook-outcomes.md

# Generic Webhook Outcomes

Status: rule-action draft recipe for partner-specific callbacks. This is a
control-plane and operator handoff surface; it does not register or enable a
hosted outbound webhook runtime by itself.

## Purpose

Generic webhook outcomes let LoyaltyRails rules queue a durable outbound
payload for a partner endpoint before the partner deserves a named adapter such
as Braze, mParticle, or Salesforce Marketing Cloud.

Use this when:

- the partner needs a callback derived from rule execution,
- the action is not yet common enough to justify a named vendor adapter,
- the payload can be reviewed as a stable contract, and
- endpoint URLs and credentials can live in backend connection metadata and
  secret references.

Do not use this as a shortcut around named vendor adapters when the provider
has strict semantics for consent, identity, rate limits, retries, or replay.

## Taxonomy

- `vendorNamespace: "webhook"`
- `integrationRecipe: "integrate rule-action webhook"`
- `runtimeAdapter: "none"` for CLI-generated draft artifacts
- `actionType: "trigger_webhook"`

`runtimeAdapter: "none"` is intentional for the CLI draft. The draft does not
install runtime code, create an integration connection, read secrets, or enable
network dispatch. Backend runtime registration and connection rollout remain
separate operator gates.

## Draft Command

```bash
loyaltyrails integrate rule-action webhook --json
```

The generated `CreateRuleRequest` stays in `draft` status and should remain
there until the operator reviews identity, consent, payload fields,
idempotency, connection metadata, retry behavior, and dead-letter handling.

## Config Shape

```json
{
  "type": "vendor_action",
  "vendorNamespace": "webhook",
  "actionType": "trigger_webhook",
  "actionKey": "lr_loyalty_webhook_event",
  "consentPurpose": "marketing_export",
  "payloadTemplate": {
    "source": "loyaltyrails",
    "eventType": "{{event.type}}",
    "eventId": "{{event.id}}",
    "memberExternalId": "{{member.externalId}}",
    "ruleName": "{{rule.name}}"
  },
  "idempotencyKeyTemplate": "rule:{{rule.id}}:{{event.idempotencyKey}}:webhook:lr_loyalty_webhook_event"
}
```

`actionKey` names a backend-configured endpoint, route, or partner contract. It
must not be a URL. Destination URLs, signing secrets, bearer tokens, API keys,
header templates, and retry policy overrides belong in backend connection
metadata and secret references.

## Runtime Semantics

When a rule executes, the rule engine writes a durable `rule.vendor_action`
outbound envelope in the same transaction as the rule outcome. The rule engine
does not call partner endpoints inline.

Once enabled, the hosted outbound layer owns:

- connection lookup,
- endpoint resolution from `actionKey`,
- secret resolution,
- request signing,
- rate limiting,
- retry scheduling,
- dead-letter review,
- replay, and
- redacted audit metadata.

## Backend Connection Metadata

Generic webhook endpoint routes live in backend `integration_connections`
metadata, not in rule config. The backend accepts `vendorNamespace: "webhook"`
connection metadata shaped like this:

```json
{
  "credentialNamespace": "production/generic-webhook",
  "endpoints": [
    {
      "actionKey": "partner_post_purchase_callback",
      "url": "https://partner.example/loyalty/callback",
      "method": "POST",
      "signing": {
        "algorithm": "hmac_sha256",
        "secretRef": "vault:/loyaltyrails/acme/webhook#signing-secret",
        "signatureHeader": "X-LoyaltyRails-Signature",
        "timestampHeader": "X-LoyaltyRails-Timestamp"
      },
      "idempotencyHeader": "Idempotency-Key",
      "correlationHeader": "X-LoyaltyRails-Correlation-Id"
    }
  ],
  "liveDispatchEnabled": false
}
```

The backend validates that endpoint routes use safe `actionKey` values, HTTPS
URLs, `POST`, HMAC-SHA256 signing, and secret references. It rejects raw
credentials in config and keeps `liveDispatchEnabled` defaulted off. Operator
credential-smoke checks can resolve signing secret references and the outbound
dashboard can show webhook rollout readiness, but this still does not enable
live sends without a hosted sender.

Compatibility note: outbound metadata currently reuses `vendorNamespace:
"webhook"` alongside the existing inbound webhook connection surface. Create
and status responses can still expose inbound-only fields such as `webhookUrl`
or `runtimeAdapter: "webhook"`. Operators should treat those fields as receiver
signals only; outbound readiness is represented by `liveSendReady` and the
`hosted_webhook_sender_implemented` rollout check.

## Operator Review Checklist

- [ ] The rule is still `draft`.
- [ ] `actionKey` is a stable backend-configured route name, not a URL.
- [ ] `payloadTemplate` contains only approved partner fields.
- [ ] The inbound event carries allowed `marketing_export` consent or the
      partner-specific consent purpose chosen for the connection.
- [ ] `idempotencyKeyTemplate` is stable across retries and replays.
- [ ] Destination URL, signing secret, bearer token, and custom headers are not
      present in rule config.
- [ ] The integration connection has redacted metadata and secret references
      only.
- [ ] The generic webhook connection has `liveDispatchEnabled=false` until the
      hosted sender has been implemented and reviewed.
- [ ] Operators know how to inspect dead letters and mark approved replays.

## Recommended Next Steps

1. Keep generic webhook outcomes draft-only until the backend connection,
   signing, retry, and replay gates are explicit for the target partner.
2. Promote repeated partner-specific webhook patterns into named vendor
   adapters once their consent, identity, rate-limit, and replay behavior is
   stable.
3. Add simulation and rollout-readiness checks before any generic webhook path
   is allowed to send live traffic.

---

# Braze Rollout Recipe

Source: ../docs/integrations/braze/rollout-recipe.md
URL: https://docs.rails.sh/braze-rollout-recipe
Markdown: https://docs.rails.sh/markdown/braze-rollout-recipe.md

# Braze Agentic Rollout Recipe

Status: operator and CLI rollout recipe for the backend-owned Braze adapter
path. This document complements the hosted adapter readiness contract; it does
not enable live dispatch by itself.

## Scope

Use this recipe when a customer wants LoyaltyRails rule outcomes or platform
events to reach Braze through the hosted outbound substrate. The recipe is also
the handoff contract for agentic CLI work that must inspect a customer's actual
app architecture before wiring ingress, identity, consent, and operator
runbooks.

Taxonomy:

- `vendorNamespace: "braze"`
- `integrationRecipe: "integrate vendor braze"`
- `runtimeAdapter: "none"` for CLI-generated planning artifacts
- `plannedRuntimeAdapter: "braze"` only inside the backend readiness contract
  and only after the registry/live gate is approved

## Official Vendor Anchors

- Create and update users:
  https://www.braze.com/docs/api/endpoints/user_data/post_user_track
- API overview and REST API key security:
  https://www.braze.com/docs/api/basics

Provider assumptions:

- Use the customer-approved HTTPS Braze REST endpoint for the workspace.
- Send `/users/track` requests with a REST API key as a server-side Bearer
  token.
- Require the `users.track` API-key permission.
- Default rule outcomes send custom events through `/users/track`.
- Bulk import remains a separate rollout decision.
- Prefer `external_id` as the primary identifier so `email` and `phone` remain
  profile attributes instead of lookup identifiers.

## Rule Outcome Wiring

Generate the rule action draft:

```bash
loyaltyrails integrate rule-action braze --json
```

Operator review must confirm:

- `ruleType: "integration_action"`
- `vendorNamespace: "braze"`
- `actionType: "track_event"`
- `actionKey` maps to the Braze custom event name
- `consentPurpose: "marketing_export"`
- `payloadTemplate` contains only approved event properties
- `idempotencyKeyTemplate` is stable for replay and duplicate prevention

When the rule executes, LoyaltyRails writes a durable `rule.vendor_action`
outbound envelope in the rule transaction. The rule engine does not call Braze
inline. Dispatch, retry, dead-letter review, replay, and audit remain owned by
hosted outbound workers.

## No-Live-Credentials Rollout

Run this sequence while real Braze credentials are unavailable:

```bash
loyaltyrails integrate vendor braze --dry-run
loyaltyrails integrate vendor braze
loyaltyrails outbound simulate --program <program-id> \
  --vendor braze \
  --scenario accepted \
  --reason "Braze rollout rehearsal"
loyaltyrails outbound snapshot --program <program-id> \
  --vendor braze \
  --window-hours 24 \
  --reason "Braze rollout snapshot"
loyaltyrails outbound dashboard --program <program-id> --vendor braze --limit 10
```

Simulation proves the LoyaltyRails mapping, config validation, secret-reference
shape, and deterministic fake transport without producing a production
credential-smoke audit event.

## Live Dispatch Gates

Do not promote a rule or connection to live dispatch until all of these are
true:

- Integration connection is active and stores only Braze secret locators.
- `platformConfig.liveDispatchEnabled` is explicitly true for the connection.
- Backend Braze runtime registration is approved for the environment.
- Replay worker and live worker runtime flags are enabled for the rollout
  window.
- `loyaltyrails outbound credential-smoke <connection-id> --reason ...` has
  passed with real secret references.
- Snapshot/dashboard history shows no blocking retry, dead-letter, consent, or
  rule-vendor-action alerts.

## Acceptance Checklist

- [ ] No raw Braze REST API key appears in generated files, manifests, audit
      metadata, or dead-letter payloads.
- [ ] Member identity maps to an approved `external_id`, `user_alias`,
      `braze_id`, `email`, or `phone` source.
- [ ] Rule action `actionKey` and payload fields match the approved mapping
      fixture.
- [ ] `marketing_export` consent is present and fail-closed behavior is
      accepted.
- [ ] Simulation, snapshot, and dashboard review are captured for the target
      program.
- [ ] Credential smoke is fresh before production live dispatch.
- [ ] Dead-letter and replay queues are clear or explicitly accepted by the
      operator.

## Recommended Next Steps

1. Use this recipe as the source of truth for Braze CLI handoff prompts and
   agentic implementation plans.
2. Keep runtime registration, credential smoke, and live worker enablement as
   separate operator gates.
3. Mirror any new Braze rule outcome type back into the mapping fixture,
   rule-action draft, simulation harness, and dashboard checks together.

---

# mParticle Rollout Recipe

Source: ../docs/integrations/mparticle/rollout-recipe.md
URL: https://docs.rails.sh/mparticle-rollout-recipe
Markdown: https://docs.rails.sh/markdown/mparticle-rollout-recipe.md

# mParticle Agentic Rollout Recipe

Status: operator and CLI rollout recipe for the backend-owned mParticle
adapter path. This document complements the hosted adapter readiness contract;
it does not enable live dispatch by itself.

## Scope

Use this recipe when a customer wants LoyaltyRails rule outcomes or platform
events to reach mParticle through the hosted outbound substrate. The recipe is
also the handoff contract for agentic CLI work that must inspect a customer's
actual app architecture before wiring ingress, identity, consent, and operator
runbooks.

Taxonomy:

- `vendorNamespace: "mparticle"`
- `integrationRecipe: "integrate vendor mparticle"`
- `runtimeAdapter: "none"` for CLI-generated planning artifacts
- `plannedRuntimeAdapter: "mparticle"` only inside the backend readiness
  contract and only after the registry/live gate is approved

## Official Vendor Anchors

- mParticle Events API: https://docs.mparticle.com/developers/apis/http/

Provider assumptions:

- Use a pod-specific Events API base URL ending in `/v2`.
- Resolve the API key and API secret from secret-manager references only.
- Send server-side Events API requests using HTTP Basic auth.
- Default rule outcomes build one `/v2/events` batch.
- `/v2/bulkevents` remains an explicit batching decision.
- Treat a rule vendor action as an Events API custom event.
- Respect provider retry guidance for rate limits and temporary failures.

## Rule Outcome Wiring

Generate the rule action draft:

```bash
loyaltyrails integrate rule-action mparticle --json
```

Operator review must confirm:

- `ruleType: "integration_action"`
- `vendorNamespace: "mparticle"`
- `actionType: "track_event"`
- `actionKey` maps to the mParticle custom event name
- `consentPurpose: "marketing_export"`
- `payloadTemplate` contains only approved event fields
- `idempotencyKeyTemplate` is stable for replay and duplicate prevention

When the rule executes, LoyaltyRails writes a durable `rule.vendor_action`
outbound envelope in the rule transaction. The rule engine does not call
mParticle inline. Dispatch, retry, dead-letter review, replay, and audit remain
owned by hosted outbound workers.

## No-Live-Credentials Rollout

Run this sequence while real mParticle credentials are unavailable:

```bash
loyaltyrails integrate vendor mparticle --dry-run
loyaltyrails integrate vendor mparticle
loyaltyrails outbound simulate --program <program-id> \
  --vendor mparticle \
  --scenario accepted \
  --reason "mParticle rollout rehearsal"
loyaltyrails outbound snapshot --program <program-id> \
  --vendor mparticle \
  --window-hours 24 \
  --reason "mParticle rollout snapshot"
loyaltyrails outbound dashboard --program <program-id> --vendor mparticle --limit 10
```

Simulation proves the LoyaltyRails mapping, config validation, secret-reference
shape, and deterministic fake transport without producing a production
credential-smoke audit event.

## Live Dispatch Gates

Do not promote a rule or connection to live dispatch until all of these are
true:

- Integration connection is active and stores only mParticle secret locators.
- `platformConfig.liveDispatchEnabled` is explicitly true for the connection.
- Backend mParticle runtime registration is approved for the environment.
- Replay worker and live worker runtime flags are enabled for the rollout
  window.
- `loyaltyrails outbound credential-smoke <connection-id> --reason ...` has
  passed with real secret references.
- Snapshot/dashboard history shows no blocking retry, dead-letter, consent, or
  rule-vendor-action alerts.

## Acceptance Checklist

- [ ] No raw mParticle credentials appear in generated files, manifests, audit
      metadata, or dead-letter payloads.
- [ ] Member identity maps to an approved mParticle user identity.
- [ ] Rule action `actionKey` and payload fields match the approved mapping
      fixture.
- [ ] `marketing_export` consent is present and fail-closed behavior is
      accepted.
- [ ] Simulation, snapshot, and dashboard review are captured for the target
      program.
- [ ] Credential smoke is fresh before production live dispatch.
- [ ] Dead-letter and replay queues are clear or explicitly accepted by the
      operator.

## Recommended Next Steps

1. Use this recipe as the source of truth for mParticle CLI handoff prompts and
   agentic implementation plans.
2. Keep runtime registration, credential smoke, and live worker enablement as
   separate operator gates.
3. Mirror any new mParticle rule outcome type back into the mapping fixture,
   rule-action draft, simulation harness, and dashboard checks together.

---

# Salesforce Marketing Cloud Rollout Recipe

Source: ../docs/integrations/salesforce_marketing_cloud/rollout-recipe.md
URL: https://docs.rails.sh/salesforce-marketing-cloud-rollout-recipe
Markdown: https://docs.rails.sh/markdown/salesforce-marketing-cloud-rollout-recipe.md

# Salesforce Marketing Cloud Agentic Rollout Recipe

Status: operator and CLI rollout recipe for the backend-owned Salesforce
Marketing Cloud adapter path. This document complements the hosted adapter
readiness contract; it does not enable live dispatch by itself.

## Scope

Use this recipe when a customer wants LoyaltyRails rule outcomes or platform
events to enter Salesforce Marketing Cloud Journey Builder through the hosted
outbound substrate. The recipe is also the handoff contract for agentic CLI
work that must inspect a customer's actual app architecture before wiring
ingress, identity, consent, and operator runbooks.

Taxonomy:

- `vendorNamespace: "salesforce_marketing_cloud"`
- `vendorAlias: "sfmc"`
- `integrationRecipe: "integrate vendor salesforce_marketing_cloud"`
- `runtimeAdapter: "none"` for CLI-generated planning artifacts
- `plannedRuntimeAdapter: "salesforce_marketing_cloud"` only inside the
  backend readiness contract and only after the registry/live gate is approved

## Official Vendor Anchors

- Server-to-server access token:
  https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/access-token-s2s.html
- Synchronous Journey Builder event entry:
  https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/postEvent.html
- Async Journey Builder batch entry:
  https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/enterContactsIntoJourneyInBatches.html
- Tenant-specific endpoints:
  https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/your-subdomain-tenant-specific-endpoints.html

Provider assumptions:

- Use the tenant Authentication Base URI plus `/v2/token` with the
  server-to-server `client_credentials` grant.
- Cache reusable OAuth tokens server-side; do not request a token for every
  rule outcome.
- Use the OAuth `rest_instance_url` for Journey Builder REST calls.
- Default rule outcomes send `POST /interaction/v1/events` with `ContactKey` and
  `EventDefinitionKey`.
- Async batch entry uses `/interaction/v1/async/events` and remains an explicit
  rollout decision.

## Rule Outcome Wiring

Generate the rule action draft:

```bash
loyaltyrails integrate rule-action sfmc --json
```

Operator review must confirm:

- `ruleType: "integration_action"`
- `vendorNamespace: "salesforce_marketing_cloud"`
- `actionType: "trigger_journey"`
- `actionKey` maps to the Journey Builder `EventDefinitionKey`
- `consentPurpose: "marketing_export"`
- `payloadTemplate` contains only approved Journey Builder `Data` fields
- `idempotencyKeyTemplate` is stable for replay and duplicate prevention

When the rule executes, LoyaltyRails writes a durable `rule.vendor_action`
outbound envelope in the rule transaction. The rule engine does not call SFMC
inline. Dispatch, retry, dead-letter review, replay, OAuth token handling, and
audit remain owned by hosted outbound workers.

## No-Live-Credentials Rollout

Run this sequence while real SFMC credentials are unavailable:

```bash
loyaltyrails integrate vendor sfmc --dry-run
loyaltyrails integrate vendor sfmc
loyaltyrails outbound simulate --program <program-id> \
  --vendor sfmc \
  --scenario accepted \
  --reason "SFMC rollout rehearsal"
loyaltyrails outbound snapshot --program <program-id> \
  --vendor sfmc \
  --window-hours 24 \
  --reason "SFMC rollout snapshot"
loyaltyrails outbound dashboard --program <program-id> --vendor sfmc --limit 10
```

Simulation proves the LoyaltyRails mapping, tenant URL validation,
secret-reference shape, OAuth request construction, and deterministic fake
transport without producing a production credential-smoke audit event.

## Live Dispatch Gates

Do not promote a rule or connection to live dispatch until all of these are
true:

- Integration connection is active and stores only SFMC secret locators.
- `platformConfig.liveDispatchEnabled` is explicitly true for the connection.
- Backend SFMC runtime registration is approved for the environment.
- Replay worker and live worker runtime flags are enabled for the rollout
  window.
- `loyaltyrails outbound credential-smoke <connection-id> --reason ...` has
  passed with real secret references.
- Snapshot/dashboard history shows no blocking OAuth, retry, dead-letter,
  consent, Journey Builder, or rule-vendor-action alerts.

## Acceptance Checklist

- [ ] No SFMC client ID, client secret, bearer token, authorization value, or
      access token appears in generated files, manifests, audit metadata, or
      dead-letter payloads.
- [ ] Member identity maps to the approved `ContactKey`.
- [ ] Rule action `actionKey` maps to the approved `EventDefinitionKey`.
- [ ] Payload fields match the approved mapping fixture and Journey Builder
      `Data` contract.
- [ ] `marketing_export` consent is present and fail-closed behavior is
      accepted.
- [ ] Simulation, snapshot, and dashboard review are captured for the target
      program.
- [ ] Credential smoke is fresh before production live dispatch.
- [ ] Dead-letter and replay queues are clear or explicitly accepted by the
      operator.

## Recommended Next Steps

1. Use this recipe as the source of truth for SFMC CLI handoff prompts and
   agentic implementation plans.
2. Keep runtime registration, credential smoke, OAuth cache behavior, and live
   worker enablement as separate operator gates.
3. Mirror any new SFMC Journey Builder outcome type back into the mapping
   fixture, rule-action draft, simulation harness, and dashboard checks
   together.

---

# SDK Components

Source: ../docs/sdk-components.md
URL: https://docs.rails.sh/sdk-components
Markdown: https://docs.rails.sh/markdown/sdk-components.md

# SDK Components

Status: migration source is highly relevant; platform package and recipe wiring
still need consolidation.

The original TOLDs SDK is not just an API client. Its most durable asset is a
React-focused loyalty component system: frontend components such as
`TierProgress`, `PointsBalance`, `OfferGrid`, `RewardCatalog`, `PunchCard`, and
`ChallengeBoard`.

These components are intentionally platform agnostic. They should remain useful
across rails, Shopify Hydrogen, Next.js, TanStack Router, TanStack
Start, React Router, Vite, Astro, and other React host apps.

## Source Material

Current source material lives in `~/Development/tolds`:

| Source | Use |
|--------|-----|
| `ARCHITECTURE.md` | Backend-agnostic component and adapter model |
| `COMPONENT_PLAYBOOK.md` | Component standards, docs anatomy, a11y, theming, and framework support |
| `MANUAL_INSTALLATION.md` | Manual install and framework-specific CSS notes |
| `packages/react/src/components/*` | Loyalty UI components |
| `packages/react/src/progress/*` | Progress system used by `TierProgress` |
| `packages/docs/src/content/components/*` | Component MDX docs |
| `packages/docs/src/examples/components/*` | Copyable component examples |
| `packages/examples-nextjs/*` | Next.js examples |
| `packages/examples-tanstack-router/*` | TanStack Router examples |
| `packages/examples-tanstack-start/*` | TanStack Start examples |
| `packages/examples-react-router/*` | React Router examples |

## Component Principles

The component documentation should preserve these rules:

- Components accept canonical props and do not call loyalty backends directly.
- Components do not import vendor SDKs.
- Components do not contain browser-exposed secrets.
- Host apps own auth, data fetching, mutations, and idempotency.
- Adapters map rails or third-party vendor data into canonical component
  props.
- Components accept `className`, support theme tokens, and work in light, dark,
  and high-contrast modes.
- Interactive components include keyboard and screen-reader behavior.

Think of the SDK component layer as loyalty-specific headless UI: components
render the experience, while recipes and adapters supply the data.

## Component References

Published migration references:

| Component | Reference | Notes |
|-----------|-----------|-------|
| `TierProgress` | [TierProgress](./sdk/components/tier-progress.md) | Tier progress, framework notes, Hydrogen adaptation pattern |
| `PointsBalance` | [PointsBalance](./sdk/components/points-balance.md) | Balance display, server-only data boundary, state guidance |
| `CampaignTiles` | [CampaignTiles](./sdk/components/campaign-tiles.md) | rails target based on the TOLDs `OfferGrid`/`OfferTile` lineage |

## Canonical Data Layer

Component docs should teach the canonical shapes independently from any one
backend:

| Shape | Purpose |
|-------|---------|
| `Member` | Display name, identifiers, locale, and optional provider extras |
| `TierStatus` | Current tier, next tier, progress, points to next tier, period, benefits |
| `PointsAccount` | Balance, pending value, currency, expiry windows |
| `ActivityItem` | Earn, burn, adjustment, bonus, reference, description |
| `Offer` | Offer state, eligibility, reward, dates, CTAs |
| `Challenge` | Progress, steps, windows, completion state |
| `Reward` | Redemption cost, rules, inventory, confirmation state |

rails adapters should map backend API responses into these shapes.
Shopify adapters may combine rails data with Shopify customer, order, or
metafield data before rendering the same components.

## TierProgress Example

`TierProgress` is a good example of the desired documentation model. The
component only needs tier props. This snippet uses the intended
`@loyaltyrails/react` package naming, but `TierProgress` is not part of that
package today: the live package (`packages/react/src/index.ts`) currently
ships `PointsBalance`, `TierBadge`, `RedemptionCard`, `SpinWheel`,
`OnboardingChallenge`, and `CampaignTiles` — no `TierProgress`. Treat the
import below as a planned addition and finalize the exact export during SDK
packaging.

```tsx
// Planned import — not yet exported by @loyaltyrails/react today.
import { TierProgress } from '@loyaltyrails/react';
import type { TierStatus } from '@loyaltyrails/react';

export function AccountTierProgress({ tier }: { tier: TierStatus }) {
  return (
    <TierProgress
      progress={tier.progress}
      showLabels
      currentLabel={tier.currentTier}
      nextLabel={tier.nextTier}
      showPercentage
    />
  );
}
```

The framework guide should show how `tier` is loaded for that framework. The
component reference should not assume whether data came from rails,
Shopify, a cache, or another loyalty provider.

## Recipe And Component Coupling

The CLI recipes should eventually support combined backend and frontend
installation paths.

For example, a Shopify Hydrogen tier-progress recipe should document and
generate both layers:

| Layer | Responsibility |
|-------|----------------|
| Backend recipe | Server-only rails helper, Shopify identity mapping, balance/tier route, optional webhook ingestion |
| Data adapter | Map rails and Shopify data into `TierStatus` |
| Frontend component | Add a Hydrogen-safe `TierProgress` wrapper and styling tokens |
| Host integration | Place the wrapper in account, product, cart, or checkout-adjacent surfaces |
| Verification | Run `loyaltyrails doctor`, smoke-test the member/tier route, and render the component without secrets |

The generated frontend component should call the host app's route, not rails
directly from browser code.

## Framework Guide Requirements

Each framework page should include:

- Install or copy mode.
- Where to import CSS and tokens.
- Where server-side routes or loaders live.
- How identity is derived.
- How to map host data into canonical props.
- Loading, empty, error, and signed-out states.
- SSR and hydration notes.
- Accessibility checks.
- Recipe commands when a CLI recipe exists.

Initial framework targets:

| Framework | Documentation emphasis |
|-----------|------------------------|
| Next.js App Router | Server routes, React Server Components boundary, client component wrappers |
| Shopify Hydrogen | Storefront routes, customer identity, Shopify order webhooks, account/cart placement |
| TanStack Router | Loader data, route context, TanStack Query integration |
| TanStack Start | Server functions, SSR, hydration |
| React Router | Loaders/actions and client wrappers |
| Vite/manual React | Manual CSS import and app-owned data fetching |

## Documentation Structure

The SDK docs should split component docs from API-client docs:

```text
SDK
  Overview
  Component Principles
  Canonical Data Shapes
  Components
    TierProgress
    PointsBalance
    OfferGrid
    RewardCatalog
    ChallengeBoard
  Framework Guides
    Next.js
    Shopify Hydrogen
    TanStack Router
    TanStack Start
    React Router
    Vite
  Recipes
    Add TierProgress
    Add Balance Widget
    Add Campaign Tiles
  API Client Migration Notes
```

The component docs can be migrated from TOLDs earlier than the API client,
because their contract is mostly platform agnostic. API-client docs should wait
until route/auth contracts are aligned with rails.

## Acceptance Criteria

The component docs are ready to publish when:

- Component examples use rails package names.
- Components remain backend-agnostic and props-driven.
- Framework guides show where data fetching belongs.
- Examples keep secrets server-side.
- Shopify Hydrogen docs explain both frontend placement and backend recipe
  wiring.
- Component prop references are generated or checked from source.
- Accessibility, theming, loading, empty, and error states are documented.

---

# TierProgress

Source: ../docs/sdk/components/tier-progress.md
URL: https://docs.rails.sh/tier-progress
Markdown: https://docs.rails.sh/markdown/tier-progress.md

# TierProgress

Status: component documentation migrated from TOLDs source material.
`TierProgress` is not part of the live `@loyaltyrails/react` package
(`packages/react/src/index.ts`) today — that package currently ships
`PointsBalance`, `TierBadge`, `RedemptionCard`, `SpinWheel`,
`OnboardingChallenge`, and `CampaignTiles` instead. Treat the imports on this
page as a planned addition, not a shipped export.

`TierProgress` renders a member's movement from one loyalty tier to the next.
It is a platform-agnostic React component: it accepts canonical props and does
not call rails, Shopify, or any other backend directly.

Use it when the host app already has a tier snapshot from a server route,
loader, server component, or cache and needs to render progress consistently
across account, checkout-adjacent, campaign, or dashboard surfaces.

## Current Source References

Agent-oriented source map:

- rails migration context: `docs/sdk-components.md`
- SDK/API caveats: `docs/sdk-reference.md`
- Current SDK package inventory: `packages/sdk/src/*`
- TOLDs component source:
  `~/Development/tolds/packages/react/src/components/TierProgress.tsx`
- TOLDs progress dependency:
  `~/Development/tolds/packages/react/src/progress/*`
- TOLDs canonical types:
  `~/Development/tolds/packages/data/src/types/domain.ts`
- TOLDs docs/example:
  `~/Development/tolds/packages/docs/src/content/components/status-earned-value/tier-progress.mdx`
  and
  `~/Development/tolds/packages/docs/src/examples/components/tier-progress/tier-progress-basic.tsx`

## Props And Data Shape

The component supports three equivalent input modes. Choose one mode per render.

```ts
type TierStatus = {
  currentTier: string;
  nextTier?: string | null;
  progress: number; // 0..1
  pointsToNext?: number | null;
  periodStart?: string;
  periodEnd?: string;
  benefits?: Array<{ code: string; label: string; description?: string }>;
  programId?: string;
  programName?: string;
  extras?: Record<string, unknown>;
};

type TierProgressProps =
  | { tier: TierStatus; label?: string }
  | { progress: number; label?: string }
  | { currentPoints: number; nextTierPoints: number; label?: string };
```

Common display props from the TOLDs implementation include:

| Prop | Purpose |
|------|---------|
| `showLabels` | Shows current and next tier labels. |
| `currentLabel`, `nextLabel` | Overrides labels derived from `tier`. |
| `etaText` | Adds helper copy such as points remaining or period end. |
| `variant` | Supports `bar`, `segmented`, `ring`, `stepper`, `arc`, `ladder`, `timeline`, and legacy variants. |
| `showPercentage` | Renders the computed percentage as text. |
| `percentagePlacement` | Places the percentage `inside` or `outside` where supported. |
| `segments`, `milestones` | Adds segmented or milestone-based progress. |
| `animate`, `durationMs` | Controls progress animation. |
| `size`, `className`, `style` | Host app styling controls. |

`progress` is normalized from `0` to `1`. `currentPoints` and
`nextTierPoints` are converted into the same percentage internally.

## Usage

This example keeps data fetching on the server. Replace the server function with
your app's route, loader, or server action once the rails adapter
contract is finalized.

```tsx
// Planned import — not yet exported by @loyaltyrails/react today.
import { TierProgress } from '@loyaltyrails/react';
import type { TierStatus } from '@loyaltyrails/react';

type AccountTierProps = {
  tier: TierStatus;
};

export function AccountTierProgress({ tier }: AccountTierProps) {
  return (
    <TierProgress
      tier={tier}
      showLabels
      showPercentage
      etaText={
        tier.pointsToNext
          ? `${tier.pointsToNext.toLocaleString()} points to ${tier.nextTier}`
          : undefined
      }
    />
  );
}
```

For static or demo surfaces, pass direct progress:

```tsx
// Planned import — not yet exported by @loyaltyrails/react today.
import { TierProgress } from '@loyaltyrails/react';

export function PreviewTierProgress() {
  return (
    <TierProgress
      progress={0.64}
      currentLabel="Gold"
      nextLabel="Platinum"
      variant="segmented"
      segments={8}
      showLabels
      showPercentage
    />
  );
}
```

## Accessibility Expectations

`TierProgress` should expose `role="progressbar"` for determinate progress with
`aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and an accessible label.
Visible labels should not be the only accessibility path; provide `label` when
the surrounding page context is ambiguous.

Animation must respect `prefers-reduced-motion`. The TOLDs implementation has a
reduced-motion guard for legacy variants. When porting to rails, keep
that behavior and test progress updates with screen readers, keyboard-only
navigation, light mode, dark mode, and high-contrast mode.

## Styling And Theming

The source component uses CSS variables such as `--tolds-muted`,
`--tolds-accent`, `--tolds-accent-contrast`, `--tolds-radius-pill`, and
`--tolds-font-size-sm`. During migration, these should become rails
tokens or compatibility aliases.

Recommended theming rules:

- Import component/tokens CSS once at the framework root.
- Prefer `className` for layout and local spacing.
- Use semantic tier tokens only for accents; do not rely on color alone to
  communicate progress.
- Verify long tier names, localized labels, and right-to-left layouts.
- Avoid browser-side formatting assumptions; pass already localized helper copy
  when business language matters.

## Framework Notes

### Next.js App Router

Fetch tier data in a server component, route handler, or server action. Render a
small client wrapper only if the selected `TierProgress` variant uses animation
or browser-only effects. Do not put rails integration keys in client
components.

```tsx
// app/account/tier/page.tsx
import { AccountTierProgress } from './AccountTierProgress';
import { getTierForCurrentMember } from '@/lib/server/loyalty';

export default async function TierPage() {
  const tier = await getTierForCurrentMember();
  return <AccountTierProgress tier={tier} />;
}
```

### TanStack Router

Load the member tier in the route loader or through TanStack Query using a
browser-safe application route. The component should receive a `TierStatus`
object from loader data or query data, not a rails client instance.

```tsx
export const Route = createFileRoute('/account/tier')({
  loader: ({ context }) => context.loyalty.getTierForCurrentMember(),
  component: TierRoute,
});

function TierRoute() {
  const tier = Route.useLoaderData();
  return <TierProgress tier={tier} showLabels showPercentage />;
}
```

### Shopify Hydrogen

Use Hydrogen customer identity on the server, map it to the rails member
identifier in a server-only route or loader, then pass canonical `TierStatus` to
the component. Good placements include account overview, cart nudges, product
purchase incentives, and checkout-adjacent surfaces. Do not call rails
with integration credentials from the storefront browser.

## States

The host app owns loading, empty, signed-out, and error states. Suggested
patterns:

- Loading: reserve stable layout space or render a skeleton outside the
  component.
- Empty: show an enrollment prompt instead of a zero-progress tier when the
  member is not enrolled.
- Error: show retry UI and log the server trace ID outside the component.
- Signed out: avoid rendering member-specific tier data.

## Implementation Status And Caveats

The TOLDs implementation is mature as a props-driven React component, but the
rails adapter is not finished, and `TierProgress` has no export in the live
`@loyaltyrails/react` package yet (see the Status note above). The current
repository also has `@loyaltyrails/sdk` API-client inventory in `packages/sdk`,
but `docs/sdk-reference.md` flags route/auth drift and says not to present
that client as the production browser integration path.

Migration tasks before GA:

- Add a `TierProgress` export to the live `@loyaltyrails/react` package
  (`packages/react/src/index.ts`) alongside its existing components.
- Rename TOLDs tokens/imports to rails tokens/imports.
- Validate `TierStatus` against the rails backend DTOs or an adapter.
- Keep the component backend-agnostic and props-only.
- Add typechecked examples for Next.js, TanStack Router, and Hydrogen recipes.

---

# PointsBalance

Source: ../docs/sdk/components/points-balance.md
URL: https://docs.rails.sh/points-balance
Markdown: https://docs.rails.sh/markdown/points-balance.md

# PointsBalance

Status: component documentation migrated from TOLDs source material. rails
package naming and backend adapters are not final. The live
`@loyaltyrails/react` package (`packages/react/src/index.ts`) does export a
`PointsBalance` component today, but its real props (`value`, `className`,
`style`, `unit`, `loadingFallback`, reading from `LoyaltyProvider` context)
are simpler than the `account`/`points`/`accrualRate`/`expiryHint` API
documented below — this page still describes the TOLDs-derived migration
target, not the shipped component.

`PointsBalance` displays a member's current points or miles balance with
optional accrual and expiration metadata. It is a platform-agnostic React
component: the host app fetches and maps data, and the component renders the
canonical shape.

Use it in account summaries, member dashboards, cart/account sidebars, Hydrogen
account routes, or embedded loyalty panels where the balance is already safe to
show to the current member.

## Current Source References

Agent-oriented source map:

- rails migration context: `docs/sdk-components.md`
- SDK/API caveats: `docs/sdk-reference.md`
- Current SDK package inventory: `packages/sdk/src/*`
- TOLDs component source:
  `~/Development/tolds/packages/react/src/components/PointsBalance.tsx`
- TOLDs canonical types:
  `~/Development/tolds/packages/data/src/types/domain.ts`
- TOLDs docs/example:
  `~/Development/tolds/packages/docs/src/content/components/status-earned-value/points-balance.mdx`
  and
  `~/Development/tolds/packages/docs/src/examples/components/points-balance/points-balance-basic.tsx`

## Props And Data Shape

The component accepts either a full canonical account object or a direct points
number.

```ts
type PointsAccount = {
  balance: number;
  pending?: number;
  currency: 'points' | 'miles' | string;
  expiry?: Array<{ date: string; amount: number }>;
  programId?: string;
  programName?: string;
  extras?: Record<string, unknown>;
};

type PointsBalanceProps =
  | {
      account: PointsAccount;
      label?: string;
      accrualRate?: string;
      expiryHint?: string;
      className?: string;
      style?: React.CSSProperties;
    }
  | {
      points: number;
      label?: string;
      accrualRate?: string;
      expiryHint?: string;
      className?: string;
      style?: React.CSSProperties;
    };
```

| Prop | Purpose |
|------|---------|
| `account` | Canonical points account from an adapter. |
| `points` | Direct numeric balance for simple or static renders. |
| `label` | Accessible and visible label; defaults to `Points balance`. |
| `accrualRate` | Optional display copy such as `2x on groceries`. |
| `expiryHint` | Optional display copy for upcoming expiration. |
| `className`, `style` | Host app styling controls. |

The TOLDs source formats the number through a component context formatter. In
rails, keep number/date formatting owned by the app or by a shared
provider so locale, currency, and copy rules remain explicit.

## Usage

This example renders an account object that was fetched server-side and adapted
before it reached the browser component.

```tsx
// This shows the migration-target API — the live @loyaltyrails/react
// PointsBalance component accepts value/unit/loadingFallback today, not
// account/points/accrualRate/expiryHint (see Status above).
import { PointsBalance } from '@loyaltyrails/react';
import type { PointsAccount } from '@loyaltyrails/react';

type AccountBalanceProps = {
  account: PointsAccount;
};

export function AccountPointsBalance({ account }: AccountBalanceProps) {
  const nextExpiry = account.expiry?.[0];

  return (
    <PointsBalance
      account={account}
      label={account.programName ?? 'Rewards balance'}
      expiryHint={
        nextExpiry
          ? `${nextExpiry.amount.toLocaleString()} ${account.currency} expire ${new Date(
              nextExpiry.date,
            ).toLocaleDateString()}`
          : undefined
      }
    />
  );
}
```

For lightweight surfaces, pass `points` directly:

```tsx
import { PointsBalance } from '@loyaltyrails/react';

export function HeaderBalance() {
  return <PointsBalance points={12840} label="Available points" />;
}
```

## Accessibility Expectations

`PointsBalance` should render the label and numeric balance as text, not as
decorative-only content. The TOLDs source wraps the display in a labeled
`section` and inner `role="group"`, which is a good baseline for screen reader
navigation.

Guidelines:

- Make `label` specific when multiple balances appear on the same page.
- Do not communicate expiration, pending, or earning state by color alone.
- If the balance updates after a mutation, announce the update from the host app
  with an `aria-live` region.
- Keep large numbers readable with locale-aware formatting.

## Styling And Theming

The source component uses CSS variables such as `--tolds-muted`,
`--tolds-muted-fg`, `--tolds-space-sm`, `--tolds-space-md`,
`--tolds-radius-md`, and `--tolds-font-size-lg`. During migration, these should
become rails tokens or compatibility aliases.

Recommended theming rules:

- Import component/tokens CSS once at the framework root.
- Use `className` for local layout and responsive placement.
- Keep the balance compact enough for account headers and panels.
- Test light, dark, high-contrast, long labels, and large balances.
- Treat `expiryHint` as content supplied by the host app so legal/program copy
  can be reviewed outside the component.

## Framework Notes

### Next.js App Router

Fetch the balance in a server component, route handler, or server action. Pass
only the adapted `PointsAccount` or direct number to the client component. Never
expose rails integration keys in browser code.

```tsx
// app/account/page.tsx
import { AccountPointsBalance } from './AccountPointsBalance';
import { getPointsForCurrentMember } from '@/lib/server/loyalty';

export default async function AccountPage() {
  const account = await getPointsForCurrentMember();
  return <AccountPointsBalance account={account} />;
}
```

### TanStack Router

Use a route loader for SSR-friendly balance data or TanStack Query against a
browser-safe route owned by the app. The component should receive data, not
perform the fetch.

```tsx
export const Route = createFileRoute('/account')({
  loader: ({ context }) => context.loyalty.getPointsForCurrentMember(),
  component: AccountRoute,
});

function AccountRoute() {
  const account = Route.useLoaderData();
  return <PointsBalance account={account} label="Rewards balance" />;
}
```

### Shopify Hydrogen

Hydrogen should resolve the Shopify customer on the server, map that identity to
a rails member, then render a canonical `PointsAccount`. Relevant
placements include account overview, cart drawer, product PDP incentives, and
order history. Keep server-only rails credentials in Hydrogen server
code or a backend integration route.

## States

The host app owns loading, empty, signed-out, and error states.

- Loading: reserve the balance footprint or show a skeleton outside the
  component.
- Empty: use a program enrollment or activation prompt when no account exists.
- Error: avoid showing stale balances unless clearly labeled as last updated.
- Signed out: render a sign-in prompt rather than member-specific value.

## Implementation Status And Caveats

The TOLDs `PointsBalance` source is compact and props-driven. It currently
depends on TOLDs naming and formatting context, and the rails backend
adapter is not complete.

Important caveat: `packages/sdk` contains a `getBalance` method, but
`docs/sdk-reference.md` identifies API-client route/auth drift. Component docs
should not imply that production browser apps can call rails directly
with that client.

Migration tasks before GA:

- Reconcile this page's `account`/`points` prop API with the live
  `@loyaltyrails/react` `PointsBalance` component's simpler
  `value`/`unit`/`loadingFallback` API, or extend the shipped component to
  cover the richer shape documented here.
- Rename TOLDs tokens/imports to rails tokens/imports.
- Define the rails adapter from backend balance DTOs to
  `PointsAccount`.
- Preserve server-side auth and browser-safe rendering boundaries.
- Add examples that typecheck in Next.js, TanStack Router, and Hydrogen.

---

# CampaignTiles

Source: ../docs/sdk/components/campaign-tiles.md
URL: https://docs.rails.sh/campaign-tiles
Markdown: https://docs.rails.sh/markdown/campaign-tiles.md

# CampaignTiles

Status: planned rails component page based on TOLDs `OfferGrid` and
`OfferTile` source material. A literal `CampaignTiles` component was not found
in `~/Development/tolds`; treat this page as the migration target for
campaign-facing offer tiles. The live `@loyaltyrails/react` package
(`packages/react/src/index.ts`) does ship a `CampaignTiles` component today,
but its real props (`campaigns: {id, title, description, mechanic, accent,
actionLabel, onOpen, ribbon, locked, lockedHint}[]`, `title`, `layout`,
`className`, `style`) are a simpler, gamification-mechanic-oriented shape —
not the `Offer`-derived `CampaignStatus`/`eligibility`/`reward`/`ctas` API
documented below.

`CampaignTiles` renders a responsive set of loyalty campaigns, offers, or
promotions. It should remain platform agnostic: host apps fetch campaign data,
map it into canonical props, and pass event handlers for user actions.

Use it for account offer shelves, Shopify storefront incentives, campaign
landing panels, dashboard previews, and embedded loyalty experiences where
members can inspect or activate available campaigns.

## Current Source References

Agent-oriented source map:

- rails migration context: `docs/sdk-components.md`
- SDK/API caveats: `docs/sdk-reference.md`
- Current SDK package inventory: `packages/sdk/src/*`
- TOLDs grid source:
  `~/Development/tolds/packages/react/src/components/OfferGrid.tsx`
- TOLDs tile source:
  `~/Development/tolds/packages/react/src/components/OfferTile.tsx`
- TOLDs canonical `Offer` type:
  `~/Development/tolds/packages/data/src/types/domain.ts`
- TOLDs docs/example:
  `~/Development/tolds/packages/docs/src/content/components/offers-rewards/offer-grid.mdx`
  and
  `~/Development/tolds/packages/docs/src/examples/components/offer-grid/offer-grid-basic.tsx`

## Props And Data Shape

Until a rails `CampaignTiles` source component exists, model it as an
offer/campaign grid over canonical `Offer` data.

```ts
type CampaignStatus = 'active' | 'upcoming' | 'expired' | 'enrolled' | 'ineligible';

type CampaignTile = {
  id: string | number;
  title: string;
  description?: string;
  status: CampaignStatus;
  eligibility?: {
    state: 'eligible' | 'ineligible' | 'unknown';
    reason?: string;
  };
  start?: string;
  end?: string;
  reward?: {
    type: 'points' | 'coupon' | 'cash' | string;
    value?: number | string;
  };
  ctas?: Array<{
    label: string;
    action: 'enroll' | 'view' | 'shop' | 'link' | string;
    href?: string;
  }>;
  programId?: string;
  programName?: string;
  extras?: Record<string, unknown>;
};

type CampaignTilesProps = {
  campaigns: CampaignTile[];
  minColumnWidth?: number;
  columns?: number;
  imageForCampaign?: (campaign: CampaignTile) => string | undefined;
  renderBadge?: (campaign: CampaignTile) => React.ReactNode;
  onAction?: (campaignId: CampaignTile['id']) => void;
  ctaLabel?: string;
  getStatus?: (campaign: CampaignTile) => string | null;
  isEligible?: (campaign: CampaignTile) => boolean;
  getEndsAt?: (campaign: CampaignTile) => string | null;
  countdownFormatter?: (ms: number) => string;
  className?: string;
  style?: React.CSSProperties;
};
```

TOLDs `OfferGrid` names these props `offers`, `imageForOffer`, `onAction`,
`getStatus`, `isEligible`, and `getEndsAt`. rails can either preserve
the offer naming for source compatibility or add a thin campaign-named wrapper.

## Usage

The example below uses pre-adapted campaign data. The action handler is supplied
by the host app so this component example does not include secrets or browser
backend calls.

```tsx
// This shows the migration-target API — the live @loyaltyrails/react
// CampaignTiles component takes {id, title, mechanic, onOpen, ...} tiles
// today, not the Offer-derived shape below (see Status above).
import { CampaignTiles } from '@loyaltyrails/react';
import type { CampaignTile } from '@loyaltyrails/react';

type CampaignShelfProps = {
  campaigns: CampaignTile[];
  onActivate: (campaignId: CampaignTile['id']) => void;
};

export function CampaignShelf({ campaigns, onActivate }: CampaignShelfProps) {
  return (
    <CampaignTiles
      campaigns={campaigns}
      minColumnWidth={280}
      ctaLabel="Activate"
      onAction={onActivate}
      getStatus={(campaign) => campaign.status}
      isEligible={(campaign) => campaign.eligibility?.state !== 'ineligible'}
      getEndsAt={(campaign) => campaign.end ?? null}
    />
  );
}
```

If the migrated component is still named `OfferGrid`, use this temporary
adapter shape:

```tsx
import { OfferGrid } from '@loyaltyrails/react';
import type { Offer } from '@loyaltyrails/react';

export function CampaignShelf({ campaigns }: { campaigns: Offer[] }) {
  return (
    <OfferGrid
      offers={campaigns}
      minColumnWidth={280}
      ctaLabel="Activate"
      getStatus={(offer) => offer.status}
      isEligible={(offer) => offer.eligibility?.state !== 'ineligible'}
      getEndsAt={(offer) => offer.end ?? null}
    />
  );
}
```

## Accessibility Expectations

The grid should preserve reading order and keyboard focus order. Each tile
should have a clear heading, text status, and CTA name. Decorative images should
use empty alt text and `aria-hidden`; meaningful campaign imagery needs
descriptive alt text supplied by the host app.

Guidelines:

- Prefer a semantic section with a specific accessible label such as
  `Available campaigns`.
- Expose state text for active, upcoming, expired, enrolled, and ineligible
  campaigns.
- Disable unavailable CTAs with both native `disabled` and appropriate
  explanatory copy nearby.
- Avoid using countdown timers as the only urgency signal.
- Announce activation success or failure from the host app after mutations.

## Styling And Theming

The TOLDs source uses CSS variables such as `--tolds-muted`,
`--tolds-muted-fg`, `--tolds-accent`, `--tolds-accent-contrast`,
`--tolds-space-md`, `--tolds-radius-md`, and `--tolds-font-size-sm`. During
migration, these should become rails tokens or compatibility aliases.

Recommended theming rules:

- Use `minColumnWidth` for responsive auto-fit grids.
- Keep tile media aspect ratios stable to avoid layout shift.
- Make status and eligibility visible in text, not only color.
- Test long campaign names, localized CTA text, RTL, and high-contrast mode.
- Keep generated or personalized copy provenance outside the critical CTA path
  unless the product explicitly enables AI content surfaces.

## Framework Notes

### Next.js App Router

Fetch campaigns in a server component or route handler. Mutations such as
activation/enrollment should go through server actions or app-owned API routes
that add idempotency keys and server-side rails credentials.

```tsx
// app/account/campaigns/page.tsx
import { CampaignShelf } from './CampaignShelf';
import { getCampaignsForCurrentMember } from '@/lib/server/loyalty';

export default async function CampaignsPage() {
  const campaigns = await getCampaignsForCurrentMember();
  return <CampaignShelf campaigns={campaigns} />;
}
```

### TanStack Router

Use route loaders for campaign reads and actions or mutations for activation.
If using TanStack Query, call a browser-safe app route and keep integration
credentials server-side.

```tsx
export const Route = createFileRoute('/account/campaigns')({
  loader: ({ context }) => context.loyalty.getCampaignsForCurrentMember(),
  component: CampaignsRoute,
});

function CampaignsRoute() {
  const campaigns = Route.useLoaderData();
  return <CampaignTiles campaigns={campaigns} minColumnWidth={280} />;
}
```

### Shopify Hydrogen

Hydrogen is a strong fit for campaign tiles, but it needs both layers:

- Server route or loader: derive Shopify customer identity and map it to a
  rails member.
- Adapter: combine rails campaign eligibility with Shopify customer,
  product, cart, order, or metafield context when needed.
- Storefront component: render canonical campaign props in account, cart,
  product, or collection surfaces.
- Mutation route: activate, enroll, or redeem through a server-only endpoint
  with idempotency.

Do not expose rails integration keys in storefront JavaScript.

## States

The host app owns loading, empty, signed-out, and error states.

- Loading: use skeleton tiles with fixed dimensions when campaign fetches are
  pending.
- Empty: show neutral copy such as no available campaigns rather than a broken
  grid.
- Error: show retry UI and avoid partially activating campaigns without a clear
  result.
- Signed out: show sign-in or enrollment prompts instead of personalized
  eligibility.
- Disabled: explain ineligible, expired, upcoming, or sold-out states in text.

## Implementation Status And Caveats

No `CampaignTiles` component was found in the TOLDs React source, but a
`CampaignTiles` component now ships in `@loyaltyrails/react`
(`packages/react/src/CampaignTiles.tsx`) with a gamification-mechanic-oriented
shape (see Status above), not the `Offer`/`OfferGrid`-derived shape this page
documents.

Important caveat: the current `packages/sdk` API client is not the production
component data source. `docs/sdk-reference.md` calls out route/auth drift and
server-only integration-key concerns. Campaign examples should keep reads and
mutations behind host app routes, loaders, or server functions.

Migration tasks before GA:

- Reconcile this page's `Offer`-derived prop API with the live
  `@loyaltyrails/react` `CampaignTiles` component's shipped mechanic-tile API,
  or extend the shipped component to cover the richer shape documented here.
- Rename TOLDs tokens/imports to rails tokens/imports.
- Define the adapter from rails campaign/offer DTOs to canonical
  campaign tile props.
- Add idempotent activation/enrollment recipe examples.
- Add typechecked examples for Next.js, TanStack Router, and Shopify Hydrogen.

---

# SDK API Client Migration

Source: ../docs/sdk-reference.md
URL: https://docs.rails.sh/sdk-api-client
Markdown: https://docs.rails.sh/markdown/sdk-api-client.md

# SDK Migration Notes

Status: split migration track. The platform-agnostic React component docs are
highly reusable; the API-client contract is not yet adapted to rails.

Package currently present in this repository: `@loyaltyrails/sdk`

Current source inventory:

- `packages/sdk/src/client.ts`
- `packages/sdk/src/types.ts`
- `packages/sdk/src/http.ts`
- `packages/sdk/src/errors.ts`
- Platform-agnostic component SDK and documentation material in
  `~/Development/tolds`

## Current Position

The SDK work has two different surfaces that should be documented separately:

| Surface | Status | Documentation stance |
|---------|--------|----------------------|
| React loyalty components | Highly relevant and mostly platform agnostic | Migrate and publish as SDK component docs after package naming and examples are updated |
| API client methods | Not adapted to rails route/auth contracts | Keep as migration notes until the platform client contract is redesigned |

The original TOLDs component model deliberately kept React loyalty components
independent from backend vendors. Components such as `TierProgress` consume
canonical props and do not call provider APIs directly. That documentation is
still valuable for rails, Shopify Hydrogen, Next.js, TanStack Router,
TanStack Start, and other React host apps.

The current platform integration paths are:

- The backend API, especially `/internal/v1/*` for server-side integration-key
  flows.
- The rails CLI and generated integration recipes.
- The CLI local integration agent, which plans, previews, and applies supported
  recipes through safety gates.

Until the API client is intentionally migrated, do not present `packages/sdk`
API examples as the recommended way to integrate production applications. The
component SDK docs should move forward as a separate, platform-agnostic track.

See also [SDK Components](./sdk-components.md).

## API Client Inventory

The current `packages/sdk` package exports these API client methods:

| Method | Migration status |
|--------|------------------|
| `award(params)` | Legacy inventory; review against `/internal/v1/award` and current DTOs |
| `getBalance(customerId)` | Legacy inventory; route/auth model must be redesigned |
| `redeem(params)` | Legacy inventory; route/auth model must be redesigned |
| `getBatches(params)` | Legacy inventory; review against batch lineage API |
| `getBatchLineage(batchId)` | Legacy inventory; review against batch lineage API |
| `getLiability(programId?, groupBy?)` | Legacy inventory; review against liability API |
| `getBatchContext(contextRef)` | Legacy inventory; review against context API |

Important drift to resolve before public API-client docs exist:

- The SDK HTTP client always sends `X-API-Key`.
- Some legacy methods target `/alp/v1/*`.
- The backend still mounts `/alp/v1/*` behind a wallet-context end-user JWT,
  but that surface is legacy — the current end-user surface is
  `/public/v1/members/me/*`, authenticated with a short-lived member JWT
  minted server-side via `/api/v1/member-tokens/issue` (see
  [Authentication § End-User Access](./authentication.md#end-user-access)).
  Any future SDK client work should target `/public/v1/members/me/*`, not
  `/alp/v1/*`.
- Server-side integration-key flows live under `/internal/v1/*`.
- Current SDK response types do not fully match the Rust backend DTOs.

This drift is expected because the API client has not been adapted. It should
not be framed as a bug in a GA SDK.

## Component SDK Inventory

The component SDK material in `~/Development/tolds` is much more reusable. It
should be migrated as component documentation and recipe source material.

High-value component areas:

| Area | Examples |
|------|----------|
| Status and earned value | `TierProgress`, `TierRibbon`, `PointsBalance`, `PointsActivity` |
| Offers and rewards | `OfferTile`, `OfferGrid`, `RewardCatalog`, `RedemptionFlow` |
| Progress and challenges | `PunchCard`, `ChallengeBoard`, `MiniChallenge`, `StreakTracker`, `BadgeCase` |
| Identity and membership | `MemberCard`, `ProfileBadge`, `MemberQR`, `MemberBarcode` |
| Agentic and dynamic | `AgentRecommendationCard`, `AgentPermissionBanner`, `AgentTrustMeter` |

Component docs should preserve the backend-agnostic contract:

- Components accept canonical props.
- Components do not import vendor SDKs or call rails directly.
- Host apps own auth, data fetching, mutations, and idempotency.
- Recipes and adapters map rails or third-party data into component
  props.
- Secrets remain server-side.

Shopify Hydrogen is the clearest combined case: a recipe may need to install a
server-side Shopify/rails backend route and also adapt `TierProgress`
into the Hydrogen storefront.

## TOLDs Source Map

The old `~/Development/tolds` project contains useful material to migrate after
the platform SDK contract is designed:

| TOLDs material | rails use |
|----------------|-------------------|
| `ADAPTER_GUIDE.md` | Integration adapter guide and certification checklist |
| `CAPABILITIES_MATRIX.md` | Platform capability matrix by commerce/marketing vendor |
| `CANONICAL_MAPPING.md` | Canonical mapping guidance for recipes and adapters |
| `TROUBLESHOOTING.md` | Troubleshooting guide for SDK and generated integrations |
| `packages/docs/src/content/components/*` | Component and UI reference source material |
| `packages/docs/src/examples/components/*` | Example code for loyalty components |
| `packages/react/*` | Platform-agnostic React loyalty component source |
| `packages/gamify-*` | Future gamification runtime and admin SDK source material |
| `packages/examples-*` | Framework-specific examples for Next.js, TanStack, and React Router |

Before publishing any migrated content:

- Rename product language from TOLDs to rails.
- Remove or quarantine any standalone-only architecture assumptions.
- Verify package names, imports, environment variables, and API routes against
  this repository.
- Separate SDK component docs from API-client roadmap material.
- Preserve framework-agnostic component guidance where it is already accurate.

## Migration Shape

The SDK migration should be treated as a product design and contract effort, not
as a documentation cleanup.

Recommended sequence:

1. Split the SDK docs into React components, canonical data/adapters, framework
   guides, recipes, and API-client migration notes.
2. Decide public package names for React components and API clients.
3. Migrate component MDX and examples from TOLDs, updating names and imports.
4. Document canonical data shapes and adapter responsibilities.
5. Update CLI recipe docs to show how backend recipes feed frontend components.
6. Split auth models explicitly: server integration keys, operator/admin
   sessions, and end-user JWT/member flows.
7. Generate or validate API-client route contracts from the backend API source of
   truth.
8. Port only the API methods that map cleanly to current rails routes.
9. Add typechecked snippets and integration tests for every documented method
   and component recipe.

Open design questions:

- `@loyaltyrails/react` already exists (`packages/react/src/index.ts`) and
  ships `LoyaltyProvider`, `useLoyalty`, `useMemberBalance`, `useMemberTier`,
  `PointsBalance`, `TierBadge`, `RedemptionCard`, `SpinWheel`,
  `OnboardingChallenge`, and `CampaignTiles` — the open question is
  reconciling this page's TOLDs-derived component docs with that shipped
  surface, not deciding a package name.
- Should the server SDK and browser/member SDK be separate packages?
- Should gamification UI components live in the same package as loyalty account
  components?
- Which SDK surface belongs to proprietary rails versus future ALP
  reference SDKs?
- Should the SDK be generated from OpenAPI, hand-authored, or hybrid?
- How should generated CLI recipes, canonical adapters, and SDK helpers share
  templates or types?

## Public Docs Acceptance Criteria

Do not publish a production API-client reference until these are true:

- SDK examples authenticate with the same auth model as the route they call.
- No documented method sends `X-API-Key` to an end-user JWT route.
- Method names, request types, and response types match the Rust backend.
- Snippets typecheck in CI.
- Error examples match real backend error envelopes.
- The docs clearly distinguish server-only integration code from browser-safe
  member code.
- Legacy TOLDs examples have been renamed, reviewed, and tested.

Component docs may publish earlier when:

- Component examples use rails package names.
- Components stay backend-agnostic and props-driven.
- Framework guides show where data fetching and identity live.
- Recipe docs show the bridge from backend routes to frontend components.
- Shopify Hydrogen docs cover both backend recipe wiring and storefront
  component placement.

## Current Developer Guidance

For current integrations, use:

- [Quick Start](./quick-start.md)
- [SDK Components](./sdk-components.md)
- [Integration Recipes](./integrations/recipes.md)
- [API Reference](./api-reference.md)
- [CLI Guide](./cli.md)

Return to this page when planning the future SDK migration.

---

# Agent Guide

Source: ../docs/agent-guide.md
URL: https://docs.rails.sh/agent-guide
Markdown: https://docs.rails.sh/markdown/agent-guide.md

# Agent Guide

Status: current. Refreshed against the agent tool modules, the approval
stream contract, and the shipped typed-artifact cards. Verified capability
claims are cross-referenced to [Agent Tools Reference](./reference/agent-tools.md)
(generated from `agent/src/agent/*.py`).

## Two Different Agents

rails has two agent surfaces. Do not conflate them:

| Surface | Location | Purpose |
|---------|----------|---------|
| Admin agent service | `agent/` (FastAPI + LangGraph), rendered in the dashboard chat UI | Conversational assistant that reads program state and, with approval, creates and edits programs, rules, campaigns, experiences, alerts, and more |
| CLI local integration agent | `packages/cli/src/agent/*` | Deterministic planner/previewer/applier that maps natural-language intent to reviewed, recipe-bound code changes inside a customer's app repository |

The admin agent talks to the rails backend over the network and can request
approval for platform changes. The CLI agent never talks to the backend on
your behalf for platform mutations — it plans and applies local file edits
from a fixed recipe catalog, gated by `--preview`/`--apply`/`--yes`. This
page covers the admin agent; see [CLI Guide](./cli.md) for the CLI agent's
own commands.

## What The Agent Can Do

The admin agent is a LangGraph ReAct agent (Anthropic model, PostgreSQL
checkpointing) with a curated tool set — 117 tools as of this writing, split
into safe/read-only and approval-required registries. The full generated
inventory, with the exact backend endpoint each tool calls, is in the
[Agent Tools Reference](./reference/agent-tools.md). In prose and in the UI
these are always described as actions, never as internal tool identifiers —
the product's agent interaction contract bans raw tool names in
user-facing copy.

Read-only, no approval needed:

- List and inspect programs, rules, campaigns, experiences, alerts, and
  integrations.
- Look up a member's balance, point lineage, and batch history; forecast
  program liability.
- Simulate a rule against test transactions without saving it, and get
  improvement suggestions for a rule configuration.
- Pull program analytics, experience metrics, the content review queue, and
  difficulty recommendations.
- Preview how a campaign or generated content would appear to a specific
  member.
- Design a candidate tier structure, or compose a full multi-step build plan
  from a natural-language goal, without committing anything.
- Render a live program, campaign, or usage summary card in the chat.
- Read stablecoin readiness, setup status, and diagnostics for a program
  (deferred issuance features stay read-only through the agent — see
  [Stablecoin Rewards](./stablecoin-rewards.md)).

Mutating — the agent always pauses for approval first:

- Create a program; create or supersede a tier ladder.
- Create, update, delete, pause, or activate a rule — including
  simulate-then-commit, where the agent shows you the simulated outcome
  before the rule is actually saved.
- Create a campaign from a description; update, schedule, activate, or pause
  a campaign.
- Assemble a complete game experience (spin wheel, scratch-off, quiz) for a
  segment or vertical, including its prize pool.
- Generate or edit AI content variants, approve or reject them, and apply a
  difficulty recommendation.
- Pause, resume, or deprecate a program; suspend or reactivate a member;
  pause an integration.
- Create, update, pause, or activate an alert, and acknowledge or resolve a
  triggered one.
- Prepare a non-secret integration handoff, or a stablecoin
  configuration/reconciliation change, as an operator handoff — the agent
  never mints or reveals credentials itself.

Example prompts:

```text
Show me the last 30 days of reserve utilization for this program.
```

```text
Simulate a double-points-Tuesday rule against last week's transactions before we commit it.
```

```text
Create a draft welcome bonus rule for program <program_id>.
```

```text
Assemble a holiday spin wheel for gold members with a controlled prize budget.
```

```text
Pause the program — we found a data issue in today's ingestion.
```

## The Approval Model

Every mutating action pauses the conversation and asks a human to decide
before anything is written. This is enforced by LangGraph `interrupt()` on
each approval-required tool; the API resumes the paused graph through
`POST /api/v1/approve`.

- **Before/after diffs.** An update approval renders the specific
  field-level changes (`before` → `after`), not just a restated intent. A
  rule approval built through simulate-then-commit renders the simulation
  projection first — match count, points that would be awarded, and a
  per-transaction breakdown — so you approve the actual outcome, not a
  promise.
- **Exactly-once.** Each pending interrupt is claimed atomically before it
  resumes. A duplicate approval, a concurrent approval from a second tab, or
  a reconnect during the decision all resolve to the same single write; a
  losing request gets a 409 rather than a second execution.
- **Superseded by a new message.** Sending a new message while an approval
  is still pending resolves the pending decision as rejected ("superseded")
  and starts the new turn — a paused thread never silently accumulates two
  live decisions.
- **Approve, reject, or modify.** Rejecting can carry free-text feedback
  that re-enters the conversation. Modify opens a tailored, pre-populated
  form for the highest-traffic actions (creating a program, a tier ladder,
  or a rule) and a free-text fallback for everything else; the structured
  edits are merged into the payload before the tool applies it.
- **Approval is not confirmation of the write.** Approval means the human
  gate was passed. The agent still reports separately whether the backend
  call actually committed, and never presents a proposal, a simulation, or
  an operator handoff as if it were a completed production change.

Frontend source: `frontend/src/components/agent/ApprovalCard.tsx` (diff and
simulation rendering), `frontend/src/components/agent/ApprovalModifyForm.tsx`
(structured modify forms). Backend source: `agent/src/api/routes.py`
(interrupt claim, supersede-on-new-message, and resume).

## Typed Artifacts

Some tool results render as live, typed cards in the chat instead of prose —
and stay live, refetching on the same query keys the rest of the dashboard
uses, so they don't go stale if the underlying object changes elsewhere:

| Artifact | Card | Carries |
|----------|------|---------|
| `program_summary` | `frontend/src/components/agentic/program-summary-card.tsx` | Program ID only; the card live-fetches the rest |
| `campaign_summary` | `frontend/src/components/agentic/campaign-summary-card.tsx` | Program + campaign ID |
| `integration_handoff` | `frontend/src/components/agentic/integration-handoff-card.tsx` | A non-secret handoff bundle (program, recipe, environment) for pairing a local integration — never a minted key |

Because these are minimal, ID-keyed payloads rather than snapshots, they
stay correct after the object is edited from the regular dashboard UI, not
just from the agent.

## Agent-Built Objects Are Ordinary API Objects

A program, rule, campaign, or experience the agent creates is not a
special agent-only record — it's the same row your integration reads and
writes through the regular API, with the same IDs, the same lifecycle, and
the same auth model. Use these pages to integrate against what the agent
built:

- [Programs API](./api/programs.md) — program fields, lifecycle
  (pause/resume/deprecate), reward-mode settings, tier ladders.
- [Rules API](./api/rules.md) — rule types, statuses, and the simulate
  endpoint the agent's simulate-then-commit flow calls directly.
- [Campaigns API](./api/campaigns.md) — campaign CRUD, scheduling,
  audience targeting.
- [Games API](./api/games.md) — experiences, prize pools, and how an
  active campaign gates experience visibility.
- [Members API](./api/members.md) and [Events API](./api/events.md) — the
  ingestion and balance surfaces every rule the agent creates ultimately
  evaluates against.

## Agent API

Base URL defaults to `http://localhost:8081` locally, set through
`VITE_AGENT_API_URL` in the frontend. Requests other than `/api/v1/health`
require an HS256 JWT (`AGENT_JWT_SECRET`, issuer/audience from
`AGENT_JWT_ISSUER`/`AGENT_JWT_AUDIENCE`) carrying the acting user, org, and
tenant — this is enabled by default (`REQUIRE_JWT_AUTH=true`).

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/api/v1/capabilities` | Report which optional agent features (e.g. checkpointing) are enabled |
| `POST` | `/api/v1/chat` | Send a message and receive a non-streaming response |
| `POST` | `/api/v1/chat/stream` | Stream response events over Server-Sent Events |
| `POST` | `/api/v1/approve` | Resume an interrupted thread with an approval, rejection, or modification |
| `GET` | `/api/v1/threads` | List threads for the current user |
| `GET` | `/api/v1/threads/{thread_id}` | Read a thread's durable event journal (tool calls, decisions, plan state) |
| `DELETE` | `/api/v1/threads/{thread_id}` | Acknowledge a deletion request; does not currently delete LangGraph checkpoint rows |
| `GET` | `/api/v1/health` | Agent service health check |

### Chat Request

```json
{
  "thread_id": "optional-thread-id",
  "turn_id": "optional-client-generated-turn-id",
  "message": "Create a draft welcome bonus rule",
  "program_id": "optional-program-context",
  "surface_context": { "route": "/admin/programs/<id>" }
}
```

`program_id` and `surface_context` give the agent the operator's current
dashboard location so it doesn't have to ask for it.

### Chat Response

```json
{
  "thread_id": "thread-id",
  "messages": [{ "role": "assistant", "content": "I can create that as a draft rule..." }],
  "interrupted": false,
  "interrupt_data": null,
  "artifacts": [],
  "data_changed": [],
  "tool_events": []
}
```

### Stream Events

`/api/v1/chat/stream` emits JSON objects in `data:` Server-Sent Events. Per
the interaction contract, every non-conversational tool call is reported as
a `tool_start`/`tool_end` pair carrying a human-readable label (never the
raw tool name) and a redacted, bounded input preview:

| Event type | Carries |
|------------|---------|
| `thread_id` | `thread_id`, `turnId` |
| `stage` | `turnId`, `stage` (understanding, acting, synthesizing, awaiting input, awaiting approval, complete, failed), `label` |
| `message` | `content` |
| `tool_start` / `tool_end` | `name`, `label`, `toolCallId`, `turnId`, optional `inputPreview` |
| `artifact` | A typed artifact payload (see above) |
| `data_changed` | Query keys the frontend should invalidate |
| `clarify_question` | A focused question plus suggested-reply pills |
| `interrupt` | The pending approval envelope |
| `error` | `error` (sanitized; never a raw exception string) |
| `done` | none |

## Running The Agent Locally

```bash
cd agent
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn api.app:app --reload --port 8081
```

Required environment (see [Agent Tools Reference § Required Settings](./reference/agent-tools.md#required-settings)
for the full list and defaults):

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Model access |
| `DATABASE_URL` | LangGraph checkpointing |
| `BACKEND_URL` | Backend API base URL |
| `AGENT_SERVICE_SHARED_SECRET` | Agent-principal auth to the backend (`X-Agent-Shared-Secret` plus acting-user headers) |
| `AGENT_JWT_SECRET` | Signs/verifies chat-endpoint JWTs |

## Frontend Agent UI

Source:

- `frontend/src/hooks/use-agent-runtime.ts`
- `frontend/src/lib/agent-api.ts`
- `frontend/src/components/agent/AgentChat.tsx`
- `frontend/src/components/agent/ApprovalCard.tsx`
- `frontend/src/components/agent/ApprovalModifyForm.tsx`

The UI supports streaming responses, thread creation and restore (tool
traces and decisions rehydrate from the durable turn journal), program/route
context forwarding, approve/reject/modify, voice input where the browser
supports speech recognition, and starting a new conversation.

Known limitation: production CORS policy and agent auth hardening remain an
ongoing concern as the agent surface opens to more callers.

## CLI Local Integration Agent

```bash
loyaltyrails agent "add a member balance widget"
```

It is deterministic and recipe-bound — it does not invent arbitrary file
edits.

```bash
loyaltyrails agent "wire Shopify orders paid webhooks"
loyaltyrails agent "add campaign tiles" --preview
loyaltyrails agent "add a member balance widget" --json
loyaltyrails agent "add a member balance widget" --apply --yes
```

Safety behavior:

- Plan mode is read-only.
- Preview mode runs redacted dry-run planners.
- Apply mode applies exactly one ready local integration recipe, requires a
  clean git worktree (unless `--allow-dirty`), and requires `--yes`.
- Recipe preview/apply can enforce profile, program, scope, and
  generated-app credential safety.

See [CLI Guide](./cli.md) for the full command surface, including the
`join --configure` demo-handoff flow that pairs a generated app with a
program using a non-secret handoff bundle rather than a hand-copied key.

## Recommended User Guidance

Teach users to ask the agent for intent, not implementation internals:

```text
Add campaign tiles to this storefront and show the files before writing.
```

```text
Create a draft spin wheel for gold members, but do not publish it.
```

```text
Simulate this rule against three sample purchase events before saving it.
```

```text
Explain why this difficulty recommendation was generated.
```

For any money-moving or production-sensitive task, ask the agent for a
preview first, confirm the auth scope it's acting under, and verify the
resulting object through the API pages above before treating it as done.

---

# Agent Tools Reference

Source: ../docs/reference/agent-tools.md
URL: https://docs.rails.sh/agent-tools-reference
Markdown: https://docs.rails.sh/markdown/agent-tools-reference.md

# Agent Tools Reference

> Generated from rails agent source. Do not edit by hand; run `node docs-site/scripts/generate-source-references.mjs`.

## Source Inputs

- `agent/src/agent/tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/alert_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/lifecycle_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/stablecoin_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/pilot_health_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/analytics_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/test_event_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/developer_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/tenant_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/onboarding_tools.py`: LangChain tool definitions and safe/destructive registries.
- `agent/src/agent/prompts.py`: system prompt capability and approval policy context.
- `agent/src/agent/graph.py`: LangGraph ReAct agent assembly with Anthropic model and optional PostgreSQL checkpointer.
- `agent/src/api/routes.py`: FastAPI chat, approval, thread, and health endpoints.
- `agent/src/agent/config.py`: environment-backed service settings.

## Runtime Model

- Agent implementation: LangGraph ReAct agent created with all tools from `get_tools()`.
- Model provider: Anthropic via `ChatAnthropic`.
- Persistence: PostgreSQL checkpointer in the persisted agent path; a no-checkpointer constructor exists for tests/simple use.
- Backend access: tools create an `httpx.AsyncClient` against `settings.backend_url` carrying agent-principal headers (`X-Agent-Shared-Secret` + acting-user attribution); the legacy `X-API-Key` path only exists for explicitly unauthenticated dev configurations.
- Approval boundary: tools in `DESTRUCTIVE_TOOLS` call `interrupt(...)`; API clients resume them through `/api/v1/approve`.

## Tool Counts

| Class | Count |
| --- | --- |
| safe/read-only | 68 |
| approval-required | 49 |
| total registered/discovered | 117 |

## Tool Index

| Tool | Safety | Registry | Summary | Backend endpoints | Source |
| --- | --- | --- | --- | --- | --- |
| `get_member_point_lineage` | safe/read-only | SAFE_TOOLS | Get complete point lineage for a member showing earn sources and usage. | `GET /internal/v1/admin/programs/{program_id}/members/{member_id}/balance`<br>`GET /internal/v1/programs/{program_id}/members/{member_address}/batches` | agent/src/agent/tools.py:813 |
| `trace_batch_history` | safe/read-only | SAFE_TOOLS | Trace the complete history of a specific point batch from earn to current state. | `GET /internal/v1/batches/{batch_id}/lineage` | agent/src/agent/tools.py:902 |
| `get_liability_forecast` | safe/read-only | SAFE_TOOLS | Get liability forecast based on earn cohorts and redemption velocity. | `GET /internal/v1/programs/{program_id}/liability` | agent/src/agent/tools.py:961 |
| `get_batch_context` | safe/read-only | SAFE_TOOLS | Get the context data for a batch earn/redeem/transfer event. | `GET /internal/v1/contexts/{context_ref}` | agent/src/agent/tools.py:1024 |
| `get_program_analytics` | safe/read-only | SAFE_TOOLS | Get analytics for a loyalty program. | `GET /internal/v1/admin/programs/{program_id}/analytics/{endpoint}` | agent/src/agent/tools.py:1070 |
| `get_member_balance` | safe/read-only | SAFE_TOOLS | Get a member's point balance and transaction history. | `GET /internal/v1/admin/programs/{program_id}/members/{external_id}/balance` | agent/src/agent/tools.py:1120 |
| `list_rules` | safe/read-only | SAFE_TOOLS | List all rules for a loyalty program. | `GET /internal/v1/admin/programs/{program_id}/rules` | agent/src/agent/tools.py:1145 |
| `get_rule_details` | safe/read-only | SAFE_TOOLS | Get detailed information about a specific rule. | `GET /internal/v1/admin/rules/{rule_id}` | agent/src/agent/tools.py:1176 |
| `list_programs` | safe/read-only | SAFE_TOOLS | List all loyalty programs accessible to the current user. | `GET /internal/v1/admin/programs` | agent/src/agent/tools.py:1194 |
| `ask_clarify_question` | safe/read-only | SAFE_TOOLS | Ask the user ONE clarifying question and pause for their answer. | local analysis | agent/src/agent/tools.py:1207 |
| `simulate_rule` | safe/read-only | SAFE_TOOLS | Simulate a rule against test transactions without saving it. | `POST /internal/v1/admin/programs/{program_id}/rules/simulate` | agent/src/agent/tools.py:1244 |
| `suggest_rule_improvements` | safe/read-only | SAFE_TOOLS | Analyze a rule configuration and suggest improvements. | local analysis | agent/src/agent/tools.py:1292 |
| `create_rule` | approval-required | DESTRUCTIVE_TOOLS | Create a new rule for a loyalty program. | `POST /internal/v1/admin/programs/{program_id}/rules` | agent/src/agent/tools.py:1474 |
| `update_rule` | approval-required | DESTRUCTIVE_TOOLS | Update an existing rule. | `GET /internal/v1/admin/rules/{rule_id}`<br>`PATCH /internal/v1/admin/rules/{rule_id}` | agent/src/agent/tools.py:1593 |
| `delete_rule` | approval-required | DESTRUCTIVE_TOOLS | Delete a rule from a loyalty program. | `GET /internal/v1/admin/rules/{rule_id}`<br>`DELETE /internal/v1/admin/rules/{rule_id}` | agent/src/agent/tools.py:1648 |
| `pause_rule` | approval-required | DESTRUCTIVE_TOOLS | Pause an active rule (stops it from being evaluated). | `GET /internal/v1/admin/rules/{rule_id}`<br>`POST /internal/v1/admin/rules/{rule_id}/pause` | agent/src/agent/tools.py:1692 |
| `activate_rule` | approval-required | DESTRUCTIVE_TOOLS | Activate a paused rule. | `GET /internal/v1/admin/rules/{rule_id}`<br>`POST /internal/v1/admin/rules/{rule_id}/activate` | agent/src/agent/tools.py:1738 |
| `get_experience_metrics` | safe/read-only | SAFE_TOOLS | Get game experience performance metrics for adaptive difficulty analysis. | `GET /internal/v1/admin/experiences/{experience_id}/metrics` | agent/src/agent/tools.py:1789 |
| `get_content_review_queue` | safe/read-only | SAFE_TOOLS | Get the content review queue for a program. | `GET /internal/v1/admin/programs/{program_id}/content/variants` | agent/src/agent/tools.py:1823 |
| `preview_generated_content` | safe/read-only | SAFE_TOOLS | Preview a specific content variant by ID. | `GET /internal/v1/admin/content/variants/{variant_id}` | agent/src/agent/tools.py:1849 |
| `get_difficulty_recommendations` | safe/read-only | SAFE_TOOLS | Get pending difficulty adjustment recommendations for a program. | `GET /internal/v1/admin/programs/{program_id}/difficulty/recommendations` | agent/src/agent/tools.py:1884 |
| `generate_experience_content` | approval-required | DESTRUCTIVE_TOOLS | Enqueue AI content generation for a game experience. | `POST /internal/v1/admin/programs/{program_id}/content/generate` | agent/src/agent/tools.py:1908 |
| `approve_content_variant` | approval-required | DESTRUCTIVE_TOOLS | Approve a content variant for live use. | `GET /internal/v1/admin/content/variants/{variant_id}`<br>`POST /internal/v1/admin/content/variants/{variant_id}/approve` | agent/src/agent/tools.py:1975 |
| `apply_difficulty_recommendation` | approval-required | DESTRUCTIVE_TOOLS | Apply an adaptive difficulty recommendation to a live experience. | `GET /internal/v1/admin/programs/{program_id}/difficulty/recommendations`<br>`POST /internal/v1/admin/difficulty/recommendations/{recommendation_id}/approve` | agent/src/agent/tools.py:2037 |
| `create_campaign_from_description` | approval-required | DESTRUCTIVE_TOOLS | Create a draft campaign from a natural-language goal and audience description. | `POST /internal/v1/admin/programs/{program_id}/campaigns` | agent/src/agent/tools.py:2219 |
| `preview_campaign_for_member` | safe/read-only | SAFE_TOOLS | Preview how a campaign would appear to a specific member. | `GET /internal/v1/admin/campaigns/{campaign_id}/audience/preview`<br>`POST /internal/v1/admin/programs/{program_id}/content/generate` | agent/src/agent/tools.py:2337 |
| `generate_questions_for_vertical` | approval-required | DESTRUCTIVE_TOOLS | Generate quiz questions appropriate for a specific business vertical. | local analysis | agent/src/agent/tools.py:2453 |
| `suggest_campaign_optimizations` | safe/read-only | SAFE_TOOLS | Analyze a campaign's configuration and suggest optimizations. | `GET /internal/v1/admin/campaigns/{campaign_id}` | agent/src/agent/tools.py:2521 |
| `assemble_spin_wheel_for_segment` | approval-required | DESTRUCTIVE_TOOLS | Assemble a complete spin-the-wheel experience targeting a member segment. | `POST /internal/v1/admin/programs/{program_id}/experiences`<br>`POST /internal/v1/admin/experiences/{experience_id}/prize-pool`<br>`POST /internal/v1/admin/programs/{program_id}/campaigns`<br>`POST /internal/v1/admin/campaigns/{campaign_id}/experiences`<br>`POST /internal/v1/admin/campaigns/{campaign_id}/personalization-rules` | agent/src/agent/tools.py:2687 |
| `create_promotion_window` | approval-required | DESTRUCTIVE_TOOLS | Create a time-bounded promotion rule (G5 sugar over create_rule). | `POST /internal/v1/admin/programs/{program_id}/rules` | agent/src/agent/tools.py:3050 |
| `assemble_scratch_off_for_segment` | approval-required | DESTRUCTIVE_TOOLS | Assemble a complete scratch-off experience targeting a member segment. | `POST /internal/v1/admin/programs/{program_id}/experiences`<br>`POST /internal/v1/admin/experiences/{experience_id}/prize-pool` | agent/src/agent/tools.py:3222 |
| `assemble_quiz_for_vertical` | approval-required | DESTRUCTIVE_TOOLS | Assemble a complete quiz experience for a business vertical. | `POST /internal/v1/admin/programs/{program_id}/experiences` | agent/src/agent/tools.py:3411 |
| `list_members` | safe/read-only | SAFE_TOOLS | List members of a loyalty program with optional filters (G11 read). | `GET /internal/v1/admin/programs/{program_id}/members` | agent/src/agent/tools.py:3606 |
| `suspend_member` | approval-required | DESTRUCTIVE_TOOLS | Suspend a program member (G11 destructive). | `POST /internal/v1/admin/members/{member_id}/suspend` | agent/src/agent/tools.py:3705 |
| `reactivate_member` | approval-required | DESTRUCTIVE_TOOLS | Reactivate a previously-suspended program member (G11 destructive). | `POST /internal/v1/admin/members/{member_id}/reactivate` | agent/src/agent/tools.py:3794 |
| `list_integrations` | safe/read-only | SAFE_TOOLS | List integration connections for a loyalty program (Chunk 7 read). | `GET /internal/v1/programs/{program_id}/integrations` | agent/src/agent/tools.py:4028 |
| `test_integration` | safe/read-only | SAFE_TOOLS | Run a read-only smoke check against an integration (Chunk 7 read). | `GET /internal/v1/integrations/{integration_id}` | agent/src/agent/tools.py:4127 |
| `pause_integration` | approval-required | DESTRUCTIVE_TOOLS | Pause (disconnect) an integration (Chunk 7 destructive). | `GET /internal/v1/integrations/{integration_id}`<br>`POST /internal/v1/integrations/{integration_id}/disconnect` | agent/src/agent/tools.py:4202 |
| `lookup_loyalty_benchmark` | safe/read-only | SAFE_TOOLS | Look up a loyalty program for use as a structural reference. | local analysis | agent/src/agent/tools.py:4382 |
| `list_top_programs_in_vertical` | safe/read-only | SAFE_TOOLS | List the top-ranked loyalty programs in a given industry/vertical. | local analysis | agent/src/agent/tools.py:4424 |
| `semantic_program_search` | safe/read-only | SAFE_TOOLS | Program-level semantic search across the Corpus Labs document corpus. | local analysis | agent/src/agent/tools.py:4456 |
| `get_program_dossier_section` | safe/read-only | SAFE_TOOLS | Fetch a specific dossier section for a Corpus Labs program. | local analysis | agent/src/agent/tools.py:4488 |
| `create_program` | approval-required | DESTRUCTIVE_TOOLS | Create a new loyalty program (the top-level container). | `POST /internal/v1/admin/programs` | agent/src/agent/tools.py:4535 |
| `get_stablecoin_readiness` | safe/read-only | SAFE_TOOLS | Read organization-level stablecoin readiness (rails configured? KYC done?). | `GET /internal/v1/admin/organization/stablecoin/readiness` | agent/src/agent/tools.py:4604 |
| `get_program_reward_settings` | safe/read-only | SAFE_TOOLS | Read a program's reward settings (points-only vs stablecoin-primary, etc.). | `GET /internal/v1/admin/programs/{program_id}/reward-settings` | agent/src/agent/tools.py:4623 |
| `setup_stablecoin_rail_handoff` | approval-required | DESTRUCTIVE_TOOLS | Prepare the stablecoin rail configuration as an operator handoff. | `GET /internal/v1/admin/organization/stablecoin/readiness` | agent/src/agent/tools.py:4638 |
| `set_program_reward_settings_handoff` | approval-required | DESTRUCTIVE_TOOLS | Prepare program reward-settings update as an operator handoff. | local analysis | agent/src/agent/tools.py:4726 |
| `setup_integration` | approval-required | DESTRUCTIVE_TOOLS | Create an outbound integration connection (Braze, mParticle, SFMC, Shopify). | `POST /internal/v1/integrations` | agent/src/agent/tools.py:4793 |
| `design_tier_structure` | safe/read-only | SAFE_TOOLS | Design a multi-tier structure using audience segments + bonus rules. | local analysis | agent/src/agent/tools.py:4914 |
| `synthesize_program_plan` | safe/read-only | SAFE_TOOLS | Compose a complete, executable build plan from natural-language intent. | local analysis | agent/src/agent/tools.py:5199 |
| `create_tier_ladder` | approval-required | DESTRUCTIVE_TOOLS | Create or supersede a program's tier ladder. | local analysis | agent/src/agent/tools.py:5670 |
| `update_tier_ladder` | approval-required | DESTRUCTIVE_TOOLS | Supersede the currently-active tier ladder with a new version. | local analysis | agent/src/agent/tools.py:5863 |
| `show_program_summary` | safe/read-only | SAFE_TOOLS | Render a live program summary card in the chat. | local analysis | agent/src/agent/tools.py:6063 |
| `show_campaign_summary` | safe/read-only | SAFE_TOOLS | Render a live campaign summary card in the chat. | local analysis | agent/src/agent/tools.py:6080 |
| `show_usage` | safe/read-only | SAFE_TOOLS | Render a live usage summary card in the chat. | local analysis | agent/src/agent/tools.py:6101 |
| `recommend_plan` | safe/read-only | SAFE_TOOLS | Compare the org's projected usage against every plan and recommend a switch only when a cheaper plan actually fits. | local analysis | agent/src/agent/tools.py:6115 |
| `prepare_integration_handoff` | approval-required | SAFE_TOOLS | Produce a non-secret integration handoff for a configured program. | `GET /internal/v1/admin/programs` | agent/src/agent/tools.py:6230 |
| `simulate_then_commit_rule` | approval-required | DESTRUCTIVE_TOOLS | Simulate a proposed rule against test transactions, show the human the projected outcomes, and on approval commit the rule for real. | `POST /internal/v1/admin/programs/{program_id}/rules/simulate`<br>`POST /internal/v1/admin/programs/{program_id}/rules` | agent/src/agent/tools.py:6493 |
| `list_alerts` | safe/read-only | ALERT_SAFE_TOOLS | List all alert definitions configured for a loyalty program. | `GET /internal/v1/admin/programs/{program_id}/alerts` | agent/src/agent/alert_tools.py:65 |
| `get_alert_details` | safe/read-only | ALERT_SAFE_TOOLS | Get the full configuration of a single alert definition. | `GET /internal/v1/admin/alerts/{alert_id}` | agent/src/agent/alert_tools.py:84 |
| `get_alert_history` | safe/read-only | ALERT_SAFE_TOOLS | List triggered alerts (alert history) for a program. | `GET /internal/v1/admin/programs/{program_id}/alerts/history` | agent/src/agent/alert_tools.py:103 |
| `create_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Create a new alert definition for a program. | `POST /internal/v1/admin/programs/{program_id}/alerts` | agent/src/agent/alert_tools.py:140 |
| `update_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Update an existing alert definition. | `GET /internal/v1/admin/alerts/{alert_id}`<br>`PATCH /internal/v1/admin/alerts/{alert_id}` | agent/src/agent/alert_tools.py:222 |
| `delete_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Delete an alert definition. | `GET /internal/v1/admin/alerts/{alert_id}`<br>`DELETE /internal/v1/admin/alerts/{alert_id}` | agent/src/agent/alert_tools.py:274 |
| `pause_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Pause an alert definition (stops it from triggering). | `GET /internal/v1/admin/alerts/{alert_id}`<br>`POST /internal/v1/admin/alerts/{alert_id}/pause` | agent/src/agent/alert_tools.py:323 |
| `activate_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Activate a paused alert definition. | `GET /internal/v1/admin/alerts/{alert_id}`<br>`POST /internal/v1/admin/alerts/{alert_id}/activate` | agent/src/agent/alert_tools.py:367 |
| `acknowledge_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Acknowledge a triggered alert (marks the incident as seen). | `POST /internal/v1/admin/alerts/history/{history_id}/acknowledge` | agent/src/agent/alert_tools.py:408 |
| `resolve_alert` | approval-required | ALERT_DESTRUCTIVE_TOOLS | Resolve a triggered alert (closes the incident). | `POST /internal/v1/admin/alerts/history/{history_id}/resolve` | agent/src/agent/alert_tools.py:446 |
| `get_program_status` | safe/read-only | LIFECYCLE_SAFE_TOOLS | Get detailed operational status for a program. | `GET /internal/v1/admin/programs/{program_id}/status` | agent/src/agent/lifecycle_tools.py:64 |
| `pause_program` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Pause a live loyalty program (emergency lever — halts rule evaluation and token operations for the whole program). | `GET /internal/v1/admin/programs/{program_id}/status`<br>`POST /internal/v1/admin/programs/{program_id}/pause` | agent/src/agent/lifecycle_tools.py:86 |
| `resume_program` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Resume a paused loyalty program. | `GET /internal/v1/admin/programs/{program_id}/status`<br>`POST /internal/v1/admin/programs/{program_id}/resume` | agent/src/agent/lifecycle_tools.py:139 |
| `deprecate_program` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Deprecate a loyalty program (terminal lifecycle state). | `GET /internal/v1/admin/programs/{program_id}/status`<br>`POST /internal/v1/admin/programs/{program_id}/deprecate` | agent/src/agent/lifecycle_tools.py:180 |
| `list_campaigns` | safe/read-only | LIFECYCLE_SAFE_TOOLS | List campaigns for a program. | `GET /internal/v1/admin/programs/{program_id}/campaigns` | agent/src/agent/lifecycle_tools.py:230 |
| `get_campaign` | safe/read-only | LIFECYCLE_SAFE_TOOLS | Get a single campaign's full configuration. | `GET /internal/v1/admin/campaigns/{campaign_id}` | agent/src/agent/lifecycle_tools.py:262 |
| `update_campaign` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Update a campaign's configuration. | `GET /internal/v1/admin/campaigns/{campaign_id}` | agent/src/agent/lifecycle_tools.py:296 |
| `activate_campaign` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Activate a campaign (starts serving its experiences to the audience). | `POST /internal/v1/admin/campaigns/{campaign_id}/activate` | agent/src/agent/lifecycle_tools.py:394 |
| `pause_campaign` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Pause an active campaign. | `POST /internal/v1/admin/campaigns/{campaign_id}/pause` | agent/src/agent/lifecycle_tools.py:418 |
| `schedule_campaign` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Schedule a draft campaign to run within its configured start/end window. | `POST /internal/v1/admin/campaigns/{campaign_id}/schedule` | agent/src/agent/lifecycle_tools.py:442 |
| `list_experiences` | safe/read-only | LIFECYCLE_SAFE_TOOLS | List game experiences for a program. | `GET /internal/v1/admin/programs/{program_id}/experiences` | agent/src/agent/lifecycle_tools.py:474 |
| `get_experience` | safe/read-only | LIFECYCLE_SAFE_TOOLS | Get a single game experience's full configuration. | `GET /internal/v1/admin/experiences/{experience_id}` | agent/src/agent/lifecycle_tools.py:492 |
| `get_prize_pool` | safe/read-only | LIFECYCLE_SAFE_TOOLS | Get the prize pool attached to a game experience. | `GET /internal/v1/admin/experiences/{experience_id}/prize-pool` | agent/src/agent/lifecycle_tools.py:510 |
| `update_experience` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Update a game experience's configuration. | `GET /internal/v1/admin/experiences/{experience_id}` | agent/src/agent/lifecycle_tools.py:528 |
| `publish_experience` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Publish a game experience (makes it live for members). | `POST /internal/v1/admin/experiences/{experience_id}/publish` | agent/src/agent/lifecycle_tools.py:620 |
| `pause_experience` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Pause a live game experience. | `POST /internal/v1/admin/experiences/{experience_id}/pause` | agent/src/agent/lifecycle_tools.py:648 |
| `create_prize_pool` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Create (or replace) the prize pool for a game experience. | `POST /internal/v1/admin/experiences/{experience_id}/prize-pool` | agent/src/agent/lifecycle_tools.py:672 |
| `reject_content_variant` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Reject a generated content variant (completes the review loop — the agent could previously only approve). | `POST /internal/v1/admin/content/variants/{variant_id}/reject` | agent/src/agent/lifecycle_tools.py:724 |
| `edit_content_variant` | approval-required | LIFECYCLE_DESTRUCTIVE_TOOLS | Edit a generated content variant's text before approval. | `POST /internal/v1/admin/content/variants/{variant_id}/edit` | agent/src/agent/lifecycle_tools.py:770 |
| `get_stablecoin_setup_status` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get stablecoin setup status for a program (checklist progress, rail binding state, issuance readiness). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/setup-status` | agent/src/agent/stablecoin_tools.py:104 |
| `get_stablecoin_setup_doctor` | safe/read-only | STABLECOIN_SAFE_TOOLS | Run the stablecoin setup doctor — diagnostic checks explaining what is blocking issuance for a program and how to fix it. | `GET /internal/v1/admin/stablecoin/programs/{program_id}/setup-doctor` | agent/src/agent/stablecoin_tools.py:123 |
| `get_stablecoin_issuance_config` | safe/read-only | STABLECOIN_SAFE_TOOLS | Read a program's stablecoin issuance configuration. | `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-config` | agent/src/agent/stablecoin_tools.py:142 |
| `list_reconciliation_exceptions` | safe/read-only | STABLECOIN_SAFE_TOOLS | List stablecoin reconciliation exceptions (ledger/provider mismatches). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/reconciliation/exceptions` | agent/src/agent/stablecoin_tools.py:163 |
| `get_stablecoin_issuance_funnel` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get the stablecoin issuance funnel (reward intents → issued → delivered, with drop-off at each stage). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-funnel` | agent/src/agent/stablecoin_tools.py:200 |
| `get_stablecoin_liability_buckets` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get stablecoin liability bucketed by lifecycle state (pending, issued, in-flight, settled). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/liability-buckets` | agent/src/agent/stablecoin_tools.py:232 |
| `get_stablecoin_campaign_roi` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get stablecoin campaign ROI (reward cost vs. attributed activity). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/campaign-roi` | agent/src/agent/stablecoin_tools.py:264 |
| `get_stablecoin_provider_ops` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get stablecoin provider operations summary (submission outcomes, latencies, failure classes per provider/network). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/provider-ops` | agent/src/agent/stablecoin_tools.py:289 |
| `get_stablecoin_game_economics` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get stablecoin game economics (prize cost vs. engagement per campaign/experience/session). | `GET /internal/v1/admin/stablecoin/programs/{program_id}/game-economics` | agent/src/agent/stablecoin_tools.py:317 |
| `get_reward_intent_timeline` | safe/read-only | STABLECOIN_SAFE_TOOLS | Trace a single stablecoin reward intent through its full lifecycle (intent → issuance → provider submission → settlement). | `GET /internal/v1/admin/stablecoin/programs/{program_id}` | agent/src/agent/stablecoin_tools.py:343 |
| `get_member_stablecoin_timeline` | safe/read-only | STABLECOIN_SAFE_TOOLS | Get a member's stablecoin activity timeline (rewards, issuances, settlements). | `GET /internal/v1/admin/stablecoin/programs/{program_id}` | agent/src/agent/stablecoin_tools.py:367 |
| `configure_stablecoin_issuance_handoff` | approval-required | STABLECOIN_DESTRUCTIVE_TOOLS | Propose a stablecoin issuance-config change as an operator handoff. | `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-config` | agent/src/agent/stablecoin_tools.py:396 |
| `create_reconciliation_run_handoff` | approval-required | STABLECOIN_DESTRUCTIVE_TOOLS | Propose a stablecoin reconciliation run as an operator handoff. | local analysis | agent/src/agent/stablecoin_tools.py:465 |
| `transition_reconciliation_exception_handoff` | approval-required | STABLECOIN_DESTRUCTIVE_TOOLS | Propose a reconciliation-exception transition as an operator handoff. | local analysis | agent/src/agent/stablecoin_tools.py:536 |
| `get_commerce_pilot_health` | safe/read-only | PILOT_HEALTH_TOOLS | Get the aggregated commerce pilot health snapshot for a program. | `GET /internal/v1/admin/commerce/pilot-health` | agent/src/agent/pilot_health_tools.py:32 |
| `query_metric` | safe/read-only | ANALYTICS_TOOLS | Query a registered loyalty-program analytics metric. | `POST /internal/v1/analytics/query` | agent/src/agent/analytics_tools.py:107 |
| `send_test_event` | safe/read-only | TEST_EVENT_TOOLS | Send a test event to a program and return the rule-engine outcomes. | `POST /internal/v1/programs/{program_id}/events`<br>`GET /internal/v1/admin/programs/{program_id}/activity-feed` | agent/src/agent/test_event_tools.py:85 |
| `get_activity_feed` | safe/read-only | TEST_EVENT_TOOLS | Get the most recent events for a program (or a single member). | `GET /internal/v1/admin/programs/{program_id}/activity-feed` | agent/src/agent/test_event_tools.py:247 |
| `list_integration_recipes` | safe/read-only | DEVELOPER_TOOLS | List developer-installable integration recipes. | local analysis | agent/src/agent/developer_tools.py:135 |
| `describe_integration_recipe` | safe/read-only | DEVELOPER_TOOLS | Describe a single integration recipe in detail. | local analysis | agent/src/agent/developer_tools.py:165 |
| `generate_sdk_snippet` | safe/read-only | DEVELOPER_TOOLS | Emit a ready-to-paste code snippet for a common LoyaltyRails operation. | local analysis | agent/src/agent/developer_tools.py:338 |
| `suggest_developer_next_steps` | safe/read-only | DEVELOPER_TOOLS | Suggest the next recipe(s) a developer should consider. | local analysis | agent/src/agent/developer_tools.py:384 |
| `provision_tenant` | approval-required | TENANT_TOOLS | Start provisioning a dedicated LoyaltyRails runtime for this customer. | `POST /api/v1/tenants/provision` | agent/src/agent/tenant_tools.py:53 |
| `get_tenant_status` | safe/read-only | TENANT_TOOLS | Read the current lifecycle state of a tenant. | `GET /api/v1/tenants/{tenant_uuid}` | agent/src/agent/tenant_tools.py:156 |
| `retry_tenant_provisioning` | safe/read-only | TENANT_TOOLS | Retry provisioning after a failed attempt. | `POST /api/v1/tenants/{tenant_uuid}/retry` | agent/src/agent/tenant_tools.py:208 |
| `record_onboarding_persona` | safe/read-only | ONBOARDING_TOOLS | Record the user's persona (business operator vs. developer). | local analysis | agent/src/agent/onboarding_tools.py:74 |
| `record_onboarding_vertical` | safe/read-only | ONBOARDING_TOOLS | Record the user's industry vertical (e.g., QSR, beauty, hospitality). | local analysis | agent/src/agent/onboarding_tools.py:127 |
| `record_onboarding_goal` | safe/read-only | ONBOARDING_TOOLS | Record the user's primary goal for this trial. | local analysis | agent/src/agent/onboarding_tools.py:174 |
| `bootstrap_workspace` | safe/read-only | ONBOARDING_TOOLS | Record the workspace + (optional) first program shell name. | local analysis | agent/src/agent/onboarding_tools.py:223 |
| `show_vertical_picker` | safe/read-only | ONBOARDING_TOOLS | Render a vertical pill picker as an artifact. | local analysis | agent/src/agent/onboarding_tools.py:285 |

## Service API

| Method | Path | Handler | Source |
| --- | --- | --- | --- |
| GET | `/api/v1/capabilities` | `capabilities` | agent/src/api/routes.py:1619 |
| POST | `/api/v1/chat` | `chat` | agent/src/api/routes.py:1639 |
| POST | `/api/v1/chat/stream` | `chat_stream` | agent/src/api/routes.py:1962 |
| POST | `/api/v1/approve` | `approve` | agent/src/api/routes.py:2591 |
| GET | `/api/v1/threads` | `list_threads` | agent/src/api/routes.py:2980 |
| GET | `/api/v1/threads/{thread_id}` | `get_thread` | agent/src/api/routes.py:3022 |
| DELETE | `/api/v1/threads/{thread_id}` | `delete_thread` | agent/src/api/routes.py:3120 |
| GET | `/api/v1/health` | `health_check` | agent/src/api/routes.py:3318 |

## Required Settings

| Env var | Type | Default | Source |
| --- | --- | --- | --- |
| `ANTHROPIC_API_KEY` | str | `""` | agent/src/agent/config.py:27 |
| `ANTHROPIC_MODEL` | str | `"claude-sonnet-5"` | agent/src/agent/config.py:28 |
| `BEDROCK_REGION` | str | `""` | agent/src/agent/config.py:36 |
| `BEDROCK_MODEL_ID` | str | `"anthropic.claude-3-5-sonnet-20241022-v2:0"` | agent/src/agent/config.py:37 |
| `DATABASE_URL` | str | `"postgresql://postgres:postgres@localhost:5432/loyaltyrails"` | agent/src/agent/config.py:40 |
| `BACKEND_URL` | str | `"http://localhost:8080"` | agent/src/agent/config.py:43 |
| `BACKEND_API_KEY` | str | `""` | agent/src/agent/config.py:44 |
| `AGENT_SERVICE_SHARED_SECRET` | str | `""` | agent/src/agent/config.py:54 |
| `AGENT_JWT_SECRET` | str | `(` | agent/src/agent/config.py:57 |
| `AGENT_JWT_ISSUER` | str | `"loyaltyrails-control-plane"` | agent/src/agent/config.py:60 |
| `AGENT_JWT_AUDIENCE` | str | `"loyaltyrails-agent"` | agent/src/agent/config.py:61 |
| `REQUIRE_JWT_AUTH` | bool | `True` | agent/src/agent/config.py:65 |
| `HOST` | str | `"0.0.0.0"` | agent/src/agent/config.py:68 |
| `PORT` | int | `8081` | agent/src/agent/config.py:69 |
| `DEBUG` | bool | `False` | agent/src/agent/config.py:70 |
| `MAX_TURNS` | int | `10` | agent/src/agent/config.py:73 |
| `APPROVAL_TIMEOUT_SECONDS` | int | `300` | agent/src/agent/config.py:74 |
| `TRIAL_DAILY_TURN_LIMIT` | int | `200` | agent/src/agent/config.py:84 |

## Implementation Status Caveats

- Tool schemas are source-derived from Python function signatures and docstrings; backend request/response schemas are not generated here.
- Several tool docstrings describe planned internal endpoints; availability still depends on the Rust backend implementing those paths.
- `suggest_rule_improvements` performs local analysis and does not call the backend.
- Campaign assembly and content/difficulty tools are approval-gated but may create multiple backend resources after approval.
- `delete_thread` currently returns a deleted status without deleting LangGraph checkpoint rows, per source comment.

## Tool Details

### `get_member_point_lineage`

- Source: `agent/src/agent/tools.py:813`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get complete point lineage for a member showing earn sources and usage.
- Required args: `program_id: str`, `member_id: str`
- Optional args: `external_id_type: str = "crm"`, `include_expired: bool = False`, `offset: int = 0`, `limit: int = 50`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/members/{member_id}/balance`, `GET /internal/v1/programs/{program_id}/members/{member_address}/batches`

### `trace_batch_history`

- Source: `agent/src/agent/tools.py:902`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Trace the complete history of a specific point batch from earn to current state.
- Required args: `batch_id: str`
- Backend endpoints: `GET /internal/v1/batches/{batch_id}/lineage`

### `get_liability_forecast`

- Source: `agent/src/agent/tools.py:961`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get liability forecast based on earn cohorts and redemption velocity.
- Required args: `program_id: str`
- Optional args: `group_by: str = "month"`
- Backend endpoints: `GET /internal/v1/programs/{program_id}/liability`

### `get_batch_context`

- Source: `agent/src/agent/tools.py:1024`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get the context data for a batch earn/redeem/transfer event.
- Required args: `context_ref: str`
- Backend endpoints: `GET /internal/v1/contexts/{context_ref}`

### `get_program_analytics`

- Source: `agent/src/agent/tools.py:1070`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get analytics for a loyalty program.
- Required args: `program_id: str`
- Optional args: `metric: str = "summary"`, `days: int = 30`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/analytics/{endpoint}`

### `get_member_balance`

- Source: `agent/src/agent/tools.py:1120`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get a member's point balance and transaction history.
- Required args: `program_id: str`, `external_id: str`
- Optional args: `external_id_type: str = "crm"`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/members/{external_id}/balance`

### `list_rules`

- Source: `agent/src/agent/tools.py:1145`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: List all rules for a loyalty program.
- Required args: `program_id: str`
- Optional args: `status: str = "all"`, `rule_type: Optional[str] = None`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/rules`

### `get_rule_details`

- Source: `agent/src/agent/tools.py:1176`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get detailed information about a specific rule.
- Required args: `rule_id: str`
- Backend endpoints: `GET /internal/v1/admin/rules/{rule_id}`

### `list_programs`

- Source: `agent/src/agent/tools.py:1194`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: List all loyalty programs accessible to the current user.
- Backend endpoints: `GET /internal/v1/admin/programs`

### `ask_clarify_question`

- Source: `agent/src/agent/tools.py:1207`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Ask the user ONE clarifying question and pause for their answer.
- Required args: `question: str`
- Optional args: `suggested_replies: Optional[list[str]] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `simulate_rule`

- Source: `agent/src/agent/tools.py:1244`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Simulate a rule against test transactions without saving it.
- Required args: `program_id: str`, `rule_config: dict[str, Any]`
- Optional args: `test_transactions: Optional[list[dict[str, Any]]] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/rules/simulate`

### `suggest_rule_improvements`

- Source: `agent/src/agent/tools.py:1292`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Analyze a rule configuration and suggest improvements.
- Required args: `rule_config: dict[str, Any]`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `create_rule`

- Source: `agent/src/agent/tools.py:1474`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create a new rule for a loyalty program.
- Required args: `program_id: str`, `name: str`, `rule_type: str`, `rule_config: dict[str, Any]`
- Optional args: `conditions: Optional[list[dict[str, Any]]] = None`, `priority: int = 0`, `description: Optional[str] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/rules`

### `update_rule`

- Source: `agent/src/agent/tools.py:1593`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Update an existing rule.
- Required args: `rule_id: str`, `updates: dict[str, Any]`
- Backend endpoints: `GET /internal/v1/admin/rules/{rule_id}`, `PATCH /internal/v1/admin/rules/{rule_id}`

### `delete_rule`

- Source: `agent/src/agent/tools.py:1648`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Delete a rule from a loyalty program.
- Required args: `rule_id: str`
- Backend endpoints: `GET /internal/v1/admin/rules/{rule_id}`, `DELETE /internal/v1/admin/rules/{rule_id}`

### `pause_rule`

- Source: `agent/src/agent/tools.py:1692`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Pause an active rule (stops it from being evaluated).
- Required args: `rule_id: str`
- Backend endpoints: `GET /internal/v1/admin/rules/{rule_id}`, `POST /internal/v1/admin/rules/{rule_id}/pause`

### `activate_rule`

- Source: `agent/src/agent/tools.py:1738`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Activate a paused rule.
- Required args: `rule_id: str`
- Backend endpoints: `GET /internal/v1/admin/rules/{rule_id}`, `POST /internal/v1/admin/rules/{rule_id}/activate`

### `get_experience_metrics`

- Source: `agent/src/agent/tools.py:1789`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get game experience performance metrics for adaptive difficulty analysis.
- Required args: `program_id: str`, `experience_id: str`
- Optional args: `days: int = 7`
- Backend endpoints: `GET /internal/v1/admin/experiences/{experience_id}/metrics`

### `get_content_review_queue`

- Source: `agent/src/agent/tools.py:1823`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get the content review queue for a program.
- Required args: `program_id: str`
- Optional args: `status: str = "pending_review"`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/content/variants`

### `preview_generated_content`

- Source: `agent/src/agent/tools.py:1849`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Preview a specific content variant by ID.
- Required args: `program_id: str`, `variant_id: str`
- Backend endpoints: `GET /internal/v1/admin/content/variants/{variant_id}`

### `get_difficulty_recommendations`

- Source: `agent/src/agent/tools.py:1884`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Get pending difficulty adjustment recommendations for a program.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/difficulty/recommendations`

### `generate_experience_content`

- Source: `agent/src/agent/tools.py:1908`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Enqueue AI content generation for a game experience.
- Required args: `program_id: str`, `content_type: str`, `content_scope: str`
- Optional args: `experience_id: Optional[str] = None`, `target_segment: Optional[str] = None`, `prompt: Optional[str] = None`, `additional_instructions: Optional[str] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/content/generate`

### `approve_content_variant`

- Source: `agent/src/agent/tools.py:1975`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Approve a content variant for live use.
- Required args: `program_id: str`, `variant_id: str`
- Backend endpoints: `GET /internal/v1/admin/content/variants/{variant_id}`, `POST /internal/v1/admin/content/variants/{variant_id}/approve`

### `apply_difficulty_recommendation`

- Source: `agent/src/agent/tools.py:2037`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Apply an adaptive difficulty recommendation to a live experience.
- Required args: `program_id: str`, `recommendation_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/difficulty/recommendations`, `POST /internal/v1/admin/difficulty/recommendations/{recommendation_id}/approve`

### `create_campaign_from_description`

- Source: `agent/src/agent/tools.py:2219`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create a draft campaign from a natural-language goal and audience description.
- Required args: `program_id: str`, `name: str`, `goal: str`, `target_description: str`
- Optional args: `budget_cents: Optional[int] = None`, `duration_days: Optional[int] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/campaigns`

### `preview_campaign_for_member`

- Source: `agent/src/agent/tools.py:2337`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Preview how a campaign would appear to a specific member.
- Required args: `campaign_id: str`, `member_id: str`
- Backend endpoints: `GET /internal/v1/admin/campaigns/{campaign_id}/audience/preview`, `POST /internal/v1/admin/programs/{program_id}/content/generate`

### `generate_questions_for_vertical`

- Source: `agent/src/agent/tools.py:2453`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Generate quiz questions appropriate for a specific business vertical.
- Required args: `program_id: str`, `vertical: str`
- Optional args: `count: int = 5`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `suggest_campaign_optimizations`

- Source: `agent/src/agent/tools.py:2521`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Analyze a campaign's configuration and suggest optimizations.
- Required args: `campaign_id: str`
- Backend endpoints: `GET /internal/v1/admin/campaigns/{campaign_id}`

### `assemble_spin_wheel_for_segment`

- Source: `agent/src/agent/tools.py:2687`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Assemble a complete spin-the-wheel experience targeting a member segment.
- Required args: `program_id: str`, `segment: str`, `prize_budget_cents: int`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/experiences`, `POST /internal/v1/admin/experiences/{experience_id}/prize-pool`, `POST /internal/v1/admin/programs/{program_id}/campaigns`, `POST /internal/v1/admin/campaigns/{campaign_id}/experiences`, `POST /internal/v1/admin/campaigns/{campaign_id}/personalization-rules`

### `create_promotion_window`

- Source: `agent/src/agent/tools.py:3050`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create a time-bounded promotion rule (G5 sugar over create_rule).
- Required args: `program_id: str`, `name: str`, `bonus_amount: int`, `starts_at: str`, `ends_at: str`
- Optional args: `max_uses_per_member: Optional[int] = None`, `conditions: Optional[list[dict[str, Any]]] = None`, `priority: int = 75`, `description: Optional[str] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/rules`

### `assemble_scratch_off_for_segment`

- Source: `agent/src/agent/tools.py:3222`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Assemble a complete scratch-off experience targeting a member segment.
- Required args: `program_id: str`, `segment: str`, `prize_budget_cents: int`
- Optional args: `name: Optional[str] = None`, `cooldown_seconds: int = 86400`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/experiences`, `POST /internal/v1/admin/experiences/{experience_id}/prize-pool`

### `assemble_quiz_for_vertical`

- Source: `agent/src/agent/tools.py:3411`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Assemble a complete quiz experience for a business vertical.
- Required args: `program_id: str`, `vertical: str`
- Optional args: `name: Optional[str] = None`, `question_count: int = 5`, `points_per_correct_answer: int = 50`, `passing_score_pct: int = 60`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/experiences`

### `list_members`

- Source: `agent/src/agent/tools.py:3606`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: List members of a loyalty program with optional filters (G11 read).
- Required args: `program_id: str`
- Optional args: `status: Optional[str] = None`, `limit: int = 50`, `offset: int = 0`, `search: Optional[str] = None`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/members`

### `suspend_member`

- Source: `agent/src/agent/tools.py:3705`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Suspend a program member (G11 destructive).
- Required args: `member_id: str`, `reason: str`
- Backend endpoints: `POST /internal/v1/admin/members/{member_id}/suspend`

### `reactivate_member`

- Source: `agent/src/agent/tools.py:3794`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Reactivate a previously-suspended program member (G11 destructive).
- Required args: `member_id: str`, `reason: str`
- Backend endpoints: `POST /internal/v1/admin/members/{member_id}/reactivate`

### `list_integrations`

- Source: `agent/src/agent/tools.py:4028`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: List integration connections for a loyalty program (Chunk 7 read).
- Required args: `program_id: str`
- Optional args: `status: Optional[str] = None`, `vendor: Optional[str] = None`, `limit: int = 50`, `offset: int = 0`
- Backend endpoints: `GET /internal/v1/programs/{program_id}/integrations`

### `test_integration`

- Source: `agent/src/agent/tools.py:4127`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Run a read-only smoke check against an integration (Chunk 7 read).
- Required args: `integration_id: str`
- Backend endpoints: `GET /internal/v1/integrations/{integration_id}`

### `pause_integration`

- Source: `agent/src/agent/tools.py:4202`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Pause (disconnect) an integration (Chunk 7 destructive).
- Required args: `integration_id: str`, `reason: str`
- Backend endpoints: `GET /internal/v1/integrations/{integration_id}`, `POST /internal/v1/integrations/{integration_id}/disconnect`

### `lookup_loyalty_benchmark`

- Source: `agent/src/agent/tools.py:4382`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Look up a loyalty program for use as a structural reference.
- Required args: `brand_name: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `list_top_programs_in_vertical`

- Source: `agent/src/agent/tools.py:4424`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: List the top-ranked loyalty programs in a given industry/vertical.
- Required args: `vertical: str`
- Optional args: `limit: int = 10`, `offset: int = 0`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `semantic_program_search`

- Source: `agent/src/agent/tools.py:4456`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Program-level semantic search across the Corpus Labs document corpus.
- Required args: `query: str`
- Optional args: `vertical: Optional[str] = None`, `limit: int = 10`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `get_program_dossier_section`

- Source: `agent/src/agent/tools.py:4488`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Fetch a specific dossier section for a Corpus Labs program.
- Required args: `program_id: str`, `section: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `create_program`

- Source: `agent/src/agent/tools.py:4535`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create a new loyalty program (the top-level container).
- Required args: `name: str`, `symbol: str`, `issuer: str`
- Optional args: `reserve_ratio_bps: int = 8000`, `chain_id: int = 8453`, `description: Optional[str] = None`
- Backend endpoints: `POST /internal/v1/admin/programs`

### `get_stablecoin_readiness`

- Source: `agent/src/agent/tools.py:4604`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Read organization-level stablecoin readiness (rails configured? KYC done?).
- Backend endpoints: `GET /internal/v1/admin/organization/stablecoin/readiness`

### `get_program_reward_settings`

- Source: `agent/src/agent/tools.py:4623`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Read a program's reward settings (points-only vs stablecoin-primary, etc.).
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/reward-settings`

### `setup_stablecoin_rail_handoff`

- Source: `agent/src/agent/tools.py:4638`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Prepare the stablecoin rail configuration as an operator handoff.
- Required args: `program_id: str`
- Optional args: `asset_code: str = "USDC"`, `network: str = "base-sepolia"`, `rationale: Optional[str] = None`
- Backend endpoints: `GET /internal/v1/admin/organization/stablecoin/readiness`

### `set_program_reward_settings_handoff`

- Source: `agent/src/agent/tools.py:4726`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Prepare program reward-settings update as an operator handoff.
- Required args: `program_id: str`, `reward_mode: str`
- Optional args: `default_reward_asset_code: Optional[str] = None`, `stablecoin_display_label: Optional[str] = None`, `rationale: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `setup_integration`

- Source: `agent/src/agent/tools.py:4793`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create an outbound integration connection (Braze, mParticle, SFMC, Shopify).
- Required args: `program_id: str`, `vendor: str`
- Optional args: `platform_config: Optional[dict[str, Any]] = None`, `request_credentials: bool = True`
- Backend endpoints: `POST /internal/v1/integrations`

### `design_tier_structure`

- Source: `agent/src/agent/tools.py:4914`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Design a multi-tier structure using audience segments + bonus rules.
- Required args: `program_id: str`, `tier_names: list[str]`
- Optional args: `thresholds_annual_spend: Optional[list[float]] = None`, `earn_multipliers: Optional[list[float]] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `synthesize_program_plan`

- Source: `agent/src/agent/tools.py:5199`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Compose a complete, executable build plan from natural-language intent.
- Required args: `intent_description: str`
- Optional args: `benchmark_context: Optional[dict[str, Any]] = None`, `program_name: Optional[str] = None`, `program_symbol: Optional[str] = None`, `issuer: Optional[str] = None`, `tier_names: Optional[list[str]] = None`, `enable_stablecoin: bool = False`, `stablecoin_asset: str = "USDC"`, `integrations: Optional[list[str]] = None`, `include_game: bool = False`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `create_tier_ladder`

- Source: `agent/src/agent/tools.py:5670`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Create or supersede a program's tier ladder.
- Required args: `program_id: str`, `tier_names: list[str]`, `thresholds: list[int]`, `multipliers: list[float]`
- Optional args: `expiration_days_inactive: Optional[int] = None`, `summary: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `update_tier_ladder`

- Source: `agent/src/agent/tools.py:5863`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Supersede the currently-active tier ladder with a new version.
- Required args: `program_id: str`, `version: int`, `tier_names: list[str]`, `thresholds: list[int]`, `multipliers: list[float]`
- Optional args: `expiration_days_inactive: Optional[int] = None`, `summary: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `show_program_summary`

- Source: `agent/src/agent/tools.py:6063`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Render a live program summary card in the chat.
- Required args: `program_id: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `show_campaign_summary`

- Source: `agent/src/agent/tools.py:6080`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Render a live campaign summary card in the chat.
- Required args: `program_id: str`, `campaign_id: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `show_usage`

- Source: `agent/src/agent/tools.py:6101`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Render a live usage summary card in the chat.
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `recommend_plan`

- Source: `agent/src/agent/tools.py:6115`
- Safety: `safe/read-only`
- Registry: `SAFE_TOOLS`
- Summary: Compare the org's projected usage against every plan and recommend a switch only when a cheaper plan actually fits.
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `prepare_integration_handoff`

- Source: `agent/src/agent/tools.py:6230`
- Safety: `approval-required`
- Registry: `SAFE_TOOLS`
- Summary: Produce a non-secret integration handoff for a configured program.
- Required args: `program_id: str`
- Optional args: `recipe: str = "member-journey"`, `environment: str = "test"`
- Backend endpoints: `GET /internal/v1/admin/programs`

### `simulate_then_commit_rule`

- Source: `agent/src/agent/tools.py:6493`
- Safety: `approval-required`
- Registry: `DESTRUCTIVE_TOOLS`
- Summary: Simulate a proposed rule against test transactions, show the human the projected outcomes, and on approval commit the rule for real.
- Required args: `program_id: str`, `name: str`, `rule_type: str`, `rule_config: dict[str, Any]`
- Optional args: `conditions: Optional[list[dict[str, Any]]] = None`, `priority: int = 0`, `description: Optional[str] = None`, `test_transactions: Optional[list[dict[str, Any]]] = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/rules/simulate`, `POST /internal/v1/admin/programs/{program_id}/rules`

### `list_alerts`

- Source: `agent/src/agent/alert_tools.py:65`
- Safety: `safe/read-only`
- Registry: `ALERT_SAFE_TOOLS`
- Summary: List all alert definitions configured for a loyalty program.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/alerts`

### `get_alert_details`

- Source: `agent/src/agent/alert_tools.py:84`
- Safety: `safe/read-only`
- Registry: `ALERT_SAFE_TOOLS`
- Summary: Get the full configuration of a single alert definition.
- Required args: `alert_id: str`
- Backend endpoints: `GET /internal/v1/admin/alerts/{alert_id}`

### `get_alert_history`

- Source: `agent/src/agent/alert_tools.py:103`
- Safety: `safe/read-only`
- Registry: `ALERT_SAFE_TOOLS`
- Summary: List triggered alerts (alert history) for a program.
- Required args: `program_id: str`
- Optional args: `limit: int = 50`, `include_acknowledged: bool = False`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/alerts/history`

### `create_alert`

- Source: `agent/src/agent/alert_tools.py:140`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Create a new alert definition for a program.
- Required args: `program_id: str`, `name: str`, `alert_type: str`, `conditions: list[dict[str, Any]]`
- Optional args: `severity: str | None = None`, `description: str | None = None`, `channels: list[str] | None = None`, `recipients: dict[str, Any] | None = None`, `cooldown_minutes: int | None = None`
- Backend endpoints: `POST /internal/v1/admin/programs/{program_id}/alerts`

### `update_alert`

- Source: `agent/src/agent/alert_tools.py:222`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Update an existing alert definition.
- Required args: `alert_id: str`, `updates: dict[str, Any]`
- Backend endpoints: `GET /internal/v1/admin/alerts/{alert_id}`, `PATCH /internal/v1/admin/alerts/{alert_id}`

### `delete_alert`

- Source: `agent/src/agent/alert_tools.py:274`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Delete an alert definition.
- Required args: `alert_id: str`
- Backend endpoints: `GET /internal/v1/admin/alerts/{alert_id}`, `DELETE /internal/v1/admin/alerts/{alert_id}`

### `pause_alert`

- Source: `agent/src/agent/alert_tools.py:323`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Pause an alert definition (stops it from triggering).
- Required args: `alert_id: str`
- Backend endpoints: `GET /internal/v1/admin/alerts/{alert_id}`, `POST /internal/v1/admin/alerts/{alert_id}/pause`

### `activate_alert`

- Source: `agent/src/agent/alert_tools.py:367`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Activate a paused alert definition.
- Required args: `alert_id: str`
- Backend endpoints: `GET /internal/v1/admin/alerts/{alert_id}`, `POST /internal/v1/admin/alerts/{alert_id}/activate`

### `acknowledge_alert`

- Source: `agent/src/agent/alert_tools.py:408`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Acknowledge a triggered alert (marks the incident as seen).
- Required args: `history_id: int`
- Backend endpoints: `POST /internal/v1/admin/alerts/history/{history_id}/acknowledge`

### `resolve_alert`

- Source: `agent/src/agent/alert_tools.py:446`
- Safety: `approval-required`
- Registry: `ALERT_DESTRUCTIVE_TOOLS`
- Summary: Resolve a triggered alert (closes the incident).
- Required args: `history_id: int`
- Backend endpoints: `POST /internal/v1/admin/alerts/history/{history_id}/resolve`

### `get_program_status`

- Source: `agent/src/agent/lifecycle_tools.py:64`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: Get detailed operational status for a program.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/status`

### `pause_program`

- Source: `agent/src/agent/lifecycle_tools.py:86`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Pause a live loyalty program (emergency lever — halts rule evaluation and token operations for the whole program).
- Required args: `program_id: str`, `reason: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/status`, `POST /internal/v1/admin/programs/{program_id}/pause`

### `resume_program`

- Source: `agent/src/agent/lifecycle_tools.py:139`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Resume a paused loyalty program.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/status`, `POST /internal/v1/admin/programs/{program_id}/resume`

### `deprecate_program`

- Source: `agent/src/agent/lifecycle_tools.py:180`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Deprecate a loyalty program (terminal lifecycle state).
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/status`, `POST /internal/v1/admin/programs/{program_id}/deprecate`

### `list_campaigns`

- Source: `agent/src/agent/lifecycle_tools.py:230`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: List campaigns for a program.
- Required args: `program_id: str`
- Optional args: `status: str | None = None`, `limit: int | None = None`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/campaigns`

### `get_campaign`

- Source: `agent/src/agent/lifecycle_tools.py:262`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: Get a single campaign's full configuration.
- Required args: `campaign_id: str`
- Backend endpoints: `GET /internal/v1/admin/campaigns/{campaign_id}`

### `update_campaign`

- Source: `agent/src/agent/lifecycle_tools.py:296`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Update a campaign's configuration.
- Required args: `campaign_id: str`, `updates: dict[str, Any]`
- Backend endpoints: `GET /internal/v1/admin/campaigns/{campaign_id}`

### `activate_campaign`

- Source: `agent/src/agent/lifecycle_tools.py:394`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Activate a campaign (starts serving its experiences to the audience).
- Required args: `campaign_id: str`
- Backend endpoints: `POST /internal/v1/admin/campaigns/{campaign_id}/activate`

### `pause_campaign`

- Source: `agent/src/agent/lifecycle_tools.py:418`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Pause an active campaign.
- Required args: `campaign_id: str`
- Backend endpoints: `POST /internal/v1/admin/campaigns/{campaign_id}/pause`

### `schedule_campaign`

- Source: `agent/src/agent/lifecycle_tools.py:442`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Schedule a draft campaign to run within its configured start/end window.
- Required args: `campaign_id: str`
- Backend endpoints: `POST /internal/v1/admin/campaigns/{campaign_id}/schedule`

### `list_experiences`

- Source: `agent/src/agent/lifecycle_tools.py:474`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: List game experiences for a program.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/experiences`

### `get_experience`

- Source: `agent/src/agent/lifecycle_tools.py:492`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: Get a single game experience's full configuration.
- Required args: `experience_id: str`
- Backend endpoints: `GET /internal/v1/admin/experiences/{experience_id}`

### `get_prize_pool`

- Source: `agent/src/agent/lifecycle_tools.py:510`
- Safety: `safe/read-only`
- Registry: `LIFECYCLE_SAFE_TOOLS`
- Summary: Get the prize pool attached to a game experience.
- Required args: `experience_id: str`
- Backend endpoints: `GET /internal/v1/admin/experiences/{experience_id}/prize-pool`

### `update_experience`

- Source: `agent/src/agent/lifecycle_tools.py:528`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Update a game experience's configuration.
- Required args: `experience_id: str`, `updates: dict[str, Any]`
- Backend endpoints: `GET /internal/v1/admin/experiences/{experience_id}`

### `publish_experience`

- Source: `agent/src/agent/lifecycle_tools.py:620`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Publish a game experience (makes it live for members).
- Required args: `experience_id: str`
- Backend endpoints: `POST /internal/v1/admin/experiences/{experience_id}/publish`

### `pause_experience`

- Source: `agent/src/agent/lifecycle_tools.py:648`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Pause a live game experience.
- Required args: `experience_id: str`
- Backend endpoints: `POST /internal/v1/admin/experiences/{experience_id}/pause`

### `create_prize_pool`

- Source: `agent/src/agent/lifecycle_tools.py:672`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Create (or replace) the prize pool for a game experience.
- Required args: `experience_id: str`, `pool_config: dict[str, Any]`
- Backend endpoints: `POST /internal/v1/admin/experiences/{experience_id}/prize-pool`

### `reject_content_variant`

- Source: `agent/src/agent/lifecycle_tools.py:724`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Reject a generated content variant (completes the review loop — the agent could previously only approve).
- Required args: `variant_id: str`
- Optional args: `notes: str | None = None`
- Backend endpoints: `POST /internal/v1/admin/content/variants/{variant_id}/reject`

### `edit_content_variant`

- Source: `agent/src/agent/lifecycle_tools.py:770`
- Safety: `approval-required`
- Registry: `LIFECYCLE_DESTRUCTIVE_TOOLS`
- Summary: Edit a generated content variant's text before approval.
- Required args: `variant_id: str`, `content_text: str`
- Backend endpoints: `POST /internal/v1/admin/content/variants/{variant_id}/edit`

### `get_stablecoin_setup_status`

- Source: `agent/src/agent/stablecoin_tools.py:104`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get stablecoin setup status for a program (checklist progress, rail binding state, issuance readiness).
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/setup-status`

### `get_stablecoin_setup_doctor`

- Source: `agent/src/agent/stablecoin_tools.py:123`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Run the stablecoin setup doctor — diagnostic checks explaining what is blocking issuance for a program and how to fix it.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/setup-doctor`

### `get_stablecoin_issuance_config`

- Source: `agent/src/agent/stablecoin_tools.py:142`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Read a program's stablecoin issuance configuration.
- Required args: `program_id: str`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-config`

### `list_reconciliation_exceptions`

- Source: `agent/src/agent/stablecoin_tools.py:163`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: List stablecoin reconciliation exceptions (ledger/provider mismatches).
- Required args: `program_id: str`
- Optional args: `status: str | None = None`, `limit: int | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/reconciliation/exceptions`

### `get_stablecoin_issuance_funnel`

- Source: `agent/src/agent/stablecoin_tools.py:200`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get the stablecoin issuance funnel (reward intents → issued → delivered, with drop-off at each stage).
- Required args: `program_id: str`
- Optional args: `start: str | None = None`, `end: str | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-funnel`

### `get_stablecoin_liability_buckets`

- Source: `agent/src/agent/stablecoin_tools.py:232`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get stablecoin liability bucketed by lifecycle state (pending, issued, in-flight, settled).
- Required args: `program_id: str`
- Optional args: `start: str | None = None`, `end: str | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/liability-buckets`

### `get_stablecoin_campaign_roi`

- Source: `agent/src/agent/stablecoin_tools.py:264`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get stablecoin campaign ROI (reward cost vs. attributed activity).
- Required args: `program_id: str`
- Optional args: `filters: dict[str, Any] | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/campaign-roi`

### `get_stablecoin_provider_ops`

- Source: `agent/src/agent/stablecoin_tools.py:289`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get stablecoin provider operations summary (submission outcomes, latencies, failure classes per provider/network).
- Required args: `program_id: str`
- Optional args: `filters: dict[str, Any] | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/provider-ops`

### `get_stablecoin_game_economics`

- Source: `agent/src/agent/stablecoin_tools.py:317`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get stablecoin game economics (prize cost vs. engagement per campaign/experience/session).
- Required args: `program_id: str`
- Optional args: `filters: dict[str, Any] | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/game-economics`

### `get_reward_intent_timeline`

- Source: `agent/src/agent/stablecoin_tools.py:343`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Trace a single stablecoin reward intent through its full lifecycle (intent → issuance → provider submission → settlement).
- Required args: `program_id: str`, `reward_intent_id: str`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}`

### `get_member_stablecoin_timeline`

- Source: `agent/src/agent/stablecoin_tools.py:367`
- Safety: `safe/read-only`
- Registry: `STABLECOIN_SAFE_TOOLS`
- Summary: Get a member's stablecoin activity timeline (rewards, issuances, settlements).
- Required args: `program_id: str`, `member_id: str`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}`

### `configure_stablecoin_issuance_handoff`

- Source: `agent/src/agent/stablecoin_tools.py:396`
- Safety: `approval-required`
- Registry: `STABLECOIN_DESTRUCTIVE_TOOLS`
- Summary: Propose a stablecoin issuance-config change as an operator handoff.
- Required args: `program_id: str`, `proposed_config: dict[str, Any]`
- Optional args: `rationale: str | None = None`
- Backend endpoints: `GET /internal/v1/admin/stablecoin/programs/{program_id}/issuance-config`

### `create_reconciliation_run_handoff`

- Source: `agent/src/agent/stablecoin_tools.py:465`
- Safety: `approval-required`
- Registry: `STABLECOIN_DESTRUCTIVE_TOOLS`
- Summary: Propose a stablecoin reconciliation run as an operator handoff.
- Required args: `program_id: str`
- Optional args: `run_type: str = "manual"`, `source_window_start: str | None = None`, `source_window_end: str | None = None`, `rationale: str | None = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `transition_reconciliation_exception_handoff`

- Source: `agent/src/agent/stablecoin_tools.py:536`
- Safety: `approval-required`
- Registry: `STABLECOIN_DESTRUCTIVE_TOOLS`
- Summary: Propose a reconciliation-exception transition as an operator handoff.
- Required args: `program_id: str`, `exception_id: str`, `action: str`
- Optional args: `notes: str | None = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `get_commerce_pilot_health`

- Source: `agent/src/agent/pilot_health_tools.py:32`
- Safety: `safe/read-only`
- Registry: `PILOT_HEALTH_TOOLS`
- Summary: Get the aggregated commerce pilot health snapshot for a program.
- Required args: `program_id: str`
- Optional args: `window: str = "24h"`
- Backend endpoints: `GET /internal/v1/admin/commerce/pilot-health`

### `query_metric`

- Source: `agent/src/agent/analytics_tools.py:107`
- Safety: `safe/read-only`
- Registry: `ANALYTICS_TOOLS`
- Summary: Query a registered loyalty-program analytics metric.
- Required args: `metric_id: str`, `program_id: str`
- Optional args: `window_days: Optional[int] = None`, `group_by: Optional[str] = None`, `segment_filter: Optional[dict[str, Any]] = None`
- Backend endpoints: `POST /internal/v1/analytics/query`

### `send_test_event`

- Source: `agent/src/agent/test_event_tools.py:85`
- Safety: `safe/read-only`
- Registry: `TEST_EVENT_TOOLS`
- Summary: Send a test event to a program and return the rule-engine outcomes.
- Required args: `program_id: str`, `event_type: str`, `payload: dict[str, Any]`
- Optional args: `external_id: Optional[str] = None`, `external_id_type: Optional[str] = "crm"`, `idempotency_key: Optional[str] = None`
- Backend endpoints: `POST /internal/v1/programs/{program_id}/events`, `GET /internal/v1/admin/programs/{program_id}/activity-feed`

### `get_activity_feed`

- Source: `agent/src/agent/test_event_tools.py:247`
- Safety: `safe/read-only`
- Registry: `TEST_EVENT_TOOLS`
- Summary: Get the most recent events for a program (or a single member).
- Required args: `program_id: str`
- Optional args: `member_id: Optional[str] = None`, `limit: int = 20`, `event_type: Optional[str] = None`
- Backend endpoints: `GET /internal/v1/admin/programs/{program_id}/activity-feed`

### `list_integration_recipes`

- Source: `agent/src/agent/developer_tools.py:135`
- Safety: `safe/read-only`
- Registry: `DEVELOPER_TOOLS`
- Summary: List developer-installable integration recipes.
- Optional args: `framework: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `describe_integration_recipe`

- Source: `agent/src/agent/developer_tools.py:165`
- Safety: `safe/read-only`
- Registry: `DEVELOPER_TOOLS`
- Summary: Describe a single integration recipe in detail.
- Required args: `name: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `generate_sdk_snippet`

- Source: `agent/src/agent/developer_tools.py:338`
- Safety: `safe/read-only`
- Registry: `DEVELOPER_TOOLS`
- Summary: Emit a ready-to-paste code snippet for a common LoyaltyRails operation.
- Required args: `operation: str`
- Optional args: `language: str = "ts"`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `suggest_developer_next_steps`

- Source: `agent/src/agent/developer_tools.py:384`
- Safety: `safe/read-only`
- Registry: `DEVELOPER_TOOLS`
- Summary: Suggest the next recipe(s) a developer should consider.
- Optional args: `framework: Optional[str] = None`, `installed_recipes: Optional[list[str]] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `provision_tenant`

- Source: `agent/src/agent/tenant_tools.py:53`
- Safety: `approval-required`
- Registry: `TENANT_TOOLS`
- Summary: Start provisioning a dedicated LoyaltyRails runtime for this customer.
- Optional args: `cloud_target: str = "render"`, `region: Optional[str] = None`, `slug: Optional[str] = None`
- Backend endpoints: `POST /api/v1/tenants/provision`

### `get_tenant_status`

- Source: `agent/src/agent/tenant_tools.py:156`
- Safety: `safe/read-only`
- Registry: `TENANT_TOOLS`
- Summary: Read the current lifecycle state of a tenant.
- Required args: `tenant_id: str`
- Backend endpoints: `GET /api/v1/tenants/{tenant_uuid}`

### `retry_tenant_provisioning`

- Source: `agent/src/agent/tenant_tools.py:208`
- Safety: `safe/read-only`
- Registry: `TENANT_TOOLS`
- Summary: Retry provisioning after a failed attempt.
- Required args: `tenant_id: str`
- Optional args: `alt_cloud_target: Optional[str] = None`
- Backend endpoints: `POST /api/v1/tenants/{tenant_uuid}/retry`

### `record_onboarding_persona`

- Source: `agent/src/agent/onboarding_tools.py:74`
- Safety: `safe/read-only`
- Registry: `ONBOARDING_TOOLS`
- Summary: Record the user's persona (business operator vs. developer).
- Required args: `persona: str`
- Optional args: `sub_persona: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `record_onboarding_vertical`

- Source: `agent/src/agent/onboarding_tools.py:127`
- Safety: `safe/read-only`
- Registry: `ONBOARDING_TOOLS`
- Summary: Record the user's industry vertical (e.g., QSR, beauty, hospitality).
- Required args: `vertical_slug: str`, `name: str`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `record_onboarding_goal`

- Source: `agent/src/agent/onboarding_tools.py:174`
- Safety: `safe/read-only`
- Registry: `ONBOARDING_TOOLS`
- Summary: Record the user's primary goal for this trial.
- Required args: `goal: str`
- Optional args: `sub_intent: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `bootstrap_workspace`

- Source: `agent/src/agent/onboarding_tools.py:223`
- Safety: `safe/read-only`
- Registry: `ONBOARDING_TOOLS`
- Summary: Record the workspace + (optional) first program shell name.
- Required args: `workspace_name: str`
- Optional args: `program_name: Optional[str] = None`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

### `show_vertical_picker`

- Source: `agent/src/agent/onboarding_tools.py:285`
- Safety: `safe/read-only`
- Registry: `ONBOARDING_TOOLS`
- Summary: Render a vertical pill picker as an artifact.
- Optional args: `query: Optional[str] = None`, `multi_select: bool = False`
- Backend endpoints: none discovered; tool performs local analysis or uses fetched data indirectly.

---

# Gamification

Source: ../docs/gamification.md
URL: https://docs.rails.sh/gamification
Markdown: https://docs.rails.sh/markdown/gamification.md

# Gamification

Status: initial developer-facing overview based on the current backend,
frontend, CLI, and planning material.

## Overview

rails gamification is a backend runtime plus control-plane model for
creating, resolving, playing, and measuring loyalty experiences. It is not just
a widget library. Experiences are configured by operators, resolved for members,
played through a channel-agnostic surface API, and connected to rewards,
campaigns, content, analytics, and audit events.

## Core Concepts

| Concept | Meaning |
|---------|---------|
| Experience | A complete playable interaction: mechanic type, config, display metadata, visual theme, policy, status, and schedule |
| Mechanic | The game logic shape, for example spin wheel, onboarding challenge, scratch-off, or quiz/trivia |
| Session | A member's in-progress or completed interaction with an experience |
| Campaign | Audience, budget, schedule, and packaging layer that can expose one or more experiences |
| Prize pool | Prize inventory and outcomes associated with an experience |
| Personalization rule | Campaign or experience rule that can adjust the resolved experience for a member |
| Question bank | Reusable questions for onboarding and quiz-style mechanics |
| Content Studio | Review and approval workflow for generated content variants |
| Difficulty recommendation | AI-assisted recommendation to tune experience configuration based on performance |

## Deep Dives

| Guide | Covers |
|-------|--------|
| [Gamification Builder](./gamification/builder.md) | Builder model, mechanic config, display config, visual theme, and publish gates |
| [Experiences](./gamification/experiences.md) | Experience model, mechanic types, session policy, runtime surface APIs, and recipes |
| [Campaigns](./gamification/campaigns.md) | Campaign model, audience and budget config, activation, campaign tiles, and agent workflows |
| [Content Intelligence](./gamification/content-intelligence.md) | Generated content, approval queues, content scopes, cache behavior, and adaptive difficulty |

## Implemented Mechanics

The backend currently models these mechanic types:

| Mechanic | Identifier | Notes |
|----------|------------|-------|
| Spin wheel | `spin_wheel` | 3-12 segments, segment labels/colors, prize keys, animation duration |
| Onboarding challenge | `onboarding_challenge` | Multi-step profile/question flow with optional per-step and completion rewards |
| Scratch-off | `scratch_off` | 2x2 through 6x6 reveal grid with prize keys per cell |
| Quiz/trivia | `quiz_trivia` | Question set with server-side correct answers, scoring, pass threshold, and rewards |

## Experience Lifecycle

```text
create draft
  -> update draft
  -> publish
  -> resolve for member
  -> start session
  -> submit actions
  -> complete session
  -> apply outcomes and emit events
```

Only draft experiences can be updated. Publishing validates mechanic config,
policy fields, content templates, and visual theme.

## Admin API

Experience management:

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/experiences` | List experiences |
| `POST` | `/admin/v1/programs/:program_id/experiences` | Create draft experience |
| `GET` | `/admin/v1/experiences/:experience_id` | Get experience |
| `PUT` | `/admin/v1/experiences/:experience_id` | Update draft experience |
| `POST` | `/admin/v1/experiences/:experience_id/publish` | Publish experience |
| `POST` | `/admin/v1/experiences/:experience_id/pause` | Pause experience |
| `GET` | `/admin/v1/experiences/:experience_id/prize-pool` | Get prize pool |
| `POST` | `/admin/v1/experiences/:experience_id/prize-pool` | Create prize pool |
| `GET` | `/admin/v1/experiences/:experience_id/sessions` | List sessions |

Campaign management:

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/admin/v1/programs/:program_id/campaigns` | List campaigns |
| `POST` | `/admin/v1/programs/:program_id/campaigns` | Create campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/experiences` | Attach experience |
| `POST` | `/admin/v1/campaigns/:campaign_id/activate` | Activate campaign |

## Surface API

These routes are used by generated app integrations and channel runtimes. They
use integration API-key auth and program scope checks.

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/internal/v1/games/resolve` | Resolve playable experiences for a member |
| `POST` | `/internal/v1/games/sessions` | Start an idempotent game session |
| `POST` | `/internal/v1/games/sessions/:session_id/actions` | Submit a mechanic action |
| `POST` | `/internal/v1/games/sessions/:session_id/complete` | Complete a session |
| `GET` | `/internal/v1/games/programs/:program_id/members/:member_id/reward-state` | Get member game reward state |

Resolve:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001"
}
```

Start session:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001",
  "experienceId": "550e8400-e29b-41d4-a716-446655440002",
  "campaignId": "550e8400-e29b-41d4-a716-446655440003",
  "idempotencyKey": "session-order-123",
  "surface": "web"
}
```

Submit action:

```json
{
  "sequence": 1,
  "actionType": "spin",
  "payload": {
    "segmentIndex": 0
  }
}
```

## CLI

Operator setup commands:

```bash
loyaltyrails experiences list --program <program_uuid>
loyaltyrails experiences create \
  --program <program_uuid> \
  --name "Spin to win" \
  --mechanic spin_wheel \
  --mechanic-config '{"segments":[{"label":"100 points","color":"#2f6fed","prizeKey":"points_100"},{"label":"50 points","color":"#14b86a","prizeKey":"points_50"},{"label":"Try again","color":"#d8dde8","prizeKey":"no_prize"}],"spinDurationMs":3000}'
loyaltyrails experiences publish <experience_uuid>
```

Campaign commands:

```bash
loyaltyrails campaigns create \
  --program <program_uuid> \
  --name "Spring launch" \
  --type manual \
  --audience-config '{"targetAll":true}'

loyaltyrails campaigns attach-experience <campaign_uuid> \
  --experience <experience_uuid> \
  --priority 5

loyaltyrails campaigns activate <campaign_uuid>
```

Runtime smoke commands:

```bash
loyaltyrails games resolve --member-id <member_uuid>
loyaltyrails games start \
  --experience-id <experience_uuid> \
  --member-id <member_uuid> \
  --idempotency-key game_session_123
loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{"segmentIndex":0}'
loyaltyrails games complete --session-id <session_uuid>
```

## Generated App Recipes

The CLI can generate game runtime code for customer applications:

| Recipe | Purpose |
|--------|---------|
| `loyaltyrails add game-session-route` | Server proxy for resolve/start/submit/complete |
| `loyaltyrails add onboarding-challenge` | Onboarding challenge component plus game route |
| `loyaltyrails add campaign-tiles` | Campaign tiles component plus game route |
| `loyaltyrails integrate hydrogen` | Hydrogen balance and campaign game surfaces |

Generated components call host app routes. They do not include raw rails
API keys in browser code.

## Personalization And Intelligence

The current backend supports:

- Content variants with approval/rejection/edit flows.
- Content generation queue.
- Content cache.
- Difficulty recommendations.
- Game performance analytics.
- Member engagement projections.
- RAG context builders.

Important invariant: member-facing game resolution should use cached or
precomputed content. It should not wait on a live LLM call in the hot path.

## Documentation TODO

- Add per-mechanic schemas and examples.
- Add prize pool configuration docs.
- Add campaign audience and personalization-rule schemas.
- Add generated component usage examples.
- Add admin UI screenshots once the docs site supports assets.
- Add end-to-end "publish a campaign game" guide.

---

# Gamification Builder

Source: ../docs/gamification/builder.md
URL: https://docs.rails.sh/gamification-builder
Markdown: https://docs.rails.sh/markdown/gamification-builder.md

# Gamification Builder

Status: developer and agent reference for the current rails
gamification builder surface. Backend experience APIs, publish validation, CLI
experience commands, and the admin game builder are implemented. Some richer
builder affordances, especially campaign editing inside the admin UI, are still
partial or planned.

## Source References

| Area | Source |
| --- | --- |
| Experience admin API | `backend/src/games/api/admin.rs` |
| Experience aggregate and publish gate | `backend/src/games/domain/experience.rs` |
| Mechanic config schemas | `backend/src/games/domain/mechanic.rs` |
| Visual theme validation | `backend/src/games/domain/visual_theme.rs` |
| Admin games UI | `frontend/src/routes/admin/games/index.tsx` |
| Config editors | `frontend/src/components/games/MechanicConfigs.tsx` |
| Visual theme editor | `frontend/src/components/games/VisualThemeEditor.tsx` |
| CLI commands | `packages/cli/src/commands.ts` |
| Phase plans | `docs/plans/2026-03-30-gamification-platform-implementation.md`, `docs/plans/2026-03-30-gamification-phase-2-implementation.md`, `docs/plans/2026-04-16-gamification-phase-4-implementation.md` |

## Builder Model

The builder creates and edits an `Experience`, which is the durable definition
of a playable game interaction. An experience owns:

| Field | Purpose |
| --- | --- |
| `name`, `description` | Operator-facing identity and optional context |
| `mechanicType` | One of `spin_wheel`, `onboarding_challenge`, `scratch_off`, `quiz_trivia` |
| `mechanicConfig` | Mechanic-specific JSON validated at publish time |
| `displayConfig` | Channel/display metadata, including optional `contentTemplate` |
| `visualTheme` | Mechanic-specific presentation overrides |
| `sessionExpirySeconds` | Session lifetime hint and server expiry policy |
| `maxSessionsPerMember` | Frequency cap for a member on this experience |
| `cooldownSeconds` | Minimum time between member sessions |
| `startsAt`, `endsAt` | Optional playability window |
| `status`, `version`, `publishedAt` | Lifecycle and version metadata |

The backend stores draft data as JSON, but publish is not a blind status flip.
`Experience::publish()` parses the mechanic config into a typed Rust schema,
validates policy fields, validates any content template, validates the visual
theme, and only then marks the experience `published`.

## Lifecycle

```text
create draft
  -> edit draft
  -> publish
  -> resolve for member
  -> start session
  -> submit actions
  -> complete session
```

Draft is the only editable state through `PUT /admin/v1/experiences/:id`.
Published experiences can be paused, and paused experiences can be published
again after passing validation. The current admin detail route redirects back to
the games page; the implemented editing surface is the games index page's
create/edit flow.

## Admin API

Admin routes are mounted under both session-backed `/admin/v1/*` and
internal-key `/internal/v1/admin/*` handler mounts. Use `/admin/v1/*` for
browser/admin examples unless you are documenting an internal API-key caller.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/admin/v1/programs/:program_id/experiences` | List experiences |
| `POST` | `/admin/v1/programs/:program_id/experiences` | Create a draft experience |
| `GET` | `/admin/v1/experiences/:experience_id` | Fetch one experience |
| `PUT` | `/admin/v1/experiences/:experience_id` | Update a draft experience |
| `POST` | `/admin/v1/experiences/:experience_id/publish` | Publish or republish through validation |
| `POST` | `/admin/v1/experiences/:experience_id/pause` | Pause a published experience |
| `GET` | `/admin/v1/experiences/:experience_id/prize-pool` | List bound prize pools |
| `POST` | `/admin/v1/experiences/:experience_id/prize-pool` | Create and bind a prize pool |
| `GET` | `/admin/v1/experiences/:experience_id/sessions` | Inspect recent sessions |

Create draft:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/programs/$PROGRAM_ID/experiences" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spin to win",
    "mechanicType": "spin_wheel",
    "mechanicConfig": {
      "segments": [
        { "label": "100 points", "color": "#2f6fed", "prizeKey": "points_100" },
        { "label": "50 points", "color": "#14b86a", "prizeKey": "points_50" },
        { "label": "Try again", "color": "#d8dde8", "prizeKey": "no_prize" }
      ],
      "spinDurationMs": 3000
    },
    "displayConfig": {
      "contentTemplate": "Welcome back, {{member_name}}. Try {{experience_name}}."
    },
    "visualTheme": {
      "wheel": { "pointerStyle": "arrow", "segmentFontSize": 14 },
      "animation": { "celebrationType": "confetti" }
    },
    "sessionExpirySeconds": 1800,
    "maxSessionsPerMember": 1
  }'
```

Publish:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/experiences/$EXPERIENCE_ID/publish" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"
```

## CLI

Experience management commands require an operator-token profile. Listing needs
`games:read`, creation needs `games:create`, and publishing needs
`games:update`.

```bash
loyaltyrails experiences list --program <program_uuid>

loyaltyrails experiences create \
  --program <program_uuid> \
  --name "Spin to win" \
  --mechanic spin_wheel \
  --mechanic-config ./spin-wheel.json \
  --display-config '{"contentTemplate":"Welcome back, {{member_name}}."}' \
  --visual-theme '{"wheel":{"pointerStyle":"arrow"}}' \
  --max-sessions-per-member 1

loyaltyrails experiences publish <experience_uuid>
```

JSON options accept inline JSON or a file path. Prefixing a file path with `@`
is also supported by the CLI JSON reader.

## Mechanics In The Builder

| Mechanic | Implemented config editor | Backend validation |
| --- | --- | --- |
| `spin_wheel` | Segment table, prize keys, colors, weights in UI | 3-12 segments, non-empty labels/prize keys, `spinDurationMs` 1000-10000 |
| `onboarding_challenge` | Step list for profile fields and questions | 1-20 steps, valid fields/questions, optional point rewards |
| `scratch_off` | Grid dimensions and cell prize keys | 2x2 through 6x6, `cellPrizeKeys.length == rows * cols` |
| `quiz_trivia` | Questions, options, correct index, scoring | 1-50 questions, >=2 options, valid `correctIndex`, positive points |

Current UI caveat: parts of the visual builder carry editor-only affordances
such as spin segment `weight`, scratch `revealLimit`, and quiz
`timePerQuestionMs`. The backend ignores or rejects fields that are not part of
the typed publish schema, depending on the target schema. Treat the backend
publish gate as the contract of record.

## Display Config

`displayConfig` is intentionally flexible JSON. The field currently used by
the backend is:

| Field | Type | Behavior |
| --- | --- | --- |
| `contentTemplate` | string | Rendered during `resolve` with allowed variables |

Resolve-time variables currently include:

| Variable | Meaning |
| --- | --- |
| `experience_name` | Experience name |
| `program_name` | Loyalty program name |
| `member_name` | Display name from member profile, when present |
| `member_tier` | Member tier, when present |
| `member_points` | Member tier points, when present |

Invalid or unsupported template variables fail the publish gate.

## Visual Theme

An empty object `{}` is valid for every mechanic. Non-empty themes are validated
per mechanic:

| Mechanic | Theme fields |
| --- | --- |
| `spin_wheel` | `wheel.borderColor`, `wheel.pointerStyle`, `wheel.segmentFontSize`, `wheel.centerImageUrl`, `animation.preSpinDelayMs`, `animation.celebrationType` |
| `scratch_off` | `card.coverImageUrl`, `card.coverPattern`, `card.revealAnimation`, `card.backgroundColor`, `scratchTool.cursorStyle`, `scratchTool.scratchRadius`, `scratchTool.revealThreshold` |
| `onboarding_challenge` | `layout.style`, `layout.progressIndicator`, `branding.accentColor`, `branding.logoUrl` |
| `quiz_trivia` | Pass-through JSON object for now |

Theme URLs must start with `https://`. Colors must be `#RGB` or `#RRGGBB`.
Unknown fields are rejected for the typed theme schemas.

## Publish Gates

The publish gate validates:

| Gate | Failure examples |
| --- | --- |
| Lifecycle | Cannot publish from an unsupported status |
| Mechanic config | Spin wheel with fewer than 3 segments; quiz `correctIndex` out of range |
| Policy | `maxSessionsPerMember <= 0`, negative cooldown, `endsAt <= startsAt`, expiry outside 60-86400 seconds |
| Content template | Non-string `contentTemplate` or unsupported template variable |
| Visual theme | Invalid enum, invalid URL, invalid color, out-of-range animation values |

Agents should call publish before assuming a generated config is playable.
Validation failures are the best feedback loop for refining generated JSON.

## Admin UX Status

Implemented:

- Games list with status filters and mechanic filters.
- Create/edit flow on `/admin/games`.
- Per-mechanic config editors.
- Visual theme editor and live preview component.
- Publish, pause, prize-pool, sessions, and leaderboard client API methods.

Partial or planned:

- A standalone `/admin/games/:gameId` detail route currently redirects to
  `/admin/games`.
- Campaign authoring is backend/CLI/agent-first; a dedicated campaign admin UI
  is not present in the inspected frontend.
- Packaged public runtime components are not yet official; generated app
  recipes currently provide storefront game surfaces.

---

# Experiences

Source: ../docs/gamification/experiences.md
URL: https://docs.rails.sh/gamification-experiences
Markdown: https://docs.rails.sh/markdown/gamification-experiences.md

# Gamification Experiences

Status: backend runtime, admin APIs, CLI smoke commands, and generated app
recipes are implemented for the core experience/session flow. This page
documents the current source contract and notes where frontend/runtime packaging
is still evolving.

## Source References

| Area | Source |
| --- | --- |
| Experience aggregate | `backend/src/games/domain/experience.rs` |
| Mechanic schemas | `backend/src/games/domain/mechanic.rs` |
| Shared surface types | `backend/src/games/domain/types.rs` |
| Session aggregate | `backend/src/games/domain/session.rs` |
| Game engine | `backend/src/games/service/engine.rs` |
| Surface API handlers | `backend/src/games/api/surface.rs` |
| CLI game commands | `packages/cli/src/commands.ts` |
| Generated Next.js recipes | `packages/cli/src/integration/next-app-router.ts` |
| Generated Hydrogen recipes | `packages/cli/src/integration/hydrogen.ts` |
| Admin frontend API client | `frontend/src/lib/api.ts` |

## Experience Model

An experience is a published or draft playable interaction for one loyalty
program. It combines a mechanic, display configuration, visual theme, session
policy, schedule, and lifecycle status.

| Field | Type | Notes |
| --- | --- | --- |
| `id` | UUID | Experience identifier |
| `programId` | UUID | Owning loyalty program |
| `mechanicType` | string | `spin_wheel`, `onboarding_challenge`, `scratch_off`, or `quiz_trivia` |
| `mechanicConfig` | JSON | Server-side source config; may include secrets such as quiz `correctIndex` |
| `displayConfig` | JSON | Display metadata and optional `contentTemplate` |
| `visualTheme` | JSON | Validated presentation overrides |
| `sessionExpirySeconds` | integer | Defaults to 1800 seconds at session start if unset |
| `maxSessionsPerMember` | integer | Optional lifetime cap per member and experience |
| `cooldownSeconds` | integer | Optional cooldown between sessions |
| `startsAt`, `endsAt` | RFC 3339 | Optional playability window |
| `campaignGated` | boolean | Stored internally; campaign-attached experiences resolve only through matching campaigns |
| `status` | string | `draft`, `published`, `paused`, `archived` |

Only `published` experiences inside their schedule window are playable.

## Mechanic Types

| Mechanic | Identifier | Actions | Client-safe resolved config |
| --- | --- | --- | --- |
| Spin wheel | `spin_wheel` | 1 action | Segment labels/colors and spin duration; prize keys are stripped |
| Onboarding challenge | `onboarding_challenge` | One action per step | Steps, questions, options, fields, and labels |
| Scratch-off | `scratch_off` | One action per cell | Grid dimensions and total cells; prize map is hidden |
| Quiz/trivia | `quiz_trivia` | One action per question | Questions/options and scoring policy; correct answers are hidden until answer feedback |

### Spin Wheel Config

```json
{
  "segments": [
    { "label": "100 points", "color": "#2f6fed", "prizeKey": "points_100" },
    { "label": "50 points", "color": "#14b86a", "prizeKey": "points_50" },
    { "label": "Try again", "color": "#d8dde8", "prizeKey": "no_prize" }
  ],
  "spinDurationMs": 3000
}
```

The prize pool owns probability and outcomes. Wheel segments are presentation
metadata keyed by `prizeKey`.

### Onboarding Challenge Config

```json
{
  "steps": [
    {
      "type": "question",
      "question": "Favorite category?",
      "options": ["Food", "Travel", "Shopping"],
      "field": "favorite_category"
    },
    {
      "type": "profile_field",
      "field": "email",
      "label": "Add your email"
    }
  ],
  "rewardPerStep": { "type": "points", "amount": 50 },
  "completionReward": { "type": "points", "amount": 500 }
}
```

Action payloads must include `answer`. Answers update member profile data
transactionally with session events. The event summary redacts the raw answer.

### Scratch-Off Config

```json
{
  "gridCols": 3,
  "gridRows": 3,
  "cellPrizeKeys": [
    "points_100", "no_prize", "points_50",
    "no_prize", "offer_1", "no_prize",
    "points_25", "no_prize", "badge_1"
  ]
}
```

At session start, the engine precomputes a reveal map and reserves budget for
the session. Expired scratch-off sessions release reserved budget through the
expiry worker.

### Quiz/Trivia Config

```json
{
  "questions": [
    {
      "question": "Which tier earns the most?",
      "options": ["Silver", "Gold", "Platinum"],
      "correctIndex": 2
    }
  ],
  "pointsPerCorrect": 10,
  "passingScore": 10
}
```

`correctIndex` is server-side config. It is not returned by `resolve`; it is
returned as feedback only after an answer is submitted.

## Session Rules

Session start is idempotent and transactional.

| Rule | Behavior |
| --- | --- |
| Idempotency | `programId + idempotencyKey` replays return the original session |
| Identity check | Reusing a key for another member or experience is rejected |
| Rate limit | Unique starts are limited per member/experience window; replays bypass the counter |
| Frequency cap | `maxSessionsPerMember` is checked at resolve and start |
| Cooldown | `cooldownSeconds` is checked at resolve and start |
| Expiry | Sessions expire at `startedAt + sessionExpirySeconds` or default 1800 seconds |
| Campaign gate | Campaign-gated experiences require a valid matching `campaignId` at start |
| Ordered actions | `sequence` must match the next expected action number |

## Surface API

Surface routes use integration API-key auth and program scope checks.

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| `POST` | `/internal/v1/games/resolve` | read | Resolve playable experiences for a member |
| `POST` | `/internal/v1/games/sessions` | write | Start an idempotent session |
| `POST` | `/internal/v1/games/sessions/:session_id/actions` | write | Submit one mechanic action |
| `POST` | `/internal/v1/games/sessions/:session_id/complete` | write | Complete a session |
| `GET` | `/internal/v1/games/programs/:program_id/members/:member_id/reward-state` | read | Read member game reward state |

Resolve request:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001"
}
```

Resolve response shape:

```json
[
  {
    "experienceId": "550e8400-e29b-41d4-a716-446655440002",
    "mechanicType": "spin_wheel",
    "playableConfig": {
      "mechanicType": "spin_wheel",
      "segments": [
        { "label": "100 points", "color": "#2f6fed" }
      ],
      "spinDurationMs": 3000
    },
    "displayConfig": {},
    "renderedContent": "Welcome back, Ada.",
    "campaignId": "550e8400-e29b-41d4-a716-446655440003",
    "personalized": false,
    "visualTheme": {},
    "sessionExpirySeconds": 1800
  }
]
```

Start request:

```json
{
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "memberId": "550e8400-e29b-41d4-a716-446655440001",
  "experienceId": "550e8400-e29b-41d4-a716-446655440002",
  "campaignId": "550e8400-e29b-41d4-a716-446655440003",
  "idempotencyKey": "checkout-123-spin",
  "surface": "web",
  "fingerprint": "optional-device-or-browser-token"
}
```

Submit action examples:

```json
{ "sequence": 1, "actionType": "spin", "payload": {} }
```

```json
{ "sequence": 1, "actionType": "answer", "payload": { "answerIndex": 2 } }
```

```json
{ "sequence": 1, "actionType": "reveal", "payload": { "cellIndex": 4 } }
```

```json
{ "sequence": 1, "actionType": "answer", "payload": { "answer": "Travel" } }
```

## Resolve, Start, Submit, Complete

| Step | Server behavior |
| --- | --- |
| `resolve` | Fetches published experiences, applies playability, frequency, cooldown, campaign visibility, personalization, AI content cache lookup, and returns client-safe config |
| `start` | Rechecks eligibility, enforces campaign gate, creates session, initializes mechanic state, emits `GameSessionStarted` |
| `submit` | Validates sequence and payload, appends session event, updates mechanic state, resolves/applies prizes when appropriate |
| `complete` | Completes active sessions, applies completion outcomes where appropriate, consumes/release reservations, emits completion events |

Important: clients should use `campaignId` returned from `resolve` when starting
a campaign-backed experience. The backend persists the campaign on the session
and does not re-resolve campaign state later.

## CLI Smoke Flow

The `games` CLI commands use integration-key profiles and are meant to smoke
test existing runtime state. They do not create experiences or campaigns.

```bash
loyaltyrails games resolve \
  --program <program_uuid> \
  --member-id <member_uuid>

loyaltyrails games start \
  --program <program_uuid> \
  --experience-id <experience_uuid> \
  --campaign-id <campaign_uuid> \
  --member-id <member_uuid> \
  --idempotency-key checkout-123-spin \
  --surface web

loyaltyrails games submit \
  --session-id <session_uuid> \
  --sequence 1 \
  --action-type spin \
  --payload '{}'

loyaltyrails games complete --session-id <session_uuid>
```

## Generated App Recipes

Implemented CLI recipes generate server-backed routes and client components for
host apps:

| Command | Generated behavior |
| --- | --- |
| `loyaltyrails add game-session-route` | Server proxy for resolve/start/submit/complete |
| `loyaltyrails add onboarding-challenge` | Onboarding component plus game route |
| `loyaltyrails add campaign-tiles` | Campaign tile component plus game route |
| `loyaltyrails integrate hydrogen` | Hydrogen balance and campaign game surfaces |

Generated routes keep the integration API key server-side. Browser components
call the host app route and receive a signed session token rather than raw
backend secrets.

## Implementation Boundaries

Implemented:

- Four mechanic types and typed client-safe `PlayableConfig`.
- Idempotent session start, sequence-guarded actions, expiry, rate limiting,
  prize outcomes, and event/audit writes.
- Admin APIs for experiences, prize pools, and sessions.
- CLI management commands for experiences and smoke commands for games.
- Generated Next.js/Hydrogen game-session and campaign-tile recipes.

Partial or planned:

- Official packaged runtime components are not yet implemented.
- The admin `/admin/games/:gameId` detail route currently redirects to the
  games index.
- Some frontend config-editor fields are more permissive than backend publish
  validation; the backend contract wins.

---

# Campaigns

Source: ../docs/gamification/campaigns.md
URL: https://docs.rails.sh/gamification-campaigns
Markdown: https://docs.rails.sh/markdown/gamification-campaigns.md

# Gamification Campaigns

Status: campaign backend APIs, campaign scheduling worker, CLI campaign
commands, campaign-aware game resolution, generated campaign tile recipes, and
agent campaign tools are present. A dedicated campaign admin UI was not found
in the inspected frontend; campaigns are currently strongest through backend,
CLI, generated storefront surfaces, and agent workflows.

## Source References

| Area | Source |
| --- | --- |
| Campaign domain | `backend/src/games/domain/campaign.rs` |
| Campaign admin API | `backend/src/games/api/campaigns.rs` |
| Audience evaluation | `backend/src/games/service/audience.rs` |
| Game resolution/campaign binding | `backend/src/games/service/engine.rs` |
| Campaign worker | `backend/src/games/service/campaign_worker.rs` |
| Campaign repositories | `backend/src/games/repository/campaigns.rs`, `backend/src/games/repository/campaign_budgets.rs` |
| CLI campaign commands | `packages/cli/src/commands.ts` |
| Generated campaign tiles | `packages/cli/src/integration/next-app-router.ts`, `packages/cli/src/integration/hydrogen.ts` |
| Agent tools | `agent/src/agent/tools.py` |
| Phase plan | `docs/plans/2026-04-16-gamification-phase-4-implementation.md` |

## Campaign Model

A campaign packages one or more experiences with audience targeting, scheduling,
budgets, and optional personalization rules.

| Field | Type | Notes |
| --- | --- | --- |
| `id` | UUID | Campaign identifier |
| `programId` | UUID | Owning loyalty program |
| `name`, `description` | string | Operator-facing identity |
| `campaignType` | string | `manual`, `scheduled`, `triggered`, or `agent_assembled` |
| `status` | string | `draft`, `scheduled`, `active`, `paused`, `completed`, `archived` |
| `startsAt`, `endsAt` | RFC 3339 | Optional schedule bounds |
| `audienceConfig` | object | Member-resolvable targeting |
| `budgetConfig` | object | Optional spend/session caps |
| `version` | integer | Campaign config version |

Campaigns are visibility containers. An experience attached to active campaigns
is only shown through a matching campaign. Experiences with no campaign
attachments remain standalone and can resolve for eligible members without a
campaign.

## Campaign Types

| Type | Meaning |
| --- | --- |
| `manual` | Operator-created and activated directly |
| `scheduled` | Intended to be activated by schedule |
| `triggered` | Modeled in the domain; event-triggered campaign behavior is still evolving |
| `agent_assembled` | Created from agent or natural-language workflows, starting as draft for review |

## Audience Config

`AudienceConfig` is fail-closed by default. If `targetAll` is false and there
are no conditions, the campaign matches no members.

```json
{
  "targetAll": false,
  "conditions": [
    { "type": "member_tier", "tiers": ["gold", "platinum"] },
    { "type": "member_segment", "segments": ["vip"] }
  ]
}
```

Audience-eligible conditions:

| Condition | Data source |
| --- | --- |
| `member_tier` | `member_mappings.tier` |
| `member_segment` | `member_mappings.segments` |
| `transaction_count` | Member transaction count |
| `consecutive_days` | Member streak state |
| `max_days_since_activity` | Last activity date |
| `engagement_tier` | Intelligence engagement projection |
| `profile_attribute` | Member profile JSON |
| `member_ids` | Explicit UUID allowlist |

`progression_level` and `progression_xp` are personalization-only and are
rejected in campaign audience config. They can be used in personalization rules
because progression is fetched after campaign visibility is decided.

`targetAll` cannot be combined with conditions:

```json
{ "targetAll": true, "conditions": [] }
```

## Budget Config

Budget config is optional. Missing budget config means the campaign itself does
not enforce the corresponding cap, though prize pools can still enforce their
own budgets and daily caps.

```json
{
  "maxTotalPrizeCents": 500000,
  "maxPrizePerMemberCents": 1000,
  "maxSessionsTotal": 10000,
  "maxSessionsPerMember": 1
}
```

| Field | Purpose |
| --- | --- |
| `maxTotalPrizeCents` | Total prize value cap across the campaign |
| `maxPrizePerMemberCents` | Per-member prize value cap |
| `maxSessionsTotal` | Total session cap |
| `maxSessionsPerMember` | Per-member campaign session cap |

Prize resolution reads the `campaignId` persisted on the session, so budget
accounting follows the campaign that actually produced the session.

## Campaign Selection

When multiple active campaigns attach the same experience and match the same
member, the resolver chooses one deterministically:

| Order | Rule |
| --- | --- |
| 1 | Highest campaign-experience `priority` |
| 2 | Highest audience specificity score |
| 3 | Earliest `startsAt` |
| 4 | Lowest UUID |

Specificity scores are computed from matched audience conditions:

| Condition | Weight |
| --- | --- |
| `member_ids` | 100 |
| `profile_attribute` | 20 |
| `engagement_tier` | 15 |
| `member_tier` | 15 |
| `member_segment` | 15 |
| `transaction_count` | 10 |
| `consecutive_days` | 10 |
| `max_days_since_activity` | 10 |

A `targetAll` campaign scores 0.

## Admin API

Admin routes are mounted under both `/admin/v1/*` and
`/internal/v1/admin/*`.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/admin/v1/programs/:program_id/campaigns` | List campaigns, optional `status` and `limit` |
| `POST` | `/admin/v1/programs/:program_id/campaigns` | Create campaign |
| `GET` | `/admin/v1/campaigns/:campaign_id` | Fetch campaign |
| `PUT` | `/admin/v1/campaigns/:campaign_id` | Update campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/activate` | Activate campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/schedule` | Schedule campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/pause` | Pause campaign |
| `POST` | `/admin/v1/campaigns/:campaign_id/experiences` | Attach an experience |
| `DELETE` | `/admin/v1/campaigns/:campaign_id/experiences/:experience_id` | Detach an experience |
| `GET` | `/admin/v1/campaigns/:campaign_id/personalization-rules` | List campaign rules |
| `POST` | `/admin/v1/campaigns/:campaign_id/personalization-rules` | Create campaign rule |
| `GET` | `/admin/v1/campaigns/:campaign_id/audience/preview` | Preview member eligibility |
| `POST` | `/admin/v1/members/:member_id/segments` | Add or remove manual member segments |

Create campaign:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/programs/$PROGRAM_ID/campaigns" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold reactivation",
    "campaignType": "manual",
    "audienceConfig": {
      "conditions": [
        { "type": "member_tier", "tiers": ["gold"] },
        { "type": "member_segment", "segments": ["at_risk"] }
      ]
    },
    "budgetConfig": {
      "maxTotalPrizeCents": 500000,
      "maxPrizePerMemberCents": 1000
    }
  }'
```

Attach experience:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/campaigns/$CAMPAIGN_ID/experiences" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "experienceId": "'$EXPERIENCE_ID'", "priority": 10 }'
```

## CLI

Campaign commands require an operator-token profile. Listing requires
`games:read`, creation requires `games:create`, and activation/attachment
require `games:update`.

```bash
loyaltyrails campaigns list \
  --program <program_uuid> \
  --status draft \
  --limit 10

loyaltyrails campaigns create \
  --program <program_uuid> \
  --name "Spring launch" \
  --type manual \
  --audience-config '{"targetAll":true}' \
  --budget-config '{"maxSessionsPerMember":1}'

loyaltyrails campaigns attach-experience <campaign_uuid> \
  --experience <experience_uuid> \
  --priority 5

loyaltyrails campaigns activate <campaign_uuid>
```

## Attaching Experiences

Attaching an experience creates a row in `loyalty_campaign_experiences`.
The backend verifies that the campaign and experience belong to the same
program. Duplicate attachments are rejected.

Attachment also causes the experience to be campaign-gated once it has at
least one campaign binding. In practice:

| Experience state | Resolve behavior |
| --- | --- |
| No campaign attachments | Standalone published experience can resolve |
| Campaign attachments exist, no matching active campaign | Experience is hidden |
| Matching active campaign exists | Experience resolves with `campaignId` |

Clients must pass the resolved `campaignId` into session start.

## Activation And Scheduling

Activation is allowed from `draft`, `scheduled`, or `paused`. Scheduling is
allowed from `draft` and requires `startsAt`. The campaign scheduler worker is
present in the backend and is intended to activate scheduled campaigns when
their start time arrives.

Campaign lifecycle events are appended transactionally with status changes:

| Event | Trigger |
| --- | --- |
| `CampaignCreated` | Create campaign |
| `CampaignActivated` | Activate campaign |
| `CampaignScheduled` | Schedule campaign |
| `CampaignPaused` | Pause campaign |
| `CampaignExperienceAttached` | Attach experience |
| `CampaignExperienceDetached` | Detach experience |

## Campaign Tiles

Generated app recipes expose campaign-backed experiences in storefronts.

```bash
loyaltyrails add campaign-tiles
loyaltyrails integrate hydrogen
```

The generated component calls the host app's server route, which proxies
`/internal/v1/games/resolve`. By default, campaign tiles filter to experiences
with a `campaignId`. Host apps can opt into standalone experiences through the
generated `includeStandalone` prop.

The generated route:

- Resolves member identity server-side.
- Keeps the rails integration API key server-side.
- Proxies resolve/start/submit/complete operations.
- Uses a signed local session token rather than exposing raw backend session IDs
  directly to browser code.

## Storefront Recipes

Common patterns:

| Recipe | Flow |
| --- | --- |
| Campaign launcher | Resolve experiences, show campaign-backed tiles, hand off to mechanic-specific UI |
| Onboarding campaign | Resolve onboarding challenge, start session, submit one answer per step, complete |
| Instant-win campaign | Resolve spin/scratch experience, start session, submit action, show prize result, complete |
| Loyalty hub | Combine balance widget, tier progress, campaign tiles, and game-session route |

Generated components are starting points, not the final design system. They are
safe-by-default integration code intended for adaptation inside the customer's
app.

## Agent Tools

Relevant agent tools from `agent/src/agent/tools.py`:

| Tool | Safety | Current behavior |
| --- | --- | --- |
| `create_campaign_from_description` | approval required | Parses a goal and audience description, creates a draft `agent_assembled` campaign |
| `preview_campaign_for_member` | read-only | Calls campaign audience preview |
| `suggest_campaign_optimizations` | read-only | Fetches campaign and returns local suggestions |
| `assemble_spin_wheel_for_segment` | approval required | Attempts to create an experience, prize pool, and personalization rule |

Implementation caveat: some agent tool endpoint paths use the internal admin
mount and may describe broader planned assembly behavior than the current
backend exposes through a single public workflow. Treat approval-gated agent
outputs as drafts to inspect, not as automatically production-ready campaigns.

## Current Gaps

- Dedicated campaign admin screens were not present in the inspected frontend.
- Event-triggered campaign execution is modeled but not fully documented as an
  implemented runtime.
- Campaign optimization suggestions are local agent analysis, not a backend ML
  optimizer.
- Storefront campaign tiles are generated integration code, not an official
  packaged runtime component.

---

# Content Intelligence

Source: ../docs/gamification/content-intelligence.md
URL: https://docs.rails.sh/content-intelligence
Markdown: https://docs.rails.sh/markdown/content-intelligence.md

# Gamification Content Intelligence

Status: backend Content Studio APIs, content generation queue, approval flow,
content cache integration, difficulty recommendation APIs, admin Content Studio
UI, and agent tools are present. LLM generation remains asynchronous and
approval-gated. Member-facing game resolution uses cached or static content and
does not call an LLM in the hot path.

## Source References

| Area | Source |
| --- | --- |
| Content Studio API | `backend/src/intelligence/api/admin.rs` |
| Content worker | `backend/src/intelligence/service/content_worker.rs` |
| Content cache | `backend/src/intelligence/service/content_cache.rs` |
| LLM abstraction | `backend/src/intelligence/domain/llm.rs`, `backend/src/intelligence/service/llm.rs` |
| Difficulty scheduler | `backend/src/intelligence/service/difficulty_scheduler.rs` |
| Difficulty repository | `backend/src/intelligence/repository/difficulty.rs` |
| Resolve integration | `backend/src/games/service/engine.rs` |
| Admin UI | `frontend/src/routes/admin/intelligence/index.tsx` |
| Frontend API client | `frontend/src/lib/api.ts` |
| Agent tools | `agent/src/agent/tools.py` |
| Phase plan | `docs/plans/2026-04-11-gamification-phase-3-implementation.md` |
| ADRs | `docs/adrs/ADR-004-async-content-generation.md`, `docs/adrs/ADR-005-content-approval-workflow.md`, `docs/adrs/ADR-006-three-tier-content-cache.md` |

## Core Invariant

No synchronous LLM calls happen during member-facing game resolution.

```text
enqueue generation
  -> worker builds RAG context
  -> LLM generates plain text
  -> variant enters pending_review
  -> human approves
  -> cache is populated
  -> resolve reads cache or falls back to static template
```

If generated content is missing, unapproved, rejected, or not cached, the game
runtime falls back to static `displayConfig.contentTemplate` or no rendered
content.

## Generated Content Model

Generated content is represented as a `ContentVariant`.

| Field | Meaning |
| --- | --- |
| `programId` | Tenant/program scope |
| `experienceId` | Optional target experience |
| `contentType` | Logical content class |
| `contentScope` | `segment` or `member_template` |
| `targetSegment` | Tier/segment discriminator, when scoped |
| `contentText` | Plain text only; no HTML contract |
| `llmProvider`, `llmModel` | Generation provenance |
| `approvalStatus` | `pending_review`, `approved`, or `rejected` |
| `version` | Version row for edits/audit |

Common content types used by tools and plans:

| Type | Status |
| --- | --- |
| `experience_copy` | Implemented through content generation APIs |
| `quiz_questions` | Agent/tool and question generation path present; AI should generate question text only |
| `prize_labels` | Planned/agent-facing text class |
| `notification` | Planned/agent-facing text class |

The backend accepts `contentType` as a string, so new text classes can be queued
before every downstream consumer has a specialized renderer.

## Content Scopes

| Scope | Purpose | Cache behavior | Approval validation |
| --- | --- | --- | --- |
| `segment` | Shared copy for a tier or segment | Cached by experience and segment | Plain text, no member variables |
| `member_template` | Template body rendered per member | Template body cached by experience and segment | Template variables limited to resolve-time values |

Allowed resolve-time variables for `member_template` are:

| Variable | Meaning |
| --- | --- |
| `experience_name` | Experience name |
| `program_name` | Program name |
| `member_name` | Display name from member profile |
| `member_tier` | Member tier |
| `member_points` | Member tier points |

Variables that require action-time context, such as `prize_label`, `score`, or
`rank`, are not available at resolve time and should not be used in
member-template content.

## Review Queue

Admin API:

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/admin/v1/programs/:program_id/content/variants?status=pending_review` | List variants |
| `GET` | `/admin/v1/content/variants/:variant_id` | Preview one variant |
| `POST` | `/admin/v1/content/variants/:variant_id/approve` | Approve and populate cache |
| `POST` | `/admin/v1/content/variants/:variant_id/reject` | Reject variant |
| `POST` | `/admin/v1/content/variants/:variant_id/edit` | Create edited pending-review version |
| `POST` | `/admin/v1/programs/:program_id/content/generate` | Enqueue generation |

Enqueue generation:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/programs/$PROGRAM_ID/content/generate" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "experienceId": "'$EXPERIENCE_ID'",
    "contentType": "experience_copy",
    "contentScope": "member_template",
    "targetSegment": "gold",
    "prompt": "Write concise spin wheel copy for gold members",
    "additionalInstructions": "One sentence. No HTML."
  }'
```

Approve:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/content/variants/$VARIANT_ID/approve" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"
```

Edit:

```bash
curl -X POST "$LOYALTYRAILS_API_URL/admin/v1/content/variants/$VARIANT_ID/edit" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contentText": "Welcome back, {{member_name}}. Your Gold reward is ready." }'
```

The current admin UI at `/admin/intelligence` supports:

- Filtering variants by `pending_review`, `approved`, or `rejected`.
- Approving, rejecting, and editing pending variants.
- Displaying content as plain text, not raw HTML.
- Listing and approving/rejecting difficulty recommendations.

## Approval Boundaries

| Action | Boundary |
| --- | --- |
| Generate content | Enqueues work only; does not publish member-facing content |
| Approve variant | Validates status and template scope, then populates cache |
| Reject variant | Marks variant rejected |
| Edit variant | Creates a new version row in `pending_review`; original remains for audit |
| Apply difficulty recommendation | Validates recommended config through the experience publish gate before changing live config |

Approval handler details:

- A variant must be `pending_review` to approve.
- Member-template content is validated against resolve-time variables.
- Edits sanitize text and create a new pending version.
- Approved content is not mutated in place.
- Cache writes are fail-safe; the system prefers static fallback over stale AI
  content.

## Resolve-Time Content Selection

During `resolve`, the game engine batch-fetches content for all playable
experiences:

```text
hot segment cache
  -> warm segment cache
  -> warm member-template body
  -> static displayConfig.contentTemplate
  -> none
```

For segment content, the cached content is returned as rendered content. For
member-template content, the backend renders the template with resolve-time
variables. The frontend should treat `renderedContent` as text content.

## Adaptive Difficulty

Difficulty recommendations are generated from game performance metrics and
store:

| Field | Meaning |
| --- | --- |
| `experienceId` | Target experience |
| `mechanicType` | Mechanic being tuned |
| `currentConfig` | Config snapshot when recommendation was created |
| `recommendedConfig` | Proposed replacement config |
| `rationale` | Human-readable reason |
| `metricsSnapshot` | Metrics used for the recommendation |
| `confidenceScore` | Optional model confidence |
| `status` | `pending`, `approved`, `applied`, or rejected status |

Admin API:

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/admin/v1/programs/:program_id/difficulty/recommendations` | List pending recommendations |
| `POST` | `/admin/v1/difficulty/recommendations/:recommendation_id/approve` | Apply after publish-gate validation |
| `POST` | `/admin/v1/difficulty/recommendations/:recommendation_id/reject` | Reject with optional notes |

Applying a recommendation does not bypass validation. The backend clones the
experience, swaps in `recommendedConfig`, runs `Experience::publish()` on the
clone, and only then updates the published experience's config/version inside a
transaction. Active sessions keep the state they started with.

## Agent Tools

Relevant tools from `agent/src/agent/tools.py`:

| Tool | Safety | Purpose |
| --- | --- | --- |
| `get_experience_metrics` | read-only | Fetch game metrics for adaptive analysis |
| `get_content_review_queue` | read-only | List variants awaiting review |
| `preview_generated_content` | read-only | Fetch one content variant |
| `get_difficulty_recommendations` | read-only | List pending recommendations |
| `generate_experience_content` | approval required | Enqueue content generation |
| `approve_content_variant` | approval required | Approve one generated variant |
| `apply_difficulty_recommendation` | approval required | Apply one recommendation after review |
| `generate_questions_for_vertical` | approval required | Enqueue question generation by vertical |

Agent approval gates are important because these actions either enqueue
potentially member-facing content or change live game configuration. Read-only
tools can be used for analysis and previews without approval.

Example agent-safe workflow:

```text
1. get_experience_metrics(program_id, experience_id)
2. generate_experience_content(..., content_scope="member_template")  # approval required
3. get_content_review_queue(program_id)
4. preview_generated_content(program_id, variant_id)
5. approve_content_variant(program_id, variant_id)                    # approval required
6. games resolve smoke test for a member
```

## CLI Status

The current inspected CLI exposes experience/campaign/game commands and
generated app recipes. It does not expose first-class content-intelligence
commands yet. Use the admin API, admin UI, or agent tools for content review
and difficulty workflows.

## Gaps And Assumptions

- `contentType` is stringly typed at the API boundary; consumers should agree on
  values before depending on a new type in production.
- Some agent tool docstrings describe intended internal endpoints and assembly
  behavior. Verify against backend route availability when wiring a new tool.
- Question generation should produce plain question text only; option labels and
  answer semantics should remain admin-authored.
- Content cache and LLM worker behavior depends on Redis, database queues, and
  configured provider settings being available in the deployment environment.

---

# Stablecoin Rewards

Source: ../docs/stablecoin-rewards.md
URL: https://docs.rails.sh/stablecoin-rewards
Markdown: https://docs.rails.sh/markdown/stablecoin-rewards.md

# Stablecoin Rewards

Status: coming soon. Stablecoin rewards are not enabled as a product feature
today — no member can earn, hold, or withdraw a stablecoin reward on the
platform. This page documents the planned design alongside the internal,
non-production scaffolding (fake-value settlement, schemas, and safety gates)
that already exists in code ahead of that launch.

## Overview

rails will support stablecoin rewards as a first-class reward asset that can
be produced by rules, games, API actions, and manual adjustments once this
capability is enabled. The intended product boundary is that the rules engine
will authorize rewards, while a separate settlement layer will decide how
those rewards become financial movement.

Today, the codebase implements only the internal, fake-value foundation this
future settlement layer will build on — deterministic, non-production evidence
used for local and CI testing, not a live settlement rail:

- Reward assets.
- Reward intents.
- Member wallets and external wallets.
- Withdrawal intents.
- Compliance decisions.
- Provider events.
- Stablecoin transfers.
- Ledger accounts and entries.
- Member asset balance projections.
- Provider asset mappings.
- Fake-value provider and settlement worker.
- Safety flags and provider-mode gates.

## Deep Dives

| Guide | Covers |
|-------|--------|
| [Reward Assets](./stablecoin/reward-assets.md) | Asset model, provider modes, award flow, fake-value terminology, and production gates |
| [Issuance And Settlement](./stablecoin/issuance-settlement.md) | Authorization, fake-value settlement lifecycle, idempotency, reserves, liability, and operations |
| [Wallets And Custody](./stablecoin/wallets-custody.md) | Wallet models, deterministic identifiers, Privy/ERC-4337 assumptions, external wallets, and custody boundaries |

## Current Boundary

| Capability | Current status |
|------------|----------------|
| Fake-value reward authorization | Implemented |
| Fake-value settlement evidence | Implemented |
| Member asset balance projections | Implemented |
| Stablecoin safety gates | Implemented |
| Production Base mainnet USDC movement | Not approved |
| Real provider settlement | Not approved |
| External wallet withdrawals | Not approved |
| Production custody claims | Not approved |

Do not document fake-value balances as redeemable production stablecoin. They
have no production value, no member custody, and no withdrawal right.

## Required Terminology

| Term | Meaning |
|------|---------|
| RewardIntent | Durable record that a member earned a reward from a rule, game, API, or manual adjustment |
| RewardAsset | Asset being awarded: points, stablecoin, badge, or offer |
| Settlement | Delivery of an authorized reward into the member-visible balance or wallet state |
| Redemption | Spending, burning, cashing out, or consuming a reward |
| Withdrawal | Moving stablecoin from platform/member-controlled balance to an external wallet |
| ProviderTransfer | Provider-level movement record with status, provider ID, tx hash, and reconciliation data |
| CustodyMode | Who controls the wallet: internal ledger, user, developer, provider, or external |
| Proof | Provider event, tx hash, block metadata, finality status, and ledger reconciliation |

Avoid using "mint stablecoin" as a blanket phrase. A stablecoin reward may be an
award, transfer, settlement, or withdrawal depending on the provider and asset.

## Provider Modes

Provider modes are defined in `backend/src/domain/stablecoin.rs`:

| Mode | Meaning |
|------|---------|
| `mock` | No real provider movement |
| `fake_value` | Deterministic fake provider evidence for local/CI demos |
| `sandbox` | Provider sandbox, not production value |
| `testnet` | Testnet movement only |
| `production` | Production provider mode, gated and not currently approved |

The safety service fails closed unless the matching feature flags and mode rules
allow the operation.

## Feature Flags

The runtime safety layer reads these environment flags:

| Variable | Purpose |
|----------|---------|
| `STABLECOIN_PROVIDER_MODE` | Provider mode: `mock`, `fake_value`, `sandbox`, `testnet`, or `production` |
| `STABLECOIN_CREDENTIAL_NAMESPACE` | Credential namespace |
| `STABLECOIN_REWARDS_ENABLED` | Enables stablecoin reward intent operations |
| `STABLECOIN_PROVIDER_SUBMIT_ENABLED` | Enables provider submission |
| `STABLECOIN_WITHDRAWALS_ENABLED` | Enables withdrawal operations |
| `STABLECOIN_PRODUCTION_ENABLED` | Enables production access checks |
| `STABLECOIN_FAKE_VALUE_CHAIN_IDS` | Allowed fake-value chain IDs |
| `STABLECOIN_SANDBOX_CHAIN_IDS` | Allowed sandbox chain IDs |
| `STABLECOIN_TESTNET_CHAIN_IDS` | Allowed testnet chain IDs |
| `STABLECOIN_PRODUCTION_CHAIN_IDS` | Allowed production chain IDs |
| `STABLECOIN_FAKE_SETTLEMENT_WORKER_ENABLED` | Starts the fake-value settlement worker |

Base chain IDs:

| Chain | ID |
|-------|----|
| Base mainnet | `8453` |
| Base Sepolia | `84532` |
| Local fake-value default | `31337` |

Base mainnet requires production mode and production readiness. Current docs
should not instruct developers to enable mainnet movement.

## Reward Lifecycle

```text
rule or game resolves
  -> RewardIntent is created
  -> ledger records reward authorization
  -> eligible intent is claimed by settlement worker
  -> fake provider returns deterministic evidence
  -> StablecoinTransfer is recorded
  -> provider event is stored
  -> ledger moves value from unsettled to settled
  -> member_asset_balances projection is updated
```

Phase 2A fake-value settlement uses this lifecycle without calling an external
provider.

## Balance Buckets

Stablecoin balances are projections from ledger entries. They must not be
updated as standalone counters without balanced ledger entries.

| Bucket | Meaning | Withdrawable now |
|--------|---------|------------------|
| `pending_authorization` | Reward produced but authorization is not complete | No |
| `available_unsettled` | Approved for display but backing is not finalized | No |
| `available_settled` | Finalized in the current mode | Not in Phase 2A |
| `withdrawal_held` | Withdrawal request locked funds | Not implemented for production |
| `compliance_hold` | Compliance or review hold | No |
| `fraud_hold` | Fraud hold | No |
| `withdrawn` | Funds left the platform/provider treasury | Not implemented for production |
| `reversed` | Reward was reversed | No |
| `abandoned` | Dormant balance pending legal handling | No |

In Phase 2A, `available_settled` still means fake-value or sandbox/testnet
finality only. It is not a production withdrawal claim.

## Data Model

Core tables:

| Table | Purpose |
|-------|---------|
| `reward_assets` | Asset registry with kind, chain, contract, decimals, provider, mode, status |
| `member_wallets` | Program/member wallet records and custody mode |
| `external_wallets` | Member external wallet addresses and verification/risk status |
| `compliance_decisions` | Allow, deny, or review decisions for money-moving subjects |
| `reward_intents` | Authorized reward records and lifecycle state |
| `withdrawal_intents` | Withdrawal lifecycle records |
| `stablecoin_transfers` | Provider/onchain transfer lifecycle records |
| `stablecoin_provider_events` | Provider event capture and deduplication |
| `ledger_accounts` | Finance ledger accounts |
| `ledger_entries` | Append-only balanced ledger entries |
| `member_asset_balances` | Rebuildable balance projection |
| `provider_asset_mappings` | Provider/product/value-mode/chain mapping |
| `stablecoin_settlement_runs` | Settlement batch audit rows |
| `stablecoin_settlement_run_items` | Per-intent settlement attempt rows |

## Safety Invariants

- No mainnet movement without production mode and production readiness.
- No production path may use deterministic placeholder wallets.
- All money-moving operations require idempotency keys.
- All money-moving operations require audit or ledger evidence.
- Amounts are stored in base units with explicit decimals.
- Stablecoin rewards must have reward lineage.
- Provider-specific details stay behind provider adapters.
- Failed provider movement must reconcile without double credit or double
  withdrawal.
- External withdrawal requires step-up and wallet risk checks before it can be
  approved in a future production flow.

## Developer Guidance

For local and CI demos:

- Use `fake_value` mode.
- Keep fake-value chain IDs restricted to local/test IDs.
- Enable only the flags required for the fake-value test path.
- Label all UI and docs examples as fake-value.

For production-facing docs:

- Do not claim production USDC movement exists.
- Do not claim member withdrawal exists.
- Do not claim member custody exists.
- Point readers to the current readiness gate before any provider or mainnet
  setup.

## Related Files

- `backend/src/domain/stablecoin.rs`
- `backend/src/services/stablecoin_provider.rs`
- `backend/src/services/stablecoin_safety.rs`
- `backend/src/services/stablecoin_settlement.rs`
- `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`
- `backend/migrations/20260425000002_create_stablecoin_phase2a_fake_settlement.sql`
- `docs/plans/2026-04-25-stablecoin-rewards-base-wallet-redemption-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2-base-usdc-sandbox-settlement-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2a-readiness-gate.md`

## Documentation TODO

- Add setup steps for fake-value settlement once operational env defaults are
  agreed.
- Add API/UI settlement detail docs when those surfaces are exposed.
- Add provider-mode troubleshooting.
- Add ledger examples.
- Add a production-readiness checklist only after the production gate exists.

---

# Reward Assets

Source: ../docs/stablecoin/reward-assets.md
URL: https://docs.rails.sh/reward-assets
Markdown: https://docs.rails.sh/markdown/reward-assets.md

# Stablecoin Reward Assets

Status: coming soon. Stablecoin reward assets are not enabled as a product
feature today. This is source-derived developer documentation of the internal
model and gates that exist in code so a future release can build on them;
Phase 2A fake-value settlement is implemented as non-production scaffolding,
and production stablecoin movement is gated and not approved.

## Current Boundary

rails models stablecoin rewards as `RewardAsset` records that can be
authorized by the rules and outcome system. In the current implementation, a
stablecoin reward can become a durable `RewardIntent` and, in fake-value mode,
can be settled into internal balance projections with deterministic provider
evidence — internal, non-production behavior only.

Do not treat the current stablecoin reward asset path as production USDC issuance, member custody, or a withdrawal right. Production Base mainnet value movement, real provider settlement, external wallet withdrawals, and production custody claims remain gated.

| Capability | Status | Notes |
|---|---|---|
| Reward asset registry | Implemented | `reward_assets` stores asset kind, code, chain, decimals, provider, mode, and status. |
| Asset-aware rule outcome | Implemented | Stablecoin rule outcomes are converted to `Outcome::AwardAsset`. |
| Reward intent creation | Implemented | `AwardAsset` creates `reward_intents` and balanced ledger entries. |
| Fake-value settlement | Implemented | Phase 2A worker settles eligible fake-value intents. |
| Sandbox/testnet provider adapter | Planned/gated | Coinbase CDP is the first candidate, pending a Rust REST feasibility spike. |
| Production USDC movement | Not approved | Requires production readiness, provider, legal/compliance, and operations gates. |
| External wallet withdrawal | Not approved | Schema exists, but production/member withdrawal flow is not implemented. |

## Reward Asset Model

`reward_assets` is the asset registry for points, stablecoins, badges, and offers. Stablecoin rows require a chain ID and decimals.

| Field | Meaning |
|---|---|
| `code` | Stable identifier used by rules and outcomes, such as a fake/test asset code. |
| `kind` | One of `points`, `stablecoin`, `badge`, or `offer`. |
| `chain_id` | Public chain ID for stablecoin assets. Local fake-value tests use `31337`; Base Sepolia is `84532`; Base mainnet is `8453`. |
| `contract_address` | Optional EVM token contract address. Must be a valid `0x` address when present. |
| `decimals` | Base-unit precision. Stablecoin assets must have decimals greater than zero. |
| `symbol` | Display symbol, for example `fUSDC` in fake-value tests. |
| `provider` | Provider namespace, such as `mock` or `fake_value`. |
| `provider_mode` | Safety mode: `mock`, `fake_value`, `sandbox`, `testnet`, or `production`. |
| `status` | `draft`, `active`, `paused`, or `archived`. Only active assets are awardable. |
| `metadata` | Optional policy metadata. Production flags are read from metadata but do not bypass runtime gates. |

Source references: `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`, `backend/src/domain/stablecoin.rs`.

## Program And Asset Relationship

Programs remain the tenant and policy boundary. Stablecoin reward authorization is scoped by `program_id`, `member_id`, and `asset_id`.

Important relationships:

| Relationship | Enforced by |
|---|---|
| `reward_intents.program_id -> loyalty_programs.id` | Database foreign key. |
| `reward_intents.asset_id -> reward_assets.id` | Database foreign key. |
| `reward_intents(program_id, idempotency_key)` | Unique key for replay protection. |
| `provider_asset_mappings(program_id, asset_id, provider, product, mode, chain)` | Active provider mapping for settlement eligibility. |
| Program production readiness | `loyalty_programs.metadata.stablecoinProductionEnabled` or `stablecoin_production_enabled`, plus runtime feature flags. |

An asset can be globally registered by `code`, but settlement eligibility is program-specific through provider mappings and compliance decisions. In Phase 2A, fake-value settlement requires an active `provider_asset_mappings` row for `fake_value`, `fake_value_ledger`, `fake_value`, and the asset chain ID.

## Modes

Provider mode is the most important documentation boundary.

| Mode | Current meaning |
|---|---|
| `mock` | Local authorization mode with no provider movement. Used by the current `MockStablecoinProvider`. |
| `fake_value` | Deterministic fake provider evidence and internal settlement lifecycle. No external API call and no real value. |
| `sandbox` | Planned provider sandbox mode. Not implemented as a real adapter today. |
| `testnet` | Planned testnet mode, with Base Sepolia as the intended first network. Not implemented as a real adapter today. |
| `production` | Production provider mode. Not approved and must fail closed without the production readiness gates. |

`fake_value` balances have no production value, no member custody, and no withdrawal right. `sandbox` or `testnet` balances, once implemented, will still be non-production and non-redeemable unless a later gate explicitly changes that product boundary.

## Award Flow

Rules and games should think in terms of an asset award, not provider movement.

```text
rule or game resolves
  -> Outcome::AwardAsset
  -> reward_assets lookup by code
  -> stablecoin safety guard
  -> reward_intents insert with status=authorized
  -> balance_bucket=pending_authorization
  -> budget reservation ledger entries
  -> reward intent ledger entries
  -> member_asset_balances pending projection
```

The outcome executor returns `asset_awarded` with details including:

| Response detail | Meaning |
|---|---|
| `assetCode` | Asset code used by the outcome. |
| `amountBaseUnits` | Award amount in base units. |
| `rewardIntentId` | Durable reward authorization ID. |
| `settlement` | Currently `internal_asset_authorization`. |
| `providerMovement` | `false` during authorization. |
| `withdrawalEligible` | `false` in the current implementation. |

Source references: `backend/src/domain/outcome.rs`, `backend/src/services/rule_engine.rs`, `backend/src/services/outcome_executor.rs`, `backend/tests/stablecoin_award_asset_integration.rs`.

## Fake-Value Versus Stablecoin

Use precise wording:

| Say | Avoid |
|---|---|
| "fake-value stablecoin reward" | "real USDC reward" |
| "authorized reward intent" | "minted stablecoin" |
| "settled in fake-value mode" | "paid out" |
| "member asset balance projection" | "member owns USDC" |
| "provider evidence" | "onchain proof" unless there is a real transaction |

The fake-value provider returns deterministic IDs, payload hashes, and fake transaction hashes. It does not create provider movement and does not sign or broadcast a blockchain transaction.

## Production Gates

Production access requires all relevant gates to pass. No single flag is sufficient.

| Gate | Current source |
|---|---|
| Runtime provider mode | `STABLECOIN_PROVIDER_MODE=production` only after approval. |
| Runtime feature flags | `STABLECOIN_REWARDS_ENABLED`, `STABLECOIN_PROVIDER_SUBMIT_ENABLED`, and for withdrawals, `STABLECOIN_WITHDRAWALS_ENABLED`. |
| Production readiness flag | `STABLECOIN_PRODUCTION_ENABLED=true`. |
| Program readiness | Program metadata must explicitly enable stablecoin production. |
| Asset approval | Asset metadata must mark production approval. |
| Chain allowlist | Base mainnet `8453` only in production mode with readiness enabled. |
| Provider adapter | Real adapter must be implemented and reviewed; none is production-approved now. |
| Operations/compliance | Legal, custody, reserve, reconciliation, incident, and secret-management gates must be documented before launch. |

Source references: `backend/src/services/stablecoin_safety.rs`, `docs/plans/2026-04-25-stablecoin-phase-2a-readiness-gate.md`.

## Developer Touchpoints

Existing surfaces that can touch reward assets indirectly:

| Touchpoint | Status | Notes |
|---|---|---|
| `Outcome::AwardAsset` | Implemented | Internal outcome type used by rule execution. |
| `loyaltyrails events send` | Implemented | Can trigger event-driven rules; no stablecoin-specific CLI command exists today. |
| `loyaltyrails program create --chain-id` | Implemented | Creates a program with a chain ID, defaulting to Base mainnet in the program API. This does not enable production stablecoin movement. |
| `POST /internal/v1/award` | Implemented for points | Awards points through the business-friendly API; not a stablecoin asset API. |
| `POST /internal/v1/mint` | Legacy token mint | Reserve-backed loyalty token path, not the stablecoin reward asset settlement path. |
| `/alp/v1/balance` and `/alp/v1/redeem` | Legacy/end-user token surface | Wallet-based points/token endpoints, not production stablecoin withdrawal. |

## Source References

- `docs/stablecoin-rewards.md`
- `docs/plans/2026-04-25-stablecoin-rewards-base-wallet-redemption-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2-base-usdc-sandbox-settlement-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2a-readiness-gate.md`
- `backend/src/domain/stablecoin.rs`
- `backend/src/domain/outcome.rs`
- `backend/src/services/outcome_executor.rs`
- `backend/src/services/stablecoin_safety.rs`
- `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`
- `backend/migrations/20260425000002_create_stablecoin_phase2a_fake_settlement.sql`
- `backend/tests/stablecoin_award_asset_integration.rs`

---

# Issuance And Settlement

Source: ../docs/stablecoin/issuance-settlement.md
URL: https://docs.rails.sh/issuance-settlement
Markdown: https://docs.rails.sh/markdown/issuance-settlement.md

# Stablecoin Issuance And Settlement

Status: coming soon. Stablecoin issuance and settlement are not enabled as a
product feature today — no reward is settled into real value and no funds
move. This is source-derived developer documentation of the internal design;
Phase 2A fake-value settlement is implemented as non-production scaffolding,
and production issuance, redemption, withdrawal, and provider movement remain
gated and not approved.

## Current Boundary

rails will separate reward authorization from settlement. A rule or game can
authorize an asset reward today by creating an internal `RewardIntent` record
— an internal, non-production step recorded ahead of settlement. Settlement
is intended to be a later lifecycle stage that records provider evidence,
balanced ledger movement, and member asset balance projections.

Today, only fake-value stablecoin settlement is implemented, and only for
internal testing. It creates deterministic provider evidence and internal
ledger/projection updates without any external provider API call or
blockchain transaction — no real settlement happens.

| Capability | Status |
|---|---|
| Reward intent authorization | Implemented |
| Budget reservation ledger entries | Implemented |
| Fake-value settlement worker | Implemented, disabled by default |
| Fake provider evidence | Implemented |
| Settlement run audit rows | Implemented |
| Provider event dedupe | Implemented |
| Real Coinbase CDP or Circle settlement | Planned/gated |
| Base Sepolia testnet movement | Planned/gated |
| Base mainnet production movement | Not approved |
| External wallet withdrawal | Not approved |

## Terminology

| Term | Meaning in rails |
|---|---|
| Issuance | Product-level act of granting a member an asset reward. In code this is currently reward authorization, not stablecoin minting. |
| `RewardIntent` | Durable record that a member earned an asset reward from a rule, game, API, or manual adjustment source. |
| Settlement | Movement from authorization to finalized internal asset state, with provider evidence and ledger entries. |
| Redemption | Spending, burning, cashing out, or consuming a reward. Existing token redemption is not stablecoin withdrawal. |
| Withdrawal | Future movement of stablecoin from platform/provider-controlled backing to an external wallet. Schema exists; product flow is not approved. |
| Provider evidence | Provider transfer ID, event ID, payload hash, status, fake or real transaction data, and reconciliation metadata. |

Avoid using "mint stablecoin" as the generic term. USDC settlement is usually an award, transfer, or withdrawal. The current smart contract `LoyaltyToken` is a reserve-backed loyalty token and is not the same as production USDC movement.

## Lifecycle

```text
AwardAsset outcome
  -> reward_intents.status = authorized
  -> reward_intents.balance_bucket = pending_authorization
  -> member_asset_balances.pending_authorization increases
  -> settlement worker claims eligible fake-value intent
  -> reward_intents.status = settlement_pending
  -> reward_intents.balance_bucket = available_unsettled
  -> stablecoin_transfers row is inserted
  -> fake provider submission is recorded
  -> stablecoin_provider_events row is inserted or deduped
  -> settlement ledger entries are posted
  -> reward_intents.status = settled
  -> reward_intents.balance_bucket = available_settled
  -> member_asset_balances.available_settled increases
```

In Phase 2A, `available_settled` means fake-value finality only. It is not production value, not externally withdrawable, and not a member custody claim.

## State Matrix

| Step | `reward_intents.status` | `balance_bucket` | Transfer status | Member balance effect |
|---|---|---|---|---|
| Authorization | `authorized` | `pending_authorization` | None | Increase pending authorization. |
| Worker claim | `settlement_pending` | `available_unsettled` | `created` or submitted path | Move pending to unsettled. |
| Provider evidence | `settlement_pending` | `available_unsettled` | `submitted`, `confirmed`, `finalized`, or `reconciled` | No duplicate member credit. |
| Settlement finality | `settled` | `available_settled` | `finalized` or `reconciled` | Move unsettled to settled. |
| Replay | `settled` | `available_settled` | Existing final transfer | Return existing transfer without duplicate ledger effects. |
| Conflict | `requires_review` | Usually `compliance_hold` | `requires_review` | Move to hold or rebuild projection. |

Source references: `backend/src/services/stablecoin_settlement.rs`, `backend/tests/stablecoin_phase2a_fake_settlement_integration.rs`.

## Idempotency

Idempotency is required at every money-moving boundary.

| Boundary | Idempotency mechanism |
|---|---|
| Reward authorization | `reward_intents(program_id, idempotency_key)`; generated from transaction reference, rule ID, and asset code. |
| Stablecoin transfer | `stablecoin_transfers(program_id, idempotency_key)` and unique final settlement per reward intent. |
| Provider transfer | Unique `(provider, provider_transfer_id)` when present. |
| Provider event | Unique `(provider, event_id)` or payload-hash dedupe for event payloads without an event ID. |
| Ledger posting | Unique stablecoin transfer/account posting guard for transfer-source ledger entries. |
| Settlement runs | Attempt numbers and active run-item constraints prevent concurrent duplicate active claims. |

If a replay payload does not match the persisted transfer, provider event, or ledger effect, the implementation moves the reward intent or transfer to `requires_review` instead of silently succeeding.

## Sandbox Versus Production

| Mode | External provider calls | Real value | Current implementation |
|---|---:|---:|---|
| `mock` | No | No | Authorization-only mock provider. |
| `fake_value` | No | No | Implemented fake settlement path. |
| `sandbox` | Planned | No production value | Not implemented as a provider adapter. |
| `testnet` | Planned | No production value | CDP Base Sepolia candidate is blocked pending gate review. |
| `production` | Gated | Yes | Not approved. |

Base mainnet chain ID `8453` must fail closed unless provider mode is `production`, production readiness is enabled, program/asset production gates pass, and an approved provider adapter exists.

## Reserves And Liability

The current stablecoin reward asset model uses append-only finance ledger primitives and rebuildable projections:

| Table | Purpose |
|---|---|
| `ledger_accounts` | Program/asset accounts with class, normal balance, and optional balance bucket. |
| `ledger_entries` | Append-only balanced entries sourced from reward intents, budget reservations, stablecoin transfers, and other events. |
| `member_asset_balances` | Rebuildable member projection by asset and bucket. |
| `reward_intents` | Reward authorization and lifecycle state. |
| `stablecoin_transfers` | Provider or fake-provider settlement/withdrawal movement records. |

The implemented fake-value path posts budget reservation entries, reward intent entries, and settlement entries. It does not prove production reserve custody or bank/issuer backing.

The older `LoyaltyToken` contract has reserve-ratio logic and reserve-token deposits, but that contract is a reserve-backed loyalty token path. It should not be described as the production stablecoin settlement rail until legal, reserve, custody, transferability, provider, and redemption requirements are satisfied.

## Operational Safety

Safety rules that should appear in operator runbooks and developer docs:

| Rule | Current enforcement |
|---|---|
| Rewards disabled by default | `STABLECOIN_REWARDS_ENABLED` must be true. |
| Provider submit disabled by default | `STABLECOIN_PROVIDER_SUBMIT_ENABLED` must be true for settlement. |
| Withdrawals disabled by default | `STABLECOIN_WITHDRAWALS_ENABLED` must be true, but production withdrawals are not implemented. |
| Production disabled by default | `STABLECOIN_PRODUCTION_ENABLED` must be true and is not enough alone. |
| Fake-value worker disabled by default | `STABLECOIN_FAKE_SETTLEMENT_WORKER_ENABLED` controls worker startup. |
| Mainnet blocked outside production | Safety service rejects Base mainnet in non-production mode. |
| Compliance allow required for fake settlement | Worker selects only intents with current fake-value `allow` decisions. |
| Provider mapping required | Worker requires an active fake-value provider asset mapping. |
| Review on mismatch | Idempotency and evidence conflicts move records to review/hold. |

## Developer Touchpoints

| Touchpoint | Use |
|---|---|
| `Outcome::AwardAsset` | Internal source for asset-aware reward authorization. |
| `StablecoinSettlementService::settle_fake_value_reward_intent` | Direct service entry point used by integration tests and worker orchestration. |
| `StablecoinSettlementWorker` | Polls eligible fake-value reward intents when enabled. |
| `FakeStablecoinProvider` | Produces deterministic fake evidence and fake tx hashes. |
| `loyaltyrails events send` | CLI route to send events that may trigger rules. Not stablecoin-specific. |
| `loyaltyrails program status` | CLI route to inspect program status. It does not expose stablecoin settlement detail today. |
| `GET /internal/v1/programs/:program_id/liability` | Existing liability forecast endpoint; not a stablecoin production reserve proof. |

No public API currently exposes full stablecoin reward asset creation, settlement runs, withdrawal requests, or provider proof bundles as stable docs. The database/service path exists ahead of the external product API.

## Regulatory And Product Boundaries

This page is product and engineering documentation, not legal advice.

Before any production stablecoin movement, rails needs approved provider contracts, custody classification, reserve/liability policy, sanctions/KYT/geofence policy, incident response, reconciliation operations, secrets rotation, and customer-facing terms. The current repository records the technical gates but does not constitute production launch approval.

## Source References

- `docs/stablecoin-rewards.md`
- `docs/plans/2026-04-25-stablecoin-phase-2-base-usdc-sandbox-settlement-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2a-readiness-gate.md`
- `docs/plans/2026-04-25-stablecoin-phase-2-provider-decision-coinbase-cdp-first.md`
- `backend/src/services/stablecoin_settlement.rs`
- `backend/src/services/stablecoin_provider.rs`
- `backend/src/services/stablecoin_safety.rs`
- `backend/src/services/outcome_executor.rs`
- `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`
- `backend/migrations/20260425000002_create_stablecoin_phase2a_fake_settlement.sql`
- `backend/tests/stablecoin_phase2a_fake_settlement_integration.rs`
- `contracts/src/core/LoyaltyToken.sol`

---

# Wallets And Custody

Source: ../docs/stablecoin/wallets-custody.md
URL: https://docs.rails.sh/wallets-custody
Markdown: https://docs.rails.sh/markdown/wallets-custody.md

# Wallets And Custody

Status: coming soon. Stablecoin member wallets and custody are not enabled as
a product feature today — rails does not currently provision a wallet or hold
custody for any member. This is source-derived developer documentation of the
wallet schemas and deterministic member wallet identifiers that already exist
in code; production Privy wallet provisioning, production member custody, and
external wallet withdrawals remain planned and are not approved.

## Current Boundary

rails has several wallet-like concepts. They are not interchangeable, and
none of them today grants a member a production wallet or custody right.

| Concept | Current status | Custody claim |
|---|---|---|
| Deterministic member wallet address | Implemented | Identifier for member balance and token paths; not proof of a provisioned wallet or private key custody. |
| `member_wallets` table | Implemented schema | Records custody mode and provider wallet metadata; not proof that production wallets are provisioned. |
| `external_wallets` table | Implemented schema | Records member-supplied destination addresses and verification/risk state; withdrawal flow not approved. |
| Privy/ERC-4337 member wallet UX | Planned | Product direction only; no production integration in current backend. |
| Developer/provider-controlled test wallets | Planned for Phase 2B | Testnet-only candidate, not member custody. |
| Production external withdrawal | Not approved | Requires separate product, legal, compliance, and operations gates. |

Do not describe current fake-value or test records as member-held stablecoin. In Phase 2A, stablecoin balances are internal projections.

## Wallet Model

| Model | Meaning | Implemented now |
|---|---|---|
| `internal_ledger` | Member has an internal asset balance tracked by rails. No blockchain private key is implied. | Schema and fake-value balance projection exist. |
| `user_controlled` | Member controls the wallet/signer. | Schema only; production flow not implemented. |
| `developer_controlled` | rails or developer controls a test/operational wallet. | Planned for provider testnet work; no approved production custody claim. |
| `provider_controlled` | Provider controls the wallet or clearing account. | Schema only. |
| `external` | Member-supplied destination address outside rails. | Schema only; withdrawal flow not approved. |

Source references: `backend/src/domain/stablecoin.rs`, `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`.

## Member Identity And Wallet Address

Current member records store a `wallet_address`. For API-created members and awards by external ID, the backend derives a deterministic EVM-looking address from:

```text
sha256("{external_id_type}:{external_id}") first 20 bytes
```

The TypeScript SDK mirrors this behavior for customer-ID balance lookups. The backend comment says production would call Privy to create an embedded wallet, but that production integration does not exist today.

Implications:

| Implication | Documentation rule |
|---|---|
| Deterministic address is stable for the same ID namespace/value. | Safe to describe as a member identifier. |
| It is not created by Privy today. | Do not call it a Privy wallet. |
| No private key is generated or stored by this path. | Do not claim member self-custody or platform custody from this address alone. |
| Different ID types produce different addresses for the same external ID. | Include external ID type in integration docs. |

Source references: `backend/src/api/award.rs`, `backend/src/api/members.rs`, `packages/sdk/src/client.ts`.

## Privy And ERC-4337 Assumptions

Planning docs identify Privy and ERC-4337 account abstraction as the intended member wallet direction. The current source does not include a production Privy integration or Privy-backed member wallet provisioning.

Current accurate wording:

| Area | Accurate wording |
|---|---|
| Product direction | "Privy/ERC-4337 is the planned member wallet UX direction." |
| Backend implementation | "The current backend uses JWT wallet claims for `/alp/v1/*` and deterministic wallet identifiers for member mapping." |
| Stablecoin Phase 2A | "No member wallet custody is created by fake-value settlement." |
| Phase 2B CDP candidate | "CDP wallets/accounts, if approved, are developer-controlled operational test wallets, not member-controlled wallets." |
| Production | "Production custody classification is gated and requires legal, provider, security, and operations approval." |

Avoid saying that rails currently provides non-custodial Privy wallets for stablecoin rewards. That is still planned and not yet enabled.

## Authentication Boundary

The `/alp/v1/*` surface uses JWT authentication. The current JWT claims include:

| Claim | Use |
|---|---|
| `sub` | End-user subject ID. |
| `wallet` | Wallet address inserted into `AuthenticatedUser`. |
| `exp` and `iat` | Token lifetime fields validated by the JWT library. |

The redemption handler checks that the request wallet matches the wallet claim. It currently trusts JWT authentication and has a TODO for EIP-712 signature verification. This route belongs to the legacy/end-user token surface and must not be documented as a production stablecoin withdrawal route.

Source references: `backend/src/api/middleware/jwt.rs`, `backend/src/api/extractors.rs`, `backend/src/api/redemption.rs`, `docs/api-reference.md`.

## External Wallets

`external_wallets` stores addresses supplied as withdrawal destinations.

| Field | Meaning |
|---|---|
| `program_id` and `member_id` | Tenant and member ownership scope. |
| `address` | EVM destination address. |
| `chain_id` | Public chain ID for the address. |
| `verification_status` | `unverified`, `pending`, `verified`, `rejected`, or `revoked`. |
| `risk_status` | `unknown`, `pending`, `clear`, `review`, or `blocked`. |
| `last_screened_at` | Last risk-screening timestamp. |
| `metadata` | Provider or policy details. |

The table supports future withdrawal controls, but no production external-wallet withdrawal path is approved. Planned requirements include step-up auth, ownership verification where possible, sanctions/KYT/geofence checks, velocity limits, provider submission controls, and irreversible-transfer warnings.

## Key And Secret Boundaries

Current source and plans define these boundaries:

| Secret/key material | Boundary |
|---|---|
| Member deterministic wallet address | Not secret; do not treat as a private key or signer. |
| JWT signing secret | Backend auth secret; never expose to frontend or logs. |
| API keys and operator CLI tokens | Server/operator credentials; use existing auth and audit controls. |
| CDP API key secret and wallet secret | Planned high-risk provider secrets; no backend integration today. Must never be logged, persisted in provider evidence, or exposed to API responses. |
| Production private keys or treasury signers | Not implemented. Production approach requires separate review. |

Production secrets are expected to live in approved secret stores, not committed config. Security docs also call out that traces may contain wallet addresses and must never contain private keys or API key values.

Source references: `SECURITY.md`, `docs/plans/2026-04-25-stablecoin-phase-2-provider-decision-coinbase-cdp-first.md`.

## Custody Matrix

| Account or balance | Control today | Production caveat |
|---|---|---|
| Member asset balance projection | rails database/ledger | Internal accounting view only in Phase 2A. |
| Deterministic member wallet address | Derived identifier | Not a provisioned wallet. |
| `member_wallets` row | Database record | Custody mode is a classification field, not proof of legal custody. |
| `external_wallets` row | Member-supplied address record | Transfers to it are not enabled by current product. |
| Fake provider transfer | Deterministic fake evidence | No external movement. |
| CDP test wallet candidate | Planned developer-controlled test wallet | Blocked pending Phase 2B gate and feasibility spike. |
| Privy embedded wallet | Planned member wallet UX | Not implemented in production source. |
| Program treasury wallet | Planned provider/treasury model | Requires legal and operations approval before production. |

## Regulatory And Operational Caveats

This page is not legal advice. It documents current product and engineering boundaries.

Before production stablecoin rewards can imply custody, redemption, or withdrawal rights, rails needs approved custody classification, provider contracts, member terms, treasury and reserve operations, sanctions/KYT/geofence policy, incident response, support playbooks, reconciliation procedures, and secret-rotation controls.

## Developer Touchpoints

| Touchpoint | Use |
|---|---|
| `POST /internal/v1/members` | Creates member mapping with deterministic wallet address. |
| `POST /internal/v1/award` | Awards points and may create member mapping by external ID. Not stablecoin custody. |
| `GET /alp/v1/balance?wallet=...` | JWT-protected wallet balance lookup for existing wallet surface. |
| `POST /alp/v1/redeem` | Legacy token redemption path; not production stablecoin withdrawal. |
| `loyaltyrails members balance` | CLI balance lookup by external ID. |
| `member_wallets` and `external_wallets` tables | Future stablecoin wallet/custody records. |

## Source References

- `docs/stablecoin-rewards.md`
- `docs/plans/2026-04-25-stablecoin-rewards-base-wallet-redemption-plan.md`
- `docs/plans/2026-04-25-stablecoin-phase-2-provider-decision-coinbase-cdp-first.md`
- `docs/plans/2026-04-18-authentication-subscription-implementation.md`
- `backend/migrations/20260425000001_create_stablecoin_phase1_foundation.sql`
- `backend/src/domain/stablecoin.rs`
- `backend/src/api/award.rs`
- `backend/src/api/members.rs`
- `backend/src/api/middleware/jwt.rs`
- `backend/src/api/extractors.rs`
- `backend/src/api/redemption.rs`
- `packages/sdk/src/client.ts`
- `SECURITY.md`

---

# Agentic Docs

Source: ../docs/agentic-docs.md
URL: https://docs.rails.sh/agentic-docs
Markdown: https://docs.rails.sh/markdown/agentic-docs.md

# Agentic-First Documentation

Status: source-aligned. The docs-site build (`pnpm docs:generate` +
`pnpm docs:build`, wired into `pnpm docs:check`) actually produces the
per-page Markdown, `llms.txt`, `llms-full.txt`, and OpenAPI artifacts
described below at `https://docs.rails.sh`. Sections still marked aspirational
below are not built yet — do not claim them as available.

## Principle

rails documentation is built for humans, coding agents, and runtime
assistants from the same source. Every canonical page in
`docs-site/content.manifest.json` renders to a human-facing page and to a
raw Markdown file from the identical source file — there is no separate
"agent copy" that can drift from what a person reads.

## Required Artifacts

| Artifact | Audience | Status | Source |
|----------|----------|--------|--------|
| Rendered docs site | Humans | Implemented | Markdown in `docs/`, served by `docs-site/` |
| Raw Markdown pages (`/markdown/<slug>.md`) | Humans and agents | Implemented | `docs-site/scripts/sync-agent-docs.mjs` copies each manifest source verbatim into `docs-site/public/markdown/` |
| Per-page Markdown / Copy / Download controls | Humans | Implemented | `docs-site/src/App.tsx` |
| `llms.txt` | Coding agents | Implemented | Generated sitemap + one-line description per manifest page |
| `llms-full.txt` | Coding agents | Implemented | Full Markdown concatenation with source paths and per-page URLs |
| `docs-index.json` | Agents | Implemented | Structured `{slug, title, url, markdown}` per page |
| `sitemap.xml` | Search, agents | Implemented | Generated alongside the above |
| `openapi.json` | Developers and agents | Implemented | Copy of `api-contracts/loyaltyrails-cli.v1.openapi.json` — this is the CLI contract, not a full backend API spec |
| `cli-reference.md` | Developers and agents | Implemented, generated | `docs/reference/cli.md`, generated from the CLI's command definitions |
| `agent-tools-reference.md` | Developers and agents | Implemented, generated | `docs/reference/agent-tools.md`, generated from `agent/src/agent/*.py` — do not hand-edit |
| `sdk-components.md` / `sdk-reference.md` | Developers and agents | Migration-status pages, not generated | `docs/sdk-components.md`, `docs/sdk-reference.md` |
| Full docs zip | Agents, solution engineers | Aspirational — not built | — |
| Recipe manifests | Developers and agents | Implemented (CLI-side, not docs-site) | `.loyaltyrails/manifest.json` schema, written by `loyaltyrails init` |

## Page Frontmatter

Manifest entries (`docs-site/content.manifest.json`) carry `slug`, `title`,
`section`, `description`, `source`, and `status` today — there is no
per-page YAML frontmatter block inside the Markdown files themselves. If
that changes, this section should describe the actual shape rather than a
proposed one.

## Agent Blocks

Add compact agent blocks to task pages when a page's instructions are meant
to be pasted directly into a coding agent's context. These should be useful
copied into Claude Code, Copilot, Codex, or another coding agent without
edits.

Example:

````markdown
### Agent Context

Use this when asking an agent to wire a Shopify Hydrogen storefront:

```
Follow the rails Hydrogen recipe. Use a program-scoped, non-admin
integration key. Keep `LOYALTYRAILS_API_KEY`, `LOYALTYRAILS_PROGRAM_ID`,
and `LOYALTYRAILS_API_URL` server-side. Run `loyaltyrails integrate
hydrogen --dry-run` before writing files.
```
````

Agent blocks must be specific enough to prevent unsafe shortcuts — never
tell an agent to skip `--dry-run`/`--preview` or to commit a raw credential
to a file that isn't gitignored.

## Search And Retrieval

The rendered docs site indexes titles, headings, and manifest descriptions.
`llms.txt`, `llms-full.txt`, and `docs-index.json` give an agent a stable
way to enumerate every page without crawling rendered HTML. There is no
separate full-text/code-snippet search index today; an agent that needs to
find a specific route, CLI command, or env var should fetch `llms-full.txt`
or the relevant page's raw Markdown and search that.

## Source-Derived Reference Pipeline

What `pnpm docs:generate` + `pnpm docs:build` actually do, in order:

1. `docs-site/scripts/generate-source-references.mjs` extracts the CLI
   command tree and the agent's `@tool` definitions (from
   `agent/src/agent/*.py`) into `docs/reference/cli.md` and
   `docs/reference/agent-tools.md`.
2. `docs-site/scripts/sync-agent-docs.mjs` copies every manifest source file
   into `docs-site/public/markdown/`, copies the CLI OpenAPI contract to
   `openapi.json`, and writes `llms.txt`, `llms-full.txt`, `docs-index.json`,
   and `sitemap.xml`.
3. `pnpm docs:build` builds the Vite site itself.
4. `pnpm docs:check` additionally runs a docs-bundle check, a link checker,
   a rendered-link checker, and the CLI OpenAPI contract-drift check
   (`contract:check`) before any of the above is trusted.

Not yet built: SDK component page generation, SDK API-client reference
generation, and a full-backend OpenAPI spec (`openapi.json` today is the
narrower CLI contract copy, not every backend route).

## Safety Labels

Use explicit labels on pages, examples, and agent actions:

| Label | Meaning |
|-------|---------|
| Read-only | Does not write project files or mutate rails state |
| Writes local files | Creates or updates files in the host app |
| Mutates platform state | Changes programs, keys, rules, campaigns, experiences, or content |
| Requires approval | Agent or UI pauses for human approval before applying |
| Requires operator token | Uses control-plane operator auth |
| Requires integration key | Uses program-scoped API key in server code |
| Server-only | Must not run in browser/client code |
| Fake-value only | Does not represent real stablecoin movement |
| Production gated | Disabled by default and requires separate readiness approval |

## `llms.txt` Shape (Actual)

Generated by `docs-site/scripts/sync-agent-docs.mjs`, one line per manifest
page plus the OpenAPI link:

```text
# rails docs

> Developer and agent documentation for the rails platform.

## Documentation

- [Overview](https://docs.rails.sh/markdown/overview.md): ...
- [Agent Guide](https://docs.rails.sh/markdown/agent-guide.md): ...
...

## OpenAPI Specs

- [rails CLI OpenAPI](https://docs.rails.sh/openapi.json)
```

## Documentation CI

Enforced today via `pnpm docs:check`:

- Docs bundle check (`check-docs-bundle.mjs`).
- Markdown link check, source and rendered (`check-docs-links.mjs`,
  `check-docs-rendered-links.mjs`).
- Full docs-site build (`docs:build`) as a build-correctness gate.
- CLI OpenAPI contract-drift check (`contract:check`).

Not yet built as CI gates: frontmatter validation (there is no per-page
frontmatter to validate — see above), CLI help snapshot drift, SDK snippet
typecheck, generated-recipe snapshot check, secret scanning of docs
examples, and a forbidden-wording check for stablecoin production claims.
Treat those as manual review items until they're automated.

## Migration Notes From TOLDs

The old `~/Development/tolds` docs include useful patterns, especially:

- Component docs with prop tables.
- Framework guides.
- Adapter guides.
- Capabilities matrices.
- Accessibility docs.
- Troubleshooting docs.
- Offline/browser support notes.

Before publishing them under rails:

- Rename package names and concepts; use "rails" (lowercase), never
  "Loyalty Rails" with a space.
- Verify code examples against current packages.
- Preserve the backend-agnostic component contract: components receive
  props, while recipes and adapters fetch data.
- Remove TOLDs-only UI claims that no longer match the platform.
- Keep canonical mapping and capability descriptors, but update them for
  rails integrations and recipes.

---