Add initial scripts and project conventions

examples/hello-world.md

@@ -0,0 +1,45 @@
+# hello-world.sh
+
+Reference example script — prints a greeting. Demonstrates the required
+structure every script in this repo must follow: `common.sh` sourcing,
+`SCRIPT_HELP` heredoc, `--help` handling, and argument parsing with
+`common::die` on invalid input.
+
+**This is not a real utility.** Copy its structure when writing an actual
+script; don't invoke it from other scripts or automation.
+
+## What it does
+
+Prints `Hello, <name>!` to stdout, where `<name>` defaults to `world` or
+whatever is passed via `--name`.
+
+## Requirements
+
+- Bash 4+ (uses `set -euo pipefail`, no external commands beyond common.sh)
+
+## Usage
+
+```bash
+./examples/hello-world.sh [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-h`, `--help` | Show help message and exit |
+| `-n`, `--name NAME` | Name to greet (default: `world`) |
+
+## Examples
+
+```bash
+# Default greeting
+./examples/hello-world.sh
+# → Hello, world!
+```
+
+```bash
+# Custom name
+./examples/hello-world.sh --name Danail
+# → Hello, Danail!
+```

examples/hello-world.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+#
+# hello-world.sh — reference example demonstrating the StrixScripts
+# conventions (see AGENTS.md). Not a real utility script — copy this
+# pattern when creating an actual script, don't call this one from
+# anywhere real.
+#
+# Full documentation: see hello-world.md in this same folder.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "${SCRIPT_DIR}/../lib/common.sh"
+
+SCRIPT_HELP=$(cat <<'HELP'
+Usage: hello-world.sh [-n NAME]
+
+Prints a greeting. Reference example only — demonstrates the SCRIPT_HELP
+pattern, argument parsing, and common.sh usage that every real script in
+this repo should follow.
+
+Options:
+  -h, --help        Show this help message and exit
+  -n, --name NAME   Name to greet (default: world)
+
+Examples:
+  ./hello-world.sh
+  ./hello-world.sh --name Danail
+HELP
+)
+
+common::show_help_if_requested "$@"
+
+name="world"
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -n|--name)
+            [[ $# -ge 2 ]] || common::die "--name requires a value"
+            name="$2"
+            shift 2
+            ;;
+        *)
+            common::die "unknown argument: $1"
+            ;;
+    esac
+done
+
+common::log "Greeting ${name}..."
+echo "Hello, ${name}!"