@atollhq/skill-claude 0.4.0 → 0.4.3

package/README.md

@@ -7,19 +7,20 @@ Gives your Claude Code agent the ability to manage tasks, goals, KPIs, initiativ
 ## Install
 
 ```bash
-npx @atollhq/skill-claude --key sk_atoll_... --org your-org-id --project project-id --team team-id
+npx @atollhq/skill-claude --profile agent-a --key sk_atoll_... --org your-org-id --project project-id --team team-id
 # or
 ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-claude
 ```
 
-Optional defaults: `--project`, `--team`, and `--base-url` write `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` for the agent.
+Optional defaults: `--profile`, `--project`, `--team`, and `--base-url` write `ATOLL_PROFILE`, `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` for the agent. Use `--no-project`, `--no-team`, or `--no-base-url` to clear previously saved defaults. When `--profile` is set, the installer also creates or updates that profile in `~/.atoll/config.json`.
 
 Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
 
-This does two things:
+This does three things:
 
 1. Copies the skill into `~/.claude/skills/atoll-api/`
 2. Writes Atoll env vars into `~/.claude/settings.json` under `env`
+3. Creates or updates the named Atoll CLI profile when `--profile` is provided
 
 Restart Claude Code and the `atoll-api` skill is available.
 

package/bin/install.mjs

@@ -10,16 +10,24 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 function parseArgs(argv) {
   const args = {}
   for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === '--key' && argv[i + 1]) {
+    if (argv[i] === '--profile' && argv[i + 1]) {
+      args.profile = argv[++i]
+    } else if (argv[i] === '--key' && argv[i + 1]) {
       args.key = argv[++i]
     } else if (argv[i] === '--org' && argv[i + 1]) {
       args.org = argv[++i]
     } else if (argv[i] === '--project' && argv[i + 1]) {
       args.project = argv[++i]
+    } else if (argv[i] === '--no-project') {
+      args.clearProject = true
     } else if (argv[i] === '--team' && argv[i + 1]) {
       args.team = argv[++i]
+    } 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] === '--help' || argv[i] === '-h') {
       args.help = true
     }
@@ -29,15 +37,19 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-claude --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
+Usage: npx @atollhq/skill-claude [--profile <name>] --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
    or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-claude
 
 Options:
+  --profile   Atoll CLI profile name to create/update. Defaults to ATOLL_PROFILE.
   --key       Atoll API key (sk_atoll_...). Defaults to ATOLL_API_KEY.
   --org       Organization ID. Defaults to ATOLL_ORG_ID.
   --project   Default project ID. Defaults to ATOLL_PROJECT.
+  --no-project Clear any saved default project.
   --team      Default team ID or slug. Defaults to ATOLL_TEAM.
+  --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.
   --help      Show this help message
 
 This installs the Atoll skill for Claude Code, giving your agent
@@ -46,11 +58,15 @@ the ability to manage tasks, goals, KPIs, and initiatives.
 }
 
 const args = parseArgs(process.argv)
+args.profile ??= process.env.ATOLL_PROFILE
 args.key ??= process.env.ATOLL_API_KEY
 args.org ??= process.env.ATOLL_ORG_ID
-args.project ??= process.env.ATOLL_PROJECT
-args.team ??= process.env.ATOLL_TEAM
-args.baseUrl ??= process.env.ATOLL_BASE_URL
+if (args.clearProject) delete args.project
+else args.project ??= process.env.ATOLL_PROJECT
+if (args.clearTeam) delete args.team
+else args.team ??= process.env.ATOLL_TEAM
+if (args.clearBaseUrl) delete args.baseUrl
+else args.baseUrl ??= process.env.ATOLL_BASE_URL
 
 if (args.help) {
   printUsage()
@@ -68,6 +84,42 @@ if (!args.key.startsWith('sk_atoll_')) {
   process.exit(1)
 }
 
+function readJson(path) {
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    console.error(`Warning: could not parse ${path}, creating fresh config`)
+    return {}
+  }
+}
+
+function writeAtollProfile() {
+  if (!args.profile) return
+
+  const atollDir = join(homedir(), '.atoll')
+  const configPath = join(atollDir, 'config.json')
+  const config = readJson(configPath)
+  config.profiles ??= {}
+  config.profiles[args.profile] ??= {}
+  const profile = config.profiles[args.profile]
+
+  profile.apiKey = args.key
+  profile.orgId = args.org
+  delete profile.orgSlug
+  if (args.project) profile.defaultProject = args.project
+  else delete profile.defaultProject
+  if (args.team) profile.defaultTeam = args.team
+  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')
+  console.log(`Configured Atoll CLI profile "${args.profile}" in ${configPath}`)
+}
+
 // 1. Copy skill files to ~/.claude/skills/atoll-api/
 const skillSrc = join(__dirname, '..', 'skill')
 const skillDest = join(homedir(), '.claude', 'skills', 'atoll-api')
