ci-sourcerer · Nov 5, 2026 · Nov 3, 2026 · Nov 5, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/.github/workflows/stacksmith-gitops-opinionated-reusable.yml b/.github/workflows/stacksmith-gitops-opinionated-reusable.yml
@@ -23,7 +23,7 @@ on:
         type: string
         default: ""
       discovery_mode:
-        description: "Discovery mode. Supported values: auto (default), folders, flat-files, or env-files."
+        description: "Discovery mode. Supported values: auto (default), single, folders, or env-files."
         required: false
         type: string
         default: auto

diff --git a/docs/guides/advanced-authoring.md b/docs/guides/advanced-authoring.md
@@ -410,8 +410,8 @@ When `--config` points at one or more managed config layers, Stacksmith discover
 
 ```shell
 stacksmith test \
-  --config examples/shared-config-repo/stacksmith-base-config.yaml \
-  --config examples/shared-config-repo/stacksmith-config.yaml
+  --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-base-config.yaml \
+  --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-config.yaml
 ```
 
 ```shell
@@ -426,8 +426,8 @@ Use `--dump-tests` when you want to inspect the generated pytest code.
 
 ```shell
 stacksmith test \
-  --config examples/shared-config-repo/stacksmith-base-config.yaml \
-  --config examples/shared-config-repo/stacksmith-config.yaml \
+  --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-base-config.yaml \
+  --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-config.yaml \
   --dump-tests /tmp/stacksmith-generated-tests.py
 ```
 

diff --git a/docs/guides/execution.md b/docs/guides/execution.md
@@ -220,9 +220,9 @@ Use `info graph` to inspect the discovered dependency graph and the execution th
 
 ```bash
 stacksmith info graph \
-  --root examples/gitops-simple-repo \
-  --runfile examples/gitops-simple-repo/common/stacksmith.yaml \
-  --runfile examples/gitops-simple-repo/environments/dev.yaml
+  --root tests/fixtures/authoring-examples/gitops-simple-repo \
+  --runfile tests/fixtures/authoring-examples/gitops-simple-repo/common/stacksmith.yaml \
+  --runfile tests/fixtures/authoring-examples/gitops-simple-repo/environments/dev.yaml
 ```
 
 The default table view includes stack paths, dependency edges, state keys, selected components, mock-output usage, build directories, logical Terragrunt commands, and the computed order. Use `--action destroy` to preview the reversed destruction order. Stack filters (`--include-tag` and `--exclude-tag`) and component selectors (`--tag` and `--tag-expr`) use the same semantics as `run-all`.
@@ -233,9 +233,9 @@ Use `run-all --dry-run` to perform the same discovery, input resolution, static
 
 ```bash
 stacksmith run-all plan \
-  --root examples/gitops-simple-repo \
-  --runfile examples/gitops-simple-repo/common/stacksmith.yaml \
-  --runfile examples/gitops-simple-repo/environments/dev.yaml \
+  --root tests/fixtures/authoring-examples/gitops-simple-repo \
+  --runfile tests/fixtures/authoring-examples/gitops-simple-repo/common/stacksmith.yaml \
+  --runfile tests/fixtures/authoring-examples/gitops-simple-repo/environments/dev.yaml \
   --tag-expr "component_name == 'first'" \
   --dry-run \
   --format json

diff --git a/docs/guides/repository-layouts.md b/docs/guides/repository-layouts.md
@@ -0,0 +1,15 @@
+# Repository layouts
+
+Repository ownership and deployment layout are separate choices. Application teams can own stacks while platform teams own managed configuration and modules in another repository.
+
+| Layout | Identifier | Choose it when |
+| --- | --- | --- |
+| Single deployment | `single` | One deployment lives at the root with `stacksmith.yaml` or `stack.yaml`. |
+| Environment files | `env-files` | Shared inputs live in `common/stacksmith.yaml` and small overrides in `environments/dev.yaml`. |
+| Environment directories | `folders` | Each environment needs its own runfile and assets under `environments/dev/`. |
+
+Use `auto` to detect the layout. Mixing environment files and environment runfile directories requires an explicit mode or reorganizing the root. Shared runfiles do not count as a competing single deployment. Single deployments use `default` as their target identity.
+
+Start with the local examples in `examples/quickstart`, then compare `examples/environment-files` and `examples/environment-directories`. They use the same workload. Shared changes affect all environments; environment-specific changes select their target. Unknown changed paths conservatively select every environment.
+
+A monorepo can contain several ordinary deployment roots; this does not require another layout. Platform currently configures one root per repository. Local examples use local state; configure durable remote state before CI execution.
diff --git a/docs/integrations/ci.md b/docs/integrations/ci.md
@@ -25,7 +25,7 @@ The deployment CI selector is named `command` in GitHub Actions and `COMMAND` in
 
 - GitHub Actions `workflow_dispatch` can run all environments, or a comma-delimited subset with `environments`.
 - `plan-operation` previews native operations without approval or execution; `apply-operation` previews, requests approval, and executes them. Supply a comma-delimited `operation_names` input such as `publish_image,deploy_app,smoke_test`, or leave it empty to select all operations in each stack. Set the repository, organization, job, or folder variable `STACKSMITH_MAX_PARALLEL_OPERATIONS` to cap concurrency and `STACKSMITH_FORCE_RERUN=1` to force replacement of selected operation runner resources when their execution identities have not changed.
-- `discovery_mode` selects how environments are discovered. Use `folders` for `environments/<env>/` directories, `flat-files` for root-level `stacksmith.<env>.yaml|yml|json` files, or `env-files` for the hybrid `environments/<env>.yaml` layout. The aliases `env` and `env-files` both map to the hybrid env-file discovery path.
+- `discovery_mode` supports `auto`, `single`, `folders`, and `env-files`. See the [repository layout guide](../guides/repository-layouts.md).
 - In GitHub Actions, `STACKSMITH_GITOPS_ROOT` defaults to `.` and can be overridden per run with `gitops_root`.
 - Changes under `<gitops_root>/common` and `<gitops_root>/manifests/common` fan out to all environments.
 - Changes under `<gitops_root>/environments/<env>` and `<gitops_root>/manifests/environments/<env>` target only that environment.
@@ -76,7 +76,7 @@ In your own repository, you can do either of the following.
 The wrappers pass reusable workflow inputs from repository variables when available.
 
 - `STACKSMITH_GITOPS_ROOT` (default `.`)
-- `STACKSMITH_DISCOVERY_MODE` (default `auto`; set to `flat-files` for root-level env files, or `env-files` for the hybrid `environments/<env>.yaml` layout)
+- `STACKSMITH_DISCOVERY_MODE` (default `auto`; supported values: `single`, `folders`, and `env-files`)
 - `STACKSMITH_WORKDIR` (default `.`)
 - `STACKSMITH_ENV_FILE` (default `/dev/null`)
 - `STACKSMITH_IMAGE_VERSION` (default `latest`)
@@ -205,7 +205,7 @@ jobs:
 
 > ℹ️ **Tip:** Pin the `uses:` reference to a release tag for stable downstream usage.
 
-The reusable workflow also supports the `folders` and `flat-files` discovery modes for repositories that prefer those layouts.
+See the [repository layout guide](../guides/repository-layouts.md) to choose between single deployments, environment files, and environment directories.
 
 ## Jenkins
 
@@ -254,7 +254,7 @@ Configure these values as Jenkins folder properties or job environment variables
 - `STACKSMITH_IMAGE_VERSION`: Image tag when `STACKSMITH_IMAGE` is unset. Defaults to `latest`.
 - `STACKSMITH_TEST_PIPELINE`: Set to a truthy value to make the job a test-only pipeline. The `COMMAND` parameter is not exposed in this mode and cannot override the test command.
 - `STACKSMITH_GITOPS_ROOT`: GitOps root for discovery. Defaults to `WORKDIR` in Jenkins.
-- `STACKSMITH_DISCOVERY_MODE`: `auto`, `folders`, `flat-files`, or `env-files`. Defaults to `auto`.
+- `STACKSMITH_DISCOVERY_MODE`: `auto`, `single`, `folders`, or `env-files`. Defaults to `auto`.
 - `STACKSMITH_MAX_PARALLEL_OPERATIONS`: Maximum independent operations planned or run concurrently within each environment. Defaults to `10`.
 - `STACKSMITH_ENV_FILE`: Env file passed to Stacksmith. Defaults to `/dev/null` to prevent implicit `.env` loading.
 - `STACKSMITH_CONFIG_REF`: Required platform-managed Stacksmith config reference.

