@atollhq/skill-codex 0.4.34 → 0.4.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.34",
+  "version": "0.4.36",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -12,6 +12,15 @@ 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.
+
 ## Route to the relevant reference
 
 Read only the references required for the current task:

package/skill/references/api-endpoints.md

@@ -213,6 +213,7 @@ bodies, projects only declared public issue fields, preserves nullable
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues/{issueId}/dependencies` | List dependencies (`{ blocking, blockedBy }`) |
+| GET | `/api/orgs/{id}/issues/{issueId}/dependencies?view=chain` | Read a bounded normalized dependency chain |
 | POST | `/api/orgs/{id}/issues/{issueId}/dependencies` | Add dependency |
 | PATCH | `/api/orgs/{id}/issues/{issueId}/dependencies/{depId}` | Change dependency release point |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/dependencies/{depId}` | Remove dependency |
@@ -226,6 +227,19 @@ blocking project's `done` column. During a rolling deployment, compatibility
 reads may omit release fields from older rows; treat missing release metadata as
 the legacy open-blocker behavior until the migration is applied.
 
+For `view=chain`, use `direction=upstream|downstream|both` (default
+`both`), `depth` (default `2`, maximum `5`), `limit` (default `50`), and
+the opaque `cursor`. The response normalizes readable nodes and edges, includes
+release-condition satisfaction and permission flags, and returns readable node
+`assignee_id`, nullable `due_date`, nullable `ready_if_released`, and readiness.
+It returns opaque restricted node tokens with `readiness: "unknown"` when an
+issue is not readable. The top-level `partial` is true when the depth bound, restricted nodes, or unknown readiness
+prevent a complete graph. The response is read-only and can
+be truncated; follow `page.next_cursor` only when present. Chain cursors are
+signed and bound to the current graph revision and caller scope. Graph changes
+while paging return `409 Stale dependency chain cursor`; restart without the
+cursor.
+
 ## Comments
 
 | Method | Endpoint | Description |
