@atollhq/skill-claude 0.1.3 → 0.1.4

package/package.json

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

package/skill/SKILL.md

@@ -26,9 +26,24 @@ Agents are org members with the same API, same permissions, same ability to crea
 
 All requests require: `Authorization: Bearer sk_atoll_<key>`
 
-Verify with: `GET /api/auth/me`
+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 **Settings > Members > Add Agent** (for agents) or **Settings > Members > Create API Key** (for integrations). Store as `$ATOLL_API_KEY`.
+```bash
+export ATOLL_API_KEY="sk_atoll_..."
+export ATOLL_ORG_ID="..."          # UUID of the org the key belongs to
+```
+
+**Sanity check** — exercises the org-scoped issues endpoint, not just `/api/auth/me`:
+
+```bash
+: "${ATOLL_API_KEY:?missing}" "${ATOLL_ORG_ID:?missing}" && \
+  curl -sS -o /dev/null -w "HTTP:%{http_code}\n" \
+    "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=1" \
+    -H "Authorization: Bearer $ATOLL_API_KEY"
+# Expect: HTTP:200
+```
+
+If `$ATOLL_ORG_ID` is empty, the URL collapses to `/api/orgs//issues` which 308-redirects to a non-existent route and returns `Unauthorized` — a misleading symptom that looks like an auth failure. `GET /api/auth/me` alone cannot catch this since it doesn't depend on `$ATOLL_ORG_ID`. Always guard both vars.
 
 ## Quick Start — CLI (recommended)
 
@@ -78,11 +93,16 @@ atoll milestone list --project <project-id>
 All CLI commands map to REST endpoints. Use the API directly when the CLI doesn't cover a specific operation.
 
 ```bash
-export ATOLL_API_KEY="sk_atoll_..."
-
-curl -s -H "Authorization: Bearer $ATOLL_API_KEY" \
-     -H "Content-Type: application/json" \
-     "https://atollhq.com/api/orgs/{orgId}/issues?status=todo"
+# Prereq: both env vars exported (see Authentication above)
+atoll() {
+  : "${ATOLL_API_KEY:?ATOLL_API_KEY not set}"
+  : "${ATOLL_ORG_ID:?ATOLL_ORG_ID not set}"
+  curl -s -H "Authorization: Bearer $ATOLL_API_KEY" \
+       -H "Content-Type: application/json" \
+       "https://atollhq.com$1" "${@:2}"
+}
+
+atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"
 ```
 
 ## The Heartbeat Loop
@@ -142,7 +162,7 @@ Full endpoint tables and field schemas:
 |----------|--------|------|--------|--------|
 | Orgs | POST `/api/orgs` | GET `/api/orgs` | PATCH `/api/orgs/{id}` | DELETE `/api/orgs/{id}` |
 | Projects | POST `.../projects` | GET `.../projects` | PATCH `.../projects/{id}` | DELETE `.../projects/{id}` |
-| Tasks | POST `.../issues` | GET `.../issues` | PATCH `.../issues/{id}` | DELETE `.../issues/{id}` |
+| 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}` |
@@ -152,6 +172,8 @@ Full endpoint tables and field schemas:
 
 All endpoints are under `/api/orgs/{orgId}/...`.
 
+† `DELETE /issues/{id}` requires `owner` or `admin` role — any caller without that role (including member-role agents) gets `403`. If you just need to remove a task, use `POST /api/orgs/{orgId}/issues/{issueId}/archive` (soft delete, no role gate); reverse with `DELETE` on the same path (unarchive).
+
 ### Quick enum reference
 
 - **Task status**: `backlog`, `todo`, `in_progress`, `done`, `cancelled` (custom per project)