Sunset docs.beamable.com and finish the ReadMe.io migration

[allister-beamable]

docs.beamable.com — the pre-migration ReadMe.io site — is still fully live, still the only documentation the marketing site links to, and still the search-canonical copy. The MkDocs migration that history/readme-io-to-mkdocs-conversion-manual.md on main describes was completed as a content exercise and never as a decommission exercise.

Current state

• docs.beamable.com returns 200 across the board; robots.txt is Allow: /
• Its pages carry <link rel="canonical" href="https://beamable2.readme.io/...">, so search engines are told the ReadMe copy is authoritative
• It serves an llms.txt index — an explicit invitation for AI assistants to read the legacy docs, including "Append .md to any documentation page URL to get its markdown version"
• beamable.com links only to docs.beamable.com. The homepage and every page sampled point at docs.beamable.com/docs/beamable-overview. Nothing on the marketing site links to help.beamable.com
• 316 pages in the ReadMe sitemap

Content parity: what is actually missing

Slug-matched the 316 legacy pages against every live branch, then hand-checked the buckets. 162 have a clear counterpart; 154 did not match — but most of that 154 is renaming noise, not missing content.

Bucket	Raw	Real gap after checking
Unity feature docs (*-code / *-feature-overview)	43	~1. Unity covers these under renamed paths (inventory 3 pages, content 4, stats 2, leaderboards, stores, tournaments, chat, groups, mail, announcements, events, cloud save, notifications, virtual currency all present). The exception is Parties — zero Unity pages
CLI reference	53	~0. Auto-generated and present under nested paths. Includes 20 cli-federation-local-settings-*-ifederatedgameserver-N pages that are ReadMe pagination artifacts of one command
Third-party integration pages	23	~23. The largest genuine gap — see below
Business / operations content	~6	~6. best-practices (actually "Best Practices for Pricing"), support-tiers, security-overview, performance-scalability-overview, publishing, distributing
API reference	8	8. signed-requests plus 7 basic/notification routes. Addressed by publishing api/v1.0 — see the linked issue
Legacy migration guides	2	Judgment call. unity-sdk-migration-process (1.19→2.0) and migration-unity-from-2x-to-30 are almost certainly droppable
ReadMe artifacts	3	Zero. page-not-found, a /discuss link, a license page

The third-party integration pages cover engine plugins, hosting and matchmaking providers, analytics tools, and blockchain integrations. Grep finds only passing mentions inside other pages — no dedicated page for any of them on any branch. Scope for this category is a product decision being handled outside this repo; porting should not start before it is settled, and it is the single biggest unknown in this effort.

Extraction is easy

ReadMe is authored in its own CMS and is not fed from GitHub, so there is no git source for the legacy content. But llms.txt gives a complete page index and appending .md to any URL returns clean Markdown with updatedAt frontmatter. Verified: https://beamable2.readme.io/reference/signed-requests.md → 5 KB of Markdown. A shell loop is sufficient; no scraper needed.

The updatedAt field is the triage signal worth harvesting first. signed-requests reads 2025-11-11 — three weeks after the commit that drafted its replacement on api/v1.0 — so "which copy is newer" has to be checked per page rather than assumed.

The legacy content model, for reference

Legacy descriptions carry tags like [IDEN-Apple-03], [ECON-Stores-06], [SOCL-Chat-02], [LIVE-Mail-02], [PROF-CloudSave-01], [DVTL-Admin-02] — a domain × artifact matrix (Identity / Economy / Social / LiveOps / Player Profile / Developer Tools, crossed with 01 Overview, 02 Guide, 03 Code). Useful when deciding where a ported page belongs.

Work beyond content parity

Parity is necessary but not sufficient. Sunsetting also needs:

• ReadMe-side redirects to the help.beamable.com equivalents, or at minimum noindex
• The marketing site's docs link repointed
• The new site's own canonical tags fixed — they currently point at beamable.github.io, not help.beamable.com (filed separately)
• A scoping decision on the third-party integration pages (tracked offline)
• A home for the version-independent content — see the "product lane" discussion in the comments

