carson 3.16.0 → 3.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f88fb85694afee9d6cb92ed785152851dd88e53a354bcc27f35ae2ab40f034da
-  data.tar.gz: 366e6b00767ca21554e016329a3a8112aaec7177fee2668c9678b99d90e0a4f0
+  metadata.gz: 5c18ffa310a6fdb0b0e1581eba83b9ab7dcb8c88a546c391f83200871e17d7f6
+  data.tar.gz: 77c0d6e97438a1f9512e3dbef51a22981caf1b6b0126ffe8ab3bdbf3c7ec3bbb
 SHA512:
-  metadata.gz: 8030cfb9fe88b844de38c015bb951ddc1dc4225bdad98faa6a7d7f0197246801043f6c7c0e5d881590fb892fd3cf8eba9ce45fd2a2a2110309a23c9251208dc2
-  data.tar.gz: 2b30204a052702fb44990fd76afcf456c443a861ce9a076b2cdbeebb951968c015a3f1fffd4662483e6620d96d285536d5a383327e47b51817744f1ae1f3c17c
+  metadata.gz: 5ac7c43bd96d94c1013c5ade599bd906dbda305b3c0216c184093b62292de30c93d7b8f7bd0e090ffe13fd272e97345d6adb30b321df3188f48b2e5ef50913d6
+  data.tar.gz: 00da3a36874c8dca3ade2736e2e0d5852018cbe13c7a68cb0af746a59cbcbda51b4f992ebe862a88cf855824d7388c2a3b09b04d5950da385f3bdcf6ff09af12

data/API.md

@@ -29,6 +29,21 @@ carson <command> [subcommand] [arguments]
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
+| `carson status` | Show repository state (branch, worktrees, PRs, governance). |
+
+### Batch commands (Layer 2)
+
+All batch commands operate across every governed repository registered in `govern.repos`.
+
+| Command | Purpose |
+|---|---|
+| `carson refresh --all` | Re-apply hooks, templates, and audit across all governed repos. Skips repos with active worktrees or uncommitted changes. |
+| `carson audit --all` | Run governance audit across all governed repos. Reports pass/block/fail per repo. |
+| `carson sync --all` | Sync main branch across all governed repos. |
+| `carson prune --all` | Remove stale branches across all governed repos. |
+| `carson status --all [--json]` | Portfolio-wide status overview with branch, worktrees, and governance state per repo. |
+| `carson template check --all` | Read-only template drift detection across all governed repos. |
+| `carson housekeep --all` | Sync, reap dead worktrees, and prune across all governed repos. |
 
 ### Govern commands
 
@@ -132,7 +147,7 @@ Environment overrides:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```

data/MANUAL.md

@@ -89,7 +89,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
@@ -97,7 +97,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 That directory mirrors the `.github/` structure:
 
 ```
-~/AI/LINT/
+~/AI/CODING/LINT/
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
 ├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
@@ -207,8 +207,24 @@ carson review gate
 ```bash
 carson repos           # list all governed repositories
 carson repos --json    # machine-readable output
+carson status --all    # branch, worktrees, governance per repo
 ```
 
+**Portfolio maintenance (Layer 2):**
+
+All `--all` commands run across every governed repository registered via `carson onboard`.
+
+```bash
+carson refresh --all           # re-apply hooks, templates, audit across all repos
+carson sync --all              # fast-forward main across all repos
+carson audit --all             # governance audit across all repos
+carson prune --all             # remove stale branches across all repos
+carson template check --all    # detect template drift across all repos
+carson housekeep --all         # full maintenance cycle across all repos
+```
+
+`refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
+
 **Periodic maintenance:**
 
 ```bash

data/RELEASE.md

