docs: move project documentation into docs/ by insomnious · Pull Request #24071 · Nexus-Mods/Vortex

insomnious · 2026-08-31T19:16:08Z

The six AGENTS-*.md files at the repo root are gone. Everything in them that was project or coding documentation is now in docs/, indexed by docs/README.md, and AGENTS.md covers only how to operate in this repo: commands, tools, skills, and which doc to read for a task.

They moved because a file only agents read never gets reviewed the way a doc a human opens does, so it rots. AGENTS-DIRECTORIES.md had eight wrong paths in sixty lines by the time I moved it. Auditing the rest of docs/ then turned up another 40 citations pointing at files that do not exist, mostly the packages having moved to src/<pkg>/src/ without the docs following.

The layout now:

docs/ owns all project and coding documentation, whoever the reader is
docs/README.md indexes it, and every new doc gets a line there
docs/writing-documentation.md holds the conventions: naming, structure, tone, and one owner per fact
The root keeps only the files convention puts there: README, CONTRIBUTING, CODESTYLE, CHANGELOG, RELEASES, SECURITY, SUPPORT, CODE_OF_CONDUCT

Worth looking at first: docs/I18N_STATUS.md carries a new warning rather than a fix. It documented the i18next separators as : and . while the code sets ::: and ::, and the migration guide, the locale files and the one migrated example all assume the documented format. Someone who knows the i18n work should decide which side is wrong before more strings are migrated.

The only non-markdown file is InstallManager.ts, where three comments pointed at AGENTS-COLLECTIONS.md. Comment text only, no behaviour change.

Untested beyond pnpm run format and an audit that every cited source path and relative link resolves. It is all markdown apart from those comments.

docs/ had 31 files and no index, so the AGENTS.md routing table was doing index duty by default. Adds docs/README.md grouped by task. writing-documentation.md states the convention we've been drifting towards anyway: project and coding docs go in docs/, AGENTS.md is for agent instructions only. Written as a doc so an LLM asked to add documentation finds the rule at the point of need. Also fixes four lowercase admonition markers. GitHub only renders [!NOTE] etc in uppercase; lowercase silently degrades to a blockquote.

Content is near-verbatim apart from the fixes below. Dropped the "read this file when doing X" preambles, since routing is AGENTS.md's job now. repo-layout.md: AGENTS-DIRECTORIES had drifted badly. The Packages section listed four packages that don't exist (paths, paths-node, game-extension-helpers, install-entries) and omitted nine that do. Two of four extension examples pointed at extensions/ when collections and the fomod installers actually live under src/renderer/src/extensions/. samples/sample-extension/ doesn't exist at all. All rewritten from the real tree, and the renderer/bundled extension split is now explicit because that was the part most likely to send someone to the wrong half of the repo. testing.md: AGENTS-TESTING and AGENTS-FRONTEND contradicted each other on selectors, one mandating data-testid and the other role/label/text. The codebase is genuinely split, so this documents when to use which: role where unambiguous, testid when not, text only in E2E. Keeps the reason text matching misleads in unit tests (no i18n instance, so t returns the key). Also notes that pnpm run test excludes the E2E suite. frontend.md: trimmed the commands section, which duplicated the standard build/test/format loop, keeping the pnpm run api step that is genuinely renderer-specific. Moved the i18n key format out to the i18n guide, which now records that the :: and ::: forms exist in legacy code, since that convention is unsettled and shouldn't be stated twice.

collections.md: fixes two paths AGENTS-COLLECTIONS had wrong. It cited src/extensions/mod_management/InstallManager.ts, which doesn't exist (it's under src/renderer/src/), and __tests__/PhasedInstaller.test.ts, which doesn't exist either; there is no __tests__ dir. Replaced with the four real test files. Added InstallPhaseTracker.ts, rulePhase.ts and requeueCandidates.ts to Key Files, since the critical rules named them without saying where they live. Points at InstallManager's own header comment for the phase state detail rather than restating it. DEBUGGING-GUIDE.md: AGENTS-DEBUGGING's F5/breakpoint bullets were already covered here and in CONTRIBUTING.md, so they're dropped. The VORTEX_TRACE_DB_WRITES documentation was the only unique content and was in neither, so it becomes a new Diagnostic Environment Variables section next to Log Files. The watch-log skill cross-checks the level_pivot marker strings against this text, so they're kept verbatim; drift-check passes. Also fixes the hand-maintained ToC, which listed a Native Module Debugging section that no longer exists and omitted Advanced Debugging Tools. Dropped a leftover personal TODO note from AGENTS-DEBUGGING. The three InstallManager.ts references are comments only; renderer typecheck passes.

Deletes 52 lines and adds about 10, which needs explaining: windows.md was already a strict superset of AGENTS-PACKAGING. Same version injection commands, same standalone-src/main trap with the same error string, same asar guard with the electron-builder 24.13.3 pinning rationale, same artifact list. The three updater env vars are better covered in updater-testing.md. Two things were genuinely only in the AGENTS file, and both are carried over: the explicit `node scripts/verify-packaged-asar.mjs` invocation (windows.md described the guard as a pipeline step without ever giving the command), and the pointer to the signed rehearsal and scripts/updater-e2e-staging.mjs. Nothing else was lost. The four dropped sections were duplicates.

AGENTS.md now holds only what an agent needs to operate here, and defers to docs/ for everything project and coding related. Sections: verify, commit, toolchain, tool use, MCP, skills, and a task-to-doc table. Most of this is new rather than moved. The old file had no MCP references, no tool preferences and no mention of the three repo skills, so the routing table was the only genuinely agent-specific thing in it. The new content is verified against the repo's own config: - pnpm run build already runs lint and typecheck, so the old advice to run all four separately cost two redundant Nx fan-outs per change. - pnpm run test excludes @vortex/e2e, so passing it is not evidence that E2E passes. - The pre-commit hook runs oxfmt over every staged file including markdown, which surprises anyone who carefully formatted a file first. - Node and pnpm are pinned exactly, so reaching for npm breaks things. Also removes a stale bullet from the changelog skill claiming AGENTS.md documents a reference-link convention under a ## Changelog section. No such section existed and the convention isn't written down anywhere; the line above it already names CHANGELOG.md as the style reference. README and CONTRIBUTING now point at docs/README.md rather than the bare directory. Unrelated drive-by in DEBUGGING-GUIDE.md: the Redux DevTools link pointed at src/util/reduxDevTools.ts, which doesn't exist. Repointed at where that wiring actually lives.

The packages moved to src/<pkg>/src at some point and the docs never followed, so 40 path citations pointed at nothing. Two needed more than the missing segment: the renderer telemetry module is not under extensions/, and main's build output is build/, not out/. The i18n docs also cited line numbers, which I dropped rather than update, since they rot. I18N_STATUS.md documented the i18next separators as ':' and '.' while the code sets ':::' and '::'. The doc now states what the code does and carries a warning rather than a fix, because the migration guide, the locale files and the migrated example all assume the documented format. Which side is wrong needs checking before more strings are migrated. Also gathered the diagnostic environment variables into one table linking to whichever doc owns each, documented the four that were undocumented, and gave install-instructions/ the README index the three-file rule asks for.

AGENTS.md is injected into every session, so anything the harness already provides is paid for on every run and returns nothing. The skills list, the MCP server names, prefer-file-tools-over-shell, cite-path:line and the default shell are all in the system prompt already. The toolchain section was worse than redundant: it duplicated docs/install-instructions/shared.md while hardcoding the pnpm and node versions that shared.md deliberately does not. 96 lines down to 56. New `pnpm run verify` chains format, build and test, so there is one call to make instead of three. Format goes first so build validates what the formatter produced. The pre-commit hook behaviour moved to CONTRIBUTING.md. Review feedback from Sewer56 on #24071.

Sewer56

Note that I didn't go through the frontend stuff too deeply, as I've not touched that part of the codebase.

All's good otherwise 👌

AGENTS.md is injected into every session, so anything the harness already provides is paid for on every run and returns nothing. The skills list, the MCP server names, prefer-file-tools-over-shell, cite-path:line and the default shell are all in the system prompt already. The toolchain section was worse than redundant: it duplicated docs/install-instructions/shared.md while hardcoding the pnpm and node versions that shared.md deliberately does not. 96 lines down to 56. New `pnpm run verify` chains format, build and test, so there is one call to make instead of three. Format goes first so build validates what the formatter produced. The pre-commit hook behaviour moved to CONTRIBUTING.md. Review feedback from Sewer56 on #24071.

insomnious added 8 commits August 27, 2026 23:24

docs: replace the Volta setup flow with pnpm-managed node

b06a7b0

Merge branch 'master' into docs/full-docs-sweep

a44aaca

insomnious requested a review from a team as a code owner August 31, 2026 19:16

insomnious self-assigned this Aug 31, 2026

Sewer56 reviewed Aug 31, 2026

View reviewed changes