Atoll#

Base URL: https://atollhq.com

Use the available Atoll connection for live data and controlled actions. In MCP clients, use the connected Atoll tools; do not assume a shell, installed CLI, local profile, or API key. In CLI environments, prefer the typed Atoll CLI. Live tool schemas, CLI help, and linked references define the contract.

Heartbeat is compact by default for REST and private CLI/MCP calls. Read the strategy and heartbeat reference for bounded pages, terminal acknowledgement, delta cursors, grouped dependency blockers, and the explicit --full/ view=full legacy response. The public plugin MCP heartbeat remains legacy full mode. If a requested max_bytes cannot fit the mandatory actionable record and compact envelope, REST returns 413 heartbeat_budget_too_small without advancing a page cursor or terminal receipt; retry with a larger budget or the 16 KiB default. Dependency-chain cursors are signed and revision-bound; graph drift returns 409 Stale dependency chain cursor, so restart without the cursor. Private heartbeat also carries durable execution attention. Handle resolved answers before open requests and acknowledge them with the exact versions; the acknowledgement never resumes an execution.

Read actor work with atoll work recommendations --json or the typed full/public MCP tool atoll_get_work_recommendations. Machines query only self; human target inspection uses manageable/assignable scope and caller/target permission intersection. Read the endpoint and field references for current-work inspection, hidden availability, global bounds, and signed stale cursors. Recommendations are snapshots: they never reserve, assign, start, retry, or authorize execution. The existing project-wide read uses atoll work project-recommendations --project UUID --json or MCP view: project; actor choices use work actors --project UUID or MCP view: actors. Do not rerank locally or treat failure chronology as retry supersession.

Route to the relevant reference#

Read only the references required for the current task:

• Authentication, saved profiles, organization or project selection, and environment conflicts: authentication-and-profiles.md
• PRDs, implementation plans, Artifact discovery, links, and revisions: artifact-workflow.md
• Routine CLI commands for issues, comments, goals, KPIs, initiatives, dependencies, artifacts, and other resources: cli-operations.md
• Installing, diagnosing, configuring, or operating the headless local runner, repository bindings, loopback UI, leases, or recovery: local-runner.md
• Configure GitHub verification with resume only when the exact PR, commit, runner host, and preserved Codex thread can be bound. The mode is disabled by default and fails closed when the binding or verification event is uncertain: api-fields.md
• Strategy, KPI pace, initiatives, heartbeat signals, autonomous prioritization, and common strategy workflows: strategy-and-heartbeat.md
• Agent executions, evidence, human-attention requests, resolution, and version-fenced lifecycle transitions: execution-and-attention.md
• Remote MCP exposes typed execution and requester-attention tools in both profiles. Use the lifecycle guidance in the execution reference; human resolution and runner/harness control remain outside those MCP tools.
• The public MCP profile also exposes typed issue, dependency-chain, label, subtask, strategy audit, activity, notification, project, board-column, goal, and KPI tools. Use the existing API authorization and exact field contracts; atoll_delete_project needs confirmation: "DELETE" and owner/admin access. It can still fail while linked Artifacts or active executions block deletion. Archive and unarchive emit the normal issue.updated webhook event. When a core write returns core_write_uncertain, read the resource and reconcile before replay; the server does not retry automatically. Goal and KPI tools accept exact human-readable goal titles and KPI names as documented in the API references.
• Automation-rule create, update, enable, disable, and delete can also return core_write_uncertain. For a create, list rules in the same scope and get a possible match by UUID. Set project_id to "none" for organization-wide rules. For other writes, get the exact rule and compare its definition or enabled state; for delete, check whether its UUID remains in the list. Reconcile before retrying any uncertain rule write.
• Local runner lifecycle management associates leases with canonical executions, uses a durable private outbox, and resumes resolved human attention only with the exact retained thread and closed IDs/outcome; notification and GitHub resume contracts remain separate.
• Remote MCP setup, GitHub repository and External Reference tools, AI-assisted setup, KPI HTTP sync, or advanced REST access: integrations-and-api.md
• Completed manual GitHub workflow dispatches require one current linked PR and canonical same-repository head and branch proof. Nonterminal notifications create no evidence; manual dispatch does not trigger generic CI automation.
• GitHub pull-request delivery context, required checks, and exact-head evidence: api-fields.md A plan_restricted required-check error is actionable plan-unavailable evidence; keep configured workflows separate because they remain required: false.
• Cross-resource authorization, privacy, automation, attachment, feedback, and other platform-specific rules: platform-rules.md
• Exact endpoint inventory: api-endpoints.md
• Request and response fields, enums, and validation: api-fields.md

Outbound webhooks support optional Standard Webhooks signing with a receiver supplied canonical whsec_ secret. Read the webhook references before creating or updating a destination; signing secrets are write-only and automatic retry delivery ids remain stable. Grok Automations and Hermes support this receiver contract; see the integration reference for their setup and event caveats.

