docs: document summary definitions on custom attestation types

[dangrondahl]

Description

Custom attestation types can now define an optional summary: a list of named JQ expressions that extract display values from the attestation payload, so the attestation drawer renders labeled rows instead of only raw JSON (matching the built-in Sonar, Snyk, and JUnit types). Shipped in the August 14, 2026 Platform release, but not documented anywhere.

"summary": [
  { "name": "Critical", "expression": ".critical_count" },
  { "name": "Tool", "expression": ".scanner.name" }
]

Behavior worth documenting:

• summary is part of the versioned type definition - changing it creates a new type version, like the schema and evaluator.
• Expressions are evaluated at render time against the stored payload, not at attestation time.
• Invalid JQ is rejected when the type is created (400), so authoring mistakes surface early.
• An expression that returns null or fails renders as N/A.
• Values that are valid URLs render as links, matching the existing --annotate convention.
• A top-level array payload renders one summary group per element (Summary 1:, Summary 2:, ...); expressions are authored per-object (.critical) and evaluated against each element.

Where it fits

Proposed placement, in priority order:

1. getting_started/attestations.md - the "Custom" accordion under Attestation types. This is the introduction to custom types (and where administration/managing_custom_attestation_types/overview.md already points readers for the basics), so a short subsection with the JSON snippet plus the drawer behavior belongs here.
2. tutorials/attest_custom.md - step 1 ("Create the custom attestation type first") should show a type defined with a summary, so the walkthrough ends with a readable drawer rather than raw JSON.
3. administration/managing_custom_attestation_types/overview.md - the "Each type can include" list should gain summary once the Terraform provider supports it (see blocker below).

client_reference/kosli_create_attestation-type.md is generated from the CLI and must not be hand-edited.

Blocker / decision needed

summary is currently settable only via the API - POST /api/v2/custom-attestation-types/{org}, as a field on the JSON payload:

{
  "name": "security-scan",
  "evaluator": { "content_type": "jq", "rules": [".critical_count == 0"] },
  "summary": [{ "name": "Critical", "expression": ".critical_count" }]
}

There is no --summary flag on kosli create attestation-type (as of CLI v2.36.6) and no summary attribute on the kosli_custom_attestation_type Terraform resource. Since Kosli docs steer users toward the CLI and Terraform for managing types, we should decide:

• (a) Document the API-only path now, with a note that CLI/Terraform support is pending; or
• (b) Hold the docs until the CLI flag and Terraform attribute land, and only add the concept section (what summaries are, how they render) now.

Recommendation: (b) plus the concept section - describe summaries and their rendering in getting_started/attestations.md now, then add authoring instructions to the tutorial and the Terraform page when those surfaces exist. Worth confirming with the CLI/provider owners whether flag support is already planned.

Tasks

• Decide (a) vs (b) above; check whether CLI --summary and the Terraform summary attribute are planned
• Add a summaries subsection to the "Custom" accordion in getting_started/attestations.md
• Show a summary in the type definition in tutorials/attest_custom.md
• Add summary to administration/managing_custom_attestation_types/overview.md once Terraform supports it
• Run mint broken-links

References

• Platform release entry: August 14, 2026 in changelog/index.mdx (added in chore: update changelog August 11-14 CLI and Platform releases #362)
• Implementation: kosli-dev/server#6428