docs(agents): document changelog sync rule

Author: elkaix

AGENTS.md

@@ -37,6 +37,9 @@ subagents, skills, web/visualization UIs, and multi-provider LLM authentication.
   commit status is `success`, not `pending`/`failure` or absent — and read the review summary and
   any "Actionable comments posted: N" findings. Do not merge while CodeRabbit is still reviewing or
   on an unreviewed commit; surface unresolved actionable findings instead of merging past them.
+- **Do not manually edit auto-synced changelog files.** `docs/en/release-notes/changelog.md` is
+  generated from the root `CHANGELOG.md`; edit `CHANGELOG.md` and run `npm run sync` from `docs/`
+  instead of hand-editing the generated docs changelog.
 - **When working on a PR or GitHub Actions failure, investigate and identify the root cause first.**
   Provide the best-practice, most robust design solution; never provide fast fixes or workarounds.
   This is a hard constraint.

scripts/release.py

@@ -29,15 +29,14 @@
 REVIEW_PYPROJECT = REPO_ROOT / "packages" / "pythinker-review" / "pyproject.toml"
 SDK_PYPROJECT = REPO_ROOT / "sdks" / "pythinker-sdk" / "pyproject.toml"
 
-# Single source for the three hand-authored changelog files. validate() asserts
-# the `## Unreleased` anchor in ALL of them before any write, and rewrite()
-# promotes the SAME list — defined once so the two can never drift (atomic
-# Phase-2 guarantee: no partial-write if a docs file is missing its anchor).
+# Hand-authored changelog files. The docs changelog is intentionally excluded:
+# docs/en/release-notes/changelog.md is auto-synced from the root CHANGELOG.md
+# by docs/scripts/sync-changelog.mjs and must not be edited directly.
 CHANGELOG_FILES = (
     REPO_ROOT / "CHANGELOG.md",
-    REPO_ROOT / "docs" / "en" / "release-notes" / "changelog.md",
     REPO_ROOT / "docs" / "en" / "release-notes" / "breaking-changes.md",
 )
+DOCS_CHANGELOG_SCRIPT = REPO_ROOT / "docs" / "scripts" / "sync-changelog.mjs"
 
 SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
 _DEP_PIN_RE = re.compile(
@@ -157,6 +156,10 @@ def rewrite_version_in_files(paths: list[Path], *, old: str, new: str) -> None:
         path.write_text(rewrite_version_strings(original, old=old, new=new), encoding="utf-8")
 
 
+def sync_docs_changelog() -> None:
+    subprocess.run(["node", str(DOCS_CHANGELOG_SCRIPT)], cwd=REPO_ROOT / "docs", check=True)
+
+
 def _run(cmd: list[str], *, dry_run: bool, check: bool = True) -> subprocess.CompletedProcess[str]:
     if dry_run:
         print(f"[dry-run] {' '.join(cmd)}")
@@ -185,8 +188,9 @@ def validate(target: str) -> None:
     if head != remote:
         raise ReleaseError("current HEAD is not origin/main; switch to main before release prep")
     assert_monotonic(current=read_project_version(ROOT_PYPROJECT), target=target)
-    # Assert the `## Unreleased` anchor in ALL changelog files BEFORE any write
-    # (same list rewrite() promotes) so Phase 2 cannot partially rewrite the tree.
+    # Assert the `## Unreleased` anchor in ALL hand-authored changelog files BEFORE
+    # any write (same list rewrite() promotes) so Phase 2 cannot partially rewrite
+    # the tree.
     for changelog in CHANGELOG_FILES:
         if _UNRELEASED_RE.search(changelog.read_text(encoding="utf-8")) is None:
             raise ReleaseError(f"{changelog} has no `## Unreleased` section")
@@ -214,6 +218,7 @@ def rewrite(target: str, *, bump_core: str | None, bump_host: str | None) -> Non
     today = date.today().isoformat()
     for changelog in CHANGELOG_FILES:
         promote_changelog(changelog, target, release_date=today)
+    sync_docs_changelog()
     rewrite_version_in_files(
         [
             REPO_ROOT / "README.md",