norman-abramovitz · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026
diff --git a/.codeclimate.yml b/.codeclimate.yml
diff --git a/.github/workflows/stb_tests.yml b/.github/workflows/stb_tests.yml
@@ -80,15 +80,15 @@ jobs:
       # The integration suite runs in real browsers (vite.config.ts defines
       # integration-chromium/firefox/webkit projects); CI has no browser
       # binaries by default. NOTE: installs all three to keep CI == local
-      # `npm test`; narrow to chromium if the gate gets slow.
+      # `bun run test`; narrow to chromium if the gate gets slow.
       - name: Install Playwright browsers
-        run: npx playwright install --with-deps
+        run: bun run playwright install --with-deps
 
       - name: Typecheck
-        run: npm run typecheck
+        run: bun run typecheck
 
       - name: Lint
-        run: npm run lint
+        run: bun run lint
 
       - name: Unit + integration tests
-        run: npm test
+        run: bun run test
diff --git a/Makefile b/Makefile
@@ -87,7 +87,7 @@ include version.mk
 # Stratos-specific build metadata and stamps — the per-repo config the
 # vendorable core deliberately excludes.
 $(_HIDE)BUILD_NODE_VERSION := $(shell node --version 2>/dev/null || echo "unknown")
-$(_HIDE)BUILD_TS_VERSION   := $(shell npx tsc --version 2>/dev/null | awk '{print $$2}' || echo "unknown")
+$(_HIDE)BUILD_TS_VERSION   := $(shell bun run tsc --version 2>/dev/null | awk '{print $$2}' || echo "unknown")
 $(_HIDE)BUILD_BUN_VERSION  := $(shell bun --version 2>/dev/null || echo "unknown")
 
 # Lazy (=) so the backend binary's baked-in version reflects the post-bump
@@ -622,7 +622,7 @@ define test.e2e
 			$(if $(PR),--pr $(PR) )$(call _e2e_toggle,dry-run,$(DRYRUN)); \
 	else \
 		echo "Running Playwright E2E tests..."; \
-		$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )npx playwright test \
+		$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )bun run playwright test \
 			$(call _e2e_browsers,$(E2E_BROWSERS)) \
 			$(call _e2e_flag,trace,$(E2E_TRACE)) \
 			$(call _e2e_toggle,list,$(DRYRUN)); \
@@ -727,7 +727,7 @@ $(call register, check, coverage, $($(_HIDE)BUILD_INFO_TS))
 define check.e2e
 	$(_ensure_host_backend)
 	@echo "Running Playwright E2E core tests..."
-	@$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )npx playwright test e2e/tests/core/ \
+	@$(if $(E2E_VIDEO),E2E_VIDEO=$(E2E_VIDEO) )$(if $(E2E_SCREENSHOTS),E2E_SCREENSHOTS=$(E2E_SCREENSHOTS) )bun run playwright test e2e/tests/core/ \
 		$(call _e2e_browsers,$(E2E_BROWSERS)) \
 		$(call _e2e_flag,trace,$(E2E_TRACE)) \
 		$(call _e2e_toggle,list,$(DRYRUN))

