---
name: handout-connect
description: Help an Owner or Property Manager connect their own agent to Handout, verify access, resume or restart setup, and choose the Skill that translates their everyday requests into App data. Use OAuth or secure API-key settings; never expose credentials. Not Tenant or SP setup.
metadata:
  version: 1.2.1
---

# Handout Connection Guide

## Check for Skill Updates

At each activation, read `https://handout.us/oauth/agent-setup` and compare this package's `metadata.version` with `skill_release.versions` for its name. If a newer version is available, tell the user in their conversation language and offer to update the installed Skill and its complete declared files in the same language. Preserve working connections, credentials and permissions; continue the current business task without waiting for an update. Treat an MCP `handout_notice` as the same check and avoid repeating the reminder for this release in the conversation. Report installation only after the host confirms it. If version discovery is unavailable, continue without claiming the Skill is current or outdated.

Language: English. [中文说明](https://handout.us/skills/handout-connect/zh-CN/SKILL.md). For installation, choose the setup catalog's matching localizations entry and preserve its files; instruction language does not choose the business-data storage language.

Audience: Owner and Property Manager (PO/PM) workflows only. Tenant and SP Skills are not available. Confirm the caller's intended PO/PM workflow; managed Tenant profiles do not create Tenant logins or grant access.

The user communicates with their own agent throughout setup. Open a secure browser/credentials panel when authentication requires it, then return to the same conversation. Installing a Skill is not proof that account access works.

## Resumable Workflow

1. Read the first-party installation manifest at `https://handout.us/oauth/agent-setup`. Validate that returned endpoints belong to Handout before using them. It exposes public configuration only, not user credentials or account state. If unavailable, use existing standard OAuth discovery at `https://handout.us/.well-known/oauth-authorization-server` and explain which setup information is unverified.
2. Ask which agent/client is being connected and whether the user needs read-only or read/write access. Prefer OAuth with PKCE S256 when the host supports it. Do not assume read/write permission from a prior read-only connection.
3. Configure the exact MCP endpoint: `https://handout.us/mcp`, or `https://handout.us/query-mcp` for the query-only connection. Muse manual OAuth setup uses the public Client ID from the installation manifest, not the user's API key. Use registered callback metadata and the resource matching the chosen endpoint.
4. Let the host client manage authorization code, PKCE verifier, access/refresh tokens and storage. Ask the user to sign in and approve consent in the secure browser. For the API-key alternative, have the user enter their Handout key directly in secure connector settings as Bearer/API-key authentication; never request or display it in chat.
5. Pause here while awaiting the user or host authentication. Record only non-sensitive progress such as chosen endpoint, method, permissions and the completed step. Resume at the unfinished step after checking the current manifest; never reuse a consumed authorization code.
6. After authentication, request `me.get` through the configured MCP client to verify identity and available capabilities. Only query business records needed for the user's requested task; installation alone is not permission to browse a portfolio. Report verification, not merely that a key was created or an authorization page opened.
7. Select the requested PO/PM business Skill from the manifest's `skill_catalog`, checking its `audience`, description/tools and the user's actual request. Options cover property records, access/handover, account/support, import and the owner/manager workspace. Install only the needed workflows. When file installation is supported, fetch the entry's declared `files` from first-party URLs and preserve relative paths, including references. Otherwise read the selected instructions as guidance and say so. For older manifests use the existing `skills` URL list. Report installation only with host confirmation; instructions never grant access. Business changes require preview and explicit confirmation.

## Recover Simple Errors

Read the structured `diagnostic` extension in MCP/OAuth errors when the host exposes it. Check stage, field, reason, repair class and support reference. Preserve existing MCP and OAuth error semantics.

- Correct only deterministic non-sensitive configuration mismatches against the trusted manifest: the original endpoint path, required headers, fixed resource or supported response/grant type. Do not change the account, target resource, permissions, callback or authentication security to make a request pass.
- Bearer formatting is corrected within the client's secure credentials layer, not by exposing the key to the model.
- Retry a corrected request at most twice; if the same problem persists, stop and report its support reference. For rate limits, respect Retry-After. Token exchange/refresh with an uncertain outcome cannot be blindly replayed because codes and refresh tokens are single-use.
- Invalid/expired/revoked credentials, missing consent, permission increases, unsupported PKCE and callback mismatches require user action or service support. Never automatically revoke keys, create replacement credentials, weaken security or ask the user to delete all connectors.
- Some clients hide OAuth errors inside their secure settings. If only a generic error is visible, say the root cause is unknown; guide the user to the Handout connection page or support reference rather than inventing a cause.

## Continue or Start Again

The user may continue the previous setup or start again. Restart resets only this setup's non-sensitive progress. It does not remove, revoke or modify earlier successful connections. Confirm any new credential creation with the user; preserve the host's successful result instead of generating duplicate keys on retries.

One connection's failure does not invalidate another. Handout shows each user's own connections, prioritizing still-valid connections with recorded successful requests. The actual client request must authenticate with its own credential; never substitute another credential to bypass revocation.

Keep source identity and outcomes factual. Do not claim a Skill is installed without host confirmation, OAuth works without successful authenticated verification, or that another user's connection is available. Keep diagnostics free of passwords, tokens, authorization codes and raw request payloads.

## Hand Off to an Event-Driven Workflow

Once connected, the user can describe what happened rather than name an API: "the plumber fixed the leak", "rent arrived", or "this tenant renewed". Route to the selected PO/PM Skill to resolve records, prepare App-shaped data and show a text confirmation; do not ask the user to learn field names or submit a raw JSON form.

Distinguish configured, authenticated, requested business operation completed and Skill installed. Report the last proven step and next action. A missing tool can mean this connection is read-only, restricted or on an older server; inspect capabilities before diagnosing it as a failed installation. A new PO/PM user may have no property yet; do not fabricate one just to verify a connection.