feat: update AI agent workflow rules, BOM scanning guidance, and CLI diagnostics

Author: Coding-Meet

.agents/skills/library-insight/SKILL.md

@@ -26,15 +26,16 @@ Library Insight analyzes compiled libraries (JVM artifacts and Kotlin Multiplatf
 > **Indexing & Version Discovery**
 >
 > - Use **`library-insight scan <jar|aar|klib|directory|maven-coordinate>`** to index compiled libraries.
-> - **BOM & KMP Scanning:** For Bill of Materials (BOM) coordinates (e.g. `androidx.compose:compose-bom:2024.09.00` or `com.google.firebase:firebase-bom`) and KMP libraries, `library-insight scan` automatically resolves member libraries and applies target platform filtering (`-p, --platform android` by default) to filter out non-target KMP variants (iOS, JS, Wasm), stubs, and lints in seconds. Pass `--platform all` to scan all variants.
-> - **Zero-Knowledge Version Discovery:** If the user does not specify a library version, inspect `gradle/libs.versions.toml` or `build.gradle.kts` to discover the project's declared version. If not present in the project, run **`library-insight search-central <query>`** to query the latest coordinate from Maven Central.
+> - **BOM & KMP Scanning:** For Bill of Materials (BOM) coordinates (e.g. `androidx.compose:compose-bom:2024.09.00` or `com.google.firebase:firebase-bom`) and KMP libraries, `library-insight scan` automatically resolves member libraries and applies target platform filtering (`-p, --platform android` by default) to filter out non-target KMP variants (iOS, JS, Wasm), stubs, and lints in seconds. Pass `--platform all` to scan all variants. Use **`-i, --include <pattern>`** (e.g. `-i "*foundation*"` or `-i "*ui*"`) to selectively scan matching member artifacts. **AI Agent Rule:** Use surrounding wildcards like `-i "*foundation*"` for include filters to match full group/artifact coordinates. Automatically infer and append missing `-i` and `-p` flags based on intent.
+> - **Zero-Knowledge Version Discovery:** If the user does not specify a library version, inspect `gradle/libs.versions.toml` or `build.gradle.kts` to discover the project's declared version. For standard open-source dependencies not declared in the project, run **`library-insight search-central <query>`** to query Maven Central. (Note: AndroidX and Compose libraries are hosted on Google Maven, so check `libs.versions.toml` or `build.gradle.kts` directly).
 > - Use **`library-insight scan-source <directory>`** to index a local Java/Kotlin source project without compilation.
 >
 > **Querying**
 >
 > - Use **`library-insight search <query>`** to locate packages, classes, methods, or properties.
 > - Use **`library-insight explain <class|function|member> [--deep]`** to inspect a class or top-level Kotlin symbol. Always pass **`--deep`** (or **`-d`**) when exploring DSLs or multi-type APIs (e.g. `library-insight explain Grid --deep` auto-resolves top-level `GridKt` and recursively includes all referenced receiver scopes like `GridScope` and `GridConfigurationScope` in 1 single turn).
-> - Use **`library-insight examples <class>`** to generate typical usage examples.
+> - **Inner & Companion Class Shell Escaping:** When querying nested or Companion classes in bash/zsh shell, escape the dollar sign with quotes (e.g. `library-insight explain "GridTrackSize\$Companion"`).
+> - Use **`library-insight examples <class>`** to generate typical usage examples (for top-level Kotlin functions, pass the facade class name e.g. `examples GridKt`).
 >
 > **Analysis**
 >
@@ -154,15 +155,13 @@ or
 
 ## Additional Guidance for AI Agents
 
-When answering questions about a library or project:
+When answering questions or generating code for a library or project, AI agents MUST follow this mandatory step-by-step workflow:
 
-1. Index the target if it has not already been indexed.
-2. Search before explaining.
-3. Explain only the symbols relevant to the user's request.
-4. Avoid loading the full index into context.
-5. Prefer focused symbol lookups over large exports.
-6. Generate AI context (`ai-export`) only when broad project understanding is required.
-7. When an MCP server is available, prefer MCP tools over spawning CLI processes.
+1. **Step 1: Version & Coordinates Discovery:** Check `gradle/libs.versions.toml` or `build.gradle.kts` to discover declared library versions. For undeclared libraries, run `library-insight search-central <query>` on Maven Central.
+2. **Step 2: Indexing:** Run `library-insight scan <coordinate> -i "<include-pattern>" -p android` (or `scan-source`) to index the target library.
+3. **Step 3: Mandatory Symbol Search:** ALWAYS run `library-insight search <query>` (e.g. `library-insight search Grid`) FIRST to discover all matching packages, classes, methods, and properties in the index. **DO NOT skip `search` or jump directly to `explain` without searching first.**
+4. **Step 4: Exact Symbol Priority Rule:** Run `library-insight explain <ExactSymbol> --deep` on the exact requested symbol (e.g. `Grid`) or top match from `search` before considering secondary alternatives.
+5. **Step 5: Code Generation & File Edits Rule:** Directly modify or create the target source file in the user's project with the version-matched code instead of only outputting raw code snippets in the chat response.
 
 # Scanners & Indexing
 
@@ -184,6 +183,7 @@ library-insight scan com.squareup.retrofit2:retrofit:2.11.0
 - `--db <file>`: Path to save the JSON index database (default: `build/library-insight-index.json`)
 - `-s, --sources <file>`: Path to sources JAR/AAR or source code folder to extract Javadoc/KDoc comments & guide examples
 - `-p, --platform <target>`: Target platform filter for BOM and KMP scans (`android`, `jvm`, `ios`, `desktop`, `all`). Defaults to `android`. Filters out non-target KMP variants (e.g. iOS/JS/Wasm), stubs, and lints.
+- `-i, --include <pattern>`: Filter BOM managed dependencies by wildcard pattern (e.g. `-i "compose-ui*"`, `-i "*animation*"`). Multiple allowed.
 - `--repo <url>`: Additional Maven repository URL to download coordinates (multiple allowed)
 - `--lib-name <name>`: Override the library name in the generated index
 - `--lib-version <version>`: Override the version tag in the generated index

.agents/skills/library-insight/SKILL.template.md

@@ -26,15 +26,16 @@ Library Insight analyzes compiled libraries (JVM artifacts and Kotlin Multiplatf
 > **Indexing & Version Discovery**
 >
 > - Use **`library-insight scan <jar|aar|klib|directory|maven-coordinate>`** to index compiled libraries.
-> - **BOM & KMP Scanning:** For Bill of Materials (BOM) coordinates (e.g. `androidx.compose:compose-bom:2024.09.00` or `com.google.firebase:firebase-bom`) and KMP libraries, `library-insight scan` automatically resolves member libraries and applies target platform filtering (`-p, --platform android` by default) to filter out non-target KMP variants (iOS, JS, Wasm), stubs, and lints in seconds. Pass `--platform all` to scan all variants.
-> - **Zero-Knowledge Version Discovery:** If the user does not specify a library version, inspect `gradle/libs.versions.toml` or `build.gradle.kts` to discover the project's declared version. If not present in the project, run **`library-insight search-central <query>`** to query the latest coordinate from Maven Central.
+> - **BOM & KMP Scanning:** For Bill of Materials (BOM) coordinates (e.g. `androidx.compose:compose-bom:2024.09.00` or `com.google.firebase:firebase-bom`) and KMP libraries, `library-insight scan` automatically resolves member libraries and applies target platform filtering (`-p, --platform android` by default) to filter out non-target KMP variants (iOS, JS, Wasm), stubs, and lints in seconds. Pass `--platform all` to scan all variants. Use **`-i, --include <pattern>`** (e.g. `-i "*foundation*"` or `-i "*ui*"`) to selectively scan matching member artifacts. **AI Agent Rule:** Use surrounding wildcards like `-i "*foundation*"` for include filters to match full group/artifact coordinates. Automatically infer and append missing `-i` and `-p` flags based on intent.
+> - **Zero-Knowledge Version Discovery:** If the user does not specify a library version, inspect `gradle/libs.versions.toml` or `build.gradle.kts` to discover the project's declared version. For standard open-source dependencies not declared in the project, run **`library-insight search-central <query>`** to query Maven Central. (Note: AndroidX and Compose libraries are hosted on Google Maven, so check `libs.versions.toml` or `build.gradle.kts` directly).
 > - Use **`library-insight scan-source <directory>`** to index a local Java/Kotlin source project without compilation.
 >
 > **Querying**
 >
 > - Use **`library-insight search <query>`** to locate packages, classes, methods, or properties.
 > - Use **`library-insight explain <class|function|member> [--deep]`** to inspect a class or top-level Kotlin symbol. Always pass **`--deep`** (or **`-d`**) when exploring DSLs or multi-type APIs (e.g. `library-insight explain Grid --deep` auto-resolves top-level `GridKt` and recursively includes all referenced receiver scopes like `GridScope` and `GridConfigurationScope` in 1 single turn).
-> - Use **`library-insight examples <class>`** to generate typical usage examples.
+> - **Inner & Companion Class Shell Escaping:** When querying nested or Companion classes in bash/zsh shell, escape the dollar sign with quotes (e.g. `library-insight explain "GridTrackSize\$Companion"`).
+> - Use **`library-insight examples <class>`** to generate typical usage examples (for top-level Kotlin functions, pass the facade class name e.g. `examples GridKt`).
 >
 > **Analysis**
 >
@@ -154,14 +155,12 @@ or
 
 ## Additional Guidance for AI Agents
 
-When answering questions about a library or project:
+When answering questions or generating code for a library or project, AI agents MUST follow this mandatory step-by-step workflow:
 
-1. Index the target if it has not already been indexed.
-2. Search before explaining.
-3. Explain only the symbols relevant to the user's request.
-4. Avoid loading the full index into context.
-5. Prefer focused symbol lookups over large exports.
-6. Generate AI context (`ai-export`) only when broad project understanding is required.
-7. When an MCP server is available, prefer MCP tools over spawning CLI processes.
+1. **Step 1: Version & Coordinates Discovery:** Check `gradle/libs.versions.toml` or `build.gradle.kts` to discover declared library versions. For undeclared libraries, run `library-insight search-central <query>` on Maven Central.
+2. **Step 2: Indexing:** Run `library-insight scan <coordinate> -i "<include-pattern>" -p android` (or `scan-source`) to index the target library.
+3. **Step 3: Mandatory Symbol Search:** ALWAYS run `library-insight search <query>` (e.g. `library-insight search Grid`) FIRST to discover all matching packages, classes, methods, and properties in the index. **DO NOT skip `search` or jump directly to `explain` without searching first.**
+4. **Step 4: Exact Symbol Priority Rule:** Run `library-insight explain <ExactSymbol> --deep` on the exact requested symbol (e.g. `Grid`) or top match from `search` before considering secondary alternatives.
+5. **Step 5: Code Generation & File Edits Rule:** Directly modify or create the target source file in the user's project with the version-matched code instead of only outputting raw code snippets in the chat response.
 
 {{COMMAND_REFERENCE}}

README.md

@@ -195,3 +195,11 @@ Generate application binary packages (ZIP, TAR, and local install distributions)
 ```bash
 ./gradlew installDist distZip distTar
 ```
+
+### 7. Local Development Install
+
+Compile local source code and install binaries and AI skills globally:
+
+```bash
+./install.sh --local
+```

docs/ai-agents.md

@@ -112,12 +112,15 @@ Here are concrete examples of how you can prompt AI coding assistants (Cursor, C
 ### Example 5: Version Catalog Auto-Discovery & Zero-Knowledge Scanning
 
 > **Developer Prompt:**
-> _"I want to create a grid layout using Compose, but I don't know the exact library version. Find the library name and version from our project's version catalog (`gradle/libs.versions.toml`), scan it with `library-insight`, and generate the code for me."_
+> _"I want to create a grid layout using Compose BOM in our project, but I don't know the exact library version. Find the library name and version from our project's version catalog (`gradle/libs.versions.toml`), scan it with `library-insight`, and implement the grid component inside a new file `app/src/main/java/com/example/app/ComplexGridLayout.kt`."_
 
 **AI Agent Response Workflow:**
 
 1. **Version Catalog Inspection**: The AI Agent inspects `gradle/libs.versions.toml` or `build.gradle.kts` to locate the project's declared library coordinates or BOM references (e.g. `androidx.compose.foundation:foundation-layout` or `compose-bom = "2024.09.00"`).
    _(If not declared in the project, the agent runs `library-insight search-central "foundation-layout"` to query the latest release on Maven Central)._
-2. **Recommends & Executes Scan**: The agent recommends the exact command (`library-insight scan androidx.compose.foundation:foundation-layout:1.12.0` or `library-insight scan androidx.compose:compose-bom:2024.09.00`) and executes it immediately.
-3. **Explores & Explains**: Runs `library-insight explain Grid --deep` to verify `GridScope`, `GridConfigurationScope`, and parameter signatures for that specific version.
-4. **Generates Precise Code**: Delivers exact, version-matched Kotlin code tailored to the developer's project configuration!
+2. **Auto-Infers Options & Executes Scan**: The agent automatically infers missing parameters (such as adding `-i "foundation*"` or `-p android` for BOM coordinates) to avoid downloading unnecessary member libraries or platform variants, recommending and executing:
+   ```bash
+   library-insight scan androidx.compose:compose-bom:2024.09.00 -i "foundation*" -p android
+   ```
+3. **Mandatory Symbol Search & Explanation**: The agent FIRST executes `library-insight search Grid` to discover all matching symbols across indexed packages, followed by `library-insight explain Grid --deep` to verify `GridScope`, `GridConfigurationScope`, and parameter signatures for that specific version.
+4. **Writes Project File**: Automatically creates `app/src/main/java/com/example/app/ComplexGridLayout.kt` with 100% version-matched, working Kotlin code tailored to the developer's project configuration!

docs/cli/scanners.md

@@ -18,6 +18,7 @@ library-insight scan com.squareup.retrofit2:retrofit:2.11.0
 - `--db <file>`: Path to save the JSON index database (default: `build/library-insight-index.json`)
 - `-s, --sources <file>`: Path to sources JAR/AAR or source code folder to extract Javadoc/KDoc comments & guide examples
 - `-p, --platform <target>`: Target platform filter for BOM and KMP scans (`android`, `jvm`, `ios`, `desktop`, `all`). Defaults to `android`. Filters out non-target KMP variants (e.g. iOS/JS/Wasm), stubs, and lints.
+- `-i, --include <pattern>`: Filter BOM managed dependencies by wildcard pattern (e.g. `-i "compose-ui*"`, `-i "*animation*"`). Multiple allowed.
 - `--repo <url>`: Additional Maven repository URL to download coordinates (multiple allowed)
 - `--lib-name <name>`: Override the library name in the generated index
 - `--lib-version <version>`: Override the version tag in the generated index

docs/getting-started.md

@@ -74,9 +74,9 @@ Here is how developers and AI coding agents use Library Insight step-by-step:
 - **Scan a Bill of Materials (BOM):**
 
   ```bash
-  library-insight scan androidx.compose:compose-bom:2024.09.00
+  library-insight scan androidx.compose:compose-bom:2024.09.00 -i "compose-ui*"
   ```
-  *(Filters out non-Android/non-JVM KMP targets like iOS, JS, Wasm, stubs, and lints by default. Use `--platform all` to scan all 200+ variants).*
+  *(Filters out non-Android KMP targets by default. Use `-i, --include <pattern>` to selectively target specific BOM member artifacts like `-i "compose-ui*"` or `-i "*animation*"`).*
 
 - **Scan Local Source Code:**
 
@@ -131,7 +131,7 @@ Here is how developers and AI coding agents use Library Insight step-by-step:
    ```bash
    library-insight mcp
    ```
-   _(Integrates natively with Cursor, Windsurf, or Claude Desktop)._
+   _(Integrates natively with Android Studio Gemini, Codex, Cursor, Windsurf, or Claude Desktop)._
 
 ---