Update CHANGELOG for version 2.5.0, adding new commands and structured output options. Enhance CONTRIBUTING.md with validation instructions for PowerShell scripts. Revise README.md to clarify command functionalities and reporting features. Bump installer version to 2.5.0 in windo_install.ps1.

l28bit · l28bit · commit 93ecc78a0799 · 2026-04-01T20:07:40.000-05:00
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,14 @@
+name: Validate PowerShell
+on:
+  push:
+    branches: [ Genisis, main ]
+  pull_request:
+    branches: [ Genisis, main ]
+jobs:
+  validate:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate syntax
+        shell: pwsh
+        run: ./tools/Validate-Windo.ps1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,23 @@ All notable changes to WINDO are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [2.5.0] - 2026-04-01
+
+### Added
+
+- **Operator UX:** `windo help`, `windo last`, `windo stats`, `windo history [-n N]`, `windo report [-o path]` (local HTML audit summary under `%USERPROFILE%\Documents\windo\` by default).
+- **Structured output:** append `--json` or `-Json` to `version`, `doctor`, `integrity`, `verify`, `log`, `stats`, `history`, and `last` for script-friendly output.
+- **Trust / visibility:** explicit access-denied hints after failed runs; timeout path suggests checking tasks and installer (`_suggest_if_denied`).
+- **Maintainability:** `tools/Validate-Windo.ps1` (AST parse all shipping scripts), `docs/build.md` (modularization direction), `docs/branding.md` (admin-focused logo guidance), `.github/workflows/validate.yml`.
+
+### Changed
+
+- Installer and embedded `windo` function version **2.5.0**; usage text and last-command exclusions updated for new subcommands.
+
+### Security
+
+- No change to the elevation model (scheduled tasks, RunLevel Highest), DPAPI logging, hash chain, or manifest semantics. HTML/JSON outputs may contain sensitive command text; operators must handle files accordingly.
+
 ## [2.4.0] - 2026-04-01
 
 ### Added
@@ -29,5 +46,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Baseline described in repository history and under `versions/v2.3.0/`.
 
+[2.5.0]: https://github.com/l28bit/windo/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/l28bit/windo/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/l28bit/windo/releases/tag/v2.3.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,3 +23,7 @@ Submit a pull request with:
 - clear description
 - testing notes
 - security considerations
+
+## Validation
+
+Before opening a PR that changes PowerShell scripts, run 	ools/Validate-Windo.ps1 in PowerShell 7 (local) or rely on the GitHub Actions workflow.
diff --git a/README.md b/README.md
@@ -65,8 +65,13 @@ The canonical install snippet is also kept in `docs/releases/README_INSTALL_UPDA
 
 | Command | Purpose |
 |--------|---------|
+| `windo help` | Short usage reference. |
 | `windo <command…>` | Elevate and run the command via the task bridge. |
 | `windo !!` | Re-run the last stored elevated command. |
+| `windo last` | Show the last stored command text (no execution). |
+| `windo stats` | Summarize the encrypted audit log (counts, optional avg duration). |
+| `windo history [-n N]` | Compact recent commands (default last 50). |
+| `windo report [-o path]` | Write a local HTML audit report (default under `Documents\windo\`). |
 | `windo self-update` | Trigger the self-update scheduled task (repairs task actions). |
 | `windo version` | Version, paths, hashes, task presence. |
 | `windo doctor` | Paths, tasks, logs, quick health. |
@@ -75,6 +80,8 @@ The canonical install snippet is also kept in `docs/releases/README_INSTALL_UPDA
 | `windo log -n N` | Show last N log entries (decrypted). |
 | `windo cleanup [-w]` | Back up log to `.pwsh_secure`, clear active log, remove pending req/res JSON. Optional `-w` is accepted for compatibility and ignored. |
 
+Append **`--json`** or **`-Json`** to supported commands (`version`, `doctor`, `integrity`, `verify`, `log`, and the commands above where noted) for structured output suitable for scripts and ticketing.
+
 ---
 
 ## PSReadLine keybindings (v2.4.0+)
@@ -101,6 +108,17 @@ See [`SECURITY.md`](SECURITY.md) for expectations and reporting.
 
 ---
 
+
+## Reporting and automation
+
+- **`windo report`** produces a **local HTML** summary (paths, integrity status, recent audit lines). Treat reports as **sensitive**; they may echo elevated command text.
+- **`--json` / `-Json`** on `doctor`, `integrity`, `version`, `verify`, `log`, `stats`, `history`, and `last` helps pipe output into monitors, tickets, or CMDB without scraping host-colored text.
+- **`windo stats`** / **`windo history`** give fast situational awareness without full `log` verbosity.
+
+- Maintainer notes: [`docs/build.md`](docs/build.md) (modularization path), [`docs/branding.md`](docs/branding.md) (logo direction).
+
+---
+
 ## Execution flow
 
 ```text
diff --git a/RELEASE_HELPER_v2.5.0.md b/RELEASE_HELPER_v2.5.0.md
@@ -0,0 +1,15 @@
+# Release helper — v2.5.0
+
+## Checklist
+
+1. `windo_install.ps1` has `$WindoVersion = "2.5.0"` and header matches.
+2. Run `tools/Validate-Windo.ps1`; CI runs `.github/workflows/validate.yml`.
+3. Smoke: elevated `.\windo_install.ps1`, then `. $PROFILE`, `windo help`, `windo doctor --json`, `windo report`, `windo stats`.
+4. Tag `v2.5.0` after merge.
+
+## New in 2.5.0
+
+- `last`, `stats`, `history`, `report`, `help`
+- JSON output on key diagnostics
+- HTML report, access-denied hints, timeout hint
+- `tools/Validate-Windo.ps1`, `docs/build.md`, `docs/branding.md`
diff --git a/docs/branding.md b/docs/branding.md
@@ -0,0 +1,18 @@
+# Branding direction (WINDO)
+
+WINDO targets **administrators and operators**. Visual identity should feel:
+
+- **Deliberate** — not playful; no cartoon mascots.
+- **Technical** — monospace-adjacent, clear hierarchy, high contrast.
+- **Trustworthy** — restrained palette (slate / graphite / one accent such as steel blue or amber for warnings only).
+
+## Logo
+
+Suggested evolution from current SVG assets:
+
+- **Mark**: abstract **shield** or **stile** shape (elevation / gate), or a minimal **W** formed by two crossing strokes suggesting a bridge.
+- **Wordmark**: "WINDO" in a neutral grotesk or semi-mono; avoid novelty display fonts.
+- **Color**: dark background variants for README banners; light background for docs.
+
+Apply changes to `assets/windo-logo.svg` and `assets/windo-banner.svg` in a dedicated design pass; keep file sizes small for raw GitHub viewing.
+
diff --git a/docs/build.md b/docs/build.md
@@ -0,0 +1,19 @@
+# Build / modularization (WINDO)
+
+WINDO ships a single **installer** (`windo_install.ps1`) as the source of truth: it embeds the profile `windo` function, PSReadLine block, runner, and self-update script text.
+
+## Current model
+
+- One file to copy and run elevated on target machines.
+- Bootstrap downloads that file from GitHub and executes it from disk.
+
+## Direction for modular sources (future)
+
+To reduce monolithic edit risk without changing the install contract:
+
+1. Keep **published** artifacts as today: `windo_install.ps1` at repo root.
+2. Optionally maintain fragments under `src/` (e.g. `src/windo/ProfileWindo.ps1`) that are **concatenated** by a small `tools/Build-WindoInstaller.ps1` into `windo_install.ps1` before release.
+3. **Validation**: run `tools/Validate-Windo.ps1` in CI and before tagging.
+
+No build step is required for end users; a build is only for maintainers who choose to split sources.
+
diff --git a/docs/releases/RELEASE_NOTES_v2.5.0.md b/docs/releases/RELEASE_NOTES_v2.5.0.md
@@ -0,0 +1,27 @@
+# Release notes — WINDO v2.5.0
+
+## Summary
+
+v2.5.0 strengthens **operator experience**, **visibility**, and **repository hygiene** while keeping the same elevation model: **choose elevation before execution.**
+
+## New commands
+
+| Command | Description |
+|--------|-------------|
+| `windo help` | Short usage reference. |
+| `windo last` | Show last stored command (no run). |
+| `windo stats` | Aggregate stats over the DPAPI audit log. |
+| `windo history [-n N]` | Compact history (default N=50). |
+| `windo report [-o path]` | Local HTML audit report. |
+
+## JSON output
+
+Append `--json` or `-Json` to supported commands for structured output: `version`, `doctor`, `integrity`, `verify`, `log`, `stats`, `history`, `last`.
+
+## Hints
+
+After failures that look like **access denied** (or task timeout), WINDO may print a short, **non-silent** hint to run `windo doctor` or re-run the installer elevated—without auto-elevating your shell.
+
+## Upgrade
+
+Run the installer elevated (`bootstrap` or `windo_install.ps1`), then `. $PROFILE`. Verify with `windo help` and `windo doctor`.
diff --git a/tools/Validate-Windo.ps1 b/tools/Validate-Windo.ps1
@@ -0,0 +1,25 @@
+# Validate WINDO repo scripts (syntax). Run from repo root: ./tools/Validate-Windo.ps1
+$ErrorActionPreference = "Stop"
+$root = Split-Path $PSScriptRoot -Parent
+$files = @(
+    "bootstrap.ps1",
+    "windo_install.ps1",
+    "windo_runner.ps1",
+    "windo_self_update.ps1"
+)
+$ok = $true
+foreach ($f in $files) {
+    $p = Join-Path $root $f
+    if (!(Test-Path $p)) { Write-Warning "Missing: $f"; $ok = $false; continue }
+    $err = $null
+    $null = [System.Management.Automation.Language.Parser]::ParseFile($p, [ref]$null, [ref]$err)
+    if ($err) {
+        Write-Host "FAIL $f" -ForegroundColor Red
+        $err | ForEach-Object { Write-Host $_.ToString() }
+        $ok = $false
+    } else {
+        Write-Host "OK   $f" -ForegroundColor Green
+    }
+}
+if (-not $ok) { exit 1 }
+Write-Host "Validate-Windo: all checks passed." -ForegroundColor Cyan
diff --git a/windo_install.ps1 b/windo_install.ps1
