Add CI mode flag to lifecycle commands

.ai-context/COMMANDS.md

@@ -63,10 +63,11 @@ options.
   checkout. Plain `repo init` writes local baseline files without committing or
   pushing them; `repo init --pr` commits baseline changes on a branch, pushes to
   `origin`, and opens a PR.
-- `basectl ci <setup|check|doctor> <project>` - run Base setup/check/doctor
+- `basectl <setup|check|doctor> --ci <project>` - run Base setup/check/doctor
   with CI-safe defaults. It does not run project tests or create CI runners/VMs.
-  `ci setup --format json` uses `output` for the compact final status and adds
-  `output_lines` on failures for intermediate context.
+  `setup --ci --format json` uses `output` for the compact final status and
+  adds `output_lines` on failures for intermediate context. `basectl ci`
+  remains a compatibility alias.
 - `basectl release <check|plan|notes|publish>` - inspect release readiness,
   print plans/notes, and publish guarded GitHub-side release artifacts.
 - `basectl gh <area> <command>` - manage GitHub issues, PRs, branches, repo

.ai-context/DECISIONS.md

@@ -6,8 +6,9 @@ architecture discussion.
 ## Product And Scope
 
 - Base is a Mac-first workspace control plane.
-- Linux runtime and CI support are actively being rolled out, with
-  `basectl ci` and Ubuntu GitHub Actions coverage as the current proof points.
+- Linux runtime and CI support are actively being rolled out, with `--ci` mode
+  on setup/check/doctor and Ubuntu GitHub Actions coverage as the current proof
+  points.
   Full Linux setup/bootstrap remains a narrower planned contract; keep platform
   details in `docs/linux-support.md`.
 - Windows support is not currently in scope.

.github/workflows/tests.yml

@@ -136,8 +136,8 @@ jobs:
 
       - name: Run Base setup and check smoke tests
         run: |
-          ./bin/basectl ci setup base --format json
-          ./bin/basectl ci check base --format json
+          ./bin/basectl setup --ci base --format json
+          ./bin/basectl check --ci base --format json
 
       - name: Verify shell profile integration
         run: |
@@ -203,9 +203,9 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y bats
 
-      - name: Run basectl ci smoke check
+      - name: Run basectl --ci smoke check
         run: |
-          ./bin/basectl ci check base --format json
+          ./bin/basectl check --ci base --format json
 
       - name: Run integration tests
         env:
@@ -265,7 +265,7 @@ jobs:
 
       - name: Run Ubuntu source-checkout validation
         run: |
-          ./bin/basectl ci check base --format json
+          ./bin/basectl check --ci base --format json
           env -u BASE_HOME ./bin/base-test
 
   security:

CHANGELOG.md

@@ -9,6 +9,9 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ### Added
 
+- Added `--ci` mode to `basectl setup`, `basectl check`, and `basectl doctor`
+  as the preferred CI-safe command surface while keeping `basectl ci` as a
+  compatibility alias.
 - Added `bootstrap.sh --ensure-bash` to verify or install only the Bash 4.2+
   prerequisite on macOS and Ubuntu/Debian before the full Base setup path is
   available.
@@ -21,8 +24,8 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ### Changed
 
-- Clarified `basectl ci` help and docs so CI-safe setup/readiness/diagnostics
-  are not confused with running tests, launching GitHub Actions, or creating
+- Clarified CI-safe setup/readiness/diagnostics help and docs so `--ci` mode is
+  not confused with running tests, launching GitHub Actions, or creating
   Ubuntu/Multipass VMs.
 
 ### Fixed

README.md

@@ -289,7 +289,7 @@ Current implemented commands include:
 - `basectl setup [project]`
 - `basectl check`
 - `basectl doctor`
-- `basectl ci <setup|check|doctor> <project>`
+- `basectl <setup|check|doctor> --ci <project>`
 - `basectl clean --older-than <age>`
 - `basectl clean --keep-last <count>`
 - `basectl config path`
@@ -321,12 +321,13 @@ Current implemented commands include:
 - `basectl onboard`
 - `basectl version`
 
