skills/visualize-data/references/inline-sources-receipt.md

# Inline Sources Receipt

Use this delivery reference for every source-backed inline Data answer on Codex Desktop outside positively identified Work Mode, including answers with no chart. It does not select the response mode, replace a requested report/dashboard, or change existing chart source actions. Work Mode keeps its native delivery contract.

## Capture the evidence

Keep explanatory text and material qualifications in native chat. Render an initially collapsed Sources receipt immediately below each inline chart, before any following prose or chart. Each receipt contains only the findings shown in that chart. For a text-only answer, render one receipt after the native answer. For a mixed answer, add a final receipt only for additional source-backed findings that no chart covers; do not repeat the chart findings there.

The collapsed row reads **Sources** for one finding and **Sources • N** for multiple findings, where `N` counts finding cards within that receipt. Use one card per distinct supported question/finding; give each its own recorded evidence. All sources for one finding appear together in one consolidated Overview and Evidence flow; there is no source selector or repeated per-source Overview. Within a finding, shared definitions, filters, caveats, source identities, and identical evidence steps appear once. Differing definitions, reporting periods, and qualifications retain their recorded ownership internally. Express any essential difference in the definition or qualification itself. Do not append repeated query/source-name annotations to explanatory content, calculations, timestamps, shared caveats, or filter groups. Write each assumption and caveat as a self-contained sentence that names the relevant metric, population, source, or limitation when needed to make its scope clear. For example, write “The survey excludes free users,” not “Survey data: Free users excluded.” Never rely on an automatic source-name prefix: Overview renders the authored sentence without adding attribution. Preserve source ownership in the underlying provenance. Identical qualification sentences appear once. Distinct tables and exact queries stay separate and use source labels only when more than one contributes to that tab. Do not merge different findings just because their queries coincide.

Build a separate JSON payload for each receipt with `schemaVersion: 1` and ordered `items`. Each item requires a stable lowercase-hyphenated `id`, a reader-facing `title`, and `queries`. Usually omit `description`; use it only for essential subject context absent from the definition and native answer. Each query requires its own stable `id` and a Data `source` with `label`. The same query ID can occur in different cards, but IDs within a card must be unique. Every query and row included must support that card's finding; do not attach unrelated tool results. A query may support more than one chart: include it in each relevant receipt, preserving the definitions, filters, and caveats needed to understand that chart.


Keep unanswered portions explicit in native prose and omit unsupported answer items. A correct statement that the available data cannot establish a cause does not support a causal claim; a chart of the observed change can still show that descriptive finding with a clearly scoped title. Use the existing source and result checks to explain what the evidence establishes and its most consequential limit when useful, without assigning a confidence tier or implying checks that were not performed.

Use optional item-level `assumptions: ["..."]` only for material interpretive assumptions about that finding (at most 20, each at most 2,000 characters). They appear alongside recorded `source.caveats` under **Assumptions and caveats** in Overview, without changing their provenance or converting a caveat into an assumption. Keep observed checks in `evidenceFlow` and material uncertainty in the native answer too. The Data Sources payload does not accept a `confidence` field.

Use the existing source fields: `tables`, `files`, `links`, `metricDefinitions`, `filters`, `caveats`, recorded `executedAt`, exact `sql` or `source.query.sql`, and optional recorded `evidenceFlow`. Write parallel, term-led definition sentences when there is more than one; Definitions renders them as a bulleted list. Formulas and source lineage are optional and must be supported. Show a formula beneath its definition only when it materially clarifies the metric beyond the sentence; otherwise leave the definition concise and keep result-specific arithmetic in the recorded calculation. Do not duplicate subtitles for symmetry. `componentIds` on definitions refer to item IDs. Preserve every result-changing predicate in the exact SQL or explicit source metadata, even when its field is absent from preview rows. Use `source.filters` for concise reader-facing scope and additional filtering not represented in SQL; do not transcribe every WHERE predicate into a second list. When SQL is unavailable, record the applied filters explicitly. Write one independently readable filter per `source.filters` array entry, for example `["Plan: paid", "Country: US"]`. Never combine predicates with semicolons or compress several fields into one shared-value phrase. Keep interpretation or aggregation caveats in `caveats`, not filter pills. The renderer preserves authored strings rather than guessing how to split SQL or prose. Source labels remain readable when a verified destination is unavailable; never construct a URL from an opaque identifier.

