@atollhq/skill-claude 0.4.37 → 0.4.39

package/skill/references/api-fields.md

@@ -103,6 +103,19 @@ Mutation metadata is closed: `progress` accepts `preparing`,
 `finalizing`; `errorCode` accepts `runner_error`, `sdk_error`, `model_error`,
 `timeout`, `cancelled`, or `unknown`. Free-form runtime details are rejected.
 
+For verified workflow resume, set GitHub verification mode to `resume` in
+Workspace Settings. This mode is disabled by default, requires a current Codex
+runner for the delivery agent, and adds `verificationEventId` to a verified
+workflow `attention_resume` claim. The server binds the completed issue lease to the
+repository ID, PR number, exact head SHA, source lease generation, runner
+installation, runner host, and preserved thread.
+Only a matching `verification.completed` item is routed to
+`resume_agent_thread`; uncertain or mismatched identity remains review-only.
+`RUNNER_LEASE_VERIFICATION_BINDING_MISMATCH` is a definite 409 claim
+rejection; the local attempt closes while the notification remains unread for
+the next review pass. There is no new-thread fallback. Terminal replay is
+acknowledgement-only.
+
 ## Hosted runner fleet control
 
 `GET /api/orgs/{id}/runners` is human-session only. It returns one current or
@@ -242,6 +255,30 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 `resource` is one of `humans`, `agents`, `activeProjects`, or `activeIssues`.
 
+## Member Directory Fields
+
+`GET /api/orgs/{id}/members?shape=envelope` returns the bounded member
+directory. Supplying `q`, `limit`, or `offset` also selects this directory
+mode. It returns a list envelope with exact `total`, `limit`, `offset`,
+`nextOffset`, `truncated`, and `hint` values.
+
+Each `items[]` row contains only:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Stable organization member UUID. Use this in issue `assignee_id` or `assignee_ids` writes. |
+| `display_name` | Safe display name; missing names use `Unknown member`. |
+| `type` | `human` or `agent`. |
+| `role` | Current organization role. |
+| `avatar_url` | Avatar URL or `null`. |
+
+Directory inputs are `projectId`, `type=human|agent`, case-insensitive
+display-name `q`, `limit` (default 25, maximum 100), and `offset` (default 0).
+Project results require caller access and follow existing collaborator
+visibility rules. Unprojected directory results exclude guests. `includeEmail`
+does not add email to this response. A request without `shape`, `q`, `limit`, or
+`offset` keeps the legacy member response for web consumers.
+
 ## Agent Fields
 
 Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`. Any create form may include an allowlisted `avatarPreset` ID. Arbitrary URLs are rejected. Existing agent presets are changed with `{ "preset": "codex" }` on the avatar PATCH endpoint.
@@ -366,6 +403,12 @@ attribution.
 
 V1 syncs are `GET` only, `https` only, JSON only, exact-host allowlisted, no redirects, no request bodies, no inline query strings, and no secret values. Machine actors can create drafts and validate configs only after the host is allowlisted. Human admins manage allowlists, secrets, dry-runs, publishing, disabling, and snapshot-writing run-now actions in Atoll.
 
+Both MCP profiles expose `atoll_create_kpi_http_sync_draft` and
+`atoll_validate_kpi_http_sync_config` for this draft-only workflow. The tools
+reject inline secret values and return safe draft metadata rather than request
+configuration. Public MCP does not expose secret entry, network dry runs,
+publishing, disabling, or snapshot writes.
+
 ## Initiative Fields
 
 ```json
@@ -436,16 +479,42 @@ writes persist canonical resource UUIDs within the initiative's authorized
 scope; malformed, concealed, ambiguous, and resolver-failure outcomes are
 `400`, `404`, `409`, and `500` respectively.
 
-## Public MCP planning fields
-
-The public plugin uses snake_case MCP fields and adds `profile_ref` to each
-actor-dependent call. `project_id` accepts a project UUID, exact slug, or exact
-name for initiative and milestone operations; the MCP server resolves it to a
-canonical UUID before writing. Issue references accept UUIDs, bare numbers,
-`#number`, `ATOLL-number`, `TSK-number`, and unambiguous project-derived
-prefixes. Initiative milestone-link creation also accepts an exact milestone
-name through the backing API resolver; unlink operations use the canonical
-milestone UUID.
+## Public MCP typed product fields
+
+Public plugin calls use snake_case fields and accept the opaque per-call
+`profile_ref` selector. Project references accept a UUID, exact slug, or exact
+name. Issue references accept UUIDs, bare numbers, `#number`, `ATOLL-number`,
+`TSK-number`, and unambiguous project-derived prefixes. Label references accept
+a UUID or exact label name. Initiative milestone-link creation also accepts an
+exact milestone name; unlink operations use the canonical milestone UUID.
+
+Core typed tools include issue archive/unarchive and dependency-chain reads;
+label and subtask list/create/update/delete; strategy audit; organization
+activity; notification list/acknowledgement; project create/delete and board
+column creation; and goal/KPI create/update. `atoll_get_strategy_audit` accepts
+`severity: "critical" | "warning" | "info"`; the returned summary and type
+counts match the filtered findings. `atoll_list_activity` accepts filter
+`by_me` or `mine`, `limit: 1..100`, and non-negative `offset`.
+
+Goal update accepts `goal_id` as a UUID or exact goal title. KPI create and
+update accept `goal_id` as a UUID or exact goal title; KPI update accepts
+`kpi_id` as a UUID or exact KPI name. These lookups are exact and scoped to
+the selected organization. Missing names return `reference_not_found`, and
+duplicate exact names return `ambiguous_reference`; neither writes a mutation.
+Archive and unarchive emit the normal `issue.updated` webhook event. The
+project, label, subtask, board-column, goal, and KPI writes listed in the API
+endpoint reference can return `core_write_uncertain` with `retryable: false`
+when transport failure, HTTP 5xx, or invalid success output leaves the outcome
+unclear. Use the error's readback steps to reconcile state before a replay;
+authoritative 4xx responses are preserved.
+
+Subtask creation accepts `{ title }`; update accepts `title`, `completed`, or
+both. Board-column creation accepts `project_id`, lowercase `key`, `label`,
+optional inline `description`, and optional `color`; MCP has no file-input
+field. Project deletion requires the exact `confirmation: "DELETE"` value and
+owner/admin access. Linked Artifacts and active executions can still block
+deletion. Goal writes remain owner/admin-only. KPI update changes configuration;
+use `atoll_record_kpi_snapshot` to record `current_value` measurements.
 
 Examples:
 
