htmlineage 0.0.0 → 0.1.0-beta.0

package/skills/htmlineage/references/example/.lineage/august-retention.json

@@ -0,0 +1,167 @@
+{
+  "lineage": "1.0",
+  "nodes": {
+    "q1": {
+      "step": "source",
+      "kind": "sql",
+      "desc": "Monthly 30-day retention inputs for each channel, region and signup cohort, January to August 2026",
+      "mart": "marts.retention_by_channel",
+      "period": {
+        "from": "2026-01-01",
+        "to": "2026-08-31"
+      },
+      "sql": "-- 30-day retention inputs by channel, region and cohort month, Jan to Aug 2026\nselect\n    channel,\n    region,\n    cohort_month,\n    cohort_customers,\n    retained_30d\nfrom marts.retention_by_channel\nwhere cohort_month between '2026-01-01' and '2026-08-31'",
+      "columns": [
+        "channel",
+        "region",
+        "cohort_month",
+        "cohort_customers",
+        "retained_30d"
+      ],
+      "rows": null
+    },
+    "q2": {
+      "step": "source",
+      "kind": "sql",
+      "desc": "New customers for each channel who signed up in August 2026",
+      "mart": "marts.acquisition_by_channel",
+      "period": {
+        "from": "2026-08-01",
+        "to": "2026-08-31"
+      },
+      "sql": "-- New customers by channel, August 2026\nselect\n    channel,\n    signup_month,\n    new_customers\nfrom marts.acquisition_by_channel\nwhere signup_month between '2026-08-01' and '2026-08-31'",
+      "columns": ["channel", "signup_month", "new_customers"],
+      "rows": {
+        "channel": ["paid_social", "paid_search", "organic", "referral"],
+        "signup_month": [
+          "2026-08-01",
+          "2026-08-01",
+          "2026-08-01",
+          "2026-08-01"
+        ],
+        "new_customers": [4120, 3310, 3870, 1900]
+      }
+    },
+    "x1": {
+      "step": "source",
+      "kind": "external",
+      "type": "csv",
+      "ref": "channel-retention-targets.csv",
+      "given": "Retention targets by channel for August 2026, shared as a CSV by the growth lead",
+      "columns": ["channel", "target_retention"],
+      "rows": {
+        "channel": ["paid_social", "paid_search", "organic", "referral"],
+        "target_retention": [0.45, 0.4, 0.43, 0.44]
+      }
+    },
+    "v1": {
+      "step": "view",
+      "desc": "Retention for each channel and month, with each channel ranked against the others in its month",
+      "from": ["q1"],
+      "sql": "-- Monthly 30-day retention by channel, with each channel's rank in its month\nselect\n    channel,\n    cohort_month,\n    sum(retained_30d) / sum(cohort_customers) as retention,\n    rank() over (\n        partition by cohort_month\n        order by sum(retained_30d) / sum(cohort_customers) desc\n    ) as retention_rank\nfrom q1\ngroup by channel, cohort_month",
+      "columns": ["channel", "cohort_month", "retention", "retention_rank"],
+      "encoding": {
+        "x": "cohort_month",
+        "y": "retention",
+        "series": "channel",
+        "visual": "line"
+      },
+      "rows": null
+    },
+    "v2": {
+      "step": "view",
+      "desc": "August new customers and retention for each channel, side by side",
+      "from": ["q1", "q2"],
+      "sql": "-- August new customers and 30-day retention by channel\nselect\n    q2.channel,\n    q2.new_customers,\n    sum(q1.retained_30d) / sum(q1.cohort_customers) as retention\nfrom q2\njoin q1\n    on q1.channel = q2.channel\n    and q1.cohort_month = q2.signup_month\ngroup by q2.channel, q2.new_customers\norder by retention desc",
+      "columns": ["channel", "new_customers", "retention"],
+      "encoding": {
+        "visual": "table"
+      },
+      "rows": null
+    },
+    "f1": {
+      "step": "figure",
+      "desc": "Paid social's retention for the August 2026 signup cohort",
+      "from": ["v1"],
+      "sql": "select retention\nfrom v1\nwhere channel = 'paid_social'\n  and cohort_month = '2026-08-01'",
+      "value": 0.466,
+      "display": "46.6%",
+      "label": "Paid social retention, August"
+    },
+    "f2": {
+      "step": "figure",
+      "desc": "Paid social's retention for the July 2026 signup cohort",
+      "from": ["v1"],
+      "sql": "select retention\nfrom v1\nwhere channel = 'paid_social'\n  and cohort_month = '2026-07-01'",
+      "value": 0.417,
+      "display": "41.7%",
+      "label": "Paid social retention, July"
+    },
+    "f3": {
+      "step": "figure",
+      "desc": "August retention minus July retention, as a share of July retention",
+      "from": ["f1", "f2"],
+      "expr": "(f1 - f2) / f2",
+      "value": 0.1175,
+      "display": "11.8%",
+      "label": "Change in paid social retention, August vs July"
+    },
+    "f4": {
+      "step": "figure",
+      "desc": "Paid social's retention rank among the channels in August 2026",
+      "from": ["v1"],
+      "sql": "select retention_rank\nfrom v1\nwhere channel = 'paid_social'\n  and cohort_month = '2026-08-01'",
+      "value": 1,
+      "display": "#1",
+      "label": "Paid social's retention rank among channels, August"
+    },
+    "f5": {
+      "step": "figure",
+      "desc": "Paid social's August new customers as a share of all channels' August new customers",
+      "from": ["v2"],
+      "sql": "select customer_share\nfrom (\n    select\n        channel,\n        new_customers / sum(new_customers) over () as customer_share\n    from v2\n) as shares\nwhere channel = 'paid_social'",
+      "value": 0.3121,
+      "display": "31.2%",
+      "label": "Paid social share of August new customers"
+    },
+    "f6": {
+      "step": "figure",
+      "desc": "The channel with the highest retention in August 2026",
+      "from": ["v2"],
+      "sql": "select channel\nfrom v2\norder by retention desc\nlimit 1",
+      "value": "paid_social",
+      "display": "Paid social",
+      "label": "Channel with the highest August retention"
+    },
+    "f7": {
+      "step": "figure",
+      "desc": "Paid social's August 2026 retention target",
+      "from": ["x1"],
+      "sql": "select target_retention\nfrom x1\nwhere channel = 'paid_social'",
+      "value": 0.45,
+      "display": "45%",
+      "label": "Paid social retention target, August"
+    },
+    "i1": {
+      "step": "insight",
+      "from": ["f6"],
+      "text": "Paid social led August retention."
+    },
+    "i2": {
+      "step": "insight",
+      "from": ["f1", "f2", "f3", "f4"],
+      "text": "Paid social 30-day retention rose to 46.6% in August from July's 41.7%, a relative gain of 11.8%, and ranked #1 of the four channels."
+    },
+    "i3": {
+      "step": "insight",
+      "from": ["f5", "i2"],
+      "text": "Paid social brought in 31.2% of August's new customers, so its gain lifts retention across the whole base, not just one corner of it."
+    },
+    "i4": {
+      "step": "insight",
+      "from": [],
+      "ungrounded": true,
+      "text": "Paid social's gain is likely to hold into September."
+    }
+  }
+}

