rsc-universal 0.1.1

package/skills/instagram-api/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: instagram-api
+description: "Use when wiring an agent into Instagram's Graph API to publish a Reel from a video URL, pull per-media insights (reach, views, watch-time, saves, shares, total_interactions), check the 24-hour publish cap, or ingest Reel performance into 02-DOCS/wiki/shortform. Triggers: 'publish this Reel via the API', 'pull reach and average watch time for these media IDs', 'why does /insights?metric=plays return an error', 'my container is stuck IN_PROGRESS', 'how many posts left in the 24h publish window', 'publica este Reel por la API', 'ingesta el rendimiento dels Reels al wiki'. NOT TikTok publishing (that is tiktok-api), NOT a posting calendar/cadence (that is social-publisher), NOT YouTube uploads/stats (that is youtube-api)."
+tags: [instagram, graph-api, content-publishing, reels, insights, shortform]
+recommends: [tiktok-api, youtube-api, social-publisher, shortform-strategy, api-connector-builder]
+origin: risco
+---
+
+# instagram-api
+
+The wire between an agent and Instagram's Graph API: publish Reels, pull the metrics that still exist, and write them to the wiki. You speak HTTP, OAuth scopes, container IDs, and metric names. You do not decide what to post, write the caption's voice, or cut the video — route those out.
+
+All facts below are pinned to **Graph API v25.0** (current as of 2026-06-02). When you generate code, pin the version explicitly; Meta breaks metrics on version boundaries.
+
+## When to use / when NOT
+
+| The ask | Route |
+|---|---|
+| Publish a Reel from a public `video_url` to an IG professional account | **here** |
+| Pull reach / views / watch-time / saves / shares for media IDs | **here** |
+| `/insights?metric=plays` (or `impressions`) suddenly errors | **here** (deprecation trap) |
+| Check the 24h publish cap before a batch | **here** |
+| Long-lived token exchange / refresh, scope wiring | **here** |
+| Post the same clip to **TikTok** | `tiktok-api` |
+| Upload to **YouTube** / pull YouTube stats | [`youtube-api`](../youtube-api/SKILL.md) |
+| Cadence, best-time, multi-platform calendar | [`social-publisher`](../social-publisher/SKILL.md) |
+| What to make / shortform content strategy | `shortform-strategy` |
+| Hook, cuts, on-screen captions | [`video-shorts`](../video-shorts/SKILL.md) |
+| Generic OAuth/webhook plumbing not IG-specific | `api-connector-builder` |
+
+## Prereqs & auth
+
+You cannot publish from a personal account. Confirm these before writing any call.
+
+- **IG professional account** (Business or Creator). Why: the publishing and insights endpoints reject personal accounts outright.
+- **Auth path + host** — pick one and stay on it:
+  - Facebook Login for Business → IG account linked to a FB Page → host `graph.facebook.com`.
+  - Instagram Login (direct) → host `graph.instagram.com`.
+  Why: the host is not interchangeable per call; mixing tokens and hosts throws auth errors.
+- **Scopes (current names):** `instagram_business_content_publish` to publish, `instagram_business_manage_insights` to read metrics. Why: the old `instagram_basic` / `instagram_content_publish` were deprecated 2025-01-27 and silently grant nothing now.
+- **Long-lived token = 60 days**, refreshable before expiry. A short-lived user token lasts ~1h. Why: anything in a script needs the long-lived token or it dies within the hour.
+
+Env block — generate code that reads these, never hard-code the token:
+
+```bash
+export IG_USER_ID="17841400000000000"      # the IG professional account id (NOT the page id)
+export IG_ACCESS_TOKEN="EAAG...long-lived"  # 60-day token, refresh before expiry
+export GRAPH_VERSION="v25.0"                # pin it — never blank
+export GRAPH_HOST="graph.facebook.com"      # or graph.instagram.com for IG Login
+```
+
+## Publish a Reel — the 3-step container dance
+
+Publishing is never one call. It is create → poll → publish. Skipping the poll is the #1 failure.
+
+**Step 1 — create the container.** `video_url` must be a publicly reachable MP4 (no auth header, no signed-URL-that-expires-in-30s) for the entire processing window.
+
+```bash
+curl -s -X POST "https://$GRAPH_HOST/$GRAPH_VERSION/$IG_USER_ID/media" \
+  -d "media_type=REELS" \
+  -d "video_url=https://cdn.example.com/clip.mp4" \
+  -d "caption=Shipped it." \
+  -d "share_to_feed=true" \
+  -d "access_token=$IG_ACCESS_TOKEN"
+# -> {"id":"17999999999999999"}   <- this is the CONTAINER id, not a published post
+```
+
+**Step 2 — poll status until `FINISHED`.** Meta recommends ~once per minute, ceiling ~5 minutes.
+
+```bash
+curl -s "https://$GRAPH_HOST/$GRAPH_VERSION/$CONTAINER_ID?fields=status_code,status" \
+  -d "access_token=$IG_ACCESS_TOKEN"
+# -> {"status_code":"FINISHED", ...}
+```
+
+**Step 3 — publish.** Only after `FINISHED`.
+
+```bash
+curl -s -X POST "https://$GRAPH_HOST/$GRAPH_VERSION/$IG_USER_ID/media_publish" \
+  -d "creation_id=$CONTAINER_ID" \
+  -d "access_token=$IG_ACCESS_TOKEN"
+# -> {"id":"17888888888888888"}   <- THIS is the published media id
+```
+
+A compact Python helper that does the whole dance:
+
+```python
+import os, time, requests
+
+HOST = os.environ["GRAPH_HOST"]
+VER  = os.environ["GRAPH_VERSION"]          # v25.0 — pinned
+UID  = os.environ["IG_USER_ID"]
+TOK  = os.environ["IG_ACCESS_TOKEN"]
+BASE = f"https://{HOST}/{VER}"
+
+def publish_reel(video_url: str, caption: str) -> str:
+    cid = requests.post(f"{BASE}/{UID}/media", data={
+        "media_type": "REELS", "video_url": video_url,
+        "caption": caption, "share_to_feed": "true",
+        "access_token": TOK,
+    }).json()["id"]
+
+    for _ in range(10):                      # ~5 min ceiling at 30s steps
+        st = requests.get(f"{BASE}/{cid}", params={
+            "fields": "status_code", "access_token": TOK,
+        }).json()["status_code"]
+        if st == "FINISHED":
+            break
+        if st in ("ERROR", "EXPIRED"):
+            raise RuntimeError(f"container {cid} -> {st}")
+        time.sleep(30)
+    else:
+        raise TimeoutError(f"container {cid} never reached FINISHED")
+
+    return requests.post(f"{BASE}/{UID}/media_publish", data={
+        "creation_id": cid, "access_token": TOK,
+    }).json()["id"]
+```
+
+```text
+Bad:  publish immediately after create -> "Media ID is not available" / silent fail.
+Good: poll status_code until FINISHED, then media_publish.
+
+Bad:  video_url behind auth or a 30s signed URL -> container stalls in ERROR.
+Good: a plain public MP4 that stays reachable for the full ~5 min window.
+```
+
+## Status polling rules
+
+`status_code` is the only honest signal. Branch on it, do not guess from timing.
+
+| `status_code` | Meaning | Action |
+|---|---|---|
+| `IN_PROGRESS` | Still transcoding | Keep polling (~60s) |
+| `FINISHED` | Ready | Call `media_publish` now |
+| `ERROR` | Failed (bad url, bad codec, eligibility) | Stop; read `status`, fix source |
+| `EXPIRED` | Container unpublished too long | Stop; recreate from step 1 |
+
+Why the 5-min ceiling: containers expire. If you poll forever you will eventually publish an `EXPIRED` id and get an error. Cap retries.
+
+## Limits — check before a batch
+
+| Rule | How |
+|---|---|
+| **50 API-published posts per rolling 24h** per IG account | `GET /{IG_USER_ID}/content_publishing_limit?fields=quota_usage,config` |
+| Over the cap | `media_publish` rejects with **error subcode #51** ("publishing limit reached") |
+
+```bash
+curl -s "https://$GRAPH_HOST/$GRAPH_VERSION/$IG_USER_ID/content_publishing_limit?fields=quota_usage" \
+  -d "access_token=$IG_ACCESS_TOKEN"
+# -> {"data":[{"quota_usage": 12, "config": {"quota_total": 50}}]}
+```
+
+Why check first: in a batch, hitting #51 mid-run leaves half your queue unpublished and no clean resume point. Read `quota_usage` and stop early.
+
+## Fetch insights
+
+```bash
+curl -s "https://$GRAPH_HOST/$GRAPH_VERSION/$IG_MEDIA_ID/insights" \
+  -d "metric=reach,views,likes,comments,shares,saved,total_interactions,ig_reels_avg_watch_time,ig_reels_video_view_total_time" \
+  -d "access_token=$IG_ACCESS_TOKEN"
+```
+
+**Valid Reels metric set (v25.0):** `reach`, `views`, `likes`, `comments`, `shares`, `saved`, `total_interactions`, `ig_reels_avg_watch_time`, `ig_reels_video_view_total_time` (plus optional `crossposted_views`, `facebook_views`, `reposts`). Why a fixed list: the metric set differs by media type (feed / story / reels), and one invalid name fails the **whole** call — not just that field.
+
+**Units trap:** the API returns `ig_reels_avg_watch_time` and `ig_reels_video_view_total_time` in **milliseconds**, not seconds. Store the raw value verbatim (suffix the key `_ms`) so the artifact matches the API, or divide by 1000 at ingest and rename to `_s` — never label a raw millisecond value "seconds". A 7.4s avg watch arrives as `7400`.
+
+## The deprecated-metric trap
+
+Requesting any retired metric does not return null — it **400s the entire insights call**. Map old → new before you send.
+
+| Deprecated | Replacement | Deprecated on |
+|---|---|---|
+| `plays` | `views` | 2025-04-21 (v22.0 + all versions) |
+| `clips_replays_count` | — (removed) | 2025-04-21 |
+| `ig_reels_aggregated_all_plays_count` | `views` | 2025-04-21 |
+| `impressions` | `views` / `reach` | gone for media created after 2024-07-02 |
+| `video_views` | `views` | 2025-01-08 |
+| `profile_views` (media) | — | 2025-03-25 |
+
+If a previously-working call started erroring, this table is almost certainly why: a metric you used to request was retired on a version boundary. Swap to `views` and drop the dead names.
+
+## Ingest into 02-DOCS/wiki/shortform/
+
+This is the checkable deliverable. One file per media id, idempotent overwrite (re-running a pull refreshes `pulled_at` and metrics, never duplicates).
+
+- **Path:** `02-DOCS/wiki/shortform/ig-reel-<media_id>.md`
+- **Naming:** always `ig-reel-` prefix + the published media id (not the container id).
+- **Re-runs:** overwrite the same file in place — the media id is the natural key.
+
+```markdown
+---
+platform: instagram
+media_type: REELS
+media_id: "17888888888888888"
+permalink: "https://www.instagram.com/reel/Cxxxxxx/"
+published_at: "2026-05-30T09:12:00Z"
+graph_version: v25.0
+pulled_at: "2026-06-02T08:00:00Z"
+metrics:
+  reach: 41200
+  views: 58800
+  total_interactions: 3120
+  saved: 410
+  shares: 220
+  ig_reels_avg_watch_time_ms: 7400        # raw API value — MILLISECONDS (avg per view)
+  ig_reels_video_view_total_time_ms: 435120000 # raw API value — MILLISECONDS (summed)
+---
+
+# Reel 17888888888888888
+
+Performance snapshot pulled from Graph API v25.0. Metric set is the
+current valid Reels set; no deprecated names requested.
+```
+
+Why front-matter + media-id filename: the wiki is queried by key, and re-pulls must be diffable, not additive.
+
+## Migration & gotchas
+
+- **Scopes:** replace `instagram_basic` → `instagram_business_basic`, `instagram_content_publish` → `instagram_business_content_publish`. Old names grant nothing post-2025-01-27.
+- **Host:** chosen by login path, not per call. Do not send a `graph.instagram.com` token to `graph.facebook.com`.
+- **Token:** refresh the 60-day long-lived token before expiry; expired tokens fail every call with an auth error, not a 404.
+- **Reel eligibility:** 9:16, 5–90s, H.264/HEVC. A non-conforming source surfaces as container `ERROR`, not a clean validation message.
+- **New 2025–2026 metrics** (Reels skip rate, repost counts, crossposted views): optional and version-gated. Confirm they exist on `GRAPH_VERSION` before requesting, or they trip the same 400 trap.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Publish right after `media` create | Container isn't `FINISHED`; publish errors | Poll `status_code` first |
+| Requesting `plays` / `impressions` | 400s the whole insights call | Use `views`; consult the trap table |
+| Leaving `GRAPH_VERSION` blank / using default | Metric set silently shifts on Meta's rollout | Pin `v25.0` in every call |
+| Signed/auth-gated `video_url` | Container stalls in `ERROR` | Plain public MP4 for the full window |
+| Batch publishing without cap check | Hit #51 mid-run, half-published queue | `content_publishing_limit` before the loop |
+| Old scopes (`instagram_basic`) | Grant nothing since 2025-01-27 | `instagram_business_*` scopes |
+| Storing the container id as "the post" | It's not the published media id | Persist the `media_publish` id |
+
+## References
+
+- `references/publish-reel.md` — full container field reference (reels / carousel / story), cover & thumb handling, error codes, retry/backoff, batch publish with cap check.
+- `references/insights-metrics.md` — complete current metric tables per media type, the full deprecated→replacement map with dates, version-gated 2025–2026 additions, and the `02-DOCS/wiki/shortform/` ingest schema spec.

