Skip to content

feat(ai-ide, getting-started): guide the AI setup with a walkthrough - #17969

Draft
ndoschek wants to merge 2 commits into
masterfrom
ai-walkthrough
Draft

feat(ai-ide, getting-started): guide the AI setup with a walkthrough#17969
ndoschek wants to merge 2 commits into
masterfrom
ai-walkthrough

Conversation

@ndoschek

Copy link
Copy Markdown
Member

What it does

Moves the Theia AI onboarding out of the chat welcome message into a walkthrough on the welcome page, and opens the walkthrough mechanism to Theia extensions on the way.

@theia/getting-started: WalkthroughService built its walkthroughs exclusively from the contributes.walkthroughs section of deployed plugins, so a build-time Theia extension had no way to offer one, even though everything around it (cards, progress, completion events, walkthrough.open) is source agnostic.

  • adds the WalkthroughProvider contribution point as a second, equal source
  • both sources are collected before anything is pruned, so neither drops the other's walkthroughs
  • Walkthrough.pluginId becomes optional, for walkthroughs that come from an extension rather than a plugin
  • the welcome page moves its sections into a column of their own and lists up to five walkthroughs next to them, centred in a readable measure

@theia/ai-ide: the chat welcome message taught the AI features, gated the setup and picked a default agent all at once, while the welcome page carried a second, hard-coded AI banner in a package that knows nothing about AI. Guidance therefore only appeared once a user was already stuck in the chat, and nothing tracked what was already done.

  • contributes "Get started with AI": AI support in the app, turn the features on, connect a language model, choose a default agent, ask a first question, tool confirmation and workspace trust, and a closing step on prompts, MCP, token usage, AI History and the experimental AI First layout
  • steps complete on context keys describing what the user achieved (ai.hasReadyLanguageModel, ai.chat.hasRequest, ai.chat.hasDefaultAgent, ai.chat.toolConfirmationConfigured) rather than on settings changing, so a user who configured everything earlier finds them already ticked
  • the opening step carries what the welcome page used to announce in its AI banner, including the opt-in and cost notice and the community links; the banner and news sections are removed
  • the chat welcome keeps only the states it has to show in place (no model, AI disabled, workspace not trusted), each linking into the walkthrough
  • adds ai.openGettingStartedWalkthrough ("Get Started with AI")

Contributes to #16730

How to test

With a fresh profile, or after running Help: Reset Walkthrough Progress:

  1. The welcome page lists Get started with AI in the right column, 0 of 7. Open it.
  2. Work through the steps. Each one ticks itself once you actually do it: enable the features, enter an API key, pick a default agent, send a chat message, change the tool confirmation default. The closing step is marked done by hand.
  3. Progress survives a reload, and the card leaves the welcome page once every step is done. It stays reachable via More... and Help: Open Walkthrough.
  4. Chat view: with no language model configured, and with the AI features disabled, the slim states appear and their links open the walkthrough.
  5. Regression: a VS Code extension contributing contributes.walkthroughs still shows up, and installing it does not remove the AI walkthrough.

Follow-ups

Breaking changes

  • This PR introduces breaking changes and requires careful review. If yes, the breaking changes section in the changelog has been updated.

Attribution

Review checklist

Reminder for reviewers

`WalkthroughService` built its walkthroughs exclusively from the
`contributes.walkthroughs` section of deployed plugins, so a build-time Theia
extension had no way to offer one - even though everything around it (cards,
progress, completion events, `walkthrough.open`) is source agnostic.

Add the `WalkthroughProvider` contribution point as a second, equal source.
Both sources are collected before anything is pruned, so neither drops the
other's walkthroughs, and `Walkthrough.pluginId` becomes optional for the
walkthroughs that come from an extension rather than a plugin.

To give them the room that suggests, the welcome page moves its sections into
a column of their own and lists up to five walkthroughs next to them.
The chat welcome message taught the AI features, gated the setup and picked a
default agent all at once, while the welcome page carried a second, hard-coded
AI banner in a package that knows nothing about AI. Guidance therefore only
appeared once a user was already stuck in the chat, and nothing tracked what
was already done.

Contribute "Get started with AI" instead, which walks from disabled AI features
to a first answer in the chat and keeps its progress on the welcome page. Its
steps complete on context keys describing what the user achieved rather than on
the settings changing, so a user who configured everything earlier finds them
already ticked. The opening step carries what the welcome page used to announce
in its AI banner, which is removed along with the news section.

The chat welcome keeps only the states it has to show in place - no model, AI
disabled, workspace not trusted - each linking into the walkthrough.
@github-project-automation github-project-automation Bot moved this to Waiting on reviewers in PR Backlog Aug 28, 2026
@ndoschek
ndoschek marked this pull request as draft August 28, 2026 15:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Waiting on reviewers

Development

Successfully merging this pull request may close these issues.

1 participant