docs(analytics): per-platform metrics matrix in the guides and READMEs

The SDK/openapi surfaces already carried the new support fields; the prose
did not, and the top-level README actively claimed analytics tracks
"impressions, likes, comments, shares, and engagement across all platforms" —
the exact false statement this work exists to correct. X reports no reach,
saves, clicks or video views; Bluesky and Mastodon report no impressions;
Pinterest reports no reach; YouTube reports no shares or reach; five
platforms plus LinkedIn personal profiles report nothing at all.

guides/platforms.md gains a "Metrics by Platform" section: the full support
matrix, what each engagement response field means, the Facebook read_insights
third state, and the two other legitimate zeroes (the 6-hourly snapshot not
having run, and X's billed opt-in-per-channel sync). The four READMEs now
point at it rather than repeating a partial version.

No version bump: prose only, no code or contract change in this commit.

Author: Azym

README.md

@@ -218,7 +218,7 @@ More examples in [`examples/`](examples/) — including [Python automation scrip
 - **Scheduling** — Schedule posts for any future time with timezone support, or let queue slots pick optimal times
 - **Media uploads** — Images (JPEG, PNG, WebP, GIF) and videos (MP4, MOV, WebM) up to 100 MB
 - **Recurring schedules** — Repeat posts daily, weekly, biweekly, or monthly at a set time of day
-- **Analytics** — Track impressions, likes, comments, shares, and engagement across all platforms
+- **Analytics** — Track impressions, likes, comments, shares, and engagement. Each platform reports a different subset of metrics, and the response says which (`supportedMetrics` / `supportedTotals`) so a `0` is never mistaken for a measurement — see [Metrics by Platform](guides/platforms.md#metrics-by-platform)
 - **Labels** — Organize posts and media with color-coded labels
 - **Bulk operations** — Delete or retry multiple posts in a single request
 - **Threads** — Multi-part thread posts for X, Threads, Bluesky, and Mastodon

guides/platforms.md

@@ -631,6 +631,70 @@ When publishing to multiple platforms, you may want different post types per pla
 
 If no override is set for a platform, BulkPublish selects the default post type based on the attached media.
 
+## Metrics by Platform
+
+Every platform reports a **different subset** of the metric columns, and the
+columns that a platform has no API for are stored as `0`. That makes "not
+reported" and "measured zero" identical on the wire unless you read the support
+fields — so **never present a `0` as a measurement without checking them first.**
+
+`GET /api/posts/{id}/metrics` returns, per platform entry:
+
+- `metricsSupported` — `false` when the platform exposes no per-post statistics API at all.
+- `supportedMetrics` — the metric keys that platform can populate. Anything absent is a stored `0`.
+
+`GET /api/analytics/engagement` returns the same information for a date range:
+
+| Field | Meaning |
+|---|---|
+| `metricSupport` | platform → the metric keys it can report |
+| `supportedTotals` | union across the window; a `total*` field whose key is missing here should render as "not available", never `0` |
+| `partialTotals` | supported key → platforms in the window that do **not** report it, so the total covers fewer posts than it appears to |
+| `conditionalMetrics` | supported but permission-gated (see the Facebook note below) |
+| `unmeasuredPlatforms` | platforms present that report nothing at all |
+| `metricsDisabledChannels` | channels whose metrics sync is switched off (see X below) |
+
+### Support matrix
+
+| Platform | Reports | Never reports |
+|---|---|---|
+| X | impressions, likes, comments, shares | reach, saves, clicks, video views |
+| YouTube | impressions, video views, likes, comments | reach, shares, saves, clicks |
+| Instagram | impressions, reach, likes, comments, shares, saves | clicks, video views |
+| Facebook | likes, comments, shares + impressions, reach, clicks¹ | saves, video views |
+| LinkedIn (company pages) | impressions, reach, likes, comments, shares, clicks | saves, video views |
+| TikTok | impressions, video views, likes, comments, shares | reach, saves, clicks |
+| Threads | impressions, likes, comments, shares | reach, saves, clicks, video views |
+| Pinterest | impressions, clicks, saves, likes, comments, video views | reach |
+| Bluesky | likes, comments, shares, saves (bookmarks) | impressions, reach, clicks, video views |
+| Mastodon | likes, comments, shares | everything else |
+| Google Business, Reddit, Discord, Telegram, Tumblr | *nothing* | — |
+| LinkedIn personal profiles | *nothing* | — |
+
+¹ Facebook's `impressions`, `reach` and `clicks` come from the Page Insights
+edge and require the `read_insights` permission. Without it they stay `0` even
+though the metric is listed as supported — that is "may not be readable", a
+third state distinct from both a dash and a trustworthy figure. These are the
+keys reported in `conditionalMetrics`.
+
+`engagementRate` is derived as engagements ÷ impressions, so it exists exactly
+where `impressions` does — it is permanently `0` for Bluesky and Mastodon.
+
+**LinkedIn is account-type-gated.** Share statistics are exposed only for
+**organization** pages. A personal/profile channel reports nothing, which is why
+LinkedIn can appear in both the matrix above and in `unmeasuredPlatforms`
+depending on the channel.
+
+### Two other reasons a figure is legitimately 0
+
+- **The snapshot has not run.** All figures come from a stored snapshot refreshed
+  every 6 hours (or on demand via `POST /api/analytics/refresh`) — never a live
+  read. A just-published post appears immediately with zeros.
+- **Metrics sync is switched off for the channel.** X bills every read, so its
+  per-post sync is **opt-in per channel** and runs at most once every 7 days.
+  Until it is enabled, every X figure stays `0` and `POST /api/analytics/refresh`
+  cannot change that. Affected channels are listed in `metricsDisabledChannels`.
+
 ## Character Limits
 
 Each platform enforces its own character limit on the `content` field:

mcp-server/README.md

@@ -129,7 +129,7 @@ Once deployed, add it to **claude.ai → Settings → Connectors → Add custom
 | `retry_post` | Retry a failed post |
 | `approve_post` | Approve a post awaiting team approval (roles with post:approve) |
 | `reject_post` | Reject a pending post back to draft, with an optional reason |
-| `get_post_metrics` | Get engagement metrics (impressions, likes, comments, shares) |
+| `get_post_metrics` | Get engagement metrics (impressions, likes, comments, shares). Each platform entry carries `supportedMetrics` — a key not in that list is a stored `0`, not a measurement |
 | `publish_story` | Publish as a story to Facebook or Instagram |
 | `bulk_posts` | Bulk delete or retry multiple posts |
 | `get_queue_slot` | Get the next optimal time slot for a channel |

node/README.md

@@ -56,7 +56,7 @@ BulkPublish is designed for programmatic social media management — no browser
 - **AI agents** — Use with Claude (MCP server), GPT (function calling), LangChain, or any LLM with tool use
 - **Server-side scripts** — Cron jobs, CI/CD pipelines, content syndication
 - **Bulk operations** — Iterate over data and schedule hundreds of posts programmatically
-- **Analytics pipelines** — Pull engagement data into your own dashboards or AI analysis
+- **Analytics pipelines** — Pull engagement data into your own dashboards or AI analysis (check `supportedMetrics` before treating a `0` as a measurement — platforms report different subsets)
 
 ## Full TypeScript Types
 

python/README.md

@@ -56,7 +56,7 @@ BulkPublish is designed for programmatic social media management — no browser
 - **AI agents** — Use with Claude (MCP server), GPT (function calling), LangChain, or any LLM that supports tool use
 - **Cron jobs & scripts** — Schedule content pipelines, RSS-to-social, blog-to-social workflows
 - **Bulk operations** — Upload a CSV, iterate, and schedule hundreds of posts programmatically
-- **Analytics extraction** — Pull engagement data into your own dashboards or AI analysis pipelines
+- **Analytics extraction** — Pull engagement data into your own dashboards or AI analysis pipelines (check `supportedMetrics` before treating a `0` as a measurement — platforms report different subsets)
 
 ## Async Support