diff --git a/docs/spec/shopware-guideline-compliance.md b/docs/spec/shopware-guideline-compliance.md
new file mode 100644
index 0000000..23692b9
--- /dev/null
+++ b/docs/spec/shopware-guideline-compliance.md
@@ -0,0 +1,68 @@
+# Spec: Shopware plugin guideline compliance (build/release pipeline)
+
+Outcome of the Wayfinder map `.scratch/shopware-guideline-compliance/` (tickets 01-05; research evidence
+on branches `research/shopware-guideline-checklist`, `research/shopware-cli-ci-behaviour`,
+`research/gitea-28-pipeline-standards`). Target: **Store-ready** artifacts, published to Gitea only
+(Gitea Release + Composer registry). Uploading to the Shopware Store is out of scope.
+
+## 1. Principles
+
+- Workflows are **plugin-agnostic**: no plugin name, package name, owner, repo or host is hard-coded;
+  all derive from `composer.json` and the `gitea` context. The same files must work unchanged for a
+  second plugin and be extractable to Gitea's shared-workflow repository later.
+- One artifact: the `shopware-cli extension package` zip (prebuilt admin/storefront JS) is used for
+  both the Gitea Release asset and the Composer registry.
+- `shopware-cli` is intentionally **unpinned** (`latest`). Known tradeoff: a CLI release can turn PRs
+  red without a repo change; treat that as a signal to fix config.
+- `RELEASE_TOKEN` is the only token (release, assets, registry publish, link). Workflows still declare
+  `permissions:`.
+
+## 2. Plugin changes
+
+| # | Change |
+|---|--------|
+| P1 | Commit `src/Resources/config/plugin.png` (256x256). Do not ship `plugin-transparent.png`. |
+| P2 | Logging: monolog channel `aeon_dump_manager` (`Resources/config/packages/monolog.yaml`, `build()` in the plugin class loading `packages/*.yaml`); inject `monolog.logger.aeon_dump_manager` into `PurgeDumpsTaskHandler`, `DumpService`, `CreateDumpHandler`; log dump job start/finish/failure. |
+| P3 | Migrate `services.xml` -> `services.yaml` and `routes.php` -> `routes.yaml`. No validation ignore for this. Update the "XML services" rule in `CLAUDE.md`. |
+| P4 | `composer.json`: `php` -> `^8.2`. Verify Shopware 6.6's own PHP requirement. |
+| P5 | Delete the empty lifecycle overrides in `AeonDumpManager`; keep `uninstall`. |
+| P6 | `.config/shopware-extension.yml` for build excludes and validation settings (add ignores only for real, accepted findings). |
+| P7 | Keep Keep-a-Changelog `CHANGELOG.md`; verify with a local `shopware-cli extension package --release` how the changelog is read. |
+
+## 3. Pipeline
+
+### PR workflow (`.gitea/workflows/pr.yml`, replaces `pr-version-check.yml`)
+
+Jobs (all required checks on `main`):
+1. `version-changelog` - unchanged logic (version bump + changelog heading). Keep this job/workflow name so the existing required context `version-changelog / version-changelog (pull_request)` keeps working, or update protection when renamed.
+2. `validate` - install `shopware-cli`, `extension validate .` (hard gate, no `|| true`).
+3. `package` - `extension package` with `--git-commit "$GITHUB_SHA"`, then assert the zip contains built admin JS (`Resources/public/administration/js`) when an admin entry exists.
+4. `phpunit` - `composer create-project shopware/production` (6.6.x) + MariaDB service, symlink plugin, install/activate, run phpunit. PHP 8.3.
+
+### Release workflow (`.gitea/workflows/release.yml`)
+
+On push to `main`, guarded against re-release by an existing tag:
+validate -> `extension package --git-commit "$GITHUB_SHA"` -> **validate the zip** -> create the Gitea
+release via API (`POST /repos/{owner}/{repo}/releases`, creates the tag) with the zip as asset ->
+upload the same zip to the Composer registry -> link package to repository.
+Removes the manual `git tag` step, the `akkuman` action and the `git archive` zip. Packaging happens
+before the tag exists, so a failed build leaves no orphan tag.
+
+### Branch protection (one-time, manual)
+
+`scripts/protect-main.sh` using `tea api PATCH repos/{owner}/{repo}/branch_protections/main` to set the
+required status-check contexts (current: `version-changelog / version-changelog (pull_request)`; add
+the new PR jobs). `tea branches protect` cannot set status checks. Not run by the pipeline.
+
+## 4. Open items to verify while implementing
+
+- Release POST creates a missing tag (fallback: tag step after packaging).
+- Meaning of HTTP 400 on the package-link endpoint.
+- Whether bare `validate` runs PHPStan/ESLint (needs PHP/Node on the runner); Node availability on the runner image.
+- Accepted size for `metadata.icon.size`; error-vs-warning rule list of validate.
+- Whether `routes.php` is flagged by validate; `shopware-cli extension fix` correctness for the YAML migration.
+- Exact status-check context names of the new jobs (set after the first run).
+
+## 5. Out of scope / later
+
+Shopware Store upload; Gitea shared-workflow repository; phpunit lowest-version matrix; Store listing metadata.