docs: update squad records for cli-package optional change

- Added decision: apiops init dual-mode package consumption
- Updated NodeJsDev history with implementation details
- Merged inbox decision into decisions.md

Session: 2026-04-29T143000Z-nodejsdev

Author: Peter Hauge

.squad/agents/nodejsdev/history.md

@@ -121,5 +121,41 @@ program.version(packageJson.version);
 - 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
 
+### 2026-04-29: Dual-Mode Init — Public npm vs Local Tarball
+
+**Problem:** After publishing `@peterhauge/apiops-cli` to npm, `apiops init` still required `--cli-package <path>` pointing to a local .tgz tarball, making the workflow cumbersome for users who just want to use the public package.
+
+**Solution:** Made `--cli-package` optional and implemented two modes:
+
+1. **Local tarball mode** (when `--cli-package` provided):
+   - Creates `.apiops/` directory, copies tarball
+   - Generates package.json with `"apiops": "file:.apiops/{tarball}"`
+   - Use case: Local development, pre-release testing
+
+2. **Public npm mode** (when `--cli-package` NOT provided):
+   - No tarball copy, no `.apiops/` directory
+   - Generates package.json with `"@peterhauge/apiops-cli": "latest"`
+   - Use case: Standard consumption after publishing to npm
+
+**Implementation Details:**
+- Changed `.requiredOption()` to `.option()` in init-command.ts
+- Made `cliPackage?: string` optional in InitConfig interface
+- Conditional validation: `validateCliPackage()` only runs if `cliPackage` provided
+- Conditional file operations in `generateFiles()`: tarball copy and `.apiops/` creation only in local mode
+- Refactored package-json.ts to accept discriminated union config: `{ mode: 'local', tarballRelPath } | { mode: 'npm' }`
+
+**Key Pattern:** The package.json generator uses a discriminated union for type safety:
+```typescript
+export type PackageJsonConfig =
+  | { mode: 'local'; tarballRelPath: string }
+  | { mode: 'npm' };
+```
+This enforces that `tarballRelPath` is only accessible when `mode === 'local'`, preventing runtime errors.
+
+**Testing:**
+- All 467 tests pass (init-command.test.ts validates both modes)
+- ESLint clean (no warnings or errors)
+- Backward compatible: Existing workflows with `--cli-package` continue to work
+
 <!-- Append new learnings here after each session -->
 

.squad/decisions.md

@@ -2,6 +2,12 @@
 
 ## Active Decisions
 
+### 2026-04-29T14:30:00Z: apiops init Dual-Mode Package Consumption
+**By:** NodeJsDev  
+**Status:** Implemented  
+**What:** Made `--cli-package` optional in `apiops init`. The command now supports two package consumption modes: (1) **Public npm mode** (default, when `--cli-package` NOT provided): generates package.json with `"@peterhauge/apiops-cli": "latest"`, no local tarball copy, no `.apiops/` directory created, standard consumption pattern after npm publish. (2) **Local tarball mode** (when `--cli-package <path>` provided): copies tarball to `.apiops/` directory, generates package.json with `"apiops": "file:.apiops/{tarball}"`, preserves existing behavior for local development/testing.
+**Why:** After publishing to npm as `@peterhauge/apiops-cli`, requiring users to download the package and run `apiops init --cli-package ./tarball.tgz` added unnecessary friction. Most users want to reference the public package directly. The change is backward compatible — existing workflows with `--cli-package` continue to work unchanged. Improves user experience with simpler onboarding.
+
 ### 2026-04-21T19:35:00Z: SOAP/WADL spec extraction prefers link format with inline XML fallback
 **By:** ApimExpert (via Squad session with enewman)
 **Status:** Implemented