From e953a4a24dd0b92c971b7030484a3d50f978cd51 Mon Sep 17 00:00:00 2001
From: David Boreham <david@bozemanpass.com>
Date: Sun, 2 Aug 2026 16:00:15 -0600
Subject: [PATCH] Update wording associated with the check subcommand

---
 docs/commands.md                 |  2 +-
 docs/commands/chart.md           |  2 +-
 docs/commands/check.md           | 37 ++++++++++++++++++++++++++------
 docs/commands/list.md            |  2 +-
 src/stack/checklist/checklist.py |  9 +++++++-
 5 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/docs/commands.md b/docs/commands.md
index f3367cc..d4c5784 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -60,7 +60,7 @@ stack COMMAND SUBCOMMAND --help
 
 ### 📊 Information & Analysis
 - **[list](commands/list.md)** - List available stacks
-- **[check](commands/check.md)** - Check if stack containers are ready
+- **[check](commands/check.md)** - Dry run of prepare: report what is missing
 - **[chart](commands/chart.md)** - Generate a mermaid graph of the stack
 
 ### 🌐 Web Applications
diff --git a/docs/commands/chart.md b/docs/commands/chart.md
index 5890c72..c160511 100644
--- a/docs/commands/chart.md
+++ b/docs/commands/chart.md
@@ -44,4 +44,4 @@ stack chart --stack my-stack --no-show-volumes --no-show-http-targets
 ## See Also
 
 - [stack list](list.md) - List available stacks
-- [stack check](check.md) - Check if stack containers are ready
+- [stack check](check.md) - Dry run of prepare: report what is missing
diff --git a/docs/commands/check.md b/docs/commands/check.md
index 81ffbbf..0db38b8 100644
--- a/docs/commands/check.md
+++ b/docs/commands/check.md
@@ -1,6 +1,6 @@
 # stack check
 
-Check if stack containers are ready
+Dry run of prepare: report what is missing
 
 ## Synopsis
 
@@ -10,7 +10,30 @@ stack check [OPTIONS]
 
 ## Description
 
-[Placeholder: Add detailed description of how the check command verifies container readiness and health status]
+Reports what [`stack prepare`](prepare.md) would still have to fetch or build,
+without doing any of it.
+
+This is a question about the *build* inputs of a stack, not about a running
+deployment — it inspects repos and container images on disk, and never starts,
+stops or contacts a deployment. To ask about running containers, use
+[`stack manage status`](manage.md#status) instead.
+
+It is most useful when some time has passed since you ran `stack prepare` and
+you no longer remember whether it finished. Re-running `prepare` would answer
+the question too, but if images are in fact missing it may build for several
+minutes; `check` answers immediately.
+
+For each repo and container image the stack requires, one status is reported:
+
+| Status | Meaning |
+|--------|---------|
+| `ready` | The image is present locally; nothing to do. |
+| `available from <registry>` | Not local, but can be pulled by `stack prepare`. |
+| `needs built` | Not local and not available remotely; `stack prepare` must build it. |
+| `repo needs fetched` | A required stack repo is not present; `stack fetch` must clone it. |
+
+If every item is `ready`, `check` prints a confirmation. Otherwise it names the
+`stack prepare` command that would resolve the gaps.
 
 ## Options
 
@@ -22,14 +45,14 @@ stack check [OPTIONS]
 
 ## Exit Codes
 
-- `0`: All containers are ready
-- `1`: One or more containers are not ready
+- `0`: Everything the stack needs is already in place
+- `1`: One or more repos or images still need to be fetched or built
 - `2`: Error occurred during check
 
 ## Examples
 
 ```bash
-# Check if all containers in a stack are ready
+# Report anything still missing before deploying
 stack check --stack my-stack
 
 # Check with specific registry
@@ -41,5 +64,7 @@ stack check --stack my-stack --git-ssh
 
 ## See Also
 
-- [stack manage status](manage.md#status) - Report stack and container status
+- [stack prepare](prepare.md) - Build or download the containers `check` reports on
+- [stack fetch](fetch.md) - Clone the repos `check` reports as missing
+- [stack manage status](manage.md#status) - Report status of a *running* deployment
 - [stack list](list.md) - List available stacks
diff --git a/docs/commands/list.md b/docs/commands/list.md
index 32fae20..437f483 100644
--- a/docs/commands/list.md
+++ b/docs/commands/list.md
@@ -66,6 +66,6 @@ stack list database --show-path
 
 ## See Also
 
-- [stack check](check.md) - Check if stack containers are ready
+- [stack check](check.md) - Dry run of prepare: report what is missing
 - [stack chart](chart.md) - Generate a mermaid graph of the stack
 - [stack init](init.md) - Create a stack specification file
diff --git a/src/stack/checklist/checklist.py b/src/stack/checklist/checklist.py
index e27c5f9..2e92280 100644
--- a/src/stack/checklist/checklist.py
+++ b/src/stack/checklist/checklist.py
@@ -99,7 +99,14 @@ def container_disposition(parent_stack, image_registry, git_ssh):
 )
 @click.pass_context
 def command(ctx, stack, image_registry, git_ssh):
-    """check if stack containers are ready"""
+    """dry run of prepare: report what is missing
+
+    Reports what `stack prepare` would still have to fetch or build, without
+    doing any of it. Useful when you have stepped away since preparing and
+    want a quick answer rather than a build that may take minutes.
+
+    Exits non-zero if anything is missing.
+    """
 
     stack = resolve_stack(stack)
     what_needs_done = container_disposition(stack, image_registry, git_ssh)