@damiangilgonzalez/harness 1.3.7

package/skills/linkedin-api/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: linkedin-api
+description: "Use when wiring an app to LinkedIn's organic Posts / Community Management API — 3-legged OAuth, publishing text, article or document posts to a member profile or company page, and pulling impressions, engagement and follower stats into a durable feedback record. NOT writing the post copy (that is `linkedin-content`), NOT planning cadence (that is `linkedin-strategy`), NOT DM sequences (that is `linkedin-outreach`)."
+tags: [linkedin, social-api, oauth, community-management-api, analytics, connector]
+recommends: [api-connector-builder, webhooks, analytics, knowledge-ops]
+origin: risco
+---
+
+# LinkedIn API: publish and pull analytics over the wire
+
+You own the **transport**. Auth headers, scopes, URNs, request shapes, rate-limit handling, token refresh, and the write that turns post performance into a durable feedback log. You do **not** decide what to post or why.
+
+**Decision line:** if the question is *which HTTP call, which header, which scope, which URN, how do I store the numbers* → you. If it is about the *meaning* of the content → a sibling.
+
+- Words, hooks, CTA for one post → `linkedin-content` (planned sibling).
+- Cadence, pillars, audience plan → `linkedin-strategy` (planned sibling).
+- The multi-slide PDF artifact → `linkedin-carousels` (planned sibling) builds it; you only upload the resulting document URN.
+- DMs, connection requests, sequences → `linkedin-outreach` (planned sibling).
+- Generic OAuth2 / webhook scaffolding with no LinkedIn specifics → `../api-connector-builder/SKILL.md`, `../webhooks/SKILL.md`.
+
+## Prereqs: app + products + scopes
+
+You configure this on the LinkedIn Developer portal once, before any code runs.
+
+1. Create a developer app, associate it with a company page (required to request org products).
+2. On the **Products** tab, request the product that grants the scopes you need:
+   - **Share on LinkedIn** → grants `w_member_social` (default-grantable, post as the member).
+   - **Community Management API** / **Marketing Developer Platform (MDP)** → grants the organization scopes and member-read. These require approval — the app sits in a review queue.
+3. Add your exact **redirect URI** under Auth. It must match the one in the authorize URL byte-for-byte or the callback fails.
+
+| Scope | Grants | Product needed | Page-role requirement |
+|---|---|---|---|
+| `w_member_social` | post/comment/like as the authed member | Share on LinkedIn | none |
+| `r_member_social` | read the member's own posts | restricted — approved apps only | none |
+| `w_organization_social` | post on behalf of an org | Community Management / MDP | ADMINISTRATOR, CONTENT_ADMIN, or DIRECT_SPONSORED_CONTENT_POSTER on the page |
+| `r_organization_social` | read org posts/stats | Community Management / MDP | same role set |
+
+> "unauthorized scope `w_organization_social`" at the consent screen does not mean a typo — it means the app's Community Management / MDP product is **not yet approved**. The fix is product approval, not code.
+
+## Step 1 — 3-legged OAuth
+
+Authorization-code flow. Two endpoints:
+
+```text
+GET  https://www.linkedin.com/oauth/v2/authorization   # send the user here
+POST https://www.linkedin.com/oauth/v2/accessToken     # exchange code -> token
+```
+
+Send the user to authorize with `response_type=code`, your `client_id`, `redirect_uri`, a CSRF `state`, and space-separated `scope`. On callback, exchange the `code`:
+
+```bash
+curl -X POST https://www.linkedin.com/oauth/v2/accessToken \
+  -d grant_type=authorization_code \
+  -d code="$AUTH_CODE" \
+  -d redirect_uri="$LINKEDIN_REDIRECT_URI" \
+  -d client_id="$LINKEDIN_CLIENT_ID" \
+  -d client_secret="$LINKEDIN_CLIENT_SECRET"
+```
+
+Access tokens are short-lived (~60 days). Marketing / Community apps can be issued **refresh tokens** — store the refresh token and exchange it (`grant_type=refresh_token`) before expiry. Why: re-prompting consent on every expiry breaks unattended publishing and looks broken to the user.
+
+```text
+Bad:  client_secret = "WPL_AP1.abc..."            # committed in source
+Good: client_secret = process.env.LINKEDIN_CLIENT_SECRET   # injected at runtime, file gitignored
+```
+
+Never write the token or secret into a tracked file. `scripts/verify.sh` greps for committed `client_secret=` and `AQED`-style token literals and fails the build if it finds one.
+
+## Step 2 — resolve the author URN
+
+Every post needs an `author`. Two shapes:
+
+- Member: `urn:li:person:{id}` (the `sub` from the OpenID userinfo / token introspection).
+- Organization: `urn:li:organization:{id}` (the numeric page id).
+
+Before publishing as an org, confirm the authed member holds an eligible **page role** (ADMINISTRATOR / CONTENT_ADMIN / DIRECT_SPONSORED_CONTENT_POSTER). Why: with the scope granted but no role, the publish still returns **403 ACCESS_DENIED** — the scope authorizes the app, the role authorizes the person.
+
+## Step 3 — publish
+
+Current organic endpoint: `POST https://api.linkedin.com/rest/posts`. The legacy `/v2/ugcPosts` and `/v2/shares` are deprecated — migrate to the versioned `/rest/posts`. Pin the version **once**:
+
+```bash
+LINKEDIN_VERSION=202605   # latest; 202505 is sunset — pinning a sunset version breaks
+```
+
+Every versioned call carries **two** headers (omit either and you get 426/400):
+
+```text
+Linkedin-Version: 202605
+X-Restli-Protocol-Version: 2.0.0
+```
+
+### Text post
+
+```bash
+curl -X POST https://api.linkedin.com/rest/posts \
+  -H "Authorization: Bearer $LINKEDIN_TOKEN" \
+  -H "Linkedin-Version: $LINKEDIN_VERSION" \
+  -H "X-Restli-Protocol-Version: 2.0.0" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "author": "urn:li:organization:12345",
+    "commentary": "Shipping notes for this week.",
+    "visibility": "PUBLIC",
+    "distribution": {
+      "feedDistribution": "MAIN_FEED",
+      "targetEntities": [],
+      "thirdPartyDistributionChannels": []
+    },
+    "lifecycleState": "PUBLISHED",
+    "isReshareDisabledByAuthor": false
+  }'
+```
+
+Success is **201**, and the new post URN comes back in the **`x-restli-id` response header** (`urn:li:share:{id}` or `urn:li:ugcPost:{id}`) — not the body. Capture that header; you need the URN to pull analytics later.
+
+### Article (link share) post
+
+The Posts API does **NOT scrape the URL**. You set the preview fields yourself, and the `thumbnail` must be an **Image URN** you uploaded via the Images API first:
+
+```jsonc
+"content": {
+  "article": {
+    "source": "https://example.com/post",
+    "title": "Our launch writeup",
+    "description": "What we shipped and why",
+    "thumbnail": "urn:li:image:C5..."
+  }
+}
+```
+
+### Document post
+
+Upload the file via the **Documents API** to get `urn:li:document:{id}`, then reference it:
+
+```jsonc
+"content": { "media": { "id": "urn:li:document:C4..." } }
+```
+
+(Images → Images API → `urn:li:image:`; videos → Videos API → `urn:li:video:`.) Full reshare / multi-image / poll payloads and the retrieval finders live in `references/api-reference.md`.
+
+## Step 4 — pull analytics
+
+### Share statistics (post-level engagement)
+
+```text
+GET https://api.linkedin.com/rest/organizationalEntityShareStatistics
+    ?q=organizationalEntity
+    &organizationalEntity=urn%3Ali%3Aorganization%3A12345
+```
+
+**Organic only** (sponsored excluded), **rolling 12-month window**. Omit `timeIntervals` for lifetime; include it for a time-bound slice. Returns `impressionCount`, `uniqueImpressionsCount`, `clickCount`, `likeCount`, `commentCount`, `shareCount`, and `engagement` (engagement rate).
+
+### Follower statistics
+
+```text
+GET https://api.linkedin.com/rest/organizationalEntityFollowerStatistics
+```
+
+Lifetime or time-bound follower counts, segmented by facet (geo, industry, seniority, function, staff size), covering **paid + organic** followers.
+
+> URNs in any URL path or query **must be URL-encoded**: `urn:li:organization:12345` → `urn%3Ali%3Aorganization%3A12345`. An un-encoded colon silently breaks the route.
+
+## Step 5 — ingest performance into the wiki
+
+This is the deliverable that makes the skill durable: after pulling stats, write one file per post under `docs/wiki/linkedin/`. Later content decisions get grounded in what actually worked, not vibes.
+
+Filename: the post id slug, e.g. `docs/wiki/linkedin/share-7012345678901234567.md`.
+
+```markdown
+---
+type: linkedin-record
+title: "Share 7012345678901234567 — OAuth pitfalls carousel"
+description: Performance snapshot for one LinkedIn post, pulled from organizationalEntityShareStatistics.
+tags: [linkedin, analytics, post-performance]
+timestamp: "2026-06-02T10:00:00Z"
+topic: linkedin
+status: stable
+post_urn: "urn:li:share:7012345678901234567"
+author: "urn:li:organization:12345"
+captured_at: "2026-06-02T10:00:00Z"
+impressions: 4821
+unique_impressions: 4102
+clicks: 213
+likes: 96
+comments: 14
+shares: 8
+engagement: 0.0683
+---
+
+# Share 7012345678901234567 — OAuth pitfalls carousel
+
+Carousel on OAuth pitfalls. Highest unique-impression post this month;
+CTR ~4.4%. The "common 403 causes" hook outperformed the plain howto.
+```
+
+`type` is the only required OKF v0.1 field; `title`/`description`/`tags`/`timestamp` are the recommended OKF surface. The DOMAIN keys below them are mandatory and must stay byte-for-byte — `verify.sh` checks that `post_urn`, `captured_at`, `impressions`, and `engagement` are present in every file under that directory. `captured_at` is the API-capture instant (a domain value verify.sh parses); `timestamp` is the OKF last-edit field — keep both. Note these files share `docs/wiki/linkedin/` with `linkedin-strategy`; using `type: linkedin-record` keeps the two skills' wiki content consistent.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| Pinning `Linkedin-Version: 202505` | That version is sunset; calls start failing on cutover | Pin `202605` in one constant; bump deliberately |
+| Sending only `Linkedin-Version`, dropping `X-Restli-Protocol-Version` | Versioned endpoints reject the request (426/400) | Always send both headers together |
+| Expecting the API to scrape an article URL | Posts API never fetches OG tags; you get a bare link | Set `source`/`title`/`description` + an uploaded Image URN |
+| Reading the new post id from the response body | The URN is in `x-restli-id`, body has no id | Read the `x-restli-id` response header |
+| Treating share statistics as total reach | They are **organic only**, 12-month window | Pull sponsored from the ads stats endpoints separately |
+| Un-encoded URN in the URL path/query | The colons break routing → 400/404 | URL-encode every URN argument |
+| Committing the token or `client_secret` | Leaked credential, instant revoke | Read from env; gitignore token files |
+| Re-prompting consent on every token expiry | Breaks unattended jobs, looks broken | Store the refresh token, refresh before ~60-day expiry |
+| Granted scope but member has no page role | Publish still returns 403 ACCESS_DENIED | Verify ADMINISTRATOR/CONTENT_ADMIN/DSC role first |
+| Polling analytics in a tight loop | `429 TOO_MANY_REQUESTS` throttle | Back off and batch; schedule, don't hammer |
+
+## Verify
+
+Run `scripts/verify.sh [TARGET_DIR]` (default current dir). It is read-only and static — no network. It confirms each `docs/wiki/linkedin/*.md` carries the required front-matter keys, and fails on any committed token / client secret in the tree. A clean or not-yet-run target passes with a NOTE.
+
+## References
+
+`references/api-reference.md` — full curl bodies (text, article, document, reshare, multi-image, poll), post retrieval finders, the complete analytics query params and response schemas for both statistics endpoints, the HTTP error-code catalog (400/401/403/404/409/422/429/500/503), URL-encoding and query-tunneling rules, and the version-deprecation note.

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

