### First-Time Setup Workflow

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

A multi-step process for initial setup, including installing from a remote script, importing a GPG key, applying encrypted files, and verifying the setup.

```bash
# 1. Install from remote
ASK=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/narze/dotfiles/master/remote_install.sh) -k"
```

```bash
# 2. Retrieve GPG key and import
gpg --import private-key.asc
```

```bash
# 3. Apply encrypted files
chezmoi apply
```

```bash
# 4. Verify everything
chezmoi verify
```

--------------------------------

### Install and Start skhd Hotkey Daemon

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Installs skhd as a service and starts it to manage hotkey bindings. This script checks if skhd is available before installation and starting.

```bash
# Install and start skhd (hotkey daemon)
if command -v skhd &> /dev/null; then
  skhd --install-service
  skhd --start-service
fi
```

--------------------------------

### Install and Start Komorebi Window Manager

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Enables Komorebi for autostart and then starts the window manager service. This is intended for systems using Komorebi for window management.

```bash
# Install and start Komorebi (Windows-style window manager)
if command -v komorebic &> /dev/null; then
  komorebic enable-autostart --bar
  komorebic start --bar
fi
```

--------------------------------

### Remote Installation of Dotfiles

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Installs Chezmoi and your dotfiles remotely using a script. Recommended for first-time setup. Follow prompts for personal information and GPG key setup if needed.

```bash
# Remote installation (recommended)
ASK=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/narze/dotfiles/master/remote_install.sh) -k -v"
```

--------------------------------

### Custom Debian Profile Script Example

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

An example shell script for a custom Debian profile that installs specified packages using apt.

```bash
#!/bin/sh

# My profile custom packages
sudo apt install -y my-package1 my-package2

echo "my-profile setup complete"
```

--------------------------------

### Minimal Debian Profile Git Tools Setup

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Installs and configures necessary git tools as a final step in the `minimal` Debian profile setup.

```bash
run_once_before_05_git_tools.sh
  └─ Install git tools and configure
```

--------------------------------

### Remote Installation Script for Dotfiles

Source: https://github.com/narze/dotfiles/blob/master/README.md

Execute this script to install dotfiles remotely. It prompts for user customization on the first run and may require multiple applications for full setup. Ensure GPG keys are handled manually.

```shell
ASK=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/narze/dotfiles/master/remote_install.sh) -k -v"
```

--------------------------------

### Skip Encrypted Files During First Install with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/00-project-overview.md

Initialize chezmoi and apply dotfiles while skipping encrypted files using the `-x` flag. This is useful for initial setup on a new machine where encrypted files might not be immediately needed or configured.

```bash
chezmoi init --apply narze --keep-going -x encrypted
```

--------------------------------

### Idempotent Script Example

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Ensure scripts are safe to run multiple times by checking if a command already exists before installation.

```bash
#!/bin/sh

# Good: Check if already installed
if ! command -v myapp >/dev/null; then
  sudo apt install -y myapp
fi
```

```bash
# Bad: Always try to install (may fail if already installed)
sudo apt install -y myapp
```

--------------------------------

### Debian Setup Profile Structure

Source: https://github.com/narze/dotfiles/blob/master/README.md

Illustrates the directory structure for Debian setup profiles, including run-once scripts and per-apply scripts. Profiles are automatically discovered and executed based on the active configuration.

```directory
chezmoi/.chezmoiscripts/debian/        # run-once installs
  run_once_before_00_install_packages.sh   # base (every profile)
  run_once_before_01_install_mise.sh       # base (every profile)
  homelab/run_once_before_50_packages.sh   # only when profile=homelab
  ai-agent/run_once_before_50_packages.sh  # only when profile=ai-agent

scripts/linux-debian/<profile>/        # optional per-apply scripts
```

--------------------------------

### Re-run Chezmoi Apply

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

If Homebrew installation fails, skip packages with SKIP_BREW=1 and then re-run the main apply command to complete the setup.

```bash
SKIP_BREW=1 chezmoi apply
```

```bash
chezmoi apply
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Run this command to ensure the Xcode Command Line Tools are installed, which is often a prerequisite for Homebrew.

```bash
xcode-select --install
```

--------------------------------

### Skip Encrypted Files during Chezmoi Install

Source: https://github.com/narze/dotfiles/blob/master/CLAUDE.md

When installing fresh without a GPG key, use the '-x encrypted' flag to skip encrypted files. This prevents errors during initial setup.

```bash
chezmoi init -x encrypted
```

--------------------------------

### Verifying Plugin Installation Paths

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Commands to list installed plugins for Zellij and Hammerspoon to verify installation paths.

```bash
# Zellij plugins
ls ~/.config/zellij/plugins/

