rsc-universal 0.1.1

package/skills/lead-gen/scripts/verify.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+#
+# verify.sh — scored-list QA gate for the `lead-gen` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Lints a produced scored-list CSV against the schema in
+#   references/scoring-model.md. Per file it checks:
+#     1. Header carries the required columns:
+#        account, contact, source, fit, intent, engagement, total, tier, opt_out
+#     2. Every data row: account/contact/source/opt_out non-empty (provenance +
+#        compliance flag present).
+#     3. fit/intent/engagement are integers >= 0 and sum to total.
+#     4. total is an integer in 0..100.
+#     5. tier label matches its score band (A 90-100, B 75-89, C 60-74).
+#   A list missing scoring or compliance fields FAILS the build.
+#
+# HOW TO RUN (inside YOUR project, pointing at a produced list)
+#   ./verify.sh                       # scan ./ for *.csv that look like lists
+#   ./verify.sh path/to/list.csv      # lint one file
+#   ./verify.sh --path lists/         # scan a directory of lists
+#
+# EXIT CODES
+#   0  clean, or nothing to check (empty/clean target — never a false failure)
+#   1  a real schema/compliance failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+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; fail_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)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    TARGET="${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 ;;
+    *)         TARGET="$1"; shift ;;
+  esac
+done
+[ -z "$TARGET" ] && TARGET="."
+
+if [ ! -e "$TARGET" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$TARGET" "$NC"; exit 2
+fi
+
+# Required columns, in any order.
+REQUIRED="account contact source fit intent engagement total tier opt_out"
+
+# Collect candidate CSV files.
+FILES=""
+if [ -f "$TARGET" ]; then
+  FILES="$TARGET"
+else
+  FILES="$(find "$TARGET" -type f -name '*.csv' 2>/dev/null || true)"
+fi
+
+if [ -z "$FILES" ]; then
+  skip "no .csv list files found under $TARGET — nothing to lint"
+  printf '\nok=%d skip=%d fail=%d\n' "$ok_count" "$skip_count" "$fail_count"
+  exit 0
+fi
+
+# col_index <header_line> <name> : 1-based index of a column, or empty.
+col_index() {
+  printf '%s' "$1" | tr ',' '\n' | grep -niE "^[[:space:]]*$2[[:space:]]*$" 2>/dev/null \
+    | head -n1 | cut -d: -f1
+}
+
+# field <line> <index> : the Nth comma-separated field, trimmed.
+field() {
+  printf '%s' "$1" | cut -d',' -f"$2" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//'
+}
+
+is_int() { case "$1" in ''|*[!0-9]*) return 1 ;; *) return 0 ;; esac; }
+
+for f in $FILES; do
+  [ -s "$f" ] || { skip "$f is empty — skipped"; continue; }
+
+  header="$(head -n1 "$f")"
+
+  # Skip non-list CSVs gracefully: if it has none of our key columns, it is not
+  # a scored list — do not fail an unrelated CSV.
+  if ! printf '%s' "$header" | grep -qiE '(^|,)[[:space:]]*total[[:space:]]*(,|$)'; then
+    skip "$f has no 'total' column — not a scored list, skipped"
+    continue
+  fi
+
+  # 1. required columns present
+  missing=""
+  for col in $REQUIRED; do
+    [ -z "$(col_index "$header" "$col")" ] && missing="$missing $col"
+  done
+  if [ -n "$missing" ]; then
+    fail "$f missing required column(s):$missing"
+    continue
+  fi
+
+  i_acc="$(col_index "$header" account)"
+  i_con="$(col_index "$header" contact)"
+  i_src="$(col_index "$header" source)"
+  i_fit="$(col_index "$header" fit)"
+  i_int="$(col_index "$header" intent)"
+  i_eng="$(col_index "$header" engagement)"
+  i_tot="$(col_index "$header" total)"
+  i_tier="$(col_index "$header" tier)"
+  i_opt="$(col_index "$header" opt_out)"
+
+  row_errs=0
+  lineno=1
+  # Read data rows (skip header). tail -n +2 is portable on macOS.
+  while IFS= read -r line; do
+    lineno=$((lineno + 1))
+    [ -z "$line" ] && continue
+
+    acc="$(field "$line" "$i_acc")"
+    con="$(field "$line" "$i_con")"
+    src="$(field "$line" "$i_src")"
+    fit="$(field "$line" "$i_fit")"
+    int="$(field "$line" "$i_int")"
+    eng="$(field "$line" "$i_eng")"
+    tot="$(field "$line" "$i_tot")"
+    tier="$(field "$line" "$i_tier")"
+    opt="$(field "$line" "$i_opt")"
+
+    # 2. non-empty account/contact/provenance/compliance
+    if [ -z "$acc" ] || [ -z "$con" ]; then
+      fail "$f:$lineno empty account or contact"; row_errs=$((row_errs + 1)); continue
+    fi
+    if [ -z "$src" ]; then
+      fail "$f:$lineno empty source/provenance"; row_errs=$((row_errs + 1)); continue
+    fi
+    if [ -z "$opt" ]; then
+      fail "$f:$lineno empty opt_out compliance flag"; row_errs=$((row_errs + 1)); continue
+    fi
+
+    # 3. subscores integers and sum to total
+    if ! is_int "$fit" || ! is_int "$int" || ! is_int "$eng" || ! is_int "$tot"; then
+      fail "$f:$lineno fit/intent/engagement/total must be integers (got $fit/$int/$eng/$tot)"
+      row_errs=$((row_errs + 1)); continue
+    fi
+    sum=$((fit + int + eng))
+    if [ "$sum" -ne "$tot" ]; then
+      fail "$f:$lineno subscores $fit+$int+$eng=$sum != total $tot"
+      row_errs=$((row_errs + 1)); continue
+    fi
+
+    # 4. total in 0..100
+    if [ "$tot" -lt 0 ] || [ "$tot" -gt 100 ]; then
+      fail "$f:$lineno total $tot out of range 0..100"; row_errs=$((row_errs + 1)); continue
+    fi
+
+    # 5. tier matches band
+    case "$tier" in
+      A|a) [ "$tot" -ge 90 ] || { fail "$f:$lineno tier A but total $tot < 90"; row_errs=$((row_errs + 1)); } ;;
+      B|b) { [ "$tot" -ge 75 ] && [ "$tot" -le 89 ]; } || { fail "$f:$lineno tier B but total $tot not in 75..89"; row_errs=$((row_errs + 1)); } ;;
+      C|c) { [ "$tot" -ge 60 ] && [ "$tot" -le 74 ]; } || { fail "$f:$lineno tier C but total $tot not in 60..74"; row_errs=$((row_errs + 1)); } ;;
+      *)   fail "$f:$lineno unknown tier '$tier' (expected A/B/C)"; row_errs=$((row_errs + 1)) ;;
+    esac
+  done < <(tail -n +2 "$f")
+
+  [ "$row_errs" -eq 0 ] && ok "$f passes scored-list schema + compliance checks"
+done
+
+printf '\nok=%d skip=%d fail=%d\n' "$ok_count" "$skip_count" "$fail_count"
+[ "$fail_count" -gt 0 ] && exit 1
+exit 0

