@atollhq/skill-gemini 0.1.11 → 0.1.12

package/README.md

@@ -7,11 +7,13 @@ Gives your Gemini agent the ability to manage tasks, goals, KPIs, initiatives, m
 ## Install
 
 ```bash
-npx @atollhq/skill-gemini --key sk_atoll_... --org your-org-id
+npx @atollhq/skill-gemini --key sk_atoll_... --org your-org-id --project project-id --team team-id
 # or
 ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-gemini
 ```
 
+Optional defaults: `--project`, `--team`, and `--base-url` write `ATOLL_PROJECT`, `ATOLL_TEAM`, and `ATOLL_BASE_URL` for the agent.
+
 Get an API key from **Settings > Members > Add Agent** (or **Create API Key** for integrations) in the Atoll app.
 
 This does four things:
@@ -19,7 +21,7 @@ This does four things:
 1. Installs the `atoll-api` skill to `~/.gemini/skills/atoll-api/`
 2. Appends (or updates) an `# Atoll Integration` section in `~/.gemini/GEMINI.md`
 3. Copies API reference files to `~/.gemini/atoll-references/`
-4. Appends `ATOLL_API_KEY` and `ATOLL_ORG_ID` exports to your shell profile (`~/.zshrc` or `~/.bashrc`)
+4. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`)
 
 Open a fresh shell (or `source` your profile) and Gemini has the Atoll integration.
 
@@ -31,6 +33,7 @@ Once installed, ask Gemini anything task-related:
 "List my Atoll tasks"
 "Create an issue to fix the login bug, priority 1"
 "What goals are off pace?"
+"Check my Atoll heartbeat"
 "Move ATOLL-42 to in_progress"
 ```
 
@@ -40,19 +43,26 @@ For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@ato
 
 ```bash
 npm install -g @atollhq/cli
-atoll auth setup
-atoll issue list
+atoll auth login --profile agent-a --key sk_atoll_... --org your-org-slug --project project-id --team team-id
+atoll heartbeat
+atoll issue list --json
+atoll agent-context
 ```
 
 For multiple agents or orgs, use CLI auth profiles:
 
 ```bash
-atoll auth manage
-atoll auth profiles
-atoll auth login --profile agent-a --key sk_atoll_... --org acme --project project-uuid
-atoll auth login --profile agent-b --key sk_atoll_... --org client
+atoll auth login --profile agent-a --key sk_atoll_... --org acme
+atoll auth login --profile agent-b --key sk_atoll_... --org client --project project-id --team team-id
 atoll --profile agent-b issue list
-atoll auth delete-profile agent-b --force
+```
+
+The companion CLI also supports safer issue removal and local/upstream feedback:
+
+```bash
+atoll issue archive ATOLL-42
+atoll issue delete ATOLL-42 --dry-run
+atoll feedback "The heartbeat output should include blocked issue details"
 ```
 
 ## License

package/bin/install.mjs

@@ -12,6 +12,9 @@ function parseArgs(argv) {
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === '--key' && argv[i + 1]) args.key = argv[++i]
     else if (argv[i] === '--org' && argv[i + 1]) args.org = argv[++i]
+    else if (argv[i] === '--project' && argv[i + 1]) args.project = argv[++i]
+    else if (argv[i] === '--team' && argv[i + 1]) args.team = argv[++i]
+    else if (argv[i] === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i]
     else if (argv[i] === '--help' || argv[i] === '-h') args.help = true
   }
   return args
@@ -19,24 +22,30 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-gemini --key <api-key> --org <org-id>
+Usage: npx @atollhq/skill-gemini --key <api-key> --org <org-id> [--project <id>] [--team <id-or-slug>] [--base-url <url>]
    or: ATOLL_API_KEY=<api-key> ATOLL_ORG_ID=<org-id> npx @atollhq/skill-gemini
 
 Options:
-  --key   Atoll API key (sk_atoll_...). Defaults to ATOLL_API_KEY.
-  --org   Organization ID. Defaults to ATOLL_ORG_ID.
-  --help  Show this help message
+  --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.
+  --team      Default team ID or slug. Defaults to ATOLL_TEAM.
+  --base-url  Atoll base URL. Defaults to ATOLL_BASE_URL.
+  --help      Show this help message
 
 Installs the Atoll integration for Gemini CLI:
   - Installs the atoll-api skill to ~/.gemini/skills/atoll-api/
   - Writes GEMINI.md with API reference to ~/.gemini/
