debate/.planning/research/FEATURES.md

# Feature Landscape

**Domain:** Linux Distribution Builder and Customization Platform
**Researched:** 2026-01-25

## Table Stakes

Features users expect. Missing = product feels incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| **Package Selection** | Core functionality - users need to choose what software gets installed | Medium | All ISO builders (archiso, Cubic, live-build) provide this. Must support searching, categorizing packages. Debate metaphor: "Talking Points" |
| **Base Distribution Selection** | Users need a foundation to build from | Low | Standard in all tools. Debate calls this "Opening Statement" (Arch, Ubuntu, etc.) |
| **ISO Generation** | End product - bootable installation media | High | Essential output format. Tools like archiso, Cubic all produce .iso files. Requires build system integration |
| **Configuration Persistence** | Users expect to save and reload their work | Medium | All modern tools save configurations (archiso profiles, NixOS configs). Debate calls this "Speech" |
| **Bootloader Configuration** | ISOs must boot on target hardware | Medium | Both UEFI and BIOS support expected. archiso supports syslinux, GRUB, systemd-boot |
| **Kernel Selection** | Users may need specific kernel versions | Low | archiso allows multiple kernels. Important for hardware compatibility |
| **User/Password Setup** | Basic system access configuration | Low | Expected in all distribution builders |
| **Locale/Keyboard Configuration** | System must support user's language/region | Low | Standard feature across all tools |

## Differentiators

Features that set product apart. Not expected, but valued.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| **Visual Conflict Resolution** | Makes dependency hell visible and solvable for non-experts | High | UNIQUE to Debate. Current tools show cryptic error messages. Visual "Objection" system could be game-changing for accessibility |
| **Live Preview in Browser** | See customizations before building ISO | Very High | Web-based VM preview would be revolutionary. Current tools require local VM testing. Enables instant gratification |
| **Curated Starting Templates** | Pre-configured setups (like Omarchy) as starting points | Medium | Inspired by Hyprland dotfiles community and r/unixporn. Debate's "Opening Statements" as gallery |
| **Visual Theme Customization** | GUI for selecting/previewing window managers, themes, icons | Medium | Tools like HyprRice exist for post-install. Doing it PRE-install is differentiator. Debate's "Rhetoric" metaphor |
| **One-Click Export to Multiple Formats** | ISO, USB image, Ventoy-compatible, VM disk | Medium | Ventoy integration is emerging trend. Multi-format export reduces friction |
| **Conflict Explanation System** | AI-assisted or rule-based explanations for why packages conflict | High | Educational value. Turns errors into learning moments. Could use LLM for natural language explanations |
| **Community Template Gallery** | Browse/fork/share custom configurations | Medium | Inspired by dotfiles.github.io and awesome-dotfiles. Social feature drives engagement |
| **Configuration Comparison** | Visual diff between two "Speeches" | Medium | Helps users understand what changed. Useful for learning from others' configs |
| **Automatic Optimization Suggestions** | "You selected KDE and GNOME - did you mean to?" | Medium | Catches common mistakes. Reduces ISO bloat |
| **Real-time Build Size Calculator** | Show ISO size as user adds packages | Low | Prevents surprise "ISO too large" errors at build time |
| **Secure Boot Support** | Generate signed ISOs for secure boot systems | High | archiso added this recently. Becoming table stakes for 2026+ |
| **Reproducible Builds** | Same config = identical ISO every time | Medium | Security/verification feature. Inspired by NixOS philosophy |

## Anti-Features

