ci(docs): sync SDK and example READMEs to their dev.dotcms.com pages

[jdcmsd]

Closes #38024

Proposed Changes

• Adds .github/workflows/publish_readme-docs.yml. It copies markdown files from this repo, mostly the SDK and example READMEs, into their documentation pages (DotcmsDocumentation contentlets) on the dotCMS authoring server.
• Today dev.dotcms.com mirrors these READMEs from GitHub at request time (GITHUB_DOCS_MAP in the devsite). After this change the text lives in dotCMS, where search indexes it. The file stays the single source of truth: each run overwrites the page body, and dotCMS keeps the version history.
• The page list lives in dotCMS, not in this workflow. Every documentation page whose new readmeSource field holds a https://github.com/dotCMS/core/blob/main/<path>.md URL is synced. Adding or removing a page is a field edit in dotCMS and needs no core PR. URLs pointing anywhere else (other repos, npm) are left alone.
• Runs on every merge to main that touches a *.md file, about 4 a day, each taking a few seconds. Each run checks all mapped pages and writes only those whose body differs, so a newly mapped page fills in on the next markdown merge.
• The cleanup matches the devsite's live mirror. It drops the "Table of Contents" section and the first H1 (both ignored inside code fences), and points relative links and images at GitHub.
• Each changed page goes through the authoring server's Push Publish workflow action (save, publish, unlock, push to the prod environment), with "disabledWYSIWYG": ["documentation"] so the markdown is stored as markdown (the same flag issue_autodoc.yml uses). The run then finds that page's push bundle in the publishing queue and waits for it to succeed.
• Safeguards:
  • The token is checked first. An invalid token would otherwise still read the public pages as anonymous.
  • If no mapped pages are found, the run fails rather than doing nothing.
  • Source paths must be normalized relative .md paths that exist in the checkout.
  • Each page is compared with its current version read directly, not with search results, which can lag behind recent saves.
  • A save that fails with a dotCMS 5xx error is retried once. During testing, dotCMS failed saves intermittently, and a retry always succeeded. If the save still fails, the page is unlocked.
  • The push is confirmed through its bundle. The action returns success even when the user may not push to any environment; the bundle then never moves, and the run fails with a hint about the environment permission.
• Credentials: the existing AUTODOC_DOTCMS_BASE_URL var, and a new AUTODOC_DOTCMS_API_TOKEN_PUBLISH secret (already added) for the CI Autodoc Publish User. That user exists only on the authoring server, so production applies pushes as its system user. Its Dev Publish role needs View, Edit and Publish on the site, the same on the Documentation content type (which lives on System Host), permission to use the Push Publish action, and permission to push to prod. The draft-only autodoc user and secret are unchanged; autodoc's new docs still go through human review.
• A manual workflow_dispatch is available. It is a dry run by default, posts per-page diffs to the run summary, and can be limited to specific pages by urlTitle.
• On failure, dotBot DMs a fixed list of people (NOTIFY_GITHUB_USERS, looked up in .github/data/slack-mappings.json). This posts directly with SLACK_BOT_TOKEN. It does not use or change the shared channel resolver or the PR notifier.

Currently mapped (12 pages): the 8 core-web/libs/sdk/* libraries, core-web/apps/mcp-server, and the examples/{nextjs,angular,astro} READMEs.

Checklist

• Tests:
  • Passes actionlint (shellcheck and pyflakes clean).
  • The inline script was run locally against the authoring server on a clean checkout of main:
    • all 12 mapped pages found and unchanged; they were seeded with this same cleanup;
    • the page filter works, and an unknown page name fails;
    • a locally edited README produces the expected diff, with its relative link rewritten;
    • an invalid token fails immediately;
    • the path checks reject .., absolute and non-.md paths, fail on missing files, and skip other repos and npm.
  • Real runs with the publish token:
    • sdk-events-library picked up a README change merged after seeding, and its push to prod succeeded.
    • sdk-types-library was given a draft that differed from the README; the run detected it, published and pushed the README text, and confirmed bundle SUCCESS in about 30 seconds. A dry run afterwards reports all 12 pages unchanged.
  • Not exercised live: the 5xx retry path, and the stalled-bundle timeout. That stall is the failure the bundle check exists for: an earlier manual test without the environment permission left a bundle stuck at BUNDLE_REQUESTED.
• Translations: N/A
• Security Implications Contemplated:
  • permissions: contents: read. The dotCMS credential is a non-admin publishing user limited to the Dev Publish role. Run summaries are public and contain only markdown text and diffs.
  • Merges to main now reach production without a person checking the page. The text is reviewed repo markdown, and dotCMS keeps every version, so any page can be restored.
  • Because the mapping lives in dotCMS, anyone who can edit documentation pages can point a page at any markdown file in this repo, and that file would then be published.

Additional Info

• All 12 pages are already seeded, published and pushed (and sdk-events-library is current), so the first run after merge should report everything unchanged.
• The authoring server runs two instances. During testing, one of them refused the publishing user's new permissions until caches were flushed. If runs fail on alternate attempts with a 403 on the content type, flush caches. A manual dry run is a good smoke test: Actions → Publish README Docs → Run workflow.
• Out of scope for now: the PHP SDK pages (private dotcms-php-sdk repo) and the .NET example page. Removing the synced entries from the devsite's GITHUB_DOCS_MAP is a separate follow-up.

🤖 Generated with Claude Code