# Surface Map

Use this quick map when a consumer needs one output path and the package emits
several related fields.

| Field | Meaning | Prefer it when | Do not assume |
|------|---------|----------------|---------------|
| `artifact` | Generic primary artifact path for a call or run. | You need a backward-compatible or workflow-agnostic artifact pointer. | That it is always the final model answer. |
| `response` | Canonical preserved final-answer artifact for freeform-style runs. | You need the final model answer and the field is present. | That every provider or phase emits it. |
| `raw_output_artifact` | Provider-direct output captured before higher-level normalization. | You need raw provider output or a fallback when higher-level response metadata is absent. | That it is user-friendly, final, or schema-normalized. |
| `conversation_log` | Structured transcript or transcript-like provider conversation surface. | You need transcript facts, message/tool counts, or provider-native debugging. | That it is a Markdown share/export view. |
| human-readable sidecar | Rendered share/export transcript or convenience view. | A human needs quick reading and no structured parsing is required. | That downstream parsers should depend on it. |

## Quick Rules

- Prefer `response` over `artifact` when the task is explicitly about the final
  preserved answer.
- Keep `artifact` for generic tooling and older consumers even when `response`
  points at the same file.
- Prefer `conversation_log` for transcript checks and policy evaluation.
- Use `derive_transcript_facts(...)` when you only need high-level shared facts
  rather than provider-specific event parsing.
