docs(help): parse-tree help page and graphic announcement

Help/markdown/vscode/announcements/2026-07-26-parse-tree-graphic.md

@@ -0,0 +1,88 @@
+# 📢 Announcement — See Your Parse Tree
+
+![NLP++ parse-tree graphic](ParseTreeGraphic.png)
+
+**Every `.tree` file your analyzer writes can now be drawn as a classic linguistic tree
+diagram** — right inside VS Code, beside the text file it came from.
+
+NLP++ has always given you the parse tree as text: one indented line per node, with its
+span and type. That's precise, and it's still there. But a tree is a *picture*, and now you
+can see it as one — phrases branching over their words, exactly the way a linguist would
+draw it on a whiteboard.
+
+---
+
+## Opening the graphic
+
+From any `.tree` file:
+
+- 🌲 **The tree button** in the editor title bar — draws the whole tree.
+- 🖱️ **Right-click → Graph Entire Tree** — the same thing, from the context menu.
+- 🖱️ **Right-click → Graph Selected Portion of Tree** — draws just the **selected lines**,
+  or, with nothing selected, the **subtree under your cursor**. Perfect for looking at one
+  noun phrase in a 400-node tree.
+
+The graphic is strictly on-demand: opening a `.tree` file never draws anything on its own,
+so tree files still open instantly. And it re-uses a single panel, so asking for another
+tree replaces the one you're looking at instead of piling up tabs.
+
+---
+
+## Getting around the tree
+
+The whole diagram is live. The hint bar along the bottom sums it up, but here it is in full:
+
+| Do this | Get this |
+| --- | --- |
+| **Scroll** | Zoom in and out |
+| **Shift + scroll** | Squeeze or spread the horizontal spacing between nodes |
+| **Drag** | Pan around the canvas |
+| **Click a phrase node** | Open **one level** — just that node's children |
+| **Click a word (leaf)** | **Reveal it in the text** — selects that word in the input file |
+| **Right-click** | Menu (below) |
+
+Trees open with the root expanded and everything else closed, so you **drill down one node
+at a time** rather than being hit with hundreds of tokens at once. Small trees (roughly 30
+nodes or fewer) open fully, and every tree is fit to the window when it opens.
+
+Labels don't collide, either: at **every level** of the tree, labels that would overlap are
+staggered into the minimum number of extra rows needed — and they drop back onto a single
+line as soon as they fit, or as soon as you spread the tree out with Shift + scroll.
+
+---
+
+## The right-click menu
+
+Right-click anywhere in the graphic:
+
+- **Reveal Text** — on **any** node, word or phrase. Selects that node's whole span in the
+  analyzed text file. Right-click an `_np` and the entire noun phrase lights up.
+- **Expand all below** / **Collapse all below** — open or close an entire subtree at once
+  (shown on nodes that have children).
+- **Center all** — fit the whole tree back into the window.
+- **Expand all** / **Collapse all** — open or close the entire tree.
+
+---
+
+## The text `.tree` file still does everything it did
+
+The graphic is an *alternative* view, not a replacement. In the `.tree` file itself, put
+your cursor on **any node line** and right-click:
+
+- **Highlight text** — selects that node's text in the input file and opens it beside the
+  tree. Works on any node, at any depth — click a phrase node and you highlight the whole
+  phrase; click a word and you highlight the word.
+- **Display Rule Fired** — opens the pass that built the node and jumps straight to the rule
+  that fired (for nodes that came from a dictionary, it searches the dictionaries instead).
+- **Generate @PATH** — writes the context `@PATH` for that node, ready to paste into a rule.
+- **Open Pass File** — jumps to the pass that produced this tree.
+- **Fold / Unfold** (all, or recursively) — collapse the text tree the same way you collapse
+  the graphic.
+
+Between the two views you get both halves of the picture: the graphic for *shape* — how the
+parse actually came together — and the text file for *detail*, the spans, the rules, and the
+paths you need when you sit down to write the next rule.
+
+**Read the full guide:** [Parse Trees](../parsetrees.md)
+
+_See more on the [Help home](../home.md)._

Help/markdown/vscode/home.md

@@ -32,6 +32,7 @@ the logic is human-written code you can read, [test](testing.md), and ship.
 
 - **[Quick Start](quickstart.md)** — install the engine, create or open an analyzer, and run it over text.
 - **Claude Prompts** — let Claude help you build a prototype analyzer. The Help view lists several ready-to-paste prompts, one per task; choose the one you need and it opens with your machine's engine and analyzer paths already filled in. Start with [**General pointers: Claude + NLP++**](prompts/00-general-pointers.md) for an overview of the library.
+- **[Parse Trees](parsetrees.md)** — read the `.tree` files your passes produce, and draw any tree as a linguistic diagram you can zoom, drill into, and click back into the text.
 - **[Calling Analyzers from Python & Node.js](packages.md)** — drive an analyzer from your own code with the `NLPPlus` (PyPI) / `nlpplus` (npm) packages: pass data in, get results back.
 - **[Compiling Analyzers](compiling.md)** — turn an analyzer (and/or its knowledge base) into a fast compiled C++ library.
 - **[Regression Testing](testing.md)** — set up golden-file regression tests so you catch changes in your analyzer's output.

Help/markdown/vscode/parsetrees.md