@@ -460,6 +529,36 @@ Examples:
 
 Initiative creation accepts either a non-empty `title` or the legacy `name`
 alias; updates use `title` only. Initiative, target, and milestone due dates use `YYYY-MM-DD`.
+
+## Read-only repository context fields
+
+`atoll_list_project_repositories` accepts `org_id` and `project_id`;
+`project_id` supports a UUID, exact slug, or exact name. Its response contains
+`project`, mapped `repositories`, and `truncated`. Each repository includes an
+opaque `repo_ref`, safe repository and project identities, `default_ref`, and
+`read_only_app.status: "connected"`.
+
+The other four tools accept that `repo_ref`. Tree, file, search, and commit
+results include `requested_ref` and `resolved_commit_sha`, which identifies the
+exact commit used for the read. Tree entries contain `name`, `path`, `type`,
+nullable `sha`, and nullable `size`; the response keeps `truncated`. File
+results contain `path`, bounded `content`, `encoding: "utf-8"`, and `size`.
+Search results contain `query`, nullable `path`, verified `hits`, `total_count`,
+and `incomplete_results`; each hit includes `name`, `path`, `sha`, nullable
+`html_url`, and `verified_at_commit_sha`. Commit results contain `sha`, nullable
+`html_url`, bounded `message`, `message_truncated`, nullable `author` and
+`committer` snapshots, valid `parents` with nullable `html_url`, and
+`parents_truncated`. Public and full/private MCP output schemas reject
+undeclared fields.
+
+Repository errors preserve the REST `{ error, code, retryable }` fields. Codes
+include `repository_not_connected`, `repository_access_denied`,
+`github_installation_unavailable`, `github_permission_missing`,
+`repository_ref_invalid`, `git_ref_not_found`, `repository_path_not_found`,
+`repository_search_ref_unsupported`, `repository_file_too_large`,
+`repository_file_encoding_unsupported`, and `repository_context_unavailable`.
+Public plugin responses also wrap the same data in `result: { ok, data }` or
+`result: { ok, error }`.
 Initiative target writes use the existing target fields above. Public milestone
 create and upsert accept `status: "active" | "closed"`; closed creation is
 persisted in the same downstream write. Public milestone upsert compares exact-name fields and returns `unchanged` for an identical