# Hammerspoon spoons
ls ~/.hammerspoon/Spoons/
```

--------------------------------

### Skip Package Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Applies dotfile changes while skipping package installations. This example shows skipping Homebrew on macOS.

```bash
SKIP_BREW=1 chezmoi apply     # macOS: skip Homebrew
```

--------------------------------

### Local Installation Script

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

Execute the local installation script for Chezmoi. This script handles environment detection, Chezmoi installation if needed, and initialization.

```bash
sh /path/to/dotfiles/install.sh
```

--------------------------------

### Cross-Platform Installation Paths

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Lists common installation paths for Tmux and Zellij plugins across different operating systems.

```shell
~/.tmux.conf                             # Tmux main config
~/.tmux.conf.local                       # Tmux local overrides
~/.config/zellij/plugins/zjstatus.wasm   # Zellij status bar
~/.config/zellij/plugins/zellij-autolock.wasm  # Zellij autolock
~/.local/share/git-worktree-runner/      # Git worktree helper
```

--------------------------------

### Fix Failed Installation Workflow

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

A sequence of commands to address failed installations. It involves continuing application despite errors, checking the status, manually fixing issues, verifying the setup, and re-running the application.

```bash
# Keep applying despite errors
chezmoi apply -k
```

```bash
# Check what failed
chezmoi status
```

```bash
# Fix manually, then verify
chezmoi verify
```

```bash
# Re-run
chezmoi apply
```

--------------------------------

### Install Mise Runtime Manager

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Installs mise, a runtime version manager for various programming languages. Run this script to set up mise.

```bash
curl https://mise.jdx.dev/install.sh | sh
```

--------------------------------

### Install and Configure Kitty on Apple Silicon

Source: https://github.com/narze/dotfiles/blob/master/README.md

This snippet outlines the steps to build and install the Kitty terminal emulator from source on Apple Silicon, including replacing the default CLI link.

```shell
ghq get -l kovidgoyal/kitty
/opt/homebrew/bin/python3 setup.py kitty.app # Needs python3 from brew
cp -r kitty.app /Applications/kitty.app

# Replace CLI
rm /opt/homebrew/bin/kitty
ln -s $PWD/kitty/launcher/kitty /opt/homebrew/bin/kitty
```

--------------------------------

### Apply Chezmoi Configurations

Source: https://github.com/narze/dotfiles/blob/master/README.md

Run this command after the initial installation to ensure all configurations are applied correctly. Repeat until no further changes are needed.

```shell
chezmoi -k apply
```

--------------------------------

### Homelab Profile Package Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Installs homelab-specific tools such as Docker and Kubernetes CLI, extending the base `minimal` profile.

```bash
debian/homelab/run_once_before_50_packages.sh
  └─ Install homelab tools (docker, k8s, etc.)
```

--------------------------------

### Example Managed SSH Configuration

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/08-git-integration.md

An example of a managed SSH configuration file that can be included in the main SSH config.

```bash
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa
    AddKeysToAgent yes

Host *.example.com
    User myuser
    IdentityFile ~/.ssh/example_key
    Port 2222
```

--------------------------------

### Start Karabiner Elements Remapping Daemon

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Restarts the Karabiner Elements service to apply key remapping configurations. Ensure Karabiner Elements is installed.

```bash
# Start Karabiner Elements key remapping daemon
brew services restart goku
```

--------------------------------

### Minimal Debian Profile Mise Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Installs or upgrades the `mise` runtime version manager as part of the `minimal` Debian profile setup.

```bash
run_once_before_01_install_mise.sh
  └─ Install/upgrade mise
```

--------------------------------

### Install Delta Diff Viewer

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/08-git-integration.md

Provides package manager commands for installing the Delta syntax-highlighting diff viewer on macOS and Debian/Ubuntu systems.

```bash
# via Homebrew (macOS)
brew install git-delta

# via apt (Debian/Ubuntu)
sudo apt install git-delta

```

--------------------------------

### Check Chezmoi Version

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Displays the currently installed version of chezmoi.

```bash
chezmoi version
```

--------------------------------

### Zsh Environment Setup for Agents

Source: https://github.com/narze/dotfiles/blob/master/CLAUDE.md

This zsh environment file activates 'mise' for specific agents like Claude Code, Cursor, and OpenCode. Ensure 'mise' is installed and configured.

```zsh
export MISE_DATA_DIR="$HOME/.local/share/mise"
export PATH="$HOME/.local/bin:$PATH"

# Activate mise for Claude Code / Cursor / OpenCode agents
if command -v mise &> /dev/null; then
  eval "$(mise activate zsh)"
fi
```

--------------------------------

### macOS Installation Paths

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Specifies default installation paths for Hammerspoon and keyboard layouts on macOS.

```shell
~/.hammerspoon/stackline/               # Stackline automation
~/.hammerspoon/Spoons/FocusHighlight.spoon/
~/.hammerspoon/Spoons/MouseFollowsFocus.spoon/
~/.hammerspoon/Spoons/PaperWM.spoon/
~/.hammerspoon/Spoons/WarpMouse.spoon/
~/Library/Keyboard Layouts/Manoonchai.bundle/
```

--------------------------------

### Install ARM and x86 Homebrew on Apple Silicon

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Installs both the native ARM version of Homebrew (in /opt/homebrew) and the x86 version via Rosetta 2 (in /usr/local) on Apple Silicon Macs. This allows compatibility with both architectures.

```bash
# Install ARM version (native, in /opt/homebrew)
arch -arm64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install x86 version (via Rosetta, in /usr/local)
arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Master Script Router Example

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/03-scripts-reference.md

This script executes after all files are applied and routes to OS-specific directories. It determines the OS and profile, then runs all OS-specific scripts and optionally profile-specific scripts.

