KubaO · Oct 12, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/BUGS-TO-REPORT.md b/BUGS-TO-REPORT.md
diff --git a/WIP.IDE.md b/WIP.IDE.md
@@ -0,0 +1,211 @@
+# The IDE section — finishing it
+
+The IDE section (`docs/IDE/`, `/tB/IDE`) is being rewritten so that every page is fit for
+the book. The goal is that `docs/_book.yml` holds no IDE entry under `left_out:`. This file
+covers the structure, the conventions, where each fact comes from, and how a chapter is
+written. Owner decisions, 2026-10-11:
+
+- task chapters plus a reference part;
+- permalinks flattened, with redirects;
+- the how-to material in `Features/Compiler-IDE` moved here;
+- `docs/IDE/_Images/*.af` deleted.
+
+The section is not bound to the structure it had. The existing pages are raw material.
+
+## What "book-ready" means for a page
+
+- No heading without text under it, no TODO, and no list of labels copied off a screenshot.
+  Every menu item, button and option has at least a sentence saying what it does.
+- Every claim about behaviour has been checked against BETA 1005 or newer: read from `main.js`,
+  or tried in an IDE on a private desktop. A screenshot or an older page is not a source.
+- The prose carries the information. Alt text describes the picture and holds no fact the
+  prose lacks; a long alt text that lists labels is a sign the prose is missing.
+- The conventions below are followed, and the page is in the IDE part of `_book.yml`.
+
+## Structure
+
+**Part A, Working in the IDE.** Each chapter is one page, or a short landing page with a few
+children. Second person ("you") is allowed here, as in tutorials.
+
+| # | Chapter | Permalink | Takes in |
+|---|---|---|---|
+| 1 | A tour of the IDE (landing page) | `/tB/IDE` | `index.md` |
+| 2 | Starting a project | `/tB/IDE/Starting` | New Project, Splash Screen, FAQ's first-launch and VBP-import parts |
+| 3 | Projects and files | `/tB/IDE/Projects` | Project Explorer (file and object views, Add, context menu, resource editors), references and packages (links to Features/Packages), Export Project (from Menu/File) |
+| 3a | Project Settings (reference) | `/tB/IDE/Project-Settings` | `Project Settings.md`, kept whole; **its anchors stay**, as 19 links use them |
+| 4 | Writing code | `/tB/IDE/Code` + children | Editor, Find/Replace, Outline, Open Editors, History, Diagnostics, `Features/Compiler-IDE/CodeLens` |
+| 5 | Designing forms and reports | `/tB/IDE/Forms`, `/tB/IDE/Reports` | tbForm, Toolbox, Properties, the Format menu's operations, tbReport |
+| 6 | Running and debugging | `/tB/IDE/Debugging` + children | Menu/Debug's run-time error walkthrough and Debugger Options, Menu/Run, Debug Console, Variables, Watches, Call Stack, Memory, `Features/Compiler-IDE/Debugging` |
+| 7 | Building | `/tB/IDE/Building` | Toolbar's Build configuration, Menu/File's Build and Clean, Package Publishing, links to LLVM and Project-Types |
+| 8 | Customising the IDE | `/tB/IDE/Customising/` + children (**written**) | IDE Options (all of them), themes and custom `.theme` files, panel layouts, keyboard shortcuts, language (from Menu/Window and Menu/Tools) |
+| 9 | Add-ins | `/tB/IDE/AddIns/` | AddIns/* as they are, Community given content |
+| 10 | When something goes wrong | `/tB/IDE/Troubleshooting` | Status Bar's service states, Restart the compiler, TRACE mode, error reporting |
+
+**Part B, Reference.** Written impersonally. One page per menu, plus the Toolbar, the Status Bar
+and the keyboard shortcuts, under `/tB/IDE/Reference/…`. Each entry gives the item, its
+shortcut, one or two sentences, and a link to the chapter that explains it.
+
+- The keymap is shown as a table, not the JSON dump `Menu/Window.md` holds now. The table can be
+  generated from `main.js` if keeping it by hand proves error-prone. Decide that when the page is
+  written.
+- Webpage and the other panes that are not in a chapter get a reference entry.
+
+**Moving pages.** When a page moves, its old permalink goes into `redirect_from:`, and every
+inbound link is changed to the new canonical URL. The 61 inbound links are in
+`Features/`, `Reference/`, `Tutorials/`, `LLVM/`, `Miscellaneous/FAQs.md`, `Documentation/`
+and `docs/index.md`. An anchor another page links to keeps its heading text.
+`redirect_from` cannot rescue an anchor, so check these:
+
+- `Project-Settings#…`;
+- `Window#language`, from `FAQs.md`.
+
+Where a merged page's pictures live does not change: `shoot_docs.mjs` writes them by path
+(`out`), so leave the files in `docs/IDE/Images/` and `Menu/Images/` and change only the links.
+
+**Features/Compiler-IDE** keeps a short "what's new compared to VB6" page that links into
+the chapters. The how-to sections of `IDE-Features.md`, `Debugging.md` and `CodeLens.md` move
+here, and those pages get `redirect_from` only if they are removed outright.
+
+**A landing page with children has a trailing slash** (`/tB/IDE/Customising/`, as
+`/tB/IDE/AddIns/`). Without the slash, the link check resolves `Customising#anchor` to the
+child folder.
+
+**Language names in a script the font subsets lack** (Cyrillic, Devanagari, Malayalam, CJK) are
+written in English only. The subsets cover Latin and Greek; see `scripts/build_fonts.py`.
+
+**Nav order.** The chapters take `nav_order` 1--10 in the order of the table above.
+`IDE Reference` has 99. The nav sorts numbered pages before unnumbered ones, so until a pane
+page is absorbed it sorts after the Reference.
+
+**The book.** `_book.yml`'s IDE part becomes Part A's chapters followed by Part B. A page leaves
+`left_out:` when it is finished, not before.
+
+## Conventions
+
+These apply across `docs/IDE/`. The first three also apply to any page that names the IDE's
+controls or keys, and `docs/Documentation/Authoring.md` (*Formatting conventions*) states them
+for contributors.
+
+- **UI names** in bold, as the IDE spells them: **Project Explorer**, **Break On All Errors**.
+- **Menu paths** in bold with an arrow: **File → Export Project**.
+- **Keys**: `<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd>`, with key names in mixed case and no
+  spaces around the `+`. Every key is written by name: `<kbd>Enter</kbd>`, `<kbd>F5</kbd>`,
+  `<kbd>Break</kbd>`, and arrows as `<kbd>Up</kbd>`, `<kbd>Down</kbd>`, `<kbd>Left</kbd>` and
+  `<kbd>Right</kbd>`. Glyphs are avoided, because the font subsets need not hold them. The 59 existing `<kbd>CTRL</kbd>`
+  are converted in one mechanical pass.
+- **Never re-list a picture's labels** (owner). The screenshots are SVGs whose text is
+  accessible, so a bare list of a menu's or dialog's items (label and keys, nothing else) only
+  repeats the picture. A reference entry says what the item does. An item with nothing to say
+  beyond its label is left to the picture.
+- **Headings** in sentence case, with no icon and no shortcut inside them.
+- **The section names no build**, except in a defect callout (owner's standing rule). Lines such
+  as "Components list coming soon" go, unless the IDE itself shows that text and the page says
+  so.
+- **Defects the twinBASIC developers already know of** (owner) are not queued, but a page that
+  describes the feature still carries the callout rule 6 calls for:
+  - Rename Symbol (<kbd>F2</kbd>) renames nothing;
+  - accepting a function from the completion list by typing `(` doubles the parenthesis
+    (`Area(()`).
+- Callouts follow WIP.md rule 6. A twinBASIC defect found while writing goes into
+  `BUGS-TO-REPORT.md` with a reproducer, never into a page alone.
+
+## Where the facts come from
+
+- **`<install>\ide\main.js`** (one line, about 1.3 MB). Search it with a Node script and
+  bounded regexes, never with `grep`, which takes minutes on one line. Useful landmarks, by
+  name, since offsets move between builds:
+  - `ideCommands`: every command id, such as `tbEditor_ClipboardPasteAsComment`, and its default
+    keys;
+  - `ideOptionsSchema`: the IDE Options, one flat list of about 30 options;
+  - `rootMenu…offsetHeight` blocks: the menus;
+  - `runningProcessesContainer`: the running programs, shown as **PROCESS** boxes in the
+    status bar (not in the Run menu);
+  - `createDropDowns`: the editor's three combo boxes;
+  - `showDesignerContextMenu`: the form designer's context menu;
+  - `tbFormDesigner_MenuEditor*`: the menu editor;
+  - `tbProblems_*`: Diagnostics;
+  - `reloadThemesFromDisk`: `.theme` files;
+  - `statusErrorsDiv` and `statusMemUsageDiv`: the status bar.
+- **The running IDE**, for behaviour the code does not show plainly. Use `Lane` from
+  `scripts/lib/tb-lane.mjs` on a private desktop, as `shoot_docs.mjs` setups do. Never use the
+  owner's IDE or the real `APPDATA`.
+- **`shoot_docs.mjs` and WIP.Screenshots.md** hold the states the screenshots already set up,
+  which are often the quickest way to reach a dialog. A new picture is a new shot there, taken
+  in both themes; never make a picture by hand.
+- The kit `.claude/tooling-review-scratch/beta995-probes/ide-driving-survey.md` (gitignored)
+  maps the debugger, Settings and Export internals.
+
+## Writing a chapter
+
+1. **Fact sheet.** A Sonnet agent reads `main.js` and the existing pages and writes
+   `.claude/tooling-review-scratch/ide-docs/<chapter>-facts.md`. Each item in it has its source,
+   a command id or a regex, and is marked *read* or *needs trying*.
+2. **Trying.** The *needs trying* items are tried in a lane IDE. Use an Opus agent, one at a
+   time, recording the registry hashes before and after as for any harness run.
+3. **Pictures.** New `shoot_docs` shots for what the chapter shows and no picture shows yet. Use
+   an Opus agent, then `--svg`.
+4. **Writing.** A Sonnet agent writes the pages from the fact sheet only, nothing from memory.
+5. **Review.** Read the diff against the fact sheet, then run `build.bat && check.bat`. Then move
+   the pages into the book part, run `book.bat`, and check the pages there.
+
+**Order**, by what readers need most:
+
+1. Customising (IDE Options)
+2. Writing code
+3. Running and debugging
+4. Forms and reports
+5. Projects and files
+6. Building
+7. Starting a project
+8. Troubleshooting
+9. Reference
+10. The tour
+
+The restructure comes first, in its own commit, before any chapter is written. It moves only
+the pages whose place in the new structure is settled:
+
+- Project Settings;
+- the menus, the Toolbar and the Status Bar, into Part B.
+
+It also sets up the nav and the book parts.
+
+A page that a chapter will absorb keeps its old URL until that chapter is written. The chapter
+then takes the old URL into its `redirect_from:`. That way nothing moves twice.
+
+## What the IDE has that no page covers yet
+
+From the survey of BETA 1005. Each chapter's fact sheet confirms the items in its own chapter.
+
+- **IDE Options:** all of them except Tab Size and the LLVM options. Examples are Intellisense
+  mode, the Handles/Implements syntax, Show Hidden Members, advanced hover, sticky scrolling,
+  Restore Editors State, the fonts, and the real OS title bar.
+- **Code editor:**
+  - the component, scope and procedure combo boxes, which also insert event handlers;
+  - Rename Symbol, Go To Definition and Last Position;
+  - bookmarks;
+  - the right-click menu and the tab context menu;
+  - Paste As Comment;
+  - Monaco's command palette and multi-cursor commands;
+  - automatic backups.
+- **Finding:** Find In Project, the Quick Find widget, Go To Line/Column.
+- **Form designer:** the menu editor, control arrays, locking, tab-index overlay, grid and zoom,
+  "Launch the form in isolation", Select Parent, the in-place toolbar, the context menu, and the
+  Toolbox's search, names toggle and "more components".
+- **Properties:** search, the system-colour picker, ActiveX property pages.
+- **Report designer:** everything beyond the list of bands and tools.
+- **Running:**
+  - the status bar's **PROCESS** boxes for running programs (Terminate, Bring To Front);
+  - **Run Or Preview** (<kbd>F6</kbd>);
+  - setting a breakpoint in the gutter, and whether breakpoints persist;
+  - Step Out (on the toolbar, not on the Debug menu).
+- **Diagnostics:** the four filter toggles and the context menu.
+- **Debug Console:** the copy commands in its context menu.
+- **Project Explorer:** the file context menu (Copy Path, View As JSON, View As Markdown Preview,
+  Export…), the object view, search, and the empty headings for each Add item.
+- **Packages:** the Available Packages tab, Import from file, the link and overwrite prompts, and
+  the "package needed" prompts for WinNativeForms and CustomControls.
+- **Status bar:** the error, warning, hint and info counters, and the memory figure.
+- **Themes:** custom `.theme` files in a `themes` folder.
+- **Webpage:** mobile mode, and back, forward and reload.
+- **Troubleshooting:** the DevTools command (`tbIdeDevTools_Show`, which has no menu item).
+- The **View → Object Browser** item does nothing; say so.
diff --git a/WIP.Screenshots.md b/WIP.Screenshots.md
@@ -181,9 +181,9 @@ Exit codes: 0 every picture written or unchanged, 1 a picture failed, 2 the tool
   page's `currentDPI` to the 2x ratio, or the IDE's 5 s DPI check covers every designer with
   RESYNC), and `forms` (the same without the add-in), `community` (the demo, its compiler
   restarted on an empty licence key in the page) and `splash` (the demo, for the splash
-  alone), `programs`, `codelens`, `package` and `fusion` (pictures of a running program),
+  alone), `programs`, `codelens`, `memory`, `package` and `fusion` (pictures of a running program),
   `package-server`, `settings-linked` and `package-check`, `import`, `webpage` and `web` (a
-  Chrome, not an IDE), `featuremap`, `customcontrols`, `code` and `sample9` (all described
+  Chrome, not an IDE), `featuremap`, `code-chapter`, `debugging`, `customcontrols`, `code` and `sample9` (all described
   below). A setup is `{name, start, prepare}`.
   Every add-in a setup loads has its `SaveSetting` key snapshotted, emptied and restored
   (`tbDocsHelp`, `GlobalSearchAddIn`).
@@ -249,6 +249,51 @@ scroll, advanced hover info, inline hints, folding always shown and the debugger
 are switched on in the page only; the memory figures, which change from run to run, are fixed in
 the page once real ones are shown, as History's times are.
 
+## The "Writing code" chapter
+
+Setup `code-chapter` (three parts): FeatureTour, the feature map's Inventory project, with
+`test/shots/codechapter/` staged onto it (`Helpers`, `Ev`/`Ev2`, `Watcher`) and the project's
+warnings set so that TB0016 is a hint and TB0012 information. Its 20 pictures are under
+`docs/IDE/Code/Images/`, plus `Menu_Edit` and `Menu_View`, now taken with the code focused.
+
+- **Each picture starts from the default layout and its own tabs** (`chapterTabs`), and closes
+  Monaco's find widget first: the editor is one for every file, so a widget left open shows over
+  the next file's code.
+- **The minimap is left out of every crop but Editor_Panel**: it is drawn a little differently
+  according to what the editor showed before, so a crop with it changes with the shots' order.
+- **A tab is tinted only when the compiler sends the file's diagnostics while it is open**, not
+  when it opens on a file already reported: Tabs_States edits Inventory and undoes it.
+- Edits are made in the page and undone (`editedThenUndone`) or discarded with their tab; the
+  clipboard is the tool's own text (`FAKE_CLIPBOARD`), never the host's.
+
+## The "Running and debugging" chapter
+
+Setup `debugging` (three parts): the code-chapter project with `test/shots/debugging/`
+staged onto it as well, a module `Checks` with the chapter's `FillTable` (a Subscript error on
+its fourth pass), `PingLater` (`Shell "ping -n 20 127.0.0.1", vbHide`) and `WaitAWhile` (a
+`DoEvents` loop of a minute at most). It is a setup of its own because the code chapter's
+combo boxes list the project's modules. Its 16 pictures are under `docs/IDE/Debugging/Images/`,
+plus `Menu_Debug` (paused, the code focused) and `Menu_Run` (WaitAWhile running).
+
+- **Each picture starts from nothing** (`debugReset`: the program stopped, no breakpoint, no
+  watch, no tab, the default layout, an empty DEBUG CONSOLE) and leaves the IDE so. Most stop
+  `Main` in `Inventory.Total` at the loop line (`pausedInTotal`, first or second pass);
+  `pausedInMain` stops it on Main's last line.
+- **What changes from run to run is set in the page before the capture**: an object's
+  `{object: N}` (`OBJECT_ADDRESS`), the Variables tooltip's `Pointer` (`POINTER_TEXT`), the
+  PROCESS box's id (`PROCESS_ID`), and the console's times and `time taken` (`fixConsoleTimes`).
+- **The ping ends with the run**: the box's own Terminate, else `killTree` on the id the console
+  printed (`endPing`).
+- A tree row is expanded with a click on its plus box, made again until the flip holds
+  (`toggleRow`); the Variables edit box opens with a double-click made again the same way.
+- The Variables tooltip is taken with the panel docked (a floating panel is drawn over it), once
+  it has the class `visibleTooltip` and its fade has ended: before that it is laid out, hidden,
+  at another place.
+- The DEBUG CONSOLE is never cut out: a cut-out shows the line it measures text with. Its menu
+  is opened inside the panel instead.
+- A line for the console is put in its input row whole and entered (`consoleRun`): a space typed
+  while the row's completion list is open accepts the list's first entry.
+
 ## Special IDE states
 
 - **`Services_Unavailable`**: the badge in the `no-project` setup. With no project the badge's
@@ -353,6 +398,13 @@ the page once real ones are shown, as History's times are.
   line times (the page's clock for some lines, the compiler's for `Debug.Print`) and the time
   taken are set in the page once shown. `Scale factor` prints what the lane's compiler reads,
   1.50 on this machine.
+- **`Memory_String`** (setup `memory`, `test/shots/memory`, MemoryDemo): Sub Main run with
+  Start to its `Stop`, the MEMORY 1 pane floated and sized to two rows, `s` typed into its box,
+  which the IDE turns into `StrPtr(s)`; the fifteen characters and their terminating null fill
+  the two rows, so no other memory shows. The string's address changes from run to run and is
+  set in the page once the rows are read (`MEMORY_ADDRESSES`). The box can already read
+  `StrPtr(s)` from the theme before, so the shot waits for the cell at the address to take the
+  focus, which happens only once the rows are drawn for the new answer, and then blurs it.
 - **`Toolbar_4`**: setup `designer`, the sample run with Start (`context.codeExecuting`) and
   stopped after.
 - **`8d74d820`** (setup `package`) and **Fusion's `569099635`** (setup `fusion`): the paths the

diff --git a/WIP.md b/WIP.md
@@ -12,6 +12,7 @@ one covering what you are about to change.
 | About to | Read first |
 |---|---|
 | write or edit any page under `docs/` | [WIP.Authoring.md](WIP.Authoring.md) --- page template, frontmatter, cross-section linking tables, per-symbol workflow |
+| write or restructure a page under `docs/IDE/` | [WIP.IDE.md](WIP.IDE.md) --- the plan for finishing the IDE section: its structure, conventions, fact sources and chapter workflow |
 | document a specific package | that package's own file, listed under [Package API notes](#package-api-notes) |
 | run or change the twinBASIC compiler harness | [WIP.Harness.md](WIP.Harness.md) --- `export`, the attribute census, `tbbuild`, `tbrun`, the add-in test runner |
 | change `builder/`, `scripts/`, or any gate | [WIP.Build.md](WIP.Build.md) --- the pipeline and why each gate exists |

diff --git a/bugs/compile-error-reported-as-codegen/repro.json b/bugs/compile-error-reported-as-codegen/repro.json
@@ -0,0 +1,8 @@
+{
+  "mode": "lane",
+  "lane": "ide:debugging",
+  "tests": [
+    "a compile error in a procedure Main calls is reported at F5 as a codegen error to report, at Main's call"
+  ],
+  "steps": "1. A Sub Main whose line 7 calls Direct. Add the line x = = 1 to Direct; the editor marks it as an error.\n2. Press F5. The DEBUG CONSOLE prints [LINKER] compilation (codegen) error detected in 'Startup.Main' at line #7, and the run stops on Main's Sub line with a panel headed ERROR OCCURRED: COMPILATION (CODEGEN) ERROR AT LINE #7.  PLEASE REPORT THIS ERROR TO https://git.io/JMh6S. Nothing of Main runs."
+}