diff --git a/CHANGELOG.md b/CHANGELOG.md
index 438cb8cf..4d66b960 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Added
+- `bashunit doc --custom` lists the assertions your own project defines, rendering the comment block above each one; plain `bashunit doc` appends them as a "Custom assertions" section. Needs `--boot` / `BASHUNIT_BOOTSTRAP`, which `bashunit doc` now accepts (#918)
 - `bashunit::assert_once <label> <actual>` makes a composed custom assertion count and report once instead of once per inner step, with its own label rather than the internal step's message. Opt-in, so existing totals are unchanged (#917)
 - `assert_assertion_passes`, `assert_assertion_fails` and `assert_assertion_fails_with <message>` test a custom assertion for the verdict it reports. The inner assertion runs isolated — its counters, output and stop-on-failure guard are restored — so testing a failing assertion no longer means rebuilding the expected string from `bashunit::console_results::print_failed_test` (#916)
 - `bashunit::assert_that <expected> <actual> <cmd> [args...]` writes a custom assertion in one call: it runs the command and marks the assertion passed or failed, so the two counters can no longer drift apart by a forgotten `return` or a missing `bashunit::assertion_passed` (#915)
diff --git a/completions/_bashunit b/completions/_bashunit
index 31477610..8f8374db 100644
--- a/completions/_bashunit
+++ b/completions/_bashunit
@@ -59,6 +59,7 @@ _bashunit() {
   fi
 
   _arguments \
+    '--custom[Show only the assertions your project defines]' \
     '(-a --assert)'{-a,--assert}'[Run a standalone assert function]:function:' \
     '(-e --env --boot)'{-e,--env,--boot}'[Load a custom env/bootstrap file]:file:_files' \
     '(-f --filter)'{-f,--filter}'[Only run tests matching the name]:name:' \
diff --git a/completions/bashunit.bash b/completions/bashunit.bash
index 353a2d95..2285a328 100644
--- a/completions/bashunit.bash
+++ b/completions/bashunit.bash
@@ -10,6 +10,9 @@
 
 _BASHUNIT_COMPLETIONS_SUBCOMMANDS="test bench doc init learn upgrade assert watch"
 
+# Flags accepted by the doc subcommand.
+_BASHUNIT_COMPLETIONS_DOC_OPTS="--custom -e --env --boot -h --help"
+
 _BASHUNIT_COMPLETIONS_TEST_OPTS="--assert --boot --coverage --coverage-exclude \
 --coverage-min --coverage-paths --coverage-report --coverage-report-html \
 --debug --detailed --env --exclude-tag --fail-on-risky --failures-only \
@@ -82,6 +85,15 @@ _bashunit_completions() {
     return 0
   fi
 
+  # `bashunit doc <filter>` completes assertion names, plus its own flags.
+  if [ "$COMP_CWORD" -ge 2 ] && [ "${COMP_WORDS[1]}" = "doc" ]; then
+    case "$cur" in
+    -*) COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_DOC_OPTS" -- "$cur")) ;;
+    *) COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_ASSERT_FNS" -- "$cur")) ;;
+    esac
+    return 0
+  fi
+
   # First word: subcommands (plus flags, since `test` is the default command).
   if [ "$COMP_CWORD" -eq 1 ] && [ "${cur#-}" = "$cur" ]; then
     COMPREPLY=($(compgen -W "$_BASHUNIT_COMPLETIONS_SUBCOMMANDS" -- "$cur"))
diff --git a/docs/command-line.md b/docs/command-line.md
index b3c6b527..49766ad5 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -13,7 +13,7 @@ bashunit test [path] [options]    # Run tests (default)
 bashunit bench [path] [options]   # Run benchmarks
 bashunit watch [path] [options]   # Watch files, re-run tests on change
 bashunit assert <fn> <args>       # Run standalone assertion
-bashunit doc [filter]             # Show assertion documentation
+bashunit doc [options] [filter]   # Show assertion documentation
 bashunit init [dir]               # Initialize test directory
 bashunit learn                    # Interactive tutorial
 bashunit upgrade                  # Upgrade to latest version
@@ -890,10 +890,19 @@ also uses polling.
 
 ## doc
 
-> `bashunit doc [filter]`
+> `bashunit doc [options] [filter]`
 
 Display documentation for assertion functions.
 
+| Option | Description |
+|--------|-------------|
+| `--custom` | Show only the assertions your project defines |
+| `-e, --env, --boot <file>` | Load a bootstrap file defining custom assertions |
+
+With a bootstrap loaded, `bashunit doc` appends a **Custom assertions** section
+rendering the comment block above each of your own `assert_*` functions. See
+[Custom asserts](/custom-asserts).
+
 ::: code-group
 ```bash [Examples]
 # Show all assertions
@@ -904,6 +913,9 @@ bashunit doc equals
 
 # Show file-related assertions
 bashunit doc file
+
+# Show only your project's assertions
+bashunit doc --custom --boot tests/bootstrap.sh
 ```
 ```[Output]
 ## assert_equals
diff --git a/docs/custom-asserts.md b/docs/custom-asserts.md
index d8c8c7d8..62a24b10 100644
--- a/docs/custom-asserts.md
+++ b/docs/custom-asserts.md
@@ -302,6 +302,42 @@ source "$(dirname "${BASH_SOURCE[0]}")/custom_asserts.sh"
 See [Configuration](/configuration) and [Command line](/command-line) for the
 full bootstrap options.
 
+## Listing your assertions
+
+`bashunit doc` prints the built-in catalogue. Once a bootstrap defines your own
+assertions, it appends them too, rendering the comment block above each one:
+
+```bash
+./bashunit doc --boot tests/bootstrap.sh     # built-ins, then a "Custom assertions" section
+./bashunit doc --custom --boot tests/bootstrap.sh  # only your own
+./bashunit doc --custom http                 # ...narrowed by a filter
+```
+
+```
+## assert_http_success
+--------------
+Asserts that the status code is a 2xx.
+```
+
+With `BASHUNIT_BOOTSTRAP` set, the `--boot` flag can be omitted. A bootstrap is
+required either way: it is the only point at which your assertions are
+guaranteed loaded, which is another reason to prefer it over sourcing from
+`set_up`.
+
+Write the docstring as a plain comment block immediately above the function —
+the same shape the built-ins use:
+
+```bash
+# Asserts that the status code is a 2xx.
+# Arguments: $1 - the status code
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+```
+
 ## Best practices
 
 1. **Prefer `bashunit::assert_that`**: one call marks the assertion passed or failed, so you cannot forget the `return` after a failure (which would bump both counters) or forget `bashunit::assertion_passed` (which would leave the test with zero assertions, reported as risky).
diff --git a/src/console_header.sh b/src/console_header.sh
index e8c31382..6050397e 100644
--- a/src/console_header.sh
+++ b/src/console_header.sh
@@ -208,17 +208,22 @@ EOF
 
 function bashunit::console_header::print_doc_help() {
   cat <<EOF
-Usage: bashunit doc [filter]
+Usage: bashunit doc [options] [filter]
 
 Display documentation for assertion functions.
 
 Arguments:
 filter                      Optional filter to show only matching assertions
 
+Options:
+--custom                    Show only the assertions your project defines
+-e, --env, --boot <file>    Load a bootstrap file defining custom assertions
+
 Examples:
 bashunit doc                Show all assertions
 bashunit doc equals         Show assertions containing 'equals'
 bashunit doc file           Show file-related assertions
+bashunit doc --custom       Show only your project's own assertions
 EOF
 }
 
diff --git a/src/doc.sh b/src/doc.sh
index f168af14..21697884 100644
--- a/src/doc.sh
+++ b/src/doc.sh
@@ -56,3 +56,143 @@ function bashunit::doc::print_asserts() {
     }
   '
 }
+
+##
+# Collects the assert_* functions a bootstrap defined, i.e. those declared now
+# that were not declared before it was sourced, into
+# _BASHUNIT_DOC_CUSTOM_FNS_OUT (newline separated, sorted).
+#
+# Diffing against a snapshot rather than a hardcoded list means the built-in set
+# never has to be maintained in two places.
+# Arguments: $1 - newline separated assert_* names known before the bootstrap
+##
+_BASHUNIT_DOC_CUSTOM_FNS_OUT=""
+
+function bashunit::doc::custom_fns_to_slot() {
+  local known="$1"
+  # Declare and assign separately: bash 3.0 does not expand a compound array
+  # assignment attached to `local`.
+  local -a found
+  found=()
+  local count=0
+  local fn
+
+  for fn in $(compgen -A function assert_ 2>/dev/null); do
+    case "
+$known
+" in
+    *"
+$fn
+"*) continue ;;
+    esac
+
+    # Insertion sort. A project's own assertion list is tiny, so this beats a
+    # `sort` fork -- and `LC_ALL=C sort` is banned in src/ because bash 5.3.9 on
+    # macOS segfaults on that prefix inside a command substitution (#912).
+    local i=$count
+    while [ "$i" -gt 0 ] && [ "${found[$((i - 1))]}" \> "$fn" ]; do
+      found[i]=${found[$((i - 1))]}
+      i=$((i - 1))
+    done
+    found[i]=$fn
+    count=$((count + 1))
+  done
+
+  local out=""
+  local j=0
+  while [ "$j" -lt "$count" ]; do
+    out="$out${found[j]}"$'\n'
+    j=$((j + 1))
+  done
+
+  _BASHUNIT_DOC_CUSTOM_FNS_OUT="${out%$'\n'}"
+}
+
+##
+# Prints the leading comment block of a function, with the comment markers
+# stripped. Silent when the function has no comment or was defined somewhere
+# unreadable (e.g. sourced from a process substitution).
+# Arguments: $1 - function name
+##
+function bashunit::doc::print_fn_comment() {
+  local fn="$1"
+
+  # extdebug is toggled inside the subshell only: enabling it in the caller's
+  # shell clobbers caller state (#808).
+  local info
+  info="$(
+    shopt -s extdebug
+    declare -F "$fn"
+  )"
+
+  local rest="${info#* }"
+  local def_line="${rest%% *}"
+  local file="${rest#* }"
+
+  case "$def_line" in
+  '' | *[!0-9]*) return 0 ;;
+  esac
+  [ -n "$file" ] && [ -f "$file" ] || return 0
+
+  # Read the file once into an array; walking backwards needs random access and
+  # a per-line `sed -n Np` loop is exactly the quadratic pattern #807 removed.
+  local -a lines
+  lines=()
+  local count=0
+  local line
+  while IFS= read -r line || [ -n "$line" ]; do
+    lines[count]="$line"
+    count=$((count + 1))
+  done <"$file"
+
+  # Collect the comment run immediately above the definition, then print it in
+  # source order.
+  local first=$((def_line - 1))
+  local i=$((first - 1))
+  while [ "$i" -ge 0 ]; do
+    case "${lines[i]:-}" in
+    '#'*) i=$((i - 1)) ;;
+    *) break ;;
+    esac
+  done
+
+  local j=$((i + 1))
+  while [ "$j" -lt "$first" ]; do
+    line="${lines[j]:-}"
+    # Strip the marker: "## " fences render as blank, "# text" as "text".
+    line="${line#\#}"
+    line="${line#\#}"
+    line="${line# }"
+    printf '%s\n' "$line"
+    j=$((j + 1))
+  done
+}
+
+##
+# Prints the custom assertions defined by a bootstrap, in the shape
+# bashunit::doc::print_asserts already uses.
+# Arguments: $1 - optional filter
+# Returns: 0 when at least one was printed, 1 when there were none
+##
+function bashunit::doc::print_custom_asserts() {
+  local filter="${1:-}"
+  local printed=1
+  local fn
+
+  for fn in $_BASHUNIT_DOC_CUSTOM_FNS_OUT; do
+    if [ -n "$filter" ]; then
+      case "$fn" in
+      *"$filter"*) ;;
+      *) continue ;;
+      esac
+    fi
+
+    printf '## %s\n' "$fn"
+    printf -- '--------------\n'
+    bashunit::doc::print_fn_comment "$fn"
+    printf '\n'
+    printed=0
+  done
+
+  return $printed
+}
diff --git a/src/main.sh b/src/main.sh
index a6cc91b7..fb66c493 100644
--- a/src/main.sh
+++ b/src/main.sh
@@ -733,14 +733,63 @@ function bashunit::main::cmd_bench() {
 # Subcommand: doc
 #############################
 function bashunit::main::cmd_doc() {
-  case "${1:-}" in
-  -h | --help)
-    bashunit::console_header::print_doc_help
+  local filter=""
+  local custom_only=false
+  local boot_file="${BASHUNIT_BOOTSTRAP:-}"
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    -h | --help)
+      bashunit::console_header::print_doc_help
+      exit 0
+      ;;
+    --custom)
+      custom_only=true
+      shift
+      ;;
+    -e | --env | --boot)
+      boot_file="${2:-}"
+      shift 2
+      ;;
+    *)
+      filter="$1"
+      shift
+      ;;
+    esac
+  done
+
+  # Snapshot before sourcing: whatever assert_* appears afterwards is the
+  # project's own.
+  local known
+  known="$(compgen -A function assert_ 2>/dev/null)"
+
+  if [ -n "$boot_file" ]; then
+    if [ ! -r "$boot_file" ]; then
+      printf "%sError: cannot read the bootstrap file: '%s'.%s\n" \
+        "$_BASHUNIT_COLOR_FAILED" "$boot_file" "$_BASHUNIT_COLOR_DEFAULT" >&2
+      exit 1
+    fi
+    # shellcheck disable=SC1090,SC2086
+    source "$boot_file" ${BASHUNIT_BOOTSTRAP_ARGS:-}
+  fi
+
+  bashunit::doc::custom_fns_to_slot "$known"
+
+  if [ "$custom_only" = true ]; then
+    if ! bashunit::doc::print_custom_asserts "$filter"; then
+      printf 'No custom assertions found.\n'
+      printf 'Load them with --boot <file> or BASHUNIT_BOOTSTRAP.\n'
+    fi
     exit 0
-    ;;
-  esac
+  fi
+
+  bashunit::doc::print_asserts "$filter"
+
+  if [ -n "$_BASHUNIT_DOC_CUSTOM_FNS_OUT" ]; then
+    printf '\n## Custom assertions\n\n'
+    bashunit::doc::print_custom_asserts "$filter" || true
+  fi
 
-  bashunit::doc::print_asserts "${1:-}"
   exit 0
 }
 
diff --git a/tests/acceptance/bashunit_doc_custom_test.sh b/tests/acceptance/bashunit_doc_custom_test.sh
new file mode 100644
index 00000000..d28127d3
--- /dev/null
+++ b/tests/acceptance/bashunit_doc_custom_test.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+
+BOOT="tests/acceptance/fixtures/custom_assert_docs.sh"
+
+function test_doc_custom_lists_the_project_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_contains "## assert_positive_number" "$output"
+  assert_contains "## assert_http_success" "$output"
+}
+
+function test_doc_custom_renders_the_leading_comment_block() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_contains "Asserts that the value is a number greater than zero." "$output"
+  assert_contains "Arguments: \$1 - the value under test" "$output"
+  assert_contains "Asserts that the status code is a 2xx." "$output"
+}
+
+function test_doc_custom_skips_functions_that_are_not_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_not_contains "helper_not_an_assertion" "$output"
+}
+
+function test_doc_custom_does_not_list_the_built_in_assertions() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" 2>&1) || true
+
+  assert_not_contains "## assert_same" "$output"
+  assert_not_contains "## assert_line_count" "$output"
+}
+
+function test_doc_custom_without_a_bootstrap_reports_none() {
+  local output
+  output=$(./bashunit doc --custom 2>&1) || true
+
+  assert_contains "No custom assertions" "$output"
+}
+
+function test_doc_custom_without_a_bootstrap_still_exits_zero() {
+  local exit_code=0
+
+  ./bashunit doc --custom >/dev/null 2>&1 || exit_code=$?
+
+  assert_same "0" "$exit_code"
+}
+
+function test_doc_appends_a_custom_section_when_a_bootstrap_defines_any() {
+  local output
+  output=$(./bashunit doc --boot "$BOOT" 2>&1) || true
+
+  # Built-in catalogue still there, custom section appended after it.
+  assert_contains "## assert_same" "$output"
+  assert_contains "Custom assertions" "$output"
+  assert_contains "## assert_positive_number" "$output"
+}
+
+function test_doc_without_a_bootstrap_has_no_custom_section() {
+  local output
+  output=$(./bashunit doc 2>&1) || true
+
+  assert_not_contains "Custom assertions" "$output"
+}
+
+function test_doc_custom_honours_a_filter() {
+  local output
+  output=$(./bashunit doc --custom --boot "$BOOT" http 2>&1) || true
+
+  assert_contains "## assert_http_success" "$output"
+  assert_not_contains "## assert_positive_number" "$output"
+}
+
+function test_doc_custom_reports_an_unreadable_bootstrap() {
+  local output
+  output=$(./bashunit doc --custom --boot "does/not/exist.sh" 2>&1) || true
+
+  assert_contains "cannot read the bootstrap file" "$output"
+}
diff --git a/tests/acceptance/fixtures/custom_assert_docs.sh b/tests/acceptance/fixtures/custom_assert_docs.sh
new file mode 100644
index 00000000..0e58f534
--- /dev/null
+++ b/tests/acceptance/fixtures/custom_assert_docs.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+# A bootstrap defining project assertions, used to check that `bashunit doc`
+# picks them up and renders their leading comment block.
+
+# Asserts that the value is a number greater than zero.
+# Arguments: $1 - the value under test
+function assert_positive_number() {
+  bashunit::assert_that "positive number" "$1" test "$1" -gt 0
+}
+
+# Asserts that the status code is a 2xx.
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+
+# Not an assertion, so it must not be listed.
+function helper_not_an_assertion() {
+  return 0
+}
diff --git a/tests/unit/completions_test.sh b/tests/unit/completions_test.sh
index b29c262f..0ad81011 100644
--- a/tests/unit/completions_test.sh
+++ b/tests/unit/completions_test.sh
@@ -16,6 +16,16 @@ function completions_expected_test_flags() {
     LC_ALL=C sort -u
 }
 
+# Flags accepted by cmd_doc, straight from its option-parsing case arms. The
+# zsh script advertises every flag from one _arguments block, so its expected
+# set is the union of the test and doc flags.
+function completions_expected_doc_flags() {
+  awk '/^function bashunit::main::cmd_doc\(\)/,/^}$/' src/main.sh |
+    grep -E '^[[:space:]]+--?[a-zA-Z][a-zA-Z0-9-]*( \| --?[a-zA-Z][a-zA-Z0-9-]*)*\)' |
+    sed 's/)$//' | tr -d ' ' | tr '|' '\n' |
+    LC_ALL=C sort -u
+}
+
 function completions_expected_assert_functions() {
   grep -hoE '^function assert_[a-z_0-9]+' src/assert*.sh |
     sed 's/^function //' | LC_ALL=C sort -u
@@ -64,12 +74,29 @@ function test_bash_completion_flags_match_main_sh() {
 
 function test_zsh_completion_flags_match_main_sh() {
   local expected actual
-  expected=$(completions_expected_test_flags)
+  expected=$(
+    {
+      completions_expected_test_flags
+      completions_expected_doc_flags
+    } | LC_ALL=C sort -u
+  )
   actual=$(completions_zsh_flags)
 
   assert_same "$expected" "$actual"
 }
 
+function test_bash_completion_doc_flags_match_main_sh() {
+  local expected actual
+  expected=$(completions_expected_doc_flags)
+  actual=$(
+    # shellcheck source=/dev/null
+    source "$BASH_COMPLETION_FILE" 2>/dev/null
+    echo "$_BASHUNIT_COMPLETIONS_DOC_OPTS" | tr ' ' '\n' | grep -v '^$' | LC_ALL=C sort -u
+  )
+
+  assert_same "$expected" "$actual"
+}
+
 function test_bash_completion_lists_all_subcommands() {
   local subcommands
   subcommands=$(