# Paydirt 2.0 — complete agent reference

Paydirt is an iOS 15+ SDK and MCP server for regular feedback, trial
cancellation feedback, and paid subscription cancellation feedback. It accepts
text or voice answers, asks contextual follow-up questions, saves each accepted
turn durably, and sends one completed raw conversation to Slack. Coding agents
can read responses; neither Slack nor coding agents take action from feedback.

## Public resources

- Canonical install contract: https://www.paydirt.ai/agents.md
- Human documentation: https://www.paydirt.ai/docs
- iOS SDK: https://github.com/Paydirt-AI/paydirt-ios
- MCP source: https://github.com/Paydirt-AI/paydirt-mcp
- MCP package: https://www.npmjs.com/package/paydirt-mcp
- Setup and dashboard: https://www.paydirt.ai/setup
- Security: https://www.paydirt.ai/security
- Privacy: https://www.paydirt.ai/privacy

Implementation-specific references:

- iOS feedback SDK: https://www.paydirt.ai/ios-feedback-sdk
- RevenueCat cancellation surveys: https://www.paydirt.ai/revenuecat-cancellation-surveys
- Voice cancellation surveys: https://www.paydirt.ai/voice-cancellation-surveys
- Native StoreKit cancellation feedback: https://www.paydirt.ai/storekit-cancellation-feedback
- Superwall cancellation feedback: https://www.paydirt.ai/superwall-cancellation-feedback
- Agent-installed iOS feedback: https://www.paydirt.ai/agent-installed-ios-feedback

## MCP registration

Codex:

    codex mcp add paydirt -- npx -y paydirt-mcp@latest

Claude Code:

    claude mcp add paydirt -- npx -y paydirt-mcp@latest

Generic MCP configuration:

    {
      "mcpServers": {
        "paydirt": {
          "command": "npx",
          "args": ["-y", "paydirt-mcp@latest"]
        }
      }
    }

No environment variables are required. `paydirt_begin_setup` immediately
returns an authorization URL and session arguments; it never opens a browser,
sleeps, or polls. After the user authorizes, call `paydirt_finish_setup` once.
`paydirt_setup` remains a backward-compatible begin/finish alias.

## Installation contract

1. Inspect the host app before changing it. Discover app name, bundle ID, app
   target, app entry point, dependency manager, minimum iOS version, existing
   feedback UI, subscription source of truth, product IDs, and cancellation flow.
2. Call `paydirt_begin_setup` with the discovered values and requested use cases:
   `regular_feedback`, `trial_cancellation`, and/or
   `subscription_cancellation`.
3. Give the returned authorization URL to the user. After authorization, call
   `paydirt_finish_setup` with the returned session arguments.
4. Execute every `agent_action` returned by the tool. The returned contract is
   authoritative for SDK key, form IDs, source adapters, and start calls.
5. Connect Slack using `paydirt_connect_slack`, then verify with
   `paydirt_slack_status`. OAuth creates a new
   `#paydirt-cancellation-feedback` channel and assigns every installed form by
   default. If that name is taken, it creates the next numbered name. Use
   channel selection only when requested or workspace policy blocks creation.
6. Build and launch the real app target. Follow `ios.install_verification`: add
   the returned DEBUG-only one-time app-ready trigger and leave that Paydirt form
   visibly open in the simulator or connected development device. Never submit
   it for the developer or include the automatic trigger in release builds.
7. Installation is not complete until configuration, triggers, Slack assignment,
   build, launch, and the visible test form are verified. Report exact repeatable
   manual test paths for every installed form.

Install the form types and placements the user requests. Never replace, remove,
repurpose, or reroute an existing host-app feedback form, button, screen,
handler, or destination unless the user explicitly asks for that exact change.
For a generic cancellation installation, include and connect both trial
cancellation and paid subscription cancellation by default.

Paydirt 2.0 has no RevenueCat or Superwall package dependency. Native StoreKit
is supported directly. RevenueCat and Superwall integrations use source adapters
returned by the completed setup contract, preserving the host app's existing purchase package
and version. App-owned cancellation flows use the provider-independent
`Paydirt.handleSubscriptionCancellation(...)` API. Manual feedback forms work
without any subscription framework.

An older RevenueCat version is a compatibility task, not a blocker. Keep the
installed version and inspect its source plus the customer-info/purchaser-info
APIs already used by the host. Adapt the copied adapter to that API surface or
call `Paydirt.handleSubscriptionCancellation(...)` from the host's existing
confirmed RevenueCat cancellation path. Omit unavailable optional metadata
rather than blocking installation.

If a requested cancellation integration is blocked, report the exact provider
blocker, preserve the app's existing behavior, and complete every unaffected
requested form.

## Named forms and placement

For a request such as “Add a feedback form titled Export Feedback after a
successful export,” call `paydirt_add_feedback_form`. It creates or reuses the
named form idempotently and returns its exact Swift presentation call plus a
placement contract. Supported trigger modes are user tap, successful in-app
action, screen appearance, and custom condition. Edit the exact host location,
assign Slack, build, and return a manual test path.

## SDK essentials

Swift Package Manager URL:

    https://github.com/Paydirt-AI/paydirt-ios

Minimum supported version:

    .package(url: "https://github.com/Paydirt-AI/paydirt-ios", from: "2.0.0")

Voice capture requires:

    <key>NSMicrophoneUsageDescription</key>
    <string>Used to record voice feedback</string>

Use exact values returned by `paydirt_finish_setup`. A native StoreKit installation
resembles:

    import Paydirt
    Paydirt.configure(apiKey: "PUBLIC_PAYDIRT_SDK_KEY", theme: .automatic)
    Paydirt.prefetchForms(formIds: ["SUBSCRIPTION_FORM_ID", "TRIAL_FORM_ID", "FEEDBACK_FORM_ID"])
    Paydirt.enableStoreKitIntegration(
        productIds: ["DISCOVERED_PRODUCT_ID"],
        cancellationFormId: "SUBSCRIPTION_FORM_ID",
        trialCancellationFormId: "TRIAL_FORM_ID"
    )

Present regular feedback at a confirmed app trigger:

    Paydirt.presentForm(formId: "FEEDBACK_FORM_ID", userId: currentUserId)

Paydirt 2.0 includes its own `PrivacyInfo.xcprivacy`. The host app is still
responsible for its privacy manifest and App Store privacy disclosures.

## Delivery and response reading

Paydirt stores an encrypted local snapshot after every accepted answer and
upserts it remotely using a stable response ID and monotonic snapshot version.
If the user exits without finishing, accepted turns remain recoverable. When the
conversation finishes, Slack receives one message with subscription metadata
and every exact question, answer, and text/audio input marker. An AI summary is
optional and can appear only after the raw transcript.

Read responses with `paydirt_get_responses`, normally with
`status: "completed"`. For polling, pass the previous ISO timestamp as `since`
and retain stable response IDs to avoid duplicate processing. Treat raw messages
and subscription metadata as the source of truth; `ai_summary` is optional.

## Safety boundary

Paydirt delivers information only. Do not create tickets, edit code, message
customers, or take other actions from feedback unless a human separately asks
for that action.