Refresh Vortex extension design doc against settled decisions and new facts

[TheValiantOne]

Summary

docs/vortex-extension-design.md was written as a design-only reference for a future Vortex extension that would drive WSM's CLI/MCP interface. Since then, a separate planning effort (research, an advisor consult, a Plan-agent review, and explicit owner decisions) resolved most of its 8 open questions and surfaced facts the original draft didn't have. This PR folds those in, correcting/removing stale material rather than just appending, while keeping the doc's existing voice, structure, and section numbering.

• Records the scope decision (companion extension to Vortex's game-witcher3, not a replacement — no context.registerGame, no reimplementing deployment/load-order/config-matrix merging) and the location decision (vortex-extension/ folder in this repo, kept outside .sln/dotnet build/dotnet format) up front.
• Fixes the game-witcher3 source citation: Nexus-Mods/vortex-games is now archived (confirmed via gh api); current source lives in the Nexus-Mods/Vortex monorepo under extensions/games/game-witcher3/src/ (re-verified directly, not carried over from the stale citation).
• Corrects vortex-api findings against its published lib/api.d.ts typings: there is no context.registerTool API (only addDiscoveredTool); IRunOptions has no stdio/pipe access at all, so an MCP client must bypass vortex-api with a raw child_process.spawn; the documented extension entry point is init(context), not activate(context).
• Documents a second coexistence hazard: game-witcher3's per-Vortex-profile merge backup/restore (mergeBackup.ts) has no concept of MergeInventory.xml, which is a single global file with no profile awareness.
• Records the v1 bundle-content scope decision: vanilla-baseline DLC matching (e.g. Blood & Wine) is in scope; conflicts between mods Vortex deploys via its own witcher3dlc mod type are explicitly out of scope for this round.
• Replaces the old "hand-edit WitcherScriptMerger.exe.config XML" proposal with the incoming WSM_<KeyName> env-var override mechanism as the recommended approach — while keeping the hand-edit pattern's interim safety rule for anyone implementing before that mechanism lands.
• Updates Open Questions 1, 4, 5, and 6 to reflect what's now resolved or partially resolved, while leaving 2, 3, 7, and 8 genuinely open since nothing in this round settles them.
• Fixes now-stale framing: the self-contained publish convention and the Linux-capable Headless host both exist now (previously "depended-upon-but-unbuilt"); CLAUDE.md citations point at the specific per-project file responsible for each claim, since an earlier commit federated the single combined CLAUDE.md into per-project files.

Docs-only change — no source code touched.

AI assistance disclosure

This PR was drafted with Claude Code (Anthropic). All factual claims about current repo state (file/API paths, CLI verb shape, MCP tool names) and about Vortex's game-witcher3/vortex-api were independently re-verified this session via direct gh api lookups and a live fetch of the Vortex wiki, rather than trusted from the task brief or prior summaries. Reviewed by the code-review skill before submission; both findings it raised were addressed.

Test plan

• Docs-only change — no build/test required.
• Verified docs/vortex-extension-design.md is plain UTF-8, no BOM, CRLF line endings, matching this repo's existing markdown convention.
• Verified every file/API/path reference either kept or newly added against current reality (repo source files, gh api lookups against Nexus-Mods/Vortex, Nexus-Mods/vortex-games, Nexus-Mods/vortex-api, and the Vortex wiki).
• Ran the code-review skill against the diff and addressed both findings (an interim safety-rule gap in §4.1, and self-containment of Open Question 5's "landing alongside this refresh" caveat).

🤖 Generated with Claude Code

https://claude.ai/code/session_01GXAuGMLB44T5Zv5o5ZzKah