diff --git a/Makefile b/Makefile
index 03708b0a7..5b47e223e 100644
--- a/Makefile
+++ b/Makefile
@@ -15,22 +15,9 @@ all: bin manpages
 bin:
 	cargo build --release --features "$(CARGO_FEATURES)"
 
-# Generate man pages from markdown sources
-MAN5_SOURCES := $(wildcard docs/src/man/*.5.md)
-MAN8_SOURCES := $(wildcard docs/src/man/*.8.md)
-TARGETMAN := target/man
-MAN5_TARGETS := $(patsubst docs/src/man/%.5.md,$(TARGETMAN)/%.5,$(MAN5_SOURCES))
-MAN8_TARGETS := $(patsubst docs/src/man/%.8.md,$(TARGETMAN)/%.8,$(MAN8_SOURCES))
-
-$(TARGETMAN)/%.5: docs/src/man/%.5.md
-	@mkdir -p $(TARGETMAN)
-	go-md2man -in $< -out $@
-
-$(TARGETMAN)/%.8: docs/src/man/%.8.md
-	@mkdir -p $(TARGETMAN)
-	go-md2man -in $< -out $@
-
-manpages: $(MAN5_TARGETS) $(MAN8_TARGETS)
+.PHONY: manpages
+manpages:
+	cargo run --package xtask -- manpages
 
 STORAGE_RELATIVE_PATH ?= $(shell realpath -m -s --relative-to="$(prefix)/lib/bootc/storage" /sysroot/ostree/bootc/storage)
 install:
@@ -41,12 +28,8 @@ install:
 	ln -s "$(STORAGE_RELATIVE_PATH)" "$(DESTDIR)$(prefix)/lib/bootc/storage"
 	install -D -m 0755 crates/cli/bootc-generator-stub $(DESTDIR)$(prefix)/lib/systemd/system-generators/bootc-systemd-generator 
 	install -d $(DESTDIR)$(prefix)/lib/bootc/install
-	if [ -n "$(MAN5_TARGETS)" ]; then \
-	  install -D -m 0644 -t $(DESTDIR)$(prefix)/share/man/man5 $(MAN5_TARGETS); \
-	fi
-	if [ -n "$(MAN8_TARGETS)" ]; then \
-	  install -D -m 0644 -t $(DESTDIR)$(prefix)/share/man/man8 $(MAN8_TARGETS); \
-	fi
+	install -D -m 0644 -t $(DESTDIR)$(prefix)/share/man/man5 target/man/*.5; \
+	install -D -m 0644 -t $(DESTDIR)$(prefix)/share/man/man8 target/man/*.8; \
 	install -D -m 0644 -t $(DESTDIR)/$(prefix)/lib/systemd/system systemd/*.service systemd/*.timer systemd/*.path systemd/*.target
 	install -d -m 0755 $(DESTDIR)/$(prefix)/lib/systemd/system/multi-user.target.wants
 	ln -s ../bootc-status-updated.path $(DESTDIR)/$(prefix)/lib/systemd/system/multi-user.target.wants/bootc-status-updated.path
diff --git a/crates/lib/src/cli_json.rs b/crates/lib/src/cli_json.rs
index d1017ef0d..0b3472540 100644
--- a/crates/lib/src/cli_json.rs
+++ b/crates/lib/src/cli_json.rs
@@ -13,6 +13,7 @@ pub struct CliOption {
     pub help: String,
     pub possible_values: Vec<String>,
     pub required: bool,
+    pub is_boolean: bool,
 }
 
 /// Representation of a CLI command for JSON export
@@ -73,16 +74,27 @@ pub fn command_to_json(cmd: &Command) -> CliCommand {
 
             let help = arg.get_help().map(|h| h.to_string()).unwrap_or_default();
 
+            // For boolean flags, don't show a value name
+            // Boolean flags use SetTrue or SetFalse actions and don't take values
+            let is_boolean = matches!(
+                arg.get_action(),
+                clap::ArgAction::SetTrue | clap::ArgAction::SetFalse
+            );
+            let value_name = if is_boolean {
+                None
+            } else {
+                arg.get_value_names()
+                    .and_then(|names| names.first())
+                    .map(|s| s.to_string())
+            };
+
             options.push(CliOption {
                 long: arg
                     .get_long()
                     .map(String::from)
                     .unwrap_or_else(|| id.to_string()),
                 short: arg.get_short().map(|c| c.to_string()),
-                value_name: arg
-                    .get_value_names()
-                    .and_then(|names| names.first())
-                    .map(|s| s.to_string()),
+                value_name,
                 default: arg
                     .get_default_values()
                     .first()
@@ -91,6 +103,7 @@ pub fn command_to_json(cmd: &Command) -> CliCommand {
                 help,
                 possible_values,
                 required: arg.is_required_set(),
+                is_boolean,
             });
         }
     }
diff --git a/crates/xtask/src/man.rs b/crates/xtask/src/man.rs
index 42ba4b7c9..28d512517 100644
--- a/crates/xtask/src/man.rs
+++ b/crates/xtask/src/man.rs
@@ -26,6 +26,8 @@ pub struct CliOption {
     pub possible_values: Vec<String>,
     /// Whether the option is required
     pub required: bool,
+    /// Whether this is a boolean flag
+    pub is_boolean: bool,
 }
 
 /// Represents a CLI command from the JSON dump
@@ -132,7 +134,8 @@ fn format_options_as_markdown(options: &[CliOption], positionals: &[CliPositiona
         // Add long flag
         flag_line.push_str(&format!("**--{}**", opt.long));
 
-        // Add value name if option takes argument
+        // Add value name if option takes argument (but not for boolean flags)
+        // Boolean flags are detected by having no value_name (set to None in cli_json.rs)
         if let Some(value_name) = &opt.value_name {
             flag_line.push_str(&format!("=*{}*", value_name));
         }
@@ -140,8 +143,8 @@ fn format_options_as_markdown(options: &[CliOption], positionals: &[CliPositiona
         result.push_str(&format!("{}\n\n", flag_line));
         result.push_str(&format!("    {}\n\n", opt.help));
 
-        // Add possible values for enums
-        if !opt.possible_values.is_empty() {
+        // Add possible values for enums (but not for boolean flags)
+        if !opt.possible_values.is_empty() && !opt.is_boolean {
             result.push_str("    Possible values:\n");
             for value in &opt.possible_values {
                 result.push_str(&format!("    - {}\n", value));
@@ -191,10 +194,12 @@ pub fn update_markdown_with_subcommands(
         before, begin_marker, generated_subcommands, end_marker, after
     );
 
-    fs::write(markdown_path, new_content)
-        .with_context(|| format!("Writing to {}", markdown_path))?;
-
-    println!("Updated subcommands in {}", markdown_path);
+    // Only write if content has changed to avoid updating mtime unnecessarily
+    if new_content != content {
+        fs::write(markdown_path, new_content)
+            .with_context(|| format!("Writing to {}", markdown_path))?;
+        println!("Updated subcommands in {}", markdown_path);
+    }
     Ok(())
 }
 
@@ -238,10 +243,12 @@ pub fn update_markdown_with_options(
         format!("{}\n\n{}\n{}{}", before, begin_marker, end_marker, after)
     };
 
-    fs::write(markdown_path, new_content)
-        .with_context(|| format!("Writing to {}", markdown_path))?;
-
-    println!("Updated {}", markdown_path);
+    // Only write if content has changed to avoid updating mtime unnecessarily
+    if new_content != content {
+        fs::write(markdown_path, new_content)
+            .with_context(|| format!("Writing to {}", markdown_path))?;
+        println!("Updated {}", markdown_path);
+    }
     Ok(())
 }
 
@@ -374,21 +381,6 @@ pub fn sync_all_man_pages(sh: &Shell) -> Result<()> {
     Ok(())
 }
 
-/// Test the sync workflow
-pub fn test_sync_workflow(sh: &Shell) -> Result<()> {
-    println!("🧪 Testing man page sync workflow...");
-
-    // Create a backup of current files
-    let test_dir = "target/test-sync";
-    sh.create_dir(test_dir)?;
-
-    // Run sync
-    sync_all_man_pages(sh)?;
-
-    println!("✅ Sync workflow test completed successfully");
-    Ok(())
-}
-
 /// Generate man pages from hand-written markdown sources
 pub fn generate_man_pages(sh: &Shell) -> Result<()> {
     let man_src_dir = Utf8Path::new("docs/src/man");
@@ -432,18 +424,31 @@ pub fn generate_man_pages(sh: &Shell) -> Result<()> {
         let content = fs::read_to_string(&path)?;
         let content_with_version = content.replace("<!-- VERSION PLACEHOLDER -->", &version);
 
-        // Create temporary file with version-replaced content
-        let temp_path = format!("{}.tmp", path.display());
-        fs::write(&temp_path, content_with_version)?;
+        // Check if we need to regenerate by comparing input and output modification times
+        let should_regenerate = if let (Ok(input_meta), Ok(output_meta)) =
+            (fs::metadata(&path), fs::metadata(&output_file))
+        {
+            input_meta.modified().unwrap_or(std::time::UNIX_EPOCH)
+                > output_meta.modified().unwrap_or(std::time::UNIX_EPOCH)
+        } else {
+            // If output doesn't exist or we can't get metadata, regenerate
+            true
+        };
+
+        if should_regenerate {
+            // Create temporary file with version-replaced content
+            let temp_path = format!("{}.tmp", path.display());
+            fs::write(&temp_path, content_with_version)?;
 
-        cmd!(sh, "go-md2man -in {temp_path} -out {output_file}")
-            .run()
-            .with_context(|| format!("Converting {} to man page", path.display()))?;
+            cmd!(sh, "go-md2man -in {temp_path} -out {output_file}")
+                .run()
+                .with_context(|| format!("Converting {} to man page", path.display()))?;
 
-        // Clean up temporary file
-        fs::remove_file(&temp_path)?;
+            // Clean up temporary file
+            fs::remove_file(&temp_path)?;
 
-        println!("Generated {}", output_file);
+            println!("Generated {}", output_file);
+        }
     }
 
     // Apply post-processing fixes for apostrophe handling
@@ -495,9 +500,9 @@ pub fn update_manpages(sh: &Shell) -> Result<()> {
     // Check each command and create man page if missing
     for command_parts in commands_to_check {
         let filename = if command_parts.len() == 1 {
-            format!("bootc-{}.md", command_parts[0])
+            format!("bootc-{}.8.md", command_parts[0])
         } else {
-            format!("bootc-{}.md", command_parts.join("-"))
+            format!("bootc-{}.8.md", command_parts.join("-"))
         };
 
         let filepath = format!("docs/src/man/{}", filename);
@@ -511,6 +516,23 @@ pub fn update_manpages(sh: &Shell) -> Result<()> {
                 let command_name_full = format!("bootc {}", command_parts.join(" "));
                 let command_description = cmd.about.as_deref().unwrap_or("TODO: Add description");
 
+                // Generate SYNOPSIS line with proper arguments
+                let mut synopsis = format!("**{}** \\[*OPTIONS...*\\]", command_name_full);
+
+                // Add positional arguments
+                for positional in &cmd.positionals {
+                    if positional.required {
+                        synopsis.push_str(&format!(" <*{}*>", positional.name.to_uppercase()));
+                    } else {
+                        synopsis.push_str(&format!(" \\[*{}*\\]", positional.name.to_uppercase()));
+                    }
+                }
+
+                // Add subcommand if this command has subcommands
+                if !cmd.subcommands.is_empty() {
+                    synopsis.push_str(" <*SUBCOMMAND*>");
+                }
+
                 let template = format!(
                     r#"# NAME
 
@@ -518,7 +540,7 @@ pub fn update_manpages(sh: &Shell) -> Result<()> {
 
 # SYNOPSIS
 
-**{}** [*OPTIONS*]
+{}
 
 # DESCRIPTION
 
@@ -549,19 +571,19 @@ TODO: Add practical examples showing how to use this command.
                 std::fs::write(&filepath, template)
                     .with_context(|| format!("Writing template to {}", filepath))?;
 
-                println!("✓ Created man page template: {}", filepath);
+                println!("Created man page template: {}", filepath);
                 created_count += 1;
             }
         }
     }
 
     if created_count > 0 {
-        println!("✓ Created {} new man page templates", created_count);
+        println!("Created {} new man page templates", created_count);
     } else {
-        println!("✓ All commands already have man pages");
+        println!("All commands already have man pages");
     }
 
-    println!("🔄 Syncing OPTIONS sections...");
+    println!("Syncing OPTIONS sections...");
     sync_all_man_pages(sh)?;
 
     println!("Man pages updated.");
@@ -585,6 +607,13 @@ fn apply_man_page_fixes(sh: &Shell, dir: &Utf8Path) -> Result<()> {
             .and_then(|s| s.to_str())
             .map_or(false, |e| e.chars().all(|c| c.is_numeric()))
         {
+            // Check if the file already has the fix applied
+            let content = fs::read_to_string(&path)?;
+            if content.starts_with(".ds Aq \\(aq\n") {
+                // Already fixed, skip
+                continue;
+            }
+
             // Apply the same sed fixes as before
             let groffsub = r"1i .ds Aq \\(aq";
             let dropif = r"/\.g \.ds Aq/d";
diff --git a/crates/xtask/src/xtask.rs b/crates/xtask/src/xtask.rs
index ec42cfeee..acc314c24 100644
--- a/crates/xtask/src/xtask.rs
+++ b/crates/xtask/src/xtask.rs
@@ -36,9 +36,6 @@ fn main() {
 #[allow(clippy::type_complexity)]
 const TASKS: &[(&str, fn(&Shell) -> Result<()>)] = &[
     ("manpages", man::generate_man_pages),
-    ("sync-manpages", man::sync_all_man_pages),
-    ("test-sync-manpages", man::test_sync_workflow),
-    ("update-json-schemas", update_json_schemas),
     ("update-generated", update_generated),
     ("package", package),
     ("package-srpm", package_srpm),
@@ -47,17 +44,21 @@ const TASKS: &[(&str, fn(&Shell) -> Result<()>)] = &[
 ];
 
 fn try_main() -> Result<()> {
-    // Ensure our working directory is the toplevel
+    // Ensure our working directory is the toplevel (if we're in a git repo)
     {
-        let toplevel_path = Command::new("git")
+        if let Ok(toplevel_path) = Command::new("git")
             .args(["rev-parse", "--show-toplevel"])
             .output()
-            .context("Invoking git rev-parse")?;
-        if !toplevel_path.status.success() {
-            anyhow::bail!("Failed to invoke git rev-parse");
+        {
+            if toplevel_path.status.success() {
+                let path = String::from_utf8(toplevel_path.stdout)?;
+                std::env::set_current_dir(path.trim()).context("Changing to toplevel")?;
+            }
+        }
+        // Otherwise verify we're in the toplevel
+        if !Utf8Path::new("ADOPTERS.md").try_exists()? {
+            anyhow::bail!("Not in toplevel")
         }
-        let path = String::from_utf8(toplevel_path.stdout)?;
-        std::env::set_current_dir(path.trim()).context("Changing to toplevel")?;
     }
 
     let task = std::env::args().nth(1);
@@ -393,11 +394,20 @@ fn update_json_schemas(sh: &Shell) -> Result<()> {
     Ok(())
 }
 
-/// Update generated files using the new sync approach
+/// Update all generated files
+/// This is the main command developers should use to update generated content.
+/// It handles:
+/// - Creating new man page templates for new commands
+/// - Syncing CLI options to existing man pages
+/// - Updating JSON schema files
 #[context("Updating generated files")]
 fn update_generated(sh: &Shell) -> Result<()> {
+    // Update man pages (create new templates + sync options)
     man::update_manpages(sh)?;
+
+    // Update JSON schemas
     update_json_schemas(sh)?;
+
     Ok(())
 }
 
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 1b6b0851c..54857e667 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -21,30 +21,30 @@
 - [Accessing registries and offline updates](registries-and-offline.md)
 - [Logically bound images](logically-bound-images.md)
 - [Booting local builds](booting-local-builds.md)
-- [`man bootc`](man/bootc.md)
-- [`man bootc-status`](man/bootc-status.md)
-- [`man bootc-upgrade`](man/bootc-upgrade.md)
-- [`man bootc-switch`](man/bootc-switch.md)
-- [`man bootc-rollback`](man/bootc-rollback.md)
-- [`man bootc-usr-overlay`](man/bootc-usr-overlay.md)
-- [`man bootc-fetch-apply-updates.service`](man-md/bootc-fetch-apply-updates.service.md)
-- [`man bootc-status-updated.path`](man-md/bootc-status-updated.path.md)
-- [`man bootc-status-updated.target`](man-md/bootc-status-updated.target.md)
+- [`man bootc`](man/bootc.8.md)
+- [`man bootc-status`](man/bootc-status.8.md)
+- [`man bootc-upgrade`](man/bootc-upgrade.8.md)
+- [`man bootc-switch`](man/bootc-switch.8.md)
+- [`man bootc-rollback`](man/bootc-rollback.8.md)
+- [`man bootc-usr-overlay`](man/bootc-usr-overlay.8.md)
+- [`man bootc-fetch-apply-updates.service`](man/bootc-fetch-apply-updates.service.5.md)
+- [`man bootc-status-updated.path`](man/bootc-status-updated.path.5.md)
+- [`man bootc-status-updated.target`](man/bootc-status-updated.target.5.md)
 - [Controlling bootc via API](bootc-via-api.md)
 
 # Using `bootc install`
 
 - [Understanding `bootc install`](bootc-install.md)
-- [`man bootc-install`](man/bootc-install.md)
-- [`man bootc-install-config`](man-md/bootc-install-config.md)
-- [`man bootc-install-to-disk`](man/bootc-install-to-disk.md)
-- [`man bootc-install-to-filesystem`](man/bootc-install-to-filesystem.md)
-- [`man bootc-install-to-existing-root`](man/bootc-install-to-existing-root.md)
+- [`man bootc-install`](man/bootc-install.8.md)
+- [`man bootc-install-config`](man/bootc-install-config.5.md)
+- [`man bootc-install-to-disk`](man/bootc-install-to-disk.8.md)
+- [`man bootc-install-to-filesystem`](man/bootc-install-to-filesystem.8.md)
+- [`man bootc-install-to-existing-root`](man/bootc-install-to-existing-root.8.md)
 
 # Bootc usage in containers
 
 - [Read-only when in a default container](bootc-in-container.md)
-- [`man bootc-container-lint`](man/bootc-container-lint.md)
+- [`man bootc-container-lint`](man/bootc-container-lint.8.md)
 
 # Architecture
 
@@ -52,7 +52,7 @@
 - [Filesystem](filesystem.md)
 - [Filesystem: sysroot](filesystem-sysroot.md)
 - [Container storage](filesystem-storage.md)
-- [Bootloader](bootloader.md)
+- [Bootloader](bootloaders.md)
 
 # Experimental features
 
diff --git a/docs/src/bootc-in-container.md b/docs/src/bootc-in-container.md
index 56783eaa8..8cd15c804 100644
--- a/docs/src/bootc-in-container.md
+++ b/docs/src/bootc-in-container.md
@@ -12,7 +12,7 @@ There are only two supported operations in a container environment today:
 
 - `bootc status`: This can reliably be used to detect whether the system is
   actually booted via bootc or not.
-- `bootc container lint`: See [man/bootc-container-lint.md](man/bootc-container-lint.md).
+- `bootc container lint`: See [man/bootc-container-lint.8.md](man/bootc-container-lint.8.md).
 
 ### Testing bootc in a container
 
diff --git a/docs/src/bootc-install.md b/docs/src/bootc-install.md
index 146323b12..ed356d915 100644
--- a/docs/src/bootc-install.md
+++ b/docs/src/bootc-install.md
@@ -115,7 +115,7 @@ taking precedence.  If for example you are building a derived container image fr
 you could create a `50-myos.toml`  that sets `type = "btrfs"` which will override the
 prior setting.
 
-For other available options, see [bootc-install-config](man-md/bootc-install-config.md).
+For other available options, see [bootc-install-config](man/bootc-install-config.5.md).
 
 ## Installing an "unconfigured" image
 
diff --git a/docs/src/building/bootc-runtime.md b/docs/src/building/bootc-runtime.md
index 2393544f3..4e6e690f5 100644
--- a/docs/src/building/bootc-runtime.md
+++ b/docs/src/building/bootc-runtime.md
@@ -62,7 +62,7 @@ system do it).
 
 Relevant links:
 
-- [bootc rollback](../man/bootc-rollback.md)
+- [bootc rollback](../man/bootc-rollback.8.md)
 - [CentOS Automotive SIG unattended updates](https://sigs.centos.org/automotive/building/unattended_updates/#watchdog-in-qemu)
   (note that as of right now, greenboot does not yet integrate with bootc)
 - <https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/>
diff --git a/docs/src/man/bootc-container-lint.8.md b/docs/src/man/bootc-container-lint.8.md
index 13f502b99..d72ab58d3 100644
--- a/docs/src/man/bootc-container-lint.8.md
+++ b/docs/src/man/bootc-container-lint.8.md
@@ -5,7 +5,7 @@ checks as part of a container build
 
 # SYNOPSIS
 
-**bootc container lint** [*OPTIONS...*]
+**bootc container lint** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
@@ -24,34 +24,22 @@ part of a build process; it will error if any problems are detected.
 
     Default: /
 
-**--fatal-warnings**=*FATAL_WARNINGS*
+**--fatal-warnings**
 
     Make warnings fatal
 
-    Possible values:
-    - true
-    - false
-
-**--list**=*LIST*
+**--list**
 
     Instead of executing the lints, just print all available lints. At the current time, this will output in YAML format because it's reasonably human friendly. However, there is no commitment to maintaining this exact format; do not parse it via code or scripts
 
-    Possible values:
-    - true
-    - false
-
 **--skip**=*SKIP*
 
     Skip checking the targeted lints, by name. Use `--list` to discover the set of available lints
 
-**--no-truncate**=*NO_TRUNCATE*
+**--no-truncate**
 
     Don't truncate the output. By default, only a limited number of entries are shown for each lint, followed by a count of remaining entries
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # VERSION
diff --git a/docs/src/man/bootc-container.8.md b/docs/src/man/bootc-container.8.md
index 9eeab9a90..313f7d59e 100644
--- a/docs/src/man/bootc-container.8.md
+++ b/docs/src/man/bootc-container.8.md
@@ -5,7 +5,7 @@ container build
 
 # SYNOPSIS
 
-**bootc container** [*OPTIONS...*] <*SUBCOMMAND*>
+**bootc container** \[*OPTIONS...*\] <*SUBCOMMAND*>
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc-edit.8.md b/docs/src/man/bootc-edit.8.md
index dcf0581da..48bd00d46 100644
--- a/docs/src/man/bootc-edit.8.md
+++ b/docs/src/man/bootc-edit.8.md
@@ -4,7 +4,7 @@ bootc-edit - Apply full changes to the host specification
 
 # SYNOPSIS
 
-**bootc edit** [*OPTIONS...*]
+**bootc edit** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
@@ -26,14 +26,10 @@ Only changes to the `spec` section are honored.
 
     Use filename to edit system specification
 
-**--quiet**=*QUIET*
+**--quiet**
 
     Don't display progress
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # VERSION
diff --git a/docs/src/man/bootc-fetch-apply-updates.service.5.md b/docs/src/man/bootc-fetch-apply-updates.service.5.md
index 50da19408..de5a1bb41 100644
--- a/docs/src/man/bootc-fetch-apply-updates.service.5.md
+++ b/docs/src/man/bootc-fetch-apply-updates.service.5.md
@@ -1,5 +1,3 @@
-% bootc-fetch-apply-updates(5)
-
 # NAME
 
 bootc-fetch-apply-updates.service
diff --git a/docs/src/man/bootc-install-config.5.md b/docs/src/man/bootc-install-config.5.md
index d52b75ce6..b4343784f 100644
--- a/docs/src/man/bootc-install-config.5.md
+++ b/docs/src/man/bootc-install-config.5.md
@@ -1,5 +1,3 @@
-% bootc-install-config(5)
-
 # NAME
 
 bootc-install-config.toml
diff --git a/docs/src/man/bootc-install-ensure-completion.8.md b/docs/src/man/bootc-install-ensure-completion.8.md
index 9977882ff..2b66c4930 100644
--- a/docs/src/man/bootc-install-ensure-completion.8.md
+++ b/docs/src/man/bootc-install-ensure-completion.8.md
@@ -5,7 +5,7 @@ are performing an ostree-based installation, not bootc
 
 # SYNOPSIS
 
-**bootc install ensure-completion** [*OPTIONS...*]
+**bootc install ensure-completion** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc-install-finalize.8.md b/docs/src/man/bootc-install-finalize.8.md
index 5101c6e6e..c15b4ec66 100644
--- a/docs/src/man/bootc-install-finalize.8.md
+++ b/docs/src/man/bootc-install-finalize.8.md
@@ -5,7 +5,7 @@ installation using `install to-filesystem`
 
 # SYNOPSIS
 
-**bootc install finalize** [*OPTIONS...*] <*ROOT_PATH*>
+**bootc install finalize** \[*OPTIONS...*\] <*ROOT_PATH*>
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc-install-print-configuration.8.md b/docs/src/man/bootc-install-print-configuration.8.md
index 2057971ff..bf50664a5 100644
--- a/docs/src/man/bootc-install-print-configuration.8.md
+++ b/docs/src/man/bootc-install-print-configuration.8.md
@@ -7,7 +7,7 @@ discover the desired root filesystem type from the container image
 
 # SYNOPSIS
 
-**bootc install print-configuration** [*OPTIONS...*]
+**bootc install print-configuration** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc-install-to-disk.8.md b/docs/src/man/bootc-install-to-disk.8.md
index 951f35280..2c92959d8 100644
--- a/docs/src/man/bootc-install-to-disk.8.md
+++ b/docs/src/man/bootc-install-to-disk.8.md
@@ -4,7 +4,7 @@ bootc-install-to-disk - Install to the target block device
 
 # SYNOPSIS
 
-**bootc install to-disk** [*OPTIONS...*] <*DEVICE*>
+**bootc install to-disk** \[*OPTIONS...*\] <*DEVICE*>
 
 # DESCRIPTION
 
@@ -28,14 +28,10 @@ more complex such as RAID, LVM, LUKS etc.
 
     This argument is required.
 
-**--wipe**=*WIPE*
+**--wipe**
 
     Automatically wipe all existing data on device
 
-    Possible values:
-    - true
-    - false
-
 **--block-setup**=*BLOCK_SETUP*
 
     Target root block device setup
@@ -71,38 +67,22 @@ more complex such as RAID, LVM, LUKS etc.
 
     Specify the image to fetch for subsequent updates
 
-**--enforce-container-sigpolicy**=*ENFORCE_CONTAINER_SIGPOLICY*
+**--enforce-container-sigpolicy**
 
     This is the inverse of the previous `--target-no-signature-verification` (which is now a no-op).  Enabling this option enforces that `/etc/containers/policy.json` includes a default policy which requires signatures
 
-    Possible values:
-    - true
-    - false
-
-**--run-fetch-check**=*RUN_FETCH_CHECK*
+**--run-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--skip-fetch-check**=*SKIP_FETCH_CHECK*
+**--skip-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--disable-selinux**=*DISABLE_SELINUX*
+**--disable-selinux**
 
     Disable SELinux in the target (installed) system
 
-    Possible values:
-    - true
-    - false
-
 **--karg**=*KARG*
 
     Add a kernel argument.  This option can be provided multiple times
@@ -111,14 +91,10 @@ more complex such as RAID, LVM, LUKS etc.
 
     The path to an `authorized_keys` that will be injected into the `root` account
 
-**--generic-image**=*GENERIC_IMAGE*
+**--generic-image**
 
     Perform configuration changes suitable for a "generic" disk image. At the moment:
 
-    Possible values:
-    - true
-    - false
-
 **--bound-images**=*BOUND_IMAGES*
 
     How should logically bound images be retrieved
@@ -134,14 +110,10 @@ more complex such as RAID, LVM, LUKS etc.
 
     The stateroot name to use. Defaults to `default`
 
-**--via-loopback**=*VIA_LOOPBACK*
+**--via-loopback**
 
     Instead of targeting a block device, write to a file via loopback
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # EXAMPLES
diff --git a/docs/src/man/bootc-install-to-existing-root.8.md b/docs/src/man/bootc-install-to-existing-root.8.md
index 3b81f003d..9efb4adb1 100644
--- a/docs/src/man/bootc-install-to-existing-root.8.md
+++ b/docs/src/man/bootc-install-to-existing-root.8.md
@@ -4,7 +4,7 @@ bootc-install-to-existing-root - Install to the host root filesystem
 
 # SYNOPSIS
 
-**bootc install to-existing-root** [*OPTIONS...*] [*ROOT_PATH*]
+**bootc install to-existing-root** \[*OPTIONS...*\] \[*ROOT_PATH*\]
 
 # DESCRIPTION
 
@@ -47,38 +47,22 @@ to be cleaned up if desired when rebooted into the new root.
 
     Specify the image to fetch for subsequent updates
 
-**--enforce-container-sigpolicy**=*ENFORCE_CONTAINER_SIGPOLICY*
+**--enforce-container-sigpolicy**
 
     This is the inverse of the previous `--target-no-signature-verification` (which is now a no-op).  Enabling this option enforces that `/etc/containers/policy.json` includes a default policy which requires signatures
 
-    Possible values:
-    - true
-    - false
-
-**--run-fetch-check**=*RUN_FETCH_CHECK*
+**--run-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--skip-fetch-check**=*SKIP_FETCH_CHECK*
+**--skip-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--disable-selinux**=*DISABLE_SELINUX*
+**--disable-selinux**
 
     Disable SELinux in the target (installed) system
 
-    Possible values:
-    - true
-    - false
-
 **--karg**=*KARG*
 
     Add a kernel argument.  This option can be provided multiple times
@@ -87,14 +71,10 @@ to be cleaned up if desired when rebooted into the new root.
 
     The path to an `authorized_keys` that will be injected into the `root` account
 
-**--generic-image**=*GENERIC_IMAGE*
+**--generic-image**
 
     Perform configuration changes suitable for a "generic" disk image. At the moment:
 
-    Possible values:
-    - true
-    - false
-
 **--bound-images**=*BOUND_IMAGES*
 
     How should logically bound images be retrieved
@@ -110,22 +90,14 @@ to be cleaned up if desired when rebooted into the new root.
 
     The stateroot name to use. Defaults to `default`
 
-**--acknowledge-destructive**=*ACKNOWLEDGE_DESTRUCTIVE*
+**--acknowledge-destructive**
 
     Accept that this is a destructive action and skip a warning timer
 
-    Possible values:
-    - true
-    - false
-
-**--cleanup**=*CLEANUP*
+**--cleanup**
 
     Add the bootc-destructive-cleanup systemd service to delete files from the previous install on first boot
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # VERSION
diff --git a/docs/src/man/bootc-install-to-filesystem.8.md b/docs/src/man/bootc-install-to-filesystem.8.md
index 1f9a33f43..f50363824 100644
--- a/docs/src/man/bootc-install-to-filesystem.8.md
+++ b/docs/src/man/bootc-install-to-filesystem.8.md
@@ -5,7 +5,7 @@ filesystem structure
 
 # SYNOPSIS
 
-**bootc install to-filesystem** [*OPTIONS...*] <*ROOT_PATH*>
+**bootc install to-filesystem** \[*OPTIONS...*\] <*ROOT_PATH*>
 
 # DESCRIPTION
 
@@ -41,22 +41,14 @@ is currently expected to be empty by default.
     - wipe
     - alongside
 
-**--acknowledge-destructive**=*ACKNOWLEDGE_DESTRUCTIVE*
+**--acknowledge-destructive**
 
     If the target is the running system's root filesystem, this will skip any warnings
 
-    Possible values:
-    - true
-    - false
-
-**--skip-finalize**=*SKIP_FINALIZE*
+**--skip-finalize**
 
     The default mode is to "finalize" the target filesystem by invoking `fstrim` and similar operations, and finally mounting it readonly.  This option skips those operations.  It is then the responsibility of the invoking code to perform those operations
 
-    Possible values:
-    - true
-    - false
-
 **--source-imgref**=*SOURCE_IMGREF*
 
     Install the system from an explicitly given source
@@ -71,38 +63,22 @@ is currently expected to be empty by default.
 
     Specify the image to fetch for subsequent updates
 
-**--enforce-container-sigpolicy**=*ENFORCE_CONTAINER_SIGPOLICY*
+**--enforce-container-sigpolicy**
 
     This is the inverse of the previous `--target-no-signature-verification` (which is now a no-op).  Enabling this option enforces that `/etc/containers/policy.json` includes a default policy which requires signatures
 
-    Possible values:
-    - true
-    - false
-
-**--run-fetch-check**=*RUN_FETCH_CHECK*
+**--run-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--skip-fetch-check**=*SKIP_FETCH_CHECK*
+**--skip-fetch-check**
 
     Verify the image can be fetched from the bootc image. Updates may fail when the installation host is authenticated with the registry but the pull secret is not in the bootc image
 
-    Possible values:
-    - true
-    - false
-
-**--disable-selinux**=*DISABLE_SELINUX*
+**--disable-selinux**
 
     Disable SELinux in the target (installed) system
 
-    Possible values:
-    - true
-    - false
-
 **--karg**=*KARG*
 
     Add a kernel argument.  This option can be provided multiple times
@@ -111,14 +87,10 @@ is currently expected to be empty by default.
 
     The path to an `authorized_keys` that will be injected into the `root` account
 
-**--generic-image**=*GENERIC_IMAGE*
+**--generic-image**
 
     Perform configuration changes suitable for a "generic" disk image. At the moment:
 
-    Possible values:
-    - true
-    - false
-
 **--bound-images**=*BOUND_IMAGES*
 
     How should logically bound images be retrieved
diff --git a/docs/src/man/bootc-install.8.md b/docs/src/man/bootc-install.8.md
index aaea2c6a4..cc4a91a4c 100644
--- a/docs/src/man/bootc-install.8.md
+++ b/docs/src/man/bootc-install.8.md
@@ -4,7 +4,7 @@ bootc-install - Install the running container to a target
 
 # SYNOPSIS
 
-**bootc install** [*OPTIONS...*] <*SUBCOMMAND*>
+**bootc install** \[*OPTIONS...*\] <*SUBCOMMAND*>
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc-rollback.8.md b/docs/src/man/bootc-rollback.8.md
index bc6215a19..e5f22e173 100644
--- a/docs/src/man/bootc-rollback.8.md
+++ b/docs/src/man/bootc-rollback.8.md
@@ -4,7 +4,7 @@ bootc-rollback - Change the bootloader entry ordering
 
 # SYNOPSIS
 
-**bootc rollback** [*OPTIONS...*]
+**bootc rollback** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
@@ -34,14 +34,10 @@ merges happen when new deployments are created.
 # OPTIONS
 
 <!-- BEGIN GENERATED OPTIONS -->
-**--apply**=*APPLY*
+**--apply**
 
     Restart or reboot into the rollback image
 
-    Possible values:
-    - true
-    - false
-
 **--soft-reboot**=*SOFT_REBOOT*
 
     Configure soft reboot behavior
diff --git a/docs/src/man/bootc-status-updated.path.5.md b/docs/src/man/bootc-status-updated.path.5.md
index 5fc8ffe79..8404b46f1 100644
--- a/docs/src/man/bootc-status-updated.path.5.md
+++ b/docs/src/man/bootc-status-updated.path.5.md
@@ -1,5 +1,3 @@
-% bootc-status-updated.path(8)
-
 # NAME
 
 bootc-status-updated.path
@@ -16,7 +14,7 @@ update/upgrade/edit/switch/rollback operation.
 
 # SEE ALSO
 
-**bootc**(1), **bootc-status-updated.target**(8)
+**bootc**(1), **bootc-status-updated.target**(5)
 
 # VERSION
 
diff --git a/docs/src/man/bootc-status-updated.target.5.md b/docs/src/man/bootc-status-updated.target.5.md
index 4f5e0fccf..b9bc71833 100644
--- a/docs/src/man/bootc-status-updated.target.5.md
+++ b/docs/src/man/bootc-status-updated.target.5.md
@@ -1,5 +1,3 @@
-% bootc-status-updated.target(8)
-
 # NAME
 
 bootc-status-updated.target
@@ -20,7 +18,7 @@ WantedBy=bootc-status-updated.target
 
 # SEE ALSO
 
-**bootc**(1), **bootc-status-updated.path**(8)
+**bootc**(1), **bootc-status-updated.path**(5)
 
 # VERSION
 
diff --git a/docs/src/man/bootc-status.8.md b/docs/src/man/bootc-status.8.md
index efc7e958d..d2342110b 100644
--- a/docs/src/man/bootc-status.8.md
+++ b/docs/src/man/bootc-status.8.md
@@ -4,7 +4,7 @@ bootc-status - Display status
 
 # SYNOPSIS
 
-**bootc status** [*OPTIONS...*]
+**bootc status** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
@@ -40,22 +40,14 @@ Invoke e.g. `bootc status --json`, and check if `status.booted` is not `null`.
 
     The desired format version. There is currently one supported version, which is exposed as both `0` and `1`. Pass this option to explicitly request it; it is possible that another future version 2 or newer will be supported in the future
 
-**--booted**=*BOOTED*
+**--booted**
 
     Only display status for the booted deployment
 
-    Possible values:
-    - true
-    - false
-
-**-v**, **--verbose**=*VERBOSE*
+**-v**, **--verbose**
 
     Include additional fields in human readable format
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # EXAMPLES
diff --git a/docs/src/man/bootc-switch.8.md b/docs/src/man/bootc-switch.8.md
index 1d504c90c..c46816aea 100644
--- a/docs/src/man/bootc-switch.8.md
+++ b/docs/src/man/bootc-switch.8.md
@@ -4,7 +4,7 @@ bootc-switch - Target a new container image reference to boot
 
 # SYNOPSIS
 
-**bootc switch** [*OPTIONS...*] <*TARGET*>
+**bootc switch** \[*OPTIONS...*\] <*TARGET*>
 
 # DESCRIPTION
 
@@ -41,22 +41,14 @@ Soft reboot allows faster system restart by avoiding full hardware reboot when p
 
     This argument is required.
 
-**--quiet**=*QUIET*
+**--quiet**
 
     Don't display progress
 
-    Possible values:
-    - true
-    - false
-
-**--apply**=*APPLY*
+**--apply**
 
     Restart or reboot into the new target image
 
-    Possible values:
-    - true
-    - false
-
 **--soft-reboot**=*SOFT_REBOOT*
 
     Configure soft reboot behavior
@@ -71,22 +63,14 @@ Soft reboot allows faster system restart by avoiding full hardware reboot when p
 
     Default: registry
 
-**--enforce-container-sigpolicy**=*ENFORCE_CONTAINER_SIGPOLICY*
+**--enforce-container-sigpolicy**
 
     This is the inverse of the previous `--target-no-signature-verification` (which is now a no-op)
 
-    Possible values:
-    - true
-    - false
-
-**--retain**=*RETAIN*
+**--retain**
 
     Retain reference to currently booted image
 
-    Possible values:
-    - true
-    - false
-
 <!-- END GENERATED OPTIONS -->
 
 # EXAMPLES
diff --git a/docs/src/man/bootc-upgrade.8.md b/docs/src/man/bootc-upgrade.8.md
index a0c611a8a..451cdf82a 100644
--- a/docs/src/man/bootc-upgrade.8.md
+++ b/docs/src/man/bootc-upgrade.8.md
@@ -4,7 +4,7 @@ bootc-upgrade - Download and queue an updated container image to apply
 
 # SYNOPSIS
 
-**bootc upgrade** [*OPTIONS...*]
+**bootc upgrade** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
@@ -41,30 +41,18 @@ Soft reboot allows faster system restart by avoiding full hardware reboot when p
 # OPTIONS
 
 <!-- BEGIN GENERATED OPTIONS -->
-**--quiet**=*QUIET*
+**--quiet**
 
     Don't display progress
 
-    Possible values:
-    - true
-    - false
-
-**--check**=*CHECK*
+**--check**
 
     Check if an update is available without applying it
 
-    Possible values:
-    - true
-    - false
-
-**--apply**=*APPLY*
+**--apply**
 
     Restart or reboot into the new target image
 
-    Possible values:
-    - true
-    - false
-
 **--soft-reboot**=*SOFT_REBOOT*
 
     Configure soft reboot behavior
diff --git a/docs/src/man/bootc-usr-overlay.8.md b/docs/src/man/bootc-usr-overlay.8.md
index fb3b9d632..afb032ad1 100644
--- a/docs/src/man/bootc-usr-overlay.8.md
+++ b/docs/src/man/bootc-usr-overlay.8.md
@@ -5,7 +5,7 @@ will be discarded on reboot
 
 # SYNOPSIS
 
-**bootc usr-overlay** [*OPTIONS...*]
+**bootc usr-overlay** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
diff --git a/docs/src/man/bootc.8.md b/docs/src/man/bootc.8.md
index cc3b3b48d..adb1c72c8 100644
--- a/docs/src/man/bootc.8.md
+++ b/docs/src/man/bootc.8.md
@@ -5,7 +5,7 @@ images
 
 # SYNOPSIS
 
-**bootc** [*OPTIONS...*] <*SUBCOMMAND*>
+**bootc** \[*OPTIONS...*\] <*SUBCOMMAND*>
 
 # DESCRIPTION
 
diff --git a/docs/src/upgrades.md b/docs/src/upgrades.md
index b6d1802ed..efe10eea1 100644
--- a/docs/src/upgrades.md
+++ b/docs/src/upgrades.md
@@ -18,7 +18,7 @@ There is also an opinionated `bootc-fetch-apply-updates.timer` and corresponding
 service available in upstream for operating systems and distributions
 to enable.
 
-Man page: [bootc-upgrade](man/bootc-upgrade.md).
+Man page: [bootc-upgrade](man/bootc-upgrade.8.md).
 
 ## Changing the container image source
 
@@ -38,7 +38,7 @@ container image being tracked.
 This will preserve existing state in `/etc` and `/var` - for example,
 host SSH keys and home directories.
 
-Man page: [bootc-switch](man/bootc-switch.md).
+Man page: [bootc-switch](man/bootc-switch.8.md).
 
 ## Rollback
 
@@ -46,6 +46,6 @@ There is a  `bootc rollback` verb, and associated declarative interface
 accessible to tools via `bootc edit`.  This will swap the bootloader
 ordering to the previous boot entry.
 
-Man page: [bootc-rollback](man/bootc-rollback.md).
+Man page: [bootc-rollback](man/bootc-rollback.8.md).