From 93d4eddda27a0b195f25099d7e31c3070c884c89 Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 21 Aug 2026 11:52:11 +1000 Subject: [PATCH 1/3] Say how to get an installed tree in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 444f178..5f951d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,6 +74,14 @@ The reasons are editing, not rendering. A long line reflows to whatever width th Line breaks still mean something everywhere else, and none of this touches them: list items, table rows, headings, fenced code, VitePress `:::` containers, YAML frontmatter and the body of an HTML comment all keep the shape they have. +## Bootstrap + +`npm ci` at the repository root, on the Node pinned in [`.nvmrc`](.nvmrc). + +Do not add `--ignore-scripts`. `postinstall` is where a usable tree comes from: `electron-builder install-app-deps` fetches the Electron binary and rebuilds the native file-locking module against its ABI, and `npm run build:once` generates `src/renderer/index.js` and `index.css`, which are not committed. Skip it and there is no renderer to load and no Electron to load it. The lint workflow installs that way deliberately, so that it never executes the pull request's code — it is the exception, not the pattern to copy. + +The user guide under `docs/` is a separate npm package with its own lockfile. A root `npm ci` does not reach it, and `npm run docs:*` fails with `vitepress: not found` until `npm ci --prefix docs` has been run once; [CONTRIBUTING.md](CONTRIBUTING.md) covers the rest of that workflow. + ## Commands See `package.json` scripts. To run a single test file (not exposed as a script): `node --test tests/unit/azure-sign.test.cjs`. From ada0de189cc2253814a0b90cfa13fb2140215ebd Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 21 Aug 2026 11:53:53 +1000 Subject: [PATCH 2/3] Correct where the Electron binary comes from 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 --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5f951d1..c68b8db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,7 +78,11 @@ Line breaks still mean something everywhere else, and none of this touches them: `npm ci` at the repository root, on the Node pinned in [`.nvmrc`](.nvmrc). -Do not add `--ignore-scripts`. `postinstall` is where a usable tree comes from: `electron-builder install-app-deps` fetches the Electron binary and rebuilds the native file-locking module against its ABI, and `npm run build:once` generates `src/renderer/index.js` and `index.css`, which are not committed. Skip it and there is no renderer to load and no Electron to load it. The lint workflow installs that way deliberately, so that it never executes the pull request's code — it is the exception, not the pattern to copy. +Do not add `--ignore-scripts`. The root `postinstall` is what makes the tree usable: `electron-builder install-app-deps` rebuilds the native file-locking module against Electron's ABI, and `npm run build:once` generates `src/renderer/index.js` and `index.css`, which are not committed. Skip it and there is no renderer to load. The lint workflow installs that way deliberately, so that it never executes the pull request's code — it is the exception, not the pattern to copy. + +The Electron binary is not part of that. `electron` ships no install script of its own; `require('electron')` downloads it into `node_modules/electron/dist/` the first time something asks for it. So a finished `npm ci` still has that download in front of the first `npm start`, `npm run test:electron` or end-to-end run. + +The `allowScripts` map in `package.json` is npm's install-script approval list, and a fresh install warns about the few packages it does not cover. That warning is expected; approving more is a change to make deliberately, not a step in getting set up. The user guide under `docs/` is a separate npm package with its own lockfile. A root `npm ci` does not reach it, and `npm run docs:*` fails with `vitepress: not found` until `npm ci --prefix docs` has been run once; [CONTRIBUTING.md](CONTRIBUTING.md) covers the rest of that workflow. From cade9d1a8aa4245735b6c602e96b7a653d4a23b8 Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 21 Aug 2026 11:57:39 +1000 Subject: [PATCH 3/3] Tidy up AI-generated instructions Co-authored-by: Gio Lodi --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c68b8db..c71347a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,11 +78,11 @@ Line breaks still mean something everywhere else, and none of this touches them: `npm ci` at the repository root, on the Node pinned in [`.nvmrc`](.nvmrc). -Do not add `--ignore-scripts`. The root `postinstall` is what makes the tree usable: `electron-builder install-app-deps` rebuilds the native file-locking module against Electron's ABI, and `npm run build:once` generates `src/renderer/index.js` and `index.css`, which are not committed. Skip it and there is no renderer to load. The lint workflow installs that way deliberately, so that it never executes the pull request's code — it is the exception, not the pattern to copy. +Do not add `--ignore-scripts`. The root `postinstall` is what makes the tree usable. -The Electron binary is not part of that. `electron` ships no install script of its own; `require('electron')` downloads it into `node_modules/electron/dist/` the first time something asks for it. So a finished `npm ci` still has that download in front of the first `npm start`, `npm run test:electron` or end-to-end run. +Notice that a finished `npm ci` still has to download the Electron binary. `electron` ships no install script of its own; `require('electron')` downloads it into `node_modules/electron/dist/` the first time something asks for it. -The `allowScripts` map in `package.json` is npm's install-script approval list, and a fresh install warns about the few packages it does not cover. That warning is expected; approving more is a change to make deliberately, not a step in getting set up. +The `allowScripts` map in `package.json` is npm's install-script approval list, and a fresh install warns about the few packages it does not cover. That warning is expected. The user guide under `docs/` is a separate npm package with its own lockfile. A root `npm ci` does not reach it, and `npm run docs:*` fails with `vitepress: not found` until `npm ci --prefix docs` has been run once; [CONTRIBUTING.md](CONTRIBUTING.md) covers the rest of that workflow.