@atollhq/skill-codex 0.4.22 → 0.4.24

package/skill/references/api-endpoints.md

@@ -14,6 +14,7 @@ write access returns `403`; collection reads may omit unreadable linked rows.
 ## Table of Contents
 
 - [Authentication](#authentication)
+- [Error and routing semantics](#error-and-routing-semantics)
 - [Organizations](#organizations)
 - [Projects](#projects)
 - [Project Members](#project-members)
@@ -25,6 +26,7 @@ write access returns `403`; collection reads may omit unreadable linked rows.
 - [Subtasks](#subtasks)
 - [Members](#members)
 - [Milestones](#milestones)
+- [Artifacts](#artifacts)
 - [Goals](#goals)
 - [KPIs](#kpis)
 - [Initiatives](#initiatives)
@@ -41,6 +43,7 @@ write access returns `403`; collection reads may omit unreadable linked rows.
 - [Attachments](#attachments)
 - [Profile Images](#profile-images)
 - [PR Links](#pr-links)
+- [External References](#external-references)
 - [Project Status Updates](#project-status-updates)
 - [Project Health](#project-health)
 - [Analytics](#analytics)
@@ -61,7 +64,7 @@ write access returns `403`; collection reads may omit unreadable linked rows.
 | GET | `/api/auth/me` | Resolve the caller's org role, key scopes, and live `projectAccess[]` grants |
 | POST | `/mcp` | Hosted MCP Streamable HTTP endpoint at `https://atollhq.com/mcp` |
 | GET | `/.well-known/oauth-protected-resource` | Public MCP protected-resource metadata |
-| GET | `/oauth/consent?authorization_id=...` | Human OAuth consent and multi-profile agent selection UI |
+| GET | `/oauth/consent?authorization_id=...` | Inert OAuth continuation page; profile selection or automatic client return starts only after explicit continuation |
 | POST | `/api/oauth/consent` | Approve or deny an OAuth request after explicitly selecting one or more agents |
 | GET | `/api/oauth/agent-profiles` | OAuth connection validation and currently usable profile summaries |
 | GET | `/api/oauth/connections` | List the signed-in human's OAuth connections and grants |
@@ -73,6 +76,15 @@ Project-scoped agents remain organization guests. Use `projectAccess[]` to
 inspect their effective `view`, `edit`, or `admin` access; membership changes
 do not require key rotation.
 
+## Error and routing semantics
+
+Missing authentication on a shared guarded API route returns `401` JSON with
+`{ "error": "Unauthorized", "code": "unauthorized" }`. Unknown `/api/*`
+paths return `404` JSON with `{ "error": "Not found", "code": "not_found" }`.
+Signed-out workspace-style page routes return a neutral real `404` that does
+not confirm whether a workspace exists; fixed protected routes retain their
+normal sign-in behavior.
+
 ## Organizations
 
 | Method | Endpoint | Description |
@@ -146,6 +158,17 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | 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 |
 
+When a task that blocks other work changes projects, include
+`dependencyReleaseMappings: [{ "dependencyId": "uuid", "releaseColumnId": "uuid" }]`
+for every blocking dependency. The destination columns must belong to the new
+project; projectless moves with blocking dependencies are rejected. REST also
+accepts top-level `dependency_release_mappings` and legacy
+`releaseColumnMappings`, plus item aliases `dependency_id` and
+`release_column_id`. MCP uses `dependency_release_mappings` with
+`dependency_id` and `release_column_id`; the CLI equivalent is
+`--dependency-release-mappings '<json-array>'` with camelCase items
+`dependencyId` and `releaseColumnId`.
+
 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
@@ -170,6 +193,19 @@ The existing `GET /api/orgs/{id}/issues/{issueId}` detail route accepts an autho
 - `offset` -- pagination offset
 - `shape=envelope` or `response_shape=cli` -- opt into CLI-compatible list responses: `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`
 
+Full issue-list items include the canonical project-prefixed `identifier` and
+collision-free `projectSlug` for project issues, or `null` for projectless
+issues. Compact board/list views do not include these fields.
+
+The MCP `atoll_list_issues` tool always returns the exact `{ resource, items,
+total, limit, offset, nextOffset, truncated, hint }` envelope. In the full
+profile it is in `structuredContent`; in the public plugin it is under
+`structuredContent.result.data`. Project-scoped calls may add `project_context`
+alongside the envelope. It accepts both legacy REST `{ issues, total, limit,
+offset }` and CLI-compatible REST `{ resource: "issues", items, ... }` upstream
+bodies, projects only declared public issue fields, preserves nullable
+`identifier` and `projectSlug`, and does not expose the CLI-derived `url` field.
+
 **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
@@ -178,9 +214,16 @@ The existing `GET /api/orgs/{id}/issues/{issueId}` detail route accepts an autho
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues/{issueId}/dependencies` | List dependencies (`{ blocking, blockedBy }`) |
 | POST | `/api/orgs/{id}/issues/{issueId}/dependencies` | Add dependency |
+| PATCH | `/api/orgs/{id}/issues/{issueId}/dependencies/{depId}` | Change dependency release point |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/dependencies/{depId}` | Remove dependency |
 
-Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`. Circular dependencies rejected (400). Duplicates return 409.
+Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`; snake_case aliases `{ "blocked_by_issue_id": "uuid" }` and `{ "blocking_issue_id": "uuid" }` are also accepted. The blocking issue must belong to a project; a projectless issue may be the blocked target. Optionally include `releaseColumnId` from the blocking project's board columns. Omit it to use the blocking project's `done` column. PATCH the dependency with `{ "releaseColumnId": "uuid" }`. Circular dependencies rejected (400). Duplicates return 409.
+
+Dependency reads include each authorized target issue's canonical `identifier` and `projectSlug` when it belongs to a project. Projectless targets have both fields `null`; inaccessible targets remain `issue: null`. Release fields include `releaseColumnId` and the compatibility alias `release_column_id`; POST and PATCH accept either camelCase or snake_case release-column input. Release metadata is present when the blocking issue is authorized; a `blocking` target projection may still be `issue: null` independently.
+The dependency-release migration backfills existing dependencies to the
+blocking project's `done` column. During a rolling deployment, compatibility
+reads may omit release fields from older rows; treat missing release metadata as
+the legacy open-blocker behavior until the migration is applied.
 
 ## Comments
 
@@ -202,6 +245,8 @@ List-comment responses include `comments[].mentioned_members`, an array of `{ id
 
 Replies use `reply_to_comment_id`. List/read responses include a `reply_to_comment` object containing the parent comment's routing-safe `source_metadata`. Agent-authored comments may submit explicit `source_metadata` with `harness`, `thread_id` and/or `session_id`, and optional `host_id`; unknown keys and human-authored provenance are rejected. Omit it unless a real thread or session ID exists, and never invent one. The issue-update comment path uses `comment_source_metadata`.
 
+Automation-authored comments return `author_type: "automation"` with null `author_id` and null comment routing `source_metadata`; their matching `comment.created` Activity is actorless and keeps automation provenance in metadata.
+
 Responses that create comments include `outcome.persistence` and `outcome.mentions`, with the legacy top-level `mentions` alias. `created` means a new notification row, `deduped` means an existing idempotent row, and `notification_rows.status: "failed"` reports notification setup failure without changing persisted comment state. `transport.dispatch: "scheduled"` is asynchronous Google Chat scheduling, not final delivery, including repair of a missing durable delivery row; `already_scheduled` means the durable delivery row already existed. `transport.final` stays null while any final delivery is unknown, and is `mixed` when all recipient deliveries are terminal but differ. Inspect each recipient outcome for mixed results. `transport.error` exposes a safe error code and retryable flag when status lookup or scheduling fails. Each skipped target includes `member_id` and `reason`.
 
 ## Subtasks
@@ -242,6 +287,32 @@ 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.
 
+## Artifacts
+
+The exact opt-in issue request
+`GET /api/orgs/{id}/issues/{issueId}?include=artifact_manifest` adds only PRD
+and Implementation Plan metadata. Default issue detail does not query or expose
+Artifacts.
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| `GET` | `/api/orgs/{id}/artifacts` | List readable artifact metadata and visible links; revision content is omitted; supports `limit` (1-100, default 50) and `offset` (0-10000), and returns `hasMore` |
+| `POST` | `/api/orgs/{id}/artifacts` | Create artifact and immutable revision 1 atomically |
+| `GET` | `/api/orgs/{id}/artifacts/{artifactId}` | Read artifact metadata and visible links |
+| `GET` | `/api/orgs/{id}/artifacts/{artifactId}/revisions` | List immutable revision summaries without content; supports `limit` (1-100, default 50) and `offset`, and returns `hasMore` |
+| `POST` | `/api/orgs/{id}/artifacts/{artifactId}/revisions` | Create a content revision or title-aware full snapshot with an expected current revision |
+| `GET` | `/api/orgs/{id}/artifacts/{artifactId}/revisions/{revisionId}` | Read one sanitized revision including content |
+| `POST` | `/api/orgs/{id}/artifacts/{artifactId}/links` | Link to an authorized issue or project |
+| `DELETE` | `/api/orgs/{id}/artifacts/{artifactId}/links/{linkId}` | Unlink atomically |
+
+Creation accepts `{ type, title, content, content_format?, links? }`. Types are
+`prd`, `implementation_plan`, `test_plan`, `decision`, `research`, and
+`release_checklist`. Content is normalized to safe HTML, titles are capped at
+200 UTF-8 bytes, and stored revisions at 256 KiB. Stale revision writes return
+`409`. Linked access follows the target; unlinked artifacts are for non-guest
+members and owners/admins have organization-wide access. Removing the final
+link requires owner or admin access.
+
 ## Goals
 
 | Method | Endpoint | Description |
@@ -261,7 +332,7 @@ Milestone deletion remains organization owner/admin-only.
 | GET | `/api/orgs/{id}/kpis/{kpiId}` | Get KPI with visible `initiative_impacts`; 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`); non-guest Strategy read access required |
+| GET | `/api/orgs/{id}/kpis/{kpiId}/snapshots` | List snapshots (optional `?limit=50`; `?projection=provenance_v1` adds nullable source-window dates); 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) |
@@ -303,9 +374,10 @@ 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`.
+reads omit unreadable KPIs; KPI-impact writes require write access to the
+initiative and read access to the same-org KPI, not KPI Strategy write access.
+Unreadable directly requested resources return `404`; readable resources
+without sufficient write access return `403`.
 
 Detail reads include read-only intended-impact projections. Initiative detail
 embeds `kpi_impacts` only for KPIs the caller may read. KPI detail embeds
@@ -318,8 +390,8 @@ attribution; mutate them only through the initiative KPI-impact link endpoints.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | 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 |
+| POST | `.../initiatives/{id}/kpi-impacts` | Add (`{ kpi_id, expected_impact? }`); initiative write access plus readable same-org KPI required |
+| DELETE | `.../initiatives/{id}/kpi-impacts/{impactId}` | Remove link; initiative write access plus readable same-org KPI 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 by UUID, number, `#number`, `ATOLL-number`, `TSK-number`, or unambiguous project-derived prefix (`{ issue_id }`) |
 | DELETE | `.../initiatives/{id}/issues/{issueId}` | Unlink issue |
@@ -388,9 +460,9 @@ KPI stale/off-pace signal metadata includes `linked_initiatives` and `recent_att
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/activity` | Org activity feed (`?limit=&offset=&filter=by_me\|mine`) |
-| GET | `/api/orgs/{id}/issues/{issueId}/activity` | Task activity feed |
+| GET | `/api/orgs/{id}/issues/{issueId}/activity?limit=50&offset=0` | Canonical task Activity history |
 
-Filters: `by_me` = your actions; `mine` = activity on issues assigned to you.
+Filters: `by_me` = your actions; `mine` = activity on issues assigned to or created by you.
 
 Organization activity is limited to accessible projects; eligible non-guests may
 also receive projectless activity. Project-bound issue activity requires project
@@ -423,16 +495,16 @@ Custom statuses per project. Each column defines a valid status value and may in
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/projects/{projectId}/board-columns` | Return `{ columns, accepted_statuses }`; columns are ordered by position and `cancelled` is a separate system status, not a column row |
+| GET | `/api/orgs/{id}/projects/{projectId}/board-columns` | Return `{ columns, accepted_statuses }`; columns are ordered by position and include nullable `recommendation_role`, `issue_count`, and `release_reference_count` impact counts |
 | GET | `/api/orgs/{id}/projects/{projectId}/board-context` | Get board milestone and initiative focus context |
-| 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) |
+| POST | `/api/orgs/{id}/projects/{projectId}/board-columns` | Append column (`{ key, label, description?, color?, recommendationRole? }`; `recommendation_role` is also accepted) |
+| PATCH | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Update column (`{ label?, description?, color?, recommendationRole? }`; `recommendation_role` is also accepted; both values must match when both aliases are present; use `null` to clear) |
+| DELETE | `/api/orgs/{id}/projects/{projectId}/board-columns/{columnId}` | Delete column; use independent `?reassignTo={columnId}&releaseReassignTo={columnId}` targets when issue or release references exist |
 | 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
+deleted, release references require an explicit independent target, 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.
@@ -533,6 +605,21 @@ For project-bound issues, listing requires project access and attaching requires
 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.
 
+## External References
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/orgs/{id}/issues/{issueId}/external-references` | List issue external references |
+| POST | `/api/orgs/{id}/issues/{issueId}/external-references` | Resolve and link a GitHub PR |
+| GET | `/api/orgs/{id}/issues/{issueId}/external-references/{referenceId}` | Inspect a linked reference |
+| DELETE | `/api/orgs/{id}/issues/{issueId}/external-references/{referenceId}` | Unlink a reference |
+| GET | `/api/orgs/{id}/projects/{projectId}/external-references` | List project external references |
+| POST | `/api/orgs/{id}/projects/{projectId}/external-references` | Resolve and link a GitHub PR |
+| GET | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Inspect a linked reference |
+| DELETE | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Unlink a reference |
+
+External Reference POST requests accept `{ "url": "https://github.com/owner/repo/pull/123" }`. They require an authorized GitHub connection and store a reference only when the live response proves numeric immutable repository and pull-request IDs. Missing proof returns `422` with `code: "github_identity_unavailable"`. URLs and caller owner/repo fields are not identity or authorization inputs. Existing PR-link operations remain independent; CLI/MCP tools are deferred to a later slice.
+
 ## Project Status Updates
 
 | Method | Endpoint | Description |
@@ -578,10 +665,15 @@ receive projectless work. An inaccessible explicit `projectId` is concealed as
 | GET | `/api/orgs/{id}/automation-rules/{ruleId}` | Get rule |
 | PUT | `/api/orgs/{id}/automation-rules/{ruleId}` | Update rule (owner/admin) |
 | DELETE | `/api/orgs/{id}/automation-rules/{ruleId}` | Delete rule (owner/admin) |
-| GET | `/api/orgs/{id}/automation-rules/{ruleId}/activity` | Rule execution history |
+| GET | `/api/orgs/{id}/automation-rules/{ruleId}/activity` | Rule execution history (owner/admin; latest 100 runs) |
 | POST | `/api/orgs/{id}/automation-rules/{ruleId}/test` | Dry-run test |
 
 Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`.
+Create and update requests reject unsupported action types or malformed action
+values before persistence. Activity returns safe durable run/action history;
+non-matches, dry runs, and rules without executable actions create no history,
+and action inputs, raw event payloads, credentials, headers, and response
+bodies are not returned.
 
 ## Webhooks
 
@@ -648,7 +740,8 @@ Google Chat mention cards include the task title, a safely formatted plain-text
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/agents` | List agents (owner/admin) |
-| GET | `/api/orgs/{id}/agents/manageable` | List manageable agents with visible project IDs, named accessible projects, and heartbeat policy status/focus summary |
+| GET | `/api/orgs/{id}/agents/workforce` | Read a bounded workforce projection; org owners/admins may list all agents, project admins must pass `?projectId=...`, and individual owners may read their own agents |
+| GET | `/api/orgs/{id}/agents/manageable` | List manageable agents with visible project IDs, named accessible projects, heartbeat policy status/focus summary, API-key usage metadata, and aggregate active-key/OAuth activity |
 | POST | `/api/orgs/{id}/agents` | Create org agent (`{ name, role?, setupScoped? }`), project-scoped agent (`{ name, projectIds }` or legacy `{ name, projectId, projectIds? }`), or personal agent (`{ name, personal: true }`); key-minting responses include one-time `apiKey` and stable `apiKeyId` (`oauthOnly` omits both) |
 | DELETE | `/api/orgs/{id}/agents/{agentId}` | Revoke manageable agent |
 | PATCH | `/api/orgs/{id}/agents/{agentId}/projects` | Replace project access for a manageable non-personal agent |
@@ -658,6 +751,11 @@ Google Chat mention cards include the task title, a safely formatted plain-text
 | DELETE | `/api/orgs/{id}/agents/{agentId}/keys/{keyId}` | Revoke key for a manageable agent |
 | POST | `/api/orgs/{id}/agents/{agentId}/rotate` | Rotate all keys for a manageable agent |
 | POST | `/api/orgs/{id}/agents/{agentId}/install-snippets` | Get install snippets for a manageable agent (`{ key, profileName?, projectId?, teamId?, baseUrl? }`) |
+| GET | `/api/orgs/{id}/runners/self` | Read the authenticated agent's runner installation and computed presence state |
+| PUT | `/api/orgs/{id}/runners/self` | Register or refresh the authenticated agent's runner installation |
+| DELETE | `/api/orgs/{id}/runners/self` | Disconnect the authenticated agent's current runner installation; idempotent |
+| POST | `/api/orgs/{id}/runner-leases/claim` | Atomically claim or safely replay a runner lease; untouched pre-intent replays can reissue a token |
+| PATCH | `/api/orgs/{id}/runner-leases/{leaseId}` | Apply a fenced lifecycle transition; paused or stale runners cannot mutate or replay |
 
 Install snippets returns config for `claude-code`, `codex`, `gemini`, `openclaw` (agent prompt), `openclaw-manual`, `hermes` (agent prompt), and `hermes-manual`. The server resolves the org slug and validates optional project/team IDs before generating snippets.
 
@@ -693,6 +791,9 @@ The default new-agent local path (without `setupAgentMemberId`) atomically creat
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/github-connections` | List GitHub connections (owner/admin) |
+| PATCH | `/api/orgs/{id}/github-connections/{connectionId}` | Update workflow verification mode, 1–10 paths of at most 255 characters each, or delivery agent (owner/admin) |
+| POST | `/api/orgs/{id}/github-connections/{connectionId}/reconcile` | Reconcile the signed GitHub hook and retry pending workflow evidence after current GitHub and PR-link readback (owner/admin) |
+| GET | `/api/orgs/{id}/github-connections/{connectionId}/workflow-runs` | List bounded workflow-run evidence (owner/admin; `limit` defaults to 25 and has a maximum of 100) |
 | GET | `/api/integrations/github/repos` | List available repos |
 | POST | `/api/integrations/github/connect` | Connect a repo |
 | POST | `/api/integrations/github/disconnect` | Disconnect a repo |

package/skill/references/api-fields.md

@@ -3,6 +3,7 @@
 ## Table of Contents
 
 - [Auth Context](#auth-context)
+- [Error Responses](#error-responses)
 - [OAuth Agent Profiles](#oauth-agent-profiles)
 - [Task Fields](#task-fields)
 - [Goal Fields](#goal-fields)
@@ -17,6 +18,7 @@
 - [Private Inbox Fields](#private-inbox-fields)
 - [Setup Proposal Fields](#setup-proposal-fields)
 - [Heartbeat Response](#heartbeat-response)
+- [Artifact Fields](#artifact-fields)
 - [Analytics Response](#analytics-response)
 - [Plan Limit Errors](#plan-limit-errors)
 - [Agent Fields](#agent-fields)
@@ -54,6 +56,50 @@ the selected agent connection:
 Project-scoped agents intentionally remain organization guests. Role and
 project-access changes are read live and do not require key rotation.
 
+## Error Responses
+
+Shared missing-auth failures return `401` JSON with `error: "Unauthorized"`
+and `code: "unauthorized"`. Unknown `/api/*` paths return `404` JSON with
+`error: "Not found"` and `code: "not_found"`. The `code` field is additive;
+other route-specific legacy errors may contain only `error`.
+
+## Local runner presence
+
+`GET`, `PUT`, and `DELETE /api/orgs/{id}/runners/self` are agent-only. The
+organization and agent member come from authentication. `PUT` accepts
+`instanceId`, optional `hostId` (the server-bound host routing identity), `platform` (`darwin`, `linux`, or `windows`), `arch` (`arm64`,
+`x64`, or `amd64`), `capabilities` (unique values from `codex` and `git`),
+`clientVersion` (numeric semantic version), and `intakeState` (`active` or
+`paused`). The server derives the display name. Responses include computed
+`presence_state`: `connected`, `stale` after 10 minutes, or `offline` after
+explicit disconnect. They contain no API keys, profile names, prompts,
+process IDs, or local/machine/worktree paths. Refreshes are limited to 60
+per authenticated agent per minute and return `429` with `Retry-After`. If the
+shared rate-limit check fails, the route fails closed with `503` and
+`code: "RATE_LIMIT_CHECK_FAILED"`. Rate-limit responses also include
+`code: "RATE_LIMITED"`, `retryAfterSeconds`, `limit`, and `currentCount`;
+recent-instance conflicts use `code: "RUNNER_INSTALLATION_CONFLICT"`.
+
+## Local runner leases
+
+`POST /api/orgs/{id}/runner-leases/claim` atomically claims an assigned,
+accessible, dependency-satisfied issue for the authenticated agent's current
+runner. The body accepts `issueId` and `idempotencyKey`; `attention_resume`
+also requires `attentionItemId`, `runnerHostId` (maximum 255 characters), `preservedThreadId`, and
+`actionKind`. The response returns an ephemeral token; only its SHA-256 hash is
+stored. An untouched, unexpired, pre-intent `active` replay returns a new token
+with `token_reissued: true` and invalidates the original token. During overlapping recovery retries, the four newest prior recovery tokens remain valid for one minute or until one is used, which promotes it. Other replays
+return `token: null`; terminal attention replays are acknowledgement-only. `PATCH /api/orgs/{id}/runner-leases/{leaseId}` accepts fenced renew,
+progress, turn-milestone, terminal, reconciliation, and acknowledgement
+transitions, including `model_completed`. Organization, agent, runner, generation, token, and sequence must
+match. Exact mutation retries are idempotent, and `uncertain_outcome` blocks
+automatic replacement. Paused, disconnected, stale, or replaced runners cannot
+mutate or replay. Lease rows enforce a composite `(issue_id, org_id)` foreign key.
+Mutation metadata is closed: `progress` accepts `preparing`,
+`turn_intent_persisted`, `sdk_accepted`, `running`, `model_completed`, or
+`finalizing`; `errorCode` accepts `runner_error`, `sdk_error`, `model_error`,
+`timeout`, `cancelled`, or `unknown`. Free-form runtime details are rejected.
+
 ## OAuth Agent Profiles
 
 `GET /api/oauth/agent-profiles` and `atoll_list_agent_profiles` return only
@@ -83,7 +129,7 @@ calls return stable errors: `no_profiles_authorized`, `profile_required`
 
 ## Task Fields
 
-Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also accepted for backward compatibility. Responses always use snake_case.
+Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also accepted for backward compatibility. Responses generally use snake_case; dependency responses retain camelCase release fields (`releaseColumnId`, `releaseColumn`, and nested `projectId`) plus the `release_column_id` compatibility alias.
 
 ## Avatar Upload Response
 
@@ -137,6 +183,19 @@ Most fields work on both POST (create) and PATCH (update). `labelIds` is accepte
 - **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`.
 
+Full `GET /api/orgs/{id}/issues` list items include the canonical
+project-prefixed `identifier` and collision-free `projectSlug` for project
+issues, or `null` for projectless issues. Compact `view=board` and `view=list`
+items do not include these fields.
+
+The MCP `atoll_list_issues` projection exposes optional nullable
+`identifier` and `projectSlug`, drops undeclared REST enrichment including the
+CLI-derived `url`, and normalizes both legacy `{ issues, total, limit, offset }`
+and CLI-compatible `{ resource: "issues", items, ... }` responses into the
+exact public list envelope. The full profile exposes it in `structuredContent`;
+the public plugin exposes it under `structuredContent.result.data`. Project-
+scoped calls may add `project_context` alongside the envelope.
+
 **Bulk create** (`POST /issues/bulk`):
 ```json
 { "issues": [{ "title": "Task 1", "status": "todo", "priority": 1, "projectId": "..." }] }
@@ -166,6 +225,10 @@ Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": f
 
 Key-minting agent creation responses contain the one-time raw `apiKey` and its stable `apiKeyId`. Creation with `oauthOnly: true` omits both fields.
 
+Manageable-agent rows always include nullable `key_prefix`, `last_used_at`, and `activity_last_used_at`. `key_prefix` and `last_used_at` describe only the selected active API key. `activity_last_used_at` is the latest timestamp from an active API key or a non-revoked OAuth agent profile. Historical OAuth use is not backfilled.
+
+Workforce read rows from `GET /api/orgs/{id}/agents/workforce` contain bounded identity fields, safe `projects` summaries, `project_ids`, `created_at`, nullable aggregated `last_used_at`, nullable personal-agent `owner` display metadata, `scope` (`personal`, `project`, or `organization`), and `capabilities` with `can_view`, `can_manage_access`, `can_manage_keys`, `can_disable`, and `can_revoke` booleans. Project-admin visibility sets only `can_view` unless an existing creator/personal-owner management rule independently grants more. `key_prefix` is optional and is returned only when existing key-management authority allows it. The response never includes emails, auth IDs, hidden projects, credentials, OAuth grants, prompts, raw activity, lifecycle fields, or organization capacity.
+
 ## Agent Heartbeat Policy Fields
 
 Heartbeat policy replacement uses a complete object with `sections` booleans for `goals`, `standalone_kpis`, `standalone_initiatives`, `assigned_issues`, `project_context`, `signals`, and `attention`; `signal_categories` booleans for `task`, `initiative`, `kpi`, and `project`; `project_ids`; `initiative_ids`; and `columns` entries shaped as `{ "project_id": "...", "column_id": "..." }`. Empty focus arrays mean all. Policy fields narrow proactive attention and never grant access. Management `saved_policy` retains stale IDs so saved previews and real heartbeats fail closed; `effective_policy` is the sanitized editable form, `stale_selections` reports removals, and saving it clears stale restrictions. Manageable-agent list rows include visible `project_ids`, named `accessible_projects`, and `heartbeat_policy_summary.{status,focus_summary}`.
@@ -236,6 +299,12 @@ Calculated KPIs do not accept manual snapshots.
 
 `api_poll` snapshots are written by published KPI HTTP Syncs and include provenance: `source_sync_id`, `source_sync_run_id`, `source_config_hash`, `source_recorded_for`, `observed_at`, and optional `provider_recorded_at`.
 
+Snapshot list/create responses keep an explicit legacy projection. Use
+`projection=provenance_v1` on the list route to add nullable
+`source_window_start` and `source_window_end` calendar dates. Before the
+source-window migration is active, both opt-in fields are `null`. Existing
+clients and snapshot-create responses do not receive the added fields.
+
 ## KPI detail relationship fields
 
 KPI detail includes `initiative_impacts` for initiatives visible to the caller
@@ -403,8 +472,31 @@ multiple exact-name milestones already exist, upsert returns a structured
 }
 ```
 
+Supported action values are: `set_status` (lowercase status key using letters,
+digits, and underscores), `set_assignee` (member UUID or `null`),
+`set_priority` (integer `0` through `3`), `add_label` (label UUID),
+`post_comment` (non-empty text), and `close_issue` (no value or `null`).
+Unsupported action types or malformed values return `400` and are not saved.
+
 **Dry-run test**: Send `{ "issue_id": "uuid" }` or `{ "issue": { "status": "todo", "priority": 2 } }`. Returns `{ matched, actions_that_would_run }`.
 
+**Automation run history**: `GET /api/orgs/{id}/automation-rules/{ruleId}/activity`
+returns `{ runs }` to owner/admin members, newest first and limited to the
+latest 100 runs. Each run contains its status,
+timestamps, safe error fields, a safe source-event projection, and ordered
+`automation_action_runs` for actions that were actually attempted. Non-matching
+events, dry runs, and rules with no executable actions create no run row. The
+response excludes event payloads, action inputs, request headers, credentials,
+and third-party response bodies.
+
+If a definitive action-audit start fails after an earlier action, the run is
+terminal with safe `error_code: "automation_execution_partial"` and message
+`automation execution stopped after one or more earlier actions`; earlier
+action evidence is not replayed. Deleting a rule or its project preserves the
+run and action rows with the original rule UUID as an immutable snapshot, so
+authorized Activity lookup remains possible. Deleting the organization may
+remove its organization-owned history.
+
 ## Custom View Fields
 
 ```json
@@ -423,9 +515,12 @@ multiple exact-name milestones already exist, upsert returns a structured
 ## 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.
+`DELETE .../board-columns/{columnId}?reassignTo={targetColumnId}&releaseReassignTo={releaseTargetColumnId}`.
+`reassignTo` is required when the source column contains issues and
+`releaseReassignTo` is required when it has dependency release references;
+the targets are independent, must belong to the same project, and reassignment
+and deletion are atomic. The board-column list reports `issue_count` and
+`release_reference_count` so clients can fail closed before deletion.
 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
@@ -629,7 +724,7 @@ 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. 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`.
+Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, direct replies, assignee comments, and creator-visible status changes. Authorized REST and CLI heartbeat calls can also include `verification.completed`; the public MCP heartbeat excludes this private event type. Verification items include a validated `verification` object with bounded repository, PR, workflow, run attempt, head SHA, conclusion, canonical run URL, and `next_action` fields. They contain no raw payloads, secrets, logs, or thread identifiers. 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 single Google Chat preference is stored under `mention.created` and controls mentions, assignments, and direct-reply comments; ordinary comments and status changes are excluded. 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`. New direct-message installations receive a welcome before configuration. Classic Chat interaction apps link humans through a short-lived `REQUEST_CONFIG` session after `connect`; Workspace add-ons use `basic_authorization_prompt`. Both flows retain display-safe Chat identity fields and memberships owned by the signed-in human. Add-on callbacks require the endpoint URL audience and exact per-project add-on service account email; classic callbacks continue to trust Google's Chat service account and can use a project-number audience. Connect-session and member endpoints require a human web session; a one-time `connect <token>` command remains a manual fallback.
 
@@ -671,6 +766,22 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 - Initiative health: `initiative_missing_impact`, `initiative_missing_execution`, `initiative_stalled`, `initiative_target_missing_execution`, `initiative_target_overdue`, `initiative_target_blocked`
 - Execution: `issue_blocked`, `issue_overdue`, `milestone_overdue`
 
+## Artifact Fields
+
+Artifacts contain `id`, `org_id`, `type`, `title`, `current_revision_id`,
+`created_by`, `created_at`, and `updated_at`. Artifact links contain `id`,
+`artifact_id`, canonical `artifact_type`, `target_type` (`issue` or `project`), `target_id`, `created_by`,
+and `created_at`. Revisions contain `id`, `artifact_id`, `revision_number`, immutable `title_snapshot`,
+`content_format`, `content_digest`, `created_by`, and `created_at`; the full
+revision endpoint also returns sanitized `content`. Revision summaries never
+return content. Content formats are `markdown` and `html`; both are stored as
+sanitized HTML. Titles are limited to 200 UTF-8 bytes and revisions to 256 KiB.
+If a member is deleted, creator provenance is retained as `null`.
+The opt-in issue manifest contains only `id`, `type`, `title`,
+`current_revision_id`, `created_at`, and `updated_at`. Issue PRD and
+Implementation Plan links are limited to one slot per issue, and each such
+Artifact can be authoritative for only one issue.
+
 ## Analytics Response
 
 ```json
@@ -690,12 +801,14 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 |--------|-------|--------|
 | Task | `status` | Project-defined stored board-column key matching `^[a-z0-9_]+$`; defaults are `backlog`, `todo`, `in_progress`, `done`, with system status `cancelled` |
 | Board column | `description` | Optional stage criteria or agent guidance |
+| Board column | `recommendationRole` / `recommendation_role` | Nullable workflow role request field: `candidate`, `active`, or `excluded`; both aliases must match when both are present. Responses use `recommendation_role`; `null` means unconfigured and not eligible for future recommendations. |
 | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) |
 | Task update request | `comment_body` | Optional Markdown/plain text or rich-text HTML comment body created with the issue update; stored and returned as sanitized HTML |
 | Task update request | `comment_mentions[].member_id` | Stable Atoll org member ID to mention in the issue update comment created by `comment_body`; not an auth user ID or display name |
 | Task update request | `comment_source_metadata` | Optional explicit agent provenance using the same validated shape as direct comment `source_metadata` |
 | Comment create request | `reply_to_comment_id` | Optional comment ID that this flat, one-level reply addresses; target must be an active comment on the same task |
 | Comment create request | `source_metadata` | Optional agent-only routing object: `harness`, real `thread_id` and/or `session_id`, optional `host_id`; omit it when the host lacks a real identifier, and never invent one |
+| Comment response | `author_type` | `human`, `agent`, or `automation`; automation comments have null `author_id` and null comment routing `source_metadata` |
 | Comment response | `reply_to_comment` | Parent context including `id`, `body`, `author_type`, and routing-safe `source_metadata` |
 | Comment list response | `comments[].mentioned_members[]` | Persisted mention recipient summary with `id`, nullable `display_name`, and nullable `type`; empty when no mentions are recorded |
 | Comment create request | `mentions[].member_id` | Stable Atoll org member ID to mention in a direct comment API request; recommended for agents and integrations |
@@ -744,6 +857,72 @@ 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.
 
+## Dependencies
+
+Dependency creation requires the blocking issue to belong to a project because
+the persistent release point is a board column there. A projectless issue may
+be the blocked target when the caller has permission to use it.
+
+`GET /api/orgs/{id}/issues/{issueId}/dependencies` returns `blocking` and
+`blockedBy` arrays. Each dependency includes:
+
+| Response field | Type | Notes |
+|---|---|---|
+| `id` | UUID | Dependency identifier |
+| `issue` | object or null | Authorized target projection with `id`, `number`, `identifier`, `projectSlug`, `title`, and `status`; inaccessible targets are `null` |
+| `issue.identifier` | string or null | Canonical project-prefixed issue reference for navigation; `null` for projectless targets |
+| `issue.projectSlug` | string or null | Collision-free project route segment; `null` for projectless targets |
+| `createdAt` | timestamp | Dependency creation time |
+| `releaseColumnId` | UUID | Persistent release column in the blocking issue's project; present when the blocking issue is authorized |
+| `release_column_id` | UUID | Compatibility alias for `releaseColumnId`; present with the canonical field |
+| `releaseColumn` | object or null | `{ id, key, label, position, projectId }` release column projection |
+| `satisfied` | boolean or null | Whether the blocker reached the release column position, or is cancelled |
+
+The dependency-release migration backfills existing dependencies to the
+blocking project's `done` column. During a rolling deployment, compatibility
+reads may omit release fields from older rows; treat missing release metadata as
+the legacy open-blocker behavior until the migration is applied.
+
+## External References
+
+External-reference response items contain `link_id`, `id`, `org_id`,
+`target_type` (`issue` or `project`), `target_id`, `provider`, `object_type`,
+`provider_object_id`, `provider_container_id`, `canonical_url`, bounded
+`display_metadata`, `provenance`, `resolvable`, `resolution_error`,
+`last_observed_at`, `created_at`, `updated_at`, and `linked_at`. The REST POST
+request accepts `url` plus optional `provider: "github"` and
+`object_type: "pull_request"`; provider identity fields are not caller
+inputs. GitHub links require numeric immutable IDs from the authorized live
+provider response or return `422` with
+`code: "github_identity_unavailable"`. Link and unlink writes emit the
+metadata-only Activity actions `external_reference.linked`,
+`external_reference.updated`, or `external_reference.unlinked`.
+
+## Task Activity
+
+`GET /api/orgs/{id}/activity` returns `{ data, currentMemberId, limit, offset,
+hasMore }` and accepts `filter=all|by_me|mine`. `GET
+/api/orgs/{id}/issues/{issueId}/activity` returns `{ data, items, limit, offset,
+hasMore }`. Items retain the `activity_events` fields. Top-level `actor` is a
+current member projection and can reflect later profile changes; the immutable
+event-time actor snapshot is `metadata.actor` with `id`, `display_name`, `type`,
+and `avatar_url`. The
+canonical actions cover task lifecycle, comments, assignees, labels,
+dependencies, initiative/target links, GitHub PR links and updates, attachments,
+and subtasks. Notification, webhook, realtime, and delivery records are excluded.
+The exact canonical `action` values are `issue.created`, `issue.updated`,
+`issue.archived`, `issue.unarchived`, `comment.created`, `comment.updated`,
+`comment.deleted`, `assignee.added`, `assignee.removed`, `label.added`,
+`label.removed`, `dependency.added`, `dependency.removed`, `dependency.release_updated`,
+`initiative.linked`, `initiative.unlinked`, `initiative_target.linked`,
+`initiative_target.unlinked`, `github_pr.linked`, `github_pr.updated`,
+`attachment.added`, `attachment.removed`, `subtask.created`,
+`subtask.completed`, `subtask.reopened`, `subtask.removed`, `subtask.updated`,
+`external_reference.linked`, `external_reference.updated`, and
+`external_reference.unlinked`.
+Use `limit` in `1..100` and a non-negative `offset`; older history may be
+partial because pre-contract events are not fabricated or backfilled.
+
 ## Response Format
 
 Most endpoints return JSON; attachment content returns binary bytes. Successful: