Document project onboarding boundary

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.

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 <project>` 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
 

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 <project>` 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 <project>` reconciles a Base-managed project from its manifest.
+- `<project>/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

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
+<project>` 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: