Playbooks

1. Read the teams resource, or call epismo_team_list if resource reads are unavailable, when workspace context matters.
2. Use epismo_playbook_resource_list when a resource kind can narrow the discovery space.
3. Find candidates with epismo_playbook_search; pass resourceKind and resourceRef together for a resource-filtered list, or use a text query instead.
4. Read the latest definition with epismo_playbook_get, which also returns the playbook's open suggestions, recent versions, and aliases in the same read (free for a public playbook, 1 credit otherwise).
5. Pin reproducible work with epismo_playbook_version_get.
6. Validate input and adapt steps into the agent runtime's plan.

A step is not a task. The agent may omit, combine, or reorder steps. Resource hints are candidates, not installation commands; check permission, trust, and credentials before use.

epismo_playbook_create / epismo_playbook_version_publish / epismo_playbook_access_get / epismo_playbook_access_set

Playbooks and cases have an owning user or workspace account (ownerId), which is also the billing home. A personal owner has full rights; current owners and admins exercise ownership rights for a workspace. Other members need explicit user or team grants, or public visibility for published reads. Workspace membership alone grants no resource access. Removing a workspace member clears their direct grants on items owned by that workspace, including archived and completed items. If removal would leave any affected item without an explicit editor, add another user or team editor first, including on completed and archived items. Personal and other-workspace shares remain unchanged. Team and management authority follow current membership. Required SSO applies to members; non-member direct shares use normal Epismo authentication. Cross-workspace team sharing verifies the participation workspace's SSO. Lists use explicit access and supported public visibility; ownership alone does not include an item.

Viewers can read shared content but cannot edit; playbook drafts require editing. Editors may change content and sharing, retain at least one explicit editor when changing grants, and archive or restore. Ownership is required for affiliation transfer, maintainer changes, permanent case deletion, and historical playbook version archival. assignedTo expresses responsibility and never grants rights. A newly selected assignee or maintainer must already have editing access and, for a workspace-owned resource, belong to that workspace. Reassignment preserves sharing; ownership transfer does not automatically add the former owner as an editor.

An authoring surface iterates through a draft instead of publishing every attempt: epismo_playbook_draft_save to save (with baseRevision, not an idempotency key), epismo_playbook_draft_get to read it back, and epismo_playbook_draft_publish or epismo_playbook_draft_discard to finish. A draft follows playbook edit access; public readers and share links cannot read it.

Explicit creation settings and sharing updates use access: { visibility, grants }: restricted/public visibility and user/team UUID or registered user email keys with viewer/editor values. Emails resolve to user UUIDs before saving; responses contain UUID keys. An unregistered email or conflicting roles for the same resolved user rejects the entire write. Updates replace the whole object; preserve unrelated grants and include your own grant if you want to retain it. Owners retain management independently of grants. Assignees and maintainers receive no implicit access. Editors can inspect and replace sharing, retain at least one explicit editor when changing grants, and archive or restore. Ordinary resource JSON omits private grant maps; editors can retrieve the complete settings with access-get. See Access and identity.

Copy a readable published version to adapt it independently. The copy has its own content and versions; it does not inherit sharing, drafts, cases, suggestions, aliases, stars, or history, and edits never synchronize. Choose sharing explicitly; omit ownerId to use the active workspace or personal home. copiedFrom records the immediate source and immutable source version; sourceAccessible indicates whether the source remains readable. Copy lists show only readable copies. Copying costs the normal playbook creation price.

epismo_playbook_copy / epismo_playbook_copies_list

Ownership, responsibility, and lifecycle

Omit ownerId on creation or copy to use the active workspace, or your personal account when no workspace is selected. Supplying it explicitly chooses the home subject to authorization. When a workspace is selected, including a saved connection default, creation requires exactly one of private: true, non-empty teamIds, or access. Personal creation may omit sharing. Team editor access covers the creator without adding a redundant direct grant; an explicitly requested creator grant is preserved. Maintenance and assignment do not replace sharing.

Editors and owners may archive and restore the playbook. List archived playbooks without a text query using archived=true (playbook list --archived or epismo_playbook_search), then restore with playbook restore or epismo_playbook_restore. Versions, sharing, and maintenance are preserved. Owners can change responsibility with playbook assign --assigned-to or epismo_playbook_assign; this grants no access. Historical version archival remains ownership-only, and the latest version cannot be archived.

In the Web Archived playbooks view, an owner can permanently delete an archived playbook only when no case references it (including completed or archived cases) and no other playbook was copied from it. This cannot be undone. CLI and MCP archive/restore operations do not perform permanent deletion.

Suggestions belong to their live parent playbook and have no separate owner or sharing snapshot. authorId records who created the proposal; baseVersionId preserves the immutable content reference for evaluating it. Reading requires current parent access; an archived parent hides its suggestions until restored. Authors may edit their open proposals while retaining parent access; current playbook editors may adopt or decline proposals. After a transfer, existing proposals follow the parent’s current sharing. Publish the result before marking a proposal applied.

Playbook assignment uses assignedTo, just like case assignment, and uses the same assignedTo field in responses. Use epismo_playbook_assign, playbook assign <playbook-id> --assigned-to <user-id>, or PATCH /v1/playbooks/{playbookId}/assignee. Ownership is required; the target must already be able to edit.