The human-only manageable-agent inventory includes admin-only personal owner names and shared agent/integration capacity. Non-admins receive null owner and capacity metadata. See the Agent Fields reference; machine callers remain forbidden on this management route. API-key integrations continue to consume the agent allowance, and failed billing reads never imply zero usage.

Agent creation can select an allowlisted built-in icon with avatarPreset. Manage an existing guest agent icon through the member avatar endpoint: upload a custom image with POST, select a built-in preset with PATCH, or remove it with DELETE. Read api-endpoints.md and api-fields.md for the exact contract and limits.

For automation rule V1 actions (including create issue and send webhook), explicit project or organization scope, CI create-or-webhook rules, scheduled schedule.issue_time rules, event conditions, validation, safe disabling, repair, and example-only CI dry runs, read Automation Rule Fields. Use atoll automation for rule management, previews, and run history; see CLI operations. Both full/private and public MCP profiles also expose typed list, get, create, update, enable, disable, test, run-history, and delete tools. MCP creation requires explicit scope and always leaves the rule disabled; test is a dry run. Use the same separate disable, repair, test, and enable sequence for invalid rules. Atoll enforces owner/admin access for rule writes and history. REST rule lists accept ?project_id=<UUID> for exact project rules or ?project_id=none for organization-wide rules only. Omission lists all rules in the organization. See list filter access and validation. Rule creates require an explicit project_id: use a project UUID for project scope or null for organization scope. Partial updates preserve the saved scope when project_id is omitted; include it only when intentionally changing scope. An invalid rule executes no actions. Repair an invalid rule with separate disable, update while it is disabled, test, and enable operations. Enable only after the latest saved revision passes the dry run.

For recurring issues, completion remains the default materialization mode. Scheduled recurrence uses the existing issue create/update REST and CLI inputs with a local time and an IANA timezone. Its interval must be at most 10000; completion-mode roots can retain larger positive intervals. See Task Fields and CLI operations. The recurrence root owns the schedule. Its occurrences can remain open without delaying later occurrences. Both MCP profiles expose completion recurrence type/interval and nullable spawn-column inputs on existing issue tools. Scheduled inputs remain REST/CLI only. After a series move, the next task uses its current project and target. Column deletion requires exact confirmation and independent atomic remaps. See API endpoints.

Do not load every reference by default. Start with this entrypoint and load a topic reference only when the requested operation needs it.

Workflow contract#

Select the actor and project#

For actor-dependent MCP calls:

1. Reuse the profile_ref already established in the current conversation.
2. If none is established, call atoll_list_agent_profiles before an actor-dependent read or write.
3. Select a profile directly when the user names it. Otherwise select a unique profile only when the organization or project clearly identifies it.
4. Ask when multiple authorized profiles remain plausible.
5. Include the chosen profile_ref in every later actor-dependent call.

A profile_ref is an opaque selector, not a credential. Do not persist it, expose it as a secret, silently switch actors, or infer identity from a mutable server-side active profile. If the selector is invalid, rediscover profiles. If no profile is authorized, explain that the user must authorize one.

For CLI work, use the named profile required by the repository or user. Resolve the organization and project from live accessible data. Do not carry mutable IDs or board mappings across conversations without checking them.

Read before write, then verify#

For state-changing work:

resolve actor -> resolve organization/project -> read the target -> inspect linked context when relevant -> make the smallest required write -> read back the changed resource -> verify the requested final state

Before creating work, search for a matching issue, milestone, goal, KPI, or initiative or Artifact. Update the existing resource when it represents the request. Never invent an ID, success response, stored value, or visible state.

Readback is mandatory for requested mutations. Report both the stored value and the user-visible value when both exist, and state anything that could not be verified.

Use the narrowest available typed command or tool. Use raw REST only when the typed surface does not cover the operation and the current environment authorizes REST access. In MCP clients, if a required tool is unavailable, report that limitation; do not bypass it through CLI or raw API access. Do not duplicate tool schemas from memory.

Preserve the Atoll model#

• Goals describe directional business outcomes and deadlines.
• KPIs measure business outcomes and pace.
• Initiatives are bets expected to move one or more KPIs.
• Initiative targets measure commitments or launch gates.
• Milestones are delivery checkpoints.
• Issues are executable work.

Preserve links between these layers. Do not turn them into interchangeable standalone tasks.

Resolve workflow from live data#

Board columns belong to projects. Use atoll_get_project_workflow, then atoll_move_issue (or the corresponding typed CLI operation), instead of guessing. Match the visible destination label and verify both the stored status key and visible label after the move. Never treat a key such as ready_to_build as universal.

Discover collaborators and assignees#

