docs: fix the four front-door examples that misrepresented the language

README.md

@@ -145,7 +145,9 @@ reading is 5.0
 reading is 2.0
 reading is 5.0
 reading is 2.0
-report of reading             # "oscillating"
+reading is 5.0
+reading is 2.0
+report of reading             # "oscillating"  (needs a few periods to classify)
 ```
 
 Trajectory states: `converged`, `stable`, `equilibrium`, `oscillating`,
@@ -269,7 +271,9 @@ Pure EigenScript libraries under `lib/`:
 
 ```eigenscript
 load_file of "lib/list.eigs"
-doubled is map of [[1,2,3], double]
+define double as:                        # functions take one argument, n
+    return n * 2
+doubled is map of [[1, 2, 3], double]    # [2, 4, 6]
 ```
 
 See [docs/STDLIB.md](docs/STDLIB.md) for the full library guide.

docs/GRAMMAR.md

@@ -47,7 +47,9 @@ COMMENT     = '#' { any } '\n'
 
 letter      = 'a'..'z' | 'A'..'Z'
 digit       = '0'..'9'
-escape      = '\n' | '\t' | '\r' | '\\' | '\"' | '\{' | '\}'
+escape      = '\n' | '\t' | '\r' | '\\' | '\"' | '\' any
+              # only n t r \ " are special; any other '\x' yields literal x
+              # (so '\{' and '\}' give literal braces)
 ```
 
 ### Keywords

docs/LANGUAGE_CONTRACT.md

@@ -118,7 +118,9 @@ examples (executed by the suite).
   byte-offset operations — this is the documented consequence of the byte
   model, not a bug.
 - Strings are immutable; comparison (`==`, `<`) is bytewise.
-- String literals support the escapes `\n \t \r \\ \" \{ \}`. There is no `\0`,
+- String literals recognize the escapes `\n \t \r \\ \"`; any other `\x`
+  yields the literal character `x` (the backslash is dropped) — this is how
+  `\{` and `\}` produce literal braces in f-strings. There is no `\0`,
   `\xNN`, or `\u{…}` escape, so a string cannot embed a NUL or an arbitrary
   byte from source (only the raw bytes present in the source file flow
   through). An embedded NUL, if one ever arrived from file/buffer input,

docs/SYNTAX.md

@@ -135,6 +135,10 @@ print of f"list length: {len of items}"
 Expressions inside `{}` are evaluated and converted to strings. Use `\{` and
 `\}` for literal braces.
 
+Both plain and `f` strings recognize the escapes `\n`, `\t`, `\r`, `\\`, and
+`\"`. Any other `\x` yields the literal character `x` (the backslash is
+dropped) — which is exactly why `\{` and `\}` produce literal braces.
+
 ## Interactive REPL
 
 Run `eigenscript` with no arguments to enter the REPL:

lib/format.eigs

@@ -8,7 +8,7 @@
 #   fmt_num of [value, decimals]            # "3.14"
 #   fmt_percent of [0.856, 1]               # "85.6%"
 #   fmt_table of [headers, rows]            # aligned text table
-#   fmt_bar of [value, max_val, width]      # "████░░░░░░"
+#   fmt_bar of [6, 10, 10]                  # "[######....] 60.0%"
 #   fmt_padded of [value, width]            # right-aligned in field
 
 # ---- fmt_num: format number to fixed decimal places ----