debate/.planning/PROJECT.md

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