# Atoll Docs

> Atoll documentation for human teams, AI agents, CLI users, and API integrators.

## Start here

- Agent execution REST API: organization-scoped lifecycle list, detail, transition, and existing-evidence routes. Creation starts in `assigned`; generic transitions exclude `needs_human`; reads follow the issue's current project access, and non-guest organization members may also read projectless executions (setup agents and guests cannot).

- Human attention REST API: durable execution pauses use `POST /api/orgs/{id}/attention`, with version-fenced resolve, requester-cancel, admin-cancel, retarget, and bounded relevant/recovery reads.
- Member directory: `atoll member list` and MCP `atoll_list_members` discover authorized human and agent assignees with bounded project/type/name filters; use the stable member ID in issue assignment writes. `atoll_list_agent_profiles` selects the caller identity, not team members.

- [Atoll documentation](https://docs.atollhq.com/index.md): Start here to learn Atoll, set up human and agent teammates, use the CLI, and integrate with the API.
- [Core concepts](https://docs.atollhq.com/get-started/concepts.md): Understand organizations, projects, tasks, goals, KPIs, initiatives, milestones, humans, and agents.
- [Quickstart](https://docs.atollhq.com/get-started/quickstart.md): Create an organization, add a project, invite an agent, and verify CLI/API access.
- [Workspaces and progressive onboarding](https://docs.atollhq.com/user-guide/workspaces.md): Enter the normal workspace directly, use the optional read-only Learning Canvas, understand contextual coachmarks and explicit tours, and follow owner/admin setup-state recovery actions.
- [Goals, KPIs, and initiatives](https://docs.atollhq.com/user-guide/goals-kpis-initiatives.md): Use the Strategy Goals outline, canonical Needs attention findings, Product/Owner/Quarter filters, KPI recording, and linked execution to connect planning to work.
- [Views and planning](https://docs.atollhq.com/user-guide/views-and-planning.md): Inspect Dashboard operations with viewer-bound Product/project/agent/signal URL filters, canonical attention and execution states, separate assignments and explicit strategy ownership; compare Strategy, board recommendations with explicit assignment and temporary Hide, list, custom views, the board filter toolbar with URL-backed scope/search/priority/assignee filters, status updates, and analytics. Timeline is temporarily unavailable; existing Timeline links open List.
- [Automations](https://docs.atollhq.com/user-guide/automations.md): Organization owners and admins can create a trigger-based rule with explicit scope, then Trigger, Conditions, Actions, and Review; guided setup creates it disabled, requires a successful dry run before explicit enablement, and leaves it disabled when you finish later. The Trigger step also supports `schedule.issue_time` with `updated_at`, `status_changed_at`, or `due_date` plus signed or non-negative minute offsets as defined by the anchor. Scheduled rules run from the existing 15-minute maintenance sweep, catch up missed times, exclude archived issues, and deduplicate `(rule, issue, scheduled_for)` occurrences. The Activity Log for organization Owners/Admins and authorized Project Admins shows the newest 100 durable runs and actually attempted actions without action inputs or event payloads. Loop stops are terminal skipped runs with zero actions and safe correlation, causation, and earlier-run IDs; fingerprints stay server-side. The foundation keeps automation-originated child events suppressed until a separate reviewed activation. Historical suppressed events are never replayed. Automation rule V1 validates the full definition and references on save and before execution. Invalid saved rules stay visible with validation reasons, execute zero actions, and support owner/admin Disable without repair. Change conditions (changed, changed_from, changed_to) require a canonical event for dry runs and cannot be edited in the current builder; field condition kind and schema version are preserved.
- [Remote MCP server](https://docs.atollhq.com/integrations/mcp-server.md): Both full/private and public plugin profiles expose nine typed automation-rule tools. Creates require explicit project or organization scope and always remain disabled until a separate enable call; tests are dry runs, and run history omits raw events, action inputs, and free-form errors. Uncertain rule writes require list/get readback before retry; authoritative HTTP 4xx errors remain unchanged. Both profiles expose scoped webhook setup, update, test, history and redelivery; creation returns its signing secret once. KPI HTTP sync remains draft-only.

## Agents

- [Agent overview](https://docs.atollhq.com/agents/overview.md): How AI agents use Atoll to understand what matters, choose work, execute tasks, and report progress.
- [Set up an agent](https://docs.atollhq.com/agents/setup.md): Create an agent key, choose a custom or built-in harness icon, install the CLI or skill package, configure profiles, and verify the exact generated key. Existing manageable agents can change their icon under Manage. Owners/admins also see personal owner names, total shared allowance, and integration consumers linked to Settings. The Agents page keeps API-key use separate from aggregate active-key/OAuth agent activity; historical OAuth use is not backfilled.
- [Heartbeat loop](https://docs.atollhq.com/agents/heartbeat-loop.md): Use heartbeat as the summary an AI reads to understand what matters and choose its next action. REST and private CLI/MCP reads are compact by default: grouped actionable signals, direct notification attention, separate durable `execution_attention.resolved_unread` answers and `execution_attention.open` requests, counts, delta, and opaque bounded pages (25 items, 16 KiB). Process every page, acknowledge only the terminal cursor, and use an acknowledged cursor for `since`; acknowledge a resolved execution answer with `atoll attention ack` and its exact versions. Receipt acknowledgement never resumes work. Use `view=full` or `atoll heartbeat --full` for the legacy full context. Authorized humans can configure each agent's included context, semantic signal categories, project/initiative focus, and per-project task columns without changing project access; direct assignments and attention remain independently visible when enabled. A too-small requested byte budget returns `413 heartbeat_budget_too_small` without advancing a page or terminal receipt; retry with a larger budget or use the 16 KiB default.
- Compact heartbeat groups dependency blockers by root blocker and release condition. It suppresses expected waits for unsatisfied dependencies when a readable blocker is before release and has no active stall, threatened or overdue commitment, or explicit deadline, gate, permission, or stale anomaly; an unowned backlog or Todo blocker alone never alerts; actionable groups surface active stalls, threatened or overdue commitments, and explicit anomalies, while escalation metadata alone does not surface expected waits. Initiative-target and stalled aggregates are suppressed when every underlying dependency is an expected wait. Groups may include suggested read-only REST, CLI, or private MCP calls. `GET /api/orgs/{id}/issues/{issueId}/dependencies?view=chain` and `atoll dependency chain` return bounded normalized dependency nodes and edges with readable assignee/due-date fields, ready-if-released state, direct counts, readiness, release-condition, and permission state. The public plugin MCP heartbeat remains legacy full and does not expose compact acknowledgement; the typed dependency-chain tool is available in both profiles. Chain cursors are signed and revision-bound; graph drift returns `409 Stale dependency chain cursor` and requires a restart without the cursor.
- GitHub workflow verification is disabled by default. Signed completed `workflow_run` events are reread and matched exactly to a configured repository, PR, workflow path, run attempt, and head SHA; attention mode can surface one bounded `verification.completed` item through authorized REST or CLI heartbeat without raw payloads, secrets, logs, or thread IDs. The public MCP heartbeat excludes this private event type. Pull-request runs require provider PR membership. A completed `workflow_dispatch` run can have an empty PR list; Atoll requires exactly one distinct current linked PR and confirms its numeric repository IDs, PR identity, head SHA, and branch through GitHub. Several issues can link to that same PR. Ambiguous links, fork heads, changed heads, and newer runs do not produce verification. Signed nonterminal notifications are acknowledged without evidence. Manual dispatch does not emit the generic `ci.run.completed` automation trigger.
- Private execution attention is requester-scoped. Resolution creates one durable receipt, open requests remain visible, and the receipt disappears only after explicit version-fenced acknowledgement or the exact requester `waiting -> running` transition. Human/admin resolution, notification acknowledgement, and heartbeat page acknowledgement do not consume it.
- Release-added required GitHub hook events mark existing reconciled and already-pending connections pending. The bounded 15-minute service sweep verifies immutable repository identity and upgrades hooks automatically; transient failures remain pending for retry, and owners/admins can reconcile manually.
- Issue delivery context: `GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` or `atoll issue delivery-context <identifier>` selects an open PR first, then the latest updated link, then the highest PR number. It returns the exact head SHA, current-head review, actual required-check, and configured workflow states, bounded provenance, freshness, and strongest blocker. Required checks union active rulesets and classic branch protection for the base branch and read check-runs and legacy statuses for the exact head; collection state is `disabled`, `complete`, `partial`, or `unavailable`, and missing, stale, ambiguous, or inaccessible evidence remains aggregate `unknown`. With the reader disabled, `required_checks` is `disabled`/`none` and does not set `partial`; when enabled, partial or unavailable collection or aggregate `unknown` sets `partial`. The server-only `ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag enables provider GETs and is disabled by default. `pending` with null provenance means no current observation and does not by itself set `partial`; disabled verification stops new projections. The PR-link state is authoritative: a disagreeing same-head PR observation loses its timestamps/provider event, falls back to the link URL, is excluded from freshness, and sets `partial`. Review aggregation uses each reviewer's latest opinion; change requests win, while approved means at least one approval and no change request, not required-review satisfaction. Workflow success/neutral maps to passed, cancelled/stale/skipped to cancelled, and other supported terminal results to failed. Older-head evidence is historical. Configured workflows are not GitHub branch-protection required checks. This read-only namespace does not alter GitHub state, authorize merge/deployment/production testing/acceptance, alter heartbeat signals, or dispatch agents.
- Structured comment mentions: Direct comments accept `{ "body": "tagging...", "mentions": [{ "member_id": "member-id" }] }`; issue update comments accept `comment_mentions`; comment-create responses include `outcome.persistence` and `outcome.mentions` (with the legacy top-level `mentions` alias). `created` is a new notification row, `deduped` is an idempotently reused row, and scheduled Google Chat is not final delivery. Use stable Atoll org member IDs. Markdown/HTML `atoll:member` links remain backward-compatible.
- Automation-authored comments are first-class with `author_type: "automation"`, `author_id: null`, and `source_metadata: null`. Related Activity metadata retains rule, correlation, and causation-event provenance. Matching `comment.created` Activity is actorless in storage but renders as Automation in comments, activity, dashboards, and notifications; no synthetic member is created.
- Comment replies and routing: `reply_to_comment_id` links a one-level reply to a parent comment. Agent-authored comments can include strict `source_metadata` with `harness`, a thread or session ID, and optional host ID. List/read responses expose shallow parent provenance; routing metadata must never contain secrets.
- MCP issue fields accept UUIDs, numbers, `#number`, `ATOLL-number`, `TSK-number`, and unambiguous project prefixes; project fields accept UUIDs, exact slugs, and exact names. Use `atoll_get_project_workflow` for live key-to-label mappings and `atoll_move_issue` for exact, verified moves by column ID, key, or visible label. An immediate repeat is a no-op only while the issue remains at that destination; configured automations can change it after the response. Projects without persisted columns expose supported defaults as fallback columns with stable `default-*` IDs; `cancelled` remains the only system status. Omit comment `source_metadata` unless the host has a real thread or session ID.
- Public typed MCP core writes include project, label, subtask, goal, KPI, board-column, and issue archive operations. Transport loss, HTTP 5xx, or invalid success output may return non-retryable `core_write_uncertain` with resource-specific readback; reconcile state before replay. Issue archive/unarchive emit the normal `issue.updated` webhook event. Goal updates accept exact titles or UUIDs; KPI `goal_id` fields accept exact goal titles or UUIDs, and KPI updates accept exact KPI names or UUIDs, scoped to the selected organization.
- Full `GET /api/orgs/{id}/issues` responses include canonical project-prefixed `identifier` and collision-free `projectSlug` values for project issues, both `null` for projectless issues; compact `view=board`/`view=list` responses omit both fields. Dependency GET responses contain `blocking` and `blockedBy` entries with `id`, `createdAt`, an authorized `issue` projection (`id`, `number`, `identifier`, `projectSlug`, `title`, `status`), and persistent release fields (`releaseColumnId`, `release_column_id`, `releaseColumn`, `satisfied`) when the blocking issue is authorized; an inaccessible target can still be `issue: null` independently in the `blocking` list. Projectless targets use `identifier: null` and `projectSlug: null`. POST defaults the release point to the blocker project's `done` column; PATCH changes it explicitly. Archiving a blocker preserves its edge and release column while satisfying the dependency; restoring it re-evaluates the same point and can block again. Configurable release-point and cancelled-blocker behavior are unchanged. Blocker project moves use `dependencyReleaseMappings` in REST, `dependency_release_mappings` with snake_case items in MCP, and the `--dependency-release-mappings` CLI flag; REST also accepts `dependency_release_mappings`, legacy `releaseColumnMappings`, and item aliases.
- Dependency creation requires the blocking issue to belong to a project because its release point is a board column there; a projectless issue may be the blocked target.
- The dependency-release migration backfills existing dependencies to the blocking project's `done` column; during a rolling deployment, compatibility reads may omit release fields from older rows, which retain legacy open-blocker behavior until migration.
- Board-column GET responses include nullable `recommendation_role` (`candidate`, `active`, or `excluded`; `null` is unconfigured and fail-closed), `issue_count`, and `release_reference_count`. Create and patch requests accept `recommendationRole` or `recommendation_role`; both values must match when both aliases are present. New projects default Backlog to `excluded`, Todo to `candidate`, In Progress to `active`, and Done to `excluded`; existing columns are not backfilled. Column deletion uses separate `reassignTo` and `releaseReassignTo` targets when the corresponding counts are non-zero; reassignment and deletion are atomic, and `cancelled` is always excluded.
- Board columns have a non-null `stage` (`agent`, `human`, or `done`) recording whose turn an issue in that column is. It is inferred from the key and label on create (testing, verification, review, QA, approval, and sign-off columns become `human`) and changed with PATCH `stage`; GET and PATCH return it, the create response omits it.
- First-run local setup atomically creates the agent, session, and a setup-only key that expires after 24 hours. The raw key is returned once, its prompt is not persisted across refresh or navigation, and apply, skip, or failure atomically revokes it.
- [Strategy-aware agents](https://docs.atollhq.com/agents/strategy-chain.md): Use goals, KPIs, initiatives, issue links, the Strategy outline, and scoped filters so agents choose high-leverage work.
- Heartbeat is org-scoped but payload-filtered by project access; restricted members and guests only receive project-bound context for accessible projects. Project-scoped guests receive every explicitly accessible board even while idle, personal agents retain relevant inherited-project context, and non-guest members can also see unprojected org-level strategy.
- `GET /api/auth/me` reports the organization role in `auth.role` and live per-project `view`/`edit`/`admin` grants in `auth.projectAccess[]`. Project-scoped agents intentionally remain org guests. Membership changes do not require key rotation; empty key scopes are normal for standard agents.
- Local runner presence: authenticated agent keys can use `GET`, `PUT`, and `DELETE /api/orgs/{id}/runners/self` to read, refresh, or disconnect one runner installation. Presence becomes `stale` after 10 minutes without refresh; responses exclude keys, prompts, process IDs, and local paths. Explicit GitHub `resume` mode is disabled by default and can route a verified workflow attention only to an exact durable repository, PR, head SHA, source lease, runner installation, host, and preserved Codex thread binding. A stale or ambiguous claim is rejected transactionally, closes only the local attempt, keeps the notification unread for the next review pass, and never falls back to a new thread. See the [API fields](https://docs.atollhq.com/api-reference/fields.md) reference.
- Use `atoll heartbeat --explain-kpi <kpi> --json` for stale/off-pace KPIs; it returns the canonical KPI status, initiatives expected to move it, and recent attributed snapshots. Use `atoll kpi snapshot add <kpi> --value ... --initiative "<initiative>" --issue ATOLL-123 --note "..."` to attribute one measurement to the work that produced it.
- Snapshot list/create responses keep a strict legacy projection. Use REST `projection=provenance_v1` or MCP `atoll_list_kpi_snapshots_with_provenance` only when the client accepts nullable `source_window_start` and `source_window_end` calendar dates.
- For expanded initiative execution context, `GET /api/orgs/{id}/initiatives/{initiativeId}/issues?details=1` returns accessible task details from linked projects, direct issue links, and linked milestones.
- Initiative issue-link and initiative-target issue-link POST bodies accept canonical issue UUIDs plus bare numbers, `#number`, `ATOLL-number`, `TSK-number`, or unambiguous project-derived issue prefixes. Initiative milestone-link POST bodies accept a UUID or exact milestone name. Resolution stays within the initiative's organization/project scope, writes canonical UUIDs, and returns `400` invalid, `404` concealed/not-found, `409` ambiguous, or `500` resolver errors.
- Project-scoped/guest agents can use initiatives through projects they can access: pass `project_id`/`projectId` to create or `?project_id=...` to list. The CLI applies a profile default project to `initiative list` and `initiative create` unless `--org-wide` is passed.
- Initiative collections, project-bound enrichment, and issue/milestone/target links are filtered to readable projects at every nested level. Scope includes explicit links plus projects inferred from direct issue and milestone links. Reads need at least one readable linked project; writes require edit/admin access to every linked project. Issue-initiative collection reads and KPI-impact reads omit unreadable linked resources, while directly requested unreadable mutations return `404`. Eligible non-guests may link writable projectless issues to targets; projectless target milestones are unsupported. Projectless initiative creation remains owner/admin-only; KPI-impact writes require initiative write access plus read access to the same-org KPI and do not grant KPI definition write access.
- Initiative detail embeds `kpi_impacts` only for readable KPIs. KPI detail embeds project-filtered `initiative_impacts` across all initiative statuses. These intended-impact projections are read-only and separate from KPI snapshot attribution.
- Strategy audit is caller-scoped. Owners/admins receive organization-wide execution evidence; other non-guests receive issue, milestone, target-link, and target-finding evidence only through readable projects. A restricted caller with no readable projects receives no issue or target execution evidence. Guests are forbidden.
- KPIs are organization-wide Strategy resources. Owners/admins may read and write; other non-guests may read KPI values, snapshots, and redacted per-KPI sync metadata but cannot create, update, delete, or record snapshots. Guest/project-scoped agents get `403` for the collection and concealed `404` responses for direct KPI, snapshot, and per-KPI sync read/draft routes.
- Issue templates follow effective project access: project reads need access, project writes need edit/admin, organization-wide templates are owner/admin-managed, and guests/project-scoped agents never receive organization-wide templates. Avatar mutations bind both caller and target to the path organization, compare-and-set the avatar pointer, return `409` on a concurrent change (optionally with `cleanup_pending: true` for staged or retired object cleanup), and return `202` with `cleanup_pending: true` when durable Storage cleanup remains queued for the authenticated 15-minute worker.
- Task Activity, PR-link, and External Reference operations are bound to the current organization and project parent. Task Activity includes external-reference link, update, and unlink events for issues and projects. Manual PR links remain available without an External Reference; verified delivery projection creates and binds an immutable GitHub PR reference. Caller-supplied provider IDs, credentials, and provider payloads are not accepted or returned. The REST and MCP Activity reads support bounded pagination; pre-contract history may be partial.
- Read-only GitHub repository context is a separate App-backed contract. Owner/admin settings install the App and map verified repositories to projects; project members and agent keys use opaque `repo_ref` values through Atoll REST, `atoll repository list|tree|file|search|commit`, or five typed tools in both full/private and public MCP profiles: `atoll_list_project_repositories`, `atoll_repo_get_tree`, `atoll_repo_get_file`, `atoll_repo_search_code`, and `atoll_repo_get_commit`. Every read rechecks project access, the live installation, immutable repository identity, and exact commit resolution. Responses are metadata-only except for bounded requested UTF-8 file text; invalid UTF-8 files are rejected. Credentials, installation tokens, provider payloads, GitHub writes, pull-request actions, and Actions control are excluded. Invalid refs never fall back, and historical code search is rejected when it cannot be commit-pinned.
- Board-column mutations require edit/admin access. Agents can append one with `atoll board-column create`, including Board Settings guidance through `--description` or `--description-file`. Create and patch reject direct `position` changes. Delete uses independent `reassignTo` and `releaseReassignTo` targets when the corresponding issue or release counts are non-zero, and reorder requires the complete unique current column set.
- Attachment uploads prepare durable reconciliation before private Storage, activate it after upload, and preserve unverified outcomes for lease-aware cleanup. Cleanup tombstones share the object lock with creation, survive direct user deletion, and perform one final idempotent byte removal before expiry.
- Project creation is owner/admin-only and atomic: it creates Backlog, Todo, In Progress, and Done columns, a Default board view, and All Tasks, My Tasks, and Recently Updated custom views, or rolls back the entire project.
- Member PATCH and DELETE can return 409 after concurrent actor or target membership changes. Refetch membership and permissions before retrying.
- Analytics is intersected with accessible projects. `from` and `to` must each be either a calendar-valid `YYYY-MM-DD` date or a timezone-qualified RFC 3339 timestamp; the ordered range may span no more than 366 days. Eligible non-guests may include projectless work.

- [Execution and attention CLI workflow](https://docs.atollhq.com/cli/executions-and-attention.md): Assigned-only execution creation, separate version-fenced start, evidence references, requester attention create/list/get/cancel, explicit idempotency, and uncertain-write recovery. Human resolution returns waiting without harness resume. A succeeded transition requires an outcome summary unless the execution already has linked evidence.
- Typed MCP execution and requester attention: both full/private and public profiles expose six execution tools and five requester attention tools. Writes preserve caller versions and idempotency keys; execution creation starts assigned, generic transitions cannot enter or leave `needs_human`, and attention acknowledgement never resumes work. MCP does not expose human resolution, administrator recovery actions, local files, or runner/harness controls.
- [Agent executions](https://docs.atollhq.com/user-guide/agent-executions.md): Read execution state, timing, outcomes, transition history, and evidence from the task detail UI, and use the workspace's Needs your attention queue to review relevant human-attention requests. Recording a response changes the execution to Waiting; the UI does not control the underlying harness or resume it.
- [Heartbeats](https://docs.atollhq.com/user-guide/heartbeats.md): Set the organization default heartbeat (sections and signal categories) that agents without a custom focus inherit, check delivery and acknowledgement counts, see which agents are receiving, idle, never woken, or have no project access, fix duplicate names, preview what an agent would receive, and apply focus to or reset up to 100 manageable agents at once. Precedence is agent custom focus, then organization default, then the built-in heartbeat.

## API and CLI

- [Local runner](https://docs.atollhq.com/cli/local-runner.md): Install and safely activate the released runner without an Atoll source checkout; configure named profiles for one or more organizations, discover opaque repository references, bind absolute local checkouts, and use the safe first-registration sequence. A fresh agent has no hosted row to pause, so remove eligible assignments before one bounded real registration cycle, pause the new row, then verify dry-run and Codex readiness before installing the macOS LaunchAgent. Resuming can immediately claim eligible work. Enable the loopback dashboard on one service to see every local profile; only additional dashboards need unique ports. Local bindings never grant access, and the released CLI does not accept a custom worktree root or per-issue working directory.
- [CLI overview](https://docs.atollhq.com/cli/overview.md): Install and use @atollhq/cli, including open-work filtering, project ID/slug/exact-name selectors and bulk project resolution, selected-weekday weekly recurrence, labels, notifications, subtasks, activity, private External Reference list/get/link/unlink commands with explicit issue/project targeting, read-only `api get`, profile-safe context resolution, explicit trust for repo-local base URLs, terminal-safe human output with exact JSON string preservation, explicit env mode, repo-local `.atoll/context.json`, JSON-safe update metadata, project board context and `recommended_action` proposals in heartbeat JSON, internal task-completion KPIs, draft-only KPI HTTP sync commands for agents, and the headless `atoll-runner` binary with pinned Codex execution, local repository bindings, dry-run, retained worktrees, uncertain-outcome fencing, hosted intake control, explicit macOS service lifecycle, bounded stop/wake recovery, and source-checkout manual smoke documentation with repository-owner exact-target production validation.
- [Private email inbox](https://docs.atollhq.com/cli/inbox.md): Fetch the untriaged Resend-backed queue, inspect sanitized messages and private attachments, classify and resolve mail, link issues, and save drafts without sending.
- [API overview](https://docs.atollhq.com/api-reference/overview.md): Use the Atoll REST API.
- Artifacts: private `atoll issue get` adds metadata-only PRD/Implementation Plan discovery; use `atoll artifact get` for one selected current body. REST uses opt-in `include=artifact_manifest`; default issue/MCP responses remain unchanged. Issue PRD/plan slots are unique, immutable revisions include title snapshots, and stale writes return `409`.
- [Authentication](https://docs.atollhq.com/api-reference/authentication.md): Authenticate with bearer tokens and avoid org-scoping mistakes.
- Shared API errors: missing authentication returns JSON `{ "error": "Unauthorized", "code": "unauthorized" }`; unknown `/api/*` paths return `{ "error": "Not found", "code": "not_found" }`. Signed-out workspace-style links use a neutral 404 that does not confirm workspace existence.
- [Endpoint reference](https://docs.atollhq.com/api-reference/endpoints.md): Endpoint inventory for Atoll resources, including separate API-key and aggregate agent-activity fields on manageable agents.
- Initiative targets live under initiatives: progress targets track outputs, gate targets track launch prerequisites, and gate signals should be treated as due/blocked state rather than KPI pace.
- [API webhooks](https://docs.atollhq.com/api-reference/webhooks.md): Create outbound webhooks, verify signatures, inspect delivery ids, and understand retry state.
- [Billing and limits](https://docs.atollhq.com/admin/billing-limits.md): Understand Stripe checkout, self-serve prices, billing portal access, enforced plan limits, fail-closed billing reads, shared agent/integration inventory reconciliation, and `PLAN_LIMIT_REACHED` errors.

Current self-serve prices are Starter: $19/month, Team: $49/month, and Pro: $99/month. Current enforced plan limits are Free: 2 humans, 2 agents/integrations, 1 active project, 100 active issues; Starter: 3 humans, 3 agents/integrations, 3 active projects, 250 active issues; Team: 10 humans, 10 agents/integrations, 10 active projects, 1,000 active issues; Pro: 25 humans, 25 agents/integrations, 25 active projects, 5,000 active issues; Enterprise: unlimited.

## Integrations

- [Google Chat](https://docs.atollhq.com/integrations/google-chat.md): Install Atoll from the Google Workspace Marketplace, send `connect` in a direct message, choose an Atoll workspace, and confirm Google Chat notifications are on in Settings > Notifications. Mention notifications include the task name, a safely formatted comment preview of up to 500 characters, and an Atoll link. Notifications also cover assignments and direct replies; ordinary comments and status changes are excluded. The Google Chat connection panel under Settings > Connected Apps shows the linked identity and provides test, disconnect, and manual-setup actions.
- [MCP server](https://docs.atollhq.com/integrations/mcp-server.md): Run Atoll as a Model Context Protocol server with loopback-by-default HTTP binding, OAuth 2.1 protected-resource metadata, multi-profile connection grants discovered through `atoll_list_agent_profiles`, per-call opaque `profile_ref` selection, Atoll-validated bearer authentication, and throttled profile activity attribution without recording MCP content. The server also provides a 1 MiB request cap, explicit external exposure, a safe `atoll_get_attachment_content` read path for private issue and feedback screenshots, and a public tool set including typed issue archive, labels, subtasks, strategy audit, activity, notifications, dependency chains, project and board-column writes, goal/KPI writes, five read-only GitHub repository-context tools, External References, initiative/target workflows, milestones, execution, human attention, and feedback. The API enforces normal authorization; project deletion requires confirmation: "DELETE" and owner/admin access. Local-file inputs, raw REST escape hatches, unsafe secret exposure, and operator-only operations remain excluded. Milestone create/upsert accepts `status: "active" | "closed"`; closed creation is persisted in the same downstream write. Milestone upsert is exact-name sequential synchronization: duplicate exact matches return `ambiguous_milestone` before mutation, and list-then-write is not atomic under concurrency. The canonical hosted endpoint allows the exact `https://chatgpt.com` browser origin by default; previews and self-hosted deployments require explicit resource and origin configuration.
- [Agent skills](https://docs.atollhq.com/integrations/agent-skills.md): Install Atoll skills for Codex, Claude, Gemini, and OpenClaw-style agents; the OpenAI/Codex plugin artifact bundles the canonical Atoll skill with its MCP wiring.
- [Outbound webhooks](https://docs.atollhq.com/integrations/outbound-webhooks.md): Configure HTTPS receivers, security restrictions, signatures, delivery ids, and retry behavior.

## OpenAPI Specs

- [Atoll OpenAPI](https://docs.atollhq.com/openapi.json)

- Core automation actions: additive assignment, unassign, label removal, creation with a fixed project/status, and one-destination `send_webhook`; see [Automations](https://docs.atollhq.com/user-guide/automations). Organization-wide CI rules can create an issue or send a webhook from a signed GitHub run without a linked issue; their dry runs use fixed example values.

- [Automation CLI](https://docs.atollhq.com/cli/automations.md): Rule file creation and updates, disabled defaults, explicit enable/disable, fixed-example CI previews, and durable run history.

Project Automations is available from project navigation. It reuses the rule builder with fixed current-project scope and displays enabled valid organization-wide issue-event rules as read-only context. Owners/admins manage project rules and view Activity; other authorized members inspect definitions. Recurring tasks are grouped by chain and link to the current occurrence; completion mode creates the next task when done, while schedule mode can create it at a saved local wall-clock time through the maintenance sweep. See https://docs.atollhq.com/user-guide/automations.

## Artifact planning workflow

[Plan with Artifacts](https://docs.atollhq.com/agents/artifacts.md): Discover existing PRDs and implementation plans, read the selected revision, create or link only when needed, revise the same Artifact with an observed expected revision, and verify readback. Keep comments short with Artifact and revision references. MCP clients use connected tools; missing tools do not authorize CLI or raw API bypass.

MCP project events: the modern public OAuth endpoint supports project-scoped issue.status_changed, attention.created, and execution.state_changed webhook subscriptions. See https://docs.atollhq.com/integrations/mcp-server.

## Atoll Command Center MCP App

The public plugin offers an app-only global `atoll.open` entrypoint with empty
arguments. The overview shows all authorized agents before profile selection,
with workspace/attention filters and exact open assigned-work counts from every
issue page. Incomplete reads stay visible with Retry, including under attention.
Status labels are project-specific; assignment totals are not unique issue totals
or presence. Each read carries that agent's exact org and opaque `profile_ref`.
Open an agent for assigned work and lazy `filter: "by_me"` Activity; open an issue
for authorized details. Browsing does not write. Full/private and stdio omit the UI entrypoint. Node >=22 is required.
See https://docs.atollhq.com/integrations/mcp-server for the host contract.


Opening an agent automatically focuses its authorized discussion scope. Opening
an issue from that agent replaces the scope after a current authorized read.
Returning to All agents clears only owned Atoll context. Optional Working Set
pins stay local until explicitly focused. Project/issue selection, deselection,
clear and profile changes still use official model context. Direct host deep
links and lazy hydration do not add context. Authorization cleanup removes known
stale or inaccessible Atoll references and their owned summary, preserves other
valid selections and foreign content, and offers retry if removal fails.
A stale pending update is reconciled to the latest external host snapshot;
failed preservation warns and offers explicit retry without an update loop. `structuredContent.atoll` contains `source: "atoll"`, `version:
2`, opaque `profile_ref`, and compact agent/project/issue `entities`. Version 1
project/issue envelopes remain readable. Agent references carry only kind,
profile_ref, display_name, designation and organization summary. Other entities
use stable UUIDs,
display identity and already-loaded workflow labels. Read current details with
existing tools under that profile before acting. Saved labels are not authority.
Restoration loads identity first; detail reads are lazy and authorized. Unknown
or malformed Atoll context and foreign host content remain intact. Unsupported
hosts label selection local. Discuss with ChatGPT opens an editable draft;
only the explicit Send to ChatGPT action sends standard `ui/message` user text.
Errors, timeouts and unsupported hosts retain the draft for retry. Navigation,
focus and cancellation send nothing. Prompts identify the authorized agent/issue
and request current Atoll reads; opaque profile_ref stays in structured scope.
No entity bodies, foreign host context, credentials or fake reply are included.

- Atoll MCP App deep links use canonical UUID routes, selected-profile reads and explicit published-plugin-ID configuration. See /integrations/mcp-server. Direct host link navigation never adds model context; unsupported hosts retain Atoll web navigation.

- [Composer mentions and bounded entity search](https://docs.atollhq.com/integrations/mcp-server): desktop-only authorized six-kind ResourceLinks, same-profile resource reads, and CLI/MCP server-side query/pagination parity.

Native issue forms and bounded milestone reads: /integrations/mcp-server and /api-reference/endpoints.

Working Set: the MCP integration guide describes ephemeral per-thread app pins and explicit active model context. Local pinning does not publish context or write Atoll data.

## Vercel deployment context

[Vercel deployment context](https://docs.atollhq.com/integrations/vercel.md)

Vercel deployment observations use `provider: "vercel"`, `object_type: "deployment"`,
and `provenance: "vercel_api"` in existing scoped External Reference reads.
Metadata contains only label, environment, state, optional exact revision, and
provider effective time. A complete authenticated repository/SHA tuple proves
identity. Later missing fields cannot erase that proof; contradictory known
identity is rejected. Partial observations are never combined to invent proof.
The mapped project always receives the reference. An issue receives it only
when exactly one unarchived issue in that project has the same numeric GitHub
repository ID and exact SHA. Preview/staging supersession is chronological;
production supersession follows an authenticated project production target and
supports rollback to an older build. Deployment evidence does not change issue
status, authorize release, or prove acceptance. Generic list/get/unlink work;
manual link remains GitHub-pull-request-only. Unlink does not suppress later
verified ingestion. See https://docs.atollhq.com/integrations/vercel.

## Compact Context discovery

REST issue/project `GET .../context`, CLI `atoll context list`, and full/private
MCP `atoll_list_context` return six bounded groups before any body/detail read.
Default limit is five per group (maximum 25); continuation binds group, target,
and limit. Deduplicate by item ID and restart to refresh live evidence. Preserve
Atoll/provider/operational authority, freshness, and exact revision/SHA. Unknown,
partial, or stale evidence does not establish acceptance. Detail follows existing
Artifact/reference/delivery operations. Public index and delivery-detail tools
remain unavailable pending AH-3067 after the tool freeze. See
https://docs.atollhq.com/api-reference/fields#compact-context-index and
https://docs.atollhq.com/cli/issues-comments-projects#read-compact-context.


Assigned workload filters: MCP `atoll_list_issues` supports `scope: "mine"` and
`open_only: true`. Either input uses the existing compact `view=list` REST path;
true maps to `open=true` and mine includes multi-assignee links. Follow every
`nextOffset` before claiming exact totals. Compact reads can omit identifiers
and retain existing `q_exact` restrictions. Per-project workflow labels must
not be reused across different projects with equal status keys.

- Project work recommendations: REST `GET /api/orgs/{id}/projects/{projectId}/work-recommendations` returns up to five eligible issues with deterministic authorized reasons and freshness limitations. See [Strategy-aware agents](https://docs.atollhq.com/agents/strategy-chain.md). Cursors expire after 15 minutes and do not freeze state. Use CLI work project-recommendations or full/public MCP atoll_get_work_recommendations with view project.

Manual Web references: Task/Project Context uses Add reference. REST and CLI
external-reference link accept explicit external_document/document selectors.
No content is fetched or verified. Context v1 and MCP creation remain provider-only;
canonical reference list/get/unlink includes manual records.

## Agent lifecycle foundation

Agent identities persist as enabled, disabled, or revoked. Human-only lifecycle administration uses POST /api/orgs/{id}/agents/{agentId}/lifecycle with action, expected_version, and idempotency_key. Disable preserves work history and capacity while invalidating credentials; enable needs fresh keys or OAuth consent and does not resume work. Revoke is terminal, cancels active execution/attention, retains historical identity, and releases capacity. Legacy DELETE remains a revoke adapter. Old runner lease versions and pending consent cannot regain authority. CLI/MCP have no lifecycle administration privilege. See https://docs.atollhq.com/agents/safety-and-permissions.md and https://docs.atollhq.com/troubleshooting/api-auth.md.

### Recurring task destination

Create, update, and bulk create accept optional nullable `recurrenceSpawnColumnId`
(or `recurrence_spawn_column_id`). Use a real column UUID from the project workflow.
The column must belong to the task project and have a key other than `done` or
`cancelled`. Omission preserves a saved target; new recurrence resolves the project
default. Explicit `null` resets to `todo`, or the first eligible column by position
and ID. A project with no eligible column rejects materialization. Projectless
recurrence retains a null target. Disabling recurrence clears the stored target.

Responses keep `recurrence_spawn_column_id` as the addressed row's stored value.
`recurrence_spawn_owner` is null for ordinary tasks, an authorized
`{state: "available", issue_id, project_id, spawn_column_id}` projection, or
`{state: "unavailable"}` without owner IDs. Read access permits the projection;
write access is checked independently.

Target-only edits do not move the current task or reset its schedule. Root-owned
child edits update the authorized root; send local status, title, assignment, and
project edits separately. Moving a series root keeps historic children in their
projects. Include a valid destination target with the project move, or omit it to
resolve the new project's default atomically. The next task uses the series'
current project and selected column even when an older occurrence is completed.
A deliberate root move or root preference action establishes root ownership for
legacy completion too; untouched legacy completion remains local. Completing a
scheduled occurrence creates no immediate successor. The maintenance sweep
materializes its next scheduled occurrence in the current series destination.
Unreadable owners reveal no IDs; denied destination writes create no successor.

Delete a referenced board column with independent `reassignTo` (issue statuses),
`releaseReassignTo` (dependency release points), and `recurrenceReassignTo`
(nonterminal recurrence targets) mappings. An eligible `reassignTo` is the
compatibility fallback for recurring targets. Remaps and deletion are atomic.
Explicit new-field requests fail with 503 while the additive migration is
unavailable; ordinary requests retain compatibility.

### Recurrence and column deletion parity

Both full/private and public plugin MCP expose optional completion recurrence
`recurrence_type`, `recurrence_interval`, and nullable
`recurrence_spawn_column_id` on `atoll_create_issue` and `atoll_update_issue`.
Use only the fields exposed by the connected tool; this does not add scheduled
recurrence inputs. Reads expose the addressed stored target and authorized owner
projection. A target-only occurrence edit follows existing owner routing.

`atoll_delete_board_column` is available in both profiles. It requires exact
`confirmation: "DELETE"`, `project_id`, and `column_id`; optional `reassign_to`,
`release_reassign_to`, and `recurrence_reassign_to` select the three independent
reference destinations. Authorization remains the existing project edit/admin
check. The tool is destructive and does not retry an uncertain write. On
`core_write_uncertain`, use `atoll_get_project_workflow` and `atoll_get_issue` to
reconcile the result before another intent. No provider write occurs.

- [Actor work recommendations](https://docs.atollhq.com/agents/work-recommendations): read-only API, CLI, and full/public MCP suggestions, concealed occupation, inactive targets, and signed stale cursors.

## Archive lifecycle

[Archive and restore work](https://docs.atollhq.com/user-guide/archive-and-restore.md)
describes reversible project and task archive. Project and issue collections
accept `archive_scope=active|archived|all` and default to effectively active work.
A task's `effective_archived` is true when its own `archived_at` is set or its
parent project is archived. `archive_reason` is `none`, `individual`, `project`,
or `individual_and_project`. `includeArchived=true` remains an issue alias for
all; open-work filtering always excludes both archive sources. Archived
projects retain authorized exact reads but are read-only and suspend new
automated work. POST/DELETE `/api/orgs/{id}/projects/{projectId}/archive` archive
and restore with owner/admin access and `{ project, changed }` responses.
Restore preserves individual task flags and checks capacity atomically;
`409 PLAN_LIMIT_REACHED` leaves the project archived. Frozen writes return
`409 PROJECT_ARCHIVED`. CLI project archive/restore and list
`--archive-scope` match typed `atoll_archive_project` / `atoll_restore_project`
and MCP list `archive_scope` in both profiles. Archived blockers satisfy
release without losing edges or columns; restore can re-block.

Dependency-chain edge `reason` is `release_reached`, `release_not_reached`,
`readiness_unknown`, `individual_archive`, `project_archive`,
`individual_and_project_archive`, or `cancelled` in REST and both MCP profiles.
Archive reasons distinguish own, parent, or both and take precedence over
cancelled/release position. Authorized archived or cancelled blockers remain
satisfied even without a legacy release column; ordinary reads expose the
matching `satisfaction_reason`. Restoring the parent can re-block a blocker
below its release point if it has no individual archive and is not cancelled.
Restricted blockers retain unknown readiness without disclosing identity.

Project milestone GET/list reads select scope automatically from the authorized
parent's archive state. Optional response `countScope` is `active` or
`historical` and is retained by both MCP profiles. Archived-parent counts and
exact milestone task detail use retained history, including individual archives;
active-parent counts exclude effective archives. There is no new public
milestone archive query parameter. Archived exact project overview labels
milestone counts Historical: x/y complete and retains authorized issue-only
initiative links/counts. Ordinary active dashboards and collections keep active
defaults; restore preserves independent task archives.

Products are optional same-organization groups with stable IDs/slugs and reversible Product-only archive. Owner/admin REST endpoints create/edit/archive/restore Products and PUT project affiliation with UUID or explicit null. Product metadata reads preserve guest/agent project scope and contain no child counts. GET projects supports product_id=UUID|none; existing projects remain standalone. Typed CLI and full/public MCP tools expose Product discovery, management, affiliation and ownership with these same permissions.

- Strategy Product ownership: goals, KPIs and initiatives each carry nullable product_id. Existing REST POST/PATCH accept UUID/null; list filters accept UUID/none. Scope is explicit and independent of contribution or project affiliation. Owner/admin moves preserve history and links; archived Products reject new assignments. Typed CLI list/create/update uses --product UUID|exact-name|none; both MCP profiles accept optional product_id filters and nullable ownership writes.

Product web navigation: Products lists and ID-based overviews support owner/admin create, profile edit and archive/restore. Project Settings supports Product affiliation and None / standalone for active and archived projects without changing workflows or issues. Sidebar groups authorized projects under Product labels with direct board links; active children remain reachable under archived Products. Product overviews show explicit strategy owners, linked context and canonical Product-scoped operations previews with source errors; no new permissions or API contracts.

## Typed Product tools

A Product mutation can return `core_write_uncertain` if its result is lost or
cannot be verified. It may already have taken effect. Read the exact Product or
project before another write. For create, search authorized Products by exact
name with `archive_scope: "all"`, inspect candidates with `atoll_get_product`,
and reconcile the requested fields before another create. Names are not unique;
do not blindly retry. Authoritative permission and conflict errors stay unchanged.

Both full/private MCP and the public plugin expose `atoll_list_products`,
`atoll_get_product`, `atoll_create_product`, `atoll_update_product`,
`atoll_archive_product`, `atoll_restore_product`, and `atoll_set_project_product`.
Use `atoll_list_products` to discover authorized UUIDs. Product reads return
metadata only, without child counts or implicit sibling access. Product list
supports `archive_scope` (`active`, `archived`, `all`), `q`, `q_exact`, `limit`
(1–100), and `offset`.

`atoll_update_product` replaces supplied name/description values; null clears the
description. `atoll_set_project_product` replaces or clears existing affiliation.
Both tools advertise `destructiveHint: true`. Omitted update fields stay unchanged.

Product tool IDs are UUIDs. `atoll_set_project_product` requires `product_id`
as a UUID or explicit `null`. Project list accepts optional `product_id` as a
UUID or `"none"` for standalone projects. Goal, KPI and initiative list tools
accept the same filter; their create/update tools accept optional nullable
`product_id`. Omit it to preserve legacy defaults or the existing owner;
`null` selects Organization ownership. Human `owner_id` remains separate.

Public tools require the selected opaque `profile_ref` on each actor-dependent
call. Discover it with `atoll_list_agent_profiles`; never switch profiles to
bypass a denied write. Existing REST permissions remain authoritative, including
owner/admin Product and ownership writes and concealed inaccessible reads.
Mutation outputs retain the server's `changed` flag. Product archive leaves
project/task lifecycle unchanged. Continue to use bounded project and strategy
lists for authorized related records; heartbeat gains no full Product catalog.

See [CLI Products and ownership](https://docs.atollhq.com/cli/issues-comments-projects.md#products-and-strategy-ownership) for CLI examples.

Earliest runner starts: task `agent_not_before` uses the saved organization IANA timezone (UTC default). Read the tasks guide and local runner guide. Heartbeat includes `workspace_date`; new ordinary claims reject future dates with 409 `RUNNER_LEASE_ISSUE_NOT_BEFORE`. Existing work and attention resume continue.

- Atomic strategy setup: `POST /api/orgs/{id}/strategy/setup` creates a goal, manual KPI, optional initiative, links and initial snapshot in one transaction. Owner/admin only. Retry identical input with the same actor-scoped UUID idempotency_key; changed input returns 409. Goal details show UTC snapshot history and editable properties. See the Goals, KPIs, and initiatives guide.

- [Organization agent role changes](https://docs.atollhq.com/admin/members-teams-permissions): Human owners/admins change enabled organization-wide agents between Member and Admin from detail; existing credentials use the role on the next request.

## Project Admin automation rules

Human and agent Project Admins can create, edit, test, enable, disable, delete,
and inspect authorized history for rules in their own project. Personal agents
use their owner's effective project access. Project View/Edit access is read-only.
Organization-wide rules and Settings → Automations still require organization
Owner/Admin for management.

Project Admin definitions cannot change source scope, create issues in another
project. A project send_webhook requires a matching project-owned destination and current Dispatch permission. These checks apply to saved rules and complete
merged updates before reference validation. A privileged saved rule can still
be disabled or deleted in its own project, but cannot be edited, tested, or
enabled with Project Admin authority. Lists omit inaccessible projects;
non-admin organization-rule context includes enabled rules only. History omits
inaccessible issue links and organization webhook delivery details.

Project-bound execution stays in the saved project after the creator loses
project access. Ordinary agent lifecycle and archive stops still apply. Existing
organization-admin rules keep their authorized cross-project behavior. An
organization admin can explicitly widen a project-bound definition; creator
attribution is retained and execution uses that admin's authority. No new role,
credential, endpoint, or approval step is required. Continue to create disabled,
dry-run the saved revision, then enable.

## Scoped agent permissions

An agent has one stable identity. Humans edit its Projects, Product KPI creation,
individual KPI permissions, Product-wide KPI permissions, and automation access
without replacing its member ID, API keys, or OAuth profiles. Human roles remain
unchanged. Agent `role` is a compatibility projection; it is not the grant source.
Read `GET /api/auth/me` → `auth.permissions` for explicit grants, permission
revision, owner project following, and effective project access with sources.
Use `atoll agent-context --live-permissions` for the selected CLI profile, or
`atoll_get_auth_context` in full/public MCP. CLI context reports conflicts, tenant
mismatch or unavailable reads without switching identities or printing errors.

Project access remains `project_members` View/Edit/Admin. Optional owner following
uses the human owner's current project access only. It never inherits the owner's
organization strategy or administration permissions. Project access does not grant
Product KPI access. New scoped agents have no KPI-create permission by default.

`kpi.create` targets one Product or Organization. An agent must send `product_id`
explicitly: a Product UUID or `null` for Organization. KPI creation, its explicit
creator `kpi.manage` grant, and an optional initial snapshot commit atomically.
The response KPI includes `effective_access: { level: "manage", source:
"explicit_kpi_grant" }`. Creating a KPI grants no access to existing KPIs. Removing
the creator's grant removes access unless another explicit grant covers the KPI.
Names remain unique within their Product or Organization owner; duplicate creation
returns `409`. An archived Product or incompatible Goal cannot receive the KPI.

KPI Read permits reading the measurement. Record includes Read and recording
non-formula snapshots. Manage includes Read, Record, definition/target changes,
and deletion. Ownership changes still require strategy ownership permission.
Product-wide grants cover current and future KPIs under that Product. Organization
scope covers organization-owned KPIs only; `all_kpis` explicitly covers every KPI
in the organization, including all Products. Grants add access; removing a narrow
grant cannot override a broader grant. KPI filtering happens before pagination and
counts. Selected formula measurements stay canonical; source issues and initiative
links require separate access.

Human-only `GET` and `PUT /api/orgs/{id}/agents/{agentId}/permissions` inspect and
replace permissions. PUT requires `expected_revision`, `follow_owner_projects`,
`projects: [{ project_id, access_level }]`, and `grants: [{ capability, target_kind,
target_id }]`. A stale revision or active execution conflict returns `409` without
a partial update. Stop active executions and reload before changing access. Grants
and project membership changes are audited together. Agents cannot administer
grants. Legacy agent role PATCH is rejected with `agent_permissions_required`;
legacy project PATCH remains a compatibility adapter. No CLI/MCP permission-write
tool is exposed because this control requires a verified human session.

Project webhook creation uses `webhook.create(project)`. Creation atomically grants
its agent creator `webhook.manage(new webhook)` and `webhook.dispatch(new webhook)`.
Manage and Dispatch are independently revocable. Sending also requires project
rule management and current project access. Project Admin alone grants agents no
webhook rights. Organization administration retains its explicit organization grant.

**Delete agent** uses terminal revoke. It permanently invalidates credentials and
execution authority, releases the agent slot, hides it from active agent lists and
pickers, and disables active automation rules that execute as that identity. Past
work, attribution, grant history and the member row remain. It cannot be undone.
Disable remains reversible and keeps the slot; enabling requires fresh credentials.
`DELETE /api/orgs/{id}/agents/{agentId}` remains the human-only idempotent adapter.
The stored marker stays `lifecycle_state: "revoked"`. Use **Show deleted agents**
for history. Admin agent list APIs accept `include_deleted=true` for deliberate
history reads.

- [Heartbeat task selection](https://docs.atollhq.com/api-reference/heartbeat): per-agent task filters, workspace calendar, exclusion preview and compatibility.
- Project-owned automation webhooks use independent Create, Manage and Dispatch grants. Both MCP profiles and CLI expose scoped setup, credential rotation, test, history and redelivery. See https://docs.atollhq.com/api-reference/webhooks#project-owned-webhook-destinations.

- Conditional outbound heartbeats: explicitly authorized opt-in delivery, dry-run decisions, history, stable wake IDs and acceptance semantics. See https://docs.atollhq.com/api-reference/heartbeat#outbound-heartbeat-delivery.

Heartbeat management: independent heartbeat.manage_self and heartbeat.manage_others grants; other excludes self. See /user-guide/heartbeats and /agents/safety-and-permissions. New typed management tools are full/private MCP only; package availability is a separate release.


A CLI or full/private MCP outbound test can return `core_write_uncertain` with `retryable: false` after a lost, malformed or server-error response. Read `heartbeat outbound get --agent UUID` or `atoll_get_outbound_heartbeat` for the same agent and inspect authorized history before taking further action. Do not repeat the test while the outcome is unclear. The clients do not retry the POST automatically.