Ownership

The takedown itself is a one-way door with marketing implications and needs Vitor's sign-off, and probably someone on the commercial side for the pricing and support-tier pages and for the third-party integration scoping. This issue exists to make the work visible and triage-able, not to commit to a date.

[allister-beamable]

Is there a product lane we are missing?

Yes — one, fairly clearly. Here is the reasoning, and the method so the conclusion can be re-checked.

Method, and how much to trust it

1. All 316 legacy pages from the ReadMe sitemap
2. Every .md on every live branch, normalized to path-token forms so flat ReadMe slugs (cli-project-new) match nested MkDocs paths (cli/commands/cli-command-reference/project/new.md)
3. Titles and one-line descriptions for the unmatched set, joined from llms.txt — this is what turned raw slug misses into a judgment about actual content
4. Hand-checks with find against the branches for each bucket

Confidence is high at the bucket level and medium per page. Slug matching cannot tell a renamed page from a rewritten one, and it cannot detect content that was merged into a differently-scoped page. Anyone porting should re-check individual pages, but the shape below should hold.

The step that mattered most was step 4. The raw diff claimed 43 missing Unity feature pages; checking the branches showed Unity covers essentially all of them under renamed paths — inventory has 3 pages, content 4, stats 2, and leaderboards, stores, tournaments, chat, groups, mail, announcements, events, cloud save, notifications, and virtual currency are all present. The one real exception is Parties: zero Unity pages. That belongs in the Unity lane, not a new one.

What genuinely has no home

After Unity-Latest, Unreal-Latest, CLI-Latest, and a hypothetical API-Latest:

1. Third-party integration pages (~23). Engine plugins, hosting and matchmaking providers, analytics tools, and blockchain integrations. Grep finds only incidental mentions inside other pages; no dedicated page anywhere on the new site. Scope for this category is a product decision and is being handled outside this issue — it is not editorial, and porting should not start before it is settled.

2. Commercial and operational content (~6 pages). Pricing guidance, support tiers, a security overview, a performance and scalability overview, publishing, and sharing microservices between projects.

The structural reason these have no home

Every lane in the current architecture is version-indexed — the branch name carries an SDK or CLI version, and the version selector is the primary navigation axis. Both leftover categories are version-independent. An analytics integration guide does not have a Unity version; support tiers do not have a CLI version. The model has no shelf for content whose identity is not a version, which is exactly why this content stayed behind on ReadMe.

Note the architecture already accommodates this: internal and home are both unversioned branches. So an unversioned lane is precedent, not novelty.

Recommendation

One new lane: integrations (unversioned) — assuming the scoping decision lands in favor of carrying this category forward at all.

The argument is specifically that these pages are cross-cutting, not that they are merely homeless. Some are engine-facing, some are server-side and engine-agnostic, some are API-level. Filing them per-engine would duplicate most of them across Unity, Unreal, and WebSDK and guarantee three-way drift — the same problem the core-owned-paths mechanism exists to solve, but without a sync to solve it. A single unversioned lane, linked from each engine lane where relevant, avoids that.

It would also need a card on the home product chooser, or it is undiscoverable — the chooser is the only thing that makes a lane visible to a reader arriving at the top.

Do not invent a second lane for the commercial content. Pricing guidance and support tiers are sales and account-management material that happens to live in a docs tool. It belongs on the marketing site or in the account portal, where the people who maintain pricing can maintain it. Putting it behind a version selector on an SDK docs site is how it went stale in the first place. The security and performance/scalability overviews are the genuine exceptions in that bucket — those are platform-concept pages and fit core well.

[allister-beamable]

Chain: #134 (publish api/v1.0 — covers the 8 API-reference pages), blocked by #135 (spec-url). Related and required for search-authority transfer, though not labeled part of the chain: #136 (canonical tags). Also surfaced by this work: #137 (104 doc: links, which need the same legacy slug → new path mapping) and #132 (auth grant types).