Skip to content

USER_MANUAL.md

Latest commit

 

History

History
executable file
·
629 lines (448 loc) · 18.5 KB

USER_MANUAL.md

File metadata and controls

executable file
·
629 lines (448 loc) · 18.5 KB
Raw

Bravais User Manual

A Steelbore OS NixOS Distribution Version: 2.1 | Date: 2026-04-05

Table of Contents

  1. Getting Started
  2. Login and Session Selection
  3. Desktop Environments
  4. Terminal Emulators
  5. Keyboard Layout
  6. Shell Configuration
  7. System Administration
  8. Steelbore Theme
  9. Troubleshooting

1. Getting Started

1.1 System Overview

Bravais is a NixOS-based operating system built on the Spacecraft Software Standard. It features:

  • Four desktop environments: Niri, LeftWM, COSMIC, and GNOME
  • Unified theming: All applications use the Steelbore color palette
  • Rust-first tooling: Memory-safe alternatives wherever possible
  • Declarative configuration: All settings managed through Nix

1.2 First Boot

After installation, you will be greeted by the tuigreet login screen:

STEELBORE :: BRAVAIS
2026-04-05 14:30:00

Username: _

Enter your username and password to log in.

2. Login and Session Selection

2.1 tuigreet Interface

The login manager displays:

  • Current date and time (ISO 8601 format)
  • Username prompt
  • Password prompt (displayed as asterisks)
  • Session selector

2.2 Selecting a Desktop Session

After entering your username, press F2 or use the session selector to choose:

Session Description
niri-session Niri scrolling tiling (Wayland)
start-cosmic COSMIC desktop (Wayland)
gnome-session GNOME desktop (Wayland)
leftwm LeftWM tiling WM (X11)

The session selector remembers your last choice.

3. Desktop Environments

3.1 Niri (Wayland)

Niri is a scrolling tiling Wayland compositor. Windows are arranged in columns that scroll horizontally.

3.1.1 Core Concepts

  • Columns: Windows are stacked vertically within columns
  • Scrolling: Columns scroll left/right across the workspace
  • Workspaces: Multiple virtual workspaces (1-9)

3.1.2 Keybindings

Legend: Mod = Super/Windows key

Session Control
Keybinding Action
Mod+Shift+E Quit Niri (logout)
Application Launch
Keybinding Action
Mod+Return Open terminal (Alacritty)
Mod+D Open launcher (onagre)
Mod+Shift+D Open launcher (anyrun)
Window Management
Keybinding Action
Mod+Q Close focused window
Mod+F Maximize column
Mod+Shift+F Fullscreen window
Focus Navigation (Vim-style)
Keybinding Action
Mod+H Focus column left
Mod+L Focus column right
Mod+K Focus window up
Mod+J Focus window down
Focus Navigation (Arrow keys)
Keybinding Action
Mod+Left Focus column left
Mod+Right Focus column right
Mod+Up Focus window up
Mod+Down Focus window down
Move Windows (Vim-style)
Keybinding Action
Mod+Shift+H Move column left
Mod+Shift+L Move column right
Mod+Shift+K Move window up
Mod+Shift+J Move window down
Move Windows (Arrow keys)
Keybinding Action
Mod+Shift+Left Move column left
Mod+Shift+Right Move column right
Mod+Shift+Up Move window up
Mod+Shift+Down Move window down
Workspaces
Keybinding Action
Mod+1 to Mod+9 Focus workspace 1-9
Mod+Shift+1 to Mod+Shift+9 Move column to workspace 1-9
Mod+WheelUp Focus workspace up
Mod+WheelDown Focus workspace down
Resize
Keybinding Action
Mod+Minus Decrease column width 10%
Mod+Equal Increase column width 10%
Screenshots
Keybinding Action
Print Screenshot entire screen
Mod+Print Screenshot focused window

3.1.3 Status Bar (Ironbar)

The top bar displays:

  • Left: Workspace indicators, focused window title
  • Center: Clock (HH:MM:SS :: YYYY-MM-DD)
  • Right: CPU %, RAM %, system tray

3.2 LeftWM (X11)

LeftWM is a tiling window manager for X11, written in Rust.

3.2.1 Core Concepts

  • Tags: LeftWM uses "tags" instead of workspaces (1-9)
  • Layouts: Multiple layout algorithms available
  • Scratchpad: Hidden terminal accessible via keybinding

3.2.2 Keybindings

Legend: Mod = Super/Windows key

