@atollhq/skill-codex 0.4.6 → 0.4.8

package/README.md

@@ -12,9 +12,9 @@ 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: `--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.
+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.
 
-Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
+Get an agent API key from **Agents** in the Atoll app. Integration keys are still managed from **Settings > Members**.
 
 This does five things:
 
@@ -24,7 +24,7 @@ This does five things:
 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
 
-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.
+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.
 
 ## Using the integration
 

package/bin/install.mjs

@@ -170,8 +170,25 @@ for (const file of ['api-endpoints.md', 'api-fields.md']) {
 }
 console.log(`Copied API references to ${refsDir}`)
 
+const shell = process.env.SHELL || '/bin/bash'
+const profilePath = shell.includes('zsh')
+  ? join(homedir(), '.zshrc')
+  : join(homedir(), '.bashrc')
+
 // 4. In profile mode, keep credentials scoped to the Atoll CLI profile.
 if (args.profile) {
+  if (existsSync(profilePath)) {
+    let profile = readFileSync(profilePath, 'utf-8')
+    profile = removeExport(profile, 'ATOLL_PROFILE')
+    profile = removeExport(profile, 'ATOLL_API_KEY')
+    profile = removeExport(profile, 'ATOLL_ORG_ID')
+    profile = removeExport(profile, 'ATOLL_PROJECT')
+    profile = removeExport(profile, 'ATOLL_TEAM')
+    profile = removeExport(profile, 'ATOLL_BASE_URL')
+    profile = removeExport(profile, 'ATOLL_ENV_MODE')
+    writeFileSync(profilePath, profile)
+    console.log(`Removed stale Atoll shell exports from ${profilePath}`)
+  }
   writeAtollProfile()
   console.log('No Atoll shell exports were written.')
   console.log(`Run profile-scoped commands with: atoll --profile ${args.profile} ...`)
@@ -180,11 +197,6 @@ if (args.profile) {
 }
 
 // 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')
-  : join(homedir(), '.bashrc')
-
 function upsertExport(profile, name, value) {
   const line = `export ${name}="${value}"`
   const pattern = new RegExp(`^export ${name}=.*$`, 'm')
@@ -211,10 +223,11 @@ if (existsSync(profilePath)) {
   else profile = removeExport(profile, 'ATOLL_TEAM')
   if (args.baseUrl) profile = upsertExport(profile, 'ATOLL_BASE_URL', args.baseUrl)
   else profile = removeExport(profile, 'ATOLL_BASE_URL')
+  profile = upsertExport(profile, 'ATOLL_ENV_MODE', '1')
   writeFileSync(profilePath, profile)
 
   const configuredVars = []
-  configuredVars.push('ATOLL_API_KEY', 'ATOLL_ORG_ID')
+  configuredVars.push('ATOLL_API_KEY', 'ATOLL_ORG_ID', 'ATOLL_ENV_MODE')
   if (args.project) configuredVars.push('ATOLL_PROJECT')
   if (args.team) configuredVars.push('ATOLL_TEAM')
   if (args.baseUrl) configuredVars.push('ATOLL_BASE_URL')
@@ -227,6 +240,7 @@ if (existsSync(profilePath)) {
     args.project ? `export ATOLL_PROJECT="${args.project}"` : null,
     args.team ? `export ATOLL_TEAM="${args.team}"` : null,
     args.baseUrl ? `export ATOLL_BASE_URL="${args.baseUrl}"` : null,
+    'export ATOLL_ENV_MODE="1"',
   ].filter(Boolean)
   const envBlock = `\n${envLines.join('\n')}\n`
   writeFileSync(profilePath, envBlock)

package/package.json

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

package/skill/SKILL.md

@@ -26,7 +26,7 @@ Agents are org members with the same API, same permissions, same ability to crea
 
 All requests require: `Authorization: Bearer sk_atoll_<key>`
 
-API keys are generated in **Settings > Members > Add Agent** (for agents) or **Settings > Members > Create API Key** (for integrations). Each key is scoped to one org. Store both values as env vars:
+API keys are generated in **Agents** (for agents) or **Settings > Members > Create API Key** (for integrations). Each key is scoped to one org. Store both values as env vars:
 
 ```bash
 export ATOLL_API_KEY="sk_atoll_..."
@@ -94,6 +94,8 @@ atoll --profile agent-b issue list
 
 Profiles can store default org ID, project, team, and base URL values. For named profiles, always persist `--org-id` or pass `--org-id` per command. Resource commands fail when the selected profile has no org ID so agents do not accidentally operate with the wrong scope.
 
