@atollhq/skill-claude 0.4.15 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"
@@ -22,9 +22,6 @@
     "url": "git+https://github.com/atollhq/atoll.git",
     "directory": "packages/skill-claude"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT",
   "type": "module"
 }

package/skill/SKILL.md

@@ -65,6 +65,8 @@ For OpenClaw / ClawHub, prefer skill-scoped config in `~/.openclaw/openclaw.json
 
 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.
 
+For agent diagnostics, `/api/auth/me` reports the organization role in `auth.role` and live per-project `view`/`edit`/`admin` grants in `auth.projectAccess[]`. Project-scoped agents intentionally remain org guests. Organization-role and project-access changes are read live and do not require key rotation; `scopes: []` is normal for a standard agent key.
+
 ## Quick Start — CLI (recommended)
 
 Install globally or use via npx:
@@ -96,7 +98,7 @@ Profiles can store default org ID, project, team, and base URL values. For named
 
 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. For `atoll issue create`, `--project` accepts a project ID, slug, or exact name. `--milestone` accepts a milestone ID, or an exact milestone name when a project is selected with `--project` or the active profile's default project.
+`atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed. Issue command `--project` flags accept a project ID, slug, or exact name, including list and bulk defaults. In bulk JSON items, `project` accepts those references while `projectId` and `project_id` are canonical IDs. `--milestone` accepts a milestone ID, or an exact milestone name when a project is selected with `--project` or the active profile's default project.
 
 Common commands:
 
@@ -345,12 +347,12 @@ The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
 - **Initiative progress**: total/completed/stalled/blocked issue counts, expected KPI impacts, and initiative targets
 - **Assigned work** for this agent
-- **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents
+- **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context.
 - **Signals** sorted by severity — the agent's prioritized to-do list
 - **Attention items**: direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes, with an `ack_endpoint` to call after handling
 - **Recommended action**: one deterministic strategy-backed next action when Atoll has enough evidence (`create_work`, `start_work`, `escalate_blocker`, or `refresh_metric`), including why-now, expected impact, first step, success criteria, quality warnings, and any suggested write.
 
-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.
+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. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. 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`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -439,6 +441,16 @@ This is the structural-health lens (is the strategy well-formed?), complementary
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).
 
+### Google Chat notifications
+
+Google Chat is a separate notification channel. Notification preferences accept `channel: "google_chat"` for `mention.created`; muting it does not acknowledge or clear in-app notifications.
+
+User pairing is human-driven. When verified-email auto-linking is ambiguous, Google Chat receives `REQUEST_CONFIG` and sends the user to Atoll to sign in, choose one of their own workspace memberships, and return to Chat. Sending the stable word `connect` in the Atoll direct message explicitly starts this flow for reconnects or additional workspaces. `GET|POST /api/integrations/google-chat/connect-session` and the org-scoped member status, disconnect, and test endpoints require an authenticated human web session and reject `sk_atoll_...` agent or integration keys. `POST /api/orgs/{id}/integrations/google-chat/link-token` remains a manual fallback. Do not call `/api/integrations/google-chat/events` as an Atoll API client: Google Chat calls that endpoint with a Google-signed OIDC ID token whose audience is the callback URL.
+
+Mention notifications are queued durably and dispatched asynchronously immediately after the notification request. A 15-minute recovery drain retries interrupted or transiently failed deliveries with deterministic Google request/message IDs, exponential backoff, and a five-attempt limit.
+
+Config sessions and unused manual connect tokens expire after 10 minutes. Session completion and identical event replays are idempotent and cannot establish a different member or direct-message link.
+
 ### 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.

package/skill/references/api-endpoints.md

@@ -6,6 +6,7 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 
 ## Table of Contents
 
+- [Authentication](#authentication)
 - [Organizations](#organizations)
 - [Projects](#projects)
 - [Project Members](#project-members)
@@ -46,6 +47,16 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 
 ---
 
+## Authentication
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/auth/me` | Resolve the caller's org role, key scopes, and live `projectAccess[]` grants |
+
+Project-scoped agents remain organization guests. Use `projectAccess[]` to
+inspect their effective `view`, `edit`, or `admin` access; membership changes
+do not require key rotation.
+
 ## Organizations
 
 | Method | Endpoint | Description |
@@ -104,11 +115,11 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues` | List tasks (see filters below) |
-| POST | `/api/orgs/{id}/issues` | Create task |
+| POST | `/api/orgs/{id}/issues` | Create task; the target project requires `edit` or `admin` access |
 | GET | `/api/orgs/{id}/issues/{issueId}` | Get task detail |
 | PATCH | `/api/orgs/{id}/issues/{issueId}` | Update task; optional `comment_body` and `comment_mentions` also add a task comment in the same request |
 | DELETE | `/api/orgs/{id}/issues/{issueId}` | Delete task (admin/owner only) |
-| POST | `/api/orgs/{id}/issues/bulk` | Bulk create tasks (up to 50) |
+| POST | `/api/orgs/{id}/issues/bulk` | Bulk create tasks (up to 50); every target project requires `edit` or `admin` access |
 | 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 }`) |
@@ -286,7 +297,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, direct `attention_items`, `attention_summary`, signals, and a deterministic `recommended_action` when Atoll can propose one concrete strategy-backed next action. 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.
+Returns computed briefing with goal status, KPI pace/trend, initiative progress, assigned work, direct `attention_items`, `attention_summary`, signals, and a deterministic `recommended_action` when Atoll can propose one concrete strategy-backed next action. The endpoint is org-scoped, but project-bound payload details are filtered by the caller's project access. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. 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`.
 
