Add recipe-style usage examples to the README

README.md

@@ -81,6 +81,119 @@ One import, one line. A clean, sorted DataFrame you can read or feed into the ne
 
 ## Examples
 
+These are short, recipe-style examples that go beyond the one-liner above and are intentionally not covered in the [documentation](https://data-centt.github.io/percentify/documentation/). The docs show each function in isolation; these show how to chain them into a real workflow.
+
+### A 30-second data-quality gate
+
+Drop this into CI to block training on a dataset that isn't ready:
+
+```python
+import pandas as pd
+from percentify import profiler
+
+df = pd.read_parquet("train.parquet")
+report = profiler(df, target="label")
+
+assert report.errors.empty, report.to_frame()
+assert report.health >= 80, f"health too low: {report.health}"
+```
+
+### Rank correlations by significance
+
+Pull the pairs that are both strong *and* unlikely to be noise:
+
+```python
+import pandas as pd
+from percentify import correlate
+
+df = pd.DataFrame({
+    "x":   range(50),
+    "y":   [v * 0.9 + (v % 3) for v in range(50)],
+    "z":   [v * 0.05 for v in range(50)],
+    "w":   [v % 7 for v in range(50)],
+})
+
+print(correlate(df).sort_values("p_value").head(5))
+```
+
+### Build a transform pipeline from `skew_report`
+
+Let `skew_report` tell you what to apply, then apply it:
+
+```python
+import numpy as np
+import pandas as pd
+from percentify import skew_report
+
+df = pd.DataFrame({
+    "income": [30_000, 35_000, 1_200_000, 40_000, 28_000],
+    "visits": [1, 1, 1, 50, 2],
+})
+
+plan = skew_report(df)
+print(plan[["feature", "skew", "suggested_transform"]])
+#    feature   skew suggested_transform
+# 0   income  2.27              log1p
+# 1   visits  2.19              log1p
+
+df["income_log"] = np.log1p(df["income"])     # numpy / pandas, not percentify
+df["visits_log"] = np.log1p(df["visits"])
+```
+
+### Interpret PCA with both calls
+
+Variance tells you *how much* of the signal each axis carries; loadings tell you *what it means*:
+
+```python
+import pandas as pd
+from percentify import pca_variance, pca_loadings
+
+df = pd.DataFrame({
+    "height_cm": [160, 170, 180, 175, 165],
+    "weight_kg": [55,  68,  82,  74,  60],
+    "age":       [25,  35,  45,  30,  28],
+})
+
+print(pca_variance(df))    # PC1 carries most of the variance
+print(pca_loadings(df))    # PC1 = (height, weight) with similar signs
+```
+
+### Drop collinear columns before modelling
+
+Use `vif` with a threshold to get a drop-list you can feed straight into `df.drop`:
+
+```python
+import pandas as pd
+from percentify import vif
+
+df = pd.DataFrame({
+    "price":  [10, 12, 11, 13, 9,  14, 8,  12],
+    "cost":   [ 6,  7,  7,  8, 5,   8, 4,   7],   # tracks price
+    "margin": [ 4,  5,  4,  5, 4,   6, 4,   5],   # = price - cost
+    "stock":  [100, 80, 90, 70, 110, 60, 120, 85],
+})
+
+to_drop = vif(df, flag=5.0)["feature"].tolist()
+print(to_drop)                # e.g. ['cost', 'margin']
+clean = df.drop(columns=to_drop)
+```
+
+### Month-over-month KPI table
+
+`change` over a DataFrame applies period-over-period growth to every numeric column at once:
+
+```python
+import pandas as pd
+from percentify import change
+
+kpis = pd.DataFrame({
+    "revenue": [100, 120, 150, 135, 180],
+    "signups": [400, 420, 470, 460, 510],
+}, index=["Jan", "Feb", "Mar", "Apr", "May"])
+
+print(change(kpis))
+```
+
 - [Worked examples for every function](https://data-centt.github.io/percentify/documentation/)
 - [Project documentation](https://data-centt.github.io/percentify/)