Add Shell Integration Setup to First-Time Onboarding Flow

[urbantech]

Overview

Currently, AINative Studio IDE does not guide users through shell integration setup during onboarding. This feature would add a dedicated onboarding step to help users install the shell command for terminal integration.

User Story

As a new AINative Studio IDE user
I want to be guided through setting up shell integration during first-time onboarding
So that I can easily open files and projects from the terminal without manually configuring shell commands

Current Behavior

• No shell integration setup during onboarding
• Users must manually configure shell commands after installation
• Missing opportunity to improve terminal workflow adoption

Proposed Solution

Add a "Set up shell" step to the multi-step onboarding wizard with the following design:

UI Components

• Icon representing shell/terminal integration (gear + terminal icon)
• Heading: "Set up shell"
• Descriptive text: "This integrates AINative Studio with your shell and allows you to open files and projects from the terminal"
• Primary action button to trigger installation
• "Skip" button for users who want to configure later
• Navigation: "Back", progress dots, "Skip All" options

Permission Handling

• When user clicks the action button, prompt for administrator privileges
• System dialog message: "AINative Studio will now prompt for Administrator privileges to install the shell command"
• Provide "Cancel" and "OK" options in permission dialog
• Handle cancellation gracefully without blocking onboarding

Acceptance Criteria

1. Onboarding Flow Integration

• Add "Set up shell" step to existing onboarding wizard
• Position after initial setup steps but before completion
• Display appropriate shell/terminal icon
• Integrate with multi-step navigation system

2. Clear User Communication

• Display clear heading and explanation text
• Explain what shell integration enables
• Show benefits of terminal integration

3. Permission & Installation

• Prompt for administrator privileges using platform-specific dialogs
• macOS: Use osascript for privilege escalation
• Windows: Use appropriate elevation method
• Linux: Use sudo or pkexec as appropriate
• Install shell command to system PATH
• Verify installation success

4. User Choice & Navigation

• Provide prominent "Skip" button
• Allow skipping without blocking IDE access
• Show progress indicators (dots)
• Enable "Back" and "Skip All" navigation
• Maintain state if user navigates back

5. Error Handling

• Handle permission denial gracefully
• Show clear error messages if installation fails
• Provide option to retry or skip on error
• Don't block onboarding completion on failure

Technical Implementation Notes

Platform-Specific Considerations

• macOS: Use osascript for privilege prompt, install to /usr/local/bin/
• Windows: Use UAC elevation, install to user or system PATH
• Linux: Use sudo/pkexec, install to /usr/local/bin/ or ~/.local/bin/

Code Locations

• Onboarding flow likely in: ainative-studio/src/vs/workbench/contrib/welcomeGettingStarted/ or similar
• CLI integration: ainative-studio/cli/
• Shell command installation logic may need to be added to main process
• Use IPC channels for main/renderer communication for privilege escalation

Shell Command Naming

• Determine command name: ainative or code or both
• Support common use cases:
  • ainative . - Open current directory
  • ainative <file> - Open specific file
  • ainative <folder> - Open folder

Installation Verification

• After installation, verify command is accessible in PATH
• Provide visual confirmation to user
• Log installation details for troubleshooting

Design Reference

See attached screenshot showing the desired UX flow with permission dialog.

Priority

Medium - Improves first-run experience and reduces friction for terminal-based workflows, but users can manually configure later if needed.

Related

• May relate to existing CLI functionality in ainative-studio/cli/
• Consider consistency with VS Code's shell integration approach