[Hackathon] feat(workspace): add interactive onboarding tours with AI tutor

[xuang7]

Demo video (2 min, onboarding journey): basics component, first workflow, agent, trophy shelf.

demo.mov

Motivation

New users land in the Texera workspace and face a dense canvas-and-panels UI with no in-product guidance. The only path to fluency today is reading external docs, watching recorded videos, or asking an instructor in person — high friction for new user onboarding.

To address this gap, this PR introduces a self-contained, opt-in onboarding tutorial that meets users inside the workspace they actually use: short 1–2 minute guided tours, hands-on build flows, an always-on AI tutor, and a trophy shelf to make progress visible.

Changes

This PR ships three pieces that together turn first-time workspace use from a doc-reading exercise into a guided, interactive experience. New users can go from "where do I click?" to a working visualization in minutes without leaving the page, get unstuck via an in-context AI tutor when the spotlight isn't enough, and have a visible reason to come back and finish the flows.

1. Tutorial tour mode (driver.js-powered, 1–2 min, multiple difficulty levels, resumable)

• Guided spotlights highlight real UI elements and auto-advance when the user performs the expected action, so the tour feels like doing rather than reading.
• Four flows ship out of the box: a workspace orientation with optional per-toolbar deep dives, two hands-on build flows for first CSV-to-chart pipelines, and a public-workflow explore path. Difficulty scales from quick orientation to full pipeline.
• Versioned localStorage progress means users can close the tab mid-tour and resume exactly where they left off, with a single config flag to disable the entire feature in production.

2. Argus, an all-seeing AI tutor (in-context, can act on the canvas)

• A peacock-feather-eye mascot lives next to the canvas with idle, thinking, cheer, and wave states, so the tutor feels alive rather than static.
• Free-form chat backed by the existing agent-service answers questions about the current step in context.
• Action directives let Argus drop operators directly onto the canvas instead of only describing them.

3. Trophy shelf (per-flow badges plus bonus achievements, makes progress visible and replayable)

• Micro-rewards on each step advance (sparkles and XP) for moment-to-moment feedback.
• Per-flow badges plus bonus achievements for completing all flows or speed-running them, shown in a flip-card trophy shelf.
• Locked and coming-soon flows appear in the same shelf so users see what's next.

Demos

Screenshot 1: tour selection

Screenshot 2: step-by-step guided tour

Screenshot 3: resume popover after returning mid-tour

Screenshot 4: Argus AI tutor chat interface

Screenshot 5: trophy shelf with earned badges and coming-soon flows

Tests

20 new tests, all passing locally:

• tutorial-progress.spec.ts (7 cases): load/save round-trip, legacy-flag migration, stale-schema reset, malformed-JSON fallback.
• flows-integrity.spec.ts (13 invariants over the FLOWS registry): unique flow + badge ids, valid skipToStep targets, intact chainTo / prerequisites references, branching layout for overview-workspace.
• workspace.component.spec.ts: tutorialEnabled getter passthrough.

Future improvements

• More tours: add a platform-overview tour (hub, dashboards, account) and additional content beyond the four workspace flows shipped here. build-ml (Logistic Regression on prebuilt workflow) and hub-tour stubs are already in place.
• Dynamic story generation: The current version highly relies on the frontend source — step selectors and copy are written against today's HTML, so any UI change may break a flow. Future work can introduce an agent that generates tour content automatically from the frontend source (component metadata, route map, form schemas), keeping tours in sync with the UI as it evolves.
• Tighter agent integration with tours: Argus is currently separate from the tour flow — users have to switch contexts to ask questions. Future work can embed the agent into individual steps so it can proactively explain, hint, or assist within the tour itself. The action vocabulary can also expand beyond add_operator to connect, configure, run, etc.
• Production LLM setup: LLM creds sourced from local LiteLLM; production needs the operator-hosted proxy or equivalent.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 43.15%. Comparing base (e27b98a) to head (8325945).

Files with missing lines	Patch %	Lines
...pache/texera/service/resource/ConfigResource.scala	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #5104      +/-   ##
============================================
- Coverage     43.17%   43.15%   -0.02%     
+ Complexity     2214     2211       -3     
============================================
  Files          1045     1045              
  Lines         40260    40261       +1     
  Branches       4250     4250              
============================================
- Hits          17381    17376       -5     
- Misses        21812    21813       +1     
- Partials       1067     1072       +5     

Flag	Coverage Δ		*Carryforward flag
access-control-service	39.53% <ø> (ø)
agent-service	33.72% <ø> (ø)		Carriedforward from e27b98a
amber	43.81% <ø> (-0.04%)	⬇️
computing-unit-managing-service	0.00% <ø> (ø)
config-service	0.00% <0.00%> (ø)
file-service	32.18% <ø> (ø)
frontend	34.05% <ø> (ø)		Carriedforward from e27b98a
python	90.43% <ø> (ø)		Carriedforward from e27b98a
workflow-compiling-service	56.81% <ø> (ø)

*This pull request uses carry forward flags. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Yicong-Huang]

Thank you for participating in the hackathon. We really enjoyed your idea and appreciate the contribution.

We are now archiving hackathon submissions by closing the submission PRs. However, we strongly encourage you to continue developing your idea and explore the possibility of merging it into the main branch.

To move forward, please:

1. Open an issue describing your idea, and link this PR as a reference.
2. Discuss the design and implementation plan with us in the issue.
3. Open smaller, focused PRs so they can go through proper review.

Thanks again for your participation and contribution!

[Yicong-Huang]

@xuang7 how likely can we merge this into main?

[xuang7]

@xuang7 how likely can we merge this into main?

I think the full hackathon PR is not ready to merge into main directly yet. The current version is still tightly coupled to UI internals, such as CSS selectors and class names, so future UI refactors could silently break the tours.

I do think the tutorial feature is useful and worth continuing. A possible path forward is to split the work into smaller focused PRs. We can start with a simple guided tour based on this existing PR and introduce a data-tour-id attribute contract on key workspace UI elements to reduce the impact of UI refactors. Then we can consider adding more advanced parts like the AI tutor, progress tracking, and trophy shelf in later PRs.

[Yicong-Huang]

I think this is a well designed feature (you have an end to end experience). I suggest you open an umbrella issue and start to create sub-issues to add those components piece by piece. The hackathon project can easily cut into 10+ PRs.