From f8a61e929046b0a21cc55b20fa592bf050bc6276 Mon Sep 17 00:00:00 2001
From: lachtan <martin.blazik@gmail.com>
Date: Sun, 15 Mar 2026 14:36:53 +0100
Subject: [PATCH] Improve CLAUDE.md docs and add bash style rules

Expand CLAUDE.md with detailed helper function reference,
environment variables section, and commit conventions.
Add .claude/rules/bash-style.md for bash coding standards.
---
 .claude/rules/bash-style.md | 64 +++++++++++++++++++++++++++++++++++++
 CLAUDE.md                   | 35 ++++++++++++++++----
 2 files changed, 93 insertions(+), 6 deletions(-)
 create mode 100644 .claude/rules/bash-style.md

diff --git a/.claude/rules/bash-style.md b/.claude/rules/bash-style.md
new file mode 100644
index 0000000..3227323
--- /dev/null
+++ b/.claude/rules/bash-style.md
@@ -0,0 +1,64 @@
+---
+paths:
+  - "**/*.sh"
+  - "bashrc"
+  - "bin/*"
+---
+
+# Bash Readability Style
+
+The primary goal is code that is **easy to understand at a glance**. Write bash that reads naturally, follows established conventions, and doesn't require the reader to puzzle over clever tricks. Favor clarity and well-known idioms over brevity.
+
+Complements CLAUDE.md. Does not repeat rules already defined there.
+
+## Formatting
+
+- 2-space indentation, no tabs
+- `then`/`do` on same line: `if cond; then` / `for x in list; do`
+- Blank lines between logical sections; no blanks between tightly coupled statements
+- Long pipe chains: one command per line with leading `|`
+
+## Naming
+
+- `UPPER_CASE` — exported env vars and constants
+- `snake_case` — local variables and function names
+- `verb_noun` pattern for functions: `set_ps1_prompt`, `docker_aws_login`
+- Meaningful names, no single letters except loop counters (`i`, `f`)
+
+## Functions
+
+```bash
+function do_thing() {
+  local name="$1"
+  local count="${2:-0}"
+  ...
+}
+```
+
+- Always `function name() {` declaration style
+- Always `local` for function variables, assigned on declaration line
+- Name parameters immediately: `local filename="$1"` — no raw `$1` in logic
+- Default values via `${VAR:-default}`
+- Guard clauses with early `return` over deep nesting
+- Keep functions focused — single responsibility
+
+## Syntax Preferences
+
+- `[[ ]]` over `[ ]` for conditionals
+- `(( ))` for arithmetic comparisons
+- `$(command)` for substitution, never backticks
+- Double quotes around expansions: `"$var"`, `"${array[@]}"`
+- Single quotes for literals that must not expand
+- `printf` over `echo` when output contains escapes or format strings
+
+## Commands
+
+- Long options for clarity: `--recursive` not `-r` (common test flags `-f`, `-d`, `-e` are fine)
+- Redirect stderr: `> /dev/null 2>&1`
+- `# shellcheck shell=bash` at top of sourced (non-executable) files
+
+## Comments
+
+- Minimal — explain *why*, not *what*
+- URL reference when pattern comes from external source
+- No banner/divider comments
diff --git a/CLAUDE.md b/CLAUDE.md
index ad3c0fc..4bbc4b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,7 @@
-# CLAUDE.md
+# Linux Workspace
 
-Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh` (ordered by prefix) and adds `bin/` to PATH. `$LWS` points to repo root.
+Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh` (ordered by prefix)
+and adds `bin/` to PATH. `$LWS` points to repo root.
 
 ## Directory Layout
 
@@ -9,19 +10,34 @@ Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh
 - `bin/` — Scripts auto-added to PATH. New CLI tools go here.
 - `scripts/` — Setup scripts NOT on PATH (git-config, docker fixes, gnome config).
 - `conf/` — Tool configs (vim, WireGuard, WSL).
-- `functions.sh` — Core lib: `append_path`, `prepend_path`, `set_uniq_path`, `source_directory_sh`, `is_fast_init`/`is_slow_init`, WSL detection, debug logging.
+- `functions.sh` — Core lib (see below).
+
+## Key Helpers (`functions.sh`)
+
+- `can_run <cmd>` — check if command is available
+- `is_slow_init` / `is_fast_init` — check `LWS_FAST` mode
+- `is_interactive_shell` — true when `[[ $- == *i* ]]`
+- `is_wsl` — detect WSL environment
+- `true_false <val>` — normalize `1/true/yes` to boolean
+- `prepend_path` / `append_path` / `prepend_path_try` / `append_path_try` — safe PATH manipulation
+- `source_try <file>` — source file if it exists
+- `source_directory_sh <dir>` — source all `*.sh` in a directory
+- `xlog <msg>` — debug log (only in interactive + `LWS_DEBUG`)
 
 ## Conventions
 
-All new bash scripts MUST use:
+All new bash scripts should use:
+
 ```bash
 #!/usr/bin/env bash
+
 set -E -o errexit -o nounset -o pipefail
 ```
 
-Before writing shell code, check `functions.sh` for existing helper functions (e.g. `can_run`, `append_path_try`, `source_try`) and prefer them over raw commands.
+Before writing shell code, check `functions.sh` for existing helper functions and prefer them over raw commands.
 
 RC files MUST guard slow tools and check availability:
+
 ```bash
 if is_slow_init && can_run pyenv; then
     # initialize pyenv
@@ -30,4 +46,11 @@ fi
 
 Installers (`install/*.sh`) MUST be idempotent — check before installing.
 
-Env vars: `LWS_FAST=1` skips slow tools, `LWS_DEBUG=1` enables debug logging.
+## Environment Variables
+
+- `LWS_FAST=1` — skips slow tools during shell init
+- `LWS_DEBUG=1` — enables debug logging via `xlog`
+
+## Commits
+
+Do not add `Co-Authored-By` lines to commit messages.