From c6bf58dd7a147f4f3e34cfabd7bc4902f401abc7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 04:34:00 +0000
Subject: [PATCH 1/4] fix(core,server,app): what clicking through the seven
 reading features found
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A pass over the real app under Xvfb, by mouse, on the clew repo and a
small Python project, turned up these; each is fixed and tested.

- Churn: the most-changed list counted files deleted or renamed since, and
  a click on one reported a missing path. `git::churn` keeps the files
  that exist under the root now.
- Type map: a name resolved to the first type of that name in the project,
  so `impl Platform for Native` drew an edge to an enum, std's `Read` one
  to a type alias inside a function, and `Value` everywhere one to the
  first `Value`. A name now resolves within its language, to a kind it can
  mean (a Rust impl names a trait), in the same file, then the same
  folder, else not at all. Types local to a function are no nodes, and a
  Rust `type` inside an `impl` is listed as an associated type (it has a
  container now) rather than as a module's type.
- Value trace: following a value into a callee read one line of the
  declaration and took the first `(` on it — `pub(crate)`'s — so a
  wrapped parameter list, or any `pub(crate) fn`, could not be followed.
  It reads the declaration from the name on, over up to 32 lines. Lines
  read off disk were trimmed while the server's columns are on the raw
  line, so closed files were classified at the wrong column, and the
  callee's column was shifted twice for open ones: lines are raw now and
  each node keeps its indentation. `return f(x)` is "passed to f", not
  "returned"; `print(x)` is a call; `x += …` is an assignment even where
  the server lists it as a definition. When a traced file changes, each
  occurrence follows its line by its text; a line gone is marked changed
  and the tab offers to trace again — rows used to jump to stale lines.
