From e8121c701fbe7067dcb38d6ae29fb3dbd0d76dfb Mon Sep 17 00:00:00 2001
From: Haylan <code@arthurerlich.ch>
Date: Mon, 14 Sep 2026 22:00:25 +0200
Subject: [PATCH] docs: add agent guidance files

---
 AGENTS.md |  1 +
 CLAUDE.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 QWEN.md   |  1 +
 3 files changed, 74 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md
 create mode 100644 QWEN.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a6fce0a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+@CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..284ecc7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+AeonDumpManager is a Shopware 6 plugin (`shopware-platform-plugin`) that manages database dumps for
+Shopware 6 development environments. It lists, creates, and deletes gzip-compressed `mysqldump`/
+`mariadb-dump` SQL dumps, both from a Settings-page admin UI (async creation with a polling progress
+bar) and via `aeon:dump:{list,create,remove}` console commands (sync creation). Design decisions and
+the full build spec live under `.scratch/admin-dump-manager/` and `.scratch/dump-manager-implementation-spec/`
+(Wayfinder maps) — consult those before changing the dump-creation/retention/ACL behavior.
+
+- Plugin bootstrap class: `src/AeonDumpManager.php` (extends `Shopware\Core\Framework\Plugin`) — this
+  is the entry point Shopware calls for install/uninstall/activate/deactivate/update lifecycle hooks.
+- Plugin class name is wired via `composer.json` → `extra.shopware-plugin-class`.
+- Services are registered manually in `src/Resources/config/services.xml` (Symfony DI, XML format,
+  autowiring is not configured — every new service/command/task must be added here explicitly with
+  its tag, e.g. `console.command` or `shopware.scheduled.task`).
+- Plugin store-config UI fields (e.g. `maxDumps`, `retantionDays`) are defined in
+  `src/Resources/config/config.xml` and read at runtime via Shopware's SystemConfigService.
+- `src/Resources/app/administration/` holds the admin UI module (Vue-based Shopware Administration
+  extension), currently just the `swag-example` scaffold module.
+
+## Running the plugin
+
+There is no standalone runtime — this plugin only runs inside a Shopware 6 instance. Local dev uses
+`docker-compose.yml`, which mounts the repo into a `dockware/shopware` container at
+`custom/plugins/AeonDumpManager`:
+
+```bash
+docker compose up -d
+```
+
+Shop/Admin/Adminer are all served on port 80/443; SSH into the container on port 22
+(`SSH_USER=shopware` / `SSH_PWD=shopware`); admin-watcher and storefront-watcher proxies are exposed
+on 8888/9998/9999 for `bin/build-administration.sh --watch` style workflows run inside the container.
+
+Plugin install/activate must be done through Shopware's own tooling inside the container (e.g.
+`bin/console plugin:refresh`, `bin/console plugin:install --activate AeonDumpManager`) — there is no
+composer script for this in this repo.
+
+The container's internal processes run as uid/gid 33 (`www-data`). The repo directory on the host is
+group-owned by that group with setgid bit set (`chgrp -R 33` + `chmod g+s`), so both the container and
+host users in group 33 can write without ownership fights.
+
+## Tests
+
+PHPUnit, bootstrapped through Shopware's own `TestBootstrapper` (`tests/TestBootstrap.php`), which
+activates this plugin inside a real Shopware kernel for the test run (`KERNEL_CLASS` is set to
+`Shopware\Core\Kernel` in `phpunit.xml`). This means tests require a working Shopware installation/DB
+to bootstrap against — they are not runnable as an isolated PHP package.
+
+```bash
+vendor/bin/phpunit                              # full suite
+vendor/bin/phpunit --filter TestClassName        # single test class
+vendor/bin/phpunit tests/SomeTest.php            # single file
+```
+
+## Dependencies
+
+- PHP `^8.1`, `shopware/core` `~6.6.0` (from `composer.json`); `phpunit/phpunit` `^10.0` as the only
+  dev dependency.
+- PSR-4 autoload: `AeonDumpManager\` → `src/`, `AeonDumpManager\Tests\` → `tests/`.
+
+## Adding functionality
+
+- New console commands go in `src/Command/`, new scheduled tasks in `src/ScheduledTask/` — both must
+  be registered in `src/Resources/config/services.xml` with the appropriate tag or Shopware will not
+  discover them.
+- Scheduled tasks need a matching handler (tagged `messenger.message_handler`) to actually run; a bare
+  `ScheduledTask` subclass like `ExampleTask` only defines the schedule, not the behavior.
diff --git a/QWEN.md b/QWEN.md
new file mode 100644
index 0000000..a6fce0a
--- /dev/null
+++ b/QWEN.md
@@ -0,0 +1 @@
+@CLAUDE.md
\ No newline at end of file