chore: migrate pi-* deps to @earendil-works, harden native install (v0.3.1)

.agentforge/extensions/example-skill.ts

@@ -12,8 +12,8 @@
  * See: docs/pi-coding-agent-extensions.md
  */
 
-import { defineTool } from "@mariozechner/pi-coding-agent";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
 export default (pi: ExtensionAPI) => {

.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: ['20', '22']
+        node: ['22']
     steps:
       - uses: actions/checkout@v5
 

.github/workflows/release.yml

@@ -66,7 +66,7 @@ jobs:
           git config --global user.name "AgentForge CI"
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: npm
       - run: npm ci
       # Root build runs dashboard SPA + tsc --build + copy-build-assets.
@@ -87,7 +87,7 @@ jobs:
       - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
         with:
-          node-version: '20'
+          node-version: '22'
           cache: npm
           registry-url: 'https://registry.npmjs.org'
       - run: npm ci

CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.3.1] — Dependency migration & Node 22 requirement
+
+Maintenance release: migrates off the deprecated `@mariozechner/pi-*` packages
+and hardens the first-run experience on npm 11+.
+
+### Changed
+
+- **BREAKING — Node.js ≥ 22.19 is now required.** The pi execution backends
+  (`@earendil-works/pi-*` 0.79) declare `engines.node >= 22.19.0` (their bundled
+  undici relies on a Node 22 API), so Node 20 is no longer supported. `engines`
+  across all packages, the CI matrix, the runtime Docker images
+  (`node:22-alpine`), and the docs are updated accordingly.
+- **pi backends migrated to `@earendil-works/pi-*`** — `pi-ai`, `pi-agent-core`,
+  and `pi-coding-agent` move from the deprecated/renamed `@mariozechner/pi-*`
+  packages to `@earendil-works/pi-*` `^0.79.9`. This clears the deprecation
+  warnings shown on `npm install`. No public API change.
+
+### Added
+
+- **Actionable native-binding error.** A missing or incompatible `better-sqlite3`
+  build now fails with guidance to run `npm approve-scripts better-sqlite3 koffi`
+  then `npm rebuild`, instead of a cryptic "Could not locate the bindings file".
+- **npm 11+ install-script note** in both READMEs and the getting-started guide —
+  npm 11 gates dependency install scripts, and the native modules
+  (`better-sqlite3`, `koffi`) must be approved to build.
+
 ## [0.3.0] — Per-agent model selection
 
 Agent definitions can now choose their own model. Previously `spec.model`

Dockerfile

@@ -9,7 +9,7 @@
 # Platform image runs agentforge with Docker/Postgres/OTel/worker modes.
 
 # ── Stage: deps — install all workspace deps (for building) ─────────────────
-FROM node:20-alpine AS deps
+FROM node:22-alpine AS deps
 WORKDIR /app
 COPY package.json package-lock.json ./
 COPY packages/core/package.json ./packages/core/
@@ -35,22 +35,22 @@ RUN npm run build
 # Installs just agentforge-core's deps in isolation (no workspace hoisting,
 # no platform-only deps like pg/dockerode/OTel SDK). Uses a standalone
 # lockfile (packages/core/package-lock.json) so builds are deterministic.
-FROM node:20-alpine AS core-deps
+FROM node:22-alpine AS core-deps
 WORKDIR /app/packages/core
 COPY packages/core/package.json ./package.json
 COPY packages/core/package-lock.json ./package-lock.json
 RUN npm ci --omit=dev --no-audit --no-fund && npm cache clean --force
 
 # ── Stage: platform-deps — full workspace production node_modules ───────────
-FROM node:20-alpine AS platform-deps
+FROM node:22-alpine AS platform-deps
 WORKDIR /app
 COPY package.json package-lock.json ./
 COPY packages/core/package.json ./packages/core/
 COPY packages/platform/package.json ./packages/platform/
 RUN npm ci --omit=dev && npm cache clean --force
 
 # ── Target: core — slim image (agentforge-core CLI only) ────────────────────
-FROM node:20-alpine AS core
+FROM node:22-alpine AS core
 WORKDIR /app
 COPY --from=core-deps /app/packages/core/node_modules ./packages/core/node_modules
 COPY --from=core-deps /app/packages/core/package.json ./packages/core/package.json

README.md

@@ -20,6 +20,8 @@ Ships with a reference SDLC template — runnable end-to-end in minutes. Domain-
 
 ## Quick Start
 
+> **Requires Node.js 22.19 or later** (the bundled pi execution backends set this floor).
+
 ```bash
 # 1. Install
 npm install @mandarnilange/agentforge
@@ -37,6 +39,21 @@ npx @mandarnilange/agentforge run --project my-app --input "brief=Build a freela
 npx @mandarnilange/agentforge dashboard           # → http://localhost:3001
 ```
 
