docs: document version management decision

NodeJsDev implemented single-source-of-truth version management using
ESM import attributes to read from package.json at runtime.

- Created decisions.md with version management pattern
- Updated NodeJsDev history with implementation details
- Decision: Use 'with { type: 'json' }' import syntax for Node 22+

Author: Peter Hauge

.squad/agents/nodejsdev/history.md

@@ -94,5 +94,32 @@
 - Unknown commands log error to stderr and exit with code 1
 - Build and lint pass without errors
 
+### 2026-04-29: Version Management Pattern — Single Source of Truth
+
+**Problem:** Version was maintained in two places: `package.json` ("0.1.3-alpha.0") and hardcoded in `src/cli/index.ts` (".version('0.1.0')"). This caused version drift and required manual updates in both locations.
+
+**Solution:** Import version from `package.json` using ESM import attributes (Node 22+ with TypeScript):
+```typescript
+import packageJson from '../../package.json' with { type: 'json' };
+program.version(packageJson.version);
+```
+
+**Key Implementation Notes:**
+1. **Import syntax:** Use `with { type: 'json' }` (not `assert`) — TypeScript TS2880 error enforces the newer import attributes syntax
+2. **Path resolution:** From `src/cli/index.ts`, use `../../package.json` — when compiled to `dist/cli/index.js`, this resolves correctly to root `package.json`
+3. **tsconfig requirement:** `resolveJsonModule: true` (already configured) enables JSON imports in TypeScript
+4. **Node version:** Requires Node 22+ for import attributes support (already enforced via `"engines": {"node": ">=22.0.0"}`)
+
+**Benefits:**
+- Single source of truth: `package.json` version is the canonical version
+- Automated versioning: `npm version` updates package.json, CLI automatically reflects the change
+- Eliminates drift: No manual synchronization required between files
+- Standard pattern: Follows Node.js ecosystem conventions for CLI tools
+
+**Verification:**
+- Build passes: `npm run build` compiles successfully
+- Version output correct: `node dist/cli/index.js --version` displays "0.1.3-alpha.0" from package.json
+- No runtime dependencies: Uses native Node ESM features, no additional packages required
+
 <!-- Append new learnings here after each session -->
 

.squad/decisions/decisions.md

@@ -0,0 +1,14 @@
+# Technical Decisions
+
+All architectural and implementation decisions for apiops-cli.
+
+---
+
+### 2026-04-29: CLI version uses package.json as single source of truth via ESM import attributes
+**By:** NodeJsDev  
+**Status:** Implemented  
+**What:** The CLI version displayed by `apiops --version` is imported from `package.json` using ESM import attributes: `import packageJson from '../../package.json' with { type: 'json' }`. The Commander program uses `program.version(packageJson.version)` instead of a hardcoded string.  
+**Why:** Eliminates version drift between package.json and CLI output. Previously, version was hardcoded in `src/cli/index.ts` (".version('0.1.0')") while package.json had "0.1.3-alpha.0". Now `npm version` automatically updates the CLI version with no manual synchronization required. This is the standard pattern for Node.js CLI tools and requires no runtime dependencies — uses native Node 22+ ESM features with TypeScript's `resolveJsonModule: true`.  
+**Note:** Import syntax must use `with { type: 'json' }` not `assert { type: 'json' }` — TypeScript enforces the newer import attributes syntax (TS2880 error if using `assert`).
+
+---