@atollhq/skill-codex 0.4.9 → 0.4.11

package/README.md

@@ -14,15 +14,25 @@ ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex@lat
 
 Optional defaults: `--project`, `--team`, and `--base-url` are stored with the selected mode. Use `--no-project`, `--no-team`, or `--no-base-url` to clear previously saved defaults. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports to `~/.zshrc` or `~/.bashrc` in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands, or omit `--profile` to use env-var mode.
 
+For multi-org setups, keep global Codex instructions neutral and bind profiles per repo:
+
+```bash
+npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-org-id \
+  --write-project-instructions --project-dir /path/to/repo --instruction-files agents,claude
+```
+
+`--write-project-instructions` writes a small managed block to repo-local instruction files. It requires `--profile`, defaults to the current directory, writes `AGENTS.md` by default, and can also write `CLAUDE.md` with `--instruction-files agents,claude`. If the target file already has unmanaged Atoll profile guidance, pass `--force-project-instructions` after reviewing the replacement.
+
 Get an agent API key from **Agents** in the Atoll app. Integration keys are still managed from **Settings > Members**.
 
-This does five things:
+This does six things:
 
 1. Installs the `atoll-api` skill to `~/.codex/skills/atoll-api/`
-2. Appends (or updates) an `# Atoll Integration` section in `~/.codex/AGENTS.md`
+2. Appends (or updates) a neutral `# Atoll Integration` section in `~/.codex/AGENTS.md`
 3. Copies API reference files to `~/.codex/atoll-references/`
 4. Creates or updates the named Atoll CLI profile when `--profile` is provided
 5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) only when no profile is provided
+6. Optionally writes repo-local profile guidance when `--write-project-instructions` is provided
 
 For profile mode, Codex has the Atoll skill immediately and terminal commands can use `atoll --profile agent-a ...`. For env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
 
@@ -48,9 +58,9 @@ For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@ato
 npm install -g @atollhq/cli
 atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --team team-id
 atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --no-team --no-base-url
-atoll heartbeat
-atoll issue list --json
-atoll agent-context
+atoll --profile agent-a heartbeat
+atoll --profile agent-a issue list --json
+atoll --profile agent-a agent-context
 ```
 
 For multiple agents or orgs, use CLI auth profiles:

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, renameSync, rmSync } from 'node:fs'
+import { join, dirname, resolve, basename } from 'node:path'
 import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 
@@ -20,6 +20,10 @@ function parseArgs(argv) {
     else if (argv[i] === '--no-team') args.clearTeam = true
     else if (argv[i] === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i]
     else if (argv[i] === '--no-base-url') args.clearBaseUrl = true
+    else if (argv[i] === '--write-project-instructions') args.writeProjectInstructions = true
+    else if (argv[i] === '--project-dir' && argv[i + 1]) args.projectDir = argv[++i]
+    else if (argv[i] === '--instruction-files' && argv[i + 1]) args.instructionFiles = argv[++i]
+    else if (argv[i] === '--force-project-instructions') args.forceProjectInstructions = true
     else if (argv[i] === '--help' || argv[i] === '-h') args.help = true
   }
   return args
@@ -40,12 +44,21 @@ Options:
   --no-team   Clear any saved default team.
   --base-url  Atoll base URL. Defaults to ATOLL_BASE_URL.
   --no-base-url Clear any saved custom base URL.
+  --write-project-instructions
+              Write a small repo-local Atoll profile block. Requires --profile.
+  --project-dir
+              Directory for repo-local instructions. Defaults to the current directory.
+  --instruction-files
+              Comma-separated files to update: agents, claude, or agents,claude. Defaults to agents.
+  --force-project-instructions
+              Replace existing unmanaged Atoll profile guidance in repo-local instruction files.
   --help      Show this help message
 
 Installs the Atoll integration for Codex CLI:
   - Installs the atoll-api skill to ~/.codex/skills/atoll-api/
-  - Writes AGENTS.md with API reference to ~/.codex/
+  - Writes neutral AGENTS.md API guidance to ~/.codex/
   - Creates/updates an Atoll CLI profile when --profile is provided
+  - Optionally writes repo-local AGENTS.md/CLAUDE.md profile guidance with --write-project-instructions
   - Otherwise writes Atoll env vars to your shell profile for env-var mode
 `)
 }
@@ -64,6 +77,32 @@ if (args.help) { printUsage(); process.exit(0) }
 
 console.log(`Running @atollhq/skill-codex installer v${packageJson.version}`)
 