@@ -0,0 +1,3 @@
+# Evals — linkedin-api
+
+These cases are routing and capability specs, not live integration tests. `should_trigger` and `should_not_trigger` are checked by the eval harness against this skill's description and body — does the skill fire on its own asks and stay quiet on copy/strategy/outreach/generic-connector asks that belong to a sibling. The `capability` case is a rubric: run the scenario against the skill and confirm the produced plan or code mentions every line in `must_include`. No live LinkedIn API calls happen here — there is no network, no token, and no real org page; the headers, version, and wiki-file shape are verified as text, and the artifact contract is enforced separately by `scripts/verify.sh`.

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

@@ -0,0 +1,41 @@
+skill: linkedin-api
+
+should_trigger:
+  - prompt: "Connect our Next.js app to the LinkedIn Posts API and publish to our company page."
+    why: "Core connector ask — versioned /rest/posts, org author URN, the two required headers. The transport job this skill owns."
+  - prompt: "We keep getting unauthorized scope w_organization_social when users connect their org page."
+    why: "Non-obvious: the message is not a typo, it means the Community Management / MDP product is not yet approved. This skill maps the symptom to the product-approval fix."
+  - prompt: "Pull last month's impressions and engagement for our LinkedIn org posts and save them somewhere we can reference."
+    why: "Analytics read (organizationalEntityShareStatistics) plus the wiki ingest deliverable under docs/wiki/linkedin/."
+  - prompt: "Migrate our /v2/ugcPosts publishing to the new versioned endpoint."
+    why: "Non-obvious migration: ugcPosts is deprecated; move to /rest/posts with Linkedin-Version + X-Restli-Protocol-Version."
+  - prompt: "Conectar la API de LinkedIn y traer las impresiones de los posts."
+    why: "Spanish; OAuth + share statistics pull — squarely the transport surface this skill owns."
+  - prompt: "Our publish returns 403 ACCESS_DENIED even though the app has w_organization_social — what's wrong?"
+    why: "Non-obvious: scope authorizes the app, page role authorizes the person; missing ADMINISTRATOR/CONTENT_ADMIN/DSC role causes the 403."
+
+should_not_trigger:
+  - prompt: "Write me a punchy LinkedIn post about our launch."
+    route_to: linkedin-content
+    why: "Copy and hooks for one post — content meaning, not bytes over HTTP."
+  - prompt: "Plan our LinkedIn posting cadence and pillars for Q3."
+    route_to: linkedin-strategy
+    why: "The plan — what to post and when — not the wire."
+  - prompt: "Set up an automated DM sequence to new connections."
+    route_to: linkedin-outreach
+    why: "The 1:1 layer; this skill is organic publishing and analytics, not messaging."
+  - prompt: "Build a generic OAuth2 connector scaffold for a REST API I picked."
+    route_to: api-connector-builder
+    why: "Arbitrary-provider connector with no LinkedIn specifics; this skill is deep on LinkedIn's endpoints/scopes/URNs."
+
+capability:
+  - scenario: "Take an app from zero to a logged result: complete 3-legged OAuth, resolve the org author URN, publish a document post (Documents API upload -> document URN -> Posts API), pull organizationalEntityShareStatistics, and write docs/wiki/linkedin/<post-id>.md with the metric front-matter."
+    must_include:
+      - "sends both required headers: Linkedin-Version and X-Restli-Protocol-Version: 2.0.0"
+      - "pins version 202605 (not the sunset 202505)"
+      - "sets lifecycleState: PUBLISHED in the post body"
+      - "reads the new post URN from the x-restli-id response header"
+      - "uploads the document via the Documents API to get urn:li:document: then references it in content.media.id"
+      - "notes share statistics are organic-only over a rolling 12-month window"
+      - "writes the wiki file with post_urn, captured_at, impressions, and engagement keys"
+      - "reads token and client_secret from env, never committed to the repo"

