# AGENTS.md - Bippsi

Bippsi provides public discovery, A.I. Certified site tooling, account APIs, and AI Actions. Prefer structured APIs and MCP over HTML scraping.

## Discovery

- Unified site manifest: `https://bippsi.com/bippsi-unified.md`
- MCP: `https://bippsi.com/api/v1/mcp`
- MCP manifest: `https://bippsi.com/.well-known/mcp.json`
- OpenAPI: `https://bippsi.com/openapi.json`
- Human API documentation: `https://bippsi.com/api-docs`

Public discovery tools do not require authentication. User data, writes, scans for owned sites, deployment, and financial state require explicit scoped authority.

## Credentials

- Standard Bippsi API connections use current `bippsi_` credentials for account and app operations.
- AI Action Keys use `bippsi_action_` followed by 64 lowercase hexadecimal characters.
- AI Action Key scopes are `actions:read` and `actions:execute`.
- Never place credentials in URLs, prompts, generated site files, logs, or public repositories.

An AI Action Key is not a general account credential. A standard connection cannot authorize an AI Action unless it also presents the required AI Action Key.

## AI Actions

AI Actions use USD-denominated, app-restricted Action Credits.

- Execution endpoint: `POST https://bippsi.com/api/v1/ai-actions`
- Balance summary: `GET https://bippsi.com/api/v1/ai-actions`
- Merchant configuration: `GET https://bippsi.com/api/v1/ai-actions/config`
- Buyer maximum: `X-Bippsi-Max-Action-USD`
- Money fields: integer `amount_micro_usd` and `price_micro_usd`
- Idempotency: each action uses a stable `action_ref`; retries must preserve it

The merchant authenticates independently through a signed A.I. Certified request or an Action Connector credential. The buyer authenticates with an AI Action Key. A successful merchant response may include an AI Action result; a failed downstream request must use the merchant-authorized refund operation.

Agents must never increase a user's maximum, retry an insufficient balance in a loop, substitute a different site, or convert an Action Key into another authority profile.

## MCP

MCP public tools: `scan_site`, `list_pages`, `get_certification_status`, `get_api_endpoints`, `list_resources`, and `get_resource`.

Standard account tools: `whoami`, `list_sites`, `start_site_scan`, `get_site_scan`, and `deploy_ai_files`.

AI Action Key tool: `get_action_credit_balance` with `actions:read`.

## Safety

- Respect `robots.txt`, rate limits, account context, and capability scopes.
- Do not bypass human verification, reauthentication, consent, or payment limits.
- Do not infer private data from public registry records.
- Treat HTTP 401, 403, 409, 410, 422, and 429 responses as terminal until the human or system state changes.
- On HTTP 402, report the required USD amount and current limit to the user. Do not loop.

Security and privacy reports: `https://bippsi.com/contact`.