Rename default project file from .struct.yaml to .structkit.yaml

.github/instructions/struct.instructions.md

@@ -6,9 +6,9 @@ applyTo: '**'
 
 ## Role
 
-You are an expert assistant that generates valid `.struct.yaml` files for the [StructKit tool](https://github.com/httpdss/structkit), which automates project structure generation from YAML configuration.
+You are an expert assistant that generates valid `.structkit.yaml` files for the [StructKit tool](https://github.com/httpdss/structkit), which automates project structure generation from YAML configuration.
 
-## Defining the `.struct.yaml` file
+## Defining the `.structkit.yaml` file
 
 this file has 3 main keys: `structures`, `folders`, and `variables`.
 

.github/prompts/struct.prompt.md

@@ -2,9 +2,9 @@
 
 ## Role
 
-You are an expert assistant that generates valid `.struct.yaml` files for the [StructKit tool](https://github.com/httpdss/structkit), which automates project structure generation from YAML configuration.
+You are an expert assistant that generates valid `.structkit.yaml` files for the [StructKit tool](https://github.com/httpdss/structkit), which automates project structure generation from YAML configuration.
 
-## Defining the `.struct.yaml` file
+## Defining the `.structkit.yaml` file
 
 this file has 3 main keys: `structures`, `folders`, and `variables`.
 

.github/workflows/struct-generate.yaml

@@ -4,10 +4,10 @@ on:
   workflow_call:
     inputs:
       struct_file:
-        description: 'Path to the StructKit file'
+        description: 'Path to the StructKit file. When omitted, uses .structkit.yaml, falling back to .struct.yaml.'
         type: string
         required: false
-        default: '.struct.yaml'
+        default: ''
       output_dir:
         description: 'Path to the output directory'
         type: string
@@ -101,6 +101,17 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.token }}
         run: |
+          STRUCT_FILE='${{ inputs.struct_file }}'
+          if [ -z "$STRUCT_FILE" ]; then
+            if [ -f .structkit.yaml ]; then
+              STRUCT_FILE=.structkit.yaml
+            elif [ -f .struct.yaml ]; then
+              STRUCT_FILE=.struct.yaml
+            else
+              STRUCT_FILE=.structkit.yaml
+            fi
+          fi
+
           if [ -d ./custom-structures ]; then
 
             structkit list \
@@ -110,15 +121,15 @@ jobs:
               --non-interactive \
               -s ./custom-structures/${{ inputs.custom_structure_path }} \
               ${{ inputs.args }} \
-              ${{ inputs.struct_file }} \
+              "$STRUCT_FILE" \
               ${{ inputs.output_dir }}
           else
             structkit list
 
             structkit generate \
               --non-interactive \
               ${{ inputs.args }} \
-              ${{ inputs.struct_file }} \
+              "$STRUCT_FILE" \
               ${{ inputs.output_dir }}
           fi
 

.vscode/settings.json

@@ -1,6 +1,11 @@
 {
   "yaml.schemas": {
-    "./.vscode/struct-plugins.schema.json": "*.struct.yaml"
+    "./.vscode/struct-plugins.schema.json": [
+      ".structkit.yaml",
+      ".struct.yaml",
+      "*.structkit.yaml",
+      "*.struct.yaml"
+    ]
   },
   "python.languageServer": "None"
 }

README.md

@@ -39,7 +39,7 @@ docker run --rm -v "$(pwd):/workdir" ghcr.io/httpdss/structkit:main \
 These are install paths for [StructKit](https://github.com/httpdss/structkit), not separate products. Star this repo.
 
 - [GitHub Action](https://github.com/httpdss/structkit-action) — validate, generate, or drift-check in CI
-- [VS Code / Cursor](https://github.com/httpdss/vscode-structkit) — schema and autocomplete for `.struct.yaml`
+- [VS Code / Cursor](https://github.com/httpdss/vscode-structkit) — schema and autocomplete for `.structkit.yaml`
 - [Agent skills](https://github.com/httpdss/structkit-skills) — inspect, preview, generate, validate from an assistant
 - [pre-commit](https://github.com/httpdss/structkit-pre-commit) — validate structures before they land
 - [Homebrew](https://github.com/httpdss/homebrew-structkit) — `brew tap httpdss/structkit && brew install structkit`

docker-compose.yaml

@@ -14,7 +14,7 @@ services:
       "--backup=/app/backup",
       "--file-strategy=rename",
       "--log-file=/app/logfile.log",
-      "/app/examples/python-cli/.struct.yaml",
+      "/app/examples/python-cli/.structkit.yaml",
       "/app/example_project"
     ]
   structkit-test:
@@ -31,6 +31,6 @@ services:
       "--backup=/app/backup",
       "--file-strategy=rename",
       "--log-file=/app/logfile.log",
-      "/app/examples/python-cli/.struct.yaml",
+      "/app/examples/python-cli/.structkit.yaml",
       "/app/example_project"
     ]

docs/agent-skills.md

@@ -10,7 +10,7 @@ The [`structkit-workflows`](https://github.com/httpdss/structkit-skills) skill c
 2. Inspect the selected structure and its variables.
 3. Preview or dry-run the generation before writing files.
 4. Use conservative file-conflict behavior for existing repositories.
-5. Validate `.struct.yaml` files and generated output.
+5. Validate `.structkit.yaml` files and generated output.
 
 This is useful when you want an assistant to scaffold from approved StructKit templates instead of inventing project structure from scratch.
 
@@ -33,7 +33,7 @@ hermes skills install https://raw.githubusercontent.com/httpdss/structkit-skills
 Use the skill when an agent needs to:
 
 - Generate a project, Terraform module, CI baseline, documentation bundle, or application scaffold with StructKit.
-- Author or update reusable `.struct.yaml` structures.
+- Author or update reusable `.structkit.yaml` structures.
 - Review a StructKit generation plan before files are written.
 - Package StructKit-backed workflows for repeatable use across repositories.
 

docs/cli-reference.md

@@ -108,10 +108,10 @@ structkit lint [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_PATH]
 Examples:
 
 ```sh
-structkit lint .struct.yaml
+structkit lint .structkit.yaml
 structkit lint structkit/contribs/project/python.yaml
 structkit lint --all
-structkit lint .struct.yaml --json
+structkit lint .structkit.yaml --json
 ```
 
 ### `generate`
@@ -125,7 +125,7 @@ structkit generate [-h] [-l LOG] [-c CONFIG_FILE] [-i LOG_FILE] [-s STRUCTURES_P
 ```
 
 Defaults when omitted:
-- structure_definition -> .struct.yaml
+- structure_definition -> `.structkit.yaml` (falls back to `.struct.yaml` if the canonical file is missing)
 - base_path -> .
 
 Example:
@@ -135,7 +135,7 @@ structkit generate
 
 **Arguments:**
 
-- `structure_definition` (optional): Path to the YAML configuration file (default: `.struct.yaml`).
+- `structure_definition` (optional): Path to the YAML configuration file (default: `.structkit.yaml`, with a fallback to `.struct.yaml`).
 - `base_path` (optional): Base path where the structure will be created (default: `.`).
 - `-s STRUCTURES_PATH, --structures-path STRUCTURES_PATH`: Path to structure definitions. Can be set via the `STRUCTKIT_STRUCTURES_PATH` environment variable. When using the environment variable (and no explicit CLI flag), an info-level log message will be emitted indicating which path is being used. Takes precedence over named sources.
 - `--source SOURCE`: Named source to use when resolving structure definitions. You can also use `<source>/<structure>` as the structure definition.
@@ -333,7 +333,7 @@ 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`)
+3. Project config (`.structkit.yaml`, legacy `.struct.yaml`, or `--config-file`)
 4. CLI arguments (highest priority)
 
 The command also displays which configuration sources were loaded.
@@ -364,26 +364,26 @@ See the [Configuration](configuration.md) documentation for more details on conf
 
 ### `init`
 
-Initialize a basic .struct.yaml in the target directory.
+Initialize a basic .structkit.yaml in the target directory.
 
 Usage:
 
 ```sh
 structkit init [path]
 ```
 
-- Creates a .struct.yaml if it does not exist.
+- Creates a .structkit.yaml if it does not exist.
 - Includes:
   - pre_hooks/post_hooks with echo commands
   - files with a README.md placeholder
   - folders referencing github/workflows/run-structkit at ./
-- Non-destructive: if .struct.yaml already exists, it is not overwritten and a message is printed.
+- Non-destructive: if `.structkit.yaml` or a legacy `.struct.yaml` already exists, it is not overwritten and a message is printed.
 
 ## Examples
 
 ### Using Defaults
 
-Generate with default structure (.struct.yaml) into current directory:
+Generate with default structure (.structkit.yaml) into current directory:
 
 ```sh
 structkit generate

docs/configuration.md

@@ -6,7 +6,7 @@ Structkit supports a layered configuration system that allows you to set default
 
 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`
+3. **Project config** - Project-specific config from `.structkit.yaml` (legacy `.struct.yaml`) or `--config-file`
 4. **CLI arguments** - Command-line flags (highest priority)
 
 ### User Config
@@ -24,7 +24,7 @@ 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.
+Project-specific settings can be defined in a `.structkit.yaml` file or specified via the `--config-file` flag. These settings override user config and built-in defaults. A legacy `.struct.yaml` file is still accepted when `.structkit.yaml` is not present.
 
 ### CLI Arguments
 
@@ -80,7 +80,7 @@ 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
+  3. Project config: .structkit.yaml
   4. CLI arguments: highest priority
 ```
 

docs/custom-structures.md

@@ -2,7 +2,7 @@
 
 Let's say you are happy with the default structures that StructKit provides, but you want to customize them for your specific needs. This is totally possible!
 
-The best way to approach this is to have a repository where you can store your custom structures. You can then reference these structures in your `.struct.yaml` files.
+The best way to approach this is to have a repository where you can store your custom structures. You can then reference these structures in your `.structkit.yaml` files.
 
 ## Suggested Repository Structure
 
@@ -18,7 +18,7 @@ structures/
 │   └── structure2.yaml
 ```
 
-This way you could reference your custom structures in your `.struct.yaml` files like this:
+This way you could reference your custom structures in your `.structkit.yaml` files like this:
 
 ```yaml
 folders:
@@ -33,7 +33,7 @@ folders:
 For this to work, you will need to set the path to the custom structures repository using the `-s` option when running StructKit:
 
 ```sh
-structkit generate -s ~/path/to/custom-structures/structures file://.struct.yaml ./output
+structkit generate -s ~/path/to/custom-structures/structures file://.structkit.yaml ./output
 ```
 
 ## Named custom sources
@@ -64,7 +64,7 @@ Git-backed sources are cloned into `$XDG_CACHE_HOME/structkit/sources` or `~/.ca
 
 ## File-local sources
 
-Committed `.struct.yaml` files can declare their own named sources. This keeps generation portable and protects existing files from changes to a user's global `structkit sources` configuration.
+Committed `.structkit.yaml` files can declare their own named sources. This keeps generation portable and protects existing files from changes to a user's global `structkit sources` configuration. Legacy `.struct.yaml` files are still read when `.structkit.yaml` is not present.
 
 ```yaml
 sources:
@@ -104,7 +104,7 @@ folders:
       struct: github://httpdss/platform-structures@v1.2.0/structures/python/service
 ```
 
-For reproducible `.struct.yaml` files, prefer tags or commit SHAs over mutable branches.
+For reproducible `.structkit.yaml` files, prefer tags or commit SHAs over mutable branches.
 
 Use a source explicitly with `--source`:
 

docs/examples/index.md

@@ -6,11 +6,11 @@ StructKit's polished examples live in the repository-level [`examples/`](../../e
 
 | Example | Use case | Source |
 |---|---|---|
-| Python CLI | Small Python command-line tool with tests and package metadata | [`examples/python-cli/.struct.yaml`](../../examples/python-cli/.struct.yaml) |
-| FastAPI service | API service with tests, Dockerfile, and environment example | [`examples/fastapi-service/.struct.yaml`](../../examples/fastapi-service/.struct.yaml) |
-| Terraform module | Reusable infrastructure module skeleton | [`examples/terraform-module/.struct.yaml`](../../examples/terraform-module/.struct.yaml) |
-| GitHub Actions CI baseline | Standard Python CI workflow and pre-commit setup | [`examples/github-actions-ci/.struct.yaml`](../../examples/github-actions-ci/.struct.yaml) |
-| AI agent / MCP scaffold | Agent-friendly repository structure and instructions | [`examples/ai-agent-mcp/.struct.yaml`](../../examples/ai-agent-mcp/.struct.yaml) |
+| Python CLI | Small Python command-line tool with tests and package metadata | [`examples/python-cli/.structkit.yaml`](../../examples/python-cli/.structkit.yaml) |
+| FastAPI service | API service with tests, Dockerfile, and environment example | [`examples/fastapi-service/.structkit.yaml`](../../examples/fastapi-service/.structkit.yaml) |
+| Terraform module | Reusable infrastructure module skeleton | [`examples/terraform-module/.structkit.yaml`](../../examples/terraform-module/.structkit.yaml) |
+| GitHub Actions CI baseline | Standard Python CI workflow and pre-commit setup | [`examples/github-actions-ci/.structkit.yaml`](../../examples/github-actions-ci/.structkit.yaml) |
+| AI agent / MCP scaffold | Agent-friendly repository structure and instructions | [`examples/ai-agent-mcp/.structkit.yaml`](../../examples/ai-agent-mcp/.structkit.yaml) |
 
 Start with the [examples index](../../examples/README.md) for copy-paste commands, expected output, and customization notes.
 
@@ -19,7 +19,7 @@ Start with the [examples index](../../examples/README.md) for copy-paste command
 Every example can be previewed with `--dry-run --diff`:
 
 ```bash
-structkit generate --vars "project_name=DemoCLI,package_name=demo_cli,cli_command=demo-cli,description=A small Python CLI generated by StructKit." examples/python-cli/.struct.yaml /tmp/structkit-python-cli-demo --dry-run --diff
+structkit generate --vars "project_name=DemoCLI,package_name=demo_cli,cli_command=demo-cli,description=A small Python CLI generated by StructKit." examples/python-cli/.structkit.yaml /tmp/structkit-python-cli-demo --dry-run --diff
 ```
 
 Then remove `--dry-run --diff` when you're ready to write files.

docs/github-integration.md

@@ -21,6 +21,8 @@ jobs:
       token: ${{ secrets.STRUCT_RUN_TOKEN }}
 ```
 
+When `struct_file` is omitted, the workflow uses `.structkit.yaml` if present and falls back to a legacy `.struct.yaml`.
+
 ## Best Practices
 
 1. **Secure Your Token**: Store GitHub tokens in secrets management tools.

docs/hooks.md

@@ -187,11 +187,11 @@ You can disable hooks entirely using the `--no-hooks` flag or environment variab
 
 ```bash
 # Using CLI flag
-structkit generate .struct.yaml --no-hooks
+structkit generate .structkit.yaml --no-hooks
 
 # Using environment variable
 export STRUCTKIT_NO_HOOKS=true
-structkit generate .struct.yaml
+structkit generate .structkit.yaml
 ```
 
 This is recommended for:
@@ -204,7 +204,7 @@ This is recommended for:
 By default, StructKit prompts for confirmation before running hooks in interactive mode:
 
 ```bash
-$ structkit generate .struct.yaml
+$ structkit generate .structkit.yaml
 
 ⚠️  The following pre-hooks will be executed:
   - echo "Preparing environment..."
@@ -243,11 +243,11 @@ When an allowlist exists:
 You can also specify a custom allowlist path:
 
 ```bash
-structkit generate .struct.yaml --hooks-allowlist /path/to/allowlist.txt
+structkit generate .structkit.yaml --hooks-allowlist /path/to/allowlist.txt
 
 # Or via environment variable
 export STRUCTKIT_HOOKS_ALLOWLIST=/path/to/allowlist.txt
-structkit generate .struct.yaml
+structkit generate .structkit.yaml
 ```
 
 ### MCP Integration Safety
@@ -301,7 +301,7 @@ post_hooks:
 ### Safe Hook Example with Allowlist
 
 ```yaml
-# .struct.yaml
+# .structkit.yaml
 pre_hooks:
   - echo "Preparing environment..."
   - python -c "import sys; print(sys.version)"

docs/installation.md

@@ -25,7 +25,7 @@ Clone the repository and install locally. See the [Development](development.md)
 Run StructKit without installing, using Docker:
 
 ```sh
-docker run -v $(pwd):/workdir -u $(id -u):$(id -g) ghcr.io/httpdss/structkit:main generate file:///workdir/examples/python-cli/.struct.yaml /workdir/example_output
+docker run -v $(pwd):/workdir -u $(id -u):$(id -g) ghcr.io/httpdss/structkit:main generate file:///workdir/examples/python-cli/.structkit.yaml /workdir/example_output
 ```
 
 Refer to the [Quick Start](quickstart.md) guide for more options.

docs/mcp-integration.md

@@ -113,7 +113,7 @@ Lint one or more structure YAML files or structure names for quality and safety
 {
   "name": "lint_structure",
   "arguments": {
-    "targets": ["project/python", "/path/to/.struct.yaml"],
+    "targets": ["project/python", "/path/to/.structkit.yaml"],
     "structures_path": "/path/to/custom/structures",
     "lint_all": false,
     "output": "json"