pe_query.py

#!/usr/bin/env python3
# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
"""
pe_query.py - ProEssentials AI Query Tool v4.3
=================================================
Provides token-efficient access to the full ProEssentials API documentation.
AI assistants run this to get specific property, enum, event, function,
and example data on demand.

v4.3 CHANGES:
  SCORING:     Usage weight added to feature search scoring. Feature groups
               with more examples rank higher (capped at +20). Improves
               ranking for heavily-used features like manual-scaling.

v4.2 CHANGES:
  FEATURES:    pe-feature-index.json -- 69 feature groups, 590+ synonyms,
               canonical enums/methods/events per group, 116 examples indexed.
               New commands: features, example-features, features --list.

v4 ARCHITECTURE:
  PRIMARY:     net-complete-enriched.json -- .NET paths extracted from DLL binary (ground truth)
  DESCRIPTIONS: ProEssentials_unified-docs.json -- rich descriptions, comments, seeAlso, keywords
  EXAMPLES:    ProEssentials_allExamples.json -- 116 C# & C++ examples with code

Usage:
    python pe_query_v4.py props "Subsets,Points,Y,X"
    python pe_query_v4.py props --category data --object Pesgo
    python pe_query_v4.py search "real-time circular"
    python pe_query_v4.py enum "GraphPlottingMethod"
    python pe_query_v4.py events [--object Pego]
    python pe_query_v4.py functions [--type net|dll]
    python pe_query_v4.py methods "PeData.Y"
    python pe_query_v4.py examples --feature "real-time"
    python pe_query_v4.py examples --prop "CircularBuffers"
    python pe_query_v4.py example 145 [--lang csharp|cpp]
    python pe_query_v4.py related "CircularBuffers"
    python pe_query_v4.py recipe "real-time"
    python pe_query_v4.py validate "PeColor.Desk,PeData.Y,PeColor.DeskColor"

Output is always compact text optimized for AI context windows, never JSON.
Designed to run in the same folder as the JSON data files.
"""

import json
import sys
import re
import os
import argparse
from pathlib import Path

# -
# Constants
# -

VERSION = "4.3"
BASIC_EXAMPLES = ["000", "100", "200", "300", "400"]
UBIQUITOUS_THRESHOLD = 20
MAX_EXAMPLE_BADGES = 3

OBJ_SHORT = {
    "Pego": "Pg", "Pesgo": "Sg", "Pe3do": "3D",
    "Pepso": "Po", "Pepco": "Pi"
}
OBJ_ALL = list(OBJ_SHORT.keys())

# -
# Data Loading & Index Building
# -