```bash
#!/bin/bash

SCRIPTS_DIR={{ .chezmoi.workingTree }}/scripts

# Determine OS and profile
{{- if eq .chezmoi.os "darwin" }}
  OS=darwin
{{- else if and (eq .chezmoi.os "linux") (eq .chezmoi.osRelease.id "ubuntu") }}
  OS=linux-ubuntu
{{- else if and (eq .chezmoi.os "linux") (eq .chezmoi.osRelease.id "debian") }}
  OS=linux-debian
  PROFILE={{ .debian_profile | quote }}
{{- end }}

# Run all OS-specific scripts
for script in $SCRIPTS_DIR/$OS/*.*sh
do
  echo $script
  bash $script || true  # Ignore errors, continue to next
done

# Run profile-specific scripts (Debian only)
if [ -n "${PROFILE:-}" ] && [ -d "$SCRIPTS_DIR/$OS/$PROFILE" ]; then
  for script in $SCRIPTS_DIR/$OS/$PROFILE/*.*sh
  do
    echo $script
    bash $script || true
  done
fi

```

--------------------------------

### Re-run Installation Scripts with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/00-project-overview.md

Force re-execution of installation scripts by clearing their state. This is done by deleting the script state bucket and then applying the dotfiles again.

```bash
chezmoi state delete-bucket --bucket=scriptState
chezmoi apply
# Clears hash of ran scripts, forcing re-execution
```

--------------------------------

### Test Profile Setup Before Deployment

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

A workflow to test profile configurations before applying them. It involves initializing Chezmoi for a target profile, previewing changes, performing a dry-run with verbose output, and finally applying the changes.

```bash
# Change to target profile
ASK=1 chezmoi init
```

```bash
# Preview all changes
chezmoi diff
```

```bash
# Dry-run with verbose output
chezmoi apply -v
```

```bash
# When confident, actually apply
chezmoi apply
```

--------------------------------

### Coder Environment Setup

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

This script segment configures Chezmoi for Coder environments, including symlinking dotfiles, installing zsh if necessary, and clearing script state for idempotency.

```bash
if [ -n "${CODER:-}" ]; then
  # Symlink dotfiles to Coder's persistent volume
  ln -sf ~/.config/coderv2/dotfiles ~/.local/share/chezmoi
  
  # Install zsh if missing (Coder workspaces reset system packages)
  if ! command -v zsh >/dev/null; then
    sudo apt-get install -y zsh
    sudo chsh -s "$(which zsh)"
  fi
  
  # Clear script state to force re-run on workspace restart
  if [ -f ~/.local/bin/chezmoi ]; then
    ~/.local/bin/chezmoi state delete-bucket --bucket=scriptState
  fi
fi
```

--------------------------------

### Documenting Profile Scripts

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Add comments to your scripts to explain their purpose, installation targets, and intended use cases.

```bash
#!/bin/sh

# AI Agent Profile Setup
# Installs Claude Code CLI, OpenCode, and ML development tools
# Used for: LLM development, AI agent testing

sudo apt install -y ...
```

--------------------------------

### Apply Dotfiles with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Applies managed dotfiles to the current machine. Ensure chezmoi is installed and configured.

```bash
# Apply dotfiles to the current machine
chezmoi apply
```

--------------------------------

### Set Encryption Passphrase and Apply

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Initializes Chezmoi to set an encryption passphrase for sensitive files. Use '-x encrypted' to skip encrypted files during the first install if GPG key is not yet set up.

```bash
# Set encryption passphrase
SETPASS=1 chezmoi init
```

```bash
# Skip encrypted files on first install (before GPG key)
chezmoi apply -x encrypted
```

--------------------------------

### AI Agent Profile Package Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Installs AI/LLM development tools like Claude Code CLI and OpenCode CLI, extending the base `minimal` profile.

```bash
debian/ai-agent/run_once_before_50_packages.sh
  └─ Install Claude Code CLI, OpenCode CLI, LLM tools
```

--------------------------------

### Template Variables in Regular Config Files

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Demonstrates how to use template variables like hostname, email, and OS within regular configuration files that have a .tmpl suffix. Includes examples of both user-defined and built-in chezmoi variables.

```bash
#!/bin/bash
# Script: ~/.scripts/setup.sh.tmpl

# Template variables available:
HOSTNAME="{{ .hostname }}"
EMAIL="{{ .email }}"
DEBIAN_PROFILE="{{ .debian_profile }}"

# Built-in variables:
OS="{{ .chezmoi.os }}"
HOME_DIR="{{ .chezmoi.homeDir }}"
```

--------------------------------

### Install Rosetta 2 on Apple Silicon Macs

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Installs the Rosetta 2 emulation layer to ensure compatibility with x86 binaries on ARM-based Macs. This command should be run once.

```bash
softwareupdate --install-rosetta --agree-to-license
```

--------------------------------

### Apply Chezmoi Configuration with Environment Variables

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Control the apply process using environment variables. SKIP_BREW=1 skips Homebrew installation on macOS, and SCRIPTS_START_AT=50 skips scripts numbered below 50.

```bash
SKIP_BREW=1 chezmoi apply
```

```bash
SCRIPTS_START_AT=50 chezmoi apply
```

