@atollhq/skill-gemini 0.3.0 → 0.4.0

package/README.md

@@ -57,6 +57,8 @@ atoll auth login --profile agent-b --key sk_atoll_... --org-id org-uuid --projec
 atoll --profile agent-b issue list
 ```
 
+Always persist `--org-id` on named profiles, 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.
+
 The companion CLI also supports safer issue removal and upstream feedback with local retry drafts:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-gemini",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Install the Atoll project management integration for Gemini CLI",
   "bin": {
     "skill-gemini": "bin/install.mjs"

package/skill/SKILL.md

@@ -33,6 +33,26 @@ export ATOLL_API_KEY="sk_atoll_..."
 export ATOLL_ORG_ID="..."          # UUID of the org the key belongs to
 ```
 
+For OpenClaw / ClawHub, prefer skill-scoped config in `~/.openclaw/openclaw.json` instead of global shell exports:
+
+```json5
+{
+  skills: {
+    entries: {
+      "atoll-api": {
+        enabled: true,
+        apiKey: "sk_atoll_...",
+        env: {
+          ATOLL_ORG_ID: "..."
+        }
+      }
+    }
+  }
+}
+```
+
+`apiKey` maps to `ATOLL_API_KEY`; optional defaults such as `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` belong under `env`.
+
 **Sanity check** — exercises the org-scoped issues endpoint, not just `/api/auth/me`:
 
 ```bash
@@ -72,7 +92,9 @@ atoll auth use agent-a
 atoll --profile agent-b issue list
 ```
 
-Profiles can store default project, team, and base URL values. `atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed.
+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.
+
+`atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed.
 
 Common commands:
 
@@ -94,9 +116,13 @@ atoll issue view ATOLL-42   # alias kept for humans
 
 # Create a task
 atoll issue create --title "Fix login bug" --status todo --priority 1
+atoll issue upsert --match-title --project <project-id> --title "Fix login bug" --status todo
+atoll issue bulk-create --file ./issues.json --continue-on-error
 
 # Update a task
 atoll issue update ATOLL-42 --status in_progress
+atoll issue upsert ATOLL-42 --status in_progress
+atoll issue bulk-update --file ./updates.json --dry-run
 
 # Assign a task
 atoll issue assign ATOLL-42 --to <user-id>
@@ -105,6 +131,13 @@ atoll issue assign ATOLL-42 --to self
 # Comments
 atoll comment add ATOLL-42 --body "Working on this now"
 
+# Dependencies
+atoll dependency bulk-add --file ./dependencies.json --continue-on-error
+
+# Graph plans
+atoll plan validate --file ./plan.json
+atoll plan apply --file ./plan.json --dry-run
+
 # Safe removal
 atoll issue archive ATOLL-42
 atoll issue unarchive ATOLL-42
@@ -117,6 +150,7 @@ atoll feedback "The status error should list custom board statuses"
 # Projects & milestones
 atoll project list
 atoll milestone list --project <project-id>
+atoll milestone upsert --project <project-id> --name "v1.0" --date 2026-06-01
 ```
 
 Prefer the CLI for routine task operations, heartbeat checks, comments, and feedback. Use direct API calls when the CLI does not expose the needed endpoint yet.
@@ -127,6 +161,7 @@ CLI JSON conventions:
 - 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.
+- `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`.
 
 ## Quick Start — API (for advanced use)
 
@@ -226,6 +261,8 @@ Full endpoint tables and field schemas:
 | Comments | POST `.../comments` | GET `.../comments` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
 | Subtasks | POST `.../subtasks` | GET `.../subtasks` | PATCH `.../subtasks/{id}` | DELETE `.../subtasks/{id}` |
 
+Initiative create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `ownerId`, and `targetDate`.
+
 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). In the CLI, prefer `atoll issue archive <id>`. Permanent `atoll issue delete <id>` requires `--force` and supports `--dry-run`.
@@ -280,4 +317,4 @@ atoll feedback resend fb_123
 - All timestamps are ISO 8601 UTC
 - Board statuses are customizable per project -- query `/board-columns` for available values
 - API changes appear in real-time on the web board
-- List endpoints support `limit` (default 25, max 100) and `offset` pagination
+- List endpoints support `limit` (default 25, max 100), `offset` pagination, and optional `shape=envelope` / `response_shape=cli` for `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`

package/skill/references/api-endpoints.md

@@ -120,6 +120,7 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 - `orderDir` -- `asc` or `desc` (default)
 - `limit` -- max results (default 25, max 100)
 - `offset` -- pagination offset
+- `shape=envelope` or `response_shape=cli` -- opt into CLI-compatible list responses: `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`
 
 **GET task detail** returns enriched data: `milestone`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`.
 
@@ -207,6 +208,8 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | POST | `/api/orgs/{id}/initiatives/{initiativeId}/projects` | Add project to initiative |
 | DELETE | `/api/orgs/{id}/initiatives/{initiativeId}/projects` | Remove project from initiative |
 
+Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `ownerId`, and `targetDate`.
+
 ## Initiative Links
 
 | Method | Endpoint | Description |
@@ -328,8 +331,9 @@ Custom statuses per project. Each column defines a valid status value.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues/{issueId}/pr-links` | List linked pull requests |
+| POST | `/api/orgs/{id}/issues/{issueId}/pr-links` | Attach a GitHub PR URL (`{ url }`) |
 
-PR links are created automatically via the GitHub webhook integration.
+Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. PR links can also be created automatically via the GitHub webhook integration.
 
 ## Project Status Updates
 

package/skill/references/api-fields.md

@@ -129,7 +129,7 @@ Recording a snapshot auto-updates the KPI's `current_value`.
 For portfolio-style initiatives (grouping projects):
 ```json
 {
-  "name": "Q2 Platform Rewrite",
+  "title": "Q2 Platform Rewrite",
   "description": "Migrate all services to new architecture",
   "owner_id": "member-uuid",
   "start_date": "2026-04-01",
@@ -137,6 +137,8 @@ For portfolio-style initiatives (grouping projects):
 }
 ```
 
+Use `title` for create/update requests; create also accepts legacy `name`. Atoll keeps the legacy `name` field in sync for compatibility. Create accepts `goalId`, `ownerId`, and `targetDate` aliases for `goal_id`, `owner_id`, and `target_date`.
+
 Add/remove projects with `{ "project_id": "uuid" }`.
 
 ## Automation Rule Fields
@@ -254,7 +256,7 @@ URL must be HTTPS. Response includes `secret` for HMAC signature verification.
 
 All endpoints return JSON. Successful: `200` or `201`. Errors: `{ "error": "message" }` with `400`, `401`, `402`, `403`, `404`, `409`, or `500`.
 
-List responses include `total`, `limit`, `offset` for pagination.
+REST list responses use resource-specific keys by default. Main list endpoints support `?shape=envelope` or `?response_shape=cli` to return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`.
 
 ## Notes