ci(changelog): sync docs changelog from platform releases

[atharva-bhange]

Summary

Part of the tag-driven release pipeline (design, companion PR future-agi/future-agi#1729):

• changelog-sync.yml receives repository_dispatch: platform-release from the CE release pipeline and opens an editorial PR prepending the new version to src/pages/changelog.mdx — a human polishes raw bullets for a product audience (or merges as-is).
• scripts/changelog-from-release.mjs transforms release-please notes into the page format (Features→New Features, Perf→Improvements, breaking-changes section; hidden categories like chores never reach the docs). Covered by node --test (3/3 passing).
• changelog.mdx gains only the insertion-marker comment. The existing placeholder entries (fictional v1.x–v2.0.0 history dated 2024) are deliberately untouched here — they get wiped in the rollout phase before the real v1.23.0 entry lands.

Runtime prerequisites

Repo setting "Allow GitHub Actions to create and approve pull requests" must be enabled (the changelog PR is opened with GITHUB_TOKEN); dispatch requires org secret RELEASE_BOT_TOKEN on the sender side.

Verification

node --test: 3 pass / 0 fail; actionlint exit 0 on the new workflow; end-to-end local simulation inserted a synthetic entry directly below the marker and was reverted.

🤖 Generated with Claude Code

[hadarishav]

Reviewed against RELEASE-PROCESS-PLAN.md (internal-docs #41) alongside future-agi #1729 and ee #164.

The tested transform script is the standout of the whole release-process change — changelog-from-release.test.mjs (node:test, covering section mapping, insertion order, and the missing-marker throw) is the only piece of automation across the three PRs that ships with tests. I'd like to make "non-trivial CI logic ships with unit tests" the standard on the back of this. The marker + insert() design is clean too.

Must fix (plan §5.4)

1. The placeholder changelog wasn't wiped. This PR adds the insert marker above the existing ## v2.0.0 - December 2024 entry, but that entry is fictional placeholder content the plan §5.4 explicitly says to remove and re-seed at the epoch. Two problems: (a) it's fake history on a public page, and (b) future-agi #1729 currently ships the epoch as 1.23.0, so a real 1.23.0 - <month> section will insert above a fake v2.0.0, producing a version-nonsensical order (2.0.0 listed as older than 1.23.0). Delete the placeholder entries as part of this PR. (Also note the epoch-version disagreement itself — plan says v2.0.0, #1729 config says 1.23.0 — is flagged on #1729; whichever wins, this page needs to match.)

Consideration

2. MDX injection via the release body. The release body (derived from commit messages / PR titles) is decoded and written verbatim into changelog.mdx, which renders JSX. A commit message containing {...} or a <Tag> could break the docs build or inject markup. Risk is low — it's maintainer-authored text behind a human-reviewed PR — but since the page is public and this is a two-year standard, consider escaping MDX-significant characters ({, }, <) in transform(). Cheap insurance.

Minor

3. Section-map completeness. SECTION_MAP covers Features / Bug Fixes / Performance / Reverts, matching the visible release-please sections. Fine today — just flagging that if changelog-sections in the future-agi config gains a visible type, this map needs updating in lockstep or that section silently drops from the docs page.

Main ask is #1.

[atharva-bhange]

@hadarishav all three done:

1. Placeholder wiped in this PR (4fd5ce2) — you were right that shipping the marker above fake history was the wrong half-measure, especially with the epoch confirmed as v1.23.0 (would have sorted below a fictional v2.0.0). All fictional entries deleted (v2.0.0 down to and including v1.0.0), plus the now-dead Callout import. The page is empty-and-ready below the marker; G6 in the plan shrinks to the Notion guide rewrite only.
2. MDX escaping (9f0d647) — escapeMdx() escapes <, {, } on all release-body content lines (not the script's own headings), exported and covered by a new test (<Tag>/{expr} → entities, raw forms asserted absent). 4/4 tests pass.
3. Section-map lockstep — comment added above SECTION_MAP pointing at release-please-config.json, and the reciprocal comment now sits in future-agi's release-please.yml (#1729), so whichever side is edited, the reader is told about the other.

And thanks for the tests callout — "non-trivial CI logic ships with unit tests" as the standard has Atharva's support; it's noted in the internal-docs plan.

🤖 Generated with Claude Code

[atharva-bhange]

@hadarishav heads-up: target page corrected after your approval — Atharva caught that the sync pointed at the wrong surface. src/pages/changelog.mdx was orphan scaffold (zero navigation links); the real, maintained release-notes page is src/pages/docs/release-notes.mdx (the weekly 'Week of …' entries). Commit d4188591:

• Transform now emits that page's exact format (styled wrapper div + Features / Bugs/Improvements / Breaking Changes subsections; release-please's Bug Fixes + Performance merge into the existing Bugs/Improvements bucket) and prepends new versions above the existing weekly entries.
• Marker sits right below the frontmatter; verified end-to-end against the real page (synthetic v9.9.9 inserted above 'Week of 2026-06-18', then reverted).
• Orphan changelog.mdx deleted outright instead of wiped-but-kept.
• Tests: 5/5 (added an empty-subsection case alongside the format + escaping ones).

Same change synced to #773. Sorry for the re-review after approval — this one's worth it.

🤖 Generated with Claude Code

[atharva-bhange]

One more scope change per Atharva: changelog.mdx is now fully untouched by this PR — restored byte-identical to main (diff vs main for that file: zero). The PR is purely the release-notes sync (workflow + script + tests + marker in docs/release-notes.mdx). What happens to the orphan changelog page — including the placeholder-content concern from your review — is deferred to Atharva as a separate decision outside this PR. Synced to #773.

🤖 Generated with Claude Code