chore: align source build prerequisites and retire inert tsup override

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Source-build and override hygiene**: Document the qualified Node.js source-development range and one-time native bootstrap while retaining the installed Node.js 22.13 minimum; remove the fresh-resolution-proven inert tsup 8 esbuild exception and update its security-policy history without weakening other patched floors.
+
 ### Fixed
 
 - **Pi real-host prompt tests**: Use Pi 1.3's user-trigger/options runner API and raise only the development host floor to 1.3, retaining sibling section/append preservation and intentional override assertions in both extension orders. The optional Pi peer contract, production extension, legacy string-return fallback, and omp behavior are unchanged.

CONTRIBUTING.md

@@ -35,14 +35,18 @@ Use this when you just want the shortest path to a good PR:
    ```
 4. **Build the project**:
    ```bash
+   # Bootstrap once after a fresh install if the native addon is absent.
+   npm run build:native
    npm run build
    ```
 
+The first combined build runs its TypeScript CLI smoke before its native-build stage. A fresh checkout therefore needs the bootstrap above; an existing native addon can skip it.
+
 ## Development Setup
 
 ### Prerequisites
 
-- Node.js 22.19 or newer for development (required by the Pi development dependencies). Node.js 24 LTS is recommended. The published package supports Node.js 22.13 or newer.
+- Node.js `^22.19.0 || ^24.11.0 || >=26.0.0` for source development: Pi already requires >=22.19.0, while tsup 9 supports only the qualified Node branches in its engine range. Node.js 24 LTS >=24.11.0 is recommended. The published package still supports Node.js >=22.13.0.
 - Rust toolchain (for native module)
 - npm
 

README.md

@@ -240,14 +240,20 @@ Performance depends on repository size, parser coverage, provider latency, embed
 
 ## Development
 
+Source development requires Node.js `^22.19.0 || ^24.11.0 || >=26.0.0` (the already-required Pi SDK floor combined with tsup 9's qualified engine range). Prefer Node.js 24 LTS >=24.11.0; the published package still supports Node.js >=22.13.0.
+
 ```bash
 npm ci
+# Bootstrap once on a fresh checkout if the native addon is absent.
+npm run build:native
 npm run build
 npm run typecheck
 npm run lint
 npm run test:run
 ```
 
+The initial combined build's TypeScript CLI smoke requires the native addon before the normal native-build stage. Skip the bootstrap when an addon already exists.
+
 Pi integration tests use the development host `@earendil-works/pi-coding-agent`
 1.3 or newer and its `emitBeforeAgentStart(trigger, systemPromptOptions)` API.
 This test-host floor does not narrow the optional Pi peer contract or change the

SECURITY.md

@@ -54,7 +54,7 @@ Track override decisions in [#379](https://github.com/Helweg/open-codebase-index
 | `postcss@>=8.0.0 <8.5.26` | `^8.5.26` | Retain the sourceMappingURL map-file-disclosure floor from commit `5b0cf22`, including earlier PostCSS fixes |
 | `vite@>=8.0.0 <8.0.16` | `^8.0.16` | [GHSA-v6wh-96g9-6wx3](https://github.com/advisories/GHSA-v6wh-96g9-6wx3) and [GHSA-fx2h-pf6j-xcff](https://github.com/advisories/GHSA-fx2h-pf6j-xcff) |
 
-The development-only `tsup@^8.1.0` override replaces its `esbuild` edge with `^0.28.1`. Current `tsup@8.5.1` declares `^0.27.0`, whose fresh resolution is vulnerable `0.27.7`: [GHSA-g7r4-m6w7-qqqr](https://github.com/advisories/GHSA-g7r4-m6w7-qqqr), a low-severity Windows development-server file-read issue fixed in `0.28.1`. This is an intentional, scoped parent-range exception, not a claim that every declared range is satisfied. The native CLI/YAML, bundler, built CLI, full suite, and both minimum-runtime packed identities were exercised on macOS ARM64; this does not establish Windows or Linux runtime coverage. Remove the exception when tsup supports a patched esbuild range; do not restore a global pin that downgrades chord's exact `0.28.2` edge.
+The obsolete development-only `tsup@^8.1.0` esbuild override was removed after fresh two-way resolution of the same post-tsup-9 manifest produced identical non-root package records with and without it, including dependency and platform-selection metadata. `tsup@9.0.0` directly declares `esbuild:^0.28.2`; the retained lock resolves its nested copy to `0.28.2`, while the root copy remains the patched `0.28.1`. The security floor for [GHSA-g7r4-m6w7-qqqr](https://github.com/advisories/GHSA-g7r4-m6w7-qqqr), a low-severity Windows development-server file-read issue, remains `0.28.1`. The historical chord exact-`0.28.2` edge is absent after the Pi 1.3 dependency cleanup; do not restore a global override that can downgrade unrelated or future parent edges. Local macOS ARM64 checks do not establish every optional-platform behavior.
 
 ### Removed Overrides and Resolved Pi Exception
 

package.json

@@ -126,10 +126,7 @@
     "hono@>=4.0.0 <4.13.7": "^4.13.7",
     "ip-address@>=10.0.0 <10.7.1": "^10.7.1",
     "postcss@>=8.0.0 <8.5.26": "^8.5.26",
-    "vite@>=8.0.0 <8.0.16": "^8.0.16",
-    "tsup@^8.1.0": {
-      "esbuild": "^0.28.1"
-    }
+    "vite@>=8.0.0 <8.0.16": "^8.0.16"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",