[codex] fix: address follow-up promotion bugs

.github/workflows/release.yml

@@ -41,8 +41,17 @@ jobs:
           cache: npm
           registry-url: 'https://registry.npmjs.org'
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
       - run: npm ci --prefer-offline --no-audit
 
+      - name: Install Python dependencies
+        run: |
+          cd tywrap_ir
+          pip install -e .
+
       - run: npm run build
 
       - name: Run tests

docs/guide/configuration.md

@@ -328,34 +328,41 @@ Hooks are optional; implement only what your plugin needs.
 
 ## Environment Variables
 
-Override configuration with environment variables:
+Most tywrap behavior is configured in `tywrap.config.*` or when you construct a
+runtime bridge in application code. The supported `TYWRAP_*` environment
+variables are mostly codec guardrails, logging, and repo test knobs:
 
 ```bash
-# Runtime configuration
-export TYWRAP_PYTHON_PATH="/usr/local/bin/python3.11"
-export TYWRAP_VIRTUAL_ENV="./venv"
 export TYWRAP_CODEC_FALLBACK="json"
-export TYWRAP_CODEC_MAX_BYTES="10485760"  # Max response payload size (bytes)
+export TYWRAP_CODEC_MAX_BYTES="10485760"   # Max response payload size (bytes)
 export TYWRAP_REQUEST_MAX_BYTES="1048576"  # Max request payload size (bytes)
 export TYWRAP_TORCH_ALLOW_COPY="1"
+export TYWRAP_LOG_LEVEL="INFO"
+export TYWRAP_LOG_JSON="1"
+```
+
+Repo tests and benchmarks also use additional `TYWRAP_*` variables such as
+`TYWRAP_PERF_BUDGETS`.
+
+Python executable and virtual environment selection are not configured through
+environment variables today. Set them in `tywrap.config.*` or on the bridge:
 
-# Note: NodeBridge uses TYWRAP_CODEC_MAX_BYTES as the default maxLineLength when set.
-
-# Performance tuning
-export TYWRAP_CACHE_DIR="./.tywrap/cache"
-export TYWRAP_MEMORY_LIMIT="1024"
-export TYWRAP_PERF_BUDGETS="1"
-export TYWRAP_PERF_TIME_BUDGET_MS="2000"
-export TYWRAP_PERF_MEMORY_BUDGET_MB="64"
-export TYWRAP_CODEC_PERF_ITERATIONS="200"
-export TYWRAP_CODEC_PERF_TIME_BUDGET_MS="500"
-export TYWRAP_CODEC_PERF_MEMORY_BUDGET_MB="32"
-
-# Development
-export TYWRAP_VERBOSE="true"
-export TYWRAP_HOT_RELOAD="true"
+```ts
+import { defineConfig } from 'tywrap';
+
+export default defineConfig({
+  runtime: {
+    node: {
+      pythonPath: '/usr/local/bin/python3',
+      virtualEnv: './venv',
+      timeout: 30000,
+    },
+  },
+});
 ```
 
+See [Environment Variables](/reference/env-vars) for the full implemented list.
+
 ## Advanced Configuration Patterns
 
 ### Multi-Environment Setup

docs/guide/runtimes/node.md

@@ -290,19 +290,30 @@ try {
 
 ### Debugging Configuration
 
-```json
-{
-  "runtime": {
-    "node": {
-      "timeoutMs": 0, // Disable timeout for debugging
-      "env": {
-        "PYTHONUNBUFFERED": "1", // Immediate stdout/stderr
-        "TYWRAP_DEBUG": "1" // Enable debug logging
-      }
-    }
+Use the CLI's debug flag when you are troubleshooting wrapper generation:
+
+```bash
+npx tywrap generate --debug
+```
+
+Use runtime log env vars for subprocess diagnostics:
+
+```bash
+export TYWRAP_LOG_LEVEL=DEBUG
+export TYWRAP_LOG_JSON=1
+```
+
+If you need to disable timeouts or pass extra Python env vars while debugging,
+do it on the bridge instance:
+
+```typescript
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  timeoutMs: 0,
+  env: {
+    PYTHONUNBUFFERED: '1',
   },
-  "debug": true
-}
+});
 ```
 
 ### Common Error Scenarios
@@ -359,17 +370,16 @@ const [sin1, sin2, sin3] = await Promise.all([
 
 ### Memory Management
 
-```json
-{
-  "runtime": {
-    "node": {
-      "env": {
-        "PYTHONMALLOC": "malloc", // Use system malloc
-        "OMP_NUM_THREADS": "4" // Limit OpenMP threads
-      }
-    }
-  }
-}
+Pass Python-specific tuning through `env` on the bridge:
+
+```typescript
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  env: {
+    PYTHONMALLOC: 'malloc',
+    OMP_NUM_THREADS: '4',
+  },
+});
 ```
 
 ## Production Deployment
@@ -437,8 +447,8 @@ services:
   app:
     build: .
     environment:
-      - TYWRAP_PYTHON_PATH=/usr/bin/python3
       - TYWRAP_CODEC_FALLBACK=json # For smaller containers
+      - TYWRAP_LOG_LEVEL=INFO
     ports:
       - '3000:3000'
 ```
@@ -448,32 +458,36 @@ services:
 ```bash
 # Production environment
 export NODE_ENV=production
-export TYWRAP_PYTHON_PATH="/usr/local/bin/python3"
-export TYWRAP_CACHE_DIR="/tmp/tywrap-cache"
-export TYWRAP_MEMORY_LIMIT="2048"
+export TYWRAP_CODEC_MAX_BYTES=10485760
+export TYWRAP_REQUEST_MAX_BYTES=1048576
+export TYWRAP_LOG_LEVEL=INFO
 
 # Security
 export PYTHONDONTWRITEBYTECODE=1
 export PYTHONUNBUFFERED=1
 ```
 
+Set the Python executable in config or when you construct the bridge:
+
+```typescript
+const bridge = new NodeBridge({
+  pythonPath: '/usr/local/bin/python3',
+});
+```
+
 ## Security Considerations
 
 ### Subprocess Security
 
-```json
-{
-  "runtime": {
-    "node": {
-      "cwd": "/safe/directory", // Restrict working directory
-      "env": {
-        "PATH": "/usr/bin:/bin", // Limit PATH
-        "PYTHONPATH": "/safe/python/libs"
-      },
-      "timeoutMs": 10000 // Prevent hanging processes
-    }
-  }
-}
+```typescript
+const bridge = new NodeBridge({
+  cwd: '/safe/directory',
+  timeoutMs: 10000,
+  env: {
+    PATH: '/usr/bin:/bin',
+    PYTHONPATH: '/safe/python/libs',
+  },
+});
 ```
 
 ### Input Validation
@@ -536,25 +550,25 @@ chmod +x /usr/local/bin/python3
 
 **"Process timeout"**:
 
-```json
-{
-  "runtime": {
-    "node": {
-      "timeoutMs": 60000, // Increase timeout
-      "env": {
-        "OMP_NUM_THREADS": "1" // Reduce parallelism
-      }
-    }
-  }
-}
+```typescript
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  timeoutMs: 60000,
+  env: {
+    OMP_NUM_THREADS: '1',
+  },
+});
 ```
 
 ### Debug Mode
 
 ```bash
-# Enable debug logging
-export TYWRAP_DEBUG=1
-export TYWRAP_VERBOSE=1
+# Wrapper-generation diagnostics
+npx tywrap generate --debug
+
+# Runtime bridge diagnostics
+export TYWRAP_LOG_LEVEL=DEBUG
+export TYWRAP_LOG_JSON=1
 
 # Run with debug output
 node --trace-warnings your-app.js
@@ -591,14 +605,11 @@ if __name__ == '__main__':
     pass
 ```
 
-```json
-{
-  "runtime": {
-    "node": {
-      "scriptPath": "./custom_bridge.py"
-    }
-  }
-}
+```typescript
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  scriptPath: './custom_bridge.py',
+});
 ```
 
 ### Process Pooling

docs/index.md

@@ -46,6 +46,6 @@ setRuntimeBridge(new NodeBridge({ pythonPath: 'python3' }));
 const result = await math.sqrt(16); // 4 — fully typed
 ```
 
-> ⚠️ **Experimental** — APIs may change before v1.0.0. See [CHANGELOG](https://github.com/bbopen/tywrap/blob/main/CHANGELOG.md) for breaking changes.
+> ⚠️ **Experimental** — APIs may change before v1.0.0. See [Releases](https://github.com/bbopen/tywrap/releases) for breaking changes.
 
 > If tywrap saves you time, a ⭐ on [GitHub](https://github.com/bbopen/tywrap) helps others find it.