idlewatch 0.1.0

package/docs/onboarding-external.md

@@ -0,0 +1,58 @@
+# External onboarding + distribution
+
+## Paths for external users
+
+### 1) npx quickstart (fastest)
+
+```bash
+npx idlewatch-skill quickstart
+```
+
+Wizard output:
+- Generates an env file (`idlewatch.env`) under user config directory.
+- In production mode, copies the provided service-account key to `credentials/` with mode `0600`.
+- Emits next-step command to load env and run a one-shot validation.
+
+### 2) Signed DMG install (managed rollout)
+
+1. Build trusted artifacts:
+   ```bash
+   npm run package:trusted
+   ```
+2. Distribute `dist/IdleWatch-<version>-signed.dmg`.
+3. User drags app into Applications and launches.
+4. On first run, user executes quickstart from packaged app terminal context to enroll credentials.
+
+### Optional: background startup on macOS
+
+Users can register the packaged app for background startup with LaunchAgent:
+
+```bash
+npm run install:macos-launch-agent
+```
+
+To remove the LaunchAgent later:
+
+```bash
+npm run uninstall:macos-launch-agent
+```
+
+See `docs/packaging/macos-dmg.md` for signing/notarization setup.
+
+## Credential strategy (least privilege)
+
+- Prefer `FIREBASE_SERVICE_ACCOUNT_FILE` over raw JSON env values.
+- Use a dedicated service account per deployment environment.
+- Grant minimal Firestore write permissions needed for telemetry ingestion.
+- Avoid reusing broad admin credentials across developer laptops.
+- Rotate keys periodically and replace the local credential file path atomically.
+
+## Automation validation
+
+Run:
+
+```bash
+npm run validate:onboarding
+```
+
+This validates non-interactive enrollment output and secure credential file staging.

package/docs/packaging/macos-dmg.md

