# Puppetto Integration Bounty Admin Guide

Use this runbook when Puppetto wants to reward an organization with credits after the organization connects an X account and publishes an approved Puppetto-powered post.

The first supported bounty path is intentionally operational and auditable:

1. The organization signs in to Puppetto.
2. The organization creates or selects its Puppetto organization.
3. The organization connects its own X account to that Puppetto organization.
4. The user or an assisting agent creates a Puppetto post targeted to the connected X account.
5. The organization reviews and publishes or schedules the post from Puppetto.
6. An admin verifies the post and grants bounty credits with an audit note.

Agents must not ask users to paste social credentials into chat. X connection is always completed by the user through Puppetto OAuth.

## Admin Checklist

1. Confirm the bounty offer terms.

- Credit amount
- Expiration window
- Eligible organization
- Required publish channel, currently `x-api`
- Required post wording or disclosure, if any
- Verification evidence, such as Puppetto post ID plus public X post URL

2. Confirm the organization has MCP or web-app access.

- For MCP onboarding, use `https://puppetto.com/agent-assets/puppetto/mcp-quickstart.md`.
- For manual web onboarding, have the user create or select an organization from `/organizations`.
- If the organization needs an MCP token, have the user generate it from `/organizations/<orgId>/developer`.

3. Have the user connect X.

Preferred MCP-assisted path:

- Call `puppetto_get_authorized_context`.
- Call `puppetto_list_social_posting_providers`.
- Call `puppetto_get_social_connection_links`.
- Ask the user to open the X connect URL themselves.
- After OAuth returns to Puppetto, call `puppetto_list_integrations` and confirm a connected `x-api` integration exists.

Web fallback:

- Send the user to `/organizations/<orgId>/integrations`.
- The user clicks the X connection option and completes OAuth.
- The user returns to Puppetto after the OAuth callback.

4. Create or identify the bounty post.

MCP path:

- Use `puppetto_create_social_post` for a new post when no draft exists.
- Use `puppetto_set_post_targets` with the connected X integration ID.
- Use `puppetto_update_post_schedule` if the post should be scheduled.
- Use `puppetto_get_post` or `puppetto_list_posts` to confirm the post is ready.

Template-first path:

- Call `puppetto_list_onboarding_templates`.
- Use `puppetto_create_campaign_from_onboarding_template` if the user has a business brief but no campaign structure.
- Review the generated posts with the user before targeting or scheduling anything.

5. Verify publication.

Accept at least two of these signals before granting credits:

- Puppetto organization ID
- Puppetto post ID
- Connected X integration ID or handle
- Public X post URL
- Screenshot or admin-visible delivery status
- Published timestamp

If automated delivery status is unavailable or delayed, use manual verification from the public X post URL and record that URL in the credit grant reason.

6. Grant bounty credits.

- Open `/admin/organizations`.
- Search for the organization.
- Click `Grant`.
- Choose the `Bounty` quick grant, or enter the bounty amount manually.
- Put the X post URL, Puppetto post ID, and bounty name in the grant reason.
- Keep the expiration within the admin limit.

Recommended reason format:

```text
Integration bounty: verified X post <url>; Puppetto post <postId>; connected integration <integrationId>.
```

## Agent Prompt For Bounty Fulfillment

Use this prompt when handing the workflow to another agent:

```text
You are helping a Puppetto organization complete an integration bounty.

Your goal is to help the user sign in, select or create their Puppetto organization, generate an MCP token if needed, connect their own X account through Puppetto OAuth, create or choose an approved Puppetto post, target that post to the connected X account, and guide the user through publishing or scheduling it.

Use these public references:

- https://puppetto.com/agent-assets/puppetto/mcp-quickstart.md
- https://puppetto.com/agent-assets/puppetto/setup-auth.md
- https://puppetto.com/agent-assets/puppetto/campaign-onboarding.md
- https://puppetto.com/agent-assets/puppetto/integration-bounty-admin-guide.md

Start by asking the user whether they already have a Puppetto account and organization. Do not ask for Puppetto API keys or X credentials in chat. If an MCP key is needed, guide the user to generate it in Puppetto and store it in their MCP client's secret or environment-variable flow.

After MCP is connected, call `puppetto_get_authorized_context`, then inspect social providers and integrations. If X is not connected, use `puppetto_get_social_connection_links` and ask the user to open the returned X connect URL themselves.

Before publishing, show the user the proposed post copy and target account. The user must approve the final post. After publishing or scheduling, collect the Puppetto post ID and public X post URL for admin verification.
```

## Guardrails

- Do not post from an account the user has not connected to their Puppetto organization.
- Do not request or store X credentials in chat.
- Do not publish without user review of the final copy and target account.
- Do not promise credits until an admin verifies eligibility.
- Record the verification evidence in the admin grant reason.
- Avoid spammy or deceptive bounty posts. If the bounty is an incentive, include any required disclosure in the post copy.