@atollhq/skill-codex 0.4.33 → 0.4.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "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:
@@ -44,6 +53,18 @@ Read only the references required for the current task:
 - Request and response fields, enums, and validation:
   [api-fields.md](references/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.
+
+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](references/api-endpoints.md) and
+[api-fields.md](references/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

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.
 
@@ -634,10 +681,12 @@ deferred; parent deletion returns after durable queueing.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | POST | `/api/orgs/{id}/members/{memberId}/avatar` | Upload avatar to public `avatars` bucket (multipart, max 2MB, JPEG/PNG/WebP/GIF) |
+| PATCH | `/api/orgs/{id}/members/{memberId}/avatar` | Select an allowlisted built-in agent icon preset (`{ preset }`) |
 | DELETE | `/api/orgs/{id}/members/{memberId}/avatar` | Remove avatar |
 
 Members may manage their own avatar; organization owners/admins may manage
-another member only inside the same path organization. Cross-organization
+another member only inside the same path organization. A human may also manage
+a guest agent avatar when they created the agent or own the personal agent. Cross-organization
 caller or target IDs return `404`. Upload returns
 `{ "member": { "id": "...", "avatar_url": "..." } }` with no other member
 metadata. Avatar updates use compare-and-set semantics: concurrent changes
@@ -849,9 +898,30 @@ failed without executing its actions.
 | POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload (owner/admin) |
 | POST | `/api/webhooks/{id}/test` | Send ping test event (owner/admin) |
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Later lists expose only `destination_display` such as `https://example.com/…`.
-
-Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history returns safe status, `error_code`, and retry timing only—not payloads, receiver response bodies, or raw errors. Atoll retries network failures and 5xx responses after 5s and 30s, then records `status: retry_pending` with `next_retry_at`; an internal cron drains due retries every 15 minutes.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Later lists expose only `destination_display` such as `https://example.com/…`; Standard Webhooks exposes only its configured boolean.
+
+Automation action deliveries use payload schema version `3` with current
+tenant-scoped issue and project fields. Subscription broadcasts and `ping`
+remain schema version `2`; existing queued payloads retain their stored schema
+and content. V3 includes safe sorted `trigger.changedFields`, optional
+privacy-safe artifact counts, and `project: null` for projectless issues. An
+artifact summary is omitted when its lookup fails, returns an invalid type, or
+cannot complete within the bounded 1,000-row pagination limit. CI
+actions set `issue: null`, `changedFields: []`, and retain only useful CI fields.
+Both versions omit descriptions, comment bodies, and raw change values. Delivery
+requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned
+`X-Atoll-Signatures`, `X-Atoll-Delivery-Id`, and `Idempotency-Key`. Standard
+Webhooks adds `webhook-id`, `webhook-timestamp`, and
+`webhook-signature: v1,<base64>`; the signature covers
+`deliveryId.timestamp.rawBody` with the decoded receiver key. Automatic retries
+preserve delivery id/key with fresh timestamps/signatures; manual redelivery
+uses new values, preserves v3 body content, and rewrites only legacy v2 automation bodies that contain
+`data.deliveryId`. Delivery history returns safe status, `error_code`, and retry
+timing only—not payloads, receiver response bodies, or raw errors. Atoll makes
+one 30-second request attempt per invocation. Network failures and 5xx
+responses are recorded as `status: retry_pending` with `next_retry_at`; an
+internal cron drains due retries every 15 minutes. A 2xx response proves
+acceptance only.
 
 ## Private Inbound Email Inbox
 
@@ -905,7 +975,7 @@ Google Chat mention cards include the task title, a safely formatted plain-text
 | GET | `/api/orgs/{id}/agents` | List agents (owner/admin) |
 | GET | `/api/orgs/{id}/agents/workforce` | Read a bounded workforce projection; org owners/admins may list all agents, project admins must pass `?projectId=...`, and individual owners may read their own agents |
 | GET | `/api/orgs/{id}/agents/manageable` | List manageable agents with visible project IDs, named accessible projects, heartbeat policy status/focus summary, API-key usage metadata, and aggregate active-key/OAuth activity |
-| POST | `/api/orgs/{id}/agents` | Create org agent (`{ name, role?, setupScoped? }`), project-scoped agent (`{ name, projectIds }` or legacy `{ name, projectId, projectIds? }`), or personal agent (`{ name, personal: true }`); key-minting responses include one-time `apiKey` and stable `apiKeyId` (`oauthOnly` omits both) |
+| POST | `/api/orgs/{id}/agents` | Create org, project-scoped, or personal agent; optional `avatarPreset` accepts only a built-in agent icon ID, and key-minting responses include one-time `apiKey` and stable `apiKeyId` (`oauthOnly` omits both) |
 | DELETE | `/api/orgs/{id}/agents/{agentId}` | Revoke manageable agent |
 | PATCH | `/api/orgs/{id}/agents/{agentId}/projects` | Replace project access for a manageable non-personal agent |
 | POST | `/api/orgs/{id}/projects/{projectId}/agents` | Grant selected manageable agents access to a project |

package/skill/references/api-fields.md

@@ -153,7 +153,7 @@ Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also
 
 ## Avatar Upload Response
 
-Successful `POST /api/orgs/{id}/members/{memberId}/avatar` requests return
+Successful `POST` uploads and `PATCH` preset selections at `/api/orgs/{id}/members/{memberId}/avatar` return
 `200` with exactly:
 
 ```json
@@ -244,7 +244,7 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 ## Agent Fields
 
-Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`.
+Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`. Any create form may include an allowlisted `avatarPreset` ID. Arbitrary URLs are rejected. Existing agent presets are changed with `{ "preset": "codex" }` on the avatar PATCH endpoint.
 
 Key-minting agent creation responses contain the one-time raw `apiKey` and its stable `apiKeyId`. Creation with `oauthOnly: true` omits both fields.
 
@@ -539,7 +539,11 @@ characters), and legacy `close_issue` (omit `value`, targets the valid `done` ke
 The destination must be enabled, same-org, and purpose `automation` or `both`.
 Queued transport retries do not re-run the automation action. Activity exposes
 `webhook_delivery_id` plus safe latest-attempt `webhook_delivery` state.
-Manual redelivery uses a new header and payload delivery ID.
+Automation payloads use schema v3 with current tenant-scoped project and issue
+fields, safe sorted `trigger.changedFields`, and optional artifact counts; CI
+uses `issue: null` and `changedFields: []`. Subscription broadcasts and `ping`
+remain schema v2. Manual redelivery uses a new header and rewrites a payload
+delivery ID only for legacy v2 automation bodies that contain that field.
 Already satisfied assignments, priorities, statuses, and label relationships
 succeed without duplicate mutation events. Invalid references still fail.
 Unsupported action types or malformed values return `400` and are not saved.
@@ -752,10 +756,10 @@ reject `position`.
 
 ## Webhook Fields
 
-Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing.
+Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing. The optional `standard_webhooks` setting accepts a receiver-supplied `whsec_` secret; it is write-only and must be canonical standard Base64 after the prefix, decoding to 24-64 bytes. Lists expose only `standard_webhooks.configured`.
 
 `PATCH /api/webhooks/{id}` preserves omitted fields. A blank or omitted Bearer
-secret preserves the token; `auth.type: none` clears it. URL/auth changes create
+secret preserves the token; `auth.type: none` clears it. URL/auth/Standard signing changes create
 a new private destination version; pending deliveries retain their pinned version.
 
 ```json
@@ -764,13 +768,17 @@ a new private destination version; pending deliveries retain their pinned versio
   "events": ["issue.created", "issue.updated"],
   "enabled": true,
   "purpose": "subscription",
-  "auth": { "type": "none" }
+  "auth": { "type": "none" },
+  "standard_webhooks": {
+    "enabled": true,
+    "secret": "whsec_<canonical-standard-base64>"
+  }
 }
 ```
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a `secret` for HMAC signature verification. Store it immediately; it is shown only once. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes an Atoll-generated `secret` for HMAC signature verification. Store it immediately; it is shown only once. This is distinct from the receiver-supplied Standard Webhooks `whsec_` secret. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
 
-List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Payload schema version `2` is allowlisted. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
+List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Automation action payloads use schema version `3` with current tenant-scoped project and issue fields; subscription broadcasts and `ping` remain schema version `2`. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, `X-Atoll-Delivery-Id`, and `Idempotency-Key`. When Standard Webhooks is enabled, they also include `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
 
 ## Private Inbox Fields
 