@@ -78,25 +130,25 @@ console.log(`Installed skill to ${skillDest}`)
 
 // 2. Write credentials to ~/.claude/settings.json env vars
 const settingsPath = join(homedir(), '.claude', 'settings.json')
-let settings = {}
-if (existsSync(settingsPath)) {
-  try {
-    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'))
-  } catch {
-    console.error(`Warning: could not parse ${settingsPath}, creating fresh settings`)
-    settings = {}
-  }
-}
+let settings = readJson(settingsPath)
 
 if (!settings.env) settings.env = {}
+if (args.profile) settings.env.ATOLL_PROFILE = args.profile
 settings.env.ATOLL_API_KEY = args.key
 settings.env.ATOLL_ORG_ID = args.org
 if (args.project) settings.env.ATOLL_PROJECT = args.project
+else delete settings.env.ATOLL_PROJECT
 if (args.team) settings.env.ATOLL_TEAM = args.team
+else delete settings.env.ATOLL_TEAM
 if (args.baseUrl) settings.env.ATOLL_BASE_URL = args.baseUrl
+else delete settings.env.ATOLL_BASE_URL
 
 writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
-const configuredVars = ['ATOLL_API_KEY', 'ATOLL_ORG_ID']
+writeAtollProfile()
+
+const configuredVars = []
+if (args.profile) configuredVars.push('ATOLL_PROFILE')
+configuredVars.push('ATOLL_API_KEY', 'ATOLL_ORG_ID')
 if (args.project) configuredVars.push('ATOLL_PROJECT')
 if (args.team) configuredVars.push('ATOLL_TEAM')
 if (args.baseUrl) configuredVars.push('ATOLL_BASE_URL')

package/package.json

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

package/skill/SKILL.md

@@ -151,9 +151,20 @@ atoll feedback "The status error should list custom board statuses"
 atoll project list
 atoll milestone list --project <project-id>
 atoll milestone upsert --project <project-id> --name "v1.0" --date 2026-06-01
