basefoundry · codeforester · Jul 1, 2026 · Jul 1, 2026
@@ -1275,7 +1275,7 @@ contract and mutability policy.
 
 `~/.baserc` must not set Base-owned runtime or profile variables such as
 `BASE_HOME`, `BASE_BIN_DIR`, `BASE_LIB_DIR`, `BASE_BASH_LIBS_DIR`,
-`BASE_BASH_LIBS_SOURCE`, `BASE_OS`, `BASE_SHELL`,
+`BASE_BASH_LIBS_SOURCE`, `BASE_OS`, `BASE_PLATFORM`, `BASE_SHELL`,
 `BASE_PLATFORM_TOOLS_HOME`, `BASE_PLATFORM_TOOLS_BIN_DIR`,
 `BASE_PROFILE_VERSION`, `BASE_ENABLE_BASH_DEFAULTS`, or
 `BASE_ENABLE_ZSH_DEFAULTS`. Base startup snippets reject and restore those

@@ -110,7 +110,8 @@ call Base's Python layer.
    - constants
    - globals intentionally shared across scripts, sourced modules, or subshells
 4. Use a common prefix for exported environment variables whenever practical.
-   For example: `BASE_HOME`, `BASE_HOST`, `BASE_OS`, `BASE_BASH_LIB_DIR`.
+   For example: `BASE_HOME`, `BASE_HOST`, `BASE_OS`, `BASE_PLATFORM`,
+   `BASE_BASH_LIB_DIR`.
 5. Do not use all-uppercase names for ordinary script-local variables.
 6. Use a leading underscore for private variables and functions, especially in
    libraries or sourced modules where internal names might otherwise collide.
@@ -595,8 +596,8 @@ separate explicit opt-in instead of being added to
 
 `~/.baserc` is user-managed input for simple Base preferences such as
 `BASE_DEBUG=1`. It must not set Base-owned runtime or profile state such as
-`BASE_HOME`, `BASE_BIN_DIR`, `BASE_LIB_DIR`, `BASE_OS`, `BASE_SHELL`,
-`BASE_PROFILE_VERSION`, `BASE_ENABLE_BASH_DEFAULTS`, or
+`BASE_HOME`, `BASE_BIN_DIR`, `BASE_LIB_DIR`, `BASE_OS`, `BASE_PLATFORM`,
+`BASE_SHELL`, `BASE_PROFILE_VERSION`, `BASE_ENABLE_BASH_DEFAULTS`, or
 `BASE_ENABLE_ZSH_DEFAULTS`. Shell startup code that sources `~/.baserc` should
 reject attempts to change those variables and restore the previous values.
 

@@ -16,7 +16,7 @@
 #     - validate that the runtime is Bash 4.2 or newer
 #     - derive or validate BASE_HOME
 #     - export the BASE_* paths that downstream scripts may rely on
-#     - export BASE_OS and BASE_HOST runtime metadata
+#     - export BASE_OS, BASE_PLATFORM, and BASE_HOST runtime metadata
 #     - resolve and source the reusable Bash standard library
 #     - add BASE_BIN_DIR to PATH
 #     - provide import_base_lib for convention-based Base Bash library imports
@@ -75,6 +75,32 @@ base_init_require_bash() {
     fi
 }
 
