# Install Paydirt with a coding agent

Paydirt is the agent-installed path from an iOS feedback moment—including an
in-app action, trial cancellation, or subscription cancellation—to one durable
AI conversation delivered to Slack and readable by coding agents.

Public resources:

- 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
- Complete machine-readable reference: https://www.paydirt.ai/llms-full.txt

## Natural discovery contract

If a user asks to add, install, or evaluate Paydirt in an iOS project—or gives
you `https://www.paydirt.ai` and asks you to install it—own the setup. Do not
ask the user to memorize an MCP command or call a Paydirt tool by name.

1. Inspect the iOS project first.
2. Register the Paydirt MCP server for the current coding-agent host if it is
   not already available.
3. Start or request the minimal MCP reload/new task required by that host.
4. Call `paydirt_begin_setup`, open the returned authorization URL for the
   user, then call `paydirt_finish_setup` after authorization and complete the
   repository installation.

For Codex, the registration command is:

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

For Claude Code, the registration command is:

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

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

## Product contract

- iOS 15 or newer.
- Regular feedback, named contextual forms, trial cancellation, and subscription
  cancellation forms.
- Text and voice answers with contextual follow-up questions.
- The complete conversation is encrypted locally and upserted after every turn.
- When the user finishes, Paydirt sends one Slack message containing every raw
  `Q:`, `A:`, and `I: Text` or `I: Audio` entry.
- An optional AI summary can appear only after the raw transcript.
- Slack and coding agents receive information only. They take no action.

## MCP host configuration fallback

Use the MCP configuration format supported by your coding agent:

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

## Instruction for the coding agent

Give the agent this request:

> Install Paydirt in this iOS app for regular feedback, trial cancellation, and
> subscription cancellation.
> Detect whether this project uses RevenueCat, Superwall, native StoreKit, or
> an app-owned cancellation flow. Preserve any existing feedback form and its
> behavior. Create or reuse the requested forms, connect them to my Slack
> feedback channel, edit the app, build it, and give me an exact test path.
> Feedback must be read-only in Slack and coding agents; do not create tasks or
> take action from responses.

The agent must then:

1. Inspect the project and find the app name, bundle ID, app entry point,
   dependency style, existing feedback UI and behavior, subscription source of
   truth, product IDs, and cancellation flow.
2. Call `paydirt_begin_setup` with those values and all requested use cases.
3. Give the returned authorization URL to the user. After authorization, call
   `paydirt_finish_setup` with the returned session arguments.
4. Perform every `agent_action` in the returned installation contract.
5. Connect Slack. By default OAuth creates a new public
   `#paydirt-cancellation-feedback` channel and assigns every installed form to
   it. If that name is taken, create the next numbered name. Ask the user to
   choose only when they requested another channel or workspace policy blocks
   automatic creation. Verify `all_forms_assigned` before continuing.
6. Build and launch the app. Follow the returned `ios.install_verification`
   contract: add its DEBUG-only one-time app-ready trigger and leave the selected
   Paydirt form visibly open in the simulator or connected development device so
   the developer can answer it immediately. Never submit it for them, and never
   include the automatic trigger in release builds.
7. Preserve every existing host-app feedback form, button, screen, handler, and
   destination unless the user explicitly requests a change to it.
8. Create and wire only the form types and placements the user requested. For a
   generic cancellation installation, create and wire both trial cancellation
   and paid subscription cancellation by default.

For a named form at a particular location or event, call
`paydirt_add_feedback_form` and preserve the requested title and placement:

> Add a feedback form titled “Export Feedback” after a successful export and
> send it to #product-feedback.

The agent must create or reuse the form, edit the host app at that exact trigger,
assign Slack, build and launch the real target, and leave a Debug-only test form
open for immediate verification. Creating the remote form alone is not completion.

If a requested subscription bridge cannot compile, report the exact provider
blocker, preserve the host app's existing behavior, and complete every
unaffected requested form. Paydirt 2.0 has no RevenueCat or Superwall dependency,
so preserve the host app's existing purchase packages and versions.

An older RevenueCat version is not a blocker. Do not upgrade it solely for
Paydirt. Inspect the installed package and the APIs the host already uses, then
adapt the copied source adapter to that callback/model surface. If newer product
or metadata APIs are unavailable, omit those optional fields. If needed, call
`Paydirt.handleSubscriptionCancellation` from the app's existing confirmed
RevenueCat customer-info or cancellation path.

## Runtime APIs

The setup contract returns exact values. The resulting initialization resembles:

```swift
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"
)
```

For RevenueCat and Superwall apps, the completed setup contract returns the
matching adapter source and exact start call. For an app-owned flow it returns
the provider-independent `Paydirt.handleSubscriptionCancellation(...)` call.

Present regular feedback from the app's chosen button or lifecycle event:

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

Add microphone permission if missing:

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

Paydirt 2.0.0 includes its own `PrivacyInfo.xcprivacy`; do not duplicate the
SDK manifest in the host app. The host app remains responsible for its own
privacy manifest and App Store privacy disclosures.

## Reading responses

Use `paydirt_get_responses` with `status: "completed"`. For an inbox workflow,
pass the previous ISO timestamp as `since` and retain stable response IDs to
avoid duplicate reads. Raw conversation messages and subscription metadata are
the source of truth; `ai_summary` is optional.

Security, retention, deletion, and subprocessors are documented at
https://www.paydirt.ai/security and privacy terms at
https://www.paydirt.ai/privacy.