@pasosdejesus/mpdj 0.1.0

package/dist/blockchain/credential-images.js

@@ -0,0 +1,199 @@
+// src/blockchain/credential-images.ts
+// SVG composition and PNG generation for credential badges.
+//
+// composeCredentialImage reads user SVG + site logos from publicDir,
+// composes layers (border, icon, logo, lock, star), writes SVG + renders PNG.
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ==================== SVG ASSETS (inline defaults) ====================
+const LOCK_SVG_FALLBACK = (color) => `<g transform="translate(452,4) scale(1.8)">
+  <rect x="0" y="16" width="48" height="32" rx="4" fill="${color}22" stroke="${color}" stroke-width="2"/>
+  <path d="M14 16V10a10 10 0 0 1 20 0v6" fill="none" stroke="${color}" stroke-width="2"/>
+</g>`;
+const STAR_SVG = `<g transform="translate(429,220) scale(1.5)">
+  <polygon points="24,0 30,18 48,18 33,30 39,48 24,36 9,48 15,30 0,18 18,18"
+    fill="#fbbf24" stroke="#d97706" stroke-width="1"/>
+</g>`;
+const SITE_LOGOS = {
+    'learn.tg': `<rect x="0" y="0" width="64" height="64" rx="12" fill="#7c3aed"/>
+    <text x="32" y="42" text-anchor="middle" font-size="28" fill="white" font-family="sans-serif" font-weight="bold">LT</text>`,
+    'sivel.xyz': `<rect x="0" y="0" width="64" height="64" rx="12" fill="#0891b2"/>
+    <text x="32" y="42" text-anchor="middle" font-size="24" fill="white" font-family="sans-serif" font-weight="bold">S3</text>`,
+    'stable-sl.pdJ.app': `<rect x="0" y="0" width="64" height="64" rx="12" fill="#059669"/>
+    <text x="32" y="42" text-anchor="middle" font-size="24" fill="white" font-family="sans-serif" font-weight="bold">SL</text>`,
+};
+export const TYPE_COLORS = {
+    course_completion: '#3b82f6',
+    role: '#f59e0b',
+    achievement: '#10b981',
+    nft: '#8b5cf6',
+};
+export const FONT_FAMILY = "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+const SHORT_NAMES = {
+    'learn.tg': 'learntg',
+    'sivel.xyz': 'sivel',
+    'stable-sl.pdJ.app': 'stablesl',
+};
+// ==================== SVG HELPERS ====================
+/**
+ * Escape text for safe inclusion in XML/SVG attributes and text content.
+ * Handles: & < > " '
+ */
+function xmlEscape(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Extract inner content of user's SVG (between <svg> tags).
+ */
+export function extractSvgInner(svgText) {
+    const match = svgText.match(/<svg[^>]*>([\s\S]*)<\/svg>/i);
+    if (!match)
+        throw new Error('Invalid SVG: no <svg> root found');
+    return match[1].trim();
+}
+/**
+ * Validate user's SVG file before composition.
+ */
+export function validateSvg(svgText) {
+    if (!/<svg[\s\S]*viewBox\s*=\s*["']0 0 512 512["']/i.test(svgText)) {
+        throw new Error('SVG must have viewBox="0 0 512 512"');
+    }
+    const forbidden = [
+        /<script/i,
+        /href\s*=\s*["']https?:\/\//i,
+        /xlink:href\s*=\s*["']https?:\/\//i,
+        /data:image\/svg\+xml/i,
+        /foreignObject/i,
+    ];
+    for (const pattern of forbidden) {
+        if (pattern.test(svgText)) {
+            throw new Error(`SVG contains forbidden content: ${pattern.source}`);
+        }
+    }
+    const inner = extractSvgInner(svgText);
+    if (inner.length < 50 || inner.length > 50000) {
+        throw new Error(`SVG content size out of range (${inner.length} chars)`);
+    }
+}
+// ==================== LOCK / PDJ / LOGO ====================
+let lockSvgCache = null;
+let pdjSvgCache = null;
+function getLockSvg(color, publicDir) {
+    if (!lockSvgCache) {
+        const lockSbtPath = path.join(publicDir, 'img', 'lock-sbt.svg');
+        if (fs.existsSync(lockSbtPath)) {
+            lockSvgCache = extractSvgInner(fs.readFileSync(lockSbtPath, 'utf-8'));
+        }
+    }
+    if (lockSvgCache) {
+        const colored = lockSvgCache.replace(/#10b981/gi, color);
+        return `<g transform="translate(405,4) scale(2.0)">${colored}</g>`;
+    }
+    return LOCK_SVG_FALLBACK(color);
+}
+function getPdJLogo(color, publicDir) {
+    if (!pdjSvgCache) {
+        // 1. Try project's public/img/
+        const projectPath = path.join(publicDir, 'img', 'PdJ-badge.svg');
+        if (fs.existsSync(projectPath)) {
+            pdjSvgCache = extractSvgInner(fs.readFileSync(projectPath, 'utf-8'));
+        }
+        else {
+            // 2. Fallback to @pasosdejesus/m/blockchain/img/
+            const mPath = path.join(__dirname, 'img', 'PdJ-badge.svg');
+            if (fs.existsSync(mPath)) {
+                pdjSvgCache = extractSvgInner(fs.readFileSync(mPath, 'utf-8'));
+            }
+        }
+    }
+    if (pdjSvgCache) {
+        const colored = pdjSvgCache.replace(/#currentColor/gi, color);
+        return `<g transform="translate(11,11) scale(3.5)" opacity="0.85">${colored}</g>`;
+    }
+    return '';
+}
+function getLogoSvg(svgPath) {
+    const svg = fs.readFileSync(svgPath, 'utf-8');
+    let w = 256, h = 256;
+    const vb = svg.match(/viewBox\s*=\s*["']0\s+0\s+([\d.]+)\s+([\d.]+)/i);
+    if (vb) {
+        w = parseFloat(vb[1]);
+        h = parseFloat(vb[2]);
+    }
+    const maxDim = Math.max(w, h);
+    const scale = maxDim > 0 ? (96 / maxDim).toFixed(4) : '0.375';
+    return `<g transform="scale(${scale})">${extractSvgInner(svg)}</g>`;
+}
+function getSiteLogo(site, publicDir) {
+    const short = SHORT_NAMES[site] || site;
+    // 1. Try project's public/img/ directory
+    const projectPath = path.join(publicDir, 'img', `logo-${short}.svg`);
+    if (fs.existsSync(projectPath))
+        return getLogoSvg(projectPath);
+    // 2. Fallback to @pasosdejesus/m/blockchain/img/
+    const mPath = path.join(__dirname, 'img', `logo-${short}.svg`);
+    if (fs.existsSync(mPath))
+        return getLogoSvg(mPath);
+    // 3. Last resort: inline default
+    return SITE_LOGOS[site] || '';
+}
+/**
+ * Compose credential image by layering user's SVG icon with
+ * programmatic elements (border, site logo, lock/star overlays).
+ */
+export async function composeCredentialImage(params) {
+    const { userSvgPath, tokenId, site, siteName, type, isSoulbound, isPremium, displayName, publicDir, pngCommand } = params;
+    // 1. Read and validate user SVG
+    if (!fs.existsSync(userSvgPath)) {
+        throw new Error(`SVG file not found: ${userSvgPath}`);
+    }
+    const rawSvg = fs.readFileSync(userSvgPath, 'utf-8');
+    validateSvg(rawSvg);
+    const userInner = extractSvgInner(rawSvg);
+    const color = TYPE_COLORS[type] || '#64748b';
+    const siteLogo = getSiteLogo(site, publicDir);
+    if (!siteLogo)
+        throw new Error(`Unknown site: ${site}`);
+    const generatedDir = path.join(publicDir, 'img', 'credential', 'generated');
+    const pngDir = path.join(publicDir, 'img', 'credential');
+    fs.mkdirSync(generatedDir, { recursive: true });
+    fs.mkdirSync(pngDir, { recursive: true });
+    // 2. Compose layers
+    const layers = [
+        `<rect x="0" y="0" width="512" height="512" rx="28" fill="#ffffff"/>`,
+        `<rect x="0" y="0" width="512" height="512" rx="28" fill="none" stroke="${color}" stroke-width="14"/>`,
+        getPdJLogo(color, publicDir),
+        `<g transform="translate(11,11) scale(0.95)">${userInner}</g>`,
+        `<rect x="0" y="464" width="512" height="48" rx="0" fill="${color}" opacity="0.15"/>`,
+        `<rect x="0" y="464" width="512" height="3" rx="0" fill="${color}" opacity="0.6"/>`,
+        `<g transform="translate(405,364)">${siteLogo}</g>`,
+        `<text x="501" y="498" font-family="${FONT_FAMILY}" font-weight="700" font-size="32" fill="${color}" text-anchor="end">${xmlEscape(siteName)}</text>`,
+        `<text x="8" y="498" font-family="${FONT_FAMILY}" font-weight="700" font-size="${displayName.length > 20 ? 20 : 36}" fill="${color}">${xmlEscape(displayName)}</text>`,
+    ];
+    if (isSoulbound)
+        layers.push(getLockSvg(color, publicDir));
+    if (isPremium)
+        layers.push(STAR_SVG);
+    const composedSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+${layers.join('\n')}
+</svg>
+`;
+    // 3. Write composed SVG
+    const svgPath = path.join(generatedDir, `${tokenId}.svg`);
+    fs.writeFileSync(svgPath, composedSvg, 'utf-8');
+    // 4. Convert to PNG
+    const pngPath = path.join(pngDir, `${tokenId}.png`);
+    execSync(`${pngCommand} "${pngPath}" "${svgPath}"`, { stdio: 'pipe', timeout: 10000 });
+    if (!fs.existsSync(pngPath)) {
+        throw new Error('PNG conversion failed — check pngCommand');
+    }
+    return { svgPath: `img/credential/generated/${tokenId}.svg`, pngPath: `img/credential/${tokenId}.png` };
+}

package/dist/blockchain/credentials.d.ts

@@ -0,0 +1,66 @@
+import type { PublicClient, WalletClient, Chain, Account } from 'viem';
+/**
+ * Get tokenId from courseId (reads from contract).
+ */
+export declare function getTokenIdByCourseId(publicClient: PublicClient, contractAddress: `0x${string}`, courseId: number): Promise<number>;
+/**
+ * Check if an address already holds a credential (reads balanceOf from contract).
+ * For SBTs, balance > 0 means they have it (always amount=1).
+ * For NFTs, balance > 0 means they hold at least one.
+ */
+export declare function hasCredentialOnChain(publicClient: PublicClient, contractAddress: `0x${string}`, account: `0x${string}`, tokenId: number): Promise<boolean>;
+/**
+ * Revoke (burn) a credential from a user.
+ */
+export declare function revokeCredential(walletClient: WalletClient, contractAddress: `0x${string}`, userAddress: `0x${string}`, tokenId: number, amount: number): Promise<string>;
+/**
+ * Generic mint with Celo L2 nonce retry. Handles replacement/underpriced errors.
+ *
+ * Celo's OP Stack sequencer rejects txs that try to replace pending ones
+ * ("replacement transaction underpriced"). This function handles that by:
+ *
+ * 1. Using blockTag: 'pending' to skip stuck nonces
+ * 2. Passing explicit gasPrice from the network
+ * 3. Creating fresh clients each attempt (no http() caching)
+ * 4. Retrying up to 5 times with 2s delays
+ *
+ * @param functionName — 'mintCredential' or 'mintCourseCompletion'
+ * @param args — the writeContract args array
+ * @returns tx hash on success
+ * @throws after all retries exhausted or on non-retryable errors
+ */
+export declare function mintWithRetry(params: {
+    account: Account;
+    rpcUrl: string;
+    chain: Chain;
+    contractAddress: `0x${string}`;
+    functionName: string;
+    args: any[];
+    maxAttempts?: number;
+}): Promise<string>;
+/**
+ * Mint a credential by tokenId with Celo L2 nonce handling.
+ * Calls mintCredential(address, tokenId, 1).
+ */
+export declare function mintCredentialWithRetry(params: {
+    account: Account;
+    rpcUrl: string;
+    chain: Chain;
+    contractAddress: `0x${string}`;
+    userAddress: `0x${string}`;
+    tokenId: number;
+    maxAttempts?: number;
+}): Promise<string>;
+/**
+ * Mint a course completion SBT by courseId with Celo L2 nonce handling.
+ * Calls mintCourseCompletion(address, courseId).
+ */
+export declare function mintCourseWithRetry(params: {
+    account: Account;
+    rpcUrl: string;
+    chain: Chain;
+    contractAddress: `0x${string}`;
+    userAddress: `0x${string}`;
+    courseId: number;
+    maxAttempts?: number;
+}): Promise<string>;

package/dist/blockchain/credentials.js

@@ -0,0 +1,128 @@
+// src/blockchain/credentials.ts
+// Pure functions for PasosDeJesusCredentials contract interactions.
+//
+// All functions receive WalletClient/PublicClient and contractAddress
+// as parameters. The caller wires its own keys, networks, and address.
+import { createPublicClient, createWalletClient, http } from 'viem';
+import pasosDeJesusCredentialsAbi from '../abis/PasosDeJesusCredentials.json' with { type: 'json' };
+/**
+ * Get tokenId from courseId (reads from contract).
+ */
+export async function getTokenIdByCourseId(publicClient, contractAddress, courseId) {
+    const tokenId = await publicClient.readContract({
+        address: contractAddress,
+        abi: pasosDeJesusCredentialsAbi,
+        functionName: 'courseIdToTokenId',
+        args: [BigInt(courseId)],
+    });
+    return Number(tokenId);
+}
+/**
+ * Check if an address already holds a credential (reads balanceOf from contract).
+ * For SBTs, balance > 0 means they have it (always amount=1).
+ * For NFTs, balance > 0 means they hold at least one.
+ */
+export async function hasCredentialOnChain(publicClient, contractAddress, account, tokenId) {
+    try {
+        const balance = await publicClient.readContract({
+            address: contractAddress,
+            abi: pasosDeJesusCredentialsAbi,
+            functionName: 'balanceOf',
+            args: [account, BigInt(tokenId)],
+        });
+        return balance > 0n;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Revoke (burn) a credential from a user.
+ */
+export async function revokeCredential(walletClient, contractAddress, userAddress, tokenId, amount) {
+    return await walletClient.writeContract({
+        address: contractAddress,
+        abi: pasosDeJesusCredentialsAbi,
+        functionName: 'revokeCredential',
+        args: [userAddress, BigInt(tokenId), BigInt(amount)],
+        chain: walletClient.chain,
+        account: walletClient.account,
+    });
+}
+/**
+ * Generic mint with Celo L2 nonce retry. Handles replacement/underpriced errors.
+ *
+ * Celo's OP Stack sequencer rejects txs that try to replace pending ones
+ * ("replacement transaction underpriced"). This function handles that by:
+ *
+ * 1. Using blockTag: 'pending' to skip stuck nonces
+ * 2. Passing explicit gasPrice from the network
+ * 3. Creating fresh clients each attempt (no http() caching)
+ * 4. Retrying up to 5 times with 2s delays
+ *
+ * @param functionName — 'mintCredential' or 'mintCourseCompletion'
+ * @param args — the writeContract args array
+ * @returns tx hash on success
+ * @throws after all retries exhausted or on non-retryable errors
+ */
+export async function mintWithRetry(params) {
+    const { account, rpcUrl, chain, contractAddress, functionName, args, maxAttempts = 5 } = params;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        // Fresh clients each attempt — http() caches nonce, can't reuse
+        const pc = createPublicClient({ chain, transport: http(rpcUrl) });
+        const wc = createWalletClient({ chain, transport: http(rpcUrl), account });
+        const nonce = await pc.getTransactionCount({
+            address: account.address,
+            blockTag: attempt <= 3 ? 'pending' : 'latest',
+        });
+        const gasPrice = await pc.getGasPrice();
+        try {
+            return await wc.writeContract({
+                address: contractAddress,
+                abi: pasosDeJesusCredentialsAbi,
+                functionName,
+                args,
+                chain,
+                account,
+                nonce,
+                gasPrice,
+            });
+        }
+        catch (err) {
+            lastError = err;
+            const msg = err.message || '';
+            if (msg.includes('replacement') || msg.includes('underpriced') ||
+                msg.includes('Missing or invalid')) {
+                await new Promise(r => setTimeout(r, 2000));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+/**
+ * Mint a credential by tokenId with Celo L2 nonce handling.
+ * Calls mintCredential(address, tokenId, 1).
+ */
+export async function mintCredentialWithRetry(params) {
+    const { userAddress, tokenId, ...rest } = params;
+    return mintWithRetry({
+        ...rest,
+        functionName: 'mintCredential',
+        args: [userAddress, BigInt(tokenId), BigInt(1)],
+    });
+}
+/**
+ * Mint a course completion SBT by courseId with Celo L2 nonce handling.
+ * Calls mintCourseCompletion(address, courseId).
+ */
+export async function mintCourseWithRetry(params) {
+    const { userAddress, courseId, ...rest } = params;
+    return mintWithRetry({
+        ...rest,
+        functionName: 'mintCourseCompletion',
+        args: [userAddress, BigInt(courseId)],
+    });
+}

package/dist/blockchain/ecosystem-addresses.d.ts

@@ -0,0 +1,9 @@
+export type CeloNetwork = 'celo' | 'celoSepolia';
+export declare function resolveNetwork(): CeloNetwork;
+export declare const SLEARN_ADDRESSES: Record<CeloNetwork, `0x${string}`>;
+export declare const USDT_ADDRESSES: Record<CeloNetwork, `0x${string}`>;
+export declare const SIGNERS: {
+    readonly learnTg: `0x${string}`;
+    readonly sivel3: `0x${string}`;
+    readonly stableSl: `0x${string}`;
+};

package/dist/blockchain/ecosystem-addresses.js

@@ -0,0 +1,23 @@
+// src/blockchain/ecosystem-addresses.ts
+// Shared addresses for contracts and EIP-191 signers across the Pasos de Jesús ecosystem.
+// Used by learn.tg, sivel.xyz, stable-sl.pdJ.app.
+export function resolveNetwork() {
+    return (process.env.NEXT_PUBLIC_NETWORK === 'celo' ? 'celo' : 'celoSepolia');
+}
+// ── Contracts ────────────────────────────────────────────
+export const SLEARN_ADDRESSES = {
+    celo: '0x27fd41Bea85C39254f2B12789eB37a1543152CC1',
+    celoSepolia: process.env.NEXT_PUBLIC_SLEARN_ADDRESS,
+};
+export const USDT_ADDRESSES = {
+    celo: '0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e',
+    celoSepolia: process.env.NEXT_PUBLIC_USDT_ADDRESS,
+};
+// ── EIP-191 Signers ──────────────────────────────────────
+// Addresses used by each project to sign cross-project messages.
+// These are not contracts but EOA wallets whose signatures are verified via EIP-191.
+export const SIGNERS = {
+    learnTg: '0x358643bAdcC77Cccb28A319abD439438A57339A7',
+    sivel3: '0x9F636E5653b649b44c9375E6E103600AE55aF979',
+    stableSl: '0x6B3BC1b55b28380193733a2FD27f2639d92f14be',
+};

package/dist/blockchain/index.d.ts

@@ -0,0 +1,6 @@
+export * from './credentials.js';
+export * from './credential-cache.js';
+export { verifyCredentialMetadataSchema } from './credential-cache.js';
+export * from './ecosystem-addresses.js';
+export { SlearnInfo } from './SlearnInfo.js';
+export { AddSlearnButton } from './AddSlearnButton.js';

package/dist/blockchain/index.js

@@ -0,0 +1,12 @@
+// src/blockchain/index.ts
+// Server-only modules (credential-images, admin-credentials, deployments)
+// are NOT exported from the barrel to avoid bundling Node.js 'fs' into client builds.
+// Import them directly: import { ... } from '@pasosdejesus/m/blockchain/credential-images'
+//                        import { ... } from '@pasosdejesus/m/blockchain/admin-credentials'
+//                        import { ... } from '@pasosdejesus/m/blockchain/deployments'
+export * from './credentials.js';
+export * from './credential-cache.js';
+export { verifyCredentialMetadataSchema } from './credential-cache.js';
+export * from './ecosystem-addresses.js';
+export { SlearnInfo } from './SlearnInfo.js';
+export { AddSlearnButton } from './AddSlearnButton.js';

package/dist/ia/adJ.md

@@ -0,0 +1,181 @@
+# OpenBSD/adJ Tips for AI Agents
+
+> *"By wisdom a house is built, and by understanding it is established"* (Proverbs 24:3)
+
+This document catalogs platform-specific quirks that cause recurring errors
+when AI agents assume GNU/Linux conventions. Add new entries as they surface.
+
+---
+
+## Shell & CLI
+
+### grep — BSD grep, not GNU
+
+```sh
+# ❌ GNU-only flags
+grep -P 'pattern'         # -P (Perl regex) does not exist
+grep -oP 'pattern'        # same
+grep --exclude-dir=...    # use --exclude instead
+
+# ✅ BSD-compatible
+grep -E 'pattern'          # extended regex
+grep -c 'a' file           # OK for single file
+# Multi-file: prefer separate invocations or handle exit code 1
+grep -c 'a' file1 && grep -c 'a' file2
+```
+
+### sed — BSD sed requires backup extension
+
+```sh
+# ❌ GNU
+sed -i 's/foo/bar/' file
+
+# ✅ BSD — empty string for no backup
+sed -i '' 's/foo/bar/' file
+```
+
+### bash — not at /bin/bash
+
+```sh
+# ❌
+#!/bin/bash
+
+# ✅
+#!/usr/bin/env bash
+# Or: /usr/local/bin/bash
+```
+
+### Shell defaults
+
+OpenBSD's default shell is `ksh`, not `bash`. Scripts without shebangs run
+under `ksh`. Use explicit `#!/usr/bin/env bash` for bash features.
+
+### Pipe exit codes
+
+BSD utilities can produce exit code 1 in pipelines where GNU returns 0.
+Example: `grep -c 'x' file1 file2 | head` — exit 1 if any file has 0 matches.
+
+```sh
+# ❌ May silently fail
+grep -c 'pattern' f1 f2 | head
+
+# ✅ Separate invocations or ignore exit code
+grep -c 'pattern' f1; grep -c 'pattern' f2
+```
+
+---
+
+## System Administration
+
+### Privilege escalation: doas, not sudo
+
+```sh
+# ❌
+sudo command
+
+# ✅
+doas command
+```
+
+### Package management: pkg_add, not apt/yum
+
+```sh
+# ❌
+apt install pkg
+yum install pkg
+
+# ✅
+doas pkg_add pkgname
+```
+
+### Service management: rcctl, not systemctl
+
+```sh
+# ❌
+systemctl start postgresql
+
+# ✅
+doas rcctl start postgresql
+```
+
+### /proc — minimal on OpenBSD
+
+`/proc` exists but only exposes PID and basic info. No `/proc/cpuinfo`,
+`/proc/meminfo`, etc. Use `sysctl` instead:
+
+```sh
+# ❌
+cat /proc/cpuinfo
+
+# ✅
+sysctl hw.model hw.ncpu
+```
+
+---
+
+## PostgreSQL
+
+### System user: _postgresql
+
+```sh
+# ❌ — assumes Linux
+PGUSER=postgres
+
+# ✅ — OpenBSD
+PGUSER=_postgresql
+```
+
+### Unix sockets by default
+
+PostgreSQL on OpenBSD uses Unix sockets by default. Omit `PGHOST` or set it
+to the socket directory:
+
+```sh
+PGHOST=/var/www/var/run/postgresql
+```
+
+---
+
+## Development
+
+### Package manager: pnpm
+
+`pnpm` has better performance than `npm`/`yarn` on OpenBSD. Use it consistently.
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```
+
+### Native binaries (napi-rs)
+
+Many npm packages with native Rust binaries (via napi-rs) lack prebuilt
+OpenBSD binaries. Fallbacks:
+- `@nomicfoundation/edr` → `@pasosdejesus/edr` (@ethereumjs/vm)
+- General pattern: look for `@pasosdejesus/*` fallback packages
+
+### make — BSD make, not GNU
+
+```sh
+# ❌ GNU-specific
+make -j$(nproc)
+
+# ✅ BSD
+make -j$(sysctl -n hw.ncpuonline)
+```
+
+---
+
+## File Paths
+
+### No /bin/bash
+
+Use `/usr/bin/env bash` or `/usr/local/bin/bash`.
+
+### Ports tree
+
+OpenBSD packages installed via `pkg_add` go to `/usr/local/`. This means:
+- Config in `/etc/` for base, `/usr/local/etc/` for packages
+- Binaries in `/usr/local/bin/` for packages
+- Libraries in `/usr/local/lib/` for packages