@@ -0,0 +1,122 @@
+# Parse Trees
+
+Every pass of an NLP++ analyzer writes out the **parse tree** as it stood when that pass
+finished. Those trees are how you see what your rules actually did — which phrases got
+built, out of which words, by which rule.
+
+The extension gives you **two views of the same tree**: the `.tree` **text file**, which
+carries all the detail, and the **parse-tree graphic**, which draws it as a classic
+linguistic tree diagram.
+
+[← Back to Help home](home.md)
+
+![NLP++ parse-tree graphic](announcements/ParseTreeGraphic.png)
+
+## Where the trees are
+
+When you analyze a text file, the engine writes a log folder next to it — `MyText.txt_log/`
+— containing one `.tree` file per pass (`ana001.tree`, `ana002.tree`, …) plus `final.tree`
+for the finished parse.
+
+You can open them from the file tree, or:
+
+- **Analyzer Sequence view** → right-click a pass → **Open Tree file** — the tree as of that pass.
+- **Display Final Tree** (`Ctrl+Shift+F` / `Cmd+Shift+F` in a pass file) — the finished parse.
+- **Display Pass Tree** (`Ctrl+Shift+T` / `Cmd+Shift+T` in a pass file) — the tree for the pass you're editing.
+- **View selected tree** — right-click a selection in a text file to see just that portion.
+
+## Reading the text tree
+
+A `.tree` file is an indented list. Indent depth is the hierarchy, and each line is a node:
+
+```
+_ROOT [0,1429,0,1429,0,0,node,un]
+   _paragraph [0,342,0,342,6,12,node,un]
+      _sentence [0,183,0,183,5,24,node,un, ("name" "sentence1")]
+         _city [0,10,0,10,8,13,node]
+            LOS [0,2,0,2,0,0,alpha]
+```
+
+The label comes first, then the bracketed fields: the node's **character span** in the
+text (`start,end`), the same span in the unnormalized text, the **pass number** and
+**rule line** that built it, and the node **type** (`node`, `alpha`, `white`, …). Any
+attributes the node carries follow in parentheses.
+
+## What you can do from the text tree
+
+Put your cursor on **any node line** — a word or a phrase, at any depth — and right-click:
+
+- **Highlight text** — selects that node's span in the analyzed text file and opens it
+  beside the tree. On a phrase node you get the whole phrase; on a word, the word.
+- **Display Rule Fired** — opens the pass that built the node and jumps straight to the
+  rule that fired. For nodes that came out of a dictionary, it searches the dictionaries
+  instead.
+- **Generate @PATH** — writes the context `@PATH` for that node, ready to paste into a rule.
+- **Open Pass File** — opens the pass this tree came from.
+- **Fold All** (`Ctrl+Shift+F`) / **Unfold All** (`Ctrl+Shift+U`), and fold/unfold
+  recursively — collapse the tree text to the level you care about.
+
+## The parse-tree graphic
+
+From any `.tree` file:
+
+- 🌲 **The tree button** in the editor title bar — draws the whole tree.
+- 🖱️ **Right-click → Graph Entire Tree** — the same, from the context menu.
+- 🖱️ **Right-click → Graph Selected Portion of Tree** — draws just the **selected lines**,
+  or, with nothing selected, the **subtree under the cursor**. Use this to look at one
+  phrase inside a large tree.
+
+The graphic is **on-demand only**: opening a `.tree` file never draws anything by itself,
+so tree files open instantly. It re-uses a single panel, so graphing another tree replaces
+the one on screen rather than opening more tabs.
+
+### Getting around
+
+| Do this | Get this |
+| --- | --- |
+| **Scroll** | Zoom in and out |
+| **Shift + scroll** | Squeeze or spread the horizontal spacing between nodes |
+| **Drag** | Pan around the canvas |
+| **Click a phrase node** | Open **one level** — just that node's children |
+| **Click a word (leaf)** | Reveal it in the text — selects that word in the input file |
+| **Right-click** | Menu (below) |
+
+A tree opens fit to the window with the **root expanded and everything else closed**, so
+you drill down one node at a time instead of facing hundreds of tokens at once. Small
+trees (roughly 30 nodes or fewer) open fully.
+
+Labels never pile up on each other: at every level, labels that would overlap are staggered
+into the fewest extra rows needed, and they drop back onto one line as soon as they fit —
+or as soon as you spread the tree out with Shift + scroll.
+
+### The right-click menu
+
+- **Reveal Text** — on **any** node, word or phrase. Selects that node's whole span in the
+  analyzed text file. Right-click an `_np` and the entire noun phrase lights up.
+- **Expand all below** / **Collapse all below** — open or close a whole subtree at once
+  (offered on nodes that have children).
+- **Center all** — fit the whole tree back into the window.
+- **Expand all** / **Collapse all** — open or close the entire tree.
+
+Whitespace tokens and the pass banners at the top of the file are left out of the graphic,
+so what you see is the linguistic structure.
+
+## Working with both views
+
+The two views answer different questions, and they're best used together:
+
+- **The graphic** shows you **shape** — how the parse came together, where a phrase
+  attached, what got left flat.
+- **The text tree** shows you **detail** — the spans, the attributes, the pass and rule
+  that built each node, and the `@PATH` you need to write the next rule.
+
+A common loop: graph the tree, drill down until you find the node that's wrong, right-click
+**Reveal Text** to confirm what it covers, then go back to the `.tree` file and use
+**Display Rule Fired** on that same node to land on the rule that needs fixing.
+
+## See also
+
+- **[Quick Start](quickstart.md)** — create or open an analyzer and run it over text.
+- **[Node / Parse Tree Functions](../Table_of_Parse_Tree_Functions.md)** — the NLP++ functions that read and change the tree from inside a rule.
+- **[About Parse Trees](../VisualText_Basics/About_Parse_Trees.md)** — the concept behind the tree.
+- **[Regression Testing](testing.md)** — lock in the output once the tree looks right.