@@ -496,6 +595,10 @@ multiple exact-name milestones already exist, upsert returns a structured
 }
 ```
 
+`issue.assigned` matches both assignment changes and issue creation with at
+least one assignee. This includes recurring occurrences that inherit an
+assignee from their recurrence root.
+
 Time-based rules use the same definition with `trigger_event:
 "schedule.issue_time"` and a required `schedule_config`:
 
@@ -624,8 +727,9 @@ return `400`. A project UUID requires both organization membership and caller
 read access to that project; cross-organization, inaccessible, or missing
 projects return `404`. Organization-wide and unfiltered requests retain existing
 organization-member access. Results remain newest first and include disabled
-or invalid rules with their validation diagnostics. This REST filter does not
-add CLI flags or public MCP tool parameters.
+or invalid rules with their validation diagnostics. Both MCP profiles accept
+the same optional `project_id` UUID or `none` filter; the CLI does not add
+filter flags.
 
 GET/list rules can include `validation: { valid, issues: [{ path, code, message }] }`.
 Invalid saved rows remain readable. Runtime validation rejects the whole invalid
@@ -778,6 +882,11 @@ a new private destination version; pending deliveries retain their pinned versio
 
 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 an Atoll-generated `secret` for HMAC signature verification. Store it immediately; it is shown only once. This is distinct from the receiver-supplied Standard Webhooks `whsec_` secret. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
 
+`atoll_create_webhook` is available only in the full/private MCP profile because
+normal MCP tool output may be retained in client conversation history. The
+public plugin exposes redacted webhook listing and deletion but never the
+one-time signing secret.
+
 List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Automation action payloads use schema version `3` with current tenant-scoped project and issue fields; subscription broadcasts and `ping` remain schema version `2`. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, `X-Atoll-Delivery-Id`, and `Idempotency-Key`. When Standard Webhooks is enabled, they also include `webhook-id`, `webhook-timestamp`, and `webhook-signature`. 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
@@ -825,7 +934,8 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 
 `GET /api/orgs/{id}/heartbeat` returns compact delivery by default for REST
 and private CLI/MCP callers. Compact responses contain `mode: "compact"`,
-`agent`, `timestamp`, `attention_items`, `attention_summary`, grouped `signals`, `recommended_action`,
+`agent`, `timestamp`, `attention_items`, `attention_summary`, private
+`execution_attention` and `execution_attention_summary`, grouped `signals`, `recommended_action`,
 `counts`, `delta`, and `page`. Full legacy context is available only with
 `view=full` (or the CLI `--full` flag).
 
@@ -836,6 +946,8 @@ and private CLI/MCP callers. Compact responses contain `mode: "compact"`,
 | `signals[]` | Grouped actionable signal or dependency-blocker groups. Each group has `key`, `revision`, `severity`, `kind`, `action_reason`, root and impact counts, readiness, bounded `evidence`, and optional `suggested_read`. |
 | `attention_items` | Bounded direct attention projections with required `id`, `event_type`, `severity`, `title`, `resource_type`, and `ack_endpoint`; optional `resource_id` is included when present. |
 | `attention_summary` | Counts for included direct attention items. |
+| `execution_attention` | Private queues with `resolved_unread` answers and `open` requests. Resolved answers remain until explicit receipt acknowledgement or the exact requester `waiting -> running` transition. |
+| `execution_attention_summary` | Private exact counts for `resolved_unread`, `open`, and `total`. |
 | `counts` | `actionable_groups`, severity counts, `direct_blocked`, `downstream_blocked`, `ready_if_released`, `unknown_readiness`, `restricted`, and `suppressed_expected_waits`. |
 | `delta` | `since`, `new_count`, `changed_count`, `escalated_count`, `ready_count`, suppression counts, and `reset_required`. |
 | `page` | Requested `max_bytes` (1,024-16,384) and `max_items` (1-25), returned counts/bytes, `has_more`, `next_cursor`, and terminal `ack_cursor`. |
@@ -1010,6 +1122,44 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 
 ## Artifact Fields
 
+### Revision source provenance
+
+An Artifact revision can keep one optional source from an existing External
+Reference linked to the same issue or project. The source is an immutable
+pointer snapshot. Atoll does not fetch, copy, or synchronize provider content.
+
+Create accepts optional `source_external_reference_link_id` (the Context link
+UUID). Revise uses three states: omit the field to inherit the current snapshot,
+supply a live link UUID to set or replace it, or send `null` to clear it on the
+new revision. A source-only change is valid and still requires the exact
+`expected_revision_id` or `expected_revision_number`. An unchanged title,
+content, and source is rejected. An unrelated or removed link cannot be selected.
+
+Source selection returns `404 source_reference_unavailable` for a missing,
+concealed, or concurrently removed link; these cases are indistinguishable.
+A link on an unrelated Artifact target returns `400 source_target_mismatch`.
+Choose another source or clear the selection. A stale expected revision still
+returns `409 CONFLICT` and requires rereading the Artifact before retrying.
+
+Add `?projection=source_provenance_v1` to Artifact create, revision create, or
+single-revision GET to receive `revision.source_reference`. Default responses
+and revision lists remain unchanged. Unknown or duplicate projections return
+`400`. The projection is `null` when no source exists or the caller cannot read
+the recorded source target. Otherwise it contains `external_reference_id`,
+`target_type`, `target_id`, `canonical_url`, `provider`, `object_type`,
+`provenance`, nullable `label`, and live `currently_linked`.
+
+The URL is HTTP(S), has no credentials, and is limited to 2048 UTF-8 bytes;
+provider, object type, and provenance are each limited to 64 bytes, and the
+label to 240 characters (at most 960 UTF-8 bytes). All fields except `currently_linked` come from the saved
+snapshot. Removing the live Context link preserves history and permits
+inherit or clear. Later reference changes cannot rewrite a saved source.
+Linking the Artifact to another target does not grant access to its source.
+
+The web editor and CLI support this workflow. Typed MCP source inputs and
+outputs are not yet available; their existing Artifact contract is unchanged.
+
+
 `atoll_list_artifacts` accepts optional `issue_id` for a compact issue manifest
 or `project_id` for direct project links; these selectors are mutually
 exclusive. All modes accept `limit` (1-100, default 50) and `offset`
@@ -1063,6 +1213,15 @@ returns state `assigned`. Transition requires `expected_state_version`,
 provenance; the server derives safe OAuth provenance. The generic transition
 enum excludes `needs_human`.
 
+The local runner uses `harness_kind: "atoll_local_runner"` and the lease UUID
+as `external_run_id`. Its private job record stores the exact execution state
+and version plus one bounded pending management operation. Canonical human
+attention adds private claim fields `attention_source: "human_attention"`,
+`execution_id`, `human_attention_item_id`, `expected_attention_version`, and
+`expected_execution_version`; those identities are separate from notification
+`attention_item_id`. The runner sends only canonical IDs and the closed
+resolution outcome enum to the retained thread.
+
 ## Analytics Response
 
 ```json
@@ -1098,6 +1257,23 @@ bounded `resolution_summary`. Free-form text rejects secret-like values.
 Internal requester/actor provenance, hashes, response snapshots, and mutation
 metadata are never returned by the public API.
 
