Finish publication recovery workflow

docs/consumers/publish.md

@@ -123,3 +123,53 @@ against the captured endpoint before retrying; see the [maintainer procedure](..
 for the recovery steps. The result's endpoint is the exact URL and can contain
 credentials; handle it accordingly. The [CLI contract](../cli.md) documents
 command output and exit statuses.
+
+## Retain and reconcile publication evidence
+
+`Publish` automatically attempts to save one private record for each invocation.
+The default store is under the repository's Git common directory, so linked
+worktrees share it. `ReleaseRequest.PublicationRecordDir` can override the
+directory; relative overrides resolve from the source repository root. The CLI
+equivalent is `publish --record-dir DIR`. ReleaseKit creates its owned storage
+directories privately and creates record files with owner-only permissions;
+existing directory permissions are left as they are. The caller owns storage
+retention and removal.
+
+The saved endpoint is retained exactly for later observation and may include
+credentials. Treat records, `PublicationEvidence`, and `PublicationResult` as
+sensitive. Store overrides in a location with suitable access controls, avoid
+printing raw endpoint values, and remove records when their recovery value has
+expired. Diagnostic errors and CLI output apply credential redaction; the
+private record and typed evidence preserve the raw endpoint.
+
+Recording failure is reported in `PublicationResult.RecordError`, separately
+from `Publish`'s return error and publication state. A successful push remains
+successful if storage fails, but the saved handoff is unavailable. Callers can
+still pass `result.Evidence` directly to `ReconcilePublication` when it contains
+the required identity. For example:
+
+```go
+func observe(ctx context.Context, result releasekit.PublicationResult) (releasekit.PublicationReconciliationResult, error) {
+	return releasekit.ReconcilePublication(ctx, result.Evidence)
+}
+```
+
+The evidence is populated as publication identity becomes available, including
+partial evidence on some earlier failures. An abrupt process termination before
+the save point can leave no record; removed storage also removes the handoff.
+Records from older attempts may lack the tag object, endpoint, or other identity
+needed for a conclusive observation.
+
+Use `LoadPublicationEvidence(path)` to read one explicit record,
+`ListPublicationAttempts(ctx, request)` to discover readable records and
+per-record diagnostics in a local directory, or `ReconcilePublication(ctx,
+evidence)` to observe a selected endpoint. Listing does not query remotes, and
+neither listing nor reconciliation changes saved records. Recovery does not
+infer the attempt from current HEAD, local tags, module files, or profiles.
+`ReconcilePublication` returns a nil error for a completed `published`,
+`not_published`, or `conflict` observation; unresolved `unknown` results include
+a typed error that retains the underlying cause. See the
+[GoDoc](../../recovery.go) for the exported fields and error kinds, the
+[CLI guide](../cli.md) for command statuses, and the
+[record format guide](../integrations/publication-records.md) for supported
+stored and structured formats.