Merge remote-tracking branch 'origin/main' into fix/ai-5975-tool-error-propagation

Author: suryaiyer95

.opencode/skills/data-viz/SKILL.md

@@ -100,6 +100,8 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - **Responsive**: `min-h-[VALUE]` on all charts. Grid stacks on mobile
 - **Animation**: Entry transitions only, `duration-300` to `duration-500`. Never continuous
 - **Accessibility**: `aria-label` on charts, WCAG AA contrast, don't rely on color alone
+- **Dynamic color safety**: When colors come from external sources (brand palettes, category maps, API data, user config), never apply them directly as text color without a contrast check. Dark colors are invisible on dark card backgrounds. Safe pattern: use the external color only for non-text elements (left border, dot, underline); always use the standard text color (white / `var(--text)`) for the label itself. If color-coded text is required, apply a minimum lightness floor: `color: hsl(from brandColor h s max(l, 60%))`
+- **Icon semantics**: Verify every icon matches its label's actual meaning, not just its visual shape. Common traps: using a rising-trend icon (📈) for metrics where lower is better (latency, error rate, cost); using achievement icons (🏆) for plain counts. When in doubt, use a neutral descriptive icon over a thematic one that could mislead
 
 ### Step 5: Interactivity & Annotations
 
@@ -133,3 +135,16 @@ A single insight might just be one chart with a headline and annotation. Scale c
 - Pie charts > 5 slices — use horizontal bar
 - Unlabeled dual y-axes — use two separate charts
 - Truncated bar axes — always start at zero
+- Filtering or mapping over a field not confirmed to exist in the data export — an undefined field in `.filter()` or `.map()` produces empty arrays or NaN silently, not an error; always validate the exported schema matches what the chart code consumes
+
+## Pre-Delivery Checklist
+
+Before marking a dashboard complete:
+
+- [ ] Every tab / view activated — all charts render (no blank canvases, no unexpected 0–1 axes)
+- [ ] Every field referenced in chart/filter code confirmed present in the data export
+- [ ] All text readable on its background — check explicitly when colors come from external data
+- [ ] All icons match their label's meaning
+- [ ] Tooltips appear on hover for every chart
+- [ ] No chart silently receives an empty dataset — add a visible empty state or console warning
+- [ ] Mobile: grid stacks correctly, no body-level horizontal overflow

.opencode/skills/data-viz/references/component-guide.md

@@ -392,3 +392,70 @@ const CalloutLabel = ({ viewBox, label, color = "#1e293b" }: { viewBox?: { x: nu
 ```
 
 **Rules:** Never overlap data. Use `position: "insideTopRight"/"insideTopLeft"` on labels. Pair annotations with tooltips — annotation names the event, tooltip shows the value.
+
+---
+
+## Multi-Tab Dashboard — Lazy Chart Initialization
+
+Charts initialized inside a hidden container (`display:none`) render blank. Chart.js, Recharts, and Nivo all read container dimensions at mount time — a hidden container measures as `0×0`.
+
+**Rule: never initialize a chart until its container is visible.**
+
+```js
+// Vanilla JS pattern
+var _inited = {};
+
+function activateTab(name) {
+  // 1. make the tab visible first
+  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));
+  document.getElementById('tab-' + name).classList.add('active');
+  // 2. then initialize charts — only on first visit
+  if (!_inited[name]) {
+    _inited[name] = true;
+    initChartsFor(name);
+  }
+}
+
+activateTab('overview'); // init the default visible tab on page load
+```
+
+Library-specific notes:
+- **Chart.js**: canvas reads as `0×0` inside `display:none` — bars/lines never appear
+- **Recharts `ResponsiveContainer`**: reads `clientWidth = 0` — chart collapses to nothing
+- **Nivo `Responsive*`**: uses `ResizeObserver` — fires once at `0×0`, never re-fires on show
+- **React conditional rendering**: prefer `visibility:hidden` + `position:absolute` over toggling `display:none` if you want charts to stay mounted and pre-rendered
+
+---
+
+## Programmatic Dashboard Generation — Data-Code Separation
+
+When generating a standalone HTML dashboard from a script (Python, shell, etc.), never embed JSON data inside a template string that also contains JavaScript. Curly-brace collisions in f-strings / template literals cause silent JS parse failures that are hard to debug.
+
+**Wrong** — data and JS logic share one f-string, every `{` in JS must be escaped as `{{`:
+
+```python
+html = f"""
+<script>
+  const data = {json.dumps(data)};          // fine
+  const fn = () => {{ return x; }}           // must escape — easy to miss
+  const obj = {{ key: getValue() }};         // one missed escape = blank page
+</script>
+"""
+```
+
+**Right** — separate data from logic entirely:
+
+```python
+# Step 1: write data to its own file — no template string needed
+with open('data.js', 'w') as f:
+    f.write('const DATA = ' + json.dumps(data) + ';')
+
+# Step 2: HTML loads both files; app.js is static and never needs escaping
+```
+
+```html
+<script src="data.js"></script>   <!-- generated, data only -->
+<script src="app.js"></script>    <!-- static, logic only   -->
+```
+
+Benefits: `app.js` is static and independently testable; `data.js` is regenerated without touching logic; no escaping required in either file.

CHANGELOG.md

@@ -32,7 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Recap (renamed from Tracer)** — session recap with loop detection and enhanced viewer (#381)
+- **Trace (session recording)** — session trace with loop detection and enhanced viewer (#381)
 - **ESM bundling regression tests** — 9 e2e tests verifying Node can load `altimate-dbt` via symlink, wrapper, and direct invocation paths
 
 ### Testing

README.md

@@ -131,8 +131,8 @@ Manifest parsing, test generation, model scaffolding, incremental model detectio
 ### Data Visualization
 Interactive charts and dashboards from SQL results. The data-viz skill generates publication-ready visualizations with automatic chart type selection based on your data.
 
-### Local-First Recap
-Built-in observability for AI interactions — recap tool calls, token usage, and session activity locally. No external services required. View recaps with `altimate recap`. Features include loop detection, post-session summary, and shareable HTML exports.
+### Local-First Tracing
+Built-in observability for AI interactions — trace tool calls, token usage, and session activity locally. No external services required. View session recordings with `altimate trace`. Features include loop detection, post-session summary, and shareable HTML exports.
 
 ### AI Teammate Training
 Teach your AI teammate project-specific patterns, naming conventions, and best practices. The training system learns from examples and applies rules automatically across sessions.

…ocs/assets/images/recap/summary-full.png …ocs/assets/images/trace/summary-full.pngdocs/docs/assets/images/recap/summary-full.png renamed to docs/docs/assets/images/trace/summary-full.png docs/docs/assets/images/recap/summary-full.png renamed to docs/docs/assets/images/trace/summary-full.png

@@ -1,31 +1,28 @@
-# Recap
+# Trace
 
-Altimate Code captures detailed recaps of every session, including LLM generations, tool calls, token usage, cost, and timing, and saves them locally as JSON files. Recaps are invaluable for debugging agent behavior, optimizing cost, and understanding how the agent solves problems.
+Altimate Code captures detailed traces (session recordings) of every session, including LLM generations, tool calls, token usage, cost, and timing, and saves them locally as JSON files. Traces are invaluable for debugging agent behavior, optimizing cost, and understanding how the agent solves problems.
 
-Recap is **enabled by default** and requires no configuration. Recaps are stored locally and never leave your machine unless you configure a remote exporter.
+Tracing is **enabled by default** and requires no configuration. Traces are stored locally and never leave your machine unless you configure a remote exporter.
 
-![Recap Summary View](../assets/images/recap/summary-tab.png)
-
-!!! note "Renamed from Tracer"
-    The tracer feature has been renamed to **recap**. The `trace` command still works as a backward-compatible alias (`--no-trace` is the backward-compatible flag name). New features include loop detection, post-session summary, and shareable HTML exports.
+![Trace Summary View](../assets/images/trace/summary-tab.png)
 
 ## Quick Start
 
 ```bash
-# Run a prompt (recap is saved automatically)
+# Run a prompt (trace is saved automatically)
 altimate-code run "optimize my most expensive queries"
-# → Recap saved: ~/.local/share/altimate-code/traces/abc123.json
+# → Trace saved: ~/.local/share/altimate-code/traces/abc123.json
 
-# List recent recaps
-altimate-code recap list
+# List recent traces
+altimate-code trace list
 
-# View a recap in the browser
-altimate-code recap view abc123
+# View a trace in the browser
+altimate-code trace view abc123
 ```
 
 ## What's Captured
 
-Each recap records the full agent session:
+Each trace records the full agent session:
 
 | Data | Description |
 |------|-------------|
@@ -41,7 +38,7 @@ Each recap records the full agent session:
 
 ### Data Engineering Attributes
 
-When using SQL and dbt tools, recaps automatically capture domain-specific data:
+When using SQL and dbt tools, traces automatically capture domain-specific data:
 
 | Category | Examples |
 |----------|----------|
@@ -51,7 +48,7 @@ When using SQL and dbt tools, recaps automatically capture domain-specific data:
 | **Data Quality** | Row counts, null percentages, freshness, anomaly detection |
 | **Cost Attribution** | LLM cost + warehouse compute cost + storage delta = total cost, per user/team/project |
 
-These attributes are purely optional. Recaps are valid without them. They're populated automatically by tools that have access to warehouse metadata.
+These attributes are purely optional. Traces are valid without them. They're populated automatically by tools that have access to warehouse metadata.
 
 ## Configuration
 
@@ -70,12 +67,12 @@ Add to your config file (`~/.config/altimate-code/altimate-code.json` or project
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `enabled` | `boolean` | `true` | Enable or disable recap |
-| `dir` | `string` | `~/.local/share/altimate-code/traces/` | Custom directory for recap files |
-| `maxFiles` | `number` | `100` | Max recap files to keep (oldest pruned automatically). Set to `0` for unlimited |
+| `enabled` | `boolean` | `true` | Enable or disable tracing |
+| `dir` | `string` | `~/.local/share/altimate-code/traces/` | Custom directory for trace files |
+| `maxFiles` | `number` | `100` | Max trace files to keep (oldest pruned automatically). Set to `0` for unlimited |
 | `exporters` | `array` | `[]` | Remote HTTP exporters (see below) |
 
-### Disabling Recap
+### Disabling Tracing
 
 ```json
 {
@@ -91,15 +88,15 @@ Or per-run with the `--no-trace` flag:
 altimate-code run --no-trace "quick question"
 ```
 
-## Viewing Recaps
+## Viewing Traces
 
-### List Recaps
+### List Traces
 
 ```bash
-altimate-code recap list
+altimate-code trace list
 ```
 
-Shows a table of recent recaps with session ID, timestamp, duration, tokens, cost, tool calls, and status.
+Shows a table of recent traces with session ID, timestamp, duration, tokens, cost, tool calls, and status.
 
 ```
 SESSION              WHEN       DURATION   TOKENS     COST       TOOLS  STATUS     PROMPT
@@ -112,17 +109,17 @@ Options:
 
 | Flag | Description |
 |------|-------------|
-| `-n`, `--limit` | Number of recaps to show (default: 20) |
+| `-n`, `--limit` | Number of traces to show (default: 20) |
 
-### View a Recap
+### View a Trace
 
 ```bash
-altimate-code recap view <session-id>
+altimate-code trace view <session-id>
 ```
 
-Opens a local web server with an interactive recap viewer in your browser.
+Opens a local web server with an interactive trace viewer in your browser.
 
-![Recap Full View](../assets/images/recap/summary-full.png)
+![Trace Full View](../assets/images/trace/summary-full.png)
 
 The viewer has 5 tabs:
 
@@ -148,35 +145,35 @@ Options:
 | `--port` | Port for the viewer server (default: random) |
 | `--live` | Auto-refresh every 2s for in-progress sessions |
 
-Partial session ID matching is supported. For example, `altimate-code recap view abc` matches `abc123def456`.
+Partial session ID matching is supported. For example, `altimate-code trace view abc` matches `abc123def456`.
 
 ### Live Viewing (In-Progress Sessions)
 
-Recaps are written incrementally. After every tool call and generation, a snapshot is flushed to disk. This means you can view a recap while the session is still running:
+Traces are written incrementally. After every tool call and generation, a snapshot is flushed to disk. This means you can view a trace while the session is still running:
 
 ```bash
 # In terminal 1: run a long task
 altimate-code run "refactor the entire pipeline"
 
-# In terminal 2: watch the recap live
-altimate-code recap view <session-id> --live
+# In terminal 2: watch the trace live
+altimate-code trace view <session-id> --live
 ```
 
 The `--live` flag adds a green "LIVE" indicator and polls for updates every 2 seconds. The page auto-refreshes when new spans appear.
 
 ### From the TUI
 
-Type `/recap` in the TUI to open a recap history dialog listing all recent sessions. Select any recap to open it in your browser with the interactive viewer. The current session appears at the top, and recaps are grouped by date with duration and timestamp info.
+Type `/trace` in the TUI to open a trace history dialog listing all recent sessions. Select any trace to open it in your browser with the interactive viewer. The current session appears at the top, and traces are grouped by date with duration and timestamp info.
 
 The viewer launches in live mode automatically for in-progress sessions, so you can watch spans appear as the agent works.
 
-### Sharing Recaps
+### Sharing Traces
 
-The recap viewer includes a **Share** button that exports a self-contained HTML file. This file includes all session data and can be opened in any browser without a server — perfect for sharing with teammates, attaching to tickets, or archiving sessions.
+The trace viewer includes a **Share Trace** button that exports a self-contained HTML file. This file includes all session data and can be opened in any browser without a server — perfect for sharing with teammates, attaching to tickets, or archiving sessions.
 
 ## Remote Exporters
 
-Recaps can be sent to remote backends via HTTP POST. Each exporter receives the full recap JSON on session completion.
+Traces can be sent to remote backends via HTTP POST. Each exporter receives the full trace JSON on session completion.
 
 ```json
 {
@@ -197,7 +194,7 @@ Recaps can be sent to remote backends via HTTP POST. Each exporter receives the
 | Field | Type | Description |
 |-------|------|-------------|
 | `name` | `string` | Identifier for this exporter (used in logs) |
-| `endpoint` | `string` | HTTP endpoint to POST recap JSON to |
+| `endpoint` | `string` | HTTP endpoint to POST trace JSON to |
 | `headers` | `object` | Custom headers (e.g., auth tokens) |
 
 **How it works:**
@@ -208,9 +205,9 @@ Recaps can be sent to remote backends via HTTP POST. Each exporter receives the
 - Exporters have a 10-second timeout
 - All export operations are best-effort and never crash the CLI
 
-## Recap File Format
+## Trace File Format
 
-Recaps are stored as JSON files in the traces directory. The schema is versioned for forward compatibility.
+Traces are stored as JSON files in the traces directory. The schema is versioned for forward compatibility.
 
 ```json
 {
@@ -322,15 +319,15 @@ All domain-specific attributes use the `de.*` prefix and are stored in the `attr
 
 ## Crash Recovery
 
-Recaps are designed to survive process crashes:
+Traces are designed to survive process crashes:
 
-1. **Immediate snapshot.** A recap file is written as soon as the session starts, before any LLM interaction. Even if the process crashes immediately, a minimal recap file exists.
+1. **Immediate snapshot.** A trace file is written as soon as the session starts, before any LLM interaction. Even if the process crashes immediately, a minimal trace file exists.
 
-2. **Incremental snapshots.** After every tool call and generation completion, the recap file is updated atomically (write to temp file, then rename). The file on disk always contains a valid, complete JSON document.
+2. **Incremental snapshots.** After every tool call and generation completion, the trace file is updated atomically (write to temp file, then rename). The file on disk always contains a valid, complete JSON document.
 
-3. **Crash handlers.** The `run` command registers `SIGINT`/`SIGTERM`/`beforeExit` handlers that flush the recap synchronously with a `"crashed"` status.
+3. **Crash handlers.** The `run` command registers `SIGINT`/`SIGTERM`/`beforeExit` handlers that flush the trace synchronously with a `"crashed"` status.
 
-4. **Status indicators.** Recap status tells you exactly what happened:
+4. **Status indicators.** Trace status tells you exactly what happened:
 
 | Status | Meaning |
 |--------|---------|
@@ -339,31 +336,31 @@ Recaps are designed to survive process crashes:
 | `running` | Session is still in progress (visible in live mode) |
 | `crashed` | Process was interrupted before the session completed |
 
-Crashed recaps contain all data up to the last successful snapshot. You can view them normally with `altimate-code recap view`.
+Crashed traces contain all data up to the last successful snapshot. You can view them normally with `altimate-code trace view`.
 
-## Historical Recaps
+## Historical Traces
 
-All recaps are stored in the traces directory and persist across sessions. Use `recap list` to browse history:
+All traces are stored in the traces directory and persist across sessions. Use `trace list` to browse history:
 
 ```bash
-# Show the last 50 recaps
-altimate-code recap list -n 50
+# Show the last 50 traces
+altimate-code trace list -n 50
 
-# View any historical recap
-altimate-code recap view <session-id>
+# View any historical trace
+altimate-code trace view <session-id>
 ```
 
-Recaps are automatically pruned when `maxFiles` is exceeded (default: 100). The oldest recaps are removed first. Set `maxFiles: 0` for unlimited retention.
+Traces are automatically pruned when `maxFiles` is exceeded (default: 100). The oldest traces are removed first. Set `maxFiles: 0` for unlimited retention.
 
 ## Privacy
 
-Recaps are stored **locally only** by default. They contain:
+Traces are stored **locally only** by default. They contain:
 
 - The prompt you sent
 - Tool inputs and outputs (SQL queries, file contents, command results)
 - Model responses
 
-If you configure remote exporters, recap data is sent to those endpoints. No recap data is included in the anonymous telemetry described in [Telemetry](../reference/telemetry.md).
+If you configure remote exporters, trace data is sent to those endpoints. No trace data is included in the anonymous telemetry described in [Telemetry](../reference/telemetry.md).
 
 !!! warning "Sensitive Data"
-    Recaps may contain SQL queries, file paths, and command outputs from your session. If you share recap files or configure remote exporters, be aware that this data will be included.
+    Traces may contain SQL queries, file paths, and command outputs from your session. If you share trace files or configure remote exporters, be aware that this data will be included.

…docs/assets/images/recap/summary-tab.png …docs/assets/images/trace/summary-tab.pngdocs/docs/assets/images/recap/summary-tab.png renamed to docs/docs/assets/images/trace/summary-tab.png docs/docs/assets/images/recap/summary-tab.png renamed to docs/docs/assets/images/trace/summary-tab.png

@@ -137,16 +137,16 @@ fi
 
 ---
 
-## Recap in Headless Mode
+## Traces in Headless Mode
 
-Recap works in headless mode. View recaps after the run:
+Tracing works in headless mode. View traces (session recordings) after the run:
 
 ```bash
-altimate recap list
-altimate recap view <session-id>
+altimate trace list
+altimate trace view <session-id>
 ```
 
-See [Recap](../../configure/recap.md) for the full recap reference.
+See [Trace](../../configure/trace.md) for the full trace reference.
 
 ---