# Mandates — spoke context

The user wants to set up a recurring payment authorization — a "mandate" — so Whoois can autonomously execute purchases on their behalf within rules they set.

If you haven't already, fetch `https://poc.whoois.app/whoois-context.md` for the root primer.

---

## PR-C status: real creation flow (execution deferred)

As of PR-C (2026-05-29), mandate creation is real — the user can author and authorize a mandate that persists in the mandates store. **Autonomous execution** (the engine that triggers matching purchases when conditions fire) is explicitly deferred. POC: mandate persists, but Whoois doesn't actually charge anyone on a schedule.

---

## Trigger phrases

- "Set up auto-pay"
- "Create a recurring payment"
- "Auto-buy {item} every {period}"
- "Subscribe to {merchant}"
- "Auto-refill my {thing}"
- "Set up a mandate"
- "Automate buying {X}"

---

## Tools to call

**`whoois_mandate_open`** — LLM-visible. No arguments. Opens the mandate creation iframe with the mishopping merchant catalog populating the merchant dropdown.

The iframe shows:
- Merchant picker (currently 5 mishopping merchants)
- Frequency dropdown (weekly / monthly / quarterly / on-demand)
- Per-execution amount cap (USD input)
- Cumulative cap (USD input)
- Live mandate-summary card
- "Create with passkey" CTA

**`whoois_mandate_commit`** — visibility:app (iframe-only). Fires when user taps the CTA. Persists the mandate record to DDB with `status: 'active'`.

Arguments (iframe-supplied):
- `merchant_id` (UUID)
- `frequency` (`weekly` | `monthly` | `quarterly` | `on-demand`)
- `amount_cap_cents` (integer)
- `total_cap_cents` (integer)

---

## What a mandate is (conceptually)

A user-authorized rule that lets Whoois execute purchases without per-transaction passkey confirmation, within constraints the user defines:

- **Merchant** — single merchant in POC; multi-merchant orchestration is deferred
- **Frequency** — weekly / monthly / quarterly / on-demand
- **Amount cap** — max per execution
- **Total cap** — max cumulative spend
- **Expiry** — 1 year out by default
- **Status** — active / paused / revoked (paused + revoked transitions are post-POC)

Mandates are the user's explicit consent to delegate transactional authority within bounds.

---

## Typical flow

1. User: "set up auto-pay for my favorite coffee at Demo Coffee Co"
2. Call `whoois_mandate_open()` — iframe opens with merchant dropdown
3. User picks Demo Coffee Co + monthly + $50 per execution + $600 cumulative
4. User taps "Create with passkey" → iframe calls `whoois_mandate_commit`
5. Passkey ceremony fires
6. Mandate persists to DDB; iframe transitions to success state
7. Tell the user: *"Mandate active. Whoois may charge up to $50 every month at Demo Coffee Co, up to $600 total. Note that autonomous execution isn't wired in the POC — the mandate is stored but won't fire automatically."*

---

## POC honesty

Be upfront with the user about the POC scope: the mandate persists but **Whoois won't actually execute it autonomously**. They've authorized the rule, but no recurring charges will fire until the execution engine ships (post-POC). This is `PUNCH-MANDATE-EXECUTION-ENGINE-DEFERRED`.

---

## Cross-references

- For one-off bill payments (not autonomous): `https://poc.whoois.app/context/billpay.md`
- For viewing receipts after autonomous execution (when shipped): `https://poc.whoois.app/context/mitrail.md`
- For listing the user's mandates (future tool, not yet shipped): coming with `whoois_mandates_view`

---

*This spoke is fetched from `https://poc.whoois.app/context/mandates.md`. PR-C (2026-05-29) transitioned mandate creation from preview to real flow; execution engine deferred.*