```bash
SKIP_BREW=1 chezmoi apply
# Apply everything except Homebrew packages
```

--------------------------------

### Set Computer Name and Hostname

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/04-configuration-files.md

Configures the macOS computer name, hostname, and Bonjour hostname using template variables. This script runs once after initial setup.

```zsh
chezmoi/.chezmoiscripts/run_once_after_darwin_99-macos-name.zsh.tmpl
```

--------------------------------

### Dual Homebrew Installation and Configuration for Apple Silicon

Source: https://github.com/narze/dotfiles/blob/master/README.md

Installs both ARM64 and x86 versions of Homebrew and configures the .zshrc file to use the appropriate brew binary based on the system architecture.

```shell
# Install both versions
arch -arm64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# .zshrc
if [ "$(uname -m)" == "arm64" ]; then
  # Use arm64 brew, with fallback to x86 brew
  if [ -f /opt/homebrew/bin/brew ]; then
    export PATH="/usr/local/bin${PATH+:$PATH}";
    eval $(/opt/homebrew/bin/brew shellenv)
  fi
else
  # Use x86 brew, with fallback to arm64 brew
  if [ -f /usr/local/bin/brew ]; then
    export PATH="/opt/homebrew/bin${PATH+:$PATH}";
    eval $(/usr/local/bin/brew shellenv)
  fi
fi
```

--------------------------------

### Configure Git Repository Resource

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Configure a git repository resource, specifying its URL and refresh period. This example demonstrates cloning or updating the repository on each apply.

```toml
[.local/share/repo]
    type = "git-repo"
    url = "https://github.com/user/repo.git"
    exact = true
    refreshPeriod = "48h"
```

--------------------------------

### List All Managed Files

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

The 'chezmoi list' command displays all files that Chezmoi will manage and apply. This is useful for getting an overview of your dotfile configuration.

```bash
chezmoi list
```

--------------------------------

### Minimal Debian Profile Package Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

The `minimal` Debian profile installs essential packages like `zsh`, `git`, `curl`, `unzip`, and `mise` using `apt`.

```bash
run_once_before_00_install_packages.sh
  └─ apt update
  └─ apt install: unzip zsh curl git
```

--------------------------------

### Zsh Environment Setup for Agents

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Activates mise for specific agents like Claude Code, Cursor, and OpenCode by configuring the zsh environment.

```bash
# chezmoi/dot_zshenv
# Activates mise for Claude Code / Cursor / OpenCode agents
```

--------------------------------

### Apply Dotfiles Configuration

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Applies all managed dotfiles and scripts. Use '-i files' to apply only files, skipping installation scripts. 'chezmoi diff' previews changes.

```bash
# After initialization, apply all dotfiles and scripts
chezmoi apply
```

```bash
# Or apply files only (skip installation scripts)
chezmoi apply -i files
```

```bash
# Preview what would change
chezmoi diff
```

--------------------------------

### Initialize New Machine with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/00-project-overview.md

Use `chezmoi init` to set up dotfiles on a new machine. It can prompt for all variables, use defaults interactively, or be configured programmatically with specific data.

```bash
chezmoi init                    # Prompt for all variables
# OR
ASK=1 chezmoi init             # Interactive with defaults
# OR
chezmoi init --data name=X email=Y ...  # Programmatic
```

--------------------------------

### Initialize Chezmoi with Prompts

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Initializes chezmoi and prompts the user for details like name, hostname, and email. Set ASK=1 to enable interactive prompts.

```bash
# Initialize with prompts for name/hostname/email/profile
ASK=1 chezmoi init
```

--------------------------------

### Initialize Chezmoi and Select Profile

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Command to initialize chezmoi and select a custom profile when prompted.

```bash
ASK=1 chezmoi init
# Choose "my-profile" when prompted
```

--------------------------------

### Initialize Chezmoi with Debian Profile Prompt

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Run `chezmoi init` on a Debian system to be prompted for the desired Debian profile. The selection is cached in `~/.config/chezmoi/chezmoi.toml`.

```bash
chezmoi init
# Prompts: "Debian profile (minimal/homelab/ai-agent)"
```

--------------------------------

### Usage of Chezmoi Utility Script

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/03-scripts-reference.md

This script demonstrates how to source the utility script and use the defined ANSI color codes for formatted output. It shows an example of printing a message with a green color code.

```bash
#!/bin/sh
source /tmp/chezmoi-utils.sh

printf "${green}[10 - macOS] ${reset}"
echo "Install common macOS packages"
```

--------------------------------

### Makefile: Display Help

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Use this command to see all available Makefile targets and their descriptions.

```bash
make help
```

--------------------------------

### Initialize Chezmoi with Environment Variables

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Set environment variables to control the initialization process. ASK=1 prompts for template variables, SETPASS=1 prompts only for the encryption passphrase, and CM_hostname pre-sets the hostname.

```bash
ASK=1 chezmoi init
```

```bash
SETPASS=1 chezmoi init
```

```bash
CM_hostname="my-machine" chezmoi init
```

```bash
ASK=1 SETPASS=1 chezmoi init
# Prompt for all variables and encryption passphrase
```

--------------------------------

### Makefile: Initialize Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

This command initializes Chezmoi, equivalent to running `chezmoi init`.

