docs(embed): show the mapping, the warning banner and a date anchor

Screenshots taken against the demo estate with a licence key installed, so
no evaluation banner appears. The banner section now tabulates every cause
the editor reports, because the reader is the report author looking at the
Data Controller object and the URL is the only thing they can edit.

docs/embed-va.md

@@ -69,6 +69,10 @@ Repeat the parameter to add mappings.  A report with two tabs, each holding its
 | Tab 1 | `...?embed=va&va_parmap=REGION_TAB1-REGION` |
 | Tab 2 | `...?embed=va&va_parmap=REGION_TAB2-REGION` |
 
+The applied filter is visible in the editor, above the grid - here the parameter `DROPDOWN_TAB1` filtering `SOME_DROPDOWN`, which is not its name:
+
+![A va_parmap mapping filtering a column](img/va-parmap-filtered.png)
+
 The mapping is per parameter, and additive:
 
 - a mapped parameter always filters the column it names; that column's type in the table decides how the value is formatted, exactly as for a name match
@@ -79,7 +83,25 @@ The mapping is per parameter, and additive:
 - a column name that is not a plain SAS name is ignored
 - the mapping applies to filtering only; which columns the grid displays still follows the columns VA sends
 
-If an entry cannot be used the editor shows a warning banner above the grid naming the parameter, the column and the table - for example when the column is not in the table being opened, or the entry is not in the `parameter-column` form.  The parameter is then ignored rather than falling back to the name match, so a typo never silently filters the wrong column, and the banner is what distinguishes "the mapping is wrong" from a view that simply has no filter.
+## When a mapping cannot be used
+
+A wrong mapping would otherwise look like a working filter over the whole table, so the editor puts a banner above the grid naming the parameter, the column, the table, and what to change:
+
+![The va_parmap warning banner](img/va-parmap-banner.png)
+
+Each line names one cause, and the parameter it concerns is skipped rather than falling back to the name match - a typo never silently filters the wrong column:
+
+| What the banner says | What it means |
+|---|---|
+| `is not a column of <libref>.<table>` | the mapped column does not exist in the table being opened |
+| `is not a date or datetime column` | a date anchor (`ADD`/`RANGE`) was applied to a column that holds something else |
+| `VA is not sending` | no message has named that parameter - usually a spelling mistake in the parameter side of the entry |
+| `all filter <COLUMN> ... different values will show no rows` | two parameters map to one column with different values, so the AND can never match |
+| `a range needs one value` | a `RANGE` mapping was sent several values - one `BETWEEN` carries one period |
+| `N of its M values was not a date` | part of a multi-value parameter could not be read as a date, so only the rest is applied |
+| `was ignored: it needs a "-"` / `is not a transform` | the entry itself is malformed |
+
+The banner is shown to the report author, inside the report, because that is where the entry is edited: the only fix available from the editor is to change the `va_parmap` entries in the URL of the Data Controller object.
 
 !!! note
     A parameter label containing `&` must be percent-encoded (`%26`), because `&` separates query parameters.  A space may be written as `+` or `%20`.
@@ -92,7 +114,13 @@ A mapping can resolve the parameter value through a **named date anchor** before
 https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1)
 ```
 
-A report that sends `SELECTED_DATE = 01OCT2026` then filters `D_DATE` on 2026-10-01 **and** 2026-07-01 - the selected date's quarter, plus the same point one quarter earlier.
+A report that sends `SELECTED_DATE = 27FEB1961` then filters `D_DATE` on 1961-02-27 **and** 1960-10-01 - the selected date, plus the same point one quarter earlier:
+
+In the screenshot below the mapping is `SELECTED_DATE-SOME_DATE:ADD(QUARTER_START,-1)` against the demo table, and the parameter sends 27FEB1961:
+
+![A date anchor applied to the filter](img/va-parmap-transform.png)
+
+The clause carries both values, so the row for the selected date and the row for the previous quarter are both included.
 
 | Transform | Result | Filter |
 |---|---|---|