Add initial scripts and project conventions

templates/script-template.md

@@ -0,0 +1,48 @@
+# <script-name>.sh
+
+<One or two sentence summary — same tone as the README entry, but here you
+can go into more detail immediately.>
+
+## What it does
+
+<Explain what the script does step by step, in prose. If it touches
+external systems (network, filesystem paths outside the repo, remote
+hosts, cron), say so explicitly here — a reader deciding whether to run
+this needs to know the blast radius before they run it.>
+
+## Requirements
+
+- <External commands the script depends on, e.g. `curl`, `jq`, `ssh`>
+- <Any required environment variables, config files, or permissions>
+
+## Usage
+
+```bash
+./<path-to-script>/<script-name>.sh [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-h`, `--help` | Show help message and exit |
+| `<flag>` | <description> |
+
+## Examples
+
+```bash
+# <what this example does>
+./<script-name>.sh
+```
+
+```bash
+# <what this example does>
+./<script-name>.sh --example value
+```
+
+## Notes / Caveats
+
+<Anything non-obvious: destructive operations, required order relative to
+other scripts, assumptions about the environment it runs in, known
+limitations. If there's nothing notable, delete this section — don't
+leave a placeholder "None" in real docs.>

templates/script-template.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# <script-name>.sh — <one-line description of what this script does>
+#
+# Full documentation: see <script-name>.md in this same folder.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+# Adjust the relative depth below to match this script's folder nesting
+# relative to lib/ — e.g. "../../lib/common.sh" if the script is two
+# folders deep from the repo root.
+source "${SCRIPT_DIR}/../lib/common.sh"
+
+SCRIPT_HELP=$(cat <<'HELP'
+Usage: <script-name>.sh [OPTIONS]
+
+<One paragraph explaining what the script does and when to use it.>
+
+Options:
+  -h, --help        Show this help message and exit
+  <-x, --example>   <describe other options here>
+
+Examples:
+  ./<script-name>.sh
+  ./<script-name>.sh --example value
+HELP
+)
+
+# --help must be checked before any other argument parsing.
+common::show_help_if_requested "$@"
+
+# --- Argument parsing (if the script takes options) ---
+# TODO: parse "$@" here if needed. Use common::die for invalid arguments,
+# not a raw echo+exit, so error formatting stays consistent.
+
+# --- Script logic ---
+
+common::log "Starting <script-name>..."
+
+# TODO: actual script logic goes here.
+
+common::log "Done."