docs(mac-ops): Add worked-examples.md reference

Three end-to-end diagnostic walkthroughs showing the skill in practice:

  Example 1: "Mac is slow and hot"
            health-audit → spotlight-status + wake-reasons
            Reveals mds_stores reindex + Power Nap wake pattern.
            Fix: mdutil -E + System Settings power options.

  Example 2: "Can't share screen on Zoom"
            tcc-audit -a zoom --denied
            Reveals kTCCServiceScreenCapture denial.
            Fix: tccutil reset ScreenCapture us.zoom.xos

  Example 3: "Disk full but I deleted everything"
            storage-pressure -v /
            Reveals 42 local TM snapshots + 87 GB user caches.
            Fix: tmutil thinlocalsnapshots / + brew cleanup -s

Each walkthrough shows symptom → script → signal in output → fix.
Patterns to recognize for the most common modern Mac complaints.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mods",
-  "version": "2.7.5",
+  "version": "2.7.6",
   "description": "Custom commands, skills, and agents for Claude Code - session continuity, 23 expert agents, 78 skills, 2 commands, 6 rules, 4 hooks, 13 output styles, modern CLI tools",
   "author": "0xDarkMatter",
   "repository": "https://github.com/0xDarkMatter/claude-mods",

README.md

@@ -22,6 +22,9 @@ From Python async patterns to Rust ownership models, from AWS Fargate deployment
 
 ## Recent Updates
 
+**v2.7.6** (May 2026)
+- 🩺 **`mac-ops` worked examples** - Added `worked-examples.md` reference with three end-to-end diagnostic walkthroughs: "Mac is slow and hot" (Spotlight reindex + Power Nap wake pattern), "Can't share screen on Zoom" (TCC denial after macOS update — the canonical case for `tccutil reset ScreenCapture`), and "Disk full but I deleted everything" (APFS local snapshots + cache directories). Each walkthrough shows the symptom, the script sequence, the actual signal in output, and the fix command. Useful as recognition patterns for the most common modern Mac complaints. Total: 22 scripts, 11 reference docs, 6,564 lines.
+
 **v2.7.5** (May 2026)
 - 🩺 **`mac-ops` bluetooth + fonts** - Added `bluetooth-audit.sh` (paired devices, connection state, recent connect/disconnect events, BT-driven wake settings — useful for "AirPods keep dropping" and "Magic Mouse cursor stutter" diagnoses) and `font-audit.sh` (font directory inventory across system/user/Adobe locations, fontd CPU + recent errors, duplicate font filename detection — font conflicts crash Office and Adobe apps). Total: 22 scripts, 10 reference docs, 6,355 lines.
 

skills/mac-ops/references/worked-examples.md