For Snowflake, Databricks, BigQuery, or Redshift tables, read [table usage metadata](../../../shared/table-usage.md) and make the targeted best-effort lookup through the existing authorized connector before rendering. Use `source.tables` objects with `name` and optional `trust` containing observed `provider`, `queryCount`, `uniqueUsers`, `windowDays`, `lastQueriedAt`, `usageAsOf`, and `usageNote`. Counts and their scope appear with the table in Sources. Omit unavailable values, preserve the actual observation window and cutoff, and never turn a missing lookup into zero or a verification claim. Reuse a current-task lookup rather than querying again for each card; optional usage access must not block the answer or trigger a permission escalation.

The query can also contain:

| Field | Meaning |
| --- | --- |
| `summary` | Optional concise explanation of what this source supports, grounded in the source actually read. Particularly useful for documents and links without tabular results. Do not infer causal support or treat this summary as a verification badge. |
| `sourceRoles` | Optional source-chip tooltip context: up to 40 `{kind, label, href?, role}` records per query. `kind` is `table`, `file`, `link`, or `dashboard`; `label` and optional safe `href` must identify exactly one of that query's projected source chips. `role` is a reviewed explanation of at most 1,000 characters, such as "Weekly active-user counts" or "Cross-checks the dashboard counts". Prefer a short purpose over generic narration such as "Supplies the recorded aggregate counts". Never infer authority, verification, or causal support. No role is generated when absent. |
| `rows` and `columns` | Optional recorded result preview with explicit approved columns, each a field name or `{ "field": "annual_anomaly_c", "label": "Annual anomaly (°C)" }`. Supply readable labels with source-supported units; labels do not rename fields or change recorded values. Unlisted fields are excluded. Omit both when no tabular result exists; an empty recorded result uses `rows: []` with its known columns. |
| `reportingPeriod` | Recorded measurement window in readable form. Do not infer a shared period from unrelated date columns. |
| `capturedAt` | Actual snapshot capture timestamp with timezone, distinct from the reporting period and `source.executedAt`. Omit unknown timestamps. Capture/execution timestamps stay in the payload for audit and do not create reader-facing snapshot prose or an Evidence flow tab; never describe capture time as data freshness. |
| `methods` | Optional records with `language: "python"` or `"calculation"` and exact recorded `code`. At most one of each; SQL stays in the source. These are display-only and never executed. |
| `preview` | For a sample, partial, or aggregate preview: `kind: "sample"`, `"partial"`, or `"aggregate"`, a required explanatory `note`, and optional recorded `totalRows`. Never label a partial preview as the complete result. |

Source chips reuse the report source-preview card layout for hover and focus inspection. Within that card, the icon matches the source chip's asset, color, and rendered size. Use distinct OpenAI glyphs for tables, files, dashboards, and links. A file with a recorded document, presentation, code, image, video, or audio extension gets that format's glyph; other filenames use the generic file glyph. The glyph is a presentation of the filename, not a verified MIME type or source-authority signal. A source without a safe destination retains the default cursor and the same hover treatment as a linked source; only an actual link gets the pointer cursor. The first mouse hover waits briefly before opening, while moving to another source with a card already open replaces its content immediately. Keyboard focus opens the card without a mouse hover delay.

The receipt uses `Overview`, `Data preview`, `SQL query`, and `Evidence flow`, omitting tabs without recorded evidence. Overview sizes to its content. Other tabs share that measured height and scroll internally, so switching tabs, paging through rows, or expanding evidence usually does not move the following conversation. An exceptionally short Overview gets a reading-height floor on the other tabs instead of making them unusably small; the conversation moves once when leaving or returning to that Overview. Recalculate the anchor when the receipt width changes. Local tab and pagination state is retained. When Overview is the only section, show its content directly without a tab bar.