@@ -467,13 +481,46 @@ The create body is strict and requires `execution_id`, `expected_state_version`,
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/heartbeat` | Get heartbeat context for the authenticated agent |
+| GET | `/api/orgs/{id}/heartbeat` | Get compact heartbeat context by default; use `?view=full` for the legacy full response |
+| POST | `/api/orgs/{id}/heartbeat/ack` | Acknowledge a terminal compact heartbeat page with `{ "ack_cursor": "..." }` |
 | GET | `/api/orgs/{id}/agents/{agentId}/heartbeat-policy` | Human-only manageable-agent policy, selectable scope, and stale selections |
 | PUT | `/api/orgs/{id}/agents/{agentId}/heartbeat-policy` | Human-only complete atomic policy replacement |
 | DELETE | `/api/orgs/{id}/agents/{agentId}/heartbeat-policy` | Human-only reset to default heartbeat behavior |
 | POST | `/api/orgs/{id}/agents/{agentId}/heartbeat-preview` | Human-only saved/draft preview composed as the target agent without persistence |
 
-Returns computed briefing with goal status, KPI pace/trend, initiative progress, assigned work, direct `attention_items`, `attention_summary`, signals, and a deterministic `recommended_action` when Atoll can propose one concrete strategy-backed next action. The endpoint is org-scoped, but project-bound payload details are filtered by the caller's project access. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. Non-guest members can also see unprojected org-level strategy, and shared initiatives can appear with counts and signals based only on accessible work.
+REST and private CLI/MCP calls return compact delivery by default: grouped
+actionable signals, bounded attention, counts, delta, and a page descriptor.
+The page is limited to 25 groups and 16,384 UTF-8 bytes. A page with
+`has_more: true` returns `next_cursor`; only the terminal page returns an
+`ack_cursor`. Acknowledge that cursor with the POST endpoint before using it as
+`since`. Cursor or baseline conflicts return `409`; an expired acknowledged
+baseline sets `delta.reset_required: true`. If the requested `max_bytes` cannot fit the
+mandatory actionable record and compact response envelope, the server returns
+`413` with `code: "heartbeat_budget_too_small"` and does not advance a page
+cursor or terminal receipt. Retry with a larger `max_bytes` or omit it for the
+16,384-byte default. Use `?view=full` for the full
+briefing with goals, KPI pace/trend, initiatives, assigned work, project
+context, attention, signals, and recommendation. Full mode cannot use
+`since` or cursor pagination.
+
+Cursors are opaque, server-issued, and single-use in sequence. Pass the exact
+`next_cursor` from the immediately previous page. Do not manufacture, skip, or
+replay a page cursor.
+
+Expected waits are suppressed for an unsatisfied dependency when the readable
+blocker is before its release column and there is no active stall, threatened or
+overdue commitment, or explicit deadline, gate, permission, or stale anomaly.
+An unowned backlog or Todo blocker by itself is an ordinary wait and never
+alerts. Actionable groups surface active stalls, threatened or overdue
+commitments, and explicit anomalies; escalation metadata alone does not surface
+an expected wait. When every dependency fact behind an initiative-target or
+stalled aggregate is an expected wait, that aggregate is suppressed too. Dependency blockers are grouped
+by root blocker and release condition, with bounded normalized-chain facts and
+`suggested_read` calls when additional read-only evidence is needed. The endpoint is org-scoped, but all
+project-bound details remain filtered by caller project access. Public plugin
+MCP heartbeat remains legacy full mode and does not expose compact ack or chain
+tools; private MCP exposes compact heartbeat, `atoll_ack_heartbeat`, and
+`atoll_get_dependency_chain`.
 
 An authorized human may save a per-agent attention policy for context sections, semantic signal categories, accessible projects, visible initiatives, and stable per-project board-column IDs. The API applies it before CLI/MCP severity or signals-only narrowing. Policies never broaden project access; assigned work and direct attention remain independent of generated-signal focus.
 

package/skill/references/api-fields.md

@@ -823,6 +823,53 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 
 ## Heartbeat Response
 
+`GET /api/orgs/{id}/heartbeat` returns compact delivery by default for REST
+and private CLI/MCP callers. Compact responses contain `mode: "compact"`,
+`agent`, `timestamp`, `attention_items`, `attention_summary`, grouped `signals`, `recommended_action`,
+`counts`, `delta`, and `page`. Full legacy context is available only with
+`view=full` (or the CLI `--full` flag).
+
+### Compact heartbeat fields
+
+| Field | Notes |
+|---|---|
+| `signals[]` | Grouped actionable signal or dependency-blocker groups. Each group has `key`, `revision`, `severity`, `kind`, `action_reason`, root and impact counts, readiness, bounded `evidence`, and optional `suggested_read`. |
+| `attention_items` | Bounded direct attention projections with required `id`, `event_type`, `severity`, `title`, `resource_type`, and `ack_endpoint`; optional `resource_id` is included when present. |
+| `attention_summary` | Counts for included direct attention items. |
+| `counts` | `actionable_groups`, severity counts, `direct_blocked`, `downstream_blocked`, `ready_if_released`, `unknown_readiness`, `restricted`, and `suppressed_expected_waits`. |
+| `delta` | `since`, `new_count`, `changed_count`, `escalated_count`, `ready_count`, suppression counts, and `reset_required`. |
+| `page` | Requested `max_bytes` (1,024-16,384) and `max_items` (1-25), returned counts/bytes, `has_more`, `next_cursor`, and terminal `ack_cursor`. |
+
+Compact pages are deterministic and use opaque, server-issued cursors. Request
+the next page with the exact `next_cursor` from the immediately previous page;
+do not manufacture, skip, or replay a page cursor. Cursors are single-use in sequence. Acknowledge only the terminal `ack_cursor` using
+`POST /api/orgs/{id}/heartbeat/ack`, then use that acknowledged cursor as
+`since` on a later request. Invalid cursors return `400`; stale pages or an
+unacknowledged `since` return `409`. An expired acknowledged baseline returns a
+fresh compact response with `delta.reset_required: true`. If the requested
+`max_bytes` cannot fit the mandatory actionable record and compact response
+envelope, the route returns `413` with `code: "heartbeat_budget_too_small"`;
+no page cursor or terminal receipt advances. Retry with a larger `max_bytes` or
+omit it for the 16,384-byte default. Policy, authorization, or candidate
+changes while paging invalidate the cursor.
+
+Expected waits are suppressed for an unsatisfied dependency when the readable
+blocker is before its release column and there is no active stall, threatened or
+overdue commitment, or explicit deadline, gate, permission, or stale anomaly.
+An unowned backlog or Todo blocker by itself is an ordinary wait and never
+alerts. Actionable groups surface active stalls, threatened or overdue
+commitments, and explicit anomalies; escalation metadata alone does not surface
+an expected wait. Initiative-target and stalled aggregates are also suppressed
+when every underlying dependency is an expected wait. Dependency blockers are grouped by
+root and release condition. A dependency chain may
+include readable nodes and edges, opaque restricted node tokens, readiness,
+release-condition satisfaction, and explicit permission flags; unknown
+readiness remains unknown. Suggested reads are safe GET/CLI/private-MCP calls.
+
+The public plugin MCP heartbeat keeps its legacy full response and does not
+expose compact acknowledgement or dependency-chain tools. Private MCP supports
+compact heartbeat, `atoll_ack_heartbeat`, and `atoll_get_dependency_chain`.
+
 ```json
 {
   "agent": { "id": "...", "display_name": "Growth Agent" },
@@ -1144,6 +1191,26 @@ blocking project's `done` column. During a rolling deployment, compatibility
 reads may omit release fields from older rows; treat missing release metadata as
 the legacy open-blocker behavior until the migration is applied.
 
+### Dependency chain fields
+
+`GET /api/orgs/{id}/issues/{issueId}/dependencies?view=chain` returns a bounded
+normalized graph:
+
+| Field | Notes |
+|---|---|
+| `root_issue_id` | Authorized root issue UUID. |
+| `direction` | `upstream`, `downstream`, or `both`; default `both`. |
+| `depth` | Traversal depth, default `2`, capped at `5`. |
+| `nodes[]` | Readable issue projections with readiness and dependency counts, or opaque restricted tokens with `readiness: "unknown"` and `permissions.read: false`. |
+| `edges[]` | Upstream/downstream node IDs, permission flags, optional `release_condition`, `satisfied`, and reason (`release_reached`, `release_not_reached`, or `readiness_unknown`). |
+| `counts` | Returned/known nodes and edges, direction counts, readiness counts, restricted nodes, and unsatisfied release conditions. |
+| `page` | `limit`, `truncated`, and opaque `next_cursor`. |
+
+The chain is read-only. Use `limit` and `cursor` for bounded traversal; do not
+infer restricted issue identity from the token. Chain cursors are signed,
+opaque, and bound to the current graph revision, root, direction, depth, limit,
+and caller scope. If the graph changes while paging, the route returns `409 Stale dependency chain cursor`; restart without `cursor`.
+
 ## External References
 
 External-reference response items contain `link_id`, `id`, `org_id`,

package/skill/references/cli-operations.md

@@ -47,6 +47,10 @@ atoll heartbeat
 atoll heartbeat --signals-only
 atoll heartbeat --severity critical
 atoll heartbeat --json
+atoll heartbeat --full --json
+atoll heartbeat --since <ack-cursor> --json
+atoll heartbeat --cursor <page-cursor> --json
+atoll heartbeat --ack <terminal-ack-cursor> --json
 atoll agent-context
 
 # List tasks
@@ -117,6 +121,7 @@ atoll api get /api/orgs/$ATOLL_ORG_ID/labels --json
 
 # Dependencies
 atoll dependency bulk-add --file ./dependencies.json --continue-on-error
+atoll dependency chain ATOLL-42 --direction downstream --depth 2 --json
 
 Dependency reads include a target issue `identifier` and `projectSlug` when the target belongs to a project. Inaccessible targets remain `issue: null`; projectless targets have both fields set to `null`.
 Dependencies persist a release point in the blocking project's ordered board columns. Add `releaseColumnId` when creating an edge, or omit it to default to that project's `done` column. Use the dependency API PATCH route to change the release point; reads include `releaseColumnId`, `releaseColumn`, and `satisfied`.
@@ -132,6 +137,14 @@ snake_case consumers need it; POST and PATCH accept either `releaseColumnId` or
 `release_column_id`. When deleting a board column, migrate issue
 statuses and dependency release references with separate explicit targets.
 
+`atoll dependency chain <identifier>` reads a bounded normalized dependency
+graph. Use `--direction upstream|downstream|both` (default `both`),
+`--depth` (default `2`, maximum `5`), `--limit`, and `--cursor`. Readable nodes
+include readiness and release-condition state. Restricted nodes use opaque
+tokens and `readiness: "unknown"`; never infer their issue identity. The cursor
+is signed and revision-bound; graph changes while paging return `409 Stale
+dependency chain cursor`, so restart without the cursor.
+
 # Graph plans
 atoll plan validate --file ./plan.json
 atoll plan apply --file ./plan.json --dry-run
@@ -157,6 +170,7 @@ atoll goal create --title "Reach 100 paying customers by Q2" --target-date 2026-
 atoll kpi create --name paying_customers --goal "Reach 100 paying customers by Q2" --unit count --target 100 --current 34
 atoll kpi create --name mvp_tasks_done --goal "Launch MVP" --internal-task-completion
 atoll initiative create --title "Content pipeline" --goal "Reach 100 paying customers by Q2" --status active
+atoll initiative delete "Content pipeline" --confirm DELETE
 atoll initiative kpi link "Content pipeline" paying_customers --impact "+30 customers/mo"
 atoll initiative target create "Content pipeline" --title "Publish 10 comparison posts" --mode progress --target 10 --current 0 --unit count --unit-label posts
 atoll initiative target create "Retailer coverage" --title "Get 5 retailers live by July 5" --mode gate --target 5 --current 0 --unit count --unit-label retailers --target-date 2026-07-05 --due-soon-days 7
@@ -183,7 +197,13 @@ CLI JSON conventions:
 - Interactive CLI update notices also go to stderr and are suppressed for JSON/non-TTY/CI/completion flows.
 - `atoll agent-context` returns a versioned command/flag manifest, available profile context, and structured `cli.update_available` metadata.
 - Weekly issue recurrence accepts unique selected weekdays with `--recurrence weekly --recurrence-days mon,wed,fri --recurrence-mode schedule --recurrence-time 09:00 --recurrence-timezone Asia/Singapore`. Read JSON exposes normalized `recurrence_days` and `recurrence_schedule`; unrelated updates preserve the schedule. Scheduled recurrence intervals are limited to `10000`. Use `--recurrence-mode schedule` with `--recurrence-time HH:MM` and `--recurrence-timezone IANA/Zone` to create the next task from the maintenance sweep while the current task remains open; `completion` remains the default and can retain larger positive intervals.
-- `atoll heartbeat --json` includes the same structured `cli` update metadata for agents, plus `attention_items`, `attention_summary`, and `recommended_action` when Atoll can propose one concrete strategy-backed next action. `atoll heartbeat --signals-only --json` preserves filtered `signals`, `attention_items`, `attention_summary`, and `recommended_action` for short polling. Handle direct attention items first, then call each handled item's `ack_endpoint`. Follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative_target/why-now/expected-impact/first-step/success-criteria evidence, and avoid copying deferred busywork into issue or comment payloads. If a `start_work` recommendation uses `issue.update` with a body, update the issue status and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
+- `atoll heartbeat` uses compact delivery by default. Compact JSON is bounded to 25 signal groups and 16,384 UTF-8 bytes, with `counts`, `delta`, and `page`. Follow `page.next_cursor` until the terminal page, then acknowledge its `page.ack_cursor` with `atoll heartbeat --ack <cursor> --json`. Use an acknowledged cursor with `--since`; invalid or stale cursors return an error, and an expired baseline sets `delta.reset_required: true`. If a requested REST
+`max_bytes` cannot fit the mandatory actionable record and compact response
+envelope, the API returns `413 heartbeat_budget_too_small` without advancing a
+page cursor or terminal receipt; retry with a larger budget or the 16 KiB
+default. Use `--full` for the legacy full context; full mode cannot combine with `--since` or `--cursor`.
+- Compact signal groups include dependency blockers grouped by root blocker and release condition. Expected waits are suppressed for an unsatisfied dependency when the readable blocker is before its release column and there is no active stall, threatened or overdue commitment, or explicit deadline, gate, permission, or stale anomaly. An unowned backlog or Todo blocker by itself is an ordinary wait and never alerts. Actionable groups surface active stalls, threatened or overdue commitments, and explicit anomalies; escalation metadata alone does not surface an expected wait. Initiative-target and stalled aggregates are also suppressed when every underlying dependency is an expected wait. Groups can include a bounded `suggested_read` REST, CLI, or private-MCP call. Public plugin MCP keeps legacy full heartbeat behavior; private MCP supports compact heartbeat, `atoll_ack_heartbeat`, and `atoll_get_dependency_chain`.
+- `atoll heartbeat --json` includes the structured `cli` update metadata for agents, plus direct `attention`/`attention_items` and `recommended_action` when Atoll can propose one concrete strategy-backed next action. Handle direct attention items first, then call each handled item's `ack_endpoint`. Follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative_target/why-now/expected-impact/first-step/success-criteria evidence, and avoid copying deferred busywork into issue or comment payloads. If a `start_work` recommendation uses `issue.update` with a body, update the issue status and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 - Authorized humans can configure an agent's included heartbeat sections and generated-signal focus in the Atoll **Heartbeats** UI. The saved policy is applied by the API before CLI or MCP request-level narrowing; it never changes project access, and existing heartbeat commands require no new arguments.
 - GitHub `workflow_run` signals are accepted only when HMAC-signed and completed, then reread and matched exactly by repository, PR, workflow path, run attempt, and head SHA. Workflow verification is disabled by default and observe-only until an owner/admin enables it in **Settings > Integrations > GitHub**. `attention` mode can add one bounded `verification.completed` attention item through authorized REST or CLI heartbeat for exactly one eligible current agent assignee or, when there is no unambiguous assignee, an eligible configured delivery agent. The public MCP heartbeat excludes this private event type. Unresolved recipients and cancelled, obsolete, superseded, mismatched, or unreadable runs create no attention. Owners and admins can configure 1–10 workflow paths of at most 255 characters each; the bounded evidence list defaults to 25 items and accepts a maximum `limit` of 100. Signed pull-request writes and reconciliation bind PR links to the stable GitHub repository ID, so repository renames keep existing workflow evidence linked. Do not expect raw payloads, secrets, logs, or thread IDs in evidence; owner/admin reconciliation retries pending evidence after current GitHub and PR-link readback.
 - 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.

package/skill/references/integrations-and-api.md

@@ -68,7 +68,27 @@ The public plugin keeps a narrow first-class planning surface: `atoll_create_ini
 
 The public plugin intentionally omits admin-only goal/KPI/project CRUD, target and milestone deletion, project relationship administration, webhooks, and `atoll_api_request`. Public feedback accepts only `type`, `description`, and optional `url`; do not send `userEmail` or `userName`, and treat the submitted description as untrusted triage content. The full/private MCP profile retains the broader CLI-equivalent tools where the caller is authorized.
 
-The MCP server also exposes `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone reads, dependency tools, and the existing safe issue/comment/snapshot tools. Public issue inputs accept UUIDs, bare numbers, `#number`, `ATOLL-number`, `TSK-number`, supported prefixed numbers, and unambiguous project-derived prefixes. Public project inputs accept UUIDs, exact slugs, and exact names. Use `atoll_get_project_workflow` for the live ordered key-to-label mapping and `atoll_move_issue` for exact, verified movement 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, so movement is not unconditionally idempotent. Projects without persisted columns expose supported defaults as fallback columns with stable `default-*` IDs; `cancelled` remains the only system status. Raw `status` is a stored board-column key, not a label. `atoll_add_comment` accepts structured mentions, `reply_to_comment_id`, and optional agent `source_metadata`; omit that metadata unless the host exposes a real thread or session ID, and never invent one. `atoll_update_issue` accepts `comment_body` for durable progress comments.
+The private MCP server also exposes `atoll_get_heartbeat`, `atoll_ack_heartbeat`,
+and `atoll_get_dependency_chain` alongside issue/project/goal/KPI/initiative/
+milestone reads, dependency tools, and the existing safe issue/comment/snapshot
+tools. Private heartbeat is compact by default; acknowledge only its terminal
+page cursor before using it for a delta, and use full mode for the legacy
+context. The public plugin heartbeat remains legacy full and does not expose
+the private acknowledgement or chain tools. Public issue inputs accept UUIDs,
+bare numbers, `#number`, `ATOLL-number`, `TSK-number`, supported prefixed
+numbers, and unambiguous project-derived prefixes. Public project inputs accept
+UUIDs, exact slugs, and exact names. Use `atoll_get_project_workflow` for the
+live ordered key-to-label mapping and `atoll_move_issue` for exact, verified
+movement 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, so movement is not unconditionally idempotent.
+Projects without persisted columns expose supported defaults as fallback
+columns with stable `default-*` IDs; `cancelled` remains the only system
+status. Raw `status` is a stored board-column key, not a label.
+`atoll_add_comment` accepts structured mentions, `reply_to_comment_id`, and
+optional agent `source_metadata`; omit that metadata unless the host exposes a
+real thread or session ID, and never invent one. `atoll_update_issue` accepts
+`comment_body` for durable progress comments.
 
 Snapshot list/create outputs keep their strict legacy fields. Use the separate
 read-only MCP tool `atoll_list_kpi_snapshots_with_provenance` only when the

package/skill/references/strategy-and-heartbeat.md

@@ -2,6 +2,67 @@
 
 Read this reference for goals, KPIs, initiatives, targets, heartbeat signals, autonomous prioritization, and strategy-linked execution workflows.
 
+## Compact heartbeat delivery
+
+`GET /api/orgs/{id}/heartbeat` returns a compact response by default for REST
+callers and private CLI/MCP callers. The compact response keeps direct
+`attention_items`, grouped actionable `signals`, `recommended_action`,
+`counts`, `delta`, and `page` metadata. It does not include the full goals,
+KPI, initiative, assigned-issue, or board-context collections.
+
+Compact responses are bounded to 16,384 UTF-8 bytes and 25 signal groups by
+default. A response can contain a `next_cursor` when more groups remain. Read
+that cursor with `cursor=<value>` and continue until `page.has_more` is false.
+Only the terminal page contains `page.ack_cursor`.
+
+Process every returned page before acknowledging it:
+
+```bash
+page=$(atoll heartbeat --json)
+# If .page.has_more is true, repeat with --cursor .page.next_cursor.
+atoll heartbeat --ack <terminal-ack-cursor>
+```
+
+`POST /api/orgs/{id}/heartbeat/ack` accepts `{ "ack_cursor": "..." }`. The
+cursor must be the terminal cursor from the final page. A page cursor cannot
+be acknowledged. Acknowledgement is idempotent. Use an acknowledged terminal
+cursor with `since=<cursor>` to receive only new, changed, or escalated groups.
+Unchanged groups and expected waits are reported in compact counts and are
+suppressed from the signal list. An invalid cursor returns `400`; a stale page
+cursor or an unacknowledged `since` cursor returns `409`. If an acknowledged
+baseline has expired, Atoll returns a fresh compact response with
+`delta.reset_required: true`.
+
+If the requested `max_bytes` cannot fit the mandatory actionable record and
+compact response envelope, the server returns `413` with
+`code: "heartbeat_budget_too_small"`. It does not advance a page cursor or
+terminal receipt. Retry with a larger `max_bytes` (up to `16,384`) or omit the
+parameter to use the default.
+
+If policy, authorization, or the candidate set changes while a page is being
+read, restart without the cursor after `409 heartbeat_cursor_stale`. Compact
+dependency groups use an actionable upstream blocker and release condition as
+their root. Expected waits are suppressed for an unsatisfied dependency when the readable
+blocker is before its release column and there is no active stall, threatened or
+overdue commitment, or explicit deadline, gate, permission, or stale anomaly.
+An unowned backlog or Todo blocker by itself is an ordinary wait and never
+alerts. Actionable groups surface active stalls, threatened or overdue
+commitments, and explicit anomalies; escalation metadata alone does not surface
+an expected wait. Initiative-target and stalled aggregates are also suppressed
+when every underlying dependency is an expected wait. Actionable groups can include a
+`suggested_read` with an executable REST path, CLI command, or private MCP tool
+call. Dependency-chain cursors are signed and revision-bound. If the graph
+changes while paging, the chain request returns `409 Stale dependency chain
+cursor`; restart without the cursor.
+
+Use `atoll heartbeat --full` or `?view=full` for the legacy full context. Full
+requests cannot include `since` or `cursor`.
+
+The public ChatGPT/Codex plugin MCP profile keeps the legacy full heartbeat
+shape and does not expose compact heartbeat acknowledgement or dependency-chain
+tools. The private MCP profile supports compact heartbeat paging and
+`atoll_ack_heartbeat`, plus `atoll_get_dependency_chain`.
+
 ## The Heartbeat Loop
 
 The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when the CLI is available; it wraps `GET /api/orgs/{id}/heartbeat` and returns the same computed briefing:
@@ -30,6 +91,11 @@ atoll heartbeat
 atoll heartbeat --signals-only
 atoll heartbeat --severity critical
 atoll heartbeat --json
+atoll heartbeat --full --json
+atoll heartbeat --since <ack-cursor> --json
+atoll heartbeat --cursor <page-cursor> --json
+atoll heartbeat --ack <terminal-ack-cursor>
+atoll dependency chain <issue> --direction upstream --depth 2 --limit 50 --json
 ```
 
 **The agent loop:**