PRDCT-582: merge the last 8 dev pages into help, keeping what is current and not already there

[Iamfle4ka]

Linear: PRDCT-582 · closes the tail units PRDCT-665 · PRDCT-666 · PRDCT-667 · settles six of the seven PRDCT-550 calls · unblocks PRDCT-565.

Re-cut 2026-09-22, after #1132

While this PR waited for review, #1132 (approved by Jordan, merged 2026-09-21) ported the same three dev pages verbatim onto other slugs: /extend/encryption/, /extend/jobs/ and /overview/api/ (kept as a page), and repointed 26 links at them. That put two homes on the table for each. The owner call was to keep #1132's slugs and cut this PR down to what main still lacks, plus the reviewed content where it is better.

So this PR now:

• adds what main does not have: Artifacts (reference + tutorial), /flows/schedule-api/, /extend/development-project/
• replaces the 497-line verbatim /extend/jobs/ with the 303-line version reviewed here (same slug, every anchor main links still resolves), and gives job states one home at /extend/jobs/#job-status
• carries onto main's pages two facts and three lines: the OAuth host for US Virginia GCP was the EU Frankfurt one (GET connection.us-east4.gcp.keboola.com/v2/storage says oauth.us-east4.gcp.keboola.com); the scheduler row now links /flows/schedule-api/ instead of the dev domain; one sentence on the services array as the authoritative host list; two cross-links on /extend/encryption/
• drops its own copies at /overview/apis/ and /extend/common-interface/encryption/; neither was ever published, so no stubs

Commits, in order: efa719f8 merge of main (link conflicts resolved toward main's slugs, this branch's rewrites kept), 206e477a the jobs page swap, 06c70dea the drops and repoints, 1460336f the two facts.

Not carried, by that decision: main's /overview/api/ keeps the API catalogue, the 144-line endpoint table and the Apiary console section that this PR had cut. The table is fixed where it was wrong, not removed. If the cut is still wanted, it is a follow-up on that page.

What

The dev pages with no home on help are merged the way the 2026-07-30 rule asks: the information goes into the page where the concept already lives, links are repointed, the old URL redirects.

dev page	verdict	where it lives now
/overview/api/ (284 lines)	catalogue + endpoint table duplicate the portal and GET /v2/storage	main's /overview/api/ from #1132 stays; this PR fixes the US-GCP OAuth host, repoints the scheduler row, adds one sentence
/overview/encryption/ (154)	accurate, nothing like it on help	main's /extend/encryption/ from #1132 stays; +2 cross-link lines
/integrate/jobs/ (504)	the API how-to and state semantics are new; the field dump duplicates swagger	/extend/jobs/, content replaced by the reviewed version
/automate/run-job/ (53)	duplicate of "Run a job"	folded into /extend/jobs/, redirect_from added
/automate/run-orchestration/ (56)	false claim about one component for Orchestrator and Flow	corrected in /extend/jobs/#run-a-flow, redirect_from added
/automate/set-schedule/ (308)	Scheduler API is not on help; four full dumps say the same thing	/flows/schedule-api/ (123 lines), new
/integrate/artifacts/ + tutorial (354)	unique, code-verified; one wrong config key	/extend/common-interface/artifacts/ + /tutorial/, new
dev home, "Development Project"	the offer was being republished	/extend/development-project/, new

Dropped, and why (conservation log)

Applies to the pages this PR now owns (/extend/jobs/, /flows/schedule-api/, Artifacts). The API-page cuts are listed above as not carried.

• Job object dump (120 lines), component-list response (35), two job responses (45 each). Trimmed to the fields the calls need; the schema is in the Queue API reference.
• "The same component is used for both Orchestrator and Flow jobs." False: the job queue defines keboola.orchestrator and keboola.flow separately (audit PRDCT-369, JobFactory.php).
• Postman deep links on the jobs page. Replaced by the API reference.
• Three of four Scheduler request/response dumps; scheduler.azure.keboola.com. No swagger server lists that host; the page names the two production hosts the swagger does list.
• Screenshots: orchestration-parameters, job-row-parameters.