```bash
make bootstrap
```

--------------------------------

### Skip Early Scripts

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/04-configuration-files.md

Skips execution of runtime scripts starting from a specified number. Useful for controlling the order or skipping initial setup scripts.

```bash
SCRIPTS_START_AT=50
```

--------------------------------

### Conditional Script Skipping with Environment Variables

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Control script execution during 'chezmoi apply' using environment variables to skip specific installations or start at a certain script number.

```bash
SKIP_BREW=1 chezmoi apply
# Skip all brew installation in macOS scripts
```

```bash
SCRIPTS_START_AT=10 chezmoi apply
# Skip scripts numbered < 10 (script order by filename)
```

--------------------------------

### Control Script Execution with Environment Variables

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/03-scripts-reference.md

Use environment variables to conditionally skip scripts or start execution from a specific script number. `SKIP_BREW` prevents Homebrew installations, and `SCRIPTS_START_AT` skips scripts before the specified number.

```bash
SKIP_BREW=1 chezmoi apply  # Skip Homebrew
SCRIPTS_START_AT=50 chezmoi apply  # Skip early scripts
```

--------------------------------

### Preview and Force Apply Changes

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Before applying changes, it is recommended to preview them using `chezmoi diff`. If you need to forcefully apply changes and overwrite any local modifications, use the `--force` flag with `chezmoi apply`.

```bash
chezmoi diff

# Force apply (overwrite local changes)
chezmoi apply --force
```

--------------------------------

### Configuring Resource Download URLs

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Illustrates how to specify a stable version or the latest release for external resources.

```toml
# Specific version (recommended for stability)
url = "https://github.com/.../releases/download/v0.17.0/file.wasm"

# Latest release (may change unexpectedly)
url = "https://github.com/.../releases/download/latest/file.wasm"
```

--------------------------------

### Skip Homebrew Installation

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/04-configuration-files.md

When set to 1, this environment variable prevents chezmoi from attempting to install Homebrew packages during `chezmoi apply`.

```bash
SKIP_BREW=1 chezmoi apply
```

--------------------------------

### Programmatic Chezmoi Initialization with Force Apply

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

Initialize Chezmoi non-interactively and force apply changes, overwriting existing files without confirmation using the `--force` flag.

```bash
chezmoi init --apply \
  --data name="John Doe" \
  --force
```

--------------------------------

### Initialize Chezmoi Configuration

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Re-runs the initialization process for chezmoi. Use this to change settings like the Debian profile.

```bash
# Re-run initialization (e.g. to change Debian profile)
chezmoi init
```

--------------------------------

### Project Structure

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/00-project-overview.md

Illustrates the directory layout of the dotfiles repository, highlighting key configuration and script directories.

```tree
dotfiles/
├── chezmoi/                          # Chezmoi source root (set in .chezmoiroot)
│   ├── .chezmoi.yaml.tmpl            # Template variables and Debian profile prompt
│   ├── .chezmoiexternal.toml         # External downloads (plugins, fonts, repos)
│   ├── .chezmoiignore                # Conditional per-OS file exclusions
│   ├── .chezmoiscripts/              # Installation and setup scripts
│   ├── private_dot_config/           # Encrypted managed configs
│   ├── dot_*                         # OS-managed dotfiles (templates + regular)
│   └── executable_*                  # Executable dotfiles
├── scripts/                          # Per-OS runtime scripts (post-apply)
│   ├── darwin/                       # macOS-specific
│   ├── linux-debian/                 # Debian Linux with profiles
│   └── linux-ubuntu/                 # Ubuntu Linux
├── install.sh                        # Local installation entrypoint
├── remote_install.sh                 # Remote curl installation
├── Makefile                          # Command shortcuts
└── .mise/                            # Mise tool configuration

```

--------------------------------

### Preview Changes Before Applying

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/README.md

Shows a diff of the changes that would be applied to the dotfiles. Can be used for all files or specific ones.

```bash
chezmoi diff
chezmoi diff ~/.zshrc
```

--------------------------------

### Interactive User Prompts with Chezmoi Templates

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Prompt users for input during `chezmoi init`. `promptString` prompts every time, while `promptStringOnce` caches the value.

```go-template
{{ promptString "Prompt Text" "default_value" }}
// Interactive prompt for string input during chezmoi init
// Returns user input or default if user presses Enter

{{ promptStringOnce . "key_name" "Prompt Text" "default_value" }}
// Prompts only once (first init); value cached in config
// Subsequent inits use cached value unless chezmoi init is run again
// Used for: debian_profile (should not change on every apply)

// Examples:
{{ $name = promptString "Full Name" "Manassarn Manoonchai" }}
{{ $debian_profile = promptStringOnce . "debian_profile" "Debian profile" "minimal" }}
```

--------------------------------

### Minimal Debian Profile Shell Change

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Changes the default user shell to `zsh` after it has been installed in the `minimal` Debian profile.

```bash
run_once_before_02_change_shell.sh
  └─ Change default shell to zsh
```

--------------------------------

### Preview Dotfile Changes with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Shows a preview of what changes would be made when applying dotfiles. Useful for verifying configurations before applying.

```bash
# Preview what would change
chezmoi diff
```

--------------------------------