package/skills/instagram-api/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — instagram-api
+
+These cases are prompts scored against the skill's `description` by an LLM router. `should_trigger` prompts must route to `instagram-api`; `should_not_trigger` prompts must route to the named sibling (`tiktok-api`, `social-publisher`, `youtube-api`, `video-shorts`) and never here. The `capability` case is graded by hand against its `must_include` rubric on a real generated flow — feed the scenario to the agent, then check the output covers the container dance (`media_type=REELS` → poll `status_code` to `FINISHED` → `media_publish`), an insights pull that uses only valid (non-deprecated) metrics, the `content_publishing_limit` check, a pinned `GRAPH_VERSION`, and a written artifact under `02-DOCS/wiki/shortform/`. No automated runner ships with this skill: run it by feeding each prompt to the router, confirming routing, and scoring the capability rubric manually. `scripts/verify.sh` separately lints generated artifacts/scripts for deprecated metric tokens, the three publish steps, and a pinned version.

package/skills/instagram-api/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: instagram-api
+
+should_trigger:
+  - prompt: "Publish this Reel from a video URL to our IG professional account via the API"
+    why: Core publish flow — the 3-step container dance on the Graph API.
+  - prompt: "Pull reach and average watch time for these Instagram media IDs"
+    why: Core insights read using the valid Reels metric set.
+  - prompt: "My /insights call started returning an error when I ask for metric=plays"
+    why: Non-obvious — the deprecated-metric trap; plays was retired 2025-04-21, swap to views.
+  - prompt: "How many posts do we have left in the 24-hour Instagram publish window?"
+    why: content_publishing_limit check before a batch; the 50/24h cap.
+  - prompt: "Ingesta el rendimiento de los Reels en el wiki de shortform"
+    why: Spanish — ingest IG performance into 02-DOCS/wiki/shortform, the checkable artifact.
+  - prompt: "My media container is stuck IN_PROGRESS and never publishes"
+    why: Non-obvious — status_code polling and the EXPIRED/ERROR branch, IG-specific.
+
+should_not_trigger:
+  - prompt: "Post this same clip to TikTok via their Content Posting API"
+    route_to: tiktok-api
+    why: TikTok publishing is a different platform connector.
+  - prompt: "Build me a weekly multi-platform posting calendar across IG, TikTok and YouTube"
+    route_to: social-publisher
+    why: Cadence and cross-channel scheduling, not IG API mechanics.
+  - prompt: "Upload this video to YouTube and get its view stats"
+    route_to: youtube-api
+    why: YouTube Data API uploads and stats live in the YouTube connector.
+  - prompt: "Write the hook and on-screen captions for this Reel"
+    route_to: video-shorts
+    why: Editing and scripting the asset, not posting it.
+
+capability:
+  - scenario: >
+      Given a public video_url, a caption, and an IG_USER_ID, produce the end-to-end
+      publish-then-measure flow plus a wiki artifact under 02-DOCS/wiki/shortform/.
+    must_include:
+      - "container create with media_type=REELS and the public video_url"
+      - "poll status_code until FINISHED (with ERROR/EXPIRED handling and a ~5min ceiling)"
+      - "media_publish using creation_id, persisting the returned published media id"
+      - "insights pull using only valid metrics (reach, views, ig_reels_video_view_total_time, saved, shares, total_interactions)"
+      - "no deprecated metrics requested (no plays / impressions / clips_replays_count)"
+      - "content_publishing_limit check before batch publishing"
+      - "GRAPH_VERSION pinned to v25.0 in every call"
+      - "artifact written to 02-DOCS/wiki/shortform/ig-reel-<media_id>.md with front-matter (media_id, permalink, published_at, graph_version, pulled_at, metrics)"

