# Mac Optimizer

Modular macOS system health toolkit. Runs read-only audits first, then recommends actions with user consent.

## Module Routing

| Keywords | Module |
|---|---|
| brew, homebrew, npm, nvm, pip, pyenv, packages, update, outdated | packages |
| path, shell, zshrc, environment, env, config, symlink | environment |
| security, firewall, sip, gatekeeper, filevault, ports, ssh | security |
| cache, cleanup, clean, logs, clutter, disk space, free space, trash | cleanup |
| cpu, memory, ram, disk, battery, processes, resources, slow | resources |
| doctor, audit, health, full check, everything, system check | doctor (all) |

Default to **doctor** when the request is ambiguous.

## Execution Model

Every module follows this flow:

1. **Audit** — run the module's script (read-only)
2. **Report** — parse JSON output, present findings as a severity-ranked table
3. **Recommend** — list available actions grouped by risk
4. **Consent** — ask user which actions to approve (per-category, per-item for risky)
5. **Act** — execute only approved actions

## Running Audit Scripts

All scripts are in `scripts/` and output JSON lines to stdout:

```bash
bash scripts/audit_packages.sh
bash scripts/audit_environment.sh
bash scripts/audit_security.sh
bash scripts/audit_cleanup.sh
bash scripts/audit_resources.sh
```

Each JSON line has: `{"module":"...","severity":"...","finding":"...","action":"...","details":"..."}`

Severity levels: `critical` > `warning` > `info`

If a script exits non-zero, report the error and continue with other modules.

## Running Cleanup

```bash
bash scripts/cleanup_execute.sh --help          # See all targets
bash scripts/cleanup_execute.sh --dry-run <targets>   # Preview (default)
bash scripts/cleanup_execute.sh --execute <targets>    # Actually clean
```

**Always run --dry-run first and show the user what will happen before --execute.**

## Doctor Mode Workflow

1. Run all 5 audit scripts sequentially, collect all JSON findings
2. Parse and group findings by severity (critical first, then warning, then info)
3. Present unified report table to the user
4. **STOP and ask**: "Which actions would you like me to perform? You can approve by category (e.g., 'update packages and clean caches') or review each item."
5. Execute only approved actions
6. Present final summary of actions taken

## Safety Rules

- **Never execute cleanup without explicit user approval**
- **Always show sizes before deleting anything**
- **Security module is read-only** — present findings and remediation guidance only
- **Back up shell configs** before modifying: `cp ~/.zshrc ~/.config/mac-optimizer-backups/.zshrc.$(date +%s)`
- **Process deny-list**: never suggest killing `kernel_task`, `launchd`, `WindowServer`, `loginwindow`, `mds`, `mds_stores`, `opendirectoryd`, `coreaudiod`, `SystemUIServer`, `Finder`, `Dock`
- **No sudo by default** — if an action needs sudo, state why and ask first
- Docker cleanup uses `docker system prune`, never direct file deletion

## Report Format

Present findings as a markdown table:

```
### Critical
| Module | Finding | Recommended Action |
|---|---|---|
| security | Firewall disabled | Enable in System Settings |

### Warning
| Module | Finding | Recommended Action |
|---|---|---|

### Info
| Module | Finding | Recommended Action |
|---|---|---|
```

## Reference Files

- **references/packages.md** — package manager update strategies and commands
- **references/security-checks.md** — security benchmarks and remediation guidance
- **references/cleanup-targets.md** — full list of cleanup paths with risk ratings