@@ -5,6 +5,36 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.18.0
+
+### What changed
+
+- **Layer 2 batch operations** — every command that operates on a single repo now has an `--all` variant that runs across the entire governed portfolio:
+  - `carson refresh --all` — refresh hooks, templates, and audit across all repos. Checks each repo for safety (active worktrees, uncommitted changes) and skips unsafe repos.
+  - `carson prune --all` — prune stale branches across all repos.
+  - `carson audit --all` — run governance audit across all repos. Reports pass/block/fail per repo.
+  - `carson sync --all` — sync main branch across all repos.
+  - `carson status --all` — portfolio-wide status overview with branch, worktrees, and governance state per repo. Supports `--json`.
+  - `carson template check --all` — read-only template drift detection across all repos.
+- **Portfolio safety checks** — before batch `refresh`, Carson checks each repo for active worktrees and uncommitted changes. Unsafe repos are skipped with reasons, not failed.
+- **Shared `portfolio_repo_safety` helper** — centralised safety check in `Runtime` for all batch operations. Non-git directories pass through (the command reports the real error).
+- **CLI `--all` flag registration** — `audit`, `sync`, and `status` parsers now correctly register the `--all` flag with OptionParser (previously the flag was checked but never registered).
+
+### UX improvement
+
+- A user or agent managing multiple repositories can now run a single command to maintain the entire portfolio. `carson status --all` gives a quick overview; `carson refresh --all` keeps everything in sync; `carson housekeep --all` runs the full maintenance cycle. Unsafe repos are clearly reported with skip reasons instead of cryptic failures.
+
+## 3.17.0
+
+### What changed
+
+- **Descriptive help text for all CLI commands** — every command now shows purpose, description, and usage examples when invoked with `--help`. Commands that previously used manual flag parsing (`audit`, `sync`, `status`, `repos`, `prune`, `housekeep`, `worktree`, `onboard`, `offboard`, `refresh`, `review`, `template`) now use `OptionParser` so `--help` is handled consistently.
+- **Structured top-level help** — `carson --help` shows a command catalogue with one-line descriptions and a footer guiding to per-command help, replacing the previous single-line usage banner.
+
+### UX improvement
+
+- A user encountering Carson for the first time can now understand what each command does without reading external documentation. Every `--help` surface answers: what does this do, what options are available, and how do I use it.
+
 ## 3.16.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.16.0
+3.18.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if %w[repos refresh:all prune:all housekeep:all housekeep:target].include?( command )
+			if %w[repos refresh:all prune:all housekeep:all housekeep:target template:check:all audit:all sync:all status:all].include?( command )
 				verbose = parsed.fetch( :verbose, false )
 				runtime = Runtime.new( repo_root: repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 				return dispatch( parsed: parsed, runtime: runtime )
@@ -43,7 +43,7 @@ module Carson
 			return preset.merge( verbose: verbose ) unless preset.nil?
 
 			command = argv.shift
-			result = parse_command( command: command, argv: argv, parser: parser, err: err )
+			result = parse_command( command: command, argv: argv, err: err )
 			result.merge( verbose: verbose )
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -53,7 +53,29 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|housekeep [repo] [--json]|repos [--json]|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson <command> [options]"
+				opts.separator ""
+				opts.separator "Repository governance and workflow automation for coding agents."
+				opts.separator ""
+				opts.separator "Commands:"
+				opts.separator "    status       Show repository state (branch, PRs, worktrees)"
+				opts.separator "    setup        Initialise Carson configuration"
+				opts.separator "    audit        Run pre-commit health checks"
+				opts.separator "    sync         Sync local main with remote"
+				opts.separator "    deliver      Push, create PR, and optionally merge"
+				opts.separator "    prune        Remove stale local branches"
+				opts.separator "    worktree     Manage isolated coding worktrees"
+				opts.separator "    housekeep    Sync, reap worktrees, and prune branches"
+				opts.separator "    repos        List governed repositories"
+				opts.separator "    onboard      Register a repository for governance"
+				opts.separator "    offboard     Remove a repository from governance"
+				opts.separator "    refresh      Re-install hooks and configuration"
+				opts.separator "    template     Manage canonical template files"
+				opts.separator "    review       Manage PR review workflow"
+				opts.separator "    govern       Portfolio-level PR triage loop"
+				opts.separator "    version      Show Carson version"
+				opts.separator ""
+				opts.separator "Run `carson <command> --help` for details on a specific command."
 			end
 		end
 
@@ -69,29 +91,30 @@ module Carson
 			nil
 		end
 
-		def self.parse_command( command:, argv:, parser:, err: )
+		def self.parse_command( command:, argv:, err: )
 			case command
 			when "version"
-				parser.parse!( argv )
 				{ command: "version" }
 			when "setup"
-				parse_setup_command( argv: argv, parser: parser, err: err )
-			when "onboard", "offboard"
-				parse_repo_path_command( command: command, argv: argv, parser: parser, err: err )
+				parse_setup_command( argv: argv, err: err )
+			when "onboard"
+				parse_onboard_command( argv: argv, err: err )
+			when "offboard"
+				parse_offboard_command( argv: argv, err: err )
 			when "refresh"
-				parse_refresh_command( argv: argv, parser: parser, err: err )
+				parse_refresh_command( argv: argv, err: err )
 			when "template"
-				parse_template_subcommand( argv: argv, parser: parser, err: err )
+				parse_template_subcommand( argv: argv, err: err )
 			when "prune"
-				parse_prune_command( argv: argv, parser: parser, err: err )
+				parse_prune_command( argv: argv, err: err )
 			when "worktree"
-				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
+				parse_worktree_subcommand( argv: argv, err: err )
 			when "repos"
 				parse_repos_command( argv: argv, err: err )
 			when "housekeep"
 				parse_housekeep_command( argv: argv, err: err )
 			when "review"
-				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
+				parse_review_subcommand( argv: argv, err: err )
 			when "audit"
 				parse_audit_command( argv: argv, err: err )
 			when "sync"
@@ -103,20 +126,32 @@ module Carson
 			when "govern"
 				parse_govern_subcommand( argv: argv, err: err )
 			else
-				parser.parse!( argv )
 				{ command: command }
 			end
 		end
 
-		def self.parse_setup_command( argv:, parser:, err: )
+		# --- setup ---
+
+		def self.parse_setup_command( argv:, err: )
 			options = {}
 			setup_parser = OptionParser.new do |opts|
 				opts.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]"
+				opts.separator ""
+				opts.separator "Initialise Carson configuration for the current repository."
+				opts.separator "Detects git remote, main branch, and workflow style, then writes .carson.yml."
+				opts.separator "Pass flags to override detected values."
+				opts.separator ""
+				opts.separator "Options:"
 				opts.on( "--remote NAME", "Git remote name" ) { |v| options[ "git.remote" ] = v }
 				opts.on( "--main-branch NAME", "Main branch name" ) { |v| options[ "git.main_branch" ] = v }
 				opts.on( "--workflow STYLE", "Workflow style (branch or trunk)" ) { |v| options[ "workflow.style" ] = v }
 				opts.on( "--merge METHOD", "Merge method (squash, rebase, or merge)" ) { |v| options[ "govern.merge.method" ] = v }
 				opts.on( "--canonical PATH", "Canonical template directory path" ) { |v| options[ "template.canonical" ] = v }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson setup                            Auto-detect and write config"
+				opts.separator "    carson setup --remote github            Use 'github' as the git remote"
+				opts.separator "    carson setup --merge squash             Set squash as the merge method"
 			end
 			setup_parser.parse!( argv )
 			unless argv.empty?
@@ -130,36 +165,93 @@ module Carson
 			{ command: :invalid }
 		end
 
-		def self.parse_repo_path_command( command:, argv:, parser:, err: )
-			parser.parse!( argv )
+		# --- onboard / offboard ---
+
+		def self.parse_onboard_command( argv:, err: )
+			onboard_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson onboard [REPO_PATH]"
+				opts.separator ""
+				opts.separator "Register a repository for Carson governance."
+				opts.separator "Detects the remote, installs hooks, applies templates, and runs initial audit."
+				opts.separator "Defaults to the current directory if no path is given."
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson onboard             Onboard the current repository"
+				opts.separator "    carson onboard ~/Dev/app   Onboard a specific repository"
+			end
+			onboard_parser.parse!( argv )
 			if argv.length > 1
-				err.puts "#{BADGE} Too many arguments for #{command}. Use: carson #{command} [repo_path]"
-				err.puts parser
+				err.puts "#{BADGE} Too many arguments for onboard. Use: carson onboard [repo_path]"
+				err.puts onboard_parser
 				return { command: :invalid }
 			end
+			repo_path = argv.first
+			{
+				command: "onboard",
+				repo_root: repo_path.to_s.strip.empty? ? nil : File.expand_path( repo_path )
+			}
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
+		end
 
+		def self.parse_offboard_command( argv:, err: )
+			offboard_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson offboard [REPO_PATH]"
+				opts.separator ""
+				opts.separator "Remove a repository from Carson governance."
+				opts.separator "Unregisters the repo from Carson's portfolio and removes hooks."
+				opts.separator "Defaults to the current directory if no path is given."
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson offboard            Offboard the current repository"
+			end
+			offboard_parser.parse!( argv )
+			if argv.length > 1
+				err.puts "#{BADGE} Too many arguments for offboard. Use: carson offboard [repo_path]"
+				err.puts offboard_parser
+				return { command: :invalid }
+			end
 			repo_path = argv.first
 			{
-				command: command,
+				command: "offboard",
 				repo_root: repo_path.to_s.strip.empty? ? nil : File.expand_path( repo_path )
 			}
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
-		def self.parse_refresh_command( argv:, parser:, err: )
-			all_flag = argv.delete( "--all" ) ? true : false
-			parser.parse!( argv )
+		# --- refresh ---
+
+		def self.parse_refresh_command( argv:, err: )
+			options = { all: false }
+			refresh_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson refresh [--all] [REPO_PATH]"
+				opts.separator ""
+				opts.separator "Re-install Carson hooks and configuration for a repository."
+				opts.separator "Defaults to the current directory. Use --all to refresh all governed repos."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Refresh all governed repositories" ) { options[ :all ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson refresh             Refresh the current repository"
+				opts.separator "    carson refresh --all       Refresh all governed repos"
+			end
+			refresh_parser.parse!( argv )
 
-			if all_flag && !argv.empty?
+			if options[ :all ] && !argv.empty?
 				err.puts "#{BADGE} --all and repo_path are mutually exclusive. Use: carson refresh --all OR carson refresh [repo_path]"
-				err.puts parser
+				err.puts refresh_parser
 				return { command: :invalid }
 			end
 
-			return { command: "refresh:all" } if all_flag
+			return { command: "refresh:all" } if options[ :all ]
 
 			if argv.length > 1
 				err.puts "#{BADGE} Too many arguments for refresh. Use: carson refresh [repo_path]"
-				err.puts parser
+				err.puts refresh_parser
 				return { command: :invalid }
 			end
 
@@ -168,22 +260,67 @@ module Carson
 				command: "refresh",
 				repo_root: repo_path.to_s.strip.empty? ? nil : File.expand_path( repo_path )
 			}
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
-		def self.parse_prune_command( argv:, parser:, err: )
-			all_flag = argv.delete( "--all" ) ? true : false
-			json_flag = argv.delete( "--json" ) ? true : false
-			parser.parse!( argv )
-			return { command: "prune:all", json: json_flag } if all_flag
-			{ command: "prune", json: json_flag }
+		# --- prune ---
+
+		def self.parse_prune_command( argv:, err: )
+			options = { all: false, json: false }
+			prune_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson prune [--all] [--json]"
+				opts.separator ""
+				opts.separator "Remove stale local branches."
+				opts.separator "Cleans up branches gone from the remote, orphan branches with merged PRs,"
+				opts.separator "and absorbed branches whose content is already on main."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Prune all governed repositories" ) { options[ :all ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson prune           Clean up stale branches in this repo"
+				opts.separator "    carson prune --all     Clean up across all governed repos"
+			end
+			prune_parser.parse!( argv )
+			return { command: "prune:all", json: options[ :json ] } if options[ :all ]
+			{ command: "prune", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
-		def self.parse_worktree_subcommand( argv:, parser:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
+		# --- worktree ---
+
+		def self.parse_worktree_subcommand( argv:, err: )
+			options = { json: false, force: false }
+			worktree_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson worktree <create|remove> <name> [options]"
+				opts.separator ""
+				opts.separator "Manage isolated worktrees for coding agents."
+				opts.separator "Create auto-syncs main before branching. Remove guards against"
+				opts.separator "unpushed commits and CWD-inside-worktree by default."
+				opts.separator ""
+				opts.separator "Subcommands:"
+				opts.separator "    create <name>              Create a new worktree with a fresh branch"
+				opts.separator "    remove <name> [--force]    Remove a worktree (--force skips safety checks)"
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.on( "--force", "Skip safety checks on remove" ) { options[ :force ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson worktree create feature-x    Create an isolated worktree"
+				opts.separator "    carson worktree remove feature-x    Remove after work is pushed"
+			end
+			worktree_parser.parse!( argv )
+
 			action = argv.shift
 			if action.to_s.strip.empty?
 				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree create|remove <name>"
-				err.puts parser
+				err.puts worktree_parser
 				return { command: :invalid }
 			end
 
@@ -194,45 +331,95 @@ module Carson
 					err.puts "#{BADGE} Missing name for worktree create. Use: carson worktree create <name>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:create", worktree_name: name, json: json_flag }
+				{ command: "worktree:create", worktree_name: name, json: options[ :json ] }
 			when "remove"
-				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
 				if worktree_path.to_s.strip.empty?
 					err.puts "#{BADGE} Missing path for worktree remove. Use: carson worktree remove <name-or-path>"
 					return { command: :invalid }
 				end
-				{ command: "worktree:remove", worktree_path: worktree_path, force: force, json: json_flag }
+				{ command: "worktree:remove", worktree_path: worktree_path, force: options[ :force ], json: options[ :json ] }
 			else
 				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree create|remove <name>"
 				{ command: :invalid }
 			end
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
-		def self.parse_named_subcommand( command:, usage:, argv:, parser:, err: )
+		# --- review ---
+
+		def self.parse_review_subcommand( argv:, err: )
+			review_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson review <gate|sweep>"
+				opts.separator ""
+				opts.separator "Manage PR review workflow."
+				opts.separator ""
+				opts.separator "Subcommands:"
+				opts.separator "    gate     Check if review requirements are met for merge"
+				opts.separator "    sweep    Scan and resolve pending review threads"
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson review gate     Check merge readiness"
+				opts.separator "    carson review sweep    Resolve pending review threads"
+			end
+			review_parser.parse!( argv )
+
 			action = argv.shift
-			parser.parse!( argv )
 			if action.to_s.strip.empty?
-				err.puts "#{BADGE} Missing subcommand for #{command}. Use: carson #{command} #{usage}"
-				err.puts parser
+				err.puts "#{BADGE} Missing subcommand for review. Use: carson review gate|sweep"
+				err.puts review_parser
 				return { command: :invalid }
 			end
-			{ command: "#{command}:#{action}" }
+			{ command: "review:#{action}" }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
-		def self.parse_template_subcommand( argv:, parser:, err: )
-			action = argv.shift
-			if action.to_s.strip.empty?
-				err.puts "#{BADGE} Missing subcommand for template. Use: carson template check|apply"
-				err.puts parser
-				return { command: :invalid }
+		# --- template ---
+
+		def self.parse_template_subcommand( argv:, err: )
+			# Handle parent-level help or missing subcommand.
+			if argv.empty? || [ "--help", "-h" ].include?( argv.first )
+				template_parser = OptionParser.new do |opts|
+					opts.banner = "Usage: carson template <check|apply> [options]"
+					opts.separator ""
+					opts.separator "Manage canonical template files (CI workflows, lint configs)."
+					opts.separator ""
+					opts.separator "Subcommands:"
+					opts.separator "    check                  Show template drift without making changes"
+					opts.separator "    apply [--push-prep]    Sync templates into the repository"
+					opts.separator ""
+					opts.separator "Examples:"
+					opts.separator "    carson template check    Check for template drift"
+					opts.separator "    carson template apply    Apply canonical templates"
+				end
+
+				if argv.empty?
+					err.puts "#{BADGE} Missing subcommand for template. Use: carson template check|apply"
+					err.puts template_parser
+					return { command: :invalid }
+				end
+
+				# Let OptionParser handle --help (prints and exits).
+				template_parser.parse!( argv )
+				return { command: :help }
 			end
 
+			action = argv.shift
+			return { command: "template:check:all" } if action == "check" && argv.include?( "--all" )
 			return { command: "template:#{action}" } unless action == "apply"
 
 			options = { push_prep: false }
 			apply_parser = OptionParser.new do |opts|
 				opts.banner = "Usage: carson template apply [--push-prep]"
+				opts.separator ""
+				opts.separator "Sync canonical template files (CI workflows, lint configs) into the repository."
+				opts.separator "Copies managed files from the configured canonical directory."
+				opts.separator ""
+				opts.separator "Options:"
 				opts.on( "--push-prep", "Apply templates and auto-commit any managed file changes (used by pre-push hook)" ) do
 					options[ :push_prep ] = true
 				end
@@ -249,41 +436,119 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- audit ---
+
 		def self.parse_audit_command( argv:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
+			options = { json: false, all: false }
+			audit_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson audit [--all] [--json]"
+				opts.separator ""
+				opts.separator "Run pre-commit health checks on the repository."
+				opts.separator "Validates hooks, main-branch sync, PR status, and CI baseline."
+				opts.separator "Exits with a non-zero status when policy violations are found."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Audit all governed repositories" ) { options[ :all ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson audit           Check repository health (also the default command)"
+				opts.separator "    carson audit --json    Structured output for agent consumption"
+				opts.separator "    carson audit --all     Audit all governed repos"
+			end
+			audit_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for audit: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
-			{ command: "audit", json: json_flag }
+			return { command: "audit:all" } if options[ :all ]
+			{ command: "audit", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
+		# --- sync ---
+
 		def self.parse_sync_command( argv:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
+			options = { json: false, all: false }
+			sync_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson sync [--all] [--json]"
+				opts.separator ""
+				opts.separator "Sync the local main branch with the remote."
+				opts.separator "Fetches and fast-forwards main without switching branches."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Sync all governed repositories" ) { options[ :all ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson sync            Pull latest changes from remote main"
+				opts.separator "    carson sync --json     Structured output for agent consumption"
+				opts.separator "    carson sync --all      Sync all governed repos"
+			end
+			sync_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for sync: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
-			{ command: "sync", json: json_flag }
+			return { command: "sync:all" } if options[ :all ]
+			{ command: "sync", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
+		# --- status ---
+
 		def self.parse_status_command( argv:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
+			options = { json: false, all: false }
+			status_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson status [--all] [--json]"
+				opts.separator ""
+				opts.separator "Show the current state of the repository."
+				opts.separator "Reports branch, worktrees, open PRs, stale branches, and version."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Show status for all governed repositories" ) { options[ :all ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson status           Quick overview of repository state"
+				opts.separator "    carson status --json    Structured output for agent consumption"
+				opts.separator "    carson status --all     Portfolio-wide status overview"
+			end
+			status_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for status: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
-			{ command: "status", json: json_flag }
+			return { command: "status:all", json: options[ :json ] } if options[ :all ]
+			{ command: "status", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
+		# --- deliver ---
+
 		def self.parse_deliver_command( argv:, err: )
 			options = { merge: false, json: false, title: nil, body_file: nil }
 			deliver_parser = OptionParser.new do |opts|
 				opts.banner = "Usage: carson deliver [--merge] [--json] [--title TITLE] [--body-file PATH]"
+				opts.separator ""
+				opts.separator "Push the current branch, create a pull request, and optionally merge."
+				opts.separator "Collapses the manual push → PR → merge flow into a single command."
+				opts.separator ""
+				opts.separator "Options:"
 				opts.on( "--merge", "Also merge the PR if CI passes" ) { options[ :merge ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.on( "--title TITLE", "PR title (defaults to branch name)" ) { |v| options[ :title ] = v }
 				opts.on( "--body-file PATH", "File containing PR body text" ) { |v| options[ :body_file ] = v }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson deliver               Push and open a PR"
+				opts.separator "    carson deliver --merge       Push, open a PR, and merge if CI passes"
 			end
 			deliver_parser.parse!( argv )
 			unless argv.empty?
@@ -303,25 +568,61 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- repos ---
+
 		def self.parse_repos_command( argv:, err: )
-			json_flag = argv.delete( "--json" ) ? true : false
+			options = { json: false }
+			repos_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson repos [--json]"
+				opts.separator ""
+				opts.separator "List all repositories governed by Carson."
+				opts.separator "Shows the portfolio of repos registered via carson onboard."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson repos           List governed repositories"
+				opts.separator "    carson repos --json    Structured output for agent consumption"
+			end
+			repos_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for repos: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
-			{ command: "repos", json: json_flag }
+			{ command: "repos", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
+		# --- housekeep ---
+
 		def self.parse_housekeep_command( argv:, err: )
-			all_flag = argv.delete( "--all" ) ? true : false
-			json_flag = argv.delete( "--json" ) ? true : false
+			options = { all: false, json: false }
+			housekeep_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson housekeep [REPO] [--all] [--json]"
+				opts.separator ""
+				opts.separator "Run housekeeping: sync main, reap dead worktrees, and prune stale branches."
+				opts.separator "Defaults to the current repository."
+				opts.separator ""
+				opts.separator "Options:"
+				opts.on( "--all", "Housekeep all governed repositories" ) { options[ :all ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson housekeep           Housekeep the current repository"
+				opts.separator "    carson housekeep nexus     Housekeep a named governed repo"
+				opts.separator "    carson housekeep --all     Housekeep all governed repos"
+			end
+			housekeep_parser.parse!( argv )
 
-			if all_flag && !argv.empty?
+			if options[ :all ] && !argv.empty?
 				err.puts "#{BADGE} --all and repo target are mutually exclusive. Use: carson housekeep --all OR carson housekeep [repo]"
 				return { command: :invalid }
 			end
 
-			return { command: "housekeep:all", json: json_flag } if all_flag
+			return { command: "housekeep:all", json: options[ :json ] } if options[ :all ]
 
 			if argv.length > 1
 				err.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
@@ -329,11 +630,16 @@ module Carson
 			end
 
 			target = argv.shift
-			return { command: "housekeep:target", target: target, json: json_flag } if target
+			return { command: "housekeep:target", target: target, json: options[ :json ] } if target
 
-			{ command: "housekeep", json: json_flag }
+			{ command: "housekeep", json: options[ :json ] }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
 		end
 
+		# --- govern ---
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -342,12 +648,23 @@ module Carson
 			}
 			govern_parser = OptionParser.new do |opts|
 				opts.banner = "Usage: carson govern [--dry-run] [--json] [--loop SECONDS]"
+				opts.separator ""
+				opts.separator "Portfolio-level PR triage loop."
+				opts.separator "Scans governed repositories, classifies open PRs, and takes action"
+				opts.separator "(merge, request review, or report). Runs once by default."
+				opts.separator ""
+				opts.separator "Options:"
 				opts.on( "--dry-run", "Run all checks but do not merge or dispatch" ) { options[ :dry_run ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.on( "--loop SECONDS", Integer, "Run continuously, sleeping SECONDS between cycles" ) do |s|
 					err.puts( "#{BADGE} Error: --loop must be a positive integer" ) || ( return { command: :invalid } ) if s < 1
 					options[ :loop_seconds ] = s
 				end
+				opts.separator ""
+				opts.separator "Examples:"
+				opts.separator "    carson govern                  Triage all governed repos once"
+				opts.separator "    carson govern --dry-run        Preview actions without applying them"
+				opts.separator "    carson govern --loop 300       Run continuously every 5 minutes"
 			end
 			govern_parser.parse!( argv )
 			unless argv.empty?
@@ -367,6 +684,8 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- dispatch ---
+
 		def self.dispatch( parsed:, runtime: )
 			command = parsed.fetch( :command )
 			return Runtime::EXIT_ERROR if command == :invalid
@@ -425,6 +744,14 @@ module Carson
 					json_output: parsed.fetch( :json, false ),
 					loop_seconds: parsed.fetch( :loop_seconds, nil )
 				)
+			when "template:check:all"
+				runtime.template_check_all!
+			when "audit:all"
+				runtime.audit_all!
+			when "sync:all"
+				runtime.sync_all!
+			when "status:all"
+				runtime.status_all!( json_output: parsed.fetch( :json, false ) )
 			else
 				runtime.send( :puts_line, "Unknown command: #{command}" )
 				Runtime::EXIT_ERROR

data/lib/carson/runtime/audit.rb

@@ -157,6 +157,54 @@ module Carson
 				exit_code
 			end
 
+			# Runs audit across all governed repositories.
+			def audit_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Audit all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				passed = 0
+				blocked = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.audit!
+						case status
+						when EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							passed += 1
+						when EXIT_BLOCK
+							puts_line "#{repo_name}: BLOCK" unless verbose?
+							blocked += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
+				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 		private
 			def pr_and_check_report
 				report = {

data/lib/carson/runtime/local/onboard.rb

@@ -81,6 +81,8 @@ module Carson
 			end
 
 			# Re-applies hooks, templates, and audit across all governed repositories.
+			# Checks each repo for safety (active worktrees, uncommitted changes) and
+			# skips unsafe repos to avoid disrupting active work.
 			def refresh_all!
 				repos = config.govern_repos
 				if repos.empty?
@@ -92,6 +94,7 @@ module Carson
 				puts_line ""
 				puts_line "Refresh all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
 				refreshed = 0
+				skipped = 0
 				failed = 0
 
 				repos.each do |repo_path|
@@ -102,6 +105,13 @@ module Carson
 						next
 					end
 
+					safety = portfolio_repo_safety( repo_path: repo_path )
+					unless safety.fetch( :safe )
+						puts_line "#{repo_name}: SKIP (#{safety.fetch( :reasons ).join( ', ' )})"
+						skipped += 1
+						next
+					end
+
 					status = refresh_single_repo( repo_path: repo_path, repo_name: repo_name )
 					if status == EXIT_ERROR
 						failed += 1
@@ -111,8 +121,11 @@ module Carson
 				end
 
 				puts_line ""
-				puts_line "Refresh all complete: #{refreshed} refreshed, #{failed} failed."
-				failed.zero? ? EXIT_OK : EXIT_ERROR
+				parts = [ "#{refreshed} refreshed" ]
+				parts << "#{skipped} skipped" if skipped.positive?
+				parts << "#{failed} failed" if failed.positive?
+				puts_line "Refresh all complete: #{parts.join( ', ' )}."
+				failed.zero? && skipped.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
 			def prune_all!

data/lib/carson/runtime/local/sync.rb

@@ -42,6 +42,49 @@ module Carson
 				git_system!( "switch", start_branch ) if switched && branch_exists?( branch_name: start_branch )
 			end
 
+			# Syncs main branch across all governed repositories.
+			def sync_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Sync all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				synced = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.sync!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							synced += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Sync all complete: #{synced} synced, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
 		private
 
 			# Runs a git command, suppressing stdout/stderr in JSON mode to keep output clean.

data/lib/carson/runtime/local/template.rb

@@ -43,6 +43,50 @@ module Carson
 				( drift_count + stale_count ).positive? ? EXIT_BLOCK : EXIT_OK
 			end
 
+			# Read-only template drift check across all governed repositories.
+			def template_check_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Template check all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				in_sync = 0
+				drifted = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.template_check!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: in sync" unless verbose?
+							in_sync += 1
+						else
+							puts_line "#{repo_name}: DRIFT" unless verbose?
+							drifted += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Template check complete: #{in_sync} in sync, #{drifted} drifted, #{failed} failed."
+				drifted.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 			# Applies managed template files as full-file writes from Carson sources.
 			# Also removes superseded files that are no longer part of the managed set.
 			def template_apply!( push_prep: false )

data/lib/carson/runtime/status.rb

@@ -17,6 +17,65 @@ module Carson
 				EXIT_OK
 			end
 
+			# Portfolio-wide status overview across all governed repositories.
+			def status_all!( json_output: false )
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				if json_output
+					results = []
+					repos.each do |repo_path|
+						repo_name = File.basename( repo_path )
+						unless Dir.exist?( repo_path )
+							results << { name: repo_name, status: "error", error: "path not found" }
+							next
+						end
+						begin
+							rt = build_scoped_runtime( repo_path: repo_path )
+							data = rt.send( :gather_status )
+							results << { name: repo_name, status: "ok" }.merge( data )
+						rescue StandardError => e
+							results << { name: repo_name, status: "error", error: e.message }
+						end
+					end
+					out.puts JSON.pretty_generate( { command: "status", repos: results } )
+					return EXIT_OK
+				end
+
+				puts_line "Carson #{Carson::VERSION} — Portfolio (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				puts_line ""
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: MISSING"
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						data = rt.send( :gather_status )
+						branch = data.fetch( :branch )
+						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
+						worktrees = data.fetch( :worktrees )
+						gov = data.fetch( :governance )
+						parts = []
+						parts << branch.fetch( :name ) + dirty
+						parts << "#{worktrees.count} worktree#{plural_suffix( count: worktrees.count )}" if worktrees.any?
+						parts << "templates #{gov.fetch( :templates )}" unless gov.fetch( :templates ) == :in_sync
+						puts_line "#{repo_name}: #{parts.join( '  ' )}"
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+					end
+				end
+
+				EXIT_OK
+			end
+
 		private
 
 			# Collects all status facets into a structured hash.

data/lib/carson/runtime.rb

@@ -212,6 +212,48 @@ module Carson
 		def gh_run( *args )
 			github_adapter.run( *args )
 		end
+
+		# --- Portfolio helpers (shared by all --all commands) ---
+
+		# Checks whether a governed repo is safe for batch operations.
+		# Returns { safe: true/false, reasons: [...] }.
+		# Safe means: no active worktrees beyond main, no uncommitted changes.
+		# Non-git directories pass through as safe — let the command handle the error.
+		def portfolio_repo_safety( repo_path: )
+			git = Adapters::Git.new( repo_root: repo_path )
+
+			# Non-git directories pass through — the calling command reports the real error.
+			stdout, _, git_ok, = git.run( "rev-parse", "--is-inside-work-tree" )
+			return { safe: true, reasons: [] } unless git_ok && stdout.to_s.strip == "true"
+
+			reasons = []
+
+			# Active worktrees beyond the main working tree.
+			rt = build_scoped_runtime( repo_path: repo_path )
+			worktrees = rt.send( :worktree_list )
+			main_root = rt.send( :realpath_safe, repo_path )
+			active = worktrees.reject { |wt| wt.fetch( :path ) == main_root }
+			if active.any?
+				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
+			end
+
+			# Uncommitted changes in the main working tree.
+			stdout, _, success, = git.run( "status", "--porcelain" )
+			if success && !stdout.strip.empty?
+				reasons << "uncommitted changes"
+			end
+
+			{ safe: reasons.empty?, reasons: reasons }
+		rescue StandardError => e
+			{ safe: false, reasons: [ e.message ] }
+		end
+
+		# Creates a scoped Runtime for a governed repo with captured output.
+		def build_scoped_runtime( repo_path: )
+			buf = verbose? ? out : StringIO.new
+			err_buf = verbose? ? err : StringIO.new
+			Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+		end
 	end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.16.0
+  version: 3.18.0
 platform: ruby
 authors:
 - Hailei Wang