@px-lsp/server 0.1.0

package/src/data/defines.ts

@@ -0,0 +1,123 @@
+/**
+ * Engine defines harvest: `define:NNamespace|CONSTANT` references (grep-verified
+ * pipe separator) resolve against top-level namespace blocks in
+ * `common/defines/**\/*.txt`. Layers lowest→highest priority: jomini (6 files
+ * exist only here), game (00_defines.txt + ai/audio/graphic/jomini subdirs),
+ * read-only dependency parents, then the mod. Last-wins per (namespace,
+ * constant).
+ *
+ * In-memory only — a few thousand entries; NOT persisted into the vanillaIndex
+ * cache. No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { LineIndex, parseScript, type ValueNode } from "../parser";
+import { walkDir } from "@px-lsp/protocol/fsWalk";
+
+export type DefineLayer = "jomini" | "game" | "parent" | "mod";
+
+const LAYER_RANK: Record<DefineLayer, number> = { jomini: 0, game: 1, parent: 2, mod: 3 };
+
+export interface DefineEntry {
+  namespace: string;
+  name: string;
+  /** Rendered value: the scalar text, or a collapsed `{ … }` for block values. */
+  value: string;
+  file: string;
+  line: number; // 0-based
+  layer: DefineLayer;
+}
+
+export interface DefineResolution {
+  winner: DefineEntry;
+  /** Lower-priority entries the winner shadows, highest-priority first. */
+  shadowed: DefineEntry[];
+}
+
+/** Scalar text, or a whitespace-collapsed `{ … }` rendering for block values. */
+function renderValue(text: string, value: ValueNode): string {
+  if (value.kind === "scalar") return value.quoted ? `"${value.text}"` : value.text;
+  const raw = text.slice(value.range.start, value.range.end);
+  const collapsed = raw
+    .replace(/#[^\n]*/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return collapsed.length > 200 ? collapsed.slice(0, 199) + "…" : collapsed;
+}
+
+export class DefinesIndex {
+  /** namespace -> constant -> entries in ascending priority (winner last). */
+  private ns = new Map<string, Map<string, DefineEntry[]>>();
+
+  /** Harvest one root's `common/defines` tree at the given layer. */
+  addLayer(root: string, layer: DefineLayer): void {
+    const files: string[] = [];
+    walkDir(path.join(root, "common", "defines"), ".txt", files);
+    for (const file of files.sort()) {
+      let text: string;
+      try {
+        text = fs.readFileSync(file, "utf8").replace(/^/, "");
+      } catch {
+        continue;
+      }
+      this.harvestText(text, file, layer);
+    }
+  }
+
+  /** Parse one defines file: top-level blocks are namespaces, their scalars constants. */
+  harvestText(text: string, file: string, layer: DefineLayer): void {
+    const { root } = parseScript(text);
+    const lines = new LineIndex(text);
+    for (const stmt of root.statements) {
+      if (stmt.kind !== "assignment" || stmt.key.quoted) continue;
+      const block = stmt.value;
+      if (!block || block.kind !== "block") continue;
+      const namespace = stmt.key.text;
+      let consts = this.ns.get(namespace);
+      if (!consts) this.ns.set(namespace, (consts = new Map()));
+      for (const inner of block.statements) {
+        if (inner.kind !== "assignment" || inner.key.quoted || inner.value === null) continue;
+        const name = inner.key.text;
+        const entry: DefineEntry = {
+          namespace,
+          name,
+          value: renderValue(text, inner.value),
+          file,
+          line: lines.positionAt(inner.key.range.start).line,
+          layer,
+        };
+        let list = consts.get(name);
+        if (!list) consts.set(name, (list = []));
+        list.push(entry);
+        // Stable sort keeps same-layer insertion order; winner is the last entry.
+        list.sort((a, b) => LAYER_RANK[a.layer] - LAYER_RANK[b.layer]);
+      }
+    }
+  }
+
+  namespaces(): string[] {
+    return [...this.ns.keys()].sort();
+  }
+
+  /** Winning constants of a namespace, name-sorted. */
+  constants(namespace: string): DefineEntry[] {
+    const consts = this.ns.get(namespace);
+    if (!consts) return [];
+    return [...consts.values()]
+      .map((list) => list[list.length - 1])
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  }
+
+  resolve(namespace: string, name: string): DefineResolution | null {
+    const list = this.ns.get(namespace)?.get(name);
+    if (!list || list.length === 0) return null;
+    return { winner: list[list.length - 1], shadowed: list.slice(0, -1).reverse() };
+  }
+
+  /** Winning-constant count across all namespaces (status log line). */
+  get count(): number {
+    let n = 0;
+    for (const consts of this.ns.values()) n += consts.size;
+    return n;
+  }
+}

package/src/data/docsParser.ts

@@ -0,0 +1,453 @@
+/**
+ * Parser for the Jomini `script_docs` console command output:
+ * triggers.log, effects.log, event_targets.log, modifiers.log.
+ *
+ * The format is line-based and has shifted slightly between game patches, so parse
+ * defensively: entries are separated by dashed lines; the first content line is
+ * usually `name - description`; known metadata lines (`Supported Scopes:` etc.) are
+ * extracted; anything unrecognized is appended to `doc` or `traits` instead of failing.
+ *
+ * Newer Jomini titles dump the same information in different shapes; which one a
+ * game uses is declared by its profile (GameMeta.scriptDocs, absent = classic):
+ *   - "markdown" logs: `## name` / `### name` headings, `**Supported Scopes**: …`.
+ *   - "masked-block" modifiers: `name:` + indented Mask/Name/Description lines.
+ *   - "tag-line" modifiers: one `Tag: name, Categories: …` line per modifier.
+ * All of them produce the same TokenData shape, so everything downstream (hover,
+ * completion, the docs cache) is format-agnostic.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type { TokenData, TokenKind } from "@px-lsp/protocol/types";
+import { LOG_FILES } from "@px-lsp/protocol/constants";
+import { activeProfile } from "../games/active";
+
+export { LOG_FILES };
+
+const SEPARATOR = /^-{4,}\s*$/;
+const NAME_DESC = /^([A-Za-z0-9_.:<>|[\]]+)\s+-\s*(.*)$/;
+const BARE_NAME = /^([A-Za-z0-9_]+)\s*$/;
+// A `usage:` section header; everything until the next metadata line is the example.
+const USAGE_HEADER = /^usage:\s*$/i;
+// An inline syntax example line: `add_hook = { … }`, `<scheme starter> = …`,
+// or a comparison form like `monthly_income > 10`.
+const SYNTAX_LINE = /^(?:<[^>]+>|[A-Za-z_][A-Za-z0-9_]*)\s*(?:[<>]=?|!=|=)/;
+// modifiers.log style: "Tag: monthly_income, Categories: character".
+// `$` admits templated tags ($CULTURE$_opinion); they are split off into
+// DocsLoadResult.templates downstream, never into the concrete token list.
+const TAG_LINE = /^Tag:\s*([A-Za-z0-9_.$]+)\s*(?:,\s*(.*))?$/;
+const SCOPE_LINE = /^(Supported [Ss]copes|Input [Ss]copes|Output [Ss]copes):\s*(.*)$/;
+const META_LINE =
+  /^(Supported [Tt]argets|Targets?|Traits|Categories|Use [Aa]reas|Requires [Dd]ata|Wild[ _]?[Cc]ard|Global [Ll]ink):\s*(.*)$/;
+
+export function parseLog(content: string, kind: TokenKind): TokenData[] {
+  const tokens: TokenData[] = [];
+  const seen = new Set<string>();
+  const lines = content.split(/\r?\n/);
+
+  let current: TokenData | null = null;
+  // True once a `usage:` header was seen for the current entry: subsequent
+  // non-metadata lines are captured (with indentation) as the usage example.
+  let inUsage = false;
+  const flush = () => {
+    if (current && current.name && !seen.has(current.name)) {
+      current.doc = current.doc.trim();
+      if (current.traits) current.traits = current.traits.trim();
+      if (current.usage) current.usage = current.usage.replace(/^\n+|\s+$/g, "");
+      if (!current.usage) delete current.usage;
+      seen.add(current.name);
+      tokens.push(current);
+    }
+    current = null;
+    inUsage = false;
+  };
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (SEPARATOR.test(line)) {
+      flush();
+      continue;
+    }
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      // Blank lines inside a `usage:` block are structural; keep them.
+      if (current && inUsage && current.usage) current.usage += "\n";
+      continue;
+    }
+
+    // modifiers.log (1.19+) has no dashed separators: every "Tag:" line
+    // begins a new entry. Templated tags ($CULTURE$_opinion) parse like any
+    // other; callers partition them out (script references the expanded
+    // names, so they feed lazy expansion — modifierTemplates.ts).
+    if (trimmed.startsWith("Tag:")) {
+      flush();
+      const m = TAG_LINE.exec(trimmed);
+      if (m) {
+        current = { name: m[1], kind, doc: "", scopes: [] };
+        inUsage = false;
+        if (m[2]) applyMetaLine(current, m[2]);
+      }
+      continue;
+    }
+
+    if (!current) {
+      let m = NAME_DESC.exec(trimmed);
+      if (m) {
+        current = { name: m[1], kind, doc: m[2], scopes: [] };
+        inUsage = false;
+        continue;
+      }
+      m = BARE_NAME.exec(trimmed);
+      if (m) {
+        current = { name: m[1], kind, doc: "", scopes: [] };
+        inUsage = false;
+        continue;
+      }
+      // Preamble text ("Printing a list of ..."); skip.
+      continue;
+    }
+
+    // A metadata line ends any open usage capture and is recorded structurally.
+    if (applyMetaLine(current, trimmed)) {
+      inUsage = false;
+      continue;
+    }
+    // `usage:` opens a multi-line syntax block; the header itself is dropped.
+    if (USAGE_HEADER.test(trimmed)) {
+      inUsage = true;
+      continue;
+    }
+    if (inUsage) {
+      current.usage = current.usage ? current.usage + "\n" + line : line;
+      continue;
+    }
+    // A lone inline syntax example (`add_hook = { … }`): the first one becomes
+    // the usage example; anything after it stays prose.
+    if (current.usage === undefined && SYNTAX_LINE.test(trimmed)) {
+      current.usage = trimmed;
+      continue;
+    }
+    // Otherwise: continuation of the description prose.
+    current.doc = current.doc === "" ? trimmed : current.doc + "\n" + trimmed;
+  }
+  flush();
+  return tokens;
+}
+
+/** Returns true if the line was a recognized metadata line and has been recorded. */
+function applyMetaLine(token: TokenData, line: string): boolean {
+  const scope = SCOPE_LINE.exec(line);
+  if (scope) {
+    const label = scope[1].toLowerCase();
+    const values = scope[2]
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .filter((s) => s !== "");
+    const prefix = label.startsWith("input") ? "input: " : label.startsWith("output") ? "output: " : "";
+    for (const v of values) token.scopes.push(prefix + v);
+    return true;
+  }
+  const meta = META_LINE.exec(line);
+  if (meta) {
+    const entry = `${meta[1]}: ${meta[2]}`;
+    token.traits = token.traits ? token.traits + "\n" + entry : entry;
+    return true;
+  }
+  return false;
+}
+
+// --- Newer dump dialects ------------------------------------------------
+
+// `## effect_name` / `### event_target_name`. Level 1 is the file title
+// ("# Effect Documentation") and starts no entry.
+const MD_HEADING = /^(#{1,6})\s+(.+?)$/;
+// `**Supported Scopes**: state` — the bold wrapper is the only difference from
+// the classic metadata lines, so it is unwrapped and fed to applyMetaLine.
+const MD_BOLD_LABEL = /^\*\*([^*]+)\*\*\s*:/;
+// `battle_casualties_mult:` opens a masked-block entry; its Mask/Name/Description
+// lines are indented underneath it.
+const MASKED_NAME = /^([A-Za-z0-9_.$]+):\s*$/;
+const MASKED_FIELD = /^(Mask|Name|Description):\s*(.*)$/;
+// `--- Static modifier types ---` and friends: section banners, not entries.
+const SECTION_BANNER = /^-{3,}/;
+
+const braceDelta = (s: string): number => (s.match(/\{/g) ?? []).length - (s.match(/\}/g) ?? []).length;
+
+/**
+ * Markdown dump dialect (effects.log, triggers.log, event_targets.log of newer
+ * titles): entries open at a `##`/`###` heading and run until the next one.
+ * Metadata lines are the classic ones, optionally bold-wrapped; the remaining
+ * body is prose, except a leading `name = { … }` example which is lifted into
+ * `usage` (multi-line examples are followed until the braces balance).
+ */
+export function parseMarkdownLog(content: string, kind: TokenKind): TokenData[] {
+  const tokens: TokenData[] = [];
+  const seen = new Set<string>();
+
+  let current: TokenData | null = null;
+  // >0 while a multi-line usage example is still open.
+  let openBraces = 0;
+  const flush = () => {
+    if (current && current.name && !seen.has(current.name)) {
+      current.doc = current.doc.trim();
+      if (current.traits) current.traits = current.traits.trim();
+      if (current.usage) current.usage = current.usage.trim();
+      if (!current.usage) delete current.usage;
+      seen.add(current.name);
+      tokens.push(current);
+    }
+    current = null;
+    openBraces = 0;
+  };
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    // Markdown hard line breaks are trailing double spaces; they are noise here.
+    const line = rawLine.trimEnd();
+    const heading = MD_HEADING.exec(line);
+    if (heading) {
+      flush();
+      if (heading[1].length > 1) current = { name: heading[2].trim(), kind, doc: "", scopes: [] };
+      continue;
+    }
+    const trimmed = line.trim();
+    // A trailing `------` appendix (bare lists of code-saved scope names) is not
+    // part of any entry.
+    if (SEPARATOR.test(trimmed)) {
+      flush();
+      continue;
+    }
+    if (!current) continue;
+    const meta = trimmed.replace(MD_BOLD_LABEL, "$1:");
+    if (openBraces > 0) {
+      // Some dumped examples never close their braces (`switch = { … ` has no
+      // final `}`); a metadata line always ends the entry's body, so it wins.
+      if (applyMetaLine(current, meta)) {
+        openBraces = 0;
+        continue;
+      }
+      current.usage += "\n" + line;
+      openBraces += braceDelta(line);
+      continue;
+    }
+    if (trimmed === "") continue;
+    if (applyMetaLine(current, meta)) continue;
+    if (current.usage === undefined && SYNTAX_LINE.test(trimmed)) {
+      current.usage = trimmed;
+      openBraces = Math.max(0, braceDelta(trimmed));
+      continue;
+    }
+    current.doc = current.doc === "" ? trimmed : current.doc + "\n" + trimmed;
+  }
+  flush();
+  return tokens;
+}
+
+/**
+ * "masked-block" modifiers.log: `name:` followed by indented `Mask:`, `Name:`
+ * and `Description:` lines (the display name and description become the doc,
+ * the mask is metadata). Descriptions may continue on later unindented lines.
+ */
+export function parseMaskedBlockModifiers(content: string, kind: TokenKind): TokenData[] {
+  const tokens: TokenData[] = [];
+  const seen = new Set<string>();
+  let current: TokenData | null = null;
+  const flush = () => {
+    if (current && !seen.has(current.name)) {
+      current.doc = current.doc.trim();
+      seen.add(current.name);
+      tokens.push(current);
+    }
+    current = null;
+  };
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    const trimmed = line.trim();
+    if (SECTION_BANNER.test(trimmed)) {
+      flush();
+      continue;
+    }
+    const name = MASKED_NAME.exec(line);
+    if (name) {
+      flush();
+      current = { name: name[1], kind, doc: "", scopes: [] };
+      continue;
+    }
+    if (!current || trimmed === "") continue;
+    const field = MASKED_FIELD.exec(trimmed);
+    if (field && field[1] === "Mask") {
+      current.traits = current.traits ? current.traits + "\n" + trimmed : trimmed;
+      continue;
+    }
+    // Name/Description text, plus any unindented continuation of it.
+    const text = field ? field[2] : trimmed;
+    if (text !== "") current.doc = current.doc === "" ? text : current.doc + "\n" + text;
+  }
+  flush();
+  return tokens;
+}
+
+/**
+ * "tag-line" modifiers.log: one `Tag: name, Categories: Country, , All,` line
+ * per modifier (the category list is padded with empty entries). No description
+ * is dumped, so the categories are all the metadata there is.
+ */
+export function parseTagLineModifiers(content: string, kind: TokenKind): TokenData[] {
+  const tokens: TokenData[] = [];
+  const seen = new Set<string>();
+  for (const rawLine of content.split(/\r?\n/)) {
+    const m = TAG_LINE.exec(rawLine.trim());
+    if (!m || seen.has(m[1])) continue;
+    seen.add(m[1]);
+    const token: TokenData = { name: m[1], kind, doc: "", scopes: [] };
+    const categories = (m[2] ?? "")
+      .replace(/^Categories:\s*/i, "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s !== "");
+    if (categories.length > 0) token.traits = `Categories: ${categories.join(", ")}`;
+    tokens.push(token);
+  }
+  return tokens;
+}
+
+export interface DocsLoadResult {
+  tokens: TokenData[];
+  /** Templated modifier tags ($CULTURE$_opinion), for lazy expansion. */
+  templates: TokenData[];
+  /** mtimeMs per log file found; the cache key. */
+  mtimes: Record<string, number>;
+  /** Log file names that were missing from logsPath. */
+  missing: string[];
+  fromCache: boolean;
+}
+
+/**
+ * Parse on_actions.log (console `script_docs` output): each entry documents an
+ * on_action's expected root scope. Returns an empty map when the log is absent.
+ *
+ *   on_death:
+ *   From Code: Yes
+ *   Expected Scope: character
+ */
+export function parseOnActionsLog(logsDir: string): Map<string, string> {
+  const scopes = new Map<string, string>();
+  let content: string;
+  try {
+    content = fs.readFileSync(path.join(logsDir, "on_actions.log"), "utf8");
+  } catch {
+    return scopes;
+  }
+  const entry = /^([A-Za-z0-9_.-]+):\s*\r?\nFrom Code: (?:Yes|No)\s*\r?\nExpected Scope: (\w+)/gm;
+  let m: RegExpExecArray | null;
+  while ((m = entry.exec(content)) !== null) scopes.set(m[1], m[2].toLowerCase());
+  return scopes;
+}
+
+/** The parser for one log, per the active profile's dump dialect. */
+function parserFor(kind: TokenKind): (content: string, kind: TokenKind) => TokenData[] {
+  const dialect = activeProfile().scriptDocs;
+  if (kind === "modifier") {
+    if (dialect?.modifiers === "masked-block") return parseMaskedBlockModifiers;
+    if (dialect?.modifiers === "tag-line") return parseTagLineModifiers;
+    return parseLog;
+  }
+  return dialect?.format === "markdown" ? parseMarkdownLog : parseLog;
+}
+
+/** Parse the four script_docs logs found in `logsDir`. Missing files are reported, not fatal. */
+export function loadTokenDataFromLogs(logsDir: string): DocsLoadResult {
+  const tokens: TokenData[] = [];
+  const templates: TokenData[] = [];
+  const mtimes: Record<string, number> = {};
+  const missing: string[] = [];
+  for (const { file, kind } of LOG_FILES) {
+    const full = path.join(logsDir, file);
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      missing.push(file);
+      continue;
+    }
+    mtimes[file] = stat.mtimeMs;
+    try {
+      for (const t of parserFor(kind)(fs.readFileSync(full, "utf8"), kind)) {
+        (t.name.includes("$") ? templates : tokens).push(t);
+      }
+    } catch {
+      missing.push(file);
+    }
+  }
+  return { tokens, templates, mtimes, missing, fromCache: false };
+}
+
+interface DocsCacheFile {
+  cacheFormat: number;
+  mtimes: Record<string, number>;
+  tokens: TokenData[];
+  templates: TokenData[];
+}
+
+// Bump when the parsed TokenData shape changes (a stale mtime-keyed cache would
+// otherwise serve old parses). 3: templated modifier tags ($CULTURE$_opinion).
+// 4: added the `usage` field (syntax examples).
+// 5: per-profile dump dialects (markdown / masked-block / tag-line), which the
+// classic parser had mangled into near-empty caches for the newer titles.
+const DOCS_CACHE_FORMAT = 5;
+
+/** Load token data, using the JSON cache when log mtimes are unchanged. */
+export function loadTokenData(logsDir: string, cacheFile: string, forceReparse = false): DocsLoadResult {
+  const fresh = () => {
+    const result = loadTokenDataFromLogs(logsDir);
+    try {
+      fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+      const payload: DocsCacheFile = {
+        cacheFormat: DOCS_CACHE_FORMAT,
+        mtimes: result.mtimes,
+        tokens: result.tokens,
+        templates: result.templates,
+      };
+      fs.writeFileSync(cacheFile, JSON.stringify(payload));
+    } catch {
+      // Cache write failure is non-fatal.
+    }
+    return result;
+  };
+
+  if (forceReparse) return fresh();
+
+  let cached: DocsCacheFile;
+  try {
+    cached = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+  } catch {
+    return fresh();
+  }
+  if (cached.cacheFormat !== DOCS_CACHE_FORMAT || !cached.tokens || !cached.templates || !cached.mtimes)
+    return fresh();
+
+  // Cache is valid only if the exact same set of files exists with the same mtimes.
+  const currentMtimes: Record<string, number> = {};
+  const missing: string[] = [];
+  for (const { file } of LOG_FILES) {
+    try {
+      currentMtimes[file] = fs.statSync(path.join(logsDir, file)).mtimeMs;
+    } catch {
+      missing.push(file);
+    }
+  }
+  const cachedKeys = Object.keys(cached.mtimes).sort().join(",");
+  const currentKeys = Object.keys(currentMtimes).sort().join(",");
+  const same =
+    cachedKeys === currentKeys && Object.entries(currentMtimes).every(([f, t]) => cached.mtimes[f] === t);
+  if (!same) return fresh();
+
+  return {
+    tokens: cached.tokens,
+    templates: cached.templates,
+    mtimes: cached.mtimes,
+    missing,
+    fromCache: true,
+  };
+}

