Playbooks and versions

A playbook is a logical container with an owning account, access: { visibility, grants }, an optional official alias, latest version, and archive state. Its actual content lives in immutable versions, so a title or step change always creates a new historical fact instead of rewriting the definition used by past work.

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.

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.

Definition

A version contains schemaVersion, title, description, one category, an input schema, and an ordered list of steps. Categories are productivity, programming, design, sales, marketing, operations, and learning.

The input schema is JSON Schema Draft 2020-12 with an object root. It describes accepted case input; it does not cause Epismo to execute the playbook.

Each step has:

Steps do not have status, assignees, transitions, retry policy, dependencies, or completion timestamps. An agent may skip, combine, reorder, or extend them.

Publishing and identity

Creating a playbook creates the container and version 1 atomically. Publishing another version requires baseVersionId. If the latest version changed, publication fails with a conflict instead of overwriting concurrent work.

The server normalizes a definition, stores canonical JSON, and calculates a sha256: digest. Equivalent JSON or YAML formatting produces the same content identity. A case pinned to a version stores its version ID and digest so the guidance it started with remains verifiable.

New steps omit IDs; the server assigns them. Preserve an existing ID only when the step is the same logical step. Removed IDs are not reused.

Archiving versions

An owner manager can archive a historical version from its detail page, the CLI, MCP, or the HTTP API. Archived versions disappear from normal lists, direct reads, and new case starts. Their numbers are never reused: if version 2 is archived after versions 1–3 were published, the visible history is versions 1 and 3, and the next publication is version 4.

The latest version cannot be archived because it remains the playbook's current definition and the base for drafts and future publications. Existing cases keep their pinned version reference and continue to operate, but the archived version's content is no longer exposed through normal reads.

Drafts

A playbook has at most one draft: mutable, unpublished content that anyone with edit access can save any number of times without minting a version. Each save takes the revision last read (0 for a first draft); a stale revision is rejected, the same discipline as a base-version conflict on publish.

A draft follows playbook edit access: explicit editors and owner managers can read and edit it, while public readers and share links cannot. Publishing a draft mints a new version from its content and discards the draft in the same step; discarding it directly leaves the published version untouched.

Discovery and references

Search readable playbooks by text and category, or browse the web catalog by resource kind and normalized resource reference. The catalog groups equivalent GitHub and npm URL and provider-specific forms together, while keeping resource kinds separate. A playbook owner (or manager of its owning workspace) can give it one current alias after setting a public handle. Share it as pb:handle/alias. An alias never grants access and always points to the logical playbook, not one version. Existing bare pb:alias references remain available for local use, but are not suitable for sharing. Aliases created by readers before the owner-only rule remain resolvable but cannot be created again.

When ownership moves, the former owner's alias keeps resolving to the playbook until that namespace reuses the name for another playbook or deletes it. If the destination has a public handle and the name is unused there, that name becomes its current alias automatically. Existing destination aliases are never overwritten. Only the new owner's alias is shown as the current reference. Deleting or changing a public handle makes references with the old handle stop resolving to your playbooks; if someone else claims that handle, those references may point elsewhere. Aliases remain stored and become shareable again under a new handle.

Share URLs redirect to the playbook page; current playbook access still applies, so the URL alone does not grant read access. Public playbooks expose their instructions and resource hints, so remove secrets, signed URLs, internal-only references, and personal data before setting visibility to public.

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.

Ownership, responsibility, and lifecycle

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.