htmlineage 0.1.0-alpha.0 → 0.1.0-beta.0

package/README.md

@@ -1,8 +1,18 @@
-# htmlineage
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.svg">
+  <img src=".github/assets/logo-light.svg" alt="htmlineage" width="420">
+</picture>
 
 **A provenance layer for AI-generated reports.** Every number, chart, and claim traces back to the query that produced it.
 
-AI writes analytics reports faster than data teams can vet them. htmlineage records where each figure came from — `source → view → figure → insight` — so a reviewer can see the lineage behind any claim before it reaches a CXO deck.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/viewer-dark.png">
+  <img src=".github/assets/viewer-light.png" alt="The htmlineage viewer: a quarterly business review on the left, and on the right how its &quot;Gap to year-end target&quot; figure was computed">
+</picture>
+
+<sub>The viewer on a sample report. Halden is a fictional company and its data is made up.</sub>
+
+AI writes analytics reports faster than data teams can vet them. htmlineage records where each figure came from — `source → view → figure → insight` — so a reviewer can see the lineage behind any claim before it reaches a CXO deck. A skill teaches your AI assistant to record that lineage while it builds a report, and a small CLI checks it, composes it into one SQL script, and shows it beside the report.
 
 - **Visibility, not verification.** htmlineage shows the lineage; it doesn't assert the numbers are right.
 - **Zero builder friction.** Reports stay plain `.html`. Lineage rides along in an inert `<script type="application/lineage+json">` block and `data-lineage` attributes — invisible to the reader.
@@ -11,38 +21,70 @@ AI writes analytics reports faster than data teams can vet them. htmlineage reco
 
 ## Status
 
-⚠️ **Pre-release.** This is an early preview, published under the `next` tag. The lineage format may still change before `0.1.0`. The skill that teaches an AI assistant to write lineage as it builds a report is not included yet.
+**Beta.** The lineage format may still change before `0.1.0`.
 
 ## Install
 
