Expose reconcile state command

docs/cli.md

@@ -21,6 +21,7 @@ distributor [--help]
 distributor help
 distributor version [--format text|json]
 distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
+distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
 distributor serve [--config <path>]
 distributor validate [--format text|json] <path>
 distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
@@ -33,6 +34,7 @@ distributor manifest create --id <bundle-id> [options] <bundle-path>
 
 - `version` prints the application name and version.
 - `run` executes configured pipelines against their destinations.
+- `reconcile-state` repairs destination state records for missing managed outputs.
 - `serve` starts the authenticated HTTP upload API defined by the configuration file.
 - `validate` checks a local bundle path or a configured source bundle.
 - `inspect` reports manifest and file metadata for a local bundle path or a configured source bundle.
@@ -46,7 +48,7 @@ distributor manifest create --id <bundle-id> [options] <bundle-path>
 
 ### Common Output Format
 
-`--format text|json` is supported by `version`, `run`, `validate`, `inspect`, and `manifest create`.
+`--format text|json` is supported by `version`, `run`, `reconcile-state`, `validate`, `inspect`, and `manifest create`.
 
 - `text` is the default human-readable output.
 - `json` emits one JSON document for successful command execution.
@@ -73,6 +75,21 @@ distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
 
 `run` accepts no positional arguments.
 
+### `reconcile-state`
+
+```sh
+distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
+```
+
+- `--config <path>` loads the pipeline configuration and is required.
+- `--pipeline <id>` selects the pipeline used to identify the destination root and is required.
+- `--destination <id>` selects the destination root and is required.
+- `--all-owners` repairs missing managed output records for every owner in a shared-root state file. Without it, shared-root repair is scoped to the selected pipeline and destination owner.
+- `--dry-run` reports repairs without rewriting `.distributor.json`.
+- `--format text|json` selects human-readable or machine-readable output.
+
+Without `--dry-run`, `reconcile-state` applies state repair by removing records for managed outputs that no longer exist in storage. It reports unmanaged entries but does not delete destination files, adopt unmanaged files, or validate output digests. The command accepts no positional arguments.
+
 ### `serve`
 
 ```sh
@@ -174,6 +191,29 @@ go run ./cmd/distributor run --config examples/local-publish.yml
 
 Use `--format json` when automation needs structured run results. Use `--force` only when the operator has reviewed the destination state conflict and intentionally wants to continue.
 
+### Repair Destination State Records
+
+Preview missing managed output records for one configured destination:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive \
+  --dry-run
+```
+
+Apply the repair after reviewing the report:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive
+```
+
+Use `--all-owners` only for shared-root destination state when all owners inside the selected root should be repaired.
+
 ### Run HTML And Fan-Out Examples
 
 ```sh
@@ -217,6 +257,7 @@ Text output is optimized for direct operator use. JSON output is optimized for a
 - Use `validate` before `run` when checking a bundle supplied by another process.
 - Use `inspect --format json` when automation needs manifest metadata, normalized file details, or checksum information.
 - Use `run --dry-run` before publishing to review destination actions.
+- Use `reconcile-state --dry-run` to inspect missing managed output records before repairing destination state.
 - Use [Configuration](config.md) for schema and default details.
 - Use [Troubleshooting](troubleshooting.md) for common errors and corrective action.
 - Use [Operations](operations.md) for HTTP upload operation, state files, and recovery workflows.