Corrections carried from the audits

• Artifacts: the shared-artifacts config key is shared, as in job-queue's Artifacts.php, not orchestration (PRDCT-368 A13, its fix PR was never merged).
• Jobs: five job types, not four; retryContainer listed with a VERIFY(owner) for its description (PRDCT-368 A1). [job types](todo) → a real anchor. Three typos.
• Scheduler: the master-token requirement is not confirmed by the code (CanModifySchedules), so it is a VERIFY(owner), not a statement.
• Artifacts "preview feature" note: kept, with a VERIFY(owner) — not checkable from public sources.

Links

Dev-domain links in src/: 52 on main → 47 here. The 11 links this branch had aimed at its own slugs now point at main's. /storage/api/import-export/ keeps /storage/jobs/: that sentence is about a Storage async job, not a Queue job, so the mechanical repoint to /extend/jobs/#job-polling in #1132 was reverted there.

Verification

Full build of the committed tree, 2026-09-22:

Check	main	this PR
npm run build	367 pages	371 (+4), 272 redirect pages
audit-phase2 broken internal links	0	0
missing images	0	0
anchor checker from #1073	27 (all pre-existing)	27, the same set; none in a file this PR touches; all fixed by #1112
anchors main already links on /extend/jobs/	—	run-a-job, job-polling, job-status, job-runtime-configuration, working-with-the-jobs-api: all render
redirect stubs	—	/automate/set-schedule/, /automate/run-job/, /automate/run-orchestration/, /integrate/jobs/, /overview/jobs/, /integrate/artifacts/ each land on the right page
line endings	—	no file changes its convention (management/jobs/index.md stays CRLF, 92/92)

Reproduce: git merge-tree --write-tree upstream/main HEAD (clean), npm run build, node scripts/audit-phase2.mjs.

Notes for the reviewer

• PRDCT-572: consolidated dev→help redirect map + conservation checker (re-cut off main) #1091 (contract): 8 of its 201 rows point at this PR's former slugs and get regenerated to main's right after this lands. PRDCT-658: flip dev-domain links whose targets already live on help #1094 (link flips) needs a rebase; 4 of its flips target /overview/apis/. developers-docs#418 likewise.
• PRDCT-544: fold dev SSH-tunnel how-to into /components/extractors/database/ #1019 adds the same redirect_from: /integrate/database/ line to the database page; either merges first, the second resolves one line.
• Three help links to developers.keboola.com/#development-project stay until PRDCT-540: combine dev+help home and overview (top-down pilot) #1022 lands the dev home's "Development Project" section.
• Title and nav label of /extend/jobs/ stay "Component Jobs" as approved in Fix the Starlight overrides that match nothing, port three dev-docs pages, add robots/llms #1132; only the content and the description change. Renaming it "Jobs API" would match how every link text refers to it — reviewer's call.

Independent review, 2026-09-09

