@atollhq/skill-codex 0.4.15 → 0.4.18

package/README.md

@@ -38,6 +38,11 @@ For profile mode, Codex has the Atoll skill immediately, global Codex guidance p
 
 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.
 
+The installer writes credential-bearing files atomically, refuses symbolic-link
+targets, uses `0600` for credential files, and uses `0700` for dedicated
+credential directories. Concurrent installer runs are serialized, and env-var
+mode shell-quotes every value written to the shell profile.
+
 ## Using the integration
 
 Once installed, ask Codex anything task-related:

package/bin/install.mjs

@@ -1,8 +1,23 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, renameSync, rmSync } from 'node:fs'
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
 import { join, dirname, resolve, basename } from 'node:path'
 import { homedir } from 'node:os'
+import fsExt from 'fs-ext-extra-prebuilt'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -114,21 +129,142 @@ if (!args.key.startsWith('sk_atoll_')) {
   process.exit(1)
 }
 
+function lstatIfExists(path) {
+  try {
+    return lstatSync(path)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+function assertSafeFile(path) {
+  const stat = lstatIfExists(path)
+  if (!stat) return
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Refusing symbolic link for credential file: ${path}`)
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Refusing non-file credential path: ${path}`)
+  }
+}
+
+function ensurePrivateDirectory(path) {
+  const stat = lstatIfExists(path)
+  if (stat) {
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Refusing symbolic link for credential directory: ${path}`)
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`Refusing non-directory credential path: ${path}`)
+    }
+  } else {
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+  }
+  chmodSync(path, 0o700)
+}
+
 function readJson(path) {
+  assertSafeFile(path)
   if (!existsSync(path)) return {}
   try {
     return JSON.parse(readFileSync(path, 'utf-8'))
-  } catch {
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error
     console.error(`Warning: could not parse ${path}, creating fresh config`)
     return {}
   }
 }
 
+function readPrivateFile(path) {
+  assertSafeFile(path)
+  return readFileSync(path, 'utf-8')
+}
+
+function writePrivateFile(path, content) {
+  assertSafeFile(path)
+  const tmpPath = join(
+    dirname(path),
+    `.${basename(path)}.atoll-${process.pid}-${Date.now()}.tmp`,
+  )
+  try {
+    writeFileSync(tmpPath, content, { flag: 'wx', mode: 0o600 })
+    chmodSync(tmpPath, 0o600)
+    renameSync(tmpPath, path)
+    chmodSync(path, 0o600)
+  } catch (error) {
+    if (existsSync(tmpPath)) rmSync(tmpPath, { force: true })
+    throw error
+  }
+}
+
+function acquireInstallerLock() {
+  const atollDir = join(homedir(), '.atoll')
+  const target = join(atollDir, 'installer.lock-target')
+  ensurePrivateDirectory(atollDir)
+  try {
+    writeFileSync(target, '', { flag: 'wx', mode: 0o600 })
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+    assertSafeFile(target)
+  }
+  chmodSync(target, 0o600)
+  const fd = openSync(target, 'r+')
+  const deadline = Date.now() + 10_000
+  const waitState = new Int32Array(new SharedArrayBuffer(4))
+  while (true) {
+    try {
+      if (process.platform === 'win32') {
+        fsExt.lockFileExSync(
+          fd,
+          fsExt.constants.LOCKFILE_EXCLUSIVE_LOCK
+            | fsExt.constants.LOCKFILE_FAIL_IMMEDIATELY,
+          0,
+          0,
+          1,
+          0,
+        )
+      } else {
+        fsExt.fcntlSync(fd, 'setlk', fsExt.constants.F_WRLCK, 0, 0)
+      }
+      break
+    } catch (error) {
+      if (!['EACCES', 'EAGAIN', 'EBUSY', 'EWOULDBLOCK'].includes(error?.code)) {
+        closeSync(fd)
+        throw error
+      }
+      if (Date.now() >= deadline) {
+        closeSync(fd)
+        throw new Error(`Timed out waiting for installer lock: ${target}`)
+      }
+      Atomics.wait(waitState, 0, 0, 25)
+    }
+  }
+
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    try {
+      if (process.platform === 'win32') {
+        fsExt.unlockFileExSync(fd, 0, 0, 1, 0)
+      } else {
+        fsExt.fcntlSync(fd, 'setlk', fsExt.constants.F_UNLCK, 0, 0)
+      }
+    } finally {
+      closeSync(fd)
+    }
+  }
+}
+
+const releaseInstallerLock = acquireInstallerLock()
+
 function writeAtollProfile() {
   if (!args.profile) return null
 
   const atollDir = join(homedir(), '.atoll')
   const configPath = join(atollDir, 'config.json')
+  ensurePrivateDirectory(atollDir)
   const config = readJson(configPath)
   config.profiles ??= {}
   config.profiles[args.profile] ??= {}
@@ -144,8 +280,7 @@ function writeAtollProfile() {
   if (args.baseUrl) profile.baseUrl = args.baseUrl
   else delete profile.baseUrl
 
-  mkdirSync(atollDir, { recursive: true })
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
+  writePrivateFile(configPath, JSON.stringify(config, null, 2) + '\n')
   console.log(`Configured Atoll CLI profile "${args.profile}" in ${configPath}`)
   return configPath
 }
@@ -322,7 +457,7 @@ const profilePath = shell.includes('zsh')
 // 4. In profile mode, keep credentials scoped to the Atoll CLI profile.
 if (args.profile) {
   if (existsSync(profilePath)) {
-    let profile = readFileSync(profilePath, 'utf-8')
+    let profile = readPrivateFile(profilePath)
     profile = removeExport(profile, 'ATOLL_PROFILE')
     profile = removeExport(profile, 'ATOLL_API_KEY')
     profile = removeExport(profile, 'ATOLL_ORG_ID')
@@ -330,7 +465,7 @@ if (args.profile) {
     profile = removeExport(profile, 'ATOLL_TEAM')
     profile = removeExport(profile, 'ATOLL_BASE_URL')
     profile = removeExport(profile, 'ATOLL_ENV_MODE')
-    writeFileSync(profilePath, profile)
+    writePrivateFile(profilePath, profile)
     console.log(`Removed stale Atoll shell exports from ${profilePath}`)
   }
   writeAtollProfile()
@@ -339,14 +474,19 @@ if (args.profile) {
   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 configured.`)
+  releaseInstallerLock()
   process.exit(0)
 }
 
 // 4. Set env vars in shell profile for env-var mode.
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\"'\"'")}'`
+}
+
 function upsertExport(profile, name, value) {
-  const line = `export ${name}="${value}"`
+  const line = `export ${name}=${shellQuote(value)}`
   const pattern = new RegExp(`^export ${name}=.*$`, 'm')
-  if (pattern.test(profile)) return profile.replace(pattern, line)
+  if (pattern.test(profile)) return profile.replace(pattern, () => line)
   return `${profile.trimEnd()}\n${line}\n`
 }
 
