Update documentation for features added since 0.8.0

Document the verify/run simulator integration, three-scope column
alignment with grid-array exclusions, well/group name completion,
boilerplate completion, and diagnostic quick fixes across the
extension README, DEVELOPMENT, and the demo video script.

- README: add formatting settings entry and Unreleased release notes
- DEVELOPMENT: refresh src module layout, builder test, build/sync scripts
- VIDEO-SCRIPT: add verify/run/PRT clip plus quick-fix and snippet takes

Author: magnesj

DEVELOPMENT.md

@@ -9,9 +9,27 @@ opm-flow-editor-support/
 │                            #   opm/input/eclipse/share/keywords)
 ├── scripts/                 # keyword-index builder (Python)
 │   ├── build_keyword_index.py
+│   ├── test_build_keyword_index.py   # pytest suite for the builder
 │   └── requirements.txt
+├── demo-decks/              # runnable sample decks + VIDEO-SCRIPT.md walkthrough
+├── examples/                # small decks illustrating single features
 └── vscode-extension/        # the VS Code extension
-    ├── src/extension.ts
+    ├── src/
+    │   ├── extension.ts          # activation, command + provider wiring
+    │   ├── analysis.ts           # deck parsing + diagnostics engine
+    │   ├── boilerplate.ts        # keyword-completion snippet bodies
+    │   ├── names.ts              # well/group name harvesting (WELSPECS/GRUPTREE)
+    │   ├── udq.ts                # UDQ / ACTIONX recognition + metadata
+    │   ├── formatting.ts         # Align Record Columns / Add Column Headers
+    │   ├── align-exclusions.ts   # keywords skipped by the deck-wide align sweep
+    │   ├── diagnostics-exclusions.ts
+    │   ├── keyword-supplement.ts # deck-name alias / family resolution
+    │   ├── links.ts              # INCLUDE/IMPORT/RESTART/GDFILE file links
+    │   ├── paths.ts              # PATHS alias expansion + path resolution
+    │   ├── outline.ts            # section/keyword tree view
+    │   ├── simulator.ts          # Verify Deck / Run Simulation (optional)
+    │   └── *.test.ts             # Jest unit tests, one per module
+    ├── scripts/sync-manual-ref.js    # stamps the manual commit into README
     ├── syntaxes/opm-flow.tmLanguage.json
     ├── language-configuration.json
     ├── data/keyword_index_compact.json
@@ -62,6 +80,14 @@ npm test               # all unit tests
 npx jest analysis      # a single suite
 ```
 
+The Python keyword-index builder has its own pytest suite:
+
+```sh
+cd scripts
+pip install -r requirements.txt
+python -m pytest test_build_keyword_index.py
+```
+
 ### Corpus false-positive harness
 
 `src/corpus.test.ts` runs the diagnostics engine over the
@@ -98,6 +124,18 @@ python build_keyword_index.py \
     --compact ../vscode-extension/data/keyword_index_compact.json
 ```
 
+Or run the wrapper from the extension, which writes the compact index in place:
+
+```sh
+cd vscode-extension
+npm run build-index
+```
+
+`vscode-extension/README.md` carries the manual commit it was built from inside a
+`<!-- manual-ref:start -->` marker. `npm run sync-manual-ref` (also part of
+`vscode:prepublish`) stamps the current `opm-reference-manual` submodule commit
+into that marker, so the listing always shows the data revision being shipped.
+
 ## Release
 
 Releases are tag-driven. On pushing a `v*` tag, CI:

demo-decks/README.md

@@ -10,7 +10,7 @@ without any external files.
 
 | Folder | Deck | Feature focus |
 |--------|------|---------------|
-| `01-spe1-basics/`        | `SPE1CASE1.DATA`   | Highlighting, section/keyword folding, hover, diagnostics, completion, **Align Record Columns**, **Add Column Headers**, docs sidebar, Generate Keyword Reference |
+| `01-spe1-basics/`        | `SPE1CASE1.DATA`   | Highlighting, section/keyword folding, hover, diagnostics + quick fixes, completion (boilerplate snippets), **Align Record Columns**, **Add Column Headers**, docs sidebar, Generate Keyword Reference, **Verify Deck** / **Run Simulation** + **Open PRT File** |
 | `02-udq-actionx/`        | `UDQ_WCONPROD.DATA`, `ACTIONX_M1.DATA` | UDQ three-column alignment, UDQ/ACTIONX recognition + hover, value completion |
 | `03-includes-and-names/` | `TEST1_WS.DATA`    | `Ctrl+click` `INCLUDE` navigation, well/group-name completion from `WELSPECS`/`GRUPTREE` |
 | `04-msw-multirecord/`    | `MSW-SIMPLE.DATA`  | Multi-record keyword hover (`WELSEGS`/`COMPSEGS`), per-record **Add Column Headers**, `PATHS` alias navigation |

