Update to Publora

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,78 +1,97 @@
 ---
 name: publora-media
 description: >
-  Attach images and video to a Publora post — by public URL or by uploading a
-  local file — and fix media problems that block scheduling. Use when a post
-  needs a picture or clip, when Instagram, TikTok or YouTube refuse a text-only
-  post, or when media errors stop a post from being scheduled.
+  Attach images or video to Publora posts from a chat file, public URL or
+  uploaded bytes, and resolve media errors before scheduling. Use when a post
+  needs media, an upload is pending, or an attachment blocks publication.
 ---
 
 # Media in Publora
 
-Two ways in, and one of them is much shorter.
+For personal posts, use the paths below. Agency client posts use
+`company_reserve_media`, `company_complete_media`, `company_delete_media`
+and `company_list_post_media`; follow the Agency flow in
+`publora-publishing`. Never mix their media IDs or post IDs.
+
+Finish the media work before scheduling. An attachment operation does not
+authorize publication or rescheduling.
+
+## File from the conversation
+
+1. Create a personal draft with `create_post`, omitting `scheduledTime`
+   and `publishNow`, or use the existing authorized draft.
+2. Call `attach_media` with its `postGroupId` and the real file reference
+   accepted by the current host's `file` parameter. Optional `fileName`
+   changes the stored filename.
+3. Verify the attachment is ready with `get_post`.
+
+The host resolves the file to a temporary download URL for Publora. Do not
+invent a URL, paste base64, or send a sandbox path as a download URL. If the
+host exposes an absolute-local-path file parameter, supply an actual file
+there. If it cannot resolve the file, use a public URL or upload the bytes.
+
+One file per call. No PUT or `complete_media` is needed for this path.
+`attach_media` leaves the post in draft and demotes an already scheduled post.
+Explain that effect before changing a scheduled post; restore only the schedule
+the user has authorized. Retrying the same attachment uses the same post,
+file identity, filename and idempotency key.
 
-## By URL, when the file is already on the web
+## Public file URL
 
-Pass `mediaUrls` to `create_post` or `update_post`. Publora downloads the files
-server-side, so nothing is uploaded from the conversation.
+Pass `mediaUrls` to `create_post` or `update_post`. Publora fetches and
+stores the file on its servers.
 
-```
-create_post
-  platforms: ["<platformId>"]
-  content: "<caption>"
-  mediaUrls: ["https://example.com/image.png"]
-  scheduledTime: "2026-08-12T09:00:00Z"
-```
-
-Requirements that actually bite:
-
-- **Direct file URLs only.** A Google Drive or Dropbox share page is a web page,
-  not a file, and the download fails.
+- Use direct public HTTPS file URLs, not Google Drive/Dropbox share pages.
 - Images: jpeg, png, gif, webp, tiff, avif, up to 25 MB.
 - Videos: mp4, mov, webm, up to 150 MB.
-- Up to 10 files per post.
-
-If a URL cannot be fetched, the whole call fails and the response names the
-file and the HTTP status behind it. Report that to the user rather than
-retrying the same URL — an expired or private link will not start working.
-
-## By upload, when the file is local
-
-Three steps per file, in order:
-
-1. `get_upload_url` with a **unique** file name → returns a presigned URL and a
-   `mediaId`. Reusing a name returns the same slot instead of adding a new one,
-   which is how several files silently collapse into one.
-2. `PUT` the bytes to that URL.
-3. `complete_media` for that `mediaId` — Publora inspects the bytes and marks
-   the file ready.
-
-Create the post as a draft first (no `scheduledTime`), attach the media, then
-`update_post` with `status: "scheduled"` and the time. Scheduling before the
-media is ready fails validation.
-
-## Networks that require media
-
-Instagram, TikTok and YouTube cannot take a text-only post. If the user wants
-one of those without a file, say so and offer either to attach something or to
-drop that network — do not schedule and hope.
-
-## Covers and network options
-
-`platformSettings` carries the extras: an Instagram Reels cover image, a
-YouTube title, tags and privacy, TikTok viewer setting. A cover URL follows the
-same rule as any media URL — public, direct, https.
-
-## When media blocks scheduling
-
-Two errors show up in practice:
-
-- **Too many media slots, or a slot that was never uploaded.** Call `get_post`
-  and read its `media` array: each entry carries a status. Remove the offending
-  file with `delete_media`.
-- **A reference to a file that no longer exists.** `prune_media_reference`
-  clears a dangling reference that `delete_media` cannot, because the underlying
-  record is already gone.
+- Up to 10 files; each target may impose a lower limit or other format rules.
 
-Both are destructive and cannot be undone. Name the exact file you are about to
-remove, and let the user confirm before you remove it.
+`update_post.mediaUrls` appends files; it does not replace existing attachments
+or unfinished upload slots. Inspect `get_post` before adding replacements.
+Report download/validation errors accurately. A private or expired link needs
+repair; a repeated call with the same unusable link will not help.
+For drafts omit publishing fields. Schedule separately after content/media
+approval, using the current `update_post` schema.
+
+## Upload bytes
+
+Use this route only if you can read the bytes and perform the PUT.
+
+1. `get_upload_url` with postGroupId, a unique filename, contentType and type.
+2. PUT the exact bytes to the returned uploadUrl with the same Content-Type.
+   Do not send a Publora credential to storage.
+3. `complete_media` with the returned mediaId.
+4. `get_post` to verify ready before scheduling.
+
+For the same unfinished upload, identical postGroupId/fileName/contentType/type
+reissues the same slot. Use distinct filenames for distinct files.
+
+- `MEDIA_UPLOAD_PENDING`: upload the bytes before retrying completion.
+- `MEDIA_VALIDATION_PENDING`, or `retryable: true` with
+  `WAIT_AND_RETRY_SAME_MEDIA`: wait retryAfterSec, then repeat
+  `complete_media` with the same mediaId. Do not reserve another slot.
+- Follow the server's nextAction for other failures. Never label pending
+  media ready or schedule while validation is incomplete.
+
+## Repairing attachments
+
+Read `get_post.media` to identify the exact attachment and state.
+
+- Use `delete_media` for an existing duplicate or unfinished reservation
+  only when the user's request authorizes discarding that specific file.
+- Use `prune_media_reference` for `MEDIA_REFERENCE_MISSING` when the
+  reference remains but the MediaFile record is absent or inaccessible.
+- Deleting media from a scheduled post demotes it to draft. Inspect the
+  resulting state and restore the authorized schedule only after repair.
+- A failed upload alone is not permission to discard another attachment.
+  When intent is unclear, ask about the exact file before removing it.
+
+## Network requirements
+
+Instagram and TikTok require media; YouTube requires a video, not just an
+image. Check each target's format and count limits. Offer suitable media or a
+change of target if required; do not silently drop a network.
+
+Use supported `platformSettings` for a Reels cover, YouTube title/privacy or
+TikTok viewer setting. Covers must be public direct HTTPS files of the required
+type. Before scheduling, verify the saved media, content and target settings.