Skip to content

Add a Base FAQ document #405

@codeforester

Description

@codeforester

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.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions