carson 2.7.0 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdf6978ed4ecdbef69aba67dba84b678d1145038ff47925a1dfbfdc777170135
-  data.tar.gz: a79ce86bc59f79528e0bf73d51098cd8f1ef1c96c2034d98900c282e26d047c7
+  metadata.gz: 76c0a5589cad84c4aaba1fee42bd667a21a55cea4840092b2984ae9eaeb84f6c
+  data.tar.gz: 656462b041f6764fd38780b500945ca0389b8235d741805367613051a27bd9da
 SHA512:
-  metadata.gz: 5c11f2bd0fa18ca630b6c51bc23aae320e96bc63cfd24359c685b4664dd45594c68e3333554a9628c0411833de6c4a1779ef18cdd1d6b048516b116848a88484
-  data.tar.gz: c6d3810f02303d1dbe6f614bc85b6d4a4186a171fa08b9705f66a86cac206eaf1f7c63e67c8a346d5ec9fd0a4c3454fbedbf5fed7275e46a9f1d03f5bd6d55fb
+  metadata.gz: 14cc66d4582c9ddfb9c5e87ec8e550d1f97cbcf6701a499e730dea4c06b5598ccdc6e8f61057a921ddba2d6ac9799fed4b3191a1a6dc1e440c4bc7249eec06bd
+  data.tar.gz: ce5e6f40342c08378830563ae0188cf61964d1f4650cc0be47a8cf52cb72f02b4f6413fa2b8d15a3dc70e3714628897446ab852ab7b276ac68a98cff0e5d1d54

data/.github/workflows/carson_policy.yml

@@ -66,13 +66,6 @@ jobs:
       - name: Install pinned RuboCop
         run: gem install rubocop -v "${{ inputs.rubocop_version }}" --no-document
 
-      - name: Align remote name for Carson
-        working-directory: host
-        run: |
-          if ! git remote get-url github >/dev/null 2>&1; then
-            git remote rename origin github
-          fi
-
       - name: Carson audit
         working-directory: host
         env:

data/API.md

@@ -15,8 +15,9 @@ carson <command> [subcommand] [arguments]
 
 | Command | Purpose |
 |---|---|
+| `carson setup` | Interactive quiz to configure remote, main branch, workflow, and merge method. Writes `~/.carson/config.json`. |
 | `carson lint setup --source <path-or-git-url> [--ref <git-ref>] [--force]` | Seed or refresh `~/.carson/lint` policy files from an explicit source. |
-| `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. |
+| `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. Auto-triggers `setup` on first run. |
 | `carson prepare` | Install or refresh Carson-managed global hooks. |
 | `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. |
 | `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |

data/MANUAL.md

