carson 2.8.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3f3bf2f0ea58a2d460c36fb57b6313d5dab97c08b76ec94ae1c1e9b685b24f
-  data.tar.gz: 48562197450233540c28a6fa912c38eaa636910ed3bab57e32e95d7b0b66c10a
+  metadata.gz: 45443353a34297748fec8177c152d898dabb8cf7f1641d7870b7aff59d9a2f6c
+  data.tar.gz: 627bdc81dcf78ad41998840796a3427512c39b6b2e80e2b961895bdf4423a456
 SHA512:
-  metadata.gz: 63a4d9fed728d78b2fcaf0d0d6ffb158a93e464af24997d661b24d77a2764e4a84014f45d4cfe2e204c7bac337c796f8e69e3722fe30a135f98650176271dba3
-  data.tar.gz: aba034301bccbf786198a1a44bd767d3f239370807a68841a89b6ffc40340719ef37dea2ddae9a0d54eedadf1b42c2446d02614721ab946586b809de0438a2d4
+  metadata.gz: 96a9e858b5d934d5e5570443e25b79e28255cfe54279623be8d44474e55d592a7c9cd3161da8611d84fd24141cd10a98b6922fb364609630d843f651858bf78c
+  data.tar.gz: ee85efae91e54e07d872c560ad7305553b3d45246f9ec502b6fef5b7d1e6e843c8a03787629adb55190541cf5101be76a3f3ee625ec31540876b718905013ba4

data/RELEASE.md

@@ -5,6 +5,79 @@ 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`.
 
+## 2.9.0 — Concise UX for All Commands
+
+### What changed
+
+- **Concise output by default.** Every Carson command now prints clean, minimal output — what happened, what needs attention, what to do next. Diagnostic key-value lines are suppressed unless `--verbose` is passed.
+- **`--verbose` flag.** Global flag available on all commands. Restores full diagnostic output (same as pre-2.9.0 behaviour). The pre-commit hook runs `carson audit` (no flags) so it automatically gets clean output.
+- **Audit concise output.** A healthy audit prints one line (`Audit: ok`). Problems print only actionable summaries (e.g. `Hooks: mismatch — run carson prepare.`).
+- **Refresh concise output.** Prints ~5 lines: hooks installed, templates in sync, audit result, done.
+- **All other commands.** `prepare`, `inspect`, `offboard`, `template check/apply`, `prune`, `review gate/sweep`, `govern`, `lint setup`, `setup`, and `housekeep` all follow the same concise/verbose pattern.
+
+### What users must do now
+
+1. Upgrade Carson to `2.9.0`.
+2. Use `--verbose` when you need full diagnostics (debugging, CI troubleshooting).
+
+### Breaking or removed behaviour
+
+- Default output is now concise. Scripts that parse Carson's key-value diagnostic lines must add `--verbose`.
+- Removed `@concise` internal flag (replaced by `--verbose` opt-in pattern).
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+```
+
+## 2.8.1 — Onboard UX and Install Cleanup
+
+### What changed
+
+- **Concise onboard output.** `carson onboard` now prints a clean 8-line summary instead of verbose internal state (hook paths, template statuses, config lines). Tells users what happened, what needs attention, and what to do next.
+- **Graceful handling of fresh repos.** Onboard no longer fails with a fatal error on repositories with no commits yet.
+- **Suppressed RubyGems PATH warning.** The misleading `WARNING: You don't have ... in your PATH, gem executables will not run` message from `gem install --user-install` is now suppressed during installation. Carson symlinks the executable to `~/.carson/bin`, making the gem bin directory irrelevant.
+- **Default workflow style changed from `trunk` to `branch`.** All governed repositories now enforce PR-only merges by default. Direct commits, merge commits, and pushes to protected branches (`main`/`master`) are blocked by hooks unless explicitly opted out.
+
+### What users must do now
+
+1. Upgrade Carson to `2.8.1`.
+2. If you rely on direct commits to main, re-run `carson setup` and choose `trunk`, or set `CARSON_WORKFLOW_STYLE=trunk` in your environment.
+
+### Breaking or removed behaviour
+
+- Default `workflow.style` changed from `trunk` to `branch`. Repositories that previously relied on the implicit `trunk` default will now block direct commits to protected branches. Escape hatches: run `carson setup` to choose `trunk`, or set `CARSON_WORKFLOW_STYLE=trunk`.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+```
+
+### Engineering Appendix
+
+#### Modified components
+
+- `lib/carson/runtime.rb` — added `concise?` flag and `with_captured_output` helper for suppressing sub-command detail during onboard.
+- `lib/carson/runtime/local.rb` — rewrote `onboard!` to use concise orchestration (`onboard_apply!`), added `onboard_report_remote!` and `onboard_run_audit!` helpers, added `unless concise?` guards to `prepare!` and `template_apply!`.
+- `install.sh` — capture `gem install` stderr and filter out RubyGems PATH warning.
+- `script/install_global_carson.sh` — same PATH warning suppression.
+- `test/runtime_govern_test.rb` — updated onboard output assertions.
+
+#### Public interface and config changes
+
+- No new CLI commands or config keys.
+- Exit status contract unchanged.
+
+---
+
 ## 2.8.0 — Interactive Setup and Remote Detection
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.8.0
+2.9.0

data/lib/carson/cli.rb

@@ -19,7 +19,8 @@ module Carson
 				return Runtime::EXIT_ERROR
 			end
 
-			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, out: out, err: err )
+			verbose = parsed.fetch( :verbose, false )
+			runtime = Runtime.new( repo_root: target_repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 			dispatch( parsed: parsed, runtime: runtime )
 		rescue ConfigError => e
 			err.puts "#{BADGE} CONFIG ERROR: #{e.message}"
@@ -30,12 +31,14 @@ module Carson
 		end
 
 		def self.parse_args( argv:, out:, err: )
+			verbose = argv.delete( "--verbose" ) ? true : false
 			parser = build_parser
 			preset = parse_preset_command( argv: argv, out: out, parser: parser )
-			return preset unless preset.nil?
+			return preset.merge( verbose: verbose ) unless preset.nil?
 
 			command = argv.shift
-			parse_command( command: command, argv: argv, parser: parser, err: err )
+			result = parse_command( command: command, argv: argv, parser: parser, err: err )
+			result.merge( verbose: verbose )
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
 			err.puts parser

data/lib/carson/runtime/audit.rb

@@ -8,42 +8,62 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 				audit_state = "ok"
-				print_header "Repository"
-				puts_line "root: #{repo_root}"
-				puts_line "current_branch: #{current_branch}"
-				print_header "Working Tree"
-				puts_line git_capture!( "status", "--short", "--branch" ).strip
-				print_header "Hooks"
+				audit_concise_problems = []
+				puts_verbose ""
+				puts_verbose "[Repository]"
+				puts_verbose "root: #{repo_root}"
+				puts_verbose "current_branch: #{current_branch}"
+				puts_verbose ""
+				puts_verbose "[Working Tree]"
+				puts_verbose git_capture!( "status", "--short", "--branch" ).strip
+				puts_verbose ""
+				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
-				audit_state = "block" unless hooks_ok
-				print_header "Local Lint Quality"
+				unless hooks_ok
+					audit_state = "block"
+					audit_concise_problems << "Hooks: mismatch — run carson prepare."
+				end
+				puts_verbose ""
+				puts_verbose "[Local Lint Quality]"
 				local_lint_quality = local_lint_quality_report
-				audit_state = "block" if local_lint_quality.fetch( :status ) == "block"
-				print_header "Main Sync Status"
+				if local_lint_quality.fetch( :status ) == "block"
+					audit_state = "block"
+					blocking_langs = local_lint_quality.fetch( :languages ).select { |l| l.fetch( :status ) == "block" }
+					blocking_langs.each do |lang|
+						exit_code = lang.fetch( :exit_code, 1 )
+						audit_concise_problems << "Lint: #{lang.fetch( :language )} failed (exit #{exit_code})."
+					end
+				end
+				puts_verbose ""
+				puts_verbose "[Main Sync Status]"
 				ahead_count, behind_count, main_error = main_sync_counts
 				if main_error
-					puts_line "main_vs_remote_main: unknown"
-					puts_line "WARN: unable to calculate main sync status (#{main_error})."
+					puts_verbose "main_vs_remote_main: unknown"
+					puts_verbose "WARN: unable to calculate main sync status (#{main_error})."
 					audit_state = "attention" if audit_state == "ok"
 				elsif ahead_count.positive?
-					puts_line "main_vs_remote_main_ahead: #{ahead_count}"
-					puts_line "main_vs_remote_main_behind: #{behind_count}"
-					puts_line "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
+					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
+					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
+					puts_verbose "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
 					audit_state = "block"
+					audit_concise_problems << "Main sync: ahead by #{ahead_count} — reset local drift."
 				elsif behind_count.positive?
-					puts_line "main_vs_remote_main_ahead: #{ahead_count}"
-					puts_line "main_vs_remote_main_behind: #{behind_count}"
-					puts_line "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
+					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
+					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
+					puts_verbose "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
 					audit_state = "attention" if audit_state == "ok"
+					audit_concise_problems << "Main sync: behind by #{behind_count} — run carson sync."
 				else
-					puts_line "main_vs_remote_main_ahead: 0"
-					puts_line "main_vs_remote_main_behind: 0"
-					puts_line "ACTION: local #{config.main_branch} is in sync with #{config.git_remote}/#{config.main_branch}."
+					puts_verbose "main_vs_remote_main_ahead: 0"
+					puts_verbose "main_vs_remote_main_behind: 0"
+					puts_verbose "ACTION: local #{config.main_branch} is in sync with #{config.git_remote}/#{config.main_branch}."
 				end
-				print_header "PR and Required Checks (gh)"
+				puts_verbose ""
+				puts_verbose "[PR and Required Checks (gh)]"
 				monitor_report = pr_and_check_report
 				audit_state = "attention" if audit_state == "ok" && monitor_report.fetch( :status ) != "ok"
-				print_header "Default Branch CI Baseline (gh)"
+				puts_verbose ""
+				puts_verbose "[Default Branch CI Baseline (gh)]"
 				default_branch_baseline = default_branch_ci_baseline_report
 				audit_state = "block" if default_branch_baseline.fetch( :status ) == "block"
 				audit_state = "attention" if audit_state == "ok" && default_branch_baseline.fetch( :status ) != "ok"
@@ -56,9 +76,14 @@ module Carson
 							audit_status: audit_state
 						)
 					)
-				print_header "Audit Result"
-				puts_line "status: #{audit_state}"
-				puts_line( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+				puts_verbose ""
+				puts_verbose "[Audit Result]"
+				puts_verbose "status: #{audit_state}"
+				puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+				unless verbose?
+					audit_concise_problems.each { |problem| puts_line problem }
+					puts_line "Audit: #{audit_state}"
+				end
 				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
 			end
 
@@ -83,7 +108,7 @@ module Carson
 				unless gh_available?
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "gh CLI not available in PATH"
-					puts_line "SKIP: #{report.fetch( :skip_reason )}"
+					puts_verbose "SKIP: #{report.fetch( :skip_reason )}"
 					return report
 				end
 				pr_stdout, pr_stderr, pr_success, = gh_run( "pr", "view", current_branch, "--json", "number,title,url,state,reviewDecision" )
@@ -91,7 +116,7 @@ module Carson
 					error_text = gh_error_text( stdout_text: pr_stdout, stderr_text: pr_stderr, fallback: "unable to read PR for branch #{current_branch}" )
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = error_text
-					puts_line "SKIP: #{error_text}"
+					puts_verbose "SKIP: #{error_text}"
 					return report
 				end
 				pr_data = JSON.parse( pr_stdout )
@@ -102,16 +127,16 @@ module Carson
 				state: pr_data[ "state" ].to_s,
 				review_decision: blank_to( value: pr_data[ "reviewDecision" ], default: "NONE" )
 				}
-				puts_line "pr: ##{report.dig( :pr, :number )} #{report.dig( :pr, :title )}"
-				puts_line "url: #{report.dig( :pr, :url )}"
-				puts_line "review_decision: #{report.dig( :pr, :review_decision )}"
+				puts_verbose "pr: ##{report.dig( :pr, :number )} #{report.dig( :pr, :title )}"
+				puts_verbose "url: #{report.dig( :pr, :url )}"
+				puts_verbose "review_decision: #{report.dig( :pr, :review_decision )}"
 				checks_stdout, checks_stderr, checks_success, checks_exit = gh_run( "pr", "checks", report.dig( :pr, :number ).to_s, "--required", "--json", "name,state,bucket,workflow,link" )
 				if checks_stdout.to_s.strip.empty?
 					error_text = gh_error_text( stdout_text: checks_stdout, stderr_text: checks_stderr, fallback: "required checks unavailable" )
 					report[ :checks ][ :status ] = "skipped"
 					report[ :checks ][ :skip_reason ] = error_text
 					report[ :status ] = "attention"
-					puts_line "checks: SKIP (#{error_text})"
+					puts_verbose "checks: SKIP (#{error_text})"
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
@@ -123,17 +148,17 @@ module Carson
 				report[ :checks ][ :pending_count ] = pending.count
 				report[ :checks ][ :failing ] = normalise_check_entries( entries: failing )
 				report[ :checks ][ :pending ] = normalise_check_entries( entries: pending )
-				puts_line "required_checks_total: #{report.dig( :checks, :required_total )}"
-				puts_line "required_checks_failing: #{report.dig( :checks, :failing_count )}"
-				puts_line "required_checks_pending: #{report.dig( :checks, :pending_count )}"
-				report.dig( :checks, :failing ).each { |entry| puts_line "check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.dig( :checks, :pending ).each { |entry| puts_line "check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				puts_verbose "required_checks_total: #{report.dig( :checks, :required_total )}"
+				puts_verbose "required_checks_failing: #{report.dig( :checks, :failing_count )}"
+				puts_verbose "required_checks_pending: #{report.dig( :checks, :pending_count )}"
+				report.dig( :checks, :failing ).each { |entry| puts_verbose "check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.dig( :checks, :pending ).each { |entry| puts_verbose "check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
 				report[ :status ] = "attention" if report.dig( :checks, :failing_count ).positive? || report.dig( :checks, :pending_count ).positive?
 				report
 				rescue JSON::ParserError => e
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
-					puts_line "SKIP: #{report.fetch( :skip_reason )}"
+					puts_verbose "SKIP: #{report.fetch( :skip_reason )}"
 					report
 				end
 
@@ -148,8 +173,8 @@ module Carson
 					blocking_languages: 0,
 					languages: []
 				}
-				puts_line "lint_target_source: #{target_source}"
-				puts_line "lint_target_files_total: #{target_files.count}"
+				puts_verbose "lint_target_source: #{target_source}"
+				puts_verbose "lint_target_files_total: #{target_files.count}"
 				config.lint_languages.each do |language, entry|
 					language_report = lint_language_report(
 						language: language,
@@ -162,7 +187,7 @@ module Carson
 					report[ :status ] = "block"
 					report[ :blocking_languages ] += 1
 				end
-				puts_line "lint_blocking_languages: #{report.fetch( :blocking_languages )}"
+				puts_verbose "lint_blocking_languages: #{report.fetch( :blocking_languages )}"
 				report
 			rescue StandardError => e
 				report ||= {
@@ -191,7 +216,7 @@ module Carson
 				if github_pull_request_event?
 					files = lint_target_files_for_pull_request
 					return [ files, "github_pull_request" ] unless files.nil?
-					puts_line "WARN: unable to resolve pull request changed files; falling back to full repository files."
+					puts_verbose "WARN: unable to resolve pull request changed files; falling back to full repository files."
 				end
 
 				if github_actions_environment?
@@ -265,16 +290,16 @@ module Carson
 					config_files: entry.fetch( :config_files ),
 					exit_code: 0
 				}
-				puts_line "lint_language: #{language} enabled=#{report.fetch( :enabled )} files=#{report.fetch( :file_count )}"
+				puts_verbose "lint_language: #{language} enabled=#{report.fetch( :enabled )} files=#{report.fetch( :file_count )}"
 				if language == "ruby" && outsider_mode?
 					local_rubocop_path = File.join( repo_root, ".rubocop.yml" )
 					if File.file?( local_rubocop_path )
 						report[ :status ] = "block"
 						report[ :reason ] = "repo-local RuboCop config is forbidden: #{relative_path( local_rubocop_path )}; remove it and use ~/.carson/lint/rubocop.yml."
 						report[ :exit_code ] = EXIT_BLOCK
-						puts_line "lint_#{language}_status: block"
-						puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
-						puts_line "ACTION: remove .rubocop.yml from this repository and run carson lint setup --source <path-or-git-url>."
+						puts_verbose "lint_#{language}_status: block"
+						puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
+						puts_verbose "ACTION: remove .rubocop.yml from this repository and run carson lint setup --source <path-or-git-url>."
 						return report
 					end
 				end
@@ -286,9 +311,9 @@ module Carson
 					report[ :status ] = "block"
 					report[ :reason ] = "missing config files: #{missing_config_files.join( ', ' )}"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
-					puts_line "ACTION: run carson lint setup --source <path-or-git-url> to prepare ~/.carson/lint policy files."
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "ACTION: run carson lint setup --source <path-or-git-url> to prepare ~/.carson/lint policy files."
 					return report
 				end
 
@@ -298,16 +323,16 @@ module Carson
 					report[ :status ] = "block"
 					report[ :reason ] = "missing lint command"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
 					return report
 				end
 				unless command_available_for_lint?( command_name: command_name )
 					report[ :status ] = "block"
 					report[ :reason ] = "command not available: #{command_name}"
 					report[ :exit_code ] = EXIT_BLOCK
-					puts_line "lint_#{language}_status: block"
-					puts_line "lint_#{language}_reason: #{report.fetch( :reason )}"
+					puts_verbose "lint_#{language}_status: block"
+					puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}"
 					return report
 				end
 
@@ -322,9 +347,9 @@ module Carson
 						fallback: "lint command failed for #{language}"
 					)
 				end
-				puts_line "lint_#{language}_status: #{report.fetch( :status )}"
-				puts_line "lint_#{language}_exit: #{report.fetch( :exit_code )}"
-				puts_line "lint_#{language}_reason: #{report.fetch( :reason )}" unless report.fetch( :reason ).nil?
+				puts_verbose "lint_#{language}_status: #{report.fetch( :status )}"
+				puts_verbose "lint_#{language}_exit: #{report.fetch( :exit_code )}"
+				puts_verbose "lint_#{language}_reason: #{report.fetch( :reason )}" unless report.fetch( :reason ).nil?
 				report
 			end
 
@@ -405,7 +430,7 @@ module Carson
 				unless gh_available?
 					report[ :status ] = "skipped"
 					report[ :skip_reason ] = "gh CLI not available in PATH"
-					puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+					puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 					return report
 				end
 				owner, repo = repository_coordinates
@@ -455,32 +480,32 @@ module Carson
 				report[ :status ] = "block" if report.fetch( :pending_count ).positive?
 				report[ :status ] = "block" if report.fetch( :no_check_evidence )
 				report[ :status ] = "attention" if report.fetch( :status ) == "ok" && ( report.fetch( :advisory_failing_count ).positive? || report.fetch( :advisory_pending_count ).positive? )
-				puts_line "default_branch_repository: #{report.fetch( :repository )}"
-				puts_line "default_branch_name: #{report.fetch( :default_branch )}"
-				puts_line "default_branch_head_sha: #{report.fetch( :head_sha )}"
-				puts_line "default_branch_workflows_total: #{report.fetch( :workflows_total )}"
-				puts_line "default_branch_check_runs_total: #{report.fetch( :check_runs_total )}"
-				puts_line "default_branch_failing: #{report.fetch( :failing_count )}"
-				puts_line "default_branch_pending: #{report.fetch( :pending_count )}"
-				puts_line "default_branch_advisory_failing: #{report.fetch( :advisory_failing_count )}"
-				puts_line "default_branch_advisory_pending: #{report.fetch( :advisory_pending_count )}"
-				report.fetch( :failing ).each { |entry| puts_line "default_branch_check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.fetch( :pending ).each { |entry| puts_line "default_branch_check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
-				report.fetch( :advisory_failing ).each { |entry| puts_line "default_branch_check_advisory_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
-				report.fetch( :advisory_pending ).each { |entry| puts_line "default_branch_check_advisory_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
+				puts_verbose "default_branch_repository: #{report.fetch( :repository )}"
+				puts_verbose "default_branch_name: #{report.fetch( :default_branch )}"
+				puts_verbose "default_branch_head_sha: #{report.fetch( :head_sha )}"
+				puts_verbose "default_branch_workflows_total: #{report.fetch( :workflows_total )}"
+				puts_verbose "default_branch_check_runs_total: #{report.fetch( :check_runs_total )}"
+				puts_verbose "default_branch_failing: #{report.fetch( :failing_count )}"
+				puts_verbose "default_branch_pending: #{report.fetch( :pending_count )}"
+				puts_verbose "default_branch_advisory_failing: #{report.fetch( :advisory_failing_count )}"
+				puts_verbose "default_branch_advisory_pending: #{report.fetch( :advisory_pending_count )}"
+				report.fetch( :failing ).each { |entry| puts_verbose "default_branch_check_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.fetch( :pending ).each { |entry| puts_verbose "default_branch_check_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} #{entry.fetch( :link )}".strip }
+				report.fetch( :advisory_failing ).each { |entry| puts_verbose "default_branch_check_advisory_fail: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
+				report.fetch( :advisory_pending ).each { |entry| puts_verbose "default_branch_check_advisory_pending: #{entry.fetch( :workflow )} / #{entry.fetch( :name )} (advisory) #{entry.fetch( :link )}".strip }
 				if report.fetch( :no_check_evidence )
-					puts_line "ACTION: default branch has workflow files but no check-runs; align workflow triggers and branch protection check names."
+					puts_verbose "ACTION: default branch has workflow files but no check-runs; align workflow triggers and branch protection check names."
 				end
 				report
 			rescue JSON::ParserError => e
 				report[ :status ] = "skipped"
 				report[ :skip_reason ] = "invalid gh JSON response (#{e.message})"
-				puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
 			rescue StandardError => e
 				report[ :status ] = "skipped"
 				report[ :skip_reason ] = e.message
-				puts_line "baseline: SKIP (#{report.fetch( :skip_reason )})"
+				puts_verbose "baseline: SKIP (#{report.fetch( :skip_reason )})"
 				report
 			end
 
@@ -577,10 +602,10 @@ module Carson
 			# Writes monitor report artefacts and prints their locations.
 			def write_and_print_pr_monitor_report( report: )
 				markdown_path, json_path = write_pr_monitor_report( report: report )
-				puts_line "report_markdown: #{markdown_path}"
-				puts_line "report_json: #{json_path}"
+				puts_verbose "report_markdown: #{markdown_path}"
+				puts_verbose "report_json: #{json_path}"
 			rescue StandardError => e
-				puts_line "report_write: SKIP (#{e.message})"
+				puts_verbose "report_write: SKIP (#{e.message})"
 			end
 
 			# Persists report in both machine-readable JSON and human-readable Markdown.
@@ -703,28 +728,29 @@ module Carson
 				return { status: "ok", split_required: false } if files.empty?
 
 				scope = scope_integrity_status( files: files, branch: current_branch )
-				print_header "Scope Integrity Guard"
-				puts_line "scope_file_source: #{files_source}"
-				puts_line "scope_file_count: #{files.count}"
-				puts_line "branch: #{scope.fetch( :branch )}"
-				puts_line "scope_basis: changed_paths_only"
-				puts_line "detected_groups: #{scope.fetch( :detected_groups ).sort.join( ', ' )}"
-				puts_line "core_groups: #{scope.fetch( :core_groups ).empty? ? 'none' : scope.fetch( :core_groups ).sort.join( ', ' )}"
-				puts_line "non_doc_groups: #{scope.fetch( :non_doc_groups ).empty? ? 'none' : scope.fetch( :non_doc_groups ).sort.join( ', ' )}"
-				puts_line "docs_only_changes: #{scope.fetch( :docs_only )}"
-				puts_line "unmatched_paths_count: #{scope.fetch( :unmatched_paths ).count}"
-				scope.fetch( :unmatched_paths ).each { |path| puts_line "unmatched_path: #{path}" }
-				puts_line "violating_files_count: #{scope.fetch( :violating_files ).count}"
-				scope.fetch( :violating_files ).each { |path| puts_line "violating_file: #{path} (group=#{scope.fetch( :grouped_paths ).fetch( path )})" }
-				puts_line "checklist_single_business_intent: pass"
-				puts_line "checklist_single_scope_group: #{scope.fetch( :split_required ) ? 'advisory' : 'pass'}"
-				puts_line "checklist_cross_boundary_changes_justified: #{( scope.fetch( :split_required ) || scope.fetch( :misc_present ) ) ? 'advisory' : 'pass'}"
+				puts_verbose ""
+				puts_verbose "[Scope Integrity Guard]"
+				puts_verbose "scope_file_source: #{files_source}"
+				puts_verbose "scope_file_count: #{files.count}"
+				puts_verbose "branch: #{scope.fetch( :branch )}"
+				puts_verbose "scope_basis: changed_paths_only"
+				puts_verbose "detected_groups: #{scope.fetch( :detected_groups ).sort.join( ', ' )}"
+				puts_verbose "core_groups: #{scope.fetch( :core_groups ).empty? ? 'none' : scope.fetch( :core_groups ).sort.join( ', ' )}"
+				puts_verbose "non_doc_groups: #{scope.fetch( :non_doc_groups ).empty? ? 'none' : scope.fetch( :non_doc_groups ).sort.join( ', ' )}"
+				puts_verbose "docs_only_changes: #{scope.fetch( :docs_only )}"
+				puts_verbose "unmatched_paths_count: #{scope.fetch( :unmatched_paths ).count}"
+				scope.fetch( :unmatched_paths ).each { |path| puts_verbose "unmatched_path: #{path}" }
+				puts_verbose "violating_files_count: #{scope.fetch( :violating_files ).count}"
+				scope.fetch( :violating_files ).each { |path| puts_verbose "violating_file: #{path} (group=#{scope.fetch( :grouped_paths ).fetch( path )})" }
+				puts_verbose "checklist_single_business_intent: pass"
+				puts_verbose "checklist_single_scope_group: #{scope.fetch( :split_required ) ? 'advisory' : 'pass'}"
+				puts_verbose "checklist_cross_boundary_changes_justified: #{( scope.fetch( :split_required ) || scope.fetch( :misc_present ) ) ? 'advisory' : 'pass'}"
 				if scope.fetch( :split_required )
-					puts_line "ACTION: multiple module groups detected (informational only)."
+					puts_verbose "ACTION: multiple module groups detected (informational only)."
 				elsif scope.fetch( :misc_present )
-					puts_line "ACTION: unmatched paths detected; classify via scope.path_groups for stricter module checks."
+					puts_verbose "ACTION: unmatched paths detected; classify via scope.path_groups for stricter module checks."
 				else
-					puts_line "ACTION: scope integrity is within commit policy."
+					puts_verbose "ACTION: scope integrity is within commit policy."
 				end
 				{ status: scope.fetch( :status ), split_required: scope.fetch( :split_required ) }
 			end

data/lib/carson/runtime/govern.rb

@@ -83,7 +83,8 @@ module Carson
 
 			# Standalone housekeep: sync + prune.
 			def housekeep!
-				print_header "Housekeep"
+				puts_verbose ""
+				puts_verbose "[Housekeep]"
 				sync_status = sync!
 				if sync_status != EXIT_OK
 					puts_line "housekeep: sync returned #{sync_status}; skipping prune."
@@ -571,8 +572,8 @@ module Carson
 				md_path = File.join( report_dir, GOVERN_REPORT_MD )
 				File.write( json_path, JSON.pretty_generate( report ) )
 				File.write( md_path, render_govern_markdown( report: report ) )
-				puts_line "report_json: #{json_path}"
-				puts_line "report_markdown: #{md_path}"
+				puts_verbose "report_json: #{json_path}"
+				puts_verbose "report_markdown: #{md_path}"
 			end
 
 			def render_govern_markdown( report: )
@@ -632,7 +633,11 @@ module Carson
 				end
 
 				repos_count = Array( report[ :repos ] ).length
-				puts_line "govern_summary: repos=#{repos_count} prs=#{total_prs} ready=#{ready_count} blocked=#{blocked_count}"
+				if verbose?
+					puts_line "govern_summary: repos=#{repos_count} prs=#{total_prs} ready=#{ready_count} blocked=#{blocked_count}"
+				else
+					puts_line "Govern: #{repos_count} repo#{plural_suffix( count: repos_count )}, #{total_prs} PR#{plural_suffix( count: total_prs )} (#{ready_count} ready, #{blocked_count} blocked)"
+				end
 			end
 		end
 

data/lib/carson/runtime/lint.rb

@@ -7,7 +7,8 @@ module Carson
 		module Lint
 			# Prepares canonical lint policy files under ~/.carson/lint from an explicit source.
 			def lint_setup!( source:, ref: "main", force: false )
-				print_header "Lint Setup"
+				puts_verbose ""
+				puts_verbose "[Lint Setup]"
 				source_text = source.to_s.strip
 				if source_text.empty?
 					puts_line "ERROR: lint setup requires --source <path-or-git-url>."
@@ -29,12 +30,12 @@ module Carson
 						target_coding_dir: target_coding_dir,
 						force: force
 					)
-					puts_line "lint_setup_source: #{source_text}"
-					puts_line "lint_setup_ref: #{ref_text}" if lint_source_git_url?( source: source_text )
-					puts_line "lint_setup_target: #{target_coding_dir}"
-					puts_line "lint_setup_created: #{copy_result.fetch( :created )}"
-					puts_line "lint_setup_updated: #{copy_result.fetch( :updated )}"
-					puts_line "lint_setup_skipped: #{copy_result.fetch( :skipped )}"
+					puts_verbose "lint_setup_source: #{source_text}"
+					puts_verbose "lint_setup_ref: #{ref_text}" if lint_source_git_url?( source: source_text )
+					puts_verbose "lint_setup_target: #{target_coding_dir}"
+					puts_verbose "lint_setup_created: #{copy_result.fetch( :created )}"
+					puts_verbose "lint_setup_updated: #{copy_result.fetch( :updated )}"
+					puts_verbose "lint_setup_skipped: #{copy_result.fetch( :skipped )}"
 
 					missing_policy = missing_lint_policy_files
 					if missing_policy.empty?
@@ -43,7 +44,7 @@ module Carson
 					end
 
 					missing_policy.each do |entry|
-						puts_line "missing_lint_policy_file: language=#{entry.fetch( :language )} path=#{entry.fetch( :path )}"
+						puts_verbose "missing_lint_policy_file: language=#{entry.fetch( :language )} path=#{entry.fetch( :path )}"
 					end
 					puts_line "ACTION: update source CODING policy files, rerun carson lint setup, then rerun carson audit."
 					EXIT_ERROR

data/lib/carson/runtime/local.rb

@@ -43,12 +43,19 @@ module Carson
 				return prune_no_stale_branches if stale_branches.empty?
 
 				counters = prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch )
-				puts_line "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
+				unless verbose?
+					puts_line "Pruned #{counters.fetch( :deleted )} stale branch#{plural_suffix( count: counters.fetch( :deleted ) )}."
+				end
 				EXIT_OK
 			end
 
 			def prune_no_stale_branches
-				puts_line "OK: no stale local branches tracking deleted #{config.git_remote} branches."
+				if verbose?
+					puts_line "OK: no stale local branches tracking deleted #{config.git_remote} branches."
+				else
+					puts_line "No stale branches."
+				end
 				EXIT_OK
 			end
 
@@ -72,7 +79,7 @@ module Carson
 
 			def prune_skip_stale_branch( type:, branch:, upstream: )
 				status = type == :protected ? "skip_protected_branch" : "skip_current_branch"
-				puts_line "#{status}: #{branch} (upstream=#{upstream})"
+				puts_verbose "#{status}: #{branch} (upstream=#{upstream})"
 				:skipped
 			end
 
@@ -89,8 +96,8 @@ module Carson
 			end
 
 			def prune_safe_delete_success( branch:, upstream:, stdout_text: )
-				out.print stdout_text unless stdout_text.empty?
-				puts_line "deleted_local_branch: #{branch} (upstream=#{upstream})"
+				out.print stdout_text if verbose? && !stdout_text.empty?
+				puts_verbose "deleted_local_branch: #{branch} (upstream=#{upstream})"
 				:deleted
 			end
 
@@ -108,20 +115,20 @@ module Carson
 			end
 
 			def prune_force_delete_success( branch:, upstream:, merged_pr:, force_stdout: )
-				out.print force_stdout unless force_stdout.empty?
-				puts_line "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
+				out.print force_stdout if verbose? && !force_stdout.empty?
+				puts_verbose "deleted_local_branch_force: #{branch} (upstream=#{upstream}) merged_pr=#{merged_pr.fetch( :url )}"
 				:deleted
 			end
 
 			def prune_force_delete_failed( branch:, upstream:, force_stderr: )
 				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
-				puts_line "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
+				puts_verbose "fail_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error_text}"
 				:skipped
 			end
 
 			def prune_force_delete_skipped( branch:, upstream:, delete_error_text:, force_error: )
-				puts_line "skip_delete_branch: #{branch} (upstream=#{upstream}) reason=#{delete_error_text}"
-				puts_line "skip_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error}" unless force_error.to_s.strip.empty?
+				puts_verbose "skip_delete_branch: #{branch} (upstream=#{upstream}) reason=#{delete_error_text}"
+				puts_verbose "skip_force_delete_branch: #{branch} (upstream=#{upstream}) reason=#{force_error}" unless force_error.to_s.strip.empty?
 				:skipped
 			end
 
@@ -153,26 +160,34 @@ module Carson
 					target_path = File.join( hooks_dir, hook_name )
 					FileUtils.cp( source_path, target_path )
 					FileUtils.chmod( 0o755, target_path )
-					puts_line "hook_written: #{relative_path( target_path )}"
+					puts_verbose "hook_written: #{relative_path( target_path )}"
 				end
 				git_system!( "config", "core.hooksPath", hooks_dir )
 				File.write( File.join( hooks_dir, "workflow_style" ), config.workflow_style )
-				puts_line "configured_hooks_path: #{hooks_dir}"
+				puts_verbose "configured_hooks_path: #{hooks_dir}"
+				unless verbose?
+					puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
+					return EXIT_OK
+				end
+
 				inspect!
 			end
 
 			# One-command onboarding for new repositories: detect remote, install hooks,
-			# apply templates, and produce a first audit report.
+			# apply templates, and run initial audit.
 			def onboard!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Onboard"
 				unless inside_git_work_tree?
 					puts_line "ERROR: #{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
 
+				repo_name = File.basename( repo_root )
+				puts_line ""
+				puts_line "Onboarding #{repo_name}..."
+
 				unless global_config_exists?
 					if self.in.respond_to?( :tty? ) && self.in.tty?
 						setup_status = setup!
@@ -182,21 +197,7 @@ module Carson
 					end
 				end
 
-				report_detected_remote!
-				hook_status = prepare!
-				return hook_status unless hook_status == EXIT_OK
-
-				template_status = template_apply!
-				return template_status unless template_status == EXIT_OK
-
-				audit_status = audit!
-				if audit_status == EXIT_OK
-					puts_line "OK: Carson onboard completed for #{repo_root}."
-				elsif audit_status == EXIT_BLOCK
-					puts_line "BLOCK: Carson onboard completed with policy blocks; resolve and rerun carson audit."
-				end
-				print_onboarding_guidance
-				audit_status
+				onboard_apply!
 			end
 
 			# Re-applies hooks, templates, and audit after upgrading Carson.
@@ -204,29 +205,52 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Refresh"
 				unless inside_git_work_tree?
 					puts_line "ERROR: #{repo_root} is not a git repository."
 					return EXIT_ERROR
 				end
-				hook_status = prepare!
+
+				if verbose?
+					puts_verbose ""
+					puts_verbose "[Refresh]"
+					hook_status = prepare!
+					return hook_status unless hook_status == EXIT_OK
+
+					template_status = template_apply!
+					return template_status unless template_status == EXIT_OK
+
+					audit_status = audit!
+					if audit_status == EXIT_OK
+						puts_line "OK: Carson refresh completed for #{repo_root}."
+					elsif audit_status == EXIT_BLOCK
+						puts_line "BLOCK: Carson refresh completed with policy blocks; resolve and rerun carson audit."
+					end
+					return audit_status
+				end
+
+				puts_line "Refresh"
+				hook_status = with_captured_output { prepare! }
 				return hook_status unless hook_status == EXIT_OK
+				puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
 
-				template_status = template_apply!
+				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
+				if template_drift_count.positive?
+					puts_line "Templates applied (#{template_drift_count} updated)."
+				else
+					puts_line "Templates in sync."
+				end
 
 				audit_status = audit!
-				if audit_status == EXIT_OK
-					puts_line "OK: Carson refresh completed for #{repo_root}."
-				elsif audit_status == EXIT_BLOCK
-					puts_line "BLOCK: Carson refresh completed with policy blocks; resolve and rerun carson audit."
-				end
+				puts_line "Refresh complete."
 				audit_status
 			end
 
 			# Removes Carson-managed repository integration so a host repository can retire Carson cleanly.
 			def offboard!
-				print_header "Offboard"
+				puts_verbose ""
+				puts_verbose "[Offboard]"
 				unless inside_git_work_tree?
 					puts_line "ERROR: #{repo_root} is not a git repository."
 					return EXIT_ERROR
@@ -240,16 +264,20 @@ module Carson
 					absolute = resolve_repo_path!( relative_path: relative, label: "offboard target #{relative}" )
 					if File.exist?( absolute )
 						FileUtils.rm_rf( absolute )
-						puts_line "removed_path: #{relative}"
+						puts_verbose "removed_path: #{relative}"
 						removed_count += 1
 					else
-						puts_line "skip_missing_path: #{relative}"
+						puts_verbose "skip_missing_path: #{relative}"
 						missing_count += 1
 					end
 				end
 				remove_empty_offboard_directories!
-				puts_line "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
-				puts_line "OK: Carson offboard completed for #{repo_root}."
+				puts_verbose "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
+				if verbose?
+					puts_line "OK: Carson offboard completed for #{repo_root}."
+				else
+					puts_line "Removed #{removed_count} file#{plural_suffix( count: removed_count )}. Offboard complete."
+				end
 				EXIT_OK
 			end
 
@@ -258,9 +286,13 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Inspect"
+				puts_verbose ""
+				puts_verbose "[Inspect]"
 				ok = hooks_health_report( strict: true )
-				puts_line( ok ? "status: ok" : "status: block" )
+				puts_verbose( ok ? "status: ok" : "status: block" )
+				unless verbose?
+					puts_line( ok ? "Hooks: ok" : "Hooks: block" )
+				end
 				ok ? EXIT_OK : EXIT_BLOCK
 			end
 
@@ -269,14 +301,24 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Template Sync Check"
+				puts_verbose ""
+				puts_verbose "[Template Sync Check]"
 				results = template_results
 				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
 				results.each do |entry|
-					puts_line "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
+					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
+				end
+				puts_verbose "template_summary: total=#{results.count} drift=#{drift_count} error=#{error_count}"
+				unless verbose?
+					if drift_count.positive?
+						drift_files = results.select { |entry| entry.fetch( :status ) == "drift" }.map { |entry| entry.fetch( :file ) }
+						puts_line "Templates: #{drift_count} of #{results.count} drifted"
+						drift_files.each { |file| puts_line "  #{file}" }
+					else
+						puts_line "Templates: #{results.count} files in sync"
+					end
 				end
-				puts_line "template_summary: total=#{results.count} drift=#{drift_count} error=#{error_count}"
 				return EXIT_ERROR if error_count.positive?
 
 				drift_count.positive? ? EXIT_BLOCK : EXIT_OK
@@ -287,29 +329,37 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Template Sync Apply"
+				puts_verbose ""
+				puts_verbose "[Template Sync Apply]"
 				results = template_results
 				applied = 0
 				results.each do |entry|
 					if entry.fetch( :status ) == "error"
-						puts_line "template_file: #{entry.fetch( :file )} status=error reason=#{entry.fetch( :reason )}"
+						puts_verbose "template_file: #{entry.fetch( :file )} status=error reason=#{entry.fetch( :reason )}"
 						next
 					end
 
 					file_path = File.join( repo_root, entry.fetch( :file ) )
 					if entry.fetch( :status ) == "ok"
-						puts_line "template_file: #{entry.fetch( :file )} status=ok reason=in_sync"
+						puts_verbose "template_file: #{entry.fetch( :file )} status=ok reason=in_sync"
 						next
 					end
 
 					FileUtils.mkdir_p( File.dirname( file_path ) )
 					File.write( file_path, entry.fetch( :applied_content ) )
-					puts_line "template_file: #{entry.fetch( :file )} status=updated reason=#{entry.fetch( :reason )}"
+					puts_verbose "template_file: #{entry.fetch( :file )} status=updated reason=#{entry.fetch( :reason )}"
 					applied += 1
 				end
 
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
-				puts_line "template_apply_summary: updated=#{applied} error=#{error_count}"
+				puts_verbose "template_apply_summary: updated=#{applied} error=#{error_count}"
+				unless verbose?
+					if applied.positive?
+						puts_line "Templates applied (#{applied} updated)."
+					else
+						puts_line "Templates in sync."
+					end
+				end
 				error_count.positive? ? EXIT_ERROR : EXIT_OK
 			end
 
@@ -370,9 +420,9 @@ module Carson
 			def print_hooks_path_status( configured:, expected: )
 				configured_abs = configured.nil? ? nil : File.expand_path( configured )
 				hooks_path_ok = configured_abs == expected
-				puts_line "hooks_path: #{configured || '(unset)'}"
-				puts_line "hooks_path_expected: #{expected}"
-				puts_line( hooks_path_ok ? "hooks_path_status: ok" : "hooks_path_status: attention" )
+				puts_verbose "hooks_path: #{configured || '(unset)'}"
+				puts_verbose "hooks_path_expected: #{expected}"
+				puts_verbose( hooks_path_ok ? "hooks_path_status: ok" : "hooks_path_status: attention" )
 				hooks_path_ok
 			end
 
@@ -381,7 +431,7 @@ module Carson
 					exists = File.file?( path )
 					symlink = File.symlink?( path )
 					executable = exists && !symlink && File.executable?( path )
-					puts_line "hook_file: #{relative_path( path )} exists=#{exists} symlink=#{symlink} executable=#{executable}"
+					puts_verbose "hook_file: #{relative_path( path )} exists=#{exists} symlink=#{symlink} executable=#{executable}"
 				end
 			end
 
@@ -406,13 +456,13 @@ module Carson
 				if strict && !hooks_path_ok
 					configured_text = configured.to_s.strip
 					if configured_text.empty?
-						puts_line "ACTION: hooks path is unset (expected=#{expected})."
+						puts_verbose "ACTION: hooks path is unset (expected=#{expected})."
 					else
-						puts_line "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
+						puts_verbose "ACTION: hooks path mismatch (configured=#{configured_text}, expected=#{expected})."
 					end
 				end
 				message = strict ? "ACTION: run carson prepare to align hooks with Carson #{Carson::VERSION}." : "ACTION: run carson prepare to enforce local main protections."
-				puts_line message
+				puts_verbose message
 			end
 
 			# Returns ahead/behind counts for local main versus configured remote main.
@@ -611,17 +661,17 @@ module Carson
 			def disable_carson_hooks_path!
 				configured = configured_hooks_path
 				if configured.nil?
-					puts_line "hooks_path: (unset)"
+					puts_verbose "hooks_path: (unset)"
 					return EXIT_OK
 				end
-				puts_line "hooks_path: #{configured}"
+				puts_verbose "hooks_path: #{configured}"
 				configured_abs = File.expand_path( configured, repo_root )
 				unless carson_managed_hooks_path?( configured_abs: configured_abs )
-					puts_line "hooks_path_kept: #{configured} (not Carson-managed)"
+					puts_verbose "hooks_path_kept: #{configured} (not Carson-managed)"
 					return EXIT_OK
 				end
 				git_system!( "config", "--unset", "core.hooksPath" )
-				puts_line "hooks_path_unset: core.hooksPath"
+				puts_verbose "hooks_path_unset: core.hooksPath"
 				EXIT_OK
 			rescue StandardError => e
 				puts_line "ERROR: unable to update core.hooksPath (#{e.message})"
@@ -667,25 +717,77 @@ module Carson
 					next unless Dir.empty?( absolute )
 
 					Dir.rmdir( absolute )
-					puts_line "removed_empty_dir: #{relative}"
+					puts_verbose "removed_empty_dir: #{relative}"
 				end
 			end
 
 			# Verifies configured remote exists and logs status without mutating remotes.
 			def report_detected_remote!
 				if git_remote_exists?( remote_name: config.git_remote )
-					puts_line "remote_ok: #{config.git_remote}"
+					puts_verbose "remote_ok: #{config.git_remote}"
 				else
 					puts_line "WARN: remote '#{config.git_remote}' not found; run carson setup to configure."
 				end
 			end
 
-			def print_onboarding_guidance
-				puts_line ""
-				puts_line "Carson is ready. Current workflow: #{config.workflow_style}"
+			# Concise onboard orchestration: hooks, templates, remote, audit, guidance.
+			def onboard_apply!
+				hook_status = with_captured_output { prepare! }
+				return hook_status unless hook_status == EXIT_OK
+				puts_line "Hooks installed (#{config.required_hooks.count} hooks)."
+
+				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_status = with_captured_output { template_apply! }
+				return template_status unless template_status == EXIT_OK
+				if template_drift_count.positive?
+					puts_line "Templates synced (#{template_drift_count} file#{plural_suffix( count: template_drift_count )} updated)."
+				else
+					puts_line "Templates in sync."
+				end
+
+				onboard_report_remote!
+				audit_status = onboard_run_audit!
+
 				puts_line ""
-				puts_line "Reconfigure anytime with: carson setup"
-				puts_line "Run carson refresh after changing config."
+				puts_line "Carson is ready. Workflow: #{config.workflow_style}"
+				puts_line "Reconfigure anytime: carson setup"
+				audit_status
+			end
+
+			# Friendly remote status for onboard output.
+			def onboard_report_remote!
+				if git_remote_exists?( remote_name: config.git_remote )
+					puts_line "Remote: #{config.git_remote} (connected)."
+				else
+					puts_line "Remote not configured yet — carson setup will walk you through it."
+				end
+			end
+
+			# Runs audit with captured output; reports summary instead of full detail.
+			def onboard_run_audit!
+				audit_error = nil
+				audit_status = with_captured_output { audit! }
+			rescue StandardError => e
+				audit_error = e
+				audit_status = EXIT_OK
+			ensure
+				return onboard_print_audit_result( status: audit_status, error: audit_error )
+			end
+
+			def onboard_print_audit_result( status:, error: )
+				if error
+					if error.message.to_s.match?( /HEAD|rev-parse/ )
+						puts_line "No commits yet — run carson audit after your first commit."
+					else
+						puts_line "Audit skipped — run carson audit for details."
+					end
+					return EXIT_OK
+				end
+
+				if status == EXIT_BLOCK
+					puts_line "Some checks need attention — run carson audit for details."
+				end
+				status
 			end
 
 			# Uses `git remote get-url` as existence check to avoid parsing remote lists.

data/lib/carson/runtime/review/gate_support.rb

@@ -8,10 +8,10 @@ module Carson
 					return unless config.review_wait_seconds.positive?
 					quick = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_number )
 					if quick[ :unresolved_threads ].empty? && quick[ :unacknowledged_actionable ].empty?
-						puts_line "warmup_skip: all threads resolved"
+						puts_verbose "warmup_skip: all threads resolved"
 						return quick
 					end
-					puts_line "warmup_wait_seconds: #{config.review_wait_seconds}"
+					puts_verbose "warmup_wait_seconds: #{config.review_wait_seconds}"
 					sleep config.review_wait_seconds
 					nil
 				end
@@ -19,7 +19,7 @@ module Carson
 				# Poll delay between consecutive snapshot reads during convergence checks.
 				def wait_for_review_poll
 					return unless config.review_poll_seconds.positive?
-					puts_line "poll_wait_seconds: #{config.review_poll_seconds}"
+					puts_verbose "poll_wait_seconds: #{config.review_poll_seconds}"
 					sleep config.review_poll_seconds
 				end
 
@@ -173,10 +173,10 @@ module Carson
 						json_name: REVIEW_GATE_REPORT_JSON,
 						renderer: method( :render_review_gate_markdown )
 					)
-					puts_line "review_gate_report_markdown: #{markdown_path}"
-					puts_line "review_gate_report_json: #{json_path}"
+					puts_verbose "review_gate_report_markdown: #{markdown_path}"
+					puts_verbose "review_gate_report_json: #{json_path}"
 				rescue StandardError => e
-					puts_line "review_gate_report_write: SKIP (#{e.message})"
+					puts_verbose "review_gate_report_write: SKIP (#{e.message})"
 				end
 
 				# Human-readable review gate report for merge-readiness evidence.

data/lib/carson/runtime/review/sweep_support.rb

@@ -202,10 +202,10 @@ module Carson
 						json_name: REVIEW_SWEEP_REPORT_JSON,
 						renderer: method( :render_review_sweep_markdown )
 					)
-					puts_line "review_sweep_report_markdown: #{markdown_path}"
-					puts_line "review_sweep_report_json: #{json_path}"
+					puts_verbose "review_sweep_report_markdown: #{markdown_path}"
+					puts_verbose "review_sweep_report_json: #{json_path}"
 				rescue StandardError => e
-					puts_line "review_sweep_report_write: SKIP (#{e.message})"
+					puts_verbose "review_sweep_report_write: SKIP (#{e.message})"
 				end
 
 				# Human-readable scheduled sweep report.

data/lib/carson/runtime/review.rb

@@ -16,7 +16,11 @@ module Carson
 			def review_gate!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
-				print_header "Review Gate"
+				puts_verbose ""
+				puts_verbose "[Review Gate]"
+				unless verbose?
+					puts_line "Review Gate"
+				end
 				unless gh_available?
 					puts_line "ERROR: gh CLI not available in PATH."
 					return EXIT_ERROR
@@ -67,13 +71,13 @@ module Carson
 					snapshot = review_gate_snapshot( owner: owner, repo: repo, pr_number: pr_summary.fetch( :number ) )
 					last_snapshot = snapshot
 					signature = review_gate_signature( snapshot: snapshot )
-					puts_line "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
-					puts_line "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
-					puts_line "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
-					puts_line "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
+					puts_verbose "poll_attempt: #{poll_attempts}/#{config.review_max_polls}"
+					puts_verbose "latest_activity: #{snapshot.fetch( :latest_activity ) || 'unknown'}"
+					puts_verbose "unresolved_threads: #{snapshot.fetch( :unresolved_threads ).count}"
+					puts_verbose "unacknowledged_actionable: #{snapshot.fetch( :unacknowledged_actionable ).count}"
 					if !last_signature.nil? && signature == last_signature
 						converged = true
-						puts_line "convergence: stable"
+						puts_verbose "convergence: stable"
 						break
 					end
 					last_signature = signature
@@ -110,6 +114,9 @@ module Carson
 					unacknowledged_actionable: last_snapshot.fetch( :unacknowledged_actionable )
 				}
 				write_review_gate_report( report: report )
+				unless verbose?
+					puts_line "Polling... (converged after #{poll_attempts} attempt#{plural_suffix( count: poll_attempts )})"
+				end
 				if block_reasons.empty?
 					puts_line "OK: review gate passed."
 					return EXIT_OK
@@ -128,7 +135,8 @@ module Carson
 			def review_sweep!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
-				print_header "Review Sweep"
+				puts_verbose ""
+				puts_verbose "[Review Sweep]"
 				unless gh_available?
 					puts_line "ERROR: gh CLI not available in PATH."
 					return EXIT_ERROR
@@ -137,8 +145,8 @@ module Carson
 				owner, repo = repository_coordinates
 				cutoff_time = Time.now.utc - ( config.review_sweep_window_days * 86_400 )
 				pull_requests = recent_pull_requests_for_sweep( owner: owner, repo: repo, cutoff_time: cutoff_time )
-				puts_line "window_days: #{config.review_sweep_window_days}"
-				puts_line "candidate_prs: #{pull_requests.count}"
+				puts_verbose "window_days: #{config.review_sweep_window_days}"
+				puts_verbose "candidate_prs: #{pull_requests.count}"
 				findings = []
 
 				pull_requests.each do |entry|

data/lib/carson/runtime/setup.rb

@@ -4,7 +4,8 @@ module Carson
 			WELL_KNOWN_REMOTES = %w[origin github upstream].freeze
 
 			def setup!
-				print_header "Setup"
+				puts_verbose ""
+				puts_verbose "[Setup]"
 
 				unless inside_git_work_tree?
 					puts_line "WARN: not a git repository. Skipping remote and branch detection."
@@ -43,19 +44,19 @@ module Carson
 				choices = {}
 				if detected && detected != config.git_remote
 					choices[ "git.remote" ] = detected
-					puts_line "detected_remote: #{detected}"
+					puts_verbose "detected_remote: #{detected}"
 				elsif detected
-					puts_line "detected_remote: #{detected}"
+					puts_verbose "detected_remote: #{detected}"
 				else
-					puts_line "detected_remote: none"
+					puts_verbose "detected_remote: none"
 				end
 
 				branch = detect_main_branch
 				if branch && branch != config.main_branch
 					choices[ "git.main_branch" ] = branch
-					puts_line "detected_main_branch: #{branch}"
+					puts_verbose "detected_main_branch: #{branch}"
 				elsif branch
-					puts_line "detected_main_branch: #{branch}"
+					puts_verbose "detected_main_branch: #{branch}"
 				end
 
 				write_setup_config( choices: choices )
@@ -103,8 +104,8 @@ module Carson
 				puts_line ""
 				puts_line "Workflow style"
 				options = [
-					{ label: "trunk — commit directly to main (default)", value: "trunk" },
-					{ label: "branch — enforce PR-only merges", value: "branch" }
+					{ label: "branch — enforce PR-only merges (default)", value: "branch" },
+					{ label: "trunk — commit directly to main", value: "trunk" }
 				]
 				prompt_choice( options: options, default: 0 )
 			end

data/lib/carson/runtime.rb

@@ -4,6 +4,7 @@
 require "fileutils"
 require "json"
 require "open3"
+require "stringio"
 require "time"
 
 module Carson
@@ -22,12 +23,13 @@ module Carson
 		DISPOSITION_TOKENS = %w[accepted rejected deferred].freeze
 
 		# Runtime wiring for repository context, tool paths, and output streams.
-		def initialize( repo_root:, tool_root:, out:, err:, in_stream: $stdin )
+		def initialize( repo_root:, tool_root:, out:, err:, in_stream: $stdin, verbose: false )
 			@repo_root = repo_root
 			@tool_root = tool_root
 			@out = out
 			@err = err
 			@in = in_stream
+			@verbose = verbose
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
@@ -37,6 +39,27 @@ module Carson
 
 		attr_reader :repo_root, :tool_root, :out, :err, :in, :config, :git_adapter, :github_adapter
 
+		# Returns true when full diagnostic output is enabled via --verbose.
+		def verbose?
+			@verbose
+		end
+
+		# Prints a line only when verbose mode is active.
+		def puts_verbose( message )
+			puts_line( message ) if verbose?
+		end
+
+		# Runs a block with all output captured (suppressed from the user).
+		# Returns the block's return value; output is silently discarded.
+		def with_captured_output
+			saved_out, saved_err = @out, @err
+			@out = StringIO.new
+			@err = StringIO.new
+			yield
+		ensure
+			@out, @err = saved_out, saved_err
+		end
+
 		# Current local branch name.
 		def current_branch
 			git_capture!( "rev-parse", "--abbrev-ref", "HEAD" ).strip

metadata

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