From d36271082458ab4e1445668cbb1675ca3987b055 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah Date: Fri, 29 May 2026 13:58:24 -0700 Subject: [PATCH] Document project onboarding boundary --- CHANGELOG.md | 2 ++ README.md | 6 ++++-- docs/basectl-onboard.md | 15 +++++++++++++++ docs/project-installers.md | 6 ++++++ 4 files changed, 27 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ebcaaff..8f77b59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ and Base versions are tracked in the repo-root `VERSION` file. ### Added - Added documentation guidance for using `mise` with Go and Java projects. +- Added documentation for the boundary between `basectl onboard` and + project-owned installers. - Added a repo-owned `bin/base-test` runner and declared it through `base_manifest.yaml` so Base can dogfood `basectl test base`. - Added GitHub CLI authentication diagnostics to developer prerequisite checks. diff --git a/README.md b/README.md index d6ef992..70ffa0a 100644 --- a/README.md +++ b/README.md @@ -495,8 +495,10 @@ to `PATH`, so `basectl` can be run without spelling out the full path. Use `basectl version` or `basectl --version` to report the installed Base version. Project-specific onboarding should live in project installers that call Base -internally. See [Project Installers](docs/project-installers.md) for the -recommended boundary between Base and scripts such as `banyanlabs/install.sh`. +internally. Base intentionally does not provide `basectl onboard ` for +product-specific setup; that flow belongs in scripts such as +`banyanlabs/install.sh`. See [Project Installers](docs/project-installers.md) +for the recommended boundary. ## Documentation diff --git a/docs/basectl-onboard.md b/docs/basectl-onboard.md index 380b6f9..896b3d8 100644 --- a/docs/basectl-onboard.md +++ b/docs/basectl-onboard.md @@ -7,6 +7,21 @@ 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. +## Decision + +Base should not grow `basectl onboard ` as a product-specific guided +installer. Project onboarding belongs in the project repository, where the +installer can speak in that product's language, clone or update that product's +repo, explain product-specific prerequisites, and call Base for the workspace +mechanics it owns. + +The stable split is: + +- `basectl onboard` guides first-run Base setup. +- `basectl setup ` reconciles a Base-managed project from its manifest. +- `/install.sh` or a packaged project installer guides product-specific + onboarding and calls Base internally. + ## Audience `basectl onboard` is for someone who can use a terminal but does not yet know diff --git a/docs/project-installers.md b/docs/project-installers.md index 26505dc..0090d0f 100644 --- a/docs/project-installers.md +++ b/docs/project-installers.md @@ -3,6 +3,12 @@ Base should stay a developer workspace engine. Project-specific installers should own the friendlier, product-specific onboarding experience. +This is an intentional product boundary. Base should not add `basectl onboard +` for now. That command would make Base responsible for every +project's product narrative, repository bootstrap choices, credentials, and +next-step guidance. Those concerns change per project and are better owned by +the project itself. + This distinction matters because Base and a project installer serve different audiences: