@atollhq/skill-claude 0.4.10 → 0.4.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"

package/skill/SKILL.md

@@ -111,6 +111,7 @@ atoll agent-context
 # List tasks
 atoll issue list --json
 atoll issue list --status todo --priority 1 --limit 25
+atoll issue list --scope blocked --initiative initiative-uuid --order-by due_date --order-dir asc
 
 # View a task
 atoll issue get ATOLL-42
@@ -118,11 +119,13 @@ atoll issue view ATOLL-42   # alias kept for humans
 
 # Create a task
 atoll issue create --title "Fix login bug" --status todo --priority 1
+atoll issue create --title "Weekly status review" --due-date 2026-07-06 --recurrence weekly
 atoll issue upsert --match-title --project <project-id> --title "Fix login bug" --status todo
 atoll issue bulk-create --file ./issues.json --continue-on-error
 
 # Update a task
 atoll issue update ATOLL-42 --status in_progress
+atoll issue update ATOLL-42 --status in_progress --comment-body "Starting this because the activation KPI is off pace."
 atoll issue upsert ATOLL-42 --status in_progress
 atoll issue bulk-update --file ./updates.json --dry-run
 
@@ -133,6 +136,17 @@ atoll issue assign ATOLL-42 --to self
 # Comments
 atoll comment add ATOLL-42 --body "Working on this now"
 
+# Labels, notifications, subtasks, activity
+atoll label list
+atoll label add ATOLL-42 bug
+atoll notification list --json
+atoll notification ack notification-uuid
+atoll subtask create ATOLL-42 --title "Verify recurrence"
+atoll activity issue ATOLL-42
+
+# Read-only API fallback for uncommon inspection gaps
+atoll api get /api/orgs/$ATOLL_ORG_ID/labels --json
+
 # Dependencies
 atoll dependency bulk-add --file ./dependencies.json --continue-on-error
 
@@ -161,6 +175,9 @@ atoll kpi create --name paying_customers --goal "Reach 100 paying customers by Q
 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 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
+atoll initiative target issue link "Retailer coverage" "Get 5 retailers live by July 5" ATOLL-42
 atoll kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
 
 # Audit the strategy chain for gaps (orphaned initiatives, goals with no KPI, etc.)
@@ -179,7 +196,7 @@ CLI JSON conventions:
 - Diagnostics and errors go to stderr.
 - 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.
-- `atoll heartbeat --json` includes the same structured `cli` update metadata for agents.
+- `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 plan validate/apply` consumes `schemaVersion: "atoll.plan.v1"` files with `milestones`, `issues`, `dependencies`, `initiativeLinks`, and `milestoneLinks`; local `key` values can be referenced by `milestoneKey`, `issueKey`, `dependsOn`, `blockedBy`, or `blocks`.
 
 ## KPI HTTP Sync Drafts
@@ -292,7 +309,11 @@ Keep it practical. I want the smallest strategy layer that would help an AI agen
 
 ## Quick Start — API (for advanced use)
 
-All CLI commands map to REST endpoints. Use the API directly when the CLI doesn't cover a specific operation.
+All CLI commands map to REST endpoints. Use `atoll api get` for GET-only inspection gaps when a typed command does not exist yet. The CLI blocks `/api/internal/*`, billing, and KPI sync admin routes because some GET endpoints can run jobs, synchronize external state, or require human-admin review. Use direct API calls for writes only when the CLI does not cover a specific operation and the workflow is not human-admin-gated.
+
+```bash
+atoll api get "/api/orgs/$ATOLL_ORG_ID/issues?status=todo" --json
+```
 
 ```bash
 # Prereq: both env vars exported (see Authentication above)
@@ -313,14 +334,18 @@ The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when
 
 - **Goal status** with days remaining
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
-- **Initiative progress**: total/completed/stalled/blocked issue counts, expected KPI impacts
+- **Initiative progress**: total/completed/stalled/blocked issue counts, expected KPI impacts, and initiative targets
 - **Assigned work** for this agent
 - **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents
 - **Signals** sorted by severity — the agent's prioritized to-do list
+- **Attention items**: direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes, with an `ack_endpoint` to call after handling
+- **Recommended action**: one deterministic strategy-backed next action when Atoll has enough evidence (`create_work`, `start_work`, `escalate_blocker`, or `refresh_metric`), including why-now, expected impact, first step, success criteria, quality warnings, and any suggested write.
 
 Heartbeat is org-scoped, but project-bound payload details are filtered by the caller's project access. Owners/admins receive full org context; members/guests only receive project-bound strategy, work health, assigned work, milestone signals, and board context for accessible projects. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
 
-Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
+Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
+
+Targets under initiatives are commitments, not business KPIs. KPIs measure business outcomes such as MRR, traffic, paying customers, or onboarding success. Use progress targets for initiative outputs such as "publish 10 comparison posts." Use gate targets for launch prerequisites such as "get 5 retailers live by July 5." Gate targets emit stateful due/blocked messages and should not be converted into fractional KPI pace such as "0.07 retailers/day."
 
 Useful CLI forms:
 
@@ -333,10 +358,12 @@ atoll heartbeat --json
 
 **The agent loop:**
 1. Call heartbeat
-2. Read signals (highest severity first)
-3. Reason about highest-leverage action given KPI pace and initiative state
-4. Execute (unblock issues, update KPIs, create work, report progress)
-5. Repeat
+2. Handle direct `attention_items` that need a reply, task update, or blocker follow-up
+3. Call each handled item's `ack_endpoint`
+4. Read remaining signals (highest severity first)
+5. Reason about highest-leverage action given direct attention, gate targets, KPI pace, and initiative state
+6. Execute (unblock issues, update KPIs, create work, report progress)
+7. Repeat
 
 ## Other Common Workflows
 
@@ -345,7 +372,7 @@ atoll heartbeat --json
 ```bash
 atoll heartbeat --signals-only                        # orient first
 atoll issue list --status todo --assignee self --json # find assigned work
-atoll issue update ATOLL-42 --status in_progress      # start work
+atoll issue update ATOLL-42 --status in_progress --comment-body "Starting because the linked KPI is off pace." # start work with durable context
 atoll comment add ATOLL-42 --body "Progress update…"  # report progress
 atoll issue update ATOLL-42 --status done              # complete
 ```
@@ -357,7 +384,8 @@ atoll issue update ATOLL-42 --status done              # complete
 3. `POST /api/orgs/{id}/kpis/{kpiId}/snapshots` -- record measurement (auto-updates `current_value`)
 4. `POST /api/orgs/{id}/initiatives` -- create initiative linked to goal
 5. `POST /api/orgs/{id}/initiatives/{id}/kpi-impacts` -- declare expected KPI impact
-6. Link issues and milestones to the initiative
+6. `POST /api/orgs/{id}/initiatives/{id}/targets` -- create progress or gate targets for initiative commitments
+7. Link issues and milestones to the initiative and to specific targets when the work exists to satisfy that target
 
 CLI equivalent:
 
@@ -366,6 +394,8 @@ 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 initiative create --title "Content pipeline" --goal "Reach 100 paying customers by Q2" --status active
 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
 atoll kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
 ```
 
@@ -412,7 +442,7 @@ Delivery rows expose `delivery_id`, `status`, and `next_retry_at`. Network failu
 
 ### Billing and plan limits
 
-Owners/admins can read billing state with `GET /api/orgs/{id}/billing` and start Stripe checkout with `POST /api/orgs/{id}/billing/checkout` using `{ "plan": "starter" }` or `{ "plan": "team" }`.
+Owners/admins can read billing state with `GET /api/orgs/{id}/billing` and start a self-serve Stripe billing flow with `POST /api/orgs/{id}/billing/checkout` using `{ "plan": "starter" }`, `{ "plan": "team" }`, or `{ "plan": "pro" }`. Owner/admin read requests sync Stripe first and return `502` with `Stripe billing sync failed` if that sync cannot complete, rather than serving stale local billing state. New subscribers use Checkout; existing active, trialing, or past-due subscribers use a Billing Portal update confirmation.
 
 Creation endpoints can return `402` with `code: "PLAN_LIMIT_REACHED"` when an org reaches limits for humans, agents/integrations, active projects, or active issues.
 