@@ -50,14 +50,25 @@ Policy layout: language config files sit directly under `CODING/` (flat layout,
 carson onboard /path/to/your-repo
 ```
 
+On first run (no `~/.carson/config.json` exists), `onboard` launches `carson setup` — an interactive quiz that detects your remotes, main branch, and preferred workflow. In non-interactive environments (CI, pipes), Carson auto-detects settings silently.
+
 `onboard` performs:
-- Remote alignment using configured `git.remote` (default `github`).
+- Interactive setup quiz (first run only).
+- Remote detection and verification using configured `git.remote` (default `origin`).
 - Hook installation under `~/.carson/hooks/<version>/`.
 - Repository `core.hooksPath` alignment to Carson global hooks.
 - Commit-time governance gate via managed `pre-commit` hook.
 - Managed `.github/*` template synchronisation.
 - Initial governance audit.
 
+### Reconfigure later
+
+```bash
+carson setup
+```
+
+Re-run the interactive setup quiz to change your remote, main branch, workflow style, or merge method. Choices are saved to `~/.carson/config.json`.
+
 ### Step 3: Commit generated files
 
 After `onboard`, commit the generated `.github/*` changes in your repository. From this point the repository is governed.

data/RELEASE.md

@@ -5,6 +5,109 @@ 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.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.
+
+### What users must do now
+
+1. Upgrade Carson to `2.8.1`.
+
+### Breaking or removed behaviour
+
+- None.
+
+### 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
+
+- **`carson setup` command.** An interactive quiz that detects git remotes, main branch, workflow style, and merge method. Writes answers to `~/.carson/config.json`. In non-TTY environments, Carson auto-detects settings silently.
+- **Auto-triggered on first onboard.** `carson onboard` now launches the setup quiz when no `~/.carson/config.json` exists. Existing users are not affected.
+- **Remote renaming removed.** Carson no longer renames `origin` to `github` during onboard. Instead, it detects the existing remote and adapts. This respects the user's repository layout.
+- **Default remote changed from `github` to `origin`.** The built-in default `git.remote` is now `origin`, matching the convention of most git hosting providers. Users who previously relied on the `github` default should run `carson setup` or set `git.remote` in config.
+- **Post-install message.** `gem install carson` now displays a getting-started guide pointing to `carson onboard`.
+- **CI lint fallback simplified.** `lint_target_files_for_pull_request` uses `config.git_remote` directly with a minimal fallback to `origin`.
+
+### What users must do now
+
+1. Upgrade Carson to `2.8.0`.
+2. If you relied on the `github` remote default, either rename your remote to `origin` or run `carson setup` to configure `git.remote`.
+
+### Breaking or removed behaviour
+
+- `git.remote` default changed from `github` to `origin`.
+- `carson onboard` no longer renames `origin` to `github`.
+- The `align_remote_name_for_carson!` method has been removed.
+
+### Upgrade steps
+
+```bash
+cd ~/Dev/carson
+git pull
+bash install.sh
+carson version
+carson setup
+```
+
+### Engineering Appendix
+
+#### New files
+
+- `lib/carson/runtime/setup.rb` — interactive quiz, remote/branch detection, config persistence.
+- `test/runtime_setup_test.rb` — quiz, detection, and config merge tests.
+
+#### Modified components
+
+- `lib/carson/config.rb` — default `git.remote` changed from `"github"` to `"origin"`, added `attr_accessor :git_remote`.
+- `lib/carson/runtime.rb` — added `in_stream:` parameter and `@in` attribute.
+- `lib/carson/cli.rb` — added `"setup"` command dispatch, updated banner.
+- `lib/carson/runtime/local.rb` — replaced `align_remote_name_for_carson!` with `report_detected_remote!`, updated `onboard!` to auto-trigger setup, updated `print_onboarding_guidance`.
+- `lib/carson/runtime/audit.rb` — simplified `lint_target_files_for_pull_request` CI fallback.
+- `test/runtime_govern_test.rb` — removed `origin` → `github` rename.
+- `test/runtime_audit_lint_test.rb` — updated remote name from `github` to `origin`.
+- `carson.gemspec` — added `spec.post_install_message`.
+- `MANUAL.md` — documented `carson setup`, updated remote default.
+- `API.md` — added `setup` command entry.
+
+#### Public interface and config changes
+
+- Added CLI command: `carson setup`.
+- Default `git.remote` changed from `"github"` to `"origin"`.
+- Runtime constructor accepts `in_stream:` keyword argument.
+- Exit status contract unchanged.
+
+---
+
 ## 2.7.0 — Documentation and Test Fixes
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.7.0
+2.8.1

data/carson.gemspec

@@ -19,6 +19,18 @@ Gem::Specification.new do |spec|
 		"documentation_uri" => "https://github.com/wanghailei/carson/blob/main/MANUAL.md"
 	}
 
+	spec.post_install_message = <<~MSG
+
+		\u29D3 Carson at your service.
+
+		  Step into your project directory and run:
+
+		    carson onboard
+
+		  I'll walk you through everything from there.
+
+	MSG
+
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]

data/lib/carson/cli.rb

@@ -44,7 +44,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [audit|sync|prune|prepare|inspect|onboard [repo_path]|refresh [repo_path]|offboard [repo_path]|template check|template apply|lint setup --source <path-or-git-url>|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|housekeep|version]"
+				opts.banner = "Usage: carson [setup|audit|sync|prune|prepare|inspect|onboard [repo_path]|refresh [repo_path]|offboard [repo_path]|template check|template apply|lint setup --source <path-or-git-url>|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|housekeep|version]"
 			end
 		end
 
@@ -187,6 +187,8 @@ module Carson
 			return Runtime::EXIT_ERROR if command == :invalid
 
 			case command
+			when "setup"
+				runtime.setup!
 			when "audit"
 				runtime.audit!
 			when "sync"

data/lib/carson/config.rb

@@ -6,7 +6,8 @@ module Carson
 
 	# Config is built-in only for outsider mode; host repositories do not carry Carson config files.
 	class Config
-		attr_reader :git_remote, :main_branch, :protected_branches, :hooks_base_path, :required_hooks,
+		attr_accessor :git_remote
+		attr_reader :main_branch, :protected_branches, :hooks_base_path, :required_hooks,
 			:path_groups, :template_managed_files, :lint_languages,
 			:review_wait_seconds, :review_poll_seconds, :review_max_polls, :review_sweep_window_days,
 			:review_sweep_states, :review_disposition_prefix, :review_risk_keywords,
@@ -28,7 +29,7 @@ module Carson
 		def self.default_data
 			{
 				"git" => {
-					"remote" => "github",
+					"remote" => "origin",
 					"main_branch" => "main",
 					"protected_branches" => [ "main", "master" ]
 				},

data/lib/carson/runtime/audit.rb

@@ -205,19 +205,11 @@ module Carson
 				base_ref = ENV.fetch( "GITHUB_BASE_REF", "" ).to_s.strip
 				return nil if base_ref.empty?
 
-				preferred_remote = config.git_remote.to_s.strip
-				remote_name = nil
-
-				remotes_stdout, _, remotes_success, = git_run( "remote" )
-				if remotes_success
-					available_remotes = remotes_stdout.lines.map { |line| line.to_s.strip }.reject( &:empty? )
-					candidates = [ preferred_remote, "origin", "github" ].map( &:to_s ).map( &:strip ).reject( &:empty? ).uniq
-					remote_name = candidates.find { |candidate| available_remotes.include?( candidate ) }
-					remote_name ||= available_remotes.first unless available_remotes.empty?
+				remote_name = config.git_remote
+				unless git_remote_exists?( remote_name: remote_name )
+					remote_name = "origin" if git_remote_exists?( remote_name: "origin" )
 				end
 
-				remote_name ||= ( preferred_remote.empty? ? "origin" : preferred_remote )
-
 				_, _, fetch_success, = git_run( "fetch", "--no-tags", "--depth", "1", remote_name, base_ref )
 				return nil unless fetch_success
 

data/lib/carson/runtime/local.rb

@@ -153,40 +153,43 @@ 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_line "hook_written: #{relative_path( target_path )}" unless concise?
 				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_line "configured_hooks_path: #{hooks_dir}" unless concise?
+				return EXIT_OK if concise?
+
 				inspect!
 			end
 
-			# One-command onboarding for new repositories: align remote naming, install hooks,
-			# apply templates, and produce a first audit report.
+			# One-command onboarding for new repositories: detect remote, install hooks,
+			# 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
-				align_remote_name_for_carson!
-				hook_status = prepare!
-				return hook_status unless hook_status == EXIT_OK
 
-				template_status = template_apply!
-				return template_status unless template_status == EXIT_OK
+				repo_name = File.basename( repo_root )
+				puts_line ""
+				puts_line "Onboarding #{repo_name}..."
 
-				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."
+				unless global_config_exists?
+					if self.in.respond_to?( :tty? ) && self.in.tty?
+						setup_status = setup!
+						return setup_status unless setup_status == EXIT_OK
+					else
+						silent_setup!
+					end
 				end
-				print_onboarding_guidance
-				audit_status
+
+				onboard_apply!
+			ensure
+				@concise = false
 			end
 
 			# Re-applies hooks, templates, and audit after upgrading Carson.
@@ -277,29 +280,29 @@ module Carson
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
-				print_header "Template Sync Apply"
+				print_header "Template Sync Apply" unless concise?
 				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_line "template_file: #{entry.fetch( :file )} status=error reason=#{entry.fetch( :reason )}" unless concise?
 						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_line "template_file: #{entry.fetch( :file )} status=ok reason=in_sync" unless concise?
 						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_line "template_file: #{entry.fetch( :file )} status=updated reason=#{entry.fetch( :reason )}" unless concise?
 					applied += 1
 				end
 
 				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
-				puts_line "template_apply_summary: updated=#{applied} error=#{error_count}"
+				puts_line "template_apply_summary: updated=#{applied} error=#{error_count}" unless concise?
 				error_count.positive? ? EXIT_ERROR : EXIT_OK
 			end
 
@@ -661,31 +664,75 @@ module Carson
 				end
 			end
 
-			# Ensures Carson expected remote naming (`github`) while keeping existing
-			# repositories safe when neither `github` nor `origin` exists.
-			def align_remote_name_for_carson!
+			# 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}"
-					return
+				else
+					puts_line "WARN: remote '#{config.git_remote}' not found; run carson setup to configure."
 				end
-				if git_remote_exists?( remote_name: "origin" )
-					git_system!( "remote", "rename", "origin", config.git_remote )
-					puts_line "remote_renamed: origin -> #{config.git_remote}"
-					return
-				end
-				puts_line "WARN: no #{config.git_remote} or origin remote configured; continue with local baseline only."
 			end
 
+			# Concise onboard orchestration: hooks, templates, remote, audit, guidance.
+			def onboard_apply!
+				@concise = true
+
+				hook_status = 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 = 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!
 
-			def print_onboarding_guidance
-				puts_line ""
-				puts_line "Carson is ready. Current workflow: #{config.workflow_style}"
-				puts_line ""
-				puts_line "Customise in ~/.carson/config.json:"
-				puts_line "  { \"workflow\": { \"style\": \"branch\" } }  — enforce PR-only merges"
-				puts_line "  { \"workflow\": { \"style\": \"trunk\" } }   — allow direct main commits (default)"
 				puts_line ""
-				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/setup.rb

@@ -0,0 +1,295 @@
+module Carson
+	class Runtime
+		module Setup
+			WELL_KNOWN_REMOTES = %w[origin github upstream].freeze
+
+			def setup!
+				print_header "Setup"
+
+				unless inside_git_work_tree?
+					puts_line "WARN: not a git repository. Skipping remote and branch detection."
+					return write_setup_config( choices: {} )
+				end
+
+				if self.in.respond_to?( :tty? ) && self.in.tty?
+					interactive_setup!
+				else
+					silent_setup!
+				end
+			end
+
+		private
+
+			def interactive_setup!
+				choices = {}
+
+				remote_choice = prompt_remote
+				choices[ "git.remote" ] = remote_choice unless remote_choice.nil?
+
+				branch_choice = prompt_main_branch
+				choices[ "git.main_branch" ] = branch_choice unless branch_choice.nil?
+
+				workflow_choice = prompt_workflow_style
+				choices[ "workflow.style" ] = workflow_choice unless workflow_choice.nil?
+
+				merge_choice = prompt_merge_method
+				choices[ "govern.merge.method" ] = merge_choice unless merge_choice.nil?
+
+				write_setup_config( choices: choices )
+			end
+
+			def silent_setup!
+				detected = detect_git_remote
+				choices = {}
+				if detected && detected != config.git_remote
+					choices[ "git.remote" ] = detected
+					puts_line "detected_remote: #{detected}"
+				elsif detected
+					puts_line "detected_remote: #{detected}"
+				else
+					puts_line "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}"
+				elsif branch
+					puts_line "detected_main_branch: #{branch}"
+				end
+
+				write_setup_config( choices: choices )
+			end
+
+			def prompt_remote
+				remotes = list_git_remotes
+				if remotes.empty?
+					puts_line "No remotes found. Carson will operate in local-only mode."
+					return nil
+				end
+
+				puts_line ""
+				puts_line "Git remote"
+				options = build_remote_options( remotes: remotes )
+				options << { label: "Other (enter name)", value: :other }
+
+				default_index = 0
+				choice = prompt_choice( options: options, default: default_index )
+
+				if choice == :other
+					prompt_custom_value( label: "Remote name" )
+				else
+					choice
+				end
+			end
+
+			def prompt_main_branch
+				puts_line ""
+				puts_line "Main branch"
+				options = build_main_branch_options
+				options << { label: "Other (enter name)", value: :other }
+
+				default_index = 0
+				choice = prompt_choice( options: options, default: default_index )
+
+				if choice == :other
+					prompt_custom_value( label: "Branch name" )
+				else
+					choice
+				end
+			end
+
+			def prompt_workflow_style
+				puts_line ""
+				puts_line "Workflow style"
+				options = [
+					{ label: "trunk — commit directly to main (default)", value: "trunk" },
+					{ label: "branch — enforce PR-only merges", value: "branch" }
+				]
+				prompt_choice( options: options, default: 0 )
+			end
+
+			def prompt_merge_method
+				puts_line ""
+				puts_line "Merge method"
+				options = [
+					{ label: "squash — one commit per PR (recommended)", value: "squash" },
+					{ label: "rebase — linear history, individual commits", value: "rebase" },
+					{ label: "merge — merge commits", value: "merge" }
+				]
+				prompt_choice( options: options, default: 0 )
+			end
+
+			def prompt_choice( options:, default: )
+				options.each_with_index do |option, index|
+					puts_line "  #{index + 1}) #{option.fetch( :label )}"
+				end
+				out.print "#{BADGE} Choice [#{default + 1}]: "
+				out.flush
+				raw = self.in.gets
+				return options[ default ].fetch( :value ) if raw.nil?
+
+				input = raw.to_s.strip
+				return options[ default ].fetch( :value ) if input.empty?
+
+				index = Integer( input ) - 1
+				return options[ default ].fetch( :value ) if index < 0 || index >= options.length
+
+				options[ index ].fetch( :value )
+			rescue ArgumentError
+				options[ default ].fetch( :value )
+			end
+
+			def prompt_custom_value( label: )
+				out.print "#{BADGE} #{label}: "
+				out.flush
+				raw = self.in.gets
+				return nil if raw.nil?
+
+				value = raw.to_s.strip
+				value.empty? ? nil : value
+			end
+
+			def build_remote_options( remotes: )
+				sorted = sort_remotes( remotes: remotes )
+				sorted.map do |entry|
+					name = entry.fetch( :name )
+					url = entry.fetch( :url )
+					{ label: "#{name} (#{url})", value: name }
+				end
+			end
+
+			def sort_remotes( remotes: )
+				well_known = []
+				others = []
+				remotes.each do |entry|
+					if WELL_KNOWN_REMOTES.include?( entry.fetch( :name ) )
+						well_known << entry
+					else
+						others << entry
+					end
+				end
+				well_known.sort_by { |e| WELL_KNOWN_REMOTES.index( e.fetch( :name ) ) || 999 } + others.sort_by { |e| e.fetch( :name ) }
+			end
+
+			def build_main_branch_options
+				options = []
+				main_exists = branch_exists_locally_or_remote?( branch: "main" )
+				master_exists = branch_exists_locally_or_remote?( branch: "master" )
+
+				if main_exists
+					options << { label: "main", value: "main" }
+					options << { label: "master", value: "master" } if master_exists
+				elsif master_exists
+					options << { label: "master", value: "master" }
+					options << { label: "main", value: "main" }
+				else
+					options << { label: "main", value: "main" }
+					options << { label: "master", value: "master" }
+				end
+				options
+			end
+
+			def branch_exists_locally_or_remote?( branch: )
+				return true if branch_exists?( branch_name: branch )
+
+				remote = config.git_remote
+				_, _, success, = git_run( "rev-parse", "--verify", "#{remote}/#{branch}" )
+				success
+			end
+
+			def list_git_remotes
+				stdout_text, _, success, = git_run( "remote", "-v" )
+				return [] unless success
+
+				remotes = {}
+				stdout_text.lines.each do |line|
+					parts = line.strip.split( /\s+/ )
+					next if parts.length < 2
+
+					name = parts[ 0 ]
+					url = parts[ 1 ]
+					remotes[ name ] ||= url
+				end
+				remotes.map { |name, url| { name: name, url: url } }
+			end
+
+			def detect_git_remote
+				remotes = list_git_remotes
+				remote_names = remotes.map { |entry| entry.fetch( :name ) }
+				return nil if remote_names.empty?
+
+				return config.git_remote if remote_names.include?( config.git_remote )
+				return remote_names.first if remote_names.length == 1
+
+				candidate = WELL_KNOWN_REMOTES.find { |name| remote_names.include?( name ) }
+				return candidate unless candidate.nil?
+
+				remote_names.first
+			end
+
+			def detect_main_branch
+				return "main" if branch_exists_locally_or_remote?( branch: "main" )
+				return "master" if branch_exists_locally_or_remote?( branch: "master" )
+
+				nil
+			end
+
+			def write_setup_config( choices: )
+				config_data = build_config_data_from_choices( choices: choices )
+
+				config_path = Config.global_config_path( repo_root: repo_root )
+				if config_path.empty?
+					puts_line "WARN: unable to determine config path; skipping config write."
+					return EXIT_OK
+				end
+
+				existing_data = load_existing_config( path: config_path )
+				merged = Config.deep_merge( base: existing_data, overlay: config_data )
+
+				FileUtils.mkdir_p( File.dirname( config_path ) )
+				File.write( config_path, JSON.pretty_generate( merged ) )
+				puts_line ""
+				puts_line "Config saved to #{config_path}"
+
+				reload_config_after_setup!
+				EXIT_OK
+			end
+
+			def build_config_data_from_choices( choices: )
+				data = {}
+				choices.each do |key, value|
+					next if value.nil?
+
+					parts = key.split( "." )
+					current = data
+					parts[ 0..-2 ].each do |part|
+						current[ part ] ||= {}
+						current = current[ part ]
+					end
+					current[ parts.last ] = value
+				end
+				data
+			end
+
+			def load_existing_config( path: )
+				return {} unless File.file?( path )
+
+				JSON.parse( File.read( path ) )
+			rescue JSON::ParserError
+				{}
+			end
+
+			def reload_config_after_setup!
+				@config = Config.load( repo_root: repo_root )
+			end
+
+			def global_config_exists?
+				path = Config.global_config_path( repo_root: repo_root )
+				!path.empty? && File.file?( path )
+			end
+		end
+
+		include Setup
+	end
+end

data/lib/carson/runtime.rb

@@ -4,6 +4,7 @@
 require "fileutils"
 require "json"
 require "open3"
+require "stringio"
 require "time"
 
 module Carson
@@ -22,11 +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: )
+		def initialize( repo_root:, tool_root:, out:, err:, in_stream: $stdin )
 			@repo_root = repo_root
 			@tool_root = tool_root
 			@out = out
 			@err = err
+			@in = in_stream
+			@concise = false
 			@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 )
@@ -34,7 +37,23 @@ module Carson
 
 	private
 
-		attr_reader :repo_root, :tool_root, :out, :err, :config, :git_adapter, :github_adapter
+		attr_reader :repo_root, :tool_root, :out, :err, :in, :config, :git_adapter, :github_adapter
+
+		# Returns true when output should be minimal (used by onboard/refresh).
+		def concise?
+			@concise
+		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
@@ -187,3 +206,4 @@ require_relative "runtime/lint"
 require_relative "runtime/audit"
 require_relative "runtime/review"
 require_relative "runtime/govern"
+require_relative "runtime/setup"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.1
 platform: ruby
 authors:
 - Hailei Wang
@@ -56,6 +56,7 @@ files:
 - lib/carson/runtime/review/query_text.rb
 - lib/carson/runtime/review/sweep_support.rb
 - lib/carson/runtime/review/utility.rb
+- lib/carson/runtime/setup.rb
 - lib/carson/version.rb
 - templates/.github/AGENTS.md
 - templates/.github/CLAUDE.md
@@ -70,6 +71,16 @@ metadata:
   changelog_uri: https://github.com/wanghailei/carson/blob/main/RELEASE.md
   bug_tracker_uri: https://github.com/wanghailei/carson/issues
   documentation_uri: https://github.com/wanghailei/carson/blob/main/MANUAL.md
+post_install_message: |2+
+
+  ⧓ Carson at your service.
+
+    Step into your project directory and run:
+
+      carson onboard
+
+    I'll walk you through everything from there.
+
 rdoc_options: []
 require_paths:
 - lib
@@ -88,3 +99,4 @@ rubygems_version: 4.0.3
 specification_version: 4
 summary: Outsider governance runtime for repository hygiene and merge readiness.
 test_files: []
+...