# Fanful developer docs

Fanful developer docs are for human developers and AI agents building against Fanful's public agent surface. The canonical browser entrypoint is https://docs.fanful.net; the same content is available at https://fanful.net/docs.

## Start here

### Give any agent one setup URL
- Status: Available now
- Audience: AI coding agents
- Link: https://fanful.net/agent-setup
- Use the Cloudflare-style setup prompt to point Codex, Claude, ChatGPT, Cursor, or another agent at Fanful MCP, API docs, CLI, skills, recipes, and safety rules.

### Discover Fanful as an agent
- Status: Available now
- Audience: AI agents
- Link: https://fanful.net/llms.txt
- Start from llms.txt, the agent overview, and public manifests. Use server-side contracts instead of scraping the web UI.

### Connect an MCP client
- Status: Available now
- Audience: MCP clients
- Link: https://fanful.net/mcp
- Use the public Streamable HTTP endpoint for network clients or the local stdio server while developing.

### Use starter examples
- Status: Available now
- Audience: External agents
- Link: https://fanful.net/agent-docs/fanful-agent-sdk-starter.md
- Copy the provider-neutral TypeScript starter or no-SDK HTTP fallback to discover manifests, handle 401/403, and validate confirmation envelopes.

### Build against the API reference
- Status: Available now
- Audience: Developers
- Link: https://fanful.net/api
- Use the API map for manifests, action contracts, workflow-trigger subscriptions, recipes, and the official SDK release plan.

### Copy Fanful skills
- Status: Available now
- Audience: Agent operators
- Link: https://fanful.net/skills
- Install provider-neutral prompt skills for setup, MCP operation, webhooks, creator commerce, listener chat, and SDK planning.

### Choose hosted or external execution
- Status: Available now
- Audience: Agent builders
- Link: https://fanful.net/agent-docs/fanful-hosted-agent-runtime.md
- Use the hosted-runtime boundary to decide when a custom worker can stay external and when a future Fanful-managed worker needs logs, limits, approval, and cancellation.

### Smoke-test public answers
- Status: Available now
- Audience: AI answer systems
- Link: https://fanful.net/agent-docs/fanful-agent-ingestion-qa.md
- Use the Q&A matrix to check whether public pages support common Fanful, competitor, agent-action, and not-ready answers without overclaiming.

### Inspect action contracts
- Status: Preview
- Audience: App builders
- Link: https://fanful.net/api/agent/action-contracts
- Read the shared confirmation, audit, idempotency, and redaction rules before adding any mutating tool.

### Prepare for scoped auth
- Status: Planned
- Audience: Product engineers
- Link: https://fanful.net/agents
- Private listener and creator workflows use scoped grants, one-time token exchange, and account-level revocation.

## Reference links

- [Agent setup](https://fanful.net/agent-setup): Cloudflare-style one-stop page for any AI coding agent starting with Fanful.
- [Agent setup prompt](https://fanful.net/agent-setup/prompt.md): Copy-paste prompt that points agents to Fanful MCP, API docs, CLI, skills, and safety rules.
- [API reference](https://fanful.net/api): API map, auth model, workflow-trigger recipes, code examples, and official SDK release plan.
- [API reference markdown](https://fanful.net/api.md): Model-readable mirror of the Fanful API reference and recipes.
- [Agent skills](https://fanful.net/skills): Copyable provider-neutral skills for Fanful agents and integrations.
- [Agent skills markdown](https://fanful.net/skills.md): Model-readable skill catalog with prompt blocks.
- [Developer docs](https://fanful.net/docs): Human-readable entrypoint for Fanful agent, MCP, CLI, and integration docs.
- [Developer docs markdown](https://fanful.net/docs.md): Compact model-readable mirror of the developer docs.
- [llms.txt](https://fanful.net/llms.txt): Canonical discovery file for AI agents and crawlers.
- [Agent access overview](https://fanful.net/agents): Current MCP tools, resources, safety boundaries, and roadmap status.
- [Agent markdown guide](https://fanful.net/agent-docs/fanful-agent-surface.md): Concise agent-facing instructions for current public tools and non-goals.
- [Agent SDK starter](https://fanful.net/agent-docs/fanful-agent-sdk-starter.md): Provider-neutral TypeScript example and no-SDK HTTP fallback for external agents.
- [Hosted runtime boundary](https://fanful.net/agent-docs/fanful-hosted-agent-runtime.md): External-first recommendation, future hosted worker limits, redacted run-record fixture, approval, retry, and cancellation rules.
- [Agent-ingestion Q&A matrix](https://fanful.net/agent-docs/fanful-agent-ingestion-qa.md): Source-backed smoke matrix for common Fanful, competitor comparison, agent-action, and not-ready answers.
- [Public MCP endpoint](https://fanful.net/mcp): Stateless Streamable HTTP MCP endpoint for current public/read-safe resources.
- [Community chat manifest](https://fanful.net/api/agent/community-chat): Channel, message, posting, moderation, and creator-attribution contracts.
- [Embedded rooms manifest](https://fanful.net/api/agent/embedded-rooms): Room, roster, media-token, host, attendee, and moderation boundaries.
- [Creator commerce manifest](https://fanful.net/api/agent/creator-commerce): Lesson/coaching offers, shop products, creator state, service price previews, confirmed lesson price/policy writes, Stripe Price mapping boundaries, membership tier writes, and safe shop product create/visibility/details/Stripe Price writes.
- [Artist analytics manifest](https://fanful.net/api/agent/artist-analytics): Creator/admin aggregate analytics summary with source funnels, top content outcomes, listener cohorts, recent signals, and raw listener rows redacted.
- [Listener experience manifest](https://fanful.net/api/agent/listener-experience): Fan account, focused profile/preference, membership entitlement, live support, library, playback, notification, and Listen Along readbacks.
- [Idea board manifest](https://fanful.net/api/agent/idea-board): Member ideas, vote state, review fields, confirmed listener submit/vote writes, and creator review/settings contracts.
- [ChatGPT app readiness](https://fanful.net/api/agent/chatgpt-app): Apps SDK mapping, descriptor status, widget posture, and submission blockers.
- [Action contracts manifest](https://fanful.net/api/agent/action-contracts): Shared auth, confirmation, audit, idempotency, rate-limit, and redaction contract.
- [Sync jobs manifest](https://fanful.net/api/agent/sync-jobs): Cursor/checkpoint contract plus authenticated Stripe catalog app-reference drift run/status endpoints with redacted durable output.

## Status glossary

- Manifest-only: Fanful publishes a model-readable HTTP/MCP manifest so agents can discover the shape, fields, redactions, and future workflow. It is not an executable feature yet.
- Contract-only: Fanful has written down the safety contract for an action, including auth, confirmation, audit, idempotency, and redaction rules. The action remains blocked until a narrow confirmed write wrapper ships.
- API-only: The server endpoint exists outside the current MCP catalog. Agents can use it only with the documented HTTP contract and required scoped credentials.

## Agent setup and skills

Use https://fanful.net/agent-setup/prompt.md as the one prompt to paste into a coding agent. It points agents to MCP, HTTP manifests, CLI docs, API examples, workflow-trigger recipes, and safety rules. Use https://fanful.net/skills or https://fanful.net/skills.md for copyable Fanful skills such as `fanful-mcp-operator`, `fanful-api-integrator`, `fanful-creator-commerce`, and `fanful-listener-community`.

## API reference and SDK plan

Use https://fanful.net/api or https://fanful.net/api.md for the current Fanful API map. Fanful has executable HTTP agent manifests, MCP, action contracts, workflow-trigger subscriptions, sync feeds, and a repo CLI today. Official language SDK packages such as Python are not published yet; the API reference documents the release checklist for versioning, auth, schema generation, webhook helpers, examples, CI, package ownership, and support policy.

## SDK starter examples

Use the provider-neutral starter at https://fanful.net/agent-docs/fanful-agent-sdk-starter.md when an external agent needs typed HTTP discovery or a no-SDK fallback. The copy-paste example lives at `examples/fanful-agent-starter/client.ts`. Credentials belong in transport headers or environment variables such as `FANFUL_AGENT_BEARER_TOKEN`, never in prompt-visible tool input.

```ts
import {
  FanfulAgentHttpError,
  createFanfulAgentClientFromEnv,
} from "./examples/fanful-agent-starter/client";

const fanful = createFanfulAgentClientFromEnv(process.env);

const listenerManifest = await fanful.manifest("listener-experience");
const checkoutContracts = await fanful.actionContracts({
  audience: "listener",
  domain: "checkout",
});

try {
  const analytics = await fanful.creatorAnalytics({ window: "30d" });
  console.log(analytics);
} catch (error) {
  if (error instanceof FanfulAgentHttpError && error.isAuthBoundary) {
    console.log("Ask the human for a scoped creator grant; never paste tokens into prompts.");
  } else {
    throw error;
  }
}

await fanful.validateEnvelope({
  contractId: "listener.checkout.start",
  actor: { role: "listener", displayName: "Signed-in listener" },
  client: { id: "starter-example", name: "Fanful starter example", kind: "other" },
  action: {
    requested: "listener.checkout.start",
    mode: "validate",
  },
  target: {
    type: "checkout-intent",
    id: "support-donation",
    summary: "Support donation checkout for $25.00",
  },
  dryRun: true,
  confirmation: {
    text: "I confirm listener.checkout.start for Support donation checkout for $25.00.",
    acknowledgedRisk: true,
  },
  idempotencyKey: "starter-example-support-checkout-2026-05-16",
  auditCorrelationId: "starter-example-audit-2026-05-16",
  reason: "Validate the shared confirmation envelope before calling an executable write tool.",
});
```

No-SDK HTTP fallback:

```bash
curl -fsS https://fanful.net/llms.txt
curl -fsS https://fanful.net/api/agent/listener-experience
curl -fsS 'https://fanful.net/api/agent/action-contracts?audience=listener&domain=checkout'
curl -fsS -H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
  'https://fanful.net/api/agent/artist-analytics?window=30d'
curl -fsS -H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
  'https://fanful.net/api/agent/media-upload-sessions'
curl -fsS -X POST https://fanful.net/api/agent/action-contracts/envelope \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $FANFUL_AGENT_BEARER_TOKEN" \
  --data @agent-write-envelope.json
```

## Hosted runtime boundary

Use https://fanful.net/agent-docs/fanful-hosted-agent-runtime.md before proposing any Fanful-managed worker. Fanful is external-first today: workflow triggers, agent sessions, sync jobs, MCP tools, HTTP manifests, and action contracts define the boundaries, while arbitrary code execution and custom reasoning stay outside Fanful infrastructure. A future hosted worker needs a redacted run record, correlation id, idempotency key, logs, limits, approval state, cancellation, retries, and audit links before implementation.

## Agent-ingestion Q&A smoke

Use https://fanful.net/agent-docs/fanful-agent-ingestion-qa.md when testing whether an AI answer system can explain Fanful from public sources. The matrix covers what Fanful is, who it is for, Patreon/Circle/Linktree/Shopify comparisons, what agents can do, and what remains planned or blocked.

## Workflow status

| Workflow | Status | Creator path | Listener path | Agent contract |
| --- | --- | --- | --- | --- |
| Read public platform capabilities | Available now | Inspect current creator-commerce, live, room, and community capabilities. | Inspect public fan surfaces, ideas, room readiness, and listener-safe summaries. | Use HTTP manifests, /mcp, and fanful_agent_manifest_read. |
| Start an external agent integration | Available now | Use scoped creator grants for private analytics, commerce, live, room, and moderation reads or confirmed writes. | Use first-party listener sessions or scoped grants for entitlements, profile preferences, support, membership, or shop checkout, and purchase status. | Start from the SDK starter, then use MCP, direct HTTP manifests, action contracts, workflow triggers, agent sessions, and sync jobs without exposing credentials in prompts. |
| Render listener checkout confirmations | Available now | No creator commerce state changes when the render tool runs; creator billing/catalog writes remain on their own confirmed tools. | Show a ChatGPT confirmation review before a support donation, membership tier, or signed-CD shop checkout start. | Use fanful_listener_checkout_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/listener-checkout-confirmation.html, and must be followed by fanful_listener_support_checkout_start, fanful_listener_membership_checkout_start, or fanful_listener_shop_checkout_start with scoped listener credentials, the exact purchase-link preview confirmation text, idempotency, reason, and audit correlation. Lesson and paid-room starts remain blocked. |
| Decide whether Fanful should host a worker | Available now | Keep custom reasoning external unless a bounded worker family has explicit logs, limits, approval, cancellation, rollback, and audit semantics. | Listener-impacting workers stay preview/read-only until a confirmed action contract says a write is executable. | Use the hosted-runtime boundary and safe run-record fixture before opening worker-family implementation issues. |
| Preview creator coaching price/policy changes | Preview | Preview lesson or coaching price/policy impact without changing Stripe, checkout, booking policy, or public pages. | Fan-facing checkout starts remain planned. | Use fanful_creator_lesson_price_preview first; lesson price cents, existing lesson Stripe Price mapping, and replacement lesson Stripe Price creation have confirmed wrappers. |
| Execute confirmed lesson price writes | Available now | Preview a lesson or coaching price change, then confirm the supported Fanful offering price update through the wrapper. | Future fan-facing catalogs see the new Fanful service price after the confirmed creator write succeeds. | Use fanful_creator_service_price_policy_update with exact confirmation, observed updated_at, idempotency, reason, and audit correlation. Stripe Price, credit, refund, cancellation execution, and entitlement writes remain blocked. |
| Execute confirmed lesson policy settings writes | Available now | Read the latest creator-commerce policy settings, then confirm an artist-default or offering-override lesson policy settings change. | Future lesson surfaces can explain the configured cutoff, refund, no-show, skip-week, and credit-expiration settings after the confirmed creator write succeeds. | Use fanful_creator_lesson_policy_update with exact confirmation, observed lesson_policy_settings.updated_at or observed policy id set, idempotency, reason, and audit correlation. Refund execution, credit ledger mutations, booking cancellation/reschedule execution, bundles, subscriptions, and entitlement writes remain blocked. |
| Render ChatGPT lesson price/policy confirmations | Available now | Show a ChatGPT confirmation review for a lesson price or lesson policy settings change before the separate write tool runs. | No listener-facing lesson catalog or policy change occurs until the matching confirmed write succeeds. | Use fanful_creator_lesson_price_policy_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-lesson-price-policy-confirmation.html, and must be followed by fanful_creator_service_price_policy_update or fanful_creator_lesson_policy_update with exact confirmation, stale-state guards, idempotency, reason, audit correlation, and scoped/admin credentials. |
| Execute confirmed lesson availability writes | Available now | Read the latest creator-commerce lesson availability, render the optional ChatGPT confirmation review when useful, then confirm one future open/cancelled lesson window change. | Future lesson surfaces see the updated open/cancelled availability only after the confirmed creator write succeeds. | For ChatGPT UI, use fanful_creator_lesson_availability_confirmation_render first. Then use fanful_creator_lesson_availability_update with exact confirmation, observed lesson_availability_windows.updated_at or observed availability id set, idempotency, reason, and audit correlation. Held/booked slots, booking workflow execution, meeting URLs, private notes, refunds, credits, and Stripe remain blocked. |
| Execute confirmed lesson Stripe Price mapping writes | Available now | Read the latest creator-commerce or Stripe catalog state, then confirm selecting or clearing an already-known Stripe Price mapping for one lesson offering. | Future lesson checkout uses the mapped Stripe Price only after the confirmed creator write succeeds. | Use fanful_creator_lesson_stripe_price_select with exact confirmation, observed updated_at, idempotency, reason, and audit correlation. Product metadata, policy, tier, credit, cancellation, and entitlement writes remain blocked. |
| Execute confirmed lesson Stripe Price creation | Available now | Read the latest creator-commerce or Stripe catalog state, then confirm creating and selecting one replacement Stripe Price for one lesson offering. | Future lesson checkout uses the replacement Stripe Price only after the confirmed creator write succeeds. | Use fanful_creator_lesson_stripe_price_create with exact confirmation, observed updated_at, idempotency, reason, audit correlation, server-side Stripe credentials, and existing product context. Product metadata, policy, tier, credit, cancellation, and entitlement writes remain blocked. |
| Execute confirmed membership Stripe Price mapping writes | Available now | Read the latest creator-commerce or Stripe catalog state, then confirm selecting or clearing an already-known Stripe Price mapping for one membership tier. | Future membership checkout uses the mapped Stripe Price only after the confirmed creator write succeeds. | Use fanful_creator_membership_stripe_price_select with exact confirmation, observed updated_at, idempotency, reason, audit correlation, and catalog compatibility checks. Tier profile, amount, entitlement metadata, and existing membership writes remain blocked. |
| Execute confirmed membership Stripe Price creation | Available now | Read the latest creator-commerce or Stripe catalog state, then confirm creating and selecting one replacement monthly Stripe Price for one membership tier. | Future membership checkout uses the replacement monthly Stripe Price only after the confirmed creator write succeeds. | Use fanful_creator_membership_stripe_price_create with exact confirmation, observed updated_at, monthly amount, interval=month, idempotency, reason, audit correlation, server-side Stripe credentials, and existing product context. Tier profile, entitlement metadata, checkout policy, and existing membership writes remain blocked. |
| Execute confirmed membership tier lifecycle writes | Available now | Create an inactive tier draft, update one tier's public profile/benefits, or archive/restore a tier for future joins through focused confirmed tools. | Future membership surfaces see the changed tier catalog only after the confirmed creator write succeeds. | Use fanful_creator_membership_tier_create, fanful_creator_membership_tier_update, or fanful_creator_membership_tier_archive_state with exact confirmation, stale-state/catalog guards, idempotency, reason, and audit correlation. Amount changes, Stripe Price mapping, entitlement metadata, checkout policy, and existing membership revocation stay in separate tools or blocked contracts. |
| Render ChatGPT membership tier confirmations | Available now | Show a ChatGPT confirmation review for a membership tier create, update, archive/restore, or Stripe Price change before the separate write tool runs. | No listener-visible catalog change occurs until the matching confirmed write succeeds. | Use fanful_creator_membership_tier_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-membership-tier-confirmation.html, and must be followed by the matching membership write tool with exact confirmation, stale-state/catalog guards, idempotency, reason, audit correlation, and scoped/admin credentials. |
| Execute confirmed shop product creation | Available now | Read the latest creator-commerce shop catalog, then confirm one safe product create with observed product ids. | Future shop and checkout surfaces see the new product only after the confirmed creator write succeeds and the product is active/visible. | For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_create with exact confirmation, observed product ids, idempotency, reason, audit correlation, duplicate id/slug checks, and scoped/admin credentials. Raw download URLs, external URLs, Stripe Price ids, checkout sessions, fulfillment execution, orders, refunds, and credits remain blocked. |
| Execute confirmed shop product detail writes | Available now | Read the latest creator-commerce shop product state, then confirm safe details on one existing editable product. | Future shop and checkout surfaces see the changed copy, inventory, and fulfillment metadata only after the confirmed creator write succeeds. | For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_visibility_update for active/show-in-shop flags and fanful_creator_shop_product_details_update for title, description, inventory tracking/count, fulfillment note, download display metadata, and sort order. Raw download URLs, external URLs, product kind/id, checkout sessions, order fulfillment, and refunds remain blocked or separate contracts. |
| Execute confirmed shop product Stripe Price writes | Available now | Read the latest creator-commerce or Stripe catalog state, then confirm selecting/clearing a compatible Price or creating one replacement one-time Price for an existing shop product. | Future shop checkout uses the selected or replacement Stripe Price only after the confirmed creator write succeeds. | For ChatGPT UI, use fanful_creator_shop_product_confirmation_render first. Then use fanful_creator_shop_product_stripe_price_select or fanful_creator_shop_product_stripe_price_create with exact confirmation, observed updated_at, idempotency, reason, audit correlation, catalog compatibility checks, server-side Stripe credentials for creation, and existing Product context. Raw download URLs, external URLs, checkout sessions, fulfillment execution, orders, refunds, and credits remain blocked. |
| Update community channel tier access | Available now | Read the latest community channel state, then confirm one non-default channel access-mode or membership-tier access metadata change. | Listener access to that protected community channel updates only after the confirmed creator/admin write succeeds. | For ChatGPT UI, use fanful_creator_entitlement_metadata_confirmation_render first. Then use fanful_creator_entitlement_metadata_update with exact confirmation, observed community_chat_channels.updated_at, idempotency, reason, audit correlation, and scoped creator/admin credentials. Inactive tier creation is handled by the separate membership-tier lifecycle contract; paid-room policy, entitlement-group, and membership writes remain blocked. |
| Render ChatGPT live status confirmations | Available now | Show a ChatGPT confirmation review for go-live, end, cancel, or scheduled-status transitions before the separate live status write tool runs. | No listener-visible live room state changes until the matching confirmed status write succeeds. | Use fanful_creator_live_status_confirmation_render for ChatGPT UI confirmation summaries. It is read-only, advertises ui://fanful/widgets/creator-live-status-confirmation.html, and must be followed by fanful_creator_live_status_update with exact confirmation, observed live_events.updated_at, idempotency, reason, audit correlation, and scoped/admin credentials. Event creation, schedule edits, stream provider provisioning, roster/stage changes, chat moderation, and notification fan-out stay in separate contracts. |
| Read fan membership and entitlements | Available now | No creator write is performed; this only explains fan access to gated experiences. | Ask what membership tier, benefits, purchases, and gated experiences the signed-in fan can access. | Use listener.entitlementStatus or fanful_listener_entitlements_read with listener:entitlements:read for private scoped clients. |
| Read fan profile and notification preferences | Available now | No creator write is performed; this only explains the fan's own account preference state. | Ask what email confirmation state, notification channels, categories, and community-chat notification routing are configured. | Use listener.profilePreferences or fanful_listener_profile_preferences_read with listener:profile:read plus listener:preferences:read for private scoped clients. |
| Update fan display name | Available now | No creator write is performed; this only changes the signed-in fan's account display name for future attribution. | Read the current display name, choose the exact new visible name, then confirm the update so future account chrome, community posts, chat, and comments use it. | Use fanful_listener_display_name_confirmation_render when a ChatGPT UI confirmation summary is useful, then use fanful_listener_display_name_update or POST /api/agent/listener-experience with confirm_listener_display_name_update after a fresh profile read, exact confirmation text, acknowledged risk, idempotency key, reason, audit correlation id, observed display-name stale-state guard, and scoped listener:profile:write or first-party listener credentials. |
| Preview live-room support checkout readiness | Available now | No creator write is performed; this only explains what support CTA agents may show during live rooms. | Ask whether a live-room support CTA is available, what generic support/donation confirmation copy is needed, confirm support-only checkout start, then inspect redacted checkout status. | Use listener.liveSupport or fanful_listener_live_support_preview first, then fanful_listener_support_checkout_start or POST /api/agent/listener-experience with listener.checkout.start. Use listener.purchaseLinkStatus or fanful_listener_purchase_link_status for redacted follow-up status. Membership checkout uses listener.purchaseLinkPreview plus fanful_listener_membership_checkout_start; signed-CD shop checkout uses listener.purchaseLinkPreview plus fanful_listener_shop_checkout_start; lesson and paid-room starts remain blocked. |
| Validate write envelopes | Preview | Check whether a future creator action carries confirmation, idempotency, actor, and client attribution. | Check whether a future fan action has the same confirmation and audit fields. | Use /api/agent/action-contracts and the dry-run envelope validator once merged. |
| Preview and execute live schedule writes | Available now | Preview a live create, schedule edit, or reschedule payload with stream/replay fields redacted, optionally preview follower notification copy, then confirm supported new-event creates or existing-event updates through the wrappers. | Listener-facing live room state and optional in-app notification-center rows update only after the confirmed creator/admin write succeeds. Email and push are not sent by the schedule-write slice. | Use fanful_live_schedule_preview first, then fanful_creator_live_schedule_create for new events or fanful_creator_live_schedule_update for existing events with confirmation, idempotency, reason, audit correlation, and matching fanNotification audience/title/body/timeZone when notifying followers. Existing-event updates also require observed updated_at. |
| Execute confirmed live status writes | Available now | Preview a live-room status change, then confirm go-live, end, cancel, or restore-scheduled through the wrapper. | Listener-facing live room state updates only after the confirmed creator/admin write succeeds. | Use fanful_live_status_preview first. In ChatGPT UI, optionally render fanful_creator_live_status_confirmation_render before fanful_creator_live_status_update with confirmation, observed updated_at, idempotency, reason, and audit correlation. |
| Execute confirmed embedded-room roster changes | Available now | Read one embedded-room roster, then confirm a single invite, co-host promotion, stage move, removal, or restore through the wrapper. | Listener room access and presenter state update only after the confirmed creator/admin write succeeds. | Use fanful_agent_manifest_read(surface=embedded-rooms) first, then fanful_creator_embedded_room_roster_update with confirmation, observed participant updated_at for existing participants, idempotency, reason, and audit correlation. |
| Read creator analytics | Available now | Ask for aggregate source funnels, top content outcomes, listener cohorts, and recent signals without exporting listener rows. | No listener-facing data is exposed; raw listener ids, anonymous ids, session ids, and referrer query strings stay redacted. | Use fanful_agent_manifest_read(surface=artist-analytics) or /api/agent/artist-analytics with creator:laurel:analytics:read, creator:laurel:read, admin, or automation credentials. |
| Run catalog sync jobs | Available now | Run the first-party Stripe catalog app-reference drift worker and inspect redacted checkpoint output before proposing commerce changes. | No listener-facing write is performed; sync output only informs creator/operator review. | Use fanful_sync_job_run with an idempotency key and audit correlation id, then fanful_sync_job_status_read or /api/agent/sync-jobs?jobId=... to inspect durable redacted runs. |
| Authorize private agent access | Planned | Approve scoped creator grants for live, commerce, rooms, and moderation. | Approve scoped listener grants for entitlements, preferences, purchases, and Listen Along. | Uses scoped grants, one-time token exchange, account revocation, and MCP principal resolution. |
| Execute confirmed writes | Planned | Moderate rooms, speak as creator, or make broader commerce changes only after confirmation. | Start support, membership, or shop checkout, post ideas, update preferences, or join experiences only with scoped attribution. | Live schedule/status, embedded-room roster/stage, lesson price, lesson Stripe Price mapping/creation, membership tier lifecycle, membership Stripe Price mapping/creation, shop product create/visibility/details/Stripe Price writes, support checkout, membership checkout, signed-CD shop checkout, and community-message post/reply writes are ready in narrow wrappers; destructive, unsupported public-content, and unsupported billing writes remain unavailable until a manifest explicitly marks them ready. |

## Safe-use rules

- Prefer MCP resources and HTTP manifests over browser automation.
- Do not pass admin secrets or bearer credentials as prompt-visible tool input.
- Treat public and private data boundaries as separate. Listener ids, device ids, payment ids, media URLs, invite tokens, and raw internal ids stay redacted unless a contract explicitly marks a field safe.
- Treat destructive, billing-impacting, moderation, and creator-speech writes as unavailable unless the relevant manifest says the operation is ready and requires confirmation plus audit attribution. Confirmed live schedule/status writes, safe shop product create/details writes, shop product Stripe Price writes, and confirmed community channel tier-access metadata writes are current ready examples.
- Keep ChatGPT app widgets and metadata as optional layers over the shared MCP surface, not separate product contracts.