-`basectl ci` wraps setup, check, and doctor with CI-safe defaults such as
-non-interactive behavior and JSON-capable output. It does not run project tests,
-launch GitHub Actions locally, or create Ubuntu/Multipass VMs. Use
+`--ci` runs setup, check, and doctor with CI-safe defaults such as
+non-interactive behavior and JSON-capable output. The legacy `basectl ci`
+wrapper remains as a compatibility alias. Neither surface runs project tests,
+launches GitHub Actions locally, or creates Ubuntu/Multipass VMs. Use
 `basectl test` for a project's declared test command and `bin/base-test` for
 Base's full source-checkout validation suite. See
-[basectl ci](docs/basectl-ci.md) for the CI contract, and
+[CI-safe mode](docs/basectl-ci.md) for the CI contract, and
 [Command Quick Reference](docs/command-reference.md) for a scannable command
 lookup table.
 

cli/bash/commands/basectl/README.md

@@ -35,7 +35,7 @@ such command directories exist. Optional utility CLIs such as `caff` and
 - `activate`
 - `setup`
 - `check`
-- `ci setup/check/doctor`
+- `ci setup/check/doctor` (compatibility alias for `setup/check/doctor --ci`)
 - `clean`
 - `config`
 - `doctor`
@@ -71,9 +71,10 @@ such command directories exist. Optional utility CLIs such as `caff` and
   project argument validates `project.name`.
 - `basectl check [project]` verifies the same local requirements without making
   changes and can include project manifest artifacts.
-- `basectl ci setup/check/doctor <project>` runs Base setup, readiness checks,
-  and diagnostics with CI-safe defaults and text or JSON output. It does not
-  run project tests or launch CI runners/VMs.
+- `basectl setup/check/doctor --ci <project>` runs Base setup, readiness
+  checks, and diagnostics with CI-safe defaults and text or JSON output.
+  `basectl ci setup/check/doctor <project>` remains a compatibility alias.
+  Neither surface runs project tests or launches CI runners/VMs.
 - `basectl setup/check/doctor --profile <list>` manage opt-in prerequisite
   profiles. `sre` is the first additional built-in profile, and profiles compose
   as comma-separated lists such as `--profile dev,sre`.

cli/bash/commands/basectl/subcommands/check.sh

@@ -14,6 +14,7 @@ Usage:
   basectl check [project] [options]
 
 Options:
+  --ci                  Run checks with CI-safe defaults.
   --profile <list>      Include named prerequisite profiles. Known profiles: dev, sre, ai, linux-lab.
   --format <text|json>  Select output format. Defaults to text.
   --manifest <path>     Use a specific base_manifest.yaml path for project checks.
@@ -34,6 +35,7 @@ Purpose:
 
 See also:
   basectl doctor [project] [options]
+  basectl ci check <project> [options]  Compatibility alias for check --ci.
 
 Check does:
   1. Verify platform-specific runtime prerequisites.
@@ -65,6 +67,9 @@ base_check_subcommand_main() {
                 base_check_subcommand_usage
                 return 0
                 ;;
+            --ci)
+                setup_enable_ci_mode
+                ;;
             --format)
                 shift
                 if [[ -z "${1:-}" ]]; then

cli/bash/commands/basectl/subcommands/ci.sh

@@ -32,7 +32,8 @@ Profiles:
   linux-lab - Multipass tooling for local Ubuntu lab VMs on macOS hosts.
 
 Purpose:
-  Run Base setup, checks, and diagnostics with CI-safe defaults.
+  Compatibility alias for setup/check/doctor --ci.
+  Prefer: basectl <setup|check|doctor> --ci <project> [options]
   Sets BASE_CI=true so setup and diagnostic paths can choose CI-safe behavior.
   Does not run project tests, launch GitHub Actions, or create Ubuntu/Multipass VMs.
 EOF
