This directory holds design, architecture, and operational documentation for Base. The top-level README is the product front door, and 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.

For GitHub labels, milestones, Projects, issue assignment, branch names, and worktree-based PR trains, see GitHub Workflow.

Use stable topic names for documentation files:

• architecture.md for the broad product and system architecture.
• <feature>.md for focused feature designs such as ide-bootstrapping.md.
• <domain>-<topic>.md when a shorter topic name would be ambiguous.
• Avoid generic names such as design.md once the subject is known.

Document titles can still say whether a page is a design, model, boundary, or reference. The filename should answer "what is this about?"

• Architecture describes Base's product direction, command model, environment model, manifest shape, and repository conventions.
• First-Mile Bootstrap documents bootstrap.sh, install mode selection, handoff commands, and contributor setup.
• Execution Model documents the current basectl runtime, dispatch order, public launchers, and runtime shell behavior.
• Linux Support defines the first Ubuntu/Debian runtime support plan and bootstrap boundaries.
• Runtime Environment is the canonical reference for Base-managed environment variables, ~/.baserc, and mutability rules.
• Testing explains Base's Python, BATS, and hermetic integration test layers.
• Tool Boundaries records ecosystem decisions for tools such as mise, direnv, Homebrew, IDEs, Docker, and dotfile managers.

• IDE Bootstrapping covers project IDE manifests, supported IDEs, extensions, additive settings, and diagnostics.
• Local Config covers user-local Base config, precedence, sync guidance, and the user/project boundary.
• Project Installers defines how project-owned installers should use Base without moving product-specific logic into Base.
• Python Manifest Section records the future structured Python manifest shape and its relationship to current python-package artifacts.
• Repository Baseline documents basectl repo init, basectl repo check, and basectl repo configure for standardizing new Base-managed repositories.
• Workspace Manifest defines the future team-shared repo-set contract and its relationship to discovered local projects.
• Setup Hooks Boundary records why Base does not support arbitrary manifest setup hooks yet.
• basectl onboard captures the guided setup experience and its relationship to project installers.
• basectl ci defines the future non-interactive CI entry point and its relationship to Linux support.
• basectl check parallelism records the evaluation and implementation constraints for parallel check probes.
• Doctor Finding IDs is the stable reference for BASE-D*, BASE-P*, and BASE-H* finding identifiers emitted by basectl doctor --format json.
• Base-managed demo project defines the proof project criteria for showing Base's complete workspace workflow.
• Project Demo Workflow documents demo.script, basectl demo, Base's self-demo, and the base-demo reference repository.
• Demo Maintenance defines the needs-demo label and PR convention for keeping executable demos aligned with product changes.
• base_cli Runtime Package describes the Python CLI foundation used by Base and Base-supported project CLIs.
• GitHub Workflow documents how Base uses GitHub Issues, labels, milestones, Projects, worktrees, and PR trains.