### Change Profile and Re-run Scripts

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Initialize Chezmoi with `ASK=1` to select a new profile. Subsequent `chezmoi apply` commands will run scripts for the new profile alongside base scripts, ignoring the old profile's scripts.

```bash
ASK=1 chezmoi init
# Select new profile

chezmoi apply
# New profile's scripts run alongside base
# (Old profile's scripts remain ignored)
```

--------------------------------

### Chezmoi Template Variables

Source: https://github.com/narze/dotfiles/blob/master/AGENTS.md

Demonstrates common template variables available in chezmoi for OS-specific configurations and user data.

```go
# {{ .chezmoi.os }} — darwin, linux, windows
# {{ .chezmoi.osRelease.id }} — debian, ubuntu (Linux only)
# {{ .debian_profile }} — active Debian profile
# {{ .hostname }}, {{ .name }}, {{ .email }}, {{ .github_user }}
# {{ .flags.delta_is_not_installed }}, {{ .flags.gh_is_installed }}, {{ .flags.is_codespace }}
```

--------------------------------

### Chezmoi GPG Encryption Configuration

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

Example configuration for GPG symmetric encryption in Chezmoi. Ensures sensitive files are protected.

```yaml
encryption: gpg
gpg:
  symmetric: true
  args: ["--batch", "--passphrase", "{{ $passphrase }}", "--no-symkey-cache", "--quiet"]

```

--------------------------------

### Download Sketchybar App Font Script

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/03-scripts-reference.md

Downloads the latest sketchybar-app-font from GitHub and installs it to ~/Library/Fonts. It checks a version file to ensure idempotency.

```bash
# Get latest release from GitHub API
LATEST_VERSION=$(curl -s https://api.github.com/repos/kvndrsslr/sketchybar-app-font/releases/latest | grep '"tag_name":' | cut -d '"' -f 4)

# Check if version has changed
if [ -f "$VERSION_FILE" ]; then
  STORED_VERSION=$(<"$VERSION_FILE")
  if [ "$STORED_VERSION" = "$LATEST_VERSION" ]; then
    exit 0  # Already latest
  fi
fi

# Download and copy .ttf files to Fonts directory
find "$TARGET_DIR" -name "*.ttf" -exec cp {} "$FONTS_DIR" \;
```

--------------------------------

### Set Initial Key Repeat Delay

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Configures the initial delay before key repetition starts. Lower values mean faster repeat.

```bash
defaults write NSGlobalDomain InitialKeyRepeat
```

--------------------------------

### Apply macOS Preferences with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Demonstrates commands to preview preference changes using `chezmoi diff`, apply them with `chezmoi apply`, or run a specific preference script directly using `bash`.

```bash
# Preview what would change:
chezmoi diff ~/.chezmoi_scripts/98-macos-preferences.sh
```

```bash
# Apply and run immediately:
chezmoi apply
```

```bash
# Or run the script directly:
bash chezmoi/.chezmoiscripts/run_once_after_darwin_98_macos-preferences.sh.tmpl
```

--------------------------------

### Skip Specific Directories

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

This command allows you to skip specific directories, including their contents, during the Chezmoi apply process. The example skips the ~/.config/nvim directory.

```bash
chezmoi apply --exclude "^\.config/nvim"
```

--------------------------------

### Software Update Preferences

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Manage Software Update settings, including check frequency, automatic checks, background downloads, and automatic installation of security updates.

```bash
defaults write com.apple.SoftwareUpdate ScheduleFrequency
```

```bash
defaults write com.apple.SoftwareUpdate AutomaticCheckEnabled
```

```bash
defaults write com.apple.SoftwareUpdate AutomaticDownload
```

```bash
defaults write /Library/Preferences/com.apple.alf globalstate
```

--------------------------------

### Download Tmux Main Configuration

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Downloads the main tmux configuration file from a GitHub repository. This file contains keybindings and settings.

```toml
[.tmux.conf]
    type = "file"
    url = "https://raw.githubusercontent.com/narze/.tmux/master/.tmux.conf"
    refreshPeriod = "168h"
```

--------------------------------

### Conditional Delta Integration for Git

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/08-git-integration.md

This Go template conditionally enables Delta, a syntax-highlighting diff viewer, for Git pager commands. It is only applied if Delta is installed on the system.

```ini
{{ if not .flags.delta_is_not_installed }}
[pager]
    diff = delta
    log = delta
    blame = delta
    show = delta

[delta]
    line-numbers = true
    syntax-theme = Monokai Extended
    plus-style = syntax "#004620"
    minus-style = syntax "#3f0001"
    features = decorations
{{ end }}

```

--------------------------------

### Chezmoi Core Configuration (.chezmoi.yaml.tmpl)

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/04-configuration-files.md

Defines template variables, handles conditional initialization via environment variables or prompts, performs runtime detection, and configures encryption settings. Use this file to set up default values for personal information and system configurations.