- Ask's `changes` tool ignored uncommitted edits: asked what the work in
  progress changed, it answered with the last commit. With edits in the
  working tree it diffs from where the work started to the working tree
  (the branch's merge base, or HEAD on main/master) and says so.
- Glossary: any short all-caps name (`SYSTEM`, `MAX`) was an "acronym". An
  acronym is now one the docs spell out — "Debug Adapter Protocol (DAP)"
  or "LSP (Language Server Protocol)", initials matching. Rustdoc links
  (`[Foo::bar]`, `[text][ref]`) read as their text; the old stripping
  could also pair one link's bracket with the next link's. Each section
  is capped on its own, so many types no longer hide the modules.
- Export: the glossary section was empty unless the docs index had been
  built; the export now starts that build and waits for it (bounded). A
  straight run of visits no longer indents one level per visit — the
  trail nests only at forks. Free text is escaped and identifiers are code
  spans, so `__init__` reads as written. The dialog opens in the project.
- Graph legend: one import-graph legend served every graph ("838 files" on
  the type map). It now says what a node and an arrow are for the graph
  shown, what colour means with heat on or off, and explains the cycle
  and last-run rings where they apply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
---
 crates/clew-core/src/apidoc.rs    |  13 +-
 crates/clew-core/src/git.rs       | 116 +++++++++++-
 crates/clew-core/src/git/tests.rs |  60 ++++++
 crates/clew-core/src/outline.rs   |  13 +-
 crates/clew-server/src/agent.rs   |  89 +++++++--
 src/app.rs                        |   2 +-
 src/app/export.rs                 | 241 ++++++++++++++++++------
 src/app/flow.rs                   | 263 ++++++++++++++++++++------
 src/app/glossary.rs               | 295 ++++++++++++++++++++++++++----
 src/app/message.rs                |  14 +-
 src/app/navigation.rs             |  12 +-
 src/app/tasks.rs                  |  13 +-
 src/app/tests.rs                  | 290 ++++++++++++++++++++++++++++-
 src/app/watch.rs                  |   3 +
 src/editor/flow.rs                | 219 ++++++++++++++++++++--
 src/graph/typegraph.rs            | 229 +++++++++++++++++++++--
 src/ui/docs_stats.rs              |  47 ++---
 src/ui/graph.rs                   |  70 +++++--
 src/ui/panels.rs                  |  29 +++
 src/ui/tests.rs                   | 125 ++++++++++++-
 20 files changed, 1885 insertions(+), 258 deletions(-)

diff --git a/crates/clew-core/src/apidoc.rs b/crates/clew-core/src/apidoc.rs
index 9eedd5d..71da251 100644
--- a/crates/clew-core/src/apidoc.rs
+++ b/crates/clew-core/src/apidoc.rs
@@ -13,6 +13,10 @@ use clew_protocol::DocItem;
 use crate::highlight::Lang;
 use crate::outline::Container;
 
+/// The kind an associated type (a Rust `type` inside an `impl` or a trait)
+/// is listed under, apart from the module's own type aliases.
+pub const ASSOCIATED_TYPE: &str = "associated type";
+
 /// How deeply the emitted [`DocItem`] tree may nest before further items are
 /// folded up as siblings at the cap.
 ///
@@ -71,7 +75,14 @@ pub fn build_file(source: &str, lang_key: &str) -> Vec<DocItem> {
             let s = &l.symbol;
             Raw {
                 name: s.name.clone(),
-                kind: s.kind.clone(),
+                // `type Item = …;` in an `impl` is a member of the impl, not
+                // a type of the module: saying so keeps it out of the type
+                // map and the glossary, which list the project's own types.
+                kind: if lang == Lang::Rust && s.kind == "type" && l.container.is_some() {
+                    ASSOCIATED_TYPE.to_string()
+                } else {
+                    s.kind.clone()
+                },
                 line: s.line,
                 end_line: s.end_line,
                 // From where the declaration starts, and at least through the
diff --git a/crates/clew-core/src/git.rs b/crates/clew-core/src/git.rs
index 99a1329..1058ebc 100644
--- a/crates/clew-core/src/git.rs
+++ b/crates/clew-core/src/git.rs
@@ -1544,8 +1544,113 @@ pub fn range_patch_of(
 /// HEAD, merges left out: every file those commits touched (root-relative;
 /// files outside the project root are not counted), with its commit count
 /// and the time of its latest commit, most changed first, then by path.
-/// Capped at [`MAX_CHURN_FILES`] files. A repository without commits, or a
+/// Only files that exist under `root` now are listed: one deleted or renamed
+/// away since is history, not a file to open. Capped at [`MAX_CHURN_FILES`]
+/// files. A repository without commits, or a
 /// project directory none of them touch, has none.
+/// Whether the project's tracked files differ from `HEAD`, staged or not:
+/// work not committed yet. `false` in a repository without a commit.
+pub fn has_uncommitted(root: &Path) -> Result<bool, GitError> {
+    let git = Git::open(root)?;
+    if !git.has_head()? {
+        return Ok(false);
+    }
+    // `--quiet` exits 1 when there ARE changes; `-- .` keeps the question to
+    // the project directory.
+    let unchanged = git.check([
+        "diff",
+        "--quiet",
+        "--no-ext-diff",
+        END_OF_OPTIONS,
+        "HEAD",
+        "--",
+        ".",
+    ])?;
+    Ok(!unchanged)
+}
+
+/// The commit the current work started from, for a review `base` (a base
+/// branch, or `HEAD` / `HEAD~1` on HEAD's own line): where HEAD left it.
+fn work_start(git: &Git<'_>, base: &str) -> Result<String, GitError> {
+    let out = git.text(["merge-base", END_OF_OPTIONS, base, "HEAD"], GIT_TIMEOUT)?;
+    let start = out.trim();
+    if start.is_empty() {
+        return Err(GitError::Refused(format!(
+            "{base} shares no commit with HEAD"
+        )));
+    }
+    Ok(start.to_string())
+}
+
+/// [`changed_files`], up to the working tree rather than `HEAD`: what the
+/// branch's commits and the uncommitted edits change together, from where
+/// the work left `base`.
+pub fn work_changed_files(root: &Path, base: &str) -> Result<Vec<(String, char)>, GitError> {
+    check_base(base)?;
+    let git = Git::open(root)?;
+    let start = work_start(&git, base)?;
+    let out = git.bytes(
+        [
+            "diff",
+            "--no-color",
+            "--no-ext-diff",
+            "--relative",
+            "--name-status",
+            "-z",
+            END_OF_OPTIONS,
+            &start,
+        ],
+        GIT_TIMEOUT,
+    )?;
+    Ok(parse_name_status_z(&out))
+}
+
+/// [`range_patch`], up to the working tree (see [`work_changed_files`]).
+pub fn work_patch(root: &Path, base: &str, max_bytes: usize) -> Result<String, GitError> {
+    check_base(base)?;
+    let git = Git::open(root)?;
+    let start = work_start(&git, base)?;
+    git.text_truncated(
+        [
+            "diff",
+            "--no-color",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--relative",
+            END_OF_OPTIONS,
+            &start,
+        ],
+        max_bytes,
+    )
+}
+
+/// [`range_patch_of`], up to the working tree (see [`work_changed_files`]).
+pub fn work_patch_of(
+    root: &Path,
+    base: &str,
+    rel: &str,
+    max_bytes: usize,
+) -> Result<String, GitError> {
+    check_base(base)?;
+    check_rel(rel)?;
+    let git = Git::open(root)?;
+    let start = work_start(&git, base)?;
+    git.text_truncated(
+        [
+            "diff",
+            "--no-color",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--relative",
+            END_OF_OPTIONS,
+            &start,
+            "--",
+            rel,
+        ],
+        max_bytes,
+    )
+}
+
 pub fn churn(root: &Path, commits: usize) -> Result<Vec<FileChurn>, GitError> {
     let git = Git::open(root)?;
     if !git.has_head()? {
@@ -1569,7 +1674,13 @@ pub fn churn(root: &Path, commits: usize) -> Result<Vec<FileChurn>, GitError> {
         ],
         GIT_HISTORY_TIMEOUT,
     )?;
-    Ok(parse_churn(&out))
+    // History names files deleted or renamed since: they are no file the
+    // reader can open (a click on one only reported a missing path), so the
+    // most-changed list keeps the files that are here now.
+    let mut files = parse_churn(&out);
+    files.retain(|f| root.join(&f.rel).exists());
+    files.truncate(MAX_CHURN_FILES);
+    Ok(files)
 }
 
 /// `%x00<sha>%x00<time>`: a commit's header line, which no path can start
@@ -1607,7 +1718,6 @@ fn parse_churn(out: &str) -> Vec<FileChurn> {
         .map(|(rel, (commits, last))| FileChurn { rel, commits, last })
         .collect();
     files.sort_by(|a, b| b.commits.cmp(&a.commits).then_with(|| a.rel.cmp(&b.rel)));
-    files.truncate(MAX_CHURN_FILES);
     files
 }
 
diff --git a/crates/clew-core/src/git/tests.rs b/crates/clew-core/src/git/tests.rs
index 329c601..a31aa3f 100644
--- a/crates/clew-core/src/git/tests.rs
+++ b/crates/clew-core/src/git/tests.rs
@@ -944,6 +944,15 @@ fn churn_counts_each_files_commits_over_the_recent_history() {
         ["a.rs"],
         "{recent:?}"
     );
+
+    // A file deleted (or renamed away) since is history, not a file the
+    // reader can open: it leaves the list, however often it changed.
+    sh_git(&dir, &["rm", "-q", "b.rs"]);
+    sh_git(&dir, &["mv", "ünï.rs", "moved.rs"]);
+    commit_all(&dir, "drop b, rename ünï");
+    let files = churn(&dir, 300).unwrap();
+    let names: Vec<&str> = files.iter().map(|f| f.rel.as_str()).collect();
+    assert_eq!(names, ["a.rs", "moved.rs"], "{files:?}");
 }
 
 /// A blobless clone fetches old blobs on demand from its promisor remote, and
@@ -1734,3 +1743,54 @@ fn review_queries_are_scoped_to_a_subdirectory_root() {
     let small = range_patch(&sub, &base, 16).unwrap();
     assert!(small.ends_with("… (truncated)\n"), "{small:?}");
 }
+
+/// The current work includes what is not committed yet: from where the
+/// branch left its base (or from HEAD on the base itself) to the working
+/// tree — the branch's commits and the edits on top, together.
+#[test]
+fn uncommitted_work_is_part_of_the_current_work() {
+    let dir = repo_dir("git-work");
+    assert!(!has_uncommitted(&dir).unwrap(), "no commit yet");
+    std::fs::write(dir.join("a.rs"), "1\n").unwrap();
+    std::fs::write(dir.join("b.rs"), "1\n").unwrap();
+    commit_all(&dir, "start");
+    assert!(!has_uncommitted(&dir).unwrap());
+    std::fs::write(dir.join("a.rs"), "1\nedited\n").unwrap();
+    assert!(has_uncommitted(&dir).unwrap());
+    // On the base itself, the work is the edit alone.
+    assert_eq!(
+        work_changed_files(&dir, "HEAD").unwrap(),
+        [("a.rs".to_string(), 'M')]
+    );
+    let patch = work_patch(&dir, "HEAD", 64 * 1024).unwrap();
+    assert!(patch.contains("+edited"), "{patch}");
+    // Staged counts too.
+    sh_git(&dir, &["add", "a.rs"]);
+    assert!(has_uncommitted(&dir).unwrap());
+    sh_git(&dir, &["commit", "-qm", "edit a"]);
+    assert!(!has_uncommitted(&dir).unwrap());
+
+    // On a branch: its commit, and an uncommitted edit of another file.
+    let base = sh_git_out(&dir, &["rev-parse", "--abbrev-ref", "HEAD"]);
+    sh_git(&dir, &["checkout", "-q", "-b", "feature"]);
+    std::fs::write(dir.join("c.rs"), "new\n").unwrap();
+    commit_all(&dir, "add c");
+    std::fs::write(dir.join("b.rs"), "1\nwip\n").unwrap();
+    let files = work_changed_files(&dir, &base).unwrap();
+    assert_eq!(
+        files,
+        [("b.rs".to_string(), 'M'), ("c.rs".to_string(), 'A')],
+        "the branch's commit and the edit on top"
+    );
+    let patch = work_patch_of(&dir, &base, "b.rs", 64 * 1024).unwrap();
+    assert!(patch.contains("+wip") && !patch.contains("c.rs"), "{patch}");
+    // The commits-only range still leaves the edit out.
+    assert_eq!(
+        changed_files(&dir, &base).unwrap(),
+        [("c.rs".to_string(), 'A')]
+    );
+    assert!(
+        work_changed_files(&dir, "-x").is_err(),
+        "an option is no base"
+    );
+}
diff --git a/crates/clew-core/src/outline.rs b/crates/clew-core/src/outline.rs
index 13643be..1bd73e5 100644
--- a/crates/clew-core/src/outline.rs
+++ b/crates/clew-core/src/outline.rs
@@ -535,11 +535,13 @@ fn template_wrapper(node: Node) -> Node {
     top
 }
 
-/// The container of a Rust method (see [`Container`]).
+/// The container of a Rust method or associated type (see [`Container`]):
+/// a `type Item = …;` inside an `impl` is the impl's, not a type of the
+/// module — the docs index names it an associated type for that reason.
 fn container_of(def: Node, lang: Lang) -> Option<Container> {
     match lang {
         Lang::Rust => {
-            if def.kind() != "function_item" {
+            if !matches!(def.kind(), "function_item" | "type_item") {
                 return None;
             }
             let list = def.parent().filter(|p| p.kind() == "declaration_list")?;
@@ -2103,6 +2105,13 @@ fn build_inner() -> B { B }
         assert_eq!(required[0].container, Some(Container::TraitImpl));
         assert_eq!(find(&items, "inherent").container, Some(Container::Impl));
         assert_eq!(find(&items, "free").container, None);
+
+        // An impl's associated type is the impl's; a module's alias is nobody's.
+        let src = "struct S;\nimpl Iterator for S {\n  type Item = u8;\n  fn next(&mut self) -> Option<u8> { None }\n}\nimpl S {\n  type Own = u16;\n}\ntype Free = u32;\n";
+        let items = extract_located(src, "rust");
+        assert_eq!(find(&items, "Item").container, Some(Container::TraitImpl));
+        assert_eq!(find(&items, "Own").container, Some(Container::Impl));
+        assert_eq!(find(&items, "Free").container, None);
     }
 
     /// One parse yields all three facts, identical to the separate extractors.
diff --git a/crates/clew-server/src/agent.rs b/crates/clew-server/src/agent.rs
index 1c33b5b..69e02ea 100644
--- a/crates/clew-server/src/agent.rs
+++ b/crates/clew-server/src/agent.rs
@@ -701,8 +701,9 @@ fn system_prompt(ctx: &Ctx) -> String {
            Prefer these over `search` when tracing call chains or same-named symbols.\n\
          - `history` for how a file evolved, `explanations` for cached AI summaries\n\
          - `changes` for what the current work changes (the branch versus main/master, \
-           else the last commit): its commit messages, changed files and diff — for \
-           \"what did this branch change\" and \"why was this changed\" questions\n\
+           else the last commit, with any uncommitted edits included): its commit \
+           messages, changed files and diff — for \"what did this branch change\", \
+           \"what am I changing\" and \"why was this changed\" questions\n\
          Explore purposefully. The moment you can answer, call `answer` and then write \
          it. Do not guess at code you have not read.\n\
          \n\
@@ -830,7 +831,7 @@ fn tool_defs() -> Vec<llm::ToolDef> {
         ),
         t(
             "changes",
-            "What the current work changes versus its review base (the branch against main/master, else the last commit): the commit messages, the changed files with their status, and the unified diff — the whole diff truncated to fit, or one file's whole diff when `file` is given.",
+            "What the current work changes: the branch against main/master, else the last commit — and, when there are edits not committed yet, those too (on main/master, the uncommitted edits alone). The commit messages, the changed files with their status, and the unified diff — the whole diff truncated to fit, or one file's whole diff when `file` is given.",
             serde_json::json!({
                 "type": "object",
                 "properties": {
@@ -1456,12 +1457,20 @@ fn exec_tool_basic(
                     );
                 }
             }
-            let (base, label) = match git::review_base(&ctx.root) {
-                Ok(Some(base)) => base,
-                Ok(None) => {
+            // Edits not committed yet are the current work too: on a branch
+            // they ride on its commits, on main/master they are the work.
+            let review = git::review_base(&ctx.root)
+                .and_then(|review| Ok((review, git::has_uncommitted(&ctx.root)?)));
+            let (base, label, worktree) = match review {
+                Ok((Some((base, label)), true)) if base != "HEAD~1" => {
+                    (base, format!("{label} + uncommitted"), true)
+                }
+                Ok((_, true)) => ("HEAD".to_string(), "uncommitted".to_string(), true),
+                Ok((Some((base, label)), false)) => (base, label, false),
+                Ok((None, false)) => {
                     return (
-                        "nothing to review: the project has no branch ahead of main/master and \
-                         no commit before HEAD"
+                        "nothing to review: the project has no branch ahead of main/master, no \
+                         uncommitted edit and no commit before HEAD"
                             .into(),
                         title(""),
                         Vec::new(),
@@ -1477,11 +1486,20 @@ fn exec_tool_basic(
             };
             let gathered = (|| -> Result<_, git::GitError> {
                 let commits = git::commit_subjects(&ctx.root, &base)?;
-                let changed = git::changed_files(&ctx.root, &base)?;
-                let patch = if rel.is_empty() {
-                    git::range_patch(&ctx.root, &base, MAX_CHANGES_PATCH_BYTES)?
+                let changed = if worktree {
+                    git::work_changed_files(&ctx.root, &base)?
                 } else {
-                    git::range_patch_of(&ctx.root, &base, rel, MAX_CHANGES_PATCH_BYTES)?
+                    git::changed_files(&ctx.root, &base)?
+                };
+                let patch = match (worktree, rel.is_empty()) {
+                    (false, true) => git::range_patch(&ctx.root, &base, MAX_CHANGES_PATCH_BYTES)?,
+                    (false, false) => {
+                        git::range_patch_of(&ctx.root, &base, rel, MAX_CHANGES_PATCH_BYTES)?
+                    }
+                    (true, true) => git::work_patch(&ctx.root, &base, MAX_CHANGES_PATCH_BYTES)?,
+                    (true, false) => {
+                        git::work_patch_of(&ctx.root, &base, rel, MAX_CHANGES_PATCH_BYTES)?
+                    }
                 };
                 Ok((commits, changed, patch))
             })();
@@ -1502,8 +1520,17 @@ fn exec_tool_basic(
                     Vec::new(),
                 );
             }
+            // What the range is, in words: the label is the chips' short form.
+            let scope = match label.as_str() {
+                "uncommitted" => "the edits not committed yet".to_string(),
+                "last commit" => "the last commit".to_string(),
+                other => match other.strip_suffix(" + uncommitted") {
+                    Some(vs) => format!("the current work {vs}, uncommitted edits included"),
+                    None => format!("the current work {other}"),
+                },
+            };
             let mut content = format!(
-                "Reviewing: the current work {label} ({} commits, {} files)\n\nCommits (oldest first):\n",
+                "Reviewing: {scope} ({} commits, {} files)\n\nCommits (oldest first):\n",
                 commits.len(),
                 changed.len()
             );
@@ -3045,6 +3072,21 @@ mod tests {
         assert_eq!(title, "changes");
         assert!(refs.is_empty());
 
+        // An edit on main, not committed yet: that is the current work.
+        std::fs::write(dir.join("src/same.rs"), "fn same() {}\nfn wip() {}\n").unwrap();
+        let (content, title, refs, _) = exec_tool(&ctx, "changes", &serde_json::json!({}));
+        assert!(
+            content.starts_with("Reviewing: the edits not committed yet (0 commits, 1 files)"),
+            "{content}"
+        );
+        assert!(
+            content.contains("M src/same.rs") && content.contains("+fn wip() {}"),
+            "{content}"
+        );
+        assert_eq!(title, "changes uncommitted (1 files)");
+        assert_eq!(refs.len(), 1);
+        git(&["checkout", "-q", "--", "src/same.rs"]);
+
         git(&["checkout", "-q", "-b", "feature"]);
         std::fs::write(dir.join("src/x.rs"), "fn x() {}\nfn added() {}\n").unwrap();
         std::fs::write(dir.join("src/new.rs"), "fn fresh() {}\n").unwrap();
@@ -3100,6 +3142,27 @@ mod tests {
             &serde_json::json!({ "file": "../outside.rs" }),
         );
         assert!(!content.contains("Reviewing"), "refused: {content}");
+
+        // On the branch, an edit not committed yet rides on its commits.
+        std::fs::write(dir.join("src/same.rs"), "fn same() {}\nfn wip() {}\n").unwrap();
+        let (content, title, _, _) = exec_tool(&ctx, "changes", &serde_json::json!({}));
+        assert!(
+            content.starts_with(
+                "Reviewing: the current work vs main, uncommitted edits included (1 commits, 3 files)"
+            ),
+            "{content}"
+        );
+        assert!(
+            content.contains("+fn wip() {}") && content.contains("+fn fresh() {}"),
+            "{content}"
+        );
+        assert_eq!(title, "changes vs main + uncommitted (3 files)");
+        let (content, _, _, _) = exec_tool(
+            &ctx,
+            "changes",
+            &serde_json::json!({ "file": "src/same.rs" }),
+        );
+        assert!(content.contains("+fn wip() {}"), "{content}");
     }
 
     /// A file's history is asked of git by where the file is: through a
diff --git a/src/app.rs b/src/app.rs
index 29d2260..e80d152 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -56,7 +56,7 @@ mod debug;
 mod docs;
 mod editor;
 mod explain;
-mod export;
+pub(crate) mod export;
 pub(crate) mod flow;
 pub(crate) mod glossary;
 mod graph;
diff --git a/src/app/export.rs b/src/app/export.rs
index 8874aca..ade98cc 100644
--- a/src/app/export.rs
+++ b/src/app/export.rs
@@ -29,10 +29,11 @@ pub(crate) struct Export<'a> {
 /// The Markdown document for `x`. Sections in reading order — notes,
 /// bookmarks, trail, walkthroughs, glossary — each with its count, an empty
 /// one saying so rather than vanishing (so the reader can see what the
-/// export covers).
+/// export covers). Identifiers are code spans and free text is escaped, so a
+/// `__init__` or a `*ptr` reads as written.
 pub(crate) fn render(x: &Export<'_>) -> String {
     let mut out = String::new();
-    out.push_str(&format!("# {} — reading notes\n\n", x.project));
+    out.push_str(&format!("# {} — reading notes\n\n", md(x.project)));
     out.push_str("Exported from clew.\n\n");
 
     out.push_str(&format!("## Notes ({})\n\n", x.notes.len()));
@@ -41,9 +42,13 @@ pub(crate) fn render(x: &Export<'_>) -> String {
     }
     for n in x.notes {
         let mark = if n.understood { " ✓ understood" } else { "" };
-        out.push_str(&format!("- `{}` · **{}**{mark}\n", n.rel, code(&n.symbol)));
+        out.push_str(&format!(
+            "- `{}` · `{}`{mark}\n",
+            code(&n.rel),
+            code(&n.symbol)
+        ));
         for line in n.text.lines().filter(|l| !l.trim().is_empty()) {
-            out.push_str(&format!("  > {}\n", line.trim_end()));
+            out.push_str(&format!("  > {}\n", md(line.trim_end())));
         }
     }
     out.push('\n');
@@ -55,13 +60,13 @@ pub(crate) fn render(x: &Export<'_>) -> String {
     for b in x.bookmarks {
         let preview = code(b.preview.trim());
         if preview.is_empty() {
-            out.push_str(&format!("- `{}:{}`\n", b.rel, b.line));
+            out.push_str(&format!("- `{}:{}`\n", code(&b.rel), b.line));
         } else {
-            out.push_str(&format!("- `{}:{}` — `{preview}`\n", b.rel, b.line));
+            out.push_str(&format!("- `{}:{}` — `{preview}`\n", code(&b.rel), b.line));
         }
         if let Some(note) = b.note.as_deref().map(str::trim).filter(|s| !s.is_empty()) {
             for line in note.lines() {
-                out.push_str(&format!("  > {}\n", line.trim_end()));
+                out.push_str(&format!("  > {}\n", md(line.trim_end())));
             }
         }
     }
@@ -71,7 +76,21 @@ pub(crate) fn render(x: &Export<'_>) -> String {
     if x.trail.is_empty() {
         out.push_str("_No trail._\n\n");
     }
+    // A straight run of visits is one list; it nests only where the trail
+    // forks — where the reader went back and took another way — and each
+    // way taken from a fork starts with `↳`.
+    let mut ancestors: Vec<(usize, bool)> = Vec::new();
     for v in x.trail {
+        while ancestors.last().is_some_and(|&(depth, _)| depth >= v.depth) {
+            ancestors.pop();
+        }
+        let indent = ancestors.iter().filter(|&&(_, forks)| forks).count();
+        let branch = if ancestors.last().is_some_and(|&(_, forks)| forks) {
+            "↳ "
+        } else {
+            ""
+        };
+        ancestors.push((v.depth, v.forks));
         let rel = v
             .loc
             .path
@@ -80,16 +99,19 @@ pub(crate) fn render(x: &Export<'_>) -> String {
             .to_string_lossy()
             .replace('\\', "/");
         let at = match v.loc.line {
-            Some(line) => format!("{rel}:{line}"),
-            None => rel,
+            Some(line) => format!("{}:{line}", code(&rel)),
+            None => code(&rel),
         };
         let label = v
             .label
             .as_deref()
-            .map(|l| format!(" — {}", code(l)))
+            .map(|l| format!(" — `{}`", code(l)))
             .unwrap_or_default();
         let here = if v.is_current { " ← here" } else { "" };
-        out.push_str(&format!("{}- `{at}`{label}{here}\n", "  ".repeat(v.depth)));
+        out.push_str(&format!(
+            "{}- {branch}`{at}`{label}{here}\n",
+            "  ".repeat(indent)
+        ));
     }
     out.push('\n');
 
@@ -98,27 +120,25 @@ pub(crate) fn render(x: &Export<'_>) -> String {
         out.push_str("_No walkthroughs._\n\n");
     }
     for t in x.tours {
-        out.push_str(&format!("### {}\n\n", t.title.trim()));
+        out.push_str(&format!("### {}\n\n", md(t.title.trim())));
         let scope = t.scope.trim();
         if !scope.is_empty() {
-            out.push_str(&format!("_Scope: {scope}_\n\n"));
+            out.push_str(&format!("_Scope: {}_\n\n", md(scope)));
         }
         for (i, s) in t.steps.iter().enumerate() {
-            let mut at = s.file.clone();
+            let mut at = code(&s.file);
             if let Some(line) = s.line {
                 at.push_str(&format!(":{line}"));
             }
+            let title = s.title.trim();
+            // The step's symbol, unless the title already is it.
             let symbol = s
                 .symbol
                 .as_deref()
-                .filter(|s| !s.is_empty())
-                .map(|s| format!(" ({})", code(s)))
+                .filter(|sym| !sym.is_empty() && *sym != title)
+                .map(|sym| format!(" (`{}`)", code(sym)))
                 .unwrap_or_default();
-            out.push_str(&format!(
-                "{}. **{}** — `{at}`{symbol}\n",
-                i + 1,
-                s.title.trim()
-            ));
+            out.push_str(&format!("{}. **{}** — `{at}`{symbol}\n", i + 1, md(title)));
             for line in s.narration.lines() {
                 out.push_str(&format!("   {}\n", line.trim_end()));
             }
@@ -133,23 +153,45 @@ pub(crate) fn render(x: &Export<'_>) -> String {
     }
     for t in terms {
         out.push_str(&format!(
-            "- **{}** ({}) — {} · `{}:{}`\n",
+            "- **`{}`** ({}) — {} · `{}:{}`\n",
             code(&t.name),
             t.badge,
-            t.definition,
-            t.rel,
+            md(&t.definition),
+            code(&t.rel),
             t.line
         ));
     }
     out
 }
 
-/// `s` fit for a Markdown code span or a bold run: backticks dropped (they
-/// would end the span), newlines flattened.
+/// `s` fit for a Markdown code span: backticks dropped (they would end the
+/// span), newlines flattened.
 fn code(s: &str) -> String {
     s.replace('`', "").replace(['\n', '\r'], " ")
 }
 
+/// `s` as plain text in Markdown: every character Markdown reads as markup
+/// (emphasis, links, headings, tables, HTML) escaped, newlines flattened.
+fn md(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for c in s.chars() {
+        match c {
+            '\\' | '`' | '*' | '_' | '[' | ']' | '<' | '>' | '#' | '|' | '~' => {
+                out.push('\\');
+                out.push(c);
+            }
+            '\n' | '\r' => out.push(' '),
+            c => out.push(c),
+        }
+    }
+    out
+}
+
+/// How long an export waits for the docs index the glossary is built from,
+/// per check, and how many checks before it writes without it.
+const DOCS_WAIT_STEP: std::time::Duration = std::time::Duration::from_millis(200);
+pub(crate) const DOCS_WAITS: u32 = 50;
+
 impl App {
     /// The export of the open project's reading state, as rendered now;
     /// `None` with no project open.
@@ -177,36 +219,19 @@ impl App {
                     self.status = "Open a project to export its reading notes".into();
                     return Task::none();
                 };
+                // The glossary is built from the docs index, which is only
+                // built on demand: start it while the reader picks a file.
+                self.ensure_docs();
                 let file_name = format!("{}-reading-notes.md", project_name(&root));
-                save_markdown(self.main_window, file_name)
+                // A local project's own folder to start in; a remote one's
+                // root is a path on another machine.
+                let folder = self.local_project_state().then_some(root);
+                save_markdown(self.main_window, file_name, folder)
                     .map(|path| Message::Export(ExportMsg::Picked(path)))
             }
             ExportMsg::Picked(None) => Task::none(),
-            ExportMsg::Picked(Some(path)) => {
-                let Some(markdown) = self.export_markdown() else {
-                    return Task::none();
-                };
-                let stamp = self.stamp();
-                Task::perform(
-                    async move {
-                        let write_path = path.clone();
-                        let result = tokio::task::spawn_blocking(move || {
-                            std::fs::write(&write_path, markdown.as_bytes())
-                                .map_err(|e| e.to_string())
-                        })
-                        .await
-                        .unwrap_or_else(|e| Err(format!("the write failed unexpectedly: {e}")));
-                        (path, result)
-                    },
-                    move |(path, result)| {
-                        Message::Export(ExportMsg::Written {
-                            stamp: stamp.clone(),
-                            path,
-                            result,
-                        })
-                    },
-                )
-            }
+            ExportMsg::Picked(Some(path)) => self.export_when_ready(path, 0),
+            ExportMsg::Ready { path, waited, .. } => self.export_when_ready(path, waited),
             ExportMsg::Written { path, result, .. } => {
                 self.status = match result {
                     Ok(()) => format!("Exported reading notes to {}", path.display()),
@@ -216,6 +241,54 @@ impl App {
             }
         }
     }
+
+    /// Write the export to `path` once the docs index is in (its glossary
+    /// section is built from it), checking again every [`DOCS_WAIT_STEP`];
+    /// after [`DOCS_WAITS`] checks it is written with what there is.
+    fn export_when_ready(&mut self, path: PathBuf, waited: u32) -> Task<Message> {
+        if waited == 0 {
+            self.ensure_docs();
+        }
+        if self.docs_loading() && waited < DOCS_WAITS {
+            if waited == 0 {
+                self.status = "Exporting — waiting for the docs index…".into();
+            }
+            let stamp = self.stamp();
+            // Created where it is polled: a timer needs the runtime's context.
+            return Task::perform(
+                async { tokio::time::sleep(DOCS_WAIT_STEP).await },
+                move |()| {
+                    Message::Export(ExportMsg::Ready {
+                        stamp: stamp.clone(),
+                        path: path.clone(),
+                        waited: waited + 1,
+                    })
+                },
+            );
+        }
+        let Some(markdown) = self.export_markdown() else {
+            return Task::none();
+        };
+        let stamp = self.stamp();
+        Task::perform(
+            async move {
+                let write_path = path.clone();
+                let result = tokio::task::spawn_blocking(move || {
+                    std::fs::write(&write_path, markdown.as_bytes()).map_err(|e| e.to_string())
+                })
+                .await
+                .unwrap_or_else(|e| Err(format!("the write failed unexpectedly: {e}")));
+                (path, result)
+            },
+            move |(path, result)| {
+                Message::Export(ExportMsg::Written {
+                    stamp: stamp.clone(),
+                    path,
+                    result,
+                })
+            },
+        )
+    }
 }
 
 /// The project's display name: its root folder's name.
@@ -319,10 +392,10 @@ Exported from clew.
 
 ## Notes (2)
 
-- `src/lib.rs` · **parse** ✓ understood
+- `src/lib.rs` · `parse` ✓ understood
   > tricky
-  > second `line`
-- `src/main.rs` · **main**
+  > second \\`line\\`
+- `src/main.rs` · `main`
 
 ## Bookmarks (2)
 
@@ -332,8 +405,8 @@ Exported from clew.
 
 ## Reading trail (2)
 
-- `src/lib.rs:3` — parse
-  - `src/util.rs` ← here
+- `src/lib.rs:3` — `parse`
+- `src/util.rs` ← here
 
 ## Walkthroughs (1)
 
@@ -341,13 +414,13 @@ Exported from clew.
 
 _Scope: boot_
 
-1. **Entry** — `src/main.rs:1` (main)
+1. **Entry** — `src/main.rs:1` (`main`)
    Where it starts.
    Two lines.
 
 ## Glossary (1)
 
-- **Parser** (struct) — Reads tokens · `src/lib.rs:2`
+- **`Parser`** (struct) — Reads tokens · `src/lib.rs:2`
 ";
         assert_eq!(md, expected);
 
@@ -374,6 +447,56 @@ _Scope: boot_
         }
     }
 
+    /// A straight run of visits stays one list; the trail nests only where
+    /// the reader went back and took another way, each way marked `↳`. A
+    /// title with Markdown in it reads as written, and a step's symbol is
+    /// not repeated when it is the title.
+    #[test]
+    fn the_trail_nests_at_forks_and_text_is_escaped() {
+        let root = PathBuf::from("/p");
+        let at = |rel: &str| Loc {
+            path: root.join(rel),
+            line: Some(1),
+        };
+        let mut history = History::default();
+        history.push(at("a.rs"), None);
+        history.push(at("b.rs"), None);
+        history.push(at("d.rs"), None);
+        history.back();
+        history.back();
+        history.push(at("c.rs"), Some("__init__".into()));
+        let trail = history.flatten();
+        let tours = vec![Walkthrough {
+            title: "__init__ and *ptr".into(),
+            scope: String::new(),
+            steps: vec![walkthrough::Step {
+                title: "__init__".into(),
+                file: "a.rs".into(),
+                symbol: Some("__init__".into()),
+                line: Some(1),
+                narration: String::new(),
+            }],
+        }];
+        let glossary = Glossary::default();
+        let md = render(&Export {
+            project: "p",
+            root: &root,
+            notes: &[],
+            bookmarks: &[],
+            trail: &trail,
+            tours: &tours,
+            glossary: &glossary,
+        });
+        assert!(
+            md.contains(
+                "- `a.rs:1`\n  - ↳ `b.rs:1`\n  - `d.rs:1`\n  - ↳ `c.rs:1` — `__init__` ← here\n"
+            ),
+            "{md}"
+        );
+        assert!(md.contains("### \\_\\_init\\_\\_ and \\*ptr\n"), "{md}");
+        assert!(md.contains("1. **\\_\\_init\\_\\_** — `a.rs:1`\n"), "{md}");
+    }
+
     #[test]
     fn the_project_is_named_after_its_root_folder() {
         assert_eq!(project_name(Path::new("/tmp/clew")), "clew");
diff --git a/src/app/flow.rs b/src/app/flow.rs
index 2192e16..531c347 100644
--- a/src/app/flow.rs
+++ b/src/app/flow.rs
@@ -5,10 +5,17 @@
 //! binds it as a parameter, passes it to a call, returns it, branches on it,
 //! reaches into it, or reads it. A `Passed` node follows the value into the
 //! callee: its definition is looked up, the argument's parameter read off
-//! the declaration line ([`flow::parameter_at`]), and that parameter's
+//! the declaration from the callee's name on, over the lines a wrapped
+//! parameter list runs onto ([`flow::parameter_in`]), and that parameter's
 //! occurrences become the node's children — as deep as the reader cares to
 //! go.
 //!
+//! Lines are classified as the file has them, untrimmed, so the server's
+//! columns land where they point. When a traced file changes, each
+//! occurrence follows its line by the line's text (`App::reanchor_flow`);
+//! one whose line reads differently now is marked changed, and the tab
+//! offers to trace again.
+//!
 //! Line text comes from the open panes when the file is open, else off disk
 //! for a local project. A remote project's occurrences in files not open
 //! here are shown by location, unclassified (the tab says so): reading
@@ -17,7 +24,7 @@
 //!
 //! Its messages, [`FlowMsg`], arrive through `App::update_flow`.
 
-use crate::app::navigation::read_location_previews;
+use crate::app::navigation::read_location_lines;
 use crate::app::prelude::*;
 use crate::graph::tree;
 use crate::*;
@@ -27,6 +34,10 @@ pub(crate) use crate::flow::{Role, Use};
 /// Occurrences a trace keeps at most (per level).
 pub(crate) const MAX_FLOW_NODES: usize = 400;
 
+/// Lines a callee's declaration is read over to find a parameter: a
+/// parameter list wrapped one per line, as rustfmt and black wrap long ones.
+pub(crate) const SIGNATURE_LINES: usize = 32;
+
 /// One occurrence of a traced identifier.
 #[derive(Debug, Clone)]
 pub struct FlowNode {
@@ -52,6 +63,13 @@ pub struct FlowNode {
     pub text: String,
     /// Whether `text` was read and the role classified from it.
     pub classified: bool,
+    /// The raw line's leading whitespace, in chars: `col`, the callee's
+    /// column and the server's `character` are on the raw line, `text` is
+    /// trimmed.
+    pub indent: usize,
+    /// The file changed since and this line could not be found in it any
+    /// more: the row shows where it was.
+    pub changed: bool,
     pub depth: usize,
     pub parent: Option<usize>,
     /// `None` until followed (a `Passed` node), else the children.
@@ -78,10 +96,15 @@ pub struct FlowTree {
     pub token: u64,
     pub symbol: String,
     pub lang: &'static str,
-    /// Where the trace was asked for.
+    /// Where the trace was asked for: the file and the 0-based line, and the
+    /// identifier's char column on it (`origin_col`).
     pub origin: (PathBuf, usize),
+    pub origin_col: usize,
     /// A note for the reader (occurrences left unclassified, a cap hit).
     pub note: Option<String>,
+    /// A traced file changed and some occurrence could not be followed to
+    /// its new line (see `App::reanchor_flow`).
+    pub stale: bool,
     nodes: Vec<FlowNode>,
     roots: Vec<usize>,
 }
@@ -93,7 +116,9 @@ impl FlowTree {
             symbol,
             lang,
             origin,
+            origin_col: 0,
             note: None,
+            stale: false,
             nodes: Vec::new(),
             roots: Vec::new(),
         }
@@ -126,6 +151,11 @@ impl FlowTree {
         self.nodes.len()
     }
 
+    /// Whether an occurrence of the trace is in `path`.
+    pub fn depends_on(&self, path: &Path) -> bool {
+        self.origin.0 == path || self.nodes.iter().any(|n| n.abs == path)
+    }
+
     /// The root occurrences under each role, in the roles' order, roles
     /// without any left out.
     pub fn grouped_roots(&self) -> Vec<(Role, Vec<usize>)> {
@@ -227,6 +257,8 @@ fn node_for(
         col: 0,
         text: String::new(),
         classified: false,
+        indent: 0,
+        changed: false,
         depth: 0,
         parent: None,
         children: None,
@@ -247,9 +279,15 @@ fn classify_node(
 ) {
     let col = viewer::Col::from_offset(text, node.character, encoding).0;
     node.col = col;
+    node.indent = text.chars().take_while(|c| c.is_whitespace()).count();
     node.text = text.trim().to_string();
     node.classified = true;
-    if let Some(role) = role_hint {
+    // A definition is `Declared` whatever its line says — unless the line
+    // reassigns (`x += …`): Python's server lists every assignment among a
+    // name's definitions.
+    let hint = role_hint
+        .filter(|&r| !(r == Role::Declared && crate::flow::reassigns(text, col, &node.symbol)));
+    if let Some(role) = hint {
         node.role = role;
         return;
     }
@@ -302,12 +340,9 @@ impl App {
         self.flow_token += 1;
         let token = self.flow_token;
         self.proj.flow_pending = Some(token);
-        self.proj.flow = Some(FlowTree::new(
-            token,
-            word.clone(),
-            lang,
-            (path.clone(), line),
-        ));
+        let mut tree = FlowTree::new(token, word.clone(), lang, (path.clone(), line));
+        tree.origin_col = start;
+        self.proj.flow = Some(tree);
         self.sidebar = SidebarTab::Flow;
         let stamp = self.stamp();
         let reveal = ui::reveal_sidebar_tab(SidebarTab::Flow);
@@ -412,7 +447,7 @@ impl App {
         let stamp = self.stamp();
         Task::perform(
             async move {
-                tokio::task::spawn_blocking(move || read_location_previews(to_read))
+                tokio::task::spawn_blocking(move || read_location_lines(to_read))
                     .await
                     .unwrap_or_default()
             },
@@ -463,7 +498,7 @@ impl App {
     pub(crate) fn on_flow_expand(&mut self, token: u64, id: usize) -> Task<Message> {
         // What the node says, read and released before anything else of
         // the app is touched.
-        let (lang, symbol, callee, callee_col, argument, abs, line, line_text) = {
+        let (lang, symbol, callee, callee_col, argument, abs, line, line_text, indent) = {
             let Some(tree) = self.proj.flow.as_mut().filter(|t| t.token == token) else {
                 return Task::none();
             };
@@ -492,6 +527,7 @@ impl App {
                 node.abs.clone(),
                 node.line,
                 node.text.clone(),
+                node.indent,
             )
         };
         let client = match self.proj.link.lsp.get(lang) {
@@ -502,19 +538,14 @@ impl App {
             }
         };
         let local = self.local_project_state();
-        // The callee's column on the line, in the server's encoding: the
-        // node's text is the trimmed line, so the raw line is preferred when
-        // the file is open here; else the trimmed one serves, its leading
-        // whitespace already cut.
-        let raw = self.pane_line(&abs, line);
-        let (base, shift) = match &raw {
-            Some(raw) => (
-                raw.clone(),
-                raw.chars().count() - raw.trim_start().chars().count(),
-            ),
-            None => (line_text.clone(), 0),
-        };
-        let character = viewer::Col(callee_col + shift).to_offset(&base, client.encoding);
+        // The callee's column is on the raw line the node was classified
+        // from: the pane's when the file is open here, else the node's text
+        // put back behind its indentation (whitespace is one unit in every
+        // encoding, so spaces stand in for tabs).
+        let base = self
+            .pane_line(&abs, line)
+            .unwrap_or_else(|| format!("{}{line_text}", " ".repeat(indent)));
+        let character = viewer::Col(callee_col).to_offset(&base, client.encoding);
         // Signature lines of the files open here, in case the callee is in one.
         let open_lines: Vec<(PathBuf, Vec<String>)> = self
             .proj
@@ -524,7 +555,9 @@ impl App {
             .map(|v| {
                 (
                     v.abs.clone(),
-                    (0..v.lines.len()).map(|l| v.line_text(l + 1)).collect(),
+                    (0..v.lines.len())
+                        .map(|l| v.source_line(l).unwrap_or("").to_string())
+                        .collect(),
                 )
             })
             .collect();
@@ -542,42 +575,55 @@ impl App {
                     .into_iter()
                     .next()
                     .ok_or_else(|| format!("no definition of `{callee}` found"))?;
-                let sig = open_lines
-                    .iter()
-                    .find(|(p, _)| *p == declared.path)
-                    .and_then(|(_, lines)| lines.get(declared.line).cloned())
-                    .or_else(|| {
-                        local
-                            .then(|| {
-                                read_location_previews(vec![(
-                                    0,
-                                    declared.path.clone(),
-                                    declared.line,
-                                )])
+                // The declaration from the callee's name on, over the lines
+                // its parameter list may wrap onto.
+                let sig_lines: Vec<String> =
+                    match open_lines.iter().find(|(p, _)| *p == declared.path) {
+                        Some((_, lines)) => lines
+                            .iter()
+                            .skip(declared.line)
+                            .take(SIGNATURE_LINES)
+                            .cloned()
+                            .collect(),
+                        None if local => {
+                            let wanted: Vec<(usize, PathBuf, usize)> = (0..SIGNATURE_LINES)
+                                .map(|k| (k, declared.path.clone(), declared.line + k))
+                                .collect();
+                            // The unbroken run from the declaration's line (a
+                            // file shorter than the window ends it early).
+                            read_location_lines(wanted)
                                 .into_iter()
-                                .next()
-                                .map(|(_, t)| t)
-                            })
-                            .flatten()
-                    })
-                    .ok_or_else(|| {
-                        format!(
-                            "open {} to follow into `{callee}`",
-                            declared
-                                .path
-                                .file_name()
-                                .map(|n| n.to_string_lossy().into_owned())
-                                .unwrap_or_default()
-                        )
-                    })?;
-                let (param, param_col) = crate::flow::parameter_at(&sig, argument, lang)
-                    .ok_or_else(|| format!("`{callee}` has no parameter {}", argument + 1))?;
-                let param_character = viewer::Col(param_col).to_offset(&sig, client.encoding);
+                                .enumerate()
+                                .take_while(|(i, (k, _))| i == k)
+                                .map(|(_, (_, text))| text)
+                                .collect()
+                        }
+                        None => Vec::new(),
+                    };
+                let Some(first) = sig_lines.first() else {
+                    return Err(format!(
+                        "open {} to follow into `{callee}`",
+                        declared
+                            .path
+                            .file_name()
+                            .map(|n| n.to_string_lossy().into_owned())
+                            .unwrap_or_default()
+                    ));
+                };
+                let name_col =
+                    viewer::Col::from_offset(first, declared.character, client.encoding).0;
+                let (param, offset, param_col) =
+                    crate::flow::parameter_in(&sig_lines, name_col, argument, lang)
+                        .ok_or_else(|| format!("`{callee}` has no parameter {}", argument + 1))?;
+                let param_text = sig_lines[offset].clone();
+                let param_line = declared.line + offset;
+                let param_character =
+                    viewer::Col(param_col).to_offset(&param_text, client.encoding);
                 let refs = client
                     .navigate(
                         "textDocument/references",
                         &declared.path,
-                        declared.line,
+                        param_line,
                         param_character,
                     )
                     .await?;
@@ -587,7 +633,7 @@ impl App {
                         .enumerate()
                         .map(|(i, t)| (i, t.path.clone(), t.line))
                         .collect();
-                    read_location_previews(wanted)
+                    read_location_lines(wanted)
                 } else {
                     Vec::new()
                 };
@@ -595,10 +641,10 @@ impl App {
                     symbol: param,
                     declared: lsp::client::Target {
                         path: declared.path,
-                        line: declared.line,
+                        line: param_line,
                         character: param_character,
                     },
-                    decl_text: sig,
+                    decl_text: param_text,
                     refs,
                     texts,
                 })
@@ -686,6 +732,102 @@ impl App {
         Task::none()
     }
 
+    /// Follow the trace's occurrences in `path` to their lines in its new
+    /// `content` (`None`: the file is gone): each by its own line's text,
+    /// nearest where it was, so a row still opens where its line now is. An
+    /// occurrence whose line reads differently now is marked changed and the
+    /// trace stale — the tab offers to trace again.
+    pub(crate) fn reanchor_flow(&mut self, path: &Path, content: Option<&str>) {
+        let Some(lang) = self
+            .proj
+            .flow
+            .as_ref()
+            .filter(|t| t.depends_on(path))
+            .map(|t| t.lang)
+        else {
+            return;
+        };
+        let encoding = match self.proj.link.lsp.get(lang) {
+            Some(LspSlot::Ready(c)) => c.encoding,
+            _ => clew_core::lsp::client::PositionEncoding::Utf16,
+        };
+        let lines: Vec<&str> = content
+            .map(|c| c.lines().map(|l| l.trim_end_matches('\r')).collect())
+            .unwrap_or_default();
+        let Some(tree) = self.proj.flow.as_mut() else {
+            return;
+        };
+        let mut stale = false;
+        for node in tree.nodes.iter_mut().filter(|n| n.abs == path) {
+            let found = content
+                .filter(|_| node.classified)
+                .and_then(|_| crate::flow::moved_line(&lines, &node.text, node.line));
+            if let Some(line) = found {
+                let raw = lines[line];
+                let col =
+                    crate::flow::nearest_word(raw, &node.symbol, node.col).unwrap_or(node.col);
+                node.line = line;
+                node.col = col;
+                node.character = viewer::Col(col).to_offset(raw, encoding);
+                node.indent = raw.chars().take_while(|c| c.is_whitespace()).count();
+                node.changed = false;
+            } else {
+                node.changed = true;
+                stale = true;
+            }
+        }
+        tree.stale |= stale;
+    }
+
+    /// Trace the same identifier again from where it was asked for, found
+    /// in the file as it is now (nearest the line and column it was at).
+    fn retrace_flow(&mut self) -> Task<Message> {
+        let Some((path, line, col, symbol)) = self.proj.flow.as_ref().map(|t| {
+            (
+                t.origin.0.clone(),
+                t.origin.1,
+                t.origin_col,
+                t.symbol.clone(),
+            )
+        }) else {
+            return Task::none();
+        };
+        let Some(pane) = self
+            .proj
+            .panes
+            .iter()
+            .position(|p| p.as_ref().is_some_and(|v| v.abs == path))
+        else {
+            self.status = format!(
+                "Open {} to trace `{symbol}` again",
+                path.file_name()
+                    .map(|n| n.to_string_lossy().into_owned())
+                    .unwrap_or_default()
+            );
+            return Task::none();
+        };
+        let found = self.proj.panes[pane].as_ref().and_then(|v| {
+            let n = v.lines.len();
+            (0..n.max(line + 1)).find_map(|d| {
+                [line + d, line.wrapping_sub(d)]
+                    .into_iter()
+                    .filter(|&l| l < n)
+                    .find_map(|l| {
+                        v.source_line(l)
+                            .and_then(|text| crate::flow::nearest_word(text, &symbol, col))
+                            .map(|c| (l, c))
+                    })
+            })
+        });
+        match found {
+            Some((l, c)) => self.flow_at(pane, l, c),
+            None => {
+                self.status = format!("`{symbol}` is no longer in that file");
+                Task::none()
+            }
+        }
+    }
+
     pub(crate) fn update_flow(&mut self, message: FlowMsg) -> Task<Message> {
         match message {
             FlowMsg::FromMenu => {
@@ -712,6 +854,7 @@ impl App {
             FlowMsg::Expanded {
                 token, id, result, ..
             } => self.on_flow_expanded(token, id, result),
+            FlowMsg::Retrace => self.retrace_flow(),
             FlowMsg::Toggle { token, id } => {
                 if let Some(tree) = self.proj.flow.as_mut().filter(|t| t.token == token) {
                     tree.toggle(id);
diff --git a/src/app/glossary.rs b/src/app/glossary.rs
index 7fec929..19c3cf2 100644
--- a/src/app/glossary.rs
+++ b/src/app/glossary.rs
@@ -4,12 +4,15 @@
 //! or browsed as a whole (the Glossary page) without hunting for the
 //! declaration first.
 //!
-//! Definitions are the project's own words, never invented: a type's or an
-//! acronym's comes from the author's doc comment (the API-docs index, as
-//! the DOCS tab shows it), a module's or folder's from clew's cached
-//! explanation of that file or folder (Explain All). A name with neither is
-//! not a term — a glossary is definitions, and the DOCS tab already lists
-//! every declaration.
+//! Definitions are the project's own words, never invented: a type's comes
+//! from the author's doc comment (the API-docs index, as the DOCS tab shows
+//! it), an acronym's from where the docs spell it out — "Debug Adapter
+//! Protocol (DAP)" or "LSP (Language Server Protocol)", the initials
+//! matching — and a module's or folder's from clew's cached explanation of
+//! that file or folder (Explain All). A name with none of these is not a
+//! term — a glossary is definitions, and the DOCS tab already lists every
+//! declaration. An all-caps name is no acronym by itself: `MAX` and
+//! `SYSTEM` are constants.
 
 use crate::app::prelude::*;
 use crate::*;
@@ -21,8 +24,7 @@ pub(crate) enum TermKind {
     Type,
     /// A source file or a folder — named by its module label / path.
     Module,
-    /// An all-caps name (`LSP`, `DAP`, `RPC`): a constant, a type or a
-    /// function, documented.
+    /// An abbreviation the docs spell out (`DAP`: Debug Adapter Protocol).
     Acronym,
 }
 
@@ -96,7 +98,7 @@ impl Glossary {
         let mut terms: Vec<Term> = Vec::new();
         for file in files {
             for item in &file.items {
-                collect_items(item, &file.rel, &mut terms);
+                collect_items(item, None, &file.rel, &mut terms);
             }
         }
         if let Some(root) = root {
@@ -144,6 +146,13 @@ impl Glossary {
                 .then_with(|| a.line.cmp(&b.line))
         });
         terms.dedup();
+        // An acronym spelled out in several places is one term (its first
+        // place); two different expansions stay two (and ambiguous).
+        let mut spelled: HashSet<(String, String)> = HashSet::new();
+        terms.retain(|t| {
+            t.kind != TermKind::Acronym
+                || spelled.insert((t.name.clone(), t.definition.to_lowercase()))
+        });
         let mut unique: HashMap<String, usize> = HashMap::new();
         let mut ambiguous: HashSet<String> = HashSet::new();
         for (i, t) in terms.iter().enumerate() {
@@ -197,34 +206,148 @@ impl Glossary {
 
 /// Walk `item` and its children (a nested class, an impl's associated
 /// types) for the terms they define.
-fn collect_items(item: &clew_protocol::DocItem, rel: &str, out: &mut Vec<Term>) {
-    let kind = if crate::typegraph::TYPE_KINDS.contains(&item.kind.as_str()) {
-        Some(TermKind::Type)
-    } else if is_acronym(&item.name) {
-        Some(TermKind::Acronym)
-    } else {
-        None
-    };
-    if let Some(kind) = kind
+fn collect_items(
+    item: &clew_protocol::DocItem,
+    parent_kind: Option<&str>,
+    rel: &str,
+    out: &mut Vec<Term>,
+) {
+    // A type declared in a function body is that function's, not the project's.
+    let local = parent_kind.is_some_and(crate::typegraph::is_callable_kind);
+    if crate::typegraph::TYPE_KINDS.contains(&item.kind.as_str())
+        && !local
         && let Some(definition) = definition_of(&item.doc)
     {
         out.push(Term {
             name: item.name.clone(),
-            kind,
+            kind: TermKind::Type,
             badge: item.kind.clone(),
             rel: rel.to_string(),
             line: item.line,
             definition,
         });
     }
+    for (abbr, long) in acronyms_in(&item.doc) {
+        out.push(Term {
+            name: abbr,
+            kind: TermKind::Acronym,
+            badge: "acronym".into(),
+            rel: rel.to_string(),
+            line: item.line,
+            definition: long,
+        });
+    }
     for child in &item.children {
-        collect_items(child, rel, out);
+        collect_items(child, Some(&item.kind), rel, out);
+    }
+}
+
+/// The words that may sit inside a spelled-out acronym without a letter of
+/// their own ("Bring Your Own Key", "Line of Business").
+const ACRONYM_FILLERS: &[&str] = &["of", "and", "the", "for", "to", "in", "on", "a", "an", "&"];
+
+/// Every acronym `doc` spells out, with its expansion: "Long Form (ABBR)" or
+/// "ABBR (Long Form)", where the long form's initials are the acronym's
+/// capitals in order (filler words aside). "The debugger (DAP)" spells
+/// nothing out; neither does "UI (it goes in the status bar)".
+pub(crate) fn acronyms_in(doc: &str) -> Vec<(String, String)> {
+    let flat = strip_inline_markup(&doc.split_whitespace().collect::<Vec<_>>().join(" "));
+    let mut found: Vec<(String, String)> = Vec::new();
+    let mut rest = flat.as_str();
+    let mut before = String::new();
+    while let Some(open) = rest.find('(') {
+        let Some(len) = rest[open..].find(')') else {
+            break;
+        };
+        let head = &rest[..open];
+        let inner = rest[open + 1..open + len].trim();
+        before.push_str(head);
+        let words_before: Vec<&str> = before.split_whitespace().collect();
+        // "Long Form (ABBR)".
+        if is_acronym(inner)
+            && let Some(long) = spelled_out(inner, &words_before, true)
+        {
+            found.push((inner.to_string(), long));
+        }
+        // "ABBR (Long Form)".
+        if let Some(abbr) = words_before
+            .last()
+            .map(|w| w.trim_matches(|c: char| !c.is_alphanumeric()))
+            && is_acronym(abbr)
+        {
+            let words: Vec<&str> = inner.split_whitespace().collect();
+            if let Some(long) = spelled_out(abbr, &words, false)
+                && long.split_whitespace().count() == words.len()
+            {
+                found.push((abbr.to_string(), long));
+            }
+        }
+        before.push_str(&rest[open..open + len + 1]);
+        rest = &rest[open + len + 1..];
+    }
+    found
+}
+
+/// The words of `words` that spell `abbr` out: its capitals are the initials
+/// of consecutive words, fillers aside — the last words when `from_end`
+/// ("Long Form (ABBR)"), the first otherwise ("ABBR (Long Form)").
+fn spelled_out(abbr: &str, words: &[&str], from_end: bool) -> Option<String> {
+    let letters: Vec<char> = abbr
+        .chars()
+        .filter(|c| c.is_ascii_uppercase())
+        .map(|c| c.to_ascii_lowercase())
+        .collect();
+    let clean = |w: &str| {
+        w.trim_matches(|c: char| !(c.is_alphanumeric() || c == '-' || c == '&'))
+            .to_string()
+    };
+    let mut taken: Vec<String> = Vec::new();
+    let mut want = letters.len();
+    let ordered: Vec<&str> = if from_end {
+        words.iter().rev().copied().collect()
+    } else {
+        words.to_vec()
+    };
+    for w in ordered {
+        if want == 0 {
+            break;
+        }
+        let word = clean(w);
+        // A hyphenated word gives an initial per part ("Just-In-Time").
+        let parts: Vec<&str> = word.split('-').filter(|p| !p.is_empty()).collect();
+        let initials: Vec<char> = parts
+            .iter()
+            .filter_map(|p| p.chars().next())
+            .map(|c| c.to_ascii_lowercase())
+            .collect();
+        let needed: Vec<char> = if from_end {
+            letters[want.saturating_sub(initials.len())..want].to_vec()
+        } else {
+            let done = letters.len() - want;
+            letters[done..(done + initials.len()).min(letters.len())].to_vec()
+        };
+        if !initials.is_empty() && initials == needed {
+            want -= initials.len();
+            taken.push(word);
+        } else if !taken.is_empty() && ACRONYM_FILLERS.contains(&word.to_lowercase().as_str()) {
+            taken.push(word);
+        } else {
+            return None;
+        }
     }
+    if want != 0 {
+        return None;
+    }
+    if from_end {
+        taken.reverse();
+    }
+    Some(taken.join(" "))
 }
 
-/// Whether `name` reads as an acronym: two to eight characters, all upper
-/// case letters or digits, at least two letters (`LSP`, `DAP`, `HTTP2`;
-/// not `A`, `V2`, `MAX_LEN`).
+/// Whether `name` is shaped like an acronym: two to eight characters, all
+/// upper case letters or digits, at least two letters (`LSP`, `DAP`,
+/// `HTTP2`; not `A`, `V2`, `MAX_LEN`). The shape alone makes no term: it is
+/// only an acronym where the docs spell it out ([`acronyms_in`]).
 pub(crate) fn is_acronym(name: &str) -> bool {
     let n = name.chars().count();
     (2..=8).contains(&n)
@@ -346,20 +469,24 @@ fn first_sentence(s: &str) -> String {
 fn strip_inline_markup(s: &str) -> String {
     let mut out = String::with_capacity(s.len());
     let mut rest = s;
+    // Links to their text: `[text](url)`, a reference `[text][ref]`, and a
+    // rustdoc intra-doc link `[path]` / `[`path`]`, whose text is the path.
     while let Some(open) = rest.find('[') {
         let (before, from_open) = rest.split_at(open);
         out.push_str(before);
-        match from_open.find("](") {
-            Some(close) if from_open[close..].contains(')') => {
-                out.push_str(&from_open[1..close]);
-                let after = from_open[close..].find(')').unwrap_or(0);
-                rest = &from_open[close + after + 1..];
-            }
-            _ => {
-                out.push('[');
-                rest = &from_open[1..];
-            }
-        }
+        let Some(close) = from_open.find(']') else {
+            out.push_str(from_open);
+            rest = "";
+            break;
+        };
+        out.push_str(&from_open[1..close]);
+        let after = &from_open[close + 1..];
+        let skip = match after.chars().next() {
+            Some('(') => after.find(')').map(|e| e + 1),
+            Some('[') => after.find(']').map(|e| e + 1),
+            _ => None,
+        };
+        rest = &after[skip.unwrap_or(0)..];
     }
     out.push_str(rest);
     let out: String = out.chars().filter(|c| !matches!(c, '`' | '*')).collect();
@@ -481,6 +608,68 @@ mod glossary_tests {
         assert!(d.ends_with('…'));
     }
 
+    #[test]
+    fn acronyms_are_where_the_docs_spell_them_out() {
+        let pairs = |doc: &str| acronyms_in(doc);
+        assert_eq!(
+            pairs("Talks the Debug Adapter Protocol (DAP) to the adapter."),
+            [("DAP".to_string(), "Debug Adapter Protocol".to_string())]
+        );
+        assert_eq!(
+            pairs("Asks the LSP (Language Server Protocol) server."),
+            [("LSP".to_string(), "Language Server Protocol".to_string())]
+        );
+        assert_eq!(
+            pairs("Identified by its Stock Keeping Unit (SKU)."),
+            [("SKU".to_string(), "Stock Keeping Unit".to_string())]
+        );
+        assert_eq!(
+            pairs("Bring Your Own Key (BYOK), and a Line of Business (LOB) report"),
+            [
+                ("BYOK".to_string(), "Bring Your Own Key".to_string()),
+                ("LOB".to_string(), "Line of Business".to_string()),
+            ]
+        );
+        assert_eq!(
+            pairs("Compiled Just-In-Time (JIT)."),
+            [("JIT".to_string(), "Just-In-Time".to_string())]
+        );
+        // Spelled across a wrapped doc comment, with markup.
+        assert_eq!(
+            pairs("the `Debug\nAdapter` **Protocol** (DAP)"),
+            [("DAP".to_string(), "Debug Adapter Protocol".to_string())]
+        );
+        for nothing in [
+            "The debugger (DAP) runs.",
+            "UI (it goes in the status bar)",
+            "Counts (2) of them",
+            "A constant, SYSTEM.",
+            "",
+        ] {
+            assert!(
+                pairs(nothing).is_empty(),
+                "{nothing:?}: {:?}",
+                pairs(nothing)
+            );
+        }
+    }
+
+    #[test]
+    fn links_read_as_their_text() {
+        assert_eq!(
+            definition_of("Dropped before [Abandon::keep] — see [`lookup`]."),
+            Some("Dropped before Abandon::keep — see lookup".into())
+        );
+        assert_eq!(
+            definition_of("Wraps a [client][c] and a [server](https://x) here."),
+            Some("Wraps a client and a server here".into())
+        );
+        assert_eq!(
+            definition_of("An [a] and a [b](u) together."),
+            Some("An a and a b together".into())
+        );
+    }
+
     #[test]
     fn acronyms_are_short_all_caps_names() {
         for yes in ["LSP", "DAP", "HTTP2", "IO", "UUID"] {
@@ -500,8 +689,24 @@ mod glossary_tests {
                 items: vec![
                     item("Client", "struct", "A connection to one server.", 10),
                     item("undocumented", "struct", "", 20),
-                    item("RPC", "const", "Remote procedure call framing.", 30),
+                    item(
+                        "SYSTEM",
+                        "constant",
+                        "The system prompt. An all-caps name is no acronym.",
+                        25,
+                    ),
+                    item(
+                        "frame",
+                        "function",
+                        "Frames a Remote Procedure Call (RPC) for the wire.",
+                        30,
+                    ),
                     item("connect", "function", "Opens a client. Not a term.", 40),
+                    {
+                        let mut run = item("run", "function", "", 45);
+                        run.children = vec![item("Local", "struct", "A helper of run.", 46)];
+                        run
+                    },
                     {
                         let mut outer = item("Outer", "class", "", 50);
                         outer.children = vec![item("Inner", "enum", "Nested state.", 52)];
@@ -511,7 +716,16 @@ mod glossary_tests {
             },
             DocFile {
                 rel: "src/other.rs".into(),
-                items: vec![item("Client", "struct", "Another one.", 3)],
+                items: vec![
+                    item("Client", "struct", "Another one.", 3),
+                    // The same spelling elsewhere is the same term.
+                    item(
+                        "send",
+                        "function",
+                        "Sends a remote procedure call (RPC).",
+                        9,
+                    ),
+                ],
             },
         ];
         let mut cache = explain::Cache::new();
@@ -561,9 +775,14 @@ mod glossary_tests {
         // A name defined twice is ambiguous: not looked up. The rest are.
         assert!(g.lookup("Client").is_none());
         let rpc = g.lookup("RPC").unwrap();
-        assert_eq!(rpc.definition, "Remote procedure call framing");
-        assert_eq!(rpc.badge, "const");
+        assert_eq!(rpc.definition, "Remote Procedure Call");
+        assert_eq!(rpc.badge, "acronym");
         assert_eq!((rpc.rel.as_str(), rpc.line), ("src/net/client.rs", 30));
+        assert!(g.lookup("SYSTEM").is_none(), "a constant is no acronym");
+        assert!(
+            g.lookup("Local").is_none(),
+            "a function's own type is no term"
+        );
         assert_eq!(
             g.lookup("Inner").unwrap().peek_line(),
             "Inner: Nested state — src/net/client.rs:52"
diff --git a/src/app/message.rs b/src/app/message.rs
index e3054c2..21b35f0 100644
--- a/src/app/message.rs
+++ b/src/app/message.rs
@@ -1862,6 +1862,8 @@ pub enum FlowMsg {
     },
     /// Fold or unfold a node with children.
     Toggle { token: u64, id: usize },
+    /// Trace the same identifier again, after a traced file changed.
+    Retrace,
     /// Forget the trace.
     Clear,
 }
@@ -1878,6 +1880,7 @@ impl FlowMsg {
             | FlowMsg::AtCursor
             | FlowMsg::Expand { .. }
             | FlowMsg::Toggle { .. }
+            | FlowMsg::Retrace
             | FlowMsg::Clear => None,
         }
     }
@@ -2058,6 +2061,13 @@ pub enum ExportMsg {
     Start,
     /// The save dialog closed: the path picked, or `None` for cancelled.
     Picked(Option<PathBuf>),
+    /// Check again whether the docs index the glossary needs is in, before
+    /// writing to `path` (`waited` checks so far).
+    Ready {
+        stamp: Stamp,
+        path: PathBuf,
+        waited: u32,
+    },
     /// The file was written (or not).
     Written {
         stamp: Stamp,
@@ -2071,7 +2081,9 @@ impl ExportMsg {
     /// new variant cannot compile until it is classified here.
     pub fn origin(&self) -> Option<Origin<'_>> {
         match self {
-            ExportMsg::Written { stamp, .. } => Some(Origin::Stamped(stamp)),
+            ExportMsg::Written { stamp, .. } | ExportMsg::Ready { stamp, .. } => {
+                Some(Origin::Stamped(stamp))
+            }
             ExportMsg::Start | ExportMsg::Picked(..) => None,
         }
     }
diff --git a/src/app/navigation.rs b/src/app/navigation.rs
index 967660c..42e5076 100644
--- a/src/app/navigation.rs
+++ b/src/app/navigation.rs
@@ -25,6 +25,16 @@ use crate::*;
 pub(crate) fn read_location_previews(
     targets: Vec<(usize, PathBuf, usize)>,
 ) -> Vec<(usize, String)> {
+    read_location_lines(targets)
+        .into_iter()
+        .map(|(i, line)| (i, line.trim().to_string()))
+        .collect()
+}
+
+/// [`read_location_previews`], each line as the file has it: untrimmed, so a
+/// column the language server gives for it lands where it points (a trimmed
+/// line shifts every column by the indentation). A trailing `\r` is dropped.
+pub(crate) fn read_location_lines(targets: Vec<(usize, PathBuf, usize)>) -> Vec<(usize, String)> {
     // Per file, the (line, hit index) pairs wanted from it, in line order.
     let mut by_file: HashMap<PathBuf, Vec<(usize, usize)>> = HashMap::new();
     for (i, path, line) in targets {
@@ -51,7 +61,7 @@ pub(crate) fn read_location_previews(
                 continue;
             }
             while let Some(&(_, i)) = next.next_if(|(line, _)| *line == n) {
-                out.push((i, text_line.trim().to_string()));
+                out.push((i, text_line.trim_end_matches('\r').to_string()));
             }
         }
     }
diff --git a/src/app/tasks.rs b/src/app/tasks.rs
index 7827fdf..e346777 100644
--- a/src/app/tasks.rs
+++ b/src/app/tasks.rs
@@ -3043,17 +3043,22 @@ pub(crate) fn pick_file(window: Option<iced::window::Id>) -> Task<Option<PathBuf
 }
 
 /// Native save dialog for a Markdown export (the ⋯ menu's Export row), in a
-/// sheet on `window`, proposing `file_name`.
+/// sheet on `window`, proposing `file_name` in `folder`.
 pub(crate) fn save_markdown(
     window: Option<iced::window::Id>,
     file_name: String,
+    folder: Option<PathBuf>,
 ) -> Task<Option<PathBuf>> {
     picker(window, move |dialog| {
-        dialog
+        let dialog = dialog
             .set_title("Export reading notes")
             .set_file_name(file_name)
-            .add_filter("Markdown", &["md"])
-            .save_file()
+            .add_filter("Markdown", &["md"]);
+        match folder {
+            Some(folder) => dialog.set_directory(folder),
+            None => dialog,
+        }
+        .save_file()
     })
 }
 
diff --git a/src/app/tests.rs b/src/app/tests.rs
index 1541079..0baa679 100644
--- a/src/app/tests.rs
+++ b/src/app/tests.rs
@@ -11549,6 +11549,39 @@ enum StubAnswers {
     LoadsOn(u64),
     /// The connection closed at the prepare on this line: the server gone.
     HangsUpOn(u64),
+    /// Definitions and references as the script says, and nothing else;
+    /// the positions each was asked at are noted in it.
+    Navigates(&'static NavScript),
+}
+
+/// What a navigating stub server ([`StubAnswers::Navigates`]) answers, and
+/// where it was asked: `(method, line, character)`.
+struct NavScript {
+    definition: serde_json::Value,
+    references: serde_json::Value,
+    asked: std::sync::Mutex<Vec<(String, u64, u64)>>,
+}
+
+impl NavScript {
+    /// A script, leaked for the stub's `'static` borrow (one per test).
+    fn leak(definition: serde_json::Value, references: serde_json::Value) -> &'static NavScript {
+        Box::leak(Box::new(NavScript {
+            definition,
+            references,
+            asked: Default::default(),
+        }))
+    }
+
+    /// Where `method` was asked, in order.
+    fn asked_at(&self, method: &str) -> Vec<(u64, u64)> {
+        self.asked
+            .lock()
+            .unwrap()
+            .iter()
+            .filter(|(m, ..)| m == method)
+            .map(|&(_, l, c)| (l, c))
+            .collect()
+    }
 }
 
 /// Each request a stub language server was asked, and each request it was
@@ -11755,6 +11788,23 @@ async fn started_stub_lsp_server(
                             let _ = peer_tx.lock().await.shutdown().await;
                             return;
                         }
+                        (
+                            "textDocument/definition" | "textDocument/references",
+                            StubAnswers::Navigates(script),
+                        ) => {
+                            let at = &msg["params"]["position"];
+                            script.asked.lock().unwrap().push((
+                                method.to_string(),
+                                at["line"].as_u64().unwrap_or(0),
+                                at["character"].as_u64().unwrap_or(0),
+                            ));
+                            let result = if method == "textDocument/definition" {
+                                script.definition.clone()
+                            } else {
+                                script.references.clone()
+                            };
+                            serde_json::json!({ "jsonrpc": "2.0", "id": id, "result": result })
+                        }
                         _ => serde_json::json!({ "jsonrpc": "2.0", "id": id, "result": null }),
                     };
                     if send(peer_tx.clone(), reply).await.is_err() {
@@ -17418,6 +17468,11 @@ fn stamped_samples(app: &App, stamp: &Stamp) -> Vec<Message> {
             path: root.join("notes.md"),
             result: Ok(()),
         }),
+        Message::Export(ExportMsg::Ready {
+            stamp: s(),
+            path: root.join("notes.md"),
+            waited: 1,
+        }),
         Message::Editor(EditorMsg::FileLoaded {
             stamp: s(),
             req: 1,
@@ -27025,7 +27080,7 @@ fn export_notes_writes_the_markdown_where_picked() {
         "{written}"
     );
     assert!(
-        written.contains("- `src/lib.rs` · **origin** ✓ understood\n  > returns the origin\n"),
+        written.contains("- `src/lib.rs` · `origin` ✓ understood\n  > returns the origin\n"),
         "{written}"
     );
     assert!(
@@ -27059,3 +27114,236 @@ fn export_notes_writes_the_markdown_where_picked() {
     }
     assert!(app.status.starts_with("Export failed: "), "{}", app.status);
 }
+
+/// Following a value into a callee works on the code as rustfmt writes it:
+/// a `pub(crate)` before the name and the parameters one per line, in a file
+/// no pane shows (its lines read raw off disk, so the server's columns land
+/// where they point). The callee is looked up at its own column on the
+/// call's line, and the parameter's references at the parameter's own line.
+#[tokio::test(flavor = "multi_thread")]
+async fn following_a_value_reads_a_wrapped_signature_from_disk() {
+    use crate::app::flow::Role;
+    let mut app = scanned_app("flow-wrapped-signature");
+    let root = app.proj.project.as_ref().unwrap().root.clone();
+    let shop = root.join("src/shop.rs");
+    std::fs::write(
+        &shop,
+        "pub(crate) fn save_markdown(\n    window: Option<u32>,\n    file_name: String,\n) -> String {\n    file_name\n}\n\nfn start() {\n        let file_name = String::new();\n        save_markdown(None, file_name);\n}\n",
+    )
+    .unwrap();
+    let uri = format!("file://{}", shop.display());
+    let at = |line: u64, character: u64| {
+        serde_json::json!({
+            "uri": uri,
+            "range": {
+                "start": { "line": line, "character": character },
+                "end": { "line": line, "character": character + 1 },
+            },
+        })
+    };
+    let script = NavScript::leak(
+        serde_json::json!([at(0, 14)]),
+        serde_json::json!([at(2, 4), at(4, 4)]),
+    );
+    let client = stub_lsp_client(&root, StubAnswers::Navigates(script)).await;
+    app.proj
+        .link
+        .lsp
+        .insert("rust".into(), LspSlot::Ready(client));
+
+    let target = |line: usize, character: usize| lsp::client::Target {
+        path: shop.clone(),
+        line,
+        character,
+    };
+    app.flow_token += 1;
+    let token = app.flow_token;
+    app.proj.flow_pending = Some(token);
+    app.proj.flow = Some(crate::app::flow::FlowTree::new(
+        token,
+        "file_name".into(),
+        "rust",
+        (shop.clone(), 8),
+    ));
+    let task = app.on_flow_found(
+        token,
+        "file_name".into(),
+        Ok((vec![target(8, 12)], vec![target(9, 28)])),
+    );
+    for msg in run_task_async(task).await {
+        let _ = app.update(msg);
+    }
+    let tree = app.proj.flow.as_ref().unwrap();
+    assert_eq!(tree.node(0).role, Role::Declared);
+    let passed = tree.node(1);
+    assert_eq!(passed.role, Role::Passed, "{passed:?}");
+    assert_eq!(passed.detail, "save_markdown");
+    assert_eq!(passed.argument, Some(1));
+    assert_eq!(passed.indent, 8);
+
+    let task = app.on_flow_expand(token, 1);
+    for msg in run_task_async(task).await {
+        let _ = app.update(msg);
+    }
+    assert_eq!(
+        script.asked_at("textDocument/definition"),
+        [(9, 8)],
+        "the callee is looked up at its own column"
+    );
+    assert_eq!(
+        script.asked_at("textDocument/references"),
+        [(2, 4)],
+        "the parameter is on the third line of the declaration"
+    );
+    let tree = app.proj.flow.as_ref().unwrap();
+    let kids = tree
+        .node(1)
+        .children
+        .clone()
+        .expect("followed into the callee");
+    let param = tree.node(kids[0]);
+    assert_eq!(
+        (param.role, param.symbol.as_str()),
+        (Role::Parameter, "file_name")
+    );
+    assert_eq!(param.line, 2);
+    assert_eq!(param.text, "file_name: String,");
+    assert_eq!(tree.node(kids[1]).text, "file_name");
+}
+
+/// A value trace follows its file's edits: each occurrence moves to where
+/// its line went; one whose line is gone is marked changed and the trace
+/// stale, and "trace again" traces the same name where it now is.
+#[test]
+fn a_value_trace_follows_its_lines_when_the_file_changes() {
+    use crate::app::flow::Role;
+    let mut app = scanned_app("flow-reanchor");
+    let root = app.proj.project.as_ref().unwrap().root.clone();
+    let lib = root.join("src/lib.rs");
+    let target = |line: usize, character: usize| lsp::client::Target {
+        path: lib.clone(),
+        line,
+        character,
+    };
+    app.flow_token += 1;
+    let token = app.flow_token;
+    app.proj.flow_pending = Some(token);
+    app.proj.flow = Some(crate::app::flow::FlowTree::new(
+        token,
+        "total".into(),
+        "rust",
+        (lib.clone(), 0),
+    ));
+    let _ = app.on_flow_found(
+        token,
+        "total".into(),
+        Ok((vec![target(0, 4)], vec![target(1, 11), target(2, 4)])),
+    );
+    let _ = app.on_flow_lines(
+        token,
+        vec![
+            (0, "let total = 1;".into()),
+            (1, "    render(total);".into()),
+            (2, "    total.round()".into()),
+        ],
+    );
+    // Two lines are inserted above; the render call is rewritten.
+    let edited = "// one\n// two\nlet total = 1;\n    draw(total);\n    total.round()\n";
+    app.reanchor_flow(&lib, Some(edited));
+    let tree = app.proj.flow.as_ref().unwrap();
+    assert_eq!((tree.node(0).line, tree.node(0).changed), (2, false));
+    assert_eq!((tree.node(2).line, tree.node(2).changed), (4, false));
+    assert_eq!(tree.node(2).character, 4);
+    assert!(tree.node(1).changed, "its line reads differently now");
+    assert!(tree.stale);
+    assert_eq!(tree.node(1).role, Role::Passed, "the row keeps what it was");
+    // Another file's change leaves the trace alone.
+    app.reanchor_flow(&root.join("src/other.rs"), Some(""));
+    assert_eq!(app.proj.flow.as_ref().unwrap().node(0).line, 2);
+    // The file deleted: every occurrence in it is changed.
+    app.reanchor_flow(&lib, None);
+    let tree = app.proj.flow.as_ref().unwrap();
+    assert!((0..3).all(|id| tree.node(id).changed));
+
+    // Trace again: the name is looked for where the trace began, in the
+    // file as a pane shows it now — found two lines down, so the trace is
+    // asked for there (and wants a language server).
+    std::fs::write(&lib, edited).unwrap();
+    open_synchronously(&mut app, "src/lib.rs", None);
+    let _ = app.update(Message::Flow(FlowMsg::Retrace));
+    assert!(app.status.contains("server ready"), "{}", app.status);
+    // Gone from the file (the pane reloaded as the watcher reloads it): said so.
+    let gone = "fn nothing() {}\n";
+    if let Some(v) = app.proj.panes[app.proj.active].as_mut() {
+        v.reload(
+            Arc::new(gone.to_string()),
+            crate::highlight::plain_lines(gone),
+        );
+    }
+    let _ = app.update(Message::Flow(FlowMsg::Retrace));
+    assert_eq!(app.status, "`total` is no longer in that file");
+}
+
+/// An export waits for a docs build in flight, so its glossary is the
+/// project's (the index is built on demand, and the export started it): the
+/// write happens once the index is in — or, past the bound, with what there
+/// is, never not at all.
+#[test]
+fn an_export_waits_for_the_docs_index_its_glossary_needs() {
+    let mut app = scanned_app("export-waits-for-docs");
+    let root = app.proj.project.as_ref().unwrap().root.clone();
+    app.proj.link.pending_docs = Some(app.mint_request_id());
+    let path = root.join("notes.md");
+    let sent = run_task(app.update(Message::Export(ExportMsg::Picked(Some(path.clone())))));
+    let [ready @ Message::Export(ExportMsg::Ready { waited: 1, .. })] = sent.as_slice() else {
+        panic!("waits for the docs: {sent:?}");
+    };
+    assert!(!path.exists(), "nothing written yet");
+    assert!(
+        app.status.contains("waiting for the docs index"),
+        "{}",
+        app.status
+    );
+
+    let _ = app.apply_docs(vec![clew_protocol::DocFile {
+        rel: "src/lib.rs".into(),
+        items: vec![clew_protocol::DocItem {
+            name: "Point".into(),
+            kind: "struct".into(),
+            signature: "pub struct Point".into(),
+            doc: "A point on the plane.".into(),
+            line: 1,
+            public: true,
+            children: Vec::new(),
+            refs: Vec::new(),
+        }],
+    }]);
+    let written = run_task(app.update(ready.clone()));
+    assert!(
+        matches!(
+            written.as_slice(),
+            [Message::Export(ExportMsg::Written { result: Ok(()), .. })]
+        ),
+        "{written:?}"
+    );
+    let text = std::fs::read_to_string(&path).unwrap();
+    assert!(
+        text.contains("- **`Point`** (struct) — A point on the plane · `src/lib.rs:1`"),
+        "{text}"
+    );
+
+    // A build that never ends does not hold the export forever.
+    app.proj.link.pending_docs = Some(app.mint_request_id());
+    let late = run_task(app.update(Message::Export(ExportMsg::Ready {
+        stamp: app.stamp(),
+        path: root.join("late.md"),
+        waited: crate::app::export::DOCS_WAITS,
+    })));
+    assert!(
+        matches!(
+            late.as_slice(),
+            [Message::Export(ExportMsg::Written { result: Ok(()), .. })]
+        ),
+        "{late:?}"
+    );
+}
diff --git a/src/app/watch.rs b/src/app/watch.rs
index 2575fbd..7b32fe8 100644
--- a/src/app/watch.rs
+++ b/src/app/watch.rs
@@ -257,9 +257,12 @@ impl App {
                     // Resync the language server's copy whether or not a pane
                     // still shows the file (see `resync_open_doc` for why).
                     self.resync_open_doc(&c.path, &c.content);
+                    // A value trace through this file follows its lines.
+                    self.reanchor_flow(&c.path, Some(c.content.as_str()));
                 }
                 watch::FileEvent::Deleted(path) => {
                     touched.push(path.clone());
+                    self.reanchor_flow(&path, None);
                     structural = true;
                     deleted = true;
                     self.proj.registry.remove(&path);
diff --git a/src/editor/flow.rs b/src/editor/flow.rs
index f54610f..c2d79b7 100644
--- a/src/editor/flow.rs
+++ b/src/editor/flow.rs
@@ -94,7 +94,19 @@ pub struct Use {
 
 const KEYWORDS_BEFORE_PAREN: &[&str] = &[
     "if", "while", "for", "match", "switch", "return", "elif", "catch", "except", "foreach",
-    "until", "unless", "case", "with", "and", "or", "not", "in", "await", "yield", "let", "print",
+    "until", "unless", "case", "with", "and", "or", "not", "in", "await", "yield", "let",
+];
+
+/// The keywords of [`KEYWORDS_BEFORE_PAREN`] whose parenthesis is a
+/// condition: a value inside it is branched on.
+const BRANCH_KEYWORDS: &[&str] = &[
+    "if", "while", "for", "match", "switch", "elif", "catch", "except", "foreach", "until",
+    "unless", "case",
+];
+
+/// The operators that assign to a name that already holds a value.
+const COMPOUND_ASSIGNMENTS: &[&str] = &[
+    "+=", "-=", "*=", "/=", "%=", "|=", "&=", "^=", "<<=", ">>=", "??=", "||=", "&&=", "**=", "//=",
 ];
 
 const DECLARATION_WORDS: &[&str] = &[
@@ -134,9 +146,7 @@ pub fn classify(line: &str, col: usize, word: &str) -> Use {
         if a.starts_with(":=") {
             return Some(":=");
         }
-        for op in [
-            "+=", "-=", "*=", "/=", "%=", "|=", "&=", "^=", "<<=", ">>=", "??=", "||=", "&&=",
-        ] {
+        for &op in COMPOUND_ASSIGNMENTS {
             if a.starts_with(op) {
                 return Some(op);
             }
@@ -204,26 +214,31 @@ pub fn classify(line: &str, col: usize, word: &str) -> Use {
             callee: None,
         };
     }
-    // Returned.
     let first_word = line
         .trim_start()
         .split(|c: char| !(c.is_alphanumeric() || c == '_'))
         .next()
         .unwrap_or("");
-    if first_word == "return" || first_word == "yield" {
-        return plain(Role::Returned);
-    }
-    // Passed to a call.
+    // Passed to a call — asked before `return`: in `return f(x)` it is `f`
+    // that receives the value, and what is returned is `f`'s.
     if let Some((callee, index, callee_col)) = call_before(&chars, col) {
-        if KEYWORDS_BEFORE_PAREN.contains(&callee.as_str()) {
-            return plain(Role::Branched);
+        match callee.as_str() {
+            c if BRANCH_KEYWORDS.contains(&c) => return plain(Role::Branched),
+            "return" | "yield" => return plain(Role::Returned),
+            c if KEYWORDS_BEFORE_PAREN.contains(&c) => {}
+            _ => {
+                return Use {
+                    role: Role::Passed,
+                    detail: callee.clone(),
+                    argument: Some(index),
+                    callee: Some((callee, callee_col)),
+                };
+            }
         }
-        return Use {
-            role: Role::Passed,
-            detail: callee.clone(),
-            argument: Some(index),
-            callee: Some((callee, callee_col)),
-        };
+    }
+    // Returned.
+    if first_word == "return" || first_word == "yield" {
+        return plain(Role::Returned);
     }
     // Branched on.
     if matches!(
@@ -421,10 +436,180 @@ pub fn parameter_at(signature: &str, index: usize, lang: &str) -> Option<(String
     None
 }
 
+/// Whether `line` assigns to `word` (at char column `col`) with an operator
+/// that needs a value there already (`+=`, `-=`, …): a reassignment, even
+/// where the language server lists the line among the name's definitions,
+/// as Python's does for every assignment.
+pub fn reassigns(line: &str, col: usize, word: &str) -> bool {
+    let after: String = line
+        .chars()
+        .skip(col.saturating_add(word.chars().count()))
+        .collect();
+    let after = after.trim_start();
+    COMPOUND_ASSIGNMENTS.iter().any(|op| after.starts_with(op))
+}
+
+/// The `index`-th (0-based) parameter of the declaration whose name starts
+/// at char column `name_col` of `lines[0]`, where the parameter list may run
+/// over the following lines (`fn f(\n    a: A,\n    b: B,\n)`): its
+/// name, the line it is on (an offset into `lines`) and its char column on
+/// that line. The search starts at the name, so a `pub(crate)` or a Go
+/// receiver before it is not taken for the parameter list.
+pub fn parameter_in(
+    lines: &[String],
+    name_col: usize,
+    index: usize,
+    lang: &str,
+) -> Option<(String, usize, usize)> {
+    let first = lines.first()?;
+    let head: String = first.chars().skip(name_col).collect();
+    let mut joined = head;
+    for l in &lines[1..] {
+        joined.push('\n');
+        joined.push_str(l);
+    }
+    let (name, col) = parameter_at(&joined, index, lang)?;
+    // Back from a column of `joined` to a line and a column on it.
+    let before: Vec<char> = joined.chars().take(col).collect();
+    let line = before.iter().filter(|&&c| c == '\n').count();
+    let on_line = match before.iter().rposition(|&c| c == '\n') {
+        Some(nl) => col - nl - 1,
+        None => col + name_col,
+    };
+    Some((name, line, on_line))
+}
+
+/// The line of `lines` whose trimmed text is `text`, nearest to `old`: where
+/// a traced occurrence's line went after the file changed. `None` when no
+/// line reads so any more.
+pub fn moved_line<S: AsRef<str>>(lines: &[S], text: &str, old: usize) -> Option<usize> {
+    let text = text.trim();
+    if text.is_empty() {
+        return None;
+    }
+    let n = lines.len();
+    let is = |i: usize| lines[i].as_ref().trim() == text;
+    (0..n.max(old + 1)).find_map(|d| {
+        let below = old + d;
+        if below < n && is(below) {
+            return Some(below);
+        }
+        old.checked_sub(d).filter(|&above| above < n && is(above))
+    })
+}
+
+/// The char column of the whole-word occurrence of `word` in `line` nearest
+/// to column `near`.
+pub fn nearest_word(line: &str, word: &str, near: usize) -> Option<usize> {
+    let chars: Vec<char> = line.chars().collect();
+    let w: Vec<char> = word.chars().collect();
+    if w.is_empty() || w.len() > chars.len() {
+        return None;
+    }
+    let ident = |c: char| c.is_alphanumeric() || c == '_';
+    (0..=chars.len() - w.len())
+        .filter(|&i| chars[i..i + w.len()] == w[..])
+        .filter(|&i| i == 0 || !ident(chars[i - 1]))
+        .filter(|&i| i + w.len() == chars.len() || !ident(chars[i + w.len()]))
+        .min_by_key(|&i| i.abs_diff(near))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn a_value_handed_to_a_call_on_a_return_line_is_passed() {
+        let u = of("    return apply_discount(subtotal, discount)", "subtotal");
+        assert_eq!(u.role, Role::Passed);
+        assert_eq!(u.detail, "apply_discount");
+        assert_eq!(u.argument, Some(0));
+        let line = "    return apply_discount(subtotal, discount)";
+        let u = classify(line, line.rfind("discount").unwrap(), "discount");
+        assert_eq!((u.role, u.argument), (Role::Passed, Some(1)));
+        assert_eq!(of("    return subtotal", "subtotal").role, Role::Returned);
+        assert_eq!(of("    return (subtotal)", "subtotal").role, Role::Returned);
+        assert_eq!(of("    yield f(x)", "x").role, Role::Passed);
+        assert_eq!(of("if (ready) {", "ready").role, Role::Branched);
+        assert_eq!(of("while (n > 0) {", "n").role, Role::Branched);
+        assert_eq!(of("    print(total)", "total").role, Role::Passed);
+    }
+
+    #[test]
+    fn a_compound_assignment_reassigns() {
+        let line = "        subtotal += line_total(line)";
+        assert!(reassigns(line, 8, "subtotal"));
+        assert!(reassigns("x //= 2", 0, "x"));
+        assert!(!reassigns("    subtotal = 0", 4, "subtotal"));
+        assert!(!reassigns("    if subtotal == 0:", 7, "subtotal"));
+    }
+
+    #[test]
+    fn a_parameter_list_over_several_lines_is_read_from_the_name_on() {
+        let lines: Vec<String> = [
+            "pub(crate) fn save_markdown(",
+            "    window: Option<iced::window::Id>,",
+            "    file_name: String,",
+            ") -> Task<Option<PathBuf>> {",
+        ]
+        .map(String::from)
+        .to_vec();
+        let name_col = "pub(crate) fn ".chars().count();
+        assert_eq!(
+            parameter_in(&lines, name_col, 1, "rust"),
+            Some(("file_name".into(), 2, 4))
+        );
+        assert_eq!(
+            parameter_in(&lines, name_col, 0, "rust"),
+            Some(("window".into(), 1, 4))
+        );
+        assert_eq!(parameter_in(&lines, name_col, 2, "rust"), None);
+        // One line, with a `pub(crate)` before the name.
+        let one = vec!["pub(crate) fn f(a: u8, b: u8) {".to_string()];
+        assert_eq!(
+            parameter_in(&one, "pub(crate) fn ".len(), 1, "rust"),
+            Some(("b".into(), 0, 23))
+        );
+        // A Go receiver before the name is not the parameter list.
+        let go = vec!["func (s *Shop) Total(order Order, rate int) int {".to_string()];
+        assert_eq!(
+            parameter_in(&go, "func (s *Shop) ".len(), 1, "go"),
+            Some(("rate".into(), 0, 34))
+        );
+        let py: Vec<String> = [
+            "def apply_discount(",
+            "    subtotal: int,",
+            "    discount: Discount,",
+            ") -> int:",
+        ]
+        .map(String::from)
+        .to_vec();
+        assert_eq!(
+            parameter_in(&py, 4, 0, "python"),
+            Some(("subtotal".into(), 1, 4))
+        );
+    }
+
+    #[test]
+    fn a_moved_line_is_found_nearest_to_where_it_was() {
+        let lines = [
+            "",
+            "a = 1",
+            "x",
+            "    subtotal = 0",
+            "y",
+            "    subtotal = 0",
+        ];
+        assert_eq!(moved_line(&lines, "subtotal = 0", 2), Some(3));
+        assert_eq!(moved_line(&lines, "subtotal = 0", 5), Some(5));
+        assert_eq!(moved_line(&lines, "subtotal = 0", 40), Some(5));
+        assert_eq!(moved_line(&lines, "gone", 1), None);
+        assert_eq!(moved_line(&lines, "", 1), None);
+        assert_eq!(nearest_word("ab a_b ab", "ab", 8), Some(7));
+        assert_eq!(nearest_word("ab a_b ab", "ab", 0), Some(0));
+        assert_eq!(nearest_word("abc", "ab", 0), None);
+    }
+
     fn of(line: &str, word: &str) -> Use {
         let col = line.find(word).expect("the word is on the line");
         classify(line, line[..col].chars().count(), word)
diff --git a/src/graph/typegraph.rs b/src/graph/typegraph.rs
index 7288ee9..c3af1a1 100644
--- a/src/graph/typegraph.rs
+++ b/src/graph/typegraph.rs
@@ -10,8 +10,14 @@
 //! names; see `clew_core::apidoc`) and, for Rust, the structure index (whose
 //! `impl Trait for Type` blocks the docs do not list), resolved against the
 //! project's own type names: a word that is no project type is dropped, so
-//! `Vec`, `String` and a field's name cost nothing. Same-named types (two
-//! `Config`s) resolve to the first by path and line.
+//! `Vec`, `String` and a field's name cost nothing. A name resolves only
+//! within its language, and only to a kind it can mean: an inherited name
+//! to a kind one can inherit from (in Rust, a trait — `impl Read for X`
+//! names `std::io::Read`, never a project enum or struct called `Read`).
+//! When several project types share a name, the one in the same file wins,
+//! then the one in the same folder; past that the name is ambiguous and
+//! draws no edge — a wrong edge misleads, a missing one only omits. Types
+//! declared inside a function are local to it and are not nodes.
 
 use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
@@ -29,6 +35,36 @@ pub const TYPE_KINDS: &[&str] = &[
     "union",
 ];
 
+/// Whether an item of `kind` is a function or method (whose body's types are
+/// its own).
+pub(crate) fn is_callable_kind(kind: &str) -> bool {
+    matches!(
+        kind,
+        "function" | "method" | "constructor" | "fn" | "func" | "procedure"
+    )
+}
+
+/// The languages whose types can name one another's: a TypeScript file and a
+/// JavaScript one, a C header and the C++ that includes it.
+fn family(lang: Option<&str>) -> Option<&str> {
+    match lang? {
+        "typescript" | "tsx" | "javascript" | "jsx" => Some("js"),
+        "c" | "cpp" => Some("c"),
+        other => Some(other),
+    }
+}
+
+/// Whether a type of `kind` can be inherited from by a type of `lang`: in
+/// Rust only a trait is implemented or extended; elsewhere anything but an
+/// enum or a union can be a base.
+fn inheritable(kind: &str, lang: Option<&str>) -> bool {
+    if lang == Some("rust") {
+        kind == "trait"
+    } else {
+        !matches!(kind, "enum" | "union")
+    }
+}
+
 /// How one type relates to another, strongest first.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum Relation {
@@ -78,13 +114,16 @@ impl TypeGraph {
         let mut raws: Vec<Raw> = Vec::new();
         fn collect(
             items: &[DocItem],
+            parent_kind: Option<&str>,
             rel: &str,
             file: &Path,
             lang: Option<&'static str>,
             out: &mut Vec<Raw>,
         ) {
             for item in items {
-                if TYPE_KINDS.contains(&item.kind.as_str()) {
+                // A type declared in a function body is that function's.
+                let local = parent_kind.is_some_and(is_callable_kind);
+                if TYPE_KINDS.contains(&item.kind.as_str()) && !local {
                     out.push(Raw {
                         node: TypeNode {
                             name: item.name.clone(),
@@ -99,13 +138,13 @@ impl TypeGraph {
                         lang,
                     });
                 }
-                collect(&item.children, rel, file, lang, out);
+                collect(&item.children, Some(&item.kind), rel, file, lang, out);
             }
         }
         for f in files {
             let file = root.join(&f.rel);
             let lang = crate::highlight::detect(&file);
-            collect(&f.items, &f.rel, &file, lang, &mut raws);
+            collect(&f.items, None, &f.rel, &file, lang, &mut raws);
         }
         raws.sort_by(|a, b| {
             a.node
@@ -114,21 +153,47 @@ impl TypeGraph {
                 .then_with(|| a.node.line.cmp(&b.node.line))
                 .then_with(|| a.node.name.cmp(&b.node.name))
         });
-        let mut by_name: HashMap<&str, usize> = HashMap::new();
+        let mut by_name: HashMap<&str, Vec<usize>> = HashMap::new();
         for (i, r) in raws.iter().enumerate() {
-            by_name.entry(r.node.name.as_str()).or_insert(i);
+            by_name.entry(r.node.name.as_str()).or_default().push(i);
         }
-        let resolve = |name: &str| -> Option<usize> {
+        // `name` as type `from` means it, or `None` (see the module docs).
+        let resolve = |name: &str, from: usize, inherited: bool| -> Option<usize> {
             let last = name.rsplit(['.', ':']).next().unwrap_or(name);
-            by_name.get(last).copied()
+            let here = &raws[from];
+            let fits: Vec<usize> = by_name
+                .get(last)?
+                .iter()
+                .copied()
+                .filter(|&j| j != from)
+                .filter(|&j| family(raws[j].lang) == family(here.lang))
+                .filter(|&j| !inherited || inheritable(&raws[j].node.kind, here.lang))
+                .collect();
+            let only = |picked: Vec<usize>| (picked.len() == 1).then(|| picked[0]);
+            if fits.len() <= 1 {
+                return fits.first().copied();
+            }
+            let dir = |rel: &str| rel.rsplit_once('/').map_or("", |(d, _)| d).to_string();
+            only(
+                fits.iter()
+                    .copied()
+                    .filter(|&j| raws[j].node.rel == here.node.rel)
+                    .collect(),
+            )
+            .or_else(|| {
+                only(
+                    fits.iter()
+                        .copied()
+                        .filter(|&j| dir(&raws[j].node.rel) == dir(&here.node.rel))
+                        .collect(),
+                )
+            })
         };
         let mut inherits: HashSet<(usize, usize)> = HashSet::new();
         let mut uses: HashSet<(usize, usize)> = HashSet::new();
         for (i, r) in raws.iter().enumerate() {
             for base in inherited_names(&r.signature, r.lang) {
-                if let Some(j) = resolve(&base)
-                    && j != i
-                {
+                if let Some(j) = resolve(&base, i, true) {
                     inherits.insert((i, j));
                 }
             }
@@ -136,16 +201,13 @@ impl TypeGraph {
                 && let Some(ts) = structure.by_type.get(&r.node.name)
             {
                 for t in &ts.traits {
-                    if let Some(j) = resolve(t)
-                        && j != i
-                    {
+                    if let Some(j) = resolve(t, i, true) {
                         inherits.insert((i, j));
                     }
                 }
             }
             for name in &r.refs {
-                if let Some(j) = resolve(name)
-                    && j != i
+                if let Some(j) = resolve(name, i, false)
                     && !inherits.contains(&(i, j))
                 {
                     uses.insert((i, j));
@@ -507,4 +569,137 @@ mod tests {
         assert_eq!(g.layout_edges().len(), 5);
         assert!(TypeGraph::build(root, &[], &StructureIndex::default()).is_empty());
     }
+
+    /// Same-named types: a name resolves within its language, to a kind it
+    /// can mean (a Rust impl names a trait), in the same file, then the same
+    /// folder — and past that draws no edge. A type local to a function is
+    /// no node. Each case is one the type map got wrong on the clew repo.
+    #[test]
+    fn same_named_types_resolve_to_the_right_one_or_to_none() {
+        let root = Path::new("/p");
+        let file = |rel: &str, items: Vec<DocItem>| DocFile {
+            rel: rel.into(),
+            items,
+        };
+        let mut read_config = item("read_config", "function", 3, "fn read_config()", &[]);
+        read_config.children = vec![item("Read", "type", 4, "type Read = u8;", &[])];
+        let files = vec![
+            file(
+                "src/registry.rs",
+                vec![
+                    item("Platform", "enum", 1, "pub enum Platform {", &[]),
+                    item("Entry", "struct", 9, "pub struct Entry {", &[]),
+                ],
+            ),
+            file(
+                "src/shell.rs",
+                vec![
+                    item("Platform", "trait", 1, "trait Platform {", &[]),
+                    item("Native", "struct", 5, "struct Native;", &[]),
+                ],
+            ),
+            file(
+                "src/store.rs",
+                vec![
+                    item("Entry", "trait", 1, "pub trait Entry {", &[]),
+                    item("Bookmark", "struct", 8, "pub struct Bookmark {", &["Entry"]),
+                ],
+            ),
+            file(
+                "src/imports.rs",
+                vec![
+                    read_config,
+                    item("Reader", "struct", 20, "pub struct Reader {", &[]),
+                ],
+            ),
+            file(
+                "src/x/config.rs",
+                vec![item("Config", "struct", 1, "pub struct Config {", &[])],
+            ),
+            file(
+                "src/x/uses.rs",
+                vec![item(
+                    "UsesX",
+                    "struct",
+                    1,
+                    "pub struct UsesX {",
+                    &["Config"],
+                )],
+            ),
+            file(
+                "src/y/config.rs",
+                vec![item("Config", "struct", 1, "pub struct Config {", &[])],
+            ),
+            file(
+                "src/z/neither.rs",
+                vec![item(
+                    "UsesNeither",
+                    "struct",
+                    1,
+                    "pub struct UsesNeither {",
+                    &["Config"],
+                )],
+            ),
+            file(
+                "py/order.py",
+                vec![item("Order", "class", 1, "class Order:", &[])],
+            ),
+            file(
+                "src/order.rs",
+                vec![
+                    item("Order", "struct", 1, "pub struct Order {", &[]),
+                    item("Invoice", "struct", 5, "pub struct Invoice {", &["Order"]),
+                ],
+            ),
+        ];
+        let mut structure = StructureIndex::default();
+        for (ty, tr) in [
+            ("Native", "Platform"),
+            ("Bookmark", "Entry"),
+            ("Reader", "Read"),
+        ] {
+            structure
+                .by_type
+                .entry(ty.into())
+                .or_default()
+                .traits
+                .push(tr.into());
+        }
+        let g = TypeGraph::build(root, &files, &structure);
+        assert!(
+            !g.nodes.iter().any(|n| n.name == "Read"),
+            "a function's local alias is no type of the project: {:?}",
+            g.nodes
+        );
+        let label = |id: usize| format!("{}@{}", g.nodes[id].name, g.nodes[id].rel);
+        let mut edges: Vec<(String, String, Relation)> = g
+            .edges
+            .iter()
+            .map(|&(a, b, r)| (label(a), label(b), r))
+            .collect();
+        edges.sort();
+        let want = |a: &str, b: &str, r: Relation| (a.to_string(), b.to_string(), r);
+        assert_eq!(
+            edges,
+            [
+                want(
+                    "Bookmark@src/store.rs",
+                    "Entry@src/store.rs",
+                    Relation::Inherits
+                ),
+                want("Invoice@src/order.rs", "Order@src/order.rs", Relation::Uses),
+                want(
+                    "Native@src/shell.rs",
+                    "Platform@src/shell.rs",
+                    Relation::Inherits
+                ),
+                want(
+                    "UsesX@src/x/uses.rs",
+                    "Config@src/x/config.rs",
+                    Relation::Uses
+                ),
+            ],
+            "{edges:?}"
+        );
+    }
 }
diff --git a/src/ui/docs_stats.rs b/src/ui/docs_stats.rs
index f561a6a..1c5c539 100644
--- a/src/ui/docs_stats.rs
+++ b/src/ui/docs_stats.rs
@@ -177,7 +177,7 @@ pub(crate) fn kind_badge(kind: &str) -> &str {
         "class" => "class",
         "constant" | "const" => "const",
         "module" | "mod" | "namespace" => "mod",
-        "type" | "typealias" | "type_alias" => "type",
+        "type" | "typealias" | "type_alias" | clew_core::apidoc::ASSOCIATED_TYPE => "type",
         "impl" => "impl",
         "property" | "prop" => "prop",
         "field" => "field",
@@ -851,9 +851,10 @@ pub(crate) fn stats_home(app: &App) -> Element<'_, Message> {
     .into()
 }
 
-/// Most glossary rows drawn at once; past that the page asks for a filter
-/// rather than laying out thousands of rows per repaint.
-pub(crate) const GLOSSARY_ROWS_SHOWN: usize = 300;
+/// Most rows a glossary section draws; past that it asks for a filter
+/// rather than laying out thousands of rows per repaint. Per section, so a
+/// project with many types still shows its modules and acronyms.
+pub(crate) const GLOSSARY_ROWS_SHOWN: usize = 200;
 
 /// The Glossary page: the project's terms, in sections by kind, each a
 /// button to its definition; a filter on top (`app::glossary`).
@@ -901,19 +902,11 @@ pub(crate) fn glossary_home(app: &App) -> Element<'_, Message> {
         .width(Fill);
     let query = app.proj.glossary.filter.trim().to_lowercase();
     let matching: Vec<&crate::app::glossary::Term> = glossary.matching(&query).collect();
-    let hint = if matching.len() > GLOSSARY_ROWS_SHOWN {
-        format!(
-            "{} of {} terms shown · narrow the filter for the rest · click a term to open its definition",
-            GLOSSARY_ROWS_SHOWN,
-            matching.len()
-        )
-    } else {
-        format!(
-            "{} of {} terms · click a term to open its definition · hovering a term in the code shows the same line",
-            matching.len(),
-            glossary.len()
-        )
-    };
+    let hint = format!(
+        "{} of {} terms · click a term to open its definition · hovering a term in the code shows the same line",
+        matching.len(),
+        glossary.len()
+    );
 
     let mut items: Vec<Element<'_, Message>> = Vec::new();
     if matching.is_empty() {
@@ -927,14 +920,11 @@ pub(crate) fn glossary_home(app: &App) -> Element<'_, Message> {
             .into(),
         );
     }
-    let mut shown = 0;
     for kind in [TermKind::Type, TermKind::Module, TermKind::Acronym] {
         let mut rows: Vec<Element<'_, Message>> = Vec::new();
-        for term in matching.iter().filter(|t| t.kind == kind) {
-            if shown >= GLOSSARY_ROWS_SHOWN {
-                break;
-            }
-            shown += 1;
+        let of_kind: Vec<&&crate::app::glossary::Term> =
+            matching.iter().filter(|t| t.kind == kind).collect();
+        for term in of_kind.iter().take(GLOSSARY_ROWS_SHOWN) {
             let head = row![
                 button(text(term.name.clone()).size(ts::BASE).color(theme::fg()))
                     .style(theme::toolbar_button)
@@ -977,6 +967,17 @@ pub(crate) fn glossary_home(app: &App) -> Element<'_, Message> {
         if rows.is_empty() {
             continue;
         }
+        if of_kind.len() > GLOSSARY_ROWS_SHOWN {
+            rows.push(
+                text(format!(
+                    "{} more — narrow the filter to see them",
+                    of_kind.len() - GLOSSARY_ROWS_SHOWN
+                ))
+                .size(ts::CAPTION)
+                .color(theme::dim())
+                .into(),
+            );
+        }
         items.push(
             column![
                 text(kind.heading())
diff --git a/src/ui/graph.rs b/src/ui/graph.rs
index 474fa6b..4527fa8 100644
--- a/src/ui/graph.rs
+++ b/src/ui/graph.rs
@@ -217,24 +217,70 @@ pub(crate) fn graph_map_view(app: &App) -> Element<'_, Message> {
     )
     .width(Fill)
     .height(Fill);
-    let nav = map_nav_hint(app.graph_3d);
-    let legend = if layout.total > layout.nodes.len() {
-        format!(
-            "Showing the {} most-connected of {} files · {nav} · drag a node to move it · scroll to zoom · click a node to open it",
-            layout.nodes.len(),
-            layout.total,
-        )
-    } else {
-        format!(
-            "{nav} · drag a node · scroll to zoom · size = degree · hue = language · rich = root, pale = deep · arrow → the file it imports · gold ring = cycle"
-        )
-    };
+    let visited = trace_files(app);
+    let legend = graph_legend(
+        kind,
+        app.graph_3d,
+        (layout.nodes.len(), layout.total),
+        app.graph_heat && app.proj.churn.is_some(),
+        layout.nodes.iter().any(|n| visited.contains(&n.file)),
+    );
     column![map, text(legend).size(ts::CAPTION).color(theme::dim())]
         .spacing(6)
         .height(iced::Length::Fill)
         .into()
 }
 
+/// The line under a graph map that says how to read it: what a node is
+/// (`kind`), how many are shown of how many (`shown`), what its colour means
+/// (the heat overlay's change counts, or language and depth), what an arrow
+/// means, and the rings it may carry — a cycle (imports only) and a stop of
+/// the last debug run (`visited`).
+pub(crate) fn graph_legend(
+    kind: crate::Overlay,
+    graph_3d: bool,
+    shown: (usize, usize),
+    heat: bool,
+    visited: bool,
+) -> String {
+    use crate::Overlay;
+    let noun = if kind == Overlay::ProjectTypes {
+        "types"
+    } else {
+        "files"
+    };
+    let mut parts: Vec<String> = Vec::new();
+    if shown.1 > shown.0 {
+        parts.push(format!(
+            "Showing the {} most-connected of {} {noun}",
+            shown.0, shown.1
+        ));
+    }
+    parts.push(map_nav_hint(graph_3d).to_string());
+    parts.push("drag a node · scroll to zoom · size = degree".into());
+    parts.push(if heat {
+        "colour = how often it changed (red most, grey never)".into()
+    } else {
+        "hue = language, paler = deeper".into()
+    });
+    parts.push(
+        match kind {
+            Overlay::ProjectImports => "arrow → the file it imports",
+            Overlay::ProjectCalls => "arrow → the file it calls into",
+            Overlay::ProjectTypes => "arrow → the type it uses or inherits",
+        }
+        .into(),
+    );
+    if kind == Overlay::ProjectImports {
+        parts.push("gold ring = import cycle".into());
+    }
+    if visited {
+        parts.push("green ring = the last debug run stopped here".into());
+    }
+    parts.push("click a node to open it".into());
+    parts.join(" · ")
+}
+
 /// A distinct base colour per graphed language (see `theme::language_hue`).
 pub(crate) fn lang_dot_color(lang: Option<&str>) -> iced::Color {
     theme::language_hue(lang)
diff --git a/src/ui/panels.rs b/src/ui/panels.rs
index e390d87..ac0ddee 100644
--- a/src/ui/panels.rs
+++ b/src/ui/panels.rs
@@ -709,6 +709,26 @@ pub(crate) fn flow_tab(app: &App) -> Element<'_, Message> {
     .width(Fill);
 
     let mut rows: Vec<Element<'_, Message>> = Vec::new();
+    if tree.stale {
+        rows.push(
+            container(
+                row![
+                    text("A traced file changed: rows marked changed are where their line was.")
+                        .size(ts::CAPTION)
+                        .color(theme::warning())
+                        .width(Fill),
+                    button(text("trace again").size(ts::SMALL))
+                        .style(theme::toolbar_button)
+                        .padding([2, 7])
+                        .on_press(Message::Flow(crate::FlowMsg::Retrace)),
+                ]
+                .spacing(6)
+                .align_y(iced::Center),
+            )
+            .padding([4, 10])
+            .into(),
+        );
+    }
     if let Some(note) = &tree.note {
         rows.push(
             container(text(note).size(ts::CAPTION).color(theme::dim()))
@@ -781,10 +801,19 @@ fn flow_row(tree: &crate::app::flow::FlowTree, id: usize, token: u64) -> Element
         role => role.tag().to_string(),
     };
     let where_ = format!("{}:{}", node.rel, node.line + 1);
+    let changed: Element<'_, Message> = if node.changed {
+        text("changed")
+            .size(ts::CAPTION)
+            .color(theme::warning())
+            .into()
+    } else {
+        space().width(0).into()
+    };
     let body = column![
         row![
             text(label).size(ts::CAPTION).color(theme::accent()),
             text(where_).size(ts::CAPTION).color(theme::dim()),
+            changed,
         ]
         .spacing(6),
         text(if node.classified {
diff --git a/src/ui/tests.rs b/src/ui/tests.rs
index bd9446f..d2bd1c6 100644
--- a/src/ui/tests.rs
+++ b/src/ui/tests.rs
@@ -2942,6 +2942,8 @@ fn the_flow_tab_lists_occurrences_under_their_roles() {
         col: 0,
         text: text.into(),
         classified: !text.is_empty(),
+        indent: 0,
+        changed: false,
         depth: 0,
         parent: None,
         children: None,
@@ -2988,8 +2990,25 @@ fn the_flow_tab_lists_occurrences_under_their_roles() {
         x: 10.0,
         y: 10.0,
     });
-    let mut sim = sim_of(&app);
-    assert!(shows(&mut sim, "Trace Value"));
+    assert!(shows(&mut sim_of(&app), "Trace Value"));
+    app.proj.context_menu = None;
+
+    // A traced file changed and a line is gone: the row says so, and the
+    // tab offers to trace again.
+    {
+        let tree = app.proj.flow.as_mut().unwrap();
+        tree.stale = true;
+        tree.node_mut(1).unwrap().changed = true;
+    }
+    assert!(shows(&mut sim_elem(super::flow_tab(&app)), "changed"));
+    let mut sim = sim_elem(super::flow_tab(&app));
+    let _ = sim.click("trace again");
+    let sent: Vec<Message> = sim.into_messages().collect();
+    assert!(
+        sent.iter()
+            .any(|m| matches!(m, Message::Flow(crate::FlowMsg::Retrace))),
+        "{sent:?}"
+    );
 }
 
 fn doc_file(rel: &str, items: &[(&str, bool)]) -> clew_protocol::DocFile {
@@ -3570,7 +3589,12 @@ fn the_glossary_page_lists_terms_by_kind() {
         rel: "src/net.rs".into(),
         items: vec![
             item("Client", "struct", "A connection to one server.", 4),
-            item("RPC", "const", "Remote procedure call framing.", 9),
+            item(
+                "frame",
+                "function",
+                "Frames a Remote Procedure Call (RPC) for the wire.",
+                9,
+            ),
         ],
     }];
     app.proj.docs.generation += 1;
@@ -3595,7 +3619,7 @@ fn the_glossary_page_lists_terms_by_kind() {
         "Client",
         "A connection to one server",
         "RPC",
-        "Remote procedure call framing",
+        "Remote Procedure Call",
         "net",
         "Talks to the server",
         "src/net.rs:4",
@@ -3613,7 +3637,7 @@ fn the_glossary_page_lists_terms_by_kind() {
     );
     // The filter narrows the list, by name or definition.
     let _ = app.update(Message::Glossary(GlossaryMsg::FilterChanged(
-        "framing".into(),
+        "procedure".into(),
     )));
     assert!(on_page(&app, "RPC"));
     assert!(!on_page(&app, "Client"), "Client survived the filter");
@@ -3648,3 +3672,94 @@ fn the_glossary_page_lists_terms_by_kind() {
         "{sent:?}"
     );
 }
+
+/// The glossary caps each section on its own: a project with more types than
+/// the page draws still shows its modules, and the long section says how
+/// many it left out.
+#[test]
+fn a_long_glossary_section_does_not_hide_the_next() {
+    let mut app = reader_app();
+    let root = app.proj.project.as_ref().unwrap().root.clone();
+    let many = super::GLOSSARY_ROWS_SHOWN + 5;
+    let items: Vec<clew_protocol::DocItem> = (0..many)
+        .map(|i| clew_protocol::DocItem {
+            name: format!("Type{i:03}"),
+            kind: "struct".into(),
+            signature: String::new(),
+            doc: "A type.".into(),
+            line: i + 1,
+            public: true,
+            children: Vec::new(),
+            refs: Vec::new(),
+        })
+        .collect();
+    app.proj.docs.files = vec![clew_protocol::DocFile {
+        rel: "src/types.rs".into(),
+        items,
+    }];
+    app.proj.docs.generation += 1;
+    app.explain_cache_mut().insert(
+        crate::explain::Node::File(root.join("src/net.rs")),
+        crate::explain::Cached {
+            summary: "Talks to the server.".into(),
+            prompt_hash: 1,
+            detail: None,
+            basis: None,
+        },
+    );
+    let _ = app.update(Message::Glossary(GlossaryMsg::Open));
+    // Tall enough that the whole list is on screen.
+    let mut sim = iced_test::Simulator::with_size(
+        Default::default(),
+        Size::new(1000.0, 40_000.0),
+        super::glossary_home(&app),
+    );
+    assert!(shows(&mut sim, "5 more — narrow the filter to see them"));
+    assert!(
+        shows(&mut sim, "Modules"),
+        "the modules after a capped section"
+    );
+    assert!(shows(&mut sim, "Talks to the server"));
+}
+
+/// A graph's legend says how to read the graph shown: what a node is, what
+/// an arrow means, what colour means with and without the heat overlay, and
+/// which rings it can carry. It once read as the import graph's for all of
+/// them ("of 838 files" on the type map).
+#[test]
+fn the_graph_legend_says_how_to_read_the_graph_shown() {
+    use crate::Overlay;
+    let calls = super::graph_legend(Overlay::ProjectCalls, true, (160, 163), false, false);
+    assert!(
+        calls.starts_with("Showing the 160 most-connected of 163 files · drag to orbit"),
+        "{calls}"
+    );
+    assert!(calls.contains("arrow → the file it calls into"), "{calls}");
+    assert!(calls.contains("hue = language"), "{calls}");
+    assert!(
+        !calls.contains("cycle") && !calls.contains("ring"),
+        "{calls}"
+    );
+    let types = super::graph_legend(Overlay::ProjectTypes, false, (160, 838), true, true);
+    assert!(types.contains("of 838 types"), "{types}");
+    assert!(
+        types.contains("arrow → the type it uses or inherits"),
+        "{types}"
+    );
+    assert!(
+        types.contains("colour = how often it changed") && !types.contains("hue = language"),
+        "{types}"
+    );
+    assert!(
+        types.contains("green ring = the last debug run stopped here"),
+        "{types}"
+    );
+    let imports = super::graph_legend(Overlay::ProjectImports, false, (4, 4), false, false);
+    assert!(!imports.contains("Showing"), "{imports}");
+    assert!(imports.starts_with("drag to pan"), "{imports}");
+    assert!(
+        imports.contains("arrow → the file it imports")
+            && imports.contains("gold ring = import cycle"),
+        "{imports}"
+    );
+}

From bbd9af3f788befac92911420400c366047821adf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 05:12:19 +0000
Subject: [PATCH 2/4] Define modules in the glossary by their own doc comment

The docs index now carries each file's own doc comment (Rust `//!`, a
Python module docstring, Go's package comment). The glossary lists a
module term for each file that has one, named the way the language names
modules, and finds spelled-out acronyms in it too. This adds a required
field to DocFile, so the protocol version moves to 15 with a new wire
snapshot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
---
 crates/clew-core/src/apidoc.rs                | 106 ++++++++++++++++++
 crates/clew-protocol/src/lib.rs               |   8 +-
 .../tests/snapshots/wire-v15.snap             | 105 +++++++++++++++++
 crates/clew-protocol/tests/wire_snapshot.rs   |   1 +
 crates/clew-server/src/index.rs               |   6 +-
 src/app/glossary.rs                           |  85 +++++++++++++-
 src/app/tests.rs                              |   6 +
 src/graph/typegraph.rs                        |   3 +
 src/ui/tests.rs                               |   4 +
 9 files changed, 319 insertions(+), 5 deletions(-)
 create mode 100644 crates/clew-protocol/tests/snapshots/wire-v15.snap

diff --git a/crates/clew-core/src/apidoc.rs b/crates/clew-core/src/apidoc.rs
index 71da251..781e98e 100644
--- a/crates/clew-core/src/apidoc.rs
+++ b/crates/clew-core/src/apidoc.rs
@@ -46,6 +46,72 @@ pub const MAX_DOC_DEPTH: usize = 32;
 /// Build the documented API of one file: top-level items, with members nested
 /// under their enclosing type/module by source-range containment. Returns an
 /// empty list when the language has no outline.
+/// A file's own doc comment, its comment markers stripped: Rust's leading
+/// `//!` lines, a Python module's docstring, Go's package comment (the
+/// comment block right above `package`). Empty for the other languages,
+/// whose file-top comments are licence headers as often as docs, and for a
+/// file without one.
+pub fn module_doc(source: &str, lang_key: &str) -> String {
+    let lines = source.lines().map(|l| l.trim_end_matches('\r'));
+    match lang_key {
+        "rust" => {
+            let mut doc: Vec<&str> = Vec::new();
+            for line in lines {
+                let t = line.trim_start();
+                if let Some(rest) = t.strip_prefix("//!") {
+                    doc.push(rest.strip_prefix(' ').unwrap_or(rest));
+                } else if t.is_empty() && doc.is_empty() || t.starts_with("#!") && doc.is_empty() {
+                    continue;
+                } else {
+                    break;
+                }
+            }
+            doc.join("\n").trim().to_string()
+        }
+        "python" => {
+            // The first statement, when it is a string literal.
+            let body: Vec<&str> = lines
+                .skip_while(|l| {
+                    let t = l.trim();
+                    t.is_empty() || t.starts_with('#')
+                })
+                .collect();
+            let text = body.join("\n");
+            let text = text.trim_start_matches(['r', 'R', 'u', 'U']);
+            for quote in ["\"\"\"", "'''", "\"", "'"] {
+                if let Some(rest) = text.strip_prefix(quote)
+                    && let Some(end) = rest.find(quote)
+                {
+                    return rest[..end].trim().to_string();
+                }
+            }
+            String::new()
+        }
+        "go" => {
+            let all: Vec<&str> = lines.collect();
+            let Some(pkg) = all
+                .iter()
+                .position(|l| l.trim_start().starts_with("package "))
+            else {
+                return String::new();
+            };
+            let mut doc: Vec<&str> = all[..pkg]
+                .iter()
+                .rev()
+                .map(|l| l.trim_start())
+                .take_while(|l| l.starts_with("//"))
+                .map(|l| {
+                    let rest = &l[2..];
+                    rest.strip_prefix(' ').unwrap_or(rest)
+                })
+                .collect();
+            doc.reverse();
+            doc.join("\n").trim().to_string()
+        }
+        _ => String::new(),
+    }
+}
+
 pub fn build_file(source: &str, lang_key: &str) -> Vec<DocItem> {
     let Some(lang) = Lang::for_source(lang_key, source) else {
         return Vec::new();
@@ -1137,6 +1203,7 @@ mod depth_tests {
                 files: vec![clew_protocol::DocFile {
                     rel: "deep.rs".to_string(),
                     items,
+                    doc: String::new(),
                 }],
             },
         };
@@ -1660,4 +1727,43 @@ module.exports = {
         assert!(!find(&k.children, "_private").public);
         assert!(!find(&k.children, "__mangled").public);
     }
+
+    #[test]
+    fn a_files_own_doc_is_read_per_language() {
+        assert_eq!(
+            module_doc(
+                "//! Debug Adapter Protocol (DAP) support.\n//!\n//! More.\nuse x;\n",
+                "rust"
+            ),
+            "Debug Adapter Protocol (DAP) support.\n\nMore."
+        );
+        assert_eq!(module_doc("#![allow(x)]\nuse y;\n", "rust"), "");
+        assert_eq!(
+            module_doc("/// An item's doc, not the file's.\nfn f() {}\n", "rust"),
+            ""
+        );
+        assert_eq!(
+            module_doc(
+                "#!/usr/bin/env python\n# coding: utf-8\n\n\"\"\"The catalog.\n\nMore.\"\"\"\nimport x\n",
+                "python"
+            ),
+            "The catalog.\n\nMore."
+        );
+        assert_eq!(module_doc("'''Orders.'''\n", "python"), "Orders.");
+        assert_eq!(
+            module_doc("import x\n\"\"\"Not first.\"\"\"\n", "python"),
+            ""
+        );
+        assert_eq!(
+            module_doc(
+                "// Copyright.\n\n// Package shop prices orders.\n// Carts too.\npackage shop\n",
+                "go"
+            ),
+            "Package shop prices orders.\nCarts too."
+        );
+        assert_eq!(
+            module_doc("/** Licence. */\nexport const a = 1;\n", "typescript"),
+            ""
+        );
+    }
 }
diff --git a/crates/clew-protocol/src/lib.rs b/crates/clew-protocol/src/lib.rs
index e1089b1..3ad9f70 100644
--- a/crates/clew-protocol/src/lib.rs
+++ b/crates/clew-protocol/src/lib.rs
@@ -93,7 +93,9 @@ pub use payload::*;
 /// from" chains know the routes, commands and handlers a `main` alone did
 /// not name; [`GitOp::Churn`] answers how often each file changed over the
 /// recent history, for the graphs' change-frequency overlay.
-pub const PROTOCOL_VERSION: u32 = 14;
+/// v15: a [`DocFile`] carries its module's own doc comment (`doc`), which the
+/// glossary defines modules by and finds spelled-out acronyms in.
+pub const PROTOCOL_VERSION: u32 = 15;
 
 /// A hash of this crate's source as a token stream — comments and whitespace
 /// removed — computed at build time (see `build.rs`). Carried in `Hello` /
@@ -207,6 +209,10 @@ pub struct DocItem {
 pub struct DocFile {
     pub rel: Rel,
     pub items: Vec<DocItem>,
+    /// The file's own doc comment, as markdown — Rust's `//!`, a Python
+    /// module docstring, Go's package comment; empty when it has none. What
+    /// the glossary defines a module by, and where acronyms are spelled out.
+    pub doc: String,
 }
 
 /// One highlighted source line: a list of `(text, style index)` spans.
diff --git a/crates/clew-protocol/tests/snapshots/wire-v15.snap b/crates/clew-protocol/tests/snapshots/wire-v15.snap
new file mode 100644
index 0000000..520ff8c
--- /dev/null
+++ b/crates/clew-protocol/tests/snapshots/wire-v15.snap
@@ -0,0 +1,105 @@
+{"id":1,"request":{"Hello":{"protocol":15,"fingerprint":"f"}}}
+{"id":1,"request":{"OpenProject":{"root":"/p"}}}
+{"id":1,"request":{"ReadFile":{"rel":"a.rs","target":{"label":"Host (macos)","os":"macos","arch":"aarch64","family":"unix"}}}}
+{"id":1,"request":{"Search":{"query":"q","regex":false,"case_sensitive":true,"whole_word":false,"include":"*.rs","exclude":"target"}}}
+{"id":1,"request":{"GitInfo":{"rel":"a.rs"}}}
+{"id":1,"request":{"ReadState":{"root":"/p","rel":"bookmarks.json"}}}
+{"id":1,"request":{"WriteState":{"root":"/p","rel":"bookmarks.json","text":"[]"}}}
+{"id":1,"request":{"EditState":{"root":"/p","rel":"bookmarks.json","merge":{"key_fields":["rel","line"],"key":["a.rs",1],"edit":{"Upsert":{"line":1,"rel":"a.rs"}},"delete_when_empty":true},"edit_id":"4f1c9a2e7b30d865-12"}}}
+{"id":1,"request":{"EditState":{"root":"/p","rel":"bookmarks.json","merge":{"key_fields":["rel","line"],"key":["a.rs",1],"edit":"Remove","delete_when_empty":true},"edit_id":"4f1c9a2e7b30d865-12"}}}
+{"id":1,"request":{"EditState":{"root":"/p","rel":"bookmarks.json","merge":{"key_fields":["rel","line"],"key":["a.rs",1],"edit":{"Toggle":{"line":1,"rel":"a.rs"}},"delete_when_empty":true},"edit_id":"4f1c9a2e7b30d865-12"}}}
+{"id":1,"request":{"EditState":{"root":"/p","rel":"bookmarks.json","merge":{"key_fields":["rel","line"],"key":["a.rs",1],"edit":{"Patch":{"fields":{"note":"n"},"insert":{"line":1,"rel":"a.rs"},"empty_when":["note"]}},"delete_when_empty":true},"edit_id":"4f1c9a2e7b30d865-12"}}}
+{"id":1,"request":"Stats"}
+{"id":1,"request":{"ProjectCalls":{"scope":[["a.rs",["b.rs"]]]}}}
+{"id":1,"request":{"ReadSources":{"rels":["a.rs"]}}}
+{"id":1,"request":{"Git":{"op":{"FileHistory":{"rel":"a.rs","limit":10}}}}}
+{"id":1,"request":{"Git":{"op":{"SymbolHistory":{"rel":"a.rs","start":1,"end":9,"limit":10}}}}}
+{"id":1,"request":{"Git":{"op":{"FileAt":{"sha":"abc","rel":"a.rs"}}}}}
+{"id":1,"request":{"Git":{"op":{"AddedLines":{"sha":"abc","rel":"a.rs"}}}}}
+{"id":1,"request":{"Git":{"op":{"CommitMessage":{"sha":"abc"}}}}}
+{"id":1,"request":{"Git":{"op":{"CommitFileDiff":{"sha":"abc","rel":"a.rs","max_bytes":4096}}}}}
+{"id":1,"request":{"Git":{"op":{"DiffLines":{"rel":"a.rs"}}}}}
+{"id":1,"request":{"Git":{"op":"ReviewBase"}}}
+{"id":1,"request":{"Git":{"op":{"CommitSubjects":{"base":"main"}}}}}
+{"id":1,"request":{"Git":{"op":{"ChangedFiles":{"base":"main"}}}}}
+{"id":1,"request":{"Git":{"op":{"RangePatch":{"base":"main","max_bytes":4096}}}}}
+{"id":1,"request":{"Git":{"op":{"Churn":{"commits":300}}}}}
+{"id":1,"request":{"SpawnProcess":{"proc":1,"cmd":"ls","args":["-l"],"cwd":"/p"}}}
+{"id":1,"request":{"SpawnLsp":{"proc":1,"language":"rust"}}}
+{"id":1,"request":{"SpawnAdapter":{"proc":1,"lang":"native","program":"/p/bin","args":[]}}}
+{"id":1,"request":{"LspResolve":{"language":"rust"}}}
+{"id":1,"request":{"LspInstall":{"language":"rust","consent":"c0ffee"}}}
+{"id":1,"request":{"LspApprovals":{"approvals":[["rust","fp"]]}}}
+{"id":1,"request":{"ProcessInput":{"proc":1,"data":"Q29udGVudC1MZW5ndGg6IDINCg0Ke30="}}}
+{"id":1,"request":{"ProcessKill":{"proc":1}}}
+{"id":1,"request":{"Cancel":{"id":1}}}
+{"id":1,"request":{"SetAiConfig":{"chat":{"provider":"anthropic","api_key":"k","model":"m","base_url":"u"},"embed":{"api_key":"k","model":"m","base_url":"u"}}}}
+{"id":1,"request":{"SetAiConfig":{"chat":null,"embed":null}}}
+{"id":1,"request":{"Chat":{"system":"s","messages":[{"role":"user","content":"q"}],"max_tokens":64}}}
+{"id":1,"request":{"Embed":{"texts":["t"]}}}
+{"id":1,"request":{"ChatStream":{"stream":1,"system":"s","messages":[{"role":"user","content":"q"}],"max_tokens":64}}}
+{"id":1,"request":{"AgentAsk":{"stream":1,"question":"q","history":[{"role":"user","content":"q"}],"context":"c"}}}
+{"id":1,"request":{"ListDir":{"path":"~"}}}
+{"id":1,"request":"BuildDocs"}
+{"Reply":{"id":1,"event":{"Ready":{"protocol":15,"fingerprint":"f"}}}}
+{"Reply":{"id":1,"event":{"Tree":{"root":"/p","seq":1,"tree":{"dirs":[["src",{"dirs":[],"files":["a.rs"]}]],"files":["README.md"]},"files":["src/a.rs","README.md"],"truncated":false,"tracked_ignored":["README.md"]}}}}
+{"Reply":{"id":1,"event":{"FileContent":{"rel":"a.rs","source":"fn main() {}","lines":[{"spans":[["fn",1],[" main() {}",null]]}],"symbols":[{"name":"main","kind":"function","line":1,"end_line":1}],"docs":[[1,"entry"]],"inactive":[2]}}}}
+{"Reply":{"id":1,"event":{"NotebookContent":{"rel":"n.ipynb","language":"python","cells":[{"kind":"code","source":"x = 1","lines":[{"spans":[["x = 1",null]]}],"proj_line":1,"outputs":[{"Text":{"spans":[["1",2]],"stderr":false}},{"Image":{"data":"iVBORw=="}},{"Svg":"<svg/>"},{"Placeholder":"widget"}],"execution_count":1}],"symbols":[],"projection":"# %%\nx = 1"}}}}
+{"Reply":{"id":1,"event":{"GitInfo":{"rel":"a.rs","info":{"blame":[{"commit":"abc","author":"a","time":1,"summary":"s","uncommitted":false}],"status":[null,"Added","Modified"],"deleted_at":[1]}}}}}
+{"Reply":{"id":1,"event":{"Stats":{"root":"/p","report":{"totals":{"files":1,"code":2,"comments":3,"blanks":4},"langs":[{"name":"Rust","files":1,"code":2,"comments":3,"blanks":4}],"top_files":[{"rel":"a.rs","lang":"Rust","code":2,"lines":9}],"skipped":1}}}}}
+{"Reply":{"id":1,"event":{"ProjectCalls":{"root":"/p","graph":{"nodes":[{"name":"main","kind":"function","file":"a.rs","line":1,"callers":[],"callees":[1]},{"name":"helper","kind":"function","file":"a.rs","line":5,"callers":[0],"callees":[]}]}}}}}
+{"Reply":{"id":1,"event":{"Sources":{"root":"/p","files":[["a.rs","fn main() {}"]],"missing":["gone.rs"],"too_large":[["vendor.rs",2097152]],"refused":[["latin1.rs","NotUtf8"],["pipe.rs","NotPlainFile"],["leak.rs","OutsideProject"]],"unreadable":[["secret.rs","Permission denied (os error 13)"]],"deferred":["next.rs"]}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"FileHistory":[{"sha":"abc","author":"a","time":1,"subject":"s","path":"a.rs"}]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"SymbolHistory":[{"sha":"abc","author":"a","time":1,"subject":"s","path":"a.rs"}]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"FileAt":"fn main() {}"}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"AddedLines":[3]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"CommitMessage":null}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"CommitFileDiff":"@@ -1 +1 @@"}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"DiffLines":[{"kind":"Header","text":"diff --git a/a.rs b/a.rs"},{"kind":"Hunk","text":"@@ -1 +1 @@"},{"kind":"Context","text":" x"},{"kind":"Add","text":"+y"},{"kind":"Remove","text":"-z"}]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"ReviewBase":["abc","main"]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"CommitSubjects":["s"]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"ChangedFiles":[["a.rs","M"]]}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"RangePatch":""}}}}}
+{"Reply":{"id":1,"event":{"GitResult":{"root":"/p","result":{"Churn":[{"rel":"a.rs","commits":3,"last":1700000000}]}}}}}
+{"Reply":{"id":1,"event":{"StateContent":{"root":"/p","rel":"bookmarks.json","text":null}}}}
+{"Reply":{"id":1,"event":{"StateWritten":{"root":"/p","rel":"bookmarks.json"}}}}
+{"Reply":{"id":1,"event":{"StateEdited":{"root":"/p","rel":"bookmarks.json","text":"[]"}}}}
+{"Reply":{"id":1,"event":{"SearchResults":{"hits":[{"rel":"a.rs","line":1,"preview":"fn main"}],"error":null,"skipped":[{"rel":"dump.sql","reason":"larger than 64 MB"}],"skipped_total":1}}}}
+{"Reply":{"id":1,"event":{"AdapterSpawned":{"proc":1,"launch":"{}"}}}}
+{"Reply":{"id":1,"event":{"ChatResult":{"text":"t"}}}}
+{"Reply":{"id":1,"event":{"Embeddings":{"vecs":[[0.5]]}}}}
+{"Reply":{"id":1,"event":{"DirListing":{"path":"/home","parent":"/","entries":[{"name":"p","is_dir":true},{"name":"notes.txt","is_dir":false}],"omitted":0}}}}
+{"Reply":{"id":1,"event":{"Docs":{"root":"/p","files":[{"rel":"a.rs","items":[{"name":"main","kind":"function","signature":"fn main()","doc":"entry","line":1,"public":true,"children":[],"refs":[]}],"doc":"The entry file."}]}}}}
+{"Reply":{"id":1,"event":{"LspResolved":{"language":"rust","root":"/p","resolution":{"Ready":{"init_options":{"a":1},"withheld":null}}}}}}
+{"Reply":{"id":1,"event":{"LspResolved":{"language":"rust","root":"/p","resolution":{"Ready":{"init_options":null,"withheld":{"server":"rust-analyzer","version":"1","args":[],"fingerprint":"fp","options":{"a":1}}}}}}}}
+{"Reply":{"id":1,"event":{"LspResolved":{"language":"rust","root":"/p","resolution":{"Command":{"command":"/p/ra","args":[],"server":"rust-analyzer","version":"1","fingerprint":"fp","init_options":null}}}}}}
+{"Reply":{"id":1,"event":{"LspResolved":{"language":"rust","root":"/p","resolution":{"NeedsInstall":{"server":"rust-analyzer","version":"1","describe":"d","consent":"c0ffee"}}}}}}
+{"Reply":{"id":1,"event":{"LspResolved":{"language":"rust","root":"/p","resolution":{"Unsupported":{"message":"no server"}}}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":"Failed","message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":"Refused","message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":"Handshake","message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":"NotReady","message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":"Cancelled","message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":{"Status":{"code":404,"kind":"model_not_found","message":"The model does not exist"}}},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":{"Status":{"code":502,"kind":null,"message":"Bad Gateway"}}},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":"Unreached"},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":"Broken"},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":"Stream"},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":"Unusable"},"message":"boom"}}}}
+{"Reply":{"id":1,"event":{"Error":{"code":{"Provider":"Settings"},"message":"boom"}}}}
+{"Notification":{"event":{"Tree":{"root":"/p","seq":2,"tree":{"dirs":[],"files":[]},"files":[],"truncated":true,"tracked_ignored":[]}}}}
+{"Notification":{"event":{"FilesChanged":{"root":"/p","rels":["a.rs"]}}}}
+{"Notification":{"event":{"ProjectSymbols":{"root":"/p","seq":1,"full":true,"files":[{"rel":"a.rs","symbols":[{"name":"main","kind":"function","line":1,"is_test":false,"entry":"main"}],"imports":[{"module":"std::io","line":1,"is_mod":false}]}],"go_module":{"Set":"example.com/m"},"dart_package":"Unchanged","structure":{"Set":{"by_type":{"Point":{"traits":["Clone"],"methods":["norm"]}},"implementors":{"Clone":["Point"]}}}}}}}
+{"Notification":{"event":{"ProjectSymbols":{"root":"/p","seq":2,"full":false,"files":[{"rel":"a.rs","symbols":[{"name":"main","kind":"function","line":1,"is_test":false,"entry":"main"}],"imports":[{"module":"std::io","line":1,"is_mod":false}]}],"go_module":"Unchanged","dart_package":{"Set":null},"structure":{"Set":null}}}}}
+{"Notification":{"event":{"ProcessOutput":{"proc":1,"data":"AJ+Slg=="}}}}
+{"Notification":{"event":{"ProcessStarted":{"proc":1}}}}
+{"Notification":{"event":{"ProcessExited":{"proc":1,"code":0}}}}
+{"Notification":{"event":{"ProcessExited":{"proc":2,"code":null}}}}
+{"Notification":{"event":{"ChatDelta":{"stream":1,"text":"t"}}}}
+{"Notification":{"event":{"ChatStreamDone":{"stream":1,"outcome":"Done"}}}}
+{"Notification":{"event":{"ChatStreamDone":{"stream":1,"outcome":"Stopped"}}}}
+{"Notification":{"event":{"ChatStreamDone":{"stream":1,"outcome":{"Failed":"provider error"}}}}}
+{"Notification":{"event":{"AgentStep":{"stream":1,"tool":"search","title":"search \"q\" → 1","refs":[{"rel":"a.rs","line":1}]}}}}
+{"Notification":{"event":{"AgentDelta":{"stream":1,"text":"t"}}}}
+{"Notification":{"event":{"AgentDone":{"stream":1,"outcome":"Stopped"}}}}
+{"Notification":{"event":{"Status":{"message":"file watching is unavailable"}}}}
diff --git a/crates/clew-protocol/tests/wire_snapshot.rs b/crates/clew-protocol/tests/wire_snapshot.rs
index 739e03d..be577e7 100644
--- a/crates/clew-protocol/tests/wire_snapshot.rs
+++ b/crates/clew-protocol/tests/wire_snapshot.rs
@@ -973,6 +973,7 @@ fn reply_samples() -> Vec<Event> {
             root: "/p".into(),
             files: vec![DocFile {
                 rel: "a.rs".into(),
+                doc: "The entry file.".into(),
                 items: vec![DocItem {
                     name: "main".into(),
                     kind: "function".into(),
diff --git a/crates/clew-server/src/index.rs b/crates/clew-server/src/index.rs
index 0138c4d..283d617 100644
--- a/crates/clew-server/src/index.rs
+++ b/crates/clew-server/src/index.rs
@@ -324,9 +324,13 @@ pub(crate) fn build_doc_one(root: &Path, f: &FileEntry) -> Option<clew_protocol:
         return None;
     }
     let items = clew_core::apidoc::build_file(&source, lang);
-    (!items.is_empty()).then(|| clew_protocol::DocFile {
+    // A file of no API but with its own doc (a `mod.rs` of `pub mod` lines,
+    // a package's `__init__.py`) still defines its module in the glossary.
+    let doc = clew_core::apidoc::module_doc(&source, lang);
+    (!items.is_empty() || !doc.is_empty()).then(|| clew_protocol::DocFile {
         rel: f.rel.clone(),
         items,
+        doc,
     })
 }
 
diff --git a/src/app/glossary.rs b/src/app/glossary.rs
index 19c3cf2..cac4419 100644
--- a/src/app/glossary.rs
+++ b/src/app/glossary.rs
@@ -8,8 +8,9 @@
 //! from the author's doc comment (the API-docs index, as the DOCS tab shows
 //! it), an acronym's from where the docs spell it out — "Debug Adapter
 //! Protocol (DAP)" or "LSP (Language Server Protocol)", the initials
-//! matching — and a module's or folder's from clew's cached explanation of
-//! that file or folder (Explain All). A name with none of these is not a
+//! matching — and a module's from its own doc comment (Rust's `//!`, a
+//! Python docstring), else, like a folder's, from clew's cached explanation
+//! of it (Explain All). A name with none of these is not a
 //! term — a glossary is definitions, and the DOCS tab already lists every
 //! declaration. An all-caps name is no acronym by itself: `MAX` and
 //! `SYSTEM` are constants.
@@ -96,7 +97,31 @@ impl Glossary {
         root: Option<&Path>,
     ) -> Self {
         let mut terms: Vec<Term> = Vec::new();
+        // Files whose own doc defined their module: the author's words win
+        // over an explanation of the same file.
+        let mut self_documented: HashSet<&str> = HashSet::new();
         for file in files {
+            if let Some(definition) = definition_of(&file.doc) {
+                terms.push(Term {
+                    name: crate::ui::module_label(&file.rel),
+                    kind: TermKind::Module,
+                    badge: "module".into(),
+                    rel: file.rel.clone(),
+                    line: 1,
+                    definition,
+                });
+                self_documented.insert(file.rel.as_str());
+            }
+            for (abbr, long) in acronyms_in(&file.doc) {
+                terms.push(Term {
+                    name: abbr,
+                    kind: TermKind::Acronym,
+                    badge: "acronym".into(),
+                    rel: file.rel.clone(),
+                    line: 1,
+                    definition: long,
+                });
+            }
             for item in &file.items {
                 collect_items(item, None, &file.rel, &mut terms);
             }
@@ -117,7 +142,7 @@ impl Glossary {
                     continue;
                 };
                 let rel = rel.to_string_lossy().replace('\\', "/");
-                if rel.is_empty() {
+                if rel.is_empty() || self_documented.contains(rel.as_str()) {
                     continue;
                 }
                 let Some(definition) = definition_of(&cached.summary) else {
@@ -685,6 +710,7 @@ mod glossary_tests {
         let root = PathBuf::from("/p");
         let files = vec![
             DocFile {
+                doc: String::new(),
                 rel: "src/net/client.rs".into(),
                 items: vec![
                     item("Client", "struct", "A connection to one server.", 10),
@@ -715,6 +741,7 @@ mod glossary_tests {
                 ],
             },
             DocFile {
+                doc: String::new(),
                 rel: "src/other.rs".into(),
                 items: vec![
                     item("Client", "struct", "Another one.", 3),
@@ -806,4 +833,56 @@ mod glossary_tests {
         assert_eq!(Glossary::build(&files, &cache, None).len(), 4);
         assert!(Glossary::build(&[], &explain::Cache::new(), Some(&root)).is_empty());
     }
+
+    /// A file's own doc defines its module, ahead of an explanation of the
+    /// same file, and spells out acronyms like an item's doc does — the
+    /// usual place for them, at the top of a file.
+    #[test]
+    fn a_files_own_doc_defines_its_module_and_its_acronyms() {
+        let root = PathBuf::from("/p");
+        let files = vec![
+            DocFile {
+                rel: "src/dap/mod.rs".into(),
+                items: Vec::new(),
+                doc: "Debug Adapter Protocol (DAP) support: clew drives an adapter.".into(),
+            },
+            DocFile {
+                rel: "shop/catalog.py".into(),
+                items: Vec::new(),
+                doc: "The product catalog.".into(),
+            },
+        ];
+        let mut cache = explain::Cache::new();
+        cache.insert(
+            explain::Node::File(root.join("shop/catalog.py")),
+            explain::Cached {
+                summary: "Model words about the catalog.".into(),
+                prompt_hash: 1,
+                detail: None,
+                basis: None,
+            },
+        );
+        let g = Glossary::build(&files, &cache, Some(&root));
+        let dap = g.lookup("DAP").unwrap();
+        assert_eq!(dap.definition, "Debug Adapter Protocol");
+        assert_eq!((dap.rel.as_str(), dap.line), ("src/dap/mod.rs", 1));
+        assert_eq!(
+            g.lookup("dap").unwrap().definition,
+            "Debug Adapter Protocol (DAP) support: clew drives an adapter"
+        );
+        let catalog = g.lookup("shop.catalog").unwrap();
+        assert_eq!(
+            catalog.definition, "The product catalog",
+            "the author's words win"
+        );
+        assert_eq!(
+            g.terms()
+                .iter()
+                .filter(|t| t.rel == "shop/catalog.py")
+                .count(),
+            1,
+            "{:?}",
+            g.terms()
+        );
+    }
 }
diff --git a/src/app/tests.rs b/src/app/tests.rs
index 0baa679..60c483d 100644
--- a/src/app/tests.rs
+++ b/src/app/tests.rs
@@ -9200,6 +9200,7 @@ fn docs_reply(root: &Path, line: usize) -> clew_protocol::Event {
     clew_protocol::Event::Docs {
         root: root.to_string_lossy().into_owned(),
         files: vec![clew_protocol::DocFile {
+            doc: String::new(),
             rel: "src/lib.rs".into(),
             items: vec![clew_protocol::DocItem {
                 name: "origin".into(),
@@ -15473,6 +15474,7 @@ fn a_new_docs_index_rebuilds_and_redraws_an_open_type_map() {
         refs: refs.iter().map(|r| r.to_string()).collect(),
     };
     let task = app.apply_docs(vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/lib.rs".into(),
         items: vec![item("A", &["B"]), item("B", &[])],
     }]);
@@ -18178,6 +18180,7 @@ fn fill_project_session(app: &mut App) {
     p.import_ranks.files = 3;
     let _ = app.update(Message::Reading(ReadingMsg::HistoryClear));
     let _ = app.apply_docs(vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/lib.rs".into(),
         items: Vec::new(),
     }]);
@@ -27015,10 +27018,12 @@ fn hovering_a_glossary_term_shows_its_definition() {
     };
     app.proj.docs.files = vec![
         clew_protocol::DocFile {
+            doc: String::new(),
             rel: "src/net.rs".into(),
             items: vec![item("Client", "A connection to one server. More.")],
         },
         clew_protocol::DocFile {
+            doc: String::new(),
             rel: "src/lib.rs".into(),
             items: vec![item("Parser", "Reads tokens.")],
         },
@@ -27306,6 +27311,7 @@ fn an_export_waits_for_the_docs_index_its_glossary_needs() {
     );
 
     let _ = app.apply_docs(vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/lib.rs".into(),
         items: vec![clew_protocol::DocItem {
             name: "Point".into(),
diff --git a/src/graph/typegraph.rs b/src/graph/typegraph.rs
index c3af1a1..ccf1533 100644
--- a/src/graph/typegraph.rs
+++ b/src/graph/typegraph.rs
@@ -477,6 +477,7 @@ mod tests {
         let root = Path::new("/p");
         let files = vec![
             DocFile {
+                doc: String::new(),
                 rel: "src/model.rs".into(),
                 items: vec![
                     item(
@@ -506,6 +507,7 @@ mod tests {
                 ],
             },
             DocFile {
+                doc: String::new(),
                 rel: "src/money.rs".into(),
                 items: vec![item("Money", "struct", 1, "pub struct Money(u64);", &[])],
             },
@@ -578,6 +580,7 @@ mod tests {
     fn same_named_types_resolve_to_the_right_one_or_to_none() {
         let root = Path::new("/p");
         let file = |rel: &str, items: Vec<DocItem>| DocFile {
+            doc: String::new(),
             rel: rel.into(),
             items,
         };
diff --git a/src/ui/tests.rs b/src/ui/tests.rs
index d2bd1c6..f5c1ba6 100644
--- a/src/ui/tests.rs
+++ b/src/ui/tests.rs
@@ -2782,6 +2782,7 @@ fn the_type_map_lists_the_most_referenced_and_base_types() {
         }
     };
     let files = vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/lib.rs".into(),
         items: vec![
             item(
@@ -3014,6 +3015,7 @@ fn the_flow_tab_lists_occurrences_under_their_roles() {
 fn doc_file(rel: &str, items: &[(&str, bool)]) -> clew_protocol::DocFile {
     serde_json::from_value(serde_json::json!({
         "rel": rel,
+        "doc": "",
         "items": items.iter().enumerate().map(|(i, (name, public))| serde_json::json!({
             "name": name, "kind": "fn", "line": i + 1, "public": public,
             "signature": "", "doc": "", "children": [],
@@ -3586,6 +3588,7 @@ fn the_glossary_page_lists_terms_by_kind() {
         refs: Vec::new(),
     };
     app.proj.docs.files = vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/net.rs".into(),
         items: vec![
             item("Client", "struct", "A connection to one server.", 4),
@@ -3694,6 +3697,7 @@ fn a_long_glossary_section_does_not_hide_the_next() {
         })
         .collect();
     app.proj.docs.files = vec![clew_protocol::DocFile {
+        doc: String::new(),
         rel: "src/types.rs".into(),
         items,
     }];

From 9865be7ef672e16a9153eb58fe66de7d5f9d8d92 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 05:12:19 +0000
Subject: [PATCH 3/4] Open language servers with the project root as a
 workspace folder

pyright looks for a function's callers in other files only within its
workspace folders. Opened on rootUri alone, it answered every incoming
calls request with null, so the LSP-refined call graph lost every
cross-file edge and listed called functions as possibly dead.

initialize now names the root as the one workspace folder, declares
workspace folder support, and answers workspace/workspaceFolders with
the same folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
---
 crates/clew-core/src/lsp/client.rs | 50 ++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/crates/clew-core/src/lsp/client.rs b/crates/clew-core/src/lsp/client.rs
index b5925bd..377cf18 100644
--- a/crates/clew-core/src/lsp/client.rs
+++ b/crates/clew-core/src/lsp/client.rs
@@ -130,6 +130,9 @@ pub struct ServerState {
     /// `workspace/configuration` (e.g. pyright asking for `python.pythonPath`).
     /// Seeded from the resolved initializationOptions at start.
     pub settings: Option<Value>,
+    /// The workspace folders we opened the server on — the project root —
+    /// handed back when the server asks (`workspace/workspaceFolders`).
+    folders: Value,
     /// The server's current complaint, if any (e.g. rust-analyzer's "failed
     /// to load workspace"). Surfaced in the status bar so a server that is
     /// "ready" but couldn't load the project doesn't look healthy while every
@@ -716,6 +719,7 @@ impl LspClient {
         // server that pulls (pyright) still sees our initializationOptions.
         if let Ok(mut s) = state.lock() {
             s.settings = init_options.clone();
+            s.folders = workspace_folders(root);
         }
         let (rpc, mailbox) = framing::mailbox();
         // Reader task: framed stdout → messages.
@@ -1095,6 +1099,11 @@ fn initialize_params(root: &Path, init_options: Option<Value>, process_id: Optio
     let mut params = json!({
         "processId": process_id,
         "rootUri": path_to_uri(root),
+        // The root again, as the one workspace folder. pyright only looks
+        // for a function's callers in other files within its workspace
+        // folders: opened on `rootUri` alone it answered every
+        // `callHierarchy/incomingCalls` with null.
+        "workspaceFolders": workspace_folders(root),
         "capabilities": {
             // Prefer utf-8 so our byte offsets map 1:1 to LSP positions.
             "general": { "positionEncodings": ["utf-8", "utf-16"] },
@@ -1106,6 +1115,9 @@ fn initialize_params(root: &Path, init_options: Option<Value>, process_id: Optio
             "workspace": {
                 // We answer settings pulls (pyright uses this for the venv).
                 "configuration": true,
+                // We name the project root as the one workspace folder, and
+                // answer `workspace/workspaceFolders` with it.
+                "workspaceFolders": true,
                 // We re-request inlay hints when the server asks.
                 "inlayHint": { "refreshSupport": true }
             },
@@ -1133,6 +1145,16 @@ fn initialize_params(root: &Path, init_options: Option<Value>, process_id: Optio
     params
 }
 
+/// The project root as the one LSP workspace folder: its URI, named after
+/// its last component.
+fn workspace_folders(root: &Path) -> Value {
+    let name = root
+        .file_name()
+        .map(|n| n.to_string_lossy())
+        .unwrap_or_else(|| root.to_string_lossy());
+    json!([{ "uri": path_to_uri(root), "name": name }])
+}
+
 /// The actor for one session, then the child's end: a server that was asked
 /// to leave gets [`EXIT_GRACE`]; one whose transport broke — it broke the
 /// protocol, or stopped reading its input — gets none.
@@ -1296,12 +1318,17 @@ impl framing::Protocol for LspWire {
                 Handled::Response { id, result }
             }
             // A server→client request. We answer the config pull (so pyright
-            // et al. get our settings) and acknowledge everything else with a
-            // null result.
+            // et al. get our settings) and the workspace folders, and
+            // acknowledge everything else with a null result.
             Inbound::Request { id, method } => {
                 let result = if method == "workspace/configuration" {
                     let settings = self.state.lock().ok().and_then(|s| s.settings.clone());
                     configuration_response(settings.as_ref(), value.get("params"))
+                } else if method == "workspace/workspaceFolders" {
+                    self.state
+                        .lock()
+                        .map(|s| s.folders.clone())
+                        .unwrap_or(Value::Null)
                 } else {
                     // The server asks us to re-pull inlay hints once they're
                     // ready; bump the epoch the UI watches.
@@ -2321,6 +2348,25 @@ mod session_tests {
         assert_eq!(params["capabilities"]["window"]["workDoneProgress"], true);
     }
 
+    /// The project root is the one workspace folder, in `initialize` and
+    /// when the server asks for the folders: pyright looks for callers in
+    /// other files only within its workspace folders.
+    #[tokio::test]
+    async fn the_project_root_is_the_workspace_folder() {
+        let (_client, mut peer, params) = connected().await;
+        let folders = json!([{ "uri": "file:///proj", "name": "proj" }]);
+        assert_eq!(params["workspaceFolders"], folders);
+        assert_eq!(
+            params["capabilities"]["workspace"]["workspaceFolders"],
+            true
+        );
+        peer.send(json!({"jsonrpc": "2.0", "id": "wf", "method": "workspace/workspaceFolders"}))
+            .await;
+        let reply = peer.next().await;
+        assert_eq!(reply["id"], "wf");
+        assert_eq!(reply["result"], folders);
+    }
+
     /// F5: several progress reports run at once; one ending must not declare
     /// the server idle while another is still going.
     #[test]

From e390500a8502fd75345126b89e714a444d151130 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 05:12:19 +0000
Subject: [PATCH 4/4] Keep an edited value-trace row near its line; tidy empty
 export sections

When a traced file changes and a row's line now reads differently, the
row is still marked changed, but it now moves as far as its nearest
re-found neighbour did. Before, it kept its old line number, which after
an insertion above pointed at an unrelated line. The notice now says the
marked rows were edited since the trace.

An exported notes file no longer has two blank lines after an empty
Notes, Bookmarks or Reading trail section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
---
 src/app/export.rs  | 14 +++++++----
 src/app/flow.rs    | 58 ++++++++++++++++++++++++++++++----------------
 src/app/tests.rs   | 10 ++++++--
 src/editor/flow.rs | 29 +++++++++++++++++++++++
 src/ui/panels.rs   |  2 +-
 5 files changed, 86 insertions(+), 27 deletions(-)

diff --git a/src/app/export.rs b/src/app/export.rs
index ade98cc..6748934 100644
--- a/src/app/export.rs
+++ b/src/app/export.rs
@@ -38,7 +38,7 @@ pub(crate) fn render(x: &Export<'_>) -> String {
 
     out.push_str(&format!("## Notes ({})\n\n", x.notes.len()));
     if x.notes.is_empty() {
-        out.push_str("_No notes._\n\n");
+        out.push_str("_No notes._\n");
     }
     for n in x.notes {
         let mark = if n.understood { " ✓ understood" } else { "" };
@@ -55,7 +55,7 @@ pub(crate) fn render(x: &Export<'_>) -> String {
 
     out.push_str(&format!("## Bookmarks ({})\n\n", x.bookmarks.len()));
     if x.bookmarks.is_empty() {
-        out.push_str("_No bookmarks._\n\n");
+        out.push_str("_No bookmarks._\n");
     }
     for b in x.bookmarks {
         let preview = code(b.preview.trim());
@@ -74,7 +74,7 @@ pub(crate) fn render(x: &Export<'_>) -> String {
 
     out.push_str(&format!("## Reading trail ({})\n\n", x.trail.len()));
     if x.trail.is_empty() {
-        out.push_str("_No trail._\n\n");
+        out.push_str("_No trail._\n");
     }
     // A straight run of visits is one list; it nests only where the trail
     // forks — where the reader went back and took another way — and each
@@ -363,6 +363,7 @@ mod export_tests {
             }],
         }];
         let mut glossary_files = vec![clew_protocol::DocFile {
+            doc: String::new(),
             rel: "src/lib.rs".into(),
             items: vec![clew_protocol::DocItem {
                 name: "Parser".into(),
@@ -424,7 +425,8 @@ _Scope: boot_
 ";
         assert_eq!(md, expected);
 
-        // Empty everything: the sections stay, each saying it is empty.
+        // Empty everything: the sections stay, each saying it is empty, one
+        // blank line apart.
         glossary_files.clear();
         let empty = Glossary::build(&glossary_files, &explain::Cache::new(), Some(&root));
         let md = render(&Export {
@@ -445,6 +447,10 @@ _Scope: boot_
         ] {
             assert!(md.contains(section), "missing {section:?} in:\n{md}");
         }
+        assert!(
+            !md.contains("\n\n\n"),
+            "one blank line between sections:\n{md}"
+        );
     }
 
     /// A straight run of visits stays one list; the trail nests only where
diff --git a/src/app/flow.rs b/src/app/flow.rs
index 531c347..f3c1922 100644
--- a/src/app/flow.rs
+++ b/src/app/flow.rs
@@ -13,8 +13,8 @@
 //! Lines are classified as the file has them, untrimmed, so the server's
 //! columns land where they point. When a traced file changes, each
 //! occurrence follows its line by the line's text (`App::reanchor_flow`);
-//! one whose line reads differently now is marked changed, and the tab
-//! offers to trace again.
+//! one whose line reads differently now is marked changed, moved as far as
+//! its nearest followed neighbour, and the tab offers to trace again.
 //!
 //! Line text comes from the open panes when the file is open, else off disk
 //! for a local project. A remote project's occurrences in files not open
@@ -68,7 +68,7 @@ pub struct FlowNode {
     /// trimmed.
     pub indent: usize,
     /// The file changed since and this line could not be found in it any
-    /// more: the row shows where it was.
+    /// more: the row keeps what it read, at about where the line went.
     pub changed: bool,
     pub depth: usize,
     pub parent: Option<usize>,
@@ -735,8 +735,9 @@ impl App {
     /// Follow the trace's occurrences in `path` to their lines in its new
     /// `content` (`None`: the file is gone): each by its own line's text,
     /// nearest where it was, so a row still opens where its line now is. An
-    /// occurrence whose line reads differently now is marked changed and the
-    /// trace stale — the tab offers to trace again.
+    /// occurrence whose line reads differently now is marked changed, moved
+    /// as far as its nearest followed neighbour, and the trace stale — the
+    /// tab offers to trace again.
     pub(crate) fn reanchor_flow(&mut self, path: &Path, content: Option<&str>) {
         let Some(lang) = self
             .proj
@@ -757,26 +758,43 @@ impl App {
         let Some(tree) = self.proj.flow.as_mut() else {
             return;
         };
-        let mut stale = false;
-        for node in tree.nodes.iter_mut().filter(|n| n.abs == path) {
+        let place = |node: &mut FlowNode, line: usize| {
+            let raw = lines[line];
+            let col = crate::flow::nearest_word(raw, &node.symbol, node.col)
+                .unwrap_or_else(|| node.col.min(raw.chars().count()));
+            node.line = line;
+            node.col = col;
+            node.character = viewer::Col(col).to_offset(raw, encoding);
+            node.indent = raw.chars().take_while(|c| c.is_whitespace()).count();
+        };
+        // Rows whose line still reads the same move to it; the rest are
+        // changed, and move as far as their nearest found neighbour did.
+        let mut anchors = Vec::new();
+        let mut lost = Vec::new();
+        for (i, node) in tree.nodes.iter_mut().enumerate() {
+            if node.abs != path {
+                continue;
+            }
             let found = content
                 .filter(|_| node.classified)
                 .and_then(|_| crate::flow::moved_line(&lines, &node.text, node.line));
-            if let Some(line) = found {
-                let raw = lines[line];
-                let col =
-                    crate::flow::nearest_word(raw, &node.symbol, node.col).unwrap_or(node.col);
-                node.line = line;
-                node.col = col;
-                node.character = viewer::Col(col).to_offset(raw, encoding);
-                node.indent = raw.chars().take_while(|c| c.is_whitespace()).count();
-                node.changed = false;
-            } else {
-                node.changed = true;
-                stale = true;
+            match found {
+                Some(line) => {
+                    anchors.push((node.line, line));
+                    place(node, line);
+                    node.changed = false;
+                }
+                None => lost.push(i),
+            }
+        }
+        tree.stale |= !lost.is_empty();
+        for i in lost {
+            let node = &mut tree.nodes[i];
+            node.changed = true;
+            if let Some(line) = crate::flow::carried_line(&anchors, node.line, lines.len()) {
+                place(node, line);
             }
         }
-        tree.stale |= stale;
     }
 
     /// Trace the same identifier again from where it was asked for, found
diff --git a/src/app/tests.rs b/src/app/tests.rs
index 60c483d..2b13ac5 100644
--- a/src/app/tests.rs
+++ b/src/app/tests.rs
@@ -27217,8 +27217,9 @@ async fn following_a_value_reads_a_wrapped_signature_from_disk() {
 }
 
 /// A value trace follows its file's edits: each occurrence moves to where
-/// its line went; one whose line is gone is marked changed and the trace
-/// stale, and "trace again" traces the same name where it now is.
+/// its line went; one whose line reads differently is marked changed, moved
+/// as far as its neighbour, and the trace stale; and "trace again" traces
+/// the same name where it now is.
 #[test]
 fn a_value_trace_follows_its_lines_when_the_file_changes() {
     use crate::app::flow::Role;
@@ -27260,6 +27261,11 @@ fn a_value_trace_follows_its_lines_when_the_file_changes() {
     assert_eq!((tree.node(2).line, tree.node(2).changed), (4, false));
     assert_eq!(tree.node(2).character, 4);
     assert!(tree.node(1).changed, "its line reads differently now");
+    assert_eq!(
+        (tree.node(1).line, tree.node(1).col),
+        (3, 9),
+        "it moves as far as the line above it did, onto the name"
+    );
     assert!(tree.stale);
     assert_eq!(tree.node(1).role, Role::Passed, "the row keeps what it was");
     // Another file's change leaves the trace alone.
diff --git a/src/editor/flow.rs b/src/editor/flow.rs
index c2d79b7..a3e8444 100644
--- a/src/editor/flow.rs
+++ b/src/editor/flow.rs
@@ -498,6 +498,22 @@ pub fn moved_line<S: AsRef<str>>(lines: &[S], text: &str, old: usize) -> Option<
     })
 }
 
+/// Where a traced line whose text is gone most likely went, in a file now
+/// `len` lines long: `old` moved by as much as its nearest neighbour that
+/// was found again (the closest one above, else the closest below), each
+/// given in `anchors` as its `(old, new)` line. With no neighbour found, the
+/// line stays put. `None` when the file is empty.
+pub fn carried_line(anchors: &[(usize, usize)], old: usize, len: usize) -> Option<usize> {
+    let last = len.checked_sub(1)?;
+    let above = anchors.iter().filter(|a| a.0 <= old).max_by_key(|a| a.0);
+    let below = || anchors.iter().filter(|a| a.0 > old).min_by_key(|a| a.0);
+    let line = match above.or_else(below) {
+        Some(&(from, to)) => (old + to).saturating_sub(from),
+        None => old,
+    };
+    Some(line.min(last))
+}
+
 /// The char column of the whole-word occurrence of `word` in `line` nearest
 /// to column `near`.
 pub fn nearest_word(line: &str, word: &str, near: usize) -> Option<usize> {
@@ -610,6 +626,19 @@ mod tests {
         assert_eq!(nearest_word("abc", "ab", 0), None);
     }
 
+    #[test]
+    fn a_rewritten_line_moves_with_its_nearest_found_neighbour() {
+        // Lines 3 and 9 were found again two lines down and one line up.
+        let anchors = [(3, 5), (9, 8)];
+        assert_eq!(carried_line(&anchors, 4, 20), Some(6), "follows 3 → 5");
+        assert_eq!(carried_line(&anchors, 12, 20), Some(11), "follows 9 → 8");
+        assert_eq!(carried_line(&anchors, 1, 20), Some(3), "only 3 is near");
+        assert_eq!(carried_line(&anchors, 4, 5), Some(4), "kept in the file");
+        assert_eq!(carried_line(&[(3, 0)], 1, 20), Some(0), "never above 0");
+        assert_eq!(carried_line(&[], 7, 20), Some(7), "nothing to follow");
+        assert_eq!(carried_line(&anchors, 4, 0), None, "the file is empty");
+    }
+
     fn of(line: &str, word: &str) -> Use {
         let col = line.find(word).expect("the word is on the line");
         classify(line, line[..col].chars().count(), word)
diff --git a/src/ui/panels.rs b/src/ui/panels.rs
index ac0ddee..2fae4b6 100644
--- a/src/ui/panels.rs
+++ b/src/ui/panels.rs
@@ -713,7 +713,7 @@ pub(crate) fn flow_tab(app: &App) -> Element<'_, Message> {
         rows.push(
             container(
                 row![
-                    text("A traced file changed: rows marked changed are where their line was.")
+                    text("A traced file changed: rows marked changed were edited since the trace.")
                         .size(ts::CAPTION)
                         .color(theme::warning())
                         .width(Fill),