PRDCT-693: put Apps prerequisites in the shared Before you start box

[Iamfle4ka]

Linear: PRDCT-693 · targets main since #1146 landed · also carries #1149, merged into this branch on 30 September

For the reviewer

The review bot escalated this PR because it changes site code, and its policy always sends that to a person. It asks a person to check three things:

• The markdown twin, the inPrereqs and inStrip branches in src/integrations/page-markdown.mjs. Compare build-locally with its twin, and authentication with its twin. The box and the strips should come out as plain lists.
• The CSS, the .prereqs* and .stage-strip* blocks in src/styles/custom.css. Look at the same pages in light and dark and on a phone. The strip turns vertical when the content column is narrower than 36rem.
• The Open app dialog. I saw it on europe-west3 on 29 September, and nobody has checked us-east4 yet, so a VERIFY(Nikita) marks it.

Why

Nikita asked for one look for prerequisites across the docs. Getting Started shows them in a box ("BEFORE YOU START / You need"). The Apps pages used five other forms: an H2 "Before you start", an H2 "What you'll need", an H3 "Prerequisites", and an inline "Before you start." or "Before you start —" inside tabs.

What changed

• The box from the Getting Started branch (PRDCT-487: Getting Started rerun on a Free Plan project, with a course-style hub and a 10-second clip #1144) is now a shared component: src/components/Prereqs.astro for the markup, src/components/prereqs.mjs for the wording, .prereqs* in custom.css for the styles.
  • It keeps the Getting Started API: needs, tabs, and the prompt/ui/cli slots.
  • It adds id, for a page that links to the box, and groupLabel, for a second list whose items are <li slot="group">. The label can't be called group: in MDX a named slot arrives as a prop of the same name and would overwrite it.
  • A new shared item, kai, reuses the wording of the Getting Started Prompt-tab line, checked against kai/getting-started: Kai is the Kai Agent button on supported stacks, and an organization admin switches it on the first time. Both now come from one constant.
  • projectWithKai is the Kai page's project line ("on a stack where Kai is available", no sign-up link), so that page lists the project before Kai.
• The markdown twin (page-markdown.mjs) prints the box as text, ported from PRDCT-487: Getting Started rerun on a Free Plan project, with a course-style hub and a 10-second clip #1144, including the second list. Like PRDCT-487: Getting Started rerun on a Free Plan project, with a course-style hub and a 10-second clip #1144's version, it reads the component's props from the opening tag's line, so that tag stays on one line; the component says so in its header. MDX comments inside the box or a strip are dropped from the twin, because a markdown list can't hold them.
• Eight blocks on five Apps pages use the box:
  • build-locally: "You need", then "Depending on how you build" (with an AI agent, by hand). #before-you-start still works. The kbagent setup step in the Cursor, VS Code and ChatGPT app tabs and in From a terminal now links "your stack URL" to the box, as the Claude Code tab already did.
  • authentication: one box in each provider tab.
  • getting-started (Kai), streamlit, streamlit/migrate-to-python-js: renamed from .md to .mdx, because components need MDX. The slugs are unchanged.
• Additions from the reviews:
  • the Kai page links the sample opportunity.csv for readers with no data;
  • the Streamlit box names the Keboola project;
  • the Entra item says "role".
• The box isn't a heading. The four pages that had a "Before you start", "What you'll need" or "Prerequisites" heading lose that table-of-contents entry.
• Fixed on the way: the Auth0 troubleshooting row wrote {URL} in MDX, which evaluated it, so help.keboola.com shows the source of Node's URL class in that bullet. It's a code span now, which MDX leaves alone. The same one-line fix goes to main on its own in PRDCT-692: stop MDX printing JavaScript in the Auth0 troubleshooting row #1148, so it reaches the site sooner.
• The shared "A Keboola project" item links the Free Plan sign-up, because /getting-started/project/ isn't on main yet. Only build-locally uses it, as before. A VERIFY(Jordan) next to the box asks whether the Free Plan includes apps, which DECISIONS.md on the Getting Started branch lists as open.

Also in this PR: #1149

#1149 was merged into this branch, so this PR also carries it. Its description has the detail and the checks.

• src/components/StageStrip.astro, .stage-strip* in custom.css and the twin code draw numbered stages on a line. build-locally gets two strips, one under the intro of "With an AI agent" and one under "By hand".
• A screenshot of the Open app dialog, public/data-apps/open-app-dialog.png, sits under Check the app.
• The password location, checked on the product on 29 September: Open App opens a dialog with the app address and the password. Since PRDCT-693: merge Build with an AI agent into Build an app locally #1146 landed, help.keboola.com puts the password "next to Open App" twice on build-locally, and authentication, troubleshooting and the Kai getting-started page each have one wrong line about where it is. This PR fixes all five, and reference adds the dialog to its Open App line.
• VERIFY notes, for things nobody has checked yet:
  • Michal Ševčík: the Edit with Kai and Duplicate with Kai labels on operate and publish-and-share.
  • Nikita: the dialog on a sleeping app, where a draft's password shows, and the dialog labels on us-east4.

Checks

• The build is clean. check-cli-reference has 0 findings, audit-phase2 0 broken links and 0 missing images, and docs-link-redirect-check against PRDCT-693: merge Build with an AI agent into Build an app locally #1146 0 blockers and 0 warnings. Every anchor that points at these pages resolves.
• On 30 September I merged PRDCT-693: merge Build with an AI agent into Build an app locally #1146's review fixes into this branch, then main (03e148b), which adds PRDCT-694: split DataApps time credits into Python/JS and Streamlit rates #1145. The diff against main didn't change. The build is clean again, the gates are at 0, and docs-link-redirect-check against main has 0 blockers and 0 warnings.
• The twins print each box as text, with no <Prereqs, <li or slot= left.
• Preview: build-locally in light, in dark and at 375 px; the other four pages in light, authentication on its Google tab. Dark mode was also checked on authentication and migrate. At 375 px all eight boxes are 343 px wide and nothing in them overflows. build-locally and the Kai page already scroll sideways at 375 px on PRDCT-693: merge Build with an AI agent into Build an app locally #1146's branch, because of other elements, and the boxes don't add to it. #before-you-start lands on the box below the header.
• fact-checker found nothing critical. The admin-rights scope and an autolinked stack URL are fixed, and the Free Plan question is flagged.
• guide-tester found no blockers; its fixes are listed above.
• Miro's review (30 September) found a twin bug, where a comment inside the box moved the next item into the wrong list or into the next strip, plus two nits. All three are fixed in 5307615, which leaves the five pages' twins unchanged apart from the Kai page's new order. fact-checker and guide-tester passed it.
• checker: FIX on the first pass (the preview claims and the counts in this description were wrong), PASS on the second, with all eight boxes re-measured at 375 px in light and dark.

Merge order and follow-up

• PRDCT-693: merge Build with an AI agent into Build an app locally #1146 is merged and GitHub moved this PR onto main. It needs a review. PRDCT-692: stop MDX printing JavaScript in the Auth0 troubleshooting row #1148 makes the same one-line {URL} fix, so whichever lands second has nothing left to change.
• When PRDCT-487: Getting Started rebuilt on Boolabean, every task page on three tabs #1116 and PRDCT-487: Getting Started rerun on a Free Plan project, with a course-style hub and a 10-second clip #1144 rebase onto main, they switch to the shared box:
  • delete their getting-started/Prereqs.astro and prereqs.mjs;
  • point their 11 imports at src/components/Prereqs.astro;
  • drop the .gs-prereqs* CSS;
  • merge the page-markdown.mjs changes, keeping their comment stripping and PathIntro text;
  • point SHARED.project back at /getting-started/project/ ("Get a project").
• A style audit comes next and will propose a STYLE.md for the other patterns.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
connection-docs	Ready	Preview	Oct 1, 2026 5:12pm UTC

[linear-code]

PRDCT-693

[keboola-pr-reviewer-bot]

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

Escalating: the PR changes build/site tooling (src/integrations/page-markdown.mjs, src/styles/custom.css) and adds new components, so it is not a content-bucket PR.

Concerns:

• src/integrations/page-markdown.mjs: Build tooling changed; new twin slot-parsing regex needs human review against preview.
• src/styles/custom.css: ~140 lines of new component CSS; visual output not machine-verifiable.
• src/content/docs/data-apps/build-locally.mdx: Open-App password dialog may not be deployed on us-east4 yet (VERIFY notes).

Suggested reviewers: @keboola/docs

[MiroCillik]

One twin bug and two nits, inline.

• the preview looks right: build-locally at 1280, 1000 and 375 px in light and dark, and authentication at 375 px in dark. No box or strip is wider than its column, and the strip turns vertical at 375 px
• the twins of all five pages print the boxes and strips as plain lists, with no <Prereqs, <li or slot= left
• the removed headings' anchors (#what-youll-need, #prerequisites, migrate's #before-you-start) have no inbound links under src/
• I did not check the Open App dialog on us-east4; the VERIFY(Nikita) is still open

[MiroCillik]

BTW, why check Open app dialog on us-east4 specifically? :)

[MiroCillik]

All findings fixed in 5307615. The us-east4 Open App dialog VERIFY(Nikita) is still open.