```yaml
# Personal information variables (with defaults or env-var overrides)
$name = "Manassarn Manoonchai"
$email = "manassarn@gmail.com"
$github_user = "narze"
$computer_name = env("CM_computer_name") ?? "narze-computer-name"
$hostname = env("CM_hostname") ?? "narze"
$nas_mount_path = env("NAS_PATH") ?? "~/mnt/nas"
$debian_profile = "minimal"  # For Debian systems only
$passphrase = "change me with 'SETPASS=1 chezmoi init'"

# Conditional prompts
if env("ASK"):
  $name = promptString("Full Name", $name)
  $email = promptString("Email", $email)
  $github_user = promptString("GitHub Username", $github_user)
  $computer_name = promptString("Computer Name", $computer_name)
  $hostname = promptString("Hostname", $hostname)

if env("SETPASS"):
  $passphrase = promptString("Encryption Passphrase", $passphrase)

if os == "linux" && distro == "debian":
  $debian_profile = promptStringOnce("debian_profile", "Debian profile", "minimal")

# Runtime detection
$delta_is_not_installed = !(contains("delta", shell("command -v delta || true")))
$gh_is_installed = contains("gh", shell("command -v gh || true"))
$is_codespace = !!env("CODESPACES")

# Encryption configuration
encryption: gpg
gpg:
  symmetric: true
  args: ["--batch", "--passphrase", $passphrase, "--no-symkey-cache", "--quiet"]

# Export computed variables
data:
  name: $name
  email: $email
  github_user: $github_user
  computer_name: $computer_name
  hostname: $hostname
  nas_mount_path: $nas_mount_path
  debian_profile: $debian_profile
  passphrase: $passphrase
  flags:
    delta_is_not_installed: $delta_is_not_installed
    gh_is_installed: $gh_is_installed
    is_codespace: $is_codespace

```

--------------------------------

### Non-Interactive Initialization

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Initializes dotfiles programmatically without interactive prompts. Provide data via --data flags.

```bash
chezmoi init --data name="John Doe" --data email="john@example.com"
```

--------------------------------

### Platform-Specific Exclusions in .chezmoiignore

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Provides examples of using template conditionals within a .chezmoiignore file to exclude directories and files based on the operating system. This allows for OS-specific dotfile management.

```go
{{ if ne .chezmoi.os "darwin" }}
  // Exclude on non-macOS (Linux, Windows):
  .config/karabiner
  .config/kitty
  .config/sketchybar
  .local/macos
  .duti
  .hammerspoon
  .mackup
  .mackup.cfg
  .skhdrc
  .yabai*
  obsidian
{{ end }}

{{ if ne .chezmoi.os "linux" }}
  // Exclude on non-Linux (macOS, Windows):
  .local/linux
  .hushlogin
  .local/share/fonts
{{ end }}

{{ if ne .chezmoi.os "windows" }}
  // Exclude on non-Windows:
  Documents
{{ else }}
  // Exclude on Windows:
  .bash_aliases
  .inputrc
  .oh-my-zsh
  .p10k.zsh
  .ssh/authorized_keys
  .ssh/id_rsa
  .ssh/id_rsa.pub
  .tmux.conf
  .vim
  .vimrc
  .zshrc
{{ end }}
```

--------------------------------

### Using Environment Variables for Chezmoi Init

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Pre-set environment variables before running 'chezmoi init' to skip interactive prompts for configuration values.

```bash
# Set values before chezmoi init to skip prompts
CM_computer_name="my-laptop" chezmoi init
```

```bash
NAS_PATH="/mnt/custom/nas" chezmoi init
```

```bash
# Combine multiple:
CM_computer_name="m1-pro" CM_hostname="m1-pro" chezmoi init
```

--------------------------------

### Configure Hammerspoon PaperWM Spoon Git Repository

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Manage the PaperWM Hammerspoon Spoon by cloning its Git repository. Set to refresh weekly.

```toml
[basedir]
    type = "git-repo"
    url = "https://github.com/mogenson/PaperWM.spoon"
    exact = true
    refreshPeriod = "168h"
```

--------------------------------

### Re-compute Templates with Chezmoi Init

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Running 'chezmoi init' re-prompts for all variables if they are set to ASK=1, or uses existing values, effectively re-computing templates.

```bash
chezmoi init
# Re-prompts for all variables (if ASK=1) or uses existing values
```

--------------------------------

### Configure Shell for Dual Homebrew on Apple Silicon

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/06-macos-setup.md

Configures the shell environment variables (PATH and others) to prioritize the correct Homebrew installation based on the detected architecture (ARM or x86_64). This script should be added to your shell configuration file (e.g., .zshrc).

```bash
if [ "$(uname -m)" == "arm64" ]; then
  # Prefer ARM, fallback to x86
  if [ -f /opt/homebrew/bin/brew ]; then
    export PATH="/opt/homebrew/bin:$PATH"
  fi
  export PATH="/usr/local/bin${PATH+:$PATH}"
  eval $(/opt/homebrew/bin/brew shellenv)
elif [ "$(uname -m)" == "x86_64" ]; then
  # Native x86 (running under Rosetta)
  if [ -f /usr/local/bin/brew ]; then
    export PATH="/usr/local/bin:$PATH"
  fi
  export PATH="/opt/homebrew/bin${PATH+:$PATH}"
  eval $(/usr/local/bin/brew shellenv)
fi
```

--------------------------------

### View Raw Template File with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/02-chezmoi-templates.md

Use 'chezmoi cat' to display the raw content of a template file before it is rendered by chezmoi.

