feat: discover default .dot.toml configuration

README.md

@@ -43,7 +43,7 @@ The binary is written to `target/release/dot` (`dot.exe` on Windows).
 
 ## Quick start
 
-Create `dot.toml` in the directory containing the files you want to manage:
+Create `.dot.toml` in the directory containing the files you want to manage:
 
 ```toml
 [targets.workstation]
@@ -79,9 +79,13 @@ Apply the environment:
 dot apply --target workstation
 ```
 
-The default configuration path is `./dot.toml`; use `--config PATH` to select
-another file. `--target` may be omitted when exactly one configured target is
-compatible with the current platform.
+Without `--config`, `dot` checks `./.dot.toml` first, then
+`~/.config/dot/.dot.toml` on Linux and macOS or
+`%APPDATA%\dot\.dot.toml` on Windows. The first candidate whose filesystem
+entry exists is selected; load, parse, or validation errors for that path do
+not fall through to another candidate. An explicit `--config PATH` bypasses
+discovery and may use any filename. `--target` may be omitted when exactly one
+configured target is compatible with the current platform.
 
 ## Command line
 

docs/CONFIGURATION.md

@@ -6,6 +6,22 @@ configuration. This document is the human-facing explanation of that schema;
 boundaries. When they differ, update `SCHEMA.txt` first and then synchronize
 this reference.
 
+## Configuration discovery
+
+`dot` chooses one configuration using this exact precedence:
+
+1. the path from an explicit `--config PATH`, when supplied;
+2. `.dot.toml` in the current working directory;
+3. `~/.config/dot/.dot.toml` on Linux and macOS, or
+   `%APPDATA%\dot\.dot.toml` on Windows.
+
+An explicit path is used as given, may have any filename, and bypasses the
+remaining discovery candidates. Among the automatic candidates, the first
+whose filesystem entry exists is chosen. Read, parse, or validation failures
+for the chosen path are reported immediately; `dot` does not fall back to
+another candidate. It does not search parent directories recursively, merge
+configuration files, or recognize `dot.toml` as a legacy default.
+
 ## Type index
 
 - [Foundational types](#foundational-types): [`string`](#string),

docs/DESIGN.txt

@@ -652,7 +652,16 @@ dot list jobs
 ```
 
 There is no default operation. `dot` without a subcommand prints help and is an
-error. `--config PATH` is global and defaults to `./dot.toml`.
+error. `--config PATH` is global. The CLI represents its presence or absence as
+a typed ConfigRequest, and the central application facade resolves that request
+exactly once before dispatching an operation. An explicit path bypasses
+discovery and may use any filename. Otherwise dot checks `./.dot.toml`, then
+`~/.config/dot/.dot.toml` on Linux and macOS or
+`%APPDATA%\dot\.dot.toml` on Windows. The first existing filesystem entry is
+selected; load, parse, and validation failures do not fall through. Discovery
+does not recursively search, merge files, or recognize `dot.toml` as a legacy
+default. It uses native host paths and is not affected by an injected
+PlatformInfo.
 
 Target and profile options belong to `apply`, `dry-run`, `check providers`, and
 `list jobs`. `list profiles` accepts only the target option. `list targets`

docs/JOB_EXECUTION.md

@@ -103,7 +103,7 @@ from `SCHEMA.txt`. Provider IDs remain broad identifiers.
 The command pipeline is:
 
 ```text
-dot.toml
+.dot.toml
    |
    | parse + whole-configuration static validation
    v

src/app.rs

@@ -26,6 +26,11 @@ pub fn run(dispatch: Dispatch) -> ExitCode {
         platform_override,
     } = dispatch;
 
+    let config = match config.resolve() {
+        Ok(path) => path,
+        Err(error) => return command_error(error),
+    };
+
     if platform_override.is_some() {
         print_platform_warning(&operation);
     }

src/app/command.rs

@@ -1,6 +1,6 @@
 use std::fmt;
-use std::path::PathBuf;
 
+use crate::config::ConfigRequest;
 use crate::job::JobSelection;
 use crate::platform::PlatformInfo;
 use crate::schema::{SelectorIdentifier, SelectorIdentifierError};
@@ -60,7 +60,7 @@ pub enum Operation {
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Dispatch {
-    pub config: PathBuf,
+    pub config: ConfigRequest,
     pub operation: Operation,
     pub platform_override: Option<PlatformInfo>,
 }

src/cli.rs

@@ -6,6 +6,7 @@ use clap::error::ErrorKind;
 use clap::{Args, CommandFactory, Error, Parser, Subcommand};
 
 use crate::app::{Dispatch, ExecutionRequest, Operation, ProfileSelection, ScopeSelection};
+use crate::config::ConfigRequest;
 use crate::job::{JobSelection, JobSelector};
 use crate::schema::SelectorIdentifier;
 
@@ -31,15 +32,9 @@ where
     subcommand_required = true
 )]
 struct Cli {
-    /// Path to the TOML manifest
-    #[arg(
-        short,
-        long,
-        global = true,
-        value_name = "PATH",
-        default_value = "./dot.toml"
-    )]
-    config: PathBuf,
+    /// Path to the TOML manifest; defaults to ./.dot.toml, then the user fallback
+    #[arg(short, long, global = true, value_name = "PATH")]
+    config: Option<PathBuf>,
 
     /// Inject PlatformInfo for development-time compatibility selection; host environment, XDG
     /// paths, commands, and filesystem state remain unchanged
@@ -85,7 +80,9 @@ impl Cli {
         };
 
         Ok(Dispatch {
-            config: self.config,
+            config: self
+                .config
+                .map_or(ConfigRequest::Discover, ConfigRequest::Explicit),
             operation,
             platform_override,
         })