bmad-elsabro 1.0.0

package/docs/user-guide/token-economy.md

@@ -0,0 +1,601 @@
+---
+title: "Token Economy System"
+description: Understand and optimize AI token usage with budgets, efficiency modes, and real-time tracking
+---
+
+Master BMAD Studio's Token Economy System to track, manage, and optimize your AI usage with real-time analytics, smart budgets, and three efficiency modes designed to maximize value while minimizing cost.
+
+## What You'll Learn
+
+- Understand token usage and cost implications
+- Track token consumption in real-time during workflows
+- Configure budgets and receive alerts before limits
+- Choose the right efficiency mode for your needs
+- Analyze historical usage patterns
+- Optimize workflows to reduce token consumption
+- Use caching strategies to minimize redundant API calls
+
+:::note[Prerequisites]
+- BMAD Studio installed with API access configured
+- Basic understanding of AI model pricing (input/output tokens)
+- At least one project initialized for tracking
+:::
+
+:::tip[Quick Path]
+**Dashboard** → View current token usage and budget status
+**Settings** → Token Economy → Configure budgets and default mode
+**Status Bar** → Switch efficiency modes on-the-fly
+**Analytics** → Review historical usage and identify optimization opportunities
+**Achieve 40% savings** in Ultra-Save mode
+:::
+
+## Understanding Tokens
+
+### What Are Tokens?
+
+Tokens are the units of text that AI models process:
+
+- **Input Tokens** — Text sent to the AI (prompts, context, code)
+- **Output Tokens** — Text generated by the AI (responses, code, documentation)
+- **Pricing** — Input tokens cost less than output tokens
+- **Usage** — Different models have different token costs
+
+### Token Calculation
+
+**Approximate token counts:**
+
+| Text Type | Token Ratio |
+| --------- | ----------- |
+| English text | ~4 characters per token |
+| Code | ~3 characters per token |
+| JSON/YAML | ~3.5 characters per token |
+| Whitespace included | Yes, counts toward tokens |
+
+**Example:**
+- A 1,000-word document ≈ 1,300 tokens
+- A 500-line code file ≈ 2,000 tokens
+- A complete PRD (5,000 words) ≈ 6,500 tokens
+
+### Why Token Management Matters
+
+**Cost Control:**
+- Large projects can consume millions of tokens
+- Without tracking, costs can escalate unexpectedly
+- Token Economy System helps you stay within budget
+
+**Efficiency:**
+- Redundant context wastes tokens
+- Caching reduces repeated API calls
+- Smart prompts get better results with fewer tokens
+
+**Project Planning:**
+- Estimate total project cost before starting
+- Allocate budget across development phases
+- Track spend against projections
+
+## The Token Economy Dashboard
+
+### Accessing the Dashboard
+
+Navigate to **Dashboard** → **Token Analytics** to view:
+
+| Panel | Shows |
+| ----- | ----- |
+| **Current Session** | Real-time usage for active workflows |
+| **Today's Usage** | Total tokens consumed today |
+| **Budget Status** | How much of your budget remains |
+| **Historical Trends** | Usage patterns over days, weeks, months |
+| **Top Workflows** | Which workflows consume most tokens |
+| **Mode Comparison** | Efficiency across Ultra-Save, Balanced, Power |
+
+### Real-Time Tracking
+
+**During workflow execution:**
+
+- Token counter in Execution Panel updates live
+- Running total shows input + output tokens
+- Cost estimate displayed in your currency
+- Progress bar shows percentage of budget used
+- Color coding: Green (safe), Yellow (warning), Red (near limit)
+
+### Status Bar Indicator
+
+**Bottom-right status bar shows:**
+
+- Current efficiency mode (Ultra-Save / Balanced / Power)
+- Today's token usage
+- Budget remaining
+- Click to open quick actions menu
+
+## Efficiency Modes
+
+BMAD Studio offers three modes that balance capability with cost:
+
+| Mode | Token Impact | Use Case | Key Features |
+| ---- | ------------ | -------- | ------------ |
+| **Ultra-Save** | 40% reduction | Learning, prototyping, budget-conscious development | Aggressive caching, concise prompts, smaller context windows |
+| **Balanced** | Standard usage | Day-to-day development work | Reasonable caching, full prompts, optimized context |
+| **Power** | Maximum capability | Complex problems, critical analysis, detailed generation | Minimal caching, comprehensive prompts, large context |
+
+### Ultra-Save Mode
+
+**How It Reduces Tokens:**
+
+- **Aggressive Caching** — Reuses previous AI responses when context hasn't changed
+- **Concise Prompts** — Removes verbose instructions, keeps essentials only
+- **Reduced Context** — Sends only directly relevant code/files to AI
+- **Summarization** — Condenses long documents before including in prompts
+- **Skip Optional** — Omits non-critical validation and analysis steps
+
+**Best For:**
+
+- Learning BMAD Studio features
+- Prototyping and experimentation
+- Simple features with clear requirements
+- Budget-constrained projects
+- Repeated similar tasks (benefits from caching)
+
+**Trade-offs:**
+
+- May need more iterations to get desired output
+- Less context means AI might miss nuances
+- Not ideal for complex architectural decisions
+- Reduced quality checks and validations
+
+:::tip[When to Use Ultra-Save]
+Ultra-Save is perfect for learning, simple tasks, and when you're repeating similar operations. The aggressive caching means the second time you run a workflow, it uses far fewer tokens.
+:::
+
+### Balanced Mode
+
+**How It Optimizes:**
+
+- **Smart Caching** — Caches responses but refreshes when context changes significantly
+- **Full Prompts** — Includes all standard instructions and examples
+- **Optimized Context** — Sends relevant files with intelligent filtering
+- **Selective Validation** — Runs important checks, skips redundant ones
+
+**Best For:**
+
+- Day-to-day feature development
+- Standard workflow execution
+- Projects with moderate budgets
+- Most users, most of the time
+- Balanced quality and cost
+
+**Trade-offs:**
+
+- Higher token usage than Ultra-Save
+- May occasionally miss context that Power mode would catch
+- Some advanced features limited
+
+:::note[Recommended Default]
+Balanced mode is recommended for most users. It provides excellent AI quality while keeping costs reasonable. Start here and adjust if needed.
+:::
+
+### Power Mode
+
+**How It Maximizes Quality:**
+
+- **Minimal Caching** — Fresh AI responses ensure latest reasoning
+- **Comprehensive Prompts** — Includes examples, edge cases, best practices
+- **Large Context** — Sends extensive code/documentation for full understanding
+- **Complete Validation** — Runs all quality checks and analysis steps
+- **Detailed Reasoning** — AI explains its decisions thoroughly
+
+**Best For:**
+
+- Complex architectural decisions
+- Critical production code
+- Detailed security analysis
+- Comprehensive documentation generation
+- When quality matters more than cost
+
+**Trade-offs:**
+
+- Significantly higher token consumption
+- Slower execution (more data to process)
+- Can exceed budgets quickly on large projects
+
+:::caution[Budget Impact]
+Power mode can consume 2-3x more tokens than Balanced mode. Use it strategically for critical decisions, not entire workflows.
+:::
+
+### Switching Modes
+
+**During Workflow Execution:**
+
+1. Click mode indicator in status bar
+2. Select new mode from dropdown
+3. Confirmation dialog shows impact
+4. Mode switches immediately for next step
+
+**Setting Default Mode:**
+
+1. Navigate to **Settings** → **Token Economy**
+2. Select **Default Efficiency Mode**
+3. Choose Ultra-Save, Balanced, or Power
+4. New workflows start in this mode
+
+**Per-Workflow Defaults:**
+
+1. Open workflow in Visual Workflow Editor
+2. Click **Workflow Settings** in toolbar
+3. Set **Preferred Efficiency Mode**
+4. This workflow always starts in chosen mode
+
+## Budgets and Alerts
+
+### Configuring Budgets
+
+**Set spending limits to control costs:**
+
+1. Navigate to **Settings** → **Token Economy** → **Budgets**
+2. Configure budget levels:
+   - **Daily Budget** — Maximum tokens per day
+   - **Weekly Budget** — Maximum tokens per week
+   - **Monthly Budget** — Maximum tokens per month
+   - **Project Budget** — Maximum for current project
+3. Enter limits in tokens or equivalent currency
+4. Enable/disable each budget level
+5. Click **Save Budgets**
+
+**Budget Calculation:**
+
+```
+Token Budget = (Your Monthly Spend) / (Cost Per Token)
+
+Example:
+$100/month budget ÷ $0.000003/token = 33,333,333 tokens/month
+≈ 1,111,111 tokens/day
+```
+
+:::tip[Start Conservative]
+Set initial budgets conservatively. You can always increase them. It's harder to justify overruns than to celebrate coming in under budget.
+:::
+
+### Alert Thresholds
+
+**Receive notifications at key points:**
+
+| Threshold | When Triggered | Recommended Action |
+| --------- | -------------- | ------------------ |
+| **50%** | Halfway to budget limit | Informational only, no action needed |
+| **75%** | Three-quarters used | Review usage patterns, consider Ultra-Save |
+| **90%** | Approaching limit | Switch to Ultra-Save, defer non-critical work |
+| **100%** | Budget exhausted | Workflow execution pauses, requires approval |
+
+**Configure alerts:**
+
+1. **Settings** → **Token Economy** → **Alert Thresholds**
+2. Set percentages for each alert level
+3. Choose notification method:
+   - **In-App** — Notification panel in BMAD Studio
+   - **Desktop** — System notification
+   - **Email** — Send to specified address
+   - **Webhook** — POST to custom URL
+4. Enable/disable alerts independently
+
+### Budget Exceeded Behavior
+
+**When a budget is reached:**
+
+1. **Workflow Pauses** — Execution stops before next AI call
+2. **Alert Displayed** — Shows budget status and options
+3. **User Choice:**
+   - **Increase Budget** — Adjust limit and continue
+   - **Cancel Workflow** — Stop execution, save progress
+   - **Switch to Ultra-Save** — Continue in economy mode
+   - **Review Usage** — Open analytics before deciding
+
+:::caution[No Automatic Overruns]
+BMAD Studio never exceeds your configured budgets without explicit approval. This prevents surprise costs.
+:::
+
+## Token Analytics
+
+### Historical Usage Dashboard
+
+**View usage patterns over time:**
+
+**Daily View:**
+- Hourly token consumption graph
+- Peak usage times highlighted
+- Workflow execution markers
+- Mode usage breakdown
+
+**Weekly View:**
+- Daily totals with trend line
+- Weekday vs. weekend patterns
+- Budget tracking progress
+- Cost projections
+
+**Monthly View:**
+- Week-by-week comparison
+- Project breakdown
+- Mode efficiency comparison
+- Year-over-year trends (if available)
+
+### Workflow Analysis
+
+**Identify high-cost workflows:**
+
+1. Navigate to **Analytics** → **Workflows**
+2. View table showing:
+   - Workflow name
+   - Total executions
+   - Average tokens per execution
+   - Total tokens consumed
+   - Percentage of total usage
+3. Sort by any column
+4. Click workflow for detailed breakdown
+
+**Per-Workflow Details:**
+
+- Token usage per step
+- Input vs. output token ratio
+- Execution time correlation
+- Success vs. failure impact
+- Mode comparison (if workflow run in multiple modes)
+
+### Cost Tracking
+
+**Monitor spending in your currency:**
+
+1. **Settings** → **Token Economy** → **Cost Configuration**
+2. Enter your API pricing:
+   - Input token cost (e.g., $0.000003)
+   - Output token cost (e.g., $0.000015)
+   - Currency (USD, EUR, GBP, etc.)
+3. Analytics dashboard shows costs in your currency
+4. Budgets can be set in currency amount
+
+**Cost Reports:**
+
+- Daily/weekly/monthly spend summaries
+- Project cost tracking
+- Export to CSV for accounting
+- Budget vs. actual comparisons
+
+## Caching Strategies
+
+### How Caching Works
+
+**BMAD Studio caches AI responses to reduce redundant calls:**
+
+- **Cache Key** — Combination of prompt + context + model
+- **Hit** — Exact match found, cached response returned (0 tokens)
+- **Miss** — No match, new API call made, response cached
+- **Expiration** — Caches expire after configured duration
+
+### Cache Configuration
+
+**Settings** → **Token Economy** → **Caching**
+
+| Setting | Description | Default |
+| ------- | ----------- | ------- |
+| **Cache Duration** | How long responses stay cached | 1 hour (Ultra-Save), 30 min (Balanced), 5 min (Power) |
+| **Max Cache Size** | Maximum disk space for cache | 500 MB |
+| **Cache Location** | Where cached responses stored | User data directory |
+| **Cache Warming** | Pre-cache common workflows | Off |
+
+### Cache Effectiveness
+
+**View cache performance:**
+
+1. Navigate to **Analytics** → **Caching**
+2. Review metrics:
+   - **Hit Rate** — Percentage of requests served from cache
+   - **Tokens Saved** — Total tokens not sent to API due to cache
+   - **Cost Savings** — Money saved by caching
+   - **Top Cached Queries** — Most frequently reused responses
+
+**Optimizing Cache Hit Rate:**
+
+- Run similar workflows in succession
+- Use consistent prompt templates
+- Avoid unnecessary context changes
+- Batch similar tasks together
+
+:::tip[Cache Warming]
+Enable cache warming to pre-populate cache with common workflow responses. First run is slow, subsequent runs are much faster and use fewer tokens.
+:::
+
+### Cache Management
+
+**Clear cache when needed:**
+
+- **Clear All** — Remove all cached responses
+- **Clear Expired** — Remove only expired entries
+- **Clear Project** — Remove cache for current project only
+- **Selective Clear** — Remove cache for specific workflows
+
+**When to clear cache:**
+
+- After updating agent configurations
+- When AI responses seem stale
+- After BMAD Studio updates
+- Before running critical workflows in Power mode
+
+## Optimization Strategies
+
+### Reduce Token Consumption
+
+**Workflow-Level Optimizations:**
+
+1. **Remove Unnecessary Steps** — Audit workflows, remove redundant validation
+2. **Combine Steps** — Merge steps that could be done in one AI call
+3. **Optimize Context** — Send only essential files to AI
+4. **Use Templates** — Pre-filled templates reduce AI generation needs
+5. **Reuse Outputs** — Reference previous outputs instead of regenerating
+
+**Prompt-Level Optimizations:**
+
+1. **Be Specific** — Precise prompts get better results faster
+2. **Use Examples** — Show desired format to reduce iterations
+3. **Set Constraints** — Limit output length when possible
+4. **Avoid Repetition** — Don't restate context in every step
+5. **Progressive Enhancement** — Start simple, add detail only if needed
+
+**Context-Level Optimizations:**
+
+1. **File Filtering** — Exclude test files, dependencies, build artifacts
+2. **Summarization** — Summarize large files before sending to AI
+3. **Selective Loading** — Load files on-demand, not all upfront
+4. **Context Limits** — Set maximum context size per workflow
+5. **Smart Truncation** — Keep beginnings and ends, truncate middles
+
+### Mode Selection Strategy
+
+**Per-Phase Recommendations:**
+
+| Phase | Recommended Mode | Rationale |
+| ----- | ---------------- | --------- |
+| **Analysis** | Balanced or Ultra-Save | Brainstorming and research benefit from caching |
+| **Planning** | Balanced or Power | PRD and architecture need quality reasoning |
+| **Implementation** | Balanced | Code generation balances quality and cost |
+| **Testing** | Ultra-Save or Balanced | Test generation highly cacheable |
+| **Reviews** | Power | Critical reviews deserve maximum scrutiny |
+
+**Per-Task Recommendations:**
+
+| Task | Mode | Why |
+| ---- | ---- | --- |
+| **Simple bug fix** | Ultra-Save | Straightforward, well-defined |
+| **New feature** | Balanced | Standard development work |
+| **Architecture decision** | Power | Long-term impact, needs depth |
+| **Documentation** | Ultra-Save | Highly cacheable, iterative |
+| **Security review** | Power | Critical, can't compromise |
+| **Refactoring** | Balanced | Needs understanding but not urgent |
+
+### Monitoring and Adjustment
+
+**Weekly Review Process:**
+
+1. **Check Analytics** — Review weekly usage dashboard
+2. **Identify Spikes** — Find unusually high-cost workflows
+3. **Analyze Causes** — Why did those workflows consume more?
+4. **Optimize** — Apply reduction strategies to high-cost workflows
+5. **Adjust Budgets** — Reallocate budget based on actual patterns
+6. **Document Learnings** — Note what worked for future reference
+
+**Monthly Budget Planning:**
+
+1. Review previous month's actual usage
+2. Factor in upcoming project phases
+3. Adjust monthly budget if needed
+4. Set goals for cost reduction
+5. Identify opportunities for Ultra-Save mode
+
+## What You've Accomplished
+
+You've mastered BMAD Studio's Token Economy System:
+
+- Understood token concepts and cost implications
+- Configured budgets and alert thresholds
+- Learned three efficiency modes and when to use each
+- Explored historical analytics and usage patterns
+- Implemented caching strategies for cost reduction
+- Applied optimization techniques across workflows
+- Established monitoring and adjustment processes
+
+Your token management setup now includes:
+
+```
+BMAD Studio Token Economy/
+├── Real-Time Tracking
+│   ├── Current session usage
+│   ├── Budget status display
+│   └── Cost estimates
+├── Budgets & Alerts
+│   ├── Daily/Weekly/Monthly limits
+│   ├── 50%/75%/90%/100% thresholds
+│   └── Multi-channel notifications
+├── Efficiency Modes
+│   ├── Ultra-Save (40% reduction)
+│   ├── Balanced (standard)
+│   └── Power (maximum quality)
+├── Analytics Dashboard
+│   ├── Historical usage graphs
+│   ├── Workflow cost analysis
+│   └── Cache effectiveness metrics
+└── Optimization Strategies
+    ├── Caching configurations
+    ├── Context filtering rules
+    └── Mode selection guidelines
+```
+
+## Quick Reference
+
+| Action | Access Method | Purpose |
+| ------ | ------------- | ------- |
+| **View Usage** | Dashboard → Token Analytics | Current and historical usage |
+| **Switch Mode** | Status bar → Click mode indicator | Change efficiency mode |
+| **Set Budget** | Settings → Token Economy → Budgets | Configure spending limits |
+| **Check Alerts** | Notification panel | View budget warnings |
+| **Workflow Analysis** | Analytics → Workflows | Identify high-cost workflows |
+| **Cache Settings** | Settings → Token Economy → Caching | Configure cache behavior |
+| **Cost Config** | Settings → Token Economy → Cost | Set API pricing |
+| **Export Data** | Analytics → Export | Download usage reports |
+
+## Common Questions
+
+### Why are my token costs higher than expected?
+
+Check these factors:
+- **Large Context** — Sending too many files to AI
+- **Power Mode** — More comprehensive prompts use more tokens
+- **Low Cache Hit Rate** — Not benefiting from caching
+- **Output Length** — AI generating verbose responses
+- **Workflow Design** — Redundant or inefficient steps
+
+Review Analytics → Workflows to identify the highest-cost workflows and optimize them.
+
+### How accurate is the real-time token counter?
+
+Very accurate. BMAD Studio counts actual tokens sent to and received from the API. The estimate may differ slightly from final billing due to rounding, but it's typically within 1-2%.
+
+### Can I track tokens for multiple projects separately?
+
+Yes. Each project has its own token tracking. Use the project selector in Analytics to view per-project usage, costs, and budgets.
+
+### What happens if I exceed my API provider's limits?
+
+BMAD Studio respects your configured budgets but cannot prevent exceeding your API provider's account limits. If you hit provider limits, API calls will fail. Monitor your provider dashboard independently.
+
+### Does switching modes mid-workflow affect results?
+
+Yes. Steps executed in different modes may produce different results due to varying prompt detail and context. For consistency, use the same mode throughout a workflow.
+
+### How do I reduce token usage without sacrificing quality?
+
+- Start in Balanced mode
+- Optimize workflow context (exclude unnecessary files)
+- Use caching effectively (run similar tasks together)
+- Be specific in prompts (reduces back-and-forth)
+- Review workflow design (remove redundant steps)
+
+### Can I set different budgets for different projects?
+
+Yes. Navigate to Settings → Token Economy → Project Budgets. Each project can have its own daily/weekly/monthly limits.
+
+## Getting Help
+
+- **Budget Planning** — Help → Token Economy Guide
+- **Cost Optimization** — [Discord](https://discord.gg/gk8jAdXWmj) (#cost-optimization)
+- **Analytics Questions** — Help → Analytics Documentation
+- **Mode Selection** — Help → Efficiency Mode Comparison
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Ultra-Save achieves 40% reduction** — Great for learning and simple tasks
+- **Balanced mode recommended for most work** — Best quality/cost balance
+- **Set budgets before starting** — Prevents surprise costs
+- **Monitor weekly analytics** — Identify optimization opportunities
+- **Caching saves significant tokens** — Batch similar tasks together
+- **Power mode for critical decisions** — Use strategically, not everywhere
+- **Context optimization has huge impact** — Exclude unnecessary files
+:::
+
+Ready to master workflows? Return to the [Workflows Guide](/docs/user-guide/workflows.md) to apply your token optimization knowledge to workflow design, or explore the [Getting Started Guide](/docs/user-guide/getting-started.md) for foundational BMAD Studio concepts.