+
+# Goals, KPIs, and initiatives
+atoll goal create --title "Reach 100 paying customers by Q2" --target-date 2026-06-30
+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 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.)
+atoll strategy audit
+atoll strategy audit --severity critical --json
 ```
 
-Prefer the CLI for routine task operations, heartbeat checks, comments, and feedback. Use direct API calls when the CLI does not expose the needed endpoint yet.
+Prefer the CLI for routine task operations, heartbeat checks, comments, feedback, and strategy setup. Use direct API calls when the CLI does not expose the needed endpoint yet.
 
 CLI JSON conventions:
 
@@ -163,6 +174,93 @@ CLI JSON conventions:
 - `atoll agent-context` returns a versioned command/flag manifest and available profile context.
 - `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`.
 
+## Remote MCP Server
+
+Use `@atollhq/mcp-server` when an agent or ChatGPT-style client needs Atoll access but cannot run a local CLI command or read local auth profiles.
+
+```bash
+npm install -g @atollhq/mcp-server
+PORT=8787 atoll-mcp
+```
+
+Remote MCP clients call `POST /mcp` with Streamable HTTP and should send `Authorization: Bearer sk_atoll_...` per request. Single-tenant deployments can set `ATOLL_API_KEY` and `ATOLL_ORG_ID` as environment variables.
+
+The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints.
+
+Keep Atoll skills separate from the MCP package. Skills are client-side agent guidance; the MCP server is runtime infrastructure for auth, transport, validation, and Atoll API calls.
+
+## AI-Assisted Setup
+
+When a user needs help setting up Atoll, lean into the AI workflow. Atoll is most useful when the user's AI assistant helps turn messy context into projects, issues, goals, KPIs, and agent instructions.
+
+If you are the AI assistant with CLI access, prefer doing the setup directly after confirming the intended org/profile and scope. Start with read-only orientation:
+
+```bash
+atoll auth profiles
+atoll heartbeat --json
+atoll issue list --json --limit 10
+```
+
+If the user is setting up Atoll in another AI tool, give them a copyable prompt. Keep secrets out of chat: tell the user to run auth commands locally and never ask them to paste `sk_atoll_...` keys into a model conversation unless they explicitly choose that risk.
+
+If the user is in Atoll's first-run setup wizard, the key may be setup-scoped. In that mode, inspect the repo or interview the user, then create or revise the setup proposal only. Do not try to create projects, goals, KPIs, initiatives, or issues directly, and do not approve/apply the proposal. The human reviews the editable proposal in Atoll and approves it there.
+
+### Prompt: Create the First Board
+
+```text
+I am setting up Atoll for my team. Help me create the first project an AI agent could understand.
+Ask me 3-5 questions about the current push, then propose:
+- one project name
+- the outcome this project should drive
+- 3-5 initial issues with clear titles, context, priorities, and owners if known
+- which issue an agent should pick up first and why
+Keep the setup small. I want a useful first board, not a full migration.
+```
+
+### Prompt: Turn a Project Into Issues
+
+```text
+I have an Atoll project but need help turning it into actionable issues.
+Interview me about the project, then write 5 issues an AI agent could execute.
+For each issue include:
+- title
+- why it matters
+- acceptance criteria
+- suggested priority
+- any context the agent would need before starting
+Make the issues specific enough that I can paste them into Atoll with minimal editing.
+```
+
+### Prompt: Install and Authenticate the CLI
+
+```text
+Help me connect this workspace to Atoll.
+First, explain what the Atoll CLI will let you do and what credentials you need.
+Then walk me through installing @atollhq/cli, adding an agent in Atoll, authenticating with the API key, and running a safe read-only check like `atoll issue list`.
+Do not ask me to paste secrets into chat unless I explicitly choose to. Tell me where to run each command locally.
+```
+
+### Prompt: Run the First Heartbeat
+
+```text
+You are helping me set up Atoll for agentic project management.
+Use the Atoll CLI to orient before doing any work.
+Run `atoll heartbeat`, summarize what you can see, identify the highest-leverage next action, and tell me whether you have enough access to list issues and update your assigned work.
+If anything is missing, explain the exact setup step I need to complete in Atoll.
+```
+
+### Prompt: Draft the Strategy Chain
+
+```text
+Help me define the strategy chain for my Atoll workspace.
+Ask me what business outcome matters most this month, then propose:
+- one goal with a clear target date
+- 1-2 KPIs that show whether we are on pace
+- one initiative expected to move the KPI
+- 3 issues that belong under that initiative
+Keep it practical. I want the smallest strategy layer that would help an AI agent choose better work.
+```
+
 ## 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.
@@ -229,8 +327,40 @@ atoll issue update ATOLL-42 --status done              # complete
 5. `POST /api/orgs/{id}/initiatives/{id}/kpi-impacts` -- declare expected KPI impact
 6. Link issues and milestones to the initiative
 
+CLI equivalent:
+
+```bash
+atoll goal create --title "Reach 100 paying customers by Q2" --target-date 2026-06-30
+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 kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
+```
+
 Every KPI snapshot can be attributed to an initiative or issue, building a record of *what actually moved the numbers*.
 
+### Audit and improve the strategy
+
+Use the audit to review the whole strategy chain at a high level and fix structural problems — the common one being initiatives created without a goal.
+
+```bash
+atoll strategy audit            # human-readable, grouped by severity
+atoll strategy audit --json     # findings[] for programmatic remediation
+```
+
+`GET /api/orgs/{id}/strategy/audit` returns `findings[]` (each with a `type`, `severity`, the relevant entity id, and a concrete `suggested_fix`) plus `summary` counts. It diagnoses; you remediate with the normal write endpoints. Typical loop:
+
+1. `atoll strategy audit --json` to get findings.
+2. For each finding, apply its `suggested_fix`, e.g.:
+   - `initiative_orphaned` → `atoll initiative update "<initiative>" --goal "<goal>"` (or `PATCH .../initiatives/{id} { goal_id }`)
+   - `goal_missing_kpi` → `atoll kpi create --goal "<goal>" --name ... --target ...`
+   - `kpi_missing_target` → `atoll kpi update <kpi> --target ... --direction increase`
+   - `kpi_unrecorded` / `kpi_stale` → `atoll kpi snapshot add <kpi> --value ...`
+   - `initiative_missing_impact` → `atoll initiative kpi link "<initiative>" <kpi> --impact "..."`
+3. Re-run the audit to confirm the findings cleared.
+
+This is the structural-health lens (is the strategy well-formed?), complementary to `heartbeat`, which is the operational lens (what should I do today?).
+
 ### Bulk create tasks from a plan
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).

package/skill/references/api-endpoints.md

@@ -21,6 +21,7 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 - [KPIs](#kpis)
 - [Initiatives](#initiatives)
 - [Initiative Links](#initiative-links)
+- [Strategy](#strategy)
 - [Heartbeat](#heartbeat)
 - [Activity](#activity)
 - [Teams](#teams)
@@ -109,6 +110,11 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | 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 |
+| GET | `/api/orgs/{id}/issues/{issueId}/initiatives` | List initiatives linked to a task |
+| POST | `/api/orgs/{id}/issues/{issueId}/initiatives` | Link task to initiative (`{ initiative_id }`) |
+| DELETE | `/api/orgs/{id}/issues/{issueId}/initiatives/{initiativeId}` | Unlink task from initiative |
+
+Issue-centric initiative links follow task project permissions: reading links requires access to the task's project; linking and unlinking requires a non-guest member with non-view access.
 
 **List filters** (query params):
 - `status` -- `backlog`, `todo`, `in_progress`, `done`, `cancelled`
@@ -224,6 +230,14 @@ Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `owner
 | POST | `.../initiatives/{id}/milestones` | Link milestone (`{ milestone_id }`) |
 | DELETE | `.../initiatives/{id}/milestones/{milestoneId}` | Unlink milestone |
 