+Env vars remain supported for CI, containers, and one-off runtime usage, but persistent developer/agent machines should prefer profiles. When a profile is selected, ambient `ATOLL_*` env vars do not silently override profile context; conflicting env values fail before network calls. Pass `--profile`, use repo-local `.atoll/context.json`, or opt into env mode with `--env-mode` / `ATOLL_ENV_MODE=1`.
+
 `atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed.
 
 Common commands:
@@ -173,6 +175,7 @@ CLI JSON conventions:
 - Use `--json` for machine-readable output.
 - List commands return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
 - Project-scoped `atoll issue list --json` includes `project_context`; `atoll issue get/view --json` includes `status_column` plus `project_context` when available.
+- For initiative execution context via API, `GET /api/orgs/{id}/initiatives/{initiativeId}/issues?details=1` returns accessible task details from linked projects, direct issue links, and linked milestones.
 - 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.
@@ -315,6 +318,8 @@ The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when
 - **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
 
+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`.
 
 Useful CLI forms:
@@ -364,6 +369,8 @@ atoll initiative kpi link "Content pipeline" paying_customers --impact "+30 cust
 atoll kpi snapshot add paying_customers --value 42 --initiative "Content pipeline" --note "End-of-week Stripe check"
 ```
 
+Project-scoped agent profiles apply their default project to `atoll initiative list` and `atoll initiative create`. Use `--project <id-or-slug>` to override that project, or `--org-wide` to intentionally suppress the default project. API callers can pass `project_id` or `projectId` on create, and `?project_id=...` on list; guest/project-scoped callers must use a project they can access, and create requires edit/admin project access.
+
 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
@@ -392,6 +399,17 @@ This is the structural-health lens (is the strategy well-formed?), complementary
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).
 
+### Outbound webhooks
+
+`POST /api/webhooks` creates outbound webhooks. Receiver URLs must be HTTPS DNS hostnames; Atoll rejects IP literals, `localhost`, `.local` hosts, URL credentials, and fragments at creation. Delivery also resolves DNS and refuses private, loopback, link-local, documentation, multicast, and other non-public addresses; redirects are not followed.
+
+Webhook creation returns a raw `whsec_...` secret once. Delivery requests include:
+
+- `X-Atoll-Signature`: `sha256=` plus an HMAC-SHA256 over the raw body, keyed by the SHA-256 hex digest of the raw secret.
+- `X-Atoll-Delivery-Id`: stable delivery id for receiver-side deduplication.
+
+Delivery rows expose `delivery_id`, `status`, and `next_retry_at`. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
+
 ### 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" }`.
@@ -413,7 +431,7 @@ Full endpoint tables and field schemas:
 | Tasks | POST `.../issues` | GET `.../issues` | PATCH `.../issues/{id}` | DELETE `.../issues/{id}` † |
 | Goals | POST `.../goals` | GET `.../goals` | PATCH `.../goals/{id}` | DELETE `.../goals/{id}` |
 | KPIs | POST `.../kpis` | GET `.../kpis` | PATCH `.../kpis/{id}` | DELETE `.../kpis/{id}` |
-| Initiatives | POST `.../initiatives` | GET `.../initiatives` | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
+| Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` optional; required for guests) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
 | Milestones | POST `.../milestones` | GET `.../milestones` | PATCH `.../milestones/{id}` | DELETE `.../milestones/{id}` |
 | Comments | POST `.../comments` | GET `.../comments` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
 | Subtasks | POST `.../subtasks` | GET `.../subtasks` | PATCH `.../subtasks/{id}` | DELETE `.../subtasks/{id}` |

package/skill/references/api-endpoints.md

@@ -114,7 +114,7 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | 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.
+Issue-centric initiative links follow task project permissions: reading links requires access to the task's project; linking and unlinking require edit/admin access to that project. Guest callers may link only to initiatives already linked to the same accessible project.
 
 **List filters** (query params):
 - `status` -- `backlog`, `todo`, `in_progress`, `done`, `cancelled`
@@ -221,8 +221,8 @@ Roles: `owner`, `admin`, `member`, `guest`.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/initiatives` | List (optional `?goal_id=...&status=...&owner_id=...`) |
-| POST | `/api/orgs/{id}/initiatives` | Create initiative |
+| GET | `/api/orgs/{id}/initiatives` | List (optional `?goal_id=...&status=...&owner_id=...&project_id=...`; guests require `project_id`) |
+| POST | `/api/orgs/{id}/initiatives` | Create initiative (`project_id`/`projectId` optional; guests require editable project access) |
 | GET | `/api/orgs/{id}/initiatives/{initiativeId}` | Get initiative |
 | PATCH | `/api/orgs/{id}/initiatives/{initiativeId}` | Update initiative |
 | DELETE | `/api/orgs/{id}/initiatives/{initiativeId}` | Delete initiative (admin/owner only) |