class PEDocs:
    """Loads ProEssentials JSON data and provides query methods.
    
    v4: enriched.json is primary truth source for .NET paths and types.
    unified-docs.json provides rich descriptions, comments, seeAlso.
    """

    def __init__(self, enriched_path, unified_path, examples_path, feature_index_path=None):
        enriched = json.load(open(enriched_path, encoding="utf-8"))
        unified = json.load(open(unified_path, encoding="utf-8"))
        self.examples = json.load(open(examples_path, encoding="utf-8"))

        # Feature index (synonym-based feature search)
        self.feature_index = None
        if feature_index_path:
            try:
                self.feature_index = json.load(open(feature_index_path, encoding="utf-8"))
            except Exception:
                pass

        # - PRIMARY: enriched data (correct paths from DLL) -
        self.properties = enriched.get("properties", [])
        self.methods = enriched.get("methods", [])
        self.events_list = enriched.get("events", [])
        self.enums_list = enriched.get("enums", [])
        self.structs = enriched.get("structs", [])

        # - SECONDARY: unified-docs (descriptions, seeAlso, examples) -
        self.unified_props = unified.get("properties", [])
        self.unified_enums = unified.get("enums", {})
        self.unified_functions = unified.get("functions", {})
        self.unified_events = unified.get("events", {})
        self.unified_structures = unified.get("structures", [])

        # Build enriched enum dict: name -> enum
        self.enums = {}
        for e in self.enums_list:
            self.enums[e["name"]] = e

        # - INDEX: property lookup by path, name, dll constant -
        self._prop_by_path = {}    # "PeColor.Desk" -> prop
        self._prop_by_name = {}    # "deskcolor" -> prop (lowercase)
        self._prop_by_dll = {}     # "PEP_dwDESKCOLOR" -> prop
        self._all_paths = set()

        for p in self.properties:
            path = p.get("path", "")
            name = p.get("name", "")
            dlls = p.get("dllConstants", [])

            if path:
                self._prop_by_path[path] = p
                self._prop_by_path[path.lower()] = p
                self._all_paths.add(path)
            if name:
                key = name.lower()
                # Don't overwrite with less-specific path
                if key not in self._prop_by_name or len(path) < len(self._prop_by_name[key].get("path", "")):
                    self._prop_by_name[key] = p
            for dll in dlls:
                if dll.startswith("PEP_"):
                    self._prop_by_dll[dll] = p
                    self._prop_by_dll[dll.lower()] = p

        # - INDEX: method lookup by parent path -
        self._methods_by_parent = {}  # "PeData.Y" -> [method, ...]
        for m in self.methods:
            mpath = m.get("path", "")
            parts = mpath.rsplit(".", 1)
            if len(parts) == 2:
                parent = parts[0]
                # Strip overload suffix (#2, #3, etc.)
                self._methods_by_parent.setdefault(parent, []).append(m)

        # - INDEX: unified description lookup by DLL constant -
        self._unified_by_dll = {}
        self._unified_by_name = {}
        for up in self.unified_props:
            cpp = up.get("cppConstant", "")
            if cpp:
                self._unified_by_dll[cpp] = up
            uname = up.get("name", "")
            if uname:
                self._unified_by_name[uname.lower()] = up

        # - INDEX: unified event lookup -
        self._unified_net_events = {}
        for e in self.unified_events.get("net", []):
            self._unified_net_events[e["name"]] = e
        self._unified_msg_events = {}
        for e in self.unified_events.get("messages", []):
            self._unified_msg_events[e["name"]] = e

        self._build_crossref_index()

    def _get_rich_desc(self, prop, max_len=500):
        """Get rich description from unified-docs by matching DLL constant."""
        dlls = prop.get("dllConstants", [])
        up = None
        for dll in dlls:
            up = self._unified_by_dll.get(dll)
            if up:
                break
        if not up:
            up = self._unified_by_name.get(prop.get("name", "").lower())
        if not up:
            return prop.get("description", "")

        desc = up.get("description", "")
        comments = up.get("commentsHtml", "") or up.get("comments", "")
        if comments and len(desc) < max_len:
            cleaned = self._clean_desc(comments, max_len - len(desc))
            if cleaned:
                desc = desc.rstrip() + " " + cleaned
        return desc

    def _get_see_also(self, prop):
        """Get seeAlso from unified-docs."""
        dlls = prop.get("dllConstants", [])
        up = None
        for dll in dlls:
            up = self._unified_by_dll.get(dll)
            if up:
                break
        if not up:
            up = self._unified_by_name.get(prop.get("name", "").lower())
        if up:
            return up.get("seeAlso", [])
        return []

    def _build_crossref_index(self):
        """Port of DocumentationArea.js exampleIndex builder."""
        self.prop_map = {}
        self.func_map = {}
        self.event_map = {}

        prop_re = re.compile(r"(?:Pego|Pesgo|Pepso|Pe3do|Pepco)\d*\.(Pe\w+(?:\.\w+)*)")
        func_re = re.compile(r"PeFunction\.(\w+)")
        evt_re1 = re.compile(r"(?:Pego|Pesgo|Pepso|Pe3do|Pepco)\d*\.(Pe\w+)\s*\+=")
        evt_re2 = re.compile(r"(?:Pego|Pesgo|Pepso|Pe3do|Pepco)\d*_(Pe\w+)")

        for ex in self.examples.values():
            code = ""
            if isinstance(ex.get("csharp"), dict):
                code = ex["csharp"].get("code", "")
            if not code:
                continue
            lines = code.count("\n") + 1
            entry = {"id": ex["id"], "title": ex.get("title", ""), "lines": lines}

            seen = set()
            for m in prop_re.finditer(code):
                p = m.group(1)
                if p not in seen:
                    seen.add(p)
                    self.prop_map.setdefault(p, []).append(entry)

            seen_f = set()
            for m in func_re.finditer(code):
                f = m.group(1)
                if f not in seen_f:
                    seen_f.add(f)
                    self.func_map.setdefault(f, []).append(entry)

            seen_e = set()
            for m in evt_re1.finditer(code):
                e = m.group(1)
                if e not in seen_e:
                    seen_e.add(e)
                    self.event_map.setdefault(e, []).append(entry)
            for m in evt_re2.finditer(code):
                e = m.group(1)
                if e not in seen_e:
                    seen_e.add(e)
                    self.event_map.setdefault(e, []).append(entry)

        for mp in (self.prop_map, self.func_map, self.event_map):
            for k in mp:
                mp[k].sort(key=lambda x: x["lines"])

    # -
    # Example Badge Logic
    # -

    def _get_example_badges(self, item_key, scan_map, max_badges=MAX_EXAMPLE_BADGES):
        code_scan = scan_map.get(item_key, [])
        if not code_scan:
            return []
        if len(code_scan) >= UBIQUITOUS_THRESHOLD:
            basic = None
            for bid in BASIC_EXAMPLES:
                for cs in code_scan:
                    if cs["id"] == bid:
                        basic = cs
                        break
                if basic:
                    break
            pick = basic or code_scan[0]
            return [{"id": pick["id"], "title": pick["title"]}]
        return [{"id": cs["id"], "title": cs["title"]} for cs in code_scan[:max_badges]]

    # -
    # Formatting Helpers
    # -

    def _applies_short(self, applies_to):
        if not applies_to:
            return "all"
        return "|".join(OBJ_SHORT.get(o, o) for o in applies_to)

    def _format_example_badges(self, badges, scan_count=0):
        if not badges:
            return ""
        parts = []
        for b in badges:
            title = b.get("title", "")
            if title and title != f"Example {b['id']}":
                parts.append(f"{b['id']} ({title})")
            else:
                parts.append(b["id"])
        text = ", ".join(parts)
        if scan_count >= UBIQUITOUS_THRESHOLD:
            text += f" (ubiquitous - in {scan_count}+ examples)"
        return text

    def _clean_desc(self, desc, max_len=300):
        if not desc:
            return ""
        text = re.sub(r"<[^>]+>", "", desc)
        text = re.sub(r"\s+", " ", text).strip()
        if max_len and len(text) > max_len:
            text = text[:max_len].rsplit(" ", 1)[0] + "..."
        return text

    def _resolve_type(self, p, obj=None):
        """Resolve the correct type for a property, using per-control overrides when available.
        If obj is specified and typeByControl has an entry for it, returns that type.
        Otherwise returns the default type."""
        tbc = p.get("typeByControl")
        if tbc and obj:
            # Normalize obj name to match typeByControl keys (e.g., "pe3do" -> "Pe3do")
            for ctrl, ctype in tbc.items():
                if ctrl.lower() == obj.lower():
                    return ctype
        return p.get("type", "")

    # -
    # COMMAND: props
    # -

    def _resolve_prop(self, name):
        """Resolve a property by name, path, or DLL constant."""
        name_s = name.strip()
        name_l = name_s.lower()

        # Exact path match (case insensitive)
        p = self._prop_by_path.get(name_l)
        if p:
            return p

        # Exact name match
        p = self._prop_by_name.get(name_l)
        if p:
            return p

        # DLL constant
        p = self._prop_by_dll.get(name_s) or self._prop_by_dll.get(name_l)
        if p:
            return p

        # Try matching last segment of path
        matches = [pr for pr in self.properties if pr.get("path", "").rsplit(".", 1)[-1].lower() == name_l]
        if len(matches) == 1:
            return matches[0]
        if matches:
            # Return shortest path (most general)
            return min(matches, key=lambda pr: len(pr.get("path", "")))

        # Partial match (3+ chars)
        if len(name_l) >= 3:
            matches = [pr for pr in self.properties if name_l in pr.get("name", "").lower() or name_l in pr.get("path", "").lower()]
            if len(matches) == 1:
                return matches[0]

        return None

    def cmd_props(self, names=None, category=None, obj=None, list_mode=False):
        results = []

        if names:
            for name in names:
                prop = self._resolve_prop(name)
                if not prop:
                    # Try partial match for ambiguity message
                    name_l = name.strip().lower()
                    if len(name_l) >= 3:
                        matches = [p for p in self.properties if name_l in p.get("name", "").lower()]
                    else:
                        matches = []
                    if matches:
                        results.append(f"=== {name} === AMBIGUOUS ({len(matches)} matches)")
                        for m in matches[:10]:
                            results.append(f"  {m['path']} ({self._applies_short(m.get('appliesTo'))})")
                    else:
                        results.append(f"=== {name} === NOT FOUND")
                    continue
                results.append(self._format_property(prop, obj=obj))
        else:
            filtered = self.properties
            if category:
                # Map enriched sourceClass to categories
                cat_l = category.lower()
                filtered = [p for p in filtered if self._matches_category(p, cat_l)]
            if obj:
                obj_l = obj.lower()
                filtered = [p for p in filtered if any(o.lower() == obj_l for o in p.get("appliesTo", []))]

            if list_mode or (not names and not category and not obj):
                if not filtered:
                    return "No properties found."
                lines = [f"=== Properties ({len(filtered)} results) ==="]
                for p in filtered:
                    lines.append(f"  {p['path']}|{self._resolve_type(p, obj)}|{self._applies_short(p.get('appliesTo'))}")
                return "\n".join(lines)

            for p in filtered:
                results.append(self._format_property(p, obj=obj))

        return "\n\n".join(results) if results else "No properties found."

    def _matches_category(self, prop, cat_l):
        """Match property to a category keyword."""
        path = prop.get("path", "").lower()
        source = prop.get("sourceClass", "").lower()
        name = prop.get("name", "").lower()
        # Use enriched path prefix for categorization
        cat_map = {
            "data": ["pedata."],
            "color": ["pecolor."],
            "plot": ["peplot."],
            "grid": ["pegrid."],
            "axis": ["pegrid.configure.", "pegrid.option.axis", "pegrid.zoom."],
            "font": ["pefont."],
            "annotation": ["peannotation."],
            "interaction": ["peuserinterface."],
            "ui": ["peuserinterface."],
            "legend": ["pelegen."],
            "string": ["pestring."],
            "special": ["pespecial."],
            "configure": ["peconfigure."],
            "function": ["pefunction."],
            "table": ["petable.", "peannotation.table."],
            "realtime": [],  # Special: match on property names
            "export": ["peuserinterface.dialog.export", "peuserinterface.dialog.allow"],
        }
        prefixes = cat_map.get(cat_l, [])
        for prefix in prefixes:
            if path.startswith(prefix):
                return True
        # Fallback: check unified category
        up = self._unified_by_name.get(name)
        if up and up.get("category", "").lower() == cat_l:
            return True
        return False

    def _format_property(self, p, obj=None):
        lines = []
        path = p.get("path", "")
        name = p.get("name", "")
        ptype = self._resolve_type(p, obj)
        dlls = p.get("dllConstants", [])
        dll_str = dlls[0] if dlls else ""
        applies = self._applies_short(p.get("appliesTo"))

        lines.append(f"=== {name} ===")
        lines.append(f"{path}|{dll_str}|{ptype}|{applies}")

        # Show per-control type overrides when they exist
        tbc = p.get("typeByControl")
        if tbc:
            overrides = ", ".join(f"{c}:{t}" for c, t in sorted(tbc.items()))
            lines.append(f"TypeByControl: default={p.get('type','')}, {overrides}")

        # Rich description from unified
        desc = self._get_rich_desc(p, max_len=500)
        if desc:
            lines.append(self._clean_desc(desc, max_len=500))
        elif p.get("description"):
            lines.append(self._clean_desc(p["description"], max_len=500))

        # Methods on this property (from enriched methods list)
        methods = self._methods_by_parent.get(path, [])
        if methods:
            method_strs = []
            seen = set()
            for m in methods:
                mname = m.get("name", "").split("#")[0]  # Strip overload suffix
                params = ", ".join(f"{pp.get('type','')} {pp.get('name','')}" for pp in m.get("parameters", []))
                ret = m.get("returnType", "void")
                sig = f"{ret} {mname}({params})"
                if sig not in seen:
                    seen.add(sig)
                    method_strs.append(sig)
            if method_strs:
                lines.append(f"Methods: {'; '.join(method_strs[:8])}")
                if len(method_strs) > 8:
                    lines.append(f"  ... and {len(method_strs)-8} more methods")

        # SeeAlso from unified
        see_also = self._get_see_also(p)
        if see_also:
            sa_names = [s.get("name", s.get("filename", "")) for s in see_also]
            lines.append(f"SeeAlso: {', '.join(sa_names[:8])}")

        # Example badges
        key = path  # Use enriched path directly
        scan_count = len(self.prop_map.get(key, []))
        badges = self._get_example_badges(key, self.prop_map)
        if not badges:
            # Try without the first prefix segment for cross-ref compatibility
            # e.g. code uses "PeData.Subsets" but enriched path is "PeData.Subsets"
            badges = self._get_example_badges(key, self.prop_map)
        badge_str = self._format_example_badges(badges, scan_count)
        if badge_str:
            lines.append(f"Examples: {badge_str}")

        return "\n".join(lines)

    # -
    # COMMAND: methods (NEW in v4)
    # -

    def cmd_methods(self, parent_path):
        """List all methods on a property array (e.g., PeData.Y)."""
        parent = parent_path.strip()
        methods = self._methods_by_parent.get(parent, [])
        if not methods:
            # Try case-insensitive
            parent_l = parent.lower()
            for k, v in self._methods_by_parent.items():
                if k.lower() == parent_l:
                    methods = v
                    parent = k
                    break
        if not methods:
            return f"No methods found for '{parent_path}'. Try: PeData.Y, PeData.X, PeString.PointLabels, etc."

        lines = [f"=== Methods on {parent} ({len(methods)}) ==="]
        seen = set()
        for m in methods:
            mname = m.get("name", "").split("#")[0]
            params = ", ".join(f"{pp.get('type','')} {pp.get('name','')}" for pp in m.get("parameters", []))
            ret = m.get("returnType", "void")
            sig = f"{ret} {mname}({params})"
            if sig not in seen:
                seen.add(sig)
                desc = self._clean_desc(m.get("description", ""), max_len=120)
                lines.append(f"  {sig}")
                if desc:
                    lines.append(f"    {desc}")
        return "\n".join(lines)

    # -
    # COMMAND: validate (NEW in v4)
    # -

    def cmd_validate(self, paths):
        """Validate .NET paths against the enriched truth source."""
        lines = [f"=== Path Validation ==="]
        for path in paths:
            path = path.strip()
            if not path:
                continue
            if path in self._all_paths:
                p = self._prop_by_path.get(path.lower())
                tbc = p.get('typeByControl')
                tbc_note = ''
                if tbc:
                    tbc_note = ' TypeByControl: ' + ', '.join(f'{c}:{t}' for c, t in sorted(tbc.items()))
                lines.append(f"  VALID   {path} - {p.get('type','')} [{self._applies_short(p.get('appliesTo'))}]{tbc_note}")
            else:
                # Try to suggest correction
                last = path.rsplit(".", 1)[-1].lower()
                suggestions = [pr["path"] for pr in self.properties if pr.get("name","").lower() == last]
                if suggestions:
                    lines.append(f"  INVALID {path} - did you mean: {', '.join(suggestions[:3])}?")
                else:
                    lines.append(f"  INVALID {path}")
        return "\n".join(lines)

    # -
    # COMMAND: search
    # -

    def cmd_search(self, term, max_results=20):
        term_l = term.lower()
        terms = term_l.split()
        sections = []

        # Search properties (enriched + unified descriptions)
        props = []
        for p in self.properties:
            rich_desc = self._get_rich_desc(p, max_len=1000)
            searchable = " ".join(filter(None, [
                p.get("name", ""), p.get("path", ""),
                " ".join(p.get("dllConstants", [])),
                rich_desc, p.get("description", ""),
            ])).lower()
            if all(t in searchable for t in terms):
                props.append(p)
        if props:
            sections.append(f"=== Properties ({len(props)} matches) ===")
            for p in props[:max_results]:
                desc = self._clean_desc(p.get("description", ""), max_len=80)
                sections.append(f"  {p['path']}|{p.get('type','')}|{self._applies_short(p.get('appliesTo'))}|{desc}")
            if len(props) > max_results:
                sections.append(f"  ... and {len(props)-max_results} more")

        # Search DLL functions from unified
        funcs = []
        for ftype in ("dll", "net", "ocx"):
            for f in self.unified_functions.get(ftype, []):
                searchable = " ".join(filter(None, [
                    f.get("name", ""), f.get("description", ""),
                    f.get("syntax", ""),
                ])).lower()
                if all(t in searchable for t in terms):
                    funcs.append((ftype, f))
        if funcs:
            sections.append(f"\n=== Functions ({len(funcs)} matches) ===")
            for ftype, f in funcs[:max_results]:
                desc = self._clean_desc(f.get("description", ""), max_len=80)
                sections.append(f"  [{ftype}] {f['name']}|{desc}")

        # Search enriched events
        evts = []
        for e in self.events_list:
            searchable = " ".join(filter(None, [e.get("name", ""), e.get("handlerType", "")])).lower()
            if all(t in searchable for t in terms):
                evts.append(e)
        # Also search unified events for descriptions
        for etype in ("net", "messages"):
            for e in self.unified_events.get(etype, []):
                searchable = " ".join(filter(None, [e.get("name", ""), e.get("description", "")])).lower()
                if all(t in searchable for t in terms):
                    if not any(x.get("name") == e.get("name") for x in evts):
                        evts.append(e)
        if evts:
            sections.append(f"\n=== Events ({len(evts)} matches) ===")
            for e in evts[:max_results]:
                desc = self._clean_desc(e.get("description", ""), max_len=80)
                sections.append(f"  {e['name']}|{desc}")

        # Search enums
        enum_matches = []
        for name, val in self.enums.items():
            searchable = " ".join(filter(None, [
                name, " ".join(v.get("name", "") for v in val.get("values", []))
            ])).lower()
            if all(t in searchable for t in terms):
                enum_matches.append((name, val))
        if enum_matches:
            sections.append(f"\n=== Enums ({len(enum_matches)} matches) ===")
            for name, val in enum_matches[:max_results]:
                sections.append(f"  {name} ({len(val.get('values',[]))} values)")

        if not sections:
            return f"No results for '{term}'."
        return "\n".join(sections)

    # -
    # COMMAND: enum
    # -

    def cmd_enum(self, name):
        val = self.enums.get(name)
        if not val:
            name_l = name.lower()
            for k, v in self.enums.items():
                if k.lower() == name_l:
                    val = v
                    name = k
                    break
        if not val:
            name_l = name.lower()
            matches = [(k, v) for k, v in self.enums.items() if name_l in k.lower()]
            if len(matches) == 1:
                name, val = matches[0]
            elif matches:
                lines = [f"=== Ambiguous enum '{name}' ({len(matches)} matches) ==="]
                for k, v in matches:
                    lines.append(f"  {k} ({len(v.get('values',[]))} values)")
                return "\n".join(lines)
            else:
                return f"Enum '{name}' not found."

        lines = [f"=== {name} ==="]

        # Get description from unified enums
        uval = self.unified_enums.get(name, {})
        desc = self._clean_desc(uval.get("description", ""), max_len=200)
        if desc:
            lines.append(desc)

        # Properties using this enum
        using = [p["path"] for p in self.properties if name.lower() in p.get("type","").lower()]
        if using:
            lines.append(f"Used by: {', '.join(using[:8])}")

        lines.append("Values:")
        for v in val.get("values", []):
            vname = v.get("name", "")
            vval = v.get("value", "")
            lines.append(f"  {vname}={vval}")

        return "\n".join(lines)

    # -
    # COMMAND: events
    # -

    def cmd_events(self, obj=None):
        lines = []
        items = self.events_list
        if obj:
            obj_l = obj.lower()
            items = [e for e in items if any(o.lower() == obj_l for o in e.get("appliesTo", OBJ_ALL))]

        if not items:
            return "No events found."

        lines.append(f"=== .NET Events ({len(items)}) ===")
        for e in items:
            name = e.get("name", "")
            handler = e.get("handlerType", "")
            applies = self._applies_short(e.get("appliesTo"))
            # Get description from unified
            ue = self._unified_net_events.get(name, {})
            desc = self._clean_desc(ue.get("description", ""), max_len=100)
            lines.append(f"  {name}|{handler}|{applies}")
            if desc:
                lines.append(f"    {desc}")
            # Example badges
            scan_count = len(self.event_map.get(name, []))
            badges = self._get_example_badges(name, self.event_map)
            badge_str = self._format_example_badges(badges, scan_count)
            if badge_str:
                lines.append(f"    Examples: {badge_str}")

        return "\n".join(lines)

    def cmd_event(self, name):
        name_l = name.lower()
        # Search enriched events
        for e in self.events_list:
            if e.get("name", "").lower() == name_l:
                return self._format_event_detail(e)
        return f"Event '{name}' not found."

    def _format_event_detail(self, e):
        name = e.get("name", "")
        lines = [f"=== {name} ==="]
        lines.append(f"Handler: {e.get('handlerType','')}")
        lines.append(f"EventArgs: {e.get('eventArgsType','')}")
        lines.append(f"AppliesTo: {self._applies_short(e.get('appliesTo'))}")

        # Rich detail from unified
        ue = self._unified_net_events.get(name, {})
        if ue.get("eventDeclaration"):
            lines.append(f"Declaration: {ue['eventDeclaration']}")
        if ue.get("arguments"):
            lines.append("Arguments:")
            for a in ue["arguments"]:
                lines.append(f"  {a.get('type','')} {a.get('name','')} - {a.get('description','')}")
        desc = self._clean_desc(ue.get("description", ""), max_len=500)
        if desc:
            lines.append(desc)

        badges = self._get_example_badges(name, self.event_map)
        badge_str = self._format_example_badges(badges, len(self.event_map.get(name, [])))
        if badge_str:
            lines.append(f"Examples: {badge_str}")
        return "\n".join(lines)

    # -
    # COMMAND: functions (uses unified-docs which has the rich function data)
    # -

    def cmd_functions(self, func_type=None, obj=None):
        sections = []
        types_to_show = [func_type] if func_type else ["net", "dll", "ocx"]

        for ftype in types_to_show:
            items = self.unified_functions.get(ftype, [])
            if obj:
                obj_l = obj.lower()
                items = [f for f in items if any(o.lower() == obj_l for o in f.get("appliesTo", OBJ_ALL))]
            if not items:
                continue
            sections.append(f"=== {ftype.upper()} Functions ({len(items)}) ===")
            for f in items:
                name = f.get("name", "")
                desc = self._clean_desc(f.get("description", ""), max_len=100)
                if ftype in ("net", "ocx"):
                    syntax = f.get("syntax", "")
                    applies = self._applies_short(f.get("appliesTo"))
                    sections.append(f"  {name}|{applies}")
                    if syntax:
                        sections.append(f"    {syntax}")
                else:
                    syntax = f.get("syntax", "")
                    sections.append(f"  {name}")
                    if syntax:
                        sections.append(f"    {syntax}")
                if desc:
                    sections.append(f"    {desc}")
        return "\n".join(sections) if sections else "No functions found."

    def cmd_function(self, name):
        name_l = name.lower()
        for ftype in ("net", "dll", "ocx"):
            for f in self.unified_functions.get(ftype, []):
                if f.get("name", "").lower() == name_l:
                    return self._format_function_detail(f, ftype)
        return f"Function '{name}' not found."

    def _format_function_detail(self, f, ftype):
        lines = [f"=== {f['name']} [{ftype}] ==="]
        if f.get("syntax"):
            lines.append(f"Syntax: {f['syntax']}")
        if f.get("appliesTo"):
            lines.append(f"AppliesTo: {self._applies_short(f['appliesTo'])}")
        if f.get("parameters"):
            lines.append("Parameters:")
            for p in f["parameters"]:
                lines.append(f"  {p.get('type','')} {p.get('name','')} - {self._clean_desc(p.get('description',''), 150)}")
        desc = self._clean_desc(f.get("description", ""), max_len=500)
        if desc:
            lines.append(desc)
        see_also = f.get("seeAlso", [])
        if see_also:
            sa_names = [s.get("name", s.get("filename", "")) for s in see_also]
            lines.append(f"SeeAlso: {', '.join(sa_names)}")
        badges = self._get_example_badges(f["name"], self.func_map)
        badge_str = self._format_example_badges(badges, len(self.func_map.get(f["name"], [])))
        if badge_str:
            lines.append(f"Examples: {badge_str}")
        return "\n".join(lines)

    # -
    # COMMAND: examples
    # -

    def cmd_examples(self, feature=None, prop=None, obj=None):
        results = []

        if prop:
            prop_l = prop.strip().lower()
            p_obj = self._resolve_prop(prop)
            key = p_obj.get("path", "") if p_obj else None

            scan = self.prop_map.get(key, []) if key else []
            if not scan:
                for k in self.prop_map:
                    if prop_l in k.lower():
                        scan = self.prop_map[k]
                        key = k
                        break
            if scan:
                results.append(f"=== Examples using {key or prop} ({len(scan)} found) ===")
                for s in scan[:15]:
                    results.append(f"  {s['id']}|{s['title']}|{s['lines']} lines")
            else:
                results.append(f"No examples found using property '{prop}'.")
            return "\n".join(results)

        if feature:
            # Try feature index synonym search first
            if self.feature_index:
                fi_groups = self.feature_index.get("feature_groups", {})
                fi_examples = self.feature_index.get("examples", {})
                terms = feature.lower().split()
                matched_groups = []
                for gid, gdef in fi_groups.items():
                    if gid in self._SUPPRESSED_GROUPS:
                        continue
                    usage_weight = min(len(gdef.get("examples_using", [])), 20)
                    if feature.lower() == gid or feature.lower() == gid.replace("-", " "):
                        matched_groups.append((gid, gdef, 100 + usage_weight))
                        continue
                    # Substring group ID match
                    if feature.lower() in gid:
                        matched_groups.append((gid, gdef, 30 + usage_weight))
                        continue
                    for syn in gdef.get("synonyms", []):
                        syn_l = syn.lower()
                        if feature.lower() in syn_l or all(t in syn_l for t in terms):
                            matched_groups.append((gid, gdef, 20 + usage_weight))
                            break
                    else:
                        desc_l = gdef.get("description", "").lower()
                        if all(t in desc_l for t in terms):
                            matched_groups.append((gid, gdef, 10 + usage_weight))
                if matched_groups:
                    matched_groups.sort(key=lambda x: -x[2])
                    all_eids = []
                    for gid, gdef, _ in matched_groups:
                        for eid in gdef.get("examples_using", []):
                            if eid not in all_eids:
                                ex_data = fi_examples.get(eid, {})
                                if obj and not any(o.lower() == obj.lower() for o in ex_data.get("chartObjects", [])):
                                    continue
                                all_eids.append(eid)
                    gnames = ", ".join(self._display_group_id(g[0]) for g in matched_groups[:3])
                    results.append(f"=== Examples for '{feature}' via groups: {gnames} ({len(all_eids)} found) ===")
                    for eid in all_eids[:20]:
                        ex = self.examples.get(eid, {})
                        fi_ex = fi_examples.get(eid, {})
                        dist = fi_ex.get("distinctive_groups", [])
                        star = "*" if any(g[0] in dist for g in matched_groups) else ""
                        results.append(f"  {eid}{star}|{ex.get('chartObject','')}|{ex.get('title','')}")
                    if all_eids:
                        results.append(f"  (* = feature is distinctive for that example)")
                    return "\n".join(results)
            # Fallback: text search in example titles/descriptions/code
            terms = feature.lower().split()
            matches = []
            for ex in self.examples.values():
                searchable = " ".join(filter(None, [
                    ex.get("title", ""), ex.get("description", ""),
                    ex.get("chartObject", ""),
                    ex.get("csharp", {}).get("code", "")[:500]
                ])).lower()
                if all(t in searchable for t in terms):
                    matches.append(ex)
            if matches:
                results.append(f"=== Examples matching '{feature}' ({len(matches)} found) ===")
                for ex in matches[:20]:
                    results.append(f"  {ex['id']}|{ex.get('chartObject','')}|{ex.get('title','')}")
            else:
                results.append(f"No examples matching '{feature}'.")
            return "\n".join(results)

        if obj:
            obj_l = obj.lower()
            matches = [ex for ex in self.examples.values() if ex.get("chartObject", "").lower() == obj_l]
            if matches:
                results.append(f"=== {obj} Examples ({len(matches)}) ===")
                for ex in matches:
                    results.append(f"  {ex['id']}|{ex.get('title','')}")
            else:
                results.append(f"No examples for '{obj}'.")
            return "\n".join(results)

        results.append(f"=== All Examples ({len(self.examples)}) ===")
        for eid in sorted(self.examples.keys()):
            ex = self.examples[eid]
            results.append(f"  {eid}|{ex.get('chartObject','')}|{ex.get('title','')}")
        return "\n".join(results)

    def cmd_example(self, example_id, lang="csharp"):
        eid = str(example_id).zfill(3)
        ex = self.examples.get(eid)
        if not ex:
            return f"Example '{eid}' not found."

        lines = [f"=== Example {eid}: {ex.get('title','')} ==="]
        lines.append(f"ChartObject: {ex.get('chartObject','')} ({ex.get('chartObjectFull','')})")
        if ex.get("description") and ex["description"] != ex.get("title"):
            lines.append(f"Description: {ex['description']}")

        lang_key = lang.lower()
        if lang_key in ("cs", "c#"):
            lang_key = "csharp"
        elif lang_key in ("c++", "c"):
            lang_key = "cpp"
        elif lang_key in ("vb", "vbnet", "vb.net"):
            lang_key = "csharp"
            lines.append("Note: VB.NET property syntax is identical to C# - same paths, same enum names, different keywords only.")

        code_obj = ex.get(lang_key, {})
        code = code_obj.get("code", "") if isinstance(code_obj, dict) else ""

        if code:
            lines.append(f"\n--- {lang_key} code ---")
            lines.append(code)
        else:
            alt = "cpp" if lang_key == "csharp" else "csharp"
            alt_obj = ex.get(alt, {})
            if isinstance(alt_obj, dict) and alt_obj.get("code"):
                lines.append(f"\n(No {lang_key} code, showing {alt})")
                lines.append(alt_obj["code"])
            else:
                lines.append("No code available.")

        return "\n".join(lines)

    # -
    # COMMAND: related
    # -

    def cmd_related(self, name):
        prop = self._resolve_prop(name)
        if not prop:
            return f"Property '{name}' not found."

        lines = [f"=== Related to {prop['path']} ==="]

        see_also = self._get_see_also(prop)
        if see_also:
            lines.append(f"\nSeeAlso ({len(see_also)}):")
            for sa in see_also:
                sa_name = sa.get("name", sa.get("filename", ""))
                sa_prop = self._resolve_prop(sa_name)
                if sa_prop:
                    lines.append(f"  {sa_prop['path']}|{sa_prop.get('type','')}|{self._applies_short(sa_prop.get('appliesTo'))}")
                else:
                    lines.append(f"  {sa_name}")

        # Same path prefix siblings
        path = prop.get("path", "")
        prefix = path.rsplit(".", 1)[0] + "." if "." in path else ""
        if prefix:
            siblings = [p for p in self.properties if p.get("path","").startswith(prefix) and p["path"] != path]
            if siblings:
                lines.append(f"\nSame group '{prefix}*' ({len(siblings)} properties):")
                for p in siblings[:20]:
                    lines.append(f"  {p['path']}|{p.get('type','')}")
                if len(siblings) > 20:
                    lines.append(f"  ... and {len(siblings)-20} more")

        return "\n".join(lines)

    # -
    # COMMAND: structures
    # -

    def cmd_structures(self, name=None):
        if name:
            name_l = name.lower()
            for s in self.structs:
                if s.get("name", "").lower() == name_l:
                    return self._format_structure(s)
            # Also check unified
            for s in self.unified_structures:
                if s.get("name", "").lower() == name_l:
                    return self._format_structure(s)
            return f"Structure '{name}' not found."

        items = self.structs if self.structs else self.unified_structures
        lines = [f"=== Structures ({len(items)}) ==="]
        for s in items:
            lines.append(f"  {s['name']}")
        return "\n".join(lines)

    def _format_structure(self, s):
        lines = [f"=== {s['name']} ==="]
        if s.get("fields") or s.get("members"):
            fields = s.get("fields") or s.get("members", [])
            for f in fields:
                lines.append(f"  {f.get('type','')} {f.get('name','')}")
        return "\n".join(lines)

    # -
    # COMMAND: recipe
    # -

    def cmd_recipe(self, topic):
        topic_l = topic.lower().strip()
        matches = []
        for key, recipe in RECIPES.items():
            if topic_l in key or any(topic_l in tag for tag in recipe.get("tags", [])):
                matches.append((key, recipe))
        if not matches:
            terms = topic_l.split()
            for key, recipe in RECIPES.items():
                all_text = key + " " + " ".join(recipe.get("tags", []))
                if any(t in all_text for t in terms):
                    matches.append((key, recipe))
        if not matches:
            lines = [f"No recipe for '{topic}'. Available:"]
            for key, recipe in sorted(RECIPES.items()):
                lines.append(f"  {key} - {recipe.get('title', '')}")
            return "\n".join(lines)

        results = []
        for key, recipe in matches:
            results.append(f"=== Recipe: {recipe.get('title', key)} ===")
            if recipe.get("description"):
                results.append(recipe["description"])
            if recipe.get("chart_object"):
                results.append(f"ChartObject: {recipe['chart_object']}")
            if recipe.get("key_properties"):
                results.append(f"Key Properties: {', '.join(recipe['key_properties'])}")
            if recipe.get("steps"):
                results.append("Steps:")
                for i, step in enumerate(recipe["steps"], 1):
                    results.append(f"  {i}. {step}")
            if recipe.get("code"):
                results.append(f"\n--- C# Pattern ---")
                results.append(recipe["code"])
            if recipe.get("notes"):
                results.append(f"\nNotes: {recipe['notes']}")
            if recipe.get("examples"):
                results.append(f"Examples: {', '.join(recipe['examples'])}")
        return "\n\n".join(results)


    # - COMMAND: features (synonym-based feature group search) -

    # Group name filter -- suppress legacy group names from output
    _SUPPRESSED_GROUPS = {"pedo-data"}

    def _display_group_id(self, gid):
        """Return display-safe group ID (maps legacy names)."""
        if gid == "pedo-data":
            return "overlay-data"
        return gid

    def cmd_features(self, query, obj=None):
        """Search feature groups by natural language synonyms."""
        if not self.feature_index:
            return "Feature index not loaded. Place pe-feature-index.json alongside data files."

        query_lower = query.lower().strip()
        terms = query_lower.split()
        groups = self.feature_index.get("feature_groups", {})
        examples_idx = self.feature_index.get("examples", {})

        scored = []
        for gid, gdef in groups.items():
            if gid in self._SUPPRESSED_GROUPS:
                continue
            score = 0
            matched_syns = []
            # Exact group ID match
            if query_lower == gid or query_lower == gid.replace("-", " "):
                score += 100
            # Substring group ID match (e.g. "3d" matches "3d-viewport", "3d-surface")
            elif query_lower in gid:
                score += 30
            for syn in gdef.get("synonyms", []):
                syn_l = syn.lower()
                if query_lower == syn_l:
                    score += 50
                    matched_syns.append(syn)
                elif query_lower in syn_l:
                    score += 20
                    matched_syns.append(syn)
                elif all(t in syn_l for t in terms):
                    score += 15
                    matched_syns.append(syn)
                elif any(t in syn_l for t in terms if len(t) >= 3):
                    score += 5
                    matched_syns.append(syn)
            desc_l = gdef.get("description", "").lower()
            if all(t in desc_l for t in terms):
                score += 10
            # Usage weight: heavily-used features rank higher (capped at 20)
            if score > 0:
                score += min(len(gdef.get("examples_using", [])), 20)
            if score > 0:
                scored.append((gid, gdef, score, matched_syns))

        scored.sort(key=lambda x: -x[2])
        if not scored:
            return f"No feature groups matching '{query}'. Use: pe_query.py features --list"

        out = [f"=== Feature Search: '{query}' ({len(scored)} groups) ==="]
        for gid, gdef, score, syns in scored[:10]:
            ex_ids = gdef.get("examples_using", [])
            ubiq = " [UBIQ]" if gdef.get("ubiquitous") else ""
            if obj:
                obj_l = obj.lower()
                ex_ids = [eid for eid in ex_ids
                          if any(o.lower() == obj_l for o in examples_idx.get(eid, {}).get("chartObjects", []))]
            display_gid = self._display_group_id(gid)
            out.append(f"\n  {display_gid}{ubiq} ({len(ex_ids)} examples)")
            out.append(f"    {gdef.get('description', '')}")
            if syns:
                out.append(f"    matched: {', '.join(syns[:4])}")
            if ex_ids:
                shown = ex_ids[:8]
                ex_strs = []
                for eid in shown:
                    ex = examples_idx.get(eid, {})
                    dist = ex.get("distinctive_groups", [])
                    star = "*" if gid in dist else ""
                    ex_strs.append(f"{eid}{star}")
                out.append(f"    examples: {', '.join(ex_strs)}")
                if len(ex_ids) > 8:
                    out.append(f"    ... and {len(ex_ids) - 8} more")
            # Show canonical paths, enums, methods, events
            paths = gdef.get("canonical_prefixes", [])
            enums = gdef.get("canonical_enums", [])
            methods = gdef.get("canonical_methods", [])
            events = gdef.get("canonical_events", [])
            if paths:
                out.append(f"    key paths: {', '.join(paths[:5])}")
            if enums:
                out.append(f"    enums: {', '.join(enums[:4])}")
            if methods:
                out.append(f"    methods: {', '.join(methods[:4])}")
            if events:
                out.append(f"    events: {', '.join(events[:4])}")
        out.append(f"\n  (* = feature is distinctive for that example)")
        return "\n".join(out)

    def cmd_features_list(self, obj=None):
        """List all feature groups."""
        if not self.feature_index:
            return "Feature index not loaded."
        groups = self.feature_index.get("feature_groups", {})
        examples_idx = self.feature_index.get("examples", {})
        out = [f"=== All Feature Groups ({len(groups) - len(self._SUPPRESSED_GROUPS.intersection(groups))}) ==="]
        for gid in sorted(groups.keys()):
            if gid in self._SUPPRESSED_GROUPS:
                continue
            gdef = groups[gid]
            ex_ids = gdef.get("examples_using", [])
            if obj:
                obj_l = obj.lower()
                ex_ids = [eid for eid in ex_ids
                          if any(o.lower() == obj_l for o in examples_idx.get(eid, {}).get("chartObjects", []))]
            ubiq = " [UBIQ]" if gdef.get("ubiquitous") else ""
            count = f"({len(ex_ids):>2}x)" if ex_ids else "(unused)"
            display_gid = self._display_group_id(gid)
            out.append(f"  {display_gid:<28} {count}{ubiq}  {gdef.get('description','')[:50]}")
        return "\n".join(out)

    # - COMMAND: example-features -

    def cmd_example_features(self, example_id):
        """Show the feature groups and distinctive features for a single example."""
        if not self.feature_index:
            return "Feature index not loaded."
        eid = str(example_id).zfill(3)
        examples_idx = self.feature_index.get("examples", {})
        groups = self.feature_index.get("feature_groups", {})
        ex = examples_idx.get(eid)
        if not ex:
            return f"Example '{eid}' not found in feature index."
        out = [f"=== Example {eid}: {ex.get('title', '')} ==="]
        out.append(f"  Chart: {', '.join(ex.get('chartObjects', []))}")
        base = ex.get("baseExample")
        out.append(f"  Base: {base or 'standalone'}")
        fg = ex.get("feature_groups", {})
        # Handle both list format (trimmed) and dict format (full)
        fg_names = list(fg.keys()) if isinstance(fg, dict) else list(fg)
        # Filter suppressed groups
        fg_names = [g for g in fg_names if g not in self._SUPPRESSED_GROUPS]
        dist = set(ex.get("distinctive_groups", [])) - self._SUPPRESSED_GROUPS
        if dist:
            out.append(f"\n  DISTINCTIVE features ({len(dist)}):")
            for gid in sorted(dist):
                gdef = groups.get(gid, {})
                desc = gdef.get("description", "")
                display_gid = self._display_group_id(gid)
                out.append(f"    * {display_gid}: {desc}")
                paths = gdef.get("canonical_prefixes", [])[:4]
                enums = gdef.get("canonical_enums", [])[:3]
                methods = gdef.get("canonical_methods", [])[:3]
                events = gdef.get("canonical_events", [])[:3]
                if paths:
                    out.append(f"      paths: {', '.join(paths)}")
                if enums:
                    out.append(f"      enums: {', '.join(enums)}")
                if methods:
                    out.append(f"      methods: {', '.join(methods)}")
                if events:
                    out.append(f"      events: {', '.join(events)}")
        else:
            out.append(f"\n  No distinctive features (base/boilerplate only)")
        shared = [self._display_group_id(gid) for gid in sorted(fg_names)
                  if gid not in dist and not groups.get(gid, {}).get("ubiquitous")]
        if shared:
            out.append(f"\n  Shared features (also in base): {', '.join(shared)}")
        ubiq = [self._display_group_id(gid) for gid in sorted(fg_names)
                if groups.get(gid, {}).get("ubiquitous")]
        if ubiq:
            out.append(f"  Ubiquitous (boilerplate): {', '.join(ubiq)}")
        return "\n".join(out)


    # -
    # COMMAND: info
    # -

    def cmd_info(self):
        lines = [
            f"=== ProEssentials AI Query Tool v{VERSION} ===",
            f"Primary source: net-complete-enriched.json (DLL-extracted, ground truth)",
            f"Descriptions: ProEssentials_unified-docs.json (rich documentation)",
            f"Examples: ProEssentials_allExamples.json",
            f"",
            f"Properties: {len(self.properties)} (enriched paths)",
            f"Methods: {len(self.methods)} (on property arrays)",
            f"Events: {len(self.events_list)} (.NET)",
            f"Enums: {len(self.enums)}",
            f"Structures: {len(self.structs)}",
            f"Examples: {len(self.examples)}",
            f"Unified descriptions: {len(self.unified_props)} properties",
            f"DLL Functions: {len(self.unified_functions.get('dll', []))}",
            f".NET Functions: {len(self.unified_functions.get('net', []))}",
            f"OCX Functions: {len(self.unified_functions.get('ocx', []))}",
            f"Cross-ref: {len(self.prop_map)} props, {len(self.func_map)} funcs, {len(self.event_map)} events in examples",
        ]
        if self.feature_index:
            fg = self.feature_index.get("feature_groups", {})
            fi_ex = self.feature_index.get("examples", {})
            total_syns = sum(len(g.get("synonyms", [])) for g in fg.values())
            lines.append(f"Feature groups: {len(fg)} ({total_syns} synonyms, {len(fi_ex)} examples indexed)")
        else:
            lines.append("Feature index: not loaded")
        return "\n".join(lines)


