thedotmack/claude-mem · critical · Error

Missing onboarding explainer source: ${onboardingExplainerSr

Error message

Missing onboarding explainer source: ${onboardingExplainerSrc}

What it means

Build copies src/services/worker/onboarding-explainer.md into plugin/skills/how-it-works/onboarding-explainer.md. If the source markdown does not exist, the build aborts because the shipped skill tree would be missing the onboarding explainer users see. This is a source-tree completeness check, not a runtime guard.

Source

Thrown at scripts/build-hooks.js:687

        format: 'esm',
        outfile: `${opencodeOutDir}/index.js`,
        minify: true,
        logLevel: 'error',
        external: [
          'fs', 'fs/promises', 'path', 'os', 'child_process', 'url',
          'crypto', 'http', 'https', 'net', 'stream', 'util', 'events',
        ],
      });

      const opencodeStats = fs.statSync(`${opencodeOutDir}/index.js`);
      console.log(`✓ opencode plugin built (${(opencodeStats.size / 1024).toFixed(2)} KB)`);
    }

    console.log('\n📋 Copying onboarding explainer to plugin tree...');
    const onboardingExplainerSrc = 'src/services/worker/onboarding-explainer.md';
    const onboardingExplainerDst = 'plugin/skills/how-it-works/onboarding-explainer.md';
    if (!fs.existsSync(onboardingExplainerSrc)) {
      throw new Error(`Missing onboarding explainer source: ${onboardingExplainerSrc}`);
    }
    fs.mkdirSync(path.dirname(onboardingExplainerDst), { recursive: true });
    fs.copyFileSync(onboardingExplainerSrc, onboardingExplainerDst);
    console.log(`✓ Copied ${onboardingExplainerSrc} → ${onboardingExplainerDst}`);

    console.log('\n📋 Verifying distribution files...');
    const validCodexHookEvents = new Set([
      'SessionStart',
      'UserPromptSubmit',
      'PreToolUse',
      'PermissionRequest',
      'PostToolUse',
      'Stop',
    ]);
    const requiredDistributionFiles = [
      'plugin/skills/mem-search/SKILL.md',
      'plugin/skills/mode-creator/SKILL.md',
      'plugin/skills/mode-creator/scripts/install-mode.mjs',

View on GitHub (pinned to d768ba3643)

Solutions

1. Restore the source: git checkout HEAD -- src/services/worker/onboarding-explainer.md.
2. If you intentionally moved the file, update the onboardingExplainerSrc path at scripts/build-hooks.js:687 to the new location.
3. Re-run the build; it prints '✓ Copied ... → plugin/skills/how-it-works/onboarding-explainer.md' on success.

Example fix

# before: src/services/worker/onboarding-explainer.md missing (moved/renamed)

# either restore the canonical location
git checkout HEAD -- src/services/worker/onboarding-explainer.md

# or, if moved on purpose, update scripts/build-hooks.js:687
const onboardingExplainerSrc = 'src/services/worker/<new-location>/onboarding-explainer.md';

if (!fs.existsSync('src/services/worker/onboarding-explainer.md')) {
  throw new Error('onboarding explainer source missing — restore or update build path');
}

// Build-time only. Restore the file from git or update the source path in
// scripts/build-hooks.js if the doc moved intentionally.

When it happens

Trigger: Running node scripts/build-hooks.js when src/services/worker/onboarding-explainer.md has been deleted, moved, or renamed without updating build-hooks.js. A partial checkout or a bad merge that dropped the file.

Common situations: Renaming/relocating the onboarding doc and forgetting to update the source path in build-hooks.js (line 686). Deleting the file as 'cleanup'. Switching branches that don't have the file.

Related errors

• Hand-edited shell string detected in ${filePath} (mcp-search
• Hand-edited shell string detected in ${filePath} (${dottedPa
• Hand-edited Windows shell string detected in ${filePath} (${
• plugin/scripts/bun-runner.js is missing fixBrokenScriptPath
• plugin/scripts/bun-runner.js uses optional chaining (?.) or

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/b02e37f8a4dc2326. Report an issue: GitHub.