@@ -0,0 +1,199 @@
+# macOS DMG packaging pipeline
+
+IdleWatch ships an `.app` scaffold in `dist/` and a DMG installer pipeline.
+Signing/notarization are optional but available when Apple credentials are configured.
+The `scripts/` folder now includes packaging, runtime, and launch lifecycle helpers for
+local testing and release preparation.
+
+## Prerequisites
+
+- Xcode Command Line Tools (`xcode-select --install`)
+- Node.js 20+ on target host (current launcher executes payload with local `node` or bundled runtime)
+- Apple Developer signing identity (for production)
+- Notary API key/profile configured in keychain (for production)
+- Optional tools for polished DMG UX:
+  - `create-dmg`
+  - `dmgbuild`
+
+## Pipeline stages
+
+1. **Build artifact**
+   - `npm ci`
+   - `npm test`
+   - `npm pack` to generate tarball
+2. **Create app wrapper skeleton**
+   - Stage Node package + app metadata into `dist/IdleWatch.app/Contents/Resources/`
+   - Add launcher script in `Contents/MacOS/IdleWatch`
+3. **Launch lifecycle (optional)**
+   - Install LaunchAgent to keep IdleWatch running in the background:
+     - `scripts/install-macos-launch-agent.sh`
+   - Uninstall: `scripts/uninstall-macos-launch-agent.sh`
+4. **Codesign (optional)**
+   - Sign app with `codesign --deep --force --options runtime ...`
+5. **Notarize (optional)**
+   - `xcrun notarytool submit ... --wait`
+   - `xcrun stapler staple IdleWatch-<ver>-*.dmg`
+6. **Build DMG (baseline)**
+   - `hdiutil create ...` output: `dist/IdleWatch-<version>-unsigned.dmg` or `-signed.dmg`
+
+## Current scaffold commands
+
+### OpenClaw discoverability in packaged launches
+
+IdleWatch writes packaging metadata (`Contents/Resources/packaging-metadata.json`) during `package-macos` with the `openclawBinHint` used at build time.
+
+When the packaged launcher starts, it resolves the OpenClaw binary in this order:
+
+1. `IDLEWATCH_OPENCLAW_BIN` (explicit runtime override, preferred)
+2. `IDLEWATCH_OPENCLAW_BIN_HINT` (legacy launcher hint, supported)
+3. `openclawBinHint` from `packaging-metadata.json`
+   (packaging writes this value from the same `IDLEWATCH_OPENCLAW_BIN` / `IDLEWATCH_OPENCLAW_BIN_HINT` inputs used during build)
+4. `openclaw` via normal `PATH`
+
+When bundling a Node runtime, `package-macos.sh` copies a portable subset (`bin`, `lib`, `include`) with symlink dereference, so packaged layouts remain portable even when the host runtime is a symlink and avoids copying non-essential symlinked shell-completion trees.
+
+OpenClaw command probing in the packaged runtime uses the same command preference list as local runs:
+`status --json`, `usage --json`, `session status --json`, `session_status --json`, `stats --json`.
+
+This makes packaged installs more reliable in environments where `openclaw` is not on the default launcher `PATH`.
+
+
+Each packaged app includes `Contents/Resources/packaging-metadata.json` with build provenance (version, signing/runtime hints, source git commit/clean-state, payload filename, and launcher settings) to support supportability checks and deterministic QA.
+
+Optional environment variables:
+- `IDLEWATCH_OPENCLAW_BIN="/opt/homebrew/bin/openclaw"` — pins OpenClaw binary path for packaged/non-interactive runtime usage collection.
+- `IDLEWATCH_OPENCLAW_BIN_HINT="/opt/homebrew/bin/openclaw"` — legacy launcher hint (supported for compatibility). When `IDLEWATCH_OPENCLAW_BIN` is unset, this is used as the strict-mode explicit fallback as well.
+- `IDLEWATCH_NODE_BIN="/opt/homebrew/bin/node"` — pins Node binary path used by packaged app launcher.
+- `IDLEWATCH_SKIP_SOURCEMAP_VALIDATION="1"` — temporarily disables packaged sourcemap integrity validation during `package:macos` (use only for emergency/debug scenarios).
+- `IDLEWATCH_NODE_RUNTIME_DIR="/path/to/node-runtime"` — optionally bundles portable Node runtime into app resources (`<runtime>/bin/node` required).
+- `IDLEWATCH_APP_PATH="/Applications/IdleWatch.app"` — app path used by LaunchAgent scripts.
+- `IDLEWATCH_LAUNCH_AGENT_LABEL="com.idlewatch.agent"` — override LaunchAgent label.
+- `IDLEWATCH_LAUNCH_AGENT_PLIST_ROOT="$HOME/Library/LaunchAgents"` — override plist root for install/uninstall scripts.
+- `IDLEWATCH_LAUNCH_AGENT_LOG_DIR="$HOME/Library/Logs/IdleWatch"` — set log destination for LaunchAgent output.
+- `IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS=2500` — baseline per-probe timeout for OpenClaw usage commands (packaging validation wrappers default to `4000`).
+- `IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES=2097152` — maximum bytes captured per OpenClaw probe call (increase for noisy/progress-heavy OpenClaw outputs).
+- `IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES_HARD_CAP=16777216` — hard ceiling for automatic capture growth on noisy outputs before giving up.
+- OpenClaw probe output is merged from stdout+stderr before JSON extraction, so mixed-output CLIs remain parseable during packaged validation and local collection.
+- `IDLEWATCH_DRY_RUN_TIMEOUT_MS=15000` — baseline timeout in milliseconds for `--dry-run` validation helpers (prevents launchers that emit continuous output from hanging validation).
+  - Packaged runtime and DMG install validators default this to `90000` during execution to reduce false timeout failures on slow hosts.
+  - OpenClaw release-gate helpers now default this to `60000` (kept aligned with host release gates unless package-specific override is needed):
+    - `validate:openclaw-release-gates`
+    - `validate:packaged-openclaw-release-gates` (and `:reuse-artifact`)
+  - This avoids false negatives on slower machines where `openclaw --json` probes may take longer than `15000ms`.
+- `IDLEWATCH_DRY_RUN_TIMEOUT_RETRY_BONUS_MS=10000` — extra timeout budget (in ms) applied when an `--dry-run` attempt does not emit telemetry.
+  - Example: `90000` -> fallback retry tries `100000` (then `110000`, etc., if `IDLEWATCH_DRY_RUN_TIMEOUT_MAX_ATTEMPTS` is raised).
+- `IDLEWATCH_DRY_RUN_TIMEOUT_MAX_ATTEMPTS=3` — number of timeout/retry attempts for packaged validator dry-runs. Set to `1` to keep strict single-pass behavior.
+- `IDLEWATCH_DRY_RUN_TIMEOUT_BACKOFF_MS=2000` — optional backoff delay (ms) between retries in packaged validators. Helps avoid flapping when disk or mount pressure temporarily stalls output.
+  - Set to `0` for tight loops when deterministic timing is already stable.
+- `IDLEWATCH_REQUIRE_SOURCE_COMMIT_MATCH=1` — when validating reusable artifacts (including DMG-installed artifacts), require current checkout commit to match `packaging-metadata.json.sourceGitCommit`.
+  - If the artifact lacks `sourceGitCommit`, validation fails fast and requests a fresh package by default.
+  - Set `IDLEWATCH_ALLOW_LEGACY_SOURCE_GIT_COMMIT=1` to temporarily continue with older artifacts while planning a rebuild.
+- `IDLEWATCH_REQUIRE_SOURCE_DIRTY_MATCH=1` — when set, require current working-tree cleanliness to match `packaging-metadata.json.sourceGitDirty` for artifacts with reliable provenance (`sourceGitDirtyKnown: true`).
+  - For strict reuse-only workflows, this is fail-closed when provenance is incomplete.
+  - Set `IDLEWATCH_ALLOW_LEGACY_SOURCE_GIT_DIRTY=1` to temporarily keep compatibility with legacy artifacts that only expose `sourceGitDirty` or omit dirty provenance while planning a rebuild.
+  - Rebuild with `npm run package:macos` to regenerate canonical provenance (`sourceGitDirtyKnown: true`).
+- `IDLEWATCH_PACKAGED_ARTIFACT_MAX_AGE_MS=<ms>` — if set, fail reusable artifact validation when metadata `builtAt` exceeds this age.
+- `IDLEWATCH_ARTIFACT_DIR=<path>` — override artifact root when invoking `validate-packaged-artifact.mjs` against non-dist app bundles (used by `validate:dmg-install`).
+- `IDLEWATCH_DMG_ATTACH_TIMEOUT_MS=30000` — maximum wall time for `hdiutil attach` in `validate:dmg-install`.
+- `IDLEWATCH_DMG_DETACH_TIMEOUT_MS=8000` — timeout for ejecting the DMG in cleanup.
+- `MACOS_CODESIGN_IDENTITY="Developer ID Application: ..."` — signs `IdleWatch.app` during `package-macos.sh`.
+- `MACOS_NOTARY_PROFILE="<keychain-profile>"` — notarizes/staples DMG during `build-dmg.sh`.
+- `IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1` — strict mode; fails packaging unless signing/notarization prerequisites are present.
+- `IDLEWATCH_ALLOW_UNSIGNED_TAG_RELEASE=1` — explicit CI-only bypass for tag builds; disables auto-strict guard that otherwise blocks unsigned `refs/tags/*` packaging.
+- `IDLEWATCH_BUNDLED_RUNTIME_REQUIRED=1` — when set to `1`, `validate:packaged-bundled-runtime`/`:reuse-artifact` requires `nodeRuntimeBundled=1` in metadata and enforces strict PATH-scrubbed validation. In reuse mode, this defaults to `0` so prebuilt non-bundled artifacts can still validate launchability with host PATH fallback; set `1` to force strict node-free checks.
+- `IDLEWATCH_USE_ORIGINAL_PATH_FOR_NON_BUNDLED=1` — allows `validate:packaged-bundled-runtime:reuse-artifact` to validate non-bundled artifacts by falling back to current host PATH when `nodeRuntimeBundled!=1`.
+
+- `scripts/package-macos.sh`
+  - Creates `dist/IdleWatch.app`
+  - Generates the package tarball via `npm pack --json` and selects the reported filename deterministically (instead of relying on glob/mtime heuristics), then expands it into `Contents/Resources/payload/package`
+  - Installs production runtime dependencies into packaged payload (`npm ci --omit=dev` when a lockfile is available, otherwise `npm install --omit=dev`) so mounted-DMG launches do not rely on workspace/global `node_modules`
+- Validates packaged JavaScript sourcemap integrity immediately after dependency install (`node scripts/validate-packaged-sourcemaps.mjs`). If any `sourceMappingURL` points to a missing external file, packaging fails early with a concrete path list to force a clean rebuild and avoid non-deterministic DMG noise.
+  - Generates a working launcher (`Contents/MacOS/IdleWatch`) that runs:
+    - `<node> Contents/Resources/payload/package/bin/idlewatch-agent.js ...`
+    - Node binary resolution order: `IDLEWATCH_NODE_BIN` → bundled runtime (`Contents/Resources/runtime/node/bin/node`, when `IDLEWATCH_NODE_RUNTIME_DIR` is supplied at package time) → `PATH` (`node`)
+  - Launcher enforces Node.js major version `>=20` and fails with actionable runtime-path/version diagnostics otherwise
+  - Stages `dist/dmg-root` and adds `/Applications` symlink
+- `scripts/build-dmg.sh`
+  - Creates `dist/IdleWatch-<version>-unsigned.dmg` (or `-signed.dmg` when `MACOS_CODESIGN_IDENTITY` is set) from `dist/dmg-root`
+  - Writes SHA-256 checksum to `dist/IdleWatch-<version>-<signed|unsigned>.dmg.sha256`
+  - If `MACOS_NOTARY_PROFILE` is set, submits DMG via `notarytool` and staples on success
+- `scripts/validate-packaged-metadata.sh`
+  - Verifies generated `Contents/Resources/packaging-metadata.json` and packaged entrypoint integrity
+- `scripts/validate-dmg-checksum.sh`
+  - Verifies checksum integrity for latest DMG (or explicit path)
+- `npm run validate:dmg-checksum`
+  - Runs `scripts/validate-dmg-checksum.sh` for artifact integrity checks in local/release workflows
+- `npm run validate:packaged-metadata`
+  - Runs `scripts/validate-packaged-metadata.sh` and validates bundle metadata + platform consistency
+- `npm run package:release`
+  - Runs `package:trusted` and checksum validation in one command (safe for production-ready artifact preparation)
+- `scripts/install-macos-launch-agent.sh`
+  - Writes `~/Library/LaunchAgents/<label>.plist`
+  - Loads `LaunchAgent` under current user sandbox, with `StartInterval` aligned to `IDLEWATCH_INTERVAL_MS` (min 60s), background mode, stdout/stderr logs
+- `scripts/uninstall-macos-launch-agent.sh`
+  - Unloads and removes `~/Library/LaunchAgents/<label>.plist`
+- `npm run install:macos-launch-agent`
+  - Wrapper for `scripts/install-macos-launch-agent.sh`
+- `npm run uninstall:macos-launch-agent`
+  - Wrapper for `scripts/uninstall-macos-launch-agent.sh`
+- `scripts/validate-trusted-prereqs.sh`
+  - Validates local signing identity + notary keychain profile before trusted packaging
+- `npm run package:trusted`
+  - Strict signed + notarized local path (`IDLEWATCH_REQUIRE_TRUSTED_DISTRIBUTION=1`)
+- `npm run validate:dmg-install`
+  - Mounts latest DMG (or a provided path), copies `IdleWatch.app` into a temp Applications-like folder, then validates launcher dry-run schema from the copied app.
+  - Before launch dry-run, runs `scripts/validate-packaged-artifact.mjs` against mounted `IdleWatch.app` (`IDLEWATCH_ARTIFACT_DIR` override) so commit/dirty-state staleness is caught before expensive runtime checks.
+  - Runs OpenClaw-enabled dry-run first and retries up to `IDLEWATCH_DRY_RUN_TIMEOUT_MAX_ATTEMPTS` with increasing timeout (`+IDLEWATCH_DRY_RUN_TIMEOUT_RETRY_BONUS_MS`) plus optional backoff (`IDLEWATCH_DRY_RUN_TIMEOUT_BACKOFF_MS`) before a disabled-usage launchability pass (`IDLEWATCH_OPENCLAW_USAGE=off`).
+  - Uses bounded attach/detach timeouts and emits the last ~60 lines of failed attempt output to make hangs diagnosable.
+  - Uses shared noise-tolerant JSON extraction from `scripts/lib/telemetry-row-parser.mjs`, so ANSI/control frames in launcher output do not mask valid telemetry rows.
+- `npm run validate:packaged-bundled-runtime`
+  - By default, rebuilds the app with `IDLEWATCH_NODE_RUNTIME_DIR` pointed at the current Node runtime, validates the generated package metadata, then executes `IdleWatch.app/Contents/MacOS/IdleWatch --dry-run` in a PATH-scrubbed environment to confirm bundled runtime/path-resolution still works when the host PATH does not provide a Node binary.
+  - If `IDLEWATCH_SKIP_PACKAGE_MACOS=1`, the validator reuses an existing `dist/IdleWatch.app` artifact instead of repackaging (useful for repeated CI/test runs).
+    - Reuse mode now verifies the reused artifact is compatible with the current workspace (and, when strict mode is enabled, requires bundled runtime metadata); when strict mode is off it can still run launchability checks for non-bundled artifacts via fallback PATH logic.
+    - In fallback mode, the script checks Node presence with an absolute-path lookup (`which node`) to avoid shell hash-table false-positives in temporary PATH checks.
+    - If checks fail, rerun with a fresh package (`npm run package:macos` or remove `IDLEWATCH_SKIP_PACKAGE_MACOS`).
+  - Non-bundled artifacts can still be validated in host-PATH launchability mode using `IDLEWATCH_USE_ORIGINAL_PATH_FOR_NON_BUNDLED=1` (this remains the default fallback in reuse mode).
+  - The validation is timeout-bound via `IDLEWATCH_DRY_RUN_TIMEOUT_MS`, retry count (`IDLEWATCH_DRY_RUN_TIMEOUT_MAX_ATTEMPTS`), and incremental timeout/backoff (`IDLEWATCH_DRY_RUN_TIMEOUT_RETRY_BONUS_MS`, `IDLEWATCH_DRY_RUN_TIMEOUT_BACKOFF_MS`).
+  - It validates required sample fields (`host`, `ts`, and `fleet`/`source` contract) while preventing false positives from log banners.
+  - If the OpenClaw-enabled dry-run path does not emit telemetry within the timeout window, the script retries with extended timeout and then falls back to `IDLEWATCH_OPENCLAW_USAGE=off` for deterministic launchability checks.
+  - In `IDLEWATCH_OPENCLAW_USAGE=off`, schema validation expects `source.usage=disabled` and `usageFreshnessState=disabled`, so launchability checks remain deterministic even without local OpenClaw CLI availability.
+  - Failed attempt output is preserved in temp attempt logs and the last 60 lines are echoed to stderr, so intermittent startup hangs are easier to diagnose.
+  - Applies the same shared noise-tolerant JSON extractor used by other validators, keeping schema checks robust when runtime output includes ANSI/control frames.
+- `npm run validate:packaged-bundled-runtime:reuse-artifact`
+  - Fast path for validation pipelines that already ran `package:macos` (or a previous packaging step): reuses the same artifact and skips repackaging while keeping all launchability assertions.
+- Clean-machine verification note:
+  - For external QA, treat `validate:packaged-bundled-runtime` output plus a fresh `validate:dmg-install` smoke run from a separate macOS account/environment as your clean-machine gate for end-user install friction.
+  - This script is self-contained (Node-only) and does not depend on host Python tooling.
+
+
+## CI integration
+
+- Baseline packaging smoke: `.github/workflows/ci.yml` (`macos-packaging-smoke` job; includes bundled-runtime launcher validation via `npm run validate:packaged-bundled-runtime` (or `...:reuse-artifact` when `dist/` is prebuilt), packaged app telemetry schema check via `npm run validate:packaged-dry-run-schema:reuse-artifact`, packaged usage-health validation via `npm run validate:packaged-usage-health:reuse-artifact`, and OpenClaw robustness coverage via `npm run validate:packaged-openclaw-robustness:reuse-artifact` (age-SLO, alert-rate transitions, probe-noise resilience, and OpenClaw release checks), plus checksum validation via `npm run validate:dmg-checksum` and DMG install validation via `npm run validate:dmg-install`).
+- All packaged `:reuse-artifact` wrappers run `npm run validate:packaged-artifact` first, which checks `dist/` launcher presence, metadata integrity, source-commit freshness, and (by default) clean/dirty working-tree parity so mismatched build contexts fail fast with a rebuild hint.
+- Core validation coverage also runs `npm run validate:openclaw-release-gates` (host health/stats/cache guardrail) and `npm run validate:packaged-openclaw-release-gates:reuse-artifact` (which bundles `validate:packaged-usage-health:reuse-artifact`, `validate:packaged-openclaw-stats-ingestion:reuse-artifact`, and `validate:packaged-openclaw-cache-recovery-e2e:reuse-artifact`) to guard both host and packaged OpenClaw-health behavior, `stats --json` fallback path, and packaged recovery behavior when probe output is noisy or stale. `validate:openclaw-stats-ingestion` and packaged stats ingestion now explicitly cover `status.result`, `status.current`, and timestamp-alias variants (`usage_ts_ms`, `usage_timestamp_ms`, `updated_at_ms`, `ts_ms`) used in the wild.
+- For local scripted workflows, `npm run validate:openclaw-release-gates:all` (host-only on non-macOS, adds packaged reuse on macOS) plus `npm run validate:packaged-openclaw-release-gates:all` provide staged host+packaged coverage in one command.
+
+- Trusted signed/notarized release path: `.github/workflows/release-macos-trusted.yml`
+
+Trusted release workflow enforces stronger OpenClaw verification and expects these repository secrets:
+
+- `MACOS_CODESIGN_IDENTITY`
+- `APPLE_DEVELOPER_ID_APP_P12_BASE64`
+- `APPLE_DEVELOPER_ID_APP_P12_PASSWORD`
+- `APPLE_BUILD_KEYCHAIN_PASSWORD`
+- `APPLE_NOTARY_KEY_ID`
+- `APPLE_NOTARY_ISSUER_ID`
+- `APPLE_NOTARY_API_KEY_P8`
+
+When present, the workflow imports a temporary build keychain, signs `IdleWatch.app`, notarizes/staples the DMG, and uploads `IdleWatch-*-signed.dmg`.
+
+Release policy gate:
+- Trusted release workflow enforces OpenClaw resilience in two stages before artifact upload:
+  - `npm run validate:openclaw-release-gates` (host validation)
+  - `npm run validate:packaged-openclaw-release-gates:reuse-artifact` (runs `validate:packaged-usage-health:reuse-artifact`, `validate:packaged-openclaw-stats-ingestion:reuse-artifact`, and `validate:packaged-openclaw-cache-recovery-e2e:reuse-artifact` against the signed artifact).
+  In release mode the packaged checks run via the wrapper’s `IDLEWATCH_SKIP_PACKAGE_MACOS=1`, and enforce OpenClaw usage presence by default (`IDLEWATCH_REQUIRE_OPENCLAW_USAGE=1` unless explicitly disabled). Set `0|false|off|no` to disable and `1|true|on|yes` to force on.
+- Trusted release workflow additionally enforces `IDLEWATCH_MAX_OPENCLAW_USAGE_AGE_MS=300000` so packaged rows fail if usage age is excessively stale at validation time.
+- Packaging scripts now auto-enable strict trusted requirements on CI tag refs (`refs/tags/*`) to prevent accidental unsigned release artifacts; set `IDLEWATCH_ALLOW_UNSIGNED_TAG_RELEASE=1` only for deliberate break-glass exceptions.
+- Packaged validators default to packaging a fresh app unless reuse mode is requested. `validate:packaged-dry-run-schema`, `validate:packaged-usage-age-slo`, and `validate:packaged-usage-health` still auto-run `package:macos` first; their `:reuse-artifact` counterparts assume a prebuilt artifact and set `IDLEWATCH_SKIP_PACKAGE_MACOS=1` to validate the already-built binary directly.
+- Reuse-mode validation uses the artifact preflight in `scripts/validate-packaged-artifact.mjs`, so stale/foreign artifacts now fail fast before expensive dry-run execution.
+