# -
# Recipe Library (v4 - fixed, no hallucinated property names)
# -

RECIPES = {
    "real-time": {
        "title": "Real-Time / Strip Chart",
        "tags": ["realtime", "strip", "chart", "scrolling", "append", "circular", "live"],
        "description": "Three performance tiers for real-time data display.",
        "chart_object": "Pesgo (Scientific Graph Object)",
        "key_properties": [
            "PrepareImages", "AppendToEnd", "CircularBuffers",
            "ComputeShader", "StagingBufferY", "Filter2D3D",
            "Points", "Subsets", "Y", "X"
        ],
        "steps": [
            "Choose Pesgo for continuous X-axis data",
            "Set PrepareImages=True always for real-time",
            "Tier 1 (<10K pts): PeData.Y.AppendData + timer - auto-shifts data",
            "Tier 2 (10K-500K): Add CircularBuffers=True - pointer advance, no memory shift",
            "Tier 3 (500K+): Add RenderEngine=Direct3D + ComputeShader=True - GPU rendering",
            "Extreme (10M+): Add Filter2D3D=True + PeData.Y.UseDataAtLocation() for zero-copy",
        ],
        "code": (
            "// Tier 2: Circular buffer real-time\n"
            "Pesgo1.PeData.Subsets = 2;\n"
            "Pesgo1.PeData.Points = 500;\n"
            "Pesgo1.PeConfigure.PrepareImages = true;\n"
            "Pesgo1.PeData.CircularBuffers = true;\n"
            "Pesgo1.PePlot.Method = SGraphPlottingMethod.Line;\n"
            "\n"
            "// In timer tick:\n"
            "float[] newY = { sensor1, sensor2 };\n"
            "Pesgo1.PeData.Y.AppendData(newY, 1);\n"
            "Pesgo1.PeFunction.ReinitializeResetImage();"
        ),
        "notes": "Use pe_query_v4.py to look up exact property paths. Query: props PrepareImages,CircularBuffers,ComputeShader",
        "examples": ["115", "116", "145", "146", "148"],
    },

    "multi-axis": {
        "title": "Multi-Axis Chart",
        "tags": ["multiaxis", "multi-axis", "dual", "secondary", "yaxis", "multiple"],
        "description": "Multiple Y axes on a single chart.",
        "chart_object": "Pesgo or Pego",
        "key_properties": [
            "MultiAxesSubsets", "MultiAxisStyle", "WorkingAxis",
            "ManualScaleControlY", "ManualMinY", "ManualMaxY"
        ],
        "steps": [
            "Set PeGrid.MultiAxesSubsets array to assign subsets to axes",
            "Set PeGrid.Option.MultiAxisStyle for layout (SeparateAxes or GroupAllAxes)",
            "Set PeGrid.WorkingAxis = N before configuring each axis",
            "WorkingAxis-dependent: ManualScaleControlY, ManualMinY, ManualMaxY, YAxisLabel, etc.",
            "See pe-workingaxis-dependent-properties knowledge file for full list",
        ],
        "code": (
            "Pesgo1.PeData.Subsets = 5;\n"
            "// 2 subsets on axis 0, 3 on axis 1\n"
            "Pesgo1.PeGrid.MultiAxesSubsets[0] = 2;\n"
            "Pesgo1.PeGrid.MultiAxesSubsets[1] = 3;\n"
            "Pesgo1.PeGrid.Option.MultiAxisStyle = MultiAxisStyle.SeparateAxes;\n"
            "\n"
            "// Configure axis 0\n"
            "Pesgo1.PeGrid.WorkingAxis = 0;\n"
            "Pesgo1.PeGrid.Configure.ManualScaleControlY = ManualScaleControl.MinMax;\n"
            "Pesgo1.PeGrid.Configure.ManualMinY = 0;\n"
            "Pesgo1.PeGrid.Configure.ManualMaxY = 100;"
        ),
        "examples": ["100", "104", "108"],
    },

    "bar-chart": {
        "title": "Bar Chart",
        "tags": ["bar", "barchart", "stacked", "grouped"],
        "description": "Bar charts with Pego.",
        "chart_object": "Pego (Graph Object)",
        "key_properties": ["PlottingMethod", "SubsetColors", "SubsetLabels", "PointLabels"],
        "steps": [
            "Use Pego. Set PePlot.Method = GraphPlottingMethod.Bar (or BarStacked, etc.)",
            "Subsets = series count, Points = category count",
            "PeString.PointLabels[i] = category label",
            "PeString.SubsetLabels[i] = series name",
        ],
        "code": (
            "Pego1.PeData.Subsets = 3;\n"
            "Pego1.PeData.Points = 5;\n"
            "Pego1.PePlot.Method = GraphPlottingMethod.Bar;\n"
            "Pego1.PeString.SubsetLabels[0] = \"Q1\";\n"
            "Pego1.PeString.PointLabels[0] = \"Product A\";\n"
            "Pego1.PeData.Y[0, 0] = 42.0f;"
        ),
        "examples": ["000", "001", "002"],
    },

    "zoom": {
        "title": "Programmatic Zoom",
        "tags": ["zoom", "pan", "scroll", "undo"],
        "description": "Enable and control zooming programmatically.",
        "chart_object": "Pego / Pesgo",
        "key_properties": ["AllowZooming", "ZoomMinX", "ZoomMaxX", "ZoomMinY", "ZoomMaxY", "ZoomMode", "PointsToGraph", "HorzScrollPos"],
        "steps": [
            "Enable: PeUserInterface.Allow.Zooming = AllowZooming.HorzAndVert",
            "Pesgo programmatic: set PeGrid.Zoom.MinX/MaxX + PeGrid.Zoom.Mode=true",
            "Pego programmatic: set PeUserInterface.Scrollbar.PointsToGraph + HorzScrollPos",
            "Undo: PeFunction.UndoZoom()",
        ],
        "examples": ["100", "110"],
    },

    "annotations": {
        "title": "Line & Graph Annotations",
        "tags": ["annotation", "line", "label", "marker", "horizontal", "vertical"],
        "description": "Add reference lines and text annotations to charts.",
        "chart_object": "Pego / Pesgo",
        "key_properties": ["HorzLineAnnotation", "VertLineAnnotation", "GraphAnnotationX", "GraphAnnotationY"],
        "steps": [
            "Horizontal lines: PeAnnotation.Line.YAxis[i] = Y value",
            "Vertical lines: PeAnnotation.Line.XAxis[i] = X value",
            "Set Type, Text, Color per annotation",
            "Graph annotations: PeAnnotation.Graph.X[i], Y[i], Text[i]",
            "Use query tool for exact paths: props HorzLineAnnotation",
        ],
        "examples": ["006", "106"],
    },

    "datetime": {
        "title": "Date/Time Axis",
        "tags": ["date", "time", "datetime", "timestamp", "serial"],
        "description": "Configure date/time axes on Pesgo or Pego.",
        "chart_object": "Pesgo / Pego",
        "key_properties": ["DateTimeMode", "DeltaX", "StartTime", "YearMonthDayStyle"],
        "steps": [
            "Pesgo: Set PeData.DateTimeMode=true, pass serial dates as X values (DateTime.ToOADate())",
            "Pego: Set PeData.DateTimeMode=true + PeData.DeltaX (daily/monthly/etc.)",
            "Formatting: PeGrid.Option.YearMonthDayStyle for date order",
            "Custom format: disable DateTimeMode, use CustomGridNumber event (example 132)",
        ],
        "examples": ["020", "029", "132", "135"],
    },

    "pie-chart": {
        "title": "Pie / Doughnut Chart",
        "tags": ["pie", "doughnut", "donut", "slice"],
        "description": "Pie charts with Pepco.",
        "chart_object": "Pepco (Pie Chart Object)",
        "key_properties": ["SubsetColors", "SubsetLabels"],
        "steps": [
            "Use Pepco. Subsets = slices, Points = 1",
            "PeData.Y[subset, 0] = slice value",
            "PeString.SubsetLabels[i] = slice label",
        ],
        "code": (
            "Pepco1.PeData.Subsets = 4;\n"
            "Pepco1.PeData.Points = 1;\n"
            "Pepco1.PeData.Y[0, 0] = 35.0f;\n"
            "Pepco1.PeString.SubsetLabels[0] = \"North\";"
        ),
        "examples": ["400", "401"],
    },

    "printing": {
        "title": "Printing & Export",
        "tags": ["print", "export", "pdf", "emf", "png", "bitmap"],
        "description": "Print charts or export as images.",
        "chart_object": "All",
        "key_properties": ["PrintDpi", "DefOrientation", "PrintStyleControl"],
        "steps": [
            "Simple: PeFunction.PrintGraph(0, 0, DefOrientation.Landscape)",
            "Multi-chart: use PrintGraphEx with PrintDocument hDC",
            "Export: PeFunction.Image.PngToStream(width, height)",
            "Always call PeFunction.ResetImage(0, 0) after printing",
            "See pe-printing knowledge file for full patterns",
        ],
        "examples": ["034", "134"],
    },

    "hotspots": {
        "title": "Click / HotSpot Interaction",
        "tags": ["hotspot", "click", "interactive", "drill"],
        "description": "Enable clickable chart regions.",
        "chart_object": "All",
        "key_properties": ["AllowDataHotSpots", "AllowSubsetHotSpots", "AllowPointHotSpots"],
        "steps": [
            "Enable: PeUserInterface.HotSpot.Data = true (or .Subset, .Point, etc.)",
            "Handle: Pesgo1.PeDataHotSpot += (s, e) => { e.Subset, e.Point }",
            "See pe-hotspots knowledge file for full enable/event matrix",
        ],
        "examples": ["023", "123"],
    },

    "custom-grid": {
        "title": "Custom Grid Numbers / Axis Labels",
        "tags": ["custom", "grid", "label", "format", "axis"],
        "description": "Override axis number formatting via events.",
        "key_properties": ["CustomGridNumbersX", "CustomGridNumbersY"],
        "steps": [
            "Enable: PeGrid.Option.CustomGridNumbersY = true",
            "Handle PeCustomGridNumber event",
            "In handler: if (e.AxisType == 1) e.NumberString = your_format(e.NumberValue)",
        ],
        "code": (
            "Pesgo1.PeGrid.Option.CustomGridNumbersY = true;\n"
            "Pesgo1.PeCustomGridNumber += (s, e) => {\n"
            "    if (e.AxisType == 1) // Y axis\n"
            "        e.NumberString = $\"{e.NumberValue:F1}\\u00B0C\";\n"
            "};"
        ),
        "examples": ["132"],
    },
}


