PRDCT-470: phase-1 dev-docs migration — one script run (165 pages)

[Iamfle4ka]

Draft — phase 1 of the dev→help merge, fully script-driven (per Jordan: the migration must be a script, verifiable by validating the code — no LLM moving content by hand).

How to verify

Review commit 1 (scripts/migrate-devdocs.mjs) — it is the complete spec of every transformation. Commit 2 is its output:

git archive devdocs/main | tar -x -C /tmp/devsrc
node scripts/migrate-devdocs.mjs /tmp/devsrc

reproduces the tree byte-for-byte (idempotent — a second run changes nothing; collision baseline is the upstream/main tree).

What it does

• 165 pages ported 1:1 at preserved paths from devdocs/main@429efb38: automate/, integrate/ (incl. the jobs/ Queue-API page), extend/ (84 pp), overview/api/ + overview/encryption/; cli/ → cli/keboola-as-code/ ("Keboola as Code CLI") with a scripted :::caution[Deprecated] banner → kbagent CLI (Jordan's call, Jul 15).
• 10 pages skipped — already woven into help by the open weave PRs PRDCT-544: fold dev SSH-tunnel how-to into /components/extractors/database/ #1019 / PRDCT-540: combine dev+help home and overview (top-down pilot) #1022 / PRDCT-541: merge dev data-streams into /storage/data-streams/ #1023, MCP canonical, dead chrome. Full list in MIGRATION-REPORT.md.
• Conversions encoded in-script (all gaps from the pilot ports): {% include %} inlining (beta-warning → admonition), Jekyll literal-escape moustache, scalar redirect_from, relative image refs → absolute public paths, CSV/ZIP assets, kramdown/liquid syntax, one documented source-typo link fix (brabch→branch).
• Links: help-domain stripped, dev-domain internalized (everything migrates together), skip-map targets → canonicals, 57 inbound links across help flipped to internal (weave-PR files excluded to avoid conflicts).
• Redirects: /integrate/mcp/ → /ai/mcp-server/, /integrate/database/ → /components/extractors/database/, /integrate/orchestrator/ → /flows/ injected into the canonical pages (frontmatter-scoped, indent-matched). Data-streams redirects ride with PRDCT-541: merge dev data-streams into /storage/data-streams/ #1023.
• Nav: temporary collapsed Developer Docs group. Phase 2 = topic re-placement per the approved placement map (PLACEMENT-MAP artifact) — former dev pages become normal peers in their topic sections and this group disappears.

Verification

• npm run build clean — 423 pages, 184 redirect pages.
• audit-phase2: 0 new broken links, 0 missing images (heals 1 pre-existing break — the importer page now exists). The 2 remaining broken links pre-date this PR on main.
• All 3 injected redirects resolve in dist/; deprecation banner renders on /cli/keboola-as-code/.

Supersedes

#1020 / #1021 / #1024 / #1025 (closed) — their scopes re-execute here with zero hand edits. Weave PRs #1019 / #1022 / #1023 remain separate (owner-level content merges).

Gate note: the 10 open developers-docs fix-PRs (#391–#398, #402, #383) should merge and this PR re-run before final review, so their corrections ride along.

🤖 Generated with Claude Code

[linear-code]

PRDCT-470

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview, Comment	Jul 17, 2026 5:16pm

[Iamfle4ka]

Why 165 of 175 — the 10 skipped pages, explained

The skip list is part of the script (SKIP map, with a reason per page) and mirrored in MIGRATION-REPORT.md — nothing is silently dropped. The rule: the script does mechanical 1:1 moves; pages whose content had to be merged into an existing help page (weaves) are owner-level editorial work and live in their own reviewable PRs. Porting them here as well would either hard-collide with an existing help slug or duplicate the same content in two open PRs.

dev page	why skipped	where its content lives
/ (dev home)	slot / is help's home — the two homepages were hand-woven into one	weave #1022 (conservation ledger + blanked-source audit attached there)
/overview/	same — the two "Keboola Overview" pages combined	weave #1022
/overview/repositories/	killed; its one useful line folded into the overview	#1022 (301 rides there)
/integrate/data-streams/ (+ overview/, tutorial/ — 3 pages)	woven into the canonical Data Streams home; porting here would duplicate content across two open PRs	weave #1023 → /storage/data-streams/… (301s there)
/integrate/database/	SSH-tunnel how-to already folded into the canonical connectors page	fold #1019; this PR injects the 301
/integrate/mcp/	content already merged into the canonical MCP page (live on main)	/ai/mcp-server/; this PR injects the 301
/integrate/orchestrator/	empty stub — the source contains only a Jekyll comment ("merge with automate")	301 → /flows/ injected by this PR
/404.html	dev-site chrome; help has its own 404	not migrated

Net effect after this PR + the three weave PRs merge: every one of the 175 dev URLs either serves its ported page or 301s to its canonical help home.

[Iamfle4ka]

Nav updated: the Developer Docs group now mirrors the dev site's own navigation tree 1:1 (163 nested entries — same expandable-group markup as every other section, so drill-down/chevrons/dot styling are consistent). Generated by the script from the dev repo's _data/navigation.yml (Home dropped, overview children promoted, weave-owned pages pruned, cli remapped). Idempotency re-verified.

[Iamfle4ka]

fact-checker pass on /overview/encryption/ — source facts clean; exposed 2 script bugs (fixed in 53c7fbed)

All 13 factual claims CONFIRMED against keboola/object-encryptor source + README: every cipher prefix and its cloud mapping (ProjectSecure=AWS/KMS, ProjectSecureKV=Azure/AKV, ProjectSecureGKMS=GCP, plus Component/Config/ProjectWide/BranchType variants), region-boundedness by wrapper design, the #-prefix auto-encryption rule, and the POST /encrypt endpoint + Content-Type semantics. Zero drift from the dev source.

The pass also caught two silent bugs in the migration script's link rewriting (targets existed, so the audit couldn't see them): prefix-matching single-page skips swallowed ported siblings and even image paths (/overview/api/#regions… and both encryption-N.png screenshots collapsed to /overview/), and exact-skip rewrites dropped #anchors. Fixed in-script (53c7fbed) — corrects 22 ported pages; idempotency and audit re-verified.

[Iamfle4ka]

Transitional UI added (f4e5ecd): every sidebar entry that migrated from developers.keboola.com now carries an accent dot (pages + their groups, incl. the Developer Docs root) with a legend at the bottom of the sidebar — so the dev origin is visible at a glance while the seam still exists. CSS-only (custom.css), theme-aware, verified in a production build in both themes; the block is explicitly marked TRANSITIONAL and gets deleted in phase 2 together with the Developer Docs group. Check the Vercel preview sidebar.

[jordanrburger]

Devdocs migration chain review (#1027 → #1029 → #1031 → #1032 → #1033)

Overall: high-quality, mechanically sound work. Script-generated (scripts/migrate-devdocs.mjs) with self-documenting MIGRATION-REPORT.md / PLACEMENT-MAP.md outputs and reproducible. The build-safety-critical properties were verified directly against the branches, not just taken from the reports.

Check	Result
Frontmatter (title+slug) on all 199 ported pages	✅ complete
Duplicate slugs (would break the build) — phase-1 and full-stack final state	✅ 0 across 421 pages
Jekyll/Liquid leftovers ({%, {{, permalink:)	✅ 0
Moves faithful (no dropped content)	✅ #1031's 3 "removed" files = 3 re-added at new path; 0 dangling links to vacated generic-extractor/generic-writer paths
Redirects on moved pages	✅ 204 pages carry redirect_from; 38/40 generic-extractor pages
Migration script location	✅ scripts/ (tooling, not published content)

Per-PR verdicts

• PRDCT-470: phase-1 dev-docs migration — one script run (165 pages) #1027 — phase-1, 165 pages (+32k / 606 files). Merge with nits. 199 md + 199 images; 3 redirects injected into existing canonicals; 9 Jekyll includes correctly inlined to admonitions; nav mirrored (161 entries). Build-safe.
• PRDCT-551: phase-2 batch 1 — Storage API pages to their topic home #1029 — batch 1, Storage API → storage/api/*. Merge with nits. Clean topic-home consolidation.
• PRDCT-552: phase-2 batch 2 — Generic Extractor pages to their topic home #1031 — batch 2, Generic Extractor extend/ → components/extractors/generic-extractor/ (+ images to public/). Merge with nits. 83 renames + 3 remove/add pairs (no loss), cross-links rewritten.
• PRDCT-553: phase-2 batch 3 — Generic Writer pages to their topic home #1032 — batch 3, Generic Writer → components/writers/generic-writer/. Merge with nits. Small, clean.
• PRDCT-554: phase-2 batch 4 — Variables API pages under Transformations #1033 — batch 4, Variables API → transformations/variables/api/. Merge with nits.

Nits / follow-ups (none block the build)

1. ~6 inbound links in existing help pages (e.g. components/extractors/database/index.md, transformations/python-plain/index.md, tutorial/index.md) still point to https://developers.keboola.com/... targets that now exist in-repo. The report flags this as inbound links flipped: 0 — deferred by design. Worth a cleanup pass once the tree lands so they become internal links.
2. 9 internal links still point at pre-move /integrate/storage or /integrate/variables paths. They resolve (via the redirects) but aren't canonical — should be updated to /storage/api/… and /transformations/variables/api/….
3. 26 self-referential absolute https://help.keboola.com links across the tree — should be relative.
4. Domain-level 301s for the retired developers.keboola.com URLs are out-of-repo (edge/ops) — track separately so external inbound links don't dead-end.

Merge order (hard dependency)

Bottom-up, one at a time: #1027 → #1029 → #1031 → #1032 → #1033. Each is stacked on the previous branch; GitHub auto-retargets each to main as the one below merges (or rebase). Since the phase-1 /extend/ pages never shipped, the whole stack could alternatively collapse into a single merge — but the staged order is clean as-is. All five are still drafts, so nothing merges until they're marked ready.

Automated review pass (Claude Code), reviewed by a human maintainer — not an approval. Verified against the PR branches (frontmatter/slug/redirect/link scans); page prose was sampled, not exhaustively read.

[linear-code]

Nits 1–3 addressed in [#1036](#1036) — one commit stacked on #1033's branch, so it merges last. Counts at commit time were 19/9/24 (your 6/9/26 had drifted as branches moved); self-link traps and dead anchors got judgment rewrites, all listed in the PR body. Audit issues on the branch drop 56 → 13 with no new findings. Nit 4 (edge-level 301s for the retired dev domain) is tracked as a follow-up in PRDCT-560.