docs: refresh maintainer and agent handoff documentation

Document post-M3 state on main, GitHub vs AUR publishing separation,
AUR pkgrel=11 / source tag gap, M1 UI identity status, and CI test
workflow. packaging/aur/README.md clarifies local-only AUR sync.

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+> **Status (2026-06-27):** This section is merged on GitHub `main` (159 tests, CI green). Not yet in a release tag. AUR stable `bearhub 0.10.7-11` still builds source tag `0.10.7-bearhub.6` until `0.10.7-bearhub.7` (or `0.10.8`) is published.
+
 ### Added
 - Native gem loader at `bearhub/view/core/gems.py` (scans `bearhub/gems/` first, falls back to `bauh/gems/` during transition)
 - Namespace compatibility tests for migrated packages:
@@ -43,7 +45,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Gem migration plan documented (G.1 AppImage → G.4 Arch order)
 - Phase D completion criteria and remaining shim-removal steps documented
 - `docs/qt6-migration.md`, `ROADMAP.md` M6, and `NAMESPACE_MIGRATION.md` history sections updated to `bearhub/*` paths
-- `packaging/aur/README.md` release checklist aligned with next tag after `[Unreleased]`
+- `packaging/aur/README.md` — AUR workflow (GitHub vs AUR separation), current `pkgrel=11`
+- `ROADMAP.md`, `README.md` maintainer sections updated for post-migration state
 
 ### Compatibility
 - `bauh/api/*`, `bauh/commons/*`, `bauh/gems/*`, `bauh/view/*` remain installable as thin re-export shims (`from bearhub.<module> import *`)

CONTRIBUTING.md

@@ -30,3 +30,13 @@ The way to go here is to ask yourself if the improvement would be useful for mor
 - `bearhub/gems/web/resources/locale`
 
 New code should use `bearhub.*` imports. Legacy `bauh.*` imports still work via compatibility shims (see `NAMESPACE_MIGRATION.md`).
+
+Run tests before submitting changes:
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+CI (`.github/workflows/tests.yml`) runs the same on push to `main` (Python 3.11 and 3.12).

NAMESPACE_MIGRATION.md

@@ -2,7 +2,7 @@
 
 This document defines the technical migration strategy for moving the Python package namespace from `bauh` to `bearhub` safely.
 
-Last updated: 2026-06-27 (Phase D slice: version flip + packaging canonicalization).
+Last updated: 2026-06-27 (M3 merged on GitHub `main`; Phase D partial; release tag pending).
 
 ## Current State
 
