docs: add known-issues.md for recurring pitfalls and bugs

Living maintainer/agent reference for AUR/yay cache failures, GitHub vs
AUR workflow, CI import errors, release tag gaps, and M1/M2 open areas.

CHANGELOG.md

@@ -47,6 +47,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `docs/qt6-migration.md`, `ROADMAP.md` M6, and `NAMESPACE_MIGRATION.md` history sections updated to `bearhub/*` paths
 - `packaging/aur/README.md` — AUR workflow (GitHub vs AUR separation), current `pkgrel=11`
 - `ROADMAP.md`, `README.md` maintainer sections updated for post-migration state
+- `docs/known-issues.md` added — living doc for recurring issues (AUR, CI, release gaps)
 
 ### Compatibility
 - `bauh/api/*`, `bauh/commons/*`, `bauh/gems/*`, `bauh/view/*` remain installable as thin re-export shims (`from bearhub.<module> import *`)

NAMESPACE_MIGRATION.md

@@ -382,4 +382,5 @@ Run after every migration slice:
 - `docs/qt6-migration.md` — Qt6 inventory under `bearhub/view/qt/*` and `bearhub/view/core/*`
 - `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)
+- `docs/known-issues.md` — recurring bugs and maintainer pitfalls (update when learning new ones)
 - `AGENTS.md` — **local** AI/maintainer handoff (gitignored, not on GitHub)

README.md

@@ -208,6 +208,7 @@ Bearhub is currently distributed through source releases and AUR:
 - Qt6 plan: `docs/qt6-migration.md`
 - 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
+- Known issues / pitfalls: `docs/known-issues.md` (AUR, CI, release gaps — **keep updated**)
 - 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/`):

docs/known-issues.md