+const instructionFileChoices = (args.instructionFiles ?? 'agents')
+  .split(',')
+  .map((entry) => entry.trim().toLowerCase())
+  .filter(Boolean)
+const allowedInstructionFiles = new Set(['agents', 'claude'])
+if (instructionFileChoices.some((entry) => !allowedInstructionFiles.has(entry))) {
+  console.error('Error: --instruction-files must be agents, claude, or agents,claude')
+  process.exit(1)
+}
+
+const projectInstructionFiles = [...new Set(instructionFileChoices)]
+if (args.writeProjectInstructions && projectInstructionFiles.length === 0) {
+  console.error('Error: --instruction-files must include agents, claude, or agents,claude')
+  process.exit(1)
+}
+
+if (args.writeProjectInstructions && !args.profile) {
+  console.error('Error: --write-project-instructions requires --profile so the repo-local guidance can name a profile')
+  process.exit(1)
+}
+
+if (args.writeProjectInstructions && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args.profile)) {
+  console.error('Error: --write-project-instructions requires a profile name that starts with a letter or number and contains only letters, numbers, dots, underscores, or hyphens')
+  process.exit(1)
+}
+
 if (!args.key || !args.org) {
   console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
@@ -104,7 +143,6 @@ function writeAtollProfile() {
   else delete profile.defaultTeam
   if (args.baseUrl) profile.baseUrl = args.baseUrl
   else delete profile.baseUrl
-  config.activeProfile = args.profile
 
   mkdirSync(atollDir, { recursive: true })
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
@@ -112,6 +150,107 @@ function writeAtollProfile() {
   return configPath
 }
 
+const projectInstructionsStart = '<!-- ATOLL:PROJECT-INSTRUCTIONS:START -->'
+const projectInstructionsEnd = '<!-- ATOLL:PROJECT-INSTRUCTIONS:END -->'
+const projectInstructionsPattern = new RegExp(`${projectInstructionsStart}[\\s\\S]*?${projectInstructionsEnd}`)
+
+function projectInstructionBlock(profileName) {
+  return `${projectInstructionsStart}
+## Atoll
+
+For this workspace, use Atoll CLI profile \`${profileName}\`:
+
+\`\`\`bash
+atoll --profile ${profileName} ...
+\`\`\`
+${projectInstructionsEnd}`
+}
+
+function removeUnmanagedAtollProfileGuidance(content) {
+  return content
+    .split('\n')
+    .filter((line) => !/atoll\s+--profile\s+\S+/i.test(line) && !/Atoll CLI profile/i.test(line))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()
+}
+
+function buildProjectInstructionUpdate(targetPath, block) {
+  const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf-8') : ''
+
+  if (projectInstructionsPattern.test(existing)) {
+    return {
+      targetPath,
+      content: existing.replace(projectInstructionsPattern, block),
+    }
+  }
+
+  if (/atoll\s+--profile\s+\S+/i.test(existing) || /Atoll CLI profile/i.test(existing)) {
+    if (!args.forceProjectInstructions) {
+      console.error(`Error: ${targetPath} already contains unmanaged Atoll profile guidance. Re-run with --force-project-instructions to replace it.`)
+      process.exit(1)
+    }
+    const cleaned = removeUnmanagedAtollProfileGuidance(existing)
+    return {
+      targetPath,
+      content: cleaned ? `${cleaned}\n\n${block}\n` : `${block}\n`,
+    }
+  }
+
+  return {
+    targetPath,
+    content: existing.trimEnd() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`,
+  }
+}
+
+function writeProjectInstructionUpdates(updates) {
+  const prepared = []
+
+  try {
+    for (const [index, { targetPath, content }] of updates.entries()) {
+      const tmpPath = join(dirname(targetPath), `.${basename(targetPath)}.atoll-${process.pid}-${Date.now()}-${index}.tmp`)
+      const normalized = content.endsWith('\n') ? content : `${content}\n`
+      writeFileSync(tmpPath, normalized, { flag: 'wx' })
+      prepared.push({ targetPath, tmpPath })
+    }
+
+    for (const { targetPath, tmpPath } of prepared) {
+      renameSync(tmpPath, targetPath)
+      console.log(`Wrote Atoll project instructions to ${targetPath}`)
+    }
+  } catch (error) {
+    for (const { tmpPath } of prepared) {
+      if (existsSync(tmpPath)) rmSync(tmpPath, { force: true })
+    }
+    console.error(`Error: failed to write Atoll project instructions: ${error.message}`)
+    process.exit(1)
+  }
+}
+
+function writeProjectInstructions() {
+  if (!args.writeProjectInstructions) return
+
+  const projectDir = resolve(args.projectDir ?? process.cwd())
+  if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+    console.error(`Error: --project-dir must be an existing directory: ${projectDir}`)
+    process.exit(1)
+  }
+
+  const block = projectInstructionBlock(args.profile)
+  const fileNames = {
+    agents: 'AGENTS.md',
+    claude: 'CLAUDE.md',
+  }
+
+  const updates = []
+  for (const choice of projectInstructionFiles) {
+    const targetPath = join(projectDir, fileNames[choice])
+    updates.push(buildProjectInstructionUpdate(targetPath, block))
+  }
+
+  writeProjectInstructionUpdates(updates)
+}
+
 // 1. Install the Codex skill to ~/.codex/skills/atoll-api/
 const codexDir = join(homedir(), '.codex')
 mkdirSync(codexDir, { recursive: true })
@@ -126,27 +265,9 @@ console.log(`Installed Atoll skill to ${skillDest}`)
 const skillMd = readFileSync(join(skillDir, 'SKILL.md'), 'utf-8')
 // Strip YAML frontmatter for AGENTS.md
 const body = skillMd.replace(/^---[\s\S]*?---\n*/, '')
-const profileModeInstructions = args.profile ? `## Profile-scoped CLI configuration
-
-This Codex install is scoped to Atoll CLI profile \`${args.profile}\`. No global \`ATOLL_API_KEY\`, \`ATOLL_ORG_ID\`, \`ATOLL_PROJECT\`, \`ATOLL_TEAM\`, or \`ATOLL_BASE_URL\` shell exports were written. Use \`atoll --profile ${args.profile} ...\` for direct Atoll CLI commands. Direct API snippets below use \`ATOLL_API_KEY\` / \`ATOLL_ORG_ID\` only when you intentionally choose env-var mode.
-
-` : ''
-const optionalCredentialLines = [
-  args.profile ? `- Atoll CLI profile: ${args.profile}` : null,
-  args.project ? `- Default project ID: ${args.project}` : null,
-  args.team ? `- Default team: ${args.team}` : null,
-  args.baseUrl ? `- Base URL: ${args.baseUrl}` : null,
-].filter(Boolean).join('\n')
-
 const agentsMd = `# Atoll Integration
 
-${profileModeInstructions}
 ${body}
-
-## Credentials
-
-- API Key: ${args.profile ? `stored in Atoll CLI profile \`${args.profile}\`` : 'set as ATOLL_API_KEY environment variable'}
-- Org ID: ${args.org}${optionalCredentialLines ? `\n${optionalCredentialLines}` : ''}
 `
 
 const agentsPath = join(codexDir, 'AGENTS.md')
@@ -193,10 +314,11 @@ if (args.profile) {
     console.log(`Removed stale Atoll shell exports from ${profilePath}`)
   }
   writeAtollProfile()
+  writeProjectInstructions()
   console.log('No Atoll shell exports were written.')
   console.log(`Run profile-scoped commands with: atoll --profile ${args.profile} ...`)
   console.log(`Verify the profile with: atoll --profile ${args.profile} agent-context --json`)
-  console.log(`\nDone! Codex has the Atoll skill installed, and the Atoll CLI profile "${args.profile}" is active.`)
+  console.log(`\nDone! Codex has the Atoll skill installed, and the Atoll CLI profile "${args.profile}" is configured.`)
   process.exit(0)
 }
 

package/package.json

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

package/skill/SKILL.md

@@ -123,6 +123,7 @@ 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
 
@@ -161,6 +162,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,14 +183,14 @@ 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
 
 When a human asks you to help automate a KPI from a third-party API, use this Atoll skill. If the current agent environment does not have the `atoll-api` skill installed, tell the user to install it before continuing or use the Atoll CLI/MCP tools directly if they are available.
 
-Agents may create draft syncs and validate proposed configs only after a human admin has allowlisted the exact destination host in Atoll. Human admins must review the draft in Atoll, enter secrets, dry-run, publish, disable, or run-now with snapshot writing.
+Agents may create draft syncs and validate proposed configs only after a human admin has allowlisted the exact destination host in Atoll. Human admins must create or review the draft in Settings > Integrations > KPI syncs, edit supported request/extraction fields and secrets through structured UI, dry-run, publish, disable, or run-now with snapshot writing.
 
 ```bash
 atoll kpi sync validate <kpi-id> \
@@ -313,14 +317,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 +341,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 +355,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 +367,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 +377,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 +425,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 +453,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 +505,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 |
@@ -203,6 +208,7 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | POST | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | Record a snapshot |
 | GET | `/api/orgs/{id}/kpi-http-sync-policy` | List exact-host KPI HTTP sync allowlist policy |
 | POST | `/api/orgs/{id}/kpi-http-sync-policy` | Add an allowed exact host (human admin only) |
+| GET | `/api/orgs/{id}/kpi-http-syncs` | List org-wide KPI HTTP sync review rows for Settings; admins get config/secret metadata, members get redacted status rows |
 | GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | List KPI HTTP syncs |
 | POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Create a draft KPI HTTP sync |
 | PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Validate a proposed KPI HTTP sync config without storing or running it |
@@ -244,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
 
@@ -259,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`.
 
@@ -271,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 |
@@ -419,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

@@ -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