@damiangilgonzalez/harness 1.3.7

package/skills/init/references/recommend-skills.md

@@ -0,0 +1,115 @@
+# Recommend Skills — the skill map, sample printouts & the "siempre 3 opciones" pattern
+
+Phase 3 detail. Map discovery to individual rsc skills, print the exact
+`npx @damiangilgonzalez/harness add` commands, and run the requirements-first 3-option decision pattern
+for any significant choice. A skill **cannot install anything** — it recommends
+and prints commands the user runs.
+
+## The skill map
+
+| Discovery signal | Skills | One-line *why* (adapt to level) |
+| --- | --- | --- |
+| Always (every project) | `harness` | The control plane — scaffolds and governs the whole workspace (`suggest` installs with it as the floor). |
+| Backend / API / database | `fastapi` or `go`, `postgresdb` | The server, the API, the database that remembers things. |
+| Web or mobile UI | `nextjs` or `flutter`, `design` | The screens people actually see and tap. |
+| Marketing / landing / decks / teaching | `marketing`, `presentations`, `course-storytelling` | The words, slides, and lessons that explain and sell it. |
+| AI agents | `building-agents` | Agents that use tools and reason over your data. |
+| Security & shipping / ops (incl. non-code company harness connecting tools) | `secure-coding`, `deployment` | Ship it safely and wire up the external tools (email, payments, hosting). |
+
+Recommend a skill **only if discovery justified it** — same discipline as "no
+speculative tools". Don't recommend `building-agents` because agents are trendy;
+recommend it because the user said they want an agent.
+
+Note on the non-code harness: a company/ops/research/content harness almost
+always wants `harness` (the structure) + `deployment`/`secure-coding` (to connect
+external tools and handle credentials securely), and often `marketing`. It
+usually does NOT want `fastapi`/`nextjs` unless they're also building software.
+
+## What to print
+
+One `npx @damiangilgonzalez/harness add` line per recommendation (or batch them on one line), each with
+its *why* in the user's language and level.
+
+```text
+npx @damiangilgonzalez/harness add <skill> [<skill> ...]
+```
+
+### Sample printout — software, full-stack web app with marketing
+
+```text
+Based on what you described (a web app with a backend, a Next.js UI, a landing
+page, and you want to ship it securely), install these:
+
+npx @damiangilgonzalez/harness add harness        # the control plane — scaffolds and governs the workspace
+npx @damiangilgonzalez/harness add fastapi postgresdb   # the API and the database
+npx @damiangilgonzalez/harness add nextjs design  # the web UI people see
+npx @damiangilgonzalez/harness add marketing      # the words for your landing page
+npx @damiangilgonzalez/harness add secure-coding deployment   # ship it safely
+
+Once they're installed, run the harness skill and I'll build the project structure.
+```
+
+### Sample printout — non-code harness, running an agency's operations
+
+```text
+You're organizing how your agency runs — client emails, contracts, invoicing,
+and you want it all findable. That's a non-code harness; install:
+
+npx @damiangilgonzalez/harness add harness        # your 01-TOOLS (connections) + docs (your second brain)
+npx @damiangilgonzalez/harness add secure-coding deployment   # connect email, payments, drive — and keep credentials safe
+npx @damiangilgonzalez/harness add marketing      # for the proposals, decks and copy you send clients
+
+Once installed, run the harness skill and I'll set up the structure that holds it all.
+```
+
+### Sample printout — greenfield AI agent
+
+```text
+You want an AI agent that answers questions over your own documents. Install:
+
+npx @damiangilgonzalez/harness add harness            # the control plane
+npx @damiangilgonzalez/harness add building-agents    # agent loops, tools, RAG
+npx @damiangilgonzalez/harness add fastapi postgresdb # an API + database to serve it
+npx @damiangilgonzalez/harness add secure-coding deployment   # ship it safely
+
+Then run the harness skill.
+```
+
+## The "siempre 3 opciones" decision pattern
+
+For any significant decision — deploy target, database, framework, hosting, which CRM, where documents live — never decide silently and never dump ten choices. Four steps:
+
+### 1. Gather the driving requirements first
+
+Ask the questions that actually change the answer. Match question count/depth to `accompaniment_level` (L0: only hard blockers; L3: ask all, explaining why each matters). Checklists per decision type:
+
+- **Deploy target:** expected number of users; concurrent users; budget; data region / residency rules; the team's comfort operating servers; scaling needs (steady vs spiky); existing org/cloud constraints.
+- **Database:** data shape (relational vs documents vs key-value); expected size and growth; query patterns; consistency vs scale needs; managed vs self-hosted preference; budget.
+- **Framework / language:** team's existing skills; the surfaces needed; performance constraints; ecosystem/libraries required; hiring/longevity.
+- **Where knowledge/documents live (non-code harness):** volume and formats; who needs access; privacy / residency of client data; search needs; existing tools already paid for.
+
+### 2. Present EXACTLY three options
+
+Three, with honest trade-offs — what each is good at, what it costs, what it demands. Not two (false binary), not ten (paralysis). If a fourth is genuinely worth knowing, mention it in one line under the third — but the choice is between three.
+
+### 3. Recommend one, matched to their answers AND their level
+
+State your recommendation and why, in language they understand. At L3 / non-technical, explain each option in plain terms and check they followed before they pick.
+
+### 4. Log the decision
+
+Once they choose, append an entry to `docs/wiki/harness/decisions.md` (format in `accompaniment-and-profile.md`): context (the requirements you gathered), the three options, the decision, and why.
+
+## Canonical worked example — deploy target
+
+Requirements gathered: ~500 users, ~20 concurrent, low budget, EU data residency required, small team comfortable with a little server work, steady (non-spiky) traffic.
+
+> **Option 1 — Hetzner VPS + Coolify.** Cheapest by far (a capable box is a few euros a month), total control, and Hetzner has EU regions so residency is covered. The catch: you self-manage the server — updates, backups, keeping it up. Coolify makes deploys push-button, but the box is yours.
+>
+> **Option 2 — Vercel.** Zero-ops: you push, it deploys, it scales itself, nothing to maintain. The catch: it gets expensive as you grow, and you're shaped by its model (best for frontend/serverless; data residency and always-on backends need care).
+>
+> **Option 3 — Fly.io.** Managed containers that run in an EU region close to your users, simpler than raw cloud, more hands-off than a VPS. The catch: a bit pricier than Hetzner and you still think in containers.
+>
+> **Recommendation:** Option 1 (Hetzner + Coolify, EU region). Your budget is tight, EU residency is a hard requirement Hetzner satisfies cleanly, traffic is steady so you don't need autoscaling, and your team is fine managing one box. We log this and move on; if ops ever becomes a burden, Option 3 is the easy step up.
+
+This decision triggers the `deployment` skill at build time, which knows Hetzner+Coolify, Vercel, Fly.io and the rest in depth. `init` makes the choice and records it; `deployment` executes it.

