docs: document expected output and troubleshooting

CHANGELOG.md

@@ -7,7 +7,10 @@ and versions are tracked in the repo-root `VERSION` file.
 
 ## [Unreleased]
 
-No unreleased changes yet.
+### Documentation
+
+- Documented stable quick-start output, the informational collection log, and
+  troubleshooting for Bash setup, output collisions, and modified bundles.
 
 ## [0.1.1] - 2026-10-08
 

README.md

@@ -70,6 +70,110 @@ directory before repeating the real collection, or select an unused destination:
 `collect --dry-run` creates neither the output directory nor temporary
 application state beneath it.
 
+### Expected output
+
+The paths, branch name, framework commit, and timestamps vary by checkout. The
+stable lines below are the useful contract to compare with a terminal session:
+
+`./bin/beacon --help` includes:
+
+```text
+Offline support-bundle collector
+Commands:
+  status                 Show fixture and framework readiness
+  plan                   Describe bundle inputs and redactions
+  collect                Create a redacted support bundle
+  verify                 Verify a collected support bundle
+```
+
+`./bin/beacon status` reports the consumer and the immutable framework identity:
+
+```text
+application=beacon
+workspace_ready=yes
+selected_files=3
+framework_version=<release version>
+framework_provenance=release-artifact
+```
+
+`./bin/beacon plan` reports the selected inputs and redaction policy without
+creating a bundle:
+
+```text
+operation=collect
+selected_files=3
+inputs=config/app.env,logs/app.log,system/info.txt
+redact_keys=TOKEN,SECRET,PASSWORD
+include=config/app.env
+include=logs/app.log
+include=system/info.txt
+```
+
+`./bin/beacon collect --dry-run` reports the planned operation and does not
+write the destination:
+
+```text
+dry_run=true
+operation=collect
+selected_files=3
+```
+
+Successful `./bin/beacon collect` reports the bundle and checksum manifest:
+
+```text
+bundle=<output path>
+manifest=<output path>/MANIFEST.sha256
+```
+
+Successful `./bin/beacon verify --output <output path>` reports:
+
+```text
+verified=true
+files=4
+bundle=<output path>
+```
+
+On a normal, non-quiet collection, the vendored `file` module may also emit an
+`INFO` line while it updates the bundle README section. That line includes a
+temporary path and a framework source location, so both are intentionally
+environment-specific; it is informational, not a failure. Use `--quiet` when
+only the stable machine-readable result is wanted.
+
+## Troubleshooting
+
+### The launcher cannot find a supported Bash
+
+Beacon requires Bash 4.2.53 or newer. On macOS, install the Homebrew Bash
+formula and ask Base to diagnose the project setup:
+
+```bash
+brew install bash
+base-bash check --project .
+```
+
+Run the check from this repository. It confirms the launcher and framework
+setup without changing Beacon's committed vendor.
+
+### Collection refuses to overwrite an output directory
+
+Collection never overwrites an existing destination. Choose a new path, or
+remove only a bundle that you own before retrying:
+
+```bash
+./bin/beacon collect --output /tmp/my-beacon-bundle-2
+```
+
+### Verification reports a checksum mismatch
+
+The bundle is immutable after collection. If a file under `files/` was edited,
+`verify` exits non-zero with `ERROR: Manifest checksum mismatch.` Collect again
+to a new destination rather than editing the existing bundle:
+
+```bash
+./bin/beacon collect --output /tmp/my-beacon-bundle-fixed
+./bin/beacon verify --output /tmp/my-beacon-bundle-fixed
+```
+
 For a scenario-driven walkthrough whose commands are exercised by CI, follow
 [Beacon in five minutes](docs/five-minute-tutorial.md).
 
@@ -147,9 +251,11 @@ Base Bash version. From a clean checkout whose `VERSION` matches the requested
 version, build and verify the deterministic four-file artifact set locally:
 
 ```bash
-./scripts/release-artifact build --version 0.1.0 --output /tmp/beacon-release
-./scripts/release-artifact verify /tmp/beacon-release
-./scripts/release-artifact verify /tmp/beacon-release --trusted-smoke
+release_version=X.Y.Z
+release_output=/tmp/beacon-release-$release_version
+./scripts/release-artifact build --version "$release_version" --output "$release_output"
+./scripts/release-artifact verify "$release_output"
+./scripts/release-artifact verify "$release_output" --trusted-smoke
 ```
 
 The output contains the standalone archive, SHA-256 manifest, SPDX SBOM, and

