docs: add a focused JSON output example for new adopters

docs/output-formats.md

@@ -115,3 +115,95 @@ human-readable summary; redirected output remains headerless rows.
 The table and delimited forms use the columns `PROJECT` then `PATH`. CSV and
 TSV contain those two fields without a header. JSON and YAML contain a list of
 objects with `name` and `path` keys, preserving the existing JSON shape.
+
+## Focused JSON output example for new adopters
+
+A new adopter can inspect Base's JSON output with a simple command:
+
+
+
+This command emits one JSON document on stdout. Logs and errors go to stderr.
+
+The JSON document has a top-level `status` field (one of `ok`, `warn`, `error`) and a `data` field
+containing the command-specific result. For `basectl check`, the `data` field includes the project
+name and version when run in a Base-managed project.
+
+Example output:
+
+
+
+For more details on the JSON contract, see [Inspection JSON](inspection-json.md).
+
+Note: The `basectl check` command is safe to run in any Base-managed project and does not require
+a specific project setup beyond having a `base_manifest.yaml`.
+
+To quickly inspect the status field without depending on the project name or version, use jq:
+
+
+
+
+## Focused JSON output example for new adopters
+
+A new adopter can inspect Base's JSON output with a simple command:
+
+
+
+This command emits one JSON document on stdout. Logs and errors go to stderr.
+
+The JSON document has a top-level `status` field (one of `ok`, `warn`, `error`) and a `data` field
+containing the command-specific result. For `basectl check`, the `data` field includes the project
+name and version when run in a Base-managed project.
+
+Example output:
+
+
+
+For more details on the JSON contract, see [Inspection JSON](inspection-json.md).
+
+Note: The `basectl check` command is safe to run in any Base-managed project and does not require
+a specific project setup beyond having a `base_manifest.yaml`.
+
+To quickly inspect the status field without depending on the project name or version, use jq:
+
+
+
+
+## Focused JSON output example for new adopters
+
+A new adopter can inspect Base's JSON output with a simple command:
+
+```bash
+basectl check --format json
+```
+
+This command emits one JSON document on stdout. Logs and errors go to stderr.
+
+The JSON document has a top-level `status` field (one of `ok`, `warn`, `error`) and a `data` field
+containing the command-specific result. For `basectl check`, the `data` field includes the project
+name and version when run in a Base-managed project.
+
+Example output:
+
+```json
+{
+  "schema_version": 1,
+  "command": "check",
+  "status": "ok",
+  "data": {
+    "project": "demo",
+    "version": "0.4.0"
+  },
+  "error": null
+}
+```
+
+For more details on the JSON contract, see [Inspection JSON](inspection-json.md).
+
+Note: The `basectl check` command is safe to run in any Base-managed project and does not require
+a specific project setup beyond having a `base_manifest.yaml`.
+
+To quickly inspect the status field without depending on the project name or version, use jq:
+
+```bash
+basectl check --format json | jq -r '.status'
+```

docs/release-process.md

@@ -312,6 +312,39 @@ records before retrying. Known recovery patterns include:
   hosts, rerun the `Build Base Bottles` workflow, and retry consumer validation
   with `brew install --force-bottle basefoundry/base/base`.
 
+
+## Downstream consumer smoke test
+
+A downstream maintainer can validate a Base release with these steps:
+
+1. Fetch the released archive:
+   ```bash
+   curl -fsSL -o base.tar.gz https://github.com/basefoundry/base/archive/refs/tags/vX.Y.Z.tar.gz
+   ```
+
+2. Verify the archive checksum (published on the GitHub Release):
+   ```bash
+   shasum -a 256 base.tar.gz
+   ```
+
+3. Extract and check version:
+   ```bash
+   tar -xzf base.tar.gz
+   cd base-X.Y.Z
+   ./bin/basectl version
+   ```
+
+4. Run a read-only command (e.g., `basectl check` on a trivial manifest):
+   ```bash
+   echo 'name: smoke-test' > base_manifest.yaml
+   ./bin/basectl check --manifest base_manifest.yaml --ci base
+   ```
+
+If any step fails, do not use the release and consult the release issue.
+
+This smoke test confirms archive integrity, version identity, and a basic command.
+
+See the full [release process](release-process.md) for the comprehensive gate.
 ## Cleanup
 
 After the Base release PR and Homebrew tap PR are merged, clean up their