demo-decks/VIDEO-SCRIPT.md

@@ -13,6 +13,11 @@ be trimmed and reordered later.
 4. Recommended look: a dark theme, editor font ~16 px, zoom level +1
    (`Ctrl+=` once), minimap off, breadcrumbs on.
 5. Hide personal panels; keep the Explorer visible on the left.
+6. *(Only for Clip 6 — running the simulator.)* Install OPM Flow and point the
+   extension at it in Settings: set `opm-flow.simulator.executablePath`. On
+   Windows, enable `opm-flow.simulator.useWsl` and use the Linux path (e.g.
+   `/usr/bin/flow`), optionally setting `opm-flow.simulator.wslDistribution`.
+   Verify it works once off-camera so the first on-camera run is clean.
 
 Pacing tips: move the cursor deliberately, pause ~1 s on each tooltip so it is
 readable, and let folds/alignments settle before cutting.
@@ -45,13 +50,17 @@ readable, and let folds/alignments settle before cutting.
 
 - **Take 5 — Completion.** At the end of `SCHEDULE`, on a new line in column 1,
   type `WCON` — the keyword completion list appears with sections and one-line
-  summaries. Then inside a fresh `COMPDAT` record, at the STATUS column, trigger
-  completion to show the value list (`OPEN` / `SHUT` / `AUTO`). *(Undo any typing
-  before the next take with `Ctrl+Z`.)*
+  summaries. Accept `WCONPROD`: it inserts a **boilerplate record** as a
+  tab-navigable snippet (documented defaults / typed placeholders, terminated to
+  match the keyword's shape). `Tab` through a couple of placeholders to show they
+  overwrite cleanly. Then inside a fresh `COMPDAT` record, at the STATUS column,
+  trigger completion to show the value list (`OPEN` / `SHUT` / `AUTO`). *(Undo any
+  typing before the next take with `Ctrl+Z`.)*
 
 - **Take 6 — Align Record Columns.** Put the cursor inside the `SWOF` table (or
-  the `WELSPECS` block). Run **OPM Flow: Align Record Columns** from the Command
-  Palette (`Ctrl+Shift+P`). Columns snap into alignment. Show the before/after.
+  the `WELSPECS` block). Run **OPM Flow: Align Record Columns in Record** from the
+  Command Palette (`Ctrl+Shift+P`). Columns snap into alignment. Show the
+  before/after. *(Mention the companion **… in File** and **… in Deck** scopes.)*
 
 - **Take 7 — Add Column Headers.** With the cursor in the `COMPDAT` block, run
   **OPM Flow: Add Column Headers**. A `--` comment with parameter names is
@@ -83,6 +92,13 @@ camera, then `Ctrl+Z` each one back.
 - **Take 5 — Missing terminator.** Delete the trailing `/` on a `WELSPECS`
   record. Squiggle flags the missing per-record `/`.
 
+- **Take 6 — Quick Fixes.** Re-create one of the fixable mistakes above (e.g.
+  lowercase `compdat`, or an indented `WCONPROD`, or the missing `/`). Place the
+  cursor on the squiggle, open the lightbulb (`Ctrl+.`), and apply the offered
+  fix — **Convert to uppercase** / **Move keyword to column 1** / **Add
+  terminating `/`**. For an unknown keyword like `EQLDIM`, show the **Replace with
+  `EQLDIMS`** fix substituting the nearest known keyword.
+
 Undo everything so the file is clean for the next session.
 
 ---
@@ -93,7 +109,7 @@ Undo everything so the file is clean for the next session.
 
 - **Take 1 — UDQ alignment (`UDQ_WCONPROD.DATA`, `UDQ` block ~line 349).**
   Show the `UDQ` block with `DEFINE … / UNITS …` statements slightly ragged.
-  Run **OPM Flow: Align Record Columns**. The dedicated three-column layout
+  Run **OPM Flow: Align Record Columns in Record**. The dedicated three-column layout
   appears: control word and variable name left-aligned, expression right-aligned
   so every terminating `/` lines up. Point out that a `/` used as division inside
   an expression is **not** mistaken for the terminator.
@@ -150,8 +166,33 @@ Undo everything so the file is clean for the next session.
   record the group belongs to (e.g. `ISEG1`, `ISEG2`, …). Repeat in the
   `COMPSEGS` block (~line 479) to show it adapts per keyword.
 