+base_init_linux_os_release_path() {
+    printf '%s\n' "${BASE_INIT_TEST_OS_RELEASE_PATH:-/etc/os-release}"
+}
+
+base_init_detect_linux_platform() {
+    local id id_like os_release_path
+    local ID="" ID_LIKE=""
+
+    os_release_path="$(base_init_linux_os_release_path)" || return 1
+    if [[ -r "$os_release_path" ]]; then
+        # shellcheck source=/dev/null
+        source "$os_release_path"
+    fi
+
+    id="${ID,,}"
+    id_like="${ID_LIKE,,}"
+    case " $id $id_like " in
+        *" ubuntu "*|*" debian "*)
+            printf 'linux-debian\n'
+            ;;
+        *)
+            printf 'linux-unknown\n'
+            ;;
+    esac
+}
+
 base_init_resolve_home() {
     local source_path
     local source_dir
@@ -166,7 +192,7 @@ base_init_set_bash_libs_contract() {
 }
 
 base_init_export_contract() {
-    local base_home base_os base_host uname_os
+    local base_home base_os base_platform base_host uname_os
 
     base_home="$(base_init_resolve_home)" || return 1
     uname_os="$(uname -s)" || {
@@ -180,12 +206,15 @@ base_init_export_contract() {
     case "$uname_os" in
         Darwin)
             base_os=macos
+            base_platform=macos
             ;;
         Linux)
             base_os=linux
+            base_platform="$(base_init_detect_linux_platform)" || return 1
             ;;
         *)
             base_os="$(printf '%s\n' "$uname_os" | tr '[:upper:]' '[:lower:]')"
+            base_platform="$base_os"
             ;;
     esac
     base_host="$(hostname -s)" || {
@@ -207,12 +236,13 @@ base_init_export_contract() {
     base_init_set_bash_libs_contract || return 1
     BASE_SHELL_DIR="$BASE_LIB_DIR/shell"
     BASE_OS="$base_os"
+    BASE_PLATFORM="$base_platform"
     BASE_HOST="$base_host"
     BASE_SHELL="${BASE_SHELL:-bash}"
     export BASE_HOME BASE_BIN_DIR BASE_CLI_DIR BASE_BASH_DIR BASE_BASH_COMMANDS_DIR
-    export BASE_LIB_DIR BASE_BASH_LIB_DIR BASE_BASH_LIBS_DIR BASE_BASH_LIBS_SOURCE BASE_SHELL_DIR BASE_OS BASE_HOST BASE_SHELL
+    export BASE_LIB_DIR BASE_BASH_LIB_DIR BASE_BASH_LIBS_DIR BASE_BASH_LIBS_SOURCE BASE_SHELL_DIR BASE_OS BASE_PLATFORM BASE_HOST BASE_SHELL
     readonly BASE_HOME BASE_BIN_DIR BASE_CLI_DIR BASE_BASH_DIR BASE_BASH_COMMANDS_DIR
-    readonly BASE_LIB_DIR BASE_BASH_LIB_DIR BASE_BASH_LIBS_DIR BASE_BASH_LIBS_SOURCE BASE_SHELL_DIR BASE_OS BASE_HOST BASE_SHELL
+    readonly BASE_LIB_DIR BASE_BASH_LIB_DIR BASE_BASH_LIBS_DIR BASE_BASH_LIBS_SOURCE BASE_SHELL_DIR BASE_OS BASE_PLATFORM BASE_HOST BASE_SHELL
 }
 
 base_init_source_stdlib() {

@@ -13,6 +13,7 @@ base_test_unset_env=(
     -u BASE_BASH_LIBS_SOURCE
     -u BASE_SHELL_DIR
     -u BASE_OS
+    -u BASE_PLATFORM
     -u BASE_HOST
     -u BASE_SHELL
     -u BASE_PLATFORM_TOOLS_HOME
@@ -25,6 +26,7 @@ base_test_unset_env=(
     -u BASE_BASH_COMMAND_DIR
     -u BASE_BASH_COMMAND_SCRIPT
     -u BASE_BASH_BOOTSTRAP_SOURCE
+    -u BASE_INIT_TEST_OS_RELEASE_PATH
     -u BASE_PROJECT
     -u BASE_PROJECT_ROOT
     -u BASE_PROJECT_MANIFEST

@@ -22,7 +22,7 @@ EOF
     run_base_command update-profile
     [ "$status" -eq 0 ]
 
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         bash --rcfile "$TEST_HOME/.bashrc" -i -c '\

@@ -201,7 +201,7 @@ EOF
     run_base_command update-profile
     [ "$status" -eq 0 ]
 
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         bash --rcfile "$TEST_HOME/.bashrc" -i -c 'command -v basectl; printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -363,7 +363,7 @@ EOF
     run_base_command update-profile
     [ "$status" -eq 0 ]
 
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM \
         HOME="$TEST_HOME" \
         BASE_DEBUG=1 \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
@@ -381,7 +381,7 @@ EOF
     [ "$status" -eq 0 ]
 
     printf '%s\n' 'BASE_DEBUG=1' > "$TEST_HOME/.baserc"
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_DEBUG \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u BASE_DEBUG \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         bash --rcfile "$TEST_HOME/.bashrc" -i -c 'command -v basectl >/dev/null'
@@ -397,7 +397,7 @@ EOF
     [ "$status" -eq 0 ]
 
     printf '%s\n' 'BASE_DEBUG=1' > "$TEST_HOME/.baserc"
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_DEBUG \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u BASE_DEBUG \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         bash --norc -i -c 'source "$HOME/.bash_profile"; command -v basectl; printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -418,7 +418,7 @@ EOF
     [ "$status" -eq 0 ]
 
     printf '%s\n' 'BASE_DEBUG=1' > "$TEST_HOME/.baserc"
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_DEBUG \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u BASE_DEBUG \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         zsh -f -i -c 'source "$HOME/.zprofile"; source "$HOME/.zshrc"; command -v basectl; printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -437,7 +437,7 @@ EOF
     [ "$status" -eq 0 ]
 
     printf '%s\n' 'BASE_HOME=/tmp/not-base' > "$TEST_HOME/.baserc"
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_DEBUG \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u BASE_DEBUG \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         bash --rcfile "$TEST_HOME/.bashrc" -i -c 'printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -461,6 +461,7 @@ EOF
     [[ "$output" == *"BASE_BASH_COMMAND_SCRIPT"* ]]
     [[ "$output" == *"BASE_PROJECT_ROOT"* ]]
     [[ "$output" == *"BASE_PROJECT_VENV_DIR"* ]]
+    [[ "$output" == *"BASE_PLATFORM"* ]]
     [[ "$output" == *"BASE_PLATFORM_TOOLS_HOME"* ]]
     [[ "$output" == *"BASE_PLATFORM_TOOLS_BIN_DIR"* ]]
     [[ "$output" != *"BASE_ARCH"* ]]
@@ -472,7 +473,7 @@ EOF
     run_base_command update-profile
     [ "$status" -eq 0 ]
 
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         zsh -f -i -c 'source "$HOME/.zshrc"; command -v basectl; printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -537,7 +538,7 @@ EOF
     [ "$status" -eq 0 ]
 
     printf '%s\n' 'BASE_HOME=/tmp/not-base' > "$TEST_HOME/.baserc"
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_DEBUG \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u BASE_DEBUG \
         HOME="$TEST_HOME" \
         PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
         zsh -f -i -c 'source "$HOME/.zshrc"; printf "BASE_HOME=%s\n" "${BASE_HOME-unset}"'
@@ -570,7 +571,7 @@ EOF
     [[ "$(cat "$TEST_HOME/.bashrc")" != *"defaults.sh"* ]]
     [[ "$(cat "$TEST_HOME/.zshrc")" != *"defaults.sh"* ]]
 
-    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u EDITOR -u VISUAL -u EXINIT \
+    run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u EDITOR -u VISUAL -u EXINIT \
         -u HISTCONTROL -u HISTSIZE -u HISTFILESIZE \
         -u PAGER -u LESS -u MANPAGER -u GIT_PAGER \
         HOME="$TEST_HOME" \
@@ -600,7 +601,7 @@ EOF
     [[ "$output" == *'PS1=\[\033[0;35m\]\T \h\[\033[0;33m\] $(_base_bash_defaults_git_prompt)\w\[\033[00m\]: '* ]]
 
     if command -v zsh >/dev/null 2>&1; then
-        run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u EDITOR -u VISUAL -u EXINIT \
+        run env -u BASE_HOME -u BASE_HOST -u BASE_OS -u BASE_PLATFORM -u EDITOR -u VISUAL -u EXINIT \
             -u HISTFILE -u HISTSIZE -u SAVEHIST \
             -u PAGER -u LESS -u MANPAGER -u GIT_PAGER \
             HOME="$TEST_HOME" \

@@ -199,7 +199,7 @@ directory.
 Contains:
 - exported Base path contract such as `BASE_HOME`, `BASE_BIN_DIR`,
   `BASE_BASH_LIB_DIR`, `BASE_BASH_LIBS_DIR`, and `BASE_BASH_LIBS_SOURCE`
-- OS and host metadata such as `BASE_OS` and `BASE_HOST`
+- OS and host metadata such as `BASE_OS`, `BASE_PLATFORM`, and `BASE_HOST`
 - Base's Bash standard library
 - `import_base_lib` for convention-based Base Bash library imports from the
   resolved reusable Bash library root

@@ -230,7 +230,7 @@ has decided what should run.
 - exported Base environment variables such as `BASE_HOME`, `BASE_BIN_DIR`,
   `BASE_BASH_COMMANDS_DIR`, `BASE_BASH_LIB_DIR`, `BASE_BASH_LIBS_DIR`, and
   `BASE_BASH_LIBS_SOURCE`
-- OS and host metadata such as `BASE_OS` and `BASE_HOST`
+- OS and host metadata such as `BASE_OS`, `BASE_PLATFORM`, and `BASE_HOST`
 - the reusable Bash standard library, resolved from `base-bash-libs`
 - `import_base_lib`, the convention-based helper for sourcing Base Bash
   libraries from the resolved reusable root

@@ -18,7 +18,9 @@ Full bootstrap support can come after runtime support is stable.
 
 ## Platform Detection
 
-Use `/etc/os-release` for Linux distribution detection:
+Use `/etc/os-release` for Linux distribution detection and expose the result
+through `BASE_PLATFORM`. Keep `BASE_OS` coarse: `BASE_OS=linux` on Linux, with
+`BASE_PLATFORM` carrying the supported distribution family.
 
 ```bash
 if [[ -r /etc/os-release ]]; then
@@ -36,6 +38,11 @@ The setup layer should classify platforms into:
 Unsupported platforms should fail with explicit guidance rather than falling
 through to macOS assumptions.
 
+Do not add public `BASE_DISTRO_ID` or `BASE_ARCH` until diagnostics or package
+selection need them. Distribution ID and CPU architecture are separate axes:
+`BASE_PLATFORM` answers "which supported platform family is this?", while a
+future `BASE_ARCH` would answer "which binary/package architecture is this?".
+
 ## Package Manager Mapping
 
 Initial Ubuntu/Debian mappings:

@@ -49,7 +49,7 @@ boundary.
 
 `~/.baserc` may set user knobs such as `BASE_DEBUG`. It must not set Base-owned
 runtime or profile variables such as `BASE_HOME`, `BASE_BIN_DIR`, `BASE_LIB_DIR`,
-`BASE_OS`, `BASE_HOST`, `BASE_SHELL`, `BASE_BASH_LIBS_DIR`,
+`BASE_OS`, `BASE_PLATFORM`, `BASE_HOST`, `BASE_SHELL`, `BASE_BASH_LIBS_DIR`,
 `BASE_BASH_LIBS_SOURCE`,
 `BASE_PLATFORM_TOOLS_HOME`, `BASE_PLATFORM_TOOLS_BIN_DIR`, `BASE_PROFILE_VERSION`,
 `BASE_ENABLE_BASH_DEFAULTS`, or `BASE_ENABLE_ZSH_DEFAULTS`. It must also not
@@ -74,6 +74,7 @@ explicit Bash script, or starts a Base runtime Bash shell.
 | `BASE_BASH_LIBS_SOURCE` | Base | Source category for `BASE_BASH_LIBS_DIR`: `explicit`, `sibling`, or `homebrew`. `basectl check` and `basectl doctor` use this to report how Base is consuming external reusable Bash libraries. | Do not set. Readonly after `base_init.sh`. |
 | `BASE_SHELL_DIR` | Base | `$BASE_HOME/lib/shell`. Root for managed shell startup snippets and completions. | Do not set. Readonly after `base_init.sh`. |
 | `BASE_OS` | Base | Normalized host OS metadata such as `macos` or `linux`. Used by runtime decisions and diagnostics. | Do not set. Readonly after `base_init.sh`. |
+| `BASE_PLATFORM` | Base | Normalized runtime platform metadata such as `macos`, `linux-debian`, or `linux-unknown`. Used when Base needs distribution-family behavior without overloading `BASE_OS`. | Do not set. Readonly after `base_init.sh`. |
 | `BASE_HOST` | Base | Short host name from `hostname -s`. Used by runtime metadata and prompts. | Do not set. Readonly after `base_init.sh`. |
 | `BASE_SHELL` | Base | Legacy runtime marker. Plain `base_init.sh` defaults it to `bash`; Base runtime shells seed it as `1` before `base_init.sh`. New code should avoid adding new meanings to it. | Do not set in user config. Readonly after `base_init.sh`. |
 

@@ -70,7 +70,8 @@ Markers look like:
 **Layer 2 — Base runtime** (`base_init.sh`, sourced on every `basectl` invocation)
 
 Exports `BASE_HOME`, `BASE_BIN_DIR`, `BASE_BASH_LIB_DIR`,
-`BASE_BASH_LIBS_DIR`, `BASE_BASH_LIBS_SOURCE`, `BASE_OS`, `BASE_HOST`, and
+`BASE_BASH_LIBS_DIR`, `BASE_BASH_LIBS_SOURCE`, `BASE_OS`, `BASE_PLATFORM`,
+`BASE_HOST`, and
 `BASE_SHELL`. Loads the Bash standard library from the resolved reusable
 library root. Sets up
 `import_base_lib` for convention-based library imports from that reusable root.

@@ -42,6 +42,7 @@ BASE_LIB_DIR
 BASE_BASH_LIB_DIR
 BASE_SHELL_DIR
 BASE_OS
+BASE_PLATFORM
 BASE_HOST
 BASE_SHELL
 BASE_PLATFORM_TOOLS_HOME

@@ -37,6 +37,7 @@ BASE_LIB_DIR
 BASE_BASH_LIB_DIR
 BASE_SHELL_DIR
 BASE_OS
+BASE_PLATFORM
 BASE_HOST
 BASE_SHELL
 BASE_PLATFORM_TOOLS_HOME