### Example Script Naming Convention

Source: https://github.com/projectbluefin/finpilot/blob/main/build/README.md

Illustrates the naming convention for build scripts, including a base system script and an example for installing third-party software.

```bash
# 10-build.sh - Base system (already exists)
# 20-drivers.sh - Hardware drivers  
# 30-development.sh - Development tools
# 40-gaming.sh - Gaming software
# 50-cleanup.sh - Final cleanup tasks
```

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

### Install Packages and Enable Services (Bash)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

A basic build script example that installs packages using dnf5 and enables the podman socket service. Ensure packages are available in the image's repositories.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Install packages
dnf5 install -y vim git htop neovim

# Enable services
systemctl enable podman.socket

# Download binaries
curl -L https://example.com/tool -o /usr/local/bin/tool
chmod +x /usr/local/bin/tool
```

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

### Install Fonts via Brewfile Shortcut

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

An example of a Brewfile shortcut command, grouped under 'Apps', to install fonts using a specified Brewfile.

```just
[group('Apps')]
install-fonts:
    brew bundle --file /usr/share/ublue-os/homebrew/fonts.Brewfile
```

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

### Flatpak Preinstall Configuration Example

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/flatpaks/README.md

Defines Flatpak applications to be installed on first boot. Use the `Branch` key to specify the desired release branch, commonly 'stable'.

```ini
[Flatpak Preinstall org.mozilla.firefox]
Branch=stable

[Flatpak Preinstall org.gnome.Calculator]
Branch=stable
```

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

### Setup Node.js Environment using Just

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

A Just command grouped under 'Development' to set up Node.js. It downloads and installs 'fnm' (Fast Node Manager) and installs the latest LTS version of Node.js.

```just
[group('Development')]
setup-nodejs:
    #!/usr/bin/bash
    curl -fsSL https://fnm.vercel.app/install | bash
    source ~/.bashrc
    fnm install --lts
```

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

### Preinstall Flatpak Applications

Source: https://context7.com/projectbluefin/finpilot/llms.txt

`.preinstall` files in `custom/flatpaks/` are copied to `/etc/flatpak/preinstall.d/` in the image. On first boot after user setup, Flatpaks are downloaded from Flathub and installed automatically.

```ini
# custom/flatpaks/default.preinstall

# Web Browsers
[Flatpak Preinstall org.mozilla.firefox]
Branch=stable

[Flatpak Preinstall org.mozilla.Thunderbird]
Branch=stable
```

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

### Setup Pre-commit Hooks Locally

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Install and configure pre-commit hooks for local code validation. This includes installing the package, installing hooks, and running them manually.

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

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

### COPR Installation with Helper Function (Bash)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Example of installing packages from a COPR repository using a helper function `copr_install_isolated`. It's critical to use this function and disable COPRs after use to avoid conflicts.

```bash
#!/usr/bin/env bash
set -euo pipefail

source /ctx/copr-install-functions.sh

# Chrome
dnf config-manager addrepo --from-repofile=https://dl.google.com/linux/linux_signing_key.pub
dnf5 install -y google-chrome-stable

# 1Password via COPR (isolated)
copr_install_isolated username/repo package-name
```

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

### Create Custom ujust Commands

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Define custom commands using the 'just' build system. This example shows how to install development tools and create a custom system command.

```make
# vim: set ft=make :

# Install development tools
[group('Apps')]
install-dev-tools:
    #!/usr/bin/env bash
    echo "Installing development tools..."
    brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile

# Custom system command
[group('System')]
my-custom-command:
    #!/usr/bin/env bash
    echo "Running custom command..."
    # Your logic here (NO dnf5!)
```

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

### Install Default Apps using Brewfile

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command installs default applications defined in a Brewfile. It requires the 'brew bundle' command to be available.

```just
# custom/ujust/custom-apps.just

# Install default apps from Brewfile
[group('Apps')]
install-default-apps:
    #!/usr/bin/env bash
    brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile
```

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

### Install System Packages with dnf5

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Use this command in `build/10-build.sh` to install system utilities and dependencies baked into the container image. Always use the `-y` flag for non-interactive installs.

```bash
# In build/10-build.sh
dnf5 install -y vim git htop neovim tmux
```

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

### Copilot Prompt for Finpilot Setup

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

Use this prompt with GitHub Copilot to bootstrap your custom OS repository based on the Finpilot template. It ensures the entire OS is set up, GitHub Actions are enabled, and the README includes necessary setup instructions.

```text
Use @projectbluefin/finpilot as a template, name the OS the repository name. Ensure the entire operating system is bootstrapped. Ensure all github actions are enabled and running.  Ensure the README has the github setup instructions for cosign and the other steps required to finish the task.
```

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

### End-User ujust Command Examples

Source: https://context7.com/projectbluefin/finpilot/llms.txt

These bash commands demonstrate how end-users can interact with the 'ujust' system to list commands and execute various tasks like installing apps or updating the system.

```bash
# End-user usage (on the installed OS):
ujust                          # list all available commands
ujust install-default-apps
ujust install-flatpak org.gimp.GIMP
ujust configure-dev-groups
ujust update-and-reboot
ujust clean-containers

