chore: further copy fixes, highlight "patch" section as being experimental

Author: grega

README.md

@@ -4,14 +4,14 @@ A small library that explains Python error messages in a friendlier way, inspire
 
 It can be used in browser-based editors (like RPF's [Code Editor web component](https://github.com/RaspberryPiFoundation/editor-ui)) or any environment that executes Python code through Pyodide or Skulpt.
 
-This library is currently **Pyodide-first**. The copydeck and demos are developed and verified against a pinned Pyodide version (see [`docs/pyodide-config.js`](docs/pyodide-config.js)), and the demo runs that Pyodide build live to show real tracebacks. Skulpt is still supported, both runtimes emit CPython-style tracebacks and share one adapter, but it is not the current priority, so error coverage is tuned to Pyodide's messages first.
+This library is currently **Pyodide-first**. The copydeck and demos are developed and verified against a pinned Pyodide version (see [`docs/pyodide-config.js`](docs/pyodide-config.js)), and the demo runs that Pyodide build live to show real tracebacks. Skulpt is still supported, both runtimes emit CPython-style tracebacks and share one adapter, but it is not the current priority.
 
 ## Features
 
 - Parses and normalises errors from Pyodide or Skulpt (via a shared CPython-traceback adapter)
-- Matches errors against a copydeck (JSON rules and templates)
-- Copydeck-based explanations can be localised
-- Returns structured explanations as well as ready-made HTML snippets
+- Matches errors against a copydeck (containing rules and templates)
+- Copydeck-based explanations can be localised (and the copydeck contains prompts and context to help with this)
+- Returns structured explanations as well as ready-to-use HTML snippets
 
 ## Usage
 
@@ -66,6 +66,8 @@ const result = friendlyExplain({
 
 See the [demo](docs/README.md) for a full set of examples.
 
+*Note:* The "patch" section contains a suggested code change to fix the error, but should be considered experimental at this stage.
+
 ## Accessibility
 
 `result.html` is built to be accessible by default (with WCAG 2.1 AA in mind):

copydecks/en/copydeck.json

@@ -232,12 +232,13 @@
     "IndentationError": {
       "variants": [
         {
-          "title": "The indentation doesn't match",
-          "summary": "All lines in a block must start in the same column. Fix around {{loc}}.",
-          "why": "Python groups code by indentation. Mixing tabs and spaces or uneven indents breaks the block.",
+          "title": "The indentation isn't right here",
+          "summary": "Python uses the spaces at the start of a line to group code into blocks, and the spacing around {{loc}} doesn't fit. A line may be indented when it shouldn't be, or missing the indentation a block needs.",
+          "why": "Lines in the same block must start in the same column, a block only opens after a line ending in a colon (:), and a line can't be indented for no reason.",
           "steps": [
-            "Use 4 spaces per level (not tabs).",
-            "Line up all lines in the block."
+            "If a line is indented but nothing above it ends in a colon (:), remove the extra spaces.",
+            "If a block was expected (after a line ending in :), indent its lines by the same amount.",
+            "Keep spacing consistent - 4 spaces per level - and don't mix tabs and spaces."
           ],
           "_placeholders": {
             "loc": "Where the indentation problem is, eg. line 7 in main.py"
@@ -251,10 +252,10 @@
         {
           "title": "These data types don't work together",
           "summary": "You're joining (concatenating) different kinds of data types. For example, a number (integer or float) and a word (string).",
-          "why": "When using + to join text and variables together the variable must have a string data type.",
+          "why": "Python's + means 'add' for numbers and 'join' for text, so both sides have to be the same kind. It can't add a number to a piece of text.",
           "steps": [
-            "Cast the variable as a string data type.",
-            "Change the variable to the right kind: int(\"3\") or str(7)."
+            "To join them as text, convert the number with str(...).",
+            "To add them as numbers instead, make sure neither side is text."
           ]
         }
       ]
@@ -297,7 +298,7 @@
         {
           "title": "This index position does not exist",
           "summary": "You are trying to use an index position that does not exist. The list is not that long.",
-          "why": "In this list: myList[\"A\", \"B\", \"C\"] \"A\" has the index position 0, \"B\" has the index position 1 and \"C\" has the index position 2. Index position 3 does not exist.",
+          "why": "Items are counted from 0. In myList = [\"A\", \"B\", \"C\"], \"A\" is at index 0, \"B\" at 1 and \"C\" at 2 - so the largest valid index is 2, and index 3 does not exist.",
           "steps": [
             "Check the length with len(the_list).",
             "Use an index position number smaller than len(the_list)."

src/engine.ts

@@ -104,7 +104,7 @@ const pickVariant = (trace: Trace, code: string | undefined, sections?: Section[
     let patch: string | undefined = undefined;
     if (trace.type === "AttributeError" && /\.push\s*\(/i.test(codeLine)) {
       patch = codeLine.replace(/\.push\s*\(/i, ".append(");
-    } else if (trace.type === "NameError" && trace.name) {
+    } else if (trace.type === "NameError" && trace.name && !/cannot access free variable|not associated with a value/i.test(trace.message || "")) {
       patch = `${trace.name} = 0\n${codeLine}`;
     } else if (trace.type === "SyntaxError" && /^(if|for|while|def|class|elif|else|try|except|with)\b/i.test(codeLine) && !/:$/.test(codeLine.trim())) {
       const trimmedCodeLine = codeLine.replace(/\s*$/, "");