package/skills/init/scripts/verify.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# verify.sh — bootstrap gate for the `init` skill.
+#
+# WHAT IT DOES (read-only; never edits or creates a file)
+#   Static checks that Phase 1 (PROFILE) actually landed in the workspace:
+#     1. docs/wiki/harness/user-profile.md exists and carries technical_level
+#        and accompaniment_level lines.
+#     2. docs/wiki/harness/decisions.md exists (append-only decisions log).
+#     3. Root CLAUDE.md exists and its "## Knowledge map" section links the profile.
+#   Everything is detect-or-skip: a missing workspace piece is a WARNING, never a
+#   failure — `init` may simply not have run yet. The script never fails the build;
+#   it only reports. (No --strict mode: this is a presence check, not a CI gate.)
+#
+# HOW TO RUN (inside YOUR workspace, not the skills repo)
+#   ./verify.sh                 # check ./ for the profile + Knowledge-map link
+#   ./verify.sh --path some/dir # check a different workspace root
+#
+# EXIT CODES
+#   0  always, unless usage is wrong (this is a warn-only presence check)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no process
+# substitution; arrays avoided; everything POSIX-ish under `set -euo pipefail`.
+
+set -euo pipefail
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..24), stripping the leading "# "
+  sed -n '2,24p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+ROOT="."
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    ROOT="${2:?--path needs a value}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$ROOT" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$ROOT" "$NC"; exit 2
+fi
+
+PROFILE="$ROOT/docs/wiki/harness/user-profile.md"
+DECISIONS="$ROOT/docs/wiki/harness/decisions.md"
+CLAUDE_MD="$ROOT/CLAUDE.md"
+
+# has <file> <pattern>: true if a non-empty file contains a case-insensitive match.
+has() {
+  [ -s "$1" ] || return 1
+  grep -iq -e "$2" "$1" 2>/dev/null
+}
+
+printf 'Checking init PROFILE artifacts under: %s\n\n' "$ROOT"
+
+# --- 1. user profile --------------------------------------------------------
+if [ ! -s "$PROFILE" ]; then
+  warn "no user profile at docs/wiki/harness/user-profile.md — run init's PROFILE phase first"
+else
+  ok "user profile present: $PROFILE"
+  if has "$PROFILE" 'technical_level'; then
+    ok "profile records technical_level"
+  else
+    warn "profile is missing a technical_level line"
+  fi
+  if has "$PROFILE" 'accompaniment_level'; then
+    ok "profile records accompaniment_level"
+  else
+    warn "profile is missing an accompaniment_level line"
+  fi
+fi
+
+# --- 2. decisions log -------------------------------------------------------
+if [ ! -s "$DECISIONS" ]; then
+  warn "no decisions log at docs/wiki/harness/decisions.md — significant decisions should be appended here"
+else
+  ok "decisions log present: $DECISIONS"
+fi
+
+# --- 3. CLAUDE.md Knowledge map link ----------------------------------------
+if [ ! -s "$CLAUDE_MD" ]; then
+  warn "no root CLAUDE.md — init should create it with a '## Knowledge map' section"
+else
+  ok "root CLAUDE.md present"
+  if has "$CLAUDE_MD" '## *Knowledge map'; then
+    ok "CLAUDE.md has a '## Knowledge map' section"
+    if has "$CLAUDE_MD" 'user-profile.md'; then
+      ok "Knowledge map links the user profile"
+    else
+      warn "Knowledge map does not link docs/wiki/harness/user-profile.md"
+    fi
+  else
+    warn "CLAUDE.md has no '## Knowledge map' section linking the profile"
+  fi
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d\n' "$ok_count" "$skip_count" "$warn_count"
+
+cat <<'EOF'
+
+Note: every finding is a presence WARNING, not a failure. If init has not run yet,
+warnings are expected. Run init's PROFILE phase, then re-run this check.
+EOF
+
+exit 0

