diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md
deleted file mode 100644
index ef57cc7e..00000000
--- a/MIGRATION_PLAN.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Bearhub Migration Plan
-
-This plan translates the roadmap into concrete engineering tasks with sequencing and acceptance criteria.
-
-## Phase 0: Inventory and Risk Mapping
-
-Tasks:
-- Enumerate remaining `bauh` references:
-  - Python imports
-  - resource paths
-  - UI strings
-  - desktop entries
-  - log prefixes
-- Classify each reference as:
-  - user-facing
-  - internal-only
-  - compatibility-critical
-
-Acceptance:
-- Single tracking list with owner and status for each category.
-
----
-
-## Phase 1: User-Facing Decoupling
-
-Tasks:
-- Replace user-visible `bauh` names with `Bearhub`.
-- Normalize status/notification/error message prefixes.
-- Validate desktop launcher and tray naming.
-
-Acceptance:
-- No user-facing `bauh` in default UI flow.
-- Docs and runtime naming are aligned.
-
----
-
-## Phase 2: Namespace Transition Architecture
-
-Tasks:
-- Define target namespace: `bearhub`.
-- Create temporary compatibility package:
-  - `bauh` imports forward to `bearhub`.
-- Define migration order:
-  1. core modules
-  2. qt/view modules
-  3. gem backends
-  4. tests
-
-Acceptance:
-- Design note committed with:
-  - shim scope
-  - deprecation window
-  - removal criteria
-
----
-
-## Phase 3: Incremental Code Migration
-
-Tasks:
-- Move modules in small batches.
-- Update imports and resource path lookups per batch.
-- Keep compatibility imports passing until final cut.
-- Run smoke tests after each batch:
-  - app start
-  - package search
-  - install
-  - uninstall
-  - update
-
-Acceptance:
-- Main application runs from `bearhub` namespace.
-- Legacy imports still function during transition.
-
----
-
-## Phase 4: Packaging and Distribution Alignment
-
-Tasks:
-- Update `pyproject`/entry points to final namespace.
-- Validate AUR (`bearhub`, `bearhub-git`) install paths and desktop files.
-- Ensure release tags and checksums reflect migrated structure.
-
-Acceptance:
-- Stable and `-git` packages build/install successfully.
-- No stale paths in PKGBUILD or runtime scripts.
-
----
-
-## Phase 5: Compatibility Removal
-
-Tasks:
-- Announce shim deprecation in changelog.
-- Remove `bauh` compatibility layer after deprecation window.
-- Run full regression smoke test and release candidate.
-
-Acceptance:
-- Codebase is fully `bearhub` namespace.
-- No required runtime dependency on legacy `bauh` package structure.
-
----
-
-## Tracking Template
-
-Use this minimal template per task:
-
-- `Task`: short description
-- `Owner`: maintainer
-- `Status`: todo / in-progress / blocked / done
-- `Risk`: low / medium / high
-- `Verification`: command or scenario used to validate
-
----
-
-## First Technical Slice (recommended now)
-
-1. Add `NAMESPACE_MIGRATION.md` with exact module move order.
-2. Implement compatibility shim skeleton (`bauh` -> `bearhub` forwarding).
-3. Migrate one low-risk module group and validate with smoke test.
diff --git a/README.md b/README.md
index 58d69c9e..b57614e0 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,8 @@ Key features
 14. [Code structure](#code)
 15. [Roadmap](#roadmap)
 16. [Contributing](https://github.com/vinifmor/bauh/blob/master/CONTRIBUTING.md)
-17. [Donations](#donations)
+17. [Maintainer docs](#maintainer_docs)
+18. [Donations](#donations)
 
  
 
@@ -196,6 +197,11 @@ Bearhub is currently distributed through source releases and AUR:
 - [bearhub-git](https://aur.archlinux.org/packages/bearhub-git)
 
 
+#### <a name="maintainer_docs">Maintainer docs</a>
+
+- Namespace migration notes: `NAMESPACE_MIGRATION.md`
+
+
 #### <a name="types">Supported types</a>