From d7ca0092677482ef569e1e954b9504f73caae831 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Wed, 15 Jul 2026 22:45:29 -0700
Subject: [PATCH] Document and normalize the public Bash API

---
 README.md                       |  11 ++--
 lib/bash/arg/README.md          |   5 +-
 lib/bash/file/README.md         |  14 +++--
 lib/bash/gh/README.md           |   9 +++
 lib/bash/git/README.md          |  26 ++++----
 lib/bash/git/lib_git.sh         |  38 ++++++------
 lib/bash/git/tests/lib_git.bats |  56 +++++++++---------
 lib/bash/list/README.md         |  14 ++---
 lib/bash/std/README.md          | 102 ++++++++++++++++++++++++++++++++
 lib/bash/std/lib_std.sh         |  40 ++++++-------
 lib/bash/std/tests/lib_std.bats |  18 +++---
 lib/bash/str/README.md          |  20 +++----
 tests/validate.sh               |  22 +++++++
 13 files changed, 259 insertions(+), 116 deletions(-)

diff --git a/README.md b/README.md
index 5d66cd2..6cb2905 100644
--- a/README.md
+++ b/README.md
@@ -25,17 +25,18 @@ Requires Bash 4.2+. On macOS, use Homebrew Bash instead of the system `/bin/bash
   File editing helpers built on the stdlib, including idempotent
   marker-delimited file section updates.
 - [`lib/bash/git/lib_git.sh`](lib/bash/git/README.md)
-  Git helper functions built on the stdlib for lightweight repository
-  inspection, update, and script freshness checks.
+  Git helper functions built on the stdlib for default-branch, worktree,
+  upstream, remote, repository update, and script freshness checks.
 - [`lib/bash/gh/lib_gh.sh`](lib/bash/gh/README.md)
   GitHub CLI helper functions built on the stdlib for command readiness,
-  authentication diagnostics, and checked `gh` execution.
+  authentication diagnostics, remote parsing, API retries, and checked `gh`
+  execution.
 - [`lib/bash/str/lib_str.sh`](lib/bash/str/README.md)
   String helpers built on the stdlib for case conversion, trimming,
   predicates, splitting, and joining.
 - [`lib/bash/arg/lib_arg.sh`](lib/bash/arg/README.md)
-  Argument parsing helpers built on the stdlib for exact flag and value
-  options without hidden parser globals.
+  Argument parsing helpers built on the stdlib for exact flag, scalar value,
+  and repeatable value options without hidden parser globals.
 - [`lib/bash/list/lib_list.sh`](lib/bash/list/README.md)
   Indexed-array helpers built on the stdlib for in-place mutation,
   membership checks, deduplication, and length results.
diff --git a/lib/bash/arg/README.md b/lib/bash/arg/README.md
index 35701f3..07a4eb9 100644
--- a/lib/bash/arg/README.md
+++ b/lib/bash/arg/README.md
@@ -9,8 +9,11 @@ helpers are available.
 
 ## Public API
 
-- `arg_parse`
+- `arg_parse <options_array> <positionals_array> <specs_array> -- [args...]`
   Parse exact flag, value, and repeatable options into caller-owned arrays.
+  Returns `0` on success and `2` for malformed specs, unknown options, or
+  missing values; caller-owned outputs are published only after a successful
+  parse.
 
 ## Usage
 
diff --git a/lib/bash/file/README.md b/lib/bash/file/README.md
index 6c4ccce..5e110eb 100644
--- a/lib/bash/file/README.md
+++ b/lib/bash/file/README.md
@@ -8,14 +8,18 @@ Source `lib/bash/std/lib_std.sh` before this library so logging and error helper
 
 ## Public API
 
-- `file_section_exists`
+- `file_section_exists <target> <start_marker> <end_marker>`
   Inspect whether a valid marker-delimited block is present without changing
-  the file.
-- `file_section_needs_update`
+  the file; returns `0` for present, `1` for absent, and `2` for invalid
+  marker order or counts.
+- `file_section_needs_update <target> <start_marker> <end_marker> [content...]`
   Inspect whether adding or replacing a marker-delimited block would change the
-  file.
-- `update_file_section`
+  file; returns `0` when an update is needed, `1` when unchanged, and `2` for
+  invalid marker order or counts.
+- `update_file_section <target> <start_marker> <end_marker> [-r|content...]`
   Idempotently add, replace, or remove a marker-delimited block inside a file.
+  It mutates the target or symlink referent and returns nonzero on validation or
+  filesystem failure.
 
 ## Usage
 
diff --git a/lib/bash/gh/README.md b/lib/bash/gh/README.md
index bf82bdd..948f27e 100644
--- a/lib/bash/gh/README.md
+++ b/lib/bash/gh/README.md
@@ -43,8 +43,17 @@ import "/path/to/base-bash-libs/lib/bash/gh/lib_gh.sh"
   502/503/504-style failures. `BASE_GH_API_MAX_ATTEMPTS` defaults to `2`.
   `BASE_GH_API_RETRY_DELAY_SECONDS` defaults to `2` when the error output does
   not include a `Retry-After` value.
+
+All GitHub helper failures return a nonzero status and preserve the underlying
+`gh` status where applicable. The remote parser and origin inference helpers
+leave caller-owned result variables unchanged on failure; use `--optional` with
+`gh_infer_repo_from_origin` when a missing or non-GitHub origin is expected.
 ## Boundary
 
 This library is intentionally generic. It does not know about Base branch
 names, issue categories, GitHub Project fields, repository baselines, generated
 pull request bodies, or any other Base workflow policy.
+
+## Tests
+
+BATS coverage lives in `lib/bash/gh/tests/lib_gh.bats`.
diff --git a/lib/bash/git/README.md b/lib/bash/git/README.md
index f6a2c07..c02410a 100644
--- a/lib/bash/git/README.md
+++ b/lib/bash/git/README.md
@@ -8,30 +8,32 @@ Source `lib/bash/std/lib_std.sh` before this library so logging and shared error
 
 ## Public API
 
-- `git_update_repo`
+- `git_update_repo <repo> [allowed_dirty_path] [expected_branch]`
   Update a repository on its detected default branch, optionally allowing tracked changes in one specific path.
-- `git_get_current_branch`
+- `git_get_current_branch <directory> <result_var>`
   Return the current branch name through a caller-provided variable, or `detached head`.
-- `git_detect_default_branch`
+- `git_detect_default_branch <repo> <result_var>`
   Detect a repository's default branch from its remote HEAD and standard local
   fallbacks.
-- `git_worktree_path_for_branch`
+- `git_worktree_path_for_branch <branch> [repo]`
   Print the worktree path attached to a local branch.
-- `git_list_worktree_branches`
+- `git_list_worktree_branches [repo]`
   Print tab-separated worktree path and branch rows.
-- `git_branch_upstream`
+- `git_branch_upstream <repo> <branch>`
   Print the configured upstream ref for a local branch.
-- `git_branch_merged_to_ref`
+- `git_branch_merged_to_ref <repo> <branch> <ref>`
   Check whether a local branch is an ancestor of a ref.
-- `git_list_remote_branches`
+- `git_list_remote_branches [repo]`
   Print branch names from the `origin` remote.
-- `check_script_up_to_date`
+- `check_script_up_to_date [--fetch] <script>`
   Check whether a tracked script appears current relative to its configured upstream.
 
-## Internal Helper
+## Internal Helpers
 
-- `_git_only_path_dirty`
-  Internal predicate used by `git_update_repo` when an allowed dirty path is provided.
+The `__git_*__` functions used by `git_update_repo` are implementation details
+and are not part of the public API. In particular, the path-dirty predicate
+checks whether tracked changes stay within an allowed path, while the update
+helpers manage branch selection, retries, and cleanup.
 
 ## Usage
 
diff --git a/lib/bash/git/lib_git.sh b/lib/bash/git/lib_git.sh
index a752c1a..5b60aaa 100644
--- a/lib/bash/git/lib_git.sh
+++ b/lib/bash/git/lib_git.sh
@@ -156,13 +156,13 @@ git_list_remote_branches() {
 #
 # @param $1 allowed_path Path in repository root that may be dirty (for example "shared").
 #
-_git_path_matches_allowed_path() {
+__git_path_matches_allowed_path__() {
     local path="$1" allowed_path="$2"
 
     [[ "$path" == "$allowed_path" || "$path" == "$allowed_path/"* ]]
 }
 
-_git_only_path_dirty() {
+__git_only_path_dirty__() {
     local allowed_path="$1"
     local status_output line path source_path destination_path
 
@@ -175,13 +175,13 @@ _git_only_path_dirty() {
         if [[ "$path" == *" -> "* ]]; then
             source_path="${path%% -> *}"
             destination_path="${path#* -> }"
-            if ! _git_path_matches_allowed_path "$source_path" "$allowed_path" ||
-                ! _git_path_matches_allowed_path "$destination_path" "$allowed_path"; then
+            if ! __git_path_matches_allowed_path__ "$source_path" "$allowed_path" ||
+                ! __git_path_matches_allowed_path__ "$destination_path" "$allowed_path"; then
                 return 1
             fi
             continue
         fi
-        if ! _git_path_matches_allowed_path "$path" "$allowed_path"; then
+        if ! __git_path_matches_allowed_path__ "$path" "$allowed_path"; then
             return 1
         fi
     done <<< "$status_output"
@@ -189,7 +189,7 @@ _git_only_path_dirty() {
     return 0
 }
 
-_git_expected_update_branch() {
+__git_expected_update_branch__() {
     local configured_branch="${1:-}"
     local default_branch
 
@@ -229,7 +229,7 @@ _git_expected_update_branch() {
     printf '%s\n' main
 }
 
-_git_update_repo_finish() {
+__git_update_repo_finish__() {
     local git_log="${1:-}"
     local should_popd="${2:-false}"
     local status="${3:-0}"
@@ -250,7 +250,7 @@ _git_update_repo_finish() {
     return "$status"
 }
 
-_git_pull_with_retry() {
+__git_pull_with_retry__() {
     local git_log="$1"
     local max_attempts="${BASE_GIT_PULL_MAX_ATTEMPTS:-2}"
     local attempt=1
@@ -318,24 +318,24 @@ git_update_repo() {
     # the submodule update sequence below needs the repository as its cwd.
     if ! pushd "$git_repo" > /dev/null; then
         # If cd fails, we can't proceed.
-        _git_update_repo_finish "$git_log" false 1
+        __git_update_repo_finish__ "$git_log" false 1
         return $?
     fi
 
     # Check if it's a valid git repo
     if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
         log_error "'$git_repo' is not a Git repository."
-        _git_update_repo_finish "$git_log" true 1
+        __git_update_repo_finish__ "$git_log" true 1
         return $?
     fi
 
     # Make sure the current branch is the expected update branch.
     local current_branch
-    expected_branch="$(_git_expected_update_branch "$expected_branch")"
+    expected_branch="$(__git_expected_update_branch__ "$expected_branch")"
     current_branch=$(git rev-parse --abbrev-ref HEAD)
     if [[ "$current_branch" != "$expected_branch" ]]; then
         log_debug "Current branch of '$git_repo' is '${current_branch}', not '$expected_branch'. Skipping update."
-        _git_update_repo_finish "$git_log" true 0
+        __git_update_repo_finish__ "$git_log" true 0
         return $?
     fi
 
@@ -347,37 +347,37 @@ git_update_repo() {
         dirty=true
     fi
     if [[ "$dirty" == true ]]; then
-        if [[ -n "$allowed_dirty_path" ]] && _git_only_path_dirty "$allowed_dirty_path"; then
+        if [[ -n "$allowed_dirty_path" ]] && __git_only_path_dirty__ "$allowed_dirty_path"; then
             log_debug "Repo '$git_repo' only has tracked changes in '$allowed_dirty_path'; attempting git pull."
         else
             log_debug "Repo '$git_repo' has local changes; skipping auto-update. Commit or stash to enable git pull."
-            _git_update_repo_finish "$git_log" true 0
+        __git_update_repo_finish__ "$git_log" true 0
             return $?
         fi
     fi
 
-    if ! _git_pull_with_retry "$git_log"; then
+    if ! __git_pull_with_retry__ "$git_log"; then
         log_error "git pull failed on repo '$git_repo'"
         [[ -s "$git_log" ]] && log_info_file "$git_log"
-        _git_update_repo_finish "$git_log" true 1
+        __git_update_repo_finish__ "$git_log" true 1
         return $?
     fi
 
     # it is safe to run submodule commands even if the repo has no submodules
     if ! std_make_temp_file submodule_log git-submodule-log; then
         log_error "Unable to create temporary submodule log file."
-        _git_update_repo_finish "$git_log" true 1
+        __git_update_repo_finish__ "$git_log" true 1
         return $?
     fi
     if ! { git submodule init && git submodule sync && git submodule update; } >"$submodule_log" 2>&1; then
         log_error "git submodule update failed on repo '$git_repo'"
         [[ -s "$submodule_log" ]] && log_info_file "$submodule_log"
-        _git_update_repo_finish "$git_log" true 1 "$submodule_log"
+        __git_update_repo_finish__ "$git_log" true 1 "$submodule_log"
         return $?
     fi
 
     log_debug "Git repo '$git_repo' updated to latest '$expected_branch'"
-    _git_update_repo_finish "$git_log" true 0 "$submodule_log"
+    __git_update_repo_finish__ "$git_log" true 0 "$submodule_log"
     return $?
 }
 
diff --git a/lib/bash/git/tests/lib_git.bats b/lib/bash/git/tests/lib_git.bats
index 89e662e..2d0e3b5 100644
--- a/lib/bash/git/tests/lib_git.bats
+++ b/lib/bash/git/tests/lib_git.bats
@@ -377,7 +377,7 @@ EOF
     [[ "$output" != *"not 'main'"* ]]
 }
 
-@test "_git_expected_update_branch returns main when origin has main" {
+@test "__git_expected_update_branch__ returns main when origin has main" {
     local repo="$TEST_TMPDIR/repo"
     local branch
 
@@ -389,13 +389,13 @@ EOF
     git -C "$repo" branch -D main >/dev/null 2>&1
 
     pushd "$repo" >/dev/null
-    branch="$(_git_expected_update_branch)"
+    branch="$(__git_expected_update_branch__)"
     popd >/dev/null
 
     [ "$branch" = "main" ]
 }
 
-@test "_git_expected_update_branch returns master when origin only has master" {
+@test "__git_expected_update_branch__ returns master when origin only has master" {
     local repo="$TEST_TMPDIR/repo"
     local branch
 
@@ -407,26 +407,26 @@ EOF
     git -C "$repo" branch -D main >/dev/null 2>&1
 
     pushd "$repo" >/dev/null
-    branch="$(_git_expected_update_branch)"
+    branch="$(__git_expected_update_branch__)"
     popd >/dev/null
 
     [ "$branch" = "master" ]
 }
 
-@test "_git_expected_update_branch falls back to main without main or master refs" {
+@test "__git_expected_update_branch__ falls back to main without main or master refs" {
     local repo="$TEST_TMPDIR/repo"
     local branch
 
     init_git_repo "$repo"
 
     pushd "$repo" >/dev/null
-    branch="$(_git_expected_update_branch)"
+    branch="$(__git_expected_update_branch__)"
     popd >/dev/null
 
     [ "$branch" = "main" ]
 }
 
-@test "_git_only_path_dirty accepts multiple dirty files under an allowed directory" {
+@test "__git_only_path_dirty__ accepts multiple dirty files under an allowed directory" {
     local repo="$TEST_TMPDIR/repo"
     local rc
 
@@ -439,14 +439,14 @@ EOF
     printf 'local two\n' > "$repo/shared/two.txt"
 
     pushd "$repo" >/dev/null
-    _git_only_path_dirty "shared"
+    __git_only_path_dirty__ "shared"
     rc=$?
     popd >/dev/null
 
     [ "$rc" -eq 0 ]
 }
 
-@test "_git_only_path_dirty does not treat sibling path prefixes as allowed" {
+@test "__git_only_path_dirty__ does not treat sibling path prefixes as allowed" {
     local repo="$TEST_TMPDIR/repo"
     local rc
 
@@ -460,7 +460,7 @@ EOF
 
     pushd "$repo" >/dev/null
     set +e
-    _git_only_path_dirty "shared"
+    __git_only_path_dirty__ "shared"
     rc=$?
     set -e
     popd >/dev/null
@@ -468,7 +468,7 @@ EOF
     [ "$rc" -eq 1 ]
 }
 
-@test "_git_only_path_dirty rejects renames from outside the allowed path" {
+@test "__git_only_path_dirty__ rejects renames from outside the allowed path" {
     local repo="$TEST_TMPDIR/repo"
     local rc
 
@@ -480,7 +480,7 @@ EOF
 
     pushd "$repo" >/dev/null
     set +e
-    _git_only_path_dirty "shared"
+    __git_only_path_dirty__ "shared"
     rc=$?
     set -e
     popd >/dev/null
@@ -488,7 +488,7 @@ EOF
     [ "$rc" -eq 1 ]
 }
 
-@test "_git_only_path_dirty accepts renames inside the allowed path" {
+@test "__git_only_path_dirty__ accepts renames inside the allowed path" {
     local repo="$TEST_TMPDIR/repo"
     local rc
 
@@ -499,7 +499,7 @@ EOF
     git -C "$repo" mv shared/one.txt shared/two.txt
 
     pushd "$repo" >/dev/null
-    _git_only_path_dirty "shared"
+    __git_only_path_dirty__ "shared"
     rc=$?
     popd >/dev/null
 
@@ -549,25 +549,25 @@ EOF
     [[ "$(cat "$registration_file")" == *"git_log."* ]]
 }
 
-@test "_git_update_repo_finish removes temp log after success" {
+@test "__git_update_repo_finish__ removes temp log after success" {
     local git_log="$TEST_TMPDIR/git.log"
 
     printf 'pull output\n' > "$git_log"
 
-    bats_run _git_update_repo_finish "$git_log" false 0
+    bats_run __git_update_repo_finish__ "$git_log" false 0
 
     [ "$status" -eq 0 ]
     [ ! -e "$git_log" ]
 }
 
-@test "_git_update_repo_finish preserves an existing RETURN trap" {
+@test "__git_update_repo_finish__ preserves an existing RETURN trap" {
     local git_log="$TEST_TMPDIR/git.log"
     local return_trap
 
     printf 'pull output\n' > "$git_log"
     trap 'printf "outer return trap\n"' RETURN
 
-    bats_run _git_update_repo_finish "$git_log" false 0
+    bats_run __git_update_repo_finish__ "$git_log" false 0
     return_trap="$(trap -p RETURN)"
     trap - RETURN
 
@@ -576,7 +576,7 @@ EOF
     [ ! -e "$git_log" ]
 }
 
-@test "_git_update_repo_finish unregisters removed temp logs" {
+@test "__git_update_repo_finish__ unregisters removed temp logs" {
     local git_log="$TEST_TMPDIR/git.log"
     local unregister_file="$TEST_TMPDIR/unregistered-paths.txt"
 
@@ -587,7 +587,7 @@ EOF
         __orig_std_unregister_cleanup_path "$@"
     }
 
-    _git_update_repo_finish "$git_log" false 0
+    __git_update_repo_finish__ "$git_log" false 0
     unset -f std_unregister_cleanup_path __orig_std_unregister_cleanup_path
 
     [ "$(cat "$unregister_file")" = "$git_log" ]
@@ -616,7 +616,7 @@ EOF
     ! compgen -G "$TEST_TMPDIR/git-submodule-log.*" >/dev/null
 }
 
-@test "_git_pull_with_retry retries once after a transient pull failure" {
+@test "__git_pull_with_retry__ retries once after a transient pull failure" {
     local git_log="$TEST_TMPDIR/git.log"
     local pull_count="$TEST_TMPDIR/pull-count"
 
@@ -635,7 +635,7 @@ EOF
         command git "$@"
     }
 
-    bats_run _git_pull_with_retry "$git_log"
+    bats_run __git_pull_with_retry__ "$git_log"
     unset -f git
 
     [ "$status" -eq 0 ]
@@ -644,7 +644,7 @@ EOF
     [ "$(cat "$git_log")" = "pull attempt 2" ]
 }
 
-@test "_git_pull_with_retry honors configured max attempts" {
+@test "__git_pull_with_retry__ honors configured max attempts" {
     local git_log="$TEST_TMPDIR/git.log"
     local pull_count="$TEST_TMPDIR/pull-count"
 
@@ -663,7 +663,7 @@ EOF
         command git "$@"
     }
 
-    BASE_GIT_PULL_MAX_ATTEMPTS=3 bats_run _git_pull_with_retry "$git_log"
+    BASE_GIT_PULL_MAX_ATTEMPTS=3 bats_run __git_pull_with_retry__ "$git_log"
     unset -f git
 
     [ "$status" -eq 0 ]
@@ -672,7 +672,7 @@ EOF
     [ "$(cat "$git_log")" = "pull attempt 3" ]
 }
 
-@test "_git_pull_with_retry falls back for invalid configured max attempts" {
+@test "__git_pull_with_retry__ falls back for invalid configured max attempts" {
     local git_log="$TEST_TMPDIR/git.log"
     local max_attempts
     local pull_count="$TEST_TMPDIR/pull-count"
@@ -695,7 +695,7 @@ EOF
         printf '0\n' > "$pull_count"
         : > "$git_log"
 
-        BASE_GIT_PULL_MAX_ATTEMPTS="$max_attempts" bats_run _git_pull_with_retry "$git_log"
+        BASE_GIT_PULL_MAX_ATTEMPTS="$max_attempts" bats_run __git_pull_with_retry__ "$git_log"
 
         [ "$status" -eq 0 ]
         [ "$(cat "$pull_count")" = "2" ]
@@ -706,7 +706,7 @@ EOF
     unset -f git
 }
 
-@test "_git_pull_with_retry fails after two pull attempts" {
+@test "__git_pull_with_retry__ fails after two pull attempts" {
     local git_log="$TEST_TMPDIR/git.log"
     local pull_count="$TEST_TMPDIR/pull-count"
 
@@ -724,7 +724,7 @@ EOF
         command git "$@"
     }
 
-    bats_run _git_pull_with_retry "$git_log"
+    bats_run __git_pull_with_retry__ "$git_log"
     unset -f git
 
     [ "$status" -eq 1 ]
diff --git a/lib/bash/list/README.md b/lib/bash/list/README.md
index e50fa79..2567cf0 100644
--- a/lib/bash/list/README.md
+++ b/lib/bash/list/README.md
@@ -9,17 +9,17 @@ helpers are available.
 
 ## Public API
 
-- `list_append`
+- `list_append <array> [value...]`
   Append one or more values to a named indexed array.
-- `list_prepend`
+- `list_prepend <array> [value...]`
   Prepend one or more values to a named indexed array.
-- `list_remove`
+- `list_remove <value> <array>`
   Remove all exact matches from a named indexed array.
-- `list_contains`
+- `list_contains <value> <array>`
   Predicate that checks whether a named indexed array contains a value.
-- `list_unique`
+- `list_unique <result_array> <source_array>`
   Store first-seen unique values in a named result array.
-- `list_length`
+- `list_length <result_var> <source_array>`
   Store an array length in a named result variable.
 
 ## Usage
@@ -46,4 +46,4 @@ caller state.
 
 ## Tests
 
-BATS coverage lives in `tests/lib_list.bats`.
+BATS coverage lives in `lib/bash/list/tests/lib_list.bats`.
diff --git a/lib/bash/std/README.md b/lib/bash/std/README.md
index 93a0355..54f90bc 100644
--- a/lib/bash/std/README.md
+++ b/lib/bash/std/README.md
@@ -41,6 +41,108 @@ The library improves Bash-based scripting in a few practical ways:
 The goal is not to hide Bash. The goal is to make scripts fail in ways a user
 or developer can understand.
 
+## Public API Reference
+
+The functions below are the supported `lib_std.sh` API. Functions beginning
+with `__` are internal implementation details and are intentionally omitted.
+Functions that return a value through a variable name mutate that caller-owned
+variable only after validating it. Unless noted otherwise, predicates return
+zero for success and nonzero for a false or invalid condition.
+
+### Runtime and Imports
+
+- `base_bash_libs_require_version <version>`: exits with a diagnostic when the
+  loaded package version is older than the requested dotted numeric version.
+- `check_bash_version`: returns zero for Bash 4.2 or newer and reports the
+  required version otherwise.
+- `is_interactive`: returns zero when stdin and stderr are interactive TTYs.
+- `import <path>`: sources a relative path from `__SCRIPT_DIR__` or an
+  absolute path; exits when the library cannot be sourced.
+- `get_my_source_dir <result_var>`: stores the caller script directory in a
+  validated variable without printing it.
+
+### Logging and Messages
+
+- `set_log_level [-l <logger>] <level>`: changes a logger threshold and returns
+  nonzero for an unknown level or logger option error.
+- `log_fatal`, `log_error`, `log_warn`, `log_info`, `log_debug`,
+  `log_verbose <message...>`: write a structured message to stderr at the
+  named level.
+- `log_info_file`, `log_debug_file`, `log_verbose_file [-l <logger>] <file>`:
+  log a file's contents at the requested level when that level is enabled.
+- `log_info_enter`, `log_debug_enter`, `log_verbose_enter` and
+  `log_info_leave`, `log_debug_leave`, `log_verbose_leave`: log the current
+  function boundary without arguments.
+- `print_error`, `print_warn`, `print_info`, `print_success <message...>`:
+  write an unstructured user-facing message to stderr.
+- `print_bold`, `print_message <message...>`: write an unstructured message to
+  stdout; `print_bold` applies terminal formatting when enabled.
+- `print_tty <message...>`: writes only when stdout is attached to a TTY.
+- `dump_trace`: writes the current Bash call stack to stderr.
+
+### Command and Error Control
+
+- `std_run [policy options] <command> [args...]`: runs an argument-preserving
+  command, returning or exiting with its status according to the selected
+  policy. See [Running Commands Safely](#running-commands-safely).
+- `exit_if_error <status> [message...]`: returns for zero and exits with the
+  supplied status after logging a message for nonzero status.
+- `fatal_error <message...>`: logs a fatal error, prints a trace, and exits.
+- `is_dry_run`: returns zero when `DRY_RUN` or `dry_run` is truthy.
+
+### PATH and Filesystem Helpers
+
+- `add_to_path [-p] [-n] <directory...>`: prepends or appends existing PATH
+  entries, optionally allowing missing directories; returns nonzero on invalid
+  options or update failure.
+- `dedupe_path`: removes duplicate and empty PATH entries in place.
+- `print_path`: prints one PATH entry per line.
+- `safe_mkdir [-p] <directory...>`, `safe_touch <file...>`,
+  `safe_truncate <file...>`, and `safe_cd <directory>`: perform the named
+  filesystem operation with explicit diagnostics and failure statuses.
+- `safe_unalias <name...>`: removes aliases when present and ignores names that
+  are not aliases.
+
+### Cleanup and Temporary State
+
+- `std_register_cleanup_hook <function>`,
+  `std_unregister_cleanup_hook <function>`: add or remove a named cleanup
+  function from the shared exit dispatcher.
+- `std_register_cleanup_path <absolute_path...>`,
+  `std_unregister_cleanup_path <absolute_path...>`: add or remove safe paths
+  from exit cleanup; invalid paths are rejected.
+- `std_make_temp_file [--keep] [result_var] [prefix]` and
+  `std_make_temp_dir [--keep] [result_var] [prefix]`: create a temporary path,
+  store it in the caller variable, and register it for cleanup unless
+  `--keep` is used.
+
+### Introspection and Assertions
+
+- `std_command_path <result_var> <command>`: stores the resolved executable
+  path or returns nonzero when the command is unavailable.
+- `std_function_exists <name>`: returns zero when a Bash function exists.
+- `assert_function_exists <name...>`: returns nonzero and logs missing
+  functions.
+- `assert_variable_name <name...>`: validates Bash variable names.
+- `assert_indexed_array <name...>` and `assert_associative_array <name...>`:
+  validate caller-owned array declarations.
+- `assert_not_null <variable...>`: validates that named variables are set and
+  non-empty without treating values as variable names accidentally.
+- `assert_integer <value...>` and `assert_integer_range <value> <min> <max>`:
+  validate decimal integers and inclusive bounds.
+- `assert_arg_count <actual> <expected> [max]`: validates exact or ranged
+  positional argument counts.
+- `assert_command_exists <command...>`, `assert_file_exists <path...>`,
+  `assert_executable <path...>`, and `assert_dir_exists <path...>`: validate
+  required commands or filesystem objects.
+
+### Interactive Helpers
+
+- `ask_yes_no <prompt>`: prompts on a TTY and returns the user's yes/no
+  decision.
+- `wait_for_enter [prompt]`: waits for Enter on a TTY and returns nonzero when
+  no usable terminal is available.
+
 ## Loading The Library
 
 Standalone scripts can source the library directly:
diff --git a/lib/bash/std/lib_std.sh b/lib/bash/std/lib_std.sh
index 1d8871f..39049d5 100644
--- a/lib/bash/std/lib_std.sh
+++ b/lib/bash/std/lib_std.sh
@@ -592,13 +592,13 @@ set_log_level() {
 }
 
 #
-# _print_log - Core and private log printing logic.
+# __print_log__ - Core and private log printing logic.
 #
 # This is the internal engine for the logging functions. It formats the log
 # message with a timestamp, log level, and source location. It should not
 # be called directly; use the `log_*` helper functions instead.
 #
-_print_log() {
+__print_log__() {
     local in_level="${1-}"
     [[ -n "$in_level" ]] || return 1
     shift
@@ -630,11 +630,11 @@ _print_log() {
 }
 
 #
-# _print_log_file - Core function for logging the contents of a file.
+# __print_log_file__ - Core function for logging the contents of a file.
 #
 # Internal helper to be called by `log_info_file`, etc.
 #
-_print_log_file()   {
+__print_log_file__()   {
     local in_level="${1-}"
     [[ -n "$in_level" ]] || return 1
     shift
@@ -652,7 +652,7 @@ _print_log_file()   {
     log_level_set="${_loggers_level_map[$logger]}"
     if [[ $log_level_set ]]; then
         if ((log_level_set >= log_level)) && [[ -f $file ]]; then
-            _print_log "$in_level" -l "$logger" "Contents of file '$file':"
+            __print_log__ "$in_level" -l "$logger" "Contents of file '$file':"
             cat -- "$file" >&2
         fi
     else
@@ -666,29 +666,29 @@ _print_log_file()   {
 # Public logging functions.
 # These are the primary functions scripts should use for logging.
 #
-log_fatal()   { _print_log FATAL   "$@"; }
-log_error()   { _print_log ERROR   "$@"; }
-log_warn()    { _print_log WARN    "$@"; }
-log_info()    { _print_log INFO    "$@"; }
-log_debug()   { _print_log DEBUG   "$@"; }
-log_verbose() { _print_log VERBOSE "$@"; }
+log_fatal()   { __print_log__ FATAL   "$@"; }
+log_error()   { __print_log__ ERROR   "$@"; }
+log_warn()    { __print_log__ WARN    "$@"; }
+log_info()    { __print_log__ INFO    "$@"; }
+log_debug()   { __print_log__ DEBUG   "$@"; }
+log_verbose() { __print_log__ VERBOSE "$@"; }
 
 #
 # Public functions for logging the content of a file.
 #
-log_info_file()    { _print_log_file INFO    "$@"; }
-log_debug_file()   { _print_log_file DEBUG   "$@"; }
-log_verbose_file() { _print_log_file VERBOSE "$@"; }
+log_info_file()    { __print_log_file__ INFO    "$@"; }
+log_debug_file()   { __print_log_file__ DEBUG   "$@"; }
+log_verbose_file() { __print_log_file__ VERBOSE "$@"; }
 
 #
 # Public functions for logging function entry and exit points.
 #
-log_info_enter()    { _print_log INFO    "Entering function ${FUNCNAME[1]}"; }
-log_debug_enter()   { _print_log DEBUG   "Entering function ${FUNCNAME[1]}"; }
-log_verbose_enter() { _print_log VERBOSE "Entering function ${FUNCNAME[1]}"; }
-log_info_leave()    { _print_log INFO    "Leaving function ${FUNCNAME[1]}";  }
-log_debug_leave()   { _print_log DEBUG   "Leaving function ${FUNCNAME[1]}";  }
-log_verbose_leave() { _print_log VERBOSE "Leaving function ${FUNCNAME[1]}";  }
+log_info_enter()    { __print_log__ INFO    "Entering function ${FUNCNAME[1]}"; }
+log_debug_enter()   { __print_log__ DEBUG   "Entering function ${FUNCNAME[1]}"; }
+log_verbose_enter() { __print_log__ VERBOSE "Entering function ${FUNCNAME[1]}"; }
+log_info_leave()    { __print_log__ INFO    "Leaving function ${FUNCNAME[1]}";  }
+log_debug_leave()   { __print_log__ DEBUG   "Leaving function ${FUNCNAME[1]}";  }
+log_verbose_leave() { __print_log__ VERBOSE "Leaving function ${FUNCNAME[1]}";  }
 
 #
 # Simple print routines that do not prefix messages with timestamps or levels.
diff --git a/lib/bash/std/tests/lib_std.bats b/lib/bash/std/tests/lib_std.bats
index fb5d881..4c786e0 100644
--- a/lib/bash/std/tests/lib_std.bats
+++ b/lib/bash/std/tests/lib_std.bats
@@ -587,18 +587,18 @@ EOF
     [[ "$(cat "$stderr_file")" == *"Unknown log level 'NOPE' for logger 'custom'"* ]]
 }
 
-@test "_print_log requires a log level" {
-    ! _print_log
+@test "__print_log__ requires a log level" {
+    ! __print_log__
 }
 
-@test "_print_log formats timestamps without command substitution" {
+@test "__print_log__ formats timestamps without command substitution" {
     bats_run grep -nE 'timestamp="\$\((TZ=UTC0 )?printf' "$STDLIB_PATH"
 
     [ "$status" -eq 1 ]
     [ "$output" = "" ]
 }
 
-@test "_print_log emits structured records through one final printf" {
+@test "__print_log__ emits structured records through one final printf" {
     bats_run grep -nF 'printf '"'"'%b%s%b\n'"'"' "$color" "$log_line" "$COLOR_OFF"' "$STDLIB_PATH"
 
     [ "$status" -eq 0 ]
@@ -629,7 +629,7 @@ EOF
     [[ "$(cat "$stderr_file")" == *"VERBOSE"* ]]
 }
 
-@test "_print_log uses local timestamps by default" {
+@test "__print_log__ uses local timestamps by default" {
     local stderr_file="$TEST_TMPDIR/log-local-time.err"
     local expected_before expected_after output
 
@@ -642,7 +642,7 @@ EOF
     [[ "$output" == *"local timestamp"* ]]
 }
 
-@test "_print_log honors LOG_UTC for Bash timestamps" {
+@test "__print_log__ honors LOG_UTC for Bash timestamps" {
     local stderr_file="$TEST_TMPDIR/log-utc-time.err"
     local expected_before expected_after output local_before local_after
 
@@ -658,7 +658,7 @@ EOF
     [[ "$output" == *"utc timestamp"* ]]
 }
 
-@test "_print_log bounds stdlib caller stack walking" {
+@test "__print_log__ bounds stdlib caller stack walking" {
     local script="$TEST_TMPDIR/log-bounded-caller.sh"
     local caller_log="$TEST_TMPDIR/caller-count.log"
 
@@ -675,7 +675,7 @@ caller() {
     fi
     printf '%s stdlib_frame %s\n' "\$1" "\$__LIB_STD_PATH__"
 }
-_print_log INFO "bounded stack walk" >/dev/null
+__print_log__ INFO "bounded stack walk" >/dev/null
 printf 'caller_count=%s\n' "\$(( \$(wc -l < "\$caller_log") ))"
 EOF
 
@@ -699,7 +699,7 @@ EOF
     [[ "$(cat "$stderr_file")" == *"Contents of file '$target':"* ]]
     [[ "$(cat "$stderr_file")" == *"hello file"* ]]
 
-    _print_log_file INFO -l missing "$target" 2>"$stderr_file"
+    __print_log_file__ INFO -l missing "$target" 2>"$stderr_file"
     [[ "$(cat "$stderr_file")" == *"Unknown logger 'missing'"* ]]
     [[ "$(cat "$stderr_file")" != *"lib_std.sh:"* ]]
     [[ "$(cat "$stderr_file")" != *":0 "* ]]
diff --git a/lib/bash/str/README.md b/lib/bash/str/README.md
index ba17c2f..39dd09a 100644
--- a/lib/bash/str/README.md
+++ b/lib/bash/str/README.md
@@ -9,25 +9,25 @@ helpers are available.
 
 ## Public API
 
-- `str_lower`
+- `str_lower <result_var>`
   Convert a named variable's value to lowercase in place.
-- `str_upper`
+- `str_upper <result_var>`
   Convert a named variable's value to uppercase in place.
-- `str_trim`
+- `str_trim <result_var>`
   Remove leading and trailing whitespace from a named variable in place.
-- `str_ltrim`
+- `str_ltrim <result_var>`
   Remove leading whitespace from a named variable in place.
-- `str_rtrim`
+- `str_rtrim <result_var>`
   Remove trailing whitespace from a named variable in place.
-- `str_contains`
+- `str_contains <value> <substring>`
   Return success when a string contains a substring.
-- `str_starts_with`
+- `str_starts_with <value> <prefix>`
   Return success when a string starts with a prefix.
-- `str_ends_with`
+- `str_ends_with <value> <suffix>`
   Return success when a string ends with a suffix.
-- `str_split`
+- `str_split <result_array> <value> <separator>`
   Split a string by a delimiter into a caller-provided array variable.
-- `str_join`
+- `str_join <result_var> <separator> <source_array>`
   Join a caller-provided array variable into a caller-provided result variable.
 
 ## Usage
diff --git a/tests/validate.sh b/tests/validate.sh
index 6fc3a6c..5600346 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -93,6 +93,28 @@ for file in "${required_files[@]}"; do
   }
 done
 
+readme_test_paths=(
+  "lib/bash/std/README.md|lib/bash/std/tests/lib_std.bats"
+  "lib/bash/file/README.md|lib/bash/file/tests/lib_file.bats"
+  "lib/bash/git/README.md|lib/bash/git/tests/lib_git.bats"
+  "lib/bash/gh/README.md|lib/bash/gh/tests/lib_gh.bats"
+  "lib/bash/str/README.md|lib/bash/str/tests/lib_str.bats"
+  "lib/bash/arg/README.md|lib/bash/arg/tests/lib_arg.bats"
+  "lib/bash/list/README.md|lib/bash/list/tests/lib_list.bats"
+)
+
+for mapping in "${readme_test_paths[@]}"; do
+  IFS='|' read -r readme test_path <<<"$mapping"
+  [[ -f "$test_path" ]] || {
+    printf 'Documented BATS path does not exist: %s\n' "$test_path" >&2
+    exit 1
+  }
+  grep -F "$test_path" "$readme" >/dev/null || {
+    printf 'README does not document its BATS path: %s -> %s\n' "$readme" "$test_path" >&2
+    exit 1
+  }
+done
+
 printf 'Repository baseline is present.\n'
 
 run_stage "strict-mode guard" check_no_strict_mode || exit $?