Use atoll member list or the typed MCP tool atoll_list_members to find authorized human and agent collaborators. Filter by project, member type, and display name. Use the returned stable member ID in issue assignee_id or assignee_ids writes. This directory returns a compact projection and does not include email or auth identifiers. atoll_list_agent_profiles selects the caller identity; it is not the organization member directory.

Plan implementation-ready work#

Store substantial PRDs and implementation plans in linked Artifacts. Read the Artifact workflow before planning or revising them. Keep comments to short summaries and Artifact references.

For implementation planning, inspect the relevant project and existing work first. The result must let another coding agent start without repeating the product reasoning. Include only the sections that matter:

• Outcome
• Context and current behavior
• Product behavior
• Relevant repository or API surfaces
• Edge cases and compatibility
• Tests
• Acceptance criteria

Keep product decisions, security boundaries, and unresolved questions explicit. Do not add project-specific workflow keys as universal instructions.

Safety boundaries#

• Credentials belong in approved local configuration or environment variables. Never print, store in Atoll content, or include them in commands shown with real values.
• Project and organization authorization remain authoritative. Do not retry as another identity to bypass a concealed or denied resource.
• Preserve idempotency keys and expected versions for lifecycle writes. After a timeout or ambiguous failure, read state before retrying.
• Keep attention requests, comments, evidence, and feedback free of credentials, private paths, prompts, logs, or raw sensitive payloads.
• Publication, deployment, production mutation, destructive deletion, and external communication require the authority applicable to the current task.

MCP project events#