tests/docs-contracts.sh

@@ -19,6 +19,15 @@ grep -Fq '[adoption decision guide](should-i-use-base-bash-libs.md)' "$docs_cont
 grep -Fq '[five-minute Beacon tutorial](five-minute-tutorial.md)' "$docs_contract_decision"
 grep -Fq '[Beacon documentation and recommended reading path](docs/README.md)' "$docs_contract_readme"
 grep -Fq '[use Base Bash in your project](docs/use-in-your-project.md)' "$docs_contract_readme"
+grep -Fq '### Expected output' "$docs_contract_readme"
+grep -Fq '## Troubleshooting' "$docs_contract_readme"
+grep -Fq 'framework_provenance=release-artifact' "$docs_contract_readme"
+grep -Fq 'dry_run=true' "$docs_contract_readme"
+grep -Fq 'verified=true' "$docs_contract_readme"
+grep -Fq 'brew install bash' "$docs_contract_readme"
+grep -Fq 'base-bash check --project .' "$docs_contract_readme"
+grep -Fq 'ERROR: Manifest checksum mismatch.' "$docs_contract_readme"
+grep -Fq "Use \`--quiet\` when" "$docs_contract_readme"
 grep -Fq '## Code-level before and after' "$docs_contract_why"
 grep -Fq 'BEGIN BEFORE AFTER CLI' "$docs_contract_why"
 grep -Fq 'BEGIN BEFORE AFTER CLEANUP' "$docs_contract_why"

tests/docs-examples.sh

@@ -5,9 +5,11 @@ set -euo pipefail
 docs_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd -P)"
 tutorial="$docs_root/docs/five-minute-tutorial.md"
 example_script="$(mktemp "${TMPDIR:-/tmp}/beacon-docs-example.XXXXXX")"
+output_root="$(mktemp -d "${TMPDIR:-/tmp}/beacon-docs-output.XXXXXX")"
 
 cleanup() {
     rm -f "$example_script"
+    rm -rf "$output_root"
 }
 trap cleanup EXIT
 
@@ -29,6 +31,34 @@ shellcheck --shell=bash "$example_script"
 (
     cd -- "$docs_root"
     /usr/bin/env bash "$example_script"
+
+    ./bin/beacon --help > "$output_root/help.txt"
+    grep -Fq 'Offline support-bundle collector' "$output_root/help.txt"
+    grep -Fq 'Commands:' "$output_root/help.txt"
+    grep -Fq '  collect                Create a redacted support bundle' "$output_root/help.txt"
+
+    ./bin/beacon status > "$output_root/status.txt"
+    grep -Fxq 'application=beacon' "$output_root/status.txt"
+    grep -Fxq 'workspace_ready=yes' "$output_root/status.txt"
+    grep -Fxq 'framework_provenance=release-artifact' "$output_root/status.txt"
+
+    ./bin/beacon plan --output "$output_root/plan" > "$output_root/plan.txt"
+    grep -Fxq 'operation=collect' "$output_root/plan.txt"
+    grep -Fxq 'redact_keys=TOKEN,SECRET,PASSWORD' "$output_root/plan.txt"
+    grep -Fxq 'include=config/app.env' "$output_root/plan.txt"
+
+    ./bin/beacon collect --dry-run --output "$output_root/dry-run" > "$output_root/dry-run.txt"
+    grep -Fxq 'dry_run=true' "$output_root/dry-run.txt"
+    grep -Fxq 'operation=collect' "$output_root/dry-run.txt"
+    [[ ! -e "$output_root/dry-run" ]]
+
+    ./bin/beacon collect --output "$output_root/collect" > "$output_root/collect.txt" 2> "$output_root/collect.err"
+    grep -Fxq "bundle=$output_root/collect" "$output_root/collect.txt"
+    grep -Fxq "manifest=$output_root/collect/MANIFEST.sha256" "$output_root/collect.txt"
+
+    ./bin/beacon verify --output "$output_root/collect" > "$output_root/verify.txt"
+    grep -Fxq 'verified=true' "$output_root/verify.txt"
+    grep -Fxq 'files=4' "$output_root/verify.txt"
 )
 
 /usr/bin/env bash "$docs_root/tests/docs-before-after.sh"