Update README and example outputs for clarity and consistency

Author: luisggoncalves

README.md

@@ -62,10 +62,10 @@ sqlcompare analyze-diff <diff_id> --missing-current
 
 ## Example outputs
 
-See `examples/README.md` for datasets, commands, and captured outputs.
+See `examples/` for datasets, commands, and captured outputs.
 
-- Row comparison output: `examples/row_compare/output.txt`
-- Statistical comparison output: `examples/stats_compare/output.txt`
+- Row comparison output: `examples/row_compare.md`
+- Statistical comparison output: `examples/stats_compare.md`
 
 ---
 

examples/row_compare.md

@@ -0,0 +1,42 @@
+# Row Compare
+
+Compare rows using a dataset YAML with file inputs
+
+```text
+Prepared dataset tables: examples.dataset_dataset_1f232b87_previous, examples.dataset_dataset_1f232b87_new
+✅ Ensured schema 'examples' exists
+Joining tables: examples.dataset_dataset_1f232b87_previous and examples.dataset_dataset_1f232b87_new
+Rows only in current dataset: 1
++----+-------+--------+--------+
+| id | name  | amount | status |
++----+-------+--------+--------+
+| 4  | delta |   40   |  open  |
++----+-------+--------+--------+
+Rows only in previous dataset: 1
++----+-------+--------+--------+
+| id | name  | amount | status |
++----+-------+--------+--------+
+| 2  | bravo |   20   |  open  |
++----+-------+--------+--------+
+🚨 Differences in values for common rows: 2 rows in total
+
+📊 Difference statistics by column:
++-------------+------------+
+| COLUMN_NAME | diff_count |
++-------------+------------+
+|    name     |     1      |
+|   amount    |     1      |
++-------------+------------+
+
+✅ Columns with no differences: status
+
+📋 Sample differences (first 10 rows):
++----+--------+--------+---------+
+| id | COLUMN | BEFORE | CURRENT |
++----+--------+--------+---------+
+| 1  |  name  | alpha  |  alfa   |
+| 1  | amount |   10   |   11    |
++----+--------+--------+---------+
+🔎 To review the diff, run: sqlcompare analyze-diff compare_examples_dataset_dataset_1f232b87_previous_examples_dataset_dataset_1f232b87_new_20260103_234457_9180044d
+💡 Tips: --stats for per-column counts, --missing-current/--missing-previous for row-only, --column <name> to filter, --list-columns to inspect available fields.
+```

examples/row_compare_missing.md

@@ -0,0 +1,13 @@
+# Row Compare Missing
+
+Show rows only in current/previous after a dataset comparison
+
+```text
+📂 Loaded diff data: 1 total differences
+📊 Showing 1 of 1 differences:
++-------------+---------------+-----------------+-----------------+--------+----------+------------+------------+
+| id_previous | name_previous | amount_previous | status_previous | id_new | name_new | amount_new | status_new |
++-------------+---------------+-----------------+-----------------+--------+----------+------------+------------+
+|             |               |                 |                 |   4    |  delta   |     40     |    open    |
++-------------+---------------+-----------------+-----------------+--------+----------+------------+------------+
+```

examples/stats_compare.md

@@ -0,0 +1,15 @@
+# Stats Compare
+
+Compare statistics between two CSV files
+
+```text
+📊 Table statistics comparison:
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+| COLUMN_NAME | PREV_ROWS | NEW_ROWS | PREV_NULLS | NEW_NULLS | PREV_DISTINCT | NEW_DISTINCT | ROWS_DIFF | NULLS_DIFF | DISTINCT_DIFF |
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+|     id      |     5     |    6     |     0      |     0     |       5       |      6       |     1     |     0      |       1       |
+|   segment   |     5     |    6     |     0      |     0     |       3       |      3       |     1     |     0      |       0       |
+|   amount    |     5     |    6     |     0      |     0     |       4       |      5       |     1     |     0      |       1       |
+|    notes    |     5     |    6     |     2      |     1     |       1       |      1       |     1     |     -1     |       0       |
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+```

examples/stats_compare_tables.md

@@ -0,0 +1,15 @@
+# Stats Compare Tables
+
+Compare statistics between tables loaded into DuckDB
+
+```text
+📊 Table statistics comparison:
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+| COLUMN_NAME | PREV_ROWS | NEW_ROWS | PREV_NULLS | NEW_NULLS | PREV_DISTINCT | NEW_DISTINCT | ROWS_DIFF | NULLS_DIFF | DISTINCT_DIFF |
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+|     id      |     5     |    6     |     0      |     0     |       5       |      6       |     1     |     0      |       1       |
+|   segment   |     5     |    6     |     0      |     0     |       3       |      3       |     1     |     0      |       0       |
+|   amount    |     5     |    6     |     0      |     0     |       4       |      5       |     1     |     0      |       1       |
+|    notes    |     5     |    6     |     2      |     1     |       1       |      1       |     1     |     -1     |       0       |
++-------------+-----------+----------+------------+-----------+---------------+--------------+-----------+------------+---------------+
+```

scripts/generate_examples/run.py

@@ -49,15 +49,33 @@ def main() -> int:
     for name, config in examples.items():
         if not isinstance(config, dict):
             raise ValueError(f"Example '{name}' must be a mapping.")
+        description = config.get("description")
+        if not description or not isinstance(description, str):
+            raise ValueError(f"Example '{name}' is missing a description string.")
+        title = config.get("title")
+        if not title or not isinstance(title, str):
+            title = name.replace("_", " ").title()
         command = config.get("command")
         if not command or not isinstance(command, str):
             raise ValueError(f"Example '{name}' is missing a command string.")
 
         print(f"Generating example '{name}'...")
         output = _run_command(command, root, env)
-        output_path = root / "examples" / name / "output.txt"
+        markdown_output = "\n".join(
+            [
+                f"# {title}",
+                "",
+                description,
+                "",
+                "```text",
+                output.rstrip("\n"),
+                "```",
+                "",
+            ]
+        )
+        output_path = root / "examples" / f"{name}.md"
         output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(output, encoding="utf-8")
+        output_path.write_text(markdown_output, encoding="utf-8")
 
     return 0