# `publish_report`

Renders a completed run into a branded, client-facing HTML document at a permanent
converg3nce.com link.

**Tier:** mutate · **Rate limit:** ~20/min

## Input

| Param | Type | Required | Notes |
|---|---|---|---|
| `domain` | string | conditional | Publishes the brand's latest complete run |
| `run_id` | string | conditional | Publish this exact run instead |
| `engagement` | object | — | Bespoke engagement document |
| `force` | boolean | — | Publish even if the score was withheld |

**One of `domain` or `run_id` is required.** Omitting both returns `VALIDATION_FAILED`.

### `engagement`

```
{ documentKind?, statementOfWork?, guarantee?, longTerm? }
```

Omit it to reuse the brand's most recently published engagement. Validation errors name
the offending field path.

`engagement` is deliberately excluded from audit-log argument capture, since it can
carry commercial terms.

## Output

```json
{
  "url": "https://converg3nce.com/reports/…",
  "slug": "…",
  "run_id": "…",
  "brand": { "name": "…", "domain": "…" },
  "score": { "total": 63, "visibility": 83, "recommendation_rate": 41, "technical_readiness": 75 },
  "withheld": false,
  "published_at": "2026-08-31T09:40:00.000Z"
}
```

`score` is `null` when the run's score was withheld.

## Withheld runs are refused

A run that failed its [evidence gates](../../audit/scoring.md#evidence-gates) is refused
unless `force: true`. Forced publication renders a withheld notice in place of the
scorecard rather than a number.

!!!warning These documents are `noindex`
Published reports carry `noindex`, `noarchive`, and `nosnippet`, and are fully
self-contained — no external stylesheet, script, font, or image.

The robots directives are deliberate. These documents state how invisible a named brand
currently is; letting a search engine index that publishes a claim about a customer they
did not ask to have published. **Publishing is an outward-facing act — confirm with the
client before minting a link.**
!!!

## Errors

| Code | Cause |
|---|---|
| `VALIDATION_FAILED` | Neither identifier given, bad `engagement`, or a withheld run without `force` |
| `NOT_FOUND` | Unknown brand, no complete run, or no stored report |
| `UPSTREAM_ERROR` | Server misconfiguration — including a missing public site URL, where the server refuses to mint a link against a guessed origin |