@atollhq/skill-claude 0.4.6 → 0.4.7

package/README.md

@@ -12,14 +12,14 @@ npx @atollhq/skill-claude --profile agent-a --key sk_atoll_... --org your-org-id
 ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-claude
 ```
 
-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. Pass `--profile` to store credentials and defaults only in that named Atoll CLI profile; Claude settings keep only `ATOLL_PROFILE` so direct CLI commands can use the profile safely. Omit `--profile` to use env-var mode, which writes `ATOLL_ENV_MODE=1` with the credential settings.
 
-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 three things:
 
 1. Copies the skill into `~/.claude/skills/atoll-api/`
-2. Writes Atoll env vars into `~/.claude/settings.json` under `env`
+2. Stores only `ATOLL_PROFILE` in `~/.claude/settings.json` when profile mode is used
 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

@@ -41,7 +41,7 @@ Usage: npx @atollhq/skill-claude [--profile <name>] --key <api-key> --org <org-i
    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.
+  --profile   Atoll CLI profile name to create/update.
   --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.
@@ -58,7 +58,6 @@ 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
 if (args.clearProject) delete args.project
@@ -128,30 +127,46 @@ mkdirSync(join(skillDest, 'references'), { recursive: true })
 cpSync(skillSrc, skillDest, { recursive: true })
 console.log(`Installed skill to ${skillDest}`)
 
-// 2. Write credentials to ~/.claude/settings.json env vars
+// 2. Configure ~/.claude/settings.json. Profile mode stores credentials only
+// in the Atoll CLI profile and keeps Claude's host env limited to profile
+// selection, removing stale credential/default env from earlier installs.
 const settingsPath = join(homedir(), '.claude', 'settings.json')
 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
+if (args.profile) {
+  settings.env.ATOLL_PROFILE = args.profile
+  delete settings.env.ATOLL_API_KEY
+  delete settings.env.ATOLL_ORG_ID
+  delete settings.env.ATOLL_PROJECT
+  delete settings.env.ATOLL_TEAM
+  delete settings.env.ATOLL_BASE_URL
+  delete settings.env.ATOLL_ENV_MODE
+} else {
+  delete settings.env.ATOLL_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
+  settings.env.ATOLL_ENV_MODE = '1'
+}
 
 writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
 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')
+if (args.profile) {
+  configuredVars.push('ATOLL_PROFILE')
+} else {
+  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')
+}
 console.log(`Configured ${configuredVars.join(', ')} in ${settingsPath}`)
 
 console.log(`\nDone! Start Claude Code and the atoll-api skill will be available.`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "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`