package/skills/instagram-api/references/insights-metrics.md

@@ -0,0 +1,88 @@
+# Insights reference — metrics by media type, deprecations, ingest schema
+
+Endpoint: `GET /{ig-media-id}/insights?metric=<comma,list>` on Graph API **v25.0**.
+One invalid metric name fails the entire call (HTTP 400), so build the list per media type.
+
+## Valid metric sets (v25.0)
+
+### Reels
+
+`reach`, `views`, `likes`, `comments`, `shares`, `saved`, `total_interactions`,
+`ig_reels_avg_watch_time`, `ig_reels_video_view_total_time`.
+
+Optional / version-gated: `crossposted_views`, `facebook_views`, `reposts`.
+
+- `ig_reels_avg_watch_time` — average watch time per view, **milliseconds** (convert if you report seconds).
+- `ig_reels_video_view_total_time` — summed watch time across views, **milliseconds**.
+
+### Feed (image / video / carousel)
+
+`reach`, `views`, `likes`, `comments`, `shares`, `saved`, `total_interactions`,
+`profile_visits`, `follows` (availability varies by media type).
+
+### Stories
+
+`reach`, `views`, `replies`, `shares`, `total_interactions`, `navigation`
+(navigation breaks down to taps forward/back/exit via `breakdown` param).
+
+### Account-level (`GET /{ig-user-id}/insights`)
+
+`reach`, `follower_count`, `profile_views`, `accounts_engaged`, `total_interactions`
+with required `metric_type` / `period` params. Different surface from per-media — do not mix.
+
+## Deprecated → replacement (do not request)
+
+| Deprecated metric | Use instead | Deprecated on |
+|---|---|---|
+| `plays` (reels) | `views` | 2025-04-21 — v22.0 and all versions |
+| `clips_replays_count` | — removed | 2025-04-21 |
+| `ig_reels_aggregated_all_plays_count` | `views` | 2025-04-21 |
+| `impressions` | `views` / `reach` | 2025-04-21 (errors for media created on/after 2024-07-02) |
+| `video_views` | `views` | 2025-01-08 |
+| `profile_views` (per-media) | account-level only | 2025-03-25 |
+| story / carousel `impressions` | `reach` / `views` | 2025-01-08 |
+
+Symptom of requesting any of these: the whole `/insights` call returns a 400, not a partial result.
+
+## Version-gated 2025–2026 additions
+
+Added late 2025 / early 2026; present only on recent versions. Confirm against `GRAPH_VERSION` before requesting, or they trip the same 400:
+
+- Reels **skip rate** / swipe-away signal.
+- **Repost** counts (`reposts`).
+- **Crossposted** Reel views (`crossposted_views`, `facebook_views`).
+
+## Wiki ingest schema — `02-DOCS/wiki/shortform/`
+
+One file per published media id. Idempotent: re-pulls overwrite the same file (media id is the key).
+
+- **Filename:** `ig-reel-<media_id>.md`
+- **Format:** YAML front-matter + a short human-readable body.
+
+```markdown
+---
+platform: instagram          # always "instagram" for this skill
+media_type: REELS            # REELS | IMAGE | CAROUSEL | STORIES
+media_id: "<published media id>"   # NOT the container id
+permalink: "<https permalink>"
+published_at: "<ISO 8601 UTC>"
+graph_version: v25.0         # the version the pull ran on
+pulled_at: "<ISO 8601 UTC>"  # refreshed every re-run
+metrics:                     # only valid, non-deprecated names
+  reach: <int>
+  views: <int>
+  total_interactions: <int>
+  saved: <int>
+  shares: <int>
+  ig_reels_avg_watch_time_ms: <int>          # raw API value, MILLISECONDS
+  ig_reels_video_view_total_time_ms: <int>   # raw API value, MILLISECONDS
+---
+
+# Reel <media_id>
+
+One-paragraph note: which valid metric set was pulled and on which graph_version.
+```
+
+Required keys: `platform`, `media_type`, `media_id`, `published_at`, `graph_version`, `pulled_at`, `metrics`. The `metrics` block must contain only current metric names — verify.sh greps for deprecated tokens and a pinned `graph_version`.
+
+**Watch-time units:** `ig_reels_avg_watch_time` and `ig_reels_video_view_total_time` are returned by the API in **milliseconds** (see the metric notes above). Persist them raw under `_ms`-suffixed keys, matching the wire value. If you instead report seconds, divide by 1000 at ingest and rename to a `_s` suffix — do not keep the API key name while silently changing the unit.

