docs: finish the QA fix list

- README: fix the run-on support sentence, backtick htmlspecialchars()
- date example: use a 2026 timestamp (example dates use the current
  year), update the test to match
- method-reference: trim() shows its real signature, pregReplace() says
  what throws and what returns null, add missing backticks here and in
  ai-reference
- troubleshooting: decode example uses the same flags as the other pages
- ai-reference: new SmartString() works like new(); point phoneFormat()
  users at pregReplace() like the changelog does
- cut the grep-audit sentence from the encoding intro (audit tips don't
  belong on a learning page), reword three phrases into plain English

Author: daveedis

README.md

@@ -11,7 +11,7 @@ https://github.com/interactivetools-com/SmartString/blob/main/docs/ai-reference.
 
 SmartString lets you write template code that's shorter, easier to read, and XSS-safe by default.
 Values HTML-encode themselves the moment you echo, interpolate, or concatenate them, so one
-forgotten htmlspecialchars() can't become an injection.
+forgotten `htmlspecialchars()` can't become an injection.
 
 Instead of writing code like this:
 
@@ -70,7 +70,7 @@ $rows = $orders->toArray();
 
 ## Questions?
 
-This library was developed for CMS Builder, post a message in our "CMS Builder" forum here:
+This library was developed for CMS Builder. Post a message in our "CMS Builder" forum here:
 [https://www.interactivetools.com/forum/](https://www.interactivetools.com/forum/)
 
 ## License

docs/ai-reference.md

@@ -50,6 +50,11 @@ echo $str->value();                           // It's easy!<hr>
 echo $str->trim()->maxChars(60)->or('None');  // chains left to right
 ```
 
+`new SmartString($value)` and `SmartString::new($value)` do the same thing.
+`new()` also accepts arrays (returns `SmartArrayHtml`), and before PHP 8.4
+`new SmartString($x)->trim()` is a syntax error without wrapping parentheses;
+`SmartString::new($x)->trim()` always works.
+
 Key definitions used throughout:
 
 - **missing** = null or `""` exactly. Zero (`0`, `"0"`) and `false` are NOT
@@ -252,10 +257,10 @@ map(callable|string $callback, mixed ...$args): SmartString
 
 Calls `$callback($rawValue, ...$args)` and wraps the result. The callback ALWAYS
 runs and receives the raw value in its original type, null included (matches
-`array_map()`). Built-ins with typed string parameters throw TypeError on null
+`array_map()`). Built-ins with typed string parameters throw `TypeError` on null
 or numeric values - chain `->map('strval')` first. Callback must return scalar or null; other
-return types throw InvalidArgumentException. Non-callable `$callback` throws
-InvalidArgumentException.
+return types throw `InvalidArgumentException`. Non-callable `$callback` throws
+`InvalidArgumentException`.
 
 ```php
 echo $name->map('mb_strtoupper');
@@ -340,7 +345,7 @@ deprecated; always write the current name in new code.
 | `->noEncode()`             | `->rawHtml()`                                                              |
 | `->jsEncode()`             | `->jsonEncode()` - different output; the old name keeps the old behavior   |
 | `SmartString::fromArray()` | `SmartArrayHtml::new()` (SmartArray library)                               |
-| `->phoneFormat()`          | retired, no replacement - format phone numbers yourself                    |
+| `->phoneFormat()`          | retired - use `pregReplace()` or format the number yourself                |
 | `SmartString::help()`      | retired - this file and the GitHub docs replaced it                        |
 
 ---

docs/common-patterns.md

@@ -238,9 +238,9 @@ function is called just once (the name matches `array_map()` and
 `SmartArray::map()`):
 
 ```php
-echo $province->code->map('mb_strtoupper');                          // BC
-echo $user->name->map('strval')->map('mb_convert_case', MB_CASE_TITLE); // built-ins need a string: strval converts null and numbers
-echo $sku->map(fn($v) => str_pad((string)$v, 6, '0', STR_PAD_LEFT));  // zero-pads to 6 digits: 000042
+echo $province->code->map('mb_strtoupper');                              // BC
+echo $user->name->map('strval')->map('mb_convert_case', MB_CASE_TITLE);  // built-ins need a string: strval converts null and numbers
+echo $sku->map(fn($v) => str_pad((string)$v, 6, '0', STR_PAD_LEFT));     // zero-pads to 6 digits: 000042
 ```
 
 A closure even works inside a template string; wrap the whole chain in

docs/encoding-and-html.md

@@ -6,9 +6,7 @@ Auto-encoding is SmartString's main job, and this page covers all of it:
 how encoding works, the encoding methods for URLs and JSON, and the named
 methods that let real markup through: `nl2br()`, `rawHtml()`, and the
 `appendHtml()`/`wrapHtml()` pair. Markup enters your page only through
-those named methods, which is what makes SmartString output reviewable:
-search for `rawHtml(` and `Html(` and you have found every place unencoded
-markup can appear.
+those named methods; everything else comes out encoded.
 
 Contents:
 

docs/method-reference.md

@@ -71,10 +71,10 @@ ready for regular PHP code.
 | `->prepend($value)`                     | Adds `$value` to the beginning of the current value                                      |
 | `->wrap($before, $after)`               | Wraps the value; pass "" for a side you don't want                                       |
 | `->textOnly()`                          | Removes HTML tags, decodes entities, and trims whitespace                                |
-| `->trim()`                              | Trims whitespace (or the characters you specify) from both ends                          |
+| `->trim(...$args)`                      | Trims whitespace from both ends, or pass a character list like PHP `trim()`              |
 | `->maxWords($max, $ellipsis = '...')`   | Limits the value to `$max` words; adds `$ellipsis` if text was cut off                   |
 | `->maxChars($max, $ellipsis = '...')`   | Limits the value to `$max` characters; adds `$ellipsis` if text was cut off              |
-| `->pregReplace($pattern, $replacement)` | Replaces text matching a regex pattern                                      |
+| `->pregReplace($pattern, $replacement)` | Replaces text matching a regex; an invalid `$pattern` throws `InvalidArgumentException`, a value it can't process (bad UTF-8) returns null |
 
 ### [Dates & Numbers](text-and-formatting.md#formatting-dates---dateformat)
 
@@ -116,8 +116,8 @@ continues. Zero counts as present.*
 |-------------------------|--------------------------------------------------------------------------------------|
 | `->orDie($text)`        | Outputs the message and exits                                                        |
 | `->or404($text = null)` | Outputs a 404 header and the message (default: standard not-found text), then exits  |
-| `->orThrow($text)`      | Throws a RuntimeException with the message                                           |
-| `->orRedirect($url)`    | Redirects to `$url` and exits (throws RuntimeException if headers were already sent) |
+| `->orThrow($text)`      | Throws a `RuntimeException` with the message                                         |
+| `->orRedirect($url)`    | Redirects to `$url` and exits (throws `RuntimeException` if headers were already sent) |
 
 ### [Value Checks](conditionals-and-error-checking.md#truefalse-checks---isempty-isnotempty-ismissing-isnull)
 
@@ -127,8 +127,8 @@ want.*
 
 | Method           | Description                                                                          |
 |------------------|--------------------------------------------------------------------------------------|
-| `->isEmpty()`    | Returns true when the value is empty ("", null, false, 0, "0") - same as PHP empty() |
-| `->isNotEmpty()` | Returns true when the value has content - the exact opposite of isEmpty()            |
+| `->isEmpty()`    | Returns true when the value is empty ("", null, false, 0, "0") - same as PHP `empty()` |
+| `->isNotEmpty()` | Returns true when the value has content - the exact opposite of `isEmpty()`          |
 | `->isMissing()`  | Returns true when the value is missing (null or ""); zero counts as present          |
 | `->isNull()`     | Returns true when the value is null                                                  |
 

docs/performance.md

@@ -174,7 +174,7 @@ combinations, recorded in the repo at `.github/scripts/speed-results.md`.
 Four benchmark choices, stated plainly:
 
 - **Both sides produce identical output.** The helper is timed with the same
-  full flags SmartString uses, so the race is work-for-work:
+  full flags SmartString uses, so both sides do the same work:
 
   ```php
   htmlspecialchars($s, ENT_QUOTES | ENT_SUBSTITUTE | ENT_DISALLOWED | ENT_HTML5, 'UTF-8');      // both what we time against and what we produce

docs/text-and-formatting.md

@@ -160,7 +160,7 @@ shows. Numeric values are treated as unix timestamps and format in your
 server's PHP timezone; everything else is parsed with `strtotime()`:
 
 ```php
-echo SmartString::new(1684159800)->dateFormat('Y-m-d T');  // 2023-05-15 PDT
+echo SmartString::new(1778866200)->dateFormat('Y-m-d T');  // 2026-05-15 PDT
 ```
 
 Invalid dates return null rather than throwing, so a fallback chains
@@ -281,8 +281,8 @@ before the math:
 echo $value->ifNull(0)->add(50);  // 50
 ```
 
-A null result is a value like any other, so a mid-chain replacement fully
-recovers the chain; nothing is poisoned:
+A null result is a value like any other, so you can swap in a fallback
+mid-chain and the calls after it run on the new value:
 
 ```php
 echo SmartString::new("cat")->add(10)->ifNull(0)->add(5);  // 5 (recovered mid-chain)

docs/troubleshooting.md

@@ -82,7 +82,7 @@ The other cause is a database that already contains encoded text, usually
 from a form handler that encoded values before saving them. Whatever is
 stored encoded gets encoded again on output. Save the raw text instead,
 then clean up the existing rows with a one-time
-`htmlspecialchars_decode($value, ENT_QUOTES | ENT_HTML5)` (the flags
+`htmlspecialchars_decode($value, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5)` (the flags
 matter; the defaults leave `'` behind).
 
 ### or() kept my zero / isEmpty() lost my zero

tests/Integration/DocsExamplesTest.php

@@ -245,7 +245,7 @@ public function testDateFormat(): void
         $this->assertSame('May 15th, 2026', (string)$date->dateFormat());
 
         date_default_timezone_set('America/Vancouver'); // the docs show the timestamp example with T = PDT
-        $this->assertSame('2023-05-15 PDT', (string)SmartString::new(1684159800)->dateFormat('Y-m-d T'));
+        $this->assertSame('2026-05-15 PDT', (string)SmartString::new(1778866200)->dateFormat('Y-m-d T'));
 
         $invalid = SmartString::new("not a date");
         $this->assertSame('Date not set', (string)$invalid->dateFormat()->or("Date not set"));