altimate-code 0.4.9 → 0.5.0

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

@@ -0,0 +1,394 @@
+# Component Library Reference
+
+Non-obvious patterns, gotchas, and custom implementations. Standard library usage (basic bar/line/area/pie/scatter) is well-documented — this covers what agents get wrong or can't infer.
+
+## Table of Contents
+
+1. [shadcn/ui Charts](#shadcnui-charts) — Config pattern & key rules
+2. [Tremor Essentials](#tremor-essentials) — KPI cards, dashboard grid
+3. [Nivo Gotchas](#nivo-gotchas) — Height wrapper, common props
+4. [D3 + React Pattern](#d3--react-pattern) — Force-directed DAG
+5. [Layout Patterns](#layout-patterns) — Dashboard grid, card component
+6. [Color Systems](#color-systems) — Semantic, sequential, diverging, categorical
+7. [Data Transformations](#data-transformations) — Recharts pivot, KPI aggregate, treemap, time bucketing
+8. [Waterfall Chart](#waterfall-chart) — Custom Recharts pattern
+9. [Radar / Spider Chart](#radar--spider-chart) — Key rules
+10. [Calendar Heatmap](#calendar-heatmap) — Nivo setup
+11. [Annotation Patterns](#annotation-patterns) — Goal lines, highlights, callouts, anomaly dots
+
+---
+
+## shadcn/ui Charts
+
+Built on Recharts with themed, accessible wrappers. **Unique config pattern — don't skip this.**
+
+```tsx
+import { type ChartConfig } from "@/components/ui/chart"
+
+const chartConfig = {
+  revenue: { label: "Revenue", color: "hsl(var(--chart-1))" },
+  expenses: { label: "Expenses", color: "hsl(var(--chart-2))" },
+} satisfies ChartConfig
+```
+
+**Key rules:**
+- Always `min-h-[VALUE]` on `ChartContainer` (required for responsiveness)
+- Use `accessibilityLayer` prop on the main chart component
+- Colors via CSS variables `var(--color-{key})`, never hardcoded
+- Use `ChartTooltip` + `ChartTooltipContent`, not Recharts defaults
+- Use `ChartLegend` + `ChartLegendContent` for interactive legends
+
+### Area Chart Gradient (common pattern)
+
+```tsx
+<defs>
+  <linearGradient id="fillRevenue" x1="0" y1="0" x2="0" y2="1">
+    <stop offset="5%" stopColor="var(--color-revenue)" stopOpacity={0.8} />
+    <stop offset="95%" stopColor="var(--color-revenue)" stopOpacity={0.1} />
+  </linearGradient>
+</defs>
+<Area type="monotone" dataKey="revenue" stroke="var(--color-revenue)" fill="url(#fillRevenue)" />
+```
+
+---
+
+## Tremor Essentials
+
+### KPI Card Pattern
+
+```tsx
+import { Card, BadgeDelta, SparkAreaChart } from "@tremor/react"
+
+<Card className="max-w-sm">
+  <div className="flex items-center justify-between">
+    <p className="text-tremor-default text-tremor-content">Revenue</p>
+    <BadgeDelta deltaType="increase" size="xs">+12.3%</BadgeDelta>
+  </div>
+  <p className="text-tremor-metric font-semibold mt-1">$1.24M</p>
+  <SparkAreaChart data={sparkData} categories={["value"]} index="date"
+    colors={["emerald"]} className="h-8 w-full mt-4" />
+</Card>
+```
+
+### Dashboard Grid
+
+```tsx
+<div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-4">
+  {kpis.map(kpi => <KPICard key={kpi.id} {...kpi} />)}
+</div>
+```
+
+### Tremor AreaChart / BarList
+
+```tsx
+<AreaChart data={data} index="month" categories={["Revenue", "Expenses"]}
+  colors={["blue", "red"]} valueFormatter={(v) => `$${(v/1000).toFixed(0)}k`}
+  className="h-72 mt-4" showAnimation />
+
+<BarList data={[{ name: "Google", value: 45632 }, ...]} className="mt-4" />
+```
+
+---
+
+## Nivo Gotchas
+
+- **Always set `height` on the wrapper div**, not on the Nivo component: `<div style={{ height: 400 }}><ResponsiveHeatMap ... /></div>`
+- Use `emptyColor="#f3f4f6"` for missing data cells
+- For heatmaps: `colors={{ type: "sequential", scheme: "blues" }}`
+- For treemaps: `identity="name"` + `value="value"` + `labelSkipSize={12}`
+- For Sankey: `enableLinkGradient` + `linkBlendMode="multiply"` for polish
+- For Choropleth: needs GeoJSON features, `projectionScale={150}`, `projectionTranslation={[0.5, 0.5]}`
+
+---
+
+## D3 + React Pattern: Force-Directed DAG
+
+Use for lineage graphs, dependency trees, pipeline DAGs. **D3 computes positions, React renders SVG.**
+
+```tsx
+import { useEffect, useRef } from "react"
+import * as d3 from "d3"
+
+interface DagNode { id: string; label: string; type: "source" | "middle" | "output" }
+interface DagLink { source: string; target: string }
+
+const NODE_COLORS: Record<DagNode["type"], { fill: string; stroke: string }> = {
+  source: { fill: "#dbeafe", stroke: "#3b82f6" },
+  middle: { fill: "#f1f5f9", stroke: "#94a3b8" },
+  output: { fill: "#dcfce7", stroke: "#22c55e" },
+}
+
+export function ForceDAG({ nodes, links }: { nodes: DagNode[]; links: DagLink[] }) {
+  const svgRef = useRef<SVGSVGElement>(null)
+
+  useEffect(() => {
+    if (!svgRef.current) return
+    const width = svgRef.current.clientWidth || 800, height = 500
+    const svg = d3.select(svgRef.current).attr("height", height)
+    svg.selectAll("*").remove()
+
+    // Arrowhead marker
+    svg.append("defs").append("marker")
+      .attr("id", "dag-arrow").attr("viewBox", "0 -5 10 10")
+      .attr("refX", 22).attr("refY", 0)
+      .attr("markerWidth", 6).attr("markerHeight", 6).attr("orient", "auto")
+      .append("path").attr("d", "M0,-5L10,0L0,5").attr("fill", "#94a3b8")
+
+    // CRITICAL: Copy arrays — D3 mutates them with x/y/vx/vy
+    const nodesCopy = nodes.map(n => ({ ...n }))
+    const linksCopy = links.map(l => ({ ...l }))
+
+    const sim = d3.forceSimulation(nodesCopy as any)
+      .force("link", d3.forceLink(linksCopy).id((d: any) => d.id).distance(140))
+      .force("charge", d3.forceManyBody().strength(-350))
+      .force("center", d3.forceCenter(width / 2, height / 2))
+      .force("collision", d3.forceCollide().radius(50))
+
+    const linkSel = svg.append("g").selectAll("line")
+      .data(linksCopy).join("line")
+      .attr("stroke", "#cbd5e1").attr("stroke-width", 1.5)
+      .attr("marker-end", "url(#dag-arrow)")
+
+    const nodeSel = svg.append("g").selectAll<SVGGElement, DagNode>("g")
+      .data(nodesCopy).join("g")
+      .call(d3.drag<SVGGElement, any>()
+        .on("start", (e, d) => { if (!e.active) sim.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y })
+        .on("drag", (e, d) => { d.fx = e.x; d.fy = e.y })
+        .on("end", (e, d) => { if (!e.active) sim.alphaTarget(0); d.fx = null; d.fy = null }))
+
+    nodeSel.append("rect").attr("x", -54).attr("y", -18)
+      .attr("width", 108).attr("height", 36).attr("rx", 6)
+      .attr("fill", (d: any) => NODE_COLORS[d.type].fill)
+      .attr("stroke", (d: any) => NODE_COLORS[d.type].stroke).attr("stroke-width", 1.5)
+
+    nodeSel.append("text").attr("text-anchor", "middle").attr("dy", "0.35em")
+      .attr("font-size", 11).attr("fill", "#374151")
+      .text((d: any) => d.label.length > 16 ? d.label.slice(0, 15) + "…" : d.label)
+
+    sim.on("tick", () => {
+      linkSel.attr("x1", (d: any) => d.source.x).attr("y1", (d: any) => d.source.y)
+        .attr("x2", (d: any) => d.target.x).attr("y2", (d: any) => d.target.y)
+      nodeSel.attr("transform", (d: any) => `translate(${d.x},${d.y})`)
+    })
+    return () => { sim.stop() }
+  }, [nodes, links])
+
+  return <svg ref={svgRef} className="w-full" style={{ minHeight: 500 }} />
+}
+```
+
+**Rules:** Always copy nodes/links before D3. Use `clientWidth` for responsive width. Truncate labels, show full on hover. `alphaTarget(0)` on drag end lets sim cool naturally.
+
+---
+
+## Layout Patterns
+
+### Dashboard Grid (Tailwind)
+
+```tsx
+<div className="min-h-screen bg-background p-6">
+  <div className="mb-8 flex items-center justify-between">
+    <div>
+      <h1 className="text-2xl font-bold tracking-tight">Analytics</h1>
+      <p className="text-muted-foreground">Your performance overview</p>
+    </div>
+    <DateRangePicker />
+  </div>
+  <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4 mb-8">
+    {kpis.map(kpi => <KPICard key={kpi.id} {...kpi} />)}
+  </div>
+  <div className="grid gap-4 md:grid-cols-7 mb-8">
+    <Card className="col-span-4">{/* Primary chart */}</Card>
+    <Card className="col-span-3">{/* Secondary chart */}</Card>
+  </div>
+  <Card>{/* DataTable */}</Card>
+</div>
+```
+
+### shadcn-style Card
+
+```tsx
+<div className="rounded-xl border bg-card p-6 shadow-sm">
+  <div className="flex items-center justify-between">
+    <p className="text-sm font-medium text-muted-foreground">{title}</p>
+    <Icon className="h-4 w-4 text-muted-foreground" />
+  </div>
+  <div className="mt-2">
+    <p className="text-2xl font-bold">{value}</p>
+    <p className={cn("text-xs mt-1", delta > 0 ? "text-green-600" : "text-red-600")}>
+      {delta > 0 ? "+" : ""}{delta}% from last period
+    </p>
+  </div>
+</div>
+```
+
+---
+
+## Color Systems
+
+**Semantic (default):**
+```css
+--chart-1: 221.2 83.2% 53.3%;  /* Blue */
+--chart-2: 142.1 76.2% 36.3%;  /* Green */
+--chart-3: 24.6 95% 53.1%;     /* Orange */
+--chart-4: 346.8 77.2% 49.8%;  /* Red */
+--chart-5: 262.1 83.3% 57.8%;  /* Purple */
+```
+
+**Sequential** (heatmaps/gradients): Single hue light→dark. Tailwind `blue-100`→`blue-900` or Nivo schemes: `blues`, `greens`, `oranges`.
+
+**Diverging** (+/- values): Red ↔ White ↔ Green, or Red ↔ Grey ↔ Blue. Center on zero.
+
+**Categorical** (distinct groups): Max 7. Tailwind `500` shades: `blue`, `emerald`, `amber`, `rose`, `violet`, `cyan`, `orange`.
+
+---
+
+## Data Transformations
+
+### Pivot for Recharts
+
+Recharts needs flat arrays with all series as keys per data point:
+
+```ts
+// { date, category, value } rows → { date, cat_A: val, cat_B: val }
+const pivoted = _.chain(rawData).groupBy("date")
+  .map((items, date) => ({ date, ..._.fromPairs(items.map(i => [i.category, i.value])) }))
+  .value()
+```
+
+### KPI Aggregation
+
+```ts
+const kpis = {
+  total: _.sumBy(data, "revenue"), average: _.meanBy(data, "revenue"),
+  max: _.maxBy(data, "revenue"), count: data.length,
+  growth: ((current - previous) / previous * 100).toFixed(1),
+}
+```
+
+### Flat → Hierarchical (Treemaps)
+
+```ts
+const tree = { name: "root", children: _.chain(data).groupBy("category")
+  .map((items, name) => ({ name, children: items.map(i => ({ name: i.label, value: i.amount })) })).value() }
+```
+
+### Time Bucketing
+
+```ts
+import { format, startOfWeek } from "date-fns"
+const weekly = _.chain(data).groupBy(d => format(startOfWeek(new Date(d.date)), "yyyy-MM-dd"))
+  .map((items, week) => ({ week, total: _.sumBy(items, "value"), count: items.length })).value()
+```
+
+---
+
+## Waterfall Chart
+
+Recharts has no native waterfall. Use stacked Bar with invisible spacer:
+
+```tsx
+function toWaterfallSeries(items: { name: string; value: number }[]) {
+  let running = 0
+  return items.map(item => {
+    const start = item.value >= 0 ? running : running + item.value
+    running += item.value
+    return { name: item.name, value: Math.abs(item.value), start, _raw: item.value }
+  })
+}
+
+// In ComposedChart:
+<Bar dataKey="start" stackId="wf" fill="transparent" isAnimationActive={false} />
+<Bar dataKey="value" stackId="wf" radius={[4,4,0,0]}>
+  {data.map((e, i) => <Cell key={i} fill={e._raw >= 0 ? "#22c55e" : "#ef4444"} />)}
+</Bar>
+```
+
+**Critical:** Spacer bar must have `isAnimationActive={false}` (animating it reveals the trick). Hide spacer from tooltip by returning `null` in formatter. For "total" bar: `start: 0`, `value: runningTotal`, distinct color (slate).
+
+---
+
+## Radar / Spider Chart
+
+```tsx
+<RadarChart cx="50%" cy="50%" outerRadius="75%" data={data}>
+  <PolarGrid stroke="#e2e8f0" />
+  <PolarAngleAxis dataKey="dimension" tick={{ fontSize: 12, fill: "#64748b" }} />
+  <PolarRadiusAxis angle={90} domain={[0, 100]} tickCount={5} />
+  <Radar name="Current" dataKey="score" stroke="#6366f1" fill="#6366f1" fillOpacity={0.25} strokeWidth={2} />
+  <Radar name="Benchmark" dataKey="benchmark" stroke="#e2e8f0" fill="none" strokeDasharray="5 3" strokeWidth={1.5} />
+  <Tooltip /><Legend />
+</RadarChart>
+```
+
+**Rules:** `domain={[0, 100]}` for consistent comparison. Dashed benchmark gives context. Max 2 series.
+
+---
+
+## Calendar Heatmap
+
+```tsx
+import { ResponsiveCalendar } from "@nivo/calendar"
+
+<div style={{ height: 200 }}>
+  <ResponsiveCalendar data={data} from={from} to={to}
+    emptyColor="#f8fafc" colors={["#dbeafe", "#93c5fd", "#3b82f6", "#1d4ed8"]}
+    margin={{ top: 24, right: 20, bottom: 8, left: 20 }}
+    yearSpacing={40} dayBorderWidth={2} dayBorderColor="#ffffff" />
+</div>
+```
+
+**Rules:** Height on wrapper div, not component. Single-hue sequential palette. `emptyColor` near-white for sparse data.
+
+---
+
+## Annotation Patterns
+
+Annotations turn charts into stories. **Limit 3 per chart.**
+
+**Color by type:** amber `#f59e0b` = target/goal, red `#ef4444` = incident/risk, indigo `#6366f1` = event/release, green `#22c55e` = achievement.
+
+### Goal/Threshold Line
+
+```tsx
+<ReferenceLine y={targetValue} stroke="#f59e0b" strokeDasharray="6 3" strokeWidth={1.5}
+  label={{ value: `Target: ${targetValue.toLocaleString()}`, position: "insideTopRight", fontSize: 11, fill: "#f59e0b" }} />
+```
+
+### Time Range Highlight
+
+```tsx
+<ReferenceArea x1={start} x2={end} fill="#fee2e2" fillOpacity={0.5}
+  label={{ value: "Incident", position: "insideTopLeft", fontSize: 10, fill: "#ef4444" }} />
+```
+
+### Floating Callout Label
+
+```tsx
+const CalloutLabel = ({ viewBox, label, color = "#1e293b" }: { viewBox?: { x: number; y: number }; label: string; color?: string }) => {
+  if (!viewBox) return null
+  const { x, y } = viewBox, w = label.length * 7 + 16
+  return (<g>
+    <rect x={x - w/2} y={y - 34} width={w} height={20} rx={4} fill={color} />
+    <text x={x} y={y - 20} textAnchor="middle" fontSize={11} fill="white" fontWeight={500}>{label}</text>
+    <line x1={x} y1={y - 14} x2={x} y2={y} stroke={color} strokeWidth={1} />
+  </g>)
+}
+// Usage: <ReferenceLine x={date} stroke="#6366f1" strokeDasharray="4 4" label={<CalloutLabel label="v2.0 shipped" color="#6366f1" />} />
+```
+
+### Anomaly Dot Highlight
+
+```tsx
+<Line dataKey="value" strokeWidth={2} dot={(props) => {
+  const { cx, cy, payload, key } = props
+  if (!payload?.isAnomaly) return <circle key={key} cx={cx} cy={cy} r={3} fill="#6366f1" />
+  return (<g key={key}>
+    <circle cx={cx} cy={cy} r={10} fill="#ef4444" opacity={0.15} />
+    <circle cx={cx} cy={cy} r={4} fill="#ef4444" />
+    <text x={cx} y={cy - 14} textAnchor="middle" fontSize={11} fill="#ef4444">▲</text>
+  </g>)
+}} />
+```
+
+**Rules:** Never overlap data. Use `position: "insideTopRight"/"insideTopLeft"` on labels. Pair annotations with tooltips — annotation names the event, tooltip shows the value.

package/skills/dbt-analyze/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dbt-analyze
+description: Analyze downstream impact of dbt model changes using column-level lineage and the dependency graph. Use when evaluating the blast radius of a change before shipping. Powered by altimate-dbt.
+---
+
+# dbt Impact Analysis
+
+## Requirements
+**Agent:** any (read-only analysis)
+**Tools used:** bash (runs `altimate-dbt` commands), read, glob, dbt_manifest, lineage_check, dbt_lineage, sql_analyze, altimate_core_extract_metadata
+
+## When to Use This Skill
+
+**Use when the user wants to:**
+- Understand what breaks if they change a model
+- Evaluate downstream impact before shipping
+- Find all consumers of a model or column
+- Assess risk of a refactoring
+
+**Do NOT use for:**
+- Creating or fixing models → use `dbt-develop` or `dbt-troubleshoot`
+- Adding tests → use `dbt-test`
+
+## Workflow
+
+### 1. Identify the Changed Model
+
+Accept from the user, or auto-detect:
+```bash
+# From git diff
+git diff --name-only | grep '\.sql$'
+
+# Or user provides a model name
+altimate-dbt compile --model <name>    # verify it exists
+```
+
+### 2. Map the Dependency Graph
+
+```bash
+altimate-dbt children --model <name>    # direct downstream
+altimate-dbt parents --model <name>     # what feeds it
+```
+
+For the full downstream tree, recursively call `children` on each downstream model.
+
+### 3. Run Column-Level Lineage
+
+**With manifest (preferred):** Use `dbt_lineage` to compute column-level lineage for a dbt model. This reads the manifest.json, extracts compiled SQL and upstream schemas, and traces column flow via the Rust engine. More accurate than raw SQL lineage because it resolves `ref()` and `source()` to actual schemas.
+
+```
+dbt_lineage(model: <model_name>)
+```
+
+**Without manifest (fallback):** Use `lineage_check` on the raw SQL to understand:
+- Which source columns flow to which output columns
+- Which columns were added, removed, or renamed
+
+**Extract structural metadata:** Use `altimate_core_extract_metadata` on the SQL to get tables referenced, columns used, CTEs, subqueries — useful for mapping the full dependency surface.
+
+
+### 4. Cross-Reference with Downstream
+
+For each downstream model:
+1. Read its SQL
+2. Check if it references any changed/removed columns
+3. Classify impact:
+
+| Classification | Meaning | Action |
+|---------------|---------|--------|
+| **BREAKING** | Removed/renamed column used downstream | Must fix before shipping |
+| **SAFE** | Added column, no downstream reference | Ship freely |
+| **UNKNOWN** | Can't determine (dynamic SQL, macros) | Manual review needed |
+
+### 5. Generate Impact Report
+
+```
+Impact Analysis: stg_orders
+════════════════════════════
+
+Changed Model: stg_orders (materialized: view)
+  Columns: 5 → 6 (+1 added)
+  Removed: total_amount (renamed to order_total)
+
+Downstream Impact (3 models):
+
+  Depth 1:
+    [BREAKING] int_order_metrics
+      Uses: total_amount → COLUMN RENAMED
+      Fix: Update column reference to order_total
+
+    [SAFE] int_order_summary
+      No references to changed columns
+
+  Depth 2:
+    [BREAKING] mart_revenue
+      Uses: total_amount via int_order_metrics → CASCADING
+      Fix: Verify after fixing int_order_metrics
+
+Tests at Risk: 4
+  - not_null_stg_orders_order_total
+  - unique_int_order_metrics_order_id
+
+Summary: 2 BREAKING, 1 SAFE
+  Recommended: Fix int_order_metrics first, then:
+  altimate-dbt build --model stg_orders --downstream
+```
+
+## Without Manifest (SQL-Only Mode)
+
+If no manifest is available:
+1. Run `lineage_check` on the changed SQL
+2. Show column-level data flow
+3. Note: downstream impact requires a manifest
+4. Suggest: `altimate-dbt build-project` to generate one
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Only checking direct children | Always trace the FULL downstream tree recursively |
+| Ignoring test impacts | Check which tests reference changed columns |
+| Shipping without building downstream | Always `altimate-dbt build --model <name> --downstream` |
+| Not considering renamed columns | A rename is a break + add — downstream still references the old name |
+
+## Reference Guides
+
+| Guide | Use When |
+|-------|----------|
+| [references/altimate-dbt-commands.md](references/altimate-dbt-commands.md) | Need the full CLI reference |
+| [references/lineage-interpretation.md](references/lineage-interpretation.md) | Understanding lineage output |

package/skills/dbt-analyze/references/altimate-dbt-commands.md

@@ -0,0 +1,66 @@
+# altimate-dbt Command Reference
+
+All dbt operations use the `altimate-dbt` CLI. Output is JSON to stdout; logs go to stderr.
+
+```bash
+altimate-dbt <command> [args...]
+altimate-dbt <command> [args...] --format text    # Human-readable output
+```
+
+## First-Time Setup
+
+```bash
+altimate-dbt init                          # Auto-detect project root
+altimate-dbt init --project-root /path     # Explicit root
+altimate-dbt init --python-path /path      # Override Python
+altimate-dbt doctor                        # Verify setup
+altimate-dbt info                          # Project name, adapter, root
+```
+
+## Build & Run
+
+```bash
+altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt run --model <name> [--downstream]      # materialize only
+altimate-dbt test --model <name>                     # run tests only
+altimate-dbt build-project                           # full project build
+```
+
+## Compile
+
+```bash
+altimate-dbt compile --model <name>
+altimate-dbt compile-query --query "SELECT * FROM {{ ref('stg_orders') }}" [--model <context>]
+```
+
+## Execute SQL
+
+```bash
+altimate-dbt execute --query "SELECT count(*) FROM {{ ref('orders') }}" --limit 100
+```
+
+## Schema & DAG
+
+```bash
+altimate-dbt columns --model <name>                         # column names and types
+altimate-dbt columns-source --source <src> --table <tbl>    # source table columns
+altimate-dbt column-values --model <name> --column <col>    # sample values
+altimate-dbt children --model <name>                        # downstream models
+altimate-dbt parents --model <name>                         # upstream models
+```
+
+## Packages
+
+```bash
+altimate-dbt deps                                           # install packages.yml
+altimate-dbt add-packages --packages dbt-utils,dbt-expectations
+```
+
+## Error Handling
+
+All errors return JSON with `error` and `fix` fields:
+```json
+{ "error": "dbt-core is not installed", "fix": "Install it: python3 -m pip install dbt-core" }
+```
+
+Run `altimate-dbt doctor` as the first diagnostic step for any failure.

package/skills/dbt-analyze/references/lineage-interpretation.md

@@ -0,0 +1,58 @@
+# Lineage Interpretation Guide
+
+## Understanding Column-Level Lineage
+
+Column-level lineage traces how data flows from source columns through transformations to output columns.
+
+### Direct Lineage
+```
+source.customers.name → stg_customers.customer_name → dim_customers.full_name
+```
+Column was renamed at each step. A change to the source column affects all downstream.
+
+### Aggregation Lineage
+```
+source.orders.amount → (SUM) → fct_daily_revenue.total_revenue
+```
+Multiple source rows feed into one output value. The column type changes from row-level to aggregate.
+
+### Conditional Lineage
+```
+source.orders.status → (CASE WHEN) → fct_orders.is_completed
+```
+The source column feeds a derived boolean. The relationship is logical, not direct.
+
+## Impact Classification
+
+### BREAKING Changes
+- **Column removed**: Downstream models referencing it will fail
+- **Column renamed**: Same as removed — downstream still uses the old name
+- **Type changed**: May cause cast errors or silent data loss downstream
+- **Logic changed**: Downstream aggregations/filters may produce wrong results
+
+### SAFE Changes
+- **Column added**: No downstream model can reference what didn't exist
+- **Description changed**: No runtime impact
+- **Test added/modified**: No impact on model data
+
+### REQUIRES REVIEW
+- **Filter changed**: May change which rows appear → downstream counts change
+- **JOIN type changed**: LEFT→INNER drops rows, INNER→LEFT adds NULLs
+- **Materialization changed**: view→table has no logical impact but affects freshness
+
+## Reading the DAG
+
+```bash
+altimate-dbt parents --model <name>     # what this model depends on
+altimate-dbt children --model <name>    # what depends on this model
+```
+
+A model with many children has high blast radius. A model with many parents has high complexity.
+
+## Depth Matters
+
+- **Depth 1**: Direct consumers — highest risk, most likely to break
+- **Depth 2+**: Cascading impact — will break IF depth 1 breaks
+- **Depth 3+**: Usually only affected by breaking column removals/renames
+
+Focus investigation on depth 1 first.