package/skills/linkedin-api/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: linkedin-api
+description: "Use when wiring an app to LinkedIn's organic Posts / Community Management API — completing 3-legged OAuth, publishing text/article/document posts to a member profile or company page, or pulling impressions/engagement/follower stats and logging them as a durable feedback record. Triggers: 'connect our app to the LinkedIn Posts API', 'publish to our company page programmatically', 'pull last month's impressions for our org posts', 'my /v2/ugcPosts call returns 403', 'unauthorized scope w_organization_social at consent', 'log post performance into the wiki', 'publica a la pàgina de LinkedIn per API', 'conectar la API de LinkedIn y traer las impresiones'. NOT writing the post copy (that is linkedin-content), planning cadence (that is linkedin-strategy), or 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 `02-DOCS/wiki/linkedin/`. Later content decisions get grounded in what actually worked, not vibes.
+
+Filename: the post id slug, e.g. `02-DOCS/wiki/linkedin/share-7012345678901234567.md`.
+
+```markdown
+---
+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
+---
+
+Carousel on OAuth pitfalls. Highest unique-impression post this month;
+CTR ~4.4%. The "common 403 causes" hook outperformed the plain howto.
+```
+
+Keep the front-matter keys exactly as above — `verify.sh` checks that `post_urn`, `captured_at`, `impressions`, and `engagement` are present in every file under that directory.
+
+## 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 `02-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 02-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 02-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".