@atollhq/skill-codex 0.4.3 → 0.4.5

package/README.md

@@ -12,7 +12,7 @@ npx @atollhq/skill-codex --profile agent-a --key sk_atoll_... --org your-org-id
 ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex
 ```
 
-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`.
+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.
 
@@ -21,10 +21,10 @@ 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`)
-5. Creates or updates the named Atoll CLI profile when `--profile` is provided
+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
 
@@ -45,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

@@ -30,7 +30,7 @@ Usage: npx @atollhq/skill-codex [--profile <name>] --key <api-key> --org <org-id
    or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-codex
 
 Options:
-  --profile   Atoll CLI profile name to create/update. Defaults to ATOLL_PROFILE.
+  --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.
@@ -44,12 +44,12 @@ Options:
 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.profile ??= process.env.ATOLL_PROFILE
 args.key ??= process.env.ATOLL_API_KEY
 args.org ??= process.env.ATOLL_ORG_ID
 if (args.clearProject) delete args.project
@@ -83,7 +83,7 @@ function readJson(path) {
 }
 
 function writeAtollProfile() {
-  if (!args.profile) return
+  if (!args.profile) return null
 
   const atollDir = join(homedir(), '.atoll')
   const configPath = join(atollDir, 'config.json')
@@ -106,6 +106,7 @@ function writeAtollProfile() {
   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/
@@ -122,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,
@@ -130,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}` : ''}
 `
 
@@ -162,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')
@@ -185,7 +202,7 @@ if (existsSync(profilePath)) {
   if (!profile.includes('# Atoll (added by @atollhq/skill-codex)')) {
     profile = `${profile.trimEnd()}\n\n# Atoll (added by @atollhq/skill-codex)\n`
   }