@@ -440,6 +470,10 @@ Initiative create accepts `title` or legacy `name`, plus camelCase aliases `goal
 
 All endpoints are under `/api/orgs/{orgId}/...`.
 
+Issue comments inherit issue project permissions: listing comments requires access to the issue's project, comment writes (add, edit, delete) require write access to that project, edit/delete still require comment authorship, and guests cannot access comments on unprojected issues.
+
+Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stores and returns comment bodies as sanitized HTML. If sanitization leaves no visible text or safe media, the request returns `400` with `body is required` for direct comments or `comment_body is required` for issue updates with `comment_body`.
+
 † `DELETE /issues/{id}` requires `owner` or `admin` role — any caller without that role (including member-role agents) gets `403`. If you just need to remove a task, use `POST /api/orgs/{orgId}/issues/{issueId}/archive` (soft delete, no role gate); reverse with `DELETE` on the same path (unarchive). In the CLI, prefer `atoll issue archive <id>`. Permanent `atoll issue delete <id>` requires `--force` and supports `--dry-run`.
 
 ### Quick enum reference
@@ -488,7 +522,7 @@ atoll feedback resend fb_123
 ## Notes
 
 - Request bodies accept camelCase; responses use snake_case
-- Descriptions and comments support Markdown
+- Descriptions support Markdown; comment bodies accept Markdown/plain text or rich-text HTML and are stored as sanitized HTML
 - All timestamps are ISO 8601 UTC
 - Board statuses are customizable per project -- query `/board-columns` for available values and optional column descriptions
 - API changes appear in real-time on the web board

package/skill/references/api-endpoints.md

@@ -89,12 +89,12 @@ Access levels: `view`, `edit`, `admin` (default: `view`).
 
 ## Billing
 
-Org billing is managed through Stripe. Owners/admins can create checkout and billing portal sessions.
+Org billing is managed through Stripe. Owners/admins can start self-serve billing flows and create billing portal sessions.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/billing` | Get plan, status, usage, limits, and subscription summary |
-| POST | `/api/orgs/{id}/billing/checkout` | Create Stripe Checkout Session (`{ plan: "starter" \| "team" }`) |
+| GET | `/api/orgs/{id}/billing` | Get plan, status, usage, limits, and subscription summary; owner/admin read requests sync Stripe first and return `502` if that sync fails |
+| POST | `/api/orgs/{id}/billing/checkout` | Start Stripe billing flow (`{ plan: "starter" \| "team" \| "pro" }`); new subscribers use Checkout and existing active/trialing/past-due subscribers use Billing Portal update confirmation |
 | POST | `/api/orgs/{id}/billing/portal` | Create Stripe Billing Portal Session |
 
 Plan limits are enforced when creating projects, human members, agents/integrations, and active tasks. Limit errors return `402` with `code: "PLAN_LIMIT_REACHED"`.
@@ -106,7 +106,7 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | GET | `/api/orgs/{id}/issues` | List tasks (see filters below) |
 | POST | `/api/orgs/{id}/issues` | Create task |
 | GET | `/api/orgs/{id}/issues/{issueId}` | Get task detail |
-| PATCH | `/api/orgs/{id}/issues/{issueId}` | Update task |
+| PATCH | `/api/orgs/{id}/issues/{issueId}` | Update task; optional `comment_body` also adds a task comment in the same request |
 | DELETE | `/api/orgs/{id}/issues/{issueId}` | Delete task (admin/owner only) |
 | POST | `/api/orgs/{id}/issues/bulk` | Bulk create tasks (up to 50) |
 | GET | `/api/orgs/{id}/issues/search?q=...` | Search tasks by title |
@@ -120,7 +120,8 @@ Issue-centric initiative links follow task project permissions: reading links re
 - `status` -- `backlog`, `todo`, `in_progress`, `done`, `cancelled`
 - `priority` -- `0` (urgent), `1` (high), `2` (medium), `3` (low)
 - `projectId`, `assigneeId`, `teamId`, `milestoneId`
-- `q` -- search title and description (case-insensitive)
+- `q` -- full issue lists search title and description (case-insensitive)
+- Compact views (`view=board` or `view=list`) also support `assignee` (member ID or `unassigned`, including multi-assignee links), `initiativeId`, `scope` (`mine` or `blocked`), and `q` over title plus issue number
 - `includeArchived` -- `true` to include archived tasks
 - `orderBy` -- `created_at` (default), `updated_at`, `priority`, `due_date`, `title`, `status`
 - `orderDir` -- `asc` or `desc` (default)