-Requires Node 18 or later.
+**The skill** follows the open [Agent Skills](https://agentskills.io) standard, so it works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and other tools that read skills. Install it with [skills.sh](https://skills.sh):
 
 ```bash
-npx htmlineage@next --help
+npx skills add htmlineage/htmlineage -s htmlineage
 ```
 
-## Usage
+Or copy [`skills/htmlineage/`](skills/htmlineage/) into your tool's skills folder (for example `.claude/skills/` for Claude Code, `.agents/skills/` for most others).
+
+The skill is opt-in: your assistant uses it when you ask for a report that will be reviewed, traced or shared with leadership, and not for quick questions. To use it for every report in a repository, add a line such as "Every report built here uses htmlineage" to the instructions file your tool reads (`AGENTS.md`, `CLAUDE.md` or similar).
+
+**The CLI** needs Node 18 or later and nothing else. There is nothing to install: run it with `npx`.
 
 ```bash
-npx htmlineage@next check report.html       # validate the lineage and embed it into the report
-npx htmlineage@next sql report.html         # compose the whole report into one SQL script
-npx htmlineage@next sql report.html --id f3 # the SQL behind one number
-npx htmlineage@next view report.html        # open the report beside its lineage
+npx htmlineage --help
 ```
 
-Run `htmlineage <command> --help` for the options of each command.
+## Build and check a report
+
+### 1. Ask for a report
+
+Tell your assistant you want a report that will be reviewed, traced or shared with leadership. The assistant writes the report as plain HTML and, beside it, the lineage graph in `.lineage/<report>.json`.
 
-### `check`
+### 2. Check it
 
-Reads the lineage graph from `.lineage/<report>.json` beside the report, checks it against the report's `data-lineage` bindings, embeds it into the HTML, and prints a summary. Exits `0` when the report passes (warnings still pass) and `1` when it does not. Use `--no-embed` to leave the file untouched and `--json` for machine-readable output.
+This validates the graph against the report, embeds it into the HTML, and prints a summary. It exits `0` when the report passes (warnings still pass) and `1` when it does not.
 
-### `sql`
+```bash
+npx htmlineage check report.html
+```
+
+It reads the graph from `.lineage/<report>.json` beside the report, or else the block already embedded in the report; `--graph <path>` reads that file instead. Use `--no-embed` to leave the file untouched and `--json` for machine-readable output. The rules and what each message means are in [CHECKS.md](https://github.com/htmlineage/htmlineage/blob/main/CHECKS.md).
 
-Joins every source, view, and figure into a single script a reviewer can paste into the warehouse. `--id <node>` composes only that node and everything it rests on. External and ungrounded nodes are listed as trailing comments. A report that fails `check` is refused.
+### 3. Open it
 
-### `view`
+This serves a two-pane page on 127.0.0.1: the report on the left, the lineage of whatever you click on the right.
+
+```bash
+npx htmlineage view report.html
+```
 
-Serves a two-pane page on `localhost`: the report on the left, the lineage of whatever you click on the right. It reads only the report and its graph — no database, no credentials. The viewer itself makes no requests off your machine.
+### 4. Compose the SQL
+
+This joins every source, view, and figure into a single script a reviewer can paste into the warehouse. A report that fails `check` is refused.
+
+```bash
+npx htmlineage sql report.html > report.sql
+npx htmlineage sql report.html --id f3 > f3.sql
+```
+
+`--id <node>` composes only that node and everything it rests on.
+
+Each command has its own options: run `npx htmlineage <command> --help`.
+
+## Review a report
+
+To review a report someone else built, ask your assistant to review it. The skill then follows [the review guide](skills/htmlineage/references/review.md): read the check summary, trace the numbers that carry the report, and say where the evidence is weak.
+
+To do it yourself, run `check`, click through the report in `view`, and run `sql --id` on the numbers that matter.
+
+`view` serves the report, its graph and files beside the report such as images, only on 127.0.0.1. It never serves any other file whose name starts with a dot or that lies outside the report's folder, and it needs no database or credentials. More in [SECURITY.md](SECURITY.md).
 
 ## How lineage is recorded
 
@@ -62,6 +104,8 @@ Elements on the page point at nodes:
 <div class="kpi-value" data-lineage="f1">46.6%</div>
 ```
 
+Every field of every step is in the [field reference](skills/htmlineage/references/format.md), and a complete short report with its graph is in the [worked example](skills/htmlineage/references/example/).
+
 ## License
 
 Apache-2.0 © Varun Jain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlineage",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-beta.0",
   "description": "A provenance layer for AI-generated reports — every number, chart, and claim traces back to the query that produced it.",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "index.js",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"

package/skills/htmlineage/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: htmlineage
+description: Records where every number in an HTML data report came from, so a reviewer can trace each figure, chart and claim back to the query behind it. Use when the user asks for a report that will be reviewed, traced or shared with leadership, asks for lineage or htmlineage by name, or when project instructions say reports use htmlineage. Also use to review such a report or explain how one of its numbers was computed. Skip it for quick, throwaway analysis unless asked.
+---
+
+# htmlineage
+
+While you build a report, you also write down how each thing on the page was
+made: which query, which step, which value. That record is the lineage graph.
+`htmlineage check` validates it and embeds it in the report. A reviewer can
+then open any number and see the SQL behind it.
+
+This changes nothing about how you query, chart or write. The report looks the
+same with or without it. You add the graph and you run `check`.
+
+## When to use it
+
+Use it when the report will be reviewed before it is shared: the user says so,
+asks for lineage or htmlineage, or the project's instructions say every report
+there uses it. Do not use it for a quick look at some data, or when the user
+says they do not need it. When you are unsure, ask once.
+
+## The shape
+
+Every value reaches the page by one path:
+
+1. **Source.** Pull once, wide, per mart: one query per dataset, with the
+   reporting period as literal dates.
+2. **View.** Make a view for everything you show: each chart and each table
+   is a SELECT over sources or other views.
+3. **Figure.** Pick each number from a view: one cell. Or derive it from other
+   figures with an expression.
+4. **Insight.** Write each claim over the figures, views and insights it
+   rests on.
+
+If a claim rests on nothing you queried, keep it and mark it ungrounded. Never
+leave it out to make the report look cleaner.
+
+## Workflow
+
+1. Query the warehouse the way you normally would. Write each source into the
+   graph as you run it.
+2. Write the graph to `.lineage/<report-stem>.json`, beside the report. For
+   `growth-review.html` that is `.lineage/growth-review.json`. Add views,
+   figures and insights to it as you build the page, not at the end.
+3. Put `data-lineage="<id>"` on every element that shows a view, figure or
+   insight. A number inside a sentence gets its own span.
+4. Run `npx htmlineage check <report>.html`.
+5. Fix every error. Most messages end with what to change. Run `check` again.
+6. Fix the warnings you can. A warning does not fail the report, but each one
+   is something a reviewer will see.
+7. When you edit the page after this, update the graph to match and run
+   `check` again. It is the last thing you do before you hand the report over.
+
+`check` exits 0 when the report passes, with or without warnings, and 1 when
+it does not. Exit 2 means the command was wrong (a bad flag, or no report
+named): fix the command, not the graph. Never write the embedded
+`<script>` block yourself; `check` does.
+
+## Pin time
+
+Every source names its period with literal dates, both in `period` and in its
+SQL:
+
+```sql
+where order_date between '2026-08-01' and '2026-08-31'
+```
+
+Never use `current_date`, `now()`, `dateadd(…, current_date)` or "last 30
+days". A report must give the same numbers when it is run again next month.
+
+## Patterns
+
+- **Ranks.** Add a `rank() over (…)` column to the view already on the page,
+  then pick the rank as a figure. Do not make a separate unbound view for it.
+- **Shares.** Pick from the view on the page with a subquery in the figure's
+  SQL, for example a channel's count over the total, when no shown view has
+  the share as a column.
+- **A change or a ratio.** A figure with `expr` over other figures, such as
+  `(f1 - f2) / f2`. It has no `sql`.
+- **A change in a rate.** When a percentage moves, say whether the change is
+  in points or relative: "up 4.9 points" or "a relative gain of 11.8%", never
+  a bare "up 11.8%".
+- **A name.** A figure can hold text, such as the top channel's name. Its
+  `value` and `display` are the name.
+- **A number you were told.** When someone hands you a number or a file (a
+  target, a forecast, a CSV), make an external source with `given` saying what
+  you were handed and by whom. Put a figure over it, and bind the figure. Never
+  bind the source.
+- **Copy `display` exactly.** The span's text is the figure's `display`,
+  character for character: `46.6%`, not `46.60%` or `47%`.
+- **Metric names.** Write `30-day retention`, not "retention over 30 days".
+  `check` reads a number joined to a time unit by a hyphen as part of a
+  definition, not a claim to trace.
+- **Opinion and forecast.** A claim from judgement or outside knowledge is an
+  insight with `"ungrounded": true` and `"from": []`. Ungrounded means no data
+  backs it. A projection you can compute from figures, such as "at this pace
+  we end the year at $1.47M", is an `expr` figure and the claim rests on it.
+- **Every number a claim leans on.** If a claim depends on a quantity, that
+  quantity is a figure shown on the page and the claim rests on it. "All of
+  the growth came from new customers" needs new MRR on the page, not only the
+  totals beside it.
+
+## Describe each step
+
+Sql sources, views and figures carry a `desc`: one line, 120 characters at
+most, saying how the step was computed. A reviewer reads it before the SQL.
+
+- Use business words. Name the population, the filter and the time window.
+- No result values: the desc says how, not what came out.
+- No SQL words: no `select`, `join`, column names or table names.
+
+| Step               | Good                                                                          | Bad                                                           |
+| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| sql source         | Retention by channel and cohort month, January to August 2026                 | select channel, retention_30d from marts.retention_by_channel |
+| view               | Average 30-day retention for each channel and month, ranked within each month | Retention by channel, paid social leads at 46.6%              |
+| figure with `sql`  | Paid social's 30-day retention for the August 2026 cohort                     | Pick from v1 where channel = paid_social                      |
+| figure with `expr` | Change in paid social retention from July to August, relative to July         | (f1 - f2) / f2                                                |
+
+A figure's `label` is what the number _is_ ("Paid social retention,
+August"). Its `desc` is how it was _computed_.
+
+## SQL style
+
+The composed SQL is what a reviewer reads, so write it to be read:
+
+- Lowercase keywords, one clause per line, one column per line.
+- Name every computed column: `avg(retention_30d) as retention`.
+- Aliases of three letters or more.
+- A view or figure names its parents by id, as table names: `from q1`,
+  `from v2`.
+- List columns. No `select *`.
+
+## Don't
+
+- Give a figure its own query against the warehouse. It picks from a view or
+  source that is already there.
+- Leave a number in prose outside a `data-lineage` span.
+- Use `current_date` or any relative date, anywhere.
+- Chain views deeply. Each link is one more thing a reviewer has to read;
+  two deep is usually enough.
+- Drop a claim you cannot source. Mark it ungrounded instead.
+
+## When asked how a number was computed
+
+For a number, chart or claim in a report, your own or one you were handed,
+take the id from the element's `data-lineage` attribute and run:
+
+```
+npx htmlineage sql <report>.html --id <id>
+```
+
+It prints one runnable script: the source, every view and the figure, in
+order. Answer from that script rather than by reading the graph by hand.
+`npx htmlineage view <report>.html` opens the report beside its lineage for a
+person to click through.
+
+## When asked to review a report
+
+Follow [references/review.md](references/review.md). In short: read the check
+summary with `--no-embed`, trace the numbers the report rests on with
+`sql --id`, and report what is weak. Do not edit the report.
+
+## References
+
+- [references/format.md](references/format.md): every field of every kind of
+  node, what may rest on what, ids, and binding. Open it when you write your
+  first graph, or when `check` names a field you do not recognise.
+- [references/example/](references/example/): a complete short report with
+  its graph, the order it was built in, and the `check` output it gives. Read
+  it before your first report; copy its shape.
+- [references/review.md](references/review.md): how to review a report
+  someone else built. Open it only when asked to review.

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>