package/src/data/keywordDocs.ts

@@ -0,0 +1,98 @@
+/**
+ * Curated docs for grammar/math keywords that no other layer serves: script_docs
+ * documents triggers/effects but not the glue vocabulary (limit, NOT, base…),
+ * which the 2026-07 mod-coverage audit measured as the single biggest source of
+ * empty hovers (~1400 uses in one mid-size mod). Served by hover as a fallback
+ * card, so a real token/definition with the same name always wins.
+ */
+
+export const KEYWORD_DOCS: Record<string, string> = {
+  // Control flow (effects)
+  if: "Conditional effect: runs its contents when its `limit = { … }` trigger holds.",
+  else_if: "Runs when the preceding if/else_if did not, and its own `limit` holds.",
+  else: "Runs when the preceding if/else_if did not.",
+  while: "Loop effect: repeats while `limit` holds, or `count` times.",
+  switch: "Branches on one trigger: `switch = { trigger = x case_a = { … } fallback = { … } }`.",
+  // Control flow (triggers)
+  trigger_if: "Conditional trigger: contents are only checked when its `limit` holds.",
+  trigger_else_if: "Checked when the preceding trigger_if did not apply and its own `limit` holds.",
+  trigger_else: "Checked when the preceding trigger_if did not apply.",
+  limit:
+    "Trigger block: restricts the enclosing if / iterator / random_list entry to cases where these triggers hold.",
+  alternative_limit: "Additional trigger set an iterator accepts when `limit` fails.",
+  // Logic connectives
+  AND: "All child triggers must be true (the implicit default).",
+  OR: "At least one child trigger must be true.",
+  NOT: "True when the child trigger is false. Alias of NOR: with several children, true when none hold.",
+  NOR: "True when none of the child triggers are true.",
+  NAND: "True when at least one child trigger is false.",
+  calc_true_if: "True when at least `amount = N` of the listed triggers hold.",
+  // Script-value math
+  base: "Starting value of a script-value block; later steps (add, multiply…) modify it.",
+  value: "Sets the current value directly — a number, another script value, or a scope chain.",
+  add: "Adds to the current value (number, script value, or `{ … }` block). Inside weights, raises the weight.",
+  subtract: "Subtracts from the current value.",
+  multiply: "Multiplies the current value.",
+  divide: "Divides the current value.",
+  modulo: "Remainder of dividing the current value.",
+  min: "Lower clamp of the surrounding script value.",
+  max: "Upper clamp of the surrounding script value.",
+  round: "Round to the nearest integer (yes/no).",
+  ceiling: "Round up to an integer (yes/no).",
+  floor: "Round down to an integer (yes/no).",
+  fixed_range: "A uniformly random value between `min` and `max` (re-rolls each evaluation).",
+  integer_range: "A uniformly random integer between `min` and `max`.",
+  save_temporary_value_as:
+    "Saves the current value of this script-value calculation under a name; read it back later in the same calculation as `scope:<name>`.",
+  factor: "Multiplies the surrounding weight/value when the enclosing modifier's trigger holds.",
+  weight: "Weight of this entry when the game picks one of several candidates.",
+  // Durations & chances
+  days: "Duration in days: a number, a `{ min max }` range, or a script value.",
+  weeks: "Duration in weeks: a number, a range, or a script value.",
+  months: "Duration in months: a number, a range, or a script value.",
+  years: "Duration in years: a number, a range, or a script value.",
+  chance: "Percent chance, 0–100.",
+  // Iterators / lists
+  count: "How many list members must match (a number or `all`), or how many times to repeat.",
+  percent: "Fraction of list members that must match (0–1).",
+  order_by: "Script value an ordered_ iterator sorts by (descending).",
+  position: "0-based index the ordered_ iterator picks after sorting.",
+  // Descriptions & misc
+  trigger: "Trigger block: conditions that must hold for the surrounding item to apply or fire.",
+  effect: "Effect block: commands run when the surrounding item fires.",
+  desc: "Description: a loc key, or a dynamic-description block (first_valid / triggered_desc / random_valid).",
+  namespace: "Declares this file's event-id namespace: events are then named `<namespace>.<n>`.",
+  alias: "Alternate names for this game concept — each works in loc [Concept|E] links.",
+  // ai_will_do / ai_chance modifier vocabulary (_scripted_modifiers.info)
+  who: "Character whose opinion is measured, in an opinion_modifier weight.",
+  opinion_target: "Character the opinion is about, in an opinion_modifier weight.",
+  multiplier: "Weight applied per opinion/value point in opinion_modifier / compare_modifier.",
+  step: "compare_modifier: granularity — the value is divided into steps of this size.",
+};
+
+/** Lowercase logic words double the uppercase forms. */
+for (const k of ["AND", "OR", "NOT", "NOR", "NAND"]) {
+  KEYWORD_DOCS[k.toLowerCase()] = KEYWORD_DOCS[k];
+}
+
+export const SCOPE_WORD_DOCS: Record<string, string> = {
+  root: "The scope this script context started with (for an event: usually the event's target character).",
+  this: "The current scope.",
+  prev: "The scope before the last scope change. Chain for more steps back (prevprev…).",
+  from: "The sending scope in event chains. Chain for more steps back (fromfrom…).",
+};
+
+/** Doc for root/this/prev(prev…)/from(from…), any case; null when not a scope word. */
+export function scopeWordDoc(word: string): { name: string; doc: string } | null {
+  const lower = word.toLowerCase();
+  if (SCOPE_WORD_DOCS[lower]) return { name: lower, doc: SCOPE_WORD_DOCS[lower] };
+  if (/^(?:prev)+$/.test(lower)) {
+    const n = lower.length / 4;
+    return { name: lower, doc: `The scope ${n} scope-changes back (chained \`prev\`).` };
+  }
+  if (/^(?:from)+$/.test(lower)) {
+    const n = lower.length / 4;
+    return { name: lower, doc: `The sender ${n} steps back in the event chain (chained \`from\`).` };
+  }
+  return null;
+}