Problem / use case

With group + --col-axis (-A), numeric columns expand onto an axis and each expanded stat gets an empty type (so they stay one chart instead of one chart per column).

The UI then falls back:

chart title = stats[].type || dataset.name (-n) || ""

So by default the page/dataset name and the chart title (series name, save-as-image label, card title) are the same string — usually -n / "Comparisons".

Today the only way to change the chart title is to change -n, which also changes the dataset header / dataset identity.

Concrete workflow

# Want: page name "Q1 release", chart title "Framework throughput"
# Today: -n sets both; no way to split them
vizb bar examples/csv/concurrency.csv -g load -p y -A x \
  -n 'Q1 release' \
  -o out.html

Relevant code:

• shared/expand.go — clears Stat.Type on expand; documents UI name fallback
• ui/src/composables/useChartPipeline.ts — chartTitle(type) => type || datasetName || ''
• cmd/cli/dataflags.go — -n is dataset name only; no chart-title flag
• Precedent: multi-stat --select … (Title) already sets stat.type via TypeLabel

Proposed solution

Add a --title flag that overrides the chart title only when group + --col-axis produces exactly one chart. Independent of -n.

Flag contract

--title string
  Override the chart title when group + --col-axis produces exactly one chart.
  Independent of -n (dataset name).
  Ignored with a warning otherwise (including multi-stat; use --select … (Title) there).

No shorthand (-T is already time-unit).

Desired usage

vizb bar data.csv -g load -p y --col-axis x \
  -n 'Q1 release' \
  --title 'Framework throughput' \
  -o out.html

How it should work

1. Add title to DataFlags (no shorthand).
2. Plumb into the pipeline (RunMeta / local arg preferred; parsers do not need it).
3. After ExpandStatsOntoAxis succeeds in applyColAxis, if --title is non-empty, set every expanded stat’s Type to that string.
4. All points share one type → still one signature / one chart.
5. UI already shows type as title → no Dataset schema or UI change required.
6. If --title is omitted → keep empty type → fall back to -n (current behavior).
7. If --title is set but col-axis did not apply → warn once and ignore.

Single-chart gate

Implementation notes

Files (expected):

• cmd/cli/dataflags.go — flag definition
• cmd/cli/flagbag.go — Meta() / plumbing
• cmd/cli/pipeline.go — applyColAxis apply + warn paths
• cmd/cli/pipeline_test.go — suite tests
• examples/csv/README.md — concurrency section
• Optional: CHANGELOG, comparisons skill example

Do not:

• Add a Dataset.chartTitle schema field (reuse stat.type)
• Remove or repurpose --select {label} (axis/column labels) or (Title) (multi-stat tab names)
• Apply --title to multi-chart datasets
• Use -d description as chart title

Acceptance criteria

• --title + successful group + --col-axis → one chart, stats[].type == title, dataset.name == -n
• Group + --col-axis without --title → empty type, UI falls back to -n (unchanged)
• --title without col-axis / multi-column multi-chart → warning, types unchanged
• Multi-stat: --title ignored; --select … (Title) still works
• Col-axis skip paths + --title → warning
• Existing col-axis fatals (axis conflict, z without x+y) unchanged
• JSON output: emitted stats[].type equals title when applied
• Docs/example mention the flag for the concurrency / competitor compare flow

Test paths

• Happy: group + -A + --title → one chart, name and title differ
• Default: group + -A, no title → empty type
• Multi-chart reject: --title without -A on multi-column data → warn
• Multi-stat: --title ignored; (Title) still works
• Col-axis skip + title → warn
• Existing col-axis fatals unchanged

Alternatives considered

1. Only use -n — works for a “nice” chart title but forces page header == chart title. Rejected.

2. New Dataset.chartTitle field + UI fallback (title || type || name) — cleaner long-term if we need display title independent of stat.type everywhere; more cost (Go struct, migrate, TS types, merge policy). Overkill for this gap; skip until needed.

3. Remove --select title-ish syntax and fold into global --title — investigated and rejected:

   • col{label} is axis/column labels (group-pattern, value-mode "x vs y", dataset auto-names) — not the same as chart title.
   • Trailing (Title) is per multi-stat tab name; multi-chart needs per-view names, which a single global --title cannot replace.
   • Keep both; add --title only for the col-axis single-chart hole.

4. Use -d description — wrong UI slot (subtitle under header, not series/chart title). Rejected.

5. Broader --title for any single chart (including solo value mode) — out of scope for v1; value-mode already titles from axis labels.