@@ -238,7 +238,7 @@ Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `owner
 | GET | `.../initiatives/{id}/kpi-impacts` | List KPI impact links |
 | POST | `.../initiatives/{id}/kpi-impacts` | Add (`{ kpi_id, expected_impact? }`) |
 | DELETE | `.../initiatives/{id}/kpi-impacts/{impactId}` | Remove link |
-| GET | `.../initiatives/{id}/issues` | List linked issues |
+| GET | `.../initiatives/{id}/issues` | List linked issue links; add `?details=1` for accessible task details from linked projects, direct issue links, and linked milestones |
 | POST | `.../initiatives/{id}/issues` | Link issue (`{ issue_id }`) |
 | DELETE | `.../initiatives/{id}/issues/{issueId}` | Unlink issue |
 | GET | `.../initiatives/{id}/milestones` | List linked milestones |
@@ -251,7 +251,7 @@ Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `owner
 |--------|----------|-------------|
 | 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]`.
+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, dangling initiative execution links, 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
 
@@ -259,7 +259,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.
+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.
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -413,7 +413,7 @@ Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issu
 | POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload |
 | POST | `/api/webhooks/{id}/test` | Send ping test event |
 
-URL must be HTTPS. Returns webhook record plus `secret` for HMAC verification.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Delivery requests include `X-Atoll-Signature: sha256=<hmac>`, where the HMAC-SHA256 key is the SHA-256 hex digest of the webhook secret and the message is the exact raw request body. Delivery requests also include `X-Atoll-Delivery-Id` so receivers can dedupe retries. Atoll retries network failures and 5xx responses after 5s and 30s, then records `status: retry_pending` with `next_retry_at`; an internal cron drains due retries every 15 minutes.
 
 ## Notifications
 
@@ -428,13 +428,16 @@ 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?, 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 |
-| DELETE | `/api/orgs/{id}/agents/{agentId}/keys/{keyId}` | Revoke key |
-| POST | `/api/orgs/{id}/agents/{agentId}/rotate` | Rotate all keys |
-| POST | `/api/orgs/{id}/agents/{agentId}/install-snippets` | Get install snippets (`{ key, profileName?, projectId?, teamId?, baseUrl? }`) |
+| GET | `/api/orgs/{id}/agents/manageable` | List agents the current human can manage |
+| POST | `/api/orgs/{id}/agents` | Create org, project-scoped, or personal agent |
+| DELETE | `/api/orgs/{id}/agents/{agentId}` | Revoke manageable agent |
+| PATCH | `/api/orgs/{id}/agents/{agentId}/projects` | Replace project access for a manageable non-personal agent |
+| POST | `/api/orgs/{id}/projects/{projectId}/agents` | Grant selected manageable agents access to a project |
+| GET | `/api/orgs/{id}/agents/{agentId}/keys` | List API keys for a manageable agent |
+| POST | `/api/orgs/{id}/agents/{agentId}/keys` | Generate new key for a manageable agent |
+| DELETE | `/api/orgs/{id}/agents/{agentId}/keys/{keyId}` | Revoke key for a manageable agent |
+| POST | `/api/orgs/{id}/agents/{agentId}/rotate` | Rotate all keys for a manageable agent |
+| POST | `/api/orgs/{id}/agents/{agentId}/install-snippets` | Get install snippets for a manageable agent (`{ key, profileName?, projectId?, teamId?, baseUrl? }`) |
 
 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.
 

package/skill/references/api-fields.md

@@ -174,10 +174,13 @@ V1 syncs are `GET` only, `https` only, JSON only, exact-host allowlisted, no red
   "goal_id": "goal-uuid",
   "owner_id": "member-uuid",
   "status": "active",
-  "target_date": "2026-05-15"
+  "target_date": "2026-05-15",
+  "project_id": "project-uuid"
 }
 ```
 
+Create accepts `projectId` as a camelCase alias for `project_id`. Guest/project-scoped callers must pass a project they can edit when creating initiatives.
+
 For portfolio-style initiatives (grouping projects):
 ```json
 {
@@ -276,7 +279,7 @@ Add/remove projects with `{ "project_id": "uuid" }`.
 }
 ```
 
-URL must be HTTPS. Response includes `secret` for HMAC signature verification.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Response includes `secret` for HMAC signature verification. Store it immediately; it is shown only once. Delivery requests include `X-Atoll-Signature: sha256=<hmac>`, where the HMAC-SHA256 key is the SHA-256 hex digest of the webhook secret and the message is the exact raw request body. Delivery requests also include `X-Atoll-Delivery-Id` for receiver-side deduplication. Delivery history includes retry `status` and `next_retry_at`.
 
 ## Setup Proposal Fields
 
@@ -345,6 +348,8 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 }
 ```
 
+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.
+
 ## Strategy Audit Response
 
 `GET /api/orgs/{id}/strategy/audit` returns findings (sorted critical → warning → info), each with a concrete `suggested_fix`, plus summary counts.
@@ -368,7 +373,7 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 
 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`
+- 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`
 - Execution: `issue_blocked`, `issue_overdue`, `milestone_overdue`