v0.5.0: NomadArch - Binary-Free Mode Release

Features: - Binary-Free Mode: No OpenCode binary required - NomadArch Native mode with free Zen models - Native session management - Provider routing (Zen, Qwen, Z.AI) - Fixed MCP connection with explicit connectAll() - Updated installers and launchers for all platforms - UI binary selector with Native option Free Models Available: - GPT-5 Nano (400K context) - Grok Code Fast 1 (256K context) - GLM-4.7 (205K context) - Doubao Seed Code (256K context) - Big Pickle (200K context)
2025-12-26 11:27:03 +04:00
commit 1d427f4cf5
407 changed files with 100777 additions and 0 deletions
--- a/dev-docs/MVP-PRINCIPLES.md
+++ b/dev-docs/MVP-PRINCIPLES.md
@@ -0,0 +1,326 @@
+# MVP Development Principles
+
+## Core Philosophy
+
+**Focus on functionality, NOT performance.**
+
+The MVP (Minimum Viable Product) is about proving the concept and getting feedback. Performance optimization comes later, after we validate the product with real users.
+
+---
+
+## What We Care About in MVP
+
+### ✅ DO Focus On:
+
+1. **Functionality**
+   - Does it work?
+   - Can users complete their tasks?
+   - Are all core features present?
+
+2. **Correctness**
+   - Does it produce correct results?
+   - Does error handling work?
+   - Is data persisted properly?
+
+3. **User Experience**
+   - Is the UI intuitive?
+   - Are loading states clear?
+   - Are error messages helpful?
+
+4. **Stability**
+   - Does it crash?
+   - Can users recover from errors?
+   - Does it lose data?
+
+5. **Code Quality**
+   - Is code readable?
+   - Are types correct?
+   - Is it maintainable?
+
+### ❌ DON'T Focus On:
+
+1. **Performance Optimization**
+   - Virtual scrolling
+   - Message batching
+   - Lazy loading
+   - Memory optimization
+   - Render optimization
+
+2. **Scalability**
+   - Handling 1000+ messages
+   - Multiple instances with 100+ sessions
+   - Large file attachments
+   - Massive search indexes
+
+3. **Advanced Features**
+   - Plugins
+   - Advanced search
+   - Custom themes
+   - Workspace management
+
+---
+
+## Specific MVP Guidelines
+
+### Messages & Rendering
+
+**Simple approach:**
+
+```typescript
+// Just render everything - no virtual scrolling
+<For each={messages()}>
+  {(message) => <MessageItem message={message} />}
+</For>
+```
+
+**Don't worry about:**
+
+- Sessions with 500+ messages
+- Re-render performance
+- Memory usage
+- Scroll performance
+
+**When to optimize:**
+
+- Post-MVP (Phase 8)
+- Only if users report issues
+- Based on real-world usage data
+
+### State Management
+
+**Simple approach:**
+
+- Use SolidJS signals directly
+- No batching
+- No debouncing
+- No caching layers
+
+**Don't worry about:**
+
+- Update frequency
+- Number of reactive dependencies
+- State structure optimization
+
+### Process Management
+
+**Simple approach:**
+
+- Spawn servers as needed
+- Kill on close
+- Basic error handling
+
+**Don't worry about:**
+
+- Resource limits (max processes)
+- CPU/memory monitoring
+- Restart optimization
+- Process pooling
+
+### API Communication
+
+**Simple approach:**
+
+- Direct SDK calls
+- Basic error handling
+- Simple retry (if at all)
+
+**Don't worry about:**
+
+- Request batching
+- Response caching
+- Optimistic updates
+- Request deduplication
+
+---
+
+## Decision Framework
+
+When implementing any feature, ask:
+
+### Is this optimization needed for MVP?
+
+**NO if:**
+
+- It only helps with large datasets
+- It only helps with many instances
+- It's about speed, not correctness
+- Users won't notice the difference
+- It adds significant complexity
+
+**YES if:**
+
+- Users can't complete basic tasks without it
+- App is completely unusable without it
+- It prevents data loss
+- It's a security requirement
+
+### Examples
+
+**Virtual Scrolling:** ❌ NO for MVP
+
+- MVP users won't have 1000+ message sessions
+- Simple list rendering works fine for <100 messages
+- Add in Phase 8 if needed
+
+**Error Handling:** ✅ YES for MVP
+
+- Users need clear feedback when things fail
+- Prevents frustration and data loss
+- Core to usability
+
+**Message Batching:** ❌ NO for MVP
+
+- SolidJS handles updates efficiently
+- Only matters at very high frequency
+- Add later if users report lag
+
+**Session Persistence:** ✅ YES for MVP
+
+- Users expect sessions to persist
+- Losing work is unacceptable
+- Core functionality
+
+---
+
+## Testing Approach
+
+### MVP Testing Focus
+
+**Test for:**
+
+- ✅ Correctness (does it work?)
+- ✅ Error handling (does it fail gracefully?)
+- ✅ Data integrity (is data saved?)
+- ✅ User flows (can users complete tasks?)
+
+**Don't test for:**
+
+- ❌ Performance benchmarks
+- ❌ Load testing
+- ❌ Stress testing
+- ❌ Scalability limits
+
+### Acceptable Performance
+
+For MVP, these are **acceptable:**
+
+- 100 messages render in 1 second
+- UI slightly laggy during heavy streaming
+- Memory usage grows with message count
+- Multiple instances slow down app
+
+These become **unacceptable** only if:
+
+- Users complain
+- App becomes unusable
+- Basic tasks can't be completed
+
+---
+
+## When to Optimize
+
+### Post-MVP Triggers
+
+Add optimization when:
+
+1. **User Feedback**
+   - Multiple users report slowness
+   - Users abandon due to performance
+   - Performance prevents usage
+
+2. **Measurable Issues**
+   - App freezes for >2 seconds
+   - Memory usage causes crashes
+   - UI becomes unresponsive
+
+3. **Phase 8 Reached**
+   - MVP complete and validated
+   - User base established
+   - Performance becomes focus
+
+### How to Optimize
+
+When the time comes:
+
+1. **Measure First**
+   - Profile actual bottlenecks
+   - Use real user data
+   - Identify specific problems
+
+2. **Target Fixes**
+   - Fix the specific bottleneck
+   - Don't over-engineer
+   - Measure improvement
+
+3. **Iterate**
+   - Optimize one thing at a time
+   - Verify with users
+   - Stop when "fast enough"
+
+---
+
+## Communication with Users
+
+### During Alpha/Beta
+
+**Be honest about performance:**
+
+- "This is an MVP - expect some slowness with large sessions"
+- "We're focused on functionality first"
+- "Performance optimization is planned for v1.x"
+
+**Set expectations:**
+
+- Works best with <200 messages per session
+- Multiple instances may slow things down
+- We'll optimize based on your feedback
+
+### Collecting Feedback
+
+**Ask about:**
+
+- ✅ What features are missing?
+- ✅ What's confusing?
+- ✅ What doesn't work?
+- ✅ Is it too slow to use?
+
+**Don't ask about:**
+
+- ❌ How many milliseconds for X?
+- ❌ Memory usage specifics
+- ❌ Benchmark comparisons
+
+---
+
+## Summary
+
+### The MVP Mantra
+
+> **Make it work, then make it better, then make it fast.**
+
+For CodeNomad MVP:
+
+- **Phase 1-7:** Make it work, make it better
+- **Phase 8+:** Make it fast
+
+### Remember
+
+- Premature optimization is the root of all evil
+- Real users provide better optimization guidance than assumptions
+- Functionality > Performance for MVP
+- You can't optimize what users don't use
+
+---
+
+## Quick Reference
+
+**When in doubt, ask:**
+
+1. Is this feature essential for users to do their job? → Build it
+2. Is this optimization essential for the feature to work? → Build it
+3. Is this just making it faster/more efficient? → Defer to Phase 8
+
+**MVP = Minimum _Viable_ Product**
+
+- Viable = works and is useful
+- Viable ≠ optimized and fast