# <App name> — App Manual

## Contract

- App ID: `<app_id>`
- App version: `<semver>`
- Platform contract: `1.0`
- Provider: `<provider or internal>`

`APP_MANIFEST` is the machine-readable source of truth.

## Credentials

List every write-only credential, its provider, and the meanings of **Not
configured**, **Configured**, and **Connected**. State explicitly that values
are resolved from the tenant vault and never returned.

## Exported capabilities

For every capability document:

- versioned action and capability name;
- authorization scope;
- input and output examples;
- timeout, side effects, idempotency, and data classification;
- whether the operation is synchronous or queued.

## Error contract

List every stable `error.code`, its HTTP status, retryability, and safe meaning.
Never expose raw provider exceptions, credentials, stack traces, or internal
paths.

## Calling from another app

Document the required `outbound_capabilities` declaration and a
`call_capability()` example. Direct imports and direct app-to-app HTTP calls are
prohibited.

## Calling through HTTP

Document method, gateway endpoint, required JWT scope, headers, request body,
success envelope, error envelope, and `request_id`.

## Security and tenant isolation

Document credential resolution, tenant source, storage namespace, allowed
outbound capabilities, data classification, and redaction rules. Tenant,
subscription, or identity values must come from trusted gateway context, never
from client payloads.

## Observability

Document structured event names, log location, safe fields, redacted fields,
support-reference behavior, metrics, and expected health signals.

## Testing and validation

Document:

```text
python scripts/validate_app_contract.py <app_id>
```

Also list contract, credential, tenant-isolation, entitlement, error,
observability, and provider-adapter tests.

## Optional WordPress App Pack

If present, document package ID, signed distribution, shortcode/block/helper
surface, signed `plugin_file`, minimum versions, filesystem negotiation, update,
rollback, revocation behavior, and where customizations belong.
The App Pack must remain optional for capability invocation.

## Versioning and compatibility

State the current SemVer, supported contract major, additive-change policy,
deprecation window, migration requirements, and whether legacy actions remain.