+Private heartbeat execution-attention items contain bounded execution, issue,
+project, kind, title, request summary, request time, status, attention version,
+execution state version, resolution outcome/summary when resolved, the close
+state version, and an `ack_endpoint`. The receipt ack body is
+`{ expected_attention_version, expected_execution_state_version_at_close,
+idempotency_key }`. It is requester-only, checks current project access, is
+idempotent for the same key and body, and never resumes work. Stale versions return `409`, including after consumption; current versions after another consumer return `already_consumed: true` without consuming again.
+
+The full/private and public plugin MCP profiles expose typed execution tools
+for list, detail, assigned creation, version-fenced transition, evidence list,
+and existing-evidence link, plus requester attention list, detail, create,
+cancel, and receipt acknowledgement. These tools preserve the REST projections
+and require explicit lifecycle idempotency/version inputs on writes. Their
+schemas exclude local file content and do not expose human resolution,
+administrator recovery/retarget/cancel, or runner and harness controls. Public
+actor-dependent calls use the selected connection-scoped `profile_ref`.
+
 ## Enums
 
 | Domain | Field | Values |
@@ -1228,6 +1404,11 @@ metadata-only Activity actions `external_reference.linked`,
 
 ### External operational delivery context
 
+Manual `workflow_dispatch` evidence requires one distinct current linked PR,
+canonical numeric PR and repository identity, and matching head SHA and branch.
+Several issue links to that same PR are allowed. Provider PR membership remains
+required for `pull_request` runs. Unresolved dispatch identity creates no signal.
+
 `GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` returns
 `{ deliveryContext }`. The value is `null` without a linked PR. With several
 links, selection prefers an open PR, then the latest `updated_at`, then the
@@ -1334,3 +1515,230 @@ not a hosted API or MCP surface. Its browser projection excludes credentials,
 raw configuration, prompts, and model output. Local bindings use `repo_ref` but
 do not grant project/repository access. Intake is read-only locally; hosted
 Workspace Settings → Runners owns pause/resume. See the CLI local-runner guide.
