Read runtime instructions before running scripts.

Blog publishing mechanics

All remote calls go through cms.mjs (stdout = one JSON line, stderr = progress):

node "${SEOBLOG_PLUGIN_ROOT}/scripts/cms.mjs" <list|create|update|get|upload-image> --site <id> …

Write article/patch JSON to a temp file first — body HTML never goes on argv.

Images

Counts, cost, prompt craft and the generate → review → fix loop live in the blog-images skill (gen-image.mjs). Cost is $0.15 per fal call — base images × $0.15, plus up to imageReviewRounds fix rounds per image. Note the estimate in your progress output, then proceed — no approval step.

Publish-draft sequence

1. Create the draft — write article.json ({title, body, excerpt, author, status: "draft", tags, metaDescription}) to a temp dir, then cms.mjs create --site <id> --file article.json → {id, slug}. status is ALWAYS "draft" here.
2. Generate + review images — per blog-images: hero --purpose hero (16:9), inline --purpose inline (16:9 or 4:3, per placement), og --purpose og (auto-crops to exactly 1200×630). Round files are <slug>-<purpose>.rN.jpg; after the review loop copy the winning round to the canonical kebab-case name <slug>-<purpose>.jpg.
3. Upload — per image, the canonical file only (never a .rN or .src file — the basename can surface in public URLs): cms.mjs upload-image --site <id> --id <articleId> --file <slug>-<purpose>.jpg --purpose <p> --alt "…" → {imageUrl, path}. Alt text is required for hero and inline.
4. Swap placeholders — build the patched body: replace each <!-- IMAGE: … --> with <img src="<path>" alt="…" />, matching each image to the most relevant placeholder. Use the returned path verbatim — the server decides its form: root-relative on Postgres-backed sites, an absolute CDN URL on object-storage-backed sites and Shopify. The hero and OG images are NOT inserted into the body — the site renders them from their purpose slots. Then cms.mjs update --site <id> --id <articleId> --file patch.json with {"body": "…"}. If images were skipped, strip the placeholder comments the same way.
5. Record state — update ~/.config/seoblog/state/<siteId>.json: append to articleHistory ({id, slug, title, keywords, status: "draft", wordCount, createdAt}), mark the run's keywords "completed" with the articleId, set lastRunAt.

Publish flip (/seoblog:publish)

The write flow ends at draft + report and never asks about publishing; the flip only happens via /seoblog:publish or when the user's prompt explicitly said to publish.

• List drafts: cms.mjs list --site <id> --status draft --exclude-assets. --exclude-assets hides SocialCue image-holder drafts (slug sc-assets-*, tag socialcue-assets, created by /seoblog:socialcue to host post images). Never flip one of those: if a named target is an asset holder, refuse and explain that it is image storage for a SocialCue post.
• Show the user title and live-URL-to-be (<baseUrl>/blog/<slug>). Previewing drafts is the site's job, not this plugin's — point the user at whatever their site provides (e.g. plugmyplugin.com shows drafts at the live URL to signed-in admins; WordPress/Shopify have their own draft previews). Never construct a preview URL or put the API key in a URL.
• Flip: cms.mjs update --site <id> --id <articleId> --file patch.json with {"status": "published"}.
• Verify with cms.mjs get --id <articleId> (articles-api only) and print the live URL. Update the article's status in the state file.

Asset-holder drafts (from /seoblog:socialcue)

socialcue.mjs host-images creates one draft per SocialCue post whose only job is to give that post's images public URLs (the upload endpoint hangs off an article id). Recognise them by slug prefix sc-assets- or tag socialcue-assets; always pass --exclude-assets to cms.mjs list in the blog flows, never publish them, and never count them as blog content.

Per-CMS notes

• articles-api — the generic contract; plugmyplugin.com implements it, including purpose=og.
• wordpress — same wire contract, served by the Cue Up WordPress plugin (NOT the vanilla WP REST API). Behaves identically to articles-api.
• shopify — native Admin API. Hero = the article's featured image. Inline and OG uploads land in Shopify Files and return CDN URLs; Shopify has no OG slot, so mention in the run report that the OG image is in Files and the theme controls og:image. get is not supported; verify via list.