Docs: document the programmatic publishing surface for integrating plugins

[jeffpaul]

What

Adds a Publishing Programmatically section to docs/developer-docs.md (plus ToC entry and a changelog file), documenting the integration surface a companion plugin needs to drive cross-posting per post:

• The registered per-post metas — atmosphere_disabled (opt-out) and atmosphere_custom_text (per-post Bluesky text)
• Taking over the save-flow: atmosphere_auto_publish option + \Atmosphere\Publisher::publish_post() (with its is_post_publishable() gate and update_post()/delete_post() lifecycle)
• Reading back the created record via _atmosphere_bsky_uri / _atmosphere_bsky_tid
• Pointers to the existing atmosphere_publish_post_result / atmosphere_reaction_synced hooks and the comment protocol/source_url markers for synced replies

Why

I'm building a WordPress publishing plugin (Moment — a phone-first publishing prototype) that wants to delegate its Bluesky syndication to ATmosphere rather than maintain its own AT Protocol client. Everything needed for that already exists in ATmosphere — this PR just documents it as the supported integration surface, so integrators can rely on it (and so gaps get spotted if any of it isn't meant to be public API).

Testing

Docs + changelog only, no code changes. composer lint passes; npm run env-test not run since no PHP changed.

🤖 Drafted with Claude Code, human-reviewed.

[Copilot]

Pull request overview

Adds developer documentation describing how companion plugins can programmatically drive ATmosphere cross-posting on a per-post basis, and records the change via a changelog entry.

Changes:

• Add a new Publishing Programmatically section (and ToC entry) documenting per-post meta controls, manual publishing, and reading back published record references.
• Add a patch-level changelog entry for the documentation update.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/developer-docs.md	Adds a new section documenting the supported integration surface for programmatic publishing and reaction sync metadata.
.github/changelog/add-programmatic-publishing-docs	Adds a changelog entry describing the documentation addition.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pfefferle]

Thanks for this, @jeffpaul! I verified every documented symbol against the code (constants, is_post_publishable() checks, publish_post() signature/return/hook behavior, meta keys, anchors) and it all checks out. A few points, including the Copilot comments, which I checked against the code:

• Changelog: docs-only changes don't need a changelog entry — please drop .github/changelog/add-programmatic-publishing-docs; I'll add the "Skip Changelog" label.
• atmosphere_disabled removal (Copilot is right): the automatic record removal runs through the meta-change reconcile, which is skipped when atmosphere_auto_publish is off. A one-liner in the takeover section would close it, e.g. "With auto-publish disabled, call \Atmosphere\Publisher::update_post() after changing per-post metas to reconcile the remote records" (it routes ineligible posts to delete_post()).
• Reactions paragraph (Copilot is right here too): likes arrive as comments as well (comment_type like), and source_url is intentionally empty for likes and reposts (no bsky.app landing page; the author profile link is in comment_author_url). Suggested wording: "Replies, likes, and reposts synced back from Bluesky arrive as native WordPress comments (protocol comment meta atproto; for replies, source_url links to the reply on Bluesky)."
• Namespace consistency: fine either way, but fully-qualified names are safer for copy-pasting.

On your "gaps get spotted" point: merging this makes Publisher::publish_post(), the _atmosphere_bsky_uri/_atmosphere_bsky_tid metas, and the comment markers a committed integration surface — I'm comfortable with that; documenting it is exactly the right move.