diff --git a/src/docs/cli-reference.md b/src/docs/cli-reference.md index 308ed27..768297d 100644 --- a/src/docs/cli-reference.md +++ b/src/docs/cli-reference.md @@ -12,11 +12,12 @@ OpenBoot v1.0 has two real verbs: **`install`** adds things to your Mac, **`snap ``` openboot install [source] # install from preset, file, or cloud config openboot snapshot # capture your environment +openboot doctor # check system health and diagnose issues openboot login / logout # openboot.dev auth openboot version # print version ``` -> **v1.0 removed these commands:** `pull`, `push`, `diff`, `clean`, `log`, `restore`, `init`, `setup-agent`, `doctor`, `update`, `list`, `edit`, `delete`. OpenBoot no longer uninstalls packages or tracks revision history — `install` is add-only, and `snapshot --publish` overwrites. Manage configs on the [dashboard](/dashboard). See the project [CHANGELOG](https://github.com/openbootdotdev/openboot/blob/main/CHANGELOG.md) for migration. +> **v1.0 removed these commands:** `pull`, `push`, `diff`, `clean`, `log`, `restore`, `init`, `setup-agent`, `update`, `list`, `edit`, `delete`. OpenBoot no longer uninstalls packages or tracks revision history — `install` is add-only, and `snapshot --publish` overwrites. Manage configs on the [dashboard](/dashboard). See the project [CHANGELOG](https://github.com/openbootdotdev/openboot/blob/main/CHANGELOG.md) for migration. ## `openboot install` @@ -59,6 +60,8 @@ openboot install ./backup.json # local config or snapshot file openboot install developer # built-in preset openboot install myalias # alias configured on the dashboard openboot install --dry-run # preview without installing +openboot install alice/dev-setup --pick node,ripgrep # install only named packages +openboot install alice/dev-setup --dry-run # list available package names ``` Explicit flags (`--from`, `--user`/`-u`, `-p`/`--preset`) always override the positional argument. @@ -74,6 +77,7 @@ For private configs, run `openboot login` first. | `--from ` | Install from a local config or snapshot JSON | | `-s, --silent` | Non-interactive mode (for CI/automation) | | `--dry-run` | Preview without installing | +| `--pick ` | Comma-separated list of package names to install from a remote config (e.g. `--pick node,ripgrep`). Fails if any name is unknown. Use `--dry-run` to list available names. | | `--packages-only` | Skip shell, macOS, dotfiles, post-install | | `--shell ` | `install` or `skip` | | `--macos ` | `configure` or `skip` | @@ -193,6 +197,34 @@ openboot version --- +## `openboot doctor` + +Run read-only diagnostic checks on your development environment and get a pass/warn/fail summary. + +``` +openboot doctor +``` + +Checks performed: + +| Check | What it verifies | +|-------|-----------------| +| Homebrew | Installed and on PATH | +| Homebrew outdated | Reports count of outdated packages | +| Git | Installed; user.name and user.email configured | +| Node.js | Installed and reachable | +| npm | Installed and reachable | +| Shell | Default shell is zsh | +| Oh-My-Zsh | Installed at `~/.oh-my-zsh` | +| Brew shellenv | `~/.zshrc` sources `brew shellenv` (Apple Silicon only) | +| OpenBoot dir | `~/.openboot/` exists | +| OpenBoot state | `install_state.json` is valid JSON | +| PATH | `/usr/local/bin` and/or Homebrew prefix on PATH | + +All checks are read-only — `doctor` never modifies your system. + +--- + ## Upgrading OpenBoot OpenBoot no longer has a self-update command. It's installed via Homebrew — use Homebrew to upgrade: diff --git a/src/docs/config-options.md b/src/docs/config-options.md index ec99d74..68b08c7 100644 --- a/src/docs/config-options.md +++ b/src/docs/config-options.md @@ -1,6 +1,6 @@ --- title: Config Options -description: Full config schema — packages, custom scripts, dotfiles repo, visibility, aliases, and the 26 macOS preferences whitelist. +description: Full config schema — packages, custom scripts, dotfiles repo, visibility, aliases, and the macOS preferences whitelist. group: Reference order: 10 --- @@ -140,65 +140,118 @@ You can export any config as a JSON file from the dashboard. Click the **Export* ## macOS Preferences Whitelist -These are the 26 system settings that OpenBoot can configure. Only these are captured by `openboot snapshot` and applied during install. In the dashboard, preferences are grouped into collapsible accordion sections by category. +These are the system settings that OpenBoot can configure. Only these are captured by `openboot snapshot` and applied during install. In the dashboard, preferences are grouped into collapsible accordion sections by category. -### Dock +### System | Setting | Description | Default | |---------|-------------|---------| -| Auto-hide Dock | Automatically hide and show the Dock | on | -| Auto-hide delay (s) | Delay before Dock appears on hover — 0 for instant | 0 | -| Icon size | Dock icon size in pixels | 48 | -| Show recent apps | Show recently used apps in a separate Dock section | off | -| Position on screen | Which edge the Dock appears on (bottom, left, right) | bottom | -| Minimize animation | Visual effect when minimizing windows (genie or scale) | genie | -| Show only active apps | Hide non-running apps from the Dock | off | -| Animate app launches | Bounce icons when launching an app | on | +| Show all file extensions | Show extensions for all files | on | +| Always show scrollbars | Always visible, not just on scroll | Always | +| Disable auto-correct | Turn off automatic spelling correction | off | +| Disable auto-capitalization | Turn off automatic capitalization | off | +| Fast key repeat rate | How fast keys repeat when held — lower = faster (KeyRepeat) | 2 | +| Short delay until key repeat | How long before a held key starts repeating (InitialKeyRepeat) | 15 | ### Finder | Setting | Description | Default | |---------|-------------|---------| -| Default view style | How files display in new windows (icon, list, column, gallery) | list | -| New window opens | Default location for new Finder windows | Home folder | -| Default search scope | Where Finder searches by default (This Mac, current folder) | Current folder | | Show path bar | Full folder path at bottom of windows | on | | Show status bar | Item count and disk space at bottom of windows | on | -| Show hidden files | Show files and folders starting with a dot | off | -| Always show file extensions | Show extensions for all files | on | -| Show full path in title bar | Display POSIX path in window title | off | +| Show sidebar | Show sidebar in Finder windows | on | +| Show tab bar | Show tab bar in Finder windows | on | +| Show preview pane | Show preview pane in Finder windows | off | +| Default view style | How files display in new windows (Nlsv=list, icnv=icon, clmv=column, glyv=gallery) | list | +| Show hidden files | Show files and folders starting with a dot | on | +| Show full POSIX path in title | Display full path in window title bar | on | +| No extension change warning | Suppress the warning when changing a file extension | on | +| Default search scope | Where Finder searches by default (SCcf=current folder, SCev=This Mac) | Current folder | +| Keep folders on top (name sort) | Folders sorted before files when sorting by name | on | +| Keep folders on top (Desktop) | Folders sorted before files on the Desktop | on | +| Don't warn before emptying Trash | Skip confirmation dialog when emptying Trash | on | +| Remove Trash items after 30 days | Auto-purge items in Trash older than 30 days | on | +| Allow quitting Finder (⌘Q) | Enable Quit menu item for Finder | on | +| New window target | Default location for new Finder windows (PfHm=Home, PfDe=Desktop, PfDo=Documents, PfLo=custom path) | Home | +| New window custom path | Custom path when target is PfLo | — | +| Show external drives on Desktop | Show mounted external hard drives on Desktop | on | +| Show internal hard drives on Desktop | Show internal drives on Desktop | off | +| Show servers on Desktop | Show mounted network servers on Desktop | off | +| Show removable media on Desktop | Show USB drives etc. on Desktop | on | +| Show recent tags in sidebar | Show recent tags in Finder sidebar | on | +| No .DS_Store on network volumes | Suppress .DS_Store files on network shares | on | +| No .DS_Store on USB volumes | Suppress .DS_Store files on USB drives | on | -### Trackpad +### Dock | Setting | Description | Default | |---------|-------------|---------| -| Tap to click | Tap the trackpad to click instead of pressing down | on | -| Natural scrolling | Scroll content in the direction your fingers move | on | -| Three-finger drag | Drag windows and items using three fingers | off | +| Auto-hide Dock | Automatically hide and show the Dock | off | +| Show recent apps | Show recently used apps in a separate Dock section | off | +| Icon size | Dock icon size in pixels | 48 | +| Minimize animation | Visual effect when minimizing windows (scale or genie) | scale | -### Desktop +### Screenshots | Setting | Description | Default | |---------|-------------|---------| -| Click desktop to show it | Click wallpaper to hide all windows | off | +| Screenshot save location | Folder where screenshots are saved | ~/Screenshots | +| Screenshot format | File format for screenshots (png, jpg, pdf, tiff) | png | +| Disable window shadows | Remove drop shadows from window screenshots | on | + +### Trackpad + +| Setting | Description | Default | +|---------|-------------|---------| +| Tap to click (wired) | Tap the trackpad to click instead of pressing down | on | +| Tap to click (Bluetooth) | Same setting for Bluetooth trackpads | on | +| Three-finger drag | Drag windows and items using three fingers | on | ### Keyboard | Setting | Description | Default | |---------|-------------|---------| -| Key repeat rate | How fast keys repeat when held — lower = faster | 2 | -| Delay until key repeat | How long before a held key starts repeating | 15 | -| Press and hold for accents | Show accent menu when holding a key (disable for faster repeat) | off | +| Use F1–F12 as standard function keys | Fn key not required to use function keys | on | -### Screenshots +### Mission Control | Setting | Description | Default | |---------|-------------|---------| -| Screenshot format | File format for screenshots (PNG, JPEG, PDF, TIFF) | PNG | -| Disable window shadows | Remove drop shadows from window screenshots | on | +| Don't auto-rearrange Spaces | Keep Spaces order fixed instead of reordering by recent use | on | +| Group windows by application | Group windows by app in Mission Control | on | +| Top-left hot corner | Action when cursor hits top-left corner (0 = disabled) | 0 | +| Top-right hot corner | Action when cursor hits top-right corner (0 = disabled) | 0 | +| Bottom-left hot corner | Action when cursor hits bottom-left corner (0 = disabled) | 0 | +| Bottom-right hot corner | Action when cursor hits bottom-right corner (0 = disabled) | 0 | +| Top-left hot corner modifier | Modifier key for top-left corner (0 = none) | 0 | +| Top-right hot corner modifier | Modifier key for top-right corner (0 = none) | 0 | +| Bottom-left hot corner modifier | Modifier key for bottom-left corner (0 = none) | 0 | +| Bottom-right hot corner modifier | Modifier key for bottom-right corner (0 = none) | 0 | ### Menu Bar | Setting | Description | Default | |---------|-------------|---------| -| Show Sound in menu bar | Always show volume control in the menu bar | on | +| Show Sound in menu bar | Show/hide Sound icon | on | +| Show Bluetooth in menu bar | Show/hide Bluetooth icon | on | +| Show Wi-Fi in menu bar | Show/hide Wi-Fi icon | on | +| Show Battery in menu bar | Show/hide Battery icon | on | +| Hide AirDrop from menu bar | Hide AirDrop icon | on | +| Hide Display from menu bar | Hide Display icon | on | +| Hide Focus Modes from menu bar | Hide Focus Modes icon | on | +| Hide Now Playing from menu bar | Hide Now Playing icon | on | +| Hide Screen Mirroring from menu bar | Hide Screen Mirroring icon | on | +| Sound always-show mode | 3-way dropdown: 18 = Always Show, 2 = Show When Active, 8 = Don't Show (written to ByHost scope on Sequoia) | 18 (Always Show) | + +### Security + +| Setting | Description | Default | +|---------|-------------|---------| +| Require password after sleep | Ask for password after sleep or screen saver begins | on | +| No password delay | Require password immediately (no grace period) | on | + +### Desktop & Stage Manager + +| Setting | Description | Default | +|---------|-------------|---------| +| Click wallpaper to show desktop | `false` = only reveals desktop while Stage Manager is active (Sonoma+ default); `true` = always reveals desktop (pre-Sonoma) | off | diff --git a/src/docs/dotfiles-shell.md b/src/docs/dotfiles-shell.md index 4f74ec8..6f98740 100644 --- a/src/docs/dotfiles-shell.md +++ b/src/docs/dotfiles-shell.md @@ -17,6 +17,8 @@ OpenBoot sets up **Zsh** with **Oh-My-Zsh** automatically: - **Theme**: A clean, informative prompt - **Aliases**: Common shortcuts for developer workflows +External plugins referenced in `.zshrc` (such as `zsh-autosuggestions` and `zsh-syntax-highlighting`) are cloned automatically during install and snapshot restore — no manual `git clone` needed. + If you already have Oh-My-Zsh installed, OpenBoot merges its plugin recommendations without overwriting your existing config. After installation, restart your terminal or run `source ~/.zshrc` to pick up the new configuration. @@ -78,19 +80,25 @@ OpenBoot applies a curated set of developer-friendly macOS settings. These are a ### What Gets Configured -**Dock** — Auto-hide, hide delay, icon size, show recent apps, position, minimize animation, show only active apps, launch animation +**System** — Show all file extensions, always-visible scrollbars, disable auto-correct/auto-capitalization, key repeat rate and delay + +**Dock** — Auto-hide, icon size, show recent apps, minimize animation + +**Finder** — View style, new window location, search scope, path/status bar, hidden files, file extensions, POSIX title, .DS_Store suppression, desktop icon visibility, and more + +**Trackpad** — Tap to click (wired + Bluetooth), three-finger drag -**Finder** — Default view style, new window location, search scope, path bar, status bar, hidden files, file extensions, POSIX path in title bar +**Keyboard** — Use F1–F12 as standard function keys -**Trackpad** — Tap to click, natural scrolling, three-finger drag +**Screenshots** — Save location, file format (PNG/JPEG/PDF/TIFF), disable window shadows -**Desktop** — Click wallpaper to show desktop +**Mission Control** — Auto-rearrange Spaces, group windows by app, hot corners (all four) -**Keyboard** — Key repeat rate, delay until repeat, press-and-hold for accents +**Menu Bar** — Per-icon visibility (Sound, Bluetooth, Wi-Fi, Battery, AirDrop, Display, Focus, Now Playing, Screen Mirroring); Sound always-show mode -**Screenshots** — File format (PNG/JPEG/PDF/TIFF), disable window shadows +**Security** — Require password after sleep, no grace period delay -**Menu Bar** — Show Sound control +**Desktop & Stage Manager** — Click wallpaper to show desktop (Stage Manager interaction mode) ### Skipping macOS Preferences