Features to explicitly NOT build. Common mistakes in this domain.

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| **Full NixOS-style Declarative Config** | Too complex for target audience. Defeats "accessibility" goal | Provide simple GUI with optional advanced mode. Let users export to NixOS/Ansible later if they want |
| **Build Everything Locally** | Computationally expensive, slow, blocks UX | Use cloud build workers. Users configure, servers build. Stream logs for transparency |
| **Support Every Distro at Launch** | Maintenance nightmare, quality suffers | Start with Arch (Omarchy use case). Add Ubuntu/Fedora based on demand. Deep > wide |
| **Custom Package Repository Hosting** | Infrastructure burden, security liability | Use existing repos (AUR, official). Let users add custom repos via URL, but don't host |
| **Native Desktop App** | Limits accessibility, cross-platform pain | Web-first. Desktop can be Electron wrapper later if needed |
| **Real-time Collaboration** | Complex to build, unclear value | Async sharing via templates is sufficient. Can add later if users demand it |
| **Post-Install Configuration** | Scope creep - becomes a remote management tool | Focus on ISO creation. Link to Ansible/SaltStack/dotfiles managers for post-install |
| **Automated Testing of ISOs** | Resource-intensive, brittle, unclear ROI for MVP | Manual testing, community validation. Automate after product-market fit |

## Feature Dependencies

```
Foundation Layer:
  Base Distro Selection → Package Repository Access

Package Layer:
  Package Selection → Conflict Detection
  Conflict Detection → Conflict Resolution UI

Configuration Layer:
  WM/DE Selection → Theme Selection (themes must match WM)
  Package Selection → Build Size Calculator

Build Layer:
  All Configuration → ISO Generation
  ISO Generation → Export Format Options

Sharing Layer:
  Configuration Persistence → Template Gallery
  Template Gallery → Configuration Comparison
```

**Critical Path for MVP:**
1. Base Distro Selection
2. Package Selection
3. Conflict Detection (basic)
4. ISO Generation
5. Configuration Save/Load

**Enhancement Path:**
1. Visual Conflict Resolution (differentiator)
2. Theme Customization
3. Template Gallery
4. Live Preview (if feasible)

## MVP Recommendation

For MVP, prioritize:

### Must Have (Table Stakes):
1. **Base Distro Selection** - Start with Arch only (Omarchy use case)
2. **Package Selection** - Visual interface for browsing/selecting packages
3. **Basic Conflict Detection** - Show when packages conflict, even if resolution is manual
4. **Configuration Save/Load** - Users can save their "Speech"
5. **ISO Generation** - Basic working ISO output
6. **Bootloader Config** - UEFI + BIOS support

### Should Have (Core Differentiators):
7. **Curated Starting Template** - Omarchy as first "Opening Statement"
8. **Visual Conflict Resolution** - The "Objection" system - this is your moat
9. **Build Size Calculator** - Real-time feedback prevents mistakes

### Nice to Have (Polish):
10. **Theme Preview** - Screenshots of WMs/themes
11. **Export to USB Format** - Ventoy-compatible output

Defer to post-MVP:
- **Live Preview**: Very high complexity, requires VM infrastructure. Get manual testing feedback first
- **Template Gallery**: Need user base first. Can launch with 3-5 curated templates
- **Multi-distro Support**: Ubuntu/Fedora after Arch works perfectly
- **Conflict Explanations**: Start with simple error messages, enhance with AI later
- **Secure Boot**: Nice to have but not critical for target audience (Linux-curious users likely disabling secure boot anyway)
- **Reproducible Builds**: Important for security-conscious users but not core value prop

## Platform-Specific Notes

### Web Platform Advantages (for Debate):
- **Accessibility**: No installation barrier, works on any OS
- **Community**: Easy sharing via URLs
- **Iteration**: Can update without user action
- **Discovery**: SEO/social sharing drives growth

### Web Platform Challenges:
- **Build Performance**: Offload to backend workers, not client-side
- **File Size**: Users downloading multi-GB ISOs - need CDN
- **Preview**: Browser-based VM is hard - consider VNC to backend VM

## Competitive Analysis

### Existing Tool Categories:

**Command-Line Tools** (archiso, live-build):
- Strengths: Powerful, flexible, reproducible
- Weaknesses: Steep learning curve, text-based config
- Debate advantage: Visual UI, guided flow

**Desktop GUI Tools** (Cubic, HyprRice):
- Strengths: Easier than CLI, visual feedback
- Weaknesses: Post-install only (HyprRice) or Ubuntu-only (Cubic), still requires Linux knowledge
- Debate advantage: Web-based (works on any OS), pre-install customization, conflict resolution

