@atollhq/skill-codex 0.4.8 → 0.4.10

package/README.md

@@ -7,25 +7,37 @@ 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.
 
+For multi-org setups, keep global Codex instructions neutral and bind profiles per repo:
+
+```bash
+npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org your-org-id \
+  --write-project-instructions --project-dir /path/to/repo --instruction-files agents,claude
+```
+
+`--write-project-instructions` writes a small managed block to repo-local instruction files. It requires `--profile`, defaults to the current directory, writes `AGENTS.md` by default, and can also write `CLAUDE.md` with `--instruction-files agents,claude`. If the target file already has unmanaged Atoll profile guidance, pass `--force-project-instructions` after reviewing the replacement.
+
 Get an agent API key from **Agents** in the Atoll app. Integration keys are still managed from **Settings > Members**.
 
-This does five things:
+This does six things:
 
 1. Installs the `atoll-api` skill to `~/.codex/skills/atoll-api/`
-2. Appends (or updates) an `# Atoll Integration` section in `~/.codex/AGENTS.md`
+2. Appends (or updates) a neutral `# Atoll Integration` section in `~/.codex/AGENTS.md`
 3. Copies API reference files to `~/.codex/atoll-references/`
 4. Creates or updates the named Atoll CLI profile when `--profile` is provided
 5. Appends Atoll env var exports to your shell profile (`~/.zshrc` or `~/.bashrc`) only when no profile is provided
+6. Optionally writes repo-local profile guidance when `--write-project-instructions` is provided
 
 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:
@@ -46,9 +58,9 @@ For terminal-first work, see [`@atollhq/cli`](https://www.npmjs.com/package/@ato
 npm install -g @atollhq/cli
 atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --team team-id
 atoll auth login --profile agent-a --key sk_atoll_... --org-id org-uuid --project project-id --no-team --no-base-url
-atoll heartbeat
-atoll issue list --json
-atoll agent-context
+atoll --profile agent-a heartbeat
+atoll --profile agent-a issue list --json
+atoll --profile agent-a agent-context
 ```
 
 For multiple agents or orgs, use CLI auth profiles:

package/bin/install.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, renameSync, rmSync } from 'node:fs'
+import { join, dirname, resolve, basename } from 'node:path'
 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 = {}
@@ -19,6 +20,10 @@ function parseArgs(argv) {
     else if (argv[i] === '--no-team') args.clearTeam = true
     else if (argv[i] === '--base-url' && argv[i + 1]) args.baseUrl = argv[++i]
     else if (argv[i] === '--no-base-url') args.clearBaseUrl = true
+    else if (argv[i] === '--write-project-instructions') args.writeProjectInstructions = true
+    else if (argv[i] === '--project-dir' && argv[i + 1]) args.projectDir = argv[++i]
+    else if (argv[i] === '--instruction-files' && argv[i + 1]) args.instructionFiles = argv[++i]
+    else if (argv[i] === '--force-project-instructions') args.forceProjectInstructions = true
     else if (argv[i] === '--help' || argv[i] === '-h') args.help = true
   }
   return args
@@ -26,8 +31,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.
@@ -39,12 +44,21 @@ Options:
   --no-team   Clear any saved default team.
   --base-url  Atoll base URL. Defaults to ATOLL_BASE_URL.
   --no-base-url Clear any saved custom base URL.
+  --write-project-instructions
+              Write a small repo-local Atoll profile block. Requires --profile.
+  --project-dir
+              Directory for repo-local instructions. Defaults to the current directory.
+  --instruction-files
+              Comma-separated files to update: agents, claude, or agents,claude. Defaults to agents.
+  --force-project-instructions
+              Replace existing unmanaged Atoll profile guidance in repo-local instruction files.
   --help      Show this help message
 
 Installs the Atoll integration for Codex CLI:
   - Installs the atoll-api skill to ~/.codex/skills/atoll-api/
-  - Writes AGENTS.md with API reference to ~/.codex/
+  - Writes neutral AGENTS.md API guidance to ~/.codex/
   - Creates/updates an Atoll CLI profile when --profile is provided
+  - Optionally writes repo-local AGENTS.md/CLAUDE.md profile guidance with --write-project-instructions
   - Otherwise writes Atoll env vars to your shell profile for env-var mode
 `)
 }
@@ -61,6 +75,34 @@ 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}`)
+
+const instructionFileChoices = (args.instructionFiles ?? 'agents')
+  .split(',')
+  .map((entry) => entry.trim().toLowerCase())
+  .filter(Boolean)
+const allowedInstructionFiles = new Set(['agents', 'claude'])
+if (instructionFileChoices.some((entry) => !allowedInstructionFiles.has(entry))) {
+  console.error('Error: --instruction-files must be agents, claude, or agents,claude')
+  process.exit(1)
+}
+
+const projectInstructionFiles = [...new Set(instructionFileChoices)]
+if (args.writeProjectInstructions && projectInstructionFiles.length === 0) {
+  console.error('Error: --instruction-files must include agents, claude, or agents,claude')
+  process.exit(1)
+}
+
+if (args.writeProjectInstructions && !args.profile) {
+  console.error('Error: --write-project-instructions requires --profile so the repo-local guidance can name a profile')
+  process.exit(1)
+}
+
+if (args.writeProjectInstructions && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args.profile)) {
+  console.error('Error: --write-project-instructions requires a profile name that starts with a letter or number and contains only letters, numbers, dots, underscores, or hyphens')
+  process.exit(1)
+}
+
 if (!args.key || !args.org) {
   console.error('Error: provide --key and --org, or set ATOLL_API_KEY and ATOLL_ORG_ID\n')
   printUsage()
@@ -101,7 +143,6 @@ function writeAtollProfile() {
   else delete profile.defaultTeam
   if (args.baseUrl) profile.baseUrl = args.baseUrl
   else delete profile.baseUrl
-  config.activeProfile = args.profile
 
   mkdirSync(atollDir, { recursive: true })
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
@@ -109,6 +150,107 @@ function writeAtollProfile() {
   return configPath
 }
 
+const projectInstructionsStart = '<!-- ATOLL:PROJECT-INSTRUCTIONS:START -->'
+const projectInstructionsEnd = '<!-- ATOLL:PROJECT-INSTRUCTIONS:END -->'
+const projectInstructionsPattern = new RegExp(`${projectInstructionsStart}[\\s\\S]*?${projectInstructionsEnd}`)
+
+function projectInstructionBlock(profileName) {
+  return `${projectInstructionsStart}
+## Atoll
+
+For this workspace, use Atoll CLI profile \`${profileName}\`:
+
+\`\`\`bash
+atoll --profile ${profileName} ...
+\`\`\`
+${projectInstructionsEnd}`
+}
+
+function removeUnmanagedAtollProfileGuidance(content) {
+  return content
+    .split('\n')
+    .filter((line) => !/atoll\s+--profile\s+\S+/i.test(line) && !/Atoll CLI profile/i.test(line))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()
+}
+
+function buildProjectInstructionUpdate(targetPath, block) {
+  const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf-8') : ''
+
+  if (projectInstructionsPattern.test(existing)) {
+    return {
+      targetPath,
+      content: existing.replace(projectInstructionsPattern, block),
+    }
+  }
+
+  if (/atoll\s+--profile\s+\S+/i.test(existing) || /Atoll CLI profile/i.test(existing)) {
+    if (!args.forceProjectInstructions) {
+      console.error(`Error: ${targetPath} already contains unmanaged Atoll profile guidance. Re-run with --force-project-instructions to replace it.`)
+      process.exit(1)
+    }
+    const cleaned = removeUnmanagedAtollProfileGuidance(existing)
+    return {
+      targetPath,
+      content: cleaned ? `${cleaned}\n\n${block}\n` : `${block}\n`,
+    }
+  }
+
+  return {
+    targetPath,
+    content: existing.trimEnd() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`,
+  }
+}
+
+function writeProjectInstructionUpdates(updates) {
+  const prepared = []
+
+  try {
+    for (const [index, { targetPath, content }] of updates.entries()) {
+      const tmpPath = join(dirname(targetPath), `.${basename(targetPath)}.atoll-${process.pid}-${Date.now()}-${index}.tmp`)
+      const normalized = content.endsWith('\n') ? content : `${content}\n`
+      writeFileSync(tmpPath, normalized, { flag: 'wx' })
+      prepared.push({ targetPath, tmpPath })
+    }
+
+    for (const { targetPath, tmpPath } of prepared) {
+      renameSync(tmpPath, targetPath)
+      console.log(`Wrote Atoll project instructions to ${targetPath}`)
+    }
+  } catch (error) {
+    for (const { tmpPath } of prepared) {
+      if (existsSync(tmpPath)) rmSync(tmpPath, { force: true })
+    }
+    console.error(`Error: failed to write Atoll project instructions: ${error.message}`)
+    process.exit(1)
+  }
+}
+
+function writeProjectInstructions() {
+  if (!args.writeProjectInstructions) return
+
+  const projectDir = resolve(args.projectDir ?? process.cwd())
+  if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+    console.error(`Error: --project-dir must be an existing directory: ${projectDir}`)
+    process.exit(1)
+  }
+
+  const block = projectInstructionBlock(args.profile)
+  const fileNames = {
+    agents: 'AGENTS.md',
+    claude: 'CLAUDE.md',
+  }
+
+  const updates = []
+  for (const choice of projectInstructionFiles) {
+    const targetPath = join(projectDir, fileNames[choice])
+    updates.push(buildProjectInstructionUpdate(targetPath, block))
+  }
+
+  writeProjectInstructionUpdates(updates)
+}
+
 // 1. Install the Codex skill to ~/.codex/skills/atoll-api/
 const codexDir = join(homedir(), '.codex')
 mkdirSync(codexDir, { recursive: true })
@@ -123,27 +265,9 @@ console.log(`Installed Atoll skill to ${skillDest}`)
 const skillMd = readFileSync(join(skillDir, 'SKILL.md'), 'utf-8')
 // Strip YAML frontmatter for AGENTS.md
 const body = skillMd.replace(/^---[\s\S]*?---\n*/, '')
-const profileModeInstructions = args.profile ? `## Profile-scoped CLI configuration
-
-This Codex install is scoped to Atoll CLI profile \`${args.profile}\`. No global \`ATOLL_API_KEY\`, \`ATOLL_ORG_ID\`, \`ATOLL_PROJECT\`, \`ATOLL_TEAM\`, or \`ATOLL_BASE_URL\` shell exports were written. Use \`atoll --profile ${args.profile} ...\` for direct Atoll CLI commands. Direct API snippets below use \`ATOLL_API_KEY\` / \`ATOLL_ORG_ID\` only when you intentionally choose env-var mode.
-
-` : ''
-const optionalCredentialLines = [
-  args.profile ? `- Atoll CLI profile: ${args.profile}` : null,
-  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 agentsMd = `# Atoll Integration
 
-${profileModeInstructions}
 ${body}
-
-## Credentials
-
-- API Key: ${args.profile ? `stored in Atoll CLI profile \`${args.profile}\`` : 'set as ATOLL_API_KEY environment variable'}
-- Org ID: ${args.org}${optionalCredentialLines ? `\n${optionalCredentialLines}` : ''}
 `
 
 const agentsPath = join(codexDir, 'AGENTS.md')
@@ -190,9 +314,11 @@ if (args.profile) {
     console.log(`Removed stale Atoll shell exports from ${profilePath}`)
   }
   writeAtollProfile()
+  writeProjectInstructions()
   console.log('No Atoll shell exports were written.')
   console.log(`Run profile-scoped commands with: atoll --profile ${args.profile} ...`)
-  console.log(`\nDone! Codex has the Atoll skill installed, and the Atoll CLI profile "${args.profile}" is active.`)
+  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 configured.`)
   process.exit(0)
 }
 

package/package.json

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

package/skill/SKILL.md

@@ -186,7 +186,7 @@ CLI JSON conventions:
 
 When a human asks you to help automate a KPI from a third-party API, use this Atoll skill. If the current agent environment does not have the `atoll-api` skill installed, tell the user to install it before continuing or use the Atoll CLI/MCP tools directly if they are available.
 
-Agents may create draft syncs and validate proposed configs only after a human admin has allowlisted the exact destination host in Atoll. Human admins must review the draft in Atoll, enter secrets, dry-run, publish, disable, or run-now with snapshot writing.
+Agents may create draft syncs and validate proposed configs only after a human admin has allowlisted the exact destination host in Atoll. Human admins must create or review the draft in Settings > Integrations > KPI syncs, edit supported request/extraction fields and secrets through structured UI, dry-run, publish, disable, or run-now with snapshot writing.
 
 ```bash
 atoll kpi sync validate <kpi-id> \

package/skill/references/api-endpoints.md

@@ -203,6 +203,7 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | POST | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | Record a snapshot |
 | GET | `/api/orgs/{id}/kpi-http-sync-policy` | List exact-host KPI HTTP sync allowlist policy |
 | POST | `/api/orgs/{id}/kpi-http-sync-policy` | Add an allowed exact host (human admin only) |
+| GET | `/api/orgs/{id}/kpi-http-syncs` | List org-wide KPI HTTP sync review rows for Settings; admins get config/secret metadata, members get redacted status rows |
 | GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | List KPI HTTP syncs |
 | POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Create a draft KPI HTTP sync |
 | PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Validate a proposed KPI HTTP sync config without storing or running it |
@@ -429,7 +430,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