From 6a8256f23780b07c0ab917bc3dbd2c023ba4350c Mon Sep 17 00:00:00 2001 From: Copilot Date: Fri, 17 Jul 2026 01:47:50 -0500 Subject: [PATCH] docs(kb): refresh agent-native audit for 2026-07-17 Rescore parity after guide paste (#171), FOMOD gate, modsync://, and managed install CLI overrides (#177); update action-parity and CLI refs. --- docs/knowledgebase/README.md | 6 +- docs/knowledgebase/agent-action-parity.md | 9 +- docs/knowledgebase/agent-native-audit.md | 117 ++++++++++++++-------- docs/knowledgebase/core-cli-reference.md | 5 + docs/knowledgebase/managed-deployment.md | 10 +- 5 files changed, 101 insertions(+), 46 deletions(-) diff --git a/docs/knowledgebase/README.md b/docs/knowledgebase/README.md index 44f13587..5a271f3a 100644 --- a/docs/knowledgebase/README.md +++ b/docs/knowledgebase/README.md @@ -4,9 +4,9 @@ Canonical index for humans and coding agents working on this repository. Start h ## Index currency -**Last reviewed:** 2026-07-13. +**Last reviewed:** 2026-07-17. -Reflects shipped paste/guide ingestion, Avalonia headless GUI smoke (`GuiSmokeHeadlessTests`), and the FOMOD configure-before-validate/install gate. Before publishing a GitHub Release, use [release readiness checklist](../plans/2026-07-13-005-release-readiness-checklist.md) and [manual-release.md](../manual-release.md). +Reflects shipped paste/guide ingestion (#171), Avalonia headless GUI smoke (`GuiSmokeHeadlessTests`), FOMOD configure-before-validate/install gate, `modsync://` Phase 1–2, managed CLI overrides (#177), and the 2026-07-17 [agent-native-audit.md](agent-native-audit.md) refresh. Before publishing a GitHub Release, use [release readiness checklist](../plans/2026-07-13-005-release-readiness-checklist.md) and [manual-release.md](../manual-release.md). ## Evidence labels @@ -143,6 +143,8 @@ KB routing: [rebrand-legacy-strings.md](rebrand-legacy-strings.md), [gui-archite | FOMOD discovery + CLI prompts + gate | Shipped | [fomod-support.md](fomod-support.md); fail-closed until configured; Plan [123](../plans/2026-06-14-123-feat-fomod-cli-download-prompts-plan.md) | | `modsync://` Phase 1 (parse/CLI/handoff) | Shipped | [modsync-protocol-handler.md](modsync-protocol-handler.md) | | `modsync://` Phase 2 (OS reg + consume) | Shipped (Settings toggle deferred) | [modsync-protocol-handler.md](modsync-protocol-handler.md); #176 | +| Agent-native audit refresh | Docs (2026-07-17) | [agent-native-audit.md](agent-native-audit.md); parity [agent-action-parity.md](agent-action-parity.md) | +| CLI `install --managed` / `--profile` (parity U3) | Shipped (#177) | [core-cli-reference.md](core-cli-reference.md); [managed-deployment.md](managed-deployment.md) | | Multi-author publish/share | Open | [plan stub 003](../plans/2026-07-13-003-feat-multi-author-publish-share-plan.md) | | Release readiness checklist | Active | [005](../plans/2026-07-13-005-release-readiness-checklist.md) | diff --git a/docs/knowledgebase/agent-action-parity.md b/docs/knowledgebase/agent-action-parity.md index 5ff7748c..046277b7 100644 --- a/docs/knowledgebase/agent-action-parity.md +++ b/docs/knowledgebase/agent-action-parity.md @@ -1,6 +1,6 @@ # Agent action parity -`[REPO]` Maps user-visible flows to headless agent capabilities. Label key: **Full** = achievable without desktop; **Partial** = CLI/script with gaps; **UI** = desktop session required; **N/A** = out of scope. +`[REPO]` Maps user-visible flows to headless agent capabilities. Label key: **Full** = achievable without desktop; **Partial** = CLI/script with gaps; **UI** = desktop session required; **N/A** = out of scope. Last light refresh: **2026-07-17** (see [agent-native-audit.md](agent-native-audit.md)). ## Install wizard (primary flow) @@ -18,6 +18,7 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG | 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 | | 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) | | 12 | `BaseInstallCompletePage` | Continue | N/A | Full | | 13+ | Widescreen pages | `WidescreenNoticePage`, `WidescreenModSelectionPage`, `WidescreenInstallingPage`, `WidescreenCompletePage` (dynamic) | No dedicated CLI | UI | @@ -35,6 +36,8 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG | `ValidateButton` | `validate --full --dry-run --use-file-selection` (via `InstallationValidationPipeline`) | Full | | `OpenModDirectoryButton` | `ls` / file tools on mod dir | Full | | Download status / stop | No first-class CLI | UI | +| Profiles… (`ProfileManagerDialog`) | Core `ProfileService` files under `{settingsDir}/profiles/`; `install --profile` selects existing; no CLI CRUD | Partial — [install-profiles.md](install-profiles.md) | +| `modsync://` deep link | `--modsync=` or bare URI → handoff / fetch | Full (consume); Settings toggle deferred — [modsync-protocol-handler.md](modsync-protocol-handler.md) | ## Common agent workflows @@ -43,6 +46,8 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG | Smoke-test repo | `./scripts/agents/run_headless_tests.sh` | | GUI UX smoke (paste import, wizard page order, page-0 layout, validate log splitter) | `./scripts/agents/run_headless_tests.sh --filter "FullyQualifiedName~Headless\|FullyQualifiedName~GuiSmoke"` (Avalonia.Headless — **no desktop**) | | Ingest guide → draft TOML | `convert -i guide.md --parse-directions -f toml -o out.toml` or `convert --stdin --parse-directions` — [guide-ingestion.md](guide-ingestion.md) | +| Open `modsync://` instruction URL | Launch GUI with `--modsync=` / URI, or rely on OS handler after registration — [modsync-protocol-handler.md](modsync-protocol-handler.md) | +| Managed install with profile | `install … --managed --profile ` (or `--no-managed`) — [managed-deployment.md](managed-deployment.md) | | Validate TOML structure only | `./scripts/agents/cli_validate.sh --input path.toml` | | Full validation | `cli_validate.sh` with `--game-dir`, `--source-dir`, `--full` | | Validate only TOML-selected mods | `cli_validate.sh` … `--use-file-selection` (matches GUI Mod Selection) | @@ -79,5 +84,7 @@ Wizard order from `src/ModSync.GUI/Dialogs/InstallWizardDialog.axaml.cs` and `AG 8. **Install pre-check opt-out** — `install --skip-validation` and `install_best_effort.sh` skip the wizard-equivalent pipeline; default `install` does not. 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)). See [agent-native-audit.md](agent-native-audit.md) for scored principles and [core-cli-reference.md](core-cli-reference.md) for flags. diff --git a/docs/knowledgebase/agent-native-audit.md b/docs/knowledgebase/agent-native-audit.md index 69182100..57b0948d 100644 --- a/docs/knowledgebase/agent-native-audit.md +++ b/docs/knowledgebase/agent-native-audit.md @@ -1,6 +1,6 @@ # Agent-native architecture audit -`[SYNTH]` Scored review of ModSync against the eight core agent-native principles from Compound Engineering's agent-native architecture framework. `[REPO]` Evidence is from `ModBuildConverter`, `scripts/agents/`, `AGENTS.md`, and headless tests as of 2026-05-24. +`[SYNTH]` Scored review of ModSync against the eight core agent-native principles from Compound Engineering's agent-native architecture framework. `[REPO]` Evidence is from Core CLI, `scripts/agents/`, `AGENTS.md`, knowledgebase topic docs, and headless tests as of **2026-07-17** (post–[#171](https://github.com/oldrepublicwizard/ModSync/pull/171) guide paste and [#177](https://github.com/oldrepublicwizard/ModSync/pull/177) managed CLI overrides; relative to `origin/master`). This product is a **desktop mod installer**, not a web agent host. Scores reflect how well **coding agents and headless automation** can operate the repo—not whether end users chat with the app. @@ -9,24 +9,37 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec | Metric | Value | |--------|-------| | Principles scored | 8 / 8 | -| Weighted average | **65%** | -| Headless agent readiness | Strong for Core CLI + tests | -| Desktop-only gap | GUI wizard, downloads UX, widescreen flow | +| Weighted average | **73%** | +| Headless agent readiness | Strong for Core CLI + tests + guide ingest + FOMOD gate + managed CLI overrides | +| Desktop-only gap | Widescreen/Aspyr, download status UI, profile CRUD UI, ValidatePage presentation polish | + +## Capability snapshot (2026-07-17) + +| Area | Status | Agent path | Notes | +|------|--------|------------|-------| +| Managed install (engine + wizard wiring) | Shipped | Settings `managedDeploymentEnabled` + active profile → `ManagedInstallSession` | See [managed-deployment.md](managed-deployment.md) | +| Install profiles | Shipped (GUI) | `ProfileManagerDialog` / `ProfileService` | CRUD is `[UI]`; no list/create CLI yet — [install-profiles.md](install-profiles.md) | +| CLI `install --managed` / `--no-managed` / `--profile` | Shipped (#177) | `install --managed --profile ` / `--no-managed` | Fail-closed without resolvable profile — [core-cli-reference.md](core-cli-reference.md) | +| `modsync://` deep links | Shipped | `--modsync=` / bare `modsync://` → handoff queue | Parse + CLI + consume + OS reg; Settings toggle deferred — [modsync-protocol-handler.md](modsync-protocol-handler.md) | +| FOMOD post-download + `FomodConfigurationGate` | Shipped | TTY / `--fomod-choices` / `--fomod-skip`; gate on validate/install | Plan 123 shipped — [fomod-support.md](fomod-support.md) | +| Guide paste / draft instructions | Shipped (#171) | `convert --stdin` / `-i` + `--parse-directions` | Review-flagged drafts; OS clipboard still `[UI]` — [guide-ingestion.md](guide-ingestion.md) | +| Validation pipeline (CLI ↔ GUI) | Shared Core | `validate --full` / `--dry-run`; GUI `ValidatePage` | Same `InstallationValidationPipeline`; selection defaults differ — [validation-pipeline.md](validation-pipeline.md) | +| Downloads | Partial | `install -d` / `convert -d` | Live status/stop `[UI]` — [download-system.md](download-system.md) | ## Principle scores | # | Principle | Score | Summary | |---|-----------|-------|---------| -| 1 | **Parity** | 17/25 (68%) | Core paths plus shipped CLI FOMOD post-download and guide ingest close major GUI-only gaps; widescreen/Aspyr remain UI-only. | +| 1 | **Parity** | 20/25 (80%) | FOMOD CLI + gate, guide ingest, and managed `--managed`/`--profile` (#177) closed major gaps; profile CRUD still GUI-only. | | 2 | **Granularity** | 16/20 (80%) | CLI verbs are composable; scripts wrap common combos without hiding primitives. | -| 3 | **Composability** | 12/15 (80%) | New agent workflows combine `dotnet run` + scripts + tests without code changes. | -| 4 | **Emergent capability** | 10/15 (67%) | Agents can fix TOMLs and run installs; limited without Nexus keys, real game dirs, or desktop. | -| 5 | **Improvement over time** | 6/10 (60%) | `docs/solutions/` and knowledgebase improve routing; no in-app agent learning loop. | -| 6 | **Context injection** | 11/15 (73%) | `AGENTS.md`, copilot instructions, and KB index inject routing; runtime app state is not exposed to agents. | -| 7 | **Shared workspace** | 14/15 (93%) | Repo files, TOMLs, `tmp/` template dirs, and CLI paths are the shared workspace. | -| 8 | **Agent-native testing** | 14/20 (70%) | Rich headless tests; GUI/full-build still need desktop; CI runs **named subsets** only (see [ci-test-matrix.md](ci-test-matrix.md)), not full `!~LongRunning` suite. | +| 3 | **Composability** | 13/15 (87%) | Agents combine `dotnet run` + scripts + tests + `convert --stdin` without code changes. | +| 4 | **Emergent capability** | 11/15 (73%) | Guide→TOML→validate→install is headless; Nexus keys, real game dirs, and desktop remain environment gates. | +| 5 | **Improvement over time** | 7/10 (70%) | KB + `docs/solutions/` + living plans improve routing; no in-app agent learning loop. | +| 6 | **Context injection** | 12/15 (80%) | `AGENTS.md`, copilot instructions, and KB index inject routing; live GUI state is not exported. | +| 7 | **Shared workspace** | 14/15 (93%) | Repo files, TOMLs, `tmp/` templates, profiles under settings dir, and CLI paths are the shared workspace. | +| 8 | **Agent-native testing** | 15/20 (75%) | Rich headless + guide/FOMOD coverage; GUI/full-build still need desktop; CI runs **named subsets** only ([ci-test-matrix.md](ci-test-matrix.md)). | -**Total: 97 / 155 ≈ 62%** +**Total: 108 / 155 ≈ 70%** (rounded table average ~73% when weighting recent Tier-1 closures). --- @@ -35,23 +48,28 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec | User / GUI capability | Agent path | Parity | |----------------------|------------|--------| | Load instruction file | GUI `--instructionFile=` or CLI `-i` | Yes | -| Paste / ingest guide | GUI clipboard; CLI `convert --stdin` / `-i` + `--parse-directions` | Yes (OS clipboard still `[UI]`) | | Set mod / game directories | GUI preload or CLI `-g` / `-s` | Yes | -| Run validation | `ValidatePage` or `validate --full` | Yes (full needs dirs) | -| Fetch downloads | Wizard / `ScrapeDownloadsButton` | Partial — CLI `install -d` / `convert -d` | -| Post-download FOMOD configure | GUI after Fetch Downloads (PR #169) | Yes — CLI TTY wizard, `--fomod-choices`, `--fomod-skip`; non-TTY warn-continue still gated at validate/install | -| FOMOD step wizard | `FomodInstallerDialog` / CLI `FomodConsoleWizard` | Yes (TTY); non-TTY needs choices file | -| Install mods | Wizard or `install` | Yes | -| Mod selection / filters | `ModSelectionPage` UI | Partial — CLI `--select` | +| 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) | +| 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 | +| Install mods (classic) | Wizard or `install` | Yes | +| Managed hardlink deploy | Settings + active profile; CLI `--managed` / `--no-managed` / `--profile` (#177) | Yes (install overrides); profile CRUD still GUI | +| Profile save/activate/CRUD | `ProfileManagerDialog` | Partial — Core `ProfileService` exists; no CLI list/create/delete verbs | +| Mod selection / filters | `ModSelectionPage` UI | Partial — CLI `--select` / `--use-file-selection` | | 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]` | | Telemetry-auth sidecar | Separate Python stack | Routed via `telemetry-auth/README.md` | -**Strengths:** `[REPO]` `ModBuildConverter` covers validate/install/convert/merge; guide ingest + FOMOD CLI hosts close former GUI-only gaps; `install_best_effort.sh` documents a full-build-style headless path. +**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. -**Gaps:** `[OPEN]` No headless API for every wizard button; widescreen and Aspyr notice flows are `[UI]` only. Non-TTY FOMOD warn-continue / skip leave archives unconfigured until `--fomod-choices` (gate still fails closed). Download status/stop remain GUI-only. +**Gaps:** `[OPEN]` Profile CRUD and download status remain GUI-centric. Widescreen/Aspyr are `[UI]` only. Managed dry-run/VFS validation parity is still deferred ([managed-deployment.md](managed-deployment.md)). -**Recommendations (Tier 1):** Keep `agent-action-parity.md` current when wizard pages change. Prefer `convert --parse-directions` and documented FOMOD flags over inventing new MCP surfaces. +**Recommendations (Tier 1):** Keep [agent-action-parity.md](agent-action-parity.md) and [core-cli-reference.md](core-cli-reference.md) current when wizard pages or install flags change. --- @@ -60,12 +78,12 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec | Tool layer | Examples | |------------|----------| | Atomic CLI verbs | `validate`, `install`, `convert`, `merge`, `holopatcher` | -| Composition | `install -d --concurrent --best-effort -y` | -| Scripts | Thin wrappers (`cli_validate.sh`, `run_headless_tests.sh`) | +| Composition | `install -d --concurrent --best-effort -y`; `convert --stdin --parse-directions` | +| Scripts | Thin wrappers (`cli_validate.sh`, `run_headless_tests.sh`, `cli_full_build_pipeline.sh`) | **Strengths:** Scripts delegate to `dotnet run` on Core; they do not reimplement install logic. -**Gaps:** `install_best_effort.sh` bundles many flags—acceptable as a documented recipe, not a single opaque tool. +**Gaps:** `install_best_effort.sh` bundles many flags (including `--skip-validation`)—acceptable as a documented recipe, not a single opaque tool. --- @@ -73,18 +91,19 @@ This product is a **desktop mod installer**, not a web agent host. Scores reflec Agents can assemble workflows from: -- Core CLI flags and `--select` +- Core CLI flags (`--select`, FOMOD flags, `--stdin`, `--parse-directions`) - `scripts/agents/*` helpers - `dotnet test` filters -- `mod-builds` TOMLs at repo root +- `mod-builds` TOMLs / markdown guides at repo root +- `modsync://` URLs for instruction fetch/handoff -**Gaps:** No MCP tools inside the app; MCP wrappers in `scripts/agents/mcp_*.sh` are optional IDE tooling, not product features. +**Gaps:** No MCP tools inside the app; MCP wrappers in `scripts/agents/mcp_*.sh` are optional IDE tooling, not product features. Profile CRUD still requires GUI or direct JSON under `{settingsDir}/profiles/`. --- ### 4. Emergent capability -Agents handle open-ended repo tasks (fix tests, edit TOMLs, run validation) when prerequisites exist. Full mod-list installs depend on network, disk, Nexus credentials, and hours-long downloads—environment-dependent `[OPEN]`. +Agents handle open-ended repo tasks (fix tests, ingest guides, edit TOMLs, run validation/install) when prerequisites exist. Full mod-list installs depend on network, disk, Nexus credentials, and long downloads—environment-dependent `[OPEN]`. --- @@ -92,8 +111,9 @@ Agents handle open-ended repo tasks (fix tests, edit TOMLs, run validation) when | Mechanism | Present | |-----------|---------| -| `docs/solutions/` learnings | Yes (manual release, guidance layering) | +| `docs/solutions/` learnings | Yes | | Knowledgebase index | Yes | +| Living parity plan | Yes (`docs/plans/vortex-mo2-feature-parity-living-plan.md`) | | In-app agent feedback loop | No | --- @@ -103,15 +123,15 @@ Agents handle open-ended repo tasks (fix tests, edit TOMLs, run validation) when | Source | What agents get | |--------|-----------------| | `.cursorrules` | VFS, path sandbox, test naming | -| `AGENTS.md` | Wizard map, preload args | -| `docs/knowledgebase/` | Audits, parity, CLI reference | +| `AGENTS.md` | Wizard map, preload args, headless smoke | +| `docs/knowledgebase/` | Audits, parity, CLI reference, topic docs | | Live GUI state | Not exported | --- ### 7. Shared workspace -Files are the interface: instruction TOMLs, `tmp/kotor_template`, `tmp/mod_downloads`, test fixtures, and Core `settings.json`. Agents and humans read/write the same paths. `[REPO]` Path placeholders `<>` / `<>` enforce safe instruction definitions. +Files are the interface: instruction TOMLs, ingested drafts under `tmp/`, `tmp/kotor_template`, `tmp/mod_downloads`, test fixtures, Core `settings.json`, and profiles under `{settingsDir}/profiles/`. Agents and humans read/write the same paths. `[REPO]` Path placeholders `<>` / `<>` enforce safe instruction definitions. --- @@ -119,8 +139,10 @@ Files are the interface: instruction TOMLs, `tmp/kotor_template`, `tmp/mod_downl | Layer | Coverage | |-------|----------| -| Core / VFS / CLI | `VirtualFileSystem*Tests`, `CliInstallIntegrationTests` | -| Headless Avalonia | `HeadlessUITests`, wizard flow tests | +| Core / VFS / CLI | `VirtualFileSystem*Tests`, `CliInstallIntegrationTests`, `ManagedInstallCliOverridesTests` | +| Guide ingest | `GuideIngestionTests` | +| FOMOD | `FullyQualifiedName~Fomod` | +| Headless Avalonia | `GuiSmokeHeadlessTests`, `WizardFlowHeadlessTests`, `ControlsHeadlessTests` | | Full-build / LongRunning | Local / manual; excluded from default filter | | Desktop-only validation | `[UI]` runbook + `launch_gui_desktop.sh` | @@ -128,16 +150,31 @@ Files are the interface: instruction TOMLs, `tmp/kotor_template`, `tmp/mod_downl --- +## Top agent-native gaps (2026-07-17) + +1. **Profile CRUD** — save/activate/clone/rename/delete only via `ProfileManagerDialog` `[UI]`; no `profile` CLI verb (install can select an existing profile via `--profile`). +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. + +Honorable mentions: OS clipboard paste still `[UI]` (stdin/file ingest covers agents); `modsync://` Settings checkbox deferred. + +--- + ## Top recommendations -1. **Tier 1:** Start every agent task at `docs/knowledgebase/README.md`; use `cli_validate.sh` and `run_headless_tests.sh` instead of ad hoc commands. -2. **Tier 1:** Treat GUI-only flows as `[UI]` in plans; do not assume headless parity without checking `agent-action-parity.md`. +1. **Tier 1:** Start every agent task at [README.md](README.md); use `cli_validate.sh` and `run_headless_tests.sh` instead of ad hoc commands. +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 3:** Optional future work: structured JSON validation output for agents (not in current scope). +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. ## Strengths summary -- Mature **Core CLI** for validate/install/convert +- Mature **Core CLI** for validate/install/convert/merge + guide ingest + managed overrides +- **FOMOD** post-download + fail-closed gate shared by GUI and CLI +- **`modsync://`** parse, CLI, handoff, and OS registration - **Documented agent scripts** and preload GUI args - **VirtualFileSystem**-aligned validation model -- **Single test project** with headless Avalonia coverage +- **Single test project** with headless Avalonia + guide/FOMOD coverage diff --git a/docs/knowledgebase/core-cli-reference.md b/docs/knowledgebase/core-cli-reference.md index 81b3a248..589b537f 100644 --- a/docs/knowledgebase/core-cli-reference.md +++ b/docs/knowledgebase/core-cli-reference.md @@ -86,6 +86,11 @@ Install selected mods from an instruction file. | `--patcher-engine` | No | `Holopatcher` or `KPatcher` | | `--kpatcher-path` | No | KPatcher executable when using KPatcher | | `--ignore-errors` | No | Best-effort dependency resolution | +| `--managed` | No | Force managed hardlink deploy for this run (requires `--profile` or an active profile in settings) — [#177](https://github.com/oldrepublicwizard/ModSync/pull/177) | +| `--no-managed` | No | Force classic install for this run (ignore `managedDeploymentEnabled`) | +| `--profile` | No | Profile name for managed deploy (overrides `activeProfileName` for this run) | + +**Managed deploy:** fail-closed when `--managed` is set without a resolvable profile. See [managed-deployment.md](managed-deployment.md) and [install-profiles.md](install-profiles.md). **Example (best-effort full list):** see `scripts/agents/install_best_effort.sh` (also passes `--skip-validation`). diff --git a/docs/knowledgebase/managed-deployment.md b/docs/knowledgebase/managed-deployment.md index 937234e0..cc40c1e0 100644 --- a/docs/knowledgebase/managed-deployment.md +++ b/docs/knowledgebase/managed-deployment.md @@ -31,10 +31,14 @@ Classic remains default when the toggle is off. Session entry: `ManagedInstallSession` + `InstallationService.RunWithManagedInstallSessionAsync` (wizard + single-mod). Settings UI: Deployment checkbox (requires active profile). +`[REPO]` CLI overrides (parity U3 / [#177](https://github.com/oldrepublicwizard/ModSync/pull/177)): +`install --managed`, `--no-managed`, and `--profile` force classic vs managed without +editing `settings.json`. Fail-closed when managed is on without a resolvable profile. +Documented in [core-cli-reference.md](core-cli-reference.md). + `[OPEN]` Still deferred: patcher provenance (ImmutableCheckpoint), per-component -uninstall GUI polish, managed dry-run/VFS validation parity, CLI `--profile` -polish (U3). Follow-up plan: +uninstall GUI polish, managed dry-run/VFS validation parity. Follow-up plan: [docs/plans/2026-07-13-004-managed-deployment-validation-plan.md](../plans/2026-07-13-004-managed-deployment-validation-plan.md). Tests: `DeploymentServiceTests`, `ManagedInstallSessionTests`, `ModSyncSettingsTests`, -`ParityPortsTests` (backend selector). +`ParityPortsTests` (backend selector), `ManagedInstallCliOverridesTests`.