bmad-elsabro 1.0.0

package/docs/user-guide/getting-started.md

@@ -0,0 +1,348 @@
+---
+title: "Getting Started with BMAD Studio"
+description: Install BMAD Studio and launch your first project in the desktop application
+---
+
+Welcome to BMAD Studio — a professional desktop application that brings AI-powered workflows, visual editors, and intelligent token management to your software development process.
+
+## What You'll Learn
+
+- Install and launch BMAD Studio on Windows, macOS, or Linux
+- Complete the onboarding wizard in under 5 minutes
+- Navigate the Auto-Claude-inspired interface
+- Create your first project with visual workflow tools
+- Understand the key features and capabilities
+
+:::note[Prerequisites]
+- **Operating System** — Windows 10+, macOS 12+, or Ubuntu 20.04+
+- **Internet Connection** — Required for AI features and initial setup
+- **API Access** — Claude API key for AI-powered features (user-provided)
+- **Basic Project Knowledge** — Understanding of your project's goals
+:::
+
+:::tip[Quick Path]
+**Download** → Install BMAD Studio for your platform
+**Launch** → Complete 5-minute onboarding wizard
+**Create** → Initialize first project with visual editors
+**Build** → Use workflows with real-time token tracking
+:::
+
+## Understanding BMAD Studio
+
+BMAD Studio transforms the BMAD-METHOD CLI tool into a professional desktop application with powerful visual features:
+
+| Feature | What It Does |
+| ------- | ------------ |
+| **Visual Workflow Editor** | Drag-and-drop interface for creating and modifying workflows |
+| **Token Economy System** | Real-time tracking with budgets and three efficiency modes |
+| **Monaco Editor** | Professional code editor with syntax highlighting and IntelliSense |
+| **Integrated Terminal** | Execute commands without leaving the application |
+| **Agent Management** | Create and edit AI agents with visual YAML editor |
+| **Test Center** | AI-powered test generation and visual test builder |
+| **Smart Adaptation** | Auto-detect project type and suggest optimal workflows |
+
+### Three Efficiency Modes
+
+BMAD Studio offers intelligent token management:
+
+| Mode | Best For | Token Impact |
+| ---- | -------- | ------------ |
+| **Ultra-Save** | Budget-conscious development, prototyping | 40% reduction in token usage |
+| **Balanced** | Day-to-day development work | Standard token consumption |
+| **Power** | Complex problems, detailed analysis | Maximum AI capability |
+
+## Installation
+
+### Download BMAD Studio
+
+Visit the downloads page and select your platform:
+
+- **Windows** — Download `.exe` installer (Windows 10/11)
+- **macOS** — Download `.dmg` file (macOS 12+)
+- **Linux** — Download `.AppImage` file (Ubuntu 20.04+)
+
+### Install on Windows
+
+1. Run the downloaded `.exe` installer
+2. Follow the installation wizard prompts
+3. Choose installation location (default: `C:\Program Files\BMAD Studio`)
+4. Launch BMAD Studio from the Start Menu
+
+### Install on macOS
+
+1. Open the downloaded `.dmg` file
+2. Drag BMAD Studio to your Applications folder
+3. Launch from Applications or Spotlight search
+4. If prompted about security, go to System Preferences → Security & Privacy → Open Anyway
+
+:::caution[macOS Security]
+First launch may show "unidentified developer" warning. This is normal for new applications. Use System Preferences → Security & Privacy to allow the app.
+:::
+
+### Install on Linux
+
+1. Make the `.AppImage` file executable:
+   ```bash
+   chmod +x BMAD-Studio-*.AppImage
+   ```
+2. Run the AppImage:
+   ```bash
+   ./BMAD-Studio-*.AppImage
+   ```
+3. Optional: Add to your applications menu using AppImageLauncher
+
+## First Launch: Onboarding Wizard
+
+When you launch BMAD Studio for the first time, the onboarding wizard guides you through setup.
+
+### Step 1: Welcome
+
+The welcome screen introduces BMAD Studio's key features:
+- Visual workflow editing
+- Token economy management
+- AI agent integration
+- Test automation capabilities
+
+Click **Get Started** to begin.
+
+### Step 2: Configure API Access
+
+BMAD Studio requires Claude API access for AI features:
+
+1. Enter your Claude API key
+2. Test the connection
+3. Select default AI model (Sonnet recommended for balanced performance)
+
+:::tip[API Keys]
+Don't have an API key? Visit [Anthropic Console](https://console.anthropic.com/) to create one. API keys are stored securely in your local configuration only.
+:::
+
+### Step 3: Choose Your Theme
+
+Select your preferred interface theme:
+- **Dark Mode** — Easier on eyes, popular among developers
+- **Light Mode** — Clear contrast, traditional interface
+- **Auto** — Matches your system preference
+
+Theme can be changed anytime from Settings.
+
+### Step 4: Configure Default Paths
+
+Set default locations for:
+- **Projects Folder** — Where your BMAD projects are stored
+- **Workflows Directory** — Custom workflow definitions (default: `.bmad/workflows`)
+- **Agents Directory** — Agent configurations (default: `.bmad/agents`)
+
+### Step 5: Select Efficiency Mode
+
+Choose your default token economy mode:
+- **Ultra-Save** — Best for learning and experimentation
+- **Balanced** — Recommended for most users
+- **Power** — When you need maximum AI capability
+
+You can switch modes anytime during workflows.
+
+### Onboarding Complete
+
+Click **Launch BMAD Studio** to access the main interface. The entire onboarding takes under 5 minutes.
+
+## The BMAD Studio Interface
+
+BMAD Studio features an Auto-Claude-inspired layout:
+
+| Area | Purpose |
+| ---- | ------- |
+| **Sidebar (Left)** | Navigation: Dashboard, Workflows, Agents, Tests, Terminal, Settings |
+| **Main Panel (Center)** | Primary workspace: editors, workflow canvas, dashboard |
+| **Chat Panel (Right)** | AI assistant with streaming responses and context awareness |
+| **Status Bar (Bottom)** | Token usage, current mode, project status, notifications |
+
+### Collapsible Sidebar
+
+- Click the hamburger icon (☰) to collapse/expand the sidebar
+- Keyboard shortcut: `Ctrl+B` (Windows/Linux) or `Cmd+B` (macOS)
+- Collapsed sidebar shows icons only for more workspace
+
+### Dashboard View
+
+The Dashboard shows:
+- **Recent Projects** — Quick access to your last 5 projects
+- **Token Analytics** — Usage graphs and budget status
+- **Quick Actions** — Create project, import legacy, run workflow
+- **System Status** — Application health and updates
+
+### Integrated Terminal
+
+Access the terminal from the sidebar:
+- Execute commands without leaving BMAD Studio
+- Multiple terminal tabs for parallel tasks
+- Copy/paste support
+- Clear terminal and search history
+
+## Creating Your First Project
+
+Let's create a project using BMAD Studio's visual tools.
+
+### Step 1: Initialize Project
+
+1. Click **Create Project** on the Dashboard
+2. Choose project creation method:
+   - **New Project** — Start from scratch
+   - **Import Existing** — Add BMAD to existing codebase
+   - **Use Template** — Domain-specific templates (Healthcare, FinTech, etc.)
+3. Enter project details:
+   - **Project Name** — Descriptive name for your project
+   - **Project Path** — Where files will be stored
+   - **Planning Track** — Quick Flow, BMad Method, or Enterprise
+
+:::note[Planning Tracks]
+- **Quick Flow** — Simple features, 1-15 stories, tech-spec only
+- **BMad Method** — Products and platforms, 10-50+ stories, full documentation
+- **Enterprise** — Compliance systems, 30+ stories, complete governance
+:::
+
+### Step 2: Auto-Detection
+
+BMAD Studio's Smart Adaptation analyzes your project:
+
+- **Project Type** — Detects React, Vue, Node.js, etc.
+- **Project Size** — Estimates complexity
+- **Recommended Track** — Suggests appropriate planning level
+- **Required Workflows** — Lists recommended workflows for your project type
+
+Review the recommendations and adjust if needed.
+
+### Step 3: Initialize Configuration
+
+BMAD Studio creates project structure:
+
+```
+your-project/
+├── .bmad/
+│   ├── config.json              # Project configuration
+│   ├── workflows/               # Workflow definitions
+│   ├── agents/                  # Agent configurations
+│   └── steps/                   # Step definitions
+├── .bmad-output/
+│   └── (empty - artifacts saved here)
+└── ...
+```
+
+Click **Finish** to complete initialization.
+
+## Exploring Key Features
+
+### Visual Workflow Editor
+
+1. Navigate to **Workflows** in the sidebar
+2. Click **Create Workflow** or select an existing workflow
+3. Use drag-and-drop to:
+   - Add steps from the step palette
+   - Connect steps to define order
+   - Configure step parameters
+   - Save and execute workflows
+
+### Agent Editor
+
+1. Navigate to **Agents** in the sidebar
+2. Click **Create Agent** or select an existing agent
+3. Edit agent YAML with Monaco Editor:
+   - Syntax highlighting for YAML
+   - Real-time validation
+   - IntelliSense for agent properties
+   - Error highlighting with helpful messages
+
+### Token Dashboard
+
+1. Navigate to **Dashboard** → **Token Analytics**
+2. View real-time data:
+   - Current session token usage
+   - Historical usage trends (daily, weekly, monthly)
+   - Budget status and alerts
+   - Mode comparison analytics
+3. Configure budgets and alerts in Settings
+
+## What You've Accomplished
+
+You've successfully set up BMAD Studio and learned the fundamentals:
+
+- Installed BMAD Studio on your platform
+- Completed the onboarding wizard
+- Explored the Auto-Claude-inspired interface
+- Created your first project with Smart Adaptation
+- Discovered visual workflow editing and agent management
+
+Your BMAD Studio installation now includes:
+
+```
+BMAD Studio/
+├── Application Files
+├── Configuration Store
+│   ├── user-settings.json       # Your preferences
+│   ├── api-config.json          # API access (encrypted)
+│   └── token-analytics.db       # Token usage database
+└── Projects/
+    └── your-first-project/      # Your initialized project
+```
+
+## Quick Reference
+
+| Feature | Access Method | Purpose |
+| ------- | ------------- | ------- |
+| **Dashboard** | Sidebar → Dashboard | Overview and quick actions |
+| **Workflows** | Sidebar → Workflows | Create and edit workflows visually |
+| **Agents** | Sidebar → Agents | Manage AI agent configurations |
+| **Tests** | Sidebar → Tests | Test Center with AI generator |
+| **Terminal** | Sidebar → Terminal | Execute commands in-app |
+| **Settings** | Sidebar → Settings | Configure preferences |
+| **Token Analytics** | Dashboard → Analytics | View token usage and budgets |
+| **Chat Panel** | Always visible (right) | Interact with AI assistant |
+
+## Common Questions
+
+### Can I use BMAD Studio offline?
+
+Partially. All features except AI chat work offline. Monaco Editor loads from local files. You'll need internet for AI-powered workflows and chat.
+
+### Where are my API keys stored?
+
+API keys are encrypted and stored locally in your user configuration directory. They never leave your machine except to make API calls to Claude.
+
+### Can I import my existing CLI projects?
+
+Yes. Use **Import Existing** when creating a project. BMAD Studio includes a Legacy Migration Wizard to guide you through importing old `.bmad` configurations.
+
+### How do I switch efficiency modes?
+
+Click the mode indicator in the status bar or use Settings → Token Economy → Default Mode. You can also switch modes during workflow execution.
+
+### Can I customize keyboard shortcuts?
+
+Yes. Go to Settings → Keyboard Shortcuts to view and customize all keyboard bindings.
+
+### What if the application won't launch?
+
+Run the diagnostics command from your terminal:
+```bash
+bmad diagnostics
+```
+This reports system status and troubleshooting information.
+
+## Getting Help
+
+- **In-App Help** — Click the `?` icon in any panel for context-sensitive help
+- **Documentation** — Full guides available in Help → User Guide
+- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-studio-help)
+- **Issues** — Report bugs on [GitHub](https://github.com/bmad-method/bmad-studio/issues)
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Onboarding takes under 5 minutes** — Complete setup and start building
+- **Three efficiency modes** — Choose based on budget and complexity needs
+- **Smart Adaptation detects project type** — Get tailored recommendations
+- **All CLI features preserved** — Desktop app is a superset of CLI functionality
+- **Token analytics built-in** — Track usage and optimize costs from day one
+:::
+
+Ready to dive deeper? Check out the [Workflows Guide](/docs/user-guide/workflows.md) to master visual workflow editing and the [Token Economy Guide](/docs/user-guide/token-economy.md) to optimize your AI usage.