From 340d9cdd372398e4dcba02e49fe27f7631558cdf Mon Sep 17 00:00:00 2001
From: Jon B <jon@jonbogaty.com>
Date: Fri, 10 Apr 2026 11:14:27 -0500
Subject: [PATCH] docs: clearly document breaking changes and migration paths
 for pre-v1 setups

---
 CHANGELOG.md      | 20 +++++++++++++++++++-
 README.md         | 17 +++++++++++++++++
 docs/INSTALLER.md | 12 ++++++++++++
 3 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42eca88..fee6c59 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,9 +8,27 @@ status: current
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### ⚠️ BREAKING CHANGES
+- **Consolidated Installation Prefix**: The environment is now strictly managed under a single prefix (`~/.get-bashed/` by default). Runtime modules have moved from `~/.bashrc.d/` to `~/.get-bashed/bashrc.d/`, and local secrets have moved from `~/.secrets.d/` to `~/.get-bashed/secrets.d/`. The installer includes automatic migration logic, but users are strongly advised to back up custom modules and secrets before upgrading.
+- **Dotfile Symlinking Logic**: Dotfiles are no longer automatically copied to the home directory. Instead, they are copied to the managed prefix and, when `--link-dotfiles` is invoked, they are symlinked *from* the home directory *to* the managed prefix.
+
+### Added
+- Comprehensive Sphinx-based documentation published to GitHub Pages.
+- Native `globstar` enablement for recursive file matching in Bash.
+- Automatic integration of `eza` for modernized `ls` aliases when available.
+- New `mkcd` command helper in `90-functions.sh`.
+- Security enforcement: `secrets.d` and `.ssh/agent.sock` are now guaranteed to generate with restrictive (`700`/`600`) permissions to prevent exposing local credentials to other users on the system.
+
+### Changed
+- Massive performance optimization of interactive startup by eliminating multiple `$(brew --prefix <pkg>)` subshells in `.bash_profile` and `.bashrc`.
+- Redesigned `install.bash` to safely escape injected variables like `--name` and `--email`, preventing unintended command execution.
+- Redesigned `get_bashed_component` to rely on `$BASH_SOURCE` physical paths rather than trusting the `$GET_BASHED_HOME` environment variable.
+
 <!-- Release Please inserts release sections above this line. -->
 
 ## [Unreleased]
diff --git a/README.md b/README.md
index f979819..9bcfc87 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,23 @@ status: current
 
 A modular, portable Bash environment you can install on any machine. get-bashed gives you clean shell defaults, ordered runtime modules, a centralized tool installer, and reproducible configuration — without touching anything you do not explicitly ask it to touch.
 
+## ⚠️ Upgrading & Breaking Changes
+
+**BREAKING CHANGE:** As of the latest release, get-bashed consolidates all runtime modules, local secrets, and dotfiles into a single managed prefix (default: `~/.get-bashed/`).
+
+If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix.
+
+**Before upgrading, it is highly recommended to back up your custom modules:**
+```bash
+cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true
+cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true
+```
+
+To upgrade your environment, simply re-run the installer over your existing setup:
+```bash
+./install.sh --auto
+```
+
 ## What it is
 
 - Ordered `bashrc.d/` modules loaded by `bashrc` at shell startup.
diff --git a/docs/INSTALLER.md b/docs/INSTALLER.md
index 46e08ce..1e4c0a1 100644
--- a/docs/INSTALLER.md
+++ b/docs/INSTALLER.md
@@ -2,6 +2,18 @@
 
 Installer and configurator for get-bashed.
 
+## ⚠️ Upgrading & Breaking Changes
+
+**BREAKING CHANGE:** As of the latest release, get-bashed consolidates all runtime modules, local secrets, and dotfiles into a single managed prefix (default: `~/.get-bashed/`).
+
+If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix.
+
+**Before upgrading, it is highly recommended to back up your custom modules:**
+```bash
+cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true
+cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true
+```
+
 ## Overview
 
 Supports non-interactive and interactive installation with profiles,