Session Control
Keybinding Action
Mod+Shift+E Logout
Application Launch
Keybinding Action
Mod+Return Open terminal (Alacritty)
Mod+D Open launcher (rlaunch)
Mod+Shift+D Open launcher (rofi)
Window Management
Keybinding Action
Mod+Q Close focused window
Mod+F Toggle fullscreen
Mod+Shift+F Toggle floating
Focus Navigation (Vim-style)
Keybinding Action
Mod+H Focus window left
Mod+L Focus window right
Mod+K Focus window up
Mod+J Focus window down
Focus Navigation (Arrow keys)
Keybinding Action
Mod+Left Focus window left
Mod+Right Focus window right
Mod+Up Focus window up
Mod+Down Focus window down
Move Windows (Vim-style)
Keybinding Action
Mod+Shift+H Move window left
Mod+Shift+L Move window right
Mod+Shift+K Move window up
Mod+Shift+J Move window down
Tags (Workspaces)
Keybinding Action
Mod+1 to Mod+9 Go to tag 1-9
Mod+Shift+1 to Mod+Shift+9 Move window to tag 1-9
Layout Control
Keybinding Action
Mod+Space Next layout
Mod+Shift+Space Previous layout
Resize
Keybinding Action
Mod+Minus Decrease main width
Mod+Equal Increase main width
Scratchpad
Keybinding Action
Mod+Grave Toggle scratchpad terminal

3.2.3 Layouts

LeftWM supports multiple layout algorithms:

Layout Description
MainAndVertStack Main window left, stack right
MainAndHorizontalStack Main window top, stack below
MainAndDeck Main window left, deck (tabs) right
GridHorizontal Grid layout
EvenHorizontal Equal horizontal split
EvenVertical Equal vertical split
Fibonacci Fibonacci spiral layout
Monocle Single window fullscreen

Press Mod+Space to cycle through layouts.

3.2.4 Status Bar (Polybar)

The top bar displays:

  • Left: Tag indicators (workspaces)
  • Center: Clock (HH:MM:SS :: YYYY-MM-DD)
  • Right: CPU %, RAM %, network status

3.3 COSMIC (Wayland)

COSMIC is a full-featured desktop environment from System76.

3.3.1 Key Features

  • Native Wayland compositor
  • Integrated settings application
  • cosmic-panel for taskbar
  • cosmic-launcher for application search
  • cosmic-term terminal emulator

3.3.2 Default Keybindings

COSMIC uses standard keybindings:

Keybinding Action
Super Open launcher
Super+T Open terminal
Super+E Open file manager
Alt+F4 Close window
Super+Arrow Tile window

Configure keybindings in Settings > Keyboard > Shortcuts.

3.4 GNOME (Wayland)

GNOME is a full-featured desktop environment with extensive customization through extensions.

3.4.1 Installed Extensions

  • Caffeine (prevent sleep)
  • Just Perfection (UI tweaks)
  • Window Gestures
  • Vim Alt-Tab
  • Open-Bar
  • Launcher

3.4.2 Default Keybindings

Keybinding Action
Super Activities overview
Super+A Show applications
Super+Arrow Tile window
Alt+Tab Switch windows
Alt+F2 Run command

Configure keybindings in Settings > Keyboard > Keyboard Shortcuts.

4. Terminal Emulators

4.1 Available Terminals

Terminal Launch Command Description
Alacritty alacritty Default, GPU-accelerated
WezTerm wezterm Feature-rich, Lua config
Rio rio Rust-based, native rendering
Ghostty ghostty Zig-based, very fast
COSMIC Term cosmic-term COSMIC native terminal
Ptyxis ptyxis GNOME VTE-based
WaveTerm waveterm AI-native terminal
Warp warp-terminal AI-powered terminal

4.2 Recommended Usage

  • Daily use: Alacritty or Ghostty (fastest)
  • Feature-rich: WezTerm (tabs, splits, Lua scripting)
  • AI features: WaveTerm or Warp
  • COSMIC integration: cosmic-term
  • GNOME integration: Ptyxis

All terminals are themed with the Steelbore color palette.

5. Keyboard Layout

5.1 Available Layouts

  • Primary: US English (us)
  • Secondary: Arabic (ara)

5.2 Switching Layouts

Press Ctrl+Space to toggle between US and Arabic layouts.

The current layout is indicated in the status bar.

6. Shell Configuration

6.1 Default Shell

The default shell is Nushell (nu), a modern shell written in Rust.

6.2 Built-in Aliases

Alias Command Description
ll ls -l Long listing
lla ls -la Long listing with hidden
telemetry macchina System information
sensors watch -n 1 sensors Hardware sensors
sys-logs journalctl -p 3 -xb System error logs
network-diag gping google.com Network diagnostics
top-processes bottom Process monitor
disk-telemetry yazi File manager
edit hx Helix editor

6.3 Steelbore Identity

Run steelbore in the terminal to display the system identity banner:

============================================================
  STEELBORE :: Industrial Sci-Fi Desktop Environment
============================================================
  STATUS    :: ACTIVE
  LOAD      :: NOMINAL
  INTEGRITY :: VERIFIED
