Add config layering system with user and project defaults

docs/cli-reference.md

@@ -9,7 +9,7 @@ The `structkit` CLI allows you to generate project structures from YAML configur
 **Basic Usage:**
 
 ```sh
-structkit {info,validate,generate,explain,vars,graph,list,sources,generate-schema,mcp,completion,init} ...
+structkit {info,validate,generate,explain,vars,graph,list,sources,generate-schema,mcp,config,completion,init} ...
 ```
 
 ## Global Options
@@ -308,6 +308,60 @@ structkit completion install [bash|zsh|fish]
 - If no shell is provided, the command attempts to auto-detect your current shell and prints the exact commands to generate and install static completion files via shtab.
 - This does not modify your shell configuration; it only prints the commands you can copy-paste.
 
+### `config`
+
+Display and manage structkit configuration.
+
+**Usage:**
+
+```sh
+structkit config print [--format {yaml,json}] [-c CONFIG_FILE]
+```
+
+**Subcommands:**
+
+- `print`: Display the effective configuration after all layers are merged.
+
+**Arguments:**
+
+- `--format {yaml,json}`: Output format (default: yaml).
+- `-c CONFIG_FILE, --config-file CONFIG_FILE`: Path to a project configuration file.
+
+**Description:**
+
+The `config print` command shows the final merged configuration from all layers:
+
+1. Built-in defaults (lowest priority)
+2. User config (`~/.config/struct/config.yaml`)
+3. Project config (`.struct.yaml` or `--config-file`)
+4. CLI arguments (highest priority)
+
+The command also displays which configuration sources were loaded.
+
+**Examples:**
+
+View effective configuration:
+```sh
+structkit config print
+```
+
+View with project config:
+```sh
+structkit config print -c my-project-config.yaml
+```
+
+Output in JSON format:
+```sh
+structkit config print --format json
+```
+
+Override with CLI arguments:
+```sh
+structkit config print --log DEBUG -c config.yaml
+```
+
+See the [Configuration](configuration.md) documentation for more details on config layering.
+
 ### `init`
 
 Initialize a basic .struct.yaml in the target directory.

docs/configuration.md

@@ -1,6 +1,90 @@
-# YAML Configuration
+# Configuration
 
-## Configuration Properties
+## Config Layering
+
+Structkit supports a layered configuration system that allows you to set defaults at multiple levels. Configuration values are merged in the following order (from lowest to highest priority):
+
+1. **Built-in defaults** - Hard-coded defaults that are always present
+2. **User config** - Global defaults from `~/.config/struct/config.yaml`
+3. **Project config** - Project-specific config from `.struct.yaml` or `--config-file`
+4. **CLI arguments** - Command-line flags (highest priority)
+
+### User Config
+
+You can create a user-level config file at `~/.config/struct/config.yaml` to set your personal defaults. This is useful for setting preferences that apply across all your projects.
+
+Example `~/.config/struct/config.yaml`:
+
+```yaml
+structures_path: ~/my-custom-structures
+input_store: ~/.cache/structkit/input.json
+file_strategy: backup
+log: WARNING
+```
+
+### Project Config
+
+Project-specific settings can be defined in a `.struct.yaml` file or specified via the `--config-file` flag. These settings override user config and built-in defaults.
+
+### CLI Arguments
+
+Command-line arguments always take the highest priority and override all config file settings.
+
+### Supported Config Options
+
+The following options can be configured via config files:
+
+- `structures_path` - Path to custom structure definitions
+- `source` - Named source for structure definitions
+- `input_store` - Path to the input store file
+- `file_strategy` - Strategy for handling existing files (`overwrite`, `skip`, `append`, `rename`, `backup`)
+- `backup` - Path to backup folder
+- `global_system_prompt` - Global system prompt for OpenAI
+- `non_interactive` - Run in non-interactive mode (boolean)
+- `output` - Output mode (`file` or `console`)
+- `log` - Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
+- `log_file` - Path to log file
+
+### Viewing Effective Configuration
+
+To see the final merged configuration that structkit will use, run:
+
+```bash
+structkit config print
+```
+
+This displays the effective configuration after all layers have been merged. You can also output in JSON format:
+
+```bash
+structkit config print --format json
+```
+
+Example output:
+
+```yaml
+backup: null
+file_strategy: backup
+global_system_prompt: null
+input_store: /tmp/structkit/input.json
+log: INFO
+log_file: null
+non_interactive: false
+output: file
+source: null
+structures_path: /home/user/my-structures
+```
+
+The command also displays which configuration sources were used:
+
+```
+Configuration sources:
+  1. Built-in defaults: always loaded
+  2. User config: /home/user/.config/struct/config.yaml (exists)
+  3. Project config: .struct.yaml
+  4. CLI arguments: highest priority
+```
+
+## YAML Configuration Properties
 
 When defining your project structure in the YAML configuration file, you can use various properties to control the behavior of the script. Here are the available properties:
 

examples/config-layering/README.md

