Claude/update readme content dn jab (#8)

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

README.adoc

@@ -279,6 +279,97 @@ core/
 | Visual customisations: colours, themes, terminal-specific settings
 |===
 
+== Examples
+
+The `examples/` directory contains ready-to-use configuration snippets:
+
+[source,bash]
+----
+# Copy all examples to your modshells directory
+cp -r examples/* ~/.config/nushell/modshells/
+
+# Or copy individual files
+cp examples/tools/git.sh ~/.config/nushell/modshells/tools/
+cp examples/misc/aliases.sh ~/.config/nushell/modshells/misc/
+----
+
+=== Available Examples
+
+[cols="1,2"]
+|===
+| File | Description
+
+| `core/00-path.sh`
+| PATH modifications for ~/.local/bin, Cargo, Go, Deno
+
+| `core/10-history.sh`
+| History size, deduplication, timestamps, ignore patterns
+
+| `core/20-options.sh`
+| Shell options (extglob, cdspell, globstar), editor, locale
+
+| `tools/git.sh`
+| Git aliases (gs, ga, gc, gp, gl, glog, etc.)
+
+| `tools/fzf.sh`
+| Fuzzy finder setup with fd integration
+
+| `tools/starship.sh`
+| Starship prompt initialisation
+
+| `misc/aliases.sh`
+| Navigation (.., ...), ls variants, safety nets (rm -i)
+
+| `misc/functions.sh`
+| Utility functions: mkcd, extract, ff, fd, backup
+
+| `os/linux.sh`
+| Package manager aliases, systemd shortcuts
+
+| `os/macos.sh`
+| Homebrew setup, macOS-specific utilities
+
+| `ui/colours.sh`
+| Terminal colours, GCC colours, man page colours
+
+| `ui/prompt.sh`
+| Custom bash prompt with git branch (fallback for non-starship)
+|===
+
+== Testing
+
+=== Smoke Test
+
+Run the shell-based smoke test to verify the build:
+
+[source,bash]
+----
+# From the repository root
+./tests/smoke_test.sh
+----
+
+The smoke test verifies:
+
+* Source files exist
+* Examples have correct structure
+* SPDX license headers present
+* Binary runs (if built)
+* Directory creation works
+* Idempotency check passes
+
+=== Unit Tests
+
+Build and run the Ada unit tests:
+
+[source,bash]
+----
+# Build tests
+gprbuild -p -j0 -P tests/tests.gpr
+
+# Run tests
+./bin/test_shell_manager
+----
+
 == Development Status
 
 Current version: **v0.1**

examples/README.adoc

@@ -0,0 +1,69 @@
+= Modshells Example Configurations
+:toc:
+
+Example shell configuration snippets for use with Modshells.
+
+== Usage
+
+Copy the snippets you want into your modshells directory:
+
+[source,bash]
+----
+# Copy all examples
+cp -r examples/* ~/.config/nushell/modshells/
+
+# Or copy individual files
+cp examples/tools/git.sh ~/.config/nushell/modshells/tools/
+----
+
+== Directory Structure
+
+[cols="1,3"]
+|===
+| Directory | Purpose
+
+| `core/`
+| Essential settings loaded first (PATH, history, shell options)
+
+| `tools/`
+| Tool-specific configurations (git, fzf, starship)
+
+| `misc/`
+| General aliases and utility functions
+
+| `os/`
+| Operating system specific settings (Linux, macOS)
+
+| `ui/`
+| Visual customisations (colours, prompt)
+|===
+
+== File Naming
+
+Files are sourced alphabetically. Use numeric prefixes to control load order:
+
+* `00-*.sh` - Load first (PATH, critical settings)
+* `10-*.sh` - Load early (history, options)
+* `20-*.sh` - Load later (depends on earlier settings)
+* No prefix - Load in alphabetical order
+
+== Customisation
+
+These examples are starting points. Modify them to suit your workflow:
+
+1. Copy the file to your modshells directory
+2. Edit to add/remove aliases and settings
+3. Restart your shell or run `source ~/.bashrc`
+
+== Shell Compatibility
+
+These examples use POSIX-compatible syntax and work with:
+
+* Bash
+* Zsh
+* Ksh
+* Dash (limited)
+* Oils (OSH/YSH)
+
+For Fish, Nushell, or PowerShell, you'll need to translate the syntax.
+See the main README for shell-specific sourcing blocks.

examples/core/00-path.sh

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# core/00-path.sh - PATH modifications (loaded first)
+#
+# Add custom directories to PATH. Use numeric prefix to control load order.
+
+# Local binaries
+export PATH="$HOME/.local/bin:$PATH"
+
+# Cargo (Rust)
+[ -d "$HOME/.cargo/bin" ] && export PATH="$HOME/.cargo/bin:$PATH"
+
+# Go
+[ -d "$HOME/go/bin" ] && export PATH="$HOME/go/bin:$PATH"
+
+# Deno
+[ -d "$HOME/.deno/bin" ] && export PATH="$HOME/.deno/bin:$PATH"

examples/core/10-history.sh

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# core/10-history.sh - Shell history configuration
+
+# Increase history size
+export HISTSIZE=10000
+export HISTFILESIZE=20000
+
+# Ignore duplicates and commands starting with space
+export HISTCONTROL=ignoreboth:erasedups
+
+# Append to history file, don't overwrite
+shopt -s histappend 2>/dev/null || true
+
+# Timestamp history entries
+export HISTTIMEFORMAT="%Y-%m-%d %H:%M:%S  "
+
+# Ignore common commands
+export HISTIGNORE="ls:ll:la:cd:pwd:exit:clear:history"

examples/core/20-options.sh

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# core/20-options.sh - Shell options and settings
+
+# Check window size after each command
+shopt -s checkwinsize 2>/dev/null || true
+
+# Enable extended globbing
+shopt -s extglob 2>/dev/null || true
+
+# Correct minor spelling errors in cd
+shopt -s cdspell 2>/dev/null || true
+
+# Enable recursive globbing with **
+shopt -s globstar 2>/dev/null || true
+
+# Case-insensitive globbing
+shopt -s nocaseglob 2>/dev/null || true
+
+# Default editor
+export EDITOR="${EDITOR:-vim}"
+export VISUAL="${VISUAL:-$EDITOR}"
+
+# Locale
+export LANG="${LANG:-en_US.UTF-8}"
+export LC_ALL="${LC_ALL:-en_US.UTF-8}"

examples/misc/aliases.sh

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# misc/aliases.sh - General purpose aliases
+
+# Navigation
+alias ..='cd ..'
+alias ...='cd ../..'
+alias ....='cd ../../..'
+
+# List files
+alias ls='ls --color=auto'
+alias ll='ls -alF'
+alias la='ls -A'
+alias l='ls -CF'
+
+# Grep with colour
+alias grep='grep --color=auto'
+alias fgrep='fgrep --color=auto'
+alias egrep='egrep --color=auto'
+
+# Safety nets
+alias rm='rm -i'
+alias cp='cp -i'
+alias mv='mv -i'
+
+# Disk usage
+alias df='df -h'
+alias du='du -h'
+
+# Process management
+alias psg='ps aux | grep -v grep | grep -i'
+
+# Quick edit
+alias bashrc='$EDITOR ~/.bashrc'
+alias zshrc='$EDITOR ~/.zshrc'

examples/misc/functions.sh

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# misc/functions.sh - Utility functions
+
+# Create directory and cd into it
+mkcd() {
+    mkdir -p "$1" && cd "$1"
+}
+
+# Extract various archive formats
+extract() {
+    if [ -f "$1" ]; then
+        case "$1" in
+            *.tar.bz2) tar xjf "$1" ;;
+            *.tar.gz)  tar xzf "$1" ;;
+            *.tar.xz)  tar xJf "$1" ;;
+            *.bz2)     bunzip2 "$1" ;;
+            *.gz)      gunzip "$1" ;;
+            *.tar)     tar xf "$1" ;;
+            *.tbz2)    tar xjf "$1" ;;
+            *.tgz)     tar xzf "$1" ;;
+            *.zip)     unzip "$1" ;;
+            *.Z)       uncompress "$1" ;;
+            *.7z)      7z x "$1" ;;
+            *)         echo "'$1' cannot be extracted" ;;
+        esac
+    else
+        echo "'$1' is not a valid file"
+    fi
+}
+
+# Find file by name
+ff() {
+    find . -type f -iname "*$1*"
+}
+
+# Find directory by name
+fd() {
+    find . -type d -iname "*$1*"
+}
+
+# Quick backup
+backup() {
+    cp "$1" "$1.bak.$(date +%Y%m%d-%H%M%S)"
+}

examples/os/linux.sh

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# os/linux.sh - Linux-specific configuration
+
+# Only load on Linux
+[ "$(uname -s)" = "Linux" ] || return 0
+
+# Package manager aliases (adjust for your distro)
+if command -v apt >/dev/null 2>&1; then
+    alias apt-update='sudo apt update && sudo apt upgrade'
+    alias apt-search='apt search'
+    alias apt-install='sudo apt install'
+elif command -v dnf >/dev/null 2>&1; then
+    alias dnf-update='sudo dnf upgrade'
+    alias dnf-search='dnf search'
+    alias dnf-install='sudo dnf install'
+elif command -v pacman >/dev/null 2>&1; then
+    alias pac-update='sudo pacman -Syu'
+    alias pac-search='pacman -Ss'
+    alias pac-install='sudo pacman -S'
+fi
+
+# Systemd shortcuts
+if command -v systemctl >/dev/null 2>&1; then
+    alias sc='systemctl'
+    alias scs='systemctl status'
+    alias scr='sudo systemctl restart'
+    alias sce='sudo systemctl enable'
+    alias scd='sudo systemctl disable'
+fi
+
+# Open file manager
+alias open='xdg-open'

examples/os/macos.sh

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# os/macos.sh - macOS-specific configuration
+
+# Only load on macOS
+[ "$(uname -s)" = "Darwin" ] || return 0
+
+# Homebrew
+if [ -x /opt/homebrew/bin/brew ]; then
+    eval "$(/opt/homebrew/bin/brew shellenv)"
+elif [ -x /usr/local/bin/brew ]; then
+    eval "$(/usr/local/bin/brew shellenv)"
+fi
+
+# Homebrew aliases
+alias brew-update='brew update && brew upgrade'
+alias brew-cleanup='brew cleanup -s && brew autoremove'
+
+# macOS-specific aliases
+alias showfiles='defaults write com.apple.finder AppleShowAllFiles YES && killall Finder'
+alias hidefiles='defaults write com.apple.finder AppleShowAllFiles NO && killall Finder'
+
+# Flush DNS cache
+alias flushdns='sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder'
+
+# Open current directory in Finder
+alias finder='open -a Finder .'
+
+# Quick Look preview
+alias ql='qlmanage -p'
+
+# Copy to clipboard
+alias copy='pbcopy'
+alias paste='pbpaste'

examples/tools/fzf.sh

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR MIT
+# tools/fzf.sh - Fuzzy finder configuration
+
+# Check if fzf is installed
+command -v fzf >/dev/null 2>&1 || return 0
+
+# Default options
+export FZF_DEFAULT_OPTS='--height 40% --layout=reverse --border'
+
+# Use fd if available (faster than find)
+if command -v fd >/dev/null 2>&1; then
+    export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'
+    export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"
+    export FZF_ALT_C_COMMAND='fd --type d --hidden --follow --exclude .git'
+fi
+
+# Ctrl+R for history search with preview
+export FZF_CTRL_R_OPTS='--preview "echo {}" --preview-window=down:3:wrap'
+
+# fzf key bindings (if available)
+[ -f /usr/share/fzf/key-bindings.bash ] && . /usr/share/fzf/key-bindings.bash
+[ -f /usr/share/fzf/completion.bash ] && . /usr/share/fzf/completion.bash