@@ -815,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" },
@@ -1136,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
@@ -183,7 +196,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
@@ -207,14 +227,55 @@ Config sessions and unused manual connect tokens expire after 10 minutes. Sessio
 
 `POST /api/webhooks` creates outbound webhooks. Receiver URLs must be HTTPS DNS hostnames; Atoll rejects IP literals, `localhost`, `.local` hosts, URL credentials, and fragments at creation. Delivery also resolves DNS and refuses private, loopback, link-local, documentation, multicast, and other non-public addresses; redirects are not followed.
 
-Webhook creation returns a raw `whsec_...` secret once. Delivery requests include:
+Webhook creation returns an Atoll-generated signing `secret` once. Store it
+immediately; it is distinct from the receiver-supplied Standard Webhooks
+`whsec_` secret. Delivery requests include:
 
 - `X-Atoll-Signature`: `sha256=` plus an HMAC-SHA256 over the raw body, keyed by the SHA-256 hex digest of the raw secret.
 - `X-Atoll-Signature-Version`: the primary signing-key version.
 - `X-Atoll-Signatures`: versioned signatures during a bounded key-overlap window.
 - `X-Atoll-Delivery-Id`: stable delivery id for receiver-side deduplication.
-
-Webhook administration is owner/admin only. Lists return an origin-only `destination_display`; paths, queries, and signing material are never returned. Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery rows expose safe `delivery_id`, `status`, `status_code`, `error_code`, and retry timing, but not payloads, receiver response bodies, or raw errors. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
+- `Idempotency-Key`: present on every outbound delivery; it is the same logical delivery id across automatic retries, while manual redelivery uses a new id and key.
+- Optional Standard Webhooks signing adds `webhook-id`, `webhook-timestamp`, and `webhook-signature: v1,<base64>` using the receiver's canonical `whsec_` secret (24-64 decoded bytes). The signature covers `deliveryId.timestamp.rawBody`. A 2xx response proves acceptance only.
+
+
+
+### Receiver setup
+
+Grok Automations supports this Standard Webhooks option. Configure an
+`automation` destination with the receiver-supplied `whsec_` value from Grok.
+Grok validates `webhook-id`, `webhook-timestamp`, and
+`webhook-signature: v1,<base64>` within a five-minute timestamp window; HTTP
+202 means accepted for processing, not completed.
+
+Hermes supports the same Standard Webhooks `whsec_` verification on a public
+HTTPS `/webhooks/<route>` endpoint. Configure the Hermes receiver route/filter
+with `events: ["automation.action"]`; this is a receiver setting. In Atoll, set
+the destination `purpose` to `automation` (or `both`) and trigger it with an
+explicit `send_webhook` action; the Atoll destination `events` field does not
+select automation actions. Hermes should allowlist and render these v3 fields
+when present: `data.project`, `data.issue`, `data.automation.ruleId`,
+`data.automation.ruleName`, `data.trigger.eventType`, and
+`data.trigger.changedFields`. Issue payloads also include the current persisted
+`id`, optional `identifier` and `url`, `title`, `status`, `priority`, `assigneeId`,
+`updatedAt`, and an optional privacy-safe `artifacts` count. CI payloads set
+`data.issue` to null and retain only the useful `ci` fields, so handle CI events
+separately. Hermes can use `webhook-id` for one-hour deduplication. A 2xx
+response is receiver acceptance, not agent completion. No live Hermes receiver
+test was run; this setup guidance is based on source compatibility.
+
+Webhook administration is owner/admin only. Lists return an origin-only
+`destination_display`; paths, queries, and signing material are never returned.
+Automation action payloads use schema version `3`; subscription broadcasts and
+`ping` remain schema version `2`. Existing queued payloads retain their stored
+schema and content. Artifact summaries are omitted when lookup fails, data is
+invalid, or counting cannot complete within the bounded 1,000-row pagination
+limit. Both versions omit descriptions, comment bodies, and raw change values.
+Delivery rows expose safe `delivery_id`, `status`, `status_code`,
+`error_code`, and retry timing, but not payloads, receiver response bodies, or
+raw errors. Each invocation makes one 30-second request attempt. Network
+failures and 5xx responses persist `status: retry_pending` with
+`next_retry_at`; an internal drain retries due deliveries every 15 minutes.
 
 ### GitHub delivery context
 

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:**