+
+## MCP Events subscription fields
+
+The modern public OAuth MCP endpoint (`https://atollhq.com/mcp`, version `2026-07-28`) advertises `events` and supports `events/list`, `events/subscribe`, and `events/unsubscribe`. Legacy 2025 tool calls remain supported. No event subscriptions are available to API-key, private or stdio identities.
+
+The authenticated adapter uses `POST /api/mcp-events/subscriptions` to create/refresh and `DELETE /api/mcp-events/subscriptions` to unsubscribe. Resolve the OAuth connection and optional `X-Atoll-Agent-Profile` through existing auth. Request fields are the protocol `name`, `arguments`, `delivery`, optional `ttlMs`, and optional `cursor: null`. Profile selection travels in the header, not business filters.
+
+Events: `issue.status_changed` (`project_id`, optional `issue_id`, `from_status`, `to_status`); `attention.created` (`project_id`, optional `kind`); `execution.state_changed` (`project_id`, optional `issue_id`, `to_state`). Project and issue UUIDs must be readable in the selected profile; status keys must exist in the project's workflow.
+
+Subscribe requires `{ mode: "webhook", url: "https://…", secret: "whsec_…" }` with a canonical Base64 key of 24–64 bytes. Unsubscribe uses the same name/arguments/callback identity and does not require a secret. The principal is the resolved OAuth connection plus profile grant. IDs use canonical JSON and callback URLs. POST returns `{ id, refreshBefore, cursor: null, truncated: false }`; DELETE returns `{}`. Secrets are never returned.
+
+Every grant is bounded by validated OAuth access-token expiry and a shorter finite `ttlMs`, if requested. Even `ttlMs: null` receives a finite grant. Refresh rotates secrets with overlap through the previous grant's expiry. Callback verification is cached only through its granted expiry. Delivery rechecks connection/profile/project access and uses the existing SSRF-safe HTTPS boundary and 15-minute maintenance runner. One compact immutable occurrence is sent per request with stable event ID and Standard Webhooks headers; retries stop at the grant deadline active when the event occurred, even if fanout is delayed. Shorter refreshes clamp cached verification; reactivation requires a fresh challenge. Quiet expiry/revocation and expired rotation overlap clear signing material through bounded maintenance batches. No replay; 410/413 are terminal. Callback errors use `callback_endpoint_error` with a categorized `reason`, mapped to MCP `-32015`. Temporary service failures map to MCP `-32603`.
+
+## MCP App extension (not a REST endpoint)
+
+Public plugin discovery adds the app-only `atoll.open` global entrypoint,
+input `{}`, initial result `{page:"home"}`, and resource
+`ui://atoll/command-center` with MIME `text/html;profile=mcp-app`.
+`_meta.ui.resourceUri`, app-only visibility, a monochrome tool icon and
+`_meta["openai/ui"].entrypoints:[{type:"global"}]` identify the UI.
+Existing business reads keep their `profile_ref` and authorization contract.
+No REST field, write endpoint or persistent profile preference is added.
+
+## Bounded collection search
+
+Projects, goals, KPIs and initiatives accept `q` for case-insensitive literal
+substring matching of the display name/title, `q_exact=true` for the complete
+name, and `limit`/`offset` for server-side pagination. Defaults in bounded mode
+are 25 results, maximum 100, and offset 0. Filtering and authorization precede
+pagination; offsets beyond matching results return an empty page with the exact
+total. KPI pages include current calculated values. Use `shape=envelope`
+(or `response_shape=cli`) for `resource`, `items`, `total`, `limit`, `offset`,
+`nextOffset`, `truncated` and `hint`. Supplying a search or pagination parameter
+also selects bounded retrieval. Calls without these parameters retain their
+legacy resource-key response and full-list behavior.
+
+Members add `member_id=<UUID>` and `q_exact=true` in bounded directory mode.
+Identity filtering uses the same collaborator visibility rules and safe fields
+as name search; it does not grant access or return credentials or account email.
+Members and initiatives also accept `scope=accessible_projects` for a bounded
+union under the current actor. The server derives project IDs; callers cannot
+supply ID arrays. Guests see only accessible project-linked initiatives and
+eligible collaborators. Existing member/admin projectless initiative rights
+remain. Empty project access gives guests an empty page. Unknown scope or scope
+combined with an explicit project returns `400`. Explicit project scope remains
+`project_id` for initiatives and `projectId` for members.
+
+Full issue lists resolve authorized human identifiers such as `AH-123`,
+`ATOLL-123`, `#123` or a number before loose title/description matching. They also
+accept `q_exact=true` for the full title. The exact flag is rejected with `400`
+for compact `view=board`/`view=list`; existing compact search stays unchanged.
+The existing issue filters and actor/project authorization still apply.
+
+CLI list commands for projects, goals, KPIs, initiatives and members use
+`--search`, `--exact`, `--limit` and `--offset`; issue list uses `--q` with
+`--exact`. Member list also supports `--member-id`. These filters are evaluated
+by the API. Existing public/private MCP list tools expose `q`, `q_exact`,
+`limit` and `offset`; `atoll_list_members` adds `member_id`. Member and initiative
+lists expose `--accessible-projects` in the CLI and `scope=accessible_projects`
+in MCP. The initiative flag suppresses a configured default project and cannot
+combine with `--project` or `--org-wide`. Normal MCP goal/KPI/initiative calls
+without query, exact, paging or scope options retain legacy full-list responses.
+Composer search uses a constant number of bounded list calls per profile and
+entity kind, independent of the number of accessible projects.
+
+### Interactive forms and create identity
+
+`POST /api/orgs/{id}/issues` optionally accepts HTTP `Idempotency-Key: <UUID>`.
+The API scopes it to the authenticated member/org. One transaction consumes it;
+concurrent/later/changed-body replay returns 409 without another issue/effect,
+even after deletion. Invalid key returns 400; definite validation failure does
+not consume it. No header preserves independent create. Never retry an uncertain
+result automatically. The interactive tool generates this identity internally;
+ordinary CLI/MCP arguments do not expose it.
+
+`atoll_create_issue_interactive` seeds: required profile_ref; optional title,
+description, project_id UUID, project_query, milestone_query, priority 0-3 (0 Urgent, 1 High, 2 Medium, 3 Low),
+assignee_query, assignee_ids (max 10), start_date and due_date. Explicit forms
+confirm basic then project-dependent fields; cancel/refusal/expiry/invalid data
+creates nothing. State expires after ten minutes and binds grant, actor, profile,
+tool and original arguments. Both standard form and OpenAI rich-form capabilities
+are required. Normal atoll_create_issue is unchanged.
+
+Project milestone GET accepts optional q/q_exact/limit 1-100/offset>=0 and
+shape=envelope. Filter/paging happen before materialization; current calculated
+issueCount/completedCount/progress/statusCounts remain. Empty pages retain total
+and pagination. Default calls preserve the unpaged milestones alias.
+
+Forms retain at most 25 choices per collection. A truncated project or milestone
+page returns `issue_create_refine_project` or `issue_create_refine_milestone`;
+restart with a narrower `project_query` or `milestone_query`. A known accessible
+`project_id` can be supplied directly. No-match or truncated assignee search
+returns `issue_create_refine_assignee`; revise `assignee_query` rather than
+silently dropping the assignment. Recovery includes confirmed basic field seeds.
+Refinement creates no issue.
+
+
+## Vercel deployment context
+
+Vercel deployment observations use `provider: "vercel"`, `object_type: "deployment"`,
+and `provenance: "vercel_api"` in existing scoped External Reference reads.
+Metadata contains only label, environment, state, optional exact revision, and
+provider effective time. A complete authenticated repository/SHA tuple proves
+identity. Later missing fields cannot erase that proof; contradictory known
+identity is rejected. Partial observations are never combined to invent proof.
+The mapped project always receives the reference. An issue receives it only
+when exactly one unarchived issue in that project has the same numeric GitHub
+repository ID and exact SHA. Preview/staging supersession is chronological;
+production supersession follows an authenticated project production target and
+supports rollback to an older build. Deployment evidence does not change issue
+status, authorize release, or prove acceptance. Generic list/get/unlink work;
+manual link remains GitHub-pull-request-only. Unlink does not suppress later
+verified ingestion. See https://docs.atollhq.com/integrations/vercel.
+
+### Vercel connection and recovery fields
+
+
+Vercel deployment `display_metadata` has only `label`, `environment`, `state`,
+optional `revision`, and `provider_effective_at`, within 2 KiB. Environment is
+`preview|staging|production`; state is
+`queued|building|ready|failed|cancelled|superseded`. Revision is lowercase
+40-hex and is omitted when unavailable. Provider time is an RFC 3339 UTC
+string. Resolution errors also include `identity_unavailable`,
+`repository_mismatch`, and `provider_unavailable`. Unlink is association-only;
+a later verified observation can restore it.
+
+The owner/admin human-session endpoint is
+`/api/orgs/{id}/integrations/vercel`. GET returns `{ connections }` with safe
+`id`, `team_id`, `state`, `health_status`, nullable `health_code`,
+`last_health_checked_at`, `disabled_at`, `created_at`, `updated_at`,
+`webhook_url`, and `mappings`. Mapping fields are `id`, `connection_id`,
+`vercel_project_id`, `project_id`, `github_app_repository_id`, and `updated_at`.
+No credential value or ciphertext is returned.
+
+PUT requires all of these fields and rejects extras:
+
+| Field | Contract |
+| --- | --- |
+| `connection_id` | Proposed UUID for a new connection; saved UUID for edits |
+| `expected_updated_at` | `null` for a new connection, exact saved timestamp for edits |
+| `team_id`, `vercel_project_id` | 1–200 letters, digits, underscores, or hyphens |
+| `project_id`, `github_app_repository_id` | Same-org UUIDs; repository must be enabled and verified |
+| `api_token`, `webhook_secret` | Write-only non-empty strings, at most 4,096 UTF-8 bytes each |
+
+PUT validates the live Vercel project/repository and returns
+`{ connection_id, updated_at, webhook_url }`. Credentials must be supplied
+again on edit. Include every mapped Vercel project in the account webhook’s
+project scope, using the same callback URL and signing secret for the connection;
+Atoll does not change Vercel webhook settings. A mapping with history cannot change its Atoll project or
+repository. DELETE requires `{ connection_id, expected_updated_at }` and
+returns `{ disabled: true, updated_at }`. It clears credentials and revokes
+resolvability while preserving history.
+
+An organization supports at most 50 team connections, including disabled
+connections. Existing connections can reconnect and update mappings at that
+limit; new teams return `409 connection_limit`.
+
+POST `/api/orgs/{id}/integrations/vercel/reconcile` requires
+`{ connection_id }`; optional `vercel_project_id` selects one saved mapping.
+The response is `{ complete, results }`. Each result contains `mapping_id`,
+`environment`, `discovered`, `ingested`, `skipped`, `failed`, `truncated`, and
+`codes`. It reads one page of at most 50 per environment, plus the current
+production target when it is outside that page (at most 151 deployments per
+mapping). The extra target counts in `discovered`; history remains `truncated`
+when the provider has more pages. It stops new work after a bounded request budget. No raw provider response or credential is
+returned. Partial results use HTTP 200 with `complete=false`.
+
+Setup errors use `{ error: <safe code> }`: 400 for invalid input/provider
+proof, 403 for a non-human/non-admin caller, 404 for a missing connection or mapping,
+409 for `configuration_changed`, `mapping_has_history`, `mapping_limit`, or `connection_limit`,
+and 503 for transient provider, secret-key, or storage failure. Connection
+configuration uses an exact version fence; read the saved state before
+retrying an uncertain write.
+
+## Compact Context index
+
+`GET /api/orgs/{id}/issues/{issueId}/context` and
+`GET /api/orgs/{id}/projects/{projectId}/context` return `{ context }` after
+normal target authorization. Inaccessible targets are concealed. Projectless
+issues retain their existing access rules; setup-only agents receive no Artifact
+items. Project reads include directly linked records only.
+
+Use optional `group` (`development`, `design`, `discussion`, `documents`,
+`deployments`, or `production`) and `limit` (1–25, default 5 per group).
+Without `group`, all six groups are returned. Design and Discussion are reserved
+empty groups. `cursor` requires one group and the same target and limit as its
+previous page. Unknown or repeated query keys and invalid cursors return 400.
+Each group has its own `page.next_cursor` and `page.has_more`; these are live
+keyset pages, not a historical snapshot. Refresh to restart after evidence changes.
+Deduplicate continued items by `id`.
+
+The version-1 response contains `target`, `groups`, and `partial`. Each group has
+`key`, `state` (`available`, `empty`, `partial`, or `unavailable`), `items`, `page`
+(`limit`, `returned_count`, `has_more`, `next_cursor`), and safe `errors`.
+Items contain a namespaced `id`, `kind`, `group`, `authority`, `availability`,
+`summary`, `freshness`, `current_identity`, `follow_up`, and action capabilities.
+Artifact identities carry the current revision; revision-bound delivery and
+provider evidence carry an available commit SHA. Null means unknown, not current.
+External evidence is stale after 24 hours. Partial evidence stays explicit.
+
+Artifact summaries contain only title and type. Reference summaries contain a
+safe label/URL, provider/object type, environment, state, and provider time.
+Delivery summaries contain PR number/state, review, configured-workflow and
+required-check aggregates, and a fixed blocker code. Atoll records,
+provider references, and operational evidence have separate authority. A passed
+check, merged PR, ready deployment, current production target, and human
+acceptance are separate facts.
+
+Follow-ups are `artifact_revision` (Artifact and optional revision UUID),
+`external_reference` (reference UUID), or `issue_delivery_context` (issue UUID).
+Use existing authorized detail reads only when needed. The index never returns
+Artifact bodies, digests, revision history, provider payloads, credentials, or
+unbounded signal/check collections. Mutation capabilities are display hints;
+every mutation rechecks access. Responses are capped below 64 KiB; a larger
+request returns 413 `context_response_too_large`, so retry with a smaller limit.
+An individual source failure affects its group; a total read failure returns
+500 `context_unavailable`.
+
+CLI: `atoll context list --issue ATOLL-42 --json` or
+`atoll context list --project project-slug --group documents --limit 5 --json`.
+Pass exactly one target. Continue with `--group`, `--limit`, and `--cursor`.
+JSON preserves the REST envelope; human output includes explicit follow-up
+commands. The full/private MCP tool is `atoll_list_context`, with exactly one
+`issue_id` or `project_id` UUID and the same optional group, limit, and cursor.
+Public MCP Context and delivery-detail tools are not available; AH-3067 owns
+post-freeze parity. Existing public Artifact and External Reference reads remain
+available. No existing issue, heartbeat, or public tool schema changes.