package/skills/htmlineage/references/example/README.md

@@ -0,0 +1,51 @@
+# Worked example
+
+A short report as you should leave it before you run `check`: the graph sits
+in `.lineage/august-retention.json`, the page in `august-retention.html` has
+no embedded block, and the graph header holds only `lineage` and `nodes`.
+Read the JSON beside the page. `check` embeds the graph for you.
+
+## Prompt
+
+> Build a one-page August retention report for the growth review: paid social's
+> 30-day retention against July, how it ranks among the channels, and its share
+> of new customers. Compare retention with the targets the growth lead sent.
+
+## Build order
+
+The queries and steps in the order they were made. Each id appears once.
+
+1. `q1` source: one wide pinned query on `marts.retention_by_channel`, January to August 2026.
+2. `q2` source: one wide pinned query on `marts.acquisition_by_channel`, August 2026.
+3. `x1` external source: the retention targets the growth lead shared as a CSV. You were handed it, so it has `given` and no `sql`.
+4. `v1` view: retention by channel and month, with a `rank() over` column. It is the line chart.
+5. `v2` view: August new customers and retention by channel. It is the table.
+6. `f1` figure: paid social's August retention, picked from `v1`.
+7. `f2` figure: its July retention, picked from `v1`.
+8. `f3` figure: the change on July, an `expr` over `f1` and `f2`, with no `sql`.
+9. `f4` figure: its August rank, picked from `v1`.
+10. `f5` figure: its share of August new customers, a subquery over `v2`.
+11. `f6` figure: the top channel's name. A figure can hold text.
+12. `f7` figure: paid social's August target, picked from `x1`.
+13. `i1` insight: the headline, resting on `f6`.
+14. `i2` insight: the retention paragraph, resting on `f1`, `f2`, `f3` and `f4`.
+15. `i3` insight: the share paragraph, resting on `f5` and the insight `i2`.
+16. `i4` insight: a forecast no query backs. It has `from: []` and `ungrounded: true`.
+
+## Check output
+
+```text
+august-retention.html
+
+  sources    3   (1 external)
+  views      2   all shown on the page
+  figures    7   6 fully traced, 1 partially traced
+  insights   4   3 fully traced, 1 ungrounded
+
+  needs attention
+    i4   ungrounded   "Paid social's gain is likely to hold int…"
+    x1   external     channel-retention-targets.csv — a reader will be asked to confirm this with you
+```
+
+`i4` and `x1` are listed on purpose. They show a reader what is not backed by a query.
+Everything else passes with no error and no warning.

