feat: add DMG build script and enhance README with installation instructions and Start at Login feature

core/services/macos-installation-model.md

@@ -32,10 +32,30 @@ Use a staged model:
    - Avoid privileged helpers until a real system-level requirement appears.
 
 3. **Future polished distribution**
-   - Create a signed/notarized `.app` or `.pkg`.
-   - Consider `SMAppService` for login item management from inside the app.
+   - Create a signed/notarized `.app` distributed in a `.dmg` with an Applications shortcut, or a `.pkg` only if privileged installation becomes necessary.
+   - Use `SMAppService` for login item management from inside the app so the user can toggle Start at Login in the UI instead of running `launchctl` scripts manually.
    - Add a small daemon API if the UI needs richer lifecycle control than shelling out to `services.py`.
 
+## Desired user-grade install flow
+
+For a Cloudflare/Docker-like local experience, the target should be:
+
+1. User opens `AIWorkspace.dmg`.
+2. User drags `AIWorkspace.app` to `/Applications` or `~/Applications`.
+3. User launches the app.
+4. App shows service status and a **Start at Login** toggle.
+5. App registers/unregisters itself as a login item using `SMAppService`.
+6. App starts/stops workspace services through the service manager.
+
+The existing shell scripts remain useful for development and bootstrap, but should not be the primary end-user experience once the app handles login item registration itself.
+
+## Current implementation state
+
+- `AIWorkspace.app` can be packaged from `apps/mac/AIWorkspace/scripts/package-app.sh`.
+- `AIWorkspace.dmg` can be built from `apps/mac/AIWorkspace/scripts/build-dmg.sh`.
+- The app UI includes a **Start at Login** toggle backed by `SMAppService.mainApp`.
+- LaunchAgent scripts remain as development fallbacks, not the preferred user path.
+
 ## Why not LaunchDaemon now
 
 The current services are user-context services: