Add explain command to preview structure resolution

README.md

@@ -19,6 +19,7 @@
 - **🛡️ Smart File Handling** - Multiple strategies for managing existing files (overwrite, skip, backup, etc.)
 - **🪝 Automation Hooks** - Pre and post-generation shell commands
 - **🎯 Dry Run Mode** - Preview changes before applying them
+- **🔎 Structure Explanations** - Inspect nested structures, variables, hooks, remote references, and conflict behavior before generation
 - **✅ Validation & Schema** - Built-in YAML validation and IDE support
 - **🤖 MCP Integration** - Model Context Protocol support for AI-assisted development workflows
 
@@ -73,6 +74,9 @@ docker run -v $(pwd):/workdir ghcr.io/httpdss/structkit:main generate my-config.
 ### Basic Usage
 
 ```bash
+# Explain a Terraform module structure without writing files
+structkit explain terraform/modules/generic
+
 # Generate a Terraform module structure
 structkit generate terraform-module ./my-terraform-module
 

docs/cli-reference.md

@@ -9,7 +9,7 @@ The `struct` CLI allows you to generate project structures from YAML configurati
 **Basic Usage:**
 
 ```sh
-structkit {info,validate,generate,list,generate-schema,mcp,completion,init} ...
+structkit {info,validate,generate,explain,vars,list,generate-schema,mcp,completion,init} ...
 ```
 
 ## Global Options
@@ -115,6 +115,61 @@ structkit generate
 - `--mappings-file MAPPINGS_FILE`: Path to a YAML file containing mappings to be used in templates (can be specified multiple times).
 - `-o {console,file}, --output {console,file}`: Output mode.
 
+### `explain`
+
+Explain how a structure definition resolves before generation. This is structure-focused: it lists the files and folders that would be generated, nested structures referenced by `folders[].struct`, remote file references, declared variables and resolved values, hooks that would be present, and the configured conflict behavior. It does not create files or folders, fetch remote content, generate prompt-based content, or execute hooks.
+
+Use `generate --dry-run` when you want a generation-style preview of file operations and diffs. Use `explain` when you want to inspect the structure graph and metadata before any generation work happens.
+
+**Usage:**
+
+```sh
+structkit explain [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [-v VARS] [--json] [-o {text,json}] [-f {overwrite,skip,append,rename,backup}] [--mappings-file MAPPINGS_FILE] [structure_definition] [base_path]
+```
+
+**Arguments:**
+
+- `structure_definition` (optional): Built-in structure name or path to a YAML structure file (default: `.struct.yaml`).
+- `base_path` (optional): Base path used to resolve generated paths (default: `.`).
+- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions.
+- `-v VARS, --vars VARS`: Template variables in the format KEY1=value1,KEY2=value2; shown in the explanation with resolved defaults.
+- `--json`: Output the explanation as JSON.
+- `-o {text,json}, --output {text,json}`: Output format (default: `text`).
+- `-f {overwrite,skip,append,rename,backup}, --file-strategy {overwrite,skip,append,rename,backup}`: File conflict strategy to explain.
+- `--mappings-file MAPPINGS_FILE`: Path to a YAML mappings file for resolving `with` values and templates (can be specified multiple times).
+
+**Examples:**
+
+```sh
+structkit explain terraform/modules/generic
+structkit explain ./my-struct.yaml --vars project_name=demo
+structkit explain project/python --json
+```
+
+### `vars`
+
+Inspect variables declared by a structure definition without generating files.
+
+**Usage:**
+
+```sh
+structkit vars [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [--json] structure_definition
+```
+
+**Arguments:**
+
+- `structure_definition`: Built-in structure name, custom structure name, or local YAML file path. Local `.yaml` and `.yml` files can be passed directly, or with `file://`.
+- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to custom structure definitions. Can be set via the `STRUCTKIT_STRUCTURES_PATH` environment variable.
+- `--json`: Print machine-readable JSON with each variable's name, type, default value, description/help text, and required status.
+
+Examples:
+
+```sh
+structkit vars project/python
+structkit vars ./my-struct.yaml --json
+structkit vars python-basic --structures-path ~/custom-structures
+```
+
 ### `list`
 
 List available structures.
@@ -214,6 +269,16 @@ Pass template variables to the structure:
 structkit generate -v "project_name=MyApp,author=John Doe" file://structure.yaml ./output
 ```
 
+### Explaining Structure Resolution
+
+Preview the structure graph, variables, hooks, remote file references, and conflict behavior without writing files or executing hooks:
+
+```sh
+structkit explain project/python --json
+```
+
+`explain` is different from `generate --dry-run`: `explain` focuses on resolving and describing the structure definition, while `generate --dry-run` follows the generation path to preview file operations.
+
 ### Dry Run
 
 Test structure generation without creating files:

docs/mcp-integration.md

@@ -69,7 +69,57 @@ Generate a project structure using specified definition and options.
 - `mappings` (optional): Variable mappings for template substitution
 - `structures_path` (optional): Custom path to structure definitions
 
-### 4. validate_structure
+### 4. get_structure_vars
+Inspect variables declared by a specific structure without generating files.
+
+```json
+{
+  "name": "get_structure_vars",
+  "arguments": {
+    "structure_name": "project/python",
+    "structures_path": "/path/to/custom/structures",  // optional
+    "output": "json"  // "text" or "json", optional
+  }
+}
+```
+
+**Parameters:**
+- `structure_name` (required): Name or local YAML path of the structure to inspect
+- `structures_path` (optional): Custom path to structure definitions
+- `output` (optional): Output format - "text" for aligned human-readable output or "json" for machine-readable output (default: "text")
+
+### 5. explain_structure
+Explain how a structure resolves without creating files, fetching remote content, generating prompt-based content, or executing hooks. This is useful when an AI assistant needs to inspect the structure graph before deciding whether to generate it.
+
+```json
+{
+  "name": "explain_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/myproject",
+    "output": "json",
+    "variables": {
+      "project_name": "MyProject"
+    },
+    "mappings": {
+      "team": "platform"
+    },
+    "file_strategy": "overwrite",
+    "structures_path": "/path/to/custom/structures"
+  }
+}
+```
+
+**Parameters:**
+- `structure_definition` (required): Name or path to the structure definition
+- `base_path` (optional): Base path used to resolve generated paths (default: `.`)
+- `output` (optional): Output mode - `"text"` or `"json"` (default: `"text"`)
+- `variables` (optional): Template variables to resolve structure names, paths, hooks, and nested `with` values
+- `mappings` (optional): Additional mappings exposed to templates as `mappings`
+- `file_strategy` (optional): Conflict strategy to explain: `overwrite`, `skip`, `append`, `rename`, or `backup` (default: `overwrite`)
+- `structures_path` (optional): Custom path to structure definitions
+
+### 6. validate_structure
 Validate a structure configuration YAML file.
 
 ```json
@@ -204,6 +254,12 @@ async def main():
             # FastMCP tools return plain text content
             print(result.content[0].text)
 
+            explanation = await session.call_tool("explain_structure", {
+                "structure_definition": "project/python",
+                "output": "json"
+            })
+            print(explanation.content[0].text)
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```
@@ -225,8 +281,9 @@ The MCP tools can be chained together for complex workflows:
 
 1. List available structures
 2. Get detailed info about a specific structure
-3. Generate the structure with custom mappings
-4. Validate any custom configurations
+3. Explain the structure to preview files, folders, variables, hooks, and remote references
+4. Generate the structure with custom mappings
+5. Validate any custom configurations
 
 ### Integration Examples
 
@@ -265,6 +322,32 @@ The MCP tools can be chained together for complex workflows:
 }
 ```
 
+
+**Example 3: Explain Before Generate**
+```json
+// 1. Explain structure resolution without side effects
+{
+  "name": "explain_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/review",
+    "output": "json",
+    "variables": {
+      "project_name": "ReviewProject"
+    }
+  }
+}
+
+// 2. If the explanation looks correct, generate the structure
+{
+  "name": "generate_structure",
+  "arguments": {
+    "structure_definition": "project/python",
+    "base_path": "/tmp/review"
+  }
+}
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -353,6 +436,8 @@ Once connected, you can use these tools:
 - `list_structures` - Get all available structures
 - `get_structure_info` - Get details about a specific structure
 - `generate_structure` - Generate project structures
+- `get_structure_vars` - Inspect declared structure variables
+- `explain_structure` - Explain structure resolution without side effects
 - `validate_structure` - Validate YAML configuration files
 
 ## Troubleshooting

docs/usage.md

@@ -6,6 +6,7 @@ Run the script with the following command using one of the following subcommands
 - `generate-schema`: Generate JSON schema for available structure templates.
 - `validate`: Validate the YAML configuration file.
 - `info`: Display information about the script and its dependencies.
+- `vars`: Inspect variables declared by a structure definition without generating files.
 - `list`: List the available structs
 
 For more information, run the script with the `-h` or `--help` option (this is also available for each subcommand):
@@ -145,6 +146,19 @@ The file includes:
 - A README.md placeholder in files
 - A folders entry pointing to the github/workflows/run-structkit workflow at ./
 
+
+### Inspect Variables
+
+Use `structkit vars` to see the inputs a structure declares before running `generate`. The command supports built-in structures, custom structures via `--structures-path`, and local YAML files without creating any files.
+
+```sh
+structkit vars project/python
+structkit vars ./my-struct.yaml --json
+structkit vars python-basic --structures-path ~/custom-structures
+```
+
+Text output lists each variable's name, type, default value, description/help text, and whether it is required or optional. Use `--json` for CI and other machine-readable workflows.
+
 ### Validate Configuration
 
 ```sh