# Platform Surfaces v1 Draft

The gateway capability contract is the source of truth. Inter-app, WordPress,
and agent surfaces must delegate to it and must not execute a zone adapter or
worker route directly.

## Capability naming

Domain capabilities use `aroflo.<zone>.<operation>`, for example:

- `aroflo.users.search`
- `aroflo.timesheets.list`
- `aroflo.timesheets.create`
- `aroflo.tasks.get`

One Standard v1 action may initially dispatch normalized operations, but agent
tools are exposed as specific semantic capabilities rather than one unrestricted
generic executor.

## WordPress

The App Pack will expose:

```php
ams_aroflo_operation(array $request);
ams_aroflo_query(string $zone, array $options = array());
ams_aroflo_get(string $zone, string $record_id, array $options = array());
ams_aroflo_create(string $zone, array $data, array $options = array());
ams_aroflo_update(string $zone, string $record_id, array $data, array $options = array());
ams_aroflo_delete(string $zone, string $record_id, array $options = array());
ams_aroflo_job_status(string $job_id);
```

REST routes delegate to the same helpers. WordPress permissions map to platform
permissions per capability. Secrets, raw provider payloads, BOT selectors, and
worker URLs never cross this surface.

Shortcodes are consumers of the PHP helpers. They are examples and diagnostics,
not alternate connector implementations.

## Platform agent

The legacy connector-specific agent is not an official surface. Tools are
generated by `platform.agents.tool_catalog` from `AgentCapabilityContract`.

Read tools may use confirmation `never`. Reversible writes use `policy`; deletes
and material business changes use `always`. A tool declares a closed schema,
stable errors, permission, risk, classification, timeout, idempotency, and
transport-independent normalized output.

The agent discovers compact domain metadata first and loads full tool schemas
only for relevant capabilities. Cross-zone relationships use canonical fields
such as `user_id`, `task_id`, and `timesheet_id`; the agent never needs connector
source code or all zone schemas in context.

## Transport policy

- `auto`: choose the operation's preferred available transport.
- `api`: require the official API.
- `bot`: require an eligible online BOT assigned to the zone.

Fallback is operation-specific, never implicit for writes, and recorded in
result metadata. BOT operations may return `accepted` plus `job_id`. Availability
states are `offline`, `connecting`, `mfa_required`, `online`, `busy`, `degraded`,
`expired`, and `error`.

## Stable errors

The initial error vocabulary is:

`invalid_input`, `unsupported_zone`, `unsupported_operation`,
`unsupported_filter`, `transport_unavailable`, `api_unavailable`,
`bot_unavailable`, `bot_busy`, `mfa_required`, `confirmation_required`,
`idempotency_required`, `permission_denied`, `provider_invalid_response`,
`job_not_found`, and `operation_failed`.