package/skills/linkedin-api/references/api-reference.md

@@ -0,0 +1,168 @@
+# LinkedIn API reference
+
+Offloaded depth for `linkedin-api`. All paths assume the two versioned headers from `SKILL.md`:
+
+```text
+Authorization: Bearer $LINKEDIN_TOKEN
+Linkedin-Version: 202605
+X-Restli-Protocol-Version: 2.0.0
+```
+
+`202605` is the latest version moniker (`li-lms-2026-05`). `202505` is sunset — do not pin it.
+
+## Publish payloads — `POST /rest/posts`
+
+### Reshare (commentary on an existing post)
+
+```jsonc
+{
+  "author": "urn:li:organization:12345",
+  "commentary": "Worth a read.",
+  "visibility": "PUBLIC",
+  "distribution": {
+    "feedDistribution": "MAIN_FEED",
+    "targetEntities": [],
+    "thirdPartyDistributionChannels": []
+  },
+  "reshareContext": { "parent": "urn:li:share:7012345678901234567" },
+  "lifecycleState": "PUBLISHED",
+  "isReshareDisabledByAuthor": false
+}
+```
+
+### Multi-image post
+
+Upload each image via the Images API first to get `urn:li:image:` ids, then:
+
+```jsonc
+"content": {
+  "multiImage": {
+    "images": [
+      { "id": "urn:li:image:C5...", "altText": "slide 1" },
+      { "id": "urn:li:image:C5...", "altText": "slide 2" }
+    ]
+  }
+}
+```
+
+### Single image post
+
+```jsonc
+"content": { "media": { "id": "urn:li:image:C5...", "altText": "chart" } }
+```
+
+### Document post (carousel PDF)
+
+Upload via the Documents API → `urn:li:document:{id}`, then:
+
+```jsonc
+"content": { "media": { "id": "urn:li:document:C4...", "title": "OAuth pitfalls" } }
+```
+
+### Poll
+
+```jsonc
+"content": {
+  "poll": {
+    "question": "Which broke your last integration?",
+    "options": [ { "text": "missing scope" }, { "text": "sunset version" } ],
+    "settings": { "duration": "THREE_DAYS" }
+  }
+}
+```
+
+### Response
+
+`201 Created`. The new post URN is in the **`x-restli-id`** response header (`urn:li:share:{id}` or `urn:li:ugcPost:{id}`). The body does not contain the id.
+
+## Media upload (initialize-upload pattern)
+
+Images / Documents / Videos use the same two-step shape: register an upload to get an upload URL + URN, PUT the bytes, then reference the URN in `content`.
+
+```bash
+# Images example
+curl -X POST "https://api.linkedin.com/rest/images?action=initializeUpload" \
+  -H "Authorization: Bearer $LINKEDIN_TOKEN" \
+  -H "Linkedin-Version: 202605" \
+  -H "X-Restli-Protocol-Version: 2.0.0" \
+  -H "Content-Type: application/json" \
+  -d '{ "initializeUploadRequest": { "owner": "urn:li:organization:12345" } }'
+# -> { "value": { "uploadUrl": "...", "image": "urn:li:image:C5..." } }
+```
+
+`/rest/documents?action=initializeUpload` → `urn:li:document:`; `/rest/videos?action=initializeUpload` → `urn:li:video:`.
+
+## Post retrieval
+
+```text
+# Single post
+GET /rest/posts/{urn-encoded-post-urn}
+
+# By author (FINDER)
+GET /rest/posts?q=author&author=urn%3Ali%3Aorganization%3A12345&count=10
+
+# Batch
+GET /rest/posts?ids=List(urn%3Ali%3Ashare%3A...,urn%3Ali%3Ashare%3A...)
+```
+
+## Share statistics — `GET /rest/organizationalEntityShareStatistics`
+
+| Param | Value |
+|---|---|
+| `q` | `organizationalEntity` |
+| `organizationalEntity` | URL-encoded `urn:li:organization:{id}` |
+| `timeIntervals` (optional) | `(timeRange:(start:{ms},end:{ms}),timeGranularityType:DAY\|MONTH)` |
+| `shares` / `ugcPosts` (optional) | filter to specific post URNs |
+
+Organic only. Rolling 12-month window. Lifetime when `timeIntervals` omitted.
+
+Response `totalShareStatistics` fields:
+
+```jsonc
+{
+  "impressionCount": 4821,
+  "uniqueImpressionsCount": 4102,
+  "clickCount": 213,
+  "likeCount": 96,
+  "commentCount": 14,
+  "shareCount": 8,
+  "engagement": 0.0683
+}
+```
+
+## Follower statistics — `GET /rest/organizationalEntityFollowerStatistics`
+
+Same `q=organizationalEntity` shape. Lifetime or time-bound. Covers paid + organic. Segmented facets returned as `followerCountsBy*`:
+
+- `followerCountsByGeoCountry`
+- `followerCountsByIndustry`
+- `followerCountsBySeniority`
+- `followerCountsByFunction`
+- `followerCountsByStaffCountRange`
+
+Each facet entry carries `organicFollowerCount` and `paidFollowerCount`.
+
+## URL-encoding & query tunneling
+
+- Every URN in a path or query string must be percent-encoded: `urn:li:organization:12345` → `urn%3Ali%3Aorganization%3A12345`.
+- When a query string would exceed URL limits (large batch / complex `timeIntervals`), use **query tunneling**: send the request as `POST` with header `X-HTTP-Method-Override: GET` and the query in the body as `application/x-www-form-urlencoded`.
+
+## HTTP error catalog
+
+| Status | Code / meaning | Cause | Fix |
+|---|---|---|---|
+| 400 | bad request | malformed body, missing required field, un-encoded URN | validate payload; encode URNs; send both versioned headers |
+| 401 | unauthorized | expired/invalid token | refresh the token |
+| 403 | ACCESS_DENIED | missing scope OR member lacks page role | grant the scope's product; verify ADMINISTRATOR/CONTENT_ADMIN/DSC role |
+| 404 | not found | wrong/encoded URN, deleted post | check the URN and encoding |
+| 409 | conflict | duplicate publish / state conflict | dedupe before retry |
+| 422 | unprocessable | semantically invalid (e.g. article with no source) | fix the content shape |
+| 426 | upgrade required | missing `X-Restli-Protocol-Version` / version header | send both versioned headers |
+| 429 | TOO_MANY_REQUESTS | throttle | exponential back off; batch; schedule |
+| 500 / 503 | server / unavailable | transient | retry with back off |
+
+## Auth notes
+
+- 3-legged OAuth 2.0 authorization-code flow: `https://www.linkedin.com/oauth/v2/authorization` → `https://www.linkedin.com/oauth/v2/accessToken`.
+- Access tokens ~60 days. Marketing / Community apps can be issued refresh tokens — exchange with `grant_type=refresh_token` before expiry rather than re-consenting.
+- Scopes are space-separated in the authorize URL. Org scopes require the Community Management / MDP product to be approved, or consent rejects them as "unauthorized scope".

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

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# verify.sh — static, no-network checker for the linkedin-api feedback log + secret guard.
+# Read-only. Confirms each docs/wiki/linkedin/*.md carries the required metric front-matter,
+# and fails if a LinkedIn token / client secret is committed anywhere in the target tree.
+# Exits 0 on a clean or not-yet-run target (no false failure), non-zero on a real issue.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+fails=0
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify.sh: target '$TARGET' is not a directory" >&2
+  exit 2
+fi
+
+fail() { echo "FAIL [$1] $2"; fails=$((fails + 1)); }
+pass() { echo "PASS [$1] $2"; }
+note() { echo "NOTE [$1] $2"; }
+
+# ---------------------------------------------------------------------------
+# (1) Feedback-log front-matter check.
+# ---------------------------------------------------------------------------
+WIKI_DIR="$TARGET/docs/wiki/linkedin"
+REQUIRED_KEYS="post_urn captured_at impressions engagement"
+
+if [ ! -d "$WIKI_DIR" ]; then
+  note "wiki" "$WIKI_DIR not present — skill not yet run; nothing to check"
+else
+  LOG_FILES=()
+  while IFS= read -r _f; do
+    [ -n "$_f" ] && LOG_FILES+=("$_f")
+  done < <(find "$WIKI_DIR" -maxdepth 1 -type f -name '*.md' 2>/dev/null)
+
+  if [ "${#LOG_FILES[@]}" -eq 0 ]; then
+    note "wiki" "$WIKI_DIR exists but holds no *.md feedback files yet"
+  else
+    for f in "${LOG_FILES[@]}"; do
+      missing=""
+      for key in $REQUIRED_KEYS; do
+        if ! grep -Eq "^${key}:" "$f" 2>/dev/null; then
+          missing="$missing $key"
+        fi
+      done
+      if [ -n "$missing" ]; then
+        fail "front-matter" "$f missing required key(s):$missing"
+      else
+        pass "front-matter" "$f has all required metric keys"
+      fi
+    done
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# (2) Committed-secret guard. Scans source/config text, skips VCS/vendor dirs.
+# ---------------------------------------------------------------------------
+SCAN_FILES=()
+while IFS= read -r _f; do
+  [ -n "$_f" ] && SCAN_FILES+=("$_f")
+done < <(
+  find "$TARGET" \
+    \( -path '*/.git/*' -o -path '*/node_modules/*' -o -path '*/dist/*' \
+       -o -path '*/build/*' -o -path '*/.venv/*' -o -path '*/venv/*' \) -prune -o \
+    -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.mjs' \
+       -o -name '*.json' -o -name '*.env' -o -name '*.yaml' -o -name '*.yml' \
+       -o -name '*.md' -o -name '*.sh' \) -print 2>/dev/null
+)
+
+secret_hit=0
+for f in ${SCAN_FILES[@]+"${SCAN_FILES[@]}"}; do
+  [ -f "$f" ] || continue
+  # client_secret assigned a literal (not an env reference or a doc placeholder).
+  while IFS= read -r line; do
+    case "$line" in
+      *process.env*|*os.environ*|*ENV[*|*getenv*) continue ;;   # env-injected, fine
+      *...*|*Bad:*|*Good:*|*YOUR_*|*example*|*EXAMPLE*) continue ;;  # teaching placeholder, not a real secret
+    esac
+    fail "secret" "$f: $line"
+    secret_hit=1
+  done < <(grep -nE 'client_secret[[:space:]]*[=:][[:space:]]*["'"'"'][A-Za-z0-9_.-]{6,}' "$f" 2>/dev/null)
+
+  # AQED-style LinkedIn access-token literal.
+  while IFS= read -r line; do
+    fail "secret" "$f: $line (LinkedIn access-token literal)"
+    secret_hit=1
+  done < <(grep -nE 'AQ[ED][A-Za-z0-9_-]{20,}' "$f" 2>/dev/null)
+done
+[ "$secret_hit" -eq 0 ] && pass "secret" "no committed token / client_secret literals found"
+
+# ---------------------------------------------------------------------------
+if [ "$fails" -gt 0 ]; then
+  echo "verify.sh: $fails issue(s) in '$TARGET'"
+  exit 1
+fi
+echo "OK: linkedin-api checks passed for '$TARGET'"
+exit 0