skills/social-publishing/references/results-and-recovery.md

# Results, management and recovery

## Find and inspect

`social_list_uploads` needs studio/production ids. Default is the next 30 days;
use past dates for published posts. Page with `offset`/`hasMore`; window totals
are before platform/status filters, not filtered-row totals.

Read `social_get_upload` before mutations. Independently check `editable`,
`mediaEditable`, `cancellable`: rendering may allow only cancellation; failed
may allow only editing. Match the account with connected platforms. Only
`COMPLETED` proves live. Relay returned `postUrl`; null does not prove failure.
Do not invent Facebook URLs.

## Update or cancel

Preview current account/platform, content, schedule, change and consequences;
confirm each mutation. Refresh/reconfirm if material values changed.

- `social_update_upload` requires `editable`. Send changing fields only and the
  matching platform object; returned `content` is not an input template and
  nulls cannot be sent back. `publishNow` posts immediately and cannot be undone;
  never combine it with future `scheduledAt`. Use the main scheduling route.
- Media changes require `mediaEditable`. Video cannot be removed or converted
  to images, or vice versa. `assets` replaces all images; `[]` removes them only
  on text-only platforms. X replies and LinkedIn comments replace whole lists:
  start with current entries, preserve unchanged ones and X reply ids, and
  preview deletions explicitly.
- `social_cancel_upload` requires `cancellable`; it permanently removes the
  post from Content Planner, with no restore or platform deletion. Success is
  confirmed by its own response. Do not read back: cancelled ids now return
  an authorization error.

Live edits/removal happen on the platform. Never blindly repeat uncertain
mutations, especially publish-now/cancellation.

## Accounts

Resolve required studio id/slug and production id through content-discovery.
`social_connect_social_account` gives a user consent link. After they report
completion, read connected platforms and compare ids
with `connectedPlatformAccountIds`. If that snapshot is null, list accounts and
ask which was added. If none appeared, ask about the browser result before a
fresh link. Never poll by restarting connections. `isAddingAccount` selects an
additional Instagram/X account; omit `returnTo` unless a current Riverside URL
is known.

Before `social_disconnect_social_account`, read accounts, name the target and
warn that all its scheduled uploads are permanently cancelled; get explicit
confirmation. For Facebook, every Page under that login is disconnected: name
all affected Pages first. Other logins stay connected. Reconnection does not
restore cancelled uploads.

## Analytics

`social_get_upload_analytics` reads a published post found by listing. Pass
known `studioId` to diagnose permissions. Relay `asOf`; counts are not live. `hasData: false`, null metrics/days mean unavailable,
never zero. Daily values are already differenced: do not sum/difference them.
`frozen` means collection ended. `MISSING_ANALYTICS_SCOPE` requires reconnecting,
not read retries. In listing views, missing fields mean lookup failed; null
means no collected/available count.

## Recovery

Processing: report without resending. Timeout/transport failure/unusable result:
stop publishing. Listing may investigate, but no matching row cannot prove no
post; there is no idempotency key.

For explicit failures, fetch fresh guidance. Both failure and guidance must
prove no post and safe retry before a fresh upload is eligible. Never retry
success, processing, partial/unknown outcomes. Preview/confirm again; stop if
the failure repeats after one clean retry.

Prefer in-place recovery. Re-read status/capabilities. `UNKNOWN`/missing failure
category needs platform or Support verification before republishing. Expired
connections may revive scheduled posts after reconnect: no new publish or
`publishNow` until its fresh outcome is reconciled. Other confirmed failures may
use eligible in-place update with the confirmation contract above.

Export-required matches the draft-export route. Fix only identified metadata/
media errors, then preview/confirm again. Keep the main YouTube copyright gate.