+## Strategy
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/orgs/{id}/strategy/audit` | Audit the strategy chain for structural gaps + health issues, each with a suggested fix |
+
+Returns findings only (not the full graph). Use it for a high-level review — orphaned initiatives/KPIs (no goal), goals with no KPI or no initiative, KPIs missing targets/stale/off-pace, initiatives missing impact/execution or stalled, blocked/overdue work — then remediate with the goal/KPI/initiative write endpoints above. Forbidden for guests. CLI: `atoll strategy audit [--severity critical|warning|info] [--json]`.
+
 ## Heartbeat
 
 | Method | Endpoint | Description |
@@ -333,7 +347,7 @@ Custom statuses per project. Each column defines a valid status value.
 | GET | `/api/orgs/{id}/issues/{issueId}/pr-links` | List linked pull requests |
 | POST | `/api/orgs/{id}/issues/{issueId}/pr-links` | Attach a GitHub PR URL (`{ url }`) |
 
-Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. PR links can also be created automatically via the GitHub webhook integration.
+Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. On attach, Atoll refreshes GitHub metadata when available so title/status/head SHA reflect the PR instead of only the submitted URL. PR links can also be created or refreshed automatically via the GitHub webhook integration.
 
 ## Project Status Updates
 
@@ -398,7 +412,7 @@ URL must be HTTPS. Returns webhook record plus `secret` for HMAC verification.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/agents` | List agents (owner/admin) |
-| POST | `/api/orgs/{id}/agents` | Create agent (`{ name, role? }`) |
+| POST | `/api/orgs/{id}/agents` | Create agent (`{ name, role?, setupScoped? }`) |
 | DELETE | `/api/orgs/{id}/agents/{agentId}` | Revoke agent |
 | GET | `/api/orgs/{id}/agents/{agentId}/keys` | List API keys |
 | POST | `/api/orgs/{id}/agents/{agentId}/keys` | Generate new key |
@@ -408,6 +422,22 @@ URL must be HTTPS. Returns webhook record plus `secret` for HMAC verification.
 
 Install snippets returns config for `claude-code`, `codex`, `gemini`, `openclaw` (agent prompt), `openclaw-manual`, `hermes` (agent prompt), and `hermes-manual`. The server resolves the org slug and validates optional project/team IDs before generating snippets.
 