============================================================

6.4 Starship Prompt

The prompt displays:

  • Current directory (blue)
  • Git branch (cyan)
  • Git status (red if dirty)
  • Command duration (amber, if >2s)
  • Success/error indicator (green/red)

7. System Administration

7.1 Rebuilding the System

After modifying configuration files in /spacecraft-software/bravais/:

# Navigate to configuration directory
cd /spacecraft-software/bravais

# Rebuild and switch
sudo nixos-rebuild switch --flake .#bravais

7.2 Common Operations

Task Command
Rebuild system sudo nixos-rebuild switch --flake .#bravais
Test build (no switch) nixos-rebuild build --flake .#bravais
Dry-run build nixos-rebuild dry-build --flake .#bravais
Update flake inputs nix flake update
Garbage collection sudo nix-collect-garbage -d
List generations sudo nix-env --list-generations -p /nix/var/nix/profiles/system
Rollback sudo nixos-rebuild switch --rollback

7.3 Configuration Locations

Component Location
System config /spacecraft-software/bravais/
Host config /spacecraft-software/bravais/hosts/bravais/
User config /spacecraft-software/bravais/users/mj/home.nix
Hardware config /spacecraft-software/bravais/hosts/bravais/hardware.nix

7.4 Fingerprint Enrollment

To enroll your fingerprint:

# Enroll a finger
sudo fprintd-enroll

# Verify enrollment
fprintd-verify

Once enrolled, you can use your fingerprint for:

  • sudo authentication
  • Login (greetd supports PAM)
  • Screen unlock

8. Steelbore Theme

8.1 Color Palette

Color Hex Usage
Void Navy #000027 Background (mandatory)
Molten Amber #D98E32 Primary text, active elements
Steel Blue #4B7EB0 Accents, borders, inactive
Radium Green #50FA7B Success, confirmations
Red Oxide #FF5C5C Errors, warnings
Liquid Coolant #8BE9FD Info, links, highlights

8.2 Fonts

Context Font
UI Headers Orbitron
Code/Terminal JetBrains Mono
Status/HUD Share Tech Mono

8.3 Environment Variables

The theme exports these variables for application use:

SPACECRAFT_BACKGROUND=#000027
SPACECRAFT_TEXT=#D98E32
SPACECRAFT_ACCENT=#4B7EB0
SPACECRAFT_SUCCESS=#50FA7B
SPACECRAFT_WARNING=#FF5C5C
SPACECRAFT_INFO=#8BE9FD

9. Troubleshooting

9.1 Display Issues

Problem: Screen is blank after login

Solution:

  1. Press Ctrl+Alt+F2 to switch to TTY2
  2. Log in
  3. Check logs: journalctl -b -p err
  4. Try a different session (e.g., GNOME instead of Niri)

9.2 Audio Issues

Problem: No sound

Solution:

  1. Check PipeWire status: systemctl --user status pipewire
  2. Restart PipeWire: systemctl --user restart pipewire
  3. Check volume: wpctl get-volume @DEFAULT_AUDIO_SINK@
  4. Set volume: wpctl set-volume @DEFAULT_AUDIO_SINK@ 50%

9.3 Network Issues

Problem: No network connection

Solution:

  1. Check NetworkManager: nmcli general status
  2. List connections: nmcli connection show
  3. Connect to WiFi: nmcli device wifi connect "SSID" password "PASSWORD"

9.4 Build Failures

Problem: nixos-rebuild fails

Solution:

  1. Check for syntax errors in Nix files
  2. Run with --show-trace for detailed errors
  3. Verify flake: nix flake check
  4. Update flake lock: nix flake update

9.5 Session Won't Start

Problem: Selected session crashes immediately

Solution:

  1. Check session logs: journalctl --user -b
  2. Try starting manually from TTY:
    • Niri: niri-session
    • COSMIC: start-cosmic
    • GNOME: dbus-run-session gnome-session
    • LeftWM: startx leftwm

9.6 Fingerprint Not Working

Problem: Fingerprint authentication fails

Solution:

  1. Re-enroll: sudo fprintd-enroll
  2. Check device: fprintd-list $USER
  3. Verify PAM configuration is enabled

Quick Reference Card

Niri Essentials

Key Action
Mod+Return Terminal
Mod+D Launcher
Mod+Q Close window
Mod+H/J/K/L Navigate (vim)
Mod+1-9 Workspaces
Mod+Shift+E Logout

LeftWM Essentials

Key Action
Mod+Return Terminal
Mod+D Launcher
Mod+Q Close window
Mod+H/J/K/L Navigate (vim)
Mod+1-9 Tags
Mod+Space Next layout
Mod+Shift+E Logout

System

Key Action
Ctrl+Space Switch keyboard
Print Screenshot

--- Forged in Spacecraft Software ---