@@ -456,14 +467,21 @@ URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts
 | GET | `/api/orgs/{id}/notifications/preferences` | Read current-member notification preferences, including default-on mention notifications |
 | POST | `/api/orgs/{id}/notifications/preferences` | Update current-member notification preferences, including mention opt-out and cleanup |
 | GET | `/api/orgs/{id}/integrations/google-chat` | Read Google Chat integration status (owner/admin) |
-| POST | `/api/orgs/{id}/integrations/google-chat/link-token` | Create a one-time Google Chat connect command for the current member |
+| GET | `/api/integrations/google-chat/connect-session` | Read a Chat config session and the signed-in human's eligible memberships |
+| POST | `/api/integrations/google-chat/connect-session` | Consume a Chat config session and link the selected membership |
+| GET | `/api/orgs/{id}/integrations/google-chat/member` | Read the current human member's Chat link |
+| DELETE | `/api/orgs/{id}/integrations/google-chat/member` | Disconnect the current human member |
+| POST | `/api/orgs/{id}/integrations/google-chat/member/test-message` | Send a test message to the current human member |
+| POST | `/api/orgs/{id}/integrations/google-chat/link-token` | Create a manual fallback Chat connect command (web session only; API keys rejected) |
 | POST | `/api/orgs/{id}/integrations/google-chat/test-message` | Send a Google Chat test message to the current admin (owner/admin) |
-| POST | `/api/integrations/google-chat/events` | Google Chat app event callback, verified with Google bearer token |
+| POST | `/api/integrations/google-chat/events` | Google Chat callback, verified with a Google-signed OIDC ID token whose audience is the callback URL; removal returns 204 |
 | GET | `/api/notifications` | List notifications (last 50, unread first) |
 | POST | `/api/notifications/{id}/read` | Mark as read |
 | POST | `/api/notifications/read-all` | Mark all as read |
 
-Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences support `in_app` and `google_chat` channels; `google_chat` is currently supported for `mention.created`. Disabling `google_chat` stops future Chat delivery without acknowledging in-app notifications. If `in_app` mentions are muted but `google_chat` mentions are enabled, Atoll can still create an acknowledged notification row for Chat delivery without surfacing it in the bell or heartbeat. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`. Google Chat user linking uses a one-time `connect <token>` command generated from Profile settings.
+Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences support `in_app` and `google_chat` channels; `google_chat` is currently supported for `mention.created`. Disabling `google_chat` stops future Chat delivery without acknowledging in-app notifications. If `in_app` mentions are muted but `google_chat` mentions are enabled, Atoll can still create an acknowledged notification row for Chat delivery without surfacing it in the bell or heartbeat. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`. Google Chat normally links humans through Chat-native `REQUEST_CONFIG`; sending `connect` in the Atoll DM explicitly starts it. Connect-session and member endpoints require a human web session. A one-time `connect <token>` command remains a manual fallback.
+
+Google Chat mention delivery is durably queued, dispatched asynchronously immediately after the request, and recovered by a 15-minute retry drain. Retries use deterministic Google request/message IDs, exponential backoff, and a five-attempt limit. Config sessions and unused manual connect tokens expire after 10 minutes; completion and event retries are idempotent.
 
 ## Agents
 

package/skill/references/api-fields.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- [Auth Context](#auth-context)
 - [Task Fields](#task-fields)
 - [Goal Fields](#goal-fields)
 - [KPI Fields](#kpi-fields)
@@ -20,6 +21,27 @@
 
 ---
 
+## Auth Context
+
+`GET /api/auth/me` returns the caller's organization role and API-key scopes
+alongside live per-project authorization:
+
+```json
+{
+  "auth": {
+    "type": "agent",
+    "role": "guest",
+    "scopes": [],
+    "projectAccess": [
+      { "projectId": "project-uuid", "accessLevel": "admin" }
+    ]
+  }
+}
+```
+
+Project-scoped agents intentionally remain organization guests. Role and
+project-access changes are read live and do not require key rotation.
+
 ## Task Fields
 
 Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also accepted for backward compatibility. Responses always use snake_case.
@@ -428,11 +450,13 @@ 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.
+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. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
 
 Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, direct replies, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `comment_id`, `reply_to_comment_id`, optional validated parent `routing`, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
 
-Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type`, `channel` (`in_app` or `google_chat`), and `enabled` for current-member delivery preferences. The `google_chat` channel currently supports `mention.created`. Setting `enabled: false` for `google_chat` stops future Chat delivery without acknowledging in-app notifications. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`. Google Chat user linking uses a one-time `connect <token>` command generated from Profile settings.
+Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type`, `channel` (`in_app` or `google_chat`), and `enabled` for current-member delivery preferences. The `google_chat` channel currently supports `mention.created`. Setting `enabled: false` for `google_chat` stops future Chat delivery without acknowledging in-app notifications. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`. Google Chat normally links humans through a short-lived `REQUEST_CONFIG` session with display-safe Chat identity fields and memberships owned by the signed-in human. Connect-session and member endpoints require a human web session; a one-time `connect <token>` command remains a manual fallback. The Chat callback requires a Google-signed OIDC ID token whose audience is the callback URL.
+
+Google Chat delivery rows are queued with mention notifications, dispatched asynchronously immediately, and reclaimed by a 15-minute recovery drain. Deterministic Google request/message IDs make retries idempotent; exponential backoff stops after five attempts. An unused link token expires after 10 minutes, while identical replay after a successful link returns the existing member link without changing it.
 
 Agents should follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When `start_work` uses `suggested_write.operation: "issue.update"` with a body, apply the status update and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.