+## Agent-first setup
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/orgs/{id}/setup` | Read latest setup session and active draft proposal (owner/admin) |
+| POST | `/api/orgs/{id}/setup` | Create setup session (`{ preferredAi?, mode, setupAgentMemberId? }`) |
+| PATCH | `/api/orgs/{id}/setup` | Skip setup (`{ setupSessionId, status: "skipped" }`) |
+| POST | `/api/orgs/{id}/setup/proposals` | Setup-scoped local agent submits a draft proposal |
+| PATCH | `/api/orgs/{id}/setup/proposals` | Owner/admin edits the active draft proposal |
+| POST | `/api/orgs/{id}/setup/apply` | Owner/admin approves and applies a proposal |
+| POST | `/api/orgs/{id}/setup/chatkit/session` | Create ChatKit client session for a web-agent setup session |
+| POST | `/api/orgs/{id}/setup/chatkit/client-tool` | Browser-mediated ChatKit client tool endpoint for proposal submit/revise only |
+| POST | `/api/orgs/{id}/setup/chatkit/tools` | Optional server-to-server ChatKit tool endpoint for proposal submit/revise only |
+
+Setup-scoped agent keys can call setup proposal endpoints and auth validation, but not normal workspace mutation endpoints. Human approval applies proposals and promotes the setup key by clearing its setup scope. The default web-agent flow uses ChatKit client tools handled in the browser and posted to `client-tool` with the user's web session. ChatKit tools cannot apply proposals.
+
 ## Integrations
 
 | Method | Endpoint | Description |

package/skill/references/api-fields.md

@@ -10,6 +10,7 @@
 - [Automation Rule Fields](#automation-rule-fields)
 - [Custom View Fields](#custom-view-fields)
 - [Webhook Fields](#webhook-fields)
+- [Setup Proposal Fields](#setup-proposal-fields)
 - [Heartbeat Response](#heartbeat-response)
 - [Analytics Response](#analytics-response)
 - [Plan Limit Errors](#plan-limit-errors)
@@ -183,6 +184,29 @@ Add/remove projects with `{ "project_id": "uuid" }`.
 
 URL must be HTTPS. Response includes `secret` for HMAC signature verification.
 
+## Setup Proposal Fields
+
+First-run setup proposals are editable drafts. Setup-scoped local agents and ChatKit tools can submit or revise drafts; owner/admin humans apply them.
+
+```json
+{
+  "setupSessionId": "setup-session-uuid",
+  "proposal": {
+    "projects": [{ "name": "Launch v1", "description": "..." }],
+    "goals": [{ "title": "Reach 100 paying customers", "target_date": "2026-06-30" }],
+    "kpis": [{ "name": "paying_customers", "target_value": 100, "target_direction": "increase" }],
+    "initiatives": [{ "title": "Content pipeline", "description": "Publish and distribute launch content", "expected_impact": "Increase qualified signups" }],
+    "milestones": [{ "name": "Public beta", "description": "Launch the public beta workspace", "due_date": "2026-05-15" }],
+    "issues": [{ "title": "Instrument signup funnel", "description": "Track signup start, completion, and activation", "priority": 1 }]
+  },
+  "evidence": {
+    "summary": "Optional notes about repo files or user answers that informed the proposal"
+  }
+}
+```
+
+Proposal JSON currently supports at most one item in each collection: `projects`, `goals`, `kpis`, `initiatives`, `milestones`, and `issues`. A revision replaces the active draft and preserves the previous revision as history. ChatKit tools and setup-scoped agents cannot apply proposals.
+
 ## Heartbeat Response
 
 ```json
@@ -218,6 +242,34 @@ URL must be HTTPS. Response includes `secret` for HMAC signature verification.
 }
 ```
 
+## Strategy Audit Response
+
+`GET /api/orgs/{id}/strategy/audit` returns findings (sorted critical → warning → info), each with a concrete `suggested_fix`, plus summary counts.
+
+```json
+{
+  "findings": [
+    {
+      "type": "initiative_orphaned",
+      "severity": "warning",
+      "title": "\"Content pipeline\" is not attached to a goal",
+      "message": "This initiative is not linked to any goal...",
+      "suggested_fix": "Attach it to a goal: PATCH /api/orgs/{orgId}/initiatives/<id> { \"goal_id\": \"<goalId>\" }",
+      "initiative_id": "..."
+    }
+  ],
+  "summary": { "total": 7, "critical": 1, "warning": 4, "info": 2 },
+  "counts_by_type": { "initiative_orphaned": 2, "goal_missing_kpi": 1 }
+}
+```
+
+Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiative_id`, `issue_id`, `milestone_id`, `project_id`. Finding `type` values:
+
+- Structural: `initiative_orphaned`, `kpi_orphaned`, `goal_missing_kpi`, `goal_missing_initiative`
+- KPI health: `kpi_unrecorded`, `kpi_missing_target`, `kpi_stale`, `kpi_off_pace`
+- Initiative health: `initiative_missing_impact`, `initiative_missing_execution`, `initiative_stalled`
+- Execution: `issue_blocked`, `issue_overdue`, `milestone_overdue`
+
 ## Analytics Response
 
 ```json