Expose --config <PATH> and NETSUKE_CONFIG precedence

docs/developers-guide.md

@@ -158,9 +158,8 @@ let _cwd_guard = CwdGuard::acquire()?;
 std::env::set_current_dir(temp.path())?;
 ```
 
-Acquire `EnvLock` and then `CwdGuard` so Rust drops them in reverse
-declaration order: `CwdGuard` restores the CWD first, and `EnvLock` releases
-second.
+Acquire `EnvLock` and then `CwdGuard` so Rust drops them in reverse declaration
+order: `CwdGuard` restores the CWD first, and `EnvLock` releases second.
 
 ### `restore_many` and `restore_many_locked`
 
@@ -354,8 +353,8 @@ Versioning and compatibility rules:
 - `cli_overrides_from_matches` must continue to emit a JSON object, even when
   no CLI override is present.
 - `is_empty_value` treats only the empty object `{}` as "no CLI overrides".
-  Downstream tooling must not replace an empty object with `null`, `[]`, or
-  any other sentinel.
+  Downstream tooling must not replace an empty object with `null`, `[]`, or any
+  other sentinel.
 - Additional properties are ignored by `diag_json` resolution and may be
   present because the same layer object also participates in full config
   merging.

docs/netsuke-design.md

@@ -2179,9 +2179,10 @@ flowchart LR
 Netsuke configuration discovery is implemented through OrthoConfig's
 `ConfigDiscovery` builder in `src/cli/config_merge.rs`. The
 `config_discovery()` helper constructs a discovery instance rooted at
-application name `"netsuke"`, honours the `NETSUKE_CONFIG_PATH` environment
-variable as an explicit override, and adjusts project-root discovery when the
-`-C/--directory` flag is supplied.
+application name `"netsuke"` and adjusts project-root discovery when the
+`-C/--directory` flag is supplied. Explicit file selection is handled before
+discovery by `resolve_config_path()`, which applies the precedence `--config` >
+`NETSUKE_CONFIG` > `NETSUKE_CONFIG_PATH`.
 
 #### Discovery scopes and layered merging
 
@@ -2194,9 +2195,12 @@ override earlier ones—meaning project-scope has highest precedence among file
 layers. After file layers are merged, environment variables and CLI arguments
 override the merged result, ensuring explicit user intent always wins.
 
-1. **Explicit override**: `NETSUKE_CONFIG_PATH` environment variable, if set.
-   This allows users to point to any arbitrary configuration file path,
-   bypassing automatic discovery entirely.
+1. **Explicit override**: the first configured selector from this list:
+   `--config <PATH>`, `NETSUKE_CONFIG`, `NETSUKE_CONFIG_PATH`. This allows
+   users to point to any arbitrary configuration file path, bypassing automatic
+   discovery entirely. `NETSUKE_CONFIG_PATH` remains supported as a
+   backward-compatible alias, but `NETSUKE_CONFIG` is the documented
+   environment variable going forward.
 
 2. **Project scope**: Configuration files in the current working directory (or
    the directory specified via `-C/--directory`):
@@ -2255,10 +2259,15 @@ manual flag repetition.
 - Configuration files use TOML format by default. JSON5 (`.json`, `.json5`) and
   YAML (`.yaml`, `.yml`) formats are supported when the corresponding Cargo
   features are enabled.
-- The current implementation uses `NETSUKE_CONFIG_PATH` for the override
-  environment variable. Roadmap item 3.11.3 plans to expose a visible
-  `--config` CLI flag and rename the environment variable to `NETSUKE_CONFIG`
-  for improved user ergonomics.
+- Explicit config selection is handled outside OrthoConfig's built-in
+  discovery override surface because Netsuke needs its custom two-pass
+  project-over-user merge behaviour for automatic discovery. The selected file
+  still participates in the normal precedence ladder: defaults < file <
+  environment < CLI flags.
+- Relative paths passed to `--config` are resolved against the process current
+  working directory, not the `-C/--directory` anchor. This keeps config-file
+  selection aligned with normal shell path semantics while `-C` continues to
+  scope project discovery and manifest lookup.
 
 ### 8.5 Manual Pages
 

docs/roadmap.md

@@ -293,9 +293,9 @@ library, and CLI ergonomics.
   - [x] Add integration tests for each precedence tier. See
     [ortho-config-users-guide.md](ortho-config-users-guide.md) and
     `tests/cli_tests/config_discovery.rs`.
-- [ ] 3.11.3. Expose `--config <path>` and `NETSUKE_CONFIG`.
-  - [ ] Select alternative config files.
-  - [ ] Ship annotated sample configs in documentation.
+- [x] 3.11.3. Expose `--config <path>` and `NETSUKE_CONFIG`.
+  - [x] Select alternative config files.
+  - [x] Ship annotated sample configs in documentation.
 - [ ] 3.11.4. Add regression tests for OrthoConfig precedence ladder.
   - [ ] Test defaults < file < env < CLI precedence. See
     [ortho-config-users-guide.md](ortho-config-users-guide.md).

docs/sample-netsuke.toml

@@ -0,0 +1,63 @@
+# Sample Netsuke configuration
+#
+# Copy this file to `.netsuke.toml` in a project root, or point Netsuke at it
+# with `--config /path/to/file.toml` or `NETSUKE_CONFIG=/path/to/file.toml`.
+#
+# All settings below are commented out so the file is valid as-is. Uncomment
+# only the keys you want to change.
+
+# Path to the manifest file to use instead of `Netsukefile`.
+# file = "Netsukefile"
+
+# Number of parallel build jobs. Valid range: 1-64.
+# jobs = 8
+
+# Enable verbose diagnostics and timing summaries.
+# verbose = true
+
+# Locale for CLI messages, for example `en-US` or `es-ES`.
+# locale = "en-US"
+
+# Force accessible output mode on or off.
+# accessible = true
+
+# Suppress emoji glyphs in output.
+# no_emoji = false
+
+# Theme preset: `auto`, `unicode`, or `ascii`.
+# theme = "auto"
+
+# Colour output policy: `auto`, `always`, or `never`.
+# colour_policy = "auto"
+
+# Force standard stage and task progress summaries on or off.
+# progress = true
+
+# Spinner mode: `enabled` or `disabled`.
+# spinner_mode = "enabled"
+
+# Emit machine-readable diagnostics on stderr.
+# diag_json = false
+
+# Diagnostic output format: `human` or `json`.
+# output_format = "human"
+
+# Default build targets when the CLI does not name any targets.
+# default_targets = ["fmt", "lint", "test"]
+
+# Additional URL schemes allowed for the `fetch` helper.
+# fetch_allow_scheme = ["https"]
+
+# Hostnames allowed when `fetch_default_deny = true`.
+# Supports wildcards such as `*.example.com`.
+# fetch_allow_host = ["example.com", "*.example.com"]
+
+# Hostnames that are always blocked.
+# Supports wildcards such as `*.example.com`.
+# fetch_block_host = ["metadata.internal"]
+
+# Deny all fetch hosts by default and allow only the declared allowlist.
+# fetch_default_deny = false
+
+# CLI-only controls such as `--config`, `--directory`, and subcommands are not
+# read from config files.

docs/users-guide.md

@@ -548,10 +548,17 @@ command-line flags.
 
 #### Configuration file discovery
 
-Configuration files are discovered using OrthoConfig. When
-`NETSUKE_CONFIG_PATH` is set, it points to a single file and bypasses all
-automatic discovery. Otherwise, Netsuke searches for configuration in three
-scopes:
+Configuration files are discovered using OrthoConfig unless you select an
+explicit file. Netsuke honours these file-selection inputs in precedence order:
+
+- `--config <PATH>`
+- `NETSUKE_CONFIG=<PATH>`
+- `NETSUKE_CONFIG_PATH=<PATH>` (legacy alias)
+- Automatic discovery
+
+When one of the explicit selectors is set, Netsuke loads only that file and
+skips automatic discovery. Otherwise, Netsuke searches for configuration in
+three scopes:
 
 - **Project scope** — `.netsuke.toml` in the current working directory
   (or the directory specified by `-C` / `--directory`).
@@ -571,6 +578,10 @@ the project file overrides the same field from user or system files, user-scope
 settings override system-scope, and fields set only in lower-precedence files
 are still applied.
 
+The explicit config path is resolved against the shell's current working
+directory, not the `-C` / `--directory` project anchor. The directory flag only
+changes where project-scope discovery and manifest lookup begin.
+
 #### Directory flag and project anchoring
 
 The `-C <DIR>` / `--directory <DIR>` flag re-anchors project-scope discovery to
@@ -585,6 +596,10 @@ netsuke -C /path/to/project build
 With the flag, only `/path/to/project/.netsuke.toml` is considered for
 project-scope discovery; user-scope discovery is unaffected.
 
+For a documented starting point, see
+[`docs/sample-netsuke.toml`](sample-netsuke.toml), which annotates every
+supported config-file key.
+
 #### Environment variables
 
 Environment variables use the `NETSUKE_` prefix (for example,

locales/en-US/messages.ftl

@@ -7,6 +7,7 @@ cli.usage = { $usage }
 # Root-level flag help text.
 cli.flag.file.help = Path to the Netsuke manifest file to use.
 cli.flag.directory.help = Run as if started in this directory.
+cli.flag.config.help = Path to a configuration file, bypassing automatic discovery.
 cli.flag.jobs.help = Set the number of parallel build jobs.
 cli.flag.verbose.help = Enable verbose diagnostic logging and completion timing summaries.
 cli.flag.locale.help = Locale tag for CLI copy (for example: en-US, es-ES).

locales/es-ES/messages.ftl

@@ -7,6 +7,7 @@ cli.usage = { $usage }
 # Texto de ayuda para opciones globales.
 cli.flag.file.help = Ruta al archivo de manifiesto Netsuke.
 cli.flag.directory.help = Ejecutar como si se iniciara en este directorio.
+cli.flag.config.help = Ruta a un archivo de configuración, omitiendo la detección automática.
 cli.flag.jobs.help = Número de trabajos de compilación en paralelo.
 cli.flag.verbose.help = Habilitar registro de diagnóstico detallado y resúmenes de tiempo al completar.
 cli.flag.locale.help = Etiqueta de idioma para la CLI (por ejemplo: en-US, es-ES).