package/skills/instagram-api/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: instagram-api
+description: "Use when wiring an agent into Instagram's Graph API: publishing a Reel through the create/poll/publish container dance, reading per-media insights, checking the 24h publish cap, or ingesting Reel metrics into docs/wiki/shortform. NOT TikTok (that is `tiktok-api`), NOT YouTube (that is `youtube-api`), NOT cross-platform cadence (that is `social-publisher`)."
+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.
+
+## Route out
+
+| The ask | Skill |
+|---|---|
+| 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.
+```
+
+Full container field reference (reels / carousel / story), cover & thumb handling, error codes, retry/backoff, and batch publish with cap check → `references/publish-reel.md`.
+
+## 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.
+
+Complete current metric tables per media type, the full deprecated→replacement map with dates, version-gated 2025–2026 additions, and the `docs/wiki/shortform/` ingest schema spec → `references/insights-metrics.md`.
+
+## Ingest into 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:** `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
+---
+type: instagram-metrics
+title: "Reel 17888888888888888"
+description: Performance snapshot for one Instagram Reel, pulled from Graph API v25.0.
+tags: [instagram, reels, insights, shortform]
+timestamp: "2026-06-02T08:00:00Z"
+topic: shortform
+status: stable
+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.
+```
+
+`type` is the only required OKF v0.1 field; `title`/`description`/`tags`/`timestamp` are the recommended OKF surface (`timestamp` mirrors the pull instant). The DOMAIN keys below are mandatory and stay byte-for-byte — `verify.sh` requires a pinned `graph_version` and greps the `metrics` block for deprecated names; `pulled_at` is the API-pull instant verify/diff rely on. Keep both `pulled_at` and `timestamp`. Why front-matter + media-id filename: the wiki is queried by key, and re-pulls must be diffable, not additive (the idempotent overwrite re-stamps `timestamp` and `pulled_at` together).
+
+## 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`, `instagram_content_publish`) | Grant nothing since 2025-01-27 | `instagram_business_basic` / `instagram_business_content_publish` |
+| Storing the container id as "the post" | It's not the published media id | Persist the `media_publish` id |
+| Sending a `graph.instagram.com` token to `graph.facebook.com` | Host is fixed by the login path, not chosen per call | Pick the host with the auth path and stay on it |
+| Letting the 60-day long-lived token lapse | Every call fails with an auth error, not a 404 | Refresh before expiry |
+| A source video outside Reel eligibility | Surfaces as container `ERROR`, not a clean validation message | 9:16, 5–90s, H.264/HEVC |
+| Requesting the 2025–2026 additions (Reels skip rate, repost counts, crossposted views) blind | Version-gated — trips the same 400 trap as a deprecated name | Confirm they exist on `GRAPH_VERSION` first |

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 `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 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 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 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,95 @@
+# 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 — `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
+---
+type: instagram-metrics      # required OKF v0.1 field (non-empty)
+title: "Reel <media_id>"     # OKF recommended surface
+description: Performance snapshot for one Instagram Reel, pulled from Graph API v25.0.
+tags: [instagram, reels, insights, shortform]
+timestamp: "<ISO 8601 UTC>"  # OKF last-edit; re-stamped each re-run alongside pulled_at
+topic: shortform
+status: stable
+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.
+```
+
+`type` is the only required OKF v0.1 field; the rest of the OKF surface (`title`, `description`, `tags`, `timestamp`) is recommended. Required DOMAIN keys (kept byte-for-byte): `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`. `pulled_at` (the API-pull instant) and the OKF `timestamp` are re-stamped together on each idempotent overwrite — keep both.
+
+**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.