@atollhq/skill-codex 0.4.1 → 0.4.4

package/README.md

@@ -7,23 +7,24 @@ Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, mi
 ## Install
 
 ```bash
-npx @atollhq/skill-codex --key sk_atoll_... --org your-org-id --project project-id --team team-id
+npx @atollhq/skill-codex --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-codex
 ```
 
-Optional defaults: `--project`, `--team`, and `--base-url` write `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` for the agent.
+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. When `--profile` is set, credentials and defaults are stored only in that named Atoll CLI profile. The installer does not write global `ATOLL_*` exports to `~/.zshrc` or `~/.bashrc`. Use `atoll --profile agent-a ...` for profile-scoped commands, or omit `--profile` to use env-var mode.
 
 Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
 
-This does four things:
+This does five things:
 
 1. Installs the `atoll-api` skill to `~/.codex/skills/atoll-api/`
 2. Appends (or updates) an `# Atoll Integration` section in `~/.codex/AGENTS.md`
 3. Copies API reference files to `~/.codex/atoll-references/`
-4. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`)
+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
 
-Open a fresh shell (or `source` your profile) and Codex has the Atoll integration.
+For profile mode, Codex has the Atoll skill immediately and terminal commands can use `atoll --profile agent-a ...`. For env-var mode, open a fresh shell or `source` your profile.
 
 ## Using the integration
 
@@ -44,6 +45,7 @@ For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@ato
 ```bash
 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

package/bin/install.mjs

@@ -10,11 +10,15 @@ 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]) args.key = argv[++i]
+    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
   }
   return args
@@ -22,30 +26,38 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-codex --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
+Usage: npx @atollhq/skill-codex [--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-codex
 
 Options:
+  --profile   Atoll CLI profile name to create/update. Profile mode does not write shell env vars.
   --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
 
 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/
-  - Sets Atoll env vars
+  - Creates/updates an Atoll CLI profile when --profile is provided
+  - Otherwise writes Atoll env vars to your shell profile for env-var mode
 `)
 }
 
 const args = parseArgs(process.argv)
 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(); process.exit(0) }
 
@@ -60,6 +72,43 @@ 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 null
+
+  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}`)
+  return configPath
+}
+
 // 1. Install the Codex skill to ~/.codex/skills/atoll-api/
 const codexDir = join(homedir(), '.codex')
 mkdirSync(codexDir, { recursive: true })
@@ -74,7 +123,13 @@ 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,
@@ -82,11 +137,12 @@ const optionalCredentialLines = [
 
 const agentsMd = `# Atoll Integration
 
+${profileModeInstructions}
 ${body}
 
 ## Credentials
 
-- API Key: set as ATOLL_API_KEY environment variable
+- 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}` : ''}
 `
 
@@ -114,7 +170,16 @@ for (const file of ['api-endpoints.md', 'api-fields.md']) {
 }
 console.log(`Copied API references to ${refsDir}`)
 
-// 4. Set env vars in shell profile
+// 4. In profile mode, keep credentials scoped to the Atoll CLI profile.
+if (args.profile) {
+  writeAtollProfile()
+  console.log('No Atoll shell exports were written.')
+  console.log(`Run profile-scoped commands with: atoll --profile ${args.profile} ...`)
+  console.log(`\nDone! Codex has the Atoll skill installed, and the Atoll CLI profile "${args.profile}" is active.`)
+  process.exit(0)
+}
+
+// 4. Set env vars in shell profile for env-var mode.
 const shell = process.env.SHELL || '/bin/bash'
 const profilePath = shell.includes('zsh')
   ? join(homedir(), '.zshrc')
@@ -127,18 +192,29 @@ function upsertExport(profile, name, value) {
   return `${profile.trimEnd()}\n${line}\n`
 }
 
+function removeExport(profile, name) {
+  const pattern = new RegExp(`^export ${name}=.*\\n?`, 'm')
+  return profile.replace(pattern, '')
+}
+
 if (existsSync(profilePath)) {
   let profile = readFileSync(profilePath, 'utf-8')
   if (!profile.includes('# Atoll (added by @atollhq/skill-codex)')) {
     profile = `${profile.trimEnd()}\n\n# Atoll (added by @atollhq/skill-codex)\n`
   }
+  profile = removeExport(profile, 'ATOLL_PROFILE')
   profile = upsertExport(profile, 'ATOLL_API_KEY', args.key)
   profile = upsertExport(profile, 'ATOLL_ORG_ID', args.org)
   if (args.project) profile = upsertExport(profile, 'ATOLL_PROJECT', args.project)
+  else profile = removeExport(profile, 'ATOLL_PROJECT')
   if (args.team) profile = upsertExport(profile, 'ATOLL_TEAM', args.team)
+  else profile = removeExport(profile, 'ATOLL_TEAM')
   if (args.baseUrl) profile = upsertExport(profile, 'ATOLL_BASE_URL', args.baseUrl)
+  else profile = removeExport(profile, 'ATOLL_BASE_URL')
   writeFileSync(profilePath, profile)
-  const configuredVars = ['ATOLL_API_KEY', 'ATOLL_ORG_ID']
+
+  const configuredVars = []
+  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-codex",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -149,11 +149,23 @@ atoll feedback "The status error should list custom board statuses"
 
 # Projects & milestones
 atoll project list
+atoll project delete <project-id> --confirm DELETE
 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 +175,21 @@ 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.
@@ -177,6 +204,8 @@ 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
@@ -299,8 +328,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)
@@ -63,7 +64,7 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 | POST | `/api/orgs/{id}/projects` | Create project (`{ name, description?, visibility?, color?, icon?, github_repo? }`) |
 | GET | `/api/orgs/{id}/projects/{projectId}` | Get project with issues |
 | PATCH | `/api/orgs/{id}/projects/{projectId}` | Update project (`{ name?, description?, status?, visibility?, color?, icon? }`) |
-| DELETE | `/api/orgs/{id}/projects/{projectId}` | Delete project (owner/admin) |
+| DELETE | `/api/orgs/{id}/projects/{projectId}` | Permanently delete project and all tasks in it (owner/admin; body must include `{ "confirmation": "DELETE" }`) |
 
 Guest users only see projects they are assigned to.
 
@@ -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