Keep Overview brief: the meaning of the measure, its essential scope, and source identities. Show unboxed definition prose under **Definitions**, a single **Assumptions and caveats** section when either is recorded, and source identities under **Sources**. Omit absent sections. Include a short, source-backed assumption or caveat here only when it materially changes how the answer should be interpreted. Write it naturally within the relevant definition or document summary; add no mandatory section, generic warning, full filter list, or execution narration. Preserve its own source scope and keep material qualifications in the native answer too. Write each definition as a natural sentence, including the metric name where it reads naturally ("Weekly active users count distinct users..."); do not prepend a "Name: definition" label. Attach the few filters needed to interpret the measure directly to its definition in plain language ("across all plans", "among paid accounts"). Choose only scope supported by that definition's own query; never infer a shared scope from another query. Omit generic definitions of percentage change or other familiar arithmetic. Use the optional `calculationSummary` only when it adds a distinct method, comparison window, or denominator rule that the definition and reporting period do not already make clear (for example, "Count distinct users in the seven-day windows ending August 16 and 23, 2026"). Merely substituting the example's numbers into the definition is not useful. The subtitle must be grounded in that definition's own query, never inferred from SQL or another query. It appears directly below the definition in secondary text. Use a supported `formula` instead only when its math is not already obvious from the definition. Omit both for straightforward measures; keep worked arithmetic in the recorded Calculation evidence. Show each definition and any useful summary once in Overview. Calculation in Evidence flow adds only supplemental formulas hidden by a summary, worked arithmetic, and exact Python; do not repeat the Overview text there.

There is no Details disclosure or standalone date paragraph in Overview. Preserve all recorded filters and `reportingPeriod`; Evidence flow groups them inside the expandable **Filters and reporting period** checkpoint. The reporting period is a filter and uses exactly the same pill, font, size, weight, and color as the other filters. Use one continuous wrapping list, not separate per-source groups. Show the measurement/comparison window once in `reportingPeriod` (for example, "Aug 10–16 vs Aug 17–23, 2026"); do not also author synonymous "Reporting dates" and "Window" filters when they describe that same window. Keep an additional date field only when it has a distinct meaning, such as order date versus delivery date, and name that meaning. Preserve the exact date predicates in SQL and the dated returned rows. Never infer equivalent windows by parsing free text. Identical periods/filters consolidate by recorded ownership. Only filters shared by all contributing quantitative queries appear unqualified in Evidence flow. The SQL tab contains the identifying source heading, exact SQL, and a provider query link when recorded, with no filter pills. Keep additional authored periods and filters in Evidence flow with an explicit source label when they are query-specific, whether or not SQL exists. The renderer does not assume that SQL covers all authored filter metadata; avoid redundant metadata during source review rather than guessing equivalence at runtime. A filter missing from another query is not shared, even if no other value conflicts with it. Do not discard source scope to reduce visual repetition. Source names belong in the Sources list and Source selection table; retain identifying headings only where needed to distinguish separate data tables or SQL queries. Only add **Definitions** for extra lineage or definition evidence beyond Overview. **Source selection** explains why sources were used, without repeating the Sources list when no rationale exists. **Calculation** and **Verification** contain additional methods and recorded checks. Source caveats appear in Overview rather than being repeated in Verification. Do not create a checkpoint solely for a navigation link, row count, capture time, or repeated Overview content. `evidenceFlow` entries should include an explicit `kind`: `question`, `definition` (or `metric`), `source`, `filter`, `calculation` (or `method`), or `validation`/`result`. Use `showInReceipt: false` for routine execution notes retained only as audit metadata, such as reading rows, query completion, and successful non-truncation. This is an explicit disclosure choice, never a heuristic that hides errors: material limitations, incomplete results, failed checks, repairs that affect interpretation, and source-selection decisions remain visible. Their recorded prose stays in the payload. Suppress generic nested labels like "Calculation" or "Method" beneath the Calculation heading. Render human-readable formulas and arithmetic in the same body-text style; preserve whitespace and use code formatting only for actual SQL/Python. Untyped legacy entries keep their original titles as separate steps; the renderer never guesses a checkpoint from prose. State each distinct limitation once within the receipt; merge overlapping caveats without losing a qualification. Material limitations also remain in the native answer.