```bash
chezmoi cat ~/.zshrc.tmpl
# Shows raw template file (before rendering)
```

--------------------------------

### Configure Hammerspoon WarpMouse Spoon Git Repository

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Manage the WarpMouse Hammerspoon Spoon by cloning its Git repository. Set to refresh weekly.

```toml
[basedir]
    type = "git-repo"
    url = "https://github.com/mogenson/WarpMouse.spoon"
    exact = true
    refreshPeriod = "168h"
```

--------------------------------

### Show Chezmoi Source Directory

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Outputs the path to the chezmoi source directory, typically ~/.local/share/chezmoi.

```bash
chezmoi source-path
```

--------------------------------

### Programmatic Chezmoi Initialization

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

Initialize Chezmoi non-interactively by providing data via `--data` flags. Uses provided values and defaults for unspecified variables.

```bash
chezmoi init \
  --data name="John Doe" \
  --data email="john@example.com" \
  --data github_user="johndoe" \
  --data hostname="john-laptop"
```

--------------------------------

### Makefile: Apply Dotfiles

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Applies all managed dotfiles to the home directory. This is equivalent to `chezmoi apply`.

```bash
make apply
```

--------------------------------

### Re-prompt for Debian Profile

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Use `ASK=1 chezmoi init` to force a re-prompt for the Debian profile selection, even if a profile has already been chosen and cached.

```bash
ASK=1 chezmoi init
# Re-prompts for debian_profile, updates config
```

--------------------------------

### Chezmoi Profile Troubleshooting: Check Current Profile

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/05-debian-profiles.md

Verify the currently applied Debian profile using `chezmoi data` and `jq`. If incorrect, re-initialize with `chezmoi init`.

```bash
# Check current profile
chezmoi data | jq .debian_profile

# If wrong, change it:
ASK=1 chezmoi init

# Then apply
chezmoi apply
```

--------------------------------

### Authenticate with GitHub CLI

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/08-git-integration.md

Use `gh auth login` for initial authentication and `gh auth status` to verify. It supports SSH keys for secure access.

```bash
# Authenticate (first time)
gh auth login

# Choose: GitHub.com
# Choose: SSH (recommended)
# Generate new SSH key (or use existing)

# Verify authentication
gh auth status
```

--------------------------------

### Preview Dotfile Changes with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/CLAUDE.md

This command shows a preview of what changes would be made when applying dotfiles, without actually modifying any files. Useful for verification.

```bash
chezmoi diff
```

--------------------------------

### Troubleshooting External Resource Downloads

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Provides commands to check the external resource cache, verify URLs, and force re-downloads.

```bash
# Check external resource cache
ls -la ~/.cache/chezmoi/external/

# Verify URL is accessible
curl -I https://github.com/user/repo/archive/main.zip

# Force re-download by clearing cache
rm -rf ~/.cache/chezmoi/external/<resource-name>

# Try apply again
chezmoi apply
```

--------------------------------

### Apply Dotfiles with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/00-project-overview.md

Apply dotfiles using `chezmoi apply`. This command can apply all files and run scripts, or selectively apply only files while skipping scripts. `chezmoi diff` can preview changes before applying.

```bash
chezmoi apply                   # Apply all files and run scripts
chezmoi apply -i files         # Files only, skip scripts
chezmoi diff                    # Preview changes
```

--------------------------------

### Manage Git Configuration with Chezmoi

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/08-git-integration.md

Preview, edit, and apply changes to your global git configuration file using Chezmoi.

```bash
# Preview current git config
git config --list

# Edit via Chezmoi
chezmoi edit ~/.gitconfig

# Or edit directly
vim ~/.gitconfig

# Apply changes
chezmoi apply
```

--------------------------------

### Configure Hammerspoon FocusHighlight Spoon Archive

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/07-external-resources.md

Download and manage the FocusHighlight Hammerspoon Spoon from a TAR.GZ archive. Set to refresh every 90 days.

```toml
[basedir]
    type = "archive"
    url = "https://github.com/dtinth/FocusHighlight.spoon/archive/refs/tags/v0.1.tar.gz"
    exact = true
    stripComponents = 1
    refreshPeriod = "2160h"
```

--------------------------------

### Add New Managed File Workflow

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/09-command-reference.md

Copies a local file (e.g., ~/.bashrc) into the Chezmoi source directory, making it a managed dotfile.

```bash
chezmoi add ~/.bashrc
# Copies ~/.bashrc to chezmoi source as dot_bashrc
```

--------------------------------

### Chezmoi Script Execution Order

Source: https://github.com/narze/dotfiles/blob/master/CLAUDE.md

Illustrates the naming conventions for script execution order in chezmoi. Scripts are run based on their prefixes and OS-specific directories.

```bash
run_once_before_*
```

```bash
run_once_after_*
```

```bash
run_before_*
```

```bash
run_after_*
```

```bash
run_after_00-run-scripts-by-os.sh.tmpl
```

--------------------------------

### Skip File Application, Run Scripts Only

Source: https://github.com/narze/dotfiles/blob/master/_autodocs/01-installation.md

Use this command to apply only scripts and skip the application of any files. This is useful when you want to test script execution without modifying your configuration files.

```bash
chezmoi apply --exclude files
```