Eight reviewers (four fact dimensions against the service swaggers, GET /v2/storage, apis.json and public keboola code; placement on the live preview; two followability walks; one mechanical pass over #1094, #1091 and developers-docs#418) produced 99 findings; eight skeptics confirmed 90 (7 CRITICAL, 24 MAJOR, 59 MINOR) and left 9 unverifiable. Commit fa3ea655 fixes everything factual, mechanical or a followability defect; the rest is listed below for the owner.

All seven CRITICAL findings were in the artifacts pages and were inherited from the dev site: download paths are in/<type>/jobId-%job_id%/ (keboola/artifacts Filesystem.php), only one artifact type is downloaded per job (Artifacts.php download() returns after the first enabled type), tutorial example 3 nested component_id/config_id/branch_id outside filter (job-queue-job-configuration ConfigurationDefinition.php), used the legacy component id and a $CONFIG_ID that single quotes never expanded. A reader following the tutorial as published would have failed at example 3.

Other facts corrected: warning is a final job state (STATUSES_FINISHED); backend.type has xsmall; parallelism is 2–100 and infinity is capped at 100; keboola.flow is Conditional Flows and keboola.orchestrator is Legacy Flows, now linked by product name; the "all phase jobs created at once" behaviour is Legacy-Flow only; the scheduler activation needs the admin or share role (keboola/permission-checker CanModifySchedules.php), so the master-token note is a statement again, not a VERIFY; apis.json covers the services the portal documents, not every service; eight RapiDoc-style portal anchors the Scalar portal never generates became service-level links; the artifacts feature flag is code-confirmed (docker-bundle Runner.php).

Placement verdicts (reviewer judged on the preview): Jobs API, Scheduler API, Encryption and Artifacts fit; the /overview/ subsection is questionable as the landing for 25 repointed links and the home page's "API reference" (it sits inside the glossary). Cross-links the review asked for are added. Two things need the owner: whether the home "API reference" should point at api.keboola.com or the subsection becomes a first-class ## APIs; and that job states now live on three pages, two of which (/management/jobs/ "always waits for infrastructure", /components/running-jobs-in-parallel/) contradict the API page's waiting vs created semantics — pick the canonical one.

Left as VERIFY(owner) on the pages: retryContainer behaviour; how Conditional Flows create phase jobs; whether shared artifacts work inside a Conditional Flow; whether branchId is ignored with configData; the artifacts "preview" status. Screenshots to reshoot: the two encryption UI shots, artifacts tutorial image 1. management/project/tokens (4 links) and transformations/mappings:46 follow in #1094's follow-up because #1094 edits the same lines.

Placement decisions applied, 2026-09-14 (3c141835)

The four questions the review left to the owner are answered:

• APIs are a section, not a glossary entry. ## APIs on /overview/ sits ahead of "Other Commonly Used Terms", so the home page's "API reference" and the other 24 repointed links land on a first-class section. The anchor is #apis; followed here and in PRDCT-658: flip dev-domain links whose targets already live on help #1094, PRDCT-572: consolidated dev→help redirect map + conservation checker (re-cut off main) #1091 and developers-docs#418.
• Job states have one home: /management/jobs/api/#job-status, the swagger-checked list. /management/jobs/ keeps the UI half and loses both its own three-state list and the "a job always waits for infrastructure first" claim that contradicted it; /components/running-jobs-in-parallel/ keeps the billing rule and points at the same anchor.
• Two duplicate explanations collapse to a pointer: ai/index.md on apis.json, and extend/job-queue's API menu.
• The dev home's "Development Project" section lands as /extend/development-project/, the address PRDCT-540: combine dev+help home and overview (top-down pilot) #1022 also uses. The last three developers.keboola.com links in help point there now.

With #1094, the dev-domain links inside help go from 78 to three, all /integrate/database/, which #1019 rewrites. Merging this branch and #1094 together is conflict-free (git merge-tree, no conflicts).

Also added since the review: a "Before you start" block on the Jobs API page with the token and the Queue host per stack, matching the Scheduler page.

Jordan's review applied, 2026-09-14 (a08b4b09)

1. /overview/api/ now lands exactly. You were right that redirect-from.mjs takes its target from the page slug, so a redirect_from cannot carry a fragment. Took your suggestion: APIs are their own page at /overview/apis/ — portals table, token header, the service-endpoint rule, apis.json, the Postman collection — and the retired dev URL redirects straight onto it. /overview/ keeps one sentence under Stacks. 16 links follow here, 3 in #1094, 1 in developers-docs#418, and the contract row in #1091 is now moved → /overview/apis/.

2. The Development Project offer is no longer republished. Agreed that an outward-facing commitment is not the same as a behaviour note. The page keeps the conditions, the Developer Portal registration path, the support address and the request template; the size is gone until someone can confirm it. Conservation log — what the dev site stated and this page no longer does:

You can apply for a development project with the following features:

• 3.5 GB storage space
• Snowflake backend
• 10 users
• 3 orchestrations

A VERIFY(owner) on the page asks for those numbers back if they still hold.

3. The Job Queue "encrypt values" bullet is recorded as a correction rather than a deletion, as you suggested: the Queue API has no encrypt endpoint.

Verified after both changes: build 370 pages, audit-phase2 broken internal links 0, missing images 0, unclosed fences 0, /overview/api/ → /overview/apis/ in dist/, and check-redirects.mjs --build from #1091 reads 201/201 against this build.

On retirement: understood, and the sequence in the PR bodies matches yours — #1019 clears the last three content links, and the domain cannot be switched off until #1091 lands the contract. #1022 has been told on its thread to drop its duplicate extend/development-project file when it rebases.

[vercel]

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

Project	Deployment	Actions	Updated
connection-docs	Ready	Preview	Sep 23, 2026 12:57pm UTC

[linear-code]

PRDCT-582

PRDCT-666

PRDCT-665

PRDCT-667

[jordanrburger]

Review

Good work. I merged this together with #1094 locally and verified the claims rather than reading them, since the accuracy corrections are the load-bearing part of this PR.

Verified independently

Merged onto main (clean, and clean against #1094), built, and ran the audit:

Check	Result
npm run build	369 pages, 273 redirects, 0 skipped
audit-phase2 broken internal links	0
Missing images / unclosed fences / malformed tables	0 / 0 / 0
src/sidebar.mjs vs navigation.yml	in sync
The 9 retired dev URLs	all redirect
Live developers.keboola.com links in help	78 → 3, all /integrate/database/ (owned by #1019)

The 78 → 3 claim checks out exactly: the only remaining live dev links in dist/ are the three SSH-tunnel ones. The other six matches in source are inside provenance HTML comments, not links.

Fact spot-checks against the live specs all held:

• Job status — queue.keboola.com/docs/swagger.yaml JobStatus enum is exactly the nine documented values including warning
• Job types — the five-value enum (standard, container, phaseContainer, orchestrationContainer, retryContainer) confirmed in three places
• Modes — run, forceRun, debug confirmed
• backend.type — ['xsmall', 'small', 'medium', 'large'], so the xsmall correction is right
• Scheduler hosts — the swagger lists exactly scheduler.keboola.com and scheduler.eu-central-1.keboola.com as production, and no scheduler.azure.keboola.com. Dropping it was correct.
• Job Queue "encrypt values" — the Queue API has no encrypt endpoint, so removing that bullet from /extend/job-queue/ is a correction, not a loss. Worth adding to the conservation log as such.

The artifacts tutorial example 3 fix is real and material: component_id/config_id/branch_id are now nested inside filter, and '"$CONFIG_ID"' actually expands inside the single-quoted --data-urlencode. A reader following the published version would genuinely have failed there.

1. /overview/api/ redirects to the page top, not to #apis

src/integrations/redirect-from.mjs derives its target from the page's slug, so redirect_from structurally cannot carry an anchor. The built redirect is:

/overview/api/  ->  /overview/

So the most-linked retired dev page drops readers at the top of a 200-line glossary page, and they have to scroll past Deployment Options, Architecture, Governance and Extending to reach APIs. 19 in-repo links now point at /overview/#apis and those are fine — it's only the redirect that can't reach the anchor.

The section itself is well written and correctly promoted above "Other Commonly Used Terms", so this isn't a placement complaint. But given the volume of inbound traffic on that URL, consider making APIs its own page (/overview/apis/) so the redirect lands exactly — which is also a better Diátaxis fit than a dense reference table living inside a glossary page. The alternative is extending redirect-from to accept an explicit target with a fragment.

2. /extend/development-project/ publishes a stale offer

This is the one item I would not merge unverified. The page commits to third-party developers:

• 3.5 GB storage space
• Snowflake backend
• 10 users
• 3 orchestrations

plus an application process — all carried from the dev site and flagged VERIFY(owner) as possibly out of date. Everything else marked VERIFY describes behaviour; this one is an outward-facing commitment, so publishing it wrong has a different cost. Please confirm the current offer before this lands.

Other VERIFY(owner) markers — none blocking

Six more, all invisible HTML comments and correctly used per the revamp rules: artifacts "preview" status, shared artifacts in Conditional Flows (×2), how Conditional Flows create phase jobs, whether branchId is ignored with configData, and retryContainer behaviour.

Retiring dev docs

On the Slack question of whether this plus #1094 lets us switch the domain off — not quite. These two do the hard part (78 → 3 live links), but full retirement still needs:

• #1019 — owns the last three links; ready, not draft. This is the last content blocker.
• #1091 — the consolidated redirect map and conservation checker; still draft.
• #1022 — the dev home and overview; still draft, and it also creates /extend/development-project/, so one of the two resolves that file.

So: #1019 clears the content, but the domain can't be switched off until #1091 lands the redirect contract.

Summary

Mergeable once the development-project offer is confirmed. The /overview/api/ anchor is worth a decision but needn't block.

[Iamfle4ka]

Verification against current main (23b1a11d)

Rebuilt this branch at a08b4b09 and re-ran the audit today. Reproduction:

git merge-tree --write-tree --name-only upstream/main HEAD   # exit 0, merges clean
npm run build
node scripts/audit-phase2.mjs

Build is clean: 370 pages, 273 redirect stubs, 644 HTML files.

BROKEN INTERNAL LINKS: 0
MISSING IMAGES:        0

TOTAL ISSUES: 74 is 71 old-docs link smells plus 3 pre-existing multiple-<h1> pages
(/management/notifications/, /storage/byobq/, /workspace/snowflake-workspaces-access-changes/).
None is introduced here, and the smells are the dev-domain links that #1094 flips.

The measurable effect

Built the same checker against a branch that has #1112 but not this PR, for comparison:

Branch	Broken internal links
main + #1112	29
this PR	0

All 29 are /overview/encryption/, /integrate/jobs/ and /overview/api/, which are
exactly the targets this PR supplies. It fixes them two ways: the new pages carry
redirect_from for the old paths, and the inbound links are repointed in the same diff.

Spot-checked in dist/:

URL	Result
/overview/api/	stub to /overview/apis/
/overview/encryption/	stub to /extend/common-interface/encryption/
/integrate/jobs/	stub to /management/jobs/api/
/overview/apis/, /management/jobs/api/, /extend/development-project/	real pages
/extend/common-interface/encryption/, /extend/common-interface/artifacts/	real pages

What this PR does not fix

Two root-relative targets stay 404 after it, both out of scope here and both tracked:

• /storage/api/clients/, a folder with four children and no index page. Falls to the Storage API rework.
• /components/extractors/generic-extractor/user-functions/. Falls to the Generic Extractor rework.

Anchors, measured separately

audit-phase2.mjs on main strips #fragments before testing, so no anchor on the site is
currently verified by anything running in CI. Running the checker from #1073 against this build:

State	Broken anchors
this branch alone	27
plus #1112 as it stood	4
plus #1112 at 87ab5b29	0

That is independent of this PR, but it means #1120 and #1112 together leave the tree with
zero broken internal links and zero broken anchors.

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 3/5) · profile connection-docs

Needs human: this large docs merge leaves unresolved VERIFY(owner) markers in added lines and ships new security-posture encryption prose, both escalation triggers.

Impact flags: possible rollback re-introduction — see Check Run summary.

Concerns:

• src/content/docs/management/jobs/api/index.md: Unresolved VERIFY(owner) markers in added lines (also artifacts, development-project); gate 3 fails.
• src/content/docs/extend/common-interface/encryption/index.md: New page ships security-posture claims (no decryption API, in-component-only access) needing human sign-off.
• src/content/docs/extend/common-interface/artifacts/index.md: Marked 'preview feature' with status left as unconfirmed VERIFY(owner).

Suggested reviewers: @keboola/docs