docs: snapshot of the project's Claude Code memory

Decisions, environment quirks and pitfalls learned while working on AgentHub
(docs/claude-memory/, indexed by MEMORY.md). Notes holding personal account
details are left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/claude-memory/agenthub-no-launchd-on-macos.md

@@ -0,0 +1,21 @@
+---
+name: agenthub-no-launchd-on-macos
+description: "macOS auto-start: LaunchAgent BUILT 2026-09-25 (launchd-service.js + service-manager.js), uncommitted/untested on a real Mac until the tester reports"
+metadata:
+  node_type: memory
+  type: project
+  originSessionId: 149814b6-3a00-4df5-9c93-06f8c0700f5e
+  modified: 2026-09-25T04:32:05.978Z
+---
+
+2026-09-14: no launchd equivalent of the systemd unit was built — no Mac to test on, and the startup area already produced two self-kill fix releases (v1.5.7, v1.5.8). On macOS `systemctlAvailable()` is false, so the bootstrap falls back to a detached spawn from SessionStart: no reboot persistence, no auto-restart, `agenthub service install` says unavailable.
+
+2026-09-25: REOPENED. A user reported "auto-start still doesn't work on macOS"; the user confirmed they mean start-at-login without opening Claude Code, and that someone can test builds on a Mac.
+
+**Why:** the original blocker (no way to test) is gone.
+
+**How to apply:** proposed design = LaunchAgent `~/Library/LaunchAgents/io.smartgift.agenthub.plist` behind the same API as `scripts/systemd-service.js` (KeepAlive ≈ Restart=always, AbandonProcessGroup, bootout+bootstrap as the deferred restart because kickstart does not re-read the plist, marker comment for "ours", every launchctl failure falls back to the detached spawn). Ship with a Mac checklist for the tester. The #22 macOS fixes from branch ah-release-1823 were cherry-picked onto main 2026-09-25 (not the superseded UI commits).
+
+2026-09-25 later: BUILT as designed — `scripts/launchd-service.js`, `scripts/service-manager.js` (all callers require it), tests in `server/__tests__/launchd-service.test.js` (stubbed launchctl, faked platform). Mac tester checklist = INSTALL.md § macOS items 1–11. Not yet committed when written; never run on a real Mac.
+
+Other macOS caveats (code review only): needs Node ≥ 22.5, `brew install tmux`, `~/.local/bin` on PATH by hand. See [[agenthub-release-state]].