pentesting 0.90.6 → 0.90.8

package/README.md

@@ -1,229 +1,311 @@
-# pentesting
+# Pentesting 🔓
 
-`pentesting` is the public npm facade for the Builder runtime.
-
-- Installs the `pentesting` CLI.
-- Downloads the matching Builder binary from `agnusdei1207/builder-public` releases for the current OS/CPU.
-- Performs only binary resolution and direct argument forwarding before delegating execution to the Rust Builder binary.
-- Launches the same runtime with a `pentesting` banner while keeping Builder as the single internal engine.
-- Does not ship a second JavaScript or TypeScript runtime.
+> **Pentesting** is a local-first, zero-panic Rust coding agent CLI for authorized security assessments. The runtime—not the model—owns routing, tool sandboxing, verification, and completion adjudication.
 
 <div align="center">
+  <img src="pentesting-logo.svg" alt="pentesting logo" width="120" />
+  <h1>pentesting</h1>
+  <p>Security-Focused Agent Runtime</p>
 
-<div style="background-color: #050a09; border: 1px solid rgba(0, 200, 160, 0.2); border-radius: 12px; max-width: 560px; font-family: 'JetBrains Mono', monospace; overflow: hidden; box-shadow: 0 20px 40px rgba(0,0,0,0.65); margin: 24px auto; text-align: left;">
-
-  <!-- Title bar -->
-  <div style="background-color: #0d1c18; border-bottom: 1px solid rgba(0, 200, 160, 0.1); padding: 10px 16px; display: flex; align-items: center; justify-content: space-between;">
-    <div style="display: flex; gap: 6px;">
-      <span style="width: 10px; height: 10px; border-radius: 50%; background-color: #ff5f56; display: inline-block;"></span>
-      <span style="width: 10px; height: 10px; border-radius: 50%; background-color: #ffbd2e; display: inline-block;"></span>
-      <span style="width: 10px; height: 10px; border-radius: 50%; background-color: #27c93f; display: inline-block;"></span>
-    </div>
-    <span style="font-size: 11px; color: #537a6c;">pentesting-tui · wsl</span>
-  </div>
-
-  <!-- Card header -->
-  <div style="background-color: rgba(0, 200, 160, 0.05); border-bottom: 1px solid rgba(0, 200, 160, 0.1); padding: 6px 16px; color: #00c8a0; font-size: 12px; font-weight: bold;">pentesting latest</div>
-
-  <!-- Card body -->
-  <table style="width: 100%; border-collapse: collapse; border: none; background: transparent; margin: 0;">
-    <tr style="border: none; background: transparent;">
-      <!-- Left Side: Status & Logo -->
-      <td style="width: 45%; padding: 20px; text-align: center; border-right: 1px solid rgba(0, 200, 160, 0.1); vertical-align: top; border-left: none; border-top: none; border-bottom: none; background: transparent;">
-        <div style="color: #e8fff8; font-weight: 700; font-size: 13px; margin-bottom: 16px;">Welcome back!</div>
-        <div style="margin: 0 auto; width: 64px; height: 58px; display: block; filter: drop-shadow(0 0 8px rgba(0, 200, 160, 0.35));">
-          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 90" width="100%" height="100%">
-            <defs>
-              <mask id="headMask">
-                <rect x="0" y="0" width="100" height="100" fill="#ffffff" />
-                <rect x="33.25" y="59.5" width="5.5" height="5" fill="#000000" />
-                <rect x="61.25" y="59.5" width="5.5" height="5" fill="#000000" />
-              </mask>
-            </defs>
-            <rect x="15" y="10" width="70" height="52" rx="10" fill="none" stroke="#00c8a0" stroke-width="4.5" mask="url(#headMask)" />
-            <line x1="36" y1="59.75" x2="36" y2="78" stroke="#00c8a0" stroke-width="5.5" stroke-linecap="butt" />
-            <line x1="64" y1="59.75" x2="64" y2="78" stroke="#00c8a0" stroke-width="5.5" stroke-linecap="butt" />
-            <circle cx="36" cy="36" r="9.5" fill="none" stroke="#00c8a0" stroke-width="3" />
-            <circle cx="38.5" cy="33.5" r="2.8" fill="#00c8a0" />
-            <circle cx="64" cy="36" r="9.5" fill="none" stroke="#00c8a0" stroke-width="3" />
-            <circle cx="66.5" cy="33.5" r="2.8" fill="#00c8a0" />
-          </svg>
-        </div>
-        <div style="color: #a0cfbf; font-size: 11px; margin-top: 16px; font-weight: 600;">your-model · your-provider</div>
-        <div style="color: #537a6c; font-size: 10px; margin-top: 4px; word-break: break-all;">...orkspace/builder-private</div>
-      </td>
-      <!-- Right Side: Quick Commands -->
-      <td style="padding: 20px; vertical-align: top; text-align: left; border-left: none; border-top: none; border-bottom: none; border-right: none; background: transparent;">
-        <div style="color: #e8fff8; font-weight: 700; font-size: 13px; margin-bottom: 12px;">Quick commands</div>
-        <table style="width: 100%; border-collapse: collapse; font-size: 11px; text-align: left; border: none; background: transparent; margin: 0;">
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/new</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">New conversation</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/model</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Switch model</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/goal &lt;task&gt;</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Set active goal</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/goal</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Clear goal</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/auto</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Toggle goal auto</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/config</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Edit configuration</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/help</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Show all commands</td></tr>
-          <tr style="border: none; background: transparent;"><td style="color: #00c8a0; font-weight: 700; padding: 3px 12px 3px 0; white-space: nowrap; border: none; background: transparent;">/exit</td><td style="color: #a0cfbf; padding: 3px 0; border: none; background: transparent;">Quit</td></tr>
-        </table>
-      </td>
-    </tr>
-  </table>
-
-  <!-- Bottom prompt bar -->
-  <div style="border-top: 1px solid rgba(0, 200, 160, 0.1); padding: 12px 16px; font-size: 11px;">
-    <div style="color: #a0cfbf; display: flex; align-items: center; gap: 8px;">
-      <span style="color: #00c8a0;">⠸</span> Processing · analyzing workspace structure
-    </div>
-    <div style="height: 1px; background-color: rgba(0, 200, 160, 0.08); margin: 8px 0;"></div>
-    <div style="font-size: 12px; color: #e8fff8;">
-      <span style="color: #00c8a0; font-weight: bold;">❯ </span>pentesting<span style="background-color: #00c8a0; color: #020504; display: inline-block; width: 8px; height: 15px; vertical-align: middle; margin-left: 2px;"></span>
-    </div>
-    <div style="height: 1px; background-color: rgba(0, 200, 160, 0.08); margin: 8px 0;"></div>
-    <div style="color: #537a6c; font-size: 10px;">Esc to interrupt</div>
-  </div>
-
+  [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+  [![npm](https://img.shields.io/npm/v/pentesting.svg)](https://www.npmjs.com/package/pentesting)
 </div>
 
-</div>
+---
+
+> **Role:** The published npm package and the command you run are both **`pentesting`**. The internal orchestration engine is **`builder`** — `pentesting` downloads and runs it under the hood. `npm i -g pentesting` installs the **`pentesting`** command (never a `builder` command); the engine name does not surface in normal use.
 
 ---
 
-## Install
+## 🎯 Key Design Pillars
+
+* **Runtime-Owned Adjudication** — Model output is a *candidate* until a 5-gate completion lattice verifies and closes the task.
+* **Local-First State** — Runtime state and a markdown knowledge graph live on disk. No external storage service.
+* **Weak-Model Hardening** — Rust-enforced classifiers, validators, and self-reviews guard against hallucination.
+* **Lineage & Horizons** — Run lineage, objective IDs, and horizon-aware memory reuse, all in local state.
+* **Policy-Gated Tools** — `Allow/Deny/Confirm` gates shell, file, and network access (policy-based today; OS sandboxing is roadmap).
+* **Intelligent Queuing** — Queued inputs are deduplicated and prioritized live; obsolete tasks are preempted, not FIFO-replayed.
+* **Lab Session Multiplexing** — `shell-listener` runs multiple authorized TCP sessions with per-session routing and PTY upgrades.
+* **Dynamic Agent Profiles** — No fixed persona: the classifier *generates* a profile per request, *recalls* reusable templates, *reuses* them to drive tool scope, phase, and memory weighting.
+* **Ebbinghaus-Inspired Memory** — Memories carry a *strength* that fades like human memory and reinforces on recall. Faded notes are de-referenced, never destroyed.
+* **Git-Backed Rewind** — Working-tree checkpoint/restore keeps autonomous edits reversible.
+
+---
+
+## 🚀 Quick Start
+
+### Install via npm
 
 ```bash
 npm install -g pentesting
 pentesting
-pentesting --version
 ```
 
-## Quick commands
+### Run with Docker
 
 ```bash
-pentesting
-pentesting --prompt "Enumerate the target web application and summarize the next actions."
-pentesting shell-listener --bind 127.0.0.1 --port 4444
+docker run -it --rm \
+  -v "$(pwd):/workspace" \
+  -w /workspace \
+  agnusdei1207/pentesting:latest
+```
+
+### Docker Compose
+
+```bash
+PENTESTING_PROJECT_DIR=/path/to/project docker compose run pentesting
+```
+
+### Quick commands
+
+```bash
+pentesting                                                # Interactive TUI
+pentesting --prompt "Enumerate the target and summarize next actions."
+pentesting shell-listener --bind 127.0.0.1 --port 4444   # Authorized lab listener
 pentesting --version
 ```
 
-Inside the interactive TUI:
+---
 
-```text
-/goal harden the npm release flow and verify Docker startup
-/auto
+## 🧩 Orchestration Map
+
+Pentesting is a **domain-neutral** runtime with a security focus. Development, pentesting, CTF, audit, and release work layer in via skills — never baked into the core.
+
+**Profile flow** — generate → recall → reuse:
+
+```mermaid
+flowchart LR
+    R[Request] --> GEN["Generate<br/>dynamic profile"]
+    GEN --> REC["Recall<br/>named template + overlay"]
+    REC --> USE["Reuse<br/>tool scope · phase · memory weight"]
 ```
 
-- `/goal <objective>` sets the active goal only.
-- `/goal` with no text clears the goal and disables auto mode.
-- `/auto` toggles auto mode for the current goal.
-- `/auto` requires an existing goal and will not infer one from the transcript.
-- `/auto <text>` is rejected with usage guidance; use `/goal <objective>` first, then `/auto`.
+**Agent flow** — request to closure:
+
+```mermaid
+flowchart TD
+    U[User request] --> C[Intent classifier]
+    C --> P[Dynamic profile<br/>task shape + tool scope + rigor]
+    P --> R[Runtime router]
+    R --> A[Active agent]
+    A --> T{Need delegation?}
+    T -- no --> O[Tool execution]
+    T -- yes --> D[Agent tool]
+    D --> CO[coordinator]
+    D --> I[investigator]
+    D --> OP[operator]
+    D --> RV[reviewer]
+    D --> V[verifier]
+    D --> W[report-writer]
+    CO --> O
+    I --> O
+    OP --> O
+    RV --> O
+    V --> O
+    W --> O
+    O --> G[Completion gates]
+    G --> M[Memory + artifacts]
+    M --> U
+```
 
-## What npm installs
+### Built-in agent team
 
-`npm install -g pentesting` installs a thin wrapper package and then runs `postinstall`:
+| Agent | Default role | Runtime profile |
+| --- | --- | --- |
+| `builder` | Hands-on implementation, refactoring, local file changes, tests | Implement + broad local write |
+| `planner` | Implementation plans and risk breakdowns | Plan + read-only |
+| `researcher` | Read-only codebase and reference research | Investigate + read-only |
+| `coordinator` | Splits broad work into owned packets and consolidates results | Coordinate + broad local write |
+| `investigator` | Evidence gathering across code, logs, commands, APIs, and behavior | Investigate + shell diagnostics |
+| `operator` | Builds, tests, packaging, service startup, and runtime workflows | Implement + broad local write |
+| `reviewer` | Findings-first technical review | Review + strict read-only |
+| `verifier` | Reproduction, build/test proof, and completion claim checks | Verify + strict read-only |
+| `report-writer` | Reports, handoffs, release notes, and reproducibility records | Implement + bounded write |
 
-- if `BUILDER_BIN` is already set, the wrapper reuses that Builder executable
-- if `BUILDER_SKIP_DOWNLOAD=true`, the wrapper skips managed download entirely
-- otherwise it downloads the matching public Builder release asset into the package-local managed binary directory and executes that binary on launch
+### Named autonomy profiles
 
-This means the outside package name is `pentesting`, but the actual runtime engine is Builder.
+Optionally pin the top-level profile (`autonomy_profile = "ctf-competition"`); leave unset for classifier-driven defaults. Delegated subagent contracts stay intact.
 
-## Thin-wrapper design
+| Profile | Purpose |
+| --- | --- |
+| `general-agent` | Broad autonomous local orchestration for mixed tasks |
+| `local-builder` | Hands-on implementation with fresh evidence retrieval |
+| `ctf-competition` | Competition/lab workflow backed by `ctf-competition` and `pentesting-methodology` skills |
+| `enterprise-review` | Strict, review-heavy profile with read-only dynamic scope |
 
-The npm package is intentionally narrow and does not keep legacy command translators.
+### Engagement metadata
 
-- it installs a launcher, not a second agent runtime
-- it resolves or downloads the correct Builder release asset
-- it forwards arguments directly into the Rust Builder binary
-- it does not translate `interactive`, `run`, `scan`, old target flags, or permission-bypass flags
+Runs can attach typed engagement context — scope, phase, tags, and standard refs (PTES, MITRE ATT&CK, OWASP, CWE/CAPEC, NIST CSF, CIS Controls) — to workflow metadata. `/workflow report` exports it as a Markdown handoff.
 
-If a change would add orchestration, memory, monitoring, or prompt-management logic directly into the npm layer, that change belongs upstream in Builder instead.
+### Storage and graph strategy
 
-## Runtime strengths exposed through pentesting
+- **Local-first** — runtime state, notes, scratchpad, and graph inputs live on disk.
+- **Derived graph** — built from markdown notes, wiki-links/backlinks, skills, and memory; a view, not a second source of truth.
+- **Separate skills** — domain skills (`ctf-competition`, audit, release, dev) teach method without changing runtime identity.
 
-Because `pentesting` delegates to the Rust Builder runtime, it inherits the same core capabilities:
+---
 
-- goal-aware TUI sessions through `/goal`
-- explicit auto-mode toggling through `/auto`
-- post-turn self-review and persistent local memory files
-- context compression for long-running sessions
-- workflow status, budget, proof, and verification signals in the TUI
-- Docker and npm entrypoints that share one runtime instead of diverging implementations
-- the explicit `shell-listener` command for authorized lab multi-session TCP handling with per-session routing, output buffering, and PTY-upgrade helpers
+## 🧠 Memory & Knowledge
 
-## Docker and compose alternative
+One local-first store — plain markdown notes on disk, no vector DB, no cloud. Memories carry a *strength* that fades like human memory, so the store stays sharp instead of rotting.
 
-If you do not want a managed local binary, use Builder directly through Docker:
+**Storage** — Ebbinghaus lifecycle (decay · reinforce · floor, never deleted):
 
-```bash
-docker run -it --rm \
-  -v "$(pwd):/workspace" \
-  -w /workspace \
-  agnusdei1207/builder:latest
+```mermaid
+flowchart TD
+    N[New memory] --> S["strength = quality × recall × e^-λ·age"]
+    S --> U{recalled?}
+    U -- yes --> RE[reinforce ↑ · reset age]
+    U -- no --> D[decay over time]
+    RE --> S
+    D --> F{below floor?}
+    F -- no --> S
+    F -- yes --> AR[de-reference: archive / tombstone]
+    AR -. recoverable on disk .-> N
 ```
 
-For the Docker Compose facade, use the public `compose.yaml` from the public repo or mirrored docs:
+Kinds fade at different speeds (procedural outlives episodic); bi-temporal `event_time` vs `ingestion_time` lets newer facts supersede stale ones.
+
+**Retrieval** — hybrid fuse, strength-weighted, read-only:
+
+```mermaid
+flowchart LR
+    Q[Query] --> L[Lexical]
+    Q --> SE[Semantic]
+    Q --> G[Graph]
+    L --> RRF[RRF fuse]
+    SE --> RRF
+    G --> RRF
+    RRF --> RR[rerank: phase · recency · task]
+    RR --> W[weight by strength]
+    W --> P[Prompt context]
+```
 
-```bash
-PENTESTING_PROJECT_DIR=/path/to/project docker compose run pentesting
+Faded, private, or unsafe memories are held back from the prompt. Lookups never write — reinforce/archive/supersede are explicit, never search side effects.
+
+---
+
+## 🧭 Interactive Essentials
+
+Inside an interactive pentesting session, these commands are the fastest way to inspect state:
+
+```text
+/status        Show the current run phase, active tasks, gates, hooks, and budget signals
+/workflow      Show the current focus and recent workflow steps for the active conversation
+/workflow report
+               Export the active run, engagement metadata, evidence, and large outputs to Markdown
+/context       Show recent context-budget snapshots for the current conversation
+/memory        Show stored conversation memories for the current conversation
+/tools         List the currently available tools and schemas
+/agent         Switch the active agent
+/conversation  Browse conversations for the active workspace
+/goal <task>   Set the active goal
+/auto          Toggle autonomous mode for the current goal
+/help          Show all commands
+/exit          Quit
 ```
 
-## Supported runtime targets
+`/update` downloads and applies the latest public release asset for the current OS/CPU target.
 
-| OS | CPU | Release asset |
-| --- | --- | --- |
-| Linux | x64 | `builder-x86_64-unknown-linux-musl` |
-| Linux | arm64 | `builder-aarch64-unknown-linux-musl` |
-| macOS | x64 | `builder-x86_64-apple-darwin` |
-| macOS | arm64 | `builder-aarch64-apple-darwin` |
-| Windows | x64 | `builder-x86_64-pc-windows-msvc.exe` |
-| Windows | arm64 | `builder-aarch64-pc-windows-msvc.exe` |
-| Android | arm64 | `builder-aarch64-linux-android` |
+---
 
-## Environment variables
+## ⚙️ Configuration (`.pentesting.toml`)
 
-| Variable | Description |
-| --- | --- |
-| `BUILDER_BIN` | Use an already-installed Builder binary instead of the managed download. |
-| `BUILDER_PRODUCT_NAME` | Runtime banner label. The `pentesting` launcher sets this to `pentesting` automatically. |
-| `BUILDER_REPO` | Override the public release repo used for binary downloads. Defaults to `agnusdei1207/builder-public`. |
-| `BUILDER_SKIP_DOWNLOAD` | Skip the postinstall binary download. Useful in CI or when `BUILDER_BIN` will be provided later. |
+Pentesting reads a user-global config from `~/.pentesting/.pentesting.toml`, overridden by project-local `.pentesting.toml` files discovered by walking up from the working directory.
+
+```toml
+[storage]
+backend = "local"                            # Local md/fs runtime state
+```
+
+Environment variables use the `PENTESTING_` prefix, with `__` for nested keys — e.g. `PENTESTING_SESSION__MODEL_ID=...`. Set `PENTESTING_CONFIG` to override the global config directory.
+
+### Backward compatibility — `builder` ↔ `pentesting`
+
+The runtime engine is still `builder` under the hood, so legacy names keep working. Use whichever you like; the `PENTESTING_*` form wins when both are set.
+
+| Surface | Canonical | Legacy (still accepted) |
+| :--- | :--- | :--- |
+| Env vars | `PENTESTING_*` | `BUILDER_*` |
+| Config-dir override | `PENTESTING_CONFIG` | `BUILDER_CONFIG` |
+| Global config file | `~/.pentesting/.pentesting.toml` | `~/.builder/.builder.toml`, `~/builder/.builder.toml` |
+| Project config file | `.pentesting.toml` | `.builder.toml` |
+
+---
 
-## Command behavior
+## 🔐 Pentesting-Specific Notes
 
-- `pentesting` with no extra arguments starts the Builder interactive/default flow.
-- `pentesting --prompt "<objective>"` runs a direct Builder prompt.
-- `pentesting shell-listener --bind 127.0.0.1 --port 4444` starts the explicit listener command.
-- Arguments are passed through exactly; removed legacy commands are not translated.
+### Architecture — single source, two surfaces
 
-## Runtime behavior notes
+Pentesting and Builder share the **same Rust runtime binary**. The `pentesting` npm package is a thin distribution facade:
 
-- Docker and npm both end up delegating to the same upstream Builder runtime, so differences are usually install/configuration problems rather than different products.
+```text
+npm install -g pentesting
+         │
+         ▼
+  pentesting CLI (Node.js shim)
+         │  resolves or downloads the matching Builder release asset
+         ▼
+  Builder binary (Rust)  ← single runtime engine
+         │  PENTESTING_PRODUCT_NAME=pentesting
+         ▼
+  Interactive TUI with "pentesting" banner
+```
 
-## Runtime cautions
+- The npm package installs a launcher, **not** a second agent runtime.
+- It resolves or downloads the correct release asset from `agnusdei1207/pentesting-public`.
+- It forwards arguments directly into the Rust binary — no command translation or compatibility shims.
+- If a change would add orchestration, memory, or prompt logic into the npm layer, that change belongs upstream in the Rust runtime.
 
-- `BUILDER_SKIP_DOWNLOAD=true` is only safe when you intentionally plan to provide `BUILDER_BIN` later or reinstall after provisioning access to the Builder release asset.
-- The npm package does not publish Docker images itself. Docker users should treat `agnusdei1207/builder:latest` as the runtime image and `pentesting` as the public command/package facade.
-- Unsupported OS/CPU pairs fail during release asset resolution before download.
-- If the managed binary is missing at runtime, reinstall the package or set `BUILDER_BIN` explicitly.
+### Security domain skills
 
-## Development and release from source
+The `ctf-competition` and `pentesting-methodology` skills map authorized assessments to standard frameworks:
 
-If you maintain this npm facade from the private source repository, use the root `builder-private` commands rather than adding more logic inside this package:
+- **PTES** (Penetration Testing Execution Standard)
+- **MITRE ATT&CK** tactics and techniques
+- **OWASP** Top 10 and Testing Guide
+- **CWE/CAPEC** weakness and attack pattern catalogs
+- **NIST CSF** and **CIS Controls**
+
+### Shell listener for authorized labs
 
 ```bash
-npm run pentesting:status
-npm run pentesting:verify
-npm run pentesting:pack:dry-run
-npm run pentesting:release:patch:dry-run
-NPM_TOKEN=... npm run pentesting:publish -- 0.90.1
+pentesting shell-listener --bind 127.0.0.1 --port 4444
 ```
 
-## Further reading
+Manages multiple accepted TCP sessions with per-session routing, buffered output, raw byte logging, and PTY-upgrade helpers. Bound to loopback by default; `--allow-remote` is an explicit opt-in gate.
+
+---
+
+## 📦 Supported Runtime Targets
+
+| OS | CPU | Release asset |
+| --- | --- | --- |
+| Linux | x64 | `pentesting-x86_64-unknown-linux-musl` |
+| Linux | arm64 | `pentesting-aarch64-unknown-linux-musl` |
+| macOS | x64 | `pentesting-x86_64-apple-darwin` |
+| macOS | arm64 | `pentesting-aarch64-apple-darwin` |
+| Windows | x64 | `pentesting-x86_64-pc-windows-msvc.exe` |
+| Windows | arm64 | `pentesting-aarch64-pc-windows-msvc.exe` |
+| Android | arm64 | `pentesting-aarch64-linux-android` |
+
+---
+
+## 🌍 Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `PENTESTING_BIN` | Use an already-installed Builder binary instead of the managed download. |
+| `PENTESTING_PRODUCT_NAME` | Runtime banner label. The `pentesting` launcher sets this to `pentesting` automatically. |
+| `PENTESTING_REPO` | Override the public release repo used for binary downloads. Defaults to `agnusdei1207/pentesting-public`. |
+| `PENTESTING_SKIP_DOWNLOAD` | Skip the postinstall binary download. Useful in CI or when `PENTESTING_BIN` will be provided later. |
+
+---
+
+## 📖 Key Documentation
 
-- public Builder runtime docs and Docker guidance at `https://agnusdei1207.github.io/builder-public/`
-- the mirrored public `compose.yaml` facade for Docker sessions
-- the Builder release asset matching your OS/CPU target
+* [`Public site`](https://agnusdei1207.github.io/pentesting-public/) — Landing page and public runtime entry surface.
+* [`compose.yaml`](https://github.com/agnusdei1207/pentesting-public) — Docker Compose facade for pentesting sessions.
 
 ---
 

package/bin/pentesting.mjs

@@ -22,7 +22,7 @@ async function main() {
 
   if (result.error) {
     console.error(
-      `pentesting could not start Builder (${result.error.message}). Set BUILDER_BIN or reinstall the pentesting package.`,
+      `pentesting could not start Builder (${result.error.message}). Set PENTESTING_BIN or reinstall the pentesting package.`,
     );
     process.exit(127);
   }

package/lib/runtime.mjs

@@ -61,7 +61,7 @@ export function configuredBuilderReleaseTag() {
 }
 
 export function releaseRepository() {
-  return process.env.BUILDER_REPO || "agnusdei1207/builder-public";
+  return process.env.PENTESTING_REPO || "agnusdei1207/pentesting-public";
 }
 
 export function defaultReleaseTag(version = undefined) {
@@ -117,8 +117,8 @@ async function manifestMatches(expected) {
 }
 
 export async function installManagedBuilder(options = {}) {
-  if (process.env.BUILDER_BIN) {
-    return { binaryPath: process.env.BUILDER_BIN, source: "external" };
+  if (process.env.PENTESTING_BIN) {
+    return { binaryPath: process.env.PENTESTING_BIN, source: "external" };
   }
 
   const target = resolveReleaseAsset();
@@ -131,7 +131,7 @@ export async function installManagedBuilder(options = {}) {
     return { binaryPath, source: "cached", ...manifest };
   }
 
-  if (process.env.BUILDER_SKIP_DOWNLOAD === "true") {
+  if (process.env.PENTESTING_SKIP_DOWNLOAD === "true") {
     return { binaryPath, source: "skipped", ...manifest };
   }
 
@@ -174,8 +174,8 @@ export async function installManagedBuilder(options = {}) {
 }
 
 export async function resolveBuilderBinary(options = {}) {
-  if (process.env.BUILDER_BIN) {
-    return process.env.BUILDER_BIN;
+  if (process.env.PENTESTING_BIN) {
+    return process.env.PENTESTING_BIN;
   }
 
   const target = resolveReleaseAsset();
@@ -188,14 +188,14 @@ export async function resolveBuilderBinary(options = {}) {
     const install = await installManagedBuilder();
     if (install.source === "skipped") {
       throw new Error(
-        "Managed Builder download was skipped and no BUILDER_BIN override was provided.",
+        "Managed Builder download was skipped and no PENTESTING_BIN override was provided.",
       );
     }
     return install.binaryPath;
   }
 
   throw new Error(
-    "No managed Builder binary is available. Reinstall the pentesting package or set BUILDER_BIN.",
+    "No managed Builder binary is available. Reinstall the pentesting package or set PENTESTING_BIN.",
   );
 }
 
@@ -206,6 +206,6 @@ export function translateBuilderInvocation(argv) {
 export function pentestingEnvironment(baseEnv = process.env) {
   return {
     ...baseEnv,
-    BUILDER_PRODUCT_NAME: "pentesting",
+    PENTESTING_PRODUCT_NAME: "pentesting",
   };
 }

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "pentesting",
-  "version": "0.90.6",
+  "version": "0.90.8",
   "builderReleaseTag": "v0.1.4",
-  "description": "Public pentesting facade for Builder",
+  "description": "pentesting — security-focused agent runtime (internal engine: builder). Thin npm facade that downloads the managed Builder binary and forwards arguments.",
+  "license": "MIT",
+  "author": "agnusdei1207",
   "type": "module",
   "bin": {
     "pentesting": "bin/pentesting.mjs"
@@ -10,29 +12,19 @@
   "files": [
     "bin",
     "lib",
-    "scripts",
+    "scripts/postinstall.mjs",
     "README.md"
   ],
-  "scripts": {
-    "postinstall": "node ./scripts/postinstall.mjs",
-    "dev": "node ./bin/pentesting.mjs",
-    "preflight:local": "bash scripts/preflight-local.sh",
-    "test": "node --test tests/*.test.mjs",
-    "verify": "npm run preflight:local && npm run test",
-    "check": "npm run verify",
-    "prepublishOnly": "npm run verify",
-    "publish:token": "npm publish --access public",
-    "release:patch": "npm version patch && npm run verify && npm run publish:token",
-    "release:minor": "npm version minor && npm run verify && npm run publish:token",
-    "release:major": "npm version major && npm run verify && npm run publish:token"
+  "engines": {
+    "node": ">=18.18.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/agnusdei1207/builder-public.git"
+    "url": "git+https://github.com/agnusdei1207/pentesting-public.git"
   },
-  "homepage": "https://agnusdei1207.github.io/builder-public/",
+  "homepage": "https://agnusdei1207.github.io/pentesting-public/",
   "bugs": {
-    "url": "https://github.com/agnusdei1207/builder-public/issues"
+    "url": "https://github.com/agnusdei1207/pentesting-public/issues"
   },
   "keywords": [
     "penetration-testing",
@@ -51,9 +43,75 @@
     "sqlmap",
     "kali"
   ],
-  "author": "agnusdei1207",
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.18.0"
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.mjs",
+    "prepublishOnly": "npm run verify",
+    "test": "node --test tests/*.test.mjs",
+    "preflight:local": "bash scripts/preflight-local.sh",
+    "verify": "npm run preflight:local && npm run test",
+    "build": "CARGO_TARGET_DIR=${CARGO_TARGET_DIR:-$HOME/.cache/builder-target} $HOME/.cargo/bin/cargo build --bin pentesting",
+    "check": "sh -c 'npm run docker:builder:build && docker run -it --rm -v builder-workspace:/workspace -e ANTHROPIC_BASE_URL -e ANTHROPIC_AUTH_TOKEN -e ANTHROPIC_MODEL -e ANTHROPIC_API_KEY -e MINIMAX_API_KEY -e OPENAI_API_KEY -e OPENAI_BASE_URL -e GEMINI_API_KEY -e DEEPSEEK_API_KEY agnusdei1207/pentesting:latest'",
+    "check:interactive": "npm run check",
+    "check:smoke": "sh -c 'npm run docker:builder:build && docker run --rm -v builder-workspace:/workspace agnusdei1207/pentesting:latest --version'",
+    "check:clean": "npm run docker:clean && npm run check",
+    "eval": "tsx benchmarks/cli.ts",
+    "eval:all": "npm run build && find benchmarks/evals -name task.yml -exec dirname {} \\; | sort | while read -r d; do echo \"\\n=== Running $(basename $d) ===\"; tsx benchmarks/cli.ts \"$d\" || true; done",
+    "pentesting:help": "./scripts/pentesting-release-help.sh",
+    "pentesting:status": "./scripts/pentesting-release-status.sh",
+    "pentesting:test": "npm run test",
+    "pentesting:verify": "npm run verify",
+    "pentesting:pack:dry-run": "npm pack --dry-run",
+    "pentesting:check": "./scripts/check-pentesting-package.sh",
+    "pentesting:publish": "./scripts/publish-pentesting-package.sh",
+    "pentesting:publish:dry-run": "DRY_RUN=true ./scripts/publish-pentesting-package.sh",
+    "pentesting:release": "npm run pentesting:release:patch",
+    "pentesting:release:dry-run": "npm run pentesting:release:patch:dry-run",
+    "pentesting:release:patch": "npm run pentesting:check && AUTO_PUSH=true ./scripts/publish-pentesting-package.sh patch",
+    "pentesting:release:patch:dry-run": "npm run pentesting:check && DRY_RUN=true ./scripts/publish-pentesting-package.sh patch",
+    "pentesting:release:minor": "npm run pentesting:check && AUTO_PUSH=true ./scripts/publish-pentesting-package.sh minor",
+    "pentesting:release:minor:dry-run": "npm run pentesting:check && DRY_RUN=true ./scripts/publish-pentesting-package.sh minor",
+    "pentesting:release:major": "npm run pentesting:check && AUTO_PUSH=true ./scripts/publish-pentesting-package.sh major",
+    "pentesting:release:major:dry-run": "npm run pentesting:check && DRY_RUN=true ./scripts/publish-pentesting-package.sh major",
+    "public:sync": "./scripts/sync-public-repo.sh",
+    "public:sync:push": "AUTO_PUSH=true ./scripts/sync-public-repo.sh",
+    "public:pull": "git submodule update --remote --merge public",
+    "public:publish": "AUTO_PUSH=true ./scripts/sync-public-repo.sh && git add public && git commit -m 'chore: bump public facade pointer' && git push origin main",
+    "public:mirror-release": "./scripts/mirror-public-release.sh",
+    "public:ci:sync": "gh workflow run 'Sync Builder Repo' --ref main",
+    "public:ci:mirror": "gh workflow run 'Mirror Builder Release' --ref main -f version_tag=$(git describe --tags --abbrev=0)",
+    "public:ci:status": "gh run list --workflow=sync-public.yml --limit=3 && echo '---' && gh run list --workflow=mirror-release.yml --limit=3",
+    "docker:builder:build": "(docker image inspect agnusdei1207/pentesting-build-base:1.95 >/dev/null 2>&1 && docker image inspect agnusdei1207/pentesting-runtime-base:26.04 >/dev/null 2>&1 || npm run docker:base:build) && docker build --build-arg APP_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo dev) -t agnusdei1207/pentesting:latest .",
+    "docker:builder:push": "if [ -n \"$DOCKER_PASSWORD\" ]; then echo \"$DOCKER_PASSWORD\" | docker login -u \"${DOCKER_USERNAME:-agnusdei1207}\" --password-stdin; fi && npm run docker:builder:build && docker push agnusdei1207/pentesting:latest",
+    "docker:builder:tag": "docker tag agnusdei1207/pentesting:latest agnusdei1207/pentesting:$(git describe --tags --abbrev=0) && docker push agnusdei1207/pentesting:$(git describe --tags --abbrev=0)",
+    "docker:base:build": "docker build -t agnusdei1207/pentesting-build-base:1.95 -f docker/build-base.Dockerfile . && docker build -t agnusdei1207/pentesting-runtime-base:26.04 -f docker/runtime-base.Dockerfile .",
+    "docker:base:push": "if [ -n \"$DOCKER_PASSWORD\" ]; then echo \"$DOCKER_PASSWORD\" | docker login -u \"${DOCKER_USERNAME:-agnusdei1207}\" --password-stdin; fi && npm run docker:base:build && docker push agnusdei1207/pentesting-build-base:1.95 && docker push agnusdei1207/pentesting-runtime-base:26.04",
+    "docker:clean": "docker stop $(docker ps -q) 2>/dev/null || true && docker system prune -af",
+    "release": "./scripts/release-all.sh patch",
+    "release:dry": "DRY_RUN=true ./scripts/release-all.sh patch",
+    "release:local": "./scripts/run-release-in-docker.sh ./scripts/build-release-local.sh",
+    "release:local:dry": "DRY_RUN=true ./scripts/run-release-in-docker.sh ./scripts/build-release-local.sh",
+    "release:local:host": "./scripts/build-release-local.sh",
+    "release:local:host:dry": "DRY_RUN=true ./scripts/build-release-local.sh",
+    "release:backfill": "./scripts/run-release-in-docker.sh ./scripts/backfill-release-local.sh",
+    "release:backfill:dry": "DRY_RUN=true ./scripts/run-release-in-docker.sh ./scripts/backfill-release-local.sh",
+    "release:backfill:host": "./scripts/backfill-release-local.sh",
+    "release:backfill:host:dry": "DRY_RUN=true ./scripts/backfill-release-local.sh"
+  },
+  "devDependencies": {
+    "@ai-sdk/google-vertex": "^4.0.47",
+    "@types/node": "^24.10.1",
+    "@types/tmp": "^0.2.6",
+    "ai": "^6.0.77",
+    "csv-parse": "^6.1.0",
+    "handlebars": "^4.7.9",
+    "p-limit": "^7.2.0",
+    "pino": "^10.1.0",
+    "pino-pretty": "^13.1.2",
+    "strip-ansi": "^7.1.2",
+    "tmp": "^0.2.5",
+    "tsx": "^4.20.6",
+    "yaml": "^2.8.3",
+    "yargs": "^18.0.0",
+    "zod": "^3.24.1"
   }
 }

package/scripts/postinstall.mjs

@@ -1,30 +1,33 @@
 import { installManagedBuilder } from "../lib/runtime.mjs";
 
-if (process.env.BUILDER_BIN) {
-  console.log("[pentesting] BUILDER_BIN is set; skipping managed Builder download.");
+if (process.env.PENTESTING_BIN) {
+  console.log("[pentesting] PENTESTING_BIN is set; skipping managed Builder download.");
   process.exit(0);
 }
 
-if (process.env.BUILDER_SKIP_DOWNLOAD === "true") {
+if (process.env.PENTESTING_SKIP_DOWNLOAD === "true") {
   console.log("[pentesting] Skipping managed Builder download.");
   process.exit(0);
 }
 
 try {
   const result = await installManagedBuilder({
-    force: process.env.BUILDER_FORCE_DOWNLOAD === "true",
+    force: process.env.PENTESTING_FORCE_DOWNLOAD === "true",
   });
 
   if (result.source === "cached") {
-    console.log("[pentesting] Managed Builder binary already present.");
+    console.log("[pentesting] Runtime already installed.");
   } else if (result.source === "downloaded") {
-    console.log("[pentesting] Managed Builder binary downloaded successfully.");
+    console.log("[pentesting] Runtime downloaded successfully.");
   }
 } catch (error) {
-  console.error(
-    `[pentesting] Failed to provision the managed Builder binary: ${
+  // Non-fatal: never break `npm i pentesting`. The runtime is fetched on first
+  // run (resolveBuilderBinary downloads if missing), so a failed/offline
+  // postinstall just defers the download instead of failing the install.
+  console.warn(
+    `[pentesting] Runtime not pre-downloaded (${
       error instanceof Error ? error.message : String(error)
-    }`,
+    }). It will be fetched automatically on first run.`,
   );
-  process.exit(1);
+  process.exit(0);
 }

package/scripts/preflight-local.sh

@@ -1,24 +0,0 @@
-#!/bin/sh
-
-set -eu
-
-require_command() {
-  if ! command -v "$1" >/dev/null 2>&1; then
-    echo "Missing required command: $1" >&2
-    exit 1
-  fi
-}
-
-require_path() {
-  if [ ! -e "$1" ]; then
-    echo "Missing required path: $1" >&2
-    exit 1
-  fi
-}
-
-SCRIPT_DIR=$(CDPATH= cd -- "$(dirname "$0")" && pwd)
-PACKAGE_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
-
-require_command node
-require_path "$PACKAGE_ROOT/bin/pentesting.mjs"
-require_path "$PACKAGE_ROOT/lib/runtime.mjs"