@atollhq/skill-claude 0.4.38 → 0.4.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.38",
+  "version": "0.4.39",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"

package/skill/SKILL.md

@@ -73,6 +73,9 @@ Read only the references required for the current task:
   resume contracts remain separate.
 - Remote MCP setup, GitHub repository and External Reference tools, AI-assisted setup, KPI HTTP sync, or advanced REST access:
   [integrations-and-api.md](references/integrations-and-api.md)
+- Completed manual GitHub workflow dispatches require one current linked PR and
+  canonical same-repository head and branch proof. Nonterminal notifications
+  create no evidence; manual dispatch does not trigger generic CI automation.
 - GitHub pull-request delivery context, required checks, and exact-head evidence:
   [api-fields.md](references/api-fields.md#external-operational-delivery-context)
   A `plan_restricted` required-check error is actionable plan-unavailable
@@ -237,3 +240,187 @@ explicit. Do not add project-specific workflow keys as universal instructions.
   private paths, prompts, logs, or raw sensitive payloads.
 - Publication, deployment, production mutation, destructive deletion, and
   external communication require the authority applicable to the current task.
+
+### MCP project events
+
+Modern public OAuth MCP clients can monitor `issue.status_changed`, `attention.created`, and `execution.state_changed`. Each subscription requires an accessible project UUID; discover the live workflow before choosing status filters. Resolve `profile_ref` as for tools. ChatGPT manages callback verification, finite grants, refresh, and unsubscribe through `events/*` protocol methods. API-key/private/stdio clients use tools and Heartbeat. Payloads are compact immutable snapshots; fetch full current state with read tools. No replay is provided.
+
+### Atoll Command Center MCP App
+
+The public plugin offers an app-only global `atoll.open` entrypoint with empty
+arguments. A supporting host opens a read-only Command Center for attention,
+Heartbeat, executions, projects and issues. Select an authorized profile in the
+app; selection is local to that app instance and every business read carries its
+opaque `profile_ref`. Browsing does not write. The 110 model-facing business
+tools and modern MCP Events remain available. Full/private and stdio omit the
+UI entrypoint.
+
+
+Explicit project/issue selection uses official model context in supporting hosts.
+Selection/deselection/clear and profile changes update context. Navigation and
+hydration never add or promote context. Authorization cleanup removes known
+stale or inaccessible Atoll references and their owned summary, preserves other
+valid selections and foreign content, and offers retry if removal fails.
+A stale pending update is reconciled to the latest external host snapshot;
+failed preservation warns and offers explicit retry without an update loop. `structuredContent.atoll` contains `source: "atoll"`, `version:
+1`, opaque `profile_ref`, and compact project/issue `entities` with stable UUIDs,
+display identity and already-loaded workflow labels. Read current details with
+existing tools under that profile before acting. Saved labels are not authority.
+Restoration loads identity first; detail reads are lazy and authorized. Unknown
+or malformed Atoll context and foreign host content remain intact. Unsupported
+hosts label selection local. No prompt, message, draft or Atoll write is sent.
+
+
+OpenAI deep links use the same canonical app routes: `/`,
+`/projects/<uuid>`, `/issues/<uuid>`, `/attention/<uuid>`,
+`/executions/<uuid>`. Resolve with the explicitly selected authorized
+`profile_ref`; a link is identity, not permission. Invalid shapes/UUIDs are
+rejected before reads; unavailable entities never trigger a silent profile
+search. Navigation does not add Model-App Context. Atoll issue/project web
+surfaces show Open in ChatGPT only when the deployment has the explicit public
+build-time `NEXT_PUBLIC_ATOLL_PLUGIN_ID`. Never guess this published ID or
+confuse it with OAuth/marketplace configuration. Web URLs target global
+`atoll.open` and encode the complete canonical path once. Keep normal Atoll
+URLs for unsupported hosts (including Android). Local synthetic-ID tests do
+not prove published-plugin setup or authenticated provider acceptance.
+
+## Composer mentions (desktop)
+
+In supported ChatGPT desktop Composer surfaces, use `@` to find authorized
+issues, projects, human and agent members, goals, KPIs and initiatives. Search
+uses currently authorized OAuth connection profiles, not a global or default
+actor. Exact display names and authorized human issue identifiers such as
+`AH-123` precede loose name matches. Empty queries return a bounded first page;
+search does not download a full directory.
+
+The app-only, read-only `search_mentions` extension accepts `{ "query": "text" }`
+and returns `{ "items": [...] }` with standard MCP ResourceLinks. Results show
+type, organization, profile and available project context. Identical entities
+under different profiles keep separate links so the follow-up actor stays clear.
+It is separate from the 110 ordinary business tools and `atoll.open`.
+
+Resources use `atoll://profiles/<opaque-profile-ref>/<entity-kind>/<UUID>`, where
+entity kind is `issues`, `projects`, `members`, `goals`, `kpis` or `initiatives`.
+Reads validate the current grant and entity permission under that exact profile.
+Malformed routes, revoked profiles and inaccessible records fail without trying
+another actor. Resource text contains concise identity and current state,
+including `profile_ref`; it excludes long descriptions, histories and secrets.
+Fetch current details with the same profile before acting. Mention discovery and
+resource reads do not write Atoll records or alter sidebar Model-App Context.
+
+The full/private MCP profile omits this host-specific extension. Normal typed
+list tools remain available in both profiles. Provider publication and signed-in
+desktop `@` selection are separate acceptance steps; local protocol tests do not
+prove that provider flow. No mobile workaround is included.
+
+## 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.
+
+## Native interactive issue creation
+
+Use plugin-only `atoll_create_issue_interactive` only when the user asks to choose
+or confirm fields in native forms. Pass explicit `profile_ref`. Supporting
+registered desktop hosts require protocol 2026-07-28 MRTR, standard form
+elicitation and the OpenAI rich-form extension. Unsupported hosts use ordinary
+`atoll_create_issue` with complete values. Cancel/decline/invalid/expired state
+creates nothing. Final confirmation rechecks profile, project, live workflow,
+milestone and searched assignees, then sends one canonical create. Do not retry
+an uncertain outcome; reconcile the original issue first. Deterministic creation
+keeps its existing required title and behavior. No mobile workaround or client
+deployment secret is needed.
+
+Milestone lists accept optional `q`, `q_exact`, `limit`, `offset` and envelope
+shape under the existing project endpoint. They filter/page in the database and
+preserve progress/status counts. Old absent-option REST/MCP calls stay unpaged;
+CLI keeps its old request when no new options are supplied.
+
+
+### Conversation Working Set
+
+Open the app-only `atoll.working_set` thread entrypoint with `{}` in a supported
+host. Search authorized issues/projects and add local pins. Add/remove is local;
+explicit selection shares one active canonical Atoll reference through the
+existing context controller. Active requires accepted shared context; unsupported
+or failed sharing stays local. Removing a pin does not deselect shared context;
+unpinned references retain explicit Deselect/Clear selection controls.
+Status/priority/assignees refresh through existing reads; dependencies/activity
+are lazy. In-panel **Open details** preserves same-instance pins. Profile changes
+clear pins and fence old reads. Recreated panels rebuild from current authorized
+context only; unshared pins are ephemeral. No thread ID, persistent record,
+transcript request, automatic message or Atoll write is added. Native provider
+acceptance remains separate from controlled-host evidence.
+
+Artifact source provenance is available through web, REST, and private CLI.
+Create/revise accepts `source_external_reference_link_id`; revise omission
+inherits and null clears. Add `projection=source_provenance_v1` on Artifact
+create/revise or single-revision GET to read an authorized immutable source.
+Default REST and typed MCP Artifact output remain unchanged. See the Artifact
+field reference for target authorization and unlink semantics.
+
+## 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.
+
+## Compact Context discovery
+
+Use `atoll context list --issue ATOLL-42 --json` or `--project project-slug`
+before loading detail. Full/private MCP exposes `atoll_list_context` with exactly
+one issue/project UUID. Inspect authority, freshness, current revision/SHA, and
+safe summaries; follow each group cursor with the same target/limit and deduplicate
+by item ID. Load only the needed existing Artifact, reference, or delivery detail.
+See [Context fields](references/api-fields.md#compact-context-index).
+The public index and delivery-detail tools remain unavailable pending AH-3067
+and release of the public tool freeze. Existing public Artifact and reference
+reads are unchanged. Evidence never implies a later delivery or acceptance gate.

package/skill/references/api-endpoints.md

@@ -1052,6 +1052,11 @@ The default new-agent local path (without `setupAgentMemberId`) atomically creat
 
 ## GitHub Integration
 
+The signed workflow receiver acknowledges nonterminal notifications without
+evidence. Completed manual dispatches require one current linked PR and
+canonical repository, PR, head, and branch proof; they do not emit generic
+`ci.run.completed` automation events.
+
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/github-connections` | List GitHub connections (owner/admin) |
@@ -1162,3 +1167,111 @@ do not grant project/repository access. Intake is read-only locally; hosted
 Workspace Settings → Runners owns pause/resume. See the CLI local-runner guide.
 
 Automation rule create/update accepts the core action set including one `create_issue` per rule. See [Automation Rule Fields](api-fields.md#automation-rule-fields) for required fields, original-issue targets, replay results, and external-event limits.
+
+### MCP Events adapter (OAuth plugin only)
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| POST | `/api/mcp-events/subscriptions` | Create or refresh a verified project-scoped MCP webhook subscription |
+| DELETE | `/api/mcp-events/subscriptions` | Idempotently unsubscribe the resolved OAuth connection/profile and callback identity |
+
+These endpoints support MCP `events/*` methods and have no CLI or ordinary tool equivalent. API-key credentials are rejected.
+
+## 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.
+
+### Native forms and bounded milestone reads
+
+- Plugin `atoll_create_issue_interactive`: standard elicitation/create MRTR with
+  official OpenAI rich schema, explicit profile and final create confirmation;
+  normal deterministic tool remains available. No separate REST mutation route.
+- POST `/api/orgs/{id}/issues`: optional canonical UUID Idempotency-Key header;
+  consumed identity409, invalid header400, ordinary absent-header calls unchanged.
+- GET `/api/orgs/{id}/projects/{projectId}/milestones`: optional q/q_exact/limit/offset
+  and envelope; database-filtered page with calculated progress/status counts.
+  Old calls keep the unpaged milestones alias. Project read permission applies.
+
+Artifact source provenance is available through web, REST, and private CLI.
+Create/revise accepts `source_external_reference_link_id`; revise omission
+inherits and null clears. Add `projection=source_provenance_v1` on Artifact
+create/revise or single-revision GET to read an authorized immutable source.
+Default REST and typed MCP Artifact output remain unchanged. See the Artifact
+field reference for target authorization and unlink semantics.
+
+### Vercel deployment observations
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| GET | `/api/orgs/{id}/integrations/vercel` | Human owner/admin safe connection and mapping list |
+| PUT | `/api/orgs/{id}/integrations/vercel` | Validate and save team credentials and a mapping with version fencing |
+| DELETE | `/api/orgs/{id}/integrations/vercel` | Disable, erase credentials, preserve observation history |
+| POST | `/api/orgs/{id}/integrations/vercel/reconcile` | Bounded recovery of one page per mapping/environment |
+| POST | `/api/webhooks/vercel/{connectionId}` | Raw-body HMAC-SHA1 verified Vercel callback; no bearer authentication |
+
+Management requires a signed-in human owner/admin; API keys cannot use it.
+Callback verification uses `x-vercel-signature`. Invalid signatures return 401;
+unsupported events return 200 skipped; replay/identity/snapshot conflicts return
+409; provider or storage failure returns a safe 503 code. No secrets or raw
+provider payloads are returned. Provider access is authenticated GET-only.
+Safe management CLI/MCP parity is deferred under the current public tool freeze;
+it is tracked separately from generic External Reference reads.
+
+## Compact Context
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| GET | `/api/orgs/{id}/issues/{issueId}/context` | Authorized bounded issue Context |
+| GET | `/api/orgs/{id}/projects/{projectId}/context` | Authorized bounded directly linked project Context |
+
+Optional group, limit (1–25, default 5), and group-bound cursor. Details stay lazy.
+See the Compact Context index field reference. Full/private `atoll_list_context`
+only; public parity remains freeze-gated under AH-3067.

package/skill/references/api-fields.md

@@ -1122,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`
@@ -1366,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
@@ -1472,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:
@@ -220,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.
@@ -255,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.

package/skill/references/platform-rules.md

@@ -59,7 +59,7 @@ Full endpoint tables and field schemas:
 | Tasks | POST `.../issues` | GET `.../issues` | PATCH `.../issues/{id}` | DELETE `.../issues/{id}` † |
 | Goals | POST `.../goals` | GET `.../goals` | PATCH `.../goals/{id}` | DELETE `.../goals/{id}` |
 | KPIs | POST `.../kpis` | GET `.../kpis` | PATCH `.../kpis/{id}` | DELETE `.../kpis/{id}` |
-| Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` optional; required for guests) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
+| Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` required for guests unless `scope=accessible_projects`; scope cannot combine with project) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
 | Milestones | POST `.../milestones` | GET `.../milestones` | PATCH `.../milestones/{id}` | DELETE `.../milestones/{id}` |
 | Artifacts | POST `.../artifacts` | GET `.../artifacts` or `.../artifacts/{id}/revisions/{revisionId}` | POST `.../artifacts/{id}/revisions` or `.../links` | DELETE `.../artifacts/{id}/links/{linkId}` |
 | Comments | POST `.../comments` with `{ body, mentions?, reply_to_comment_id?, source_metadata? }` | GET `.../comments` or `.../comments/{id}` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |