# Social Media Manual

`datahandler-epic-mcp` · the `social_*` tools · served by `get_epic_manual` as `social` (index) and `social-NN-slug` (chapters)

This is the agent-facing reference for the social media side of the MCP server: connecting
Facebook Pages, Instagram business accounts and X accounts, drafting and previewing posts,
publishing now or on a schedule, reading live posts back, and the usage ledger behind billing.
It sits beside the Epic CLI manual and is served the same way: `get_epic_manual` with
`chapter="social"` returns this index, `chapter="social-03"` (or `"social-03-ownership-sharing-and-authorization"`,
or just `"sharing"` when unique) returns a chapter, `section=` narrows to one heading, and `query=`
searches every chapter of both manuals. Every chapter is also readable as the resource
`epic-manual://social-NN-slug`.

Only present when the server has the social tools enabled; the tool descriptions in
`tools/list` are the contract, this manual is the explanation.

**Shortcuts:** first time here? Chapters 1 → 3 → 4. Just want the call sequence for a job?
Chapter [13 — Recipes](manual/13-recipes.md). Something refused you? Chapter
[12 — Error codes](manual/12-error-codes.md).

## Chapters

| # | Chapter | What's in it |
|---|---|---|
| 1 | [What the social tools do](manual/01-what-the-social-tools-do.md) | The 37 tools in eleven groups, the one-line flow, the four things that ever send anything to a platform, the typed-result contract. |
| 2 | [Identity and members](manual/02-identity-and-members.md) | Where the caller's identity comes from, why a reconnected connector is a new person, invitations and recovery codes as the only ways back. |
| 3 | [Ownership, sharing and authorization](manual/03-ownership-sharing-and-authorization.md) | Owner / editor / viewer, what each role may do, claim tokens, the authorization kinds `post` and `standing`, what revoking cancels, the evidence trail. |
| 4 | [Connecting accounts](manual/04-connecting-accounts.md) | `social_get_status` first; the browser flow (`social_start_connect` → user approves → `social_complete_connect`), credential connect, per-platform behaviour, Meta app-review limits, reconnecting. |
| 5 | [Media](manual/05-media.md) | Upload, sniffing, limits, public URLs, what happens to posts when media is deleted. |
| 6 | [Drafts and preview](manual/06-drafts-and-preview.md) | Immutable revisions, `expected_revision` and `REVISION_CONFLICT`, destinations, titles and options, the dry-run preview and what each check means. |
| 7 | [Publishing](manual/07-publishing.md) | `social_publish_now`, asynchronous delivery, attempt and publication statuses, retries, the `unknown` outcome and reconciliation, polling. |
| 8 | [Schedules and calendar](manual/08-schedules-and-calendar.md) | Rules (once / daily / weekly / monthly), timezones and DST, briefs and `needs_content` slots, occurrence statuses, pause / resume / cancel, the minute tick. |
| 9 | [Published posts](manual/09-published-posts.md) | Reading a live post back, editing text (Facebook only), taking a post down, the change log. |
| 10 | [Usage and billing](manual/10-usage-and-billing.md) | The platform-call ledger, the X rate card and what each call costs, who is billed for what, `social_get_usage`, what the operator report contains. |
| 11 | [Platforms](manual/11-platforms.md) | Facebook, Instagram, X and the test platform: connect methods, capabilities, limits, token behaviour, platform error mapping. |
| 12 | [Error codes](manual/12-error-codes.md) | Every `error.code` the social tools answer, what it means and the next call to make. |
| 13 | [Recipes](manual/13-recipes.md) | Call-by-call sequences: first connect, post with a picture, share an account, delegate publishing, weekly schedule with briefs, fix a failed delivery, take a post down. |
| 14 | [Troubleshooting](manual/14-troubleshooting.md) | Symptom → cause: no social tools listed, `INTENT_PENDING` forever, `AUTHORIZATION_REQUIRED` for the owner, `unknown` attempts, Instagram refusing a post, X posting failures. |

## Reading guide

- **Agent meeting these tools for the first time?** 1 → 3 → 4 → 13.
- **User wants to post something right now?** 4 (connected?) → 6 → 7.
- **User wants someone else to be able to post?** 3 → 13 ("Delegate publishing").
- **User wants a recurring campaign?** 8 → 13 ("Weekly schedule with briefs").
- **A call came back `ok:false`?** 12, then 14.
- **Owner asks what the connector cost this month?** 10.