Compile the documentation's own code samples; tooling fixes and WIP reorganisation.

BUGS-TO-REPORT.md

@@ -0,0 +1,74 @@
+# twinBASIC bugs to report
+
+A queue, not a record. Each entry is a **product** bug --- something twinBASIC itself does
+wrong --- observed while working on this documentation. **Delete an entry once it has been
+filed upstream**; nothing here is meant to accumulate, and an entry that stays after it is
+filed turns this file into a second, worse issue tracker.
+
+Documentation defects do not belong here. They are fixed in `docs/`, and the ones that are
+not yet fixed are recorded in the relevant `WIP.*.md`.
+
+What an entry owes a reader:
+
+- the **build** it was seen on, because the answer changes between betas;
+- a **minimal reproduction**, narrowed rather than pasted --- the thing that made it
+  reproduce is usually smaller and stranger than the code it was found in;
+- what was tried that did **not** reproduce it, which is half of what makes a report
+  actionable;
+- how it was **observed**, so somebody else can see the same thing.
+
+---
+
+## Compiler crashes on an `Interface` whose name and base are both angle-bracket placeholders
+
+**Build:** BETA 983 (`twinBASIC_win32.dll+00141F7A`)
+**Severity:** crash --- takes the compiler down, three restarts, then the IDE gives up.
+
+This two-line file is the whole reproduction:
+
+```
+Interface <name> Extends <base-interface>
+End Interface
+```
+
+The IDE's DEBUG CONSOLE reports `NATIVE EXCEPTION: ACCESS_VIOLATION {no-basic-code}` with
+`>>> thread 0004: ParsingFileStart, <that file>`, then `restarting from MEMORY`, three
+times over.
+
+**Neither half reproduces it on its own**, which is what makes it worth reporting rather
+than shrugging at:
+
+| source | result |
+|---|---|
+| `Interface <name>` + `End Interface` | TB5182 Syntax error, no crash |
+| `Interface IFoo Extends <base-interface>` + `End Interface` | TB5182 + TB5079 + TB5127, no crash |
+| `Interface <name> Extends <base-interface>` + `End Interface` | **crash** |
+
+So it takes a placeholder in *both* positions. The input is not real code --- it is a
+syntax skeleton, the shape `docs/Reference/Attributes.md` uses to show where an attribute
+goes --- but a parser meeting nonsense should diagnose it, and this one dereferences
+something instead.
+
+**Found by** pointing `scripts/check_examples.mjs` at the documentation's own code samples;
+the skeleton is one of the 1,116 `tb` fences under `docs/`. A crash in a batch of samples
+costs the whole batch its result, which is why that tool bisects on exit code 4.
+
+---
+
+## `--buildAndExit32` writes nothing, exits 0 on a project with errors, and hangs on a failing build
+
+**Build:** BETA 983
+**Severity:** makes the documented unattended-build switch unusable.
+
+The IDE executable accepts `--buildAndExit32` and `--buildAndExit64`; `parseCommandLine()`
+reads them, and Personal Edition is refused by name, so they are real. Measured three ways:
+
+- **nothing is written to stdout or stderr, ever** --- no diagnostics, no summary;
+- it **exits 0 on a project the IDE flags with errors**;
+- when the build genuinely fails it **does not exit at all**, sitting on a *"Please wait…"*
+  dialog at 100% indefinitely.
+
+Silent, falsely green, and hanging on the one case worth catching. This is why
+`scripts/tbbuild.mjs` drives the IDE's WebView over CDP instead --- see
+[WIP.Harness.md](WIP.Harness.md#compiling-a-twinbasic-project-without-the-ide-in-front-of-you), which
+records the same measurements.

README.md

@@ -29,9 +29,10 @@ serve.bat     # localhost:4000 with watch + live reload
 check.bat     # the gates that read the built site, ending in the accessibility scan
 test.bat      # the gates that test the toolchain itself
 book.bat      # renders the PDF book; run build.bat first
+examples.bat  # compiles the twinBASIC code samples in the pages (Windows + a twinBASIC install)
 ```
 
-A clean `build.bat && check.bat` is the bar for "ready to commit"; add `test.bat` when the change touched anything outside `docs/`. Each wrapper names the gates it runs, in order, on [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools). On Linux or macOS, run the `node` command inside each batch file directly --- they are thin wrappers.
+A clean `build.bat && check.bat` is the bar for "ready to commit"; add `test.bat` when the change touched anything outside `docs/`. Each wrapper names the gates it runs, in order, on [Tools and Scripts](https://docs.twinbasic.com/Documentation/Development/Tools). On Linux or macOS, run the `node` command inside each batch file directly --- they are thin wrappers. `examples.bat` is the exception to both: it drives the twinBASIC IDE, so it is Windows-only and is deliberately outside every gate and outside CI.
 
 Where to read more: