debate/.planning/REQUIREMENTS.md

Requirements: Debate

Defined: 2026-01-25 Core Value: Make Linux customization visual and accessible to non-experts

v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

Builder Interface

• BUILD-01: User can view configuration as interactive 3D stack of layers
• BUILD-02: User can rotate and zoom the 3D visualization
• BUILD-03: User can click a layer to select it and see details
• BUILD-04: User can add layers from the layer panel
• BUILD-05: User can remove layers by dragging off stack
• BUILD-06: User can search and filter available overlays in the panel
• BUILD-07: User sees smooth 60fps animations on mid-range hardware
• BUILD-08: Conflicting layers pulse red and lift off stack
• BUILD-09: User sees "Objection!" modal when conflicts arise
• BUILD-10: User can resolve conflicts via Concede (remove), Rebut (swap), or Withdraw (undo)
• BUILD-11: User can access 2D fallback interface on low-end devices

ISO Generation

• ISO-01: User can initiate ISO build ("Deliver") when configuration is valid
• ISO-02: User sees queue position and estimated wait time
• ISO-03: User sees build progress with stages
• ISO-04: ISO builds run in sandboxed environment (systemd-nspawn)
• ISO-05: Identical configurations serve cached ISO immediately
• ISO-06: User can download completed ISO ("Take the Floor")
• ISO-07: Build failures report clear error messages to user

Speeches (Saved Configurations)

• SPCH-01: User can save current configuration as named speech
• SPCH-02: User can add description and topics (tags) to speech
• SPCH-03: User can load saved speech into builder
• SPCH-04: Non-authenticated users can save locally (browser storage)
• SPCH-05: User can publish speech publicly
• SPCH-06: Published speeches are searchable by title/description
• SPCH-07: User can browse community speeches in grid view
• SPCH-08: User can filter speeches by topics, base distribution, window manager, author
• SPCH-09: User can sort speeches by popularity, rating, recent, trending
• SPCH-10: Speech cards show mini preview, title, author, topics, stats
• SPCH-11: User can load community speech into builder
• SPCH-12: User can rate community speeches

User Accounts

• USER-01: User can register with email and password
• USER-02: User can log in with email and password
• USER-03: User session persists across browser refresh
• USER-04: User can log out
• USER-05: User can register/login via GitHub OAuth
• USER-06: User can register/login via Google OAuth
• USER-07: User receives email verification after registration
• USER-08: User can reset password via email link
• USER-09: User can set unique username
• USER-10: User can upload avatar image
• USER-11: User can write bio
• USER-12: User can view their saved speeches in dashboard
• USER-13: User can view their published speeches in dashboard
• USER-14: User can view build history in dashboard
• USER-15: Other users can view public profile (username, avatar, bio, published speeches)

Overlay System

• OVLY-01: Overlays defined via YAML manifest schema
• OVLY-02: Manifests specify name, version, type, description, author, license
• OVLY-03: Manifests specify requires (dependencies), conflicts, provides, replaces
• OVLY-04: Manifests can define user-configurable options (toggle, select, text, number)
• OVLY-05: System builds dependency graph from selected overlays
• OVLY-06: System detects conflicts (objections) before build
• OVLY-07: System detects missing requirements and shows warnings
• OVLY-08: System suggests compatible alternatives when conflicts arise
• OVLY-09: System topologically sorts overlays for correct application order
• OVLY-10: Layer hierarchy enforced: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument
• OVLY-11: Users can submit new overlays via GitHub PR workflow
• OVLY-12: Submitted overlays undergo automated schema validation
• OVLY-13: Submitted overlays undergo security scan
• OVLY-14: Approved overlays appear in builder

Distribution Support

• DIST-01: CachyOS available as Opening Statement
• DIST-02: Omarchy opinions mapped to overlays (theming, apps, configs)
• DIST-03: Hyprland available as Platform
• DIST-04: Sway available as Platform
• DIST-05: i3 available as Platform
• DIST-06: KDE Plasma available as Platform
• DIST-07: COSMIC available as Platform
• DIST-08: GNOME available as Platform
• DIST-09: Pure Arch available as Opening Statement
• DIST-10: EndeavourOS available as Opening Statement

Infrastructure

• INFR-01: API response time < 200ms (p95)
• INFR-02: ISO build completes within 15 minutes
• INFR-03: Platform available 99.9% uptime
• INFR-04: User data protected and backed up daily
• INFR-05: All traffic over HTTPS
• INFR-06: Rate limiting on API endpoints
• INFR-07: CSRF protection enabled

v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

Enhanced Build Features

• ISO-V2-01: Build size calculator shows real-time estimate
• ISO-V2-02: Live log output visible during build (collapsible)
• ISO-V2-03: Multi-format export (ISO, USB image, Ventoy-compatible)

Live Preview

• PREV-01: User can boot generated ISO in browser via WebVM
• PREV-02: Preview runs without downloading full ISO

Additional Distributions

• DIST-V2-01: Fedora available as Opening Statement
• DIST-V2-02: Ubuntu available as Opening Statement
• DIST-V2-03: Cross-distro package mapping layer

Collaboration

• COLLAB-01: Multiple users can edit same speech simultaneously
• COLLAB-02: Speech version history with diff view

Moderation

• MOD-01: Users can flag inappropriate speeches
• MOD-02: Admin can review flagged content
• MOD-03: Admin can remove/hide violating speeches
• MOD-04: Admin can warn/ban users

Out of Scope

Explicitly excluded. Documented to prevent scope creep.

Feature	Reason
Mobile application	Web-first, desktop browser target; mobile can come later
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 (Fedora/Ubuntu)	Deep > wide; get Arch family working perfectly first
Full NixOS-style declarative config	Too complex for target audience
Custom package repository hosting	Infrastructure burden, security liability
Post-install configuration management	Scope creep; link to Ansible/dotfiles instead
Secure Boot signing	Nice to have but not critical for target audience

Traceability

Which phases cover which requirements. Updated during roadmap creation.

Requirement	Phase	Status
(To be filled by roadmapper)

Coverage:

• v1 requirements: 70 total
• Mapped to phases: 0
• Unmapped: 70 (awaiting roadmap)

---

Requirements defined: 2026-01-25 Last updated: 2026-01-25 after initial definition