-- **Take 4 — Align the segment table.** Run **Align Record Columns** on the
-  `WELSEGS` segment block to tidy the long numeric rows.
+- **Take 4 — Align the segment table.** Run **Align Record Columns in Record** on
+  the `WELSEGS` segment block to tidy the long numeric rows.
+
+---
+
+## Clip 6 — Verify & run the simulation (file `01-spe1-basics/SPE1CASE1.DATA`)
+
+**Goal:** show that you can check and run a deck with OPM Flow without leaving the
+editor. *(Requires the off-camera simulator setup — step 6 above.)* SPE1 is the
+small SPE benchmark case, so a full run finishes in seconds on camera.
+
+- **Take 1 — Verify Deck (dry run).** With `SPE1CASE1.DATA` open, run **OPM Flow:
+  Verify Deck (dry run)** from the right-click menu (or Command Palette). An
+  integrated terminal opens in the deck's folder and `flow` parses and
+  initializes the model in dry-run mode — no time steps. Point out this is the
+  fast check that the deck and everything it pulls in via `INCLUDE` / `PATHS`
+  loads cleanly. *(On Windows, note the path was translated to its `/mnt/...`
+  WSL mount automatically.)*
+
+- **Take 2 — Run Simulation.** Run **OPM Flow: Run Simulation**. The same
+  terminal streams the live solver output to completion. Let the report counters
+  tick to the end of the run.
+
+- **Take 3 — Open the PRT output.** Run **OPM Flow: Open PRT File** (or
+  `Ctrl+Alt+P`). The `SPE1CASE1.PRT` print file that the run just produced opens
+  next to the deck. Scroll briefly to show the run summary. *(Good closing shot —
+  "edit, verify, run, inspect, all in one place".)*
 
 ---
 
@@ -166,4 +207,6 @@ Undo everything so the file is clean for the next session.
 7. `Ctrl+click` INCLUDE jump (Clip 4 / Take 1).
 8. Well-name completion list (Clip 4 / Take 2).
 9. WELSEGS per-record headers (Clip 5 / Take 3).
-10. Close on Generate Keyword Reference (Clip 1 / Take 8).
+10. Verify Deck dry-run in the terminal (Clip 6 / Take 1).
+11. Run Simulation to completion → Open PRT File (Clip 6 / Takes 2–3).
+12. Close on Generate Keyword Reference (Clip 1 / Take 8).

vscode-extension/README.md

@@ -379,6 +379,12 @@ you can override them per-workspace or per-folder.
 | --- | --- | --- |
 | `opm-flow.additionalFileExtensions` | `[]` | Extra file extensions (with or without a leading `.`) to open as OPM Flow on top of the built-in list. Useful for project-specific include-file conventions. Matched case-insensitively. Example: `[".myinc", "wellconv"]`. For one-off cases the VS Code-native `files.associations` setting still works too. |
 
+### Formatting
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `opm-flow.formatting.alignColumnsExcludedKeywords` | `[]` | Extra keywords to skip when aligning record columns. Names are upper-cased on read; matching is case-insensitive. Honoured by all three [Align Record Columns](#align-record-columns) commands, and *added* to the built-in deck-sweep defaults (per-cell grid/region arrays like `PORO`/`PERMX`/`COORD` and large `VFPPROD`/`VFPINJ` tables, which **Align … in Deck** already skips). |
+
 ### Simulator
 
 Optional integration for the [Verify and Run](#verify-and-run-the-simulation-optional)
@@ -451,6 +457,20 @@ The language is registered as `opm-flow`.
 
 ### Unreleased
 
+- **Align Record Columns at three scopes** — the alignment command is now split
+  into **Align Record Columns in Record** (the group under the cursor), **… in
+  File** (the whole document, or the selection), and **… in Deck** (follows the
+  `INCLUDE` chain, resolving `PATHS` aliases, and aligns every reachable file,
+  reporting the line/file counts). The deck sweep skips per-cell grid/region
+  arrays (`PORO`, `PERMX`, `COORD`, …) and large `VFPPROD`/`VFPINJ` tables by
+  default so `INCLUDE`d fixed-width files are not rewritten; the new
+  `opm-flow.formatting.alignColumnsExcludedKeywords` setting adds further
+  keywords to skip (honoured by all three commands).
+- **Well / group name completion** — in a well- or group-name column (the
+  opm-common `WELL`/`GROUP` item family — `WCONPROD`, `WELOPEN`, `GCONPROD`,
+  `WEFAC`, …) the suggestion list offers the names the deck already declares:
+  well names from `WELSPECS`, and group names from `WELSPECS` and `GRUPTREE`,
+  gathered across the whole file.
 - **Verify and run the simulation (optional)** — new **OPM Flow: Verify Deck
   (dry run)** and **OPM Flow: Run Simulation** commands launch a locally
   installed `flow` binary on the open deck in an integrated terminal. Verify uses