+> **npm 11+ note — approve native install scripts.** npm now blocks dependency
+> install scripts by default. AgentForge depends on the native module
+> `better-sqlite3` (and `koffi`), which **need** their build scripts to compile.
+> If your install warns that packages are "not yet covered by allowScripts",
+> approve and rebuild them so the native binaries are built:
+>
+> ```bash
+> npm approve-scripts better-sqlite3 koffi
+> npm rebuild
+> ```
+>
+> Skipping this leaves `better-sqlite3` uncompiled and AgentForge fails at
+> runtime with a native-binding load error. Avoid `--all` /
+> `--dangerously-allow-all-scripts`: approve only the packages you trust.
+
 ---
 
 ## The harness model — what makes AgentForge different
@@ -307,7 +324,7 @@ Every deep-dive lives in [`docs/`](docs/). Pick a track:
 
 ## Stability
 
-v0.2.0 release candidate (`v0.2.0-rc.2`) — early-feedback build. API surface is stabilising but may still shift. `npm install @mandarnilange/agentforge` pulls the RC. [Open an issue](https://github.com/mandarnilange/agentforge/issues) for anything that looks rough, or use [Discussions](https://github.com/mandarnilange/agentforge/discussions) for usage questions.
+v0.3.x — early but stabilising. The API surface is settling down but may still shift before 1.0. `npm install @mandarnilange/agentforge` pulls the latest release. [Open an issue](https://github.com/mandarnilange/agentforge/issues) for anything that looks rough, or use [Discussions](https://github.com/mandarnilange/agentforge/discussions) for usage questions.
 
 ---
 

ROADMAP.md

@@ -53,7 +53,7 @@ spec:
 
 ### OpenCode execution backend
 
-**Problem.** `@mandarnilange/agentforge-core` ships with `@mariozechner/pi-coding-agent` as the only coding runtime. The `IExecutionBackend` port exists so others can plug in, but no adapter has been written yet. OpenCode is a strong candidate — actively developed, TypeScript, similar tool surface.
+**Problem.** `@mandarnilange/agentforge-core` ships with `@earendil-works/pi-coding-agent` as the only coding runtime. The `IExecutionBackend` port exists so others can plug in, but no adapter has been written yet. OpenCode is a strong candidate — actively developed, TypeScript, similar tool surface.
 
 **Proposal.** New `OpenCodeExecutionBackend` in the platform package. Accepts an `AgentJob`, delegates to OpenCode's CLI or SDK, forwards status updates back via the `onStatus` callback, returns an `AgentJobResult`. Config via agent YAML `executor: opencode`.
 

docs/architecture.md

@@ -275,7 +275,7 @@ Two backends implement `IExecutionBackend`, selected per-agent based on the agen
 │                │    │                             │
 │  executor:     │    │  executor: pi-coding-agent  │
 │  "pi-ai"       │    │                             │
-│                │    │  Wraps @mariozechner/       │
+│                │    │  Wraps @earendil-works/     │
 │  Uses stream() │    │  pi-agent-core Agent        │
 │  from pi-ai    │    │                             │
 │                │    │  Has access to tools:       │

docs/getting-started.md

@@ -47,7 +47,7 @@ npx @mandarnilange/agentforge run --project my-saas --input "brief=Build a SaaS
 
 ## 2. Prerequisites
 
-- **Node.js** 20 or later
+- **Node.js** 22.19 or later (required by the bundled pi execution backends)
 - **npm** 9 or later
 - **An LLM API key** (Anthropic by default)
 - **Docker** (optional — for sandboxed execution and Docker executor mode)
@@ -66,6 +66,19 @@ npm install @mandarnilange/agentforge
 
 > Both packages are scoped under `@mandarnilange/*`. The CLI binaries — `agentforge` (platform) and `agentforge-core` (core only) — are unchanged; only the install paths carry the scope.
 
+> **npm 11+ — approve native install scripts.** npm now blocks dependency install
+> scripts by default. AgentForge depends on the native module `better-sqlite3`
+> (and `koffi`), which **need** their build scripts to compile. If your install
+> warns that packages are "not yet covered by allowScripts", approve and rebuild
+> them, otherwise AgentForge fails at runtime with a native-binding load error:
+>
+> ```bash
+> npm approve-scripts better-sqlite3 koffi
+> npm rebuild
+> ```
+>
+> Approve only the packages you trust — avoid `--all` / `--dangerously-allow-all-scripts`.
+
 If you want the framework primitives without the platform binary or the multi-provider / Postgres / Docker executor extras, install core directly:
 
 ```bash
@@ -83,7 +96,7 @@ npm run build
 Verify the installation:
 
 ```bash
-npx @mandarnilange/agentforge --version         # prints 0.2.0
+npx @mandarnilange/agentforge --version         # prints 0.3.1
 npx @mandarnilange/agentforge list              # lists scaffolded agents (after init)
 npx @mandarnilange/agentforge templates list    # lists bundled pipeline templates
 ```
@@ -342,7 +355,7 @@ Write a result manifest to `/output/_result.json`:
 ### Example Dockerfile
 
 ```dockerfile
-FROM node:20-alpine
+FROM node:22-alpine
 WORKDIR /app
 COPY package.json .
 RUN npm ci

docs/pi-coding-agent-extensions.md

@@ -6,7 +6,7 @@ This guide explains how to add custom functionality (extensions and tools) to th
 
 ## Core Concepts
 
-The `@mariozechner/pi-coding-agent` SDK provides two primary ways to extend an agent's capabilities:
+The `@earendil-works/pi-coding-agent` SDK provides two primary ways to extend an agent's capabilities:
 
 1.  **Custom Tools**: Direct addition of LLM-callable functions (e.g., `read_file`, `bash`).
 2.  **Extensions**: Full TypeScript modules that can subscribe to lifecycle events (`turn_start`, `message_end`), register commands, and inject context.
@@ -18,8 +18,8 @@ The `@mariozechner/pi-coding-agent` SDK provides two primary ways to extend an a
 If your extension is a stateless capability (like querying a specific database or calling an API), you can define a `ToolDefinition` and add it to the agent's initial state.
 
 ```typescript
-import { Agent } from "@mariozechner/pi-agent-core";
-import { defineTool, createCodingTools } from "@mariozechner/pi-coding-agent";
+import { Agent } from "@earendil-works/pi-agent-core";
+import { defineTool, createCodingTools } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
 // 1. Define your custom tool with a schema
@@ -70,7 +70,7 @@ import {
   loadExtensionFromFactory, 
   createExtensionRuntime, 
   ExtensionRunner 
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 // 1. Define an inline extension factory
 const myExtensionFactory = (pi: ExtensionAPI) => {

docs/platform-architecture.md

@@ -623,8 +623,8 @@ interface IExecutionBackend {
 
 | Backend | Library | Used By | Capabilities |
 |---------|---------|---------|-------------|
-| `PiAiExecutionBackend` | `@mariozechner/pi-ai` | Pure-LLM agents (e.g., analyst, architect) | LLM streaming, document generation |
-| `PiCodingAgentExecutionBackend` | `@mariozechner/pi-coding-agent` | Tool-using agents (e.g., developer, QA, security) | LLM + file tools + bash |
+| `PiAiExecutionBackend` | `@earendil-works/pi-ai` | Pure-LLM agents (e.g., analyst, architect) | LLM streaming, document generation |
+| `PiCodingAgentExecutionBackend` | `@earendil-works/pi-coding-agent` | Tool-using agents (e.g., developer, QA, security) | LLM + file tools + bash |
 
 **Backend selection**: Based on `agentDefinition.spec.executor` field (`"pi-ai"` or `"pi-coding-agent"`).
 
@@ -1631,8 +1631,8 @@ Implements domain ports with concrete technologies:
 | `SqliteStateStore` | `IStateStore` | better-sqlite3 |
 | `FsArtifactStore` | `IArtifactStore` | Node.js fs |
 | `FilePromptLoader` | `IPromptLoader` | Node.js fs |
-| `PiAiExecutionBackend` | `IExecutionBackend` | @mariozechner/pi-ai |
-| `PiCodingAgentExecutionBackend` | `IExecutionBackend` | @mariozechner/pi-coding-agent |
+| `PiAiExecutionBackend` | `IExecutionBackend` | @earendil-works/pi-ai |
+| `PiCodingAgentExecutionBackend` | `IExecutionBackend` | @earendil-works/pi-coding-agent |
 | `LocalAgentExecutor` | `IAgentExecutor` | In-process |
 | `DockerAgentExecutor` | `IAgentExecutor` | dockerode |
 | `RemoteAgentExecutor` | `IAgentExecutor` | HTTP/fetch |
@@ -1887,7 +1887,7 @@ To build a custom Docker image for the `DockerAgentExecutor`:
 **Dockerfile example:**
 
 ```dockerfile
-FROM node:20-alpine
+FROM node:22-alpine
 WORKDIR /app
 
 # Install your agent runtime