# -
# File Discovery
# -

def find_data_files(enriched_arg=None, unified_arg=None, examples_arg=None):
    script_dir = Path(__file__).parent
    search_dirs = [Path.cwd(), script_dir, script_dir / "data"]

    enriched_names = ["net-complete-enriched.json", "ProEssentials_net-complete-enriched.json"]
    unified_names = ["ProEssentials_unified-docs.json", "unified-docs.json"]
    examples_names = ["ProEssentials_allExamples.json", "allExamples.json"]
    feature_names = ["pe-feature-index.json", "pe-feature-index-slim.json"]

    def find(arg, names):
        if arg and Path(arg).exists():
            return str(arg)
        for d in search_dirs:
            for n in names:
                p = d / n
                if p.exists():
                    return str(p)
        return None

    enriched_path = find(enriched_arg, enriched_names)
    unified_path = find(unified_arg, unified_names)
    examples_path = find(examples_arg, examples_names)
    feature_path = find(None, feature_names)

    if not enriched_path:
        print("ERROR: Cannot find net-complete-enriched.json", file=sys.stderr)
        sys.exit(1)
    if not unified_path:
        print("ERROR: Cannot find unified-docs JSON file.", file=sys.stderr)
        sys.exit(1)
    if not examples_path:
        print("ERROR: Cannot find allExamples JSON file.", file=sys.stderr)
        sys.exit(1)

    return enriched_path, unified_path, examples_path, feature_path


