basefoundry · codeforester · Aug 17, 2026 · Aug 17, 2026
@@ -9,7 +9,7 @@ across independent Git repositories. Its durable loop is:
 inventory -> prepare -> verify -> trust -> onboard -> hand off
 ```
 
-Base makes a participating repo set understandable and locally ready while
+Base makes a participating repository set understandable and locally ready while
 projects keep ownership of their application behavior, services, and
 project-specific setup.
 

@@ -11,7 +11,7 @@ engineers. It gives a repeatable way to prepare, verify, test, build, and hand
 off a project, whether that project lives in one repository or spans multiple
 independent Git repositories.
 
-It makes that project or repo set easier to inventory, prepare, verify, trust,
+It makes that project or repository set easier to inventory, prepare, verify, trust,
 onboard, and hand off without turning it into a monorepo or moving
 project-specific logic into Base.
 
@@ -54,7 +54,7 @@ Every engineering project accumulates setup steps, readiness rules, trusted
 commands, and handoff context that can become scattered across READMEs, shell
 state, and maintainer memory. That problem exists within a single repository
 and becomes more visible when work spans several repositories. Base gives a
-project or participating repo set one explicit local contract for answering:
+project or participating repository set one explicit local contract for answering:
 what belongs here, what is ready, what is missing, what may run, and what the
 next person or agent needs to know.
 
@@ -777,7 +777,7 @@ run `basectl workspace configure` to apply the repair path. With
 non-Base-managed repositories, and continues after per-repo failures. Without a
 manifest, Base scans discovered local Base-managed projects under the workspace
 root. This is the fastest way to roll out shared repo or Project schema repairs
-across a local repo family while keeping each repository's `repo configure`
+across a local repository set while keeping each repository's `repo configure`
 behavior idempotent.
 
 Use `basectl workspace setup --dry-run` to preview project setup across the
@@ -1897,7 +1897,7 @@ project is one repository or a set of independent Git repositories.
 
 A single repository can use Base to make setup, readiness, trusted execution,
 and handoff explicit. When a project spans several repositories, Base extends
-the same contract across the repo set. Each project repo remains independent;
+the same contract across the repository set. Each project repo remains independent;
 Base sits beside those repos and offers:
 
 - one declared way to inventory, prepare, and verify local readiness
@@ -1969,7 +1969,7 @@ tracked in GitHub Issues using the workflow in
 
 ## Short Version
 
-Base is the local operating contract you add to a repo set so its readiness,
+Base is the local operating contract you add to a repository set so its readiness,
 trusted execution, onboarding, and handoff stop depending on private maintainer
 memory.
 

@@ -147,7 +147,7 @@ reference. The filename should answer "what is this about?"
   model for executing project-owned manifest commands from unfamiliar
   repositories.
 - [Workspace Manifest](workspace-manifest.md) defines the local team-shared
-  repo-set contract and `basectl workspace --manifest` reporting behavior.
+  repository set contract and `basectl workspace --manifest` reporting behavior.
 - [Setup Hooks Boundary](setup-hooks.md) records why Base does not support
   arbitrary manifest setup hooks yet.
 - [`basectl setup` parallelism](setup-parallelism.md) records why setup stays

@@ -44,7 +44,7 @@ machine-readable structures, and clear next actions from declared inputs and
 observable local state. It does not mean hermetic builds, byte-for-byte
 environments, or transactional multi-repository mutation.
 
-The product responsibility layers are:
+The product responsibility tiers are:
 
 1. The core outcome: deterministic local readiness and handoff.
 2. The enabling execution contract: `base_manifest.yaml`, `basectl`,
@@ -53,7 +53,7 @@ The product responsibility layers are:
    conventions.
 4. Adapters: environment managers, IDEs, containers, Nix/devenv, and AI tools.
 
-These are architecture responsibility layers, not separately installed
+These are architecture responsibility tiers, not separately installed
 packages. Major features should strengthen the outcome loop. A command does not
 become core merely because `basectl` dispatches it.
 
@@ -196,8 +196,10 @@ basectl activate myproject
 ## Shell Environment Layers
 
 Base separates ordinary shell startup from Base runtime activation.
+These shell environment layers are distinct from the product responsibility
+tiers above; their numbering is local to shell startup and runtime state.
 
-### Layer 1 — Dotfile Integration
+### Shell Layer 1 — Dotfile Integration
 
 Applied by the user's normal Bash/Zsh startup files after running
 `basectl update-profile`.
@@ -214,7 +216,7 @@ This layer must not source `base_init.sh` and must not establish the full Base
 runtime contract. It is only about Bash/Zsh startup behavior plus launcher
 availability.
 
-### Layer 2 — Base Runtime Environment
+### Shell Layer 2 — Base Runtime Environment
 
 Applied when the user invokes `basectl`, `basectl activate <project>`, or
 `basectl /path/to/script.sh`. Invoking `basectl` with no arguments in a terminal
@@ -237,7 +239,7 @@ live in [Runtime Environment](runtime-environment.md). The standalone
 `base-bash-libs` install path and post-migration contract live in
 [Base Bash Libraries](base-bash-libs.md).
 
-### Layer 3 — Project-Specific Environment
+### Shell Layer 3 — Project-Specific Environment
 
 Applied inside the project subshell when `basectl activate <project>` is run.
 
@@ -598,7 +600,7 @@ parent manifest rather than auto-discovering everything.
 
 ### Workspace manifest
 
-A workspace manifest is a team-shared repo-set contract. It is distinct from
+A workspace manifest is a team-shared repository set contract. It is distinct from
 each project's `base_manifest.yaml`: the workspace manifest says which
 repositories should belong together, while project manifests say how each
 repository participates in Base.
@@ -657,7 +659,7 @@ state, virtual environment state, and Git state across discovered projects,
 including invalid manifests without stopping the whole scan. With
 `workspace.manifest` or `--manifest <path>`, workspace commands also report
 missing required repositories, missing optional repositories, and discovered
-Base-managed projects outside the expected repo set. `basectl workspace check`
+Base-managed projects outside the expected repository set. `basectl workspace check`
 and `basectl workspace doctor` run project checks and diagnostics across
 discovered projects. `basectl workspace onboarding` is a shipped read-only text
 or JSON summary of ready, needs-setup, invalid-manifest, missing-required, and
@@ -818,18 +820,8 @@ These extras emerge organically from real needs — they are not designed upfron
 
 ## What Base Is Not
 
-- Not a replacement for Docker or dev containers — those solve a different problem
-  (containerization). Base is local and lightweight.
-- Not broadly cross-platform today — macOS remains the primary platform, while
-  Ubuntu/Debian source-checkout runtime and apt-backed setup are implemented.
-  Broader Linux distributions, WSL, and Windows are not supported today.
-- Not a universal package manager — Homebrew handles that. Base orchestrates on top
-  of Homebrew.
-- Not a generic multi-repository sync or command fan-out manager.
-- Not a hosted agent runtime, live session-transfer service, or provider upload
-  system.
-- Not trying to solve every edge case — version conflict handling across projects,
-  language runtimes beyond Python, and container integration are future considerations.
+For the canonical non-goals and ecosystem boundary, see
+[Tool Boundaries](tool-boundaries.md#what-base-is-not).
 
 ---
 

@@ -38,7 +38,7 @@ Options:
 ```text
   --profile <list> Include named prerequisite profiles.
   --dry-run        Explain and show planned actions without making changes.
