windowsweep 1.0.0 → 1.1.0

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +1,199 @@
+# AI integration guide
+
+This is the contract an automated caller can rely on: what windowsweep promises, what it refuses, what it
+prints, and what it returns. It is written for an agent or a script rather than a person. For what the tool
+*is*, read the [README](https://github.com/aoneahsan/windowsweep#readme); for what each section touches, read
+[Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
+
+**windowsweep deletes files.** Every command below that is not marked read-only can remove data. There is no
+undo for caches. Treat a real run as an irreversible operation and preview it first.
+
+## The safe sequence
+
+```powershell
+npx windowsweep --self-test --no-color --no-report     # read-only: proves the guards on this machine
+npx windowsweep --scan --no-color --no-report          # read-only: every target and its size
+npx windowsweep --dry-run --all --yes --no-color       # writes nothing; reports what a real run would remove
+npx windowsweep --all --yes --no-color                 # the real safe batch
+```
+
+Add `--json` when a program reads the result. In that mode **stdout carries exactly one line, the JSON
+summary**, and every human-readable line goes to stderr. `--json` also implies `--quiet`.
+
+## What `--yes` covers, and what it never covers
+
+`--yes` auto-confirms **regenerable caches only**: sections 0-3, 5-10, 21, and 12-14 when the console is
+already elevated.
+
+| Never covered by `--yes` | Behaviour |
+|---|---|
+| Sections 17, 18, 19, 23 | The selection prompt appears even with `--yes` and defaults to none. With no console attached nothing is selected, and each asks a final question `--yes` does not answer. Only `--select` / `--select-file` supply a choice (see below) |
+| Sections 11, 15, 16, 20 | Deep. Refused in batch mode unless `--i-understand-deep` is also passed |
+| `--uninstall-data` | Always asks; `--yes` does not answer it |
+| `--purge-all` | From a console it asks for a typed `purge` once per run. In a batch run `--yes` is the confirmation |
+
+In batch mode (`--all`, `--only`, `--profile`) sections 17, 18, 19 and 23 are refused outright and reported as
+`refused`, unless a `--select` or `--select-file` choice was supplied. They need a person choosing items -
+in advance is fine, absent is not.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | A section failed, or the self-test found a failure |
+| 2 | Usage error, or an interactive mode was started without a console |
+| 3 | A section named in `--only` was refused, or an installer was started from `npx` |
+| 130 | Interrupted before the run finished (Ctrl-C) |
+
+## Flags that matter to automation
+
+| Flag | Effect |
+|---|---|
+| `--json` | One JSON line on stdout; everything else on stderr. Implies `--quiet` |
+| `--no-color`, `--ascii` | Disable colour and Unicode glyphs. Both are automatic when output is redirected |
+| `--no-report` | Skip the JSON report file; the session log is still written |
+| `--cleanup-logs` | Delete this run's log at exit; reports are kept |
+| `--quiet` | Fewer informational lines |
+| `--only L`, `--profile NAME`, `--exclude L` | Choose sections: `--only 1,3,5-7`; profiles `dev`, `minimal`, `cache-only`, `system`, `deep`, `audit` |
+| `--days N`, `--temp-days N` | Idle windows, default 100 and 3 |
+| `--developer`, `--not-developer` | Override the saved developer answer for this run |
+| `--scan-roots "P1;P2"`, `--exclude-path P` | Section 17 roots and exclusions |
+| `--logs-dir P`, `--reports-dir P` | Redirect this run's output |
+| `--select L`, `--select-file P` | Supply an interactive section's selection in advance, by index or by full path. The only way sections 17/18/19/23 run unattended |
+| `--notify` | A Windows notification when the run ends. Never changes the exit code, never writes to stdout |
+| `--list --json` | Print the section catalogue as one JSON line instead of the human table |
+| `--pwsh` | Launcher only: run the engine on PowerShell 7 |
+
+A non-interactive run with no saved developer answer defaults to developer mode **on**, the conservative
+choice, and says so.
+
+## The `--json` line
+
+```json
+{"tool":"windowsweep","version":"1.1.0","mode":"all","dry_run":false,"elevated":false,"developer":true,
+ "freed_bytes":0,"estimated_bytes":0,
+ "sections":[{"section":1,"status":"ran","freed_bytes":0}],
+ "candidates":[],"targets":[],
+ "refusals":[],"log_file":"...","report_file":"..."}
+```
+
+| Key | Meaning |
+|---|---|
+| `tool`, `version` | Always `windowsweep` and the running version |
+| `mode` | `all`, `only`, `scan`, `walkthrough`, `menu`, ... |
+| `dry_run`, `elevated` | The two booleans that change what a run does |
+| `developer` | `true`, `false`, or `null` in a mode that never resolves the question (`--scan`, `--list`) |
+| `freed_bytes` | Real bytes removed. `0` in a dry-run |
+| `estimated_bytes` | What a dry-run says a real run would remove. `0` in a real run |
+| `sections[]` | One entry per section attempted: `section`, `status`, `freed_bytes` |
+| `candidates[]` | What an interactive section offered: `section`, `index`, `path`, `bytes`, `idle_days`, `project`. Always present, empty when none were collected |
+| `targets[]` | Scan mode only: `section`, `label`, `path`, `bytes`. Always present, empty otherwise |
+| `refusals[]` | Human-readable reasons a section was refused in batch mode |
+| `log_file`, `report_file` | Absolute paths, or `null` under `--no-report` |
+
+`status` is one of `ran`, `dry-run`, `skipped`, `refused`, `failed`.
+
+## Where output lands
+
+| Item | Path |
+|---|---|
+| Session logs | `%USERPROFILE%\.windowsweep\logs\` |
+| JSON reports and exports | `%USERPROFILE%\.windowsweep\reports\` |
+| Debug and crash bundles | `%USERPROFILE%\.windowsweep\feedback\` |
+| Settings | `%USERPROFILE%\.windowsweep\config.json` |
+
+Override the root with `WINDOWSWEEP_HOME`, or the two folders with `--logs-dir` / `--reports-dir`
+(`WINDOWSWEEP_LOG_DIR` / `WINDOWSWEEP_REPORTS_DIR`). `WINDOWSWEEP_NO_COLOR`, `NO_COLOR` and
+`WINDOWSWEEP_ASCII` are honoured; `WINDOWSWEEP_SHELL=pwsh` selects PowerShell 7 through the Node launcher.
+
+The report file is schema-versioned JSON (`schema_version: 1`) with five top-level blocks: `credits`, `meta`
+(times, host, OS, PowerShell version, mode, the three flags, the idle windows, the launcher), `disk`
+(`before` and `after` snapshots per fixed drive), `steps` (one row per section with `status` and
+`freed_bytes`), and `totals`. `--export md|html|both [N|latest|all]` renders any report to Markdown or a
+self-contained HTML page without extra tools.
+
+## Elevation
+
+Sections 12-16 and 20 need Administrator rights. Without them the runner skips each with the exact command
+to run. `--elevate` relaunches the whole run through a UAC prompt: **a new elevated window opens with its own
+log and report**, and the original process waits and returns the child's exit code. That prompt cannot be
+answered by a script, so `--elevate` does not belong in an unattended context.
+
+## Guarantees
+
+- **No network calls of its own.** The self-test greps the source for HTTP and socket calls and fails the run
+  if it finds one. There is no telemetry and no update check.
+- **Every deletion passes one chokepoint** with a declared root, and is refused if it falls outside it.
+- **Protected paths are refused regardless of flags**: drive roots, Windows, Program Files, the profile root,
+  personal folders, credentials, toolchains, browser and editor state. No flag bypasses this.
+- **Junctions and symlinks are removed as links, never followed.**
+- **`--dry-run` and `--scan` write nothing** but the log and the report.
+- **Section numbers are a public contract.** 0-25 today; a section may be retired as a no-op, and a number is
+  never reused. Read `--list --json` rather than hard-coding the set.
+- **Zero runtime dependencies.** The package is PowerShell plus a Node launcher that uses only built-in
+  modules.
+
+## Do not
+
+- Do not run `npx windowsweep` from a directory that contains a checkout of this repository: npx resolves the
+  local package and the command fails. Run it from anywhere else.
+- Do not schedule `npx windowsweep` as a task action. The npx cache is evicted and the task breaks; install
+  globally and use `--install-task`, which refuses under npx for this reason.
+- Do not pipe `y` into the tool to force a personal section. Sections 17, 18, 19 and 23 are interactive by
+  design and a piped answer selects nothing - pass `--select` or `--select-file` instead, which is the
+  supported way and names exactly what goes.
+- Do not treat a green `--dry-run` as proof that a real run frees the same amount: an app that is open at run
+  time keeps its caches.
+
+## Driving the interactive sections (1.1.0+)
+
+Sections 17, 18, 19 and 23 refuse to run unattended, because they delete things a person should choose. Two
+flags supply that choice in advance, and either one lifts the refusal:
+
+```powershell
+# 1. list what the section would offer - deletes nothing
+npx windowsweep --only 17 --dry-run --json --no-color
+#    -> read .candidates[] from the single stdout line:
+#       { "section": 17, "index": 1, "path": "...", "bytes": 0, "idle_days": 400, "project": "..." }
+
+# 2. act on exactly the ones you chose
+npx windowsweep --only 17 --select 1,3            # by index, one list per prompt, in prompt order
+npx windowsweep --only 17 --select-file picks.txt # by full path, one per line, UTF-8, # comments allowed
+```
+
+Rules a caller can rely on:
+
+- **`--yes` alone still selects nothing.** It never has. Only `--select` / `--select-file` do.
+- The scripted selection also answers that section's final confirmation, so the run does not stall.
+- `--select` is repeatable and consumed one list per prompt; `--select-file` is offered to every prompt, so
+  a line that matches nothing in a given section is reported once and skipped.
+- Neither flag reaches a path the deletion chokepoint would otherwise refuse.
+
+## Reading the catalogue and following progress
+
+```powershell
+npx windowsweep --list --json
+```
+
+One stdout line: `sections[]` (`id`, `key`, `title`, `tier`, `admin`, `batch`, `dev`), `safe_batch`,
+`safe_batch_admin`, `profiles`, `walkthrough`, `walkthrough_admin`. Read it instead of hard-coding section
+numbers - they are frozen, but the set grows.
+
+In `--json` mode every section brackets itself on **stderr**:
+
+```text
+##windowsweep section=7 event=start
+##windowsweep section=7 event=end status=ran freed_bytes=4096
+```
+
+`status` is one of `ran`, `dry-run`, `skipped`, `refused`, `failed`. Scan mode also fills `targets[]`
+(`section`, `label`, `path`, `bytes`) in the final JSON line. `candidates` and `targets` are always present,
+empty when nothing was collected.
+
+## The read-only audits
+
+`--profile audit` runs sections 0, 21, 22, 24 and 25 and deletes nothing in any mode: the health report, disk
+usage, globally installed packages, installed programs not modified for `--days`+ days, and startup items.
+Sections 22, 24 and 25 print removal commands but never execute one, and section 25 never changes a startup
+entry. Section 24 reports "not modified", not "not used" - Windows keeps no reliable last-launched record.

package/CHANGELOG.md

@@ -7,6 +7,103 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ---
 
+## [Unreleased]
+
+## [1.1.0] - 2026-09-04
+
+### Added
+
+- **Section 22 - global packages audit.** Lists what npm, pnpm, yarn, bun and deno installed globally with
+  size and idle days, flags the ones no recent project references, and prints the exact uninstall command.
+  It never uninstalls anything and declares no deletable target: several of those roots are protected paths.
+- **Section 23 - orphaned application data.** Top-level folders under `%APPDATA%` and `%LOCALAPPDATA%` that
+  no installed program, Store package or running process claims and that nothing has touched for `--days`+
+  days. Interactive, Recycle Bin, and it **fails closed** - an unreadable uninstall registry produces zero
+  candidates rather than treating everything as orphaned. Every vendor folder another section already cleans
+  is excluded automatically, derived from the declared target list so the exclusions cannot drift.
+- **Section 24 - installed programs not modified for N+ days.** Report only, largest first, with
+  `winget uninstall --id` when one `winget list` call resolves the program and its own `UninstallString`
+  otherwise; Store apps listed separately. It never runs an uninstaller.
+- **Section 25 - startup items audit.** Run and RunOnce keys, both Startup folders, logon-triggered scheduled
+  tasks and `Win32_StartupCommand` in one table with each item's enabled state. It changes nothing.
+- **`--select L` and `--select-file P`.** Answer an interactive section's selection in advance, by index or
+  by full path. Either flag lets sections 17, 18, 19 and 23 run unattended - a person did choose - and the
+  selection answers that section's final confirmation. `--yes` alone still selects nothing.
+- **`--notify`.** A Windows notification when a run ends: a real toast on Windows PowerShell 5.1, a tray
+  balloon on PowerShell 7. It never changes the exit code and never writes to stdout. `--install-task` adds
+  it to the weekly task, so the Sunday run reports itself.
+- **`--json` additions.** `candidates[]` (what an interactive section offered) and `targets[]` (what scan
+  mode measured), both always present so a caller can rely on the shape, plus per-section progress lines on
+  stderr: `##windowsweep section=NN event=start|end status=<status> freed_bytes=<n>`.
+- **`--list --json`** prints the section catalogue - sections, tiers, batch policy, the safe batch, the
+  profiles and the walkthrough order - so a front end reads it instead of hard-coding it.
+- Section 1 gained the Hugging Face model cache (`~\.cache\huggingface\hub`, pruned by the idle gate,
+  developer-gated). Section 9 lists `wsreset.exe` as the Microsoft Store cache lever and offers it as a next
+  step rather than running it: `wsreset` has no silent mode and always opens the Store.
+- Section 17 recognises `.nx`, `.mypy_cache`, `.ruff_cache`, `.tox`, `.eggs`, `.output` and `.serverless`,
+  and treats `.cache` as an artefact only when a Gatsby or Parcel config sits beside it. `.venv`, `venv` and
+  `.terraform` are deliberately still excluded.
+- `docs/sections.md` records the candidate targets that are researched but **not** shipped because the
+  software is not installed on the build machine, and why `C:\Intel` was inspected and rejected.
+
+### Fixed
+
+- `Get-OrphanExclusions` returned its exclusion set as an unrolled array, whose `.Contains` is
+  case-sensitive, so a folder named `slack` would have slipped past the `Slack` entry. Found by a new check
+  before the section shipped.
+- Section 24's idle measurement used the newest of write, access and creation time. Last-access is live on
+  many systems, so every install folder read as touched today and the section could never report anything;
+  it now reads last-write only, which is what "not modified" means.
+
+### Changed
+
+- The target table is collected from the section catalogue instead of a literal `0..21` range, so a new
+  section is reachable by `--scan`, `--list-targets` and the safety checks the moment it is declared. The
+  menu's prompt range is derived the same way.
+- Profile `audit` is now `0, 21, 22, 24, 25`. The three new report sections are read-only and safe, but stay
+  out of `--all` so a cleanup run remains a cleanup run.
+- Self-test: 27 more checks (151 total) cover the catalogue, section 23's fail-closed gate and derived
+  exclusions, section 22 declaring nothing deletable, the scripted-selection flags, the `--json` and
+  catalogue shapes, the progress-line format, the global-package verdict, the startup-state rule and the
+  artefact list. Each was proved red against a planted defect before it was kept.
+- Self-test: ten more checks cover the argument parser, section lists, docker size text, the layout-guard leaf
+  test, the `--json` shape, superseded versions, the Chromium layout, workspace storage, stale artefacts and
+  the report exporters. `Test-KnownCacheLeaf` and `Get-JsonSummary` were split out of `Invoke-TargetList` and
+  `Write-JsonSummary` so the logic can be exercised directly; no behaviour changed.
+- `AI-INTEGRATION-GUIDE.md` ships in the npm package and is mirrored on the documentation site: the contract
+  an agent or a script relies on - the safe command sequence, what `--yes` never covers, exit codes, the
+  `--json` line, output paths and the guarantees.
+- A documentation site at `windowsweep-docs.aoneahsan.com` (Docusaurus on GitHub Pages), mirroring `docs/`.
+
+## [1.0.1] - 2026-09-03
+
+### Fixed
+
+- **Sections 17, 18 and 19 no longer pre-select every item under `--yes`.** In the walkthrough and the menu
+  with auto-yes on, section 17 could remove every listed build artefact without a person choosing one, and
+  18/19 pre-selected everything before their final question. The selection prompt now appears even with
+  `--yes`, defaults to none, and section 17's final confirmation is never auto-answered. Batch mode already
+  refused these sections and is unchanged. (RW-002)
+- Section 19's title no longer names Desktop; only Downloads is scanned. (RW-003)
+- Sections 18 and 19 report the tier `recycle` instead of `permanent` in `--list`. (RW-004)
+- `--purge-all` from a console asks you to type `purge` once per run, as documented; `--yes` remains the
+  confirmation in batch runs. (RW-005)
+- A running editor's VSIX download cache is cleared as documented: it is its own target without the
+  running-editor guard. (RW-006)
+- `--install-task` and `--install-alias` refuse to run under `npx` (exit 3) and print the global-install
+  steps; the npx cache is evicted and the task or alias would break later. (RW-007)
+- The engine exits 130 when a run is interrupted before it finished; previously only the Node launcher
+  did. (RW-008)
+- `--uninstall-data` always asks; `--yes` no longer removes your history unattended. (RW-010)
+
+### Changed
+
+- Internal rename `Write-Log` -> `Write-LogLine` (18 call sites) so PSScriptAnalyzer's
+  `PSAvoidOverwritingBuiltInCmdlets` passes under PowerShell 7 in CI. No behaviour change.
+- Self-test: four new checks prove the `--yes` asymmetry at the helper and at the section 17/18/19 call sites,
+  and that every picker call in `modules/` carries `-NoAutoYes` (114 checks).
+- Keywords trimmed to twelve (`temp-files` dropped). (RW-011)
+
 ## [1.0.0] - 2026-09-03
 
 First release. The Windows member of the cleanup family beside

package/README.md

@@ -13,7 +13,7 @@
 [![node](https://img.shields.io/node/v/windowsweep.svg)](https://nodejs.org)
 [![platform](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d4?logo=windows&logoColor=white)](https://github.com/aoneahsan/windowsweep#platform-support)
 
-[Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/README.md) · [npm](https://www.npmjs.com/package/windowsweep) · [GitHub](https://github.com/aoneahsan/windowsweep) · [Changelog](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md) · [Contributing](https://github.com/aoneahsan/windowsweep/blob/main/CONTRIBUTING.md) · [Support](https://github.com/aoneahsan/windowsweep/issues)
+[Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/README.md) · [AI Guide](https://github.com/aoneahsan/windowsweep/blob/main/AI-INTEGRATION-GUIDE.md) · [npm](https://www.npmjs.com/package/windowsweep) · [GitHub](https://github.com/aoneahsan/windowsweep) · [Changelog](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md) · [Contributing](https://github.com/aoneahsan/windowsweep/blob/main/CONTRIBUTING.md) · [Support](https://github.com/aoneahsan/windowsweep/issues)
 
 </div>
 
@@ -34,12 +34,12 @@ It is the Windows member of a family with [linux-cleanup](https://github.com/aon
 
 | | |
 |---|---|
-| **Version** | `1.0.0` |
+| **Version** | `1.1.0` |
 | **License** | MIT |
 | **Node** | `>=14` (launcher only) |
 | **Runtime** | Windows PowerShell 5.1 (built in) or PowerShell 7 |
 | **Platforms** | Windows 10 (1809+) and Windows 11 |
-| **Install size** | ~78 kB packed · ~263 kB unpacked · 37 files · no dependencies |
+| **Install size** | ~109 kB packed · ~366 kB unpacked · 44 files · no dependencies |
 | **Undo** | Recycle Bin for personal files; none for caches (they regenerate) |
 | **Status** | Stable · actively maintained |
 
@@ -102,8 +102,9 @@ security scanner or a registry cleaner. It reclaims disk space, nothing else.
 
 - **Developer mode** - one question on the first run. Yes keeps package, build and test-runner caches used in
   the last 100 days and the newest version of every versioned tool; no clears them completely.
-- **22 numbered sections** - from package-manager caches to Windows Update leftovers, each naming its paths
-  before it acts. Numbers are a public contract.
+- **26 numbered sections** - from package-manager caches to Windows Update leftovers, plus four read-only
+  audits (global packages, orphaned app data, idle programs, startup items), each naming its paths before it
+  acts. Numbers are a public contract.
 - **One deletion chokepoint** - refuses drive roots, Windows, Program Files, your profile root, personal
   folders, credentials, toolchains and browser or editor state; asserts every deletion sits inside its declared
   target; never follows a junction or symlink; handles paths beyond 260 characters; skips files another program
@@ -119,8 +120,8 @@ security scanner or a registry cleaner. It reclaims disk space, nothing else.
 - **Running-app guard** - an open browser, editor or app keeps its caches; the tool tells you which to close.
 - **Session reports** - schema-versioned JSON, exportable to Markdown or a self-contained HTML page, plus
   `--json` for scripts.
-- **Self-test** - proves the guards on your machine with a real junction, a 400-character path and a dry-run
-  fixture before you trust it.
+- **Self-test** - 151 checks prove the guards on your machine with a real junction, a 400-character path and
+  a dry-run fixture before you trust it.
 - **Offline by design** - zero network calls, no telemetry, no update check. Crash bundles stay on disk.
 
 <a id="platform-support"></a>
@@ -128,9 +129,9 @@ security scanner or a registry cleaner. It reclaims disk space, nothing else.
 
 | Platform | Supported | Notes |
 |---|---|---|
-| Windows 11 | ✅ | Windows PowerShell 5.1 or PowerShell 7 |
-| Windows 10 (1809 and later) | ✅ | The primary development target |
-| Windows Server 2019+ | ⚠️ | Uses nothing newer than 1809, but Server is not in the test matrix |
+| Windows 11 | ✅ | Same engine and PowerShell hosts; a real run on Windows 11 is on the verification list ([roadmap](https://github.com/aoneahsan/windowsweep/blob/main/remaining-work-summary.md)) |
+| Windows 10 (1809 and later) | ✅ | The primary development target; every real run so far |
+| Windows Server 2019+ | ⚠️ | Uses nothing newer than 1809; CI runs the self-test and a dry-run on Windows Server (`windows-latest`) on every push, but no real cleanup has been run on Server |
 | Linux | ❌ | `os: ["win32"]` makes npm refuse to install; use [linux-cleanup](https://github.com/aoneahsan/linux-cleanup) |
 | macOS | ❌ | Use [macleanup](https://github.com/aoneahsan/macleanup) |
 
@@ -195,8 +196,8 @@ section with `a` run / `s` skip / `q` quit and a running total.
 ### The sections
 
 **Tier** says what happens to the data: *report* deletes nothing, *rebuilds* comes back on its own, *slow*
-comes back but costs minutes, *Recycle Bin* is recoverable until you empty it, *permanent* is not, *config*
-changes a setting.
+comes back but costs minutes, *Recycle Bin* is recoverable until you empty it (`--list` shows this tier as
+`recycle`), *permanent* is not, *config* changes a setting.
 
 | # | Section | Tier | Admin | Batch |
 |---|---|---|:-:|---|
@@ -222,10 +223,16 @@ changes a setting.
 | 19 | Large stale personal files in Downloads | Recycle Bin | - | interactive |
 | 20 | Docker Desktop / WSL disk-image compaction | config | yes | deep |
 | 21 | Disk usage report | report | - | safe |
+| 22 | Global packages audit (npm, pnpm, yarn, bun, deno) - never uninstalls | report | - | safe · audit only |
+| 23 | Orphaned application data under AppData | Recycle Bin | - | interactive |
+| 24 | Installed programs not modified for N+ days - never uninstalls | report | - | safe · audit only |
+| 25 | Startup items audit - never changes them | report | - | safe · audit only |
 
 *Safe* sections run in `--all`; *opt-in* ones run when named in `--only` or a profile; *deep* ones also need
-`--i-understand-deep`; *interactive* ones never run unattended. Every section is documented in
-[Sections 0-21](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
+`--i-understand-deep`; *interactive* ones never run unattended unless you pass a selection. The three
+*audit only* sections are read-only and safe, but stay out of `--all` so a cleanup run is a cleanup run -
+`--profile audit` is where they live. Every section is documented in
+[Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
 
 ### Clean interactively
 
@@ -303,6 +310,8 @@ windowsweep [mode] [options]
 | `--scan-roots "P1;P2"`, `--exclude-path P` | auto | Section 17 roots and exclusions |
 | `--hiberfil off\|reduced\|keep` | ask | What section 15 does |
 | `--permanent` | off | Sections 18/19 delete instead of using the Recycle Bin |
+| `--select L`, `--select-file P` | off | Answer an interactive section's selection in advance, by index or by path - the one way sections 17/18/19/23 run unattended |
+| `--notify` | off | A Windows notification when the run ends |
 | `--json`, `--quiet`, `--no-color`, `--ascii`, `--no-report`, `--cleanup-logs` | off | Output and record controls |
 
 Every flag, exit code and environment variable:
@@ -403,16 +412,20 @@ More: [FAQ](https://github.com/aoneahsan/windowsweep/blob/main/docs/faq.md).
 | [Quick start](https://github.com/aoneahsan/windowsweep/blob/main/docs/quick-start.md) | running your first cleanup |
 | [Safety model](https://github.com/aoneahsan/windowsweep/blob/main/docs/safety-model.md) | you want every guarantee spelled out before deleting anything |
 | [Developer mode](https://github.com/aoneahsan/windowsweep/blob/main/docs/developer-mode.md) | you want to know what the first question changes |
-| [Sections 0-21](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md) | you want to know precisely what one section touches |
+| [Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md) | you want to know precisely what one section touches |
 | [CLI reference](https://github.com/aoneahsan/windowsweep/blob/main/docs/cli-reference.md) | you need an exact flag, exit code or variable |
 | [Admin sections and elevation](https://github.com/aoneahsan/windowsweep/blob/main/docs/admin-and-elevation.md) | before running the system profile or touching the hibernation file |
 | [Reports and logs](https://github.com/aoneahsan/windowsweep/blob/main/docs/reports-and-logs.md) | parsing the JSON or finding a log |
+| [AI integration guide](https://github.com/aoneahsan/windowsweep/blob/main/AI-INTEGRATION-GUIDE.md) | an agent or a script runs it for you |
 | [Troubleshooting](https://github.com/aoneahsan/windowsweep/blob/main/docs/troubleshooting.md) | something failed |
+| [Roadmap and remaining work](https://github.com/aoneahsan/windowsweep/blob/main/remaining-work-summary.md) | you want to know what is verified, what is planned (1.1, the docs site) and what is still open |
 
 <a id="changelog"></a>
 ## 🔄 Changelog&nbsp;[#](#changelog)
 
-Latest release: **`1.0.0`** - first release: 22 sections, developer mode, the deletion chokepoint, dry-run, reports.
+Latest release: **`1.1.0`** - four new sections (global packages, orphaned app data, idle programs, startup
+items), `--select` / `--select-file` so a script or a GUI can drive the interactive sections, `--notify`, and
+`candidates[]`, `targets[]`, progress lines and `--list --json` for machine callers.
 Full history: [CHANGELOG.md](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md).
 
 <a id="contributing"></a>
@@ -478,5 +491,5 @@ this tool deletes files, so review what it proposes before confirming.
 <a id="keywords"></a>
 ## 🏷️ Keywords&nbsp;[#](#keywords)
 
-*windows · cleanup · disk-cleanup · cache-cleanup · disk-space · temp-files · node-modules · npm-cache ·
+*windows · cleanup · disk-cleanup · cache-cleanup · disk-space · node-modules · npm-cache ·
 yarn-cache · developer-tools · powershell · cli · dry-run*

package/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

package/lib/actions.ps1

@@ -4,7 +4,7 @@
 $Script:WS_CHROMIUM_PROFILE_CACHES = @('Cache', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'GrShaderCache', 'ShaderCache', 'Service Worker\ScriptCache')
 $Script:WS_CHROMIUM_ROOT_CACHES = @('ShaderCache', 'GrShaderCache', 'GraphiteDawnCache', 'Crashpad\completed', 'Crashpad\reports', 'SwReporter')
 $Script:WS_ELECTRON_CACHES = @('Cache', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'GrShaderCache', 'ShaderCache', 'Service Worker\CacheStorage', 'Service Worker\ScriptCache', 'Crashpad\completed', 'Crashpad\reports')
-$Script:WS_EDITOR_CACHES = @('Cache', 'CachedData', 'CachedProfilesData', 'CachedExtensionVSIXs', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'Service Worker\CacheStorage', 'Service Worker\ScriptCache', 'Crashpad\completed', 'Crashpad\reports')
+$Script:WS_EDITOR_CACHES = @('Cache', 'CachedData', 'CachedProfilesData', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'Service Worker\CacheStorage', 'Service Worker\ScriptCache', 'Crashpad\completed', 'Crashpad\reports')
 $Script:WS_FIREFOX_CACHES = @('cache2', 'startupCache', 'thumbnails', 'jumpListCache', 'OfflineCache', 'shader-cache')
 
 function Get-ChromiumProfileDirs {
@@ -99,6 +99,13 @@ function Confirm-Section {
   return (Confirm-Ui -Prompt $Prompt -Default $Default)
 }
 
+function Test-KnownCacheLeaf {
+  <# .SYNOPSIS Second guard for the layout kinds: only a folder whose leaf name is a declared cache name may be cleared. #>
+  param([string] $Path)
+  $known = @($Script:WS_CHROMIUM_PROFILE_CACHES + $Script:WS_CHROMIUM_ROOT_CACHES + $Script:WS_ELECTRON_CACHES + $Script:WS_EDITOR_CACHES + $Script:WS_FIREFOX_CACHES | ForEach-Object { [IO.Path]::GetFileName($_) })
+  return ($known -contains [IO.Path]::GetFileName($Path))
+}
+
 function Invoke-TargetList {
   <# .SYNOPSIS Run every target with its mode under the dry-run, developer, purge and running-app policies. Returns bytes freed/estimated. #>
   param([pscustomobject[]] $Targets)
@@ -117,11 +124,7 @@ function Invoke-TargetList {
     if ($t.Kind -in 'chromium', 'firefox', 'electron', 'editor') {
       $mode = 'clear'
       # Second guard: a layout target may only ever clear a known cache folder, never a profile or app root.
-      $known = @($Script:WS_CHROMIUM_PROFILE_CACHES + $Script:WS_CHROMIUM_ROOT_CACHES + $Script:WS_ELECTRON_CACHES + $Script:WS_EDITOR_CACHES + $Script:WS_FIREFOX_CACHES | ForEach-Object { [IO.Path]::GetFileName($_) })
-      $paths = @($paths | Where-Object {
-          $leaf = [IO.Path]::GetFileName($_)
-          if ($known -contains $leaf) { $true } else { Write-Err "REFUSE (not a known cache folder for a $($t.Kind) layout): $_"; $false }
-        })
+      $paths = @($paths | Where-Object { if (Test-KnownCacheLeaf $_) { $true } else { Write-Err "REFUSE (not a known cache folder for a $($t.Kind) layout): $_"; $false } })
     }
     if ($ws.PurgeAll -and $mode -in 'prune', 'units') { $mode = 'clear' }
     if ($t.Dev -and $ws.Developer -eq $false -and $mode -in 'prune', 'units') { $mode = 'clear' }

package/lib/config.ps1

@@ -88,3 +88,12 @@ function Resolve-DeveloperMode {
   $ws.DeveloperSource = 'default'
   Write-Note 'developer question not asked (non-interactive run) - defaulting to developer mode ON, the conservative choice; pass --not-developer to override'
 }
+
+function Confirm-PurgeAllOnce {
+  <# .SYNOPSIS --purge-all from a console asks for a typed word once per run; --yes is the confirmation in batch runs. #>
+  $ws = $Script:WS
+  if (-not $ws.PurgeAll -or $ws.DryRun -or $ws.Yes) { return }
+  if (Confirm-Typed -Prompt 'FULL PURGE: --purge-all empties every cache target completely, including files you used yesterday.' -Word 'purge') { Write-Ok 'purge-all confirmed for this run'; return }
+  $ws.PurgeAll = $false
+  Write-Info 'purge-all declined - this run prunes by the idle window instead'
+}

package/lib/constants.ps1

@@ -4,7 +4,7 @@
 # Single source of truth for the version is package.json: the Node launcher exports it as
 # WINDOWSWEEP_VERSION. A direct checkout falls back to this literal; the version:check script
 # asserts the two never drift.
-$Script:WS_VERSION_FALLBACK = '1.0.0'
+$Script:WS_VERSION_FALLBACK = '1.1.0'
 
 $Script:WS_NAME = 'windowsweep'
 $Script:WS_TAGLINE = 'Safe-by-default Windows cleanup CLI - developer-aware, dry-run first, zero install via npx.'
@@ -29,7 +29,7 @@ $Script:WS_EXIT_INTERRUPT = 130
 
 # Section catalogue. Numbering is a public contract frozen at 1.0.0: a section may be retired
 # (kept as a no-op that says so) but a number is never reused for something else.
-#   Tier:  report | rebuilds | slow | permanent | config
+#   Tier:  report | rebuilds | slow | recycle | permanent | config
 #   Batch: safe (in --all) | optin (--only/--profile with --yes) | deep (needs --i-understand-deep)
 #          | interactive (never batch; dry-run/report allowed)
 $Script:WS_SECTIONS = @(
@@ -51,10 +51,14 @@ $Script:WS_SECTIONS = @(
   @{ Id = 15; Key = 'hiberfil';   Title = 'Hibernation file (off / reduced)';                         Tier = 'config';    Admin = $true;  Batch = 'deep';        Dev = $false; Fn = 'Invoke-Section15' }
   @{ Id = 16; Key = 'eventlogs';  Title = 'Clear Windows Event Logs - PERMANENT';                     Tier = 'permanent'; Admin = $true;  Batch = 'deep';        Dev = $false; Fn = 'Invoke-Section16' }
   @{ Id = 17; Key = 'projects';   Title = 'Stale project build artefacts (node_modules, dist, .next, target, ...)'; Tier = 'rebuilds'; Admin = $false; Batch = 'interactive'; Dev = $true; Fn = 'Invoke-Section17' }
-  @{ Id = 18; Key = 'partials';   Title = 'Partial / orphan downloads -> Recycle Bin';                Tier = 'permanent'; Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section18' }
-  @{ Id = 19; Key = 'large';      Title = 'Large stale personal files (Downloads, Desktop) -> Recycle Bin'; Tier = 'permanent'; Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section19' }
+  @{ Id = 18; Key = 'partials';   Title = 'Partial / orphan downloads -> Recycle Bin';                Tier = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section18' }
+  @{ Id = 19; Key = 'large';      Title = 'Large stale personal files (Downloads) -> Recycle Bin';    Tier = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section19' }
   @{ Id = 20; Key = 'vhdx';       Title = 'Docker Desktop / WSL disk image compaction (stops Docker + WSL)'; Tier = 'config'; Admin = $true; Batch = 'deep';    Dev = $true;  Fn = 'Invoke-Section20' }
   @{ Id = 21; Key = 'diskusage';  Title = 'Disk usage report (largest entries, drives, disk images)'; Tier = 'report';    Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section21' }
+  @{ Id = 22; Key = 'globals';    Title = 'Globally installed packages audit (npm, pnpm, yarn, bun, deno) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $true; Fn = 'Invoke-Section22' }
+  @{ Id = 23; Key = 'orphaned';   Title = 'Orphaned application data under AppData -> Recycle Bin';   Tier = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section23' }
+  @{ Id = 24; Key = 'programs';   Title = 'Installed programs not modified for N+ days - report only'; Tier = 'report';   Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section24' }
+  @{ Id = 25; Key = 'startup';    Title = 'Startup items audit (Run keys, Startup folders, logon tasks) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section25' }
 )
 
 # The safe batch run by --all. Admin sections 12 and 13 join it only when already elevated.
@@ -67,11 +71,11 @@ $Script:WS_PROFILES = @{
   'cache-only' = @(1, 2, 3, 6, 7, 8, 9)
   'system'     = @(12, 13, 14)
   'deep'       = @(0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 21)
-  'audit'      = @(0, 21)
+  'audit'      = @(0, 21, 22, 24, 25)
 }
 
 # Walkthrough order (interactive default mode). Admin sections are inserted when elevated.
-$Script:WS_WALKTHROUGH = @(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 17, 18, 19)
+$Script:WS_WALKTHROUGH = @(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 17, 18, 19, 23)
 $Script:WS_WALKTHROUGH_ADMIN = @(12, 13, 14)
 
 function Get-Section {

package/lib/log.ps1

@@ -29,7 +29,7 @@ function Initialize-Log {
   try { [IO.File]::WriteAllLines($ws.LogFile, $header) } catch { $ws.LogFile = $null }
 }
 
-function Write-Log {
+function Write-LogLine {
   <# .SYNOPSIS Append one timestamped line to the run log; never throws. #>
   param([string] $Text)
   $f = $Script:WS.LogFile

package/lib/safety.ps1

@@ -155,7 +155,7 @@ function Remove-TreeInternal {
     try {
       if ($isLink) {
         if ($isDir) { [IO.Directory]::Delete($e.FullName, $false) } else { [IO.File]::Delete($e.FullName) }
-        Write-Log ("removed link (not followed): " + (Remove-LongPrefix $e.FullName))
+        Write-LogLine ("removed link (not followed): " + (Remove-LongPrefix $e.FullName))
       } elseif ($isDir) {
         if (-not (Remove-TreeInternal -Path $e.FullName -Result $Result)) { $allClear = $false }
       } else {
@@ -206,24 +206,24 @@ function Remove-PathSafe {
     if ($isLink) {
       if ($isDir) { [IO.Directory]::Delete($lp, $false) } else { [IO.File]::Delete($lp) }
       $r.Removed = $true
-      Write-Log "removed link (not followed): $p$tag"
+      Write-LogLine "removed link (not followed): $p$tag"
     } elseif ($isDir) {
       $r.Removed = Remove-TreeInternal -Path $p -Result $r
       $r.Bytes = [math]::Max([long]0, $bytes - $r.SkippedBytes)
       if ($r.Skipped -gt 0) { Write-Note "$($r.Skipped) item(s) in use or inaccessible, left in place under $p" }
-      Write-Log ("removed dir: $p ($($r.Bytes) bytes, skipped $($r.Skipped))$tag")
+      Write-LogLine ("removed dir: $p ($($r.Bytes) bytes, skipped $($r.Skipped))$tag")
     } else {
       Remove-ReadOnlyAttribute $lp
       [IO.File]::Delete($lp)
       $r.Removed = $true; $r.Bytes = $bytes; $r.Files = 1
-      Write-Log "removed file: $p ($bytes bytes)$tag"
+      Write-LogLine "removed file: $p ($bytes bytes)$tag"
     }
     Add-Freed $r.Bytes
   } catch {
     $r.Skipped++
     $r.Reason = 'in use or access denied'
     Write-Note "in use or inaccessible, skipped: $p"
-    Write-Log "skip (locked): $p - $($_.Exception.Message)"
+    Write-LogLine "skip (locked): $p - $($_.Exception.Message)"
   }
   return $r
 }
@@ -272,7 +272,7 @@ function Remove-StaleFiles {
     } catch { $null = $_ }
   }
   Add-Freed $out.Freed
-  Write-Log ("pruned $($out.Files) files ($($out.Freed) bytes) idle $Days+ days from $root; skipped $($out.Skipped)")
+  Write-LogLine ("pruned $($out.Files) files ($($out.Freed) bytes) idle $Days+ days from $root; skipped $($out.Skipped)")
   Write-Ok ("$Label - pruned {0} in {1} files idle {2}+ days ({3} skipped in use)" -f (Format-Bytes $out.Freed), $out.Files, $Days, $out.Skipped)
   return $out
 }
@@ -405,7 +405,7 @@ function Send-ToRecycleBin {
     }
     $r.Removed = $true; $r.Bytes = $bytes
     Add-Freed $bytes
-    Write-Log "recycled: $p ($bytes bytes)"
+    Write-LogLine "recycled: $p ($bytes bytes)"
     Write-Ok ("moved to Recycle Bin: {0} ({1})" -f $p, (Format-Bytes $bytes))
   } catch {
     $r.Skipped++; $r.Reason = $_.Exception.Message
@@ -424,14 +424,14 @@ function Invoke-External {
     Write-DryRun "would run: $display"
     return [pscustomobject]@{ Ran = $false; ExitCode = 0; Output = @() }
   }
-  Write-Log "run${tag}: $display"
+  Write-LogLine "run${tag}: $display"
   $lines = @()
   try {
     $raw = & $FilePath @ArgumentList 2>&1
     foreach ($l in $raw) {
       $s = [string]$l
       $lines += $s
-      if (-not $Quiet) { Write-Note $s } else { Write-Log $s }
+      if (-not $Quiet) { Write-Note $s } else { Write-LogLine $s }
     }
     $code = $LASTEXITCODE
     if ($null -eq $code) { $code = 0 }
@@ -439,7 +439,7 @@ function Invoke-External {
     $lines += $_.Exception.Message
     $code = 1
   }
-  Write-Log "exit $code$tag : $display"
+  Write-LogLine "exit $code$tag : $display"
   return [pscustomobject]@{ Ran = $true; ExitCode = $code; Output = $lines }
 }