# -
# CLI
# -

def main():
    parser = argparse.ArgumentParser(
        description=f"ProEssentials AI Query Tool v{VERSION}",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Commands:
  props <names>                     Get properties by comma-separated names
  props --category <cat>            List properties in a category
  props --object <obj>              List properties for a chart object
  search <term>                     Full-text search across all items
  enum <name>                       Get all values for an enum
  events [--object <obj>]           List .NET events
  event <name>                      Get full detail for one event
  functions [--type net|dll|ocx]     List functions (ocx = ActiveX/VCL methods)
  function <name>                   Get full detail for one function
  methods <parent>                  List methods on a property array (e.g., PeData.Y)
  validate <paths>                  Validate .NET paths against ground truth
  examples [--feature|--prop|--object]  Find examples
  example <id> [--lang csharp|cpp|vba]  Get full code for an example
  related <name>                    Get seeAlso + same-group properties
  recipe <topic>                    Show a task-oriented recipe/pattern
  structures [<name>]               List or show structures
  info                              Show dataset statistics
        """,
    )
    parser.add_argument("command", help="Query command")
    parser.add_argument("args", nargs="*", help="Command arguments")
    parser.add_argument("--category", "-c", help="Filter by category")
    parser.add_argument("--object", "-o", help="Filter by chart object")
    parser.add_argument("--feature", "-f", help="Search examples by feature")
    parser.add_argument("--prop", "-p", help="Search examples by property usage")
    parser.add_argument("--type", "-t", help="Function type: net or dll")
    parser.add_argument("--lang", "-l", default="csharp", help="Code language: csharp or cpp")
    parser.add_argument("--list", action="store_true", help="Compact list mode")
    parser.add_argument("--max", type=int, default=20, help="Max search results")
    parser.add_argument("--enriched", help="Path to enriched JSON")
    parser.add_argument("--docs", help="Path to unified-docs JSON")
    parser.add_argument("--examples", help="Path to allExamples JSON")

    args = parser.parse_args()

    enriched_path, unified_path, examples_path, feature_path = find_data_files(
        args.enriched, args.docs, args.examples
    )
    pe = PEDocs(enriched_path, unified_path, examples_path, feature_path)

    cmd = args.command.lower()

    if cmd == "props":
        names = None
        if args.args:
            names = []
            for a in args.args:
                names.extend(n.strip() for n in a.split(",") if n.strip())
        print(pe.cmd_props(names=names, category=args.category, obj=args.object, list_mode=args.list))

    elif cmd == "search":
        term = " ".join(args.args) if args.args else ""
        if not term:
            print("Usage: pe_query_v4.py search <term>")
            sys.exit(1)
        print(pe.cmd_search(term, max_results=args.max))

    elif cmd == "enum":
        name = " ".join(args.args) if args.args else ""
        if not name:
            print(f"=== All Enums ({len(pe.enums)}) ===")
            for k in sorted(pe.enums.keys()):
                n = len(pe.enums[k].get("values", []))
                print(f"  {k} ({n} values)")
        else:
            print(pe.cmd_enum(name))

    elif cmd == "events":
        if args.args:
            print(pe.cmd_event(args.args[0]))
        else:
            print(pe.cmd_events(obj=args.object))

    elif cmd == "event":
        name = " ".join(args.args) if args.args else ""
        if not name:
            print("Usage: pe_query_v4.py event <name>")
            sys.exit(1)
        print(pe.cmd_event(name))

    elif cmd == "functions":
        if args.args:
            print(pe.cmd_function(args.args[0]))
        else:
            print(pe.cmd_functions(func_type=args.type, obj=args.object))

    elif cmd == "function":
        name = " ".join(args.args) if args.args else ""
        if not name:
            print("Usage: pe_query_v4.py function <name>")
            sys.exit(1)
        print(pe.cmd_function(name))

    elif cmd == "methods":
        parent = " ".join(args.args) if args.args else ""
        if not parent:
            print("Usage: pe_query_v4.py methods <parent_path>")
            print("Example: pe_query_v4.py methods PeData.Y")
            sys.exit(1)
        print(pe.cmd_methods(parent))

    elif cmd == "validate":
        paths = []
        for a in args.args:
            paths.extend(n.strip() for n in a.split(",") if n.strip())
        if not paths:
            print("Usage: pe_query_v4.py validate <path1,path2,...>")
            sys.exit(1)
        print(pe.cmd_validate(paths))

    elif cmd == "examples":
        print(pe.cmd_examples(
            feature=args.feature or (" ".join(args.args) if args.args and not args.prop else None),
            prop=args.prop,
            obj=args.object,
        ))

    elif cmd == "example":
        if not args.args:
            print("Usage: pe_query_v4.py example <id> [--lang csharp|cpp]")
            sys.exit(1)
        print(pe.cmd_example(args.args[0], lang=args.lang))

    elif cmd == "related":
        name = " ".join(args.args) if args.args else ""
        if not name:
            print("Usage: pe_query_v4.py related <name>")
            sys.exit(1)
        print(pe.cmd_related(name))

    elif cmd == "recipe":
        topic = " ".join(args.args) if args.args else ""
        if not topic:
            print("Available recipes:")
            for key, recipe in sorted(RECIPES.items()):
                print(f"  {key} - {recipe.get('title', '')}")
        else:
            print(pe.cmd_recipe(topic))

    elif cmd == "structures":
        name = args.args[0] if args.args else None
        print(pe.cmd_structures(name))

    elif cmd == "features":
        if args.list:
            print(pe.cmd_features_list(obj=args.object))
        elif args.args:
            query = " ".join(args.args)
            print(pe.cmd_features(query, obj=args.object))
        else:
            print("Usage: pe_query.py features <query>  OR  pe_query.py features --list")
            sys.exit(1)

    elif cmd in ("example-features", "exfeatures", "ef"):
        if not args.args:
            print("Usage: pe_query.py example-features <id>")
            sys.exit(1)
        print(pe.cmd_example_features(args.args[0]))

    elif cmd == "info":
        print(pe.cmd_info())

    else:
        print(f"Unknown command: '{cmd}'")
        print("Run: python pe_query_v4.py --help")
        sys.exit(1)


if __name__ == "__main__":
    main()