docs: document make-run, fix paths stale since 0.2.0, and gate both

.pre-commit-config.yaml

@@ -31,3 +31,13 @@ repos:
         language: system
         pass_filenames: false
         types: [markdown]
+
+      # always_run, not types: [markdown] — what breaks this gate is adding a
+      # script under src/just_bashit/, and that commit touches no markdown at
+      # all. A markdown-scoped hook would have stayed silent for make-run.
+      - id: docs-coverage
+        name: docs-coverage
+        entry: make -s docs-coverage
+        language: system
+        pass_filenames: false
+        always_run: true

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+### Added
+
+- **`make-run` is documented.** It shipped in 0.4.0 as the headline feature
+    and appeared in no page, no nav entry, and no line of the README — so the
+    one tool whose whole purpose is ending hand-transcribed commands could
+    only be found by reading its source. New page under Libraries covering
+    `mk-var`, `mk-vars`, `mk-run`, `mk-has` and `mk-origin`, the
+    undefined-is-not-empty rule, and why the queries avoid `--eval`.
+
+- **`docs-coverage` gate.** Two invariants, one for each way the above went
+    unnoticed: every file shipped in `src/just_bashit/` must be named
+    somewhere in the docs, and every page under `docs/` must be reachable
+    from `zensical.toml`'s nav. `docs/changelog.md` is excluded as a mention
+    source — it records every script ever added, so counting it would pass
+    everything the moment it was released. Dispatched from pre-commit with
+    `always_run`, so it runs inside `make lint` (which CI runs) and fires on
+    commits touching no markdown, which is what adding a script looks like.
+
+### Fixed
+
+- **The docs pointed at `src/`, where nothing has lived since 0.2.0.**
+    Scripts moved to `src/just_bashit/` for Python packaging and the docs kept
+    the old path, so every `. just-bashit/src/datetime.sh` in the README, the
+    getting-started guide, and all ten library pages failed for anyone who
+    copied one — including from an unpacked release tarball, which carries the
+    current layout.
+
+- **The README described a package layout that no longer existed**, and never
+    mentioned installation, the `jb` / `jbx` / `jb-inspect` entry points, or
+    `make-run`.
+
 ## [0.4.0] - 2026-08-06
 
 ### Added

Makefile

@@ -63,6 +63,19 @@ else \
 fi
 endef
 
+# ── docs coverage ─────────────────────────────────────────────────────────────
+# A repo-local target, so it needs naming here or help-check reports a rule
+# that help does not list.
+#
+# Dispatched from .pre-commit-config.yaml rather than DOCS_CHECK_PRE_CMDS: CI
+# runs `make test`, `make coverage` and `make lint` — not `make docs-check` —
+# so a docs gate hung off docs-check would be local-only, which is how a rule
+# nobody enforces sits on main indefinitely.
+LOCAL_TARGETS += docs-coverage
+
+docs-coverage: ## Verify every shipped script is documented and in the nav
+	@bash scripts/docs_coverage.sh
+
 # ── all ───────────────────────────────────────────────────────────────────────
 # Lint first: shellcheck and shfmt are seconds, the bats suite is minutes.
 #

README.md