-  --yes            Accept setup/profile prompts; never approve manifest trust.
+  --yes            Accept setup/profile prompts; never grant manifest trust.
   --no-profile     Skip shell profile updates.
   -v               Enable DEBUG logging for underlying commands.
   -h, --help       Show help text.
@@ -111,23 +111,8 @@ Those responsibilities already belong to the setup/check/profile commands.
 
 ## Command Shape
 
-Command shape:
-
-```bash
-basectl onboard [project] [options]
-```
-
-Options:
-
-```text
-  --profile <list> Include named prerequisite profiles.
-  --dry-run        Explain and show planned actions without making changes.
-  --yes            Approve setup changes and the shell-profile prompt; never
-                   grant manifest trust.
-  --no-profile     Skip shell profile updates.
-  -v               Enable DEBUG logging for underlying commands.
-  -h, --help       Show help text.
-```
+The command shape and canonical option descriptions are documented in
+[Usage](#usage) above.
 
 The command defaults to the `base` project. Passing a project name targets the
 Base-managed project checks and setup steps without making Base responsible for

@@ -58,7 +58,7 @@ $BASE_CACHE_DIR/
 │   │       ├── base_setup/
 │   │       └── base_github_projects/
 │   └── runs/
-    │       └── <base-run-id>__<command>__<project>/
+│       └── <base-run-id>__<command>__<project>/
 │           ├── run.json
 │           ├── logs/
 │           │   └── primary.log

@@ -127,7 +127,7 @@ Doctor commands use the same diagnostic item fields. The top-level
 | `BASE-D102` | Unsupported prerequisite profile version |
 | `BASE-D103` | Homebrew unavailable for prerequisite profile checks |
 | `BASE-D104` | Prerequisite profile Homebrew package presence and freshness |
-| `BASE-D105` | GitHub CLI availability |
+| `BASE-D105` | GitHub CLI executable availability for authentication checks |
 | `BASE-D106` | GitHub CLI authentication status |
 | `BASE-D107` | AI developer tool availability and version status |
 | `BASE-D108` | Multipass availability and version status for the `linux-lab` profile |

@@ -34,7 +34,7 @@ Base gives that workspace a common, inspectable operating contract.
 Base is a local operating contract for deterministic readiness and handoff
 across independent Git repositories.
 
-It makes the repo set understandable, locally ready, explicitly trusted,
+It makes the repository set understandable, locally ready, explicitly trusted,
 onboardable, and transferable. Its durable loop is:
 
 ```text

@@ -56,9 +56,13 @@ across every repository and external tool.
 The execution contract (`base_manifest.yaml`, `basectl`, `base-wrapper`, and
 declared project commands) enables that outcome. Repository/GitHub/release
 workflow packs and environment/IDE/container/AI adapters support it without
-becoming equal product pillars. Ubuntu/Debian source-checkout runtime and
-apt-backed setup support are implemented, while broader Linux distribution
-support remains deliberately narrow and Windows is not currently in scope.
+becoming equal product pillars.
+
+### Current Platform Contract
+
+Ubuntu/Debian source-checkout runtime and apt-backed setup support are
+implemented. Broader Linux distribution support remains deliberately narrow and
+Windows is not currently in scope.
 
 The local workspace agent brief now summarizes repository readiness for a
 handoff, while onboarding, diagnostics, privacy-conscious history reports, and
@@ -194,7 +198,7 @@ The best adoption path is evidence-driven:
 
 Base can become much larger, but the larger possibility is not "put every tool
 inside Base." The larger possibility is to make readiness and operating context
-portable within a project, from a single repository to a repo set, without
+portable within a project, from a single repository to a repository set, without
 absorbing the tools that prepare, build, or host those repositories.
 
 ### 2026-07-30 / Single-repository positioning
@@ -215,9 +219,6 @@ The review also sharpened the near-term adoption risks.
 
 Immediate action items:
 
-- Ubuntu/Debian runtime and apt-backed setup support have since shipped. The
-  remaining expansion boundary is broader Linux-family, WSL, or Windows support
-  and external adoption evidence; do not generalize beyond the tested contract.
 - Semantic onboarding and transferable readiness/handoff evidence are the
   strongest moat candidate. Local workspace manifests and explicit canonical
   manifest sync support that outcome, but repository-set materialization alone
@@ -280,8 +281,6 @@ not a rewrite of historical releases.
 Remaining risks should stay issue-backed rather than becoming a parallel
 backlog here:
 
-- The first Linux target in #562 has since shipped for Ubuntu/Debian. Broader
-  Linux families, WSL, and Windows still require separate support contracts.
 - Dev Container and Nix bridges should remain export/bridge work from Base
   manifests, not a replacement for those ecosystems; this is tracked in #876.
 - A local dashboard is still plausible, but should follow durable observability
@@ -294,14 +293,21 @@ backlog here:
 
 Maintainability is the refreshed watchlist. The current file-size pressure is
 not in the reusable Bash standard library anymore; #873 documents why
-single-file shell-library standards remain intentional. The more important
-ownership pressure is in command orchestration files: `repo.sh` is roughly
-3,400 lines, `setup_common.sh` is roughly 2,170 lines, `repo.bats` is roughly
-1,730 lines, and `gh.bats`, `base_projects/engine.py`, and
-`base_github_projects/engine.py` are all around the 1,000-line mark. The right
-response is not an abstract split-everything campaign. Reduce ownership where a
-stable subdomain is visible, keep tests near behavior, and use #929 for the
-known `setup_common.sh` ownership-reduction path.
+single-file shell-library standards remain intentional. Keep the watchlist
+live instead of hardcoding line counts; inspect the current ownership pressure
+with:
+
+```bash
+wc -l \
+  cli/bash/commands/basectl/subcommands/repo.sh \
+  cli/bash/commands/basectl/subcommands/setup_common.sh \
+  cli/bash/commands/basectl/tests/repo.bats \
+  cli/bash/commands/basectl/tests/gh.bats
+```
+
+The right response is not an abstract split-everything campaign. Reduce
+ownership where a stable subdomain is visible, keep tests near behavior, and
+use #929 for the known `setup_common.sh` ownership-reduction path.
 
 ### 2026-06-25 / 1.2.0 Product Review Delta
 
@@ -314,7 +320,7 @@ The strongest shipped signal is that Base now has a more durable review and
 workflow loop around itself:
 
 - `basectl workspace init` makes a workspace repository the entry point for
-  cloning and materializing the declared repo set.
+  cloning and materializing the declared repository set.
 - `basectl prompt list` and `basectl prompt product-self-review` make
   repo-owned prompts inspectable and repeatable instead of private chat-only
   process.
@@ -341,8 +347,6 @@ organizational-impact assessment.
 
 Current watchlist for the next release line:
 
-- Ubuntu/Debian support from #562 has since shipped; keep broader Linux, WSL,
-  and Windows claims separate and evidence-backed.
 - Command history should earn user-facing reports before a local dashboard
   becomes product surface.
 - Artifact support should stay Base-managed and manifest-explicit until real
@@ -393,9 +397,6 @@ Current watchlist for the next release line:
 - Keep the clean macOS install checklist honest by automating safe repeatable
   steps where possible and explicitly preserving manual-only boundaries where
   host mutation or real Homebrew installation is required.
-- Ubuntu/Debian support from #562 has since shipped. Treat broader Linux
-  families, WSL, and Windows as separate expansion decisions with their own
-  evidence and support contracts.
 - Treat remaining ownership pressure in large shell command modules, Project
   engines, and broad BATS files as issue-backed maintainability work rather
   than as a reason to reposition the product.
@@ -436,9 +437,6 @@ organizational-impact assessment.
 
 Current watchlist for the next release line:
 
-- Keep Ubuntu/Debian claims precise: source-checkout runtime and apt-backed setup
-  are real, but broader Linux families, WSL, and Windows still need separate
-  support contracts before public claims expand.
 - Use the shipped privacy-conscious history report as handoff evidence while
   keeping the broader #1562 bundle local, redacted, and explicit about missing
   data.
@@ -539,8 +537,6 @@ Watchlist recorded at the 1.7.0 review:
   explicitly separate until the latter is actually shipped.
 - Validate the readiness and handoff wedge with external polyrepo design
   partners before expanding Base's feature surface (#1616).
-- Keep Ubuntu/Debian claims precise and treat broader Linux, WSL, and Windows as
-  separate support-contract decisions.
 - Continue issue-backed ownership reduction and preserve adapter boundaries as
   new IDE, container, AI, and environment requests arrive.
 
@@ -590,8 +586,6 @@ Current watchlist for the next release line:
   #1562 explicitly separate until the latter is actually shipped.
 - Validate the readiness and handoff wedge with external polyrepo design
   partners before expanding Base's feature surface (#1616).
-- Keep Ubuntu/Debian claims precise and treat broader Linux, WSL, and Windows
-  as separate support-contract decisions.
 - Continue issue-backed ownership reduction and preserve adapter boundaries as
   new IDE, container, AI, environment, and repository-workflow requests arrive.
 

@@ -19,7 +19,7 @@ For execution tracking, use GitHub Issues and the workflow in
 ## Product Thesis
 
 Base is a local operating contract for developers and platform engineers who
-work across multiple independent Git repositories. It should make the repo set
+work across multiple independent Git repositories. It should make the repository set
 understandable, locally ready, explicitly trusted, onboardable, and transferable
 without forcing a monorepo or taking project behavior away from its owning
 repository.
@@ -217,19 +217,8 @@ Base should help a target user answer one question at each step:
 
 ## Non-Goals
 
-Base should not become:
-
-- a general tool version manager;
-- an automatic directory-based environment loader;
-- a full dotfile manager;
-- a generic task runner;
-- a generic multi-repository checkout, sync, or command fan-out manager;
-- a full reproducible package manager or environment solver;
-- a local services platform;
-- a container runtime;
-- a hosted agent runtime, session-transfer service, or provider upload system;
-- a replacement for GitHub CLI, IDEs, Homebrew, `mise`, uv, Docker, Nix,
-  Devbox, Dev Containers, `just`, Taskfile, or project-owned build systems.
+Base's canonical non-goals are maintained in
+[What Base Is Not](tool-boundaries.md#what-base-is-not).
 
 Base can learn from and integrate with those tools. It should not absorb their
 complete domains.
@@ -286,7 +275,7 @@ Use technical docs for implementation detail:
   behavior.
 - [Runtime Environment](runtime-environment.md) owns Base-managed variables and
   mutability rules.
-- [Workspace Manifest](workspace-manifest.md) owns the team-shared repo-set
+- [Workspace Manifest](workspace-manifest.md) owns the team-shared repository set
   contract.
 - [Python Manifest Section](python-manifest.md) owns Python and uv manifest
   behavior.