Add lint command for StructKit YAML definitions

docs/cli-reference.md

@@ -80,6 +80,43 @@ structkit validate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] yaml_file
 
 - `yaml_file`: Path to the YAML configuration file.
 
+### `lint`
+
+Lint one or more StructKit YAML definitions for quality checks that are stricter than syntactic validation. The command reports warnings and errors with file paths and context. It exits with status code `1` when one or more lint errors are found, and exits `0` when only warnings or no issues are found.
+
+**Usage:**
+
+```sh
+structkit lint [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH] [--all] [--json] [targets ...]
+```
+
+**Arguments:**
+
+- `targets`: YAML file paths, `file://` YAML URLs, or bundled/custom structure names. Multiple targets are supported.
+- `--all`: Lint all bundled contrib structures, plus custom structures when `--structures-path` is supplied.
+- `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to custom structure definitions.
+- `--json`: Print machine-readable JSON with a summary and issue list.
+
+**Lint rules:**
+
+- Missing top-level `description` (warning).
+- Variables referenced in StructKit templates but not declared (error).
+- Declared variables that are never referenced (warning).
+- Duplicate file or folder entries (error).
+- Unsafe hooks, such as destructive shell patterns (error), and suspicious hooks, such as `curl | bash`, `sudo`, `eval`, or `chmod 777` (warning).
+- GitHub remote URLs that do not appear pinned to a stable tag, release, or commit SHA (warning).
+- Invalid entry names that are absolute paths or escape with `..` (error), and unusual name characters (warning).
+
+**Examples:**
+
+```sh
+structkit lint .struct.yaml
+structkit lint structkit/contribs/project/python.yaml
+structkit lint project/python
+structkit lint --all
+structkit lint .struct.yaml --json
+```
+
 ### `generate`
 
 Generate the project structure.

docs/mcp-integration.md

@@ -84,6 +84,27 @@ Validate a structure configuration YAML file.
 **Parameters:**
 - `yaml_file` (required): Path to the YAML configuration file to validate
 
+### 5. lint_structure
+Lint one or more structure configuration YAML files for quality and safety issues.
+
+```json
+{
+  "name": "lint_structure",
+  "arguments": {
+    "targets": ["/path/to/structure.yaml"],
+    "structures_path": "/path/to/custom/structures",
+    "lint_all": false,
+    "json_output": true
+  }
+}
+```
+
+**Parameters:**
+- `targets` (optional): List of YAML file paths, `file://` URLs, or bundled/custom structure names to lint
+- `structures_path` (optional): Custom path to structure definitions
+- `lint_all` (optional): Lint all bundled structures, plus custom structures when `structures_path` is supplied (default: false)
+- `json_output` (optional): Return a JSON report with summary counts and issue details (default: false)
+
 ## Usage
 
 ### Starting the MCP Server (FastMCP stdio / http / sse)
@@ -227,6 +248,7 @@ The MCP tools can be chained together for complex workflows:
 2. Get detailed info about a specific structure
 3. Generate the structure with custom mappings
 4. Validate any custom configurations
+5. Lint custom or generated configurations before using them
 
 ### Integration Examples
 
@@ -265,6 +287,17 @@ The MCP tools can be chained together for complex workflows:
 }
 ```
 
+**Example 3: Lint Custom Structures**
+```json
+{
+  "name": "lint_structure",
+  "arguments": {
+    "targets": ["/path/to/custom-structure.yaml"],
+    "json_output": true
+  }
+}
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -354,6 +387,7 @@ Once connected, you can use these tools:
 - `get_structure_info` - Get details about a specific structure
 - `generate_structure` - Generate project structures
 - `validate_structure` - Validate YAML configuration files
+- `lint_structure` - Lint YAML configuration files for quality and safety issues
 
 ## Troubleshooting