@@ -45,11 +46,7 @@ base_ci_usage_error() {
 }
 
 base_ci_apply_environment() {
-    export BASE_CI=true
-    export CI=true
-    export BASE_SETUP_NOTIFY=false
-    export BASE_SETUP_ALLOW_SYSTEM_PYTHON=true
-    export BASE_SETUP_ALLOW_NONINTERACTIVE_XCODE_INSTALL=false
+    setup_enable_ci_mode
 }
 
 base_ci_source_subcommand_module() {
@@ -118,7 +115,7 @@ base_ci_parse_args() {
                 ;;
             --recreate-venv)
                 [[ "$command" == setup ]] || {
-                    base_ci_usage_error "Option '--recreate-venv' is only supported for 'ci setup'."
+                    base_ci_usage_error "Option '--recreate-venv' is only supported for setup --ci."
                     return $?
                 }
                 BASE_CI_RECREATE_VENV=1
@@ -148,6 +145,7 @@ base_ci_parse_args() {
 }
 
 base_ci_common_delegate_args() {
+    printf '%s\n' --ci
     if [[ -n "$BASE_CI_PROFILE" ]]; then
         printf '%s\n' --profile "$BASE_CI_PROFILE"
     fi
@@ -161,6 +159,7 @@ base_ci_common_delegate_args() {
 
 base_ci_setup_delegate_args() {
     base_ci_common_delegate_args
+    printf '%s\n' --format "$BASE_CI_FORMAT"
     if ((BASE_CI_RECREATE_VENV)); then
         printf '%s\n' --recreate-venv
     fi
@@ -172,64 +171,11 @@ base_ci_check_or_doctor_delegate_args() {
     printf '%s\n' "$BASE_CI_PROJECT" --format "$BASE_CI_FORMAT"
 }
 
-base_ci_print_setup_json() {
-    local exit_code="$1"
-    local stdout_file="$2"
-    local stderr_file="$3"
-    local python_bin
-
-    python_bin="$(setup_diagnostics_python_bin)" ||
-        fatal_error "Python is required to render Base CI setup JSON."
-    setup_ensure_cached_paths
-    env BASE_HOME="$BASE_HOME" PYTHONPATH="$_BASE_SETUP_PYTHONPATH_CACHE" \
-        "$python_bin" -m base_setup.ci_json setup-json \
-        --project "$BASE_CI_PROJECT" \
-        --exit-code "$exit_code" \
-        --stdout-file "$stdout_file" \
-        --stderr-file "$stderr_file"
-}
-
-base_ci_run_setup_json() {
-    local args=("$@")
-    local stdout_file
-    local stderr_file
-    local exit_code
-    local render_status
-
-    std_make_temp_file stdout_file base-ci-setup-stdout || return 1
-    std_make_temp_file stderr_file base-ci-setup-stderr || return 1
-
-    base_setup_subcommand_main "${args[@]}" > "$stdout_file" 2> "$stderr_file"
-    exit_code=$?
-
-    # Keep JSON as stdout-only; replay setup logs to stderr for CI visibility.
-    if [[ -s "$stdout_file" ]]; then
-        cat "$stdout_file" >&2
-    fi
-    if [[ -s "$stderr_file" ]]; then
-        cat "$stderr_file" >&2
-    fi
-
-    base_ci_print_setup_json "$exit_code" "$stdout_file" "$stderr_file"
-    render_status=$?
-    rm -f "$stdout_file" "$stderr_file"
-    if ((render_status)); then
-        return "$render_status"
-    fi
-    return "$exit_code"
-}
-
 base_ci_run_setup() {
     local args=()
 
     mapfile -t args < <(base_ci_setup_delegate_args)
     base_ci_source_subcommand_module setup || return 1
-
-    if [[ "$BASE_CI_FORMAT" == json ]]; then
-        base_ci_run_setup_json "${args[@]}"
-        return $?
-    fi
-
     base_setup_subcommand_main "${args[@]}"
 }
 

cli/bash/commands/basectl/subcommands/doctor.sh

@@ -14,6 +14,7 @@ Usage:
   basectl doctor [project] [options]
 
 Options:
+  --ci                  Run diagnostics with CI-safe defaults.
   --profile <list>      Include named prerequisite profiles. Known profiles: dev, sre, ai, linux-lab.
   --format <text|json>  Select output format. Defaults to text.
   --manifest <path>     Use a specific base_manifest.yaml path for project diagnostics.
@@ -35,6 +36,7 @@ Purpose:
 
 See also:
   basectl check [project] [options]
+  basectl ci doctor <project> [options]  Compatibility alias for doctor --ci.
 EOF
 }
 
@@ -183,6 +185,9 @@ base_doctor_subcommand_main() {
                 base_doctor_subcommand_usage
                 return 0
                 ;;
+            --ci)
+                setup_enable_ci_mode
+                ;;
             --profile)
                 shift
                 if [[ -z "${1:-}" ]]; then