mount: ensure idempotent results and persist runtime roots

* read /proc/self/mountinfo to detect already mounted targets and reuse their metadata * reject conflicting mounts by source, allowing reruns without duplicating entries * return mount results sorted by target for deterministic downstream behavior * write subvolume and /var/mounts/{UUID} entries to fstab when requested
Refine default orchestration flow and documentation
2025-10-10 10:07:48 +02:00 · 2025-10-09 16:51:12 +02:00
12 changed files with 5572 additions and 316 deletions
--- a/README.md
+++ b/README.md
@@ -24,10 +24,10 @@ Key modules
  - [src/mount/ops.rs](src/mount/ops.rs)

 Features at a glance
- Topology-driven planning with built-in defaults: BtrfsSingle, BcachefsSingle, DualIndependent, Bcachefs2Copy, BtrfsRaid1, SsdHddBcachefs
- Non-destructive preview: --show/--report outputs JSON summary (disks, partition plan, filesystems, planned mountpoints)
+- Topology auto-selection with built-in defaults; optional kernel cmdline override via `zosstorage.topology=` (see ADR-0002)
+- Non-destructive preview: `--show`/`--report` outputs JSON summary (disks, partition plan, filesystems, planned mountpoints)
 - Safe discovery: excludes removable media by default (USB sticks) unless explicitly allowed
- Config-optional: the tool runs without any YAML; sensible defaults are always present and may be overridden/merged by config
+- No external YAML configuration; defaults-only per ADR-0002 (sane built-ins, topology may be overridden by kernel cmdline)

 Requirements
 - Linux with /proc and /sys mounted (initramfs friendly)
@@ -45,8 +45,6 @@ Install and build
 Binary is target/release/zosstorage.

 CLI usage
- Topology selection (config optional):
-  -t, --topology btrfs-single|bcachefs-single|dual-independent|bcachefs-2copy|btrfs-raid1|ssd-hdd-bcachefs
 - Preview (non-destructive):
  --show                      Print JSON summary to stdout
  --report PATH               Write JSON summary to a file
@@ -56,22 +54,30 @@ CLI usage
  -l, --log-level LEVEL       error|warn|info|debug (default: info)
  -L, --log-to-file           Also write logs to /run/zosstorage/zosstorage.log
 - Other:
-  -c, --config PATH           Merge a YAML config file (overrides defaults)
  -s, --fstab                 Enable writing /etc/fstab entries (when mounts are applied)
  -a, --apply                 Perform partitioning, filesystem creation, and mounts (destructive)
  -f, --force                 Present but not implemented (returns an error)

+Deprecated (ignored with warning; see ADR-0002)
+  -t, --topology VALUE        Ignored; use kernel cmdline `zosstorage.topology=` instead
+  -c, --config PATH           Ignored; external YAML configuration is not used at runtime
+
 Examples
- Single disk plan with debug logs:
-  sudo ./zosstorage --show -t btrfs-single -l debug
- RAID1 btrfs across two disks; print and write summary:
-  sudo ./zosstorage --show --report /run/zosstorage/plan.json -t btrfs-raid1 -l debug -L
- SSD+HDD bcachefs plan, include removable devices (for lab cases):
-  sudo ./zosstorage --show -t ssd-hdd-bcachefs --allow-removable -l debug
+- Single disk plan with debug logs (defaults to btrfs_single automatically):
+  sudo ./zosstorage --show -l debug
+- Two-disk plan (defaults to dual_independent automatically), write summary:
+  sudo ./zosstorage --show --report /run/zosstorage/plan.json -l debug -L
+- Include removable devices for lab scenarios:
+  sudo ./zosstorage --show --allow-removable -l debug
 - Quiet plan to file:
-  sudo ./zosstorage --report /run/zosstorage/plan.json -t dual-independent
- Apply single-disk btrfs (DESTRUCTIVE; wipes target disk):
-  sudo ./zosstorage --apply -t btrfs-single
+  sudo ./zosstorage --report /run/zosstorage/plan.json
+- Apply single-disk plan (DESTRUCTIVE; wipes target disk; defaults select topology automatically):
+  sudo ./zosstorage --apply
+
+Kernel cmdline override (at boot)
+- To force a topology, pass one of:
+  zosstorage.topology=btrfs-single | bcachefs-single | dual-independent | btrfs-raid1 | ssd-hdd-bcachefs | bcachefs-2copy
+- The override affects only topology; all other settings use sane built-in defaults.

 Preview JSON shape (examples)
 1) Already provisioned (idempotency success):