Modern public OAuth MCP clients can monitor issue.status_changed, attention.created, and execution.state_changed. Each subscription requires an accessible project UUID; discover the live workflow before choosing status filters. Resolve profile_ref as for tools. ChatGPT manages callback verification, finite grants, refresh, and unsubscribe through events/* protocol methods. API-key/private/stdio clients use tools and Heartbeat. Payloads are compact immutable snapshots; fetch full current state with read tools. No replay is provided.

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. The 110 model-facing business tools and modern MCP Events remain available. Full/private and stdio omit the UI entrypoint.

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.

OpenAI deep links use the same canonical app routes: /, /projects/<uuid>, /issues/<uuid>, /attention/<uuid>, /executions/<uuid>. Resolve with the explicitly selected authorized profile_ref; a link is identity, not permission. Invalid shapes/UUIDs are rejected before reads; unavailable entities never trigger a silent profile search. Direct host navigation does not add Model-App Context; issue navigation from an agent focuses that authorized issue automatically. Atoll issue/project web surfaces show Open in ChatGPT only when the deployment has the explicit public build-time NEXT_PUBLIC_ATOLL_PLUGIN_ID. Never guess this published ID or confuse it with OAuth/marketplace configuration. Web URLs target global atoll.open and encode the complete canonical path once. Keep normal Atoll URLs for unsupported hosts (including Android). Local synthetic-ID tests do not prove published-plugin setup or authenticated provider acceptance.

Composer mentions (desktop)#

In supported ChatGPT desktop Composer surfaces, use @ to find authorized issues, projects, human and agent members, goals, KPIs and initiatives. Search uses currently authorized OAuth connection profiles, not a global or default actor. Exact display names and authorized human issue identifiers such as AH-123 precede loose name matches. Empty queries return a bounded first page; search does not download a full directory.

The app-only, read-only search_mentions extension accepts { "query": "text" } and returns { "items": [...] } with standard MCP ResourceLinks. Results show type, organization, profile and available project context. Identical entities under different profiles keep separate links so the follow-up actor stays clear. It is separate from the 110 ordinary business tools and atoll.open.

Resources use atoll://profiles/<opaque-profile-ref>/<entity-kind>/<UUID>, where entity kind is issues, projects, members, goals, kpis or initiatives. Reads validate the current grant and entity permission under that exact profile. Malformed routes, revoked profiles and inaccessible records fail without trying another actor. Resource text contains concise identity and current state, including profile_ref; it excludes long descriptions, histories and secrets. Fetch current details with the same profile before acting. Mention discovery and resource reads do not write Atoll records or alter sidebar Model-App Context.

The full/private MCP profile omits this host-specific extension. Normal typed list tools remain available in both profiles. Provider publication and signed-in desktop @ selection are separate acceptance steps; local protocol tests do not prove that provider flow. No mobile workaround is included.

Bounded collection search#

Projects, goals, KPIs and initiatives accept q for case-insensitive literal substring matching of the display name/title, q_exact=true for the complete name, and limit/ offset for server-side pagination. Defaults in bounded mode are 25 results, maximum 100, and offset 0. Filtering and authorization precede pagination; offsets beyond matching results return an empty page with the exact total. KPI pages include current calculated values. Use shape=envelope (or response_shape=cli) for resource, items, total, limit, offset, nextOffset, truncated and hint. Supplying a search or pagination parameter also selects bounded retrieval. Calls without these parameters retain their legacy resource-key response and full-list behavior.

Members add member_id=<UUID> and q_exact=true in bounded directory mode. Identity filtering uses the same collaborator visibility rules and safe fields as name search; it does not grant access or return credentials or account email. Members and initiatives also accept scope=accessible_projects for a bounded union under the current actor. The server derives project IDs; callers cannot supply ID arrays. Guests see only accessible project-linked initiatives and eligible collaborators. Existing member/admin projectless initiative rights remain. Empty project access gives guests an empty page. Unknown scope or scope combined with an explicit project returns 400. Explicit project scope remains project_id for initiatives and projectId for members.

Full issue lists resolve authorized human identifiers such as AH-123, ATOLL-123, #123 or a number before loose title/description matching. They also accept q_exact=true for the full title. The exact flag is rejected with 400 for compact view=board/ view=list; existing compact search stays unchanged. The existing issue filters and actor/project authorization still apply.

CLI list commands for projects, goals, KPIs, initiatives and members use --search, --exact, --limit and --offset; issue list uses --q with --exact. Member list also supports --member-id. These filters are evaluated by the API. Existing public/private MCP list tools expose q, q_exact, limit and offset; atoll_list_members adds member_id. Member and initiative lists expose --accessible-projects in the CLI and scope=accessible_projects in MCP. The initiative flag suppresses a configured default project and cannot combine with --project or --org-wide. Normal MCP goal/KPI/initiative calls without query, exact, paging or scope options retain legacy full-list responses. Composer search uses a constant number of bounded list calls per profile and entity kind, independent of the number of accessible projects.

Native interactive issue creation#

Use plugin-only atoll_create_issue_interactive only when the user asks to choose or confirm fields in native forms. Pass explicit profile_ref. Supporting registered desktop hosts require protocol 2026-07-28 MRTR, standard form elicitation and the OpenAI rich-form extension. Unsupported hosts use ordinary atoll_create_issue with complete values. Cancel/decline/invalid/expired state creates nothing. Final confirmation rechecks profile, project, live workflow, milestone and searched assignees, then sends one canonical create. Do not retry an uncertain outcome; reconcile the original issue first. Deterministic creation keeps its existing required title and behavior. No mobile workaround or client deployment secret is needed.

Milestone lists accept optional q, q_exact, limit, offset and envelope shape under the existing project endpoint. They filter/page in the database and preserve progress/status counts. Old absent-option REST/MCP calls stay unpaged; CLI keeps its old request when no new options are supplied.

Conversation Working Set#

Open the app-only atoll.working_set thread entrypoint with {} in a supported host. Search authorized issues/projects and add local pins. Add/remove is local; explicit selection shares one active canonical Atoll reference through the existing context controller. Active requires accepted shared context; unsupported or failed sharing stays local. Removing a pin does not deselect shared context; unpinned references retain explicit Deselect/Clear selection controls. Status/priority/assignees refresh through existing reads; dependencies/activity are lazy. In-panel Open details preserves same-instance pins. Profile changes clear pins and fence old reads. Recreated panels rebuild from current authorized context only; unshared pins are ephemeral. No thread ID, persistent record, transcript request, automatic message or Atoll write is added. Native provider acceptance remains separate from controlled-host evidence.

Artifact source provenance is available through web, REST, and private CLI. Create/revise accepts source_external_reference_link_id; revise omission inherits and null clears. Add projection=source_provenance_v1 on Artifact create/revise or single-revision GET to read an authorized immutable source. Default REST and typed MCP Artifact output remain unchanged. See the Artifact field reference for target authorization and unlink semantics.

Vercel deployment context#

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#

Use atoll context list --issue ATOLL-42 --json or --project project-slug before loading detail. Full/private MCP exposes atoll_list_context with exactly one issue/project UUID. Inspect authority, freshness, current revision/SHA, and safe summaries; follow each group cursor with the same target/limit and deduplicate by item ID. Load only the needed existing Artifact, reference, or delivery detail. See Context fields. The public index and delivery-detail tools remain unavailable pending AH-3067 and release of the public tool freeze. Existing public Artifact and reference reads are unchanged. Evidence never implies a later delivery or acceptance gate.

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.

Manual Web references#

Use CLI external-reference link with --provider external_document --object-type document or the scoped REST route to add a manual HTTPS URL. Content is not fetched or verified. Typed MCP creation remains GitHub-only; list/get/unlink can read manual references. See the External References fields reference for trust semantics.

Agent lifecycle boundary#

Only enabled agents can authenticate or receive new work. Disable preserves history and capacity; enable needs fresh credentials and consent and does not resume work. Revoke retains historical identity and is terminal. Lifecycle administration requires a human session; CLI/MCP do not expose it. Read references/api-endpoints.md for state/version, capability, replay, and runner-lease rules.