@@ -0,0 +1,167 @@
+# Known Issues and Maintainer Pitfalls
+
+Living document for recurring problems, gaps, and non-obvious workflow traps.  
+Update this file when you hit a new issue that cost debugging time.
+
+Last updated: 2026-06-27.
+
+## How to use this file
+
+When you discover or fix a recurring problem, add an entry with:
+
+- **Symptom** — what users/maintainers see
+- **Cause** — why it happens
+- **Fix** — concrete steps
+- **Prevent** — what to do next time (docs, CI, packaging)
+
+AI agents: read this **after** `AGENTS.md` (local) and before invasive changes.
+
+---
+
+## Release and packaging gaps
+
+### `main` ahead of latest GitHub tag
+
+| | |
+|---|---|
+| **Symptom** | Code on `main` has M3 migration; `pip install` from tag or AUR stable behaves differently than `main`. |
+| **Cause** | Latest tag is `0.10.7-bearhub.6`; `[Unreleased]` on `main` is not tagged yet. |
+| **Fix** | Tag `0.10.7-bearhub.7` (or `0.10.8`), update `packaging/aur/bearhub/PKGBUILD` source URL + `sha256sums`, publish to AUR. |
+| **Prevent** | Ship release checklist in `packaging/aur/README.md` after every milestone on `main`. |
+
+### AUR stable builds old tarball
+
+| | |
+|---|---|
+| **Symptom** | `yay -S bearhub` installs code without latest `main` changes. |
+| **Cause** | AUR `bearhub` uses a **tagged** tarball (`0.10.7-bearhub.6`), not `main`. Only `bearhub-git` tracks `main`. |
+| **Fix** | Use `bearhub-git` for bleeding edge, or cut a new release tag + PKGBUILD update. |
+| **Prevent** | Document in README maintainer section (done). |
+
+### GitHub push does not update AUR
+
+| | |
+|---|---|
+| **Symptom** | PKGBUILD changed on GitHub; `yay -Ss bearhub` unchanged. |
+| **Cause** | AUR is a **separate git repo** (`aur.archlinux.org`). |
+| **Fix** | Copy `packaging/aur/*` → local AUR clone → `git push` to AUR (local sync script on maintainer machine). |
+| **Prevent** | Never assume `git push origin main` publishes packaging. See `packaging/aur/README.md`. |
+
+---
+
+## AUR / yay / makepkg
+
+### SHA256 failed: `bearhub-0.10.7.tar.gz`
+
+| | |
+|---|---|
+| **Symptom** | `makepkg` / `yay`: `bearhub-0.10.7.tar.gz ... FEHLGESCHLAGEN` |
+| **Cause** | Stale cache file with generic name; old `pkgrel` used `bearhub-0.10.7.tar.gz` instead of tag-specific archive. |
+| **Fix** | `rm -rf ~/.cache/yay/bearhub`; `yay -Sy`; ensure PKGBUILD uses `bearhub-0.10.7-bearhub.6.tar.gz`. |
+| **Prevent** | Always use tag in source filename; bump `pkgrel` when forcing cache refresh. |
+
+### yay shows old `pkgrel` (e.g. `-9` or `-10` while AUR git has `-11`)
+
+| | |
+|---|---|
+| **Symptom** | `yay -Ss bearhub` lags behind AUR git. |
+| **Cause** | Local package DB or yay clone not refreshed; AUR RPC index can trail git briefly. |
+| **Fix** | `yay -Sy`; `rm -rf ~/.cache/yay/bearhub`; retry. |
+| **Prevent** | After AUR push, wait a few minutes or bump `pkgrel` again if index stuck. |
+
+### AUR SSH: `Permission denied (publickey)`
+
+| | |
+|---|---|
+| **Symptom** | `git push` to `aur.archlinux.org` fails. |
+| **Cause** | Missing key, or `~/.ssh/aur` permissions too open (`0644`). |
+| **Fix** | `chmod 600 ~/.ssh/aur`; key registered at https://aur.archlinux.org |
+| **Prevent** | `ssh -T aur@aur.archlinux.org` after setup. |
+
+---
+
+## CI and tests
+
+### CI: `ModuleNotFoundError: No module named 'bauh.api'`
+
+| | |
+|---|---|
+| **Symptom** | GitHub Actions unittest import errors for `bauh.*`. |
+| **Cause** | Tests import `bauh.*` but shims missing (partial migration commit) or `pip install -e .` not run. |
+| **Fix** | Ensure `bauh/` shims exist; tests use `bearhub.*` for primary imports; CI must `pip install -e .`. |
+| **Prevent** | Run full test suite locally before push; 159 tests should pass. |
+
+### Tests pass locally but fail in clean venv
+
+| | |
+|---|---|
+| **Symptom** | Different results with/without editable install. |
+| **Cause** | Running tests without `pip install -e .` — packages not on `PYTHONPATH`. |
+| **Fix** | `pip install -e .` then `python -m unittest discover -s tests -p "test_*.py" -v` |
+| **Prevent** | Match CI workflow in `.github/workflows/tests.yml`. |
+
+---
+
+## Product / UX (not bugs — known gaps)
+
+### UI still looks like bauh
+
+| | |
+|---|---|
+| **Symptom** | Bearhub visually identical to upstream. |
+| **Cause** | M1 (identity) not done; same PyQt5 themes/layout; `bauh-files` assets/URLs. |
+| **Fix** | M1 milestone: branding, screenshots, tray strings, data mirrors. |
+| **Prevent** | Do not confuse M3 namespace completion with visual rebrand. |
+
+### Runtime still uses `bauh-files` URLs
+
+| | |
+|---|---|
+| **Symptom** | Logs/downloads reference `github.com/vinifmor/bauh-files`. |
+| **Cause** | Intentional until Bearhub hosts its own datasets (see `0.10.7-bearhub.6` changelog). |
+| **Fix** | Future: `bearhub-files` repo or mirrored assets. |
+| **Prevent** | Document in M1/M4 before changing URLs. |
+
+---
+
+## Namespace migration (M3)
+
+### Accidental edit under `bauh/` instead of `bearhub/`
+
+| | |
+|---|---|
+| **Symptom** | Fix works via `import bauh` but `bearhub` path stale. |
+| **Cause** | `bauh/` is shim-only; implementation belongs in `bearhub/`. |
+| **Fix** | Move logic to `bearhub/`; keep `bauh/` as `from bearhub... import *`. |
+| **Prevent** | Grep `bearhub/` for changes; read `NAMESPACE_MIGRATION.md`. |
+
+### Phase D shim removal too early
+
+| | |
+|---|---|
+| **Symptom** | Breaks users/scripts still using `import bauh`. |
+| **Cause** | Removing `bauh/*` before one stable release on shims. |
+| **Fix** | Restore shims; wait for tagged stable + AUR cycle. |
+| **Prevent** | Follow Phase D checklist in `NAMESPACE_MIGRATION.md`. |
+
+---
+
+## Open runtime issues (M2 — investigate, not fully documented)
+
+| Area | Notes |
+|------|--------|
+| Uninstall flow | Qt lifecycle / thread teardown crashes reported historically |
+| Wayland | Desktop files may force `QT_QPA_PLATFORM=xcb` |
+| AppImage + AppImageLauncher | Install crashes possible; documented in README |
+
+Add concrete repro steps here when confirmed on current `main`.
+
+---
+
+## Related docs
+
+- `AGENTS.md` — local AI handoff (gitignored)
+- `packaging/aur/README.md` — AUR publish workflow
+- `NAMESPACE_MIGRATION.md` — namespace state
+- `ROADMAP.md` — M1–M6 milestones
+- `CHANGELOG.md` — fixed issues per release