PRDCT-540: combine dev+help home and overview (top-down pilot)

[Iamfle4ka]

Draft — pilot of the top-down dev→help unification (per the Jordan sync). Rather than porting more sections bottom-up (automate #1020, integrate #1021), this combines the two most-duplicated pages first — the two homepages and the two "Keboola Overview" pages — because they frame the whole combined site. Review the real combined pages on the Vercel preview.

What changed

• Home (index.md): woven help's user orientation + dev's technical framing; new Work with Keboola Programmatically section with the three dev pillars (Integrate / Extend / Automate). Dropped the "separate docs for developers / end-users" framing and the developers.keboola.com resources link — one site now.
• Overview (overview/index.md): help's richer page is the base; added a Diátaxis Working with Keboola Programmatically technical layer (API-driven, open source, common component structure). Deduped the KBC note; MCP → cross-link to canonical /ai/mcp-server/. Kept help's current architecture diagram, dropped dev's outdated one.
• Development Project block parked at /extend/development-project/ with a VERIFY(owner) flag; linked once from the home.
• Redirect: dev /overview/repositories/ (Kill) → /overview/.

Conservation ledger (every dev source paragraph accounted for)

dev home (/)

dev content	destination
"for developers / end-users → help" framing	dropped (one site)
"What Keboola Is" (open, extensible, REST-API components)	→ home intro (technical framing)
"Where to Start" pillars (Integrate/Extend/Automate)	→ home Work with Keboola Programmatically
MCP mention	→ home + overview cross-link to /ai/mcp-server/
Development Project block	→ parked /extend/development-project/ (VERIFY owner)

dev overview (/overview/)

dev content	destination
"open system orchestrated via REST APIs"	already in help overview + home framing
KBC naming note	dedup — help overview already had it
Architecture + kbc_structure.png	help's project-structure1.png kept; dev diagram dropped (outdated: "Keboola Connection", Extractors/Writers)
Working with Keboola / Common Features / Running Jobs / Components Configuration	→ overview Working with Keboola Programmatically
Specific Components (Storage, Transformations)	folded into component breakdown + Storage API links
Model Context Protocol	→ cross-link canonical /ai/mcp-server/
/overview/repositories/ (Kill)	GitHub-repos line folded into overview; 301 → /overview/

Notes / follow-ups

• The three home pillars point at developers.keboola.com/{integrate,extend,automate}/ for now; flip to internal /integrate/ and /automate/ once PRDCT-538: migrate dev automate/ into help (pilot + converter) #1020/PRDCT-539: migrate dev integrate/ (clean remainder) into help #1021 merge (extend when that section migrates).
• VERIFY(owner) on the Development Project offer (limits, "3 orchestrations", process may be stale) — Linear issue to follow.

Verification

• npm run build clean (259 pages; /overview/repositories/ redirect resolves to /overview/).
• node scripts/audit-phase2.mjs: 0 broken internal links / 0 missing images introduced (the 3 broken links flagged are pre-existing on main, unrelated to these pages).
• Rendered HTML spot-checked: pillars + programmatic section render, KBC note appears once, MCP cross-link present, VERIFY flag renders.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 4, 2026 8:22am

[Iamfle4ka]

Blanked-source audit (Jordan's strikethrough method)

Per the agreed mechanic: every paragraph of the two merged dev pages is struck out and replaced with its destination. If any real text remained un-marked, it was missed — after commit b75c51e6 (which weaves two clauses this audit caught), the residue is zero.

dev / (home, index.md) — blanked

---
title: Keboola Developers Documentation
permalink: /
---
> MERGED — one site: help `/` is the single homepage; this page ceases to exist.

~~This documentation site is aimed for developers … separate documentation at help.keboola.com.~~
> KILLED — the "two sites / two audiences" framing is deliberately removed (one site now).

## What Keboola Is
~~Cloud based, extremely open and extendable, Keboola is the ideal environment …~~
> MOVED → `/` home intro ("Keboola is an open, extensible platform…").

~~The Keboola system consists of many independent and loosely connected components … through (mostly REST) APIs.~~
> MOVED → `/` home intro ("…a system of independent, loosely coupled components orchestrated together through (mostly REST) APIs").

## Where to Start
~~- Integrate Keboola with other systems (Storage API / data-handling backbone / wrap in your own UI / control pipeline from outside / MCP)~~
> MOVED → `/` § *Work with Keboola Programmatically* — Integrate bullet. "Wrap it in your own UI" was caught by this audit and added in `b75c51e6`. MCP → `/ai/mcp-server/` (canonical).

~~- Extend Keboola by building your own components (arbitrary Docker images / generic extractor)~~
> MOVED → `/` § *Work with Keboola Programmatically* — Extend bullet.

~~- Automate your processes (intervals / trigger programmatically when something happens)~~
> MOVED → `/` § *Work with Keboola Programmatically* — Automate bullet.

## Development Project
~~(3.5 GB storage / Snowflake / 10 users / 3 orchestrations; fair-use conditions; register in Developer Portal; email template)~~
> MOVED → `/extend/development-project/` — parked page flagged `VERIFY(owner)` (offer may be stale); linked from the home Extend bullet.

Residue: none.

dev /overview/ (overview/index.md) — blanked

---
title: Keboola Overview
permalink: /overview/
---
> MERGED — same slug as help `/overview/`; the combined page lives there.

~~Keboola is an open system of many components orchestrated together through (mostly REST) APIs. Although quite complex, it is modular …~~
> MOVED → `/` home intro (open system, REST APIs); the modularity point carries via `/overview/` § *Working with Keboola Programmatically* ("once you've worked through one, you've seen them all").

~~KBC naming note~~
> DEDUP — the identical note already exists on help `/overview/`.

## Keboola Architecture
~~(kbc_structure.png + "All Keboola parts are briefly described here → help")~~
> KILLED — diagram outdated ("Keboola Connection", Extractors/Writers naming); help's current `project-structure1.png` kept. The sentence pointed at help `/overview/` — now this very page.

## Working with Keboola
~~Everything in the UI can be done via the API; api.keboola.com; public GitHub; endless possibilities.~~
> MOVED → `/overview/` § *Working with Keboola Programmatically* (intro paragraph).
> Exception: ~~"Docker components are built on AWS ECR"~~ → KILLED — internal infra detail; if needed its home is the `/extend/` deployment reference (ported in #1025).

## Component Common Features
~~(configuration + running jobs + orchestrations; open source → repositories; synchronous actions; Developer Portal API / Get app detail)~~
> MOVED → `/overview/` § *Working with Keboola Programmatically* — Configuration/Jobs bullets; "open source on GitHub" in the intro (this also absorbs the killed `/overview/repositories/` page, which 301s → `/overview/`); synchronous actions + Developer Portal API sentence added in `b75c51e6` (caught by this audit). Orchestrations → Flows.

### Running Jobs
~~(`/run` call, `config` vs `configData`, queues an async job, full API description link)~~
> MOVED → `/overview/` — Jobs bullet (condensed; deep job detail lives at `/management/jobs/` + the Queue API reference).

### Components Configuration
~~(stored in Storage, Configurations API, referenced in `/run`; JSON schema; generic Docker Component schema)~~
> MOVED → `/overview/` — Configuration bullet.
> Exception: ~~JSON-schema / generic Docker Component schema detail~~ → KILLED here — deep reference; canonical home is `/extend/job-queue/#configuration` (ported in #1025).

## Specific Components
~~(Storage, Transformations API links)~~
> DEDUP — help `/overview/`'s component breakdown already covers Storage + Transformations with links.

## Model Context Protocol
~~(2 paragraphs + MCP integration guide link)~~
> MOVED (condensed) → `/overview/` one-line mention + cross-link to canonical `/ai/mcp-server/` (one-canonical-home rule; full MCP content lives there).

Residue: none.

Legend: MOVED = woven into the combined page · DEDUP = identical content already on the canonical help page · KILLED = intentionally dropped, with reason · MERGED = page identity collapsed into the help page at the same path.

[linear-code]

PRDCT-540

[Iamfle4ka]

fact-checker pass — clean ✅ (+ diagram proposal)

Fact-check of both combined pages (agent run, sources cited): all top testable claims CONFIRMED — the 5-stack list matches live reality and every stack URL resolves; deployment options identical to pre-merge main; the trial-wizard URL resolves; api.keboola.com / Developer Portal API / /ai/mcp-server/ / /extend/development-project/ links all valid. No CRITICAL/MAJOR/MINOR findings. The only open item stays the already-flagged VERIFY(owner) on the Development Project offer numbers (3.5 GB / Snowflake / 10 users / "3 orchestrations" — ported verbatim, no public source; note "orchestrations" is legacy wording).

Architecture diagram proposal (Jordan, Jul 15: concept-level "can never get outdated" vs the current logo-specific PNG that names Redshift/Synapse/Exasol/MLflow): a from-scratch editable SVG — sources → connectors → Storage ⇄ transformations/workspaces → destinations → consumption, with Flows and Governance bands, extension points dashed, no vendor names. Side-by-side comparison: https://claude.ai/code/artifact/cb25a54e-0fa3-4b8a-a6db-3f6a72a11b3d — say the word and I swap it into /overview/ on this branch (current PNG kept in git history).

[Iamfle4ka]

Rebased onto main — CONFLICTING → MERGEABLE.

The whole of overview/index.md conflicted, but the real deltas were small on both sides, so I re-folded rather than picked a side:

• From main: the rewritten Keboola CLI subsection (kbagent as the CLI, legacy Keboola-as-Code demoted) — kept as-is.
• From this branch: the redirect_from: /overview/repositories/ frontmatter, the two https://help.keboola.com/… → relative link fixes, and the folded ## Working with Keboola Programmatically section.

Result has all three: 0 absolute help.keboola.com self-links, the redirect intact, and main's kbagent copy untouched. npm run build clean (307 pages = 306 + the /overview/repositories/ redirect), audit-phase2: 0 missing images, no new findings sourced from /overview/.

[Iamfle4ka]

Heads-up for whoever rebases this: #1120 now ships src/content/docs/extend/development-project/index.md at the same slug, moved from the dev home's "Development Project" section, with the three help links that pointed at developers.keboola.com/#development-project flipped to it and a VERIFY(owner) on the offer's figures. When this branch rebases onto main after #1120, drop its own copy of that file and keep the rest of the home/overview weave.