Update sage -b to use ninja and deprecate sage -br

src/bin/sage

@@ -191,7 +191,15 @@ fi
 # build/bin/sage-site. See #29111; but OTOH #34627.
 
 build_sage() {
-    ( cd "$SAGE_ROOT" && make sagelib-no-deps ) || exit $?
+    # Check for the expected editable meson build directory
+    if [ -f "build/build.ninja" ]; then
+        echo "Building Sage with ninja..."
+        ( cd "$SAGE_ROOT" && ninja -C build ) || exit $?
+    else
+        echo "Error: 'sage -b' is for editable meson-based developer builds." >&2
+        echo "Please use 'make' or 'meson' directly for other builds." >&2
+        exit 1
+    fi
 }
 
 # Check for '-i' etc. before sourcing sage-env: running "make"
@@ -212,8 +220,10 @@ case "$1" in
         exit 0
         ;;
     -br|--br)
+        echo "Warning: 'sage -br' is deprecated." >&2
+        echo "In an editable install, just run './sage' to use the latest built code." >&2
         build_sage
-        shift; set -- -r "$@"  # delegate to handling of "-r" below, after sourcing sage-env
+        shift; set -- -r "$@"
         ;;
     -bn|--build-and-notebook)
         build_sage

src/doc/en/reference/repl/startup.rst

@@ -42,3 +42,22 @@ in this file.
 
 The default location of this file can be changed using the
 environment variable :envvar:`SAGE_STARTUP_FILE`.
+
+.. _sage_subcommands:
+
+Sage Subcommands
+----------------
+
+The ``sage`` script can be used to invoke several subcommands, including:
+
+* ``sage -b``: Rebuilds the Sage library. This is intended for developer-only
+  editable Meson builds. It runs ``ninja -C build`` to recompile. If a
+  non-Meson build is detected, it will error out with a message.
+
+* ``sage -br``: **Deprecated.** This command is no longer supported and
+  will be removed in a future release. Use ``sage -b`` to build and
+  ``./sage`` to run.
+
+* ``sage --python``: Runs the Python interpreter included with Sage.
+
+* ``sage -i <package>``: Installs a Sage package.