docs: add repo map (tree) and generating script

scripts/gen-repo-map.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+OUTPUT_PATH="${1:-${REPO_ROOT}/docs/repo-map.md}"
+
+if ! command -v tree >/dev/null 2>&1; then
+  echo "error: the 'tree' command is required to regenerate the repo map. Install it (e.g., 'sudo pacman -S tree') and re-run this script." >&2
+  exit 1
+fi
+
+EXCLUDES='target|\\.git|\\.github|node_modules|dist|images|themes|dev|\\.venv'
+
+TMP_FILE="$(mktemp)"
+trap 'rm -f "${TMP_FILE}"' EXIT
+
+pushd "${REPO_ROOT}" >/dev/null
+tree -a -L 2 --dirsfirst --prune -I "${EXCLUDES}" > "${TMP_FILE}"
+popd >/dev/null
+
+{
+  printf '# Repo Map\n\n'
+  printf '> Generated by `scripts/gen-repo-map.sh`. Regenerate when the layout changes.\n\n'
+  printf '```text\n'
+  cat "${TMP_FILE}"
+  printf '```\n'
+} > "${OUTPUT_PATH}"
+
+echo "Repo map written to ${OUTPUT_PATH}"