@@ -16,7 +16,9 @@ Last updated: 2026-06-27 (Phase D slice: version flip + packaging canonicalizati
 | `gems/` backends | AppImage, Flatpak, Web, Arch/AUR — all under `bearhub/gems/` |
 | Gem loader | Native `bearhub/view/core/gems.py` (dual-root scan + import fallback) |
 | Tests | 159 unit tests, all passing (CI: Python 3.11, 3.12) |
-| Compatibility shims | `bauh/*` re-exports `bearhub.*`; documented in `CHANGELOG.md` `[Unreleased]` |
+| Compatibility shims | `bauh/*` re-exports `bearhub.*`; on `main`, documented in `CHANGELOG.md` `[Unreleased]` |
+| GitHub `main` vs release tag | **Migration on `main`**; latest tag `0.10.7-bearhub.6` is behind `main` |
+| AUR stable | `0.10.7-11` builds tarball from tag **`0.10.7-bearhub.6`** until next release |
 
 ### Progress Overview (~95 % of M3 — Phase B complete, Phase D in progress)
 
@@ -376,6 +378,8 @@ Run after every migration slice:
 
 ## Related Documents
 
-- `ROADMAP.md` — milestone M3 (namespace) and M6 (Qt6, after M3 tag)
+- `ROADMAP.md` — milestones M1–M6 (M1 identity/branding still open)
 - `docs/qt6-migration.md` — Qt6 inventory under `bearhub/view/qt/*` and `bearhub/view/core/*`
-- `CHANGELOG.md` — `[Unreleased]` holds full Phase B + partial Phase D notes; tagged slices from `0.10.7-bearhub.4` through `.6`
+- `CHANGELOG.md` — `[Unreleased]` on `main` (Phase B + partial Phase D); tagged `0.10.7-bearhub.4` … `.6`
+- `packaging/aur/README.md` — AUR publish workflow (GitHub ≠ AUR)
+- `AGENTS.md` — **local** AI/maintainer handoff (gitignored, not on GitHub)

README.md

@@ -20,7 +20,8 @@ Current focus:
 - keeping the application working on current Arch Linux
 - improving the experience for Arch and AUR package management
 - maintaining compatibility with modern Python versions
-- stabilizing the existing feature set before larger changes
+- completing namespace migration (M3, ~95 % — code on `main`, release tag pending)
+- stabilizing the existing feature set before larger changes (UI still largely looks like upstream bauh until M1)
 
 ## Why This Fork Exists
 
@@ -201,14 +202,18 @@ Bearhub is currently distributed through source releases and AUR:
 
 #### <a name="maintainer_docs">Maintainer docs</a>
 
-- Namespace migration notes: `NAMESPACE_MIGRATION.md` (runtime is native under `bearhub/`; `bauh/` is shim-only until Phase D completion)
+- Namespace migration: `NAMESPACE_MIGRATION.md` (runtime native under `bearhub/`; `bauh/` shims until Phase D)
-- Unreleased migration changelog: `CHANGELOG.md` → `[Unreleased]`
+- Changelog (on `main`, not yet tagged): `CHANGELOG.md` → `[Unreleased]`
-- Qt6 migration plan: `docs/qt6-migration.md`
+- Roadmap: `ROADMAP.md` (M1 identity, M3 namespace, M6 Qt6)
-- Brand assets: `gfx/bearhub.svg`, `gfx/bearhub.png` (synced into `bearhub/view/resources/img/logo.svg` for runtime/packaging)
+- Qt6 plan: `docs/qt6-migration.md`
-- AppImage build (from `linux_dist/appimage/`):
+- AUR templates + publish workflow: `packaging/aur/README.md` (**GitHub push ≠ AUR**; local AUR clone + SSH push)
+- AUR stable (2026-06-27): `bearhub 0.10.7-11` — source still tag `0.10.7-bearhub.6` until next release
+- Local agent handoff: `AGENTS.md` (gitignored, maintainer machine only)
+- Brand assets: `gfx/bearhub.svg`, `gfx/bearhub.png` → `bearhub/view/resources/img/logo.svg`
+- AppImage build (`linux_dist/appimage/`):
 
 ```bash
-export BEARHUB_VERSION=0.10.7-bearhub.7  # next tag after CHANGELOG [Unreleased] is released
+export BEARHUB_VERSION=0.10.7-bearhub.7  # after CHANGELOG [Unreleased] is tagged
 ./build.sh
 ```
 

ROADMAP.md

@@ -13,6 +13,8 @@ This roadmap defines how Bearhub becomes an independent, Arch-first project whil
 
 ### M1: Identity Completion (2 weeks)
 
+Status (2026-06-27): **not started** — UI/themes still look ~99 % like upstream bauh; README screenshots and runtime data URLs still reference `bauh-files` in places. Namespace (M3) ≠ visual rebrand.
+
 Scope:
 - Remove remaining `bauh` naming from UI text, notifications, tray labels, and docs.
 - Ensure links (issues, docs, release checks) point to Bearhub endpoints.
@@ -37,7 +39,7 @@ Definition of Done:
 
 ### M3: Namespace Migration (`bauh` -> `bearhub`) (3-5 weeks)
 
-Status (2026-06-27): **~95 % complete** — runtime code native under `bearhub/`; `bauh/` is shim-only; version flip done; full shim removal pending one stable release. See `NAMESPACE_MIGRATION.md` and `CHANGELOG.md` `[Unreleased]`.
+Status (2026-06-27): **~95 % complete** — runtime code native under `bearhub/`; `bauh/` is shim-only; version flip done; **merged on GitHub `main`** (`CHANGELOG.md` `[Unreleased]`); **not yet in a release tag**; AUR stable still builds `0.10.7-bearhub.6`. Full shim removal pending one stable release. See `NAMESPACE_MIGRATION.md`.
 
 Scope:
 - Migrate Python package namespace from `bauh` to `bearhub`.
@@ -50,8 +52,9 @@ Definition of Done:
 - Packaging and tests run successfully with new namespace.
 
 Remaining for M3 closure:
-- Ship `[Unreleased]` migration changes as a tagged release (`0.10.7-bearhub.7` or `0.10.8`)
+- Tag `[Unreleased]` on `main` as `0.10.7-bearhub.7` (or `0.10.8`) and update AUR stable PKGBUILD source URL + checksum
-- Validate AUR `bearhub` / `bearhub-git` on real Arch systems
+- Publish PKGBUILD to AUR via **local maintainer workflow** (not GitHub push alone)
+- Validate `bearhub` / `bearhub-git` on real Arch systems (`yay -Sy` after publish)
 - Remove `bauh/*` shims after one stable cycle (Phase D completion)
 
 ### M4: Backend Governance (2-3 weeks)
@@ -153,8 +156,9 @@ Rollback strategy:
 
 ## Immediate Next Actions
 
-1. Tag release with `CHANGELOG.md` `[Unreleased]` namespace migration entries.
+1. Tag release: move `CHANGELOG.md` `[Unreleased]` → `0.10.7-bearhub.7` (or `0.10.8`); update `packaging/aur/bearhub/PKGBUILD` source tag + `sha256sums`.
-2. Close remaining M1 gaps (smoke-test checklist on real Arch desktop).
+2. Publish AUR stable (`pkgrel` bump as needed); users run `yay -Sy` — see `packaging/aur/README.md`.
-3. Build M2 issue list from current crash reports and prioritize top 3.
+3. Close M1 gaps (user-facing Bearhub branding; smoke-test on real Arch desktop).
-4. Complete M3 Phase D after one stable release (remove `bauh/*` shims, drop `provides=('bauh')` in AUR).
+4. Build M2 issue list from crash reports; prioritize uninstall/Qt teardown.
-5. Schedule M6 Qt6 PR-6.2 after M3 tag (namespace stable; do not parallelize full Qt6 migration).
+5. Complete M3 Phase D after one stable release (remove `bauh/*` shims, drop `provides=('bauh')` in AUR).
+6. Schedule M6 Qt6 PR-6.2 only after M3 tag is validated.

packaging/aur/README.md

@@ -1,35 +1,66 @@
 # AUR Packaging
 
-This directory contains starter `PKGBUILD` files for publishing Bearhub on the AUR:
+This directory contains **PKGBUILD templates** for publishing Bearhub on the AUR:
 
-- `bearhub/PKGBUILD`: stable package from tagged releases
+- `bearhub/PKGBUILD`: stable package from **tagged** GitHub releases
 - `bearhub-git/PKGBUILD`: rolling package from `main`
 
-Before publishing:
+**Important:** GitHub and AUR are separate. Updating files here and pushing to GitHub does **not** update the AUR. Publishing requires a **local AUR git clone** and `git push` to `aur.archlinux.org` (see below).
 
-1. Generate `.SRCINFO` with `makepkg --printsrcinfo > .SRCINFO` inside each package directory.
+## Current stable snapshot (2026-06-27)
-2. Build-test locally with `makepkg -si`.
+
-3. Push each package to its own AUR Git repository (`aur@aur.archlinux.org:bearhub.git` and `aur@aur.archlinux.org:bearhub-git.git`).
+| Field | Value |
+|-------|--------|
+| `pkgver` | `0.10.7` |
+| `pkgrel` | `11` |
+| Source tag | `0.10.7-bearhub.6` |
+| Source archive | `bearhub-0.10.7-bearhub.6.tar.gz` |
+
+`main` on GitHub already contains the M3 namespace migration (`[Unreleased]` in `CHANGELOG.md`). Stable AUR still builds the **`0.10.7-bearhub.6`** tarball until the next release tag and PKGBUILD URL update.
+
+## Before first publish
+
+1. Generate `.SRCINFO`: `makepkg --printsrcinfo > .SRCINFO` in each package directory.
+2. Build-test: `makepkg -si`.
+3. Clone AUR repos locally (once):
+   ```bash
+   git clone ssh://aur@aur.archlinux.org/bearhub.git ~/Projekte/development/current/aur/bearhub
+   git clone ssh://aur@aur.archlinux.org/bearhub-git.git ~/Projekte/development/current/aur/bearhub-git
+   ```
+4. Register SSH public key at https://aur.archlinux.org (key file e.g. `~/.ssh/aur`, mode `600`).
+
+## Publishing workflow (maintainer, local)
+
+1. Edit `packaging/aur/bearhub/PKGBUILD` and `.SRCINFO` in **this** repo; commit and push to **GitHub**.
+2. Copy into local AUR clone and push to AUR:
+   - **Option A:** local script `scripts/sync-aur-packaging.sh --push` (maintainer machine only — **not** in GitHub repo).
+   - **Option B:** manually:
+     ```bash
+     cp packaging/aur/bearhub/PKGBUILD ~/Projekte/development/current/aur/bearhub/
+     cp packaging/aur/bearhub/.SRCINFO ~/Projekte/development/current/aur/bearhub/
+     cd ~/Projekte/development/current/aur/bearhub
+     git add PKGBUILD .SRCINFO
+     git commit -m "updpkgsums: …"
+     git push origin master
+     ```
+3. Users refresh index: `yay -Sy`. If SHA256 fails, clear stale cache: `rm -rf ~/.cache/yay/bearhub`.
 
 ## Stable release checklist (`bearhub`)
 
-1. Move `CHANGELOG.md` `[Unreleased]` entries under the new tag (e.g. `0.10.7-bearhub.7` or `0.10.8`).
+1. Move `CHANGELOG.md` `[Unreleased]` under a new tag (e.g. `0.10.7-bearhub.7` or `0.10.8`).
-2. Commit all release changes on `main`.
+2. Commit release changes on `main` and push to GitHub.
 3. Create and push the git tag:
    ```bash
    git tag -a 0.10.7-bearhub.7 -m "Release 0.10.7-bearhub.7"
    git push origin main
    git push origin 0.10.7-bearhub.7
    ```
-4. Refresh tarball checksum in `bearhub/PKGBUILD`:
+4. Update `bearhub/PKGBUILD`: `_pkgver_tag`, source URL, `sha256sums`; regenerate `.SRCINFO`:
    ```bash
    cd packaging/aur/bearhub
-   makepkg -g >> PKGBUILD  # or updpkgsums after source URL is reachable
+   makepkg --verifysource
    makepkg --printsrcinfo > .SRCINFO
    ```
-5. Sync to local AUR clones:
+5. Commit PKGBUILD changes on GitHub `main`.
-   ```bash
+6. Publish to AUR (local clone + push — step 2 above).
-   scripts/sync-aur-packaging.sh
+7. Build-test; optional GitHub Release with assets.
-   ```
-6. Build-test both AUR packages, then publish AUR commits.
-7. Optional: create GitHub release from the new tag.