**Web Services** (SUSE Studio - discontinued):
- Strengths: Accessible, shareable
- Weaknesses: Vendor-locked, no longer maintained
- Debate advantage: Modern stack, open ecosystem (Arch/AUR), domain-specific UX (debate metaphor)

**Declarative Systems** (NixOS):
- Strengths: Reproducible, programmable, powerful
- Weaknesses: Very steep learning curve, unique syntax
- Debate advantage: Visual-first, approachable for non-programmers

### Feature Gap Analysis:

**What nobody does well:**
1. Visual conflict resolution for non-experts
2. Web-based ISO creation for any OS
3. Social/sharing features for configurations
4. Beginner-friendly theming/ricing PRE-install

**What Debate can own:**
1. "Linux customization for the visual web generation"
2. "GitHub for Linux configurations" (social sharing)
3. "What Canva did for design, Debate does for Linux"

## User Journey Feature Mapping

### Target Persona 1: Linux-Curious Switcher
**Pain Points**: Overwhelmed by options, afraid of breaking system, wants pretty desktop

**Critical Features**:
- Curated starting templates (low choice paradox)
- Visual theme preview (see before build)
- Conflict resolution with explanations (learning aid)
- One-click export to USB (easy to test)

### Target Persona 2: Enthusiast Ricer
**Pain Points**: Post-install configuration tedious, wants to share setups, iterates frequently

**Critical Features**:
- Granular package selection (power user control)
- Template gallery for inspiration/sharing
- Configuration comparison (learn from others)
- Fast iteration (quick rebuilds)

### Target Persona 3: Content Creator
**Pain Points**: Needs reproducible setups, wants to share with audience, aesthetics matter

**Critical Features**:
- Shareable configuration URLs (easy distribution)
- Reproducible builds (audience gets same result)
- Theme showcase (visual content)
- Export to multiple formats (audience flexibility)

## Sources

### Linux Distribution Builders:
- [Linux Distribution Builder Tools Features 2026](https://thelinuxcode.com/linux-distributions-a-practical-builder-friendly-guide-for-2026/)
- [archiso - ArchWiki](https://wiki.archlinux.org/title/Archiso)
- [Cubic: Custom Ubuntu ISO Creator](https://github.com/PJ-Singh-001/Cubic)
- [Kali Linux Custom ISO Creation](https://www.kali.org/docs/development/live-build-a-custom-kali-iso/)
- [5 Tools to Create Custom Linux Distro](https://www.maketecheasier.com/6-tools-to-easily-create-your-own-custom-linux-distro/)

### Customization Tools:
- [Awesome Linux Ricing Tools](https://github.com/avtzis/awesome-linux-ricing)
- [HyprRice GUI for Hyprland](https://github.com/avtzis/awesome-linux-ricing)
- [NixOS Configuration Editors](https://nixos.wiki/wiki/NixOS_configuration_editors)
- [nix-gui: NixOS Without Coding](https://github.com/nix-gui/nix-gui)

### Package Management:
- [Package Conflict Resolution](https://distropack.dev/Blog/Post?slug=package-conflict-resolution-handling-conflicting-packages)
- [Dependency Hell - Wikipedia](https://en.wikipedia.org/wiki/Dependency_hell)

### Configuration Sharing:
- [Dotfiles Inspiration Gallery](https://dotfiles.github.io/inspiration/)
- [Awesome Dotfiles Resources](https://github.com/webpro/awesome-dotfiles)
- [Hyprland Example Configurations](https://wiki.hypr.land/Configuring/Example-configurations/)
- [Best Hyprland Dotfiles](https://itsfoss.com/best-hyprland-dotfiles/)

### Multi-Boot & Export:
- [Ventoy Multi-Boot USB](https://opensource.com/article/21/5/linux-ventoy)
- [YUMI Multiboot USB Creator](https://pendrivelinux.com/yumi-multiboot-usb-creator/)

### Confidence Levels:
- **Table Stakes Features**: HIGH (verified via archiso wiki, multiple tool documentation)
- **Differentiator Features**: MEDIUM (based on market gap analysis and community tools)
- **Anti-Features**: MEDIUM (based on scope analysis and target audience research)
- **User Journey Mapping**: LOW (requires user interviews to validate)