docs: document DEF block templates, addresses, and formatting changes

Update the README and CHANGELOG to describe newly documented language-server behaviors and editor UX details.

- Read BLOCK_TEMPLATE and ADDRESS names from .def files listed under <DefinedEvents> in PSC layers and refresh on PSC/DEF changes; completion suggestions for MOM_do_template, MOM_ask_address_value, MOM_force, and MOM_suppress
- Insert quoted block templates/addresses and Always|Once|Off modes (replace auto-closed/typed quotes instead of doubling) and insert variables with a leading `$`
- Add BLOCK_LIST and ADDR_LIST completion keywords to list all loaded block templates or addresses
- Document formatting/linting of uplevel bodies as Tcl and normalization of comment spacing (#Comment → # Comment) while preserving ##, #!, and already spaced comments
- Note that the Python debug bootstrap now stops with a clear error instead of hanging when no debugpy listener or only a stale one is available

These changes are reflected under "Unreleased" in the changelog and in the README section about DEF block templates and addresses.

README.md

@@ -14,6 +14,7 @@ A comprehensive VS Code extension providing language support and remote debuggin
 - **Document Highlights** - Highlights all reads, writes, and calls of the symbol under the cursor
 - **Context-aware Completion** - Prioritizes local symbols and suggests variables, procedures, namespaces, paths, Tcl subcommands, valid argument values, and options based on cursor context
 - **PSC and TclOO Classes** - Indexes Tcl scripts referenced by PSC layers, including external folders. Classes from indexed files provide method completion, signature help, parameter hints, and class highlighting in other files. PSC script names may omit `.tcl`; relative folders resolve from the PSC directory, and environment-variable folders are supported. Missing scripts are reported in the output channel; encrypted libraries cannot supply static class metadata.
+- **DEF Block Templates and Addresses** - Reads the `.def` files listed under `<DefinedEvents>` in PSC layers and suggests their `BLOCK_TEMPLATE` and `ADDRESS` names, see [DEF block templates and addresses](#def-block-templates-and-addresses)
 - **Tcl Snippets** - Inserts placeholder-based structures for `if`, `foreach`, `proc`, `switch`, `try`, and `dict for`
 - **NX Tcl Remote Debugger** - Breakpoints, stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops directly in a running NX Post process
 
@@ -48,6 +49,32 @@ TCL files default to unlimited inlay hint length so that VS Code does not
 truncate later parameter names on a line. An explicit user setting for
 `editor.inlayHints.maximumLength` still takes precedence.
 
+## DEF Block Templates and Addresses
+
+The language server resolves the `.def` files of every PSC layer's `<DefinedEvents>` section the
+same way as layer scripts (relative to the PSC, `SubFolder`, environment variables, missing `.def`
+extension) and collects all `BLOCK_TEMPLATE` and `ADDRESS` declarations. Changes to PSC or DEF files
+are picked up automatically.
+
+| Command | Suggestions |
+|---|---|
+| `MOM_do_template` | Block templates, then variables |
+| `MOM_ask_address_value` | Addresses, then variables |
+| `MOM_force`, `MOM_suppress` | 1st argument: `Always`, `Once`, `Off`, then variables; further arguments: addresses, then variables |
+
+Block templates, addresses, and `Always|Once|Off` are inserted in quotes (`"steady_rest"`); a quote
+that is already typed or auto-closed is replaced instead of doubled. Variables are inserted with a
+leading `$`. Typing `$` yourself still shows variables only.
+
+Two keywords list all loaded names anywhere in a Tcl file:
+
+- `BLOCK_LIST` - shows all block templates
+- `ADDR_LIST` - shows all addresses
+
+Select the keyword from the completion list (or type it completely) to open the list; text typed
+directly after the keyword, such as `ADDR_LISTSP`, narrows it. The keyword is replaced by the
+selected quoted name.
+
 ## NX Tcl Remote Debugger
 
 ### Add a VS Code attach configuration
@@ -98,13 +125,14 @@ Simply open any supported file type and enjoy:
 - Syntax highlighting
 - Error detection and linting
 - Code completion
-- Code formatting (Format Document command)
+- Code formatting (Format Document command), including `uplevel` bodies and a space after `#` in comments
 - Hover information
 - Signature help while entering procedure arguments
 - Incoming and outgoing call hierarchy for custom procedures and MOM event handlers
 - Document-wide highlights for procedure and variable occurrences
 - Context-aware completion with local symbols ranked before workspace and built-in symbols, plus semantic arguments, local paths, Tcl subcommands, and options such as `string compare -nocase`
 - Placeholder-based snippets for common Tcl control structures and procedures
+- Block template and address suggestions from PSC DEF files, including `BLOCK_LIST` and `ADDR_LIST`
 - Remote NX Tcl debugging with breakpoints and full stepping
 
 ## Contributing