feat(cli): add validate --output json for agent-native reports

docs/knowledgebase/agent-action-parity.md

@@ -16,7 +16,7 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG
 | 6 | `AspyrNoticePage` | Acknowledge (K2) | No CLI equivalent | UI |
 | 7 | `ModSelectionPage` | Select mods, filters | `install` without `--select` = select all; `install --select category:X` / `tier:X` | Full (install); Partial (subset only with `--select`) |
 | 8 | `DownloadsExplainPage` | Continue (downloads may run) | `install -d` or `convert -d` (+ FOMOD: TTY / `--fomod-choices` / `--fomod-skip`) | Partial — live download status is `[UI]`; FOMOD configure is Full via CLI (see [fomod-support.md](fomod-support.md)) |
-| 9 | `ValidatePage` | Run validation | `validate --full --dry-run --use-file-selection` (same Core `InstallationValidationPipeline` as GUI) | Full |
+| 9 | `ValidatePage` | Run validation | `validate --full --dry-run --use-file-selection --output json` (same Core `InstallationValidationPipeline` as GUI) | Full |
 | 10 | `InstallStartPage` | Confirm install | `install -y` (runs `InstallationValidationPipeline` / `WizardFull` pre-check unless `--skip-validation`) | Full |
 | 10b | Managed deploy | Opt-in hardlink deploy via active profile | `install --managed` / `--no-managed` / `--profile` (#177); settings toggle still GUI | Full (CLI overrides); Partial (profile CRUD `[UI]`) — [managed-deployment.md](managed-deployment.md) |
 | 11 | `InstallingPage` | Watch progress | `install` (console progress) | Full — see [install-lifecycle.md](install-lifecycle.md) |
@@ -65,6 +65,7 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG
 | Wizard UI | `WizardFlowHeadlessTests` | Page flow without full desktop |
 | GUI UX smoke | `GuiSmokeHeadlessTests` | Paste-import button + `LoadInstructionTextAsync` markdown (no clipboard), Welcome→ValidatePage key controls, compact ScrollViewer layout, ValidatePage log splitter |
 | Guide ingest | `GuideIngestionTests` | `--stdin` / `--parse-directions` draft + sandboxed paths |
+| Validate JSON | `ValidateCliJsonTests`, `ValidationPipelineJsonFormatterTests` | `validate --output json` structured stdout |
 | Wizard validation UX | `WizardValidationStagePresenter`, `ValidationPipelineDialogMapper` | Stage cards / dialog mapper parity ([PR #110](https://github.com/th3w1zard1/ModSync/pull/110)) |
 | Version alignment | `ReleaseVersionAlignmentTests` | Release metadata consistency |
 
@@ -85,6 +86,6 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG
 9. **FOMOD post-download** — GUI prompts after Fetch Downloads (PR #169). CLI: TTY wizard, `--fomod-skip`, `--fomod-choices` / `MODSYNC_FOMOD_CHOICES`, or non-TTY **warn-continue** (marks `warned`; `FomodConfigurationGate` still blocks validate/install until `configured`). See [fomod-support.md](fomod-support.md).
 10. **Guide drafts** — `--parse-directions` / GUI paste drafts are review-flagged; never treat as trusted install instructions without review. See [guide-ingestion.md](guide-ingestion.md).
 11. **Managed / profile CLI** — `install --managed` / `--no-managed` / `--profile` shipped (#177). Profile create/list/delete remains `[UI]` / file edits under `{settingsDir}/profiles/`. See [managed-deployment.md](managed-deployment.md).
-12. **Validation presentation vs pipeline** — CLI and GUI share `InstallationValidationPipeline`; stage-card UX / copy-report / go-to-first-issue remain `[UI]` ([gui-validation-surfaces.md](gui-validation-surfaces.md)).
+12. **Validation presentation vs pipeline** — CLI and GUI share `InstallationValidationPipeline`; stage-card UX / copy-report / go-to-first-issue remain `[UI]`. Agents use `validate --output json` for structured reports ([gui-validation-surfaces.md](gui-validation-surfaces.md)).
 
 See [agent-native-audit.md](agent-native-audit.md) for scored principles and [core-cli-reference.md](core-cli-reference.md) for flags.

docs/knowledgebase/agent-native-audit.md

@@ -51,7 +51,7 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec
 | Set mod / game directories | GUI preload or CLI `-g` / `-s` | Yes |
 | Paste / ingest guide | GUI clipboard; CLI `convert --stdin` / `-i` + `--parse-directions` | Yes (file/stdin); OS clipboard `[UI]` |
 | `modsync://` open/install link | `--modsync=` / URI argv → handoff | Yes (consume); Settings toggle deferred |
-| Run validation | `ValidatePage` or `validate --full` / `--dry-run` | Yes (selection flags differ) |
+| Run validation | `ValidatePage` or `validate --full` / `--dry-run` / `validate --output json` | Yes (selection flags differ) |
 | Fetch downloads | Wizard / `ScrapeDownloadsButton` | Partial — CLI `install -d` / `convert -d`; status/stop `[UI]` |
 | Post-download FOMOD configure | GUI after Fetch Downloads | Yes — CLI TTY / `--fomod-choices` / `--fomod-skip` |
 | FOMOD configure-before-validate/install gate | GUI + Core `FomodConfigurationGate` | Yes — shared fail-closed gate |
@@ -62,7 +62,7 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec
 | Widescreen-only install block | Dynamic wizard pages | No — desktop only |
 | Aspyr notice (K2) | `AspyrNoticePage` | No — desktop only |
 | Rich-text / spoiler UI | GUI controls | No |
-| ValidatePage stage cards / copy report | Wizard presentation | Partial — pipeline Full; presentation `[UI]` |
+| ValidatePage stage cards / copy report | Wizard presentation | Partial — pipeline Full; `--output json` for machine reports; presentation `[UI]` |
 | Telemetry-auth sidecar | Separate Python stack | Routed via `telemetry-auth/README.md` |
 
 **Strengths:** `[REPO]` `ModBuildConverter` covers validate/install/convert/merge; FOMOD Plan 123 + gate; guide paste (#171); `modsync://` Phase 1–2; managed CLI overrides (#177); `install_best_effort.sh` documents a full-build-style headless path.
@@ -156,7 +156,7 @@ Files are the interface: instruction TOMLs, ingested drafts under `tmp/`, `tmp/k
 2. **Download status / stop** — CLI can download; live progress and stop controls are `[UI]` only.
 3. **Widescreen + Aspyr flows** — K2 wizard-only pages; no CLI equivalent.
 4. **Managed dry-run / VFS validation parity** — deferred `[OPEN]` in [managed-deployment.md](managed-deployment.md); classic VFS validate does not fully model managed staging/deploy.
-5. **Validation presentation / machine output** — stage-card UX / copy-report / go-to-first-issue remain `[UI]`; no structured JSON validation report for agents.
+5. **Validation presentation / machine output** — stage-card UX / copy-report / go-to-first-issue remain `[UI]`; CLI supports `validate --output json` for structured reports.
 
 Honorable mentions: OS clipboard paste still `[UI]` (stdin/file ingest covers agents); `modsync://` Settings checkbox deferred.
 
@@ -168,7 +168,7 @@ Honorable mentions: OS clipboard paste still `[UI]` (stdin/file ingest covers ag
 2. **Tier 1:** Treat GUI-only flows as `[UI]` in plans; check [agent-action-parity.md](agent-action-parity.md) before assuming headless parity.
 3. **Tier 2:** When adding wizard steps, add a CLI or script path—or document the gap in the parity matrix.
 4. **Tier 2:** Close managed dry-run/VFS validation parity ([plan 004](../plans/2026-07-13-004-managed-deployment-validation-plan.md)).
-5. **Tier 3:** Optional: structured JSON validation output; CLI profile list/create/activate verbs.
+5. **Tier 3:** Optional: extend JSON validation schema with per-mod issue IDs; CLI profile list/create/activate verbs.
 
 ## Strengths summary
 

docs/knowledgebase/core-cli-reference.md

@@ -41,6 +41,7 @@ Validate an instruction file. Structural checks work with `-i` alone; environmen
 | `--dry-run-only` | No | VFS dry-run only; skips per-component archive existence checks (requires game + source dirs) |
 | `--errors-only` | No | Suppress warnings/info |
 | `--ignore-errors` | No | Best-effort dependency order |
+| `--output` | No | Output format: `text` (default) or `json` (machine-readable report on stdout) |
 
 **Example:**
 
@@ -55,11 +56,15 @@ dotnet run --project src/ModSync.Core/ModSync.Core.csproj -f net9.0 -- \
 
 dotnet run --project src/ModSync.Core/ModSync.Core.csproj -f net9.0 -- \
   validate -i ./mod-builds/TOMLs/KOTOR1_Full.toml \
-  -g ./tmp/kotor_template -s ./tmp/mod_downloads --dry-run-only
+  -g ./tmp/kotor_template -s ./tmp/mod_downloads --dry-run-only --output json
 ```
 
 With an empty mod workspace, `--dry-run` runs archive checks first and often exits non-zero before VFS simulation. Use `--dry-run-only` when you want VFS structural validation without requiring archives on disk.
 
+**JSON output:** `--output json` writes a single JSON document to stdout (stages, counts, dry-run issues). Progress logs are suppressed so agents can parse stdout directly. Early failures (missing input file, missing dirs) also emit JSON with an `error` field.
+
+**Tests:** `dotnet test src/ModSync.Tests/ModSync.Tests.csproj --filter "FullyQualifiedName~ValidateCliJsonTests|FullyQualifiedName~ValidationPipelineJsonFormatterTests"`
+
 ---
 
 ### `install`