package/docs/packaging/macos-launch-agent.md

@@ -0,0 +1,70 @@
+# macOS LaunchAgent Setup
+
+Run IdleWatch as a background service that starts automatically at login.
+
+## Prerequisites
+
+- IdleWatch.app installed (typically `/Applications/IdleWatch.app`)
+- macOS 12+ (Monterey or later)
+- Optional: Firebase credentials configured via `quickstart`
+
+## Install
+
+```bash
+npm run install:macos-launch-agent
+```
+
+This creates a `launchd` plist at `~/Library/LaunchAgents/com.idlewatch.agent.plist` and loads it immediately.
+
+### Configuration
+
+All settings are optional environment variables set **before** running the install script:
+
+| Variable | Default | Description |
+|---|---|---|
+| `IDLEWATCH_APP_PATH` | `/Applications/IdleWatch.app` | Path to installed app |
+| `IDLEWATCH_APP_BIN` | `$APP_PATH/Contents/MacOS/IdleWatch` | Launcher binary |
+| `IDLEWATCH_LAUNCH_AGENT_LABEL` | `com.idlewatch.agent` | Plist label |
+| `IDLEWATCH_LAUNCH_AGENT_LOG_DIR` | `~/Library/Logs/IdleWatch` | Log output directory |
+| `IDLEWATCH_INTERVAL_MS` | `10000` | Collection interval (min 60s for StartInterval) |
+
+### Custom app path
+
+```bash
+IDLEWATCH_APP_PATH="$HOME/Applications/IdleWatch.app" npm run install:macos-launch-agent
+```
+
+## Uninstall
+
+```bash
+npm run uninstall:macos-launch-agent
+```
+
+Removes the plist and unloads the agent from launchd.
+
+## Logs
+
+```bash
+# stdout
+tail -f ~/Library/Logs/IdleWatch/idlewatch.out.log
+
+# stderr
+tail -f ~/Library/Logs/IdleWatch/idlewatch.err.log
+```
+
+## Verify
+
+```bash
+# Check if running
+launchctl print gui/$(id -u)/com.idlewatch.agent
+
+# Quick health check
+/Applications/IdleWatch.app/Contents/MacOS/IdleWatch --dry-run --json | python3 -m json.tool
+```
+
+## Troubleshooting
+
+- **Agent not starting:** Check `~/Library/Logs/IdleWatch/idlewatch.err.log` for errors.
+- **Permission denied:** Ensure the binary is executable: `chmod +x /Applications/IdleWatch.app/Contents/MacOS/IdleWatch`
+- **Stale telemetry:** If `openclawUsageAgeMs` stays high, OpenClaw may be idle — this is expected behavior (see `docs/telemetry/idle-stale-policy.md`).
+- **Reinstall after update:** After installing a new IdleWatch.app, re-run the install script to reload the agent.