--- a/docs/Callgraph.svg
+++ b/docs/Callgraph.svg
--- a/docs/FUNCTION_LIST.md
+++ b/docs/FUNCTION_LIST.md
@@ -0,0 +1,294 @@
+# Function Reference - Call Graph Analysis
+
+> This documentation is automatically derived from [`Callgraph.svg`](Callgraph.svg) and provides a comprehensive overview of all functions in the zosstorage project, organized by module.
+
+## Table of Contents
+
+- [Main Entry Points](#main-entry-points)
+- [CLI & Configuration](#cli--configuration)
+- [Orchestration](#orchestration)
+- [Device Discovery](#device-discovery)
+- [Partition Management](#partition-management)
+- [Filesystem Operations](#filesystem-operations)
+- [Mount Operations](#mount-operations)
+- [Idempotency & State](#idempotency--state)
+- [Reporting](#reporting)
+- [Utilities](#utilities)
+- [Logging](#logging)
+- [Type Definitions](#type-definitions)
+
+---
+
+## Main Entry Points
+
+### [`src/main.rs`](../src/main.rs)
+
+| Function | Purpose |
+|----------|---------|
+| `main()` | Application entry point; initializes the program and handles top-level errors |
+| `real_main()` | Core application logic; orchestrates the main workflow after initialization |
+
+---
+
+## CLI & Configuration
+
+### [`src/cli/args.rs`](../src/cli/args.rs)
+
+**Structs:** `Cli`, `LogLevelArg` (enum)
+
+| Function | Purpose |
+|----------|---------|
+| `from_args()` | Parses command-line arguments and returns a `Cli` configuration object |
+
+### [`src/config/loader.rs`](../src/config/loader.rs)
+
+| Function | Purpose |
+|----------|---------|
+| `load_and_merge()` | Loads configuration from multiple sources and merges them into a unified config |
+| `validate()` | Validates the merged configuration for correctness and completeness |
+| `to_value()` | Converts configuration structures to internal value representation |
+| `merge_value()` | Recursively merges configuration values, handling conflicts appropriately |
+| `cli_overlay_value()` | Overlays CLI-provided values onto existing configuration |
+| `kernel_cmdline_topology()` | Extracts topology information from kernel command line parameters |
+| `parse_topology_token()` | Parses individual topology tokens from kernel cmdline |
+| `default_config()` | Generates default configuration values when no config file is present |
+
+---
+
+## Orchestration
+
+### [`src/orchestrator/run.rs`](../src/orchestrator/run.rs)
+
+**Structs:** `Context`
+
+| Function | Purpose |
+|----------|---------|
+| `Context::new()` | Creates a new orchestration context with default settings |
+| `Context::with_show()` | Builder method to enable show/dry-run mode |
+| `Context::with_apply()` | Builder method to enable apply mode (actual execution) |
+| `Context::with_report_path()` | Builder method to set the report output path |
+| `Context::with_mount_existing()` | Builder method to configure mounting of existing filesystems |
+| `Context::with_report_current()` | Builder method to enable reporting of current system state |
+| `Context::with_topology_from_cli()` | Builder method to set topology from CLI arguments |
+| `Context::with_topology_from_cmdline()` | Builder method to set topology from kernel cmdline |
+| `run()` | Main orchestration function; coordinates all storage operations |
+| `build_device_filter()` | Constructs device filter based on configuration and user input |
+| `enforce_empty_disks()` | Validates that target disks are empty before proceeding |
+| `role_str()` | Converts partition role enum to human-readable string |
+| `build_summary_json()` | Builds a JSON summary of operations performed |
+
+---
+
+## Device Discovery
+
+### [`src/device/discovery.rs`](../src/device/discovery.rs)
+
+**Structs:** `Disk`, `DeviceFilter`, `SysProvider`  
+**Traits:** `DeviceProvider`
+
+| Function | Purpose |
+|----------|---------|
+| `DeviceFilter::matches()` | Checks if a device matches the configured filter criteria |
+| `SysProvider::new()` | Creates a new sysfs-based device provider |
+| `SysProvider::list_block_devices()` | Lists all block devices found via sysfs |
+| `SysProvider::probe_properties()` | Probes detailed properties of a specific device |
+| `discover()` | Entry point for device discovery using default provider |
+| `discover_with_provider()` | Device discovery with custom provider (for testing/flexibility) |
+| `is_ignored_name()` | Checks if device name should be ignored (loop, ram, etc.) |
+| `sys_block_path()` | Constructs sysfs path for a given block device |
+| `base_name()` | Extracts base device name from path |
+| `is_removable_sysfs()` | Checks if device is removable via sysfs |
+| `is_partition_sysfs()` | Checks if device is a partition via sysfs |
+| `read_disk_size_bytes()` | Reads disk size in bytes from sysfs |
+| `read_rotational()` | Determines if disk is rotational (HDD) or not (SSD) |
+| `read_model_serial()` | Reads device model and serial number |
+| `read_optional_string()` | Utility to safely read optional string values from sysfs |
+
+---
+
+## Partition Management
+
+### [`src/partition/plan.rs`](../src/partition/plan.rs)
+
+**Structs:** `PartitionSpec`, `DiskPlan`, `PartitionPlan`, `PartitionResult`  
+**Enums:** `PartRole`
+
+| Function | Purpose |
+|----------|---------|
+| `plan_partitions()` | Creates partition plans for all target disks based on topology |
+| `apply_partitions()` | Executes partition plans using sgdisk tool |
+| `type_code()` | Returns GPT partition type code for a given partition role |
+| `part_dev_path()` | Constructs device path for a partition (e.g., /dev/sda1) |
+| `sector_size_bytes()` | Reads logical sector size of disk |
+| `parse_sgdisk_info()` | Parses output from sgdisk to extract partition information |
+
+---
+
+## Filesystem Operations
+
+### [`src/fs/plan.rs`](../src/fs/plan.rs)
+
+**Structs:** `FsSpec`, `FsPlan`, `FsResult`  
+**Enums:** `FsKind`
+
+| Function | Purpose |
+|----------|---------|
+| `plan_filesystems()` | Plans filesystem creation for all partitions |
+| `make_filesystems()` | Creates filesystems according to plan (mkfs.* tools) |
+| `capture_uuid()` | Captures UUID of newly created filesystem |
+| `parse_blkid_export()` | Parses blkid export format to extract filesystem metadata |
+| `probe_existing_filesystems()` | Detects existing filesystems on partitions |
+
+---
+
+## Mount Operations
+
+### [`src/mount/ops.rs`](../src/mount/ops.rs)
+
+**Structs:** `PlannedMount`, `PlannedSubvolMount`, `MountPlan`, `MountResult`
+
+| Function | Purpose |
+|----------|---------|
+| `fstype_str()` | Converts FsKind enum to mount filesystem type string |
+| `plan_mounts()` | Creates mount plans for all filesystems |
+| `apply_mounts()` | Executes mount operations and creates mount points |
+| `maybe_write_fstab()` | Conditionally writes /etc/fstab entries for persistent mounts |
+
+---
+
+## Idempotency & State
+
+### [`src/idempotency/mod.rs`](../src/idempotency/mod.rs)
+
+| Function | Purpose |
+|----------|---------|
+| `detect_existing_state()` | Detects existing partitions and filesystems to avoid destructive operations |
+| `is_empty_disk()` | Checks if a disk has no partition table or filesystems |
+| `parse_blkid_export()` | Parses blkid output to identify existing filesystems |
+| `read_proc_partitions_names()` | Reads partition names from /proc/partitions |
+| `base_name()` | Extracts base name from device path |
+| `is_partition_of()` | Checks if one device is a partition of another |
+
+---
+
+## Reporting
+
+### [`src/report/state.rs`](../src/report/state.rs)
+
+**Structs:** `StateReport`
+
+| Function | Purpose |
+|----------|---------|
+| `build_report()` | Builds comprehensive state report of operations performed |
+| `write_report()` | Writes report to specified output path (JSON format) |
+
+---
+
+## Utilities
+
+### [`src/util/mod.rs`](../src/util/mod.rs)
+
+**Structs:** `CmdOutput`
+
+| Function | Purpose |
+|----------|---------|
+| `which_tool()` | Locates external tool in PATH (sgdisk, mkfs.*, etc.) |
+| `run_cmd()` | Executes shell command and returns exit status |
+| `run_cmd_capture()` | Executes command and captures stdout/stderr |
+| `udev_settle()` | Waits for udev to process device events |
+| `is_efi_boot()` | Detects if system booted in EFI mode |
+
+---
+
+## Logging
+
+### [`src/logging/mod.rs`](../src/logging/mod.rs)
+
+**Structs:** `LogOptions`
+
+| Function | Purpose |
+|----------|---------|
+| `LogOptions::from_cli()` | Creates logging configuration from CLI arguments |
+| `level_from_str()` | Converts string to log level enum |
+| `init_logging()` | Initializes logging subsystem with configured options |
+
+---
+
+## Type Definitions
+
+### [`src/types.rs`](../src/types.rs)
+
+**Core Configuration Structures:**
+
+- `Config` - Top-level configuration structure
+- `LoggingConfig` - Logging configuration
+- `DeviceSelection` - Device selection criteria
+- `Topology` - Storage topology definition (enum)
+- `Partitioning` - Partition layout specification
+- `BiosBootSpec`, `EspSpec`, `DataSpec`, `CacheSpec` - Partition type specifications
+- `FsOptions`, `BtrfsOptions`, `BcachefsOptions`, `VfatOptions` - Filesystem options
+- `MountScheme`, `MountSchemeKind` - Mount configuration
+- `ReportOptions` - Report generation configuration
+
+### [`src/errors.rs`](../src/errors.rs)
+
+**Error Types:**
+
+- `Error` - Main error enum for all error conditions
+- `Result<T>` - Type alias for `std::result::Result<T, Error>`
+
+---
+
+## Call Graph Relationships
+
+### Main Execution Flow
+
+```
+main() → real_main() → orchestrator::run()
+    ↓
+    ├─→ cli::from_args()
+    ├─→ config::load_and_merge()
+    ├─→ logging::init_logging()
+    ├─→ device::discover()
+    ├─→ partition::plan_partitions()
+    ├─→ partition::apply_partitions()
+    ├─→ fs::plan_filesystems()
+    ├─→ fs::make_filesystems()
+    ├─→ mount::plan_mounts()
+    ├─→ mount::apply_mounts()
+    └─→ report::build_report() / write_report()
+```
+
+### Key Dependencies
+
+- **Orchestrator** (`run()`) calls: All major subsystems
+- **Device Discovery** uses: Utilities for system probing
+- **Partition/FS/Mount** operations use: Utilities for command execution
+- **All operations** call: `util::run_cmd()` or `util::run_cmd_capture()`
+- **Idempotency checks** called by: Orchestrator before destructive operations
+
+---
+
+## Function Count Summary
+
+- **Main Entry**: 2 functions
+- **CLI & Config**: 9 functions
+- **Orchestration**: 13 functions  
+- **Device Discovery**: 14 functions
+- **Partition Management**: 6 functions
+- **Filesystem Operations**: 5 functions
+- **Mount Operations**: 4 functions
+- **Idempotency**: 6 functions
+- **Reporting**: 2 functions
+- **Utilities**: 6 functions
+- **Logging**: 3 functions
+
+**Total: 70 documented functions** across 15 source files
+
+---
+
+## References
+
+- Original call graph visualization: [`docs/Callgraph.svg`](Callgraph.svg)
+- Architecture documentation: [`docs/ARCHITECTURE.md`](ARCHITECTURE.md)
+- API documentation: [`docs/API.md`](API.md)
--- a/docs/SCHEMA.md
+++ b/docs/SCHEMA.md
@@ -1,27 +1,16 @@
-# zosstorage Configuration Schema
+# zosstorage Configuration (Deprecated schema)

-This document defines the YAML configuration for the initramfs-only disk provisioning utility and the exact precedence rules between configuration sources. It complements [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+This schema document is deprecated per [docs/adr/0002-defaults-only-no-external-config.md](docs/adr/0002-defaults-only-no-external-config.md). Runtime now uses defaults-only with a single optional kernel cmdline override. The YAML configuration file is not read at boot.

-Canonical paths and keys
- Kernel cmdline key: zosstorage.config=
- Default config file path: /etc/zosstorage/config.yaml
- JSON state report path: /run/zosstorage/state.json
- Optional log file path: /run/zosstorage/zosstorage.log
- fstab generation: disabled by default
- Reserved filesystem labels: ZOSBOOT (ESP), ZOSDATA (all data filesystems)
- GPT partition names: zosboot, zosdata, zoscache
+Active behavior (ADR-0002)
+- Defaults-only: all settings are defined in code. No /etc/zosstorage/config.yaml is read.
+- Optional kernel cmdline override: `zosstorage.topology=VALUE` can override only the topology. Legacy alias `zosstorage.topo=` is accepted.
+- CLI: `--config` and `--topology` are deprecated and ignored (warnings emitted). Operational flags remain (`--apply`, `--show`, `--report`, `--fstab`, logging).
+- Report path: `/run/zosstorage/state.json`. Optional log file: `/run/zosstorage/zosstorage.log`.
+- Reserved labels: `ZOSBOOT` (ESP), `ZOSDATA` (data). GPT names: `zosboot`, `zosdata`, `zoscache`.

-Precedence and merge strategy
-1. Start from built-in defaults documented here.
-2. Merge in the on-disk config file if present at /etc/zosstorage/config.yaml.
-3. Merge CLI flags next; these override file values.
-4. Merge kernel cmdline last; zosstorage.config= overrides CLI and file.
-5. No interactive prompts are permitted.
-
-The kernel cmdline key zosstorage.config= accepts:
- A path to a YAML file inside the initramfs root (preferred).
- A file: absolute path (e.g., file:/run/config/zos.yaml).
- A data: URL containing base64 YAML (optional extension).
+Historical reference (original YAML-based schema, no longer used at runtime)
+The remainder of this document preserves the previous YAML schema for archival purposes only.

 Top-level YAML structure

--- a/docs/adr/0002-defaults-only-no-external-config.md
+++ b/docs/adr/0002-defaults-only-no-external-config.md
@@ -0,0 +1,109 @@
+# ADR 0002: Defaults-Only Configuration; Remove External YAML Config
+
+Status
+- Accepted
+- Date: 2025-10-06
+
+Context
+- Running from initramfs at first boot provides no reliable access to an on-disk configuration file (e.g., /etc/zosstorage/config.yaml). An external file cannot be assumed to exist or be mounted.
+- The previous design added precedence and merge complexity across file, CLI, and kernel cmdline as documented in [docs/SCHEMA.md](../SCHEMA.md) and implemented via [fn load_and_merge()](../../src/config/loader.rs:1), increasing maintenance burden and risks of drift.
+- YAML introduces misconfiguration risk in early boot, adds I/O, and complicates idempotency guarantees without meaningful benefits for the intended minimal-first initializer.
+- The desired model is to ship with sane built-in defaults, selected automatically from detected hardware topology; optional kernel cmdline may override only the topology choice for VM/lab scenarios.
+
+Decision
+- Remove all dependency on an on-disk configuration file:
+  - Do not read /etc/zosstorage/config.yaml or any file-based config.
+  - Deprecate and ignore repository-local config files for runtime (e.g., config/zosstorage.yaml). The example file [config/zosstorage.example.yaml](../../config/zosstorage.example.yaml) remains as historical reference only and may be removed later.
+- Deprecate the --config CLI flag in [struct Cli](../../src/cli/args.rs:1). If present, emit a deprecation warning and ignore it.
+- Retain operational CLI flags and logging controls for usability:
+  - --apply, --show, --report PATH, --fstab, --log-level LEVEL, --log-to-file
+- Replace the prior file/CLI/kernel precedence with a defaults-only policy plus a single optional kernel cmdline override:
+  - Recognized key: zosstorage.topology=VALUE
+  - The key may override only the topology selection; all other settings use built-in defaults.
+- Topology defaults and override policy:
+  - 1 eligible disk:
+    - Default: btrfs_single
+    - Allowed cmdline overrides: btrfs_single, bcachefs_single
+  - 2 eligible disks:
+    - Default: dual_independent
+    - Allowed cmdline overrides: dual_independent, ssd_hdd_bcachefs, btrfs_raid1, bcachefs_2copy
+  - >2 eligible disks:
+    - Default: btrfs_raid1
+    - Allowed cmdline overrides: btrfs_raid1, bcachefs_2copy
+- Accept both snake_case and hyphenated forms for VALUE; normalize to [enum Topology](../../src/types.rs:1):
+  - btrfs_single | btrfs-single
+  - bcachefs_single | bcachefs-single
+  - dual_independent | dual-independent
+  - ssd_hdd_bcachefs | ssd-hdd-bcachefs
+  - btrfs_raid1 | btrfs-raid1
+  - bcachefs_2copy | bcachefs-2copy
+- Kernel cmdline parsing beyond topology is deferred; future extensions for VM workflows may be proposed separately.
+
+Rationale
+- Eliminates unreachable configuration paths at first boot and simplifies the mental model.
+- Reduces maintenance overhead by removing schema and precedence logic.
+- Minimizes early-boot I/O and failure modes while preserving a targeted override for lab/VMs.
+- Keeps the tool safe-by-default and fully idempotent without depending on external files.
+
+Consequences
+- Documentation:
+  - Mark [docs/SCHEMA.md](../SCHEMA.md) as deprecated for runtime behavior; retain only as historical reference.
+  - Update [docs/ARCHITECTURE.md](../ARCHITECTURE.md) and [docs/SPECS.md](../SPECS.md) to reflect defaults-only configuration.
+  - Update [docs/API.md](../API.md) and [docs/API-SKELETONS.md](../API-SKELETONS.md) where they reference file-based config.
+- CLI:
+  - [struct Cli](../../src/cli/args.rs:1) keeps operational flags; --config becomes a no-op with a deprecation warning.
+- Code:
+  - Replace [fn load_and_merge()](../../src/config/loader.rs:1) with a minimal loader that:
+    - Builds a [struct Config](../../src/types.rs:1) entirely from baked-in defaults.
+    - Reads /proc/cmdline to optionally parse zosstorage.topology and normalize to [enum Topology](../../src/types.rs:1).
+    - Removes YAML parsing, file reads, and merge logic.
+- Tests:
+  - Remove tests that depend on external YAML; add tests for cmdline override normalization and disk-count defaults.
+
+Defaults (authoritative)
+- Partitioning:
+  - GPT only, 1 MiB alignment, BIOS boot 1 MiB first unless UEFI detected via [fn is_efi_boot()](../../src/util/mod.rs:1).
+  - ESP 512 MiB labeled ZOSBOOT (GPT name: zosboot), data uses GPT name zosdata.
+- Filesystems:
+  - ESP: vfat labeled ZOSBOOT
+  - Data: label ZOSDATA
+  - Backend per topology (btrfs for btrfs_*; bcachefs for ssd_hdd_bcachefs and bcachefs_2copy)
+- Mount scheme:
+  - Root-mount all data filesystems under /var/mounts/{UUID}; final subvolume/subdir mounts from the primary data FS to /var/cache/{system,etc,modules,vm-meta}; fstab remains optional.
+- Idempotency:
+  - Unchanged: already-provisioned signals exit success-without-changes via [fn detect_existing_state()](../../src/idempotency/mod.rs:1).
+
+Implementation Plan
+1) Introduce a minimal defaults loader in [src/config/loader.rs](../../src/config/loader.rs:1):
+   - new internal fn parse_topology_from_cmdline() -> Option<Topology>
+   - new internal fn normalize_topology(s: &str) -> Option<Topology>
+   - refactor load to construct Config from constants + optional topology override
+2) CLI:
+   - Emit deprecation warning when --config is provided; ignore its value.
+3) Docs:
+   - Add deprecation banner to [docs/SCHEMA.md](../SCHEMA.md).
+   - Adjust [README.md](../../README.md) to describe defaults and the zosstorage.topology override.
+4) Tests:
+   - Add unit tests for normalization and disk-count policy; remove YAML-based tests.
+
+Backward Compatibility
+- External YAML configuration is no longer supported at runtime.
+- Kernel cmdline key zosstorage.config= is removed. Only zosstorage.topology remains recognized.
+- The JSON report, labels, GPT names, and mount behavior remain unchanged.
+
+Security and Safety
+- By eliminating external configuration input, we reduce attack surface and misconfiguration risk in early boot.
+- The emptiness and idempotency checks continue to gate destructive operations.
+
+Open Items
+- Decide whether to accept additional synonyms (e.g., “bcachefs-raid1”) and map them to existing [enum Topology](../../src/types.rs:1) variants; default is to reject unknown values with a clear error.
+- Potential future kernel cmdline keys (e.g., logging level) may be explored via a separate ADR.
+
+Links
+- Architecture: [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
+- API Index: [docs/API-SKELETONS.md](../API-SKELETONS.md)
+- Specs: [docs/SPECS.md](../SPECS.md)
+- CLI: [src/cli/args.rs](../../src/cli/args.rs)
+- Config loader: [src/config/loader.rs](../../src/config/loader.rs)
+- Types: [src/types.rs](../../src/types.rs)
+- Util: [src/util/mod.rs](../../src/util/mod.rs)
--- a/docs/adr/callgraph.html
+++ b/docs/adr/callgraph.html
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -58,8 +58,8 @@ impl std::fmt::Display for LogLevelArg {
 #[derive(Debug, Parser)]
 #[command(name = "zosstorage", disable_help_subcommand = true)]
 pub struct Cli {
-    /// Path to YAML configuration (mirrors kernel cmdline key 'zosstorage.config=')
-    #[arg(short = 'c', long = "config")]
+    /// DEPRECATED: external YAML configuration is not used at runtime (ADR-0002). Ignored with a warning.
+    #[arg(short = 'c', long = "config", hide = true)]
    pub config: Option<String>,

    /// Log level: error, warn, info, debug
@@ -74,7 +74,7 @@ pub struct Cli {
    #[arg(short = 's', long = "fstab", default_value_t = false)]
    pub fstab: bool,

-    /// Select topology (overrides config topology)
+    /// Select topology (CLI has precedence over kernel cmdline)
    #[arg(short = 't', long = "topology", value_enum)]
    pub topology: Option<crate::types::Topology>,

@@ -82,8 +82,7 @@ pub struct Cli {
    #[arg(short = 'f', long = "force")]
    pub force: bool,

-    /// Allow removable devices (e.g., USB sticks) to be considered during discovery
-    /// Overrides config.device_selection.allow_removable when provided
+    /// Include removable devices (e.g., USB sticks) during discovery (default: false)
    #[arg(long = "allow-removable", default_value_t = false)]
    pub allow_removable: bool,
 
@@ -100,7 +99,7 @@ pub struct Cli {
    #[arg(long = "show", default_value_t = false)]
    pub show: bool,
 
-    /// Write detection/planning JSON report to the given path (overrides config.report.path)
+    /// Write detection/planning JSON report to the given path
    #[arg(long = "report")]
    pub report: Option<String>,
 
--- a/src/config/loader.rs
+++ b/src/config/loader.rs
@@ -1,11 +1,12 @@
 //! Configuration loading, merging, and validation (loader).
 //!
-//! Precedence (highest to lowest):
-//! - CLI flags (and optional `--config PATH` when provided)
-//! - Kernel cmdline key `zosstorage.topo=`
-//! - Built-in defaults
-//!
-//! See [docs/SCHEMA.md](../../docs/SCHEMA.md) for the schema details.
+//// Precedence and policy (ADR-0002):
+//// - Built-in sane defaults for all settings.
+//// - Kernel cmdline key `zosstorage.topology=` (legacy alias `zosstorage.topo=`) may override topology only.
+//// - CLI flags control operational toggles only (logging, fstab, allow-removable).
+//// - `--config` and `--topology` are deprecated and ignored (warnings emitted).
+////
+//// Note: [docs/SCHEMA.md](../../docs/SCHEMA.md) is deprecated for runtime configuration; defaults are code-defined.
 //
 // REGION: API
 // api: config::load_and_merge(cli: &crate::cli::Cli) -> crate::Result<crate::config::types::Config>
@@ -40,23 +41,21 @@
 // REGION: TODO-END

 use std::fs;
-use std::path::Path;

 use crate::{cli::Cli, Error, Result};
 use crate::types::*;
 use serde_json::{Map, Value, json};
-use base64::Engine as _;
+use tracing::warn;

-//// Load defaults, merge optional CLI --config, overlay CLI flags (highest precedence),
-//// then consider kernel cmdline topology only if CLI omitted it.
+//// Build configuration from built-in defaults and minimal operational CLI overlays.
 /// Returns a validated Config on success.
 ///
-/// Behavior:
-/// - Starts from built-in defaults (documented in docs/SCHEMA.md)
-/// - Skips implicit /etc reads in initramfs
-/// - If CLI --config is provided, merge that (overrides defaults)
-/// - If kernel cmdline provides `zosstorage.topo=...` and CLI did NOT specify `--topology`, apply it
-/// - Returns Error::Unimplemented when --force is used
+/// Behavior (ADR-0002):
+/// - Start from built-in defaults (code-defined).
+/// - Ignore on-disk YAML and `--config` (deprecated); emit a warning if provided.
+/// - CLI `--topology` is supported and has precedence when provided.
+/// - If CLI does not provide topology, apply kernel cmdline `zosstorage.topology=` (or legacy `zosstorage.topo=`).
+/// - Returns Error::Unimplemented when --force is used.
 pub fn load_and_merge(cli: &Cli) -> Result<Config> {
    if cli.force {
        return Err(Error::Unimplemented("--force flag is not implemented"));
@@ -68,17 +67,17 @@ pub fn load_and_merge(cli: &Cli) -> Result<Config> {
    // 2) (initramfs) Skipped reading default on-disk config to avoid dependency on /etc.
    // If a config is needed, pass it via --config PATH or kernel cmdline `zosstorage.config=...`.

-    // 3) Merge CLI referenced config (if any)
-    if let Some(cfg_path) = &cli.config {
-        let v = load_yaml_value(cfg_path)?;
-        merge_value(&mut merged, v);
+    // 3) Deprecated config file flag: warn and ignore
+    if cli.config.is_some() {
+        warn!("--config is deprecated and ignored (ADR-0002: defaults-only)");
    }
+    // (no file merge)

    // 4) Overlay CLI flags (non-path flags)
    let cli_overlay = cli_overlay_value(cli);
    merge_value(&mut merged, cli_overlay);

-   // 5) Kernel cmdline topology (only if CLI did not specify topology), e.g., `zosstorage.topo=dual-independent`
+   // 5) Kernel cmdline topology override only when CLI did not provide topology
   if cli.topology.is_none() {
       if let Some(topo) = kernel_cmdline_topology() {
           merge_value(&mut merged, json!({"topology": topo.to_string()}));
@@ -204,14 +203,6 @@ fn to_value<T: serde::Serialize>(t: T) -> Result<Value> {
    serde_json::to_value(t).map_err(|e| Error::Other(e.into()))
 }

-fn load_yaml_value(path: &str) -> Result<Value> {
-    let s = fs::read_to_string(path)
-        .map_err(|e| Error::Config(format!("failed to read config file {}: {}", path, e)))?;
-    // Load as generic serde_json::Value for merging flexibility
-    let v: serde_json::Value = serde_yaml::from_str(&s)
-        .map_err(|e| Error::Config(format!("failed to parse YAML {}: {}", path, e)))?;
-    Ok(v)
-}

 /// Merge b into a in-place:
 /// - Objects are merged key-by-key (recursively)
@@ -259,7 +250,7 @@ fn cli_overlay_value(cli: &Cli) -> Value {
        root.insert("device_selection".into(), Value::Object(device_selection));
    }

-    // topology override via --topology (avoid moving out of borrowed field)
+    // topology override via --topology (takes precedence over kernel cmdline)
    if let Some(t) = cli.topology.as_ref() {
        root.insert("topology".into(), Value::String(t.to_string()));
    }
@@ -267,63 +258,18 @@ fn cli_overlay_value(cli: &Cli) -> Value {
    Value::Object(root)
 }

-enum KernelConfigSource {
-    Path(String),
-    /// Raw YAML from a data: URL payload after decoding (if base64-encoded).
-    Data(String),
-}
-
-/// Resolve a config from kernel cmdline key `zosstorage.config=`.
-/// Supports:
-/// - absolute paths (e.g., /run/zos.yaml)
-/// - file:/absolute/path
-/// - data:application/x-yaml;base64,BASE64CONTENT
-/// Returns Ok(None) when key absent.
-fn kernel_cmdline_config_source() -> Result<Option<KernelConfigSource>> {
+//// Parse kernel cmdline for topology override.
+//// Accepts `zosstorage.topology=` and legacy alias `zosstorage.topo=`.
+pub fn kernel_cmdline_topology() -> Option<Topology> {
    let cmdline = fs::read_to_string("/proc/cmdline").unwrap_or_default();
    for token in cmdline.split_whitespace() {
-        if let Some(rest) = token.strip_prefix("zosstorage.config=") {
-            let mut val = rest.to_string();
-            // Trim surrounding quotes if any
-            if (val.starts_with('"') && val.ends_with('"')) || (val.starts_with('\'') && val.ends_with('\'')) {
-                val = val[1..val.len() - 1].to_string();
+        let mut val_opt = None;
+        if let Some(v) = token.strip_prefix("zosstorage.topology=") {
+            val_opt = Some(v);
+        } else if let Some(v) = token.strip_prefix("zosstorage.topo=") {
+            val_opt = Some(v);
        }
-            if let Some(path) = val.strip_prefix("file:") {
-                return Ok(Some(KernelConfigSource::Path(path.to_string())));
-            }
-            if let Some(data_url) = val.strip_prefix("data:") {
-                // data:[<mediatype>][;base64],<data>
-                // Find comma separating the header and payload
-                if let Some(idx) = data_url.find(',') {
-                    let (header, payload) = data_url.split_at(idx);
-                    let payload = &payload[1..]; // skip the comma
-                    let is_base64 = header.split(';').any(|seg| seg.eq_ignore_ascii_case("base64"));
-                    let yaml = if is_base64 {
-                        let decoded = base64::engine::general_purpose::STANDARD
-                            .decode(payload.as_bytes())
-                            .map_err(|e| Error::Config(format!("invalid base64 in data: URL: {}", e)))?;
-                        String::from_utf8(decoded)
-                            .map_err(|e| Error::Config(format!("data: URL payload not UTF-8: {}", e)))?
-                    } else {
-                        payload.to_string()
-                    };
-                    return Ok(Some(KernelConfigSource::Data(yaml)));
-                } else {
-                    return Err(Error::Config("malformed data: URL (missing comma)".into()));
-                }
-            }
-            // Treat as direct path
-            return Ok(Some(KernelConfigSource::Path(val)));
-        }
-    }
-    Ok(None)
-}
-
-fn kernel_cmdline_topology() -> Option<Topology> {
-    let cmdline = fs::read_to_string("/proc/cmdline").unwrap_or_default();
-    for token in cmdline.split_whitespace() {
-        if let Some(mut val) = token.strip_prefix("zosstorage.topo=") {
-            // Trim surrounding quotes if any
+        if let Some(mut val) = val_opt {
            if (val.starts_with('"') && val.ends_with('"')) || (val.starts_with('\'') && val.ends_with('\'')) {
                val = &val[1..val.len() - 1];
            }
@@ -338,7 +284,6 @@ fn kernel_cmdline_topology() -> Option<Topology> {

 /// Helper to parse known topology tokens in kebab- or snake-case.
 fn parse_topology_token(s: &str) -> Option<Topology> {
-    // Normalize underscores to hyphens for simpler matching.
    let k = s.trim().to_ascii_lowercase().replace('_', "-");
    match k.as_str() {
        "btrfs-single" => Some(Topology::BtrfsSingle),
--- a/src/main.rs
+++ b/src/main.rs
@@ -54,6 +54,8 @@ fn real_main() -> Result<()> {
        .with_apply(cli.apply)
        .with_mount_existing(cli.mount_existing)
        .with_report_current(cli.report_current)
-        .with_report_path(cli.report.clone());
+        .with_report_path(cli.report.clone())
+        .with_topology_from_cli(cli.topology.is_some())
+        .with_topology_from_cmdline(config::loader::kernel_cmdline_topology().is_some() && cli.topology.is_none());
    orchestrator::run(&ctx)
 }
--- a/src/mount/ops.rs
+++ b/src/mount/ops.rs
@@ -41,9 +41,11 @@ use crate::{
    util::{run_cmd, run_cmd_capture, which_tool},
    Error, Result,
 };
+use std::collections::HashMap;
 use std::fs::{create_dir_all, File};
 use std::io::Write;
 use std::path::Path;
+use tracing::info;

 const ROOT_BASE: &str = "/var/mounts";
 const TARGET_SYSTEM: &str = "/var/cache/system";
@@ -52,6 +54,71 @@ const TARGET_MODULES: &str = "/var/cache/modules";
 const TARGET_VM_META: &str = "/var/cache/vm-meta";
 const SUBVOLS: &[&str] = &["system", "etc", "modules", "vm-meta"];

+#[derive(Debug, Clone)]
+struct ExistingMount {
+    source: String,
+    fstype: String,
+    options: String,
+}
+
+fn current_mounts() -> HashMap<String, ExistingMount> {
+    let mut map = HashMap::new();
+    if let Ok(content) = std::fs::read_to_string("/proc/self/mountinfo") {
+        for line in content.lines() {
+            let parts: Vec<&str> = line.split_whitespace().collect();
+            if parts.len() < 7 {
+                continue;
+            }
+            let target = parts[4].to_string();
+            let mount_options = parts[5].to_string();
+            if let Some(idx) = parts.iter().position(|p| *p == "-") {
+                if idx + 2 < parts.len() {
+                    let fstype = parts[idx + 1].to_string();
+                    let source = parts[idx + 2].to_string();
+                    let super_opts = if idx + 3 < parts.len() {
+                        parts[idx + 3].to_string()
+                    } else {
+                        String::new()
+                    };
+                    let combined_options = if super_opts.is_empty() {
+                        mount_options.clone()
+                    } else {
+                        format!("{mount_options},{super_opts}")
+                    };
+                    map.insert(
+                        target,
+                        ExistingMount {
+                            source,
+                            fstype,
+                            options: combined_options,
+                        },
+                    );
+                }
+            }
+        }
+    }
+    map
+}
+
+fn source_matches_uuid(existing_source: &str, uuid: &str) -> bool {
+    if existing_source == format!("UUID={}", uuid) {
+        return true;
+    }
+    if let Some(existing_uuid) = existing_source.strip_prefix("UUID=") {
+        return existing_uuid == uuid;
+    }
+    if existing_source.starts_with("/dev/") {
+        let uuid_path = Path::new("/dev/disk/by-uuid").join(uuid);
+        if let (Ok(existing_canon), Ok(uuid_canon)) = (
+            std::fs::canonicalize(existing_source),
+            std::fs::canonicalize(&uuid_path),
+        ) {
+            return existing_canon == uuid_canon;
+        }
+    }
+    false
+}
+
 #[derive(Debug, Clone)]
 pub struct PlannedMount {
    pub uuid: String,     // UUID string without prefix
@@ -189,11 +256,37 @@ pub fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>> {
            .map_err(|e| Error::Mount(format!("failed to create dir {}: {}", sm.target, e)))?;
    }

-    let mut results: Vec<MountResult> = Vec::new();
+    let mut results_map: HashMap<String, MountResult> = HashMap::new();
+    let mut existing_mounts = current_mounts();

    // Root mounts
    for pm in &plan.root_mounts {
        let source = format!("UUID={}", pm.uuid);
+        if let Some(existing) = existing_mounts.get(pm.target.as_str()) {
+            if source_matches_uuid(&existing.source, &pm.uuid) {
+                info!(
+                    "mount::apply_mounts: target {} already mounted; skipping",
+                    pm.target
+                );
+                let existing_fstype = existing.fstype.clone();
+                let existing_options = existing.options.clone();
+                results_map
+                    .entry(pm.target.clone())
+                    .or_insert_with(|| MountResult {
+                        source: source.clone(),
+                        target: pm.target.clone(),
+                        fstype: existing_fstype,
+                        options: existing_options,
+                    });
+                continue;
+            } else {
+                return Err(Error::Mount(format!(
+                    "target {} already mounted by {} (expected UUID={})",
+                    pm.target, existing.source, pm.uuid
+                )));
+            }
+        }
+
        let args = [
            mount_tool.as_str(),
            "-t",
@@ -204,12 +297,23 @@ pub fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>> {
            pm.target.as_str(),
        ];
        run_cmd(&args)?;
-        results.push(MountResult {
+        existing_mounts.insert(
+            pm.target.clone(),
+            ExistingMount {
+                source: source.clone(),
+                fstype: pm.fstype.clone(),
+                options: pm.options.clone(),
+            },
+        );
+        results_map.insert(
+            pm.target.clone(),
+            MountResult {
                source,
                target: pm.target.clone(),
                fstype: pm.fstype.clone(),
                options: pm.options.clone(),
-        });
+            },
+        );
    }

    // Subvolume creation (create-if-missing) and mounts for the primary
@@ -279,6 +383,31 @@ pub fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>> {
    // Subvol mounts
    for sm in &plan.subvol_mounts {
        let source = format!("UUID={}", sm.uuid);
+        if let Some(existing) = existing_mounts.get(sm.target.as_str()) {
+            if source_matches_uuid(&existing.source, &sm.uuid) {
+                info!(
+                    "mount::apply_mounts: target {} already mounted; skipping",
+                    sm.target
+                );
+                let existing_fstype = existing.fstype.clone();
+                let existing_options = existing.options.clone();
+                results_map
+                    .entry(sm.target.clone())
+                    .or_insert_with(|| MountResult {
+                        source: source.clone(),
+                        target: sm.target.clone(),
+                        fstype: existing_fstype,
+                        options: existing_options,
+                    });
+                continue;
+            } else {
+                return Err(Error::Mount(format!(
+                    "target {} already mounted by {} (expected UUID={})",
+                    sm.target, existing.source, sm.uuid
+                )));
+            }
+        }
+
        let args = [
            mount_tool.as_str(),
            "-t",
@@ -289,14 +418,28 @@ pub fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>> {
            sm.target.as_str(),
        ];
        run_cmd(&args)?;
-        results.push(MountResult {
+        existing_mounts.insert(
+            sm.target.clone(),
+            ExistingMount {
+                source: source.clone(),
+                fstype: sm.fstype.clone(),
+                options: sm.options.clone(),
+            },
+        );
+        results_map.insert(
+            sm.target.clone(),
+            MountResult {
                source,
                target: sm.target.clone(),
                fstype: sm.fstype.clone(),
                options: sm.options.clone(),
-        });
+            },
+        );
    }

+    let mut results: Vec<MountResult> = results_map.into_values().collect();
+    results.sort_by(|a, b| a.target.cmp(&b.target));
+
    Ok(results)
 }

@@ -306,19 +449,24 @@ pub fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()> {
        return Ok(());
    }

-    // Filter only the four subvol targets
+    // Partition mount results into runtime root mounts and final subvolume targets.
+    let mut root_entries: Vec<&MountResult> = mounts
+        .iter()
+        .filter(|m| m.target.starts_with(ROOT_BASE))
+        .collect();
    let wanted = [TARGET_ETC, TARGET_MODULES, TARGET_SYSTEM, TARGET_VM_META];
-    let mut entries: Vec<&MountResult> = mounts
+    let mut subvol_entries: Vec<&MountResult> = mounts
        .iter()
        .filter(|m| wanted.contains(&m.target.as_str()))
        .collect();

-    // Sort by target path ascending to be deterministic
-    entries.sort_by(|a, b| a.target.cmp(&b.target));
+    // Sort by target path ascending to be deterministic (roots before subvols).
+    root_entries.sort_by(|a, b| a.target.cmp(&b.target));
+    subvol_entries.sort_by(|a, b| a.target.cmp(&b.target));

-    // Compose lines
+    // Compose lines: include all root mounts first, followed by the four subvol targets.
    let mut lines: Vec<String> = Vec::new();
-    for m in entries {
+    for m in root_entries.into_iter().chain(subvol_entries.into_iter()) {
        // m.source already "UUID=..."
        let line = format!(
            "{} {} {} {} 0 0",
--- a/src/orchestrator/run.rs
+++ b/src/orchestrator/run.rs
@@ -43,11 +43,12 @@
 //! - Report generation and write

 use crate::{
-    types::Config,
+    types::{Config, Topology},
    logging::LogOptions,
    device::{discover, DeviceFilter, Disk},
    idempotency,
    partition,
+    report::StateReport,
    fs as zfs,
    Error, Result,
 };
@@ -75,6 +76,10 @@ pub struct Context {
    pub report_current: bool,
    /// Optional report path override (when provided by CLI --report).
    pub report_path_override: Option<String>,
+    /// True when topology was provided via CLI (--topology), giving it precedence.
+    pub topo_from_cli: bool,
+    /// True when topology was provided via kernel cmdline, giving it precedence if CLI omitted it.
+    pub topo_from_cmdline: bool,
 }

 impl Context {
@@ -88,6 +93,8 @@ impl Context {
            mount_existing: false,
            report_current: false,
            report_path_override: None,
+            topo_from_cli: false,
+            topo_from_cmdline: false,
        }
    }

@@ -136,6 +143,44 @@ impl Context {
        self.report_current = report_current;
        self
    }
+
+    /// Mark that topology was provided via CLI (--topology).
+    pub fn with_topology_from_cli(mut self, v: bool) -> Self {
+        self.topo_from_cli = v;
+        self
+    }
+
+    /// Mark that topology was provided via kernel cmdline (zosstorage.topology=).
+    pub fn with_topology_from_cmdline(mut self, v: bool) -> Self {
+        self.topo_from_cmdline = v;
+        self
+    }
+}
+#[derive(Debug, Clone, Copy)]
+enum ProvisioningMode {
+    Apply,
+    Preview,
+}
+
+#[derive(Debug, Clone, Copy)]
+enum AutoDecision {
+    Apply,
+    MountExisting,
+}
+
+#[derive(Debug)]
+struct AutoSelection {
+    decision: AutoDecision,
+    fs_results: Option<Vec<zfs::FsResult>>,
+    state: Option<StateReport>,
+}
+#[derive(Debug, Clone, Copy)]
+enum ExecutionMode {
+    ReportCurrent,
+    MountExisting,
+    Apply,
+    Preview,
+    Auto,
 }

 /// Run the one-shot provisioning flow.
@@ -143,9 +188,8 @@ impl Context {
 /// Returns Ok(()) on success and also on success-noop when already provisioned.
 /// Any validation or execution failure aborts with an error.
 pub fn run(ctx: &Context) -> Result<()> {
-    info!("orchestrator: starting run() with topology {:?}", ctx.cfg.topology);
+    info!("orchestrator: starting run()");

-    // Enforce mutually exclusive execution modes among: --mount-existing, --report-current, --apply
    let selected_modes =
        (ctx.mount_existing as u8) +
        (ctx.report_current as u8) +
@@ -156,79 +200,81 @@ pub fn run(ctx: &Context) -> Result<()> {
        ));
    }

-    // Mode 1: Mount existing filesystems (non-destructive), based on on-disk headers.
-    if ctx.mount_existing {
-        info!("orchestrator: mount-existing mode");
-        let fs_results = zfs::probe_existing_filesystems()?;
-        if fs_results.is_empty() {
-            return Err(Error::Mount(
-                "no existing filesystems with reserved labels (ZOSBOOT/ZOSDATA) were found".into(),
-            ));
-        }
-        let mplan = crate::mount::plan_mounts(&fs_results, &ctx.cfg)?;
-        let mres = crate::mount::apply_mounts(&mplan)?;
-        crate::mount::maybe_write_fstab(&mres, &ctx.cfg)?;
+    let preview_requested = ctx.show || ctx.report_path_override.is_some();

-        // Optional JSON summary for mount-existing
-        if ctx.show || ctx.report_path_override.is_some() || ctx.report_current {
-            let now = format_rfc3339(SystemTime::now()).to_string();
-            let fs_json: Vec<serde_json::Value> = fs_results
-                .iter()
-                .map(|r| {
-                    let kind_str = match r.kind {
-                        zfs::FsKind::Vfat => "vfat",
-                        zfs::FsKind::Btrfs => "btrfs",
-                        zfs::FsKind::Bcachefs => "bcachefs",
+    let initial_mode = if ctx.report_current {
+        ExecutionMode::ReportCurrent
+    } else if ctx.mount_existing {
+        ExecutionMode::MountExisting
+    } else if ctx.apply {
+        ExecutionMode::Apply
+    } else if preview_requested {
+        ExecutionMode::Preview
+    } else {
+        ExecutionMode::Auto
    };
-                    json!({
-                        "kind": kind_str,
-                        "uuid": r.uuid,
-                        "label": r.label,
-                        "devices": r.devices,
-                    })
-                })
-                .collect();

-            let mounts_json: Vec<serde_json::Value> = mres
-                .iter()
-                .map(|m| {
-                    json!({
-                        "source": m.source,
-                        "target": m.target,
-                        "fstype": m.fstype,
-                        "options": m.options,
-                    })
-                })
-                .collect();
+    match initial_mode {
+        ExecutionMode::ReportCurrent => run_report_current(ctx),
+        ExecutionMode::MountExisting => run_mount_existing(ctx, None, None),
+        ExecutionMode::Apply => run_provisioning(ctx, ProvisioningMode::Apply, None),
+        ExecutionMode::Preview => run_provisioning(ctx, ProvisioningMode::Preview, None),
+        ExecutionMode::Auto => {
+            let selection = auto_select_mode(ctx)?;
+            match selection.decision {
+                AutoDecision::MountExisting => {
+                    run_mount_existing(ctx, selection.fs_results, selection.state)
+                }
+                AutoDecision::Apply => {
+                    run_provisioning(ctx, ProvisioningMode::Apply, selection.state)
+                }
+            }
+        }
+    }
+}

-            let summary = json!({
-                "version": "v1",
-                "timestamp": now,
-                "status": "mounted_existing",
-                "filesystems": fs_json,
-                "mounts": mounts_json,
+fn auto_select_mode(ctx: &Context) -> Result<AutoSelection> {
+    info!("orchestrator: auto-selecting execution mode");
+    let state = idempotency::detect_existing_state()?;
+    let fs_results = zfs::probe_existing_filesystems()?;
+
+    if let Some(state) = state {
+        info!("orchestrator: provisioned state detected; attempting mount-existing flow");
+        return Ok(AutoSelection {
+            decision: AutoDecision::MountExisting,
+            fs_results: if fs_results.is_empty() { None } else { Some(fs_results) },
+            state: Some(state),
        });
-
-            if ctx.show || ctx.report_current {
-                println!("{}", summary);
-            }
-            if let Some(path) = &ctx.report_path_override {
-                fs::write(path, summary.to_string()).map_err(|e| {
-                    Error::Report(format!("failed to write report to {}: {}", path, e))
-                })?;
-                info!("orchestrator: wrote mount-existing report to {}", path);
-            }
    }

-        return Ok(());
+    if !fs_results.is_empty() {
+        info!(
+            "orchestrator: detected {} filesystem(s) with reserved labels; selecting mount-existing",
+            fs_results.len()
+        );
+        return Ok(AutoSelection {
+            decision: AutoDecision::MountExisting,
+            fs_results: Some(fs_results),
+            state: None,
+        });
    }

-    // Mode 3: Report current initialized filesystems and mounts (non-destructive).
-    if ctx.report_current {
+    info!(
+        "orchestrator: no provisioned state or labeled filesystems detected; selecting apply mode (topology={:?})",
+        ctx.cfg.topology
+    );
+
+    Ok(AutoSelection {
+        decision: AutoDecision::Apply,
+        fs_results: None,
+        state: None,
+    })
+}
+
+fn run_report_current(ctx: &Context) -> Result<()> {
    info!("orchestrator: report-current mode");
    let fs_results = zfs::probe_existing_filesystems()?;

-        // Parse /proc/mounts and include only our relevant targets.
    let mounts_content = fs::read_to_string("/proc/mounts").unwrap_or_default();
    let mounts_json: Vec<serde_json::Value> = mounts_content
        .lines()
@@ -282,7 +328,6 @@ pub fn run(ctx: &Context) -> Result<()> {
        "mounts": mounts_json
    });

-        // In report-current mode, default to stdout; also honor --report path when provided.
    println!("{}", summary);
    if let Some(path) = &ctx.report_path_override {
        fs::write(path, summary.to_string()).map_err(|e| {
@@ -290,60 +335,145 @@ pub fn run(ctx: &Context) -> Result<()> {
        })?;
        info!("orchestrator: wrote report-current to {}", path);
    }
-        return Ok(());
+    Ok(())
 }

-    // Default path: plan (and optionally apply) for empty-disk initialization workflow.
+fn run_mount_existing(
+    ctx: &Context,
+    fs_results_override: Option<Vec<zfs::FsResult>>,
+    state_hint: Option<StateReport>,
+) -> Result<()> {
+    info!("orchestrator: mount-existing mode");
+    let fs_results = match fs_results_override {
+        Some(results) => results,
+        None => zfs::probe_existing_filesystems()?,
+    };
+    if fs_results.is_empty() {
+        return Err(Error::Mount(
+            "no existing filesystems with reserved labels (ZOSBOOT/ZOSDATA) were found".into(),
+        ));
+    }

-    // 1) Idempotency pre-flight: if already provisioned, optionally emit summary then exit success.
-    match idempotency::detect_existing_state()? {
-        Some(state) => {
-            info!("orchestrator: already provisioned");
-            if ctx.show || ctx.report_path_override.is_some() {
+    let mplan = crate::mount::plan_mounts(&fs_results, &ctx.cfg)?;
+    let mres = crate::mount::apply_mounts(&mplan)?;
+    crate::mount::maybe_write_fstab(&mres, &ctx.cfg)?;
+
+    if ctx.show || ctx.report_path_override.is_some() || ctx.report_current {
        let now = format_rfc3339(SystemTime::now()).to_string();
-                let state_json = to_value(&state)
-                    .map_err(|e| Error::Report(format!("failed to serialize StateReport: {}", e)))?;
-                let summary = json!({
+        let fs_json: Vec<serde_json::Value> = fs_results
+            .iter()
+            .map(|r| {
+                let kind_str = match r.kind {
+                    zfs::FsKind::Vfat => "vfat",
+                    zfs::FsKind::Btrfs => "btrfs",
+                    zfs::FsKind::Bcachefs => "bcachefs",
+                };
+                json!({
+                    "kind": kind_str,
+                    "uuid": r.uuid,
+                    "label": r.label,
+                    "devices": r.devices,
+                })
+            })
+            .collect();
+
+        let mounts_json: Vec<serde_json::Value> = mres
+            .iter()
+            .map(|m| {
+                json!({
+                    "source": m.source,
+                    "target": m.target,
+                    "fstype": m.fstype,
+                    "options": m.options,
+                })
+            })
+            .collect();
+
+        let mut summary = json!({
            "version": "v1",
            "timestamp": now,
-                    "status": "already_provisioned",
-                    "state": state_json
+            "status": "mounted_existing",
+            "filesystems": fs_json,
+            "mounts": mounts_json,
        });
-                if ctx.show {
+
+        if let Some(state) = state_hint {
+            if let Ok(state_json) = to_value(&state) {
+                if let Some(obj) = summary.as_object_mut() {
+                    obj.insert("state".to_string(), state_json);
+                }
+            }
+        }
+
+        if ctx.show || ctx.report_current {
            println!("{}", summary);
        }
        if let Some(path) = &ctx.report_path_override {
            fs::write(path, summary.to_string()).map_err(|e| {
                Error::Report(format!("failed to write report to {}: {}", path, e))
            })?;
-                    info!("orchestrator: wrote idempotency report to {}", path);
-                }
-            }
-            return Ok(());
-        }
-        None => {
-            debug!("orchestrator: not provisioned; continuing");
+            info!("orchestrator: wrote mount-existing report to {}", path);
        }
    }

-    // 2) Device discovery using compiled filter from config.
+    Ok(())
+}
+
+fn run_provisioning(
+    ctx: &Context,
+    mode: ProvisioningMode,
+    state_hint: Option<StateReport>,
+) -> Result<()> {
+    let preview_outputs = ctx.show || ctx.report_path_override.is_some();
+
+    let mut state_opt = state_hint;
+    if state_opt.is_none() {
+        state_opt = idempotency::detect_existing_state()?;
+    }
+
+    if let Some(state) = state_opt {
+        info!("orchestrator: already provisioned; ensuring mounts are active");
+        return run_mount_existing(ctx, None, Some(state));
+    }
+
    let filter = build_device_filter(&ctx.cfg)?;
    let disks = discover(&filter)?;
    info!("orchestrator: discovered {} eligible disk(s)", disks.len());

-    // 3) Emptiness enforcement: skip in preview mode (--show/--report) to allow planning output.
-    let preview = ctx.show || ctx.report_path_override.is_some();
-    if ctx.cfg.partitioning.require_empty_disks && !preview {
+    if ctx.cfg.partitioning.require_empty_disks {
+        if matches!(mode, ProvisioningMode::Apply) {
            enforce_empty_disks(&disks)?;
            info!("orchestrator: all target disks verified empty");
-    } else if ctx.cfg.partitioning.require_empty_disks && preview {
-        warn!("orchestrator: preview mode detected (--show/--report); skipping empty-disk enforcement");
        } else {
+            warn!("orchestrator: preview mode detected (--show/--report); skipping empty-disk enforcement");
+        }
+    } else if matches!(mode, ProvisioningMode::Apply) {
        warn!("orchestrator: require_empty_disks=false; proceeding without emptiness enforcement");
    }

-    // 4) Partition planning (declarative).
-    let plan = partition::plan_partitions(&disks, &ctx.cfg)?;
+    let effective_cfg = {
+        let mut c = ctx.cfg.clone();
+        if !(ctx.topo_from_cli || ctx.topo_from_cmdline) {
+            let auto_topo = if disks.len() == 1 {
+                Topology::BtrfsSingle
+            } else if disks.len() == 2 {
+                Topology::DualIndependent
+            } else {
+                Topology::BtrfsRaid1
+            };
+            if c.topology != auto_topo {
+                info!("orchestrator: topology auto-selected {:?}", auto_topo);
+                c.topology = auto_topo;
+            } else {
+                info!("orchestrator: using configured topology {:?}", c.topology);
+            }
+        } else {
+            info!("orchestrator: using overridden topology {:?}", c.topology);
+        }
+        c
+    };
+
+    let plan = partition::plan_partitions(&disks, &effective_cfg)?;
    debug!(
        "orchestrator: partition plan ready (alignment={} MiB, disks={})",
        plan.alignment_mib,
@@ -353,8 +483,7 @@ pub fn run(ctx: &Context) -> Result<()> {
        debug!("plan for {}: {} part(s)", dp.disk.path, dp.parts.len());
    }

-    // Apply mode: perform destructive partition application now.
-    if ctx.apply {
+    if matches!(mode, ProvisioningMode::Apply) {
        info!("orchestrator: apply mode enabled; applying partition plan");
        let part_results = partition::apply_partitions(&plan)?;
        info!(
@@ -363,34 +492,28 @@ pub fn run(ctx: &Context) -> Result<()> {
            part_results.len()
        );

-        // Filesystem planning and creation
-        let fs_plan = zfs::plan_filesystems(&part_results, &ctx.cfg)?;
+        let fs_plan = zfs::plan_filesystems(&part_results, &effective_cfg)?;
        info!(
            "orchestrator: filesystem plan contains {} spec(s)",
            fs_plan.specs.len()
        );
-        let fs_results = zfs::make_filesystems(&fs_plan, &ctx.cfg)?;
+        let fs_results = zfs::make_filesystems(&fs_plan, &effective_cfg)?;
        info!("orchestrator: created {} filesystem(s)", fs_results.len());

-        // Mount planning and application
-        let mplan = crate::mount::plan_mounts(&fs_results, &ctx.cfg)?;
+        let mplan = crate::mount::plan_mounts(&fs_results, &effective_cfg)?;
        let mres = crate::mount::apply_mounts(&mplan)?;
-        crate::mount::maybe_write_fstab(&mres, &ctx.cfg)?;
+        crate::mount::maybe_write_fstab(&mres, &effective_cfg)?;
        return Ok(());
    }

-    // Preview-only path
    info!("orchestrator: pre-flight complete (idempotency checked, devices discovered, plan computed)");

-    // Optional: emit JSON summary via --show or write via --report
-    if ctx.show || ctx.report_path_override.is_some() {
-        let summary = build_summary_json(&disks, &plan, &ctx.cfg)?;
+    if preview_outputs {
+        let summary = build_summary_json(&disks, &plan, &effective_cfg)?;
        if ctx.show {
-            // Print compact JSON to stdout
            println!("{}", summary);
        }
        if let Some(path) = &ctx.report_path_override {
-            // Best-effort write (non-atomic for now, pending report::write_report implementation)
            fs::write(path, summary.to_string()).map_err(|e| {
                Error::Report(format!("failed to write report to {}: {}", path, e))
            })?;
@@ -511,14 +634,7 @@ fn build_summary_json(disks: &[Disk], plan: &partition::PartitionPlan, cfg: &Con
    }

    // Decide filesystem kinds and planned mountpoints (template) from plan + cfg.topology
-    let topo_str = match cfg.topology {
-        crate::types::Topology::BtrfsSingle => "btrfs_single",
-        crate::types::Topology::BcachefsSingle => "bcachefs_single",
-        crate::types::Topology::DualIndependent => "dual_independent",
-        crate::types::Topology::SsdHddBcachefs => "ssd_hdd_bcachefs",
-        crate::types::Topology::Bcachefs2Copy => "bcachefs2_copy",
-        crate::types::Topology::BtrfsRaid1 => "btrfs_raid1",
-    };
+    let topo_str = cfg.topology.to_string();

    // Count roles across plan to infer filesystems
    let mut esp_count = 0usize;
--- a/src/types.rs
+++ b/src/types.rs
@@ -38,7 +38,7 @@ pub struct DeviceSelection {
    pub min_size_gib: u64,
 }

-#[derive(Debug, Clone, Copy, Serialize, Deserialize, ValueEnum)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ValueEnum)]
 #[serde(rename_all = "snake_case")]
 #[value(rename_all = "snake_case")]
 pub enum Topology {