# Test just files locally before building:
just --justfile custom/ujust/custom-apps.just --list
just --justfile custom/ujust/custom-system.just benchmark
```

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

### Install VSCode using Flatpak Shortcut

Source: https://context7.com/projectbluefin/finpilot/llms.txt

A shortcut 'just' command to install VSCode by calling the 'install-flatpak' command with the appropriate Flatpak ID.

```just
# custom/ujust/custom-apps.just

# Shortcut examples
[group('Apps')]
install-vscode:
    ujust install-flatpak com.visualstudio.code
```

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

### List and Install Custom Commands with Just

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

Use 'just --list' to see available commands and 'just <command>' to execute them. Specify a custom justfile with '--justfile'.

```bash
just --justfile custom/ujust/custom-apps.just --list
```

```bash
just --justfile custom/ujust/custom-apps.just install-something
```

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

### Install Development Tools via Brewfile

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

A Just command grouped under 'Apps' to install development tools using a Brewfile. This is a common use case for setting up development environments.

```just
[group('Apps')]
install-dev-tools:
    brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
```

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

### Install Flatpak Manually

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Manually install a Flatpak application from a specified remote.

```bash
# Install Flatpak manually
flatpak install -y flathub org.mozilla.firefox
```

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

### Install Package Manually with Homebrew

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Manually install a package using Homebrew.

```bash
# Install manually
brew install package-name
```

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

### Commit Footer Example with Specifics

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

An example of a commit footer showing specific AI model and tool used.

```text
Assisted-by: Claude 3.5 Sonnet via GitHub Copilot
```

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

### Install JetBrains Toolbox

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command automatically fetches and installs the latest version of JetBrains Toolbox. It uses curl and jq to download and extract the application.

```just
# custom/ujust/custom-apps.just