diff --git a/docs/reference/cli-usage.md b/docs/reference/cli-usage.md
@@ -82,7 +82,7 @@ Use `info associations` to see how organization-managed association rules resolv
 `info associations --format json` writes the same details as machine-readable output to stdout.
 
 ```shell
-stacksmith info associations examples/stack-repo/stack.yaml --config examples/shared-config-repo/stacksmith-base-config.yaml --config examples/shared-config-repo/stacksmith-config.yaml --vars examples/stack-repo/vars.dev.yaml
+stacksmith info associations tests/fixtures/authoring-examples/stack-repo/stack.yaml --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-base-config.yaml --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-config.yaml --vars tests/fixtures/authoring-examples/stack-repo/vars.dev.yaml
 ```
 
 Use `info modules-and-policies` to review configured modules, mappings, metadata, and plan validations.
@@ -92,15 +92,15 @@ Use `info modules-and-policies` to review configured modules, mappings, metadata
 `info modules-and-policies --format table` writes human-readable output to stderr.
 
 ```shell
-stacksmith info modules-and-policies --config examples/shared-config-repo/stacksmith-base-config.yaml --config examples/shared-config-repo/stacksmith-config.yaml
+stacksmith info modules-and-policies --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-base-config.yaml --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-config.yaml
 ```
 
 Use `info diagnose` to inspect cache and module-resolution diagnostics for a stack.
 
 `info diagnose` writes diagnostics to stderr.
 
 ```shell
-stacksmith info diagnose examples/stack-simple-repo/stack.yaml --config examples/shared-config-repo/stacksmith-base-config.yaml --config examples/shared-config-repo/stacksmith-config.yaml
+stacksmith info diagnose tests/fixtures/authoring-examples/stack-simple-repo/stack.yaml --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-base-config.yaml --config tests/fixtures/authoring-examples/shared-config-repo/stacksmith-config.yaml
 ```
 
 ## CI commands
@@ -117,10 +117,10 @@ Run it without `--gitops-root` from a repository checkout to find every plausibl
 stacksmith ci environments
 
 stacksmith ci environments \
-  --gitops-root examples/gitops-repo \
+  --gitops-root tests/fixtures/authoring-examples/gitops-repo \
   --discovery-mode env-files \
   --event-name push \
-  --changed-path examples/gitops-repo/environments/dev.yaml
+  --changed-path tests/fixtures/authoring-examples/gitops-repo/environments/dev.yaml
 ```
 
 Use `ci validate` to run CI-oriented preflight checks with a stable check-result contract.
@@ -129,9 +129,9 @@ The first release focuses on static checks such as discovery mode validity, runf
 
 ```shell
 stacksmith ci validate \
-  --gitops-root examples/gitops-repo \
+  --gitops-root tests/fixtures/authoring-examples/gitops-repo \
   --discovery-mode env-files \
-  --workflow-runfile examples/gitops-repo/common/stacksmith.yaml \
+  --workflow-runfile tests/fixtures/authoring-examples/gitops-repo/common/stacksmith.yaml \
   --workflow-env-file /dev/null \
   --workflow-validation-report-format json
 ```

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -687,7 +687,7 @@ stacksmith info graph [-h] [--action {plan,apply,destroy}] [--root ROOT] [--stac
 
 ```text
 stacksmith ci environments [-h] [--gitops-root GITOPS_ROOT]
-                                  [--discovery-mode {folders,flat-files,env-files,single,env,auto}]
+                                  [--discovery-mode {folders,env-files,single,auto}]
                                   [--environments ENVIRONMENTS] [--event-name EVENT_NAME]
                                   [--changed-path CHANGED_PATH] [--base-ref BASE_REF] [--before BEFORE]
                                   [--after AFTER] [--format {table,json}]
@@ -696,7 +696,7 @@ stacksmith ci environments [-h] [--gitops-root GITOPS_ROOT]
 | Argument | Description |
 | - | - |
 | `--gitops-root` | Relative path to one GitOps root folder. When omitted from `ci environments`, Stacksmith searches the repository. |
-| `--discovery-mode` | Environment discovery mode. Use single, folders, flat-files, or env-files (env is an alias for env-files). Choices: `folders`, `flat-files`, `env-files`, `single`, `env`, `auto`. |
+| `--discovery-mode` | Environment discovery mode. Use single, folders, or env-files . Choices: `folders`, `env-files`, `single`, `auto`. |
 | `--environments` | Optional comma-separated environment names to target manually. |
 | `--event-name` | Optional caller event name used for event-aware selection. |
 | `--changed-path` | Changed repository path used for selection simulation. Repeatable. |
