diff --git a/docs/bootc/deprecation-notice.md b/docs/bootc/deprecation-notice.md
new file mode 100644
index 00000000000..7d5bf0e4bd9
--- /dev/null
+++ b/docs/bootc/deprecation-notice.md
@@ -0,0 +1,52 @@
+---
+title: Deprecation notice — bootc-image-builder
+custom_edit_url: null
+---
+
+# Deprecation notice: bootc-image-builder
+
+The osbuild project is **converging package mode and image mode** into a single, unified image-building experience. As part of that effort, the standalone **bootc-image-builder** container and CLI are being deprecated in favor of the unified **image-builder** CLI.
+
+This document describes the timeline, migration path, and what you need to do.
+
+## Why we're deprecating bootc-image-builder
+
+We are unifying the tooling so that one CLI and one container can build images from both **blueprints** (package mode) and **bootable containers** (image mode). The unified [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) project already supports building from bootc container inputs via `--bootc-ref` and related options, with functional equivalence to what bootc-image-builder provides. Maintaining two separate codebases and containers is no longer necessary; consolidating reduces maintenance and gives users a single entry point for all image-building workflows.
+
+## Timeline and process
+
+### RHEL 9/10 (and current container)
+
+- **Backward compatibility is guaranteed for the full life of RHEL 10.** Existing automation, documentation, and pipelines that run the container with a **bootc-image-builder** entry point remain supported.
+- **Starting in RHEL 9.7/10.2** bootc-image-builder will start only shipping new major versions with each RHEL Y release.  Upstream releases will no longer be backports to the RHEL 10.Y image. 
+- **Starting in RHEL 9.8/10.3**, the RHEL image-building container will be built on **image-builder-cli** (the unified implementation). It will **not** ship the original standalone bootc-image-builder binary. Instead, the container exposes a **bootc-image-builder entry point** that wraps image-builder-cli so that existing `podman run … bootc-image-builder` style invocations keep working without changing flags or workflows.  A new container **image-builder** will be shipped that contains the same binary as bootc-image-builder, but without the compatibility entry point.  Both the **bootc-image-builder** and **image-builder** containers will ship with the same version of image-builder-cli that is available as an rpm in respective RHEL release. 
+- **Before RHEL 9.8/10.3**, the container continues to use the current bootc-image-builder-based implementation. The transition at 10.3 is a swap of the implementation behind the same compatibility surface (entry point and expected behavior).
+
+
+
+### RHEL 11
+
+- **Only the image-builder container and CLI will be shipped.** The **bootc-image-builder** compatibility entry point will no longer be provided.
+- Consumers must complete migration to the image-builder CLI before relying on RHEL 11 or building RHEL 11.
+
+## What you should do
+
+1. **Prefer the image-builder CLI for new work.** Use the [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) documentation and invoke **image-builder** as the container entry point (or install the CLI on the host). From RHEL 10.3 onward, the RHEL container is image-builder-cli-based; the bootc-image-builder entry point exists only for backward compatibility.
+2. **If you use the Podman plugin or other tooling** that invokes bootc-image-builder, plan for a reverse-dependency check and testing with the new image-builder CLI before the RHEL 11 cutover.
+3. **If you rely on the Anaconda ISO image type:** The unified CLI currently supports the Anaconda ISO type, but we plan to **deprecate it, and remove it in RHEL 11** and move to fully container-based installer ISOs (e.g., bootc-installer) in line with Image Mode strategy. Prefer container-based installer flows where possible.
+
+## Repository and archive
+
+Development is moving to the unified [image-builder](https://github.com/osbuild/image-builder-cli) repository. The [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) repository will be **archived** after the migration plan is complete; issues and relevant contributions will be handled in the unified project. We will publish this migration plan on osbuild.org and link to it from repository notices so that existing users and contributors have a single place to reference.
+
+## Summary
+
+![migration-plan](ib-cli-transition.png)
+
+## Questions and feedback
+
+- **Documentation:** [osbuild.org docs](https://www.osbuild.org/docs/)
+- **Discussions:** [GitHub Discussions](https://github.com/orgs/osbuild/discussions)
+- **Matrix:** [#image-builder on fedoraproject.org](https://matrix.to/#/#image-builder:fedoraproject.org)
+
+If you have concerns or need help planning your migration, please reach out through one of the channels above.
diff --git a/docs/bootc/ib-cli-transition.png b/docs/bootc/ib-cli-transition.png
new file mode 100644
index 00000000000..5efe8a08204
Binary files /dev/null and b/docs/bootc/ib-cli-transition.png differ