diff --git a/README.md b/README.md
@@ -34,7 +34,7 @@ Please visit our new [documentation site](https://stratos.app/). There you can d
     1. [Docker](https://stratos.app/docs/deploy/all-in-one), as a single container deploying all components.
 1. Configuring advanced features such as [Single Sign On](https://stratos.app/docs/advanced/sso) and Cloud Foundry '[invite to org](https://stratos.app/docs/advanced/invite-user-guide)'.
 1. Guides for [developers](https://stratos.app/docs/developer/introduction).
-1. How to [extend](https://stratos.app/docs/extensions/introduction) Stratos [functionality](https://stratos.app/docs/extensions/frontend) and apply a custom [theme](https://stratos.app/docs/extensions/theming).
+1. How to [extend](https://stratos.app/docs/extensions/introduction) Stratos [functionality](https://stratos.app/docs/extensions/frontend) and apply a custom [theme](https://stratos.app/docs/theming-architecture).
 
 ## Developer Workflow
 
@@ -50,87 +50,41 @@ These are taken from `engines` in `package.json` and the `go` directive in
 
 ### First-Time Setup
 
-On a fresh checkout, run the bootstrap script **once** to initialize the development environment:
-
 ```bash
 git clone https://github.com/cloudfoundry/stratos.git
 cd stratos
-
-# One-time bootstrap (builds required infrastructure)
-./bootstrap
-# OR
-make bootstrap
-# OR
-bun run bootstrap
-
-# Install dependencies
-bun install
-
-# Start development server
-make dev-frontend
+make install          # bun install; its postinstall step builds the devkit
 ```
 
-**What bootstrap does:**
-
-1. Verifies prerequisites (Node.js, Bun, Go)
-2. Builds the devkit package (required by Angular CLI)
-3. Generates extension module imports
-4. Creates development proxy configuration
-5. Stamps `build-info.ts` so vitest can run without a full build
-6. Cleans up workspace
+The backend needs `src/jetstream/config.properties` with an encryption key and
+a login method before its first start. The
+[contributor guide](docs/contributing_guide.md#first-time-setup) has the exact
+steps, including a local `admin` user and the dev TLS certificate.
 
-**Troubleshooting:**
-
-- If `bun install` fails with missing files: Run `make bootstrap` first
-- If builds fail with "File not found" errors: Run `make bootstrap`
-- Bootstrap only needs to run once per checkout
+On a fresh worktree, `./bootstrap` also stamps `build-info.ts` so the unit
+tests can run before the first build.
 
 ### Development Commands
 
-```bash
-# Frontend development server (https://127.0.0.1:5440)
-make dev-frontend
-# OR
-bun run start
-
-# Build for production
-make build              # Both frontend and backend
-make build-frontend     # Frontend only
-make build-backend      # Backend only
-
-# Testing
-bun test                # All frontend tests
-bun run test-frontend:core
-bun run test-frontend:cloud-foundry
-bun run test-backend    # Backend tests
-bun run e2e             # End-to-end tests
-
-# Linting
-bun run lint
-```
-
-### Full Stack Development
-
-Run these in separate terminals:
+Run every command from the repository root. `make help` lists them all.
 
 ```bash
-# Terminal 1: Frontend (port 5440)
-make dev-frontend
-
-# Terminal 2: Backend API (port 5443)
-make dev-backend
-
-# Access at: https://127.0.0.1:5440
+# Development servers, in separate terminals
+make dev backend        # https://localhost:5443
+make dev frontend       # https://localhost:5440
+
+# Build
+make build              # Frontend and every backend platform
+make build frontend     # Frontend only
+make build backend PLATFORM=linux/amd64   # One backend platform
+
+# Tests and checks
+make test frontend      # Unit tests (Vitest)
+make test backend       # Go tests
+make test e2e           # End-to-end tests (Playwright)
+make check gate         # Lint and unit tests, as CI runs them
 ```
 
-For more detailed information, see [CLAUDE.md](CLAUDE.md).
-
-## Acknowledgements
-
-Tested with Browserstack
-
-<a href="https://www.browserstack.com"><img width="240px" src="docs/images/Browserstack-logo.svg" alt="Browserstack"></a>
-
 ## Stratos UI pre-packager
 
 This feature helps in pre-building the
@@ -172,44 +126,16 @@ Note: `sgs` creates security groups the first time, upgrades do not use `sgs`.
 
 ## Packaging
 
-Requires `node`, `go`, and `zip`.
-
-Build and package for all targets (linux/amd64, linux/arm64):
+Build the release packages with:
 
 ```bash
-bin/package
+make build release      # CF zip and GitHub release archives, with SHA256SUMS
+make build release cf   # Only the cf push-ready zip (linux/amd64)
 ```
 
-To skip the build step and package from existing artifacts:
-
-```bash
-bin/package --skip-build
-```
-
-To override the version (default: from `package.json`):
-
-```bash
-VERSION="4.8.1" bin/package
-```
-
-This produces per-target zips in `dist/`:
-
-```text
-dist/stratos-cf-<version>-<os>-<arch>.zip
-```
-
-Deploy with:
-
-```bash
-cf push -f dist/cf-package-<os>-<arch>/manifest.yml \
-  -p dist/stratos-cf-<version>-<os>-<arch>.zip
-```
-
-### NOTE
-
-The original packaging code was based on work from the
-[Orange Cloud Foundry Github Repository](https://github.com/orange-cloudfoundry/stratos-ui-cf-packager/).
-Many thanks to Benjamin & Arthur, we appreciate you both!
+`VERSION=<semver>` overrides the version taken from `package.json`. The CF zip
+is written to `dist/stratos-cf-<version>.zip`; see
+[CF Release Build Process](docs/developer-environment.md#cf-release-build-process).
 
 ## License
 

diff --git a/TESTING.md b/TESTING.md
@@ -155,13 +155,13 @@ Everything else stays in its existing group directory.
 
 **This ordering is enforced only by the tiered runner** (`make test e2e
 TIER=…` / `make test e2e GROUP=…`, which delegates to
-`scripts/e2e-run.mjs`). A bare `npx playwright test` or `make test e2e`
+`scripts/e2e-run.mjs`). A bare `bun run playwright test` or `make test e2e`
 (with no `TIER`/`GROUP` set) runs the plain Playwright test-runner
 directly — `dependent/` is not ordered last and can interleave with the
 parallel pool, reintroducing the blast-radius risk above.
 
 `make check e2e` also bypasses the tiered runner: it scopes directly to
-`npx playwright test e2e/tests/core/`, so it no longer covers the
+`bun run playwright test e2e/tests/core/`, so it no longer covers the
 endpoint lifecycle spec at all — `endpoints.spec.ts` lives in
 `dependent/`, outside that path.
 

diff --git a/angular.json b/angular.json
@@ -15,7 +15,7 @@
             "prebuildScripts": [
               {
                 "name": "Clean symlinks",
-                "script": "node build/clean-symlinks.cjs",
+                "script": "bun build/clean-symlinks.cjs",
                 "phase": 1,
                 "cache": true,
                 "cacheKey": ["src/frontend/packages/**/package.json"],
@@ -24,7 +24,7 @@
               },
               {
                 "name": "Store git metadata",
-                "script": "node build/store-git-metadata.cjs",
+                "script": "bun build/store-git-metadata.cjs",
                 "phase": 1,
                 "cache": true,
                 "cacheKey": [".git/HEAD", ".git/refs/heads/**"],
@@ -33,7 +33,7 @@
               },
               {
                 "name": "Generate custom imports",
-                "script": "node build/extension-generator.mjs",
+                "script": "bun build/extension-generator.mjs",
                 "phase": 2,
                 "cache": true,
                 "cacheKey": ["custom-src/**/*", "src/frontend/packages/core/custom-extensions.json"],
@@ -42,7 +42,7 @@
               },
               {
                 "name": "Prepare backend",
-                "script": "node dist-devkit/src/backend.js",
+                "script": "bun dist-devkit/src/backend.js",
                 "phase": 2,
                 "cache": true,
                 "cacheKey": ["dist-devkit/src/backend.js", "src/jetstream/**/*.go"],

diff --git a/bootstrap b/bootstrap
@@ -91,7 +91,7 @@ if [ ! -f "build/extension-generator.mjs" ]; then
     exit 1
 fi
 
-node build/extension-generator.mjs
+bun build/extension-generator.mjs
 
 if [ -f "src/frontend/packages/core/src/_custom-import.module.ts" ]; then
     print_success "Extension module generated"
@@ -107,7 +107,7 @@ if [ ! -f "build/dev-setup.cjs" ]; then
     exit 1
 fi
 
-node build/dev-setup.cjs
+bun build/dev-setup.cjs
 
 if [ -f "proxy.conf.js" ]; then
     print_success "Development configuration created"

diff --git a/build/ngbuild.sh b/build/ngbuild.sh
@@ -154,7 +154,7 @@ function build_devkit() {
   echo -e "${YELLOW}${BOLD}= Package: @stratosui/devkit${RESET}"
   echo
 
-  npm run build-devkit
+  bun run build-devkit
 
   rm -rf ${STRATOS}/npm_pkg/devkit
   cp -r ${STRATOS}/dist-devkit ${STRATOS}/npm_pkg/devkit

diff --git a/bun.lock b/bun.lock