@@ -0,0 +1,209 @@
+# Worked Examples
+
+Three end-to-end diagnostic scenarios run through mac-ops. Each shows the symptom, the script sequence, the actual signal in the output, and the fix. Treat these as patterns to recognize — they cover the most common Mac complaints in 2026.
+
+## Example 1: "My Mac is slow and feels hot"
+
+### Symptom
+
+User reports: "Mac is sluggish. Fans run constantly even when I'm not doing anything. Battery drains faster than it used to."
+
+### Diagnostic sequence
+
+```bash
+scripts/health-audit.sh --days 7
+```
+
+Expected verdict pattern:
+
+```
+=== 5. RESOURCE PRESSURE (snapshot) ===
+  Top 5 by CPU%:
+     63.2% [  582] mds_stores
+     21.4% [  328] mds
+     18.1% [    367] WindowServer
+     ...
+[WARN] mds_stores CPU :: 63.2% — sustained spike?
+
+=== 6. WAKE PATTERN (last 24h) ===
+[WARN] Wakes in pmset log (full history) :: 1247 — drill with wake-reasons.sh
+```
+
+Two signals: heavy Spotlight + lots of wakes. Drill:
+
+```bash
+scripts/spotlight-status.sh
+scripts/wake-reasons.sh --since 7d
+```
+
+Spotlight typically shows one of three causes:
+- **Heavy ongoing reindex** (new external volume mounted recently)
+- **Indexing a path it shouldn't** (large dev folders, node_modules, .git)
+- **Corrupt index** (mds_stores spinning on the same file forever)
+
+For the third case, the fix is brutal but effective:
+
+```bash
+sudo mdutil -E /                  # nuke + rebuild index
+```
+
+Plan for 1-4 hours of high mds_stores CPU after this; it's the rebuild. After that, idle CPU should return.
+
+Wake-reasons typically shows:
+
+```
+rtc scheduled   |  115 |  11%  (rtc/Maintenance)    ← Power Nap
+wifi/bluetooth  |  111 |  11%  (wlan/)               ← Wi-Fi proximity wake
+push-svc wake   |   76 |   7%  (rtc/SleepService)   ← push notification maintenance
+```
+
+The fix is in System Settings → Battery → Options:
+- Power Nap: Off (especially on battery)
+- Wake for network access: Off
+
+### Why this presents as "slow + hot"
+
+When a Mac wakes for "maintenance" hundreds of times overnight, the SoC spends fractional CPU keeping things warm. Daytime, the user perceives the heat lingering. Over a week, battery cycle count creeps up.
+
+---
+
+## Example 2: "I can't share my screen on Zoom anymore"
+
+### Symptom
+
+User reports: "Zoom worked yesterday. Today the screen-share button just doesn't do anything. No prompt appears."
+
+### Diagnostic sequence
+
+This is the textbook TCC denial. Bypassed via:
+
+```bash
+scripts/tcc-audit.sh -a zoom --denied
+```
+
+Expected output:
+
+```
+=== 2. PERMISSION GRANTS ===
+  service                      | client                                              | auth | last modified
+  -----------------------------|----------------------------------------------------|------|------------------------
+  kTCCServiceScreenCapture     | us.zoom.xos                                        | DENY | 2026-05-15 04:12:00
+```
+
+The DENY row tells the whole story: Zoom's Screen Recording permission was revoked. Common causes:
+- macOS update reset the grant
+- User clicked "Don't Allow" on a prompt
+- An MDM profile revoked it
+
+### Fix
+
+```bash
+tccutil reset ScreenCapture us.zoom.xos
+```
+
+Then re-open Zoom and attempt screen share — macOS prompts; user approves; permission persists.
+
+If the user is on a managed Mac and tccutil shows the grant has `auth_reason = 6` (MDM-set), they need to contact IT to amend the configuration profile.
+
+### Cross-verification
+
+```bash
+scripts/health-audit.sh
+```
+
+Rung 7 (TCC) will now show:
+
+```
+[WARN] User TCC grants (denied) :: 3 — drill with tcc-audit.sh
+```
+
+If that count was elevated before the Zoom fix and dropped after, you've confirmed the same kind of denial pattern.
+
+---
+
+## Example 3: "Macintosh HD is full but I deleted everything"
+
+### Symptom
+
+User reports: "About This Mac says I have 4 GB free out of 500 GB. I just emptied the Trash and the number didn't move."
+
+### Diagnostic sequence
+
+```bash
+scripts/storage-pressure.sh -v /
+```
+
+Expected output:
+
+```
+=== 1. df vs APFS reality ===
+  /dev/disk3s1s1   460Gi   456Gi   4.0Gi    99%   ...    /
+
+  diskutil info (APFS-aware):
+     Container Free Space:      103.0 GB    ← significantly more than df shows
+     APFS Snapshots are defined upon this APFS Volume.
+
+=== 2. APFS SNAPSHOTS ===
+[WARN] Local Time Machine snapshots :: 42 — purgeable space tied up
+
+=== 4. CACHE / TEMPORARY DIRECTORIES ===
+  User caches:
+    /Users/.../Library/Caches = 87 GB         ← Docker, browser caches, Spotify, etc.
+```
+
+Two reclaim paths:
+
+**Path A: Cull local Time Machine snapshots**
+
+```bash
+tmutil thinlocalsnapshots /          # macOS chooses which to delete
+# or:
+tmutil deletelocalsnapshots <name>   # specific snapshot
+```
+
+42 snapshots can easily hold 50+ GB. macOS auto-purges these under pressure, but the user perceives "disk full" before the purge fires.
+
+**Path B: Clear user caches**
+
+```bash
+rm -rf ~/Library/Caches/com.docker.docker     # Docker
+rm -rf ~/Library/Caches/com.spotify.client    # Spotify
+brew cleanup -s                                # Homebrew
+docker system prune -af --volumes              # Docker images + volumes
+```
+
+After either path, re-run `storage-pressure.sh`. Container Free Space and df should converge.
+
+### Why "About This Mac → Storage" lies
+
+That UI counts purgeable space as "Other" and rounds. APFS snapshots are user-deletable in principle but macOS won't expose them through the UI. `tmutil` and `diskutil apfs list` are the truth.
+
+---
+
+## General pattern: walking the ladder
+
+For any "my Mac is doing X weird" complaint:
+
+```bash
+# 1. Start with the orchestrator
+scripts/health-audit.sh
+
+# 2. The verdict block's "Next:" line points at the right drilldown.
+#    Run that. If multiple rungs failed, address rung 2-3 (storage,
+#    panics) BEFORE rung 6-7 (resource, TCC) since they're root-cause.
+
+# 3. Apply the minimum reversible fix.
+#    Disable startup items via safe-disable-startup.sh, not by deleting plists.
+#    Reset TCC grants via tccutil, not by editing TCC.db.
+#    Cull snapshots via tmutil, not by APFS snapshot deletion.
+
+# 4. Re-run health-audit. Confirm the verdict cleaned up.
+```
+
+The discipline: **verify before treating**. The data is always sitting in `log show`, `tmutil`, `tccutil`, `pmset -g log`. mac-ops just asks for it correctly.
+
+## Cross-references
+
+- The main skill flow: `SKILL.md`
+- For mac-ops vs windows-ops decisions: `mac-vs-windows-ops.md`
+- For each script's standalone use: that script's `--help`

skills/mac-ops/tests/run.sh

@@ -190,7 +190,7 @@ expected_refs=(
     storage-events.md recovery-patterns.md tcc-mechanics.md
     launchd-deep-dive.md panic-codes.md startup-mechanisms.md
     remote-diagnostics.md apple-silicon-specifics.md
-    mac-vs-windows-ops.md
+    mac-vs-windows-ops.md worked-examples.md
 )
 for r in "${expected_refs[@]}"; do
     assert "reference exists: $r" test -f "$root/references/$r"