From fcc66307eda4c604d522a91a999de58bcd3de9a5 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah Date: Mon, 1 Jun 2026 12:23:03 -0700 Subject: [PATCH] Add Base FAQ --- CHANGELOG.md | 1 + FAQ.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + docs/README.md | 5 +- 4 files changed, 176 insertions(+), 2 deletions(-) create mode 100644 FAQ.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b2b6d7..59a2780 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and Base versions are tracked in the repo-root `VERSION` file. project health summary. - Added `bootstrap.sh` as a first-mile macOS bootstrapper for installing Homebrew, Git, Bash, and Base before handing off to `basectl`. +- Added a top-level FAQ for common first-run and product questions. ### Fixed diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..05d4394 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,170 @@ +# Base FAQ + +## First-Time Installation + +### What should I run on a blank macOS machine? + +Use `bootstrap.sh`: + +```bash +curl -fsSL https://raw.githubusercontent.com/codeforester/base/master/bootstrap.sh | bash +``` + +The bootstrapper verifies macOS, ensures Homebrew is available, installs Git and +a supported Bash when needed, installs or updates Base, and then prints the +exact `basectl` commands needed to finish setup. + +### Why does bootstrap print commands instead of changing my shell automatically? + +`bootstrap.sh` is the first-mile handoff into Base. It intentionally avoids +editing shell startup files so a user can see what was installed and choose when +Base should affect new shells. Shell integration is owned by: + +```bash +basectl update-profile +``` + +For a source checkout that is not yet on `PATH`, use the absolute command that +bootstrap prints, typically: + +```bash +~/work/base/bin/basectl update-profile +``` + +### When should I use bootstrap.sh, install.sh, Homebrew, or a source checkout? + +Use `bootstrap.sh` on a new or uncertain macOS machine. It handles missing +first-mile prerequisites and then hands off to Base. + +Use Homebrew when you want Base managed like an ordinary installed tool: + +```bash +brew install codeforester/base/base +basectl setup +basectl update-profile +``` + +Use a source checkout when you are contributing to Base or want to inspect and +run the repository directly: + +```bash +git clone https://github.com/codeforester/base.git ~/work/base +~/work/base/bin/basectl setup +~/work/base/bin/basectl update-profile +``` + +Use `install.sh` when you specifically want the source-install path to clone or +update Base and then run setup/profile commands as one script. + +### How do I choose source mode or Homebrew mode during bootstrap? + +Pass an explicit mode: + +```bash +curl -fsSL https://raw.githubusercontent.com/codeforester/base/master/bootstrap.sh | bash -s -- --source +curl -fsSL https://raw.githubusercontent.com/codeforester/base/master/bootstrap.sh | bash -s -- --brew +``` + +Without an explicit mode, bootstrap preserves an existing Homebrew Base install, +then an existing source checkout, and otherwise defaults to source mode. + +## Homebrew And Source Coexistence + +### Can Homebrew-installed Base and source-cloned Base coexist? + +Yes. They can coexist because the active `basectl` is whichever executable your +shell resolves first. A source checkout can always be run explicitly: + +```bash +~/work/base/bin/basectl version +``` + +That does not require it to be first on `PATH`. + +### How do I know which basectl is active? + +Run: + +```bash +command -v basectl +type -a basectl +``` + +`command -v basectl` shows the command your shell will run by default. +`type -a basectl` shows every matching command your shell can see. + +### If I have both installs, which one should bootstrap prefer? + +Bootstrap should not silently take over an existing setup. If no mode is +specified, it preserves an existing Homebrew Base install first, then an +existing source checkout. Pass `--source` or `--brew` when you want a specific +route. + +## Setup, Profile, And Diagnostics + +### What is the difference between basectl setup and basectl update-profile? + +`basectl setup` prepares Base and project prerequisites: Homebrew artifacts, +Python virtual environments, configured project artifacts, and other declared +setup requirements. + +`basectl update-profile` updates shell startup files so `basectl` and Base shell +integration are available in new interactive shells. + +### What is the difference between basectl setup, basectl onboard, and basectl doctor? + +`basectl setup` makes the machine or project ready. + +`basectl onboard` is the guided first-run flow for Base itself. + +`basectl doctor` reports what is healthy, missing, or misconfigured. It is the +best command to run when something does not look right. + +### After Homebrew installation, why do I still need basectl setup? + +Homebrew installs Base's files. `basectl setup` prepares the local Base runtime +under `~/.base.d/base/.venv` and reconciles other prerequisites that Base needs +to operate. + +## Workspace Configuration + +### How should I configure my workspace root? + +If repositories live side by side under a directory such as `~/work`, configure: + +```yaml +workspace: + root: ~/work +``` + +in: + +```text +~/.base.d/config.yaml +``` + +This helps commands such as `basectl projects list`, `basectl activate +`, and `basectl test ` find participating repositories. + +### What belongs in Base versus a project-owned installer? + +Base owns workspace-level conventions: setup orchestration, diagnostics, project +discovery, shell integration, common helper libraries, and repeatable command +contracts. + +A project-owned installer owns product-specific setup: credentials, service +accounts, domain data, app-specific local services, and any onboarding language +that belongs to that product rather than to Base. + +Project installers should call Base when they need workspace primitives instead +of reimplementing them. + +## More Information + +Useful starting points: + +- [README](README.md) for the product overview and first-run guide. +- [Documentation Map](docs/README.md) for architecture and design docs. +- [Project Installers](docs/project-installers.md) for project-owned installer + boundaries. +- [Tool Boundaries](docs/tool-boundaries.md) for ecosystem ownership decisions. diff --git a/README.md b/README.md index df32277..0093d22 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ A developer may need: Base exists to provide that missing common layer. +Common first-run and product questions are answered in [FAQ.md](FAQ.md). Contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md). Release notes are tracked in [CHANGELOG.md](CHANGELOG.md). @@ -706,6 +707,7 @@ feature designs, and ecosystem boundary decisions. Key starting points: +- [FAQ](FAQ.md) - [Architecture](docs/architecture.md) - [Execution Model](docs/execution-model.md) - [Tool Boundaries](docs/tool-boundaries.md) diff --git a/docs/README.md b/docs/README.md index 7fc747c..bdd4561 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,9 @@ # Base Documentation This directory holds design, architecture, and operational documentation for -Base. The top-level [README](../README.md) is the product front door; this page -is the documentation map. +Base. The top-level [README](../README.md) is the product front door, and +[FAQ.md](../FAQ.md) answers common first-run and product questions. This page is +the documentation map. For contribution workflow, branch naming, tests, and PR expectations, see [CONTRIBUTING.md](../CONTRIBUTING.md).