PRDCT-489: Apps section rework (canonical, variant B)#1013
Draft
Iamfle4ka wants to merge 30 commits into
Draft
Conversation
…orm) Restructure src/content/docs/data-apps to the approved skeleton, realized with the real old content: hub, getting-started (real Kai walkthrough performed in project 6015 + Story of Us inspiration), examples (Jordan's 3 public picks: Seasonal, Flight Shockwave, Color Season Analyzer), what-are-apps, build-with-kai / build-in-the-ui / build-locally, python-js overview (framework page restored per review), authentication (4 OIDC pages merged), publish-and-share, reference (limits at bottom), streamlit subtree (lock-version 3->1 merge, design-guide move). Images: docs reference /data-apps/*.png served from public/data-apps/; grey placeholder PNGs in place, real captures via apps-section/screenshots.mjs. Release changelog deleted (belongs in changelog). VERIFY/TODO owner flags embedded for the accuracy stage. apps-section/ bundle: CONTEXT, STRUCTURE, content-proposal, APPS-UPDATE-PLAN, HANDOFF-PROMPT, screenshots.mjs. Structure+form only — facts moved verbatim, not verified. No PR yet. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ix sidebar order Page-by-page review of the Apps (data-apps) section, grounded in the live product UI where facts were needed. - Sidebar: move "What are apps?" before the Build guides; rename examples → "Beyond dashboards" - Canonical "Python/JS vs Streamlit" framing (what-are-apps anchor); consistent "Python/JS" label - Build with Kai: full topic breakdown (prompt/refine/governance) + real Kai chat & Approve screenshots - Build in the UI: rewrite to observed create → config → deploy flow + 3 real screenshots - Build locally: fill "Sync to project" and "AI coding tool" sections from live UI + Python/JS screenshots - What are apps: sharpen "governed by default"; add a live deployed-app screenshot - Python/JS: real app-config screenshot + downloadable AI-skill note - Authentication: correct to the real Authentication Type dropdown (6 methods) + fresh screenshot - Reference: lede + on-page nav; lock-version illustrative-versions note; code-fence languages - Remove stale/orphan images (app-modal, unused examples-*) - Add project skill: capturing-keboola-ui-screenshots (CDP screenshot workflow) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Publish and share: reframe to the grounded deploy → auth → share flow; note the dev-branch → production path; flag the ambiguous "promote to production" semantics for a maintainer instead of asserting it. - Reference: flesh out the Per-app settings table from the observed app config (Code Source, backend version/size, auto-sleep); fix the Secrets error — the variable NAME is uppercased, the value is passed through unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
apps-section/ (planning, context, handoff, capture scripts) and .claude/ are local-only working files, not product docs. Untrack and gitignore them so they don't ship in the Apps PR. Follows the repo precedent (db81d1f). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…date # Conflicts: # src/content/docs/data-apps/storage-access/index.md
Per Jordan's review: manual creation lives on the same Create App screen, so it becomes a 'Create an app manually' section of the Kai page instead of a separate page. 301 redirect added; nav + inbound links updated; Python/JS card listed first in the manual flow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The overview now carries the essential info itself (what an app is, Python/JS stack, sleep/wake, two build paths, run & share) instead of being a link directory. The three showcase apps move onto the overview as a 'Beyond dashboards' section; /data-apps/examples/ 301s here. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- python-js: new 'How development works' loop (repo, server-side data access, redeploy, logs, sleep/wake) + AI Kit block with install commands; VERIFY(Jordan) for a canonical skill-file download URL. - build-locally: AI Kit install commands alongside the in-product Download Skill. - what-are-apps: Streamlit de-emphasized — 'The stack: Python/JS' replaces the top-level comparison. - streamlit/*: 'Streamlit apps only' scoping notes; migration-page TODO. - reference: backend-versions/pre-installed packages scoped as Streamlit-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…eenshots Verified live in project 6015 (new Python/JS backend, 2026-07-10): - Kai builds a DRAFT in a split-screen builder (chat | Preview/Code | Publish to Production) — no Approve card; rewrote the build flow in build-with-kai and getting-started steps 3-5 accordingly. - App detail tabs: Overview/Advanced Settings/All Runs/Terminal Logs/ Drafts/Versions; Kai apps get a private Keboola-managed Git repo; scaffold files App.tsx / index.ts / kbcQuery.ts. - Deploy wizard: Python/JS backend format '1.6.1 - Python 3.11 + JavaScript (Node 20, Bun 1.3)'; XSmall = 8GB/1CPU (reference updated). - Auth dropdown re-shot (None/Basic/OIDC/GitLab/GitHub/JumpCloud). - Skill file source confirmed (ai-kit dataapp-development SKILL.md); direct raw download link added. - 9 screenshots replaced with new-backend captures; published-app shots still pending (app start failures in the demo project — flagged). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
For preview comparison against variant A (PR #996), per Jordan: - Sidebar groups: Build (With Kai / Locally) and Run & share (Authentication / Publish and share); Reference; Streamlit last. - convert-nav now supports label-only groups (no landing page). - python-js.md merged away: the stack explainer moves into what-are-apps (The stack: Python/JS), the dev workflow into build-locally; /data-apps/python-js/ 301s to build-locally. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…, skill CTAs Per Jordan's live review of the previews: - Remove all development-branch mentions from app pages (branches don't work for apps). - Document Basic (Password) as the default auth and where the generated password appears (next to Open App after deploy; Kai shows it last). - Prominent 'Get your agent started' skill-download CTA on build-with-kai, build-locally, python-js — a human-facing download, agents must not auto-fetch skills. - Step-4 (draft preview) screenshot placeholder — to capture in the new demo project (264, KBC Toy Co.). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…re-b # Conflicts: # src/content/docs/data-apps/python-js.md
…flow
All app screenshots re-shot in the designated demo project (KBC Toy Co.,
dummy Shopify data) on the new Python/JS backend — no real data in any
frame. End-to-end flow verified by actually building and publishing a
Toy Store Sales Dashboard with Kai:
- Confirmation card DOES appear before Kai creates the app (Decline /
Always allow / Approve) — approve step restored in getting-started
and build-with-kai with a fresh screenshot.
- New step-4 image: split-screen draft with live Preview ('a private
draft that updates live as Kai builds' — verbatim product copy).
- Publish mechanics documented from observation: Kai creates the prod
app up front, works on a draft branch in the managed repo, publish =
merge draft -> main, deploy, cleanup; final card gives URL, password,
Open App (password masked in the shot).
- Published state shot: Active config page + Kai's URL/password card.
- Old Streamlit-era live-app image removed; standalone published-app
shot flagged (needs manual password login).
- Advanced Settings houses env vars/theme/mappings; Drafts tab only
while a draft exists.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…re-b # Conflicts: # src/content/docs/data-apps/python-js.md
…rview - Standalone shot of the published Toy Store Sales Dashboard at its own URL (captured after manual password login) — restored in getting-started step 5 and what-are-apps. - Overview gains a compact 'What people build' typology (dashboards, internal tools, narratives, configurators, agent-facing services) with the live-app image, leading into Beyond dashboards. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per review feedback the CTA link becomes a solid accent button (.skill-download-btn in custom.css). The skill file is vendored into public/data-apps/ so the download attribute actually downloads (cross-origin raw.githubusercontent links open in the browser instead). Source + sync TODO noted inline (keboola/ai-kit@main). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…re-b # Conflicts: # src/content/docs/data-apps/python-js.md
Per Jordan + user: the two pages described the same flow. The merged
page lives at /data-apps/getting-started/ ('Build your first app with
Kai'): the 5-step walkthrough with screenshots, prompt tips folded into
step 2, refining into step 4, then the deeper mechanics (approval
model, drafts->production, data access, manual creation, agent-facing
apps). /data-apps/build-with-kai/ 301s here; nav entry 'Build with
Kai' points at it; all inbound links updated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…re-b # Conflicts: # _data/navigation.yml # src/content/docs/data-apps/build-with-kai.md # src/content/docs/data-apps/index.md # src/content/docs/data-apps/python-js.md # src/sidebar.mjs
…lit section The backend-version format (1.15.x - Python + Streamlit), the Python- variants table, and the pre-installed package list are Streamlit-image facts — they now live on /data-apps/streamlit/ (with the legacy /components/data-apps/backend-versions/ redirect). The reference keeps a Python/JS-focused Backend versions section: wizard format, deps from the repository, pointer to the Streamlit section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Replace auth-options.png with a clean frame: the Authentication Type dropdown open showing all six methods (None/Basic/OIDC/GitLab/GitHub/ JumpCloud). The previous 264 frame had caught the settings-reorg modal instead of the dropdown. - Publish and share had no images; add the published app's config view (App URL + Open in new tab + App Info) and mention the header action buttons. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Three distinct images, each under its heading: - Publish the app -> the Deploy App wizard (backend size + timeout). - Share with your team -> the Overview App URL block (copy + open). - Manage a deployed app -> the app header + ... menu open (Copy app, Automate, Debug mode, Delete app). Corrected the actions list to the real menu. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…onical) Per the docs-section rules, every page now ends with a single '**Next →**' footer forming one reading chain: Overview → What are apps → Build with Kai → Build locally → Authentication → Publish and share → Reference → Streamlit → back to Overview. Replaced ad-hoc 'Next steps' bullet lists with the standard footer. Retargeted two prose links off the removed python-js page to build-locally (redirect still covers old URLs). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Iamfle4ka
changed the title
- Manual create: Python/JS is Git-only — removed the inline-Code option for it (Code stays for Streamlit); fixed steps 2 & 4 + config image alt. - Removed the 'Expose the app to other agents' section from getting-started (misleading in a tutorial); the capability now lives as an 'Agent-facing services' bullet on what-are-apps. - what-are-apps: folded the one-line 'How an app is hosted' section into 'How apps fit into Keboola' (kept the hosting-model TODO). - Dedup: what-are-apps is the canonical 'What you can build' list; overview 'What people build' trimmed to a teaser linking there, and the duplicated live-app image dropped from overview. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Verified the migration live in project 264: Streamlit apps have a 'Migrate to Python/JS with Kai' button; Kai proposes a plan and builds a new Python/JS app (React UI, server-side queries) as a draft, leaving the Streamlit app untouched until you publish. - New page streamlit/migrate-to-python-js.md with the real 3-step flow + two screenshots (migrate button/plan, migrated draft preview). Linked from streamlit/index (replaced the TODO) and nav. - what-are-apps hero swapped to the migrated Shopify Store Monitor dashboard (nicer app, per Jordan) — new app-dashboard.png. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Iamfle4ka
changed the title
Iamfle4ka
changed the title
… references) Per Jordan (Jul 14 sync): the download button gave only SKILL.md, but the canonical resource is the whole dataapp-development/ folder in keboola/ai-kit — skill, app templates (python / nodejs / python-node / streamlit / duckdb-cache), and 14 reference guides the agent draws on. - Vendor the folder verbatim as public/data-apps/keboola-dataapp-development-skill.zip (87 files, from ai-kit@b7f57df); drop the single-file vendored .md - Point both download buttons (getting-started, build-locally) at the zip and say what's inside; direct GitHub link now targets the folder, not raw SKILL.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review posted on behalf of Miroslav Cillik (via Claude). Findings from verifying the Data Apps rework:
Verdict: Solid and accurate where independently verifiable — 6 auth types, Basic-password default, the Streamlit Python 3.10/3.11/3.13 split, and the deliberate choice to keep E2B out of the public docs all check out. But this is not a clean sign-off yet; please resolve the inline items plus the points below first.
To confirm before merge:
- Merge target / structure variant. This PR's description now calls itself the canonical PR superseding #996, but Linear PRDCT-489 framed #1013 as the grouped "variant B" to compare against the flatter #996. Worth confirming #1013 (grouped) is genuinely the intended merge target and #996 is retired.
- BigQuery Storage Access.
reference.mddocuments Storage Access as fully supported on both Snowflake and BigQuery, with detailed BigQuery dialect guidance. A June product note listed "BigQuery direct-storage for data apps" as a gap — please confirm it actually shipped before signing off. - Single-tenant caveat is missing. Python/JS apps, Kai, and Keboola-managed Git are limited on single-tenant stacks (per the single-tenant SOP), but the docs currently read as if these are universally available. Consider a note — or confirm the omission is intentional for public docs.
- Version numbers, KBC_TOKEN / secret-naming, OIDC issuers — see the inline comments.
- Redirects: three moved pages dropped their primary
/data-apps/…URLs (reference.md→ backend-versions + terminal-log-tab;streamlit/lock-version.md→ lock-streamlit-version + code/git-deployment;streamlit/design-guide.md→ general-design-guide). Inline suggestions on each. External bookmarks / indexed URLs would 404; no internal links break. - Leftover
<!-- TODO/VERIFY -->comments across several pages (the PRDCT-471/472/473 hand-offs) — resolve and strip before publish.
Note: the Vercel preview is auth-protected (HTTP 403), so I couldn't verify the live render (images/anchors) — worth a maintainer click-through. This review is from source only.
Posting as event COMMENT — Miro is the human reviewer; this just surfaces findings, it's not an approval or a change request.
| description: Per-app settings, environment variables, data access, backend versions, and limits for Keboola apps. | ||
| redirect_from: | ||
| - /components/data-apps/terminal-log-tab/ | ||
| - /data-apps/storage-access/ |
There was a problem hiding this comment.
Missing redirects for the primary /data-apps/… URLs. This page absorbs the old backend-versions and terminal-log-tab pages, but redirect_from only carries the /components/data-apps/terminal-log-tab/ alias — so the canonical /data-apps/backend-versions/ and /data-apps/terminal-log-tab/ URLs will 404 (the redirect integration doesn't bridge /components/… ↔ /data-apps/…). No internal links break, but external bookmarks / indexed URLs would. Suggest adding the bare paths:
Suggested change
| - /data-apps/storage-access/ | |
| - /data-apps/storage-access/ | |
| - /data-apps/backend-versions/ | |
| - /data-apps/terminal-log-tab/ |
Same pattern affects streamlit/lock-version.md and streamlit/design-guide.md (separate comments).
| redirect_from: | ||
| - /components/data-apps/lock-streamlit-version/ | ||
| - /components/data-apps/lock-streamlit-version/code-deployment/ | ||
| - /components/data-apps/lock-streamlit-version/git-deployment/ |
There was a problem hiding this comment.
Same missing-redirect pattern: only the /components/data-apps/lock-streamlit-version/… aliases are listed, so the canonical /data-apps/lock-streamlit-version/ (+ /code-deployment/, /git-deployment/) URLs will 404. Suggest:
Suggested change
| - /components/data-apps/lock-streamlit-version/git-deployment/ | |
| - /components/data-apps/lock-streamlit-version/git-deployment/ | |
| - /data-apps/lock-streamlit-version/ | |
| - /data-apps/lock-streamlit-version/code-deployment/ | |
| - /data-apps/lock-streamlit-version/git-deployment/ |
| slug: 'data-apps/streamlit/design-guide' | ||
| description: Practical patterns for building a user-friendly Streamlit app in Keboola - theming, headers, body components, footers, and Storage communication. | ||
| redirect_from: | ||
| - /components/data-apps/general-design-guide/ |
There was a problem hiding this comment.
Same pattern: the canonical /data-apps/general-design-guide/ URL is dropped (only the /components/… alias is kept) and will 404. Suggest:
Suggested change
| - /components/data-apps/general-design-guide/ | |
| - /components/data-apps/general-design-guide/ | |
| - /data-apps/general-design-guide/ |
| ## Runtime and language support | ||
|
|
||
| To securely access Storage, we recommend creating a dedicated Storage token with limited permissions and passing it to your app as a secret. You can generate such a token following the [guide here](https://help.keboola.com/management/project/tokens/). | ||
| Backend versions since **1.15.0** are available in multiple Python variants: |
There was a problem hiding this comment.
Backend version numbers look stale. The early-July Streamlit release note gives the current scheme as default 1.18.0_python-3.10_streamlit-1.51, with the Python 3.11/3.13 images on the 2.0.0 line (rebased on the Python/JS base). So "since 1.15.0" here — and the 1.15.2 - Python 3.13 + Streamlit 1.51 example on line 170 (repeated on 172) — are inconsistent: 3.13 ships on 2.0.0, not 1.15.x. Please reconcile to the real versions (default 1.18.0 / py3.10; 2.0.0 for py3.11 / py3.13) or drop the specific numbers. The 3.10/3.11/3.13 variant split itself is correct; only the version numbers are in question.
| `KBC_TOKEN` is injected automatically and must stay server-side. Don't add it as a secret yourself, and never send it to the browser. | ||
| ::: | ||
|
|
||
| <!-- VERIFY(Adam Vyborny): scaffold (React + Vite + Express), file paths, and the KBC_TOKEN guidance. Source: internal Devin answer grounded in keboola/ui SKILL.md. The current public page tells users to add #KBC_TOKEN as a secret — that is wrong (reserved, auto-injected, silently shadowed) and must be corrected here. --> |
There was a problem hiding this comment.
Genuine fix worth confirming and shipping (PRDCT-471): the current public page tells users to add #KBC_TOKEN as a secret, which is wrong — it's reserved/auto-injected and silently shadowed if user-set. The new wording on line 46 is correct. Please confirm the scaffold facts (React + Vite + Express, file paths) with Adam, then strip this <!-- VERIFY --> comment before publish.
| | `BRANCH_ID` | Storage API branch ID of the project. | | ||
| | `QUERY_SERVICE_URL` | URL of the Query Service API (stack-specific). Set with Storage Access. | | ||
|
|
||
| <!-- VERIFY(Adam Vyborny): confirm the full env-var list. Correct the existing error: KBC_TOKEN is reserved/auto-injected, not a secret the user adds; "the value is uppercased" should read "the variable name", not the value. --> |
There was a problem hiding this comment.
Two real corrections flagged here (PRDCT-471/473) that the page already applies correctly and just need sign-off:
KBC_TOKENis reserved/auto-injected, not a user-added secret (line 38 now states this).- It's the variable name that gets uppercased, not the value — line 48 now reads correctly (
#my-custom-var→MY_CUSTOM_VAR, value passed through unchanged), fixing the previous error.
Please confirm the full env-var list with Adam, then strip this <!-- VERIFY --> comment.
| If you enter an app with OIDC, you will be asked to select an `Authentication Provider` and sign in. | ||
| | Provider | Keboola provider option | Issuer URL | Notes | | ||
| |---|---|---|---| | ||
| | **Auth0** | Generic OIDC | `https://<yourDomain>.us.auth0.com/` | Register a regular web application. <!-- VERIFY(Miro): confirm the Auth0 issuer format and provider option. The old page mislabeled this issuer as "Google OAuth 2.0" — do not carry that label forward. --> | |
There was a problem hiding this comment.
OIDC provider table (PRDCT-472) — two corrections to confirm against the live UI:
- Auth0: the old page mislabeled this issuer as "Google OAuth 2.0" — good that it's dropped here; confirm the
https://<yourDomain>.us.auth0.com/format and the "Generic OIDC" provider option. - Google Cloud (line 58): the old page used an invalid
http://keboola.com(bad scheme); the bare domainkeboola.comunder Authorized domains is correct — confirm the redirect-URI step order.
Also worth confirming the Entra "Tenant ID" field set. Resolve the per-row <!-- VERIFY --> notes and the line 62 <!-- TODO --> before publish.
|
|
||
| - [Live App](https://online-marketing-dashboard-49569899.hub.north-europe.azure.keboola.com) | ||
| - [Source Code](https://github.com/keboola/marketing-dashboard-data-app) | ||
| <!-- TODO(human-review, Miro): confirm the exact "default vs supported" wording for Python/JS vs Streamlit. Do not state Streamlit is retired. --> |
There was a problem hiding this comment.
This is one of several intentional <!-- TODO/VERIFY --> hand-offs still in the pages (also index.md:41, what-are-apps.md:18 and :44, authentication.md:57-62, build-locally.md:49, reference.md:44). They don't render (HTML comments), but please resolve and strip all of them before publish. For this one specifically: settle the "default vs supported" wording for Python/JS vs Streamlit — and, as the comment notes, don't state Streamlit is retired.
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.
Apps section — full rework (canonical)
This is the canonical Apps section PR (supersedes #996, which was variant A). Base is
main; the diff is the complete rework.Structure (clean Diátaxis, sequential)
/data-apps/python-js/301s to it).Content & accuracy
Verification
npm run buildclean;node scripts/audit-phase2.mjsMISSING IMAGES 0; old URLs (/data-apps/build-in-the-ui/,/data-apps/examples/,/data-apps/python-js/) redirect.Draft — do not merge. Review chain: Mihal → Miro.
🤖 Generated with Claude Code