From 49bd83111d3b8d66dbda3b20ab6c7d4761d2598b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 20 Jun 2026 15:26:03 +0000
Subject: [PATCH 1/2] docs: add UPGRADE.md with breaking changes per release

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GH4h9HXMnBVrAkGtT4tq7W
---
 README.md  |  5 ++++
 UPGRADE.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 UPGRADE.md

diff --git a/README.md b/README.md
index 4917ed44..3527cf72 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,11 @@ chmod +x phparkitect.phar
 
 The `--autoload` option is required for all Phar runs.
 
+## Upgrading
+
+Upgrading from an older version? See [UPGRADE.md](UPGRADE.md) for the breaking
+changes you need to address.
+
 ## Contributing
 
 Found a bug or missing information? [Open an issue](https://github.com/phparkitect/arkitect/issues).
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 00000000..1bb34b61
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,69 @@
+# Upgrade guide
+
+This document lists the **breaking changes** you need to address when upgrading
+PHPArkitect, ordered from the most recent version to the oldest.
+
+> If a release is **not** listed here, it contains no breaking changes and you
+> can upgrade to it without modifying your configuration.
+
+## 1.0.0
+
+### PHP 7 support dropped
+
+The minimum supported PHP version is now **8.0**. If you are still on PHP 7.x,
+stay on the `0.8.x` line.
+
+### `--autoload` is mandatory when running as a Phar
+
+When running the Phar, you must now pass the autoload file explicitly:
+
+```diff
+- php phparkitect.phar check
++ php phparkitect.phar check --autoload vendor/autoload.php
+```
+
+### `*` in `excludePath()` no longer crosses directory separators
+
+`ClassSet::excludePath()` was reworked so that `*` matches within a single
+directory segment. Use the new `**` wildcard to restore the previous greedy
+behaviour that matched across any number of directory levels:
+
+```diff
+- $set->excludePath('src/*/Test.php');   // used to match src/A/B/C/Test.php
++ $set->excludePath('src/**/Test.php');  // matches at any depth
+```
+
+Most simple patterns (`Tests/*`, `*Test.php`) are unaffected, because they are
+consumed as a substring match.
+
+### User-defined classes in the global namespace are now evaluated
+
+PHP core classes are now auto-excluded from dependency checks via reflection
+(`isInternal()`), so you no longer need to list `\Exception`, `\DateTime`,
+`MongoDB\Driver\Manager`, etc. in your rules.
+
+As a consequence, the previous "skip everything in the root namespace" shortcut
+in `DependsOnlyOnTheseNamespaces` and `NotDependsOnTheseNamespaces` was removed.
+**User-defined** classes in the global namespace are now evaluated against your
+rules — they used to be silently skipped.
+
+### Docker image no longer published
+
+The PHPArkitect Docker image is no longer published. Existing tags on Docker Hub
+remain available, but no new ones will be pushed. Use Composer or the released
+Phar instead.
+
+## 0.6.0
+
+### `DependsOnlyOnTheseNamespaces` and `NotDependsOnTheseNamespaces` take an array
+
+These two expressions no longer accept a variadic list of namespaces; pass an
+array instead:
+
+```diff
+- new DependsOnlyOnTheseNamespaces('App\Domain', 'App\Infrastructure')
++ new DependsOnlyOnTheseNamespaces(['App\Domain', 'App\Infrastructure'])
+
+- new NotDependsOnTheseNamespaces('App\Domain', 'App\Infrastructure')
++ new NotDependsOnTheseNamespaces(['App\Domain', 'App\Infrastructure'])
+```

From 99885730ef2eb77efc0acfb03e39427a897a9543 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 20 Jun 2026 15:28:07 +0000
Subject: [PATCH 2/2] docs: add prominent UPGRADE.md link near README intro

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GH4h9HXMnBVrAkGtT4tq7W
---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 3527cf72..c987f313 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ Rule::allClasses()
     ->because('the domain must not depend on infrastructure');
 ```
 
+> Upgrading from an older version? Check [UPGRADE.md](UPGRADE.md) for breaking changes.
+
 ## Quick Start
 
 **1. Install**