package/skills/htmlineage/references/example/august-retention.html

@@ -0,0 +1,111 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>August retention by channel</title>
+  <style>
+    :root { --ink: #1d2128; --muted: #5f6570; --line: #e4e6ea; --accent: #2a6fdb; }
+    body { margin: 0; background: #fff; color: var(--ink); font: 16px/1.55 -apple-system, "Segoe UI", Roboto, sans-serif; }
+    main { max-width: 760px; margin: 0 auto; padding: 40px 20px 64px; }
+    .eyebrow { margin: 0; color: var(--muted); font-size: 13px; letter-spacing: .04em; text-transform: uppercase; }
+    h1 { margin: 6px 0 4px; font-size: 30px; line-height: 1.2; }
+    .subtitle { margin: 0 0 28px; color: var(--muted); }
+    .kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; margin-bottom: 28px; }
+    .kpi { border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; }
+    .kpi-label { color: var(--muted); font-size: 13px; }
+    .kpi-value { font-size: 26px; font-weight: 600; }
+    .kpi-note { color: var(--muted); font-size: 13px; }
+    h2 { margin: 32px 0 8px; font-size: 18px; }
+    figure { margin: 0; }
+    svg { width: 100%; height: auto; }
+    svg .grid { stroke: var(--line); }
+    svg .tick { fill: var(--muted); font-size: 11px; }
+    svg .series { font-size: 12px; }
+    table { width: 100%; border-collapse: collapse; font-variant-numeric: tabular-nums; }
+    th, td { padding: 8px 10px; border-bottom: 1px solid var(--line); text-align: right; }
+    th:first-child, td:first-child { text-align: left; }
+    th { color: var(--muted); font-weight: 500; font-size: 13px; }
+    footer { margin-top: 40px; color: var(--muted); font-size: 13px; }
+  </style>
+</head>
+<body>
+<main>
+  <header>
+    <p class="eyebrow">Growth review · August 2026</p>
+    <h1 data-lineage="i1"><span data-lineage="f6">Paid social</span> led August retention</h1>
+    <p class="subtitle">30-day retention by acquisition channel, cohorts from January to August 2026</p>
+  </header>
+
+  <section class="kpis">
+    <div class="kpi">
+      <div class="kpi-label">Paid social retention, August</div>
+      <div class="kpi-value" data-lineage="f1">46.6%</div>
+      <div class="kpi-note">vs <span data-lineage="f2">41.7%</span> in July</div>
+      <div class="kpi-note">Target <span data-lineage="f7">45%</span></div>
+    </div>
+    <div class="kpi">
+      <div class="kpi-label">Change on July</div>
+      <div class="kpi-value" data-lineage="f3">11.8%</div>
+      <div class="kpi-note">relative change</div>
+    </div>
+    <div class="kpi">
+      <div class="kpi-label">Share of August new customers</div>
+      <div class="kpi-value" data-lineage="f5">31.2%</div>
+      <div class="kpi-note">paid social</div>
+    </div>
+  </section>
+
+  <p data-lineage="i2">Paid social 30-day retention rose to <span data-lineage="f1">46.6%</span> in August from July's <span data-lineage="f2">41.7%</span>, a relative gain of <span data-lineage="f3">11.8%</span>, and ranked <span data-lineage="f4">#1</span> of the four channels.</p>
+
+  <p data-lineage="i3">Paid social brought in <span data-lineage="f5">31.2%</span> of August's new customers, so its gain lifts retention across the whole base, not just one corner of it.</p>
+
+  <p data-lineage="i4">Paid social's gain is likely to hold into September.</p>
+
+  <h2>Retention by channel, month by month</h2>
+  <figure data-lineage="v1">
+    <svg viewBox="0 0 640 260" role="img" aria-label="30-day retention by channel, January to August 2026">
+      <line class="grid" x1="44" x2="544" y1="232.0" y2="232.0"/>
+      <text class="tick" x="36" y="236.0" text-anchor="end">36%</text>
+      <line class="grid" x1="44" x2="544" y1="160.0" y2="160.0"/>
+      <text class="tick" x="36" y="164.0" text-anchor="end">40%</text>
+      <line class="grid" x1="44" x2="544" y1="88.0" y2="88.0"/>
+      <text class="tick" x="36" y="92.0" text-anchor="end">44%</text>
+      <line class="grid" x1="44" x2="544" y1="16.0" y2="16.0"/>
+      <text class="tick" x="36" y="20.0" text-anchor="end">48%</text>
+      <text class="tick" x="44.0" y="252" text-anchor="middle">Jan</text>
+      <text class="tick" x="115.4" y="252" text-anchor="middle">Feb</text>
+      <text class="tick" x="186.9" y="252" text-anchor="middle">Mar</text>
+      <text class="tick" x="258.3" y="252" text-anchor="middle">Apr</text>
+      <text class="tick" x="329.7" y="252" text-anchor="middle">May</text>
+      <text class="tick" x="401.1" y="252" text-anchor="middle">Jun</text>
+      <text class="tick" x="472.6" y="252" text-anchor="middle">Jul</text>
+      <text class="tick" x="544.0" y="252" text-anchor="middle">Aug</text>
+      <polyline fill="none" stroke="#d8dadf" stroke-width="1.5" points="44.0,196.0 115.4,188.8 186.9,179.8 258.3,185.2 329.7,176.2 401.1,172.6 472.6,174.4 544.0,181.6"/>
+      <text class="series" x="552" y="185.6" fill="#9a9ea6">paid search</text>
+      <polyline fill="none" stroke="#b5b9c0" stroke-width="1.5" points="44.0,115.0 115.4,109.6 186.9,106.0 258.3,113.2 329.7,100.6 401.1,107.8 472.6,109.6 544.0,104.2"/>
+      <text class="series" x="552" y="108.2" fill="#b5b9c0">organic</text>
+      <polyline fill="none" stroke="#8a8f98" stroke-width="1.5" points="44.0,73.6 115.4,68.2 186.9,61.0 258.3,71.8 329.7,55.6 401.1,66.4 472.6,61.0 544.0,66.4"/>
+      <text class="series" x="552" y="70.4" fill="#8a8f98">referral</text>
+      <polyline fill="none" stroke="#2a6fdb" stroke-width="2.5" points="44.0,174.4 115.4,163.6 186.9,151.0 258.3,158.2 329.7,142.0 401.1,143.8 472.6,129.4 544.0,41.2"/>
+      <text class="series" x="552" y="45.2" fill="#2a6fdb">paid social</text>
+    </svg>
+  </figure>
+
+  <h2>August by channel</h2>
+  <table data-lineage="v2">
+    <thead>
+      <tr><th>Channel</th><th>New customers</th><th>30-day retention</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Paid social</td><td>4,120</td><td>46.6%</td></tr>
+      <tr><td>Referral</td><td>1,900</td><td>45.2%</td></tr>
+      <tr><td>Organic</td><td>3,870</td><td>43.1%</td></tr>
+      <tr><td>Paid search</td><td>3,310</td><td>38.8%</td></tr>
+    </tbody>
+  </table>
+
+  <footer>Source: marts.retention_by_channel and marts.acquisition_by_channel. Retention is the 30-day active rate of each signup cohort: customers still active a month after signup, over customers in the cohort.</footer>
+</main>
+</body>
+</html>

package/skills/htmlineage/references/format.md

@@ -0,0 +1,218 @@
+# The lineage graph: field reference
+
+## Files
+
+A report is one HTML file. Its lineage graph is one JSON object kept in
+`.lineage/<report-stem>.json`, beside the report. For `report.html` that is
+`.lineage/report.json`. You write the graph there. `htmlineage check` embeds
+it in the report as a `<script type="application/lineage+json">` block, so you
+never write that block by hand.
+
+The graph is a header and a `nodes` map keyed by id:
+
+```json
+{
+  "lineage": "1.0",
+  "nodes": {
+    "q1": {},
+    "v1": {},
+    "f1": {},
+    "i1": {}
+  }
+}
+```
+
+## Kinds of node
+
+Every value on the page reaches it by one path: source, then view, then
+figure, then insight. A node's `step` says which it is.
+
+```json
+{
+  "step": "source",
+  "kind": "sql",
+  "desc": "Retention by channel and cohort month, January to August 2026",
+  "mart": "marts.retention_by_channel",
+  "period": { "from": "2026-01-01", "to": "2026-08-31" },
+  "sql": "select\n    channel,\n    cohort_month,\n    retention_30d\nfrom marts.retention_by_channel\nwhere cohort_month between '2026-01-01' and '2026-08-31'",
+  "columns": ["channel", "cohort_month", "retention_30d"]
+}
+```
+
+```json
+{
+  "step": "source",
+  "kind": "external",
+  "type": "csv",
+  "ref": "q3-targets.csv",
+  "given": "A CSV with columns channel, target_retention, shared by the builder"
+}
+```
+
+```json
+{
+  "step": "view",
+  "from": ["q1"],
+  "desc": "Average 30-day retention for each channel and cohort month",
+  "sql": "select\n    channel,\n    cohort_month,\n    avg(retention_30d) as retention\nfrom q1\ngroup by channel, cohort_month",
+  "columns": ["channel", "cohort_month", "retention"],
+  "encoding": { "x": "cohort_month", "y": "retention", "series": "channel" }
+}
+```
+
+```json
+{
+  "step": "figure",
+  "from": ["v1"],
+  "desc": "Paid social retention for August 2026",
+  "sql": "select retention\nfrom v1\nwhere channel = 'paid_social'\n  and cohort_month = '2026-08-01'",
+  "value": 0.466,
+  "display": "46.6%",
+  "label": "Paid social retention, August"
+}
+```
+
+```json
+{
+  "step": "figure",
+  "from": ["f1", "f2"],
+  "desc": "Change in paid social retention from July to August, relative to July",
+  "expr": "(f1 - f2) / f2",
+  "value": 0.1175,
+  "display": "11.8%",
+  "label": "Change in paid social retention, August vs July"
+}
+```
+
+```json
+{
+  "step": "insight",
+  "from": ["f3"],
+  "text": "Paid social retention rose by a relative 11.8%."
+}
+```
+
+A claim that rests on nothing you queried is still written down, marked
+`"ungrounded": true` with `"from": []`.
+
+## What may rest on what
+
+- A view's `from` lists sources and views.
+- A figure with `sql` lists sources and views in `from`. A figure with `expr`
+  lists figures.
+- An insight's `from` lists views, figures and insights. Never a source:
+  sources do not appear on the page.
+- A figure never gets its own query. It picks one cell from a view or source
+  that exists, or it derives from other figures.
+
+## Ids
+
+- Lowercase letters, digits and `_`, starting with a letter.
+- Start with the step's letter: `q` for a sql source, `x` for an external
+  source, `v` for a view, `f` for a figure, `i` for an insight. For example
+  `q1`, `x1`, `v1`, `f1`, `i1`.
+- Each id is used once.
+
+## Binding to the page
+
+Put `data-lineage="<id>"` on the element that shows the node:
+
+```html
+<span data-lineage="f3">11.8%</span>
+<p data-lineage="i1">
+  Paid social retention rose by a relative
+  <span data-lineage="f3">11.8%</span>.
+</p>
+<div data-lineage="v1"><svg></svg></div>
+<table data-lineage="v2"></table>
+```
+
+- Views, figures and insights bind. Sources never do.
+- Every view, figure and insight binds at least once. A figure shown in
+  several places binds in each.
+- A number inside a sentence sits in its own `data-lineage` span.
+- A chart binds on the container around the SVG, not the SVG.
+- The attribute adds no style and no behaviour.
+
+## Fields
+
+Each table below lists every field a node of that kind may carry. Required
+means an error if it is missing. Expected means a warning if it is missing.
+
+### sql source
+
+| Field       | Required | Type   | Use                                                                 |
+| ----------- | -------- | ------ | ------------------------------------------------------------------- |
+| `step`      | required | string | `"source"`                                                          |
+| `kind`      | required | string | `"sql"`                                                             |
+| `desc`      | expected | string | One line, 120 characters at most: what the query pulls, in words    |
+| `how`       | optional | string | Leave out                                                           |
+| `mart`      | expected | string | The mart the query reads                                            |
+| `period`    | expected | object | The pinned range, `{ "from": "2026-01-01", "to": "2026-08-31" }`    |
+| `sql`       | expected | string | The query, with the period as literal dates                         |
+| `columns`   | expected | list   | Output column names                                                 |
+| `rows`      | optional | object | Up to 10 rows, columnar: `{ "column": [values] }`; or `null`        |
+| `transform` | optional | string | A judgement the SQL does not show, such as "excluded the test week" |
+
+### external source
+
+| Field       | Required | Type   | Use                                           |
+| ----------- | -------- | ------ | --------------------------------------------- |
+| `step`      | required | string | `"source"`                                    |
+| `kind`      | required | string | `"external"`                                  |
+| `type`      | expected | string | What kind of thing it is, such as `csv`       |
+| `ref`       | expected | string | How a reader can find it, such as a file name |
+| `given`     | expected | string | What you were handed, in words                |
+| `columns`   | optional | list   | Column names, if it has them                  |
+| `rows`      | optional | object | Up to 10 rows, columnar; or `null`            |
+| `transform` | optional | string | A judgement the data does not show            |
+
+### view
+
+| Field        | Required | Type   | Use                                                                              |
+| ------------ | -------- | ------ | -------------------------------------------------------------------------------- |
+| `step`       | required | string | `"view"`                                                                         |
+| `from`       | required | list   | Ids of the sources and views it reads                                            |
+| `desc`       | expected | string | One line, 120 characters at most: what it computes and how, in words             |
+| `sql`        | required | string | A SELECT over the parents, which it names by id as table names                   |
+| `columns`    | expected | list   | Output column names                                                              |
+| `encoding`   | optional | object | For charts: `x`, `y`, `series`, `visual`, each a string                          |
+| `rows`       | optional | object | Up to 10 rows, columnar; or `null`. A view shown as a table needs none           |
+| `transform`  | optional | string | A judgement the SQL does not show                                                |
+| `ungrounded` | optional | bool   | `true` when it has no source: `from` may then be empty and `sql` may be left out |
+
+### figure
+
+| Field        | Required             | Type          | Use                                                                                           |
+| ------------ | -------------------- | ------------- | --------------------------------------------------------------------------------------------- |
+| `step`       | required             | string        | `"figure"`                                                                                    |
+| `from`       | required             | list          | Ids it reads: sources and views with `sql`, figures with `expr`                               |
+| `desc`       | expected             | string        | One line, 120 characters at most: how it was computed, in words                               |
+| `sql`        | one of `sql`, `expr` | string        | A single SELECT returning one cell, ideally a plain pick of one column from one row           |
+| `expr`       | one of `sql`, `expr` | string        | A SQL scalar expression over figure ids, such as `(f1 - f2) / f2`. No comments                |
+| `value`      | expected             | number/string | The number or name the page shows                                                             |
+| `display`    | expected             | string        | The text exactly as shown on the page, such as `"46.6%"`                                      |
+| `label`      | expected             | string        | What the number is, in words                                                                  |
+| `transform`  | optional             | string        | A judgement the SQL does not show                                                             |
+| `ungrounded` | optional             | bool          | `true` when it has no source: `from` may then be empty and neither `sql` nor `expr` is needed |
+
+### insight
+
+| Field        | Required | Type   | Use                                                                   |
+| ------------ | -------- | ------ | --------------------------------------------------------------------- |
+| `step`       | required | string | `"insight"`                                                           |
+| `from`       | required | list   | Ids of the views, figures and insights the claim rests on             |
+| `text`       | required | string | The claim, as it reads on the page                                    |
+| `transform`  | optional | string | A judgement behind the claim that its sources do not show             |
+| `ungrounded` | optional | bool   | `true` when the claim rests on nothing here: `from` may then be empty |
+
+### header
+
+| Field          | Required | Type   | Use                                                    |
+| -------------- | -------- | ------ | ------------------------------------------------------ |
+| `lineage`      | required | string | The format version, `"1.0"`                            |
+| `nodes`        | required | object | Every node, keyed by id                                |
+| `report_id`    | optional | string | A UUID, minted at the first build and kept on rebuilds |
+| `built_at`     | optional | string | When the report was built, an ISO timestamp            |
+| `builder_tool` | optional | string | The tool that built it, such as `report-builder`       |
+| `signature`    | optional | string | Leave out                                              |

package/skills/htmlineage/references/review.md

@@ -0,0 +1,79 @@
+# Reviewing a report
+
+Use this when you are asked to review a report someone else built, or to check
+one before it is shared. Your job is to show the reviewer what each number and
+claim rests on and where that is weak. You do not decide whether the report is
+right, and you do not change it.
+
+## 1. Read the check summary
+
+```
+npx htmlineage check <report>.html --no-embed
+```
+
+`--no-embed` leaves the file untouched. Read the summary. It lists errors
+last, but take them first:
+
+- **Errors.** The lineage is broken. Say so first: nothing below can be traced
+  with confidence until the builder fixes it, and `htmlineage sql` refuses
+  a report with errors.
+- **Ungrounded.** Claims and numbers that rest on nothing queried: a forecast,
+  an opinion, outside knowledge. List each one with its text. They may be
+  fine, but the reader should know they are not backed by data.
+- **External.** Data the builder was handed: a CSV, a number someone said.
+  Name each one and who it came from (its `given`). A reviewer may want to
+  confirm it with that person.
+- **Warnings.** Each is a gap a reader could trip on. The ones that matter
+  most: a number in prose with no lineage (C2), a page that shows a different
+  value from the graph (C3), and a source without literal dates (C7).
+
+## 2. Trace the numbers that carry the report
+
+Pick the headline numbers and the ones the main claims rest on. For each, take
+its id from the element's `data-lineage` attribute and run:
+
+```
+npx htmlineage sql <report>.html --id <id>
+```
+
+Read the script against the claim on the page:
+
+- **Population.** Does the source cover who the claim is about? A claim about
+  all customers over a source filtered to one region is a finding.
+- **Period.** Do the literal dates match the period the page names?
+- **Comparison.** Is a change measured against the base the text says (last
+  month, last year, target)?
+- **Definition.** Does the metric match its name: a 30-day rate computed over
+  30 days, a share over the right total?
+- **Descriptions.** Does each step's `desc` say what its SQL does? A `desc`
+  that promises more than the SQL is a finding.
+
+`npx htmlineage sql <report>.html` with no `--id` composes the whole report into
+one script, if the reviewer wants everything at once.
+
+## 3. Rerun, if you can and are asked to
+
+If you have read access to the warehouse and the reviewer wants the numbers
+reproduced, run the script from step 2 and compare its result with the figure's
+`display` on the page. Run it as it is; do not rewrite it first. Report any
+difference with both values. Because every source has literal dates, the script
+should give the same result as when the report was built, unless the
+underlying data has changed since.
+
+Never run anything that writes to the warehouse.
+
+## 4. Report back
+
+A short list, most serious first:
+
+1. Errors, if any.
+2. Findings from step 2 and step 3: the id, what the page says, what the SQL
+   does, and why it matters.
+3. Ungrounded claims and external data, so the reader knows what to take on
+   trust.
+4. Anything you checked and found sound, briefly. "f1, f3 and f5 trace cleanly
+   to the August retention query" is useful to a reviewer.
+
+Do not edit the report or its graph. If the builder should change something,
+say what and why. For a person to click through the lineage themselves, point
+them to `npx htmlineage view <report>.html`.