From 6e033762ad3f88d8f6a794105d0ffe6a9e3a680f Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Sun, 25 Jan 2026 01:54:28 +0000 Subject: [PATCH] docs: initialize project Visual Linux distribution customization platform with 3D builder interface, starting with Omarchy/CachyOS. Co-Authored-By: Claude Opus 4.5 --- .planning/PROJECT.md | 93 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..c76cbac --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,93 @@ +# 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 + +## 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 | + +--- +*Last updated: 2026-01-25 after initialization*