Say how to get an installed tree in AGENTS.md - #392
Open
mokagio wants to merge 3 commits into
Open
Conversation
An agent arriving here could find the review standard, the Markdown convention and how to run one test file, but nothing about installing — that lived only in `README.md`, written for a human building from source, and in `CONTRIBUTING.md`, written to explain what CI does. The warning against `--ignore-scripts` is the part worth stating rather than leaving to be discovered: `postinstall` is what fetches the Electron binary, rebuilds the native file-locking module against its ABI, and generates the renderer bundle, none of which are in the tree already. The lint workflow installs that way on purpose so it never executes a pull request's code, which makes it easy to copy for the wrong reason. --- Generated with the help of Claude Code, https://code.claude.com Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Written from the workflow comments, which say `postinstall` pulls the Electron binary. Running a clean `npm ci` and looking says otherwise: `electron` ships no install script, `node_modules/electron/dist/` is absent when the install finishes, and it appears the moment something first requires `electron`. That difference is the reason to write it down. An install that looks complete still has a download in front of the first run, which is not what "postinstall fetches it" leads anyone to expect. --- Generated with the help of Claude Code, https://code.claude.com Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds bootstrap guidance so agents can install a usable development tree without inferring steps from workflows.
Changes:
- Documents root installation, postinstall behavior, and Electron’s lazy download.
- Clarifies install-script warnings and the separate docs package.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
mokagio
commented
Aug 21, 2026
Co-authored-by: Gio Lodi <giovanni.lodi42@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a "Bootstrap" section to
AGENTS.mdwith instruction on how to set up a new checkout.AI-generated details
Why
AGENTS.mdtells an agent how to review, how to write Markdown here and how to run one test file, but never how to get an installed tree to run any of it in. Those steps existed only inREADME.md, written for a human building from source, and inCONTRIBUTING.md, written to explain what CI does — neither is where an agent looks first, and neither says which parts are traps.This came up while working on another branch: an agent following
AGENTS.mdhad no documented install step and had to infer one from the workflow files.What changes
A
Bootstrapsection aboveCommands, holding only what a reader cannot deduce frompackage.json: what the rootpostinstallactually produces, why--ignore-scriptsis the wrong shortcut even though the lint workflow uses it, when the Electron binary is really downloaded, and thatdocs/is a separate package with its own lockfile. It points atCONTRIBUTING.mdfor the docs workflow rather than restating it.One thing the second commit corrects rather than adds. The workflow comments say
postinstallpulls the Electron binary. Running a cleannpm ciand looking shows it does not:electronships no install script,node_modules/electron/dist/is absent when the install finishes, and it appears the first time something requireselectron. So a finished install still has a download in front of the firstnpm startor E2E run, which is worth knowing when a first run seems to hang.How to test this
Platforms: any — this is documentation, and the claims in it were checked on macOS.
Starting state: a clean checkout of this branch with no
node_modules.npm ciat the root. It should exit 0, warn about the packagesallowScriptsdoes not cover, and leavesrc/renderer/index.jsandsrc/renderer/index.csson disk.ls node_modules/electron/dist— should not exist yet.node -e "console.log(require('electron'))"— printsDownloading Electron binary..., then a path undernode_modules/electron/dist/.What must not have happened: none of the section's claims should hold only on one machine. If step 2 finds a
dist/directory already there, the paragraph about the lazy download is wrong for that setup and should be fixed rather than left to mislead.Risks and limitations
Documentation only; no code path changes. The three steps above were run on macOS with Node 24.19.0 against
.nvmrc's 24.18.0 — close but not identical, so a Windows or exact-version run confirming the same behaviour would be worth having before treating it as settled.Related
Follow-up to work on #391.