Account catalog provisioning

Agent identity belongs to an account; project context grants visibility, not ownership. The existing six read tools remain compatible. Three MCP write tools (role_put, skill_put, agent_put) create or append complete definitions. They do not dispatch tasks or start providers.

Authorization

Provisioning needs all three: an explicitly consented OAuth agents:write scope, an active owner/admin membership in the authenticated project, and an active account catalog editor grant for the same subject. A project owner does not implicitly control the shared catalog. Scope is neither a default OAuth grant nor a legacy static-token permission. Operators grant/revoke using:

heyaira-admin catalog-editor --account-id ACCOUNT_UUID --subject SUBJECT
heyaira-admin catalog-editor --account-id ACCOUNT_UUID --subject SUBJECT --revoke

No grants are populated automatically by migration 020. Clients need to request and consent to the new scope. Revocation is checked on every write and replay; existing grants/tokens are never widened by the migration. Editor grant commands need the existing privileged administration environment, not a project token.

Versions and retries

Pass spec with stable lowercase slug, name, status (draft, active, or deprecated), and expected_version. Create with version zero and no id; update with the returned identity id and the latest positive version. Updates append a full replacement definition. Slugs cannot change; old versions remain readable. A stale write fails atomically with version_conflict.

Roles include responsibilities, heartbeat_ref, optional source_ref. Skills include description and optional source_ref. Agents include provider, model, reasoning_level, a pinned role_id/role_version, optional soul_ref, and up to 32 distinct skills (skill_id, version). References must exist in the same account. Metadata references are not fetched or executed by provisioning. Heartbeat remains a role reference, not a skill or a scheduler. Store brief metadata and Git references here, not repository contents.

Every write requires a meaningful summary, an idempotency key, and write_context from the verified connection profile. Exact retries return the original result; reusing the key with changed input fails. Keys are scoped to the authenticated project and operation. Concurrent distinct-key updates have exactly one winner. Failed reference validation leaves no orphan identity/version/audit success. Successful writes and retry records commit in one transaction.

The reply contains stable ID, account ID, slug and new version. Use the matching *_get to retrieve the full definition. Agents retain their role/skill versions when those definitions evolve. Read-list status filtering keeps its original v0.1 meaning: latest version matching that status, which can be historical. A consumer deciding whether to execute must validate current availability separately; provisioning alone does not certify executability or model support.