lvkit 0.1.0__tar.gz → 0.2.1__tar.gz

{lvkit-0.1.0 → lvkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvkit
-Version: 0.1.0
+Version: 0.2.1
 Summary: Understand and convert LabVIEW VIs to Python without a LabVIEW license
 Project-URL: Repository, https://github.com/pragmatest-dev/lvkit
 Project-URL: Issues, https://github.com/pragmatest-dev/lvkit/issues
@@ -28,6 +28,8 @@ Requires-Dist: mcp>=0.9.0
 Requires-Dist: networkx
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pylabview
+Provides-Extra: visualize
+Requires-Dist: pyvis; extra == 'visualize'
 Description-Content-Type: text/markdown
 
 # lvkit
@@ -40,7 +42,6 @@ lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryab
 
 - [Quick Start](#quick-start)
 - [What you can do with it](#what-you-can-do-with-it)
-- [CLI Commands](#cli-commands)
 - [How it works](#how-it-works)
 - [AI and IDE integration](#ai-and-ide-integration)
 - [Cleanroom approach](#cleanroom-approach)
@@ -50,11 +51,29 @@ lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryab
 
 ```bash
 pip install lvkit
-lvkit init --skills all       # create .lvkit/ + install Claude Code and Copilot skills
+lvkit setup
 ```
 
-* Use `--skills claude` or `--skills copilot` to install for one AI agent only.
-* Use `lvkit init` alone if you don't want any AI agent skills installed.
+For a global install: `pipx install lvkit` or `uv tool install lvkit`.
+
+`lvkit setup` creates a `.lvkit/` resolution store and installs AI agent skills:
+
+- Auto-detects Claude Code (`CLAUDE.md` / `.claude/`) and Copilot (`.github/copilot-instructions.md` / `.github/instructions/` / `.github/agents.md`)
+- Pass `claude`, `copilot`, or `all` to be explicit
+- Use `--no-skills` to create the `.lvkit/` store without installing any skills
+
+| Command | Description |
+|---------|-------------|
+| `lvkit describe` | Human-readable VI description with signature and operations |
+| `lvkit docs` | Generate cross-referenced HTML documentation |
+| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
+| `lvkit visualize` | Mermaid flowchart or interactive dependency graph |
+| `lvkit generate` | Generate Python from a VI, library, or class (experimental — see [Cleanroom approach](#cleanroom-approach)) |
+| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
+| `lvkit setup` | Install AI agent skills; create `.lvkit/` resolution store |
+| `lvkit mcp` | Start the MCP server for IDE integration |
+
+`lvkit visualize --format interactive` requires `pip install lvkit[visualize]`. All other commands work on a bare `pip install lvkit`.
 
 ## What you can do with it
 
@@ -92,22 +111,7 @@ lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--place
 
 `--placeholder-on-unresolved` lets the build succeed when mappings are missing — unresolved calls become inline `raise PrimitiveResolutionNeeded(...)` in the output so you can track them down at runtime.
 
-Coverage is incremental — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `lvkit describe` | Human-readable VI description with signature and operations |
-| `lvkit docs` | Generate cross-referenced HTML documentation |
-| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
-| `lvkit visualize` | Mermaid flowchart or interactive dependency graph |
-| `lvkit generate` | Generate Python from a VI, library, or class |
-| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
-| `lvkit init` | Create `.lvkit/` resolution store; install AI editor skills |
-| `lvkit mcp` | Start the MCP server for IDE integration |
-
-`lvkit visualize --format interactive` requires `pip install pyvis`. All other commands work on a bare `pip install lvkit`.
+Coverage is incremental and results will vary — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
 
 ## How it works
 
@@ -125,17 +129,18 @@ See [`docs/graph-reference.md`](docs/graph-reference.md) for the full graph type
 
 The CLI works standalone from any terminal or CI script. For deeper IDE integration, lvkit ships two optional layers.
 
-**AI editor skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
+**AI agent skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI agent can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
 
 ```bash
-lvkit init --skills claude    # installs .claude/skills/lvkit-*
-lvkit init --skills copilot   # installs .github/prompts/ + router instruction
-lvkit init --skills all       # both
+lvkit setup           # auto-detect from project layout
+lvkit setup claude    # installs .claude/skills/lvkit-*
+lvkit setup copilot   # installs .github/prompts/ + router instruction
+lvkit setup all       # both
 ```
 
 Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive`, `lvkit-resolve-vilib`, `lvkit-idiomatic`.
 
-**MCP server** — for interactive IDE sessions where your AI needs to load a graph, walk wires, and ask follow-up questions across multiple VIs:
+**MCP server** — for interactive IDE sessions where your AI agent needs to load a graph, walk wires, and ask follow-up questions across multiple VIs:
 
 ```json
 {
@@ -168,11 +173,13 @@ Coverage is incremental. When `lvkit generate` encounters an unmapped primitive
 
 ### Project-local resolution store (`.lvkit/`)
 
-If you have a LabVIEW license, you can supplement the bundled mappings with a `.lvkit/` directory derived from your own install. lvkit reads `.lvkit/` first and falls back to its bundled data. The skills installed by `lvkit init` detect whether you're a lvkit maintainer or a downstream user and write mappings to the right destination.
+You can supplement the bundled mappings with a `.lvkit/` directory in your project root. lvkit reads `.lvkit/` first and falls back to its bundled data.
+
+Run `lvkit setup --no-skills` to create the store with a README that documents the file layout and JSON formats for adding primitive and vi.lib mappings manually.
 
 When `lvkit generate` hits an unknown, you have two options:
 
-1. **Resolve up front** — install the resolve skills (`lvkit init --skills claude`) and let your AI editor write the mapping into `.lvkit/`.
+1. **Resolve up front** — run `lvkit setup` to install the resolve skills and let your AI agent write the mapping into `.lvkit/`.
 2. **Defer to runtime** — pass `--placeholder-on-unresolved`. lvkit emits an inline `raise PrimitiveResolutionNeeded(...)` in the generated Python with full diagnostic context. The build succeeds; runtime fails at the unresolved call.
 
 ## Development

{lvkit-0.1.0 → lvkit-0.2.1}/README.md

@@ -8,7 +8,6 @@ lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryab
 
 - [Quick Start](#quick-start)
 - [What you can do with it](#what-you-can-do-with-it)
-- [CLI Commands](#cli-commands)
 - [How it works](#how-it-works)
 - [AI and IDE integration](#ai-and-ide-integration)
 - [Cleanroom approach](#cleanroom-approach)
@@ -18,11 +17,29 @@ lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryab
 
 ```bash
 pip install lvkit
-lvkit init --skills all       # create .lvkit/ + install Claude Code and Copilot skills
+lvkit setup
 ```
 
-* Use `--skills claude` or `--skills copilot` to install for one AI agent only.
-* Use `lvkit init` alone if you don't want any AI agent skills installed.
+For a global install: `pipx install lvkit` or `uv tool install lvkit`.
+
+`lvkit setup` creates a `.lvkit/` resolution store and installs AI agent skills:
+
+- Auto-detects Claude Code (`CLAUDE.md` / `.claude/`) and Copilot (`.github/copilot-instructions.md` / `.github/instructions/` / `.github/agents.md`)
+- Pass `claude`, `copilot`, or `all` to be explicit
+- Use `--no-skills` to create the `.lvkit/` store without installing any skills
+
+| Command | Description |
+|---------|-------------|
+| `lvkit describe` | Human-readable VI description with signature and operations |
+| `lvkit docs` | Generate cross-referenced HTML documentation |
+| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
+| `lvkit visualize` | Mermaid flowchart or interactive dependency graph |
+| `lvkit generate` | Generate Python from a VI, library, or class (experimental — see [Cleanroom approach](#cleanroom-approach)) |
+| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
+| `lvkit setup` | Install AI agent skills; create `.lvkit/` resolution store |
+| `lvkit mcp` | Start the MCP server for IDE integration |
+
+`lvkit visualize --format interactive` requires `pip install lvkit[visualize]`. All other commands work on a bare `pip install lvkit`.
 
 ## What you can do with it
 
@@ -60,22 +77,7 @@ lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--place
 
 `--placeholder-on-unresolved` lets the build succeed when mappings are missing — unresolved calls become inline `raise PrimitiveResolutionNeeded(...)` in the output so you can track them down at runtime.
 
-Coverage is incremental — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `lvkit describe` | Human-readable VI description with signature and operations |
-| `lvkit docs` | Generate cross-referenced HTML documentation |
-| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
-| `lvkit visualize` | Mermaid flowchart or interactive dependency graph |
-| `lvkit generate` | Generate Python from a VI, library, or class |
-| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
-| `lvkit init` | Create `.lvkit/` resolution store; install AI editor skills |
-| `lvkit mcp` | Start the MCP server for IDE integration |
-
-`lvkit visualize --format interactive` requires `pip install pyvis`. All other commands work on a bare `pip install lvkit`.
+Coverage is incremental and results will vary — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
 
 ## How it works
 
@@ -93,17 +95,18 @@ See [`docs/graph-reference.md`](docs/graph-reference.md) for the full graph type
 
 The CLI works standalone from any terminal or CI script. For deeper IDE integration, lvkit ships two optional layers.
 
-**AI editor skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
+**AI agent skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI agent can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
 
 ```bash
-lvkit init --skills claude    # installs .claude/skills/lvkit-*
-lvkit init --skills copilot   # installs .github/prompts/ + router instruction
-lvkit init --skills all       # both
+lvkit setup           # auto-detect from project layout
+lvkit setup claude    # installs .claude/skills/lvkit-*
+lvkit setup copilot   # installs .github/prompts/ + router instruction
+lvkit setup all       # both
 ```
 
 Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive`, `lvkit-resolve-vilib`, `lvkit-idiomatic`.
 
-**MCP server** — for interactive IDE sessions where your AI needs to load a graph, walk wires, and ask follow-up questions across multiple VIs:
+**MCP server** — for interactive IDE sessions where your AI agent needs to load a graph, walk wires, and ask follow-up questions across multiple VIs:
 
 ```json
 {
@@ -136,11 +139,13 @@ Coverage is incremental. When `lvkit generate` encounters an unmapped primitive
 
 ### Project-local resolution store (`.lvkit/`)
 
-If you have a LabVIEW license, you can supplement the bundled mappings with a `.lvkit/` directory derived from your own install. lvkit reads `.lvkit/` first and falls back to its bundled data. The skills installed by `lvkit init` detect whether you're a lvkit maintainer or a downstream user and write mappings to the right destination.
+You can supplement the bundled mappings with a `.lvkit/` directory in your project root. lvkit reads `.lvkit/` first and falls back to its bundled data.
+
+Run `lvkit setup --no-skills` to create the store with a README that documents the file layout and JSON formats for adding primitive and vi.lib mappings manually.
 
 When `lvkit generate` hits an unknown, you have two options:
 
-1. **Resolve up front** — install the resolve skills (`lvkit init --skills claude`) and let your AI editor write the mapping into `.lvkit/`.
+1. **Resolve up front** — run `lvkit setup` to install the resolve skills and let your AI agent write the mapping into `.lvkit/`.
 2. **Defer to runtime** — pass `--placeholder-on-unresolved`. lvkit emits an inline `raise PrimitiveResolutionNeeded(...)` in the generated Python with full diagnostic context. The build succeeds; runtime fails at the unresolved call.
 
 ## Development

{lvkit-0.1.0 → lvkit-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.1.0"
+version = "0.2.1"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,6 +45,9 @@ dependencies = [
     "pydantic>=2.0.0",
 ]
 
+[project.optional-dependencies]
+visualize = ["pyvis"]
+
 [project.urls]
 Repository = "https://github.com/pragmatest-dev/lvkit"
 Issues = "https://github.com/pragmatest-dev/lvkit/issues"
@@ -64,7 +67,7 @@ dev = [
 [tool.hatch.build.targets.wheel]
 # Bundled JSON data and skill templates live INSIDE the package at
 # src/lvkit/data/ and src/lvkit/skill_templates/ so they ride along with
-# the wheel automatically. The resolvers and `lvkit init --skills` load
+# the wheel automatically. The resolvers and `lvkit setup` load
 # them via paths relative to the package or via importlib.resources.
 packages = ["src/lvkit"]
 

{lvkit-0.1.0 → lvkit-0.2.1}/src/lvkit/cli.py

@@ -249,30 +249,39 @@ def main() -> int:
     )
     _add_project_root_arg(diff_parser)
 
-    # Init command - create .lvkit/ project store
-    init_parser = subparsers.add_parser(
-        "init",
-        help="Initialize a project-local .lvkit/ resolution store",
+    # Setup command - install AI editor skills and create .lvkit/ store
+    setup_parser = subparsers.add_parser(
+        "setup",
+        help="Install AI editor skills and create project-local .lvkit/ store",
     )
-    init_parser.add_argument(
+    setup_parser.add_argument(
         "directory",
         nargs="?",
         default=".",
         help="Directory in which to create .lvkit/ (default: current directory)",
     )
-    init_parser.add_argument(
-        "--skills",
+    setup_parser.add_argument(
+        "skills",
+        nargs="?",
         choices=["claude", "copilot", "all"],
         default=None,
         help=(
-            "Also install lvkit's resolve workflows into your LLM editor: "
-            "claude installs lvkit-prefixed Claude Code skills under "
-            ".claude/skills/; copilot installs per-workflow prompts under "
-            ".github/prompts/ plus a router at "
-            ".github/instructions/lvkit.instructions.md; all does both."
+            "AI agent to install skills for: claude, copilot, or all. "
+            "Omit to auto-detect from project layout (CLAUDE.md / .claude/ "
+            "for Claude Code; .github/copilot-instructions.md / "
+            ".github/instructions/ / .github/agents.md for Copilot)."
         ),
     )
-    init_parser.add_argument(
+    setup_parser.add_argument(
+        "--no-skills",
+        action="store_true",
+        help=(
+            "Create the .lvkit/ resolution store and README without installing "
+            "any AI editor skills. Use this if you want to add primitive or "
+            "vi.lib mappings manually."
+        ),
+    )
+    setup_parser.add_argument(
         "--force",
         action="store_true",
         help="Overwrite existing skill files even if they have local edits",
@@ -294,8 +303,8 @@ def main() -> int:
         return cmd_visualize(args)
     elif args.command == "diff":
         return cmd_diff(args)
-    elif args.command == "init":
-        return cmd_init(args)
+    elif args.command == "setup":
+        return cmd_setup(args)
     else:
         parser.print_help()
         return 0
@@ -397,7 +406,7 @@ def cmd_structure(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_mcp(args: argparse.Namespace) -> int:
+def cmd_mcp(_args: argparse.Namespace) -> int:
     """Handle the mcp command - run MCP server."""
     from .mcp.server import main as mcp_main
 
@@ -449,21 +458,52 @@ def cmd_describe(args: argparse.Namespace) -> int:
         return 1
 
 
-def cmd_init(args: argparse.Namespace) -> int:
-    """Handle the init command — create a project-local .lvkit/ store."""
+def _detect_ai_editors(root: Path) -> list[str]:
+    """Detect which AI editors are configured in the project."""
+    editors = []
+    if (root / ".claude").is_dir() or (root / "CLAUDE.md").is_file():
+        editors.append("claude")
+    if (
+        (root / ".github" / "copilot-instructions.md").is_file()
+        or (root / ".github" / "instructions").is_dir()
+        or (root / ".github" / "agents.md").is_file()
+    ):
+        editors.append("copilot")
+    return editors
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """Handle the setup command — install AI skills and create .lvkit/ store."""
     root = Path(args.directory).resolve()
     if not root.is_dir():
         print(f"Error: Not a directory: {root}", file=sys.stderr)
         return 1
 
     store = init_project_store(root)
-    print(f"Initialized project store at {store}")
-    print(f"  README: {store / 'README.md'}")
+    print(f"Initialized .lvkit/ store at {store}")
+
+    if args.no_skills:
+        return 0
+
+    # Resolve which editors to install for
+    explicit = args.skills
+    if explicit == "all":
+        editors = ["claude", "copilot"]
+    elif explicit in ("claude", "copilot"):
+        editors = [explicit]
+    else:
+        # Auto-detect from project layout
+        editors = _detect_ai_editors(root)
+        if not editors:
+            print(
+                "No AI agent detected. If you add one later, run `lvkit setup` again. "
+                "If you have one that wasn't detected, run `lvkit setup claude` or "
+                "`lvkit setup copilot` to install skills explicitly."
+            )
+            return 0
 
-    # Optional: install LLM editor skills
-    skills = getattr(args, "skills", None)
     force = getattr(args, "force", False)
-    if skills in ("claude", "all"):
+    if "claude" in editors:
         try:
             written = install_claude_skills(root, force=force)
         except FileExistsError as e:
@@ -475,7 +515,7 @@ def cmd_init(args: argparse.Namespace) -> int:
                 print(f"  {p}")
         else:
             print("Claude Code skills already up to date.")
-    if skills in ("copilot", "all"):
+    if "copilot" in editors:
         try:
             copilot_written = install_copilot_skills(root, force=force)
         except FileExistsError as e:
@@ -488,22 +528,6 @@ def cmd_init(args: argparse.Namespace) -> int:
         else:
             print("Copilot files already up to date.")
 
-    print()
-    print("Next steps:")
-    print(
-        "  - Create .lvkit/primitives.json to override primitive mappings"
-        " (use lvkit's bundled primitives.json as a reference)"
-    )
-    print(
-        "  - Add vi.lib mappings to .lvkit/vilib/<category>.json and register them"
-        " in .lvkit/vilib/_index.json"
-    )
-    print("  - lvkit will check .lvkit/ before its bundled data when resolving.")
-    if not skills:
-        print(
-            "  - Run `lvkit init --skills all` to install resolve workflows"
-            " into Claude Code and/or Copilot."
-        )
     return 0
 
 

{lvkit-0.1.0 → lvkit-0.2.1}/src/lvkit/codegen/nodes/subvi.py

@@ -34,7 +34,7 @@ def generate(node: SubVIOperation, ctx: CodeGenContext) -> CodeFragment:
     # Look up VI — polymorphic variant if selected, otherwise base name
     vilib_vi = None
     if node.poly_variant_name:
-        vilib_vi = _resolve_poly_variant(subvi_name, node, ctx)
+        vilib_vi = _resolve_poly_variant(subvi_name, node)
         if not vilib_vi:
             # Variant not in JSON — fail or emit inline raise
             return _emit_vilib_resolution(node, ctx, vilib_vi=None)
@@ -236,7 +236,7 @@ def _generate_inline(
     )
 
 def _resolve_poly_variant(
-    base_name: str, node: Operation, ctx: CodeGenContext
+    base_name: str, node: Operation
 ) -> VIEntry | None:
     """Resolve a polymorphic VI to its specific variant.
 
@@ -367,6 +367,7 @@ def _build_arguments(
                 ),
                 available=[],
                 vi_name=ctx.vi_name if ctx else None,
+                kind="vilib" if vilib_vi is not None else "subvi",
             )
 
         # Check if this parameter is an enum typedef - generate enum reference
@@ -521,6 +522,7 @@ def _build_output_bindings(
                 ),
                 available=[],
                 vi_name=ctx.vi_name if ctx else None,
+                kind="vilib" if vilib_vi is not None else "subvi",
             )
 
         bindings[term_id] = f"{result_var}.{field}"

{lvkit-0.1.0 → lvkit-0.2.1}/src/lvkit/pipeline.py

@@ -20,6 +20,7 @@ from typing import Any
 from lvkit.codegen import ClassBuilder, ClassConfig, build_module
 from lvkit.codegen.ast_utils import to_function_name, to_module_name
 from lvkit.graph import InMemoryVIGraph
+from lvkit.project_store import find_project_store
 from lvkit.structure import parse_lvclass
 from lvkit.terminal_collector import get_collector
 from lvkit.vilib_resolver import VILibResolver
@@ -661,6 +662,17 @@ def {func_name}(*args, **kwargs) -> Any:
     print(f"  stub:  {stub_count}")
     print(f"  error: {error_count}")
 
+    if error_count > 0:
+        store = find_project_store()
+        if store:
+            print(f"\n  To resolve errors, add mappings to {store}/")
+            print(f"  See {store / 'README.md'} for file formats and instructions.")
+            print("  AI agent skills can add these automatically — run `lvkit setup` if not installed.")
+        else:
+            print("\n  To resolve errors:")
+            print("  - Run `lvkit setup` to install AI agent skills that resolve unknowns automatically.")
+            print("  - Or run `lvkit setup --no-skills` to create a .lvkit/ store for manual mappings.")
+
     # Save terminal observations for incremental collection
     collector = get_collector()
     if collector.data.get("observations"):

{lvkit-0.1.0 → lvkit-0.2.1}/src/lvkit/primitive_resolver.py

@@ -75,7 +75,9 @@ class PrimitiveResolutionNeeded(Exception):
 class TerminalResolutionNeeded(Exception):
     """Raised when a specific wired terminal cannot be resolved to a known index.
 
-    The primitive definition exists, but a terminal's index doesn't match.
+    kind="primitive": a built-in LabVIEW primitive with a missing terminal index
+    kind="vilib":     a vilib VI with a missing terminal index in data/vilib/
+    kind="subvi":     a user project VI whose terminal name could not be resolved
     """
 
     def __init__(
@@ -86,6 +88,7 @@ class TerminalResolutionNeeded(Exception):
         terminal_type: str | None,
         available: list[dict[str, str | int | None]],
         vi_name: str | None = None,
+        kind: str = "primitive",
     ):
         self.prim_id = str(prim_id)
         self.prim_name = prim_name
@@ -93,13 +96,20 @@ class TerminalResolutionNeeded(Exception):
         self.terminal_type = terminal_type
         self.available = available
         self.vi_name = vi_name
+        self.kind = kind
         super().__init__(self._format_message())
 
     def _format_message(self) -> str:
-        msg = (
-            f"Terminal resolution needed for primitive"
-            f" {self.prim_id} ({self.prim_name}).\n"
-        )
+        if self.kind == "vilib":
+            header = f"Terminal resolution needed for vilib VI '{self.prim_name}'."
+        elif self.kind == "subvi":
+            header = f"Terminal resolution needed for project VI '{self.prim_name}'."
+        else:
+            header = (
+                f"Terminal resolution needed for primitive"
+                f" {self.prim_id} ({self.prim_name})."
+            )
+        msg = header + "\n"
         if self.vi_name:
             msg += f"  In VI: {self.vi_name}\n"
         msg += (
@@ -114,10 +124,24 @@ class TerminalResolutionNeeded(Exception):
             )
         if not self.available:
             msg += "    (none available)\n"
-        msg += (
-            f"\n  Fix: add/update terminal in data/primitives.json"
-            f" under primitive {self.prim_id}"
-        )
+        if self.kind == "vilib":
+            msg += (
+                f"\n  Fix: add/update terminal index in"
+                f" .lvkit/data/vilib/<category>.json (project-local)"
+                f" or data/vilib/<category>.json (upstream)"
+                f" under VI '{self.prim_name}'"
+            )
+        elif self.kind == "subvi":
+            msg += (
+                f"\n  Fix: ensure '{self.prim_name}' is reachable via --search-path"
+                f" and its terminal names are present in the VI's front panel"
+            )
+        else:
+            msg += (
+                f"\n  Fix: add primitive {self.prim_id} to"
+                f" .lvkit/data/primitives.json (project-local)"
+                f" or data/primitives.json (upstream)"
+            )
         return msg
 
 

{lvkit-0.1.0 → lvkit-0.2.1}/src/lvkit/skill_templates/lvkit-convert/SKILL.md

@@ -107,11 +107,11 @@ lvkit mcp                          # Start MCP server for IDE integration
 The MCP server (`lvkit mcp`) provides tools for interactive exploration:
 
 **Session:**
-- `load_vi` — Load VI into persistent graph
-- `list_loaded_vis` — List loaded VIs
+- `load` — Load VI into persistent graph
+- `list_loaded` — List loaded VIs
 
 **Exploration:**
-- `describe_vi` — Human-readable VI overview (signature, SubVIs, control flow)
+- `describe` — Human-readable VI overview (signature, SubVIs, control flow)
 - `get_operations` — Execution order with nested structures
 - `get_dataflow` — Wire connections, optionally filtered by operation
 - `get_structure` — Case/loop/sequence details
@@ -120,11 +120,11 @@ The MCP server (`lvkit mcp`) provides tools for interactive exploration:
 **Generation:**
 - `generate_ast_code` — Deterministic Python from loaded VI
 - `generate_python` — Full pipeline: load + generate + write files
-- `get_vi_context` — Raw VI context as JSON
+- `get_context` — Raw VI context as JSON
 
 **Documentation:**
 - `generate_documents` — Create HTML documentation
-- `analyze_vi` — Parse and return VI structure
+- `analyze` — Parse and return VI structure
 
 ## Related Skills
 

lvkit-0.2.1/src/lvkit/skill_templates/lvkit-describe/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: lvkit-describe
+description: Describe what a LabVIEW VI does — signature, operations, dataflow, structures, constants. Works via CLI or MCP.
+allowed-tools: Bash, Read, Grep
+---
+
+# Describe VI
+
+Run `lvkit describe` on the VI:
+
+```bash
+lvkit describe "<vi-path>" --search-path "<library-path>"
+```
+
+Add `--chart` to also print a Mermaid flowchart:
+
+```bash
+lvkit describe "<vi-path>" --search-path "<library-path>" --chart
+```
+
+**Report to the user using this format:**
+
+```
+# <VI name>
+
+**What it does:** <1-2 sentence interpretation — purpose, key behavior, notable observations>
+
+**Signature:** `<function signature>`
+
+| Input | Type | Default |
+|---|---|---|
+| <name> | <type> | <default or —> |
+
+| Output | Type |
+|---|---|
+| <name> | <type> |
+
+**Control flow:** <brief description — frames, loops, cases>
+<bulleted breakdown if the structure has meaningful steps>
+
+| Constant | Type | Value |
+|---|---|---|
+| <inferred name or purpose> | <type> | <value> |
+
+| Dependency | Description |
+|---|---|
+| <VI name> | <what it does> |
+
+**Notable:** <surprising things, naming quirks, caveats — omit section if nothing to say>
+```
+
+Rules:
+- Omit any table that has no rows (e.g. no inputs → no inputs table)
+- Collapse repeated dependencies: `DAQmx Write.vi ×3`
+- Use judgment on Constants — infer purpose from context, omit trivial ones
+- Interpretation leads; raw data follows
+
+## MCP alternative
+
+If MCP tools are available, use them directly:
+
+- `load` → `describe` → `get_operations` → `get_dataflow` → `get_structure` → `get_constants`
+
+## Note
+
+`lvkit describe` never requires resolution to succeed. Unknown primitives and vi.lib VIs render as `[prim N]` / their bare name.