windowsweep 1.0.1 → 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,74 @@ 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

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.1` |
+| **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** | ~81 kB packed · ~273 kB unpacked · 38 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,7 +120,7 @@ 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** - 114 checks prove the guards on your machine with a real junction, a 400-character path and
+- **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.
 
@@ -222,10 +223,16 @@ comes back but costs minutes, *Recycle Bin* is recoverable until you empty it (`
 | 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,18 +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.1`** - `--yes` never selects personal or project items; installers refuse under npx;
-exit 130 from the engine; documentation fixes.
+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>

package/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

package/lib/actions.ps1

@@ -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/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.1'
+$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.'
@@ -55,6 +55,10 @@ $Script:WS_SECTIONS = @(
   @{ 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/scan.ps1

@@ -16,10 +16,11 @@ function New-Target {
 }
 
 function Get-AllTargets {
-  <# .SYNOPSIS Collect every declared target from the loaded modules (Get-Targets00 .. Get-Targets21). #>
+  <# .SYNOPSIS Collect every declared target from the loaded modules: one Get-TargetsNN per catalogue row.
+     Driven by WS_SECTIONS, never a literal range, so a new section is reachable the moment it is declared. #>
   $all = @()
-  for ($i = 0; $i -le 21; $i++) {
-    $fn = 'Get-Targets{0:00}' -f $i
+  foreach ($s in $Script:WS_SECTIONS) {
+    $fn = 'Get-Targets{0:00}' -f $s.Id
     if (Get-Command $fn -ErrorAction SilentlyContinue) { $all += @(& $fn) }
   }
   return $all
@@ -57,7 +58,12 @@ function Show-ScanTable {
       $paths = @(Resolve-TargetPaths $t)
       if ($paths.Count -eq 0) { Write-UiLine ("  {0,-46} {1,10}  {2}" -f $t.Label, 'absent', $t.Path) 'DarkGray'; continue }
       $bytes = [long]0
-      foreach ($p in $paths) { $bytes += Get-DirectoryBytes $p }
+      foreach ($p in $paths) {
+        # Sized once per path: a second Get-DirectoryBytes pass for --json would walk every target twice.
+        $b = [long](Get-DirectoryBytes $p)
+        $bytes += $b
+        if ($Script:WS.JsonMode) { $Script:WS.ScanTargets += [ordered]@{ section = $t.Section; label = $t.Label; path = $p; bytes = $b } }
+      }
       $secTotal += $bytes
       $shown = $t.Path
       if ($paths.Count -gt 1) { $shown = "$($t.Path)  ($($paths.Count) matches)" }

package/lib/ui.ps1

@@ -159,9 +159,13 @@ function Read-Line {
 }
 
 function Confirm-Ui {
-  <# .SYNOPSIS y/N prompt. --yes auto-confirms (unless -NoAutoYes); non-interactive runs answer no. #>
-  param([string] $Prompt = 'Proceed?', [string] $Default = 'n', [switch] $NoAutoYes)
+  <# .SYNOPSIS y/N prompt. --yes auto-confirms (unless -NoAutoYes); non-interactive runs answer no.
+     -ScriptedOk: the prompt that follows an explicit --select / --select-file choice. The selection IS the
+     person's decision, so it answers this one question - and only when the preceding prompt really was
+     answered from a script (LastSelectionScripted), never merely because the flag was passed. #>
+  param([string] $Prompt = 'Proceed?', [string] $Default = 'n', [switch] $NoAutoYes, [switch] $ScriptedOk)
   $ws = $Script:WS
+  if ($ScriptedOk -and $ws.LastSelectionScripted) { Write-Warn "[scripted selection] $Prompt - yes (--select / --select-file)"; return $true }
   if ($ws.Yes -and -not $NoAutoYes) { Write-UiLine ("    [auto-yes] $Prompt") 'DarkGray'; return $true }
   if (-not $ws.Interactive) {
     Write-Note "non-interactive session: '$Prompt' answered no (pass --yes to confirm in batch)"
@@ -188,17 +192,53 @@ function Confirm-Typed {
 
 function Read-MultiSelect {
   <# .SYNOPSIS Parse "1,3,5-7" / all / none into a sorted unique list of 1-based indexes.
-     --yes answers "all" only for callers that do not pass -NoAutoYes. The personal and project pickers pass
-     it, so under --yes they still ask when a console is present and select nothing when it is not. #>
-  param([int] $Total, [switch] $NoAutoYes)
+     Order of answers: a --select-file path list matched against -Candidates, then the next queued --select
+     list, then --yes (only for callers that do not pass -NoAutoYes), then the console, then nothing.
+     --yes NEVER selects for the personal and project pickers: they pass -NoAutoYes, so under --yes they
+     still ask when a console is present and select nothing when it is not. #>
+  param([int] $Total, [switch] $NoAutoYes, [string[]] $Candidates = @())
+  $ws = $Script:WS
+  $ws.LastSelectionScripted = $false
   if ($Total -le 0) { return @() }
-  if ($Script:WS.Yes -and -not $NoAutoYes) { return @(1..$Total) }
-  if (-not $Script:WS.Interactive) { Write-Note 'non-interactive session: nothing selected (a person has to pick these)'; return @() }
+  if ($ws.SelectPaths.Count -gt 0 -and $Candidates.Count -gt 0) {
+    $picked = @(Resolve-SelectedPaths -Candidates $Candidates)
+    $ws.LastSelectionScripted = $true
+    Write-Info ("--select-file matched $($picked.Count) of $Total candidate(s)")
+    return $picked
+  }
+  if ($ws.SelectQueue.Count -gt 0) {
+    $spec = [string]$ws.SelectQueue[0]
+    $ws.SelectQueue = @($ws.SelectQueue | Select-Object -Skip 1)
+    $picked = @(ConvertTo-IndexList -Text $spec -Total $Total)
+    $ws.LastSelectionScripted = $true
+    Write-Info ("--select '$spec' -> $($picked.Count) of $Total item(s)")
+    return $picked
+  }
+  if ($ws.Yes -and -not $NoAutoYes) { return @(1..$Total) }
+  if (-not $ws.Interactive) { Write-Note 'non-interactive session: nothing selected (a person has to pick these)'; return @() }
   Write-UiLine "  Selection: 1,3,5-10 | all | none (Enter = none)" 'DarkGray' -NoLog
   $reply = Read-Line ("  Select items (1..$Total): ")
   return (ConvertTo-IndexList -Text $reply -Total $Total)
 }
 
+function Resolve-SelectedPaths {
+  <# .SYNOPSIS Match the --select-file lines against this prompt's candidate paths, case-insensitively.
+     Returns 1-based indexes into $Candidates. A line matching nothing here is reported once and skipped:
+     the same file is offered to every prompt, so an unmatched line is normal and never fatal. #>
+  param([string[]] $Candidates)
+  $set = New-Object System.Collections.Generic.SortedSet[int]
+  $matched = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  for ($i = 0; $i -lt $Candidates.Count; $i++) {
+    foreach ($want in $Script:WS.SelectPaths) {
+      if ([string]$Candidates[$i] -eq $want) { $null = $set.Add($i + 1); $null = $matched.Add($want) }
+    }
+  }
+  foreach ($want in $Script:WS.SelectPaths) {
+    if (-not $matched.Contains($want)) { Write-Note "--select-file: no candidate here matches $want" }
+  }
+  return @($set)
+}
+
 function ConvertTo-IndexList {
   <# .SYNOPSIS Pure parser behind Read-MultiSelect (kept separate so the self-test can exercise it). #>
   param([string] $Text, [int] $Total)