# Debate

## What This Is

Debate is a web-based platform that lets users visually customize Linux distributions by selecting, combining, and overriding "opinions" - preconfigured choices about packages, window managers, themes, and system configurations. Users build a 3D stack of layers, resolve conflicts visually, and generate a custom bootable ISO. The platform supports saving and sharing configurations ("speeches") with the community.

Starting with Omarchy (DHH's opinionated Arch/Hyprland distribution) as the first "opening statement," the long-term vision is to become the default way people get Linux - any distribution, customized to their needs.

## Core Value

**Make Linux customization visual and accessible to people who aren't Linux experts.**

If the 3D builder doesn't make selecting and combining Linux options feel approachable and even fun, nothing else matters.

## Requirements

### Validated

(None yet - ship to validate)

### Active

- [ ] 3D stack visualization for building configurations
- [ ] Overlay system with dependency resolution and conflict detection
- [ ] Visual conflict resolution ("objections" with concede/rebut options)
- [ ] ISO generation from valid configurations
- [ ] ISO caching for identical configurations
- [ ] Save/load configurations ("speeches")
- [ ] User accounts with authentication
- [ ] Publish speeches with tags ("topics")
- [ ] Browse and filter community speeches
- [ ] Speech ratings/popularity tracking
- [ ] Community overlay contribution workflow
- [ ] CachyOS + Omarchy as initial opening statement
- [ ] Hyprland platform support (from Omarchy)
- [ ] Additional window managers (Sway, i3, KDE, COSMIC, GNOME)

### Out of Scope

- Mobile application - web-first, desktop browser target
- Direct installation to hardware - users download ISO and install themselves
- Paid/premium tiers - v1 is free to establish user base
- Enterprise features - focus on individual users and community
- Cross-distribution support in v1 - starting with Arch-based only (Fedora, Ubuntu etc. are future phases)

## Context

**Technical environment:**
- Build server available: 6 cores, 64GB RAM, NVMe storage
- Self-hosted infrastructure
- Native Python/Node development with Docker for databases/services

**Upstream dependencies:**
- Omarchy (https://github.com/basecamp/omarchy) - no coordination with maintainers, independent project
- CachyOS repositories for optimized Arch packages
- Need to research Omarchy internals to map opinions to overlays

**Market context:**
- Growing Linux adoption driven by Windows dissatisfaction, Steam Deck success, creator influence
- Gap exists between "overwhelming choice" and "take it or leave it" distro opinions
- No existing tool offers visual 3D configuration building

**Terminology:**
The product uses debate/speech terminology throughout:
- Speech = saved configuration
- Opening statement = base distribution
- Platform = window manager
- Rhetoric = theming/ricing
- Talking points = application bundles
- Closing argument = system configuration
- Objection = conflict detected
- Deliver = generate ISO

## Constraints

- **Visual identity**: 3D visualization is the core differentiator - not optional, essential to the product
- **Base distribution**: Starting with CachyOS/Arch only; cross-distro support deferred to future phases
- **Build environment**: ISO builds run in sandboxed environment for security
- **Performance**: 3D UI must run at 60fps on mid-range hardware; 2D fallback for low-end devices
- **Independence**: No upstream coordination with Omarchy - must be resilient to their changes
- **Python tooling**: Use ruff for linting and formatting (replaces flake8, black, isort)
- **Package versions**: Always use actual latest versions from PyPI/npm, not AI training data assumptions — verify with `pip index versions` or package registries

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Start with Omarchy/CachyOS | Proves the concept with an explicitly "opinionated" distro; DHH's profile creates marketing hooks | - Pending |
| 3D visualization required | Core differentiator; no existing tool offers this | - Pending |
| Debate terminology | Creates memorable brand identity; "debate opinions" is the product concept | - Pending |
| Self-hosted infrastructure | Build server already available; full control over build environment | - Pending |
| Greenfield implementation | No legacy constraints; can build architecture correctly from start | - Pending |
| Ruff for Python tooling | Fast, replaces flake8+black+isort; better DX with single tool | - Pending |
| Verify package versions | Always check actual latest from registries, never trust AI assumptions | - Pending |

---
*Last updated: 2026-01-25 after initialization*