Update wording associated with the check subcommand

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

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

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

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

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)