-  if (args.profile) profile = upsertExport(profile, 'ATOLL_PROFILE', args.profile)
+  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)
@@ -195,10 +212,8 @@ if (existsSync(profilePath)) {
   if (args.baseUrl) profile = upsertExport(profile, 'ATOLL_BASE_URL', args.baseUrl)
   else profile = removeExport(profile, 'ATOLL_BASE_URL')
   writeFileSync(profilePath, profile)
-  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')
@@ -207,7 +222,6 @@ if (existsSync(profilePath)) {
 } else {
   const envLines = [
     '# Atoll (added by @atollhq/skill-codex)',
-    args.profile ? `export ATOLL_PROFILE="${args.profile}"` : null,
     `export ATOLL_API_KEY="${args.key}"`,
     `export ATOLL_ORG_ID="${args.org}"`,
     args.project ? `export ATOLL_PROJECT="${args.project}"` : null,
@@ -216,7 +230,6 @@ if (existsSync(profilePath)) {
   ].filter(Boolean)
   const envBlock = `\n${envLines.join('\n')}\n`
   writeFileSync(profilePath, envBlock)
-  writeAtollProfile()
   console.log(`Created ${profilePath} with Atoll env vars`)
 }
 

package/package.json

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

package/skill/SKILL.md

@@ -149,12 +149,14 @@ 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 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 kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
@@ -171,9 +173,32 @@ CLI JSON conventions:
 - Use `--json` for machine-readable output.
 - List commands return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
 - Diagnostics and errors go to stderr.
-- `atoll agent-context` returns a versioned command/flag manifest and available profile context.
+- 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 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.
+
+```bash
+atoll kpi sync validate <kpi-id> \
+  --name "PostHog visitors" \
+  --schedule daily \
+  --url https://us.posthog.com/api/projects/123/query/ \
+  --pointer /results/0/value \
+  --auth-secret-ref posthog_api_key
+
+atoll kpi sync draft <kpi-id> --file sync-draft.json
+```
+
+Draft configs must be `GET` only, `https` only, JSON only, no redirects, no request bodies, no inline query strings, no secret values, and an already-allowlisted exact destination host. Use secret reference names only for `Authorization: Bearer <secretRef>` or `X-API-Key: <secretRef>`.
+
+Never include API keys, bearer tokens, cookies, raw third-party response bodies, or secret values in prompts, draft files, comments, or issue descriptions. If a human pasted a secret into chat, stop and ask them to rotate it and enter the replacement directly in Atoll.
+
 ## 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.
@@ -321,7 +346,7 @@ atoll issue update ATOLL-42 --status done              # complete
 ### Set up the strategy chain
 
 1. `POST /api/orgs/{id}/goals` -- create goal with `target_date`
-2. `POST /api/orgs/{id}/kpis` -- attach KPI with `goal_id`, `target_value`, `target_direction`
+2. `POST /api/orgs/{id}/kpis` -- attach KPI with `goal_id`, `target_value`, `target_direction`; for launch-style goals you can use `source_type: "formula"` with `source_config.formula: "goal_linked_issue_completion"` to calculate done directly linked and milestone-linked tasks over total linked tasks
 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

package/skill/references/api-endpoints.md

@@ -64,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.
 
@@ -201,6 +201,21 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | DELETE | `/api/orgs/{id}/kpis/{kpiId}` | Delete KPI (admin/owner only) |
 | GET | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | List snapshots (optional `?limit=50`) |
 | 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}/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 |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Get a KPI HTTP sync |
+| PATCH | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Update a KPI HTTP sync draft (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/validate` | Validate a stored sync (human admin only) |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets` | List sanitized secret metadata (human admin only) |
+| PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets` | Add or replace a sync secret value (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/dry-run` | Execute a sanitized dry run without writing a snapshot (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/publish` | Publish a validated, dry-run sync (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/disable` | Disable a sync (human admin only) |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/run-now` | Preview by default; write a snapshot only with explicit admin confirmation |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/runs` | List sanitized sync run history (human admin only) |
 
 ## Initiatives
 

package/skill/references/api-fields.md

@@ -100,6 +100,22 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 }
 ```
 
+Calculated task-completion KPIs use `source_type: "formula"` and are calculated from linked work instead of snapshots:
+
+```json
+{
+  "name": "mvp_tasks_done",
+  "goal_id": "goal-uuid",
+  "source_type": "formula",
+  "source_config": {
+    "formula": "goal_linked_issue_completion",
+    "done_statuses": ["done"]
+  }
+}
+```
+
+For `goal_linked_issue_completion`, `current_value` is the count of non-archived directly linked issues and milestone-linked issues in `done` status and `target_value` is the total non-archived directly linked issue and milestone-linked issue count under initiatives for the goal.
+
 ## KPI Snapshots
 
 ```json
@@ -114,6 +130,40 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 Recording a snapshot auto-updates the KPI's `current_value`.
 
+Calculated KPIs do not accept manual snapshots.
+
+`api_poll` snapshots are written by published KPI HTTP Syncs and include provenance: `source_sync_id`, `source_sync_run_id`, `source_config_hash`, `source_recorded_for`, `observed_at`, and optional `provider_recorded_at`.
+
+## KPI HTTP Syncs
+
+```json
+{
+  "name": "PostHog visitors",
+  "schedule": "daily",
+  "request_config": {
+    "method": "GET",
+    "url": "https://us.posthog.com/api/projects/123/query/",
+    "headers": {
+      "Authorization": {
+        "secretRef": "posthog_api_key",
+        "format": "Bearer {value}"
+      }
+    }
+  },
+  "extraction_config": {
+    "contentType": "json",
+    "pointer": "/results/0/value",
+    "numeric": {
+      "mode": "number",
+      "percentageScale": null
+    }
+  },
+  "freshness_config": {}
+}
+```
+
+V1 syncs are `GET` only, `https` only, JSON only, exact-host allowlisted, no redirects, no request bodies, no inline query strings, and no secret values. Machine actors can create drafts and validate configs only after the host is allowlisted. Human admins manage allowlists, secrets, dry-runs, publishing, disabling, and snapshot-writing run-now actions in Atoll.
+
 ## Initiative Fields
 
 ```json
@@ -295,6 +345,9 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | KPI | `target_direction` | `increase`, `decrease`, `maintain` |
 | KPI | `source_type` | `manual`, `webhook`, `api_poll`, `formula` |
 | KPI snapshot | `source` | `manual`, `webhook`, `api_poll`, `formula`, `agent` |
+| KPI HTTP sync | `status` | `draft`, `published`, `disabled` |
+| KPI HTTP sync secret | `placement` | `authorization_bearer`, `x_api_key` |
+| KPI HTTP sync run | `status` | `queued`, `running`, `success`, `error` |
 | Initiative | `status` | `proposed`, `active`, `completed`, `paused`, `cancelled` |
 | Status update | `status` | `on_track`, `at_risk`, `off_track` |
 | Member | `role` | `owner`, `admin`, `member`, `guest` |