Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Collaborator
Author
|
Verification on
|
Iamfle4ka
force-pushed
the
PRDCT-487-getting-started
branch
from
August 4, 2026 23:40
6b93036 to
1b8e7f7
Compare
added 8 commits
August 5, 2026 01:42
…d arc Michal's 07-28 priority: Getting Started framed as the customer lifecycle, written for readers (and agents) who know nothing and may land on a deep link. Structure: - /tutorial/ -> /getting-started/, redirect_from on every page - steps renamed off "Part N": project (new), load, transform, write, automate, next-steps (new); optional deep-dives grouped under "Going Further" - /tutorial/onboarding/ -> /overview/onboarding/ (SECTION-MAP U2: the subtree is explanation content, not tutorial steps), google-data-policy added to the nav - description: frontmatter on all 22 pages (feeds search, RAG and the lede) - 169 dead duplicate assets removed from src/content/docs — public/ is what serves absolute image paths; a single copy now lives under public/ - 431 path references repointed across 69 files; help.keboola.com self-links made relative Supersedes #1012. Prose and screenshots follow.
Every arc page now carries the same shape, per the section-rework standard and Michal's deep-link premise (basics -> steps -> verify -> troubleshoot): lede + type marker, "What you need", numbered steps with one image each, "Check it worked", "If it goes wrong", an "Or ask Kai" aside, and a Next: footer. - index: a real overview — what you build (table), prerequisites, the 6 steps, the optional side trips, and a pointer to Platform Onboarding for rollouts - project (new): free plan / invite / sales, what a project and a stack are, the five places in the UI that matter - load: CSV Import with a destination table per file, verify in Storage - transform: input/output mapping explained before the SQL; BigQuery variant kept with a VERIFY(owner) note (unverified, and the original's `Level`.`Level` reference looks wrong) - write: was 66 lines with no headings; now the full page shape, plus the Update-rows vs Append-rows distinction - automate: rewritten against Conditional Flows (phases/tasks/Builder/plus icon, conditions, Set Schedule, Notification tasks) — the old page documented the legacy builder - next-steps (new): routes by intent, then the three agent surfaces (Kai / MCP / kbagent CLI) - home: "Where to Start" now routes by intent into the arc instead of repeating the overview; overview: fixed the malformed `[/tutorial/automate/#main-header]` link and the absolute help.keboola.com self-links - kept "Going Further" pages: footers normalised, stale "part of the tutorial" wording fixed, one malformed link repaired in transform/workspace Screenshots are still the legacy captures — reshoot pass next.
- /overview/ had no link into the arc at all — added one under the lede - /management/payg-project/ (where free-plan signups land) now points at Get a Project - components/writers/ and the Tableau connector page both promised a tutorial on "writing data from Keboola to Tableau" and linked to the Google Sheets walkthrough — reworded to what the page actually shows
The blocker: the arc recruited readers to the Free Plan, then handed them Snowflake. New Pay As You Go projects default to the BigQuery backend (storage/index.md:13), so the majority of new readers hit step 3 and stop. transform now tells you to read which SQL transformation your project offers and gives the two query blocks as peers instead of burying BigQuery in a note. The BigQuery SQL still carries VERIFY(owner) — it cannot be run in demo project 264 (Snowflake), and it is now the block most readers will use, so it needs a real Free Plan project before this ships. Both agents independently caught the same two errors: - the output bucket is PLURAL — `out.c-denormalize-opportunities` — derived from the transformation name; the singular form was inherited from the old page and the rewrite had hardened it into a table ID the write step tells you to select verbatim (4 call sites) - a Notification task fires when its phase runs, i.e. on success. Failure alerts come from the flow's Notifications tab / Edit Notifications (management/notifications). The arc promised "emails you if it breaks" and configured the opposite; condition-driven notification tasks are now the advanced note, not the baseline. Also, against the pages' own screenshots and sibling pages: - CSV Import's Destination is three controls (stage / bucket / table name), not one dotted string with a pen icon - Storage shows the bucket as `csv-import` with an IN badge; `in.c-csv-import` is the ID, not the label - New Table Input / New Table Output; New Code names a code inside Block 1 - "Recently updated by" is a column in the table list, not a field on the detail - pick Google Sheets *data destination* (`keboola.wr-google-sheets`) — the search returns source and destination side by side and only the old screenshot's red arrow disambiguated them - the Add Sheet wizard has three tabs; spreadsheet title and sheet title are different fields - Jobs shows a job per task plus the flow's own orchestration job, not six - backends are not strictly per-project (each transformation can differ; DuckDB is in beta), Free Plan runtime is *up to* 60 min and tracks last month's usage, Free Plan has no dbt, invites are Users & Settings > Invite User, kbagent is in beta, and Storage columns are text only until typed - dropped the unverifiable "write access to spreadsheets only" OAuth claim - 30 minutes -> under an hour; the "skip the Google account" promise now says what you lose Screenshots on automate are flagged in-page: all 15 are legacy-flow captures whose captions describe the intended new shots. Blocked on a logged-in session.
redirect_from generates page stubs only, so moving the section's non-page assets broke their URLs. The four sample CSVs are linked from the live tutorial today and are the kind of URL people bookmark or hotlink, so they get explicit 301s, as do the two branches CSVs and the usage-blueprint .docx. Images are not redirected — 169 of them, referenced only from pages in this repo, all updated in the restructure commit.
CSV Import is deprecated — verified live in project 264: "This component has been deprecated. New configuration cannot be created", stage PRIVATE, and it no longer appears in component search. The arc's step 2 was built entirely on it, so the guide told every new reader to configure something nobody can configure. Step 2 now uses the **HTTP** data source connector, pulling the four sample CSVs from their published URLs on help.keboola.com. This keeps the arc intact — it is a real connector, so it re-runs, schedules, and works as a flow task in step 5 — and it is reproducible in any project, which a local file upload is not. Shape follows the product rather than the old page: one configuration holding four tables as configuration rows, not four configurations. Consequences threaded through the arc: - the destination bucket is the connector's own (`keboola-ex-http-<id>`), so the hardcoded `in.c-csv-import.*` IDs are gone. transform now leans on the input mapping's Table name, which is what the SQL actually depends on and what the reader controls — and says so. - automate is three phases with one task each. The parallelism lesson is now taught where it is true: a second connector goes in phase 1, and row-based components parallelize internally. - index, next-steps, and five inbound links elsewhere no longer promise a manual CSV upload; ad-hoc's dead `#manually-loading-data` anchor is gone too. Field names and behaviour are sourced from components/extractors/storage/http/index.md, which documents this connector against these exact sample files. Live labels and screenshots still pending.
Walked the whole step in demo project 264 with keboola.ex-http and ran it: the config fetched all four sample CSVs from help.keboola.com and landed opportunity 639 rows, account 275, user 28, level 28. Seven fresh screenshots replace the eight legacy CSV-Import captures. Labels the walk corrected — several of which our own connector page still gets wrong (components/extractors/storage/http/index.md says "Add Table"; the UI says "Add Row"): - searching HTTP returns two components; you have to pick plain HTTP over HTTP Advanced (BETA) - Add Component opens a dialog first: Connect To My Data vs Use With Demo Data - the base URL lives under "Base URL and Connection Options" and needs its own Save; the section also holds Maximum Redirects - rows are Rows / Add Row / Create, not tables - a row is Download Settings (Path) + Save Settings (Table name, Incremental load, Delimiter, Enclosure) + Header & Primary Key - Read Header ALREADY defaults to "Read the header from the file(s) header", so the step is to leave it, not to change it - Run Component asks for confirmation before it runs - the run took 2 min 4 s for four rows, fetched sequentially — the page said "well under a minute"; Parallel jobs on the configuration is what changes that - the Data Sample is a tab on the table page Also corrected on automate: a flow run produces a Conditional Flows job, a Conditional Flows phase job per phase, AND the component jobs — visible in the project's job list.
…tures Walked the create-transformation path in project 264. The label dispute between our own pages resolves as "both, at different moments": - the BUTTON is **Create Transformation** (this page was right) - the DIALOG is **New Transformation** (transformations/duckdb was right) That dialog turns out to carry the answer to the backend question the guide-tester flagged as blocking: it lists what the project can actually run (Snowflake SQL / Python / R / DuckDB beta, or BigQuery SQL elsewhere), so the page now uses it as the reader's signal for which SQL block to use. Three labels in my draft were simply wrong: - section **Table Input Mapping**, button **Add Table Input** (not "New Table Input"; the legacy screenshot's "New Table Input" was also out of date) - **Queries → Create Multiple Queries**, not "New Code" — and SQL lives in a *code* inside a *block*, which the page now says - **Source** is multi-select with checkboxes, so all four tables go in at once; **Table name** auto-fills only for a single selection Also replaced `transformations-intro.png`, which the fact-checker caught showing the pre-2020 UI (a "NEW TRANSFORMATION BUCKET" button and an Orchestrations nav item), with a current Transformations list. The transformation itself is configured in project 264 — four inputs mapped to opportunity/account/user/level, output to out.c-denormalize-opportunities.opportunity_denorm, SQL in Block 1 — but the run and the remaining seven captures were cut short by a network outage. Those references stay on their legacy images so the branch keeps building clean; the in-page marker says exactly which shots are fresh and which are not.
Jordan's 08-21 framing: don't teach Keboola, show that it's easy. The overview now acknowledges the whole arc fits one long Kai request and explains why the guide still goes one prompt per step (checkable results), closing with the ease claim in plain words. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rompt Jordan's read on the overview held for the reader too: the Two-ways section shrinks from seven paragraphs to three, the What-you-will-build table now ends on a real screenshot of the finished map app (cropped from the live draft preview; final shots come with the re-walk), and the arc closes with its payoff — the whole pipeline as a single Kai prompt on the last page, with an honest note that approvals and the Google consent stay yours. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…minute promise Michal's framing for the rework is new-customer acquisition: the front door now says up front that a free project covers the whole arc with no sales call, and Before-you-start names the real time cost of the Kai path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…d live The GIF pipeline lands: Playwright recordVideo against the demo project with the saved login, ffmpeg 4x speedup to a ~420 KB looping mp4 + poster, embedded as <video autoplay loop muted playsinline> (new CSS frame rule for video, and audit-phase2 now checks mp4/webm links; record.mjs and postgif.sh stay local and gitignored like shoot.mjs). The pilot clip shows the step-5 finale prompt end to end, and Kai's on-camera answer equals the documented check numbers — the recording is also the prompt's live calibration. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…p answering for Prague kai-write (12x, 342 s real): Kai reads the Sheets config, spots the sheet mistitled 'Sheet1', shows the diff, gets approval, fixes it and runs the job to Success in 25 s — the self-healing beat sits right in the step-4 Kai tab. app-preview (2x): typing Prague's coordinates into the finished map returns 'Nearest Sighting: musky octopus, 495.1 km, 1910' — the arc's question answered on camera, embedded on the app page. Three clips total in the PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Every loop opened on seconds of blank page and an 'Initializing components' spinner (plus a promo toast on the basin clip). Trimmed to start on loaded UI, and cut the idle middle of the app clip so it goes map -> coordinates -> nearest sighting in ten seconds. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Jordan asked for beautiful GIFs and the raw speedups read too fast. Each clip now plays through a local compositor stage: variable pacing (slower while you type and where the answer lands), caption chips narrating the moment, and an octopus guide pointing at the thing to look at — the metric table, the Success badge, the nearest-sighting card. Page wording updated since fixed speed factors no longer apply. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The clips still read too fast — every rate comes down (~25%) and the end holds stretch to ~4 s, so the three pages now loop at 21-25 s. The overview's static app screenshot becomes a 25-second tour: the octopus swims the map and stops at the arc's three verified numbers — the North Atlantic (2,632 sightings), the nearest sighting to Prague (musky octopus, 495 km), the deepest record (Grimpoteuthis challengeri, 4,838 m) — ending on the fifteen-minute promise. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
All 26 step screenshots on load/transform/write/automate re-captured in project 264 against the configurations the arc actually builds — the old captures still showed the deals dataset and, in places, a previous generation of the UI. Text corrected where the product moved: - Sheets writer: 'New Table' + tabbed wizard is now a NEW SHEET button and a three-step 'Add Sheet' stepper; steps 8-10 captures pend a fresh-project walk (the wizard hides tables the config already maps). - Conditional Flows: Create Flow opens a chooser (prompt vs Build It Yourself); component picking is a full-page picker; the saved-flow capture now shows all three phases, so the off-frame caveat is gone. - Component cards read 'Create Configuration' once configs exist. - Transformations landing filtered to the Octopus folder and the notifications email blurred (PRDCT-616). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…he answer Jordan's 2026-08-21 feedback had one item still open: «Overview section too vague: reader can't tell what they'll get out of it». The question, the build table and the map tour were all on the page, but behind three paragraphs of prose, so the first screen said nothing. The tour becomes a three-act hero right under the question: the four raw CSVs where aphia_id 140605 means nothing on its own, then the question held long enough to read (that frame is the poster, so it shows before autoplay), then the finished app answering it. The detail paragraph about species IDs and lookup tables moves below the build table, where it explains the table's rows instead of delaying the payoff. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…arted # Conflicts: # src/content/docs/components/writers/index.md # src/content/docs/getting-started/ad-hoc/index.md # src/content/docs/transformations/index.md
This was referenced Sep 2, 2026
Collaborator
Author
|
Superseded by #1116, which rebuilds Getting Started on the Boolabean sample and puts every task page on the Prompt / UI / CLI tabs. It rewrites or deletes all 19 files this branch added under Closing to keep the queue honest rather than because the work was wrong — the arc, the side-trip filing and the one-prompt experiment all fed the rebuild. |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites
/tutorial/as the Getting Started arc, per Michal's 07-28 priority: Getting Started framed as the customer lifecycle, written for readers and agents who know nothing and may land on a deep link.Supersedes #1012.
Structure
/tutorial/→/getting-started/,redirect_fromon every page, 431 path references repointed across 69 files.project(new) →load→transform→write→automate→next-steps(new)tutorial/onboarding/→/overview/onboarding/— explanation content, not tutorial steps (SECTION-MAP U2)Every page: lede + type marker, What you need, numbered steps with one image each, Check it worked, If it goes wrong, an Or ask Kai aside,
Next:footer.description:frontmatter on all 22 pages.Also: 169 dead duplicate assets removed from
src/content/docs(public/is what serves absolute image paths);vercel.json301s for the moved sample CSVs, branches CSVs and the usage-blueprint.docx, sinceredirect_fromonly generates page stubs;/overview/had no link into the arc at all; andcomponents/writers/plus the Tableau page both promised "writing data from Keboola to Tableau" while linking to a Google Sheets walkthrough.The load step had to be rebuilt
CSV Import is deprecated — verified live: "This component has been deprecated. New configuration cannot be created", stage PRIVATE, absent from component search. The arc's step 2 was built entirely on it, so the guide was telling every new reader to configure something nobody can configure.
Step 2 now uses the HTTP connector pulling the four sample CSVs from their published URLs, as one configuration with four rows — the shape the product intends. It re-runs, schedules, and works as a flow task, and it is reproducible in any project, which a local file upload is not.
Walked and run live in demo project 264
loadtransformout.c-denormalize-opportunities.opportunity_denorm, 639 rows / 23 columnsautomateprojectwriteTwenty-six fresh screenshots replace the legacy captures. Everything still on a legacy image is named in that page's type marker.
What the walks corrected — including on pages outside this PR
Both QA agents independently caught the plural output bucket (
out.c-denormalize-opportunities, not singular — the write step told you to select that ID verbatim) and that a Notification task fires on success, not failure, so the arc promised "emails you if it breaks" and configured the opposite.The live walks then corrected:
Add Row, not "Add Table" —components/extractors/storage/http/index.mdstill says Add TableCreate Transformationis the button,New Transformationis the dialog — our two pages each had half of itAdd Table Input/Create Multiple Queries, and Source is multi-select+between phases adds a phase, not a task/flows/still says "Set Schedule"/management/notifications/transformations-intro.pngshowed the pre-2020 UI (a "NEW TRANSFORMATION BUCKET" button, an Orchestrations nav item)The three stale claims on
/flows/,/management/notifications/and the HTTP connector page are not fixed here — they belong to those sections.Verification
npm run buildclean — 308 pagesnode scripts/audit-phase2.mjs— MISSING IMAGES 0, zero broken links or dead anchors from any page in this PRredirect_from; no stale(/tutorial/reference remainsfact-checkerandguide-testerrun twice; the second pass had a live sessionTwo things this needs before it leaves draft
writesteps 4–12 and the flow's third phase, which is the only reason the automate screenshots show two phases rather than three.transformcarries the BigQuery SQL as a peer of the Snowflake block, but it has never been run, and new Free Plan projects default to BigQuery, so it is the block most new readers will hit. MarkedVERIFY(owner)in the page.Reference setup left in project 264
Kept deliberately, so re-shoots start from a working pipeline (schedule disabled so nothing runs daily):
[TUTORIAL] Sample data(HTTP, 4 rows)01kz5050bhhezq9scmd0t9c73fDenormalize opportunities(Snowflake SQL)01kz51rxyzdamc5vfvx704batn[TUTORIAL] Opportunity pipeline(flow)01kz5yndzrc4zvkwch85qg4x28Open question for the owner
ad-hoc(a BigQuery + Python notebook walkthrough) andbranches(7 pages) sit under "Going Further" but are advanced walkthroughs, not first-run steps. I kept them in place and only retitled them — their real home is a placement call (SECTION-MAP U4 / Core Concepts), not mine.Octopus rework (2026-08-25/26) — live-walk state & merge checklist
The arc was rebuilt on the octopus dataset and walked live in demo project 264: load 1:52 (10,000/201/5/13 rows), transform 0:53 (
octopus_atlas10,000×12, every documented number verified by SQL), Sheets delivery 0:30, Kai-built flow ran end-to-end in 3:06, daily schedule fired on its own the next morning. First "GIF" (looping mp4) embedded on the automate page — Kai's on-camera answer equals the documented checks.After merging this PR (owner checklist):
[TUTORIAL] Octopus sightingsHTTP config'sbaseUrlin project 264 back tohttps://help.keboola.com(it temporarily points at this PR's Vercel preview because the CSVs go live only with this merge).[TUTORIAL] Octopus atlas to Sheetsconfig01m0v0prttc729mz7q3jmcwng4(broken OAuth credential from an aborted authorize; the live one is01m0w7ghbsezptwdb0rhhzs7ee).Known platform finding: publishing the Kai-built data app ("[TUTORIAL] Octopus map", draft works, preview verified) rolls back silently on both the builder button and a chat request — no job record, versions frozen. Ruled out the known "apps in development branches are unsupported" limitation (2026-07-10 call): the whole walk ran in production — the top-bar "New Development Branch" item is the create button, not a branch context. Raised as authentic Kai-apps feedback; the app page documents the designed flow.
Preview: https://connection-docs-git-prdct-487-gettin-a61549-keboola-engineering.vercel.app/getting-started/
🤖 Generated with Claude Code