@@ -356,7 +496,7 @@ function removeExport(profile, name) {
 }
 
 if (existsSync(profilePath)) {
-  let profile = readFileSync(profilePath, 'utf-8')
+  let profile = readPrivateFile(profilePath)
   if (!profile.includes('# Atoll (added by @atollhq/skill-codex)')) {
     profile = `${profile.trimEnd()}\n\n# Atoll (added by @atollhq/skill-codex)\n`
   }
@@ -370,7 +510,7 @@ if (existsSync(profilePath)) {
   if (args.baseUrl) profile = upsertExport(profile, 'ATOLL_BASE_URL', args.baseUrl)
   else profile = removeExport(profile, 'ATOLL_BASE_URL')
   profile = upsertExport(profile, 'ATOLL_ENV_MODE', '1')
-  writeFileSync(profilePath, profile)
+  writePrivateFile(profilePath, profile)
 
   const configuredVars = []
   configuredVars.push('ATOLL_API_KEY', 'ATOLL_ORG_ID', 'ATOLL_ENV_MODE')
@@ -381,16 +521,17 @@ if (existsSync(profilePath)) {
 } else {
   const envLines = [
     '# Atoll (added by @atollhq/skill-codex)',
-    `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,
-    'export ATOLL_ENV_MODE="1"',
+    `export ATOLL_API_KEY=${shellQuote(args.key)}`,
+    `export ATOLL_ORG_ID=${shellQuote(args.org)}`,
+    args.project ? `export ATOLL_PROJECT=${shellQuote(args.project)}` : null,
+    args.team ? `export ATOLL_TEAM=${shellQuote(args.team)}` : null,
+    args.baseUrl ? `export ATOLL_BASE_URL=${shellQuote(args.baseUrl)}` : null,
+    `export ATOLL_ENV_MODE=${shellQuote('1')}`,
   ].filter(Boolean)
   const envBlock = `\n${envLines.join('\n')}\n`
-  writeFileSync(profilePath, envBlock)
+  writePrivateFile(profilePath, envBlock)
   console.log(`Created ${profilePath} with Atoll env vars`)
 }
 
 console.log(`\nDone! Restart your shell, then Codex will have access to the Atoll API.`)
+releaseInstallerLock()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.15",
+  "version": "0.4.18",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"
@@ -21,8 +21,8 @@
     "url": "git+https://github.com/atollhq/atoll.git",
     "directory": "packages/skill-codex"
   },
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "fs-ext-extra-prebuilt": "2.2.9"
   },
   "license": "MIT",
   "type": "module"

package/skill/SKILL.md

@@ -20,7 +20,7 @@ Goals (directional objectives with deadlines)
 
 This means an agent can reason: "We're off pace on paying_customers → the Content Pipeline initiative should drive signups but has stalled issues → unblocking those is the highest-leverage action right now."
 
-Agents are org members with the same API, same permissions, same ability to create goals, update KPIs, propose initiatives, and execute work. The system does not distinguish between human and agent actions.
+Agents are organization members using the same API and authorization model as humans. Effective organization role and project scope still govern each action; agent identity does not bypass those checks.
 
 ## Authentication
 
@@ -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,14 @@ 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.
+Repo-local `baseUrl` values cannot reuse a saved profile key unless that same base URL is stored in the profile. Set `ATOLL_TRUST_REPO_BASE_URL=1` only for a single process after verifying both the repository and destination host.
+
+`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.
+
+`atoll issue list --open` excludes terminal statuses `done` and `cancelled`,
+plus archived issues, while preserving every custom and other non-terminal
+status. It composes with other list filters, ordering, pagination, and JSON,
+and cannot be combined with `--include-archived`.
 
 Common commands:
 
@@ -110,6 +119,7 @@ atoll agent-context
 
 # List tasks
 atoll issue list --json
+atoll issue list --open
 atoll issue list --status todo --priority 1 --limit 25
 atoll issue list --scope blocked --initiative initiative-uuid --order-by due_date --order-dir asc
 
@@ -121,6 +131,7 @@ atoll issue view ATOLL-42   # alias kept for humans
 atoll issue create --title "Fix login bug" --status todo --priority 1
 atoll issue create --title "Plan rollout" --project project-slug --milestone "Launch"
 atoll issue create --title "Weekly status review" --due-date 2026-07-06 --recurrence weekly
+atoll issue create --title "MWF status review" --due-date 2026-07-06 --recurrence weekly --recurrence-days mon,wed,fri
 atoll issue upsert --match-title --project <project-id> --title "Fix login bug" --status todo
 atoll issue bulk-create --file ./issues.json --continue-on-error
 
@@ -148,6 +159,12 @@ atoll label list
 atoll label add ATOLL-42 bug
 atoll notification list --json
 atoll notification ack notification-uuid
+atoll inbox list --json
+atoll inbox view email-uuid --json
+atoll inbox triage email-uuid --category support --priority 1 --status action_required
+atoll inbox resolve email-uuid --note "Handled in ATOLL-123"
+# Draft only; this does not send:
+atoll inbox draft email-uuid --from support@atollhq.com --to user@example.com --subject "Re: Help" --body-file ./reply.txt
 atoll subtask create ATOLL-42 --title "Verify recurrence"
 atoll activity issue ATOLL-42
 
@@ -203,8 +220,10 @@ CLI JSON conventions:
 - Project-scoped `atoll issue list --json` includes `project_context`; `atoll issue get/view --json` includes `status_column` plus `project_context` when available.
 - For initiative execution context via API, `GET /api/orgs/{id}/initiatives/{initiativeId}/issues?details=1` returns accessible task details from linked projects, direct issue links, and linked milestones.
 - Diagnostics and errors go to stderr.
+- Machine-readable JSON preserves API strings exactly; human terminal output removes ANSI/VT, control, and bidirectional formatting characters from API-supplied strings.
 - Interactive CLI update notices also go to stderr and are suppressed for JSON/non-TTY/CI/completion flows.
 - `atoll agent-context` returns a versioned command/flag manifest, available profile context, and structured `cli.update_available` metadata.
+- Weekly issue recurrence accepts unique selected weekdays with `--recurrence weekly --recurrence-days mon,wed,fri`. Read JSON exposes normalized `recurrence_days` and `recurrence_schedule`; unrelated updates preserve the schedule.
 - `atoll heartbeat --json` includes the same structured `cli` update metadata for agents, plus `attention_items`, `attention_summary`, and `recommended_action` when Atoll can propose one concrete strategy-backed next action. `atoll heartbeat --signals-only --json` preserves filtered `signals`, `attention_items`, `attention_summary`, and `recommended_action` for short polling. Handle direct attention items first, then call each handled item's `ack_endpoint`. 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, and avoid copying deferred busywork into issue or comment payloads. If a `start_work` recommendation uses `issue.update` with a body, update the issue status and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 - `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`.
 
@@ -212,7 +231,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` 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 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.
+Organization-wide non-guest agents may create draft syncs and validate proposed configs for KPIs they can read, but only after a human admin has allowlisted the exact destination host in Atoll. Guest and project-scoped agents cannot use the KPI or nested sync routes. 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> \
@@ -238,7 +257,11 @@ npm install -g @atollhq/mcp-server
 PORT=8787 atoll-mcp
 ```
 
-Remote MCP clients call `POST /mcp` with Streamable HTTP and should send `Authorization: Bearer sk_atoll_...` per request. Single-tenant deployments can set `ATOLL_API_KEY` and `ATOLL_ORG_ID` as environment variables.
+HTTP mode binds to `127.0.0.1` by default. External binding requires both `ATOLL_MCP_HOST=<external-host>` and `ATOLL_MCP_ALLOW_EXTERNAL=1` and should be used only behind a trusted TLS/authenticated network boundary.
+
+Remote MCP clients call `POST /mcp` with Streamable HTTP and must send `Authorization: Bearer sk_atoll_...` per request. HTTP requests never fall back to a process-level `ATOLL_API_KEY`; that fallback is available only in explicit `--stdio` mode. HTTP deployments may set `ATOLL_ORG_ID` and `ATOLL_BASE_URL` as defaults.
+
+The server validates each HTTP bearer token through `/api/auth/me` before MCP dispatch and rejects request bodies over 1 MiB, including chunked requests.
 
 The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints. `atoll_add_comment` accepts structured mentions, `reply_to_comment_id`, and explicit agent `source_metadata`; it does not infer harness thread IDs. `atoll_update_issue` accepts `comment_body` for durable progress comments.
 
@@ -258,7 +281,7 @@ atoll issue list --json --limit 10
 
 If the user is setting up Atoll in another AI tool, give them a copyable prompt. Keep secrets out of chat: tell the user to run auth commands locally and never ask them to paste `sk_atoll_...` keys into a model conversation unless they explicitly choose that risk.
 
-If the user is in Atoll's first-run setup wizard, the key may be setup-scoped. In that mode, inspect the repo or interview the user, then create or revise the setup proposal only. Do not try to create projects, goals, KPIs, initiatives, or issues directly, and do not approve/apply the proposal. The human reviews the editable proposal in Atoll and approves it there.
+If the user is in Atoll's first-run setup wizard, the key may be setup-scoped. In that mode, inspect the repo or interview the user, then create or revise the setup proposal only. Do not try to create projects, goals, KPIs, initiatives, or issues directly, and do not approve/apply the proposal. The human reviews the editable proposal in Atoll and approves it there. Treat the setup key as temporary: it expires after 24 hours and Atoll revokes it when setup is applied, skipped, or failed. Continued use requires a separately minted ordinary key.
 
 ### Prompt: Create the First Board
 
@@ -345,12 +368,14 @@ 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.
+- **Recommended action**: one deterministic strategy-backed next action when Atoll has enough evidence (`create_work`, `start_work`, `escalate_blocker`, `refresh_metric`, or `investigate`), including why-now, expected impact, first step, success criteria, quality warnings, and any suggested write. An investigation can use `suggested_write.operation: "none"` when heartbeat lacks enough detail for a safe write.
+
+Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an `issue_stale` signal on the issue or a `milestone_overdue` signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned 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. 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`.
 
@@ -409,13 +434,33 @@ atoll kpi snapshot add paying_customers --value 42 --initiative "Content pipelin
 atoll kpi snapshot list paying_customers --include-attribution --json
 ```
 
-Project-scoped agent profiles apply their default project to `atoll initiative list` and `atoll initiative create`. Use `--project <id-or-slug>` to override that project, or `--org-wide` to intentionally suppress the default project. API callers can pass `project_id` or `projectId` on create, and `?project_id=...` on list; guest/project-scoped callers must use a project they can access, and create requires edit/admin project access.
+Project-scoped agent profiles apply their default project to `atoll initiative list` and `atoll initiative create`. Use `--project <id-or-slug>` to override that project, or `--org-wide` to intentionally suppress the default project. API callers can pass `project_id` or `projectId` on create, and `?project_id=...` on list; guest/project-scoped callers must use a project they can access, and create requires edit/admin project access. Projectless organization-wide initiative creation requires an organization owner/admin.
+
+Project-linked initiative reads require access to at least one linked project.
+The authoritative set includes explicit project links and projects inferred
+from direct issue/milestone links. Updating an initiative or mutating its issue,
+milestone, or target links requires edit/admin access to every linked project;
+a requested issue or milestone project must already be linked when it is
+project-bound. Eligible non-guests may link and unlink writable projectless
+issues; projectless milestones are unsupported. KPI-impact reads omit
+unreadable KPIs and KPI-impact writes require owner/admin Strategy access.
+Projectless initiative writes require an organization owner/admin.
+Treat `404` as concealed absence or unreadable scope and `403` as insufficient
+write access to a readable initiative.
+
+KPIs are organization-wide Strategy resources. Owners/admins may read and
+write; other non-guest organization members may read values, snapshots, and
+redacted per-KPI sync metadata but cannot create, update, delete, or record
+snapshots. Guest/project-scoped agents receive `403` for the collection and
+concealed `404` responses for direct KPI, snapshot, and per-KPI sync
+read/draft routes. Verify the active profile's organization-wide role before
+running KPI commands.
 
 Every KPI snapshot can be attributed to an initiative or issue, building a record of *what actually moved the numbers*. Keep KPI-to-initiative impact links separate from snapshot attribution: an initiative link means the initiative is expected to move the KPI, while snapshot attribution records the source of one measurement. Heartbeat reports one canonical status per KPI and can explain a KPI with `atoll heartbeat --explain-kpi <kpi> --json`.
 
 ### Audit and improve the strategy
 
-Use the audit to review the whole strategy chain at a high level and fix structural problems — the common one being initiatives created without a goal.
+Use the audit to review the strategy chain visible to the caller at a high level and fix structural problems — the common one being initiatives created without a goal.
 
 ```bash
 atoll strategy audit            # human-readable, grouped by severity
@@ -424,6 +469,12 @@ atoll strategy audit --json     # findings[] for programmatic remediation
 
 `GET /api/orgs/{id}/strategy/audit` returns `findings[]` (each with a `type`, `severity`, the relevant entity id, and a concrete `suggested_fix`) plus `summary` counts. It diagnoses; you remediate with the normal write endpoints. Typical loop:
 
+The audit follows the caller's project access. Owners/admins receive
+organization-wide execution evidence. Other non-guests receive project-bound
+issues, milestones, target links, and target findings only for readable
+projects. A restricted caller with no readable projects receives no issue or
+target execution evidence. Guests cannot run the audit.
+
 1. `atoll strategy audit --json` to get findings.
 2. For each finding, apply its `suggested_fix`, e.g.:
    - `initiative_orphaned` → `atoll initiative update "<initiative>" --goal "<goal>"` (or `PATCH .../initiatives/{id} { goal_id }`)
@@ -439,6 +490,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.
@@ -446,9 +507,11 @@ This is the structural-health lens (is the strategy well-formed?), complementary
 Webhook creation returns a raw `whsec_...` secret once. Delivery requests include:
 
 - `X-Atoll-Signature`: `sha256=` plus an HMAC-SHA256 over the raw body, keyed by the SHA-256 hex digest of the raw secret.
+- `X-Atoll-Signature-Version`: the primary signing-key version.
+- `X-Atoll-Signatures`: versioned signatures during a bounded key-overlap window.
 - `X-Atoll-Delivery-Id`: stable delivery id for receiver-side deduplication.
 
-Delivery rows expose `delivery_id`, `status`, and `next_retry_at`. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
+Webhook administration is owner/admin only. Lists return an origin-only `destination_display`; paths, queries, and signing material are never returned. Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery rows expose safe `delivery_id`, `status`, `status_code`, `error_code`, and retry timing, but not payloads, receiver response bodies, or raw errors. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
 
 ### Billing and plan limits
 
@@ -474,6 +537,7 @@ Full endpoint tables and field schemas:
 | Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` optional; required for guests) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
 | Milestones | POST `.../milestones` | GET `.../milestones` | PATCH `.../milestones/{id}` | DELETE `.../milestones/{id}` |
 | Comments | POST `.../comments` with `{ body, mentions?, reply_to_comment_id?, source_metadata? }` | GET `.../comments` or `.../comments/{id}` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
+| Attachments | POST `.../attachments` | GET `.../attachments` or `.../attachments/{id}/content` | — | DELETE `.../attachments/{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`.
@@ -482,6 +546,29 @@ All endpoints are under `/api/orgs/{orgId}/...`.
 
 Issue comments inherit issue project permissions: listing comments requires access to the issue's project, comment writes (add, edit, delete) require write access to that project, edit/delete still require comment authorship, and guests cannot access comments on unprojected issues.
 
+Project-bound milestone, status-update, board-column, issue-activity, and PR-link
+reads require effective project access. Milestone create/update, status-update
+create, board-column mutations, and project-bound PR-link create require `edit`
+or `admin`; eligible non-guests may read issue activity and read or attach PR
+links for projectless issues. Milestone delete remains organization
+owner/admin-only. Issue activity is read-only. Organization activity and
+analytics are limited to the caller's accessible projects, with eligible
+non-guests also receiving projectless data; project-health contains accessible
+projects only. Do not treat org membership alone as project authorization.
+
+Issue templates follow the same effective-project boundary: project-template
+reads require project access and writes require `edit`/`admin`.
+Organization-wide templates are readable by non-guests and manageable only by
+organization owners/admins; guest/project-scoped agents never receive them.
+Avatar mutations require both caller and target to belong to the organization
+in the request path. Avatar pointer changes use compare-and-set semantics;
+concurrent changes return `409`, and successful mutations with durable Storage
+cleanup still queued return `202` with `cleanup_pending: true`. A conflict can
+also include `cleanup_pending: true` when cleanup of a staged or retired object
+remains queued. An authenticated 15-minute worker drains due jobs
+independently, with avatar requests providing an additional opportunistic
+sweep.
+
 Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stores and returns comment bodies as sanitized HTML. If sanitization leaves no visible text or safe media, the request returns `400` with `body is required` for direct comments or `comment_body is required` for issue updates with `comment_body`.
 
 Structured mentions are recommended for agents and integrations. Direct comment requests accept `mentions: [{ "member_id": "member-id" }]`; issue updates that create comments accept `comment_mentions: [{ "member_id": "member-id" }]`. `member_id` is the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML `atoll:member` links remain backward-compatible.
@@ -492,6 +579,12 @@ Agent-authored direct comments may include explicit `source_metadata` with `harn
 
 Responses that create comments include `mentions: { requested, created, skipped }`. Each `skipped[]` entry includes `member_id` and `reason`; reasons are `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, and `mentions_muted`.
 
+Issue attachments inherit the same issue permissions. Project-scoped reads require project access; upload and delete require `edit` or `admin`. Guests cannot access attachments on unprojected issues, while non-guests follow the org-level issue rule.
+
+Attachment metadata contains `id`, `filename`, `file_size`, `mime_type`, `uploaded_by`, `created_at`, and a relative `url`. Resolve `url` against the Atoll base URL and resend the bearer credential or browser session. It is an authenticated API path, not a public or transferable storage URL; clients that consumed the former absolute public URLs must migrate.
+
+Uploads use multipart field `file`, must be non-empty, and are limited to 10 MiB (`413` when exceeded). Declared images must be signature-valid PNG, JPEG, GIF, or WebP; SVG and other declared image types are rejected. Other files are accepted but forced to download as `application/octet-stream`.
+
 † `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

package/skill/references/api-endpoints.md

@@ -2,10 +2,16 @@
 
 Base URL: `https://atollhq.com`
 
-All endpoints require `Authorization: Bearer sk_atoll_...` header.
+Endpoints require `Authorization: Bearer sk_atoll_...` unless an endpoint
+explicitly documents a different server-to-server credential.
+
+Directly requested unreadable project-bound resources return `404` without
+disclosing whether they exist. A readable project or resource with insufficient
+write access returns `403`; collection reads may omit unreadable linked rows.
 
 ## Table of Contents
 
+- [Authentication](#authentication)
 - [Organizations](#organizations)
 - [Projects](#projects)
 - [Project Members](#project-members)
@@ -46,6 +52,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 |
@@ -54,20 +70,25 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 | POST | `/api/orgs` | Create an org (`{ name }`) |
 | GET | `/api/orgs/{id}` | Get org details |
 | PATCH | `/api/orgs/{id}` | Update org |
-| DELETE | `/api/orgs/{id}` | Delete org |
+| DELETE | `/api/orgs/{id}` | Delete org (owner only; durably queues attachment object cleanup) |
 
 ## Projects
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/projects` | List projects (visibility-filtered) |
-| POST | `/api/orgs/{id}/projects` | Create project (`{ name, description?, visibility?, color?, icon?, github_repo? }`) |
+| POST | `/api/orgs/{id}/projects` | Create project and default views atomically (`{ name, description?, visibility?, color?, icon?, github_repo? }`, owner/admin) |
 | GET | `/api/orgs/{id}/projects/{projectId}` | Get project with issues |
 | PATCH | `/api/orgs/{id}/projects/{projectId}` | Update project (`{ name?, description?, status?, visibility?, color?, icon? }`) |
 | DELETE | `/api/orgs/{id}/projects/{projectId}` | Permanently delete project and all tasks in it (owner/admin; body must include `{ "confirmation": "DELETE" }`) |
 
 Guest users only see projects they are assigned to.
 
+A successful project create also creates Backlog, Todo, In Progress, and Done
+columns; a Default board view containing those columns; and All Tasks, My
+Tasks, and Recently Updated custom views. If any default cannot be created, the
+transaction rolls back and no partial project remains.
+
 ## Project Members
 
 | Method | Endpoint | Description |
@@ -104,17 +125,23 @@ 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 }`) |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/initiatives/{initiativeId}` | Unlink task from initiative |
 
-Issue-centric initiative links follow task project permissions: reading links requires access to the task's project; linking and unlinking require edit/admin access to that project. Guest callers may link only to initiatives already linked to the same accessible project.
+Issue-centric initiative links follow both resource boundaries. The collection
+read requires access to the task, omits linked initiatives the caller cannot
+read, and returns `200`. For project-bound tasks, linking and unlinking require
+edit/admin access to the task project, which must already be linked to the
+initiative. Eligible non-guests may link or unlink writable projectless tasks.
+Every mutation also requires edit/admin access to every project linked to the
+initiative. Directly requested unreadable mutations are concealed as `404`.
 
 **List filters** (query params):
 - `status` -- `backlog`, `todo`, `in_progress`, `done`, `cancelled`
@@ -122,6 +149,7 @@ Issue-centric initiative links follow task project permissions: reading links re
 - `projectId`, `assigneeId`, `teamId`, `milestoneId`
 - `q` -- full issue lists search title and description (case-insensitive)
 - Compact views (`view=board` or `view=list`) also support `assignee` (member ID or `unassigned`, including multi-assignee links), `initiativeId`, `scope` (`mine` or `blocked`), and `q` over title plus issue number
+- `open` -- `true` excludes terminal statuses `done` and `cancelled`, plus archived tasks; custom and other non-terminal statuses remain included. Takes precedence over `includeArchived`.
 - `includeArchived` -- `true` to include archived tasks
 - `orderBy` -- `created_at` (default), `updated_at`, `priority`, `due_date`, `title`, `status`
 - `orderDir` -- `asc` or `desc` (default)
@@ -129,7 +157,7 @@ Issue-centric initiative links follow task project permissions: reading links re
 - `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`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`.
+**GET task detail** returns enriched data: `milestone`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`. Recurring tasks also return normalized `recurrence_days` and `recurrence_schedule`. Create, update, and bulk-create accept `recurrenceDays` only with `recurrenceType: "weekly"`; values must be unique weekdays from `mon` through `sun`.
 
 ## Dependencies
 
@@ -183,6 +211,8 @@ Responses that create comments include `mentions: { requested, created, skipped
 
 Roles: `owner`, `admin`, `member`, `guest`.
 
+Member `PATCH` and `DELETE` can return `409` when the actor's or target member's authorization changes before the atomic mutation commits. Refetch the member and current permissions before retrying, and retry only if the action remains authorized.
+
 ## Milestones
 
 | Method | Endpoint | Description |
@@ -193,6 +223,10 @@ Roles: `owner`, `admin`, `member`, `guest`.
 | PATCH | `/api/orgs/{id}/milestones/{milestoneId}` | Update milestone |
 | DELETE | `/api/orgs/{id}/milestones/{milestoneId}` | Delete milestone |
 
+Project-bound reads require effective project access. Create and update require
+`edit` or `admin` access. Unreadable milestones are concealed as `404`.
+Milestone deletion remains organization owner/admin-only.
+
 ## Goals
 
 | Method | Endpoint | Description |
@@ -207,20 +241,20 @@ Roles: `owner`, `admin`, `member`, `guest`.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/kpis` | List KPIs (optional `?goal_id=...`) |
-| POST | `/api/orgs/{id}/kpis` | Create KPI |
-| GET | `/api/orgs/{id}/kpis/{kpiId}` | Get KPI |
-| PATCH | `/api/orgs/{id}/kpis/{kpiId}` | Update KPI |
+| GET | `/api/orgs/{id}/kpis` | List KPIs (optional `?goal_id=...`); non-guest Strategy read access required |
+| POST | `/api/orgs/{id}/kpis` | Create KPI; owner/admin Strategy write access required |
+| GET | `/api/orgs/{id}/kpis/{kpiId}` | Get KPI; non-guest Strategy read access required |
+| PATCH | `/api/orgs/{id}/kpis/{kpiId}` | Update KPI; owner/admin Strategy write access required |
 | DELETE | `/api/orgs/{id}/kpis/{kpiId}` | Delete KPI (admin/owner only) |
-| GET | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | List snapshots (optional `?limit=50`) |
-| POST | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | Record a snapshot |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | List snapshots (optional `?limit=50`); non-guest Strategy read access required |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | Record a snapshot; owner/admin Strategy write access required |
 | 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 |
-| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Get a KPI HTTP sync |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | List KPI HTTP syncs; readable KPI required |
+| POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Create a draft KPI HTTP sync; readable KPI required |
+| PUT | `/api/orgs/{id}/kpis/{kpiId}/http-syncs` | Validate a proposed KPI HTTP sync config without storing or running it; readable KPI required |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Get a KPI HTTP sync; readable KPI required |
 | PATCH | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}` | Update a KPI HTTP sync draft (human admin only) |
 | POST | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/validate` | Validate a stored sync (human admin only) |
 | GET | `/api/orgs/{id}/kpis/{kpiId}/http-syncs/{syncId}/secrets` | List sanitized secret metadata (human admin only) |
@@ -243,15 +277,28 @@ 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`.
+Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`,
+`ownerId`, and `targetDate`. Projectless creation requires an organization
+owner/admin.
+
+Project-linked initiative collections, project-bound enrichment, and
+issue/milestone/target links are filtered to projects the caller can read.
+Authoritative scope includes explicit project links plus projects inferred from
+direct issue and milestone links. A read is allowed when at least one linked
+project is readable, but write operations require edit/admin access to every
+project linked to the initiative. Projectless initiatives are readable by
+non-guest organization members and writable only by owners/admins. KPI-impact
+reads omit unreadable KPIs; KPI-impact writes additionally require owner/admin
+Strategy access. Unreadable directly requested resources return `404`; readable
+resources without sufficient write access return `403`.
 
 ## Initiative Links
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `.../initiatives/{id}/kpi-impacts` | List KPI impact links |
-| POST | `.../initiatives/{id}/kpi-impacts` | Add (`{ kpi_id, expected_impact? }`) |
-| DELETE | `.../initiatives/{id}/kpi-impacts/{impactId}` | Remove link |
+| GET | `.../initiatives/{id}/kpi-impacts` | List KPI impact links whose KPIs are readable |
+| POST | `.../initiatives/{id}/kpi-impacts` | Add (`{ kpi_id, expected_impact? }`); owner/admin KPI Strategy write access required |
+| DELETE | `.../initiatives/{id}/kpi-impacts/{impactId}` | Remove link; owner/admin KPI Strategy write access required |
 | GET | `.../initiatives/{id}/issues` | List linked issue links; add `?details=1` for accessible task details from linked projects, direct issue links, and linked milestones |
 | POST | `.../initiatives/{id}/issues` | Link issue (`{ issue_id }`) |
 | DELETE | `.../initiatives/{id}/issues/{issueId}` | Unlink issue |
@@ -263,12 +310,12 @@ Create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `owner
 | GET | `.../initiatives/{id}/targets/{targetId}` | Get target |
 | PATCH | `.../initiatives/{id}/targets/{targetId}` | Update target |
 | DELETE | `.../initiatives/{id}/targets/{targetId}` | Delete target |
-| GET | `.../initiatives/{id}/targets/{targetId}/issues` | List target issue links |
-| POST | `.../initiatives/{id}/targets/{targetId}/issues` | Link issue to target (`{ issue_id }`) |
-| DELETE | `.../initiatives/{id}/targets/{targetId}/issues/{issueId}` | Unlink issue from target |
-| GET | `.../initiatives/{id}/targets/{targetId}/milestones` | List target milestone links |
-| POST | `.../initiatives/{id}/targets/{targetId}/milestones` | Link milestone to target (`{ milestone_id }`) |
-| DELETE | `.../initiatives/{id}/targets/{targetId}/milestones/{milestoneId}` | Unlink milestone from target |
+| GET | `.../initiatives/{id}/targets/{targetId}/issues` | List readable target issue links, including readable projectless issues for non-guests |
+| POST | `.../initiatives/{id}/targets/{targetId}/issues` | Link issue to target (`{ issue_id }`); a project-bound issue's project must already be linked to the initiative, while eligible non-guests may link writable projectless issues |
+| DELETE | `.../initiatives/{id}/targets/{targetId}/issues/{issueId}` | Unlink issue from target; a project-bound issue's project must already be linked to the initiative, while eligible non-guests may unlink writable projectless issues |
+| GET | `.../initiatives/{id}/targets/{targetId}/milestones` | List readable project-bound target milestone links; projectless milestones are unsupported |
+| POST | `.../initiatives/{id}/targets/{targetId}/milestones` | Link milestone to target (`{ milestone_id }`); its project must already be linked to the initiative, and projectless milestones are unsupported |
+| DELETE | `.../initiatives/{id}/targets/{targetId}/milestones/{milestoneId}` | Unlink milestone from target; its project must already be linked to the initiative, and projectless milestones are unsupported |
 
 Targets are initiative-level commitments. Use `mode: "progress"` for normal output tracking and `mode: "gate"` for launch blockers or prerequisites where KPI pace language would be misleading. Targets do not create KPI snapshots.
 
@@ -278,7 +325,7 @@ Targets are initiative-level commitments. Use `mode: "progress"` for normal outp
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/strategy/audit` | Audit the strategy chain for structural gaps + health issues, each with a suggested fix |
 
-Returns findings only (not the full graph). Use it for a high-level review — orphaned initiatives/KPIs (no goal), goals with no KPI or no initiative, dangling initiative execution links, KPIs missing targets/stale/off-pace, initiatives missing impact/execution or stalled, blocked/overdue work — then remediate with the goal/KPI/initiative write endpoints above. Forbidden for guests. CLI: `atoll strategy audit [--severity critical|warning|info] [--json]`.
+Returns findings only (not the full graph). Use it for a high-level review — orphaned initiatives/KPIs (no goal), goals with no KPI or no initiative, dangling initiative execution links, KPIs missing targets/stale/off-pace, initiatives missing impact/execution or stalled, blocked/overdue work — then remediate with the goal/KPI/initiative write endpoints above. Owners/admins receive organization-wide execution evidence. Other non-guests receive project-bound issues, milestones, target links, and target findings only for readable projects. A restricted member with no readable projects receives no issue or target execution evidence. Forbidden for guests. CLI: `atoll strategy audit [--severity critical|warning|info] [--json]`.
 
 ## Heartbeat
 
@@ -286,7 +333,9 @@ 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.
+
+Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an `issue_stale` signal on the issue or a `milestone_overdue` signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work.
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -311,6 +360,10 @@ KPI stale/off-pace signal metadata includes `linked_initiatives` and `recent_att
 
 Filters: `by_me` = your actions; `mine` = activity on issues assigned to you.
 
+Organization activity is limited to accessible projects; eligible non-guests may
+also receive projectless activity. Project-bound issue activity requires project
+access; eligible non-guests may also read projectless issue activity.
+
 ## Teams
 
 | Method | Endpoint | Description |
@@ -340,11 +393,18 @@ Custom statuses per project. Each column defines a valid status value and may in
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/projects/{projectId}/board-columns` | List columns (ordered by position) |
 | GET | `/api/orgs/{id}/projects/{projectId}/board-context` | Get board milestone and initiative focus context |
-| POST | `/api/orgs/{id}/projects/{projectId}/board-columns` | Create column (`{ key, label, description?, color?, position? }`) |
-| PATCH | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Update column (`{ label?, description?, color?, position? }`) |
-| DELETE | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Delete column (requires `reassignTo` in body) |
+| POST | `/api/orgs/{id}/projects/{projectId}/board-columns` | Append column (`{ key, label, description?, color? }`) |
+| PATCH | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Update column (`{ label?, description?, color? }`) |
+| DELETE | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Delete column (`?reassignTo={columnId}` is required when the source contains issues) |
 | PUT | `/api/orgs/{id}/projects/{projectId}/board-columns/reorder` | Bulk reorder (`{ columns: [{id, position}] }`) |
 
+Reads require effective project access; mutations require `edit` or `admin`.
+Delete-with-reassignment and reorder are atomic, the final column cannot be
+deleted, reorder requires the complete current column set, and cross-project
+targets, duplicate positions, and negative or non-integer positions are
+rejected. Creation appends; direct `position` changes on create or patch are
+rejected.
+
 ## Board Views
 
 | Method | Endpoint | Description |
@@ -372,14 +432,41 @@ Custom statuses per project. Each column defines a valid status value and may in
 | PATCH | `/api/orgs/{id}/templates/{templateId}` | Update template |
 | DELETE | `/api/orgs/{id}/templates/{templateId}` | Delete template |
 
+Project-template reads require effective project access; create/update/delete
+require `edit` or `admin`. Organization-wide templates are readable by
+non-guests and manageable only by organization owners/admins. Guests and
+project-scoped agents never receive organization-wide templates. Unreadable or
+cross-organization IDs return `404`; readable view-only projects return `403`
+for writes.
+
 ## Attachments
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/issues/{issueId}/attachments` | List private attachments with signed URLs (`url_expires_in: 3600`) |
-| POST | `/api/orgs/{id}/issues/{issueId}/attachments` | Upload private file (multipart, `file` field, max 10MB) |
-| GET | `/api/orgs/{id}/issues/{issueId}/attachments/{attachmentId}` | Redirect authorized requests to a fresh signed URL |
-| DELETE | `/api/orgs/{id}/issues/{issueId}/attachments/{attachmentId}` | Delete private attachment |
+| GET | `/api/orgs/{id}/issues/{issueId}/attachments` | List metadata with authenticated content URLs |
+| POST | `/api/orgs/{id}/issues/{issueId}/attachments` | Upload non-empty file (multipart `file`, max 10 MiB) |
+| GET | `/api/orgs/{id}/issues/{issueId}/attachments/{attachmentId}/content` | Read private content |
+| DELETE | `/api/orgs/{id}/issues/{issueId}/attachments/{attachmentId}` | Delete attachment |
+
+Attachment `url` values are stable authenticated API paths, not public storage
+URLs. Resolve them against the Atoll base URL and resend the bearer/session
+credential; do not expect storage fields or cache/share the URL as public.
+Project-scoped reads require project access and writes require edit/admin.
+Guests cannot access unprojected issue attachments; non-guests follow the
+org-level issue rule. Empty files return `400` and files over 10 MiB return
+`413`. PNG, JPEG, GIF, and WebP are signature-checked and served inline; other
+declared images are rejected, while non-image files are forced to download.
+Upload durably prepares exact reconciliation before Storage, activates it after
+upload, and only then attempts the row. Unverified outcomes remain queued.
+Cleanup is tombstoned under the same object lock as creation before removal.
+User deletion retires surviving create work atomically; tombstone expiry makes
+one final idempotent Storage removal.
+Direct attachment deletion and permanent issue, project, or organization
+deletion commit the attachment-row or parent cascade first and atomically queue
+both transitional and private bucket paths for cleanup. A service-authenticated
+worker processes bounded due jobs every 15 minutes and retries failures. Direct
+deletion returns `202` with `"cleanup_pending": true` when immediate cleanup is
+deferred; parent deletion returns after durable queueing.
 
 ## Profile Images
 
@@ -388,6 +475,18 @@ Custom statuses per project. Each column defines a valid status value and may in
 | POST | `/api/orgs/{id}/members/{memberId}/avatar` | Upload avatar to public `avatars` bucket (multipart, max 2MB, JPEG/PNG/WebP/GIF) |
 | DELETE | `/api/orgs/{id}/members/{memberId}/avatar` | Remove avatar |
 
+Members may manage their own avatar; organization owners/admins may manage
+another member only inside the same path organization. Cross-organization
+caller or target IDs return `404`. Upload returns
+`{ "member": { "id": "...", "avatar_url": "..." } }` with no other member
+metadata. Avatar updates use compare-and-set semantics: concurrent changes
+return `409`, while a successful mutation with durable Storage cleanup still
+queued returns `202` and includes `"cleanup_pending": true`. A conflict body is
+`{ "error": "Avatar changed concurrently" }` and may add
+`"cleanup_pending": true` only for queued staged or retired object cleanup.
+An authenticated 15-minute worker drains due jobs independently, while avatar
+requests also sweep a small due batch. Uploads over 2MB return `413`.
+
 ## PR Links
 
 | Method | Endpoint | Description |
@@ -397,6 +496,11 @@ Custom statuses per project. Each column defines a valid status value and may in
 
 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`. On attach, Atoll refreshes GitHub metadata when available so title/status/head SHA reflect the PR instead of only the submitted URL. PR links can also be created or refreshed automatically via the GitHub webhook integration.
 
+For project-bound issues, listing requires project access and attaching requires
+`edit` or `admin` access. Eligible non-guests may list and attach links for
+projectless issues. Authorization is bound to the issue's current parent before
+child reads or writes and occurs before URL parsing or GitHub metadata lookup.
+
 ## Project Status Updates
 
 | Method | Endpoint | Description |
@@ -406,19 +510,32 @@ Attach PRs manually with a canonical GitHub pull request URL such as `https://gi
 
 Status values: `on_track`, `at_risk`, `off_track`.
 
+Reads require effective project access; creation requires `edit` or `admin`.
+
 ## Project Health
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/project-health` | Latest health status per project |
 
+Only accessible projects are returned. Empty project scope returns empty health.
+
 ## Analytics
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/analytics?from=...&to=...` | Get analytics data |
 
-Required: `from`, `to` (dates). Optional: `projectId`, `teamId`.
+Required: `from`, `to`. Each must be either a calendar-valid `YYYY-MM-DD` date
+or a timezone-qualified RFC 3339 timestamp (`Z` or an explicit UTC offset).
+The ordered range may span no more than 366 days; partial dates,
+timezone-less timestamps, normalized invalid dates, reversed ranges, and
+longer ranges return `400`.
+Optional: `projectId`, `teamId`.
+
+All aggregates are limited to accessible projects; eligible non-guests may also
+receive projectless work. An inaccessible explicit `projectId` is concealed as
+`404`; empty guest scope returns empty aggregates.
 
 ## Automation Rules
 
@@ -438,14 +555,36 @@ Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issu
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/webhooks?orgId=...` | List webhooks |
+| GET | `/api/webhooks?orgId=...` | List redacted webhooks (owner/admin) |
 | POST | `/api/webhooks?orgId=...` | Create webhook (owner/admin) |
 | DELETE | `/api/webhooks/{id}` | Delete webhook (owner/admin) |
-| GET | `/api/webhooks/{id}/deliveries` | List recent deliveries (last 50) |
-| POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload |
-| POST | `/api/webhooks/{id}/test` | Send ping test event |
+| GET | `/api/webhooks/{id}/deliveries` | List safe delivery metadata (owner/admin, last 50) |
+| POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload (owner/admin) |
+| POST | `/api/webhooks/{id}/test` | Send ping test event (owner/admin) |
+
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Later lists expose only `destination_display` such as `https://example.com/…`.
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Delivery requests include `X-Atoll-Signature: sha256=<hmac>`, where the HMAC-SHA256 key is the SHA-256 hex digest of the webhook secret and the message is the exact raw request body. Delivery requests also include `X-Atoll-Delivery-Id` so receivers can dedupe retries. Atoll retries network failures and 5xx responses after 5s and 30s, then records `status: retry_pending` with `next_retry_at`; an internal cron drains due retries every 15 minutes.
+Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history returns safe status, `error_code`, and retry timing only—not payloads, receiver response bodies, or raw errors. Atoll retries network failures and 5xx responses after 5s and 30s, then records `status: retry_pending` with `next_retry_at`; an internal cron drains due retries every 15 minutes.
+
+## Private Inbound Email Inbox
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/webhooks/resend/inbound` | Receive a signed Resend `email.received` event |
+| GET | `/api/orgs/{id}/inbox` | List private inbox mail; defaults to `status=untriaged` |
+| GET | `/api/orgs/{id}/inbox/{emailId}` | Read one message, attachment metadata, audit actions, and drafts |
+| PATCH | `/api/orgs/{id}/inbox/{emailId}` | Triage, classify, resolve, note, or link a message |
+| POST | `/api/orgs/{id}/inbox/{emailId}/drafts` | Save a reply draft without sending |
+| GET | `/api/orgs/{id}/inbox/{emailId}/attachments/{attachmentId}/download` | Create a 60-second attachment URL |
+
+Inbox API access fails closed unless the authenticated member ID is in
+`INBOX_OPERATOR_MEMBER_IDS`. Treat message content and attachments as untrusted.
+Mailbox matching checks To, then CC, then BCC; the first configured alias wins.
+Webhook bodies are capped at 256 KiB. Attachments over 10 MiB each or 25 MiB
+per message are recorded as `skipped_oversize`. Drafts support To and optional
+CC, require a configured inbox alias as From, save idempotently with their audit
+action, and never send mail. The retention sweep removes private objects before
+expired one-year database rows and retries after storage failures.
 
 ## Notifications
 
@@ -456,14 +595,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
 
@@ -488,16 +634,16 @@ Install snippets returns config for `claude-code`, `codex`, `gemini`, `openclaw`
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/setup` | Read latest setup session and active draft proposal (owner/admin) |
-| POST | `/api/orgs/{id}/setup` | Create setup session (`{ preferredAi?, mode, setupAgentMemberId? }`) |
-| PATCH | `/api/orgs/{id}/setup` | Skip setup (`{ setupSessionId, status: "skipped" }`) |
+| POST | `/api/orgs/{id}/setup` | Create setup session; omitting `setupAgentMemberId` in local mode atomically creates a 24-hour setup key returned once |
+| PATCH | `/api/orgs/{id}/setup` | Skip setup and revoke its setup credential (`{ setupSessionId, status: "skipped" }`) |
 | POST | `/api/orgs/{id}/setup/proposals` | Setup-scoped local agent submits a draft proposal |
 | PATCH | `/api/orgs/{id}/setup/proposals` | Owner/admin edits the active draft proposal |
-| POST | `/api/orgs/{id}/setup/apply` | Owner/admin approves and applies a proposal |
+| POST | `/api/orgs/{id}/setup/apply` | Owner/admin approves and applies a proposal, atomically revoking its setup credential |
 | POST | `/api/orgs/{id}/setup/chatkit/session` | Create ChatKit client session for a web-agent setup session |
 | POST | `/api/orgs/{id}/setup/chatkit/client-tool` | Browser-mediated ChatKit client tool endpoint for proposal submit/revise only |
 | POST | `/api/orgs/{id}/setup/chatkit/tools` | Optional server-to-server ChatKit tool endpoint for proposal submit/revise only |
 
-Setup-scoped agent keys can call setup proposal endpoints and auth validation, but not normal workspace mutation endpoints. Human approval applies proposals and promotes the setup key by clearing its setup scope. The default web-agent flow uses ChatKit client tools handled in the browser and posted to `client-tool` with the user's web session. ChatKit tools cannot apply proposals.
+The default new-agent local path (without `setupAgentMemberId`) atomically creates the agent, session, and a setup-only key that expires after 24 hours and is returned once. The existing-agent path creates only the session and returns no key. Setup-scoped keys can call setup proposal endpoints and auth validation, but not normal workspace mutation endpoints. The local-agent prompt is transient and is not restored after refresh or navigation. Applying, skipping, or failing setup atomically revokes the setup key instead of promoting it; continued use requires a separately minted ordinary key. Generic key mint/rotate returns `409` while the agent has a nonterminal setup session or any unrevoked setup-scoped key, including an expired key, so manually revoking the setup key cannot bypass the setup boundary. The default web-agent flow uses ChatKit client tools handled in the browser and posted to `client-tool` with the user's web session. ChatKit tools cannot apply proposals. The server-to-server `/setup/chatkit/tools` endpoint is the bearer-auth exception: it requires `x-atoll-chatkit-tool-secret`.
 
 ## Integrations
 

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)
@@ -9,21 +10,69 @@
 - [Initiative Fields](#initiative-fields)
 - [Automation Rule Fields](#automation-rule-fields)
 - [Custom View Fields](#custom-view-fields)
+- [Board Column Mutation Fields](#board-column-mutation-fields)
 - [Board Context Response](#board-context-response)
 - [Webhook Fields](#webhook-fields)
+- [Private Inbox Fields](#private-inbox-fields)
 - [Setup Proposal Fields](#setup-proposal-fields)
 - [Heartbeat Response](#heartbeat-response)
 - [Analytics Response](#analytics-response)
 - [Plan Limit Errors](#plan-limit-errors)
 - [Agent Fields](#agent-fields)
+- [Avatar Upload Response](#avatar-upload-response)
 - [Enums](#enums)
 
 ---
 
+## 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.
 
+## Avatar Upload Response
+
+Successful `POST /api/orgs/{id}/members/{memberId}/avatar` requests return
+`200` with exactly:
+
+```json
+{
+  "member": {
+    "id": "member-uuid",
+    "avatar_url": "https://..."
+  }
+}
+```
+
+No other member, invitation, onboarding, or account metadata is included.
+When removal of a retired Storage object is durably queued, POST returns `202`
+with the same `member` projection plus `"cleanup_pending": true`; DELETE
+returns `{ "success": true, "cleanup_pending": true }`. Concurrent pointer
+changes return `{ "error": "Avatar changed concurrently" }` with `409` and may
+add `"cleanup_pending": true` when cleanup of a staged or retired object remains
+queued. An authenticated 15-minute worker drains due jobs independently, with
+avatar requests providing an additional opportunistic sweep. Uploads over 2MB
+return `413`.
+
 ```json
 {
   "title": "Fix login bug",
@@ -39,6 +88,7 @@ Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also
   "dueDate": "2026-04-01",
   "recurrenceType": "weekly",
   "recurrenceInterval": 1,
+  "recurrenceDays": ["mon", "wed", "fri"],
   "labelIds": ["label-uuid-1", "label-uuid-2"]
 }
 ```
@@ -47,7 +97,7 @@ Most fields work on both POST (create) and PATCH (update). `labelIds` is accepte
 
 - **Multiple assignees**: Use `assigneeIds` (array). Legacy `assigneeId` (single) still works. Responses include `assignees` array with `id`, `display_name`, `type`, `avatar_url`.
 - **Start date**: Sets when work begins. Combined with `dueDate`, defines the Gantt time span.
-- **Recurring tasks**: Set `recurrenceType` + optional `recurrenceInterval` (default 1). When marked `done`, a new instance is auto-created. Response includes `recurrence_next_date`.
+- **Recurring tasks**: Set `recurrenceType` + optional `recurrenceInterval` (default 1). Weekly series can set unique `recurrenceDays` values from `mon` through `sun`; Atoll sorts them into calendar order. When marked `done`, one next instance is auto-created in the same series. Responses include normalized `recurrence_days` and `recurrence_schedule: { type, interval, days }`.
 - **Archived tasks**: Have `archived_at` timestamp. Excluded by default; pass `includeArchived=true`.
 - **GET detail** returns enriched data: `milestone`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, `isBlocked`.
 
@@ -222,7 +272,7 @@ Targets attach to initiatives and track commitments separately from business KPI
 }
 ```
 
-Target work links use `{ "issue_id": "issue-uuid" }` at `.../targets/{targetId}/issues` and `{ "milestone_id": "milestone-uuid" }` at `.../targets/{targetId}/milestones`. Target response rows include linked `issueIds` and `milestoneIds` when returned by the target list/get endpoints.
+Target work links use `{ "issue_id": "issue-uuid" }` at `.../targets/{targetId}/issues` and `{ "milestone_id": "milestone-uuid" }` at `.../targets/{targetId}/milestones`. Target response rows include linked `issueIds` and `milestoneIds` when returned by the target list/get endpoints, filtered to resources readable through the caller's project access.
 
 ## Automation Rule Fields
 
@@ -254,6 +304,19 @@ Target work links use `{ "issue_id": "issue-uuid" }` at `.../targets/{targetId}/
 
 `display_mode`: `board`, `list`. `filters` and `sort` are freeform JSON.
 
+## Board Column Mutation Fields
+
+Delete a board column with
+`DELETE .../board-columns/{columnId}?reassignTo={targetColumnId}`. The target is
+required when the source column contains issues and must belong to the same
+project; reassignment and deletion are atomic.
+The final board column cannot be deleted. Reorder with
+`{ "columns": [{ "id": "column-uuid", "position": 0 }] }` and include the
+complete current column set. Duplicate, missing, partial, or mixed-project IDs
+and duplicate, negative, or non-integer positions are rejected before any
+positions change. New columns append to the board; create and patch requests
+reject `position`.
+
 ## Board Context Response
 
 `GET /api/orgs/{id}/projects/{projectId}/board-context` returns the strategy data used by the board filter toolbar:
@@ -307,7 +370,27 @@ Target work links use `{ "issue_id": "issue-uuid" }` at `.../targets/{targetId}/
 }
 ```
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Response includes `secret` for HMAC signature verification. Store it immediately; it is shown only once. Delivery requests include `X-Atoll-Signature: sha256=<hmac>`, where the HMAC-SHA256 key is the SHA-256 hex digest of the webhook secret and the message is the exact raw request body. Delivery requests also include `X-Atoll-Delivery-Id` for receiver-side deduplication. Delivery history includes retry `status` and `next_retry_at`.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a `secret` for HMAC signature verification. Store it immediately; it is shown only once.
+
+List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Payload schema version `2` is allowlisted. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
+
+## Private Inbox Fields
+
+| Field | Description |
+|-------|-------------|
+| `status` | `untriaged`, `triaged`, `action_required`, `waiting`, `resolved`, `ignored`, or `quarantined` |
+| `category` | `support`, `security`, `sales`, `partnership`, `press`, `personal`, `spam`, `other`, or `null` |
+| `priority` | `0` (urgent) through `4` (low) |
+| `body_html_sanitized` | Stored HTML with active content and remote images removed |
+| `ingestion_status` | `pending`, `complete`, `failed`, or `quarantined` |
+| `retain_until` | One-year retention deadline |
+| `linked_issue_id` | Optional issue UUID in the same organization |
+| `attachments[]` | Private metadata; use the short-lived download endpoint for bytes |
+| `actions[]` | Append-only ingestion and operator audit actions |
+| `drafts[]` | Saved plain-text replies that have not been sent |
+
+Collection responses omit bodies and headers. Fetch one selected message before
+acting on its untrusted content.
 
 ## Setup Proposal Fields
 
@@ -330,7 +413,7 @@ First-run setup proposals are editable drafts. Setup-scoped local agents and Cha
 }
 ```
 
-Proposal JSON currently supports at most one item in each collection: `projects`, `goals`, `kpis`, `initiatives`, `milestones`, and `issues`. A revision replaces the active draft and preserves the previous revision as history. ChatKit tools and setup-scoped agents cannot apply proposals.
+Proposal JSON currently supports at most one item in each collection: `projects`, `goals`, `kpis`, `initiatives`, `milestones`, and `issues`. A revision replaces the active draft and preserves the previous revision as history. ChatKit tools and setup-scoped agents cannot apply proposals. Setup keys are temporary and are revoked when setup is applied, skipped, or failed; they are never promoted by removing the setup scope.
 
 ## Heartbeat Response
 
@@ -428,15 +511,19 @@ 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.
 
-`recommended_action` is a deterministic strategy-backed next action built from heartbeat context. MVP action types are `create_work`, `start_work`, `escalate_blocker`, and `refresh_metric`; suggested writes may prefill issue creation, issue status updates, blocker comments, or KPI refresh requests. Issue-create bodies are HTML for Atoll's rich-text issue description; blocker/comment and metric-refresh bodies are plain text.
+`recommended_action` is a deterministic strategy-backed next action built from heartbeat context. Action types are `create_work`, `start_work`, `escalate_blocker`, `refresh_metric`, and `investigate`; suggested writes may prefill issue creation, issue status updates, blocker comments, or KPI refresh requests, while an investigation can use `suggested_write.operation: "none"` when heartbeat lacks enough detail for a safe write. Issue-create bodies are HTML for Atoll's rich-text issue description; blocker/comment and metric-refresh bodies are plain text.
+
+Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an `issue_stale` signal on the issue or a `milestone_overdue` signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work.
 
 ## Strategy Audit Response
 
@@ -497,7 +584,8 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Comment create response | `mentions.created` | Count of mention notifications created or confirmed by the request |
 | Comment create response | `mentions.skipped[]` | Mention targets that did not create notifications; each entry includes `member_id` and `reason` |
 | Comment create response | `mentions.skipped[].reason` | `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, or `mentions_muted` |
-| Task | `recurrenceType` | `daily`, `weekly`, `monthly`, `yearly` |
+| Task | `recurrenceType` | `daily`, `weekly`, `biweekly`, `monthly`, `custom` |
+| Weekly task | `recurrenceDays[]` | Unique `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` values |
 | Goal | `status` | `active`, `achieved`, `missed`, `paused`, `cancelled` |
 | KPI | `unit` | `count`, `percentage`, `currency`, `duration`, `ratio`, `custom` |
 | KPI | `target_direction` | `increase`, `decrease`, `maintain` |
@@ -515,9 +603,39 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Heartbeat signal | `severity` | `info`, `warning`, `critical` |
 | Custom view | `display_mode` | `board`, `list` |
 
+## Attachment
+
+Upload with multipart field `file`. The file must be non-empty and no larger
+than 10 MiB. Declared images must be signature-valid PNG, JPEG, GIF, or WebP;
+SVG and other declared image types are rejected.
+
+| Response field | Type | Notes |
+|---|---|---|
+| `id` | UUID | Attachment identifier |
+| `filename` | string | Original filename, limited to 255 Unicode characters |
+| `file_size` | integer | Size in bytes |
+| `mime_type` | string | Declared upload type |
+| `uploaded_by` | UUID or null | Uploading member |
+| `created_at` | timestamp | Creation time |
+| `url` | string | Relative authenticated content API path; resend auth when fetching |
+
+Storage bucket and path fields are intentionally not returned. Project-scoped
+reads require project access; upload and delete require `edit` or `admin`.
+Guests cannot access attachments on unprojected issues.
+
 ## Response Format
 
-All endpoints return JSON. Successful: `200` or `201`. Errors: `{ "error": "message" }` with `400`, `401`, `402`, `403`, `404`, `409`, or `500`.
+Most endpoints return JSON; attachment content returns binary bytes. Successful:
+`200`, `201`, or `202` when durable follow-up remains pending. Errors:
+`{ "error": "message" }` with `400`, `401`, `402`, `403`, `404`, `409`,
+`413`, or `500`.
+
+Issue-child endpoints, including activity, PR links, dependencies, subtasks,
+labels, and initiative links, return `404` for a missing, wrong-organization,
+wrong-parent, or unreadable directly requested issue. Readable issues with
+insufficient write access return `403`; collection reads can omit unreadable
+linked resources. Other endpoints may use `403` for organization-membership or
+role failures.
 
 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 }`.