-  - Sets ATOLL_API_KEY and ATOLL_ORG_ID env vars
+  - Sets Atoll env vars
 `)
 }
 
 const args = parseArgs(process.argv)
 args.key ??= process.env.ATOLL_API_KEY
 args.org ??= process.env.ATOLL_ORG_ID
+args.project ??= process.env.ATOLL_PROJECT
+args.team ??= process.env.ATOLL_TEAM
+args.baseUrl ??= process.env.ATOLL_BASE_URL
 
 if (args.help) { printUsage(); process.exit(0) }
 
@@ -64,6 +73,11 @@ console.log(`Installed Atoll skill to ${skillDest}`)
 // 2. Write GEMINI.md to ~/.gemini/
 const skillMd = readFileSync(join(skillDir, 'SKILL.md'), 'utf-8')
 const body = skillMd.replace(/^---[\s\S]*?---\n*/, '')
+const optionalCredentialLines = [
+  args.project ? `- Default project ID: ${args.project}` : null,
+  args.team ? `- Default team: ${args.team}` : null,
+  args.baseUrl ? `- Base URL: ${args.baseUrl}` : null,
+].filter(Boolean).join('\n')
 
 const geminiMd = `# Atoll Integration
 
@@ -72,7 +86,7 @@ ${body}
 ## Credentials
 
 - API Key: set as ATOLL_API_KEY environment variable
-- Org ID: ${args.org}
+- Org ID: ${args.org}${optionalCredentialLines ? `\n${optionalCredentialLines}` : ''}
 `
 
 const geminiPath = join(geminiDir, 'GEMINI.md')
@@ -117,12 +131,27 @@ if (existsSync(profilePath)) {
   }
   profile = upsertExport(profile, 'ATOLL_API_KEY', args.key)
   profile = upsertExport(profile, 'ATOLL_ORG_ID', args.org)
+  if (args.project) profile = upsertExport(profile, 'ATOLL_PROJECT', args.project)
+  if (args.team) profile = upsertExport(profile, 'ATOLL_TEAM', args.team)
+  if (args.baseUrl) profile = upsertExport(profile, 'ATOLL_BASE_URL', args.baseUrl)
   writeFileSync(profilePath, profile)
-  console.log(`Configured ATOLL_API_KEY and ATOLL_ORG_ID in ${profilePath}`)
+  const configuredVars = ['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')
+  console.log(`Configured ${configuredVars.join(', ')} in ${profilePath}`)
 } else {
-  const envBlock = `\n# Atoll (added by @atollhq/skill-gemini)\nexport ATOLL_API_KEY="${args.key}"\nexport ATOLL_ORG_ID="${args.org}"\n`
+  const envLines = [
+    '# Atoll (added by @atollhq/skill-gemini)',
+    `export ATOLL_API_KEY="${args.key}"`,
+    `export ATOLL_ORG_ID="${args.org}"`,
+    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,
+  ].filter(Boolean)
+  const envBlock = `\n${envLines.join('\n')}\n`
   writeFileSync(profilePath, envBlock)
-  console.log(`Created ${profilePath} with ATOLL_API_KEY and ATOLL_ORG_ID`)
+  console.log(`Created ${profilePath} with Atoll env vars`)
 }
 
 console.log(`\nDone! Restart your shell, then Gemini CLI will have access to the Atoll API.`)

package/package.json

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

package/skill/SKILL.md

@@ -56,45 +56,44 @@ npm install -g @atollhq/cli   # or: npx @atollhq/cli ...
 Configure once:
 
 ```bash
-atoll auth setup
-
-# Or configure non-interactively:
-atoll auth login --key sk_atoll_... --org my-org
+atoll auth login --key sk_atoll_...
+atoll config set-org my-org
 ```
 
 For machines or agents that need multiple credentials, use auth profiles:
 
 ```bash
-atoll auth setup
-atoll auth manage
+atoll auth login --profile agent-a --key sk_atoll_... --org acme
+atoll auth login --profile agent-b --key sk_atoll_... --org client --project project-id --team team-id
 atoll auth profiles
 atoll auth use agent-a
 
-# Non-interactive profile setup can include default org/project context
-atoll auth login --profile agent-a --key sk_atoll_... --org acme --project project-uuid
-atoll auth login --profile agent-b --key sk_atoll_... --org client
-
 # Run one command as a specific profile
 atoll --profile agent-b issue list
-
-# Remove an obsolete profile
-atoll auth delete-profile agent-b --force
 ```
 