@@ -0,0 +1,159 @@
+# Config Layering Example
+
+This example demonstrates how to use structkit's config layering system to set defaults at multiple levels.
+
+## Overview
+
+Structkit supports configuration at four levels (from lowest to highest priority):
+
+1. **Built-in defaults** - Hard-coded baseline values
+2. **User config** - Global defaults from `~/.config/struct/config.yaml`
+3. **Project config** - Project-specific config from `.struct.yaml` or `--config-file`
+4. **CLI arguments** - Command-line flags (highest priority)
+
+## Setup
+
+### 1. Create a User Config
+
+Set your personal global defaults:
+
+```bash
+mkdir -p ~/.config/struct
+cat > ~/.config/struct/config.yaml << 'EOF'
+# Personal defaults that apply to all projects
+file_strategy: backup
+input_store: ~/.cache/structkit/input.json
+log: WARNING
+EOF
+```
+
+### 2. Create a Project Config
+
+Create a project-specific config file:
+
+```bash
+cat > project-config.yaml << 'EOF'
+# Project-specific overrides
+file_strategy: skip
+structures_path: ./custom-structures
+backup: ./backups
+EOF
+```
+
+## Usage
+
+### View Effective Configuration
+
+Display the merged configuration after all layers are applied:
+
+```bash
+# View with user config only
+structkit config print
+
+# View with project config override
+structkit config print -c project-config.yaml
+
+# View in JSON format
+structkit config print --format json
+
+# Override with CLI args
+structkit config print -c project-config.yaml --log DEBUG
+```
+
+### Example Output
+
+With user config only:
+```yaml
+file_strategy: backup
+input_store: /home/user/.cache/structkit/input.json
+log: WARNING
+non_interactive: false
+output: file
+
+Configuration sources:
+  1. Built-in defaults: always loaded
+  2. User config: /home/user/.config/struct/config.yaml (exists)
+  3. Project config: none specified
+  4. CLI arguments: highest priority
+```
+
+With project config override:
+```yaml
+backup: ./backups
+file_strategy: skip
+input_store: /home/user/.cache/structkit/input.json
+log: WARNING
+non_interactive: false
+output: file
+structures_path: ./custom-structures
+
+Configuration sources:
+  1. Built-in defaults: always loaded
+  2. User config: /home/user/.config/struct/config.yaml (exists)
+  3. Project config: project-config.yaml
+  4. CLI arguments: highest priority
+```
+
+Notice how:
+- `file_strategy` changed from `backup` (user config) to `skip` (project config)
+- `input_store` remained from user config (not overridden by project)
+- `structures_path` and `backup` are new from project config
+
+## Supported Config Options
+
+The following options can be set in config files:
+
+- `structures_path` - Path to custom structure definitions
+- `source` - Named source for structure definitions
+- `input_store` - Path to the input store file
+- `file_strategy` - Strategy for handling existing files (`overwrite`, `skip`, `append`, `rename`, `backup`)
+- `backup` - Path to backup folder
+- `global_system_prompt` - Global system prompt for OpenAI
+- `non_interactive` - Run in non-interactive mode (boolean)
+- `output` - Output mode (`file` or `console`)
+- `log` - Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
+- `log_file` - Path to log file
+
+## Precedence Rules
+
+When the same option is set at multiple levels:
+
+1. CLI arguments always win
+2. Project config overrides user config
+3. User config overrides built-in defaults
+4. Built-in defaults are always present
+
+## Common Use Cases
+
+### Personal Backup Strategy
+
+Set your preferred file strategy globally:
+```yaml
+# ~/.config/struct/config.yaml
+file_strategy: backup
+backup: ~/structkit-backups
+```
+
+### Team Project Standards
+
+Share project-specific settings in version control:
+```yaml
+# .struct.yaml (checked into git)
+structures_path: ./team-structures
+input_store: ./.structkit/input.json
+non_interactive: true
+```
+
+### Temporary Overrides
+
+Override for a single command:
+```bash
+structkit generate --file-strategy overwrite --log DEBUG
+```
+
+## Tips
+
+1. Use user config for personal preferences that apply to all projects
+2. Use project config for team standards and project-specific paths
+3. Use CLI args for one-off overrides during development
+4. Run `structkit config print` to debug configuration issues

examples/config-layering/project-config-example.yaml

@@ -0,0 +1,19 @@
+# Example project config file
+#
+# This file can be checked into version control to share project-specific
+# settings with your team. Use with --config-file or as .struct.yaml
+
+# Project-specific structures location
+structures_path: ./custom-structures
+
+# Project-specific input store
+input_store: ./.structkit/input.json
+
+# File strategy for this project
+file_strategy: skip
+
+# Backup location for this project
+backup: ./backups
+
+# Run in non-interactive mode for CI/CD
+non_interactive: true

examples/config-layering/user-config-example.yaml

@@ -0,0 +1,28 @@
+# Example user config file for ~/.config/struct/config.yaml
+#
+# This file contains personal defaults that apply to all your structkit projects.
+# Copy this to ~/.config/struct/config.yaml and customize as needed.
+
+# Default file handling strategy
+# Options: overwrite, skip, append, rename, backup
+file_strategy: backup
+
+# Where to store user input history
+input_store: ~/.cache/structkit/input.json
+
+# Default logging level
+# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+log: WARNING
+
+# Path to custom structure definitions
+# structures_path: ~/my-structures
+
+# Run in non-interactive mode by default
+# non_interactive: false
+
+# Default output mode
+# Options: file, console
+# output: file
+
+# Default backup directory
+# backup: ~/structkit-backups