package/skills/instagram-api/references/publish-reel.md

@@ -0,0 +1,98 @@
+# Publishing reference — containers, fields, errors, batching
+
+All endpoints on `https://{GRAPH_HOST}/{GRAPH_VERSION}/...` with `GRAPH_VERSION=v25.0`.
+
+## Container fields by media type
+
+### Reels (`media_type=REELS`)
+
+| Field | Required | Notes |
+|---|---|---|
+| `media_type` | yes | Literal `REELS` |
+| `video_url` | yes | Public MP4, reachable for the whole processing window |
+| `caption` | no | Up to 2200 chars; hashtags/mentions allowed |
+| `share_to_feed` | no | `true` shows the Reel in the main feed grid too |
+| `cover_url` | no | Public image URL for the cover frame |
+| `thumb_offset` | no | Milliseconds into the video for the auto-cover (ignored if `cover_url` set) |
+| `location_id` | no | A Page id usable as a location tag |
+
+### Single image / feed (`media_type` omitted or `IMAGE`)
+
+Use `image_url` instead of `video_url`. No `share_to_feed`.
+
+### Stories (`media_type=STORIES`)
+
+`video_url` or `image_url`; no `caption`. Expires after 24h. Insights metric set differs (see insights-metrics.md).
+
+### Carousel (two-stage)
+
+1. Create each child container with `is_carousel_item=true` (+ `image_url`/`video_url`).
+2. Create the parent: `media_type=CAROUSEL`, `children=<id1>,<id2>,...`, optional `caption`.
+3. Poll the parent's `status_code`, then `media_publish` the parent `creation_id`.
+
+Why the extra stage: children must each finish before the parent can be published.
+
+## Status codes
+
+`GET /{container-id}?fields=status_code,status` returns one of:
+
+- `IN_PROGRESS` — keep polling (~60s cadence).
+- `FINISHED` — publish now.
+- `ERROR` — read `status` for the reason; do not retry the same source blindly.
+- `EXPIRED` — container sat unpublished too long; recreate from step 1.
+
+Poll ceiling ~5 minutes. Containers are not permanent.
+
+## Common error subcodes on publish
+
+| Subcode | Meaning | Fix |
+|---|---|---|
+| 51 | 24h publish limit reached (50/account) | Wait or read `content_publishing_limit` |
+| 9007 | Media not ready / not `FINISHED` | Poll until `FINISHED` first |
+| 2207003 | Media download failed | Make `video_url` truly public |
+| 2207026 | Unsupported video format | Re-encode H.264/HEVC, 9:16, 5–90s |
+
+## Retry / backoff snippet
+
+```python
+import time, requests
+
+def wait_finished(base, cid, tok, max_tries=10, step=30):
+    for _ in range(max_tries):
+        st = requests.get(f"{base}/{cid}",
+                          params={"fields": "status_code", "access_token": tok}
+                          ).json()["status_code"]
+        if st == "FINISHED":
+            return
+        if st in ("ERROR", "EXPIRED"):
+            raise RuntimeError(f"{cid} -> {st}")
+        time.sleep(step)
+    raise TimeoutError(f"{cid} never FINISHED")
+```
+
+## Batch publish with cap check
+
+```python
+def remaining_quota(base, uid, tok):
+    d = requests.get(f"{base}/{uid}/content_publishing_limit",
+                     params={"fields": "quota_usage,config", "access_token": tok}
+                     ).json()["data"][0]
+    return d.get("config", {}).get("quota_total", 50) - d.get("quota_usage", 0)
+
+def publish_batch(base, uid, tok, jobs):
+    published = []
+    for video_url, caption in jobs:
+        if remaining_quota(base, uid, tok) <= 0:
+            break  # stop cleanly; don't trip subcode 51
+        cid = requests.post(f"{base}/{uid}/media", data={
+            "media_type": "REELS", "video_url": video_url,
+            "caption": caption, "access_token": tok}).json()["id"]
+        wait_finished(base, cid, tok)
+        mid = requests.post(f"{base}/{uid}/media_publish",
+                            data={"creation_id": cid, "access_token": tok}
+                            ).json()["id"]
+        published.append(mid)
+    return published
+```
+
+Check the cap *inside* the loop, not once before — each publish consumes one slot.

