# Povento agent integration

## Purpose

Povento helps an authorized agent operate a portfolio through public, account-scoped contracts. It is not a private repository, database, provider, credential, or release shortcut.

## Discover

- Agent discovery: https://povento.com/.well-known/agent.json
- Agent card: https://povento.com/.well-known/agent-card.json
- API catalog: https://povento.com/.well-known/api-catalog
- OpenAPI: https://povento.com/api/developer/openapi
- Connect guide: https://povento.com/mcp/about
- Skill: https://povento.com/skill.md

## Connect

Connect to https://povento.com/mcp. First read https://povento.com/.well-known/oauth-protected-resource/mcp, then follow its OAuth authorization-server metadata. Browser clients use authorization-code OAuth with PKCE S256. Headless clients use the documented device authorization flow. Bearer credentials belong only in the client secure store; never put them in prompts, URLs, logs, or tool arguments.

## Safe workflow

1. Inspect the effective identity and delegated account, project, environment, permissions, and adopted capabilities.
2. For onboarding, search for an existing matching project before registering a new registry-only project.
3. Read the live Launchpad catalog and preflight the requested features.
4. Create a plan and present its exact additions, unchanged state, blockers, provider setup, environment, and confirmation text.
5. Apply only the unchanged plan after explicit human confirmation, with a unique idempotency key for that logical action.
6. If an operation is interrupted or pending, read its existing durable operation/receipt. Do not send a new logical write with a new idempotency key.
7. Finish with the effective scope, what changed, what did not change, what works now, and what remains.

## Capability and release boundaries

- Available, selected, configured, provisioned, verified, and released are distinct states.
- A selected capability remains inert until its documented control-plane and provider prerequisites are satisfied. Unselected capabilities add no navigation, data, jobs, credentials, charges, or provider calls.
- A setup-required result is a handoff, not an invitation to bypass a provider boundary.
- A local test, build, preview, operation receipt, or deployment status is evidence only. Production release requires separately authorized, live-provider, client, and release evidence.

## Supported agent journeys

Use the authenticated MCP contract to read bounded portfolio and project context, discover capability availability, preflight and plan a capability change, apply a confirmed supported plan, and inspect durable operation evidence. Tool availability is determined by the effective delegated scope and the live public contract. Do not infer access from a catalog entry, UI navigation, or prior session.

## Recovery

- Permission or scope problem: request the smallest documented scope; do not switch tenant or identity.
- Stale plan: regenerate it; do not edit or force an old plan.
- Setup required: show the approved server-side setup handoff without asking for secrets.
- Pending operation: read the receipt and reuse its original idempotency key only when the public contract says it is safe.
- Unsupported or planned feature: state the blocker and safe alternative; do not present it as provisionable.