# Install JetBrains Toolbox (fetches latest version automatically)
[group('Apps')]
install-jetbrains-toolbox:
    #!/usr/bin/env bash
    pushd "$(mktemp -d)"
    curl -sSfL -o releases.json 
      "https://data.services.jetbrains.com/products/releases?code=TBA&latest=true&type=release"
    BUILD_VERSION=$(jq -r '.TBA[0].build' ./releases.json)
    DOWNLOAD_LINK=$(jq -r '.TBA[0].downloads.linux.link' ./releases.json)
    curl -sSfL -O "${DOWNLOAD_LINK}"
    tar zxf "jetbrains-toolbox-${BUILD_VERSION}.tar.gz"
    mkdir -p "$HOME/.local/share/JetBrains/ToolboxApp/"
    mv "jetbrains-toolbox-${BUILD_VERSION}"/* "$HOME/.local/share/JetBrains/ToolboxApp/"
    popd
    "$HOME/.local/share/JetBrains/ToolboxApp/bin/jetbrains-toolbox"
```

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

### Commit Footer Example

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Example of how to format the commit footer to disclose AI agent usage.

```text
Assisted-by: [Model Name] via [Tool Name]
```

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

### Brewfile Syntax Example

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/brew/README.md

Demonstrates the basic syntax for defining packages, taps, and casks within a Brewfile using Ruby syntax. This file is processed by `brew bundle`.

```ruby
# Add a tap (third-party repository)
tap "homebrew/cask"

# Install a formula (CLI tool)
brew "bat"
brew "eza"
brew "ripgrep"

# Install a cask (GUI application, macOS only)
cask "visual-studio-code"
```

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

### Install Packages with Ujust Commands

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/brew/README.md

Convenient wrapper commands provided by ujust for installing predefined sets of applications. These commands abstract the underlying `brew bundle` calls.

```bash
ujust install-default-apps
```

```bash
ujust install-dev-tools
```

```bash
ujust install-fonts
```

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

### Install Packages with Brew Bundle

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/brew/README.md

Use this command to install packages defined in a specific Brewfile after booting into your custom image. Ensure the Brewfile path is correct.

```bash
brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile
```

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

### Install a Single Flatpak

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command installs a specified Flatpak application ID from Flathub. It ensures the Flathub remote is added if it doesn't exist.

```just
# custom/ujust/custom-apps.just

# Install a single Flatpak from Flathub
[group('Apps')]
install-flatpak APP_ID:
    #!/usr/bin/bash
    flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
    flatpak install -y flathub {{ APP_ID }}
```

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

### Rclone Workflow Integration Example

Source: https://github.com/projectbluefin/finpilot/blob/main/iso/rclone/README.md

Illustrates how the `build-disk.yml` workflow reads rclone configurations from this directory, substitutes secrets, and performs uploads.

```yaml
# In .github/workflows/build-disk.yml, the workflow will:
# 1. Read the config from this directory
# 2. Substitute secrets automatically
# 3. Upload using rclone
```

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

### List Installed Flatpaks

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Display all Flatpak applications currently installed on the system.

```bash
# Check installed Flatpaks
flatpak list
```

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

### Ujust Commands for App Installation

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Provides ujust commands to bundle and install default or development applications using Homebrew. These commands reference specific Brewfile locations.

```just
[group('Apps')]
install-default-apps:
    #!/usr/bin/env bash
    brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile

[group('Apps')]
install-dev-tools:
    #!/usr/bin/env bash
    brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
```

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

### Configure Flatpak Applications

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Specify GUI applications for post-first-boot installation in `custom/flatpaks/*.preinstall` using INI format. Ensure `Branch=stable` is set for each application.

```ini
# In custom/flatpaks/default.preinstall
[Flatpak Preinstall org.mozilla.firefox]
Branch=stable

[Flatpak Preinstall com.visualstudio.code]
Branch=stable

[Flatpak Preinstall org.gnome.Calculator]
Branch=stable
```

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

### Just Command with User Prompts using Helpers

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

An example of a Just command that uses helper functions like 'Choose()' from '/usr/lib/ujust/ujust.sh' for interactive user prompts.

```just
interactive-command:
    #!/usr/bin/bash
    source /usr/lib/ujust/ujust.sh  # Provides Choose() and other helpers
    OPTION=$(Choose "Option 1" "Option 2" "Cancel")
    echo "You chose: $OPTION"
```

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

### Add Homebrew Packages

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Define CLI tools and development environments in `custom/brew/*.Brewfile` using Ruby syntax. Users install these post-deployment via `ujust` commands.

```ruby
# In custom/brew/default.Brewfile
brew "bat"        # cat with syntax highlighting
brew "eza"        # Modern replacement for ls
brew "ripgrep"    # Faster grep
brew "fd"         # Simple alternative to find
```

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

### Just Command with Grouping

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

Organizes commands into groups for better organization in 'ujust help'. This example groups the command under 'Apps'.

```just
# Groups organize commands in ujust help
[group('Apps')]
install-brewfile:
    brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
```

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

### List Packages in Brewfile

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

See which packages would be installed or managed by the Brewfile without making any changes.

```bash
# List what would be installed
brew bundle list --file custom/brew/default.Brewfile
```

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

### Build with Verbose Output

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Use this command to get detailed logs during the build process, helpful for diagnosing build failures.

```bash
# Build with verbose output
podman build --log-level=debug .
```

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

### Desktop Environment Swap (Bash)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Script to remove the GNOME desktop environment and install the COSMIC desktop. It enables a COPR, installs the new desktop, disables the COPR, and sets the default target to graphical.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Remove GNOME, install COSMIC
dnf5 group remove -y "GNOME Desktop Environment"
dnf5 copr enable -y ryanabx/cosmic-epoch
dnf5 install -y cosmic-desktop
dnf5 copr disable -y ryanabx/cosmic-epoch
systemctl set-default graphical.target
```

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

### Build Script - Accessing OCI Resources

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Example bash script demonstrating how to access and copy files from OCI containers that were staged in the 'ctx' layer of a multi-stage Docker build.

```bash
#!/usr/bin/env bash
# Example: Copy branding files
cp -r /ctx/oci/branding/* /usr/share/branding/

# Example: Copy common desktop config
cp /ctx/oci/common/config.yaml /etc/myapp/

# Example: Use brew files
cp /ctx/oci/brew/*.sh /usr/local/bin/
```

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

### Define Homebrew Packages for Image

Source: https://context7.com/projectbluefin/finpilot/llms.txt

Brewfiles placed in `custom/brew/` are copied into the image at `/usr/share/ublue-os/homebrew/` at build time. Users install packages at runtime via `brew bundle` or `ujust` shortcuts.

```ruby
# custom/brew/default.Brewfile — essential CLI tools
brew "bat"       # cat with syntax highlighting
brew "eza"       # modern ls replacement
brew "fd"        # fast alternative to find
brew "rg"        # ripgrep — faster grep
brew "gh"        # GitHub CLI
brew "git"
brew "starship"  # cross-shell prompt
brew "zoxide"    # smarter cd
brew "htop"
brew "tmux"

# custom/brew/development.Brewfile — dev tools
# brew "node", brew "python", brew "go", etc.

# custom/brew/fonts.Brewfile — programming fonts
# tap "homebrew/cask-fonts"
# cask "font-jetbrains-mono-nerd-font"
```

```bash
# Users install at runtime:
brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile
brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
brew bundle --file /usr/share/ublue-os/homebrew/fonts.Brewfile

# Or via ujust shortcuts (see ujust section below):
ujust install-default-apps
ujust install-dev-tools
ujust install-fonts
ujust install-all-brew
```

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

### Adding Packages in build/10-build.sh

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

Add desired packages to your custom image by including `dnf5 install` commands in the `build/10-build.sh` script. This script is executed during the build process.

```bash
dnf5 install -y package-name
```

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

### List Failed System Services

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Identify any services that have failed to start or are not running correctly.

```bash
# Check running services
systemctl list-units --failed
```

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

### Interactive Feature Toggle Example

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command demonstrates using 'gum' for interactive prompts to enable or disable a feature. It sources helper functions from '/usr/lib/ujust/ujust.sh'.

```just
# custom/ujust/custom-system.just

# Interactive toggle command using gum
[group('System')]
toggle-example-feature:
    #!/usr/bin/bash
    source /usr/lib/ujust/ujust.sh   # provides Choose(), Confirm(), color vars
    OPTION=$(Choose "Enable" "Disable" "Cancel")
    case "$OPTION" in
        "Enable")  echo "Enabling..."  ;;
        "Disable") echo "Disabling..." ;; 
        "Cancel")  echo "No changes."  ;; 
    esac
```

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

### Homebrew Default Brewfile Configuration

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Defines a list of CLI and development tools to be installed via Homebrew. This file is intended to be used with `brew bundle`.

```ruby
# CLI tools
brew "bat"        # Better cat
brew "eza"        # Better ls
brew "ripgrep"    # Better grep
brew "fd"         # Better find

# Dev tools
tap "homebrew/cask"
brew "node"
brew "python"
```

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

### Validate Brewfile Syntax

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Check the syntax of your Brewfile to ensure it's correctly formatted before attempting to install packages.

```bash
# Validate Brewfile syntax
brew bundle check --file custom/brew/default.Brewfile
```

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

### Add Third-Party RPM Repository

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Adds a third-party RPM repository, installs a package, and then removes the repository file. This pattern is critical for managing external package dependencies.

```bash
# Add repo
cat > /etc/yum.repos.d/google-chrome.repo << 'EOF'
[google-chrome]
name=google-chrome
baseurl=https://dl.google.com/linux/chrome/rpm/stable/x86_64
enabled=1
gpgcheck=1
gpgkey=https://dl.google.com/linux/linux_signing_key.pub
EOF

# Install
dnf5 install -y google-chrome-stable

# Clean up (required!)
rm -f /etc/yum.repos.d/google-chrome.repo

```

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

### Justfile: Local Build & VM Testing Commands

Source: https://context7.com/projectbluefin/finpilot/llms.txt

Provides a task runner for local development. Use 'just' to list recipes. Commands include building container images, converting them to bootable disk images (qcow2, raw, iso), and launching VMs. Also includes linting, formatting, and cleaning tasks.

```bash
# List all available recipes
just

# Build the container image (tags as finpilot:stable by default)
just build

# Build with a custom image name and tag
just build my-os lts

# Build a QCOW2 VM disk image (uses Bootc Image Builder)
just build-qcow2

# Build a raw disk image
just build-raw

# Build an ISO installer image
just build-iso

# Rebuild container + qcow2 in one step
just rebuild-qcow2

# Launch a QCOW2 VM — opens browser at http://localhost:8006 automatically
# (4 CPU, 8GB RAM, 64GB disk, TPM + GPU enabled via qemux/qemu)
just run-vm-qcow2

# Run via systemd-vmspawn (alternative, uses GUI console)
just spawn-vm

# Lint all shell scripts with shellcheck
just lint

# Format all shell scripts with shfmt
just format

# Clean build artifacts
just clean

```

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

### Install Packages from COPR Repositories

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Installs packages from Fedora COPR repositories using the `copr_install_isolated` function. This function ensures COPRs are automatically disabled after installation, preventing persistence issues.

```bash
source /ctx/build/copr-helpers.sh

# Install from COPR (isolated - auto-disables after install)
copr_install_isolated "ublue-os/staging" package-name

# Install multiple packages
copr_install_isolated "ryanabx/cosmic-epoch" \
    cosmic-session \
    cosmic-greeter \
    cosmic-comp

```

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

### Local Testing Workflow with 'just'

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Execute a complete local testing cycle using 'just' commands, including building container and disk images, and running them in a VM. An alternative for ISO testing is also provided.

```bash
# 1. Build container image
just build

# 2. Build QCOW2 disk image
just build-qcow2

# 3. Run in VM
just run-vm-qcow2

# Or combine all steps
just build && just build-qcow2 && just run-vm-qcow2
```

```bash
just build
just build-iso
just run-vm-iso
```

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

### List Flatpak Preinstall Directory

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Inspect the contents of the directory where Flatpak preinstall configurations are stored.

```bash
# Check Flatpak preinstall
ls -la /etc/flatpak/preinstall.d/
```

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

### Just Command Structure Best Practice

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

Demonstrates the recommended structure for a Just command, including a description, optional grouping, and a bash shebang for multi-line scripts.

```just
# Brief description of what the command does
[group('Category')]
command-name:
    #!/usr/bin/bash
    # Use bash shebang for multi-line scripts
    # Commands go here
```

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

### Check Homebrew Status

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Run Homebrew's doctor command to check for potential issues with your Homebrew installation.

```bash
# Check Homebrew status
brew doctor
```

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

### Layering Additional System Files from OCI Containers (Dockerfile)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Demonstrates how to layer additional system files from OCI containers like projectbluefin/common and ublue-os/brew into the build. These are commented out by default and require manual uncommenting.

```dockerfile
# Artwork and Branding from projectbluefin/common
COPY --from=ghcr.io/projectbluefin/common:latest /system_files/bluefin /files/bluefin
COPY --from=ghcr.io/projectbluefin/common:latest /system_files/shared /files/shared

# Homebrew system files from ublue-os/brew
COPY --from=ghcr.io/ublue-os/brew:latest /system_files /files/brew
```

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

### Switch to Custom Image

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

Use this command to switch to a newly built custom image. Ensure you replace 'your-username/your-repo-name' with your actual repository details. A reboot is required for the changes to take effect.

```bash
sudo bootc switch ghcr.io/your-username/your-repo-name:stable
sudo systemctl reboot
```

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

### Check System Information

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Retrieve system information after deployment using the bootc status command.

```bash
# Check system info
bootc status
```

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

### Flatpak Default Preinstall Configuration

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Specifies Flatpak applications to be preinstalled after the initial boot. Each entry defines the Flatpak ID and the desired branch (e.g., stable).

```ini
[Flatpak Preinstall org.mozilla.firefox]
Branch=stable

[Flatpak Preinstall org.gnome.Calculator]
Branch=stable

[Flatpak Preinstall com.visualstudio.code]
Branch=stable
```

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

### Enable and Mask System Services with systemctl

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Use systemctl to enable services like podman.socket, mask unwanted services, and set the default system target to graphical.target.

```bash
# Enable service
systemctl enable podman.socket

# Mask unwanted service
systemctl mask unwanted-service

# Set default target
systemctl set-default graphical.target
```

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

### Local Project Build Commands

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

These `just` commands are used for local testing of your project changes. They allow you to build container images, VM disk images, and test them in a browser-based VM.

```bash
just build              # Build container image
just build-qcow2        # Build VM disk image
just run-vm-qcow2       # Test in browser-based VM
```

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

### View Homebrew Brewfile

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Display the contents of the default Homebrew Brewfile used by the system.

```bash
# Check Brewfile
cat /usr/share/ublue-os/homebrew/default.Brewfile
```

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

### Multi-Stage Dockerfile - Final Image Stage

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

The second stage of a multi-stage Docker build. It starts from a base image and executes build scripts from the context stage, allowing access to all copied resources.

```dockerfile
FROM ghcr.io/ublue-os/silverblue-main:42

RUN --mount=type=bind,from=ctx,source=/,target=/ctx \
    /ctx/build/10-build.sh
```

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

### Running a Single Build Script in Containerfile

Source: https://github.com/projectbluefin/finpilot/blob/main/build/README.md

Demonstrates how to execute a specific build script during the container image creation process using the RUN command in a Containerfile.

```dockerfile
RUN /ctx/build/10-build.sh
```

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

### README 'What's Different' Section Template

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

This markdown template should be used to create the 'What's Different' section in the README.md file. It helps users understand the customizations made to the base image.

```markdown
## What Makes this Raptor Different?

Here are the changes from [Base Image Name]. This image is based on [Bluefin/Bazzite/Aurora/etc] and includes these customizations:

### Added Packages (Build-time)
- **System packages**: tmux, micro, mosh - [brief explanation of why]

### Added Applications (Runtime)
- **CLI Tools (Homebrew)**: neovim, helix - [brief explanation]
- **GUI Apps (Flatpak)**: Spotify, Thunderbird - [brief explanation]

### Removed/Disabled
- List anything removed from base image

### Configuration Changes
- Any systemd services enabled/disabled
- Desktop environment changes
- Other notable modifications

*Last updated: [date]*
```

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

### Add User to Docker and Libvirt Groups

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command adds the current user to the 'docker' and 'libvirt' groups using 'pkexec' for elevated privileges. It also ensures the groups exist.

```just
# custom/ujust/custom-system.just

# Add user to docker + libvirt groups (elevated via pkexec)
[group('System')]
configure-dev-groups:
    #!/usr/bin/pkexec bash
    CURRENT_USER="{{ `id -un` }}"
    for group in docker libvirt; do
        grep -q "^$group:" /etc/group || grep "^$group:" /usr/lib/group | tee -a /etc/group
        usermod -aG $group $CURRENT_USER
    done
```

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

### Alternative Base Images (Dockerfile)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Lists common alternative base images for different use cases, including stable, bleeding edge, and NVIDIA variants. Recommended tag is `:stable`.

```dockerfile
FROM ghcr.io/ublue-os/bluefin:stable      # Dev, GNOME, `:stable` or `:gts`
FROM ghcr.io/ublue-os/bazzite:stable      # Gaming, Steam Deck
FROM ghcr.io/ublue-os/aurora:stable       # KDE Plasma
FROM quay.io/fedora/fedora-bootc:42       # Upstream Fedora
```

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

### ISO Disk Image Configuration

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

TOML configuration for building VM disk images. This includes specifying the image format and build commands.

```toml
[customizations.installer.kickstart]
contents = """
%post
bootc switch --mutate-in-place --transport registry ghcr.io/USERNAME/REPO:stable
%end
"""
```

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

### List Flatpak Remotes

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

View the configured Flatpak remote repositories, such as Flathub.

```bash
# Check Flatpak remotes
flatpak remotes
```

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

### List Available Ujust Commands

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Display all available user convenience commands (ujust) on the system.

```bash
# Check ujust commands available
ujust --list
```

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

### Rclone Configuration File Format

Source: https://github.com/projectbluefin/finpilot/blob/main/iso/rclone/README.md

Demonstrates the standard rclone INI format used for configuration files, including placeholders for secrets that are automatically replaced by GitHub Actions.

```ini
[remote-name]
type = provider_type
access_key_id = ${SECRET_NAME}
secret_access_key = ${ANOTHER_SECRET}
```

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

### Custom Script Template

Source: https://github.com/projectbluefin/finpilot/blob/main/build/README.md

A basic template for creating custom build scripts. Ensure to replace the placeholder comment with your specific commands.

```bash
#!/usr/bin/env bash
set -oue pipefail

echo "Running custom setup..."
# Your commands here
```

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

### Dockerfile: Multi-Stage OCI Build Context and Base Image

Source: https://context7.com/projectbluefin/finpilot/llms.txt

Defines a two-stage Docker build. The first stage ('ctx') assembles local build scripts and upstream OCI layers. The second stage applies these to a chosen base image (e.g., Fedora Silverblue) and runs validation scripts. Use cache mounts for faster builds.

```dockerfile
# Stage 1: context — merge local files + upstream OCI layers
FROM scratch AS ctx

COPY build /build
COPY custom /custom

# Pin upstream OCI images via SHA digest (Renovate keeps these up to date)
COPY --from=ghcr.io/projectbluefin/common:latest@sha256:b8fe93b16674a547b4cf38493af19caa484d9575956fc3be04ca3d10faec23ff \
     /system_files /oci/common

COPY --from=ghcr.io/ublue-os/brew:latest@sha256:ca91068f51ce663d495ccfc829352d6621ec95f6c7db447ade55023b222f9762 \
     /system_files /oci/brew

# Stage 2: base image (Fedora Silverblue with GNOME)
FROM ghcr.io/ublue-os/silverblue-main:latest@sha256:f8d5fd28aa7bb0ed9e17e98e4f9fb174b6961a2dc4a3113b78c5dff4af5bdf6f

# Alternative base images (uncomment to switch):
# FROM ghcr.io/ublue-os/base-main:latest          # Fedora, no desktop
# FROM quay.io/centos-bootc/centos-bootc:stream10  # CentOS-based

# Run build scripts from the ctx stage; use cache mounts for speed
RUN --mount=type=bind,from=ctx,source=/,target=/ctx \
    --mount=type=cache,dst=/var/cache \
    --mount=type=cache,dst=/var/log \
    --mount=type=tmpfs,dst=/tmp \
    /ctx/build/10-build.sh

# Validate the final image
RUN bootc container lint

```

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

### Flatpak Preinstall Declarations

Source: https://context7.com/projectbluefin/finpilot/llms.txt

These declarations specify Flatpak applications to be preinstalled in the system image. Ensure the Branch is set to 'stable' for most applications.

```ini
[Flatpak Preinstall org.gnome.TextEditor]
Branch=stable
```

```ini
[Flatpak Preinstall org.gnome.Calculator]
Branch=stable
```

```ini
[Flatpak Preinstall com.github.tchx84.Flatseal]
Branch=stable
```

```ini
[Flatpak Preinstall io.missioncenter.MissionCenter]
Branch=stable
```

```ini
[Flatpak Preinstall org.gtk.Gtk3theme.adw-gtk3]
Branch=3.22
IsRuntime=true
```

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

### Build and Rechunk OCI Image with Podman

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

This YAML snippet defines a GitHub Actions workflow for building an OCI image using Podman and then rechunking it to optimize for registry storage. It includes steps for building, rechunking, and pushing the image.

```yaml
- name: Build image
  id: build
  run: sudo podman build -t "${IMAGE_NAME}:${DEFAULT_TAG}" -f ./Containerfile .

- name: Rechunk Image
  run: |
    sudo podman run --rm --privileged \
      -v /var/lib/containers:/var/lib/containers \
      --entrypoint /usr/libexec/bootc-base-imagectl \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}" \
      rechunk --max-layers 96 \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}" \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}"

- name: Push to Registry
  run: sudo podman push "localhost/${IMAGE_NAME}:${DEFAULT_TAG}" "${IMAGE_REGISTRY}/${IMAGE_NAME}:${DEFAULT_TAG}"
```

```yaml
- name: Rechunk Image
  run: |
    sudo podman run --rm --privileged \
      -v /var/lib/containers:/var/lib/containers \
      --entrypoint /usr/libexec/bootc-base-imagectl \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}" \
      rechunk --max-layers 67 \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}" \
      "localhost/${IMAGE_NAME}:${DEFAULT_TAG}-rechunked"
    
    # Tag the rechunked image with the original tag
    sudo podman tag "localhost/${IMAGE_NAME}:${DEFAULT_TAG}-rechunked" "localhost/${IMAGE_NAME}:${DEFAULT_TAG}"
    sudo podman rmi "localhost/${IMAGE_NAME}:${DEFAULT_TAG}-rechunked"
```

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

### Update System and Reboot Prompt

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This 'just' command updates the system using 'bootc upgrade' and then prompts the user to reboot using 'gum confirm'. It sources helper functions from '/usr/lib/ujust/ujust.sh'.

```just
# custom/ujust/custom-system.just

# Update system and optionally reboot
[group('Maintenance')]
update-and-reboot:
    #!/usr/bin/bash
    source /usr/lib/ujust/ujust.sh
    sudo bootc upgrade
    gum confirm "Reboot now to apply updates?" && systemctl reboot || echo "Reboot later."
```

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

### Base Image Selection in Containerfile

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

Specify the base Bluefin image for your custom OS by modifying this line in the `Containerfile`. This determines the foundation of your operating system.

```dockerfile
FROM ghcr.io/ublue-os/bluefin:stable
```

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

### Multi-Stage Build Context (Dockerfile)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Defines the initial build stage (ctx) by copying local files and importing resources from various OCI containers. Renovate bot automatically updates OCI container tags to SHA-256 digests.

```dockerfile
FROM scratch AS ctx

COPY build /build
COPY custom /custom
# Import from OCI containers - Renovate updates :latest to SHA-256 digests
COPY --from=ghcr.io/ublue-os/base-main:latest /system_files /oci/base
COPY --from=ghcr.io/projectbluefin/common:latest /system_files /oci/common
COPY --from=ghcr.io/projectbluefin/branding:latest /system_files /oci/branding
COPY --from=ghcr.io/ublue-os/artwork:latest /system_files /oci/artwork
COPY --from=ghcr.io/ublue-os/brew:latest /system_files /oci/brew
```

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

### Verify Signed Container Image with Cosign

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

This bash command demonstrates how to verify the signature of a container image using `cosign`. Ensure you have the public key (`cosign.pub`) available for verification.

```bash
cosign verify --key cosign.pub ghcr.io/your-username/your-repo-name:stable
```

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

### Generate SBOM with Syft and Attest to Image

Source: https://context7.com/projectbluefin/finpilot/llms.txt

Generates an SPDX-format SBOM using Syft and optionally attests it to the signed image. Requires signing to be enabled first. Uncomment steps in build.yml to enable.

```yaml
# In .github/workflows/build.yml, uncomment these steps:

# - name: Setup Syft
#   id: setup-syft
#   uses: anchore/sbom-action/download-syft@8e94d75ddd33f69f691467e42275782e4bfefe84
#   with:
#     syft-version: v1.20.0

# - name: Generate SBOM
#   env:
#     IMAGE: ${{ env.IMAGE_NAME }}
#     SYFT_CMD: ${{ steps.setup-syft.outputs.cmd }}
#   run: |
#     OUTPUT_PATH="$(mktemp -d)/sbom.json"
#     export SYFT_PARALLELISM=$(($(nproc)*2))
#     $SYFT_CMD ${IMAGE}:stable -o spdx-json=${OUTPUT_PATH}
#     echo "OUTPUT_PATH=${OUTPUT_PATH}" >> $GITHUB_OUTPUT

# - name: Add SBOM Attestation
#   env:
#     IMAGE: ${{ env.IMAGE_REGISTRY }}/${{ env.IMAGE_NAME }}
#     DIGEST: ${{ steps.push.outputs.digest }}
#     COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
#     SBOM_OUTPUT: ${{ steps.generate-sbom.outputs.OUTPUT_PATH }}
#   run: |
#     cd "$(dirname "$SBOM_OUTPUT")"
#     cosign attest -y \
#       --predicate "$(basename "$SBOM_OUTPUT")" \
#       --type spdxjson \
#       --key env://COSIGN_PRIVATE_KEY \
#       "${IMAGE}@${DIGEST}"
```

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

### Check Justfile Syntax

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Verify the syntax of your Justfiles to catch errors before running commands.

```bash
# Check syntax
just --list
```

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

### Base Image Selection (Dockerfile)

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Selects the base image for the build. Supports Fedora-based (ublue-os/silverblue-main) or CentOS-based (centos-bootc) images.

```dockerfile
FROM ghcr.io/ublue-os/silverblue-main:latest  # Default (Fedora-based)
# OR
FROM quay.io/centos-bootc/centos-bootc:stream10  # CentOS-based
```

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

### List Brewfiles Location

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Show the directory where Homebrew Brewfiles are located for inspection.

```bash
# Check Brewfiles location
ls -la /usr/share/ublue-os/homebrew/
```

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

### Import OCI Container Resources in Dockerfile

Source: https://github.com/projectbluefin/finpilot/blob/main/README.md

This Dockerfile snippet shows how to copy files from various OCI containers into the build context using `COPY --from`. These imported files are accessible at specific paths within the build environment.

```dockerfile
COPY --from=ghcr.io/ublue-os/base-main:latest /system_files /oci/base
COPY --from=ghcr.io/projectbluefin/common:latest /system_files /oci/common
COPY --from=ghcr.io/ublue-os/brew:latest /system_files /oci/brew
```

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

### Search for Flatpak IDs

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/flatpaks/README.md

Use this command to find the unique identifier for a Flatpak application you wish to preinstall.

```bash
flatpak search app-name
```

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

### Just Command with Error Handling

Source: https://github.com/projectbluefin/finpilot/blob/main/custom/ujust/README.md

A Just command that includes error handling best practices using 'set -euo pipefail' to ensure script robustness.

```just
install-something:
    #!/usr/bin/bash
    set -euo pipefail  # Exit on error, undefined vars, pipe failures
    # Your commands
```

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

### Disk Layout Configuration

Source: https://context7.com/projectbluefin/finpilot/llms.txt

This TOML configuration defines the disk layout for VM and bare-metal images, specifying the mountpoint and minimum size for the root filesystem.

```toml
# iso/disk.toml — disk layout for VM and bare-metal images
[[customizations.filesystem]]
mountpoint = "/"
minsize = "20 GiB"
```

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

### Run Just Command with Debug

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Execute a specific Just command with verbose output to aid in debugging.

```bash
# Run specific command with debug
just --verbose install-default-apps
```

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

### Pull and Run PR Build

Source: https://github.com/projectbluefin/finpilot/blob/main/AGENTS.md

Pull a specific pull request build of your repository and run it interactively in a container for testing.

```bash
# PR builds are tagged as :pr-NUMBER
podman pull ghcr.io/YOUR_USERNAME/YOUR_REPO:pr-123
podman run --rm -it ghcr.io/YOUR_USERNAME/YOUR_REPO:pr-123 bash
```

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

### GitHub Actions: Automated Build & Push Workflow

Source: https://context7.com/projectbluefin/finpilot/llms.txt

Automates building the container image with buildah and pushing to GHCR on pushes to 'main' or daily. Pull requests build and validate without pushing. Customize image metadata via environment variables.

```yaml
# .github/workflows/build.yml (key environment variables to customize)
env:
  IMAGE_DESC: "My Customized Universal Blue Image"
  IMAGE_KEYWORDS: "bootc,ublue,universal-blue"
  IMAGE_LOGO_URL: "https://avatars.githubusercontent.com/u/120078124?s=200&v=4"
  IMAGE_NAME: "${{ github.event.repository.name }}"   # auto-set from repo name
  IMAGE_REGISTRY: "ghcr.io/${{ github.repository_owner }}"
  DEFAULT_TAG: "stable"

# Resulting image tags published to GHCR:
#   ghcr.io/<owner>/<repo>:stable
#   ghcr.io/<owner>/<repo>:stable.20250115
#   ghcr.io/<owner>/<repo>:20250115

# Switch to your image after it publishes:
# sudo bootc switch ghcr.io/your-username/your-repo-name:stable
# sudo systemctl reboot

```