From 77f0bf1079a83906ac28503268dd8b936983a72e Mon Sep 17 00:00:00 2001
From: wardsvelds2l <wards_velds2l@icloud.com>
Date: Mon, 1 Jun 2026 23:37:05 +0000
Subject: [PATCH 1/2] test: use fast TEST_KDF vault in beforeEach to avoid
 Argon2id timeouts in CI

---
 __tests__/commands/add.test.ts | 7 ++++++-
 __tests__/commands/get.test.ts | 6 +++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/__tests__/commands/add.test.ts b/__tests__/commands/add.test.ts
index 0a21dd8..50014ce 100644
--- a/__tests__/commands/add.test.ts
+++ b/__tests__/commands/add.test.ts
@@ -19,6 +19,9 @@ describe('add command', () => {
     vaultPath = path.join(tmpDir, '.env.vault');
     originalEnvPassword = process.env['ENVVAULT_PASSWORD'];
     process.env['ENVVAULT_PASSWORD'] = TEST_PASSWORD;
+    // Pre-create vault with fast test KDF so addCommand doesn't use
+    // production-grade Argon2id params (which timeout in CI coverage runs).
+    writeVault(vaultPath, createVault(TEST_KDF));
   });
 
   afterEach(() => {
@@ -36,7 +39,9 @@ describe('add command', () => {
     passwordPrompt: false,
   });
 
-  it('creates a vault if none exists and adds a variable', async () => {
+  it('creates a vault if none exists and adds a variable', { timeout: 60000 }, async () => {
+    // Remove pre-created test vault so addCommand exercises the "create" path.
+    fs.rmSync(vaultPath, { force: true });
     await addCommand('FOO=bar', {}, opts());
     const v = readVault(vaultPath);
     expect(v.version).toBe(1);
diff --git a/__tests__/commands/get.test.ts b/__tests__/commands/get.test.ts
index 3f41d85..a236260 100644
--- a/__tests__/commands/get.test.ts
+++ b/__tests__/commands/get.test.ts
@@ -4,7 +4,8 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { addCommand } from '../../src/commands/add.js';
 import { getCommand } from '../../src/commands/get.js';
-import { TEST_PASSWORD } from '../helpers.js';
+import { createVault, writeVault } from '../../src/vault.js';
+import { TEST_KDF, TEST_PASSWORD } from '../helpers.js';
 import type { GlobalOptions } from '../../src/types.js';
 
 describe('get command', () => {
@@ -25,6 +26,9 @@ describe('get command', () => {
       stdout.push(typeof chunk === 'string' ? chunk : chunk.toString());
       return true;
     }) as typeof process.stdout.write;
+    // Pre-create vault with fast test KDF so addCommand doesn't use
+    // production-grade Argon2id params (which timeout in CI coverage runs).
+    writeVault(vaultPath, createVault(TEST_KDF));
     await addCommand('FOO=bar', {}, opts());
     await addCommand('EMPTY=', {}, opts());
     await addCommand('WITH_NEWLINE=line1\nline2', {}, opts());

From da1b3450ebcbc1f7ae50d26754e98564e0a21b8d Mon Sep 17 00:00:00 2001
From: wardsvelds2l <wards_velds2l@icloud.com>
Date: Tue, 2 Jun 2026 00:08:11 +0000
Subject: [PATCH 2/2] docs: add local development instructions to README

---
 README.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index cb6ec22..75387dd 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,8 @@ The full line-by-line construction is in [`examples/threat-model.md` § 5](./exa
 
 ## Installation
 
+### From npm (recommended)
+
 ```bash
 npm install -g envault
 ```
@@ -161,10 +163,23 @@ Or run it without installing:
 npx envault@^0.2.0 init
 ```
 
-Or grab the prebuilt single-file bundle from the [releases page](https://github.com/wardsvelds2l/envault/releases) — `dist/envault.js` is one self-contained file, no `node_modules` needed at runtime.
-
 Requires Node.js 20.0 or newer (we test 20 and 22 in CI on Ubuntu, macOS, and Windows).
 
+### From source (local development)
+
+```bash
+git clone https://github.com/wardsvelds2l/envault.git
+cd envault
+npm install
+npm run bundle        # builds dist/envault.js
+npm link              # makes `envault` available globally
+envault --help
+```
+
+`dist/envault.js` is one self-contained file — no `node_modules` needed at runtime. You can also grab a prebuilt bundle from the [releases page](https://github.com/wardsvelds2l/envault/releases).
+
+After `npm link`, all `envault` commands used throughout this README work as written. To unlink later, run `npm unlink -g envault`.
+
 ## Quick start
 
 ```bash