@atollhq/skill-codex 0.4.7 → 0.4.9

package/README.md

@@ -7,9 +7,9 @@ Gives your Codex agent the ability to manage tasks, goals, KPIs, initiatives, mi
 ## Install
 
 ```bash
-npx @atollhq/skill-codex --profile agent-a --key sk_atoll_... --org your-org-id --project project-id --team team-id
+npx @atollhq/skill-codex@latest --profile agent-a --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-codex
+ATOLL_API_KEY=sk_atoll_... ATOLL_ORG_ID=your-org-id npx @atollhq/skill-codex@latest
 ```
 
 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. The installer does not write global `ATOLL_*` exports to `~/.zshrc` or `~/.bashrc` in profile mode. Use `atoll --profile agent-a ...` for profile-scoped commands, or omit `--profile` to use env-var mode.
@@ -26,6 +26,8 @@ This does five things:
 
 For profile mode, Codex has the Atoll skill immediately and terminal commands can use `atoll --profile agent-a ...`. For env-var mode, the installer writes `ATOLL_ENV_MODE=1` with the credential exports; open a fresh shell or `source` your profile.
 
+Use `@latest` in the `npx` command so npm does not reuse a stale cached installer. In profile mode, the installer prints its package version and a verification command; run `atoll --profile agent-a agent-context --json` if you need to confirm the profile was created.
+
 ## Using the integration
 
 Once installed, ask Codex anything task-related:

package/bin/install.mjs

@@ -6,6 +6,7 @@ import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'))
 
 function parseArgs(argv) {
   const args = {}
@@ -26,8 +27,8 @@ function parseArgs(argv) {
 
 function printUsage() {
   console.log(`
-Usage: npx @atollhq/skill-codex [--profile <name>] --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-codex
+Usage: npx @atollhq/skill-codex@latest [--profile <name>] --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-codex@latest
 
 Options:
   --profile   Atoll CLI profile name to create/update. Profile mode does not write shell env vars.
@@ -61,6 +62,8 @@ else args.baseUrl ??= process.env.ATOLL_BASE_URL
 
 if (args.help) { printUsage(); process.exit(0) }
 
+console.log(`Running @atollhq/skill-codex installer v${packageJson.version}`)
+
 if (!args.key || !args.org) {
   console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
@@ -192,6 +195,7 @@ if (args.profile) {
   writeAtollProfile()
   console.log('No Atoll shell exports were written.')
   console.log(`Run profile-scoped commands with: atoll --profile ${args.profile} ...`)
+  console.log(`Verify the profile with: atoll --profile ${args.profile} agent-context --json`)
   console.log(`\nDone! Codex has the Atoll skill installed, and the Atoll CLI profile "${args.profile}" is active.`)
   process.exit(0)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/references/api-endpoints.md

@@ -429,7 +429,7 @@ URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/agents` | List agents (owner/admin) |
 | 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 |
+| POST | `/api/orgs/{id}/agents` | Create org agent (`{ name, role?, setupScoped? }`), project-scoped agent (`{ name, projectIds }` or legacy `{ name, projectId, projectIds? }`), or personal agent (`{ name, personal: true }`) |
 | 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 |

package/skill/references/api-fields.md

@@ -15,6 +15,7 @@
 - [Heartbeat Response](#heartbeat-response)
 - [Analytics Response](#analytics-response)
 - [Plan Limit Errors](#plan-limit-errors)
+- [Agent Fields](#agent-fields)
 - [Enums](#enums)
 
 ---
@@ -73,6 +74,10 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 `resource` is one of `humans`, `agents`, `activeProjects`, or `activeIssues`.
 
+## Agent Fields
+
+Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`.
+
 ## Goal Fields
 
 ```json