clawskills-mcp 0.6.0 → 0.7.0

package/dist/index.js

@@ -266,10 +266,26 @@ function searchClawskills(skills, playbooks, query) {
 // ---------------------------------------------------------------------------
 // Skill summary (first meaningful line)
 // ---------------------------------------------------------------------------
+// Playbooks open with a YAML frontmatter block; skills open with an H1 followed
+// by a blockquote. Without the frontmatter handling below, every playbook
+// summary came out as the literal "---" delimiter.
 function skillSummary(content) {
-    for (const line of content.split("\n")) {
-        const trimmed = line.trim();
-        if (trimmed && !trimmed.startsWith("#"))
+    const lines = content.split("\n");
+    let start = 0;
+    if (lines[0]?.trim() === "---") {
+        const closing = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+        if (closing !== -1) {
+            for (const line of lines.slice(1, closing)) {
+                const title = line.match(/^title:\s*(.+)$/);
+                if (title)
+                    return title[1].trim().replace(/^["']|["']$/g, "");
+            }
+            start = closing + 1;
+        }
+    }
+    for (const line of lines.slice(start)) {
+        const trimmed = line.trim().replace(/^>\s*/, "");
+        if (trimmed && trimmed !== "---" && !trimmed.startsWith("#"))
             return trimmed;
     }
     return "";

package/dist/index.test.js

@@ -271,6 +271,25 @@ describe("skillSummary", () => {
         const summary = skillSummary("# Title\n## Subtitle\n");
         expect(summary).toBe("");
     });
+    it("uses the frontmatter title instead of the --- delimiter", () => {
+        const summary = skillSummary("---\ntitle: Slack Incident -> Jira Issue\nsystems:\n  - slack\n---\n\n# Heading\n\nBody text.");
+        expect(summary).toBe("Slack Incident -> Jira Issue");
+    });
+    it("falls through past frontmatter that has no title", () => {
+        const summary = skillSummary("---\nsystems:\n  - slack\n---\n\n# Heading\n\nBody text.");
+        expect(summary).toBe("Body text.");
+    });
+    it("strips the blockquote marker from skill headers", () => {
+        const summary = skillSummary("# Jira Skill\n\n> **Last validated:** 2026-08-02\n");
+        expect(summary).toBe("**Last validated:** 2026-08-02");
+    });
+    it("gives every real playbook a summary that is not the --- delimiter", () => {
+        for (const [slug, content] of loadPlaybooks(REAL_PLAYBOOKS_DIR)) {
+            const summary = skillSummary(content);
+            expect(summary, `${slug} has no usable summary`).not.toBe("");
+            expect(summary, `${slug} summary is the frontmatter delimiter`).not.toBe("---");
+        }
+    });
 });
 // ---------------------------------------------------------------------------
 // Real skills validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",
@@ -50,11 +50,11 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.0.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }

package/playbooks/INDEX.md

@@ -9,6 +9,7 @@ Workflow playbooks are end-to-end guides for multi-system automations. They comp
 | [Zendesk Ticket -> Jira Bug escalation](./zendesk-jira-bug-escalation.md) | Zendesk, Jira | Escalate support-confirmed defects into engineering workflow |
 | [HubSpot Deal Won -> Asana onboarding kickoff](./hubspot-asana-onboarding.md) | HubSpot, Asana | Start implementation or onboarding work when a deal closes |
 | [Salesforce Lead -> HubSpot Contact sync](./salesforce-hubspot-lead-sync.md) | Salesforce, HubSpot | Mirror new/updated leads into marketing automation without duplicates |
+| [Slack Incident -> Jira Issue](./slack-jira-incident.md) | Slack, Jira | Convert in-chat incident escalations into tracked engineering work items |
 
 ## Playbook template
 
@@ -25,7 +26,6 @@ Each playbook should define:
 
 ## Next candidates
 
-- Slack incident -> Jira issue
 - GitHub PR -> Slack notification
 - Zendesk -> Salesforce case sync
 - Stripe payment failed -> HubSpot task

package/playbooks/slack-jira-incident.md

@@ -0,0 +1,113 @@
+---
+title: Slack Incident -> Jira Issue
+systems:
+  - slack
+  - jira
+tags:
+  - incident
+  - support
+  - engineering
+  - escalation
+  - on-call
+trigger_type: webhook_event
+---
+
+# Slack Incident -> Jira Issue
+
+## Goal
+
+Capture an incident discussion happening in Slack as a tracked Jira issue, so engineering, on-call, and leadership can follow resolution outside the noisy chat surface. The Slack message remains the conversation record; Jira becomes the accountable work item.
+
+## Systems involved
+
+- Slack: incident detection, real-time discussion, customer-impact reports
+- Jira: durable tracking, engineering ownership, link to postmortem
+- (Optional) PagerDuty or Opsgenie: paging — usually upstream of this playbook, not driven by it
+
+## Trigger
+
+Any of:
+- A Slack message receives a designated reaction emoji (e.g. `:jira:` or `:rotating_light:`) — fired via Slack `reaction_added` event
+- A Slack slash command (e.g. `/incident <summary>`) invoked in any channel
+- A message posted in a channel matching `incident-*` with a designated keyword prefix
+
+Reaction-based triggers are the most reliable and lowest-friction; slash commands are best when summary capture must be deliberate.
+
+## Source of truth
+
+- Incident discussion / customer-impact reports: Slack (channel + thread)
+- Engineering execution state, severity, owner, resolution: Jira
+- Linkage: Slack permalink in Jira description; Jira key replied to the Slack thread
+
+## Sequence
+
+1. Receive the inbound request — either a **Slack Events API event** (`reaction_added` or `message`) delivered as JSON with the event wrapped under an `event` object, OR a **Slash Command HTTP request** (separate endpoint, form-encoded body with `channel_id`, `user_id`, `text`, `trigger_id` at the top level — no `event` wrapper and no `event_id`). Both are signed by Slack; verify the request with `X-Slack-Signature` and `X-Slack-Request-Timestamp` (5-minute window).
+2. **Ack with HTTP 200 immediately after signature verification — on every delivery, not just retries.** Slack Events API enforces a 3-second response budget on first delivery and on retries; missing it causes Slack to redeliver the event and creates avoidable duplicate work. Hand the remaining steps off to an async worker / queue. If a retry header is present (`X-Slack-Retry-Num`), treat it as an expected duplicate signal — still ack 200 and let the dedupe step catch it. (Slash Command requests don't carry retries but still benefit from immediate ack so the user sees a fast response.)
+3. Build a deterministic correlation key: `slack:{team_id}:{channel_id}:{ts}`. The `{ts}` source depends on the trigger:
+   - **`reaction_added`:** `event.item.ts` — the timestamp of the message that was reacted to.
+   - **`message`:** `event.ts` — the original message timestamp; for replies posted into a thread, prefer `event.thread_ts` so the key anchors to the parent message and all in-thread activity collapses to one issue.
+   - **Slash Command:** no inbound `message_ts` exists. Either (a) require the command be invoked from inside a thread and use `thread_ts` from the command payload, or (b — recommended default) the async worker first posts a bot anchor message via `chat.postMessage` and uses that posted message's `ts`. Option (b) requires no user training and gives the thread reply a natural place to land.
+4. Fetch the originating message and thread context via `conversations.history` (with `latest=ts`, `inclusive=true`, `limit=1`) and `conversations.replies` for thread.
+5. Resolve `permalink` for the message via `chat.getPermalink`.
+6. Search Jira for an existing issue carrying that correlation key (label or custom field). If found, skip creation and reuse the Jira key.
+7. If no existing issue, create a Jira issue (`POST /rest/api/3/issue`) with:
+   - `summary` derived from the message text (first sentence, truncated to ~120 chars).
+   - `description` containing the Slack permalink, the message text, and up to N thread replies for context.
+   - `priority`, `issuetype`, `project`, `components` derived from per-channel config or sensible defaults.
+   - A label `slack-incident` plus the correlation key as a label or custom-field value.
+8. Reply in the Slack thread via `chat.postMessage` with the Jira issue link, key, and current assignee.
+9. (Optional) Pin the bot reply if the channel is an incident channel.
+10. (Optional) Mirror selected Jira status transitions back to Slack via `chat.postMessage` once a status mapping is finalized.
+
+## Field mapping
+
+| Slack | Jira |
+|-------|------|
+| Correlation source (varies by trigger): `reaction_added` → `event.item.channel` + `event.item.ts`; `message` → `event.channel` + `event.ts` (use `event.thread_ts` for in-thread replies); Slash Command → command payload `channel_id` + `ts` of the bot's anchor message (or `thread_ts` if invoked inside a thread) | correlation key `slack:{team_id}:{channel_id}:{ts}` stored in label / custom field |
+| message text (first sentence) | `summary` |
+| message text + thread replies + permalink | `description` — Jira Cloud REST v3 requires **ADF (Atlassian Document Format) JSON**; convert Slack text + thread replies into an ADF document (see `skills/jira/skill.md` § ADF) |
+| reactor user / slash command invoker | `reporter` (after Slack-user -> Atlassian-account-id mapping) |
+| channel name or category | `components` or labels |
+| keyword/severity from text | `priority` (P1/P2/P3) |
+| message permalink | external link field or `description` |
+
+## Idempotency
+
+- **Dedup key:** `slack:{team_id}:{channel_id}:{ts}` (same format as the correlation key in Sequence step 3) stored as a Jira label and/or a custom field for searchability.
+- Slack delivers Events API events at least once. Dedupe at the edge using the **payload field `event_id`** (present in the JSON wrapper, not an HTTP header). Slash command requests have **no `event_id`** — dedupe those by correlation key alone. Always re-dedupe by correlation key immediately before the Jira create call.
+- If multiple users react with the trigger emoji on the same message, only the first reaction creates the issue; subsequent reactions are noops (or append a reactor list to the Jira issue).
+- Slash command invocations must check correlation by `channel_id + thread_ts` first to avoid duplicating during incidents.
+
+## Retry and partial failure policy
+
+- **Slack rate limits** are per-method tier (Tier 1: 1+/min, Tier 4: 100+/min). On `429`, respect the `Retry-After` header — do not retry sooner.
+- **Jira rate limits** use cost-based throttling. On `429` or `503`, use bounded exponential backoff (base 1s, max 60s, max 5 attempts).
+- Do not blindly retry Jira `400` validation errors — log, surface to operators, and quarantine the event.
+- If Jira create succeeds but the Slack thread reply fails, do not retry Jira create. Reconcile by searching Jira for the correlation key and posting the thread reply on the next event or reconciliation pass.
+- Slack event endpoints must return 200 within 3 seconds. Push work to a queue if create + reply exceeds that budget.
+
+## Reconciliation
+
+- Hourly or daily job: scan recent messages in channels matching `incident-*` for trigger reactions/keywords and confirm a Jira issue with the matching correlation key exists. Create any missing issues.
+- Reverse pass: list Jira issues with label `slack-incident` updated in the last 24h; verify each has at least one Slack thread reply with the Jira link. Repair missing replies.
+- Drift check: confirm Jira issues marked `Done` have a corresponding Slack thread reply announcing closure (if status mirroring is enabled).
+
+## Rollback guidance
+
+- If a Jira issue was created in error, transition it to a closed/cancelled state (`Won't Do`, `Cancelled`) rather than deleting it — preserves the dedup key so an accidental re-reaction does not recreate it.
+- Remove the trigger reaction in Slack via `reactions.remove` (cosmetic) and add a `:white_check_mark:` reply explaining the cancellation.
+- Add the correlation key to a deny-list table to prevent re-creation if reactions get added again.
+
+## Observability
+
+- Time from reaction to Jira issue creation (target: < 5s p95).
+- Daily count of incidents created, by channel and by reactor.
+- Duplicate-detection rate (events that would have created duplicates but were short-circuited).
+- Failed Slack signature verifications (anomalous — investigate).
+- Failed Jira creates, broken down by HTTP status and error code.
+- Lag between Jira closure and Slack-thread closure message.
+
+## Related skills
+
+- [`skills/slack/skill.md`](../skills/slack/skill.md)
+- [`skills/jira/skill.md`](../skills/jira/skill.md)

package/skills/ROADMAP.md

@@ -19,9 +19,9 @@ This skill set enables end-to-end automation and integration across the most com
 | Layer | Status |
 |-------|--------|
 | **14 skill docs** — Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear | ✅ Live |
-| **MCP server** — `clawskills-mcp` v0.5.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.7.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
 | **CI pipeline** — build + test on every push/PR via `ci.yml` | ✅ Live |
-| **Release automation** — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |
+| **Release automation** — `prepare-release.yml` workflow_dispatch → release PR; `release.yml` on merge → npm publish via OIDC + tag | ✅ Live |
 | **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 14 tools) | ✅ Live |
 | **Public repo readiness** — MIT license, `.gitignore`, full `package.json` metadata | ✅ Ready |
 
@@ -83,7 +83,7 @@ The repo now needs tighter alignment between the canonical `skills/` directory,
 | Channel | Status | Next action |
 |---------|--------|-------------|
 | GitHub (public) | Ready to flip | Make repo public |
-| npm (`clawskills-mcp`) | ✅ Live — v0.5.0 | Maintain via `release.yml` |
+| npm (`clawskills-mcp`) | ✅ Live — v0.7.0 | Maintain via `release.yml` |
 | MCP registry listings | Not submitted | Submit to glama.ai, mcp.so, smithery.ai after public launch |
 | Docs website | Planned | Mintlify — fastest path to SEO-friendly browsable docs |
 | Lane A vs B | TBD | Revisit after first traction signals from public launch |
@@ -175,18 +175,19 @@ Each skill/recipe is scored on five dimensions (1–5 each):
 - **Freshness pipeline:** Weekly cron checks `Last validated:` dates (see Priority 2 above).
 - **Live smoke tests:** Optional phase B — weekly auth + read tests against sandboxes.
 - **Breaking change monitoring:** Subscribe to each vendor's developer changelog:
-  - Monday: https://developer.monday.com/changelog
-  - Salesforce: https://help.salesforce.com/s/articleView?id=release-notes.salesforce_release_notes.htm
+  - Monday: https://developer.monday.com/api-reference/docs/api-versioning (versioning table) + https://developer.monday.com/changelog (entries)
+  - Salesforce: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/rest_rns.htm — ⚠️ JS-rendered: the content body is injected client-side, so plain HTTP fetchers (curl, wget, GitHub Actions cron jobs without a JS engine) return only the page shell. Read it in a real browser, or use a headless-browser tool (Playwright/Puppeteer) — see https://github.com/Shanksg/clawskills/issues/12.
+    - **Workaround (found 2026-08-02):** https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_versions.htm **is** plain-fetchable and lists the highest published API version with its release name. That covers "did a new version ship?" — the most common freshness question — without a browser. Only the delta review still needs one.
   - Jira: https://developer.atlassian.com/cloud/jira/platform/changelog/
-  - Dynamics 365: https://learn.microsoft.com/en-us/dynamics365/release-plans/
+  - Dynamics 365: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/web-api-versions (Web API version differences) + https://learn.microsoft.com/en-us/dynamics365/released-versions/microsoft-dataverse (weekly release notes)
   - HubSpot: https://developers.hubspot.com/changelog
-  - ServiceNow: https://developer.servicenow.com/dev.do
-  - Zendesk: https://developer.zendesk.com/api-reference/ticketing/introduction/#api-changelog
-  - Asana: https://developers.asana.com/docs/changelog
-  - GitHub: https://github.blog/changelog/
-  - Figma: https://www.figma.com/developers/api#changelog
-  - Slack: https://api.slack.com/changelog
-  - Stripe: https://stripe.com/docs/changelog
+  - ServiceNow: https://www.servicenow.com/docs/bundle/australia-release-notes/page/release-notes/family-release-notes.html (current named release — rotate this URL on each new release; https://www.servicenow.com/docs/r/release-notes/available-versions.html lists which family is current)
+  - Zendesk: https://developer.zendesk.com/api-reference/changelog/changelog/
+  - Asana: https://forum.asana.com/c/forum-en/api/api-change-log/204 — Asana hosts their dated API changelog as a forum category (individual entries are threads under it); the developer-portal page just redirects here
+  - GitHub: https://github.blog/changelog/ (entries) + https://docs.github.com/en/rest/about-the-rest-api/breaking-changes (per-version breaking-change list — the fetchable source of truth for REST API versions)
+  - Figma: https://developers.figma.com/docs/rest-api/changelog/ (moved from `figma.com/developers/api#changelog`, which now redirects)
+  - Slack: https://docs.slack.dev/changelog (moved from `api.slack.com/changelog`, which now redirects)
+  - Stripe: https://docs.stripe.com/changelog (moved from `stripe.com/docs/changelog`, which now redirects)
   - Notion: https://developers.notion.com/page/changelog
   - Linear: https://linear.app/changelog
 
@@ -202,7 +203,11 @@ Each skill/recipe is scored on five dimensions (1–5 each):
 - PRs to `skill.md` files require: (a) reference to official doc, (b) tested curl/pseudocode example, (c) updated `Last validated:` date.
 - Branch convention: `skill/<toolname>` → PR → merge to main.
 - CI runs `npm test` on every PR — validates skill loads and has all required sections.
-- Releases: merge to main, then GitHub Actions → **Release** → Run workflow → pick `patch / minor / major`.
+- Releases (two stages — `main` is protected, so nothing can be pushed to it directly):
+  1. GitHub Actions → **Prepare Release** → Run workflow → pick `patch / minor / major`. Opens a `release/vX.Y.Z` PR with the version bump; publishes nothing.
+  2. Merge that PR. **Release** publishes to npm via OIDC and tags `vX.Y.Z`.
+
+  > `release.yml` must keep that exact filename — npm's trusted publisher config pins it. Renaming it breaks publishing with a 404.
 
 ---
 

package/skills/asana/skill.md

@@ -1,8 +1,25 @@
 # Asana Skill
 
-> **Last validated:** 2026-02-19 | **API:** Asana REST API 1.0
+> **Last validated:** 2026-08-02 | **API:** Asana REST API 1.0
 > **REST base URL:** `https://app.asana.com/api/1.0`
 > **Assumed product:** Asana cloud. Enterprise controls, SCIM, and admin APIs may require additional scopes and plan-specific access.
+>
+> **⚠️ Changes since 2026-02-19:**
+> - **Out of Office API (2026-04-27):** new endpoints replace the legacy `vacation_dates` field, which is now **deprecated** on the user object. Migrate any code that reads/writes `vacation_dates`.
+> - **RBAC Role API (2026-02-27):** new CRUD endpoints for managing custom roles on Enterprise plans.
+> - **Timesheet Approval Status API (2026-03-20)** and **Categories for Time Tracking Entries (2026-04-01):** new time-tracking primitives — useful for ops/finance workflows.
+> - **Project portfolio + advanced project search APIs (2026-03-23):** new endpoints for portfolio settings and advanced project filtering.
+> - **Custom Types in Memberships (2026-03-31):** memberships endpoints now support custom-type filters.
+> - **Goals API (2026-04-06):** goals now expose privacy settings, default access levels, and stories.
+> - **Enhanced filtering on the Search API (2026-04-06):** custom task types now usable as filter dimensions.
+>
+> **⚠️ Changes since 2026-05:**
+> - **Granular RBAC permissions (2026-07-02):** finer-grained role-based access control, extending the Role API above.
+> - **AI Studio Usage API (2026-07-02):** new endpoint for tracking AI Studio consumption.
+> - **`sort_by=relevance` on project search (2026-06-04):** relevance ordering now available alongside the existing sort options.
+> - **AI teammates / agent API support announced (2026-05-28)** — not yet GA; no action required, but expect new actor types on tasks and stories.
+>
+> **Source:** https://forum.asana.com/c/forum-en/api/api-change-log/204
 
 ## What this skill enables
 

package/skills/dynamics365/skill.md

@@ -1,8 +1,11 @@
 # Microsoft Dynamics 365 Skill
 
-> **Last validated:** 2026-02-19 | **API:** Dataverse Web API (OData v4) v9.2
+> **Last validated:** 2026-08-02 | **API:** Dataverse Web API (OData v4) v9.2
 > **Base URL:** `https://{org-name}.crm.dynamics.com/api/data/v9.2/`
 > **Assumed product:** Dynamics 365 Sales. Other apps (Customer Service, Field Service) share the same Web API pattern.
+>
+> **Note:** Re-confirmed on 2026-08-02: v9.0, v9.1, and v9.2 still have identical Web API behavior with no breaking changes. No v9.3 or v10 announced. The 2026 release waves are PowerApps/Copilot features, not Web API surface changes. Microsoft's own guidance is to pin the version that was current when you wrote the code and test before moving up, rather than tracking the newest automatically.
+> **Source:** https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/web-api-versions (page revision 2026-03-27)
 
 ---
 

package/skills/figma/skill.md

@@ -1,9 +1,16 @@
 # Figma Skill Reference
 
-**Last validated:** 2026-02-22
+**Last validated:** 2026-08-02
 **API version:** REST API v1 (stable) | Webhooks V2 (stable) | Pin `X-Figma-Api-Version` not required — versioning is path-based (`/v1/`, `/v2/`)
 **Base URL:** `https://api.figma.com` (Government: `https://api.figma-gov.com`)
 
+> **New since 2026-02:**
+> - **Plan access tokens — GA July 23, 2026.** Organization- and Enterprise-plan tokens that are **not tied to an individual user account**, with expiry up to one year and optional allowlists, managed by plan admins. This is now the recommended credential for CI/CD and org automation — it survives the token owner leaving the company, which personal access tokens do not. See Authentication below.
+> - **oEmbed API — March 25, 2026.** `oEmbed 1.0`-spec endpoint returning metadata for Figma files and published Makes. Requires the `file_metadata:read` scope.
+> - **AI Usage API — June 12, 2026.** Enterprise-only endpoint returning per-user, per-day AI credit usage. Requires the `org:ai_metering_usage_read` scope and a plan access token.
+>
+> **Docs moved:** the developer docs are now at `developers.figma.com/docs/rest-api/`; the old `figma.com/developers/api` URL redirects there.
+
 > **Breaking changes to be aware of:**
 > - **Nov 17, 2025** — New tiered rate limits in effect; rate limits now vary by plan (Starter/Professional/Organization/Enterprise) and seat type (View/Collab vs Dev/Full).
 > - **May 28, 2025** — Webhooks V2 major update: webhooks now attach to teams, files, or projects. `GET /v2/teams/:team_id/webhooks` deprecated → use `GET /v2/webhooks`. `DEV_MODE_STATUS_UPDATE` event added.
@@ -90,7 +97,18 @@ Variables are scoped to a collection. Types: `BOOLEAN`, `COLOR`, `FLOAT`, `STRIN
 
 ## Authentication & permissions
 
-### Option 1 — Personal Access Token (PAT) [recommended for server-to-server]
+### Option 1 — Plan access token [recommended for org automation and CI/CD, GA 2026-07-23]
+
+Organization- and Enterprise-plan only. Created and managed by plan admins, **not tied to a user account**, so the token keeps working when the person who created it leaves. Supports expiry up to one year and optional allowlists restricting where it can be used.
+
+```bash
+curl https://api.figma.com/v1/me \
+  -H "X-Figma-Token: YOUR_PLAN_ACCESS_TOKEN"
+```
+
+Same `X-Figma-Token` header as a PAT — only the provenance and lifecycle differ. Prefer this over a PAT for anything running unattended: a PAT dies with its owner's account, which is the most common cause of silently broken Figma automations.
+
+### Option 2 — Personal Access Token (PAT) [scripts and local tooling]
 
 Generate at **Figma → Account Settings → Personal access tokens**.
 Set an expiry (required since 2024) and select scopes at creation time.
@@ -100,7 +118,9 @@ curl https://api.figma.com/v1/me \
   -H "X-Figma-Token: YOUR_PAT"
 ```
 
-### Option 2 — OAuth 2.0 [recommended for user-facing apps]
+> On Organization/Enterprise plans, use a plan access token for shared automation and keep PATs for individual development work.
+
+### Option 3 — OAuth 2.0 [recommended for user-facing apps]
 
 **Authorization URL:**
 ```