LangBot/dev-docs/DOCS_MIGRATION.md

Documentation subtree and publication

Public docs live in LangBot/docs/. The former internal docs/ directory is dev-docs/ (27 top-level entries, 87 tracked files at migration). Do not merge this migration using GitHub squash or rebase: use a merge commit to retain the subtree parent and original signed commits. Imported history is reachable through the subtree merge's second parent. Use git log <imported-docs-sha> -- <file> (with the original path relative to the docs repository) to see original authors. A path-limited git log docs/ or --follow does not reliably traverse the unrelated-history import. The imported commit is 51dddcb3f891d60bc38645e88b2dbd515344da81 (888 commits, including 452 signed commit objects, all retained without rewriting).

Local checks

With Node.js 24, run npm ci, npm run typecheck, npm test, and npm run build inside docs/. Output is docs/dist/. The site remains mounted at /docs/ with canonical URL https://langbot.app/docs.

Cutover after the PR is reviewed and merged

1. Pause the legacy sync-blog-articles.yml workflow in langbot-app/langbot-docs and let any running writer finish. Freeze direct commits to that repository. Pause its legacy Wiki and landing sync workflows too, avoiding duplicate publishers while switching ownership. Do not push disabling commits directly to the mirror.
2. Fetch mirror main and confirm it is an ancestor of the new subtree split. If it advanced since import, integrate it with an unsquashed git subtree pull --prefix=docs <mirror-url> main through another reviewed PR before cutover; reapply the inert mirror workflow files if necessary. Never force-push or rewrite the mirror history.
3. Verify LANGBOT_WIKI_PUSH_TOKEN is configured in LangBot with existing access to the docs mirror, LangBot Wiki, landing upstream and production fork. The blog job additionally needs to push to LangBot main and trigger workflows. Repository workflow-file updates must be permitted by that token. Do not weaken branch protection to accommodate this migration; use a separately reviewed publication approach if the current token cannot perform the push.
4. Set LangBot repository variable DOCS_MIRROR_ENABLED=true. Dispatch sync-landing-submodule.yml on main. It fetches full main history, runs git subtree split --prefix=docs, verifies the current mirror head is an ancestor, pushes without force, then advances only landing's docs gitlink. The first split replaces legacy mirror workflows with inert manual stubs.
5. Dispatch sync-github-wiki.yml and sync-blog-articles.yml in LangBot. The blog job now commits only docs article paths to LangBot main using the dedicated token, so its push triggers the mirror and Wiki workflows.
6. Confirm the docs gitlink in langbot-app/langbot-landing-page, then confirm production fork RockChinQ/LangBot-LandingPage-Vue matches upstream. This is the actual fork in the existing sync script (not the similarly named fork mentioned in the original migration proposal). Observe Cloudflare Pages deployment and check https://langbot.app/docs/, localized pages, assets, sitemap and canonical URLs. Verify Wiki pages after publication.

The four root workflows own publication and validation. Nested workflow stubs are intentionally inert when split into the mirror. No direct writes should be made to the mirror after cutover; all edits belong in LangBot docs/.

docs/context7.json continues to identify langbot-app/langbot-docs because that repository remains available with the same tree layout and original history. Verify Context7 ingestion after the first mirror update; no library re-registration is needed merely to relocate the authoring source.

Disable DOCS_MIRROR_ENABLED to pause publishers if cutover fails. A failed mirror ancestry check must be investigated and reconciled, never bypassed by a force push. Do not restore direct mirror writers while LangBot is authoritative.