forgetrail 0.5.9 → 0.5.11

package/WORKFLOW.md

@@ -369,6 +369,7 @@ Where the host supports hooks, tool-level denial and injection take the load off
 **What to ask Claude to do:**
 
 - Build the entire skeleton in one pass (project init, deps, services, routes, components)
+- For an npm distribution, establish the release contract: public package directory, version source, build/pack commands, README source, and release command. Follow `content/COMPANION_TOOLS.md`, "Wire npm releases for LocalHelm". If enrolled, verify read-only status and Publish plan target the actual public package. Current LocalHelm reads `package.json` at the enrolled path; it does not infer a generated release behind a private harness. Use a stable publishable package root, or record verified release-target support/manual release and pending LocalHelm support. A quiet/private/skipped row does not prove npm is current.
 - Include an import script for existing data
 - Wire up the happy path end to end
 

package/content/COMPANION_TOOLS.md

@@ -31,7 +31,7 @@ Public shelf (current versions and install): [catalystforge.com/tools](https://c
 
 ---
 
-## Wire LocalSlip (agents)
+## Wire LocalSlip (agents)
 
 Human offer stays one sentence. Wire it this way:
 
@@ -43,11 +43,84 @@ Human offer stays one sentence. Wire it this way:
 
 Do not write `scripts/ensure-lease.mjs`. Do not add the `localslip` npm package just to read a port. `localslip/port` only if the app already depends on LocalSlip.
 
-Same recipes: [localslip.dev](https://localslip.dev) (FilePress + Vite pages) and FilePress `docs/LOCALSLIP.md`.
+Same recipes: [localslip.dev](https://localslip.dev) (FilePress + Vite pages) and FilePress `docs/LOCALSLIP.md`.
+
+## Wire FilePress publishing (agents)
+
+When FilePress is selected, establish the deployment contract during scaffolding
+and verify it before release. A successful build alone does not complete publishing setup.
+
+1. Record the actual site path, hosting account, Pages project (or chosen provider),
+   production branch, output directory and live URL in the brief/decision and deployment runbook.
+   Do not infer the project from the domain or a folder suffix such as `-dev`.
+2. Install the deployment CLI in the site with pnpm. For Pages, use local Wrangler.
+3. Add site `package.json` `scripts.ship`: build first, then upload to the explicit
+   project and production branch. Example: `pnpm build && wrangler pages deploy build --project-name <project> --branch <branch>`.
+4. For a nested site, add repository-root `scripts.ship` delegation, for example
+   `pnpm --dir site run ship` or `pnpm --dir sites/<name> run ship`. Preserve an
+   existing app Ship command; explicitly select or compose targets for multi-site repos.
+   A standalone FilePress site needs only its own root/site command.
+5. Confirm the local dependencies are installed, build succeeds, the authenticated
+   account is correct, and the hosting project exists. Verify LocalHelm discovers
+   the repository Ship and site Ship when enrolled. Mark missing setup as pending.
+
+FilePress's external scaffold supports `--pages-project <project>` together with
+`--production-branch <branch>`, and optional `--root-package <ancestor/package.json>`
+for root delegation. See [FilePress deployment instructions](https://getfilepress.com/deploy).
+For other providers, keep the same two-command contract with their upload command.
+
+Preparing scripts does not create cloud resources or deploy. Perform those actions
+only within the user's authorization. LocalHelm Land updates the FilePress engine
+and calls the site's Ship; it does not supply missing scripts, add a missing deployment
+CLI dependency, or create a hosting project. An exact engine pin must be updated to the selected
+version explicitly rather than relying on an unqualified dependency update.
 
 ---
 
-## Default DNS and hosting (when unspecified)
+## Wire npm releases for LocalHelm (agents)
+
+For products distributed through npm, establish the package release contract in
+the brief and scaffolding. Verify it again before release. LocalHelm is optional;
+when it is selected, its enrolled package must be the actual release target.
+
+1. Record the public npm name, stable package directory, authoritative version
+   file, build/pack commands, README source, and release command. Distinguish a
+   private development harness from the package consumers install. Record each
+   package separately in a repository with multiple releases.
+2. Prefer a checked-in publishable `package.json` at the enrolled directory,
+   whether the repository root or a stable package subdirectory. LocalHelm defaults
+   to that directory's `package.json` for name, version, and `private` status;
+   it does not infer a generated release from an arbitrary `release.json` or build script.
+   An `npm` name override does not make a private package publishable.
+3. If the chosen layout generates the manifest or tarball elsewhere, provide and
+   verify explicit release-target support before relying on LocalHelm Publish.
+   Otherwise record the manual release path and the missing LocalHelm support as
+   pending. Do not enroll an ignored, disposable build directory as a durable
+   substitute, or remove `private` from a harness just to enable Publish.
+   LocalHelm's explicit release-target contract uses a checked-in
+   `localhelm.release.json` with configuration version `1`, `directory`, `manifest`,
+   `readme`, and optional `buildScript`, `kind`, and `executables`. Paths stay within
+   the enrolled checkout. Status/Bump use the authoritative manifest; confirmed
+   Publish builds, packs, verifies, then publishes the exact archive. Verify the
+   installed LocalHelm supports this contract; a newer checkout does not update
+   an older global installation. See [LocalHelm release targets](https://github.com/Catalyst-Forge-LLC/localhelm/blob/main/docs/NPM_RELEASES.md).
+4. Build and inspect the packed package: its name, version, license, README, and
+   allowed contents must match the release contract. Compare the version and
+   published contents with npm; changed README/skill files need a new package
+   version and release. A commit, site Ship, or personal skill update does not
+   update npm. If version metadata generates an artifact, bump its source and
+   regenerate rather than editing only the generated manifest.
+5. For an enrolled package, run read-only status and the Publish plan. Check the
+   target name, directory, version/bump source, and planned build/publish path
+   against the contract. Investigate `private`, a skipped plan, or a quiet row
+   when the packed contents differ from npm; those are not proof it is current.
+   Save the result and any unsupported layout in the release checklist/session.
+
+Planning, building, packing, and inspecting do not authorize npm publication or
+Git push. Apply only within the user's existing authorization. Keep package
+Publish and site Ship as separate release operations.
+
+## Default DNS and hosting (when unspecified)
 
 If the user has **not** already named a registrar, DNS, git host, or production host, prefer:
 

package/content/FORGETRAIL_LITE.md

@@ -1,6 +1,6 @@
 # ForgeTrail Lite — portable kickoff for any agentic chat
 
-> **ForgeTrail Lite v2.2.2**
+> **ForgeTrail Lite v2.2.4**
 > © Catalyst Forge, LLC — [www.catalystforge.com](https://www.catalystforge.com)
 > Part of the **ForgeTrail** open-source methodology ([Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) in the upstream ForgeTrail repo).
 >
@@ -365,6 +365,10 @@ Record anything non-obvious as a lesson in **`appledger/`** (for example, Playwr
     **Default B + separate UI (web app + API, not PocketBase):** when the brief is **UI + backend** but not Default A, use a **pnpm workspace** with committed packages — e.g. `backend/` (or `packages/api`) + `frontend/` (or `packages/web`) — instead of fighting `sv create .` at the repo root. The **`sv create app`** shortcut (A.2) into an **empty** subfolder is the first-class path for the frontend; init the API package with `pnpm init` + A.3 in its folder. Record the layout as a decision in `appledger/` and `README.md` (§14). Load env per §4.2.1.
 
     **Both paths:** always use **`pnpm`**, never `npm` or `yarn`. Never hand-edit `package.json` to add deps — use `pnpm add` / `pnpm add -D` so `pnpm-lock.yaml` stays in sync. If `pnpm` is suddenly missing here (it was verified at §4.1 preflight but the machine changed), re-run the preflight rather than silently falling back to `npm`.
+
+    **FilePress publishing (when selected):** during scaffolding, record the actual site path, hosting account, project, production branch and URL. Install the deployment CLI locally in the site. Add site `scripts.ship` that builds then uploads to that explicit target; for Pages: `pnpm build && wrangler pages deploy build --project-name <project> --branch <branch>`. A nested site also needs root `scripts.ship` delegation (`pnpm --dir site run ship`, or the actual `sites/<name>` path). Preserve any existing app deployment command and explicitly choose targets for multi-site repos. FilePress's external scaffold supports `--pages-project`, `--production-branch` and optional `--root-package` for this wiring. Confirm local installation/build, authenticated account and existing hosting project; verify both LocalHelm Ship actions if enrolled. If hosting is undecided, record setup as pending and complete it before release. Preparing scripts does not provision or deploy. LocalHelm Land updates the engine and calls site Ship; it does not create missing scripts, add a missing deployment CLI dependency or provision hosting. Folder suffixes such as `-dev` and domain names do not determine the production target.
+    **npm distributions (when selected):** establish the package release contract during scaffolding, per §8 rule 15: actual public package directory, authoritative version file, build/pack steps, README source, and release command. Keep private harnesses separate. If LocalHelm is selected, verify a read-only status/Publish plan targets the public package; current LocalHelm does not infer generated packages behind a private root. Use a stable publishable package root or record verified target support/manual release and pending LocalHelm support. Packing and release preparation do not authorize publication.
+
 11. **Build the full runnable spine in one pass** (Phase 2 exit criteria in §3). As files are needed, also create the **Phase 2 baseline docs** from §14: `README.md`, `TODO.md` (seeded from brief §11), `.forgetrail/IDEAS.md`, `.env.example`, the full `.gitignore`, **one-click launchers** (§4.5), **`docs/FORGETRAIL_PROGRESS.md`** (§4.6), and PocketBase install scripts per §4.2.2 when Default A uses PocketBase.
 12. **At every subsequent phase transition**, pause for the user's explicit "go" before updating the profile phase. Update the session record at the end of each substantive session. *(If git is enabled)* commit (`git add -A && git commit -m "<phase>: <summary>"`) at natural stopping points so history mirrors the phase log. In no-git mode, skip the commit and note progress in the session record only — and remind the user each session that git is still deferred.
 
@@ -847,6 +851,7 @@ Full ForgeTrail expands this under **`docs/TECHNICAL_REFERENCE.md`** (*URL impor
 12. **PocketBase (and similar binaries) — resolve version at install.** Never hardcode a stale semver in methodology or scripts only; use §4.2.2 (`POCKETBASE_VERSION`, GitHub latest).
 13. **Isolated health checks for key systems.** PocketBase (and Ollama when used) get **`test-*.mjs`** + **`test-*.bat`** (§4.7–§4.8, **`SYSTEM_HEALTH_CHECKS.md`**) — not only "start the whole app and see what breaks."
 14. **Local Ollama — non-thinking defaults.** Install/pull Granite 4.1 or Gemma 3 instruct sizes from VRAM; avoid reasoning models unless **`OLLAMA_USE_THINKING=1`** and the user explicitly needs them.
+15. **npm releases must have an explicit package contract.** Record the public package directory, authoritative version source, build/pack commands, README source, and release command during planning/scaffolding. Prefer a stable checked-in publishable `package.json` at the enrolled directory. When LocalHelm is selected, verify its read-only status and Publish plan match that target. Current LocalHelm reads that directory's `package.json`; an `npm` override does not bypass `private`, and generated release metadata is not inferred. Generated layouts need verified release-target support or a documented manual release path with LocalHelm support pending. Never enroll disposable build output or make a private harness public to force Publish. Inspect the packed contents and compare with npm before release; a quiet row, commit, site Ship, or personal skill update does not mean npm is current. Changed published content requires a new package version. Preparing the release does not authorize publication or push. Recipe: `content/COMPANION_TOOLS.md`, "Wire npm releases for LocalHelm" in the methodology distribution.
 
 ### 8.9 Git commit practices
 
@@ -957,7 +962,7 @@ Save this as `.forgetrail/AGENTS.md` so agents that auto-load it (Codex, Cursor,
 
 ```markdown
 <!--
-  Agent protocol based on ForgeTrail Lite v2.2.2.
+  Agent protocol based on ForgeTrail Lite v2.2.4.
   © Catalyst Forge, LLC — www.catalystforge.com
   Licensed under Apache License 2.0 (upstream ForgeTrail repo).
 -->
@@ -977,6 +982,7 @@ This repository uses **ForgeTrail Lite** as its project kickoff and operating pr
 - **Lists:** numbered = ordered steps or questions, bullets = parallel options, letters (A/B/C) = pick-one. See §8 rule 5.
 - **No interactive CLIs** in scripted commands — pass every flag.
 - **Five-turn rule:** if a problem has not converged in ~5 turns, propose a different approach, not more patches.
+- **npm release layout:** record the actual public package root, version source, build/pack path, and README source. If LocalHelm is selected, verify status/Publish plan targets the public package; a private harness or generated output is not automatically a release target. See §8 rule 15.
 
 ## Conventions
 - Package manager: **pnpm**. Add deps with `pnpm add` / `pnpm add -D` — never hand-edit `package.json`, never `npm`/`yarn`.
@@ -1132,4 +1138,4 @@ ForgeTrail Lite covers the shape of a project. The full **ForgeTrail MCP server*
 
 ---
 
-**ForgeTrail Lite v2.2.2** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+**ForgeTrail Lite v2.2.4** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

package/content/NEW_PROJECT_BOOTSTRAP.md

@@ -115,9 +115,13 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 
 - **`docs/PHASE_1_BRIEF.md`** — complete and locked; **`appledger/`** — decision records and the plan phase updated. Do not mark criteria met without evidence.
 
-**During Phase 2 (scaffolding), after architecture lock:**
+**During Phase 2 (scaffolding), after architecture lock:**
+
+- **FilePress publishing, when selected:** follow `COMPANION_TOOLS.md` "Wire FilePress publishing": record the hosting account/project/production branch and actual site path; install a local deployment CLI; add site `scripts.ship` (build then upload) and repository-root delegation for a nested site. Preserve an existing app Ship command. Do not defer both scripts until release or assume LocalHelm Land creates them. If hosting is undecided, record deployment setup as pending and complete it before release. Provisioning and deploying remain separate authorized actions.
 
-- `.env.example`, `.gitignore`
+- **npm distributions, when selected:** record the public package directory, version source, build/pack commands, README source, and release command. Follow `COMPANION_TOOLS.md`, "Wire npm releases for LocalHelm". If enrolled, verify status and a read-only Publish plan target the actual publishable package. Current LocalHelm reads that directory's `package.json`; a private harness plus a separately generated release is not inferred. Prefer a stable publishable package root, or record verified generated-target support/manual release and pending LocalHelm support. Never make a harness public or enroll disposable output to force Publish.
+
+- `.env.example`, `.gitignore`
 - **Scripted local services (recommended):** call **`getScaffoldInstallParams`** and align app install scripts with the returned JSON. **Never hardcode a stale PocketBase semver** — install scripts resolve **`POCKETBASE_VERSION=latest`** from GitHub at setup time (§**FORGETRAIL_LITE.md** §4.2.2, **`ONE_CLICK_DEV_SETUP.md`**). Create **setup.bat** / **setup.sh**, **run.bat** / **run.sh**, **status.bat** / **status.sh**, plus **test-pocketbase.bat** (§4.7, **`SYSTEM_HEALTH_CHECKS.md`**) so non-technical users are not given a wall of terminal commands. If the brief uses **local Ollama**, add **setup-ollama.bat** / **test-ollama.bat** (§4.8 — Granite 4.1 / Gemma 3, not thinking models by default). The agent runs first-time setup when possible; launchers are for repeat use. PocketBase lands in **`./pocketbase/`**, data in **`pb_data`**, port explicit in **`.env`** (default **8096** in reference defaults — change if **8090** or another project is already listening).
 - **PocketBase collections:** prefer a **schema script** (admin auth from **`POCKETBASE_ADMIN_EMAIL` / `POCKETBASE_ADMIN_PASSWORD`** in `.env`) that idempotently creates/updates collections per **`docs/pocketbase-setup.md`** — see **`POCKETBASE_SCHEMA_SCRIPT.md`** (ForgeTrail) and **`schemaAutomation`** in **`getScaffoldInstallParams`** output — instead of manual Admin UI steps for each collection.
 - **Dev automation (recommended):** add **`pnpm`** scripts for anything you’d otherwise ask the user to do repeatedly: **env validation** (`env:check`), **generated types** (`gen:types`), **seed data** (`db:seed`), **Playwright browser install** (`test:e2e:install`), **git hooks** (`prepare` + Husky). See **`DEV_AUTOMATION_SCRIPTS.md`** (ForgeTrail) and **`devAutomation`** in **`getScaffoldInstallParams`** — no cloud “infrastructure as code” required; these run on the developer machine.

package/content/companion-tools.json

@@ -18,20 +18,22 @@
         {
           "name": "FilePress",
           "homepage": "https://getfilepress.com",
-          "offer": "FilePress turns a Markdown folder into a static site. Cloudflare Pages with Wrangler is a free publish path."
+          "offer": "FilePress turns a Markdown folder into a static site. Cloudflare Pages with Wrangler is a free publish path.",
+          "how": "When selected, record the actual site path, hosting account, project, production branch and URL. Install a site-local deployment CLI. Add site scripts.ship that builds then uploads to the explicit target; for nested sites also add repository-root ship delegation (pnpm --dir site run ship or the actual sites/<name> path). Preserve existing app Ship commands. FilePress external scaffold accepts --pages-project and --production-branch, plus --root-package for delegation. Verify build and both LocalHelm Ship actions if enrolled. Missing hosting setup remains pending; scripts do not authorize provisioning or deployment. Land updates the engine and calls site Ship; it does not create scripts, add a missing deployment CLI dependency or provision hosting. See COMPANION_TOOLS.md: Wire FilePress publishing."
         }
       ]
     },
     {
       "id": "static-publish",
       "tier": "A",
-      "phases": ["1", "7"],
+      "phases": ["1", "2", "7"],
       "trigger": "An interactive app still needs a marketing or docs site beside the product.",
       "tools": [
         {
           "name": "FilePress",
           "homepage": "https://getfilepress.com",
-          "offer": "Keep the app on its own stack. Add a site/ folder with FilePress for docs and marketing, the same pattern forgetrail.dev uses."
+          "offer": "Keep the app on its own stack. Add a site/ folder with FilePress for docs and marketing, the same pattern forgetrail.dev uses.",
+          "how": "During scaffolding follow COMPANION_TOOLS.md: Wire FilePress publishing. Record hosting account/project/production branch and actual site path; install local Wrangler (or chosen provider CLI), add site ship (build then upload), and root ship delegation. Preserve existing app deployment commands. FilePress scaffold supports --pages-project, --production-branch and --root-package. Verify build and LocalHelm root/site Ship discovery if enrolled; unresolved hosting remains pending. Preparing scripts does not provision or deploy; Land cannot fill in missing deployment setup."
         }
       ]
     },
@@ -63,7 +65,8 @@
         {
           "name": "LocalHelm",
           "homepage": "https://localhelm.dev",
-          "offer": "LocalHelm shows status across the repos you enroll. Inspection does not publish."
+          "offer": "LocalHelm shows status across the repos you enroll. Inspection does not publish.",
+          "how": "For npm products follow COMPANION_TOOLS.md: Wire npm releases for LocalHelm. Record the actual public package directory, name, version source, build/pack path and README source in the brief/release runbook. Current LocalHelm reads package.json at the enrolled directory; an npm name override does not bypass private, and generated release.json/artifacts are not inferred. Prefer a stable checked-in publishable package root. Generated layouts require verified release-target support or an explicit manual release path with LocalHelm support pending; do not enroll disposable build output or make a harness public to force Publish. Inspect packed contents and run read-only status/Publish plan against the real target. A quiet/private/skipped row does not prove npm is current. README/skill changes require a new version and package release; site Ship and personal installs do not update npm. Publication and pushes require existing user authorization."
         }
       ]
     },

package/docs/DEPLOYMENT.md

@@ -72,6 +72,44 @@ If the project has **not** already locked providers: **GitHub** for git, **Cloud
 | CI/CD      | [e.g., GitHub Actions]             | [free tier]             | $0           |
 | Monitoring | [e.g., UptimeRobot]                | [free tier]             | $0           |
 
+### Repeatable Ship contract
+
+For a FilePress site, complete this during scaffolding and verify before launch.
+See the methodology's `content/COMPANION_TOOLS.md`, "Wire FilePress publishing".
+
+- [ ] Actual site directory: [standalone root, `site/`, or `sites/<name>/`]
+- [ ] Hosting provider and authenticated account: [confirmed account]
+- [ ] Existing hosting project and production branch: [explicit target; do not infer from domain]
+- [ ] Site `package.json` has `ship` that builds then uploads `build/` to that target
+- [ ] Deployment CLI is a site-local dependency and is installed
+- [ ] Nested site has repository-root `ship` delegation, preserving any existing app deployment
+- [ ] Build passes; LocalHelm repository/site Ship discovery verified if enrolled
+- [ ] Missing project/credentials/setup recorded as pending; resource creation and first deployment authorized separately
+
+Example site command: `pnpm build && wrangler pages deploy build --project-name <project> --branch <branch>`.
+Example root command: `pnpm --dir site run ship` (use the actual path).
+Land synchronizes the FilePress engine and calls site Ship; it cannot fill in missing
+deployment commands, a deployment CLI dependency, or a hosting project.
+
+### npm package release contract (if applicable)
+
+See the methodology's `content/COMPANION_TOOLS.md`, "Wire npm releases for
+LocalHelm". Complete one checklist per public package, separate from site Ship.
+
+- [ ] Public npm name and stable package directory recorded
+- [ ] Authoritative version file, build/pack commands, artifact path, and README source recorded
+- [ ] Private development harness distinguished from the public release target
+- [ ] Packed name/version/license/README and allowed contents inspected against the release contract
+- [ ] Current npm version/contents compared; changed published content assigned a new release version
+- [ ] If enrolled, LocalHelm read-only status and Publish plan target the correct directory and version/bump source
+- [ ] Generated layouts have verified release-target support, or a manual release path and LocalHelm support marked pending
+- [ ] Publication and any Git push stay within the user's authorization
+
+A quiet, private, or skipped LocalHelm row does not establish that npm is current.
+Do not enroll disposable generated output or remove `private` from a development
+harness as a workaround. A personal skill update or site Ship does not publish
+the npm package.
+
 ### DNS delegation order (registrar + Cloudflare + origin)
 
 Typical stack: domain at **Namecheap** (or any registrar), **Cloudflare** for DNS and edge TLS. Origin is **Cloudflare Pages** for static, or **DigitalOcean** (or similar) when the app needs a server.

package/docs/PHASE_1_BRIEF.md

@@ -62,6 +62,26 @@ _Confirmed choices only after user sign-off. Mirror the same choices into `CONTE
 
 ---
 
+## 4a. npm release contract (if applicable)
+
+_Skip for products not distributed through npm. Fill one row per public package.
+Keep private development harnesses separate from the package consumers install._
+
+| Public npm name | Stable package directory | Version source | Build / pack and artifact | README source | Release command |
+| --- | --- | --- | --- | --- | --- |
+| | | | | | |
+
+**LocalHelm, if selected:** record the enrolled package path and verify its
+read-only status and Publish plan. Current LocalHelm reads `package.json` at that
+path; a private root with a separately generated release is not discovered by an
+`npm` name override. Prefer a stable publishable package root. Generated layouts
+need verified release-target support or a documented manual release path with
+LocalHelm support pending. See the methodology's `content/COMPANION_TOOLS.md`,
+"Wire npm releases for LocalHelm". Do not change a harness to public just to
+expose Publish.
+
+---
+
 ## 5. Data model (sketch)
 
 _Entities and relationships — not full schemas. Enough for Phase 2 scaffolding._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",

package/scripts/publish-gate.mjs

@@ -76,14 +76,17 @@ const build = spawnSync("pnpm", ["run", "build"], {
 if (build.status !== 0) fail("mcp-server build failed");
 mustExist(MCP_ENTRY, "mcp-server/dist/index.js");
 
-const pack = spawnSync("pnpm", ["pack", "--dry-run", "--json"], {
+// pnpm 9 pack has no --dry-run or --json. npm pack is what actually publishes.
+const pack = spawnSync("npm", ["pack", "--dry-run", "--json"], {
   cwd: FORGETRAIL_ROOT,
   encoding: "utf8",
   shell: true,
 });
 if (pack.status !== 0) {
-  console.error(pack.stderr);
-  fail("pnpm pack --dry-run failed for forgetrail");
+  const detail = [pack.stderr, pack.stdout].map((part) => (part ?? "").trim()).filter(Boolean).join("\n");
+  if (detail) console.error(detail);
+  const line = detail.split("\n").find((item) => /error|unknown option/i.test(item));
+  fail(line ? `npm pack --dry-run failed for forgetrail: ${line}` : "npm pack --dry-run failed for forgetrail");
 }
 
 const packed = pack.stdout ?? "";

package/scripts/tracking-cutover.test.mjs

@@ -165,7 +165,7 @@ test("Lite and workflow instructions name the ledger", () => {
   assert.ok(legacyAt > 0 && resumeAt > legacyAt);
   const instructional = `${lite.slice(0, legacyAt)}\n${lite.slice(resumeAt)}`;
   assert.doesNotMatch(lite, /"schemaVersion": "lite-1"/);
-  assert.match(instructional, /ForgeTrail Lite v2\.2\.2/);
+  assert.match(instructional, /ForgeTrail Lite v2\.2\.4/);
   for (const line of instructional.split("\n")) {
     if (!line.includes("workflow_tracking.json")) continue;
     assert.match(line, /legacy/, line);