Playbooks

A playbook is a versioned recipe (orishare.playbook/v1) that installs a complete mechanic setup: programs, rules, currencies, event definitions and display copy, with a few typed parameters. Installing one never writes directly. Every install, upgrade and uninstall is a preview that returns a change set; a signed-in person reviews it in the dashboard and commits it. An agent can prepare the preview; it cannot confirm it.

The catalogue

Read the live list and each manifest's parameters, bounds and required events with GET /v1/playbooks and GET /v1/playbooks/{id}.

Install

POST /v1/playbook_previews with { "playbook_id", "version", "parameters" } returns either a change set (source playbook) or a structured refusal (409 playbook_refused). Parameters are typed and bounds-checked; they fill whole values only, never parts of keys or expressions. The body may also carry collisions and prefix (below) and holdout: { "enabled": true }, which is accepted only when the manifest offers a holdout (holdout.offered), is off by default and is recorded on the installation.

A playbook names mechanics by their customer-facing words; the plan shows program kinds. A levels playbook creates a tier program (levels are XP tiers), so levels_and_badges plans a tier program player_levels next to its badge program. A playbook whose programs are fed by rules (streaks, badges, levels) also creates those rules, since such a program is never fed by its qualification.sources alone.

Refusals name what to fix:

• Missing or weaker events. Each required event has a minimum trust. A missing definition is created as server-only (client_allowed: false) with that trust. An existing definition that is weaker, or client-allowed where trusted evidence is required, is refused; the operator changes it separately (PATCH /v1/event_definitions/{id}) with an explicit acknowledgement. A playbook never weakens trust. The one exception is the browser-fed event_source: client choice below, which creates its events client-allowed and flags them for the reviewer.
• Key collisions. An existing resource with the same key is refused unless the preview says how to resolve it per key in collisions (adopt or transfer), or installs everything under a prefix.

Then a signed-in owner or admin commits the change set in the dashboard (Operations, Changes, which sends POST /v1/change_set_commits), acknowledging any flags; this writes the installation record in the same transaction. A PAT or key is refused with 403 confirmation_required. The change set expires 24 hours after the preview (409 change_set_expired), and a configuration change in between makes it 409 preview_stale; in both cases preview again. Replaying a commit creates one installation. List installs with GET /v1/playbook_installations; each owned resource reports drift: clean, edited (changed since install) or missing.

Event source: server or client

daily_habit, levels_and_badges and season_ladder take an event_source parameter that says who reports their activity events:

• server (the default): only your backend with a secret key. The install is exactly what these playbooks have always installed.
• client: a signed-in customer session in the browser or app may report the events too, with the publishable key and POST /v1/customer/events. This is for apps with no backend (for example Firebase or Supabase apps).

{
  "playbook_id": "levels_and_badges",
  "version": "1.0.0",
  "parameters": { "event_source": "client", "client_activities_per_day": 50 }
}

With client, the install changes in these ways:

• The playbook's events are created client_allowed: true with minimum_trust: customer_claim. Anonymous sessions do not count (their events are refused with trust_insufficient). The change set carries one trust flag per such event, which the reviewer acknowledges at commit. An existing definition of the event must already be client-allowed at customer_claim, or the install is refused; a playbook never changes the trust of an event that exists.
• Every program's trust policy becomes { "minimum_trust": "customer_claim", "allowed_sources": ["publishable_event", "secret_key_event"], "on_insufficient": "ignore" } with recognition caps, and every rule gets the floor trust: { "minimum": "customer_claim" }. Events from your backend are never capped.
• Caps, each a parameter with a safe default:

• Spendable value: daily_habit keeps its milestone coins in client mode. Each coin award states its value and the program carries a per-customer daily liability cap on the coins, so it publishes with no extra step and browser sessions can never create more than the cap. Keep client_coins_per_day at or above the largest milestone reward. Experience in levels_and_badges is not spendable.
• season_ladder in client mode is recognition only: a leaderboard with prizes requires merchant_asserted evidence, so the client ladder has no prize bands and creates no gems currency. A rule (leaderboard.contribute) feeds it from match.completed; in server mode the ladder keeps its prizes and is fed by POST /v1/leaderboards/{id}/contributions.

What stays server-only in every mode: purchases, refunds and other money events, referral qualification, and prizes.

Upgrade

POST /v1/playbook_upgrade_previews plans a three-way upgrade from the installed version, your current resources and the new version. Clean resources upgrade; edited or missing ones come back as conflicts that the next preview resolves in its body. The result is again a change set to review.

Uninstall and what customers keep

POST /v1/playbook_uninstall_previews returns a change set that archives, revokes, disables or stops what the installation owns and releases ownership. New earning stops. Nothing customer-owned is removed: balances, badge grants, streak and quest history, redemptions and the ledger stay, and existing liabilities (issued rewards, pending settlements) are honored.

Verification scenarios ship with every manifest: after install in the test environment, send the listed events and compare the customer state the manifest expects.