@@ -17,14 +17,31 @@ Evolving set of [shfmt](https://github.com/mvdan/sh#shfmt)-conformant, [bats](ht
 
 **[Documentation](https://just-buildit.github.io/just-bashit/)**
 
+## Install
+
+```bash
+uv tool install just-bashit   # or: pip install just-bashit
+```
+
+That puts three commands on `PATH`: `jb` (top-level CLI), `jbx` (ephemeral
+runner — fetch a script, call a function, discard), and `jb-inspect`.
+
+Nothing needs installing to *use* a script. `jbx` fetches on demand:
+
+```bash
+jbx install-deps                              # install this repo's packages
+jbx make-run mk-var -C ~/doppler DOCS_BUILD_CMD
+```
+
 ## Getting Started
 
-A release package contains shell libraries along with a script and two function templates for developing your own tools.
+A release package contains shell libraries along with script and function
+templates for developing your own tools.
 
 ```
 just-bashit
     +--README.md
-    +--src/
+    +--src/just_bashit/
     |   +-- datetime.sh
     |   +-- environment.sh
     :   :
@@ -36,7 +53,23 @@ just-bashit
 Some libraries depend on others so it's best to use the whole package and source whatever you need, for example:
 
 ```bash
-. just-bashit/src/datetime.sh # contains iso-8601-basic()
+. just-bashit/src/just_bashit/datetime.sh # contains iso-8601-basic()
 iso-8601-basic -d '10:32 AM EDT Jan 5 1982'
 19820105T143200Z
 ```
+
+## Ask a repo what its commands are
+
+`make-run` resolves a repository's targets and command variables from that
+repository's own `Makefile`, so nothing downstream has to carry a second copy
+of a command that will drift from it:
+
+```bash
+jbx make-run mk-var -C ~/doppler DOCS_BUILD_CMD
+# uv run --group docs zensical build --clean --strict
+
+jbx make-run mk-run -C ~/doppler docs   # run it, whatever it is
+```
+
+An **undefined** variable is an error, never an empty string — see
+[the docs](https://just-buildit.github.io/just-bashit/libraries/make-run/).

docs/getting-started.md

@@ -35,8 +35,8 @@ All libraries **must be sourced**, not executed. Each file enforces this at
 load time and will exit with an error if you try to run it directly.
 
 ```bash
-. just-bashit/src/logging.sh   # correct
-bash just-bashit/src/logging.sh # error: "This file must be sourced."
+. just-bashit/src/just_bashit/logging.sh   # correct
+bash just-bashit/src/just_bashit/logging.sh # error: "This file must be sourced."
 ```
 
 Some libraries depend on others (`logging.sh` sources `format.sh`,
@@ -49,7 +49,7 @@ chain resolves automatically from relative paths.
 Every function accepts `-h`:
 
 ```bash
-. just-bashit/src/datetime.sh
+. just-bashit/src/just_bashit/datetime.sh
 iso-8601-basic -h
 ```
 

docs/index.md

@@ -29,7 +29,7 @@ Download the latest release, extract it, and source whatever you need:
 
 ```bash
 tar xf just-bashit.tar.gz
-. just-bashit/src/datetime.sh
+. just-bashit/src/just_bashit/datetime.sh
 iso-8601-basic
 # 20260522T143200Z
 ```
@@ -61,6 +61,7 @@ package and source individual files from it.
 | [file](libraries/file.md)               | `add-line` `remove-line` `add-contents`                 |
 | [format](libraries/format.md)           | `trim-from` `color-echo`                                |
 | [logging](libraries/logging.md)         | `log` `log-wait`                                        |
+| [make-run](libraries/make-run.md)       | `mk-var` `mk-vars` `mk-run` `mk-has` `mk-origin`        |
 | [match](libraries/match.md)             | `is-number`                                             |
 | [network](libraries/network.md)         | `test-internet-access`                                  |
 | [path](libraries/path.md)               | `get-scriptpath` `set-scriptpath`                       |

docs/inspect.md

@@ -263,5 +263,5 @@ jbx inspect -v 2>&1 | head
 jbx inspect | diff jb.versions -
 
 # Pin script to a specific commit for reproducible CI output
-jbx gh:just-buildit/just-bashit/src/inspect.sh@abc1234 -w
+jbx gh:just-buildit/just-bashit/src/just_bashit/inspect.sh@abc1234 -w
 ```

docs/install-deps.md

@@ -282,7 +282,7 @@ jbx install-deps --template deps.toml  # write to file
 ### Pin to a specific script commit for reproducible CI
 
 ```bash
-jbx gh:just-buildit/just-bashit/src/install-deps.sh@abc1234
+jbx gh:just-buildit/just-bashit/src/just_bashit/install-deps.sh@abc1234
 ```
 
 ______________________________________________________________________

docs/just-runit.md

@@ -155,7 +155,7 @@ used.
 # See which URL a cache file came from and when it was fetched
 cat ~/.cache/just-runit/<sha256>.meta
 # ts=1779583354
-# url=https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/install-deps.sh
+# url=https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/just_bashit/install-deps.sh
 ```
 
 **Force a fresh fetch (keep the entry, overwrite it)**
@@ -173,7 +173,7 @@ jbx -n https://example.com/tool.sh run
 **Purge a single entry**
 
 ```bash
-jb cache clear https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/install-deps.sh
+jb cache clear https://raw.githubusercontent.com/just-buildit/just-bashit/main/src/just_bashit/install-deps.sh
 ```
 
 Or manually — find the hash with `-v` then remove the pair:

docs/libraries/datetime.md

@@ -1,13 +1,13 @@
 # datetime
 
-Source: `src/datetime.sh`
+Source: `src/just_bashit/datetime.sh`
 
 ## iso-8601-basic
 
 Generate a path- and filename-friendly ISO 8601 UTC timestamp.
 
 ```bash
-. just-bashit/src/datetime.sh
+. just-bashit/src/just_bashit/datetime.sh
 iso-8601-basic
 # 20260522T143200Z
 ```

docs/libraries/environment.md

@@ -1,6 +1,6 @@
 # environment
 
-Source: `src/environment.sh`
+Source: `src/just_bashit/environment.sh`
 
 Idempotent management of `~/.bashrc` entries and command existence checks.
 
@@ -11,7 +11,7 @@ ______________________________________________________________________
 Write a line to `~/.bashrc` only if it is not already present.
 
 ```bash
-. just-bashit/src/environment.sh
+. just-bashit/src/just_bashit/environment.sh
 
 # Write a verbatim line
 set-bashrc 'alias ll="ls -la"'
@@ -45,7 +45,7 @@ ______________________________________________________________________
 Remove a line from `~/.bashrc` if present. No-op if not found.
 
 ```bash
-. just-bashit/src/environment.sh
+. just-bashit/src/just_bashit/environment.sh
 
 # Remove a verbatim line
 unset-bashrc 'alias ll="ls -la"'
@@ -79,7 +79,7 @@ ______________________________________________________________________
 Return 0 if a command is available in `PATH`, 1 otherwise.
 
 ```bash
-. just-bashit/src/environment.sh
+. just-bashit/src/just_bashit/environment.sh
 
 check-command-exists curl && echo "curl is available"
 check-command-exists nonexistent || echo "not found"

docs/libraries/file.md

@@ -1,6 +1,6 @@
 # file
 
-Source: `src/file.sh`
+Source: `src/just_bashit/file.sh`
 
 Idempotent line-level file content management.
 
@@ -12,7 +12,7 @@ Write a line to a file only if it is not already present. Optionally write a
 blank line.
 
 ```bash
-. just-bashit/src/file.sh
+. just-bashit/src/just_bashit/file.sh
 
 # Append a line (idempotent — safe to call repeatedly)
 add-line "export PATH=$PATH:/opt/myapp/bin" /etc/environment
@@ -48,7 +48,7 @@ ______________________________________________________________________
 Remove a line from a file if present. No-op if not found.
 
 ```bash
-. just-bashit/src/file.sh
+. just-bashit/src/just_bashit/file.sh
 
 remove-line "export PATH=$PATH:/opt/myapp/bin" /etc/environment
 
@@ -82,7 +82,7 @@ ______________________________________________________________________
 Copy every line from one file into another, skipping duplicates.
 
 ```bash
-. just-bashit/src/file.sh
+. just-bashit/src/just_bashit/file.sh
 
 # Merge new.conf into existing.conf without duplicating lines
 add-contents new.conf existing.conf

docs/libraries/format.md

@@ -1,6 +1,6 @@
 # format
 
-Source: `src/format.sh`
+Source: `src/just_bashit/format.sh`
 
 String trimming and colorized output.
 
@@ -12,7 +12,7 @@ Trim a string at a marker character, from either direction, with optional
 greedy and keep-marker modes.
 
 ```bash
-. just-bashit/src/format.sh
+. just-bashit/src/just_bashit/format.sh
 
 trim-from 'report.2026.tar.gz'    # report.2026.tar
 trim-from -r 'report.2026.tar.gz' # 2026.tar.gz
@@ -53,7 +53,7 @@ ______________________________________________________________________
 Print colorized text to stdout using ANSI escape sequences.
 
 ```bash
-. just-bashit/src/format.sh
+. just-bashit/src/just_bashit/format.sh
 
 color-echo -bc green "Build succeeded"
 color-echo -bc red "Build failed"

docs/libraries/logging.md

@@ -1,6 +1,6 @@
 # logging
 
-Source: `src/logging.sh`
+Source: `src/just_bashit/logging.sh`
 
 Structured, colorized logging with timestamps. Depends on `format.sh`,
 `match.sh`, and `datetime.sh` — all resolved automatically from relative paths.
@@ -12,7 +12,7 @@ ______________________________________________________________________
 Log a message to stdout with a timestamp and type label.
 
 ```bash
-. just-bashit/src/logging.sh
+. just-bashit/src/just_bashit/logging.sh
 
 log "Starting deployment"
 # [20260522T143200Z::INFO]::Starting deployment
@@ -74,7 +74,7 @@ ______________________________________________________________________
 Sleep for a given duration with input validation.
 
 ```bash
-. just-bashit/src/logging.sh
+. just-bashit/src/just_bashit/logging.sh
 
 log-wait 5      # sleep 5 seconds
 log-wait 0.5    # sleep 500ms