@@ -709,17 +709,16 @@ stacksmith ci environments [-h] [--gitops-root GITOPS_ROOT]
 
 ```text
 stacksmith ci validate [-h] [--gitops-root GITOPS_ROOT]
-                              [--discovery-mode {folders,flat-files,env-files,single,env,auto}]
-                              [--environments ENVIRONMENTS] [--workflow-runfile WORKFLOW_RUNFILE]
-                              [--workflow-env-file WORKFLOW_ENV_FILE]
+                              [--discovery-mode {folders,env-files,single,auto}] [--environments ENVIRONMENTS]
+                              [--workflow-runfile WORKFLOW_RUNFILE] [--workflow-env-file WORKFLOW_ENV_FILE]
                               [--workflow-validation-report-format WORKFLOW_VALIDATION_REPORT_FORMAT]
                               [--format {table,json}]
 ```
 
 | Argument | Description |
 | - | - |
 | `--gitops-root` | Relative path to the GitOps root folder. |
-| `--discovery-mode` | Environment discovery mode. Use single, folders, flat-files, or env-files (env is an alias for env-files). Choices: `folders`, `flat-files`, `env-files`, `single`, `env`, `auto`. |
+| `--discovery-mode` | Environment discovery mode. Use single, folders, or env-files . Choices: `folders`, `env-files`, `single`, `auto`. |
 | `--environments` | Optional comma-separated environment names to target manually. |
 | `--workflow-runfile` | Optional runfile path to validate for CI invocations. |
 | `--workflow-env-file` | Env file path to validate for CI invocations. Use /dev/null to represent deterministic no-env-file mode. |
@@ -730,10 +729,9 @@ stacksmith ci validate [-h] [--gitops-root GITOPS_ROOT]
 
 ```text
 stacksmith ci prepare [-h] [--gitops-root GITOPS_ROOT]
-                             [--discovery-mode {folders,flat-files,env-files,single,env,auto}]
-                             [--environments ENVIRONMENTS] [--event-name EVENT_NAME]
-                             [--changed-path CHANGED_PATH] [--base-ref BASE_REF] [--before BEFORE]
-                             [--after AFTER]
+                             [--discovery-mode {folders,env-files,single,auto}] [--environments ENVIRONMENTS]
+                             [--event-name EVENT_NAME] [--changed-path CHANGED_PATH] [--base-ref BASE_REF]
+                             [--before BEFORE] [--after AFTER]
                              --command {test,plan,apply,destroy,plan-operation,apply-operation}
                              [--operation-names OPERATION_NAMES] [--tags TAGS] --config-ref CONFIG_REF
                              [--workdir WORKDIR] [--env-file ENV_FILE]
@@ -748,7 +746,7 @@ stacksmith ci prepare [-h] [--gitops-root GITOPS_ROOT]
 | Argument | Description |
 | - | - |
 | `--gitops-root` | Relative path to the GitOps root folder. |
-| `--discovery-mode` | Environment discovery mode. Use single, folders, flat-files, or env-files (env is an alias for env-files). Choices: `folders`, `flat-files`, `env-files`, `single`, `env`, `auto`. |
+| `--discovery-mode` | Environment discovery mode. Use single, folders, or env-files . Choices: `folders`, `env-files`, `single`, `auto`. |
 | `--environments` | Optional comma-separated environment names to target manually. |
 | `--event-name` | Optional caller event name used for event-aware selection. |
 | `--changed-path` | Changed repository path used for selection simulation. Repeatable. |

diff --git a/docs/reference/python-api.md b/docs/reference/python-api.md
@@ -87,11 +87,11 @@ merge_mode: deep
 configs:
   - source: local
     data:
-      path: examples/gitops-repo/common/stacksmith.yaml
+      path: tests/fixtures/authoring-examples/gitops-repo/common/stacksmith.yaml
 vars:
   - source: local
     data:
-      path: examples/gitops-repo/vars/vars.dev.yaml
+      path: tests/fixtures/authoring-examples/gitops-repo/vars/vars.dev.yaml
 ```
 
 For production use, add GitHub Environment protections and secrets per environment. The reusable workflow completes the unprotected plan phase first, then maps each apply phase to the matching GitHub Environment so approvals and scoped credentials gate deployment after the plan is available.