+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.
+
 Common commands:
 
 ```bash
+# Agent orientation
+atoll heartbeat
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+atoll heartbeat --json
+atoll agent-context
+
 # List tasks
-atoll issue list
-atoll issue list --project <project-id>
-atoll issue list --status todo --priority 1
+atoll issue list --json
+atoll issue list --status todo --priority 1 --limit 25
 
 # View a task
-atoll issue view ATOLL-42
+atoll issue get ATOLL-42
+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 create --title "Fix login bug" --project <project-id>
 
 # Update a task
 atoll issue update ATOLL-42 --status in_progress
@@ -106,15 +105,28 @@ atoll issue assign ATOLL-42 --to self
 # Comments
 atoll comment add ATOLL-42 --body "Working on this now"
 
+# Safe removal
+atoll issue archive ATOLL-42
+atoll issue unarchive ATOLL-42
+atoll issue delete ATOLL-42 --dry-run
+atoll issue delete ATOLL-42 --force
+
+# Report friction to Atoll maintainers
+atoll feedback "The status error should list custom board statuses"
+
 # Projects & milestones
 atoll project list
-atoll config set-project <project-id>   # optional default for issue/milestone commands
 atoll milestone list --project <project-id>
-atoll milestone list                    # uses the default project when configured
 ```
 
-Profiles can store a default project ID. Explicit `--project` flags override it, and
-`ATOLL_PROJECT` overrides profile config for one process.
+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.
+
+CLI JSON conventions:
+
+- Use `--json` for machine-readable output.
+- 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.
 
 ## Quick Start — API (for advanced use)
 
@@ -135,7 +147,7 @@ atoll "/api/orgs/$ATOLL_ORG_ID/issues?status=todo"
 
 ## The Heartbeat Loop
 
-The primary pattern for autonomous agents. `GET /api/orgs/{id}/heartbeat` returns a computed briefing:
+The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when the CLI is available; it wraps `GET /api/orgs/{id}/heartbeat` and returns the same computed briefing:
 
 - **Goal status** with days remaining
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
@@ -145,6 +157,15 @@ The primary pattern for autonomous agents. `GET /api/orgs/{id}/heartbeat` return
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
+Useful CLI forms:
+
+```bash
+atoll heartbeat
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+atoll heartbeat --json
+```
+
 **The agent loop:**
 1. Call heartbeat
 2. Read signals (highest severity first)
@@ -157,7 +178,8 @@ Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `mile
 ### Pick up and complete a task
 
 ```bash
-atoll issue list --status todo --assignee self        # find assigned work
+atoll heartbeat --signals-only                        # orient first
+atoll issue list --status todo --assignee self --json # find assigned work
 atoll issue update ATOLL-42 --status in_progress      # start work
 atoll comment add ATOLL-42 --body "Progress update…"  # report progress
 atoll issue update ATOLL-42 --status done              # complete
@@ -206,7 +228,7 @@ 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).
+† `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`.
 
 ### Quick enum reference
 
@@ -242,6 +264,14 @@ curl -X POST https://atollhq.com/api/feedback \
 
 No authentication required. Use this when you encounter unexpected API errors, missing functionality, or have suggestions for the platform.
 
+The CLI can record the same feedback locally, and optionally submit upstream:
+
+```bash
+atoll feedback "The /issues endpoint returns 500 when filtering by milestoneId and status together"
+atoll feedback --send "heartbeat should emit issue_blocked signals directly"
+atoll feedback list --json
+```
+
 ## Notes
 
 - Request bodies accept camelCase; responses use snake_case

package/skill/references/api-endpoints.md

@@ -231,6 +231,14 @@ Returns computed briefing with goal status, KPI pace/trend, initiative progress,
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
+CLI equivalent:
+
+```bash
+atoll heartbeat --json
+atoll heartbeat --signals-only
+atoll heartbeat --severity critical
+```
+
 ## Activity
 
 | Method | Endpoint | Description |
@@ -246,8 +254,6 @@ Filters: `by_me` = your actions; `mine` = activity on issues assigned to you.
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/teams` | List teams |
 | POST | `/api/orgs/{id}/teams` | Create team |
-| PATCH | `/api/orgs/{id}/teams/{teamId}` | Update team (`{ name?, slug?, description? }`) |
-| DELETE | `/api/orgs/{id}/teams/{teamId}` | Delete team |
 | GET | `/api/orgs/{id}/teams/{teamId}/members` | List team members |
 | POST | `/api/orgs/{id}/teams/{teamId}/members` | Add member to team |
 | DELETE | `/api/orgs/{id}/teams/{teamId}/members/{memberId}` | Remove from team |
@@ -392,7 +398,9 @@ URL must be HTTPS. Returns webhook record plus `secret` for HMAC verification.
 | 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 }`) |
+| POST | `/api/orgs/{id}/agents/{agentId}/install-snippets` | Get install snippets (`{ 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.
 
 ## Integrations
 
@@ -421,3 +429,11 @@ No authentication required. Sends feedback to the Atoll team's internal board.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | POST | `/api/feedback` | Submit bug report or feature request (`{ type, description, userEmail?, userName?, url? }`)
+
+CLI equivalent:
+
+```bash
+atoll feedback "Describe the bug or feature request"
+atoll feedback --send "Submit upstream as well"
+atoll feedback list --json
+```