For document-backed answers, use a short `summary` only when it supplies subject context absent from a definition. State the meaning directly ("People active in the preceding seven days"), not narration about the evidence ("The full schema describes...", "The query returned...", "These sources agree..."). Put observed checks in Evidence flow. Do not add a finding-level description just because several sources contribute. Source labels should be concise identities such as "Codex engagement"; do not append "executed query", "reviewed source", or similar process labels. Keep the exact query link and SQL in their existing fields. Recorded metadata is still evidence, not text that must all be visible by default.

Document-backed answers need no fake rows, SQL, or workflow. Recorded filters, source rationales, or secondary context can justify an Evidence flow tab without SQL or rows; caveats alone appear in Overview and do not create that tab; metadata appears within its appropriate numbered checkpoint without inventing execution, checks, or status. Omit that tab when neither supporting metadata nor recorded operations are available. Do not manufacture an execution trace, verified badge, confidence score, or proof step. A check requires a specific observed result, not an assertion that the answer was verified. Label illustrative data clearly.

## Disclosure and safety

Include available, reviewed SQL/Python/calculations and safe source links in the receipt automatically; no separate user request or `--include-sql`/`--include-source-urls` flag is needed for this renderer. Keep raw code out of native answer prose unless requested. The chart renderer requires its own explicit SQL inclusion or omission choice after the review described in [inline-chart-renderer.md](inline-chart-renderer.md); chart source URLs still need its separate opt-in.

The receipt embeds its approved evidence at creation; collapsing it is not an access boundary. Include only evidence obtained through existing authorized sources and scoped to this answer. Remove credentials, tokens, direct personal contact/payment identifiers, hidden reasoning, local absolute paths, and unrelated result fields before rendering. Ordinary source links must be HTTP(S) destinations without credentials, query parameters, fragments, or token-bearing paths; keep a source label when its only URL is unsafe. Preserve an exact provider-issued query, worksheet, or query-history URL in `source.queryUrl` when available. The SQL tab accepts recognized Snowflake and Databricks query routes, including their narrowly allowed locator parameters and fragments; never construct a URL or embed SQL in it. Review code for embedded secrets too. The validator helps enforce projection and detects common unsafe values; it cannot certify arbitrary content as safe.

Keep the input below 2 MB and the complete receipt below 1 MB. At most 20 cards, 10 queries per card, and 2,000 preview rows across the receipt are supported. If necessary, produce a smaller explicitly labeled preview from the recorded result; do not silently discard material evidence or imply all underlying rows are included.

## Render and deliver

The default Classic receipt inherits the conversation's live background, foreground, secondary text, border, popover, accent, and focus tokens. Its subtle surfaces and source icon colors derive from theme tokens. Explicitly selected Data themes retain their own surface and text palette.

Call `load_workspace_dependencies` and use its absolute bundled Node executable as `<codex-node>`. Resolve the CLI from the installed Data plugin root. The bundled example is synthetic and is available through `--example`.

```sh
"<codex-node>" "<data-plugin-root>/skills/visualize-data/scripts/render-inline-sources.mjs" \
  --input /absolute/path/reviewed-sources.json \
  --output /absolute/approved/visualizations/answer-sources.html
```

The renderer verifies the shipped, data-free receipt runtime and writes a private fragment outside the plugin and shared caches. It requires no per-answer build, dependency installation, source fetch, or publication. Render each receipt to a distinct output filename and use each returned path unchanged in exactly one native Visualize content reference. Place each chart receipt immediately after its chart reference; place a text-only or additional-findings receipt after the native answer as described above:

```text
visualize{"path":"/absolute/approved/visualizations/answer-sources.html"}
```

Do not deliver raw HTML, a download, a code block, duplicated answer prose, or a promise instead of the receipt. Do not replace the existing chart inspector or change Desktop host code. All receipt interactions are local; opening a source URL is an explicit user link action, not an automatic fetch.

If evidence is missing, state the material gap and omit unsupported cards. If validation or rendering fails, correct the specific payload problem or preserve the native answer and its available citations with a concise delivery limitation. Do not invent evidence, silently change output mode, or claim the receipt rendered without its native reference.