PRDCT-554: Variables under Components — one home, four override treatments collapsed

[Iamfle4ka]

What & why

Re-cut of phase-2 batch 4 (was #1033, stacked on the big-bang #1027) as a standalone per-unit PR off main, per the 2026-07-27 pivot. Same content/placement as #1033, but with no dependency on #1027's dots-UI / temp "Developer Docs" nav group — so it can be reviewed and merged on its own.

Moves the 2 Variables API pages under the canonical Variables page:

• /transformations/variables/api/ + /transformations/variables/api/tutorial/
• Old /integrate/variables/* URLs keep working via redirect_from.
• Nav: Variables becomes a branch with a "Variables API" child.

Verification

• npm run build clean — 258 pages.
• Live-verified in demo project 264 (GCP EU): a keboola.variables config + {{var}} placeholder resolves at runtime and the value lands in the output data — job 94591978, status: success (default-values path). The inline variableValuesData override path is verified against keboola-sdk-go source.
• node scripts/audit-phase2.mjs: 0 missing images. Broken internal links are all forward-refs from these pages to sibling batches not yet on main (/storage/api, /components/extractors/generic-extractor, /integrate/jobs, /extend/*) — they heal as those units land; acceptable during the incremental merge.

Supersedes

Replaces the stacked #1033 (which will be closed together with the #1027 big-bang stack once the per-unit queue is drained).

🤖 Generated with Claude Code

Placement / dedup audit (2026-08-03)

Ran the placement/dedup pass. Unlike Generic Extractor, this is not a clean stub-replace —
the nav already disambiguates (Variables & Shared Code → Variables API → Tutorial), so
there's no twin-entry problem. What's left is genuinely owner/SME decisions, so I applied
only one safe fix and am surfacing the rest rather than pre-deciding:

Applied: retitled the API page's frontmatter Variables → Variables API (it collided with
the existing Variables page's title; nav already calls it "Variables API").

Open decisions (for Jordan / Matias — not touched):

1. Flow-variable overrides are documented in 3 places, two of them stale:
   • flows/index.md › ## Variables — the current, canonical treatment (conditional-flows UI + JSON).
   • transformations/variables/index.md › ### Flow Usage — outdated (old orchestration screenshots).
   • this PR's …/api/ › ## Orchestrator Integration — outdated term ("orchestration" ×22, pre-conditional-flows).
     → Recommendation: make flows/index.md canonical; trim the Variables "Flow Usage" section to a
     link, and reframe the API page's "Orchestrator Integration" to "Flows" terminology + link. Touches
     the Flows section, so worth a joint call.
2. Shared Code is covered twice — UI walkthrough in transformations/variables/index.md and API in
   this page. Complementary, no dedicated Shared Code home (the nav group is "Variables & Shared Code").
   → Recommendation: cross-link rather than merge; low urgency.
3. Does Variables belong under Transformations at all? It's cross-cutting (components + flows +
   transformations). Jordan raised this on 07-30 → Matias's call. Left as-is pending that decision.

[linear-code]

PRDCT-554

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 7, 2026 11:59pm

[Iamfle4ka]

Owner decisions from the placement audit — resolved

Asked Matyáš. Two of the three open items are settled.

Decision 3 — does Variables belong under Transformations? → no, Components

Variables are a base component (keboola.variables), with no constraint on location. Target section is Components.

Not executed here, deliberately. The migrated …/api/ pages are children of the native Variables & Shared Code page, so the whole branch has to move together — that is a SECTION-MAP call, not something a migration PR should do. Recorded in SECTION-MAP.md as three MOVES rows (/transformations/variables/ + the two API children, conf: owner (Matyáš, 2026-08-04)), with the section counts adjusted: Transformations 22 → 19, Components 223 → 226. The owner call settled the section; the exact target slug is our proposal.

Decision 1 — flow-variable overrides in three places → first half applied

/flows/ is canonical; our copy here was stale (pre-conditional-flows orchestration screenshots). Pushed in 6df28b9c: the ### Flow Usage section in transformations/variables/index.md is trimmed to a cross-link.

Worth flagging what the fact-check caught, because my first attempt was wrong: I originally linked /flows/#variables, which is the Set Variable UI — a different mechanism from the one the sentence described. Corrected to name both real routes with the anchors that actually document them:

• name-matching merge → #how-variables-reach-component-jobs
• per-task override in advanced parameters → #control-task-execution

Conservation: every removed paragraph, screenshot and JSON block survives in flows/index.md, flows/flows-legacy/index.md, or this PR's own …/api/ page. The one sample with no home elsewhere was the {"config": "6939", "variableValuesData": {…}} snippet — and it was wrong: it omits componentId, which the job API requires (job-queue-internal-api-php-client → NewJobDefinition.php marks it isRequired()->cannotBeEmpty()). Not restored.

Also dropped orchestration-parameters.png and task-parameters.png (both copies each) — referenced only by the removed section. /flows/task-parameters.png is a different file (different checksum) and is untouched.

Still open

• Decision 1, second half — reframing this PR's ## Orchestrator Integration into Flows terminology is not in this commit. Of the 22 orchestrat* occurrences on that page, some are the literal component id keboola.orchestrator and real API calls, which must stay; it needs a legacy-term-vs-valid-id pass, not a rename. Filed separately.
• Decision 2 (Shared Code covered twice) — unchanged, still cross-link-not-merge, low urgency.

Verification

npm run build clean (258 pages). audit-phase2: 0 missing images, both new anchors resolve, no new findings. The 17 broken internal links are the same forward-refs to sibling batches documented in the PR body.

One finding for the Flows owner, not for this PR

flows/index.md:43-52 (Control Task Execution) reuses the legacy Task Parameters screenshot and the “Set advanced parameters” label verbatim from flows-legacy, and its bullet list was only partly updated for Conditional Flows. Since this page now cross-links that mechanism, the label and screenshot are worth confirming against the current builder.

[Iamfle4ka]

Placement decided: Flows (owner, 2026-08-05)

Jordan's option from the 07-30 call. /transformations/variables/ → /flows/variables/, with the API pages as its children; all five old URLs keep working via redirect_from (verified in dist).

The loop this closes

Overriding a configuration variable from a flow was documented in four places, two of them stale:

Where	State
transformations/variables › Flow Usage	stale (2019 Orchestrations screenshots)
flows/index.md › ## Variables	current
flows/index.md › Control Task Execution	the only one with current UI
variables/api › Orchestrator Integration	documented the legacy component as current

They collapse into one section, Driving a Configuration Variable from a Flow.

Corrected against the live flow schemas

• Conditional flows are keboola.flow; keboola.orchestrator is legacy. The API section now splits accordingly: conditional (variable tasks, merge-by-name, variableOverrides tri-state) vs legacy (the inherited task payload, labelled and cautioned).
• "value": 3600 → "3600" — the schema declares variable values as strings, so unquoted numbers fail validation.
• "If you omit thirdVar, it will be replaced by an empty string" is wrong; configuration-variables-resolver throws Missing values for placeholders: ….
• Tutorial blocker: the run-job body inlined '$VARIABLES_VALUES' unquoted, so bash word-split it — curl received JSON truncated at "values": plus 12 stray argv words. It only ever worked in zsh. Now a heredoc on stdin, verified byte-identical and json.load-valid in both shells.
• actionParameters was dropped: it belongs to the pre-keboola.orchestrator component, not to the one the heading now names.

Shared Code moved out

It substitutes code, not values, and only for transformations → /transformations/shared-code/ (UI + the API section lifted off the Variables API page), 17 images with it.

Verification

• npm run build clean, 309 pages.
• audit-phase2: broken links 54 → 54, missing images 0, one old-docs smell fixed (156 → 155 total) — measured against this branch's own tip, not main.
• feat(audit): validate link anchors, not just link paths #1073's anchor checker: no new broken anchors. The two on the API page (config-file/#input-mapping--basic) resolve once fix(extend): render the config-file mapping headings, repair their anchors #1069 lands — it converts those --- headings to em dashes, which slug to exactly the two-dash form linked here.
• flows/index.md drops 391 → 227 lines.
• fact-checker and guide-tester both run; everything they flagged is either fixed above or listed below.

Left for the owner

• VERIFY: whether a legacy keboola.orchestrator task honours variableValuesId / variableValuesData, and whether run-level values override per-task ones. Inherited from developers.keboola.com, absent from every public orchestrator schema — now carries an inline caution instead of reading as current behaviour.
• VERIFY: that Task Parameters on a conditional-flow task accept variableValuesData and the runner forwards them; the keboola.flow schema declares neither.
• The Configuration Variables section has no numbered click path and its screenshot is 2021-era — screenshots are PRDCT-594: reshoot the flow screenshots that showed retired UI #1078's scope, deliberately not touched here.
• Tutorial polish not done: the token step doesn't name the master token, and "Check the job result" has no text success criteria (both screenshot-only today).

[Iamfle4ka]

Moved to Components (08-08)

Placement is settled, so the move is folded in here rather than left to a follow-up PR.

• Jordan, 08-05 sync: Components is the correct home — "flows are technically a component, as are transformations".
• Matyáš, 08-07 in #ask-component-factory: "Call it Variables and I don't mind wherever it is. Components as a page is fine." That also answers the second question I asked him — there is no separate "Variables API" product; the calls are configuration/Storage API plus Vault.

What changed

	before	after
pages	/flows/variables/{,api/,api/tutorial/}	/components/variables/{,api/,api/tutorial/}
child page title	Variables API	Variables Through the API
nav	under Conditional Flows	under Components, next to Running Jobs in Parallel

No new redirects were needed. /flows/variables/ only ever existed on this branch, so folding the move in now costs nothing; landing first and moving later would have published a URL we would retire days later. The five live URLs still resolve — verified in dist:

/transformations/variables/              OK
/transformations/variables/api/          OK
/transformations/variables/api/tutorial/ OK
/integrate/variables/                    OK
/integrate/variables/tutorial/           OK

43 references repointed across 12 files; the PageTitle.astro emoji key follows the slug. Build clean at 311 pages, audit-phase2 reports 0 missing images.