package/skills/instagram-api/scripts/verify.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# verify.sh — instagram-api
+# Read-only, offline, deterministic lint of generated IG Graph API artifacts/scripts.
+# Exits 0 on a clean OR empty target (no false failure). Non-zero only on a real violation.
+#
+# Checks:
+#   1. No deprecated metric tokens REQUESTED in code/config (the trap names are
+#      plays / clips_replays_count / ig_reels_aggregated_all_plays_count and a
+#      bare "impressions" used as a metric value).
+#   2. If a publish script is present, it references all 3 steps: /media, status_code, /media_publish
+#   3. GRAPH_VERSION (or graph_version) is pinned, not blank
+#
+# Usage: verify.sh [TARGET_DIR]   (default: current directory)
+#
+# The skill's OWN source files (this dir) document the deprecated-metric trap
+# in prose and in eval prompts; they are not emitted artifacts, so they are
+# skipped. The lint is therefore trustworthy even when the target workspace
+# contains a checked-out copy of this skill.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory; nothing to check."
+  exit 0
+fi
+
+# Absolute path of THIS skill's root (scripts/ -> skill dir). Files inside it are
+# skill source (SKILL.md, references, evals, this script), never emitted output.
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Files worth scanning: scripts, configs, and ingested wiki artifacts.
+# Portable across bash 3.2 (macOS) — no mapfile; newline-delimited list.
+FILES=()
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  # Skip this skill's own source tree: it documents the trap on purpose.
+  abs="$(cd "$(dirname "$f")" 2>/dev/null && pwd)/$(basename "$f")"
+  case "$abs" in
+    "$SELF_DIR"/*) continue ;;
+  esac
+  FILES+=("$f")
+done < <(
+  find "$TARGET" -type f \
+    \( -name '*.sh' -o -name '*.py' -o -name '*.js' -o -name '*.ts' \
+       -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.md' \
+       -o -name '*.env' -o -name '.env' \) \
+    2>/dev/null
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "verify: no candidate files under '$TARGET'; clean by default."
+  exit 0
+fi
+
+fail=0
+
+note_fail() { echo "FAIL: $1"; fail=1; }
+
+# --- Check 1: deprecated metric tokens ---------------------------------------
+# We only flag metrics actually REQUESTED in emitted code/config, not prose that
+# merely names them. A request context is a `metric=` / `"metric":` parameter
+# whose value contains a deprecated token. This is scoped to artifact/code files;
+# the skill's own SKILL.md (which documents the trap) is not an emitted artifact.
+DEP='plays|clips_replays_count|ig_reels_aggregated_all_plays_count|impressions'
+# A real request context, NOT prose. The `metric` token must sit at a genuine
+# request boundary — start of line, a URL query delim (? or &), an opener
+# (quote / { / ( / =), or a curl flag (-d / --data) — so an English sentence like
+# "why does metric=impressions error?" (preceded by the word "does ") is ignored.
+# It must then be a metric=value / "metric":"value" param whose comma-separated
+# value list contains a deprecated token as a WHOLE field (the dep token ends the
+# field), so mid-word matches like "displays" or "impressions_rate" don't trip.
+REQ_LEAD='(^|[?&{("'"'"']|=|-d |--data[ =]|--data-urlencode )'
+REQ_CTX="${REQ_LEAD}metric[\"' ]*[:=][\"' ]*([a-z0-9_]+,)*(${DEP})([,\"' &]|$)"
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.sh|*.py|*.js|*.ts|*.json|*.yaml|*.yml|*.env|.env) ;;
+    *) continue ;;  # skip free-prose .md docs; they may legitimately name the trap
+  esac
+  if grep -nEi "$REQ_CTX" "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      note_fail "deprecated metric requested in $f: $line"
+    done < <(grep -nEi "$REQ_CTX" "$f")
+  fi
+done
+
+# Wiki artifacts (.md / .yaml) store metrics as YAML keys. Flag a deprecated
+# token used AS a metric key (e.g. "  plays: 123"), which won't match prose.
+KEY_CTX="^[[:space:]]+(${DEP})[[:space:]]*:"
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.md|*.yaml|*.yml) ;;
+    *) continue ;;
+  esac
+  if grep -nE "$KEY_CTX" "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      note_fail "deprecated metric key in artifact $f: $line"
+    done < <(grep -nE "$KEY_CTX" "$f")
+  fi
+done
+
+# --- Check 2: publish scripts must reference all 3 steps ----------------------
+# Only applies to executable code (.sh/.py/.js/.ts) that calls media_publish —
+# not to prose/yaml docs that merely mention it.
+for f in "${FILES[@]}"; do
+  case "$f" in
+    *.sh|*.py|*.js|*.ts) ;;
+    *) continue ;;
+  esac
+  if grep -qE 'media_publish' "$f" 2>/dev/null; then
+    grep -qE '/media([^_]|$|")' "$f" 2>/dev/null || note_fail "publish script $f missing the create step (/media)"
+    grep -qE 'status_code'      "$f" 2>/dev/null || note_fail "publish script $f missing the status poll (status_code)"
+    # media_publish is present by definition of entering this branch.
+  fi
+done
+
+# --- Check 3: GRAPH_VERSION pinned, not blank --------------------------------
+# Only enforce in files that actually mention the version variable.
+for f in "${FILES[@]}"; do
+  if grep -qiE 'GRAPH_VERSION|graph_version' "$f" 2>/dev/null; then
+    # Flag an explicit blank/empty assignment.
+    if grep -nEi 'GRAPH_VERSION[[:space:]]*[=:][[:space:]]*("")?[[:space:]]*$' "$f" >/dev/null 2>&1; then
+      while IFS= read -r line; do
+        note_fail "GRAPH_VERSION unpinned (blank) in $f: $line"
+      done < <(grep -nEi 'GRAPH_VERSION[[:space:]]*[=:][[:space:]]*("")?[[:space:]]*$' "$f")
+    fi
+  fi
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify: violations found."
+  exit 1
+fi
+
+echo "verify: OK — no deprecated metrics, publish steps complete, version pinned."
+exit 0