@@ -149,6 +150,10 @@ Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`. Ci
 | PATCH | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Edit comment |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Delete comment |
 
+Issue comments inherit issue project permissions: listing comments requires access to the issue's project, comment writes (add, edit, delete) require write access to that project, edit/delete still require comment authorship, and guests cannot access comments on unprojected issues.
+
+Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stores and returns comment bodies as sanitized HTML. If sanitization leaves no visible text or safe media, the request returns `400` with `body is required` for direct comments or `comment_body is required` for issue updates with `comment_body`.
+
 ## Subtasks
 
 | Method | Endpoint | Description |
@@ -245,6 +250,19 @@ Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `owner
 | GET | `.../initiatives/{id}/milestones` | List linked milestones |
 | POST | `.../initiatives/{id}/milestones` | Link milestone (`{ milestone_id }`) |
 | DELETE | `.../initiatives/{id}/milestones/{milestoneId}` | Unlink milestone |
+| GET | `.../initiatives/{id}/targets` | List initiative targets |
+| POST | `.../initiatives/{id}/targets` | Create target (`{ title, mode?, current_value?, target_value?, unit?, unit_label?, target_date?, due_soon_days? }`) |
+| GET | `.../initiatives/{id}/targets/{targetId}` | Get target |
+| PATCH | `.../initiatives/{id}/targets/{targetId}` | Update target |
+| DELETE | `.../initiatives/{id}/targets/{targetId}` | Delete target |
+| GET | `.../initiatives/{id}/targets/{targetId}/issues` | List target issue links |
+| POST | `.../initiatives/{id}/targets/{targetId}/issues` | Link issue to target (`{ issue_id }`) |
+| DELETE | `.../initiatives/{id}/targets/{targetId}/issues/{issueId}` | Unlink issue from target |
+| GET | `.../initiatives/{id}/targets/{targetId}/milestones` | List target milestone links |
+| POST | `.../initiatives/{id}/targets/{targetId}/milestones` | Link milestone to target (`{ milestone_id }`) |
+| DELETE | `.../initiatives/{id}/targets/{targetId}/milestones/{milestoneId}` | Unlink milestone from target |
+
+Targets are initiative-level commitments. Use `mode: "progress"` for normal output tracking and `mode: "gate"` for launch blockers or prerequisites where KPI pace language would be misleading. Targets do not create KPI snapshots.
 
 ## Strategy
 
@@ -260,7 +278,7 @@ Returns findings only (not the full graph). Use it for a high-level review — o
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/heartbeat` | Get heartbeat context for the authenticated agent |
 
-Returns computed briefing with goal status, KPI pace/trend, initiative progress, assigned work, and signals. The endpoint is org-scoped, but project-bound payload details are filtered by the caller's project access; non-guest members can also see unprojected org-level strategy, and shared initiatives can appear with counts and signals based only on accessible work.
+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; non-guest members can also see unprojected org-level strategy, and shared initiatives can appear with counts and signals based only on accessible work.
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -272,6 +290,8 @@ atoll heartbeat --signals-only
 atoll heartbeat --severity critical
 ```
 
+`atoll heartbeat --signals-only --json` returns filtered `signals`, direct `attention_items`, `attention_summary`, and `recommended_action` for polling agents.
+
 ## Activity
 
 | Method | Endpoint | Description |
@@ -420,10 +440,16 @@ URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
+| GET | `/api/orgs/{id}/notifications` | List unread actionable notifications for current org member |
+| POST | `/api/orgs/{id}/notifications/{notificationId}/ack` | Acknowledge current-member notification |
+| GET | `/api/orgs/{id}/notifications/preferences` | Read current-member notification preferences, including default-on mention notifications |
+| POST | `/api/orgs/{id}/notifications/preferences` | Update current-member notification preferences, including mention opt-out and cleanup |
 | GET | `/api/notifications` | List notifications (last 50, unread first) |
 | POST | `/api/notifications/{id}/read` | Mark as read |
 | POST | `/api/notifications/read-all` | Mark all as read |
 
+Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences currently support mention opt-out for `mention.created`. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`.
+
 ## Agents
 
 | Method | Endpoint | Description |

package/skill/references/api-fields.md

@@ -43,7 +43,7 @@ Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also
 }
 ```
 
-All fields work on both POST (create) and PATCH (update).
+Most fields work on both POST (create) and PATCH (update). `labelIds` is accepted on task create and bulk create. For existing tasks, use the label endpoints or `atoll label add/remove`.
 
 - **Multiple assignees**: Use `assigneeIds` (array). Legacy `assigneeId` (single) still works. Responses include `assignees` array with `id`, `display_name`, `type`, `avatar_url`.
 - **Start date**: Sets when work begins. Combined with `dueDate`, defines the Gantt time span.
@@ -201,6 +201,27 @@ Use `title` for create/update requests; create also accepts legacy `name`. Atoll
 
 Add/remove projects with `{ "project_id": "uuid" }`.
 
+## Initiative Target Fields
+
+Targets attach to initiatives and track commitments separately from business KPIs. Use `mode: "progress"` for initiative outputs and `mode: "gate"` for hard launch prerequisites. Gate target heartbeat signals use stateful copy such as `0/5 retailers complete`; agents must not convert them into fractional KPI pace.
+
+```json
+{
+  "title": "Get 5 retailers live by July 5",
+  "description": "Prerequisite before price comparison launch",
+  "mode": "gate",
+  "unit": "count",
+  "unit_label": "retailers",
+  "current_value": 0,
+  "target_value": 5,
+  "target_direction": "increase",
+  "target_date": "2026-07-05",
+  "due_soon_days": 7
+}
+```
+
+Target work links use `{ "issue_id": "issue-uuid" }` at `.../targets/{targetId}/issues` and `{ "milestone_id": "milestone-uuid" }` at `.../targets/{targetId}/milestones`. Target response rows include linked `issueIds` and `milestoneIds` when returned by the target list/get endpoints.
+
 ## Automation Rule Fields
 
 ```json
@@ -233,7 +254,7 @@ Add/remove projects with `{ "project_id": "uuid" }`.
 
 ## Board Context Response
 
-`GET /api/orgs/{id}/projects/{projectId}/board-context` returns the strategy data used by the board context rail:
+`GET /api/orgs/{id}/projects/{projectId}/board-context` returns the strategy data used by the board filter toolbar:
 
 ```json
 {
@@ -333,7 +354,20 @@ Proposal JSON currently supports at most one item in each collection: `projects`
       "total_issues": 8,
       "completed_issues": 3,
       "stalled_issues": 2,
-      "blocked_issues": 1
+      "blocked_issues": 1,
+      "project_ids": ["..."],
+      "linked_issues": [{
+        "id": "...",
+        "title": "Publish comparison page",
+        "status": "todo",
+        "priority": 1,
+        "assignee_id": "...",
+        "project_id": "...",
+        "milestone_id": null,
+        "number": 42,
+        "blocked": false,
+        "updated_at": "2026-03-28T12:00:00Z"
+      }]
     }]
   }],
   "standalone_kpis": [...],
@@ -349,12 +383,59 @@ Proposal JSON currently supports at most one item in each collection: `projects`
   }],
   "signals": [
     { "type": "kpi_off_pace", "severity": "warning", "message": "..." }
-  ]
+  ],
+  "recommended_action": {
+    "id": "create_work:...",
+    "action_type": "create_work",
+    "title": "Create Content pipeline work for paying_customers",
+    "target_type": "initiative",
+    "target_id": "...",
+    "goal_id": "...",
+    "kpi_id": "...",
+    "initiative_id": "...",
+    "source_signal_ids": ["kpi_off_pace:..."],
+    "why_now": "paying_customers is off pace, and Content pipeline has no active linked issue.",
+    "expected_impact": "Create the missing execution path for the initiative expected to move paying_customers: +30 signups/mo.",
+    "evidence": ["KPI \"paying_customers\" is off pace..."],
+    "first_step": "Open Content pipeline and define the smallest task that can move paying_customers.",
+    "success_criteria": ["Create or update concrete follow-up actions tied to paying_customers."],
+    "suggested_write": {
+      "operation": "issue.create",
+      "title": "Create Content pipeline work for paying_customers",
+      "body": "<h2>Why now</h2>...",
+      "status": "todo",
+      "priority": 1,
+      "project_id": "...",
+      "initiative_id": "...",
+      "kpi_id": "...",
+      "initiative_target_id": "..."
+    },
+    "confidence": "high",
+    "caveats": [],
+    "quality_checks": [{ "id": "kpi_link", "status": "pass", "message": "Recommendation includes a KPI link." }],
+    "usage_guidance": {
+      "instructions": [
+        "Prefer suggested_write.operation when it matches the current board state and the recommendation is still current.",
+        "Preserve goal, KPI, initiative, initiative target, why-now, expected impact, first step, suggested_write, and success criteria evidence in any issue, status update, KPI refresh, or comment you create.",
+        "Do not copy deferred busywork, unrelated tasks, or caveat text into write payloads unless it is directly needed for the recommended action."
+      ],
+      "preserve_fields": ["goal_id", "kpi_id", "initiative_id", "initiative_target_id", "why_now", "expected_impact", "first_step", "success_criteria", "suggested_write"],
+      "avoid_payload_sources": ["deferred_busywork", "unrelated_assigned_issues", "stale_recommendations_after_board_change"]
+    }
+  }
 }
 ```
 
 Heartbeat is org-scoped, but project-bound goals, KPIs, initiatives, issue health, milestone signals, assigned work, and `project_context` are filtered by the caller's project access. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
 
+Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
+
+Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type` (currently `mention.created`), `channel` (currently `in_app`), and `enabled` for current-member mention opt-out. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`.
+
+Agents should 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 in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When `start_work` uses `suggested_write.operation: "issue.update"` with a body, apply the status update and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
+
+`recommended_action` is a deterministic strategy-backed next action built from heartbeat context. MVP action types are `create_work`, `start_work`, `escalate_blocker`, and `refresh_metric`; suggested writes may prefill issue creation, issue status updates, blocker comments, or KPI refresh requests. Issue-create bodies are HTML for Atoll's rich-text issue description; blocker/comment and metric-refresh bodies are plain text.
+
 ## Strategy Audit Response
 
 `GET /api/orgs/{id}/strategy/audit` returns findings (sorted critical → warning → info), each with a concrete `suggested_fix`, plus summary counts.
@@ -376,11 +457,11 @@ Heartbeat is org-scoped, but project-bound goals, KPIs, initiatives, issue healt
 }
 ```
 
-Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiative_id`, `issue_id`, `milestone_id`, `project_id`. Finding `type` values:
+Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiative_id`, `initiative_target_id`, `issue_id`, `milestone_id`, `project_id`. Finding `type` values:
 
 - Structural: `initiative_orphaned`, `kpi_orphaned`, `goal_missing_kpi`, `goal_missing_initiative`, `dangling_initiative_project`, `dangling_initiative_issue`, `dangling_initiative_milestone`
 - KPI health: `kpi_unrecorded`, `kpi_missing_target`, `kpi_stale`, `kpi_off_pace`
-- Initiative health: `initiative_missing_impact`, `initiative_missing_execution`, `initiative_stalled`
+- Initiative health: `initiative_missing_impact`, `initiative_missing_execution`, `initiative_stalled`, `initiative_target_missing_execution`, `initiative_target_overdue`, `initiative_target_blocked`
 - Execution: `issue_blocked`, `issue_overdue`, `milestone_overdue`
 
 ## Analytics Response
@@ -403,6 +484,7 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Task | `status` | `backlog`, `todo`, `in_progress`, `done`, `cancelled` (custom per project via board-columns) |
 | Board column | `description` | Optional stage criteria or agent guidance |
 | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) |
+| Task update request | `comment_body` | Optional Markdown/plain text or rich-text HTML comment body created with the issue update; stored and returned as sanitized HTML |
 | Task | `recurrenceType` | `daily`, `weekly`, `monthly`, `yearly` |
 | Goal | `status` | `active`, `achieved`, `missed`, `paused`, `cancelled` |
 | KPI | `unit` | `count`, `percentage`, `currency`, `duration`, `ratio`, `custom` |
@@ -417,7 +499,7 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Member | `role` | `owner`, `admin`, `member`, `guest` |
 | Project member | `accessLevel` | `view`, `edit`, `admin` |
 | Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed` |
-| Heartbeat signal | `type` | `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing` |
+| Heartbeat signal | `type` | `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing` |
 | Heartbeat signal | `severity` | `info`, `warning`, `critical` |
 | Custom view | `display_mode` | `board`, `list` |
 
@@ -430,7 +512,7 @@ REST list responses use resource-specific keys by default. Main list endpoints s
 ## Notes
 
 - All timestamps are ISO 8601 in UTC
-- Description and comment fields support Markdown
+- Descriptions support Markdown; comment bodies accept Markdown/plain text or rich-text HTML and are stored as sanitized HTML
 - Board columns (statuses) are customizable per project -- query `/board-columns` for available statuses and optional descriptions
 - Default statuses for new projects: `backlog`, `todo`, `in_progress`, `done`
 - `cancelled` is always valid but not shown on the board