package/skill/references/artifact-workflow.md

@@ -71,3 +71,40 @@ In a CLI environment, use `atoll issue get` for the compact manifest and
 [CLI operations](cli-operations.md). Use the required named profile.
 Exact REST routes and field limits are in [API endpoints](api-endpoints.md#artifacts)
 and [API fields](api-fields.md#artifact-fields).
+
+### Revision source provenance
+
+An Artifact revision can keep one optional source from an existing External
+Reference linked to the same issue or project. The source is an immutable
+pointer snapshot. Atoll does not fetch, copy, or synchronize provider content.
+
+Create accepts optional `source_external_reference_link_id` (the Context link
+UUID). Revise uses three states: omit the field to inherit the current snapshot,
+supply a live link UUID to set or replace it, or send `null` to clear it on the
+new revision. A source-only change is valid and still requires the exact
+`expected_revision_id` or `expected_revision_number`. An unchanged title,
+content, and source is rejected. An unrelated or removed link cannot be selected.
+
+Source selection returns `404 source_reference_unavailable` for a missing,
+concealed, or concurrently removed link; these cases are indistinguishable.
+A link on an unrelated Artifact target returns `400 source_target_mismatch`.
+Choose another source or clear the selection. A stale expected revision still
+returns `409 CONFLICT` and requires rereading the Artifact before retrying.
+
+Add `?projection=source_provenance_v1` to Artifact create, revision create, or
+single-revision GET to receive `revision.source_reference`. Default responses
+and revision lists remain unchanged. Unknown or duplicate projections return
+`400`. The projection is `null` when no source exists or the caller cannot read
+the recorded source target. Otherwise it contains `external_reference_id`,
+`target_type`, `target_id`, `canonical_url`, `provider`, `object_type`,
+`provenance`, nullable `label`, and live `currently_linked`.
+
+The URL is HTTP(S), has no credentials, and is limited to 2048 UTF-8 bytes;
+provider, object type, and provenance are each limited to 64 bytes, and the
+label to 240 characters (at most 960 UTF-8 bytes). All fields except `currently_linked` come from the saved
+snapshot. Removing the live Context link preserves history and permits
+inherit or clear. Later reference changes cannot rewrite a saved source.
+Linking the Artifact to another target does not grant access to its source.
+
+The web editor and CLI support this workflow. Typed MCP source inputs and
+outputs are not yet available; their existing Artifact contract is unchanged.

package/skill/references/cli-operations.md

@@ -7,7 +7,7 @@ Read this reference for routine Atoll CLI installation and resource operations.
 Install globally or use via npx:
 
 ```bash
-npm install -g @atollhq/cli   # or: npx @atollhq/cli ...
+npm install -g @atollhq/cli   # or: npm exec --yes --ignore-scripts --package @atollhq/cli@latest -- atoll ...
 ```
 
 Configure once:
@@ -35,6 +35,21 @@ 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`.
 
+## Discover members
+
+Use one member directory for humans and agents. Resolve a project by UUID, exact
+slug, or exact name, then filter by member type and display name:
+
+```bash
+atoll member list --project project-slug --type human --search "Ada" --json
+atoll member list --limit 25 --offset 25
+```
+
+The result is bounded to 25 members by default and 100 maximum. It returns
+stable member IDs that can be used with issue assignment commands. The matching
+MCP tool is `atoll_list_members`; it lists collaborators, while
+`atoll_list_agent_profiles` selects the caller identity.
+
 Full REST 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.
@@ -205,7 +220,7 @@ default. Use `--full` for the legacy full context; full mode cannot combine with
 - Compact signal groups include dependency blockers grouped by root blocker and release condition. Expected waits are suppressed for an unsatisfied dependency when the readable blocker is before its release column and there is no active stall, threatened or overdue commitment, or explicit deadline, gate, permission, or stale anomaly. An unowned backlog or Todo blocker by itself is an ordinary wait and never alerts. Actionable groups surface active stalls, threatened or overdue commitments, and explicit anomalies; escalation metadata alone does not surface an expected wait. Initiative-target and stalled aggregates are also suppressed when every underlying dependency is an expected wait. Groups can include a bounded `suggested_read` REST, CLI, or private-MCP call. Public plugin MCP keeps legacy full heartbeat behavior; private MCP supports compact heartbeat, `atoll_ack_heartbeat`, and `atoll_get_dependency_chain`.
 - `atoll heartbeat --json` includes the structured `cli` update metadata for agents, plus direct `attention`/`attention_items` and `recommended_action` when Atoll can propose one concrete strategy-backed next action. 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.
 - Authorized humans can configure an agent's included heartbeat sections and generated-signal focus in the Atoll **Heartbeats** UI. The saved policy is applied by the API before CLI or MCP request-level narrowing; it never changes project access, and existing heartbeat commands require no new arguments.
-- GitHub `workflow_run` signals are accepted only when HMAC-signed and completed, then reread and matched exactly by repository, PR, workflow path, run attempt, and head SHA. Workflow verification is disabled by default and observe-only until an owner/admin enables it in **Settings > Integrations > GitHub**. `attention` mode can add one bounded `verification.completed` attention item through authorized REST or CLI heartbeat for exactly one eligible current agent assignee or, when there is no unambiguous assignee, an eligible configured delivery agent. The public MCP heartbeat excludes this private event type. Unresolved recipients and cancelled, obsolete, superseded, mismatched, or unreadable runs create no attention. Owners and admins can configure 1–10 workflow paths of at most 255 characters each; the bounded evidence list defaults to 25 items and accepts a maximum `limit` of 100. Signed pull-request writes and reconciliation bind PR links to the stable GitHub repository ID, so repository renames keep existing workflow evidence linked. Do not expect raw payloads, secrets, logs, or thread IDs in evidence; owner/admin reconciliation retries pending evidence after current GitHub and PR-link readback.
+- GitHub `workflow_run` signals are accepted only when HMAC-signed and completed, then reread and matched exactly by repository, PR, workflow path, run attempt, and head SHA. Pull-request runs require provider PR membership. A completed `workflow_dispatch` run can have an empty PR list; Atoll requires exactly one distinct current linked PR and confirms its numeric repository IDs, PR identity, head SHA, and branch through GitHub. Several issues can link to that same PR. Ambiguous links, fork heads, changed heads, and newer runs do not produce verification. Signed nonterminal notifications are acknowledged without evidence. Manual dispatch does not emit the generic `ci.run.completed` automation trigger. Workflow verification is disabled by default and observe-only until an owner/admin enables it in **Settings > Integrations > GitHub**. `attention` mode can add one bounded `verification.completed` attention item through authorized REST or CLI heartbeat for exactly one eligible current agent assignee or, when there is no unambiguous assignee, an eligible configured delivery agent. The public MCP heartbeat excludes this private event type. Unresolved recipients and cancelled, obsolete, superseded, mismatched, or unreadable runs create no attention. Owners and admins can configure 1–10 workflow paths of at most 255 characters each; the bounded evidence list defaults to 25 items and accepts a maximum `limit` of 100. Signed pull-request writes and reconciliation bind PR links to the stable GitHub repository ID, so repository renames keep existing workflow evidence linked. Do not expect raw payloads, secrets, logs, or thread IDs in evidence; owner/admin reconciliation retries pending evidence after current GitHub and PR-link readback.
 - Release-added required GitHub hook events mark existing reconciled and already-pending connections pending. The bounded 15-minute service sweep verifies immutable repository identity and upgrades hooks automatically; transient failures remain pending for retry, and owners/admins can reconcile manually.
 - Issue delivery context is read with `atoll issue delivery-context <identifier>`; `--json` preserves `{ deliveryContext }`, while TTY output includes the full head SHA, review, actual required checks, configured verification, freshness, blocker, and partial state. The endpoint selects an open PR first, then the latest updated link, then the highest PR number. Required checks union active rulesets and classic branch protection for the base branch and use exact-head check-run/status evidence. `pending` review/workflow state with null provenance means no current-head observation and does not by itself set `partial`. Required-check collection is disabled by default; with the reader disabled, state `disabled` and aggregate `none` do not set `partial`. The server-only `ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag enables read-only provider GETs; when enabled, partial or unavailable collection or aggregate `unknown` sets `partial`. This result does not authorize merge, deployment, production testing, or human acceptance. Configured workflows report `required: false`.
 - Aggregate review state keeps each reviewer's latest exact-head opinion, ignores comments, and removes dismissed opinions. Change requests win. `approved` means at least one effective approval and no effective change request; it does not prove required-review counts or branch protection.
@@ -240,3 +255,18 @@ Rule writes, tests, and run history require owner/admin access; CLI does not byp
 rule, use separate `disable`, `update` while disabled, `test`, and `enable`
 operations. Human `get` output includes invalid state and validation paths;
 `--json` preserves the API response.
+
+### Select an Artifact source
+
+Use `--source-reference-id <uuid>` on `artifact create` or `artifact update` to
+select a canonical External Reference already in the issue's Context. The CLI
+resolves its Context link ID before saving. On update, use `--clear-source` to
+clear the new revision's source. The two flags cannot be combined. Omit both
+to inherit the current snapshot. A source-only update still requires
+`--expected-revision-id`.
+
+`artifact get` and write readback request `source_provenance_v1`; text output
+shows an authorized source link, and JSON includes `revision.source_reference`.
+Historical snapshots survive removal of the live Context link. Atoll does not
+import or synchronize the source content. Typed MCP source fields remain
+unavailable.