Design basectl onboard

README.md

@@ -50,6 +50,7 @@ Planned commands include:
 - `basectl setup <project>`
 - `basectl test`
 - `basectl test <project>`
+- `basectl onboard`
 
 The important idea is that the user should not need to memorize a different
 bootstrap story for every repository in the workspace. Planned commands are
@@ -152,6 +153,11 @@ basectl doctor
 basectl doctor --dev
 ```
 
+`basectl onboard` is a planned guided setup experience for technically-adjacent
+users who want a checklist-style first Base setup. Its design is captured in
+[docs/basectl-onboard.md](docs/basectl-onboard.md). Product-specific onboarding
+should still live in project installers that call Base internally.
+
 ### 2. Shell Environment Management
 
 Base should manage shell environments at two levels:

TODO.md

@@ -39,14 +39,18 @@ they are merged.
     - Cover manifest validation, dry-run command planning, daemon-check
       failures, Compose command failures, and activate-time startup behavior.
 
-- [ ] Design `basectl onboard`.
-  - Goal: provide a guided checklist-style setup experience without making `basectl setup` itself interactive-heavy.
-  - Expected behavior: explain each prerequisite, confirm before performing major steps, and call existing setup/check primitives internally.
-
 - [ ] Package Base as a Homebrew formula or tap.
   - Goal: make Base installation feel native on macOS.
   - Expected behavior: support an install path such as `brew install codeforester/base/basectl`.
 
+- [ ] Implement `basectl onboard`.
+  - Goal: provide the guided checklist-style Base setup experience described in
+    `docs/basectl-onboard.md`.
+  - Expected behavior: orchestrate existing setup, check, doctor, profile, and
+    project-discovery primitives without duplicating their logic.
+  - Starting point: implement the v1 Bash subcommand with dry-run, prompted,
+    `--yes`, `--dev`, and `--no-profile` flows.
+
 - [ ] Add initial Linux support plan.
   - Goal: define the first supported Linux target, likely Ubuntu/Debian.
   - Expected design topics: `/etc/os-release` detection, `apt` equivalents for Homebrew-managed bootstrap dependencies, shell startup differences, and CI implications.

cli/bash/commands/basectl/README.md

@@ -34,6 +34,10 @@ that delegate to `basectl`.
 - `version`
 - `help`
 
+## Planned subcommands
+
+- `onboard`
+
 ## Notes
 
 - `basectl setup` is the default local bootstrap path.
@@ -52,5 +56,8 @@ that delegate to `basectl`.
 - `basectl update` updates the Base repository from Git and then runs `basectl setup`.
 - `basectl projects list` scans a workspace for `base_manifest.yaml` files and prints discovered project names and paths.
 - `basectl version` prints the installed Base version from the repo-root `VERSION` file.
+- `basectl onboard` is planned as a guided first-run checklist around existing
+  setup, check, doctor, profile, and project-discovery primitives. See
+  `docs/basectl-onboard.md`.
 - basectl-specific bootstrap subcommands live under `cli/bash/commands/basectl/subcommands/`.
 - basectl tests live under `cli/bash/commands/basectl/tests/`.

docs/basectl-onboard.md

@@ -0,0 +1,152 @@
+# `basectl onboard` Design
+
+`basectl onboard` is a future guided setup experience for Base itself.
+
+It should help technically-adjacent users through the first Base setup without
+turning `basectl setup` into an interactive, hand-holding command. The setup
+command should remain the direct, scriptable reconciler. The onboard command can
+be slower, friendlier, and more explanatory because that is its purpose.
+
+## Audience
+
+`basectl onboard` is for someone who can use a terminal but does not yet know
+what Base will do to their machine.
+
+Examples:
+
+- a DevOps learner setting up a Mac for a Base-managed project
+- a new developer joining a workspace that uses Base
+- a technically-adjacent user who wants confirmation before each major setup
+  step
+
+It is not the right layer for product-specific onboarding. A project such as
+Banyanlabs should still own its own `install.sh` or packaged installer and call
+Base internally. See [Project Installers](project-installers.md) for that
+boundary.
+
+## Relationship To Existing Commands
+
+`basectl onboard` should orchestrate existing Base primitives:
+
+- `basectl check` for quick environment state
+- `basectl doctor` for human-readable diagnosis and suggested fixes
+- `basectl setup` for actual reconciliation
+- `basectl setup --dev` when the user opts into Base developer prerequisites
+- `basectl update-profile` for shell startup integration
+- `basectl projects list` to show discovered projects after setup
+- `basectl activate base` as the final suggested next step
+
+It should not duplicate Homebrew, Python, venv, manifest, or shell-profile logic.
+Those responsibilities already belong to the setup/check/profile commands.
+
+## Command Shape
+
+Initial command shape:
+
+```bash
+basectl onboard [options]
+```
+
+Planned options:
+
+```text
+  --dev            Include Base developer prerequisites.
+  --dry-run        Explain and show planned actions without making changes.
+  --yes            Accept default answers for non-destructive prompts.
+  --no-profile     Skip shell profile updates.
+  -v               Enable DEBUG logging for underlying commands.
+  -h, --help       Show help text.
+```
+
+The command should default to the `base` project. Project-specific guided
+onboarding remains a project installer responsibility.
+
+## Experience Flow
+
+The first implementation should be simple and checklist-oriented:
+
+1. Print a short explanation of what Base is about to verify.
+2. Run `basectl check`.
+3. If checks fail, explain that setup can reconcile the missing pieces.
+4. Ask for confirmation before running `basectl setup`.
+5. If `--dev` was requested, include developer prerequisites in setup.
+6. Ask for confirmation before running `basectl update-profile`, unless
+   `--no-profile` was set.
+7. Run `basectl doctor` to summarize the final state.
+8. Print discovered projects with `basectl projects list` when available.
+9. Suggest `basectl` or `basectl activate base` as the next interactive step.
+
+The command should show the exact Base command before it runs it. For example:
+
+```text
+Next: basectl setup
+This installs or verifies Homebrew, Xcode Command Line Tools, Base Python, and
+Base-managed artifacts.
+Proceed? [y/N]
+```
+
+## Prompting Rules
+
+Prompts should be explicit but sparse:
+
+- Prompt before operations that can install software or edit shell startup files.
+- Do not prompt before read-only checks.
+- Treat Enter as the conservative answer when there is risk.
+- `--yes` may accept normal setup/profile prompts, but should not bypass fatal
+  safety checks such as unsupported operating systems.
+- `--dry-run` should not prompt for actions it will not perform.
+
+## Output Style
+
+The command should be friendly without hiding the mechanics:
+
+- Use plain English headings such as `Check`, `Setup`, `Shell Profile`, and
+  `Next Steps`.
+- Keep underlying command output visible so users can see long-running progress.
+- Keep logs on stderr, following Base's existing logging convention.
+- Use `basectl doctor` output for final health reporting rather than inventing a
+  separate diagnosis format.
+
+## Failure Behavior
+
+Failures should be recoverable and specific:
+
+- If `basectl check` fails, continue to the setup prompt.
+- If `basectl setup` fails, run or recommend `basectl doctor` and stop before
+  profile updates.
+- If `basectl update-profile` fails, leave setup success intact and explain how
+  to rerun that step.
+- Preserve the failing command's exit status when onboarding cannot complete.
+
+## Non-Goals
+
+`basectl onboard` should not:
+
+- become a replacement for `basectl setup`
+- become a product-specific installer
+- clone project repositories
+- manage secrets or credentials
+- hide underlying command output behind a full-screen interface in v1
+- introduce a dependency on a TUI framework before the simple checklist version
+  proves insufficient
+
+## Implementation Notes
+
+The first implementation can be a Bash subcommand under
+`cli/bash/commands/basectl/subcommands/onboard.sh`.
+
+That keeps it close to the setup/check/profile primitives it orchestrates and
+avoids adding Python dependencies for interactive prompting. If a richer UI is
+needed later, the Bash command can delegate to a Python package while preserving
+the same public command.
+
+Tests should cover:
+
+- help text
+- dry-run flow
+- declined setup prompt
+- accepted setup prompt
+- `--yes` non-interactive flow
+- `--dev` passing through to setup and doctor
+- `--no-profile` skipping profile updates
+- setup failure stopping later steps

docs/project-installers.md

@@ -92,7 +92,8 @@ Project installers should not:
 
 ## Relationship To `basectl onboard`
 
-`basectl onboard` is still useful, but it should target a different layer.
+`basectl onboard` is still useful, but it should target a different layer. Its
+command design is captured in [basectl-onboard.md](basectl-onboard.md).
 
 `basectl onboard` should be a guided Base setup experience for
 technically-adjacent users who are installing Base itself. A project installer