Problem
As Base grows, common product and onboarding questions are starting to repeat across README sections, design discussions, and issue threads. A dedicated FAQ would give users a concise place to answer first-run and conceptual questions without bloating the main README.
Proposal
Add a top-level or docs-linked FAQ Markdown document, likely docs/faq.md, and link it from the README and docs index.
Initial topics
- What should I run on a blank macOS machine?
- When should I use
bootstrap.sh, install.sh, Homebrew, or a source checkout?
- Can Homebrew-installed Base and source-cloned Base coexist?
- How do I know which
basectl is active?
- Why does bootstrap print
basectl update-profile instead of changing shell files automatically?
- What belongs in Base versus a project-owned installer?
- How should developers configure
workspace.root?
- What is the relationship between
basectl setup, basectl onboard, and basectl doctor?
Scope
- Keep the FAQ practical and user-facing.
- Avoid duplicating long design explanations already covered in focused docs.
- Cross-link deeper docs where appropriate.
Problem
As Base grows, common product and onboarding questions are starting to repeat across README sections, design discussions, and issue threads. A dedicated FAQ would give users a concise place to answer first-run and conceptual questions without bloating the main README.
Proposal
Add a top-level or docs-linked FAQ Markdown document, likely
docs/faq.md, and link it from the README and docs index.Initial topics
bootstrap.sh,install.sh, Homebrew, or a source checkout?basectlis active?basectl update-profileinstead of changing shell files automatically?workspace.root?basectl setup,basectl onboard, andbasectl doctor?Scope