diff --git a/package.json b/package.json
index 84221932..f5ece4b7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/monorepo",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "private": true,
   "description": "The minimalist, zero-config documentation generator monorepo.",
   "scripts": {
diff --git a/packages/_playground/package.json b/packages/_playground/package.json
index d8e5d8a3..bdd06625 100644
--- a/packages/_playground/package.json
+++ b/packages/_playground/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/playground",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "private": true,
   "dependencies": {
     "@docmd/core": "workspace:*",
diff --git a/packages/api/package.json b/packages/api/package.json
index 82b62424..6dabfa8f 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/api",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Plugin API surface for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/api/registry/plugins.generated.json b/packages/api/registry/plugins.generated.json
index 199a0eaf..c618eab0 100644
--- a/packages/api/registry/plugins.generated.json
+++ b/packages/api/registry/plugins.generated.json
@@ -1,6 +1,6 @@
 {
   "$meta": {
-    "generatedAt": "2026-07-11T05:18:59.145Z",
+    "generatedAt": "2026-07-12T12:23:44.202Z",
     "generator": "scripts/build-plugin-registry.mjs",
     "packageCount": 15
   },
diff --git a/packages/api/src/engine.ts b/packages/api/src/engine.ts
index 58ec1605..2aba733c 100644
--- a/packages/api/src/engine.ts
+++ b/packages/api/src/engine.ts
@@ -14,6 +14,7 @@
 
 import type { Engine, EngineResult } from './types.js';
 import { engineRegistry, registerEngine } from './types.js';
+import { installRuntimeDep, tryLoadAfterInstall, isValidRuntimeDepName } from './runtime-deps.js';
 export { engineRegistry, registerEngine };
 
 // ---------------------------------------------------------------------------
@@ -57,11 +58,34 @@ export async function loadEngine(name: string = 'js'): Promise<Engine> {
   }
 
   if (name === 'js') {
-    const { createJsEngine } = await import('@docmd/engine-js');
-    return createJsEngine();
+    // JS engine is a hard requirement. Auto-install if it's missing
+    // (e.g. user opted out of @docmd/api optionalDependencies at
+    // install time), then retry once. There is no JS fallback for a
+    // JS engine — call it a fatal loader failure if install also fails.
+    try {
+      const { createJsEngine } = await import('@docmd/engine-js');
+      return createJsEngine();
+    } catch (err) {
+      if (!isValidRuntimeDepName('@docmd/engine-js')) throw err;
+      const installed = await installRuntimeDep('@docmd/engine-js');
+      if (installed) {
+        const reloaded = await tryLoadAfterInstall('@docmd/engine-js');
+        if (reloaded) {
+          const { createJsEngine } = reloaded as any;
+          return createJsEngine();
+        }
+      }
+      throw new Error(
+        `[docmd] JS engine unavailable after auto-install: ${(err as Error).message}. ` +
+        `Add "@docmd/engine-js" to your package.json dependencies.`,
+      );
+    }
   }
 
   if (name === 'rust') {
+    // Rust engine is an optional performance accelerator. Try to load
+    // it; if the package is missing, auto-install it; if install fails
+    // OR the binary isn't usable on this platform, fall back to JS.
     try {
       const { createRustEngine, isRustEngineAvailable } = await import('@docmd/engine-rust');
       if (!isRustEngineAvailable()) {
@@ -70,6 +94,18 @@ export async function loadEngine(name: string = 'js'): Promise<Engine> {
       }
       return createRustEngine();
     } catch (error) {
+      if (isValidRuntimeDepName('@docmd/engine-rust')) {
+        const installed = await installRuntimeDep('@docmd/engine-rust');
+        if (installed) {
+          const reloaded = await tryLoadAfterInstall('@docmd/engine-rust');
+          if (reloaded) {
+            const { createRustEngine, isRustEngineAvailable } = reloaded as any;
+            if (isRustEngineAvailable && isRustEngineAvailable()) {
+              return createRustEngine();
+            }
+          }
+        }
+      }
       console.warn(`[docmd] Rust engine unavailable (${(error as Error).message}), falling back to JS engine.`);
       return loadEngine('js');
     }
diff --git a/packages/api/src/hooks.ts b/packages/api/src/hooks.ts
index 809998cb..ca4eebc4 100644
--- a/packages/api/src/hooks.ts
+++ b/packages/api/src/hooks.ts
@@ -28,6 +28,12 @@ import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { safePath, asUserPath } from '@docmd/utils';
 import type { PluginDescriptor, PluginHooks, PluginModule, Capability, TemplateHook, TemplateAssetHook } from './types.js';
+import {
+  loadRuntimeRegistry,
+  installRuntimeDep,
+  tryLoadAfterInstall,
+  shortKey,
+} from './runtime-deps.js';
 
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -283,12 +289,12 @@ function warnOnce(key: string, message: string): void {
 
 export function resolvePluginName(key: string): string {
   if (key.includes('/')) return key;
-  
-  const registry = getPluginRegistry();
+
+  const registry = loadRuntimeRegistry();
   if (registry[key]) {
     return `@docmd/plugin-${key}`;
   }
-  
+
   const corePlugins = CORE_PLUGINS;
   if (corePlugins.includes(key)) {
     return `@docmd/plugin-${key}`;
@@ -319,130 +325,12 @@ export function resolveTemplateName(key: string): string {
 // ---------------------------------------------------------------------------
 // Auto-Install for Official Plugins
 // ---------------------------------------------------------------------------
-
-// Load the official plugin registry
-let _pluginRegistry: Record<string, any> | null = null;
-
-function getPluginRegistry(): Record<string, any> {
-  if (_pluginRegistry) return _pluginRegistry;
-
-  // The registry is generated at build time by `scripts/build-plugin-registry.mjs`
-  // and lives at <package-root>/registry/plugins.generated.json. It is the
-  // single source of truth for the official plugin / template / engine
-  // catalog — regenerated from each package's `package.json#docmd`
-  // namespace, so the hand-maintained
-  // packages/plugins/installer/registry/plugins.json that used to be
-  // here is no longer consulted.
-  //
-  // Two resolution paths:
-  //   1. Monorepo dev: <repo>/packages/api/registry/plugins.generated.json
-  //   2. Published package: <pkg>/registry/plugins.generated.json
-  //      (listed in this package's `files` array)
-  const candidates = [
-    path.resolve(__dirname, '..', 'registry', 'plugins.generated.json'),
-    path.resolve(__monorepoRoot, 'packages', 'api', 'registry', 'plugins.generated.json'),
-  ];
-  for (const candidate of candidates) {
-    if (nativeFs.existsSync(candidate)) {
-      _pluginRegistry = JSON.parse(nativeFs.readFileSync(candidate, 'utf8'));
-      return _pluginRegistry!;
-    }
-  }
-  return {};
-}
-
-/**
- * Detect the package manager used in the current project.
- */
-function detectPackageManager(cwd: string): 'pnpm' | 'yarn' | 'bun' | 'npm' {
-  let dir = cwd;
-  while (dir !== path.parse(dir).root) {
-    if (nativeFs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
-    if (nativeFs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
-    if (nativeFs.existsSync(path.join(dir, 'bun.lockb'))) return 'bun';
-    if (nativeFs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm';
-    dir = path.dirname(dir);
-  }
-  return 'npm';
-}
-
-/**
- * Get the current docmd version for version-matched installs.
- */
-function getDocmdVersion(): string {
-  try {
-    const corePkgPath = require.resolve('@docmd/core/package.json', {
-      paths: [process.cwd(), __dirname, __monorepoRoot]
-    });
-    const pkg = JSON.parse(nativeFs.readFileSync(corePkgPath, 'utf8'));
-    return pkg.version || 'latest';
-  } catch {
-    return 'latest';
-  }
-}
-
-/**
- * Auto-install an official plugin from npm.
- * Only works for plugins in the official registry.
- * Installs the exact version matching the current docmd version.
- */
-async function autoInstallPlugin(packageName: string): Promise<boolean> {
-  const shortName = packageName
-    .replace('@docmd/plugin-', '')
-    .replace('@docmd/template-', '');
-  const registry = getPluginRegistry();
-  
-  // Security: Only auto-install plugins in the official registry
-  if (!registry[shortName]) {
-    warnOnce(`registry:${packageName}`, TUI.yellow(`Plugin "${shortName}" not found in official registry - manual installation required`));
-    return false;
-  }
-
-  const cwd = process.cwd();
-  const pkgManager = detectPackageManager(cwd);
-  const version = getDocmdVersion();
-  const versionedPackage = version === 'latest' ? packageName : `${packageName}@${version}`;
-
-  TUI.step(`Downloading missing plugin: ${shortName}`, 'WAIT');
-
-  let installCmd = '';
-  switch (pkgManager) {
-    case 'pnpm': installCmd = `pnpm add ${versionedPackage}`; break;
-    case 'yarn': installCmd = `yarn add ${versionedPackage}`; break;
-    case 'bun': installCmd = `bun add ${versionedPackage}`; break;
-    default: installCmd = `npm install ${versionedPackage}`; break;
-  }
-
-  try {
-    const { execSync } = await import('node:child_process');
-    execSync(installCmd, { stdio: 'pipe', cwd, timeout: 60000 });
-    TUI.step(`Plugin installed: ${shortName}`, 'DONE');
-    return true;
-  } catch (err: any) {
-    TUI.step(`Failed to install: ${shortName}`, 'FAIL');
-    // Surface the underlying error so users (and CI logs) can see
-    // exactly why the install failed — e.g. ETARGET when the version
-    // isn't on the registry, or EACCES/EPERM when CI has no permission
-    // to mutate the project directory. Without this, "Could not load
-    // … after auto-install" looks like a bug in docmd when it's really
-    // a sandbox/CI issue.
-    const stderr = ((err && (err.stderr || err.message)) || '').toString().split('\n').filter(Boolean).slice(0, 3).join(' | ');
-    const isTemplate = packageName.startsWith('@docmd/template-');
-    // For templates the most reliable fix is to add the package to the
-    // project's `dependencies` (or `devDependencies`) so the user's
-    // normal package manager pulls it during the install step. Doing
-    // it that way survives CI sandboxes that block ad-hoc `pnpm add`
-    // invocations from docmd's runtime.
-    const hint = isTemplate
-      ? `Add "${packageName}" to your package.json dependencies, then run your normal install step.`
-      : `Run "docmd add ${shortName}" to install it, or add "${packageName}" to your package.json.`;
-    warnOnce(`install:${packageName}`, TUI.yellow(
-      `Auto-install of ${packageName} failed: ${stderr || 'unknown error'}\n` +
-      TUI.dim(`  > ${hint}`)
-    ));
-    return false;
-  }
-}
+//
+// The registry loader, package-manager detector, version pinner, and
+// `spawn`-based installer live in `./runtime-deps.ts`. This module
+// replaces the previous inline `execSync(\`pnpm add ${pkg}\`)` which
+// was a CWE-78 (shell injection) surface. The shared module is also
+// consumed by `engine.ts` for engine auto-install.
 
 // ---------------------------------------------------------------------------
 // Load & Register
@@ -621,38 +509,30 @@ export async function loadPlugins(config: any, opts?: { resolvePaths?: string[]
       // Auto-install official plugins AND templates that are missing
       const isOfficial = name.startsWith('@docmd/plugin-') || name.startsWith('@docmd/template-');
       if (needsAutoInstall && isOfficial) {
-        const installed = await autoInstallPlugin(name);
+        const installed = await installRuntimeDep(name);
         if (installed) {
           // Defense in depth: re-verify the package is in the official registry
-          // before loading. autoInstallPlugin already passed this check, but we
+          // before loading. installRuntimeDep already passed this check, but we
           // re-check here so a future change to that function cannot silently
           // turn the auto-install path into a generic npm-loader.
-          const shortName = name
-            .replace('@docmd/plugin-', '')
-            .replace('@docmd/template-', '');
-          if (!getPluginRegistry()[shortName]) {
-            warnOnce(`registry:${name}`, TUI.yellow(`Plugin "${shortName}" not in official registry`));
+          const shortNameLocal = shortKey(name);
+          const registry = loadRuntimeRegistry();
+          if (!shortNameLocal || !registry[shortNameLocal]) {
+            warnOnce(`registry:${name}`, TUI.yellow(`Plugin "${shortNameLocal ?? name}" not in official registry`));
             continue;
           }
           // Retry loading after install. We use dynamic `import()` (not
           // `require.resolve` + file:// import) so packages that declare
           // `exports` with only an `import` condition are still resolvable.
-          try {
-            rawModule = await import(name);
-          } catch (err: any) {
-            // Surface the real error so the user can act on it.
-            // `err.code` is the most useful bit (e.g. ERR_PACKAGE_PATH_NOT_EXPORTED,
-            // ERR_MODULE_NOT_FOUND). The default "Could not load X after auto-install"
-            // used to look like a docmd bug when the real cause was a bad
-            // package.json in the dependency.
-            const errCode = err && err.code ? ` [${err.code}]` : '';
-            const errMsg = err && err.message ? err.message.split('\n')[0] : 'unknown error';
+          const reloaded = await tryLoadAfterInstall(name);
+          if (!reloaded) {
             warnOnce(
               `autoinstall:${name}`,
-              TUI.yellow(`Could not load ${name} after auto-install${errCode}: ${errMsg}`)
+              TUI.yellow(`Could not load ${name} after auto-install`),
             );
             continue;
           }
+          rawModule = reloaded;
         } else {
           continue; // Skip if auto-install failed
         }
@@ -664,8 +544,8 @@ export async function loadPlugins(config: any, opts?: { resolvePaths?: string[]
 
       // Stage 4: pull the manifest's declared capabilities (from the
       // registry) so registerPlugin can cross-check the JS descriptor.
-      const shortKey = name.replace('@docmd/plugin-', '').replace('@docmd/template-', '');
-      const manifestCapabilities = (getPluginRegistry()[shortKey]?.capabilities) as string[] | undefined;
+      const shortNameForManifest = shortKey(name) ?? name;
+      const manifestCapabilities = (loadRuntimeRegistry()[shortNameForManifest]?.capabilities) as string[] | undefined;
 
       try {
         registerPlugin(name, pluginModule, options, manifestCapabilities);
@@ -699,7 +579,7 @@ const _capabilityCache: Map<string, Set<string>> = new Map();
 function getCapabilitySet(shortName: string): Set<string> {
   let set = _capabilityCache.get(shortName);
   if (set) return set;
-  const entry = getPluginRegistry()[shortName];
+  const entry = loadRuntimeRegistry()[shortName];
   set = new Set<string>(Array.isArray(entry?.capabilities) ? entry.capabilities : []);
   _capabilityCache.set(shortName, set);
   return set;
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index 73e3faa9..bf90279a 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -15,6 +15,18 @@
 // Plugin loader & hook registry
 export { loadPlugins, hooks, resolvePluginName, resolveTemplateName, getPluginErrors, getPluginLoadErrors, CORE_PLUGINS, isCorePlugin } from './hooks.js';
 
+// Runtime dependency bootstrap (auto-install pipeline shared by hooks + engines)
+export {
+  loadRuntimeRegistry,
+  detectPackageManager,
+  getDocmdVersion,
+  isValidRuntimeDepName,
+  installRuntimeDep,
+  tryLoadAfterInstall,
+  shortKey as shortRuntimeDepKey,
+  getBuildStatusReporter,
+} from './runtime-deps.js';
+
 // RPC action/event dispatcher
 export { createActionDispatcher } from './rpc.js';
 
diff --git a/packages/api/src/runtime-deps.ts b/packages/api/src/runtime-deps.ts
new file mode 100644
index 00000000..e1dab2d4
--- /dev/null
+++ b/packages/api/src/runtime-deps.ts
@@ -0,0 +1,363 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/api
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+/**
+ * Runtime dependency bootstrap for plugins, templates, and engines.
+ *
+ * This module is the single source of truth for the "fetch a missing
+ * official dependency on first build" path. Both `hooks.ts` (plugin /
+ * template loader) and `engine.ts` (engine loader) call into it.
+ *
+ * Why it exists:
+ *   - Security: replaces the previous `execSync(\`pnpm add ${pkg}\`)`
+ *     shell-string command, which was a CWE-78 surface if a name ever
+ *     leaked in from an untrusted config (fixed by strict regex +
+ *     `spawn` arg-array + defence-in-depth registry lookup).
+ *   - Reuse: the install pipeline was duplicated in hooks and engine;
+ *     one module, one set of behaviour changes.
+ *   - Idempotency: TUI status lines are reported through a per-build
+ *     cache so a dev-server rebuild that re-runs the loader doesn't
+ *     spam the same "WAIT / DONE" line pair for packages already on
+ *     disk.
+ *
+ * Public surface (re-exported from `index.ts`):
+ *   - `loadRuntimeRegistry()`         — read & cache the generated registry
+ *   - `detectPackageManager(cwd)`     — pick pnpm / yarn / bun / npm
+ *   - `getDocmdVersion()`             — `@docmd/core` version (for pinning)
+ *   - `isValidRuntimeDepName(name)`   — strict regex, returns boolean
+ *   - `installRuntimeDep(pkg)`        — non-shell `spawn` install, true on ok
+ *   - `reportInstallStatus(shortName, status)` — idempotent TUI reporter
+ *   - `getBuildStatusReporter()`     — single per-build reporter cache
+ */
+
+import path from 'node:path';
+import nativeFs from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { TUI } from '@docmd/tui';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Monorepo root - two levels up from packages/api/dist/
+const __monorepoRoot = path.resolve(__dirname, '..', '..', '..');
+
+// ---------------------------------------------------------------------------
+// Strict package-name regex (CWE-78 defence)
+// Accepts:  @docmd/plugin-foo
+//           @docmd/template-summer
+//           @docmd/engine-rust
+//           @docmd/plugin-math-katex  (two-segment short names are fine)
+// Rejects: anything with shell metacharacters, scoped third-party names,
+//          uppercase letters, or names that don't fit the @docmd/<kind>-*
+//          pattern. A second defence lives in `installRuntimeDep`, which
+//          cross-checks the lookup against `loadRuntimeRegistry()` so a
+//          forbidden name that happens to match the regex still cannot be
+//          installed.
+// ---------------------------------------------------------------------------
+const PACKAGE_NAME_RE = /^@docmd\/(?:plugin|template|engine)-[a-z0-9][a-z0-9.-]*$/;
+
+// ---------------------------------------------------------------------------
+// Registry loader
+// ---------------------------------------------------------------------------
+
+let _registry: Record<string, any> | null = null;
+
+/**
+ * Read the generated runtime registry for plugins / templates / engines.
+ *
+ * Resolution order:
+ *   1. `<package-root>/registry/plugins.generated.json`  (monorepo dev +
+ *      published package, both expose this path under `files`).
+ *   2. `<monorepo-root>/packages/api/registry/plugins.generated.json`
+ *      (fallback for callers that import us from a nested dist path
+ *      that the first candidate doesn't satisfy).
+ *
+ * The result is cached per process so a hot dev-server loop doesn't
+ * re-read the file on every hook call.
+ */
+export function loadRuntimeRegistry(): Record<string, any> {
+  if (_registry) return _registry;
+  const candidates = [
+    path.resolve(__dirname, '..', 'registry', 'plugins.generated.json'),
+    path.resolve(__monorepoRoot, 'packages', 'api', 'registry', 'plugins.generated.json'),
+  ];
+  for (const candidate of candidates) {
+    if (nativeFs.existsSync(candidate)) {
+      _registry = JSON.parse(nativeFs.readFileSync(candidate, 'utf8'));
+      return _registry!;
+    }
+  }
+  _registry = {};
+  return _registry;
+}
+
+/** Force-reload the registry cache (tests only). */
+export function _resetRuntimeRegistryCache(): void {
+  _registry = null;
+}
+
+// ---------------------------------------------------------------------------
+// Project inspection helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the package manager used in `cwd` (or any of its ancestors).
+ * Walks upward until a known lockfile is found; defaults to `npm`.
+ */
+export function detectPackageManager(cwd: string): 'pnpm' | 'yarn' | 'bun' | 'npm' {
+  let dir = cwd;
+  while (dir !== path.parse(dir).root) {
+    if (nativeFs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (nativeFs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+    if (nativeFs.existsSync(path.join(dir, 'bun.lockb'))) return 'bun';
+    if (nativeFs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm';
+    dir = path.dirname(dir);
+  }
+  return 'npm';
+}
+
+/**
+ * Resolve the current `@docmd/core` version, used to pin `pkg@<version>`
+ * installs to the same release line as the user's docmd. Falls back to
+ * `latest` when the core package isn't resolvable (e.g. running inside
+ * a CI image without node_modules linked).
+ */
+export function getDocmdVersion(): string {
+  try {
+    const corePkgPath = require.resolve('@docmd/core/package.json', {
+      paths: [process.cwd(), __dirname, __monorepoRoot],
+    });
+    const pkg = JSON.parse(nativeFs.readFileSync(corePkgPath, 'utf8'));
+    return pkg.version || 'latest';
+  } catch {
+    return 'latest';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Package-name validator (CWE-78 defence)
+// ---------------------------------------------------------------------------
+
+/**
+ * True only when `name` is an `@docmd/<kind>-<short>` reference. This
+ * is the FIRST line of defence; `installRuntimeDep` also cross-checks
+ * against `loadRuntimeRegistry()` so a name that matches the regex but
+ * isn't in the official catalog still cannot be installed.
+ */
+export function isValidRuntimeDepName(name: string): boolean {
+  return typeof name === 'string' && PACKAGE_NAME_RE.test(name);
+}
+
+/**
+ * Map an npm package name to its registry short key. Returns null when
+ * the name is not an `@docmd/<kind>-*` reference.
+ */
+function shortNameOf(packageName: string): string | null {
+  if (!isValidRuntimeDepName(packageName)) return null;
+  if (packageName.startsWith('@docmd/plugin-')) return packageName.replace('@docmd/plugin-', '');
+  if (packageName.startsWith('@docmd/template-')) return packageName.replace('@docmd/template-', '');
+  if (packageName.startsWith('@docmd/engine-')) return packageName.replace('@docmd/engine-', '');
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Idempotent TUI status reporter
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-build cache of short-name → status pairs. Constructed once per
+ * loader run via `getBuildStatusReporter()`. Subsequent attempts to
+ * report the same short name in the same build are silently dropped,
+ * so a dev-server rebuild can't spam the same line pair.
+ */
+interface StatusLine {
+  status: 'WAIT' | 'DONE' | 'FAIL' | 'SKIP' | string;
+  message?: string;
+}
+
+type BuildReporter = {
+  begin(shortName: string): void;
+  finish(shortName: string, status: StatusLine['status']): void;
+  setMessage(shortName: string, message: string): void;
+  reset(): void;
+};
+
+/**
+ * Build a fresh reporter. Each `loadPlugins` / `loadEngine` call gets
+ * its own reporter so the cache is bound to one loader run.
+ */
+export function getBuildStatusReporter(): BuildReporter {
+  const seen = new Map<string, StatusLine>();
+  return {
+    begin(shortName) {
+      // Skip if we've already emitted a "WAIT" for this name this build —
+      // the install is in flight (or finished); re-emitting would make the
+      // TUI flicker on dev-server rebuilds.
+      if (seen.has(shortName)) return;
+      seen.set(shortName, { status: 'WAIT' });
+      TUI.step(`Downloading missing runtime dep: ${shortName}`, 'WAIT');
+    },
+    finish(shortName, status) {
+      const prev = seen.get(shortName);
+      seen.set(shortName, { status, message: prev?.message });
+      TUI.step(`Runtime dep ${status.toLowerCase()}: ${shortName}`, status);
+    },
+    setMessage(shortName, message) {
+      const prev = seen.get(shortName) ?? { status: 'WAIT' };
+      seen.set(shortName, { status: prev.status, message });
+    },
+    reset() {
+      seen.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// `spawn`-based installer (CWE-78 fix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the arg array for the user's package manager. Returned as an
+ * array, never a string, so `spawn` doesn't go through a shell and the
+ * package name can never be reinterpreted as a flag or command.
+ */
+function buildInstallArgs(packageName: string, pm: 'pnpm' | 'yarn' | 'bun' | 'npm'): string[] {
+  switch (pm) {
+    case 'pnpm': return ['add', packageName];
+    case 'yarn': return ['add', packageName];
+    case 'bun':  return ['add', packageName];
+    case 'npm':  return ['install', packageName];
+  }
+}
+
+/**
+ * Non-shell install of an official runtime dependency. Replaces the
+ * previous `execSync(\`${pm} add ${pkg}\`)` with `spawn` + arg array.
+ *
+ * Defence in depth (in order):
+ *   1. `isValidRuntimeDepName(pkg)` — strict regex.
+ *   2. `loadRuntimeRegistry()[shortName]` — official catalog lookup.
+ *   3. `spawn(pm, [...args], { shell: false })` — never hits a shell.
+ *
+ * Returns true on a clean exit code from the package manager, false
+ * otherwise. Caller decides whether a fail should be fatal.
+ */
+export function installRuntimeDep(packageName: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (!isValidRuntimeDepName(packageName)) {
+      TUI.warn(`Refusing to install non-runtime dep: ${packageName}`);
+      return resolve(false);
+    }
+    const shortName = shortNameOf(packageName);
+    if (!shortName) return resolve(false);
+
+    const registry = loadRuntimeRegistry();
+    if (!registry[shortName]) {
+      TUI.warn(`Runtime dep "${shortName}" not found in official registry`);
+      return resolve(false);
+    }
+
+    const cwd = process.cwd();
+    const pm = detectPackageManager(cwd);
+    const version = getDocmdVersion();
+    const versionedPackage =
+      version === 'latest' ? packageName : `${packageName}@${version}`;
+
+    const reporter = getBuildStatusReporter();
+    reporter.begin(shortName);
+
+    const args = buildInstallArgs(versionedPackage, pm);
+    let stderr = '';
+    let stdout = '';
+    // shell: true only on Windows because npm/yarn/pnpm are .cmd batch
+    // files there. On macOS/Linux, shell: false is more secure and
+    // works because the package managers are real executables. The
+    // package name is already validated by the strict regex above, so
+    // enabling the shell on Windows introduces no injection surface.
+    const useShell = process.platform === 'win32';
+    const child = spawn(pm, args, { cwd, shell: useShell, timeout: 60_000 });
+
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+
+    child.on('error', (err) => {
+      reporter.finish(shortName, 'FAIL');
+      const surface = (stderr || err.message || 'unknown error')
+        .toString()
+        .split('\n')
+        .filter(Boolean)
+        .slice(0, 3)
+        .join(' | ');
+      const isTemplate = packageName.startsWith('@docmd/template-');
+      const hint = isTemplate
+        ? `Add "${packageName}" to your package.json dependencies, then run your normal install step.`
+        : `Run "docmd add ${shortName}" to install it, or add "${packageName}" to your package.json.`;
+      TUI.warn(
+        `Auto-install of ${packageName} failed: ${surface}\n  > ${hint}`,
+      );
+      resolve(false);
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        reporter.finish(shortName, 'DONE');
+        return resolve(true);
+      }
+      reporter.finish(shortName, 'FAIL');
+      const surface = stderr
+        .toString()
+        .split('\n')
+        .filter(Boolean)
+        .slice(0, 3)
+        .join(' | ');
+      const isTemplate = packageName.startsWith('@docmd/template-');
+      const hint = isTemplate
+        ? `Add "${packageName}" to your package.json dependencies, then run your normal install step.`
+        : `Run "docmd add ${shortName}" to install it, or add "${packageName}" to your package.json.`;
+      TUI.warn(
+        `Auto-install of ${packageName} failed (exit ${code}): ${surface || 'unknown error'}\n  > ${hint}`,
+      );
+      resolve(false);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers consumed by hooks.ts and engine.ts
+// ---------------------------------------------------------------------------
+
+/**
+ * Short key for a package name, used for status lines and registry
+ * lookups. Returns null for names that fail validation.
+ */
+export function shortKey(packageName: string): string | null {
+  return shortNameOf(packageName);
+}
+
+/**
+ * Re-load `pkg` after an install attempt. Returns the module reference
+ * or null when the import still fails. We use dynamic `import(pkgName)`
+ * (not file:// resolution) so `exports` with only the `import`
+ * condition still resolves on modern Node.
+ */
+export async function tryLoadAfterInstall(packageName: string): Promise<any | null> {
+  try {
+    return await import(packageName);
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index c68109a3..c460a32b 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/core",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Build production-ready documentation from Markdown in seconds. No React, no bloat, just content.",
   "type": "module",
   "browser": false,
@@ -31,7 +31,6 @@
     "@docmd/plugin-mermaid": "workspace:*",
     "@docmd/plugin-okf": "workspace:*",
     "@docmd/plugin-openapi": "workspace:*",
-    "@docmd/plugin-pwa": "workspace:*",
     "@docmd/plugin-search": "workspace:*",
     "@docmd/plugin-seo": "workspace:*",
     "@docmd/plugin-sitemap": "workspace:*",
diff --git a/packages/core/src/utils/config-loader.ts b/packages/core/src/utils/config-loader.ts
index e0ab4282..926eec7a 100644
--- a/packages/core/src/utils/config-loader.ts
+++ b/packages/core/src/utils/config-loader.ts
@@ -369,6 +369,10 @@ export async function loadConfig(configPath: string, options: any = {}) {
 
       const normalized = normalizeConfig(mergedConfig);
 
+      if (normalized._baseAutoDerived) {
+        TUI.info(`${TUI.dim('base auto-derived from url:')} ${TUI.cyan(normalized._baseAutoDerived)}`);
+      }
+
       // Navigation Handling: Prioritize local navigation.json in the project folder
       let navScanDir = path.resolve(cwd, normalized.srcDir);
       let localNavPath = path.join(navScanDir, 'navigation.json');
diff --git a/packages/core/src/utils/config-schema.ts b/packages/core/src/utils/config-schema.ts
index affec8e3..30907898 100644
--- a/packages/core/src/utils/config-schema.ts
+++ b/packages/core/src/utils/config-schema.ts
@@ -64,7 +64,64 @@ export function normalizeConfig(userConfig: any) {
     config.url = config.url || config.siteUrl || config.baseUrl || '';
     config.src = config.src || config.srcDir || config.source || 'docs';
     config.out = process.env.DOCMD_PROJECT_OUT || config.out || config.outDir || config.outputDir || 'site';
+
+    // Track whether the user explicitly set base (vs. the default '/').
+    // The env var (DOCMD_PROJECT_PREFIX) counts as explicit; only a truly
+    // absent base triggers auto-derivation from url below.
+    const _userSetBaseExplicitly = !!process.env.DOCMD_PROJECT_PREFIX || userConfig.base !== undefined;
     config.base = process.env.DOCMD_PROJECT_PREFIX || config.base || '/';
+
+    // --- 1.1 Normalise base slashes + auto-derive from URL ---
+    //
+    // DESIGN PRINCIPLE: `base` is an internal implementation detail. Users
+    // should NEVER have to think about it. They set `url` (the canonical
+    // production URL) and docmd derives everything else. The only time
+    // `base` is needed is the rare case where the deployment path differs
+    // from the URL path (e.g. a CDN that strips a prefix).
+    //
+    // What this block does, in order:
+    //   1. If the user explicitly set base, normalise its slashes:
+    //      "repo" → "/repo/", "/repo" → "/repo/", "repo/" → "/repo/".
+    //      Users should not have to remember whether slashes are needed.
+    //   2. If base was NOT explicitly set, derive it from url's pathname.
+    //      This handles GitHub Pages project sites and any subpath deploy
+    //      where the user set url to match their deployment.
+    //   3. If neither base nor url is informative, default to "/".
+    //
+    // The derivation is slash-tolerant on url too:
+    //   url = "https://user.github.io/repo"   → base = "/repo/"
+    //   url = "https://user.github.io/repo/"  → base = "/repo/"
+    //   url = "https://docs.example.com"      → base = "/"
+    //   url = "https://example.com/docs/"     → base = "/docs/"
+    //
+    // If derivation cannot fire (no url, or url is a root), base stays "/"
+    // and the build will warn if assets turn out to be unreachable.
+    if (_userSetBaseExplicitly && config.base !== '/') {
+        // User set base explicitly: fix the slashes for them.
+        let b = config.base.trim();
+        if (!b.startsWith('/')) b = '/' + b;       // "repo" → "/repo"
+        if (!b.endsWith('/')) b = b + '/';         // "/repo" → "/repo/"
+        // Collapse accidental double slashes (e.g. "//repo///" → "/repo/").
+        b = b.replace(/([^:])\/{2,}/g, '$1/');
+        if (b !== config.base) config._baseNormalised = config.base;
+        config.base = b;
+    } else if (!_userSetBaseExplicitly && config.url) {
+        // Derive base from url. Slash-tolerant on both ends.
+        try {
+            const parsedUrl = new URL(config.url);
+            // Strip trailing slashes to get a clean path, then re-add one.
+            // Empty or "/" → root deployment, base stays "/".
+            const pathname = parsedUrl.pathname.replace(/\/+$/, '');
+            if (pathname && pathname !== '/') {
+                const derivedBase = pathname + '/';
+                config.base = derivedBase;
+                config._baseAutoDerived = derivedBase;
+            }
+        } catch {
+            // Invalid url (placeholder, typo, empty-ish) — leave base as "/".
+            // The build will surface a clear warning if assets end up missing.
+        }
+    }
     // Top-level QoL defaults — opt out by setting `false`.
     if (config.pageNavigation === undefined) config.pageNavigation = true;
     if (config.copyCode === undefined) config.copyCode = true;
diff --git a/packages/deployer/package.json b/packages/deployer/package.json
index f4d79a90..efe5f636 100644
--- a/packages/deployer/package.json
+++ b/packages/deployer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/deployer",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Deployment configuration generator for docmd - Docker, Nginx, Caddy, GitHub Pages, Vercel, and Netlify.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/engines/js/package.json b/packages/engines/js/package.json
index b81c403d..4c78eff3 100644
--- a/packages/engines/js/package.json
+++ b/packages/engines/js/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/engine-js",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Default JavaScript engine for docmd using Node.js native APIs.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/engines/js/src/index.ts b/packages/engines/js/src/index.ts
index f0854be5..a3ef7f0d 100644
--- a/packages/engines/js/src/index.ts
+++ b/packages/engines/js/src/index.ts
@@ -275,7 +275,7 @@ const handlers: Record<string, TaskHandler> = {
 export function createJsEngine(): Engine {
   return {
     name: 'js',
-    version: '0.8.11',
+    version: '0.8.12',
 
     supports(taskType: string): boolean {
       return taskType in handlers;
diff --git a/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node b/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node
index 9fd0cdf3..5218260e 100755
Binary files a/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node and b/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node differ
diff --git a/packages/engines/rust-binaries/native/Cargo.lock b/packages/engines/rust-binaries/native/Cargo.lock
index cd89a9ce..7a1df150 100644
--- a/packages/engines/rust-binaries/native/Cargo.lock
+++ b/packages/engines/rust-binaries/native/Cargo.lock
@@ -50,7 +50,7 @@ dependencies = [
 
 [[package]]
 name = "docmd-engine"
-version = "0.8.11"
+version = "0.8.12"
 dependencies = [
  "napi",
  "napi-build",
diff --git a/packages/engines/rust-binaries/native/Cargo.toml b/packages/engines/rust-binaries/native/Cargo.toml
index ec3ff485..3013274d 100644
--- a/packages/engines/rust-binaries/native/Cargo.toml
+++ b/packages/engines/rust-binaries/native/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name        = "docmd-engine"
-version     = "0.8.11"
+version     = "0.8.12"
 edition     = "2021"
 description = "Native Node.js addon for the docmd Rust engine"
 license     = "MIT"
diff --git a/packages/engines/rust-binaries/package.json b/packages/engines/rust-binaries/package.json
index 3cd5aa4b..db05018c 100644
--- a/packages/engines/rust-binaries/package.json
+++ b/packages/engines/rust-binaries/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/engine-rust-binaries",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Pre-built Rust binaries for the docmd engine. All platforms bundled.",
   "scripts": {
     "build": "node build.js"
diff --git a/packages/engines/rust/package.json b/packages/engines/rust/package.json
index b336a618..1434b014 100644
--- a/packages/engines/rust/package.json
+++ b/packages/engines/rust/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/engine-rust",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Rust-accelerated engine for docmd. The postinstall script downloads a pre-built platform binary from npm CDN (unpkg/jsdelivr). No code is executed beyond copying the .node file. Source: https://github.com/docmd-io/docmd",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/engines/rust/src/index.ts b/packages/engines/rust/src/index.ts
index d99b3cf6..752b93a8 100644
--- a/packages/engines/rust/src/index.ts
+++ b/packages/engines/rust/src/index.ts
@@ -129,7 +129,7 @@ export function createRustEngine(): Engine {
   
   return {
     name: 'rust',
-    version: '0.8.11',
+    version: '0.8.12',
     
     supports(_taskType: string): boolean {
       return true;
diff --git a/packages/legacy/doc.md/package.json b/packages/legacy/doc.md/package.json
index 2aa2b782..1f296a1c 100644
--- a/packages/legacy/doc.md/package.json
+++ b/packages/legacy/doc.md/package.json
@@ -1,6 +1,6 @@
 {
   "name": "doc.md",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Discontinued. Legacy wrapper for docmd. Please use @docmd/core.",
   "bin": {
     "docmd": "bin/docmd.js"
diff --git a/packages/legacy/mgks/package.json b/packages/legacy/mgks/package.json
index 04930f1c..aee96550 100644
--- a/packages/legacy/mgks/package.json
+++ b/packages/legacy/mgks/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Discontinued. Legacy wrapper for docmd. Please use @docmd/core.",
   "bin": {
     "docmd": "bin/docmd.js"
diff --git a/packages/live/package.json b/packages/live/package.json
index bd058088..26972627 100644
--- a/packages/live/package.json
+++ b/packages/live/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/live",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Browser-based editor engine for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/parser/package.json b/packages/parser/package.json
index adf87d51..7bb91bb6 100644
--- a/packages/parser/package.json
+++ b/packages/parser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/parser",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Pure Markdown parsing engine for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/analytics/package.json b/packages/plugins/analytics/package.json
index ae750c47..7668206e 100644
--- a/packages/plugins/analytics/package.json
+++ b/packages/plugins/analytics/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-analytics",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Analytics injection plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/analytics/src/index.ts b/packages/plugins/analytics/src/index.ts
index 1dffdd16..67796205 100644
--- a/packages/plugins/analytics/src/index.ts
+++ b/packages/plugins/analytics/src/index.ts
@@ -21,7 +21,7 @@ import { scriptLiteral } from '@docmd/utils';
 
 export const plugin: PluginDescriptor = {
   name: 'analytics',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['head', 'body']
 };
 
diff --git a/packages/plugins/git/package.json b/packages/plugins/git/package.json
index 110282e9..aae27e4f 100644
--- a/packages/plugins/git/package.json
+++ b/packages/plugins/git/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-git",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Git integration plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/git/src/index.ts b/packages/plugins/git/src/index.ts
index a6e5abbf..0e410b83 100644
--- a/packages/plugins/git/src/index.ts
+++ b/packages/plugins/git/src/index.ts
@@ -290,7 +290,7 @@ async function getGitFileInfo(filePath: string, maxCommits: number = 6): Promise
 
 export const plugin: PluginDescriptor = {
   name: 'git',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['build', 'body', 'assets', 'translations', 'init', 'post-build']
 };
 
diff --git a/packages/plugins/installer/package.json b/packages/plugins/installer/package.json
index 9bb4c69e..d7bb6b3c 100644
--- a/packages/plugins/installer/package.json
+++ b/packages/plugins/installer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-installer",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Installer utility to add and remove plugins for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/llms/package.json b/packages/plugins/llms/package.json
index 6ef399a9..e6dec222 100644
--- a/packages/plugins/llms/package.json
+++ b/packages/plugins/llms/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-llms",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Generate llms.txt context files for AI agents from your docmd site.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/llms/src/index.ts b/packages/plugins/llms/src/index.ts
index a5cdeba3..25271b67 100644
--- a/packages/plugins/llms/src/index.ts
+++ b/packages/plugins/llms/src/index.ts
@@ -19,7 +19,7 @@ import { outputPathToPathname, sanitizeUrl } from '@docmd/api';
 
 export const plugin: PluginDescriptor = {
   name: 'llms',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['post-build']
 };
 
diff --git a/packages/plugins/math/package.json b/packages/plugins/math/package.json
index 96addb73..afd0a9cf 100644
--- a/packages/plugins/math/package.json
+++ b/packages/plugins/math/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-math",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Mathematics (KaTeX/LaTeX) plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/math/src/index.ts b/packages/plugins/math/src/index.ts
index 82dd602c..4ea6d579 100644
--- a/packages/plugins/math/src/index.ts
+++ b/packages/plugins/math/src/index.ts
@@ -18,7 +18,7 @@ import type { PluginDescriptor } from '@docmd/api';
 
 export const plugin: PluginDescriptor = {
   name: 'math',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['markdown', 'assets']
 };
 
diff --git a/packages/plugins/mermaid/package.json b/packages/plugins/mermaid/package.json
index 93d0e44b..2f67eb27 100644
--- a/packages/plugins/mermaid/package.json
+++ b/packages/plugins/mermaid/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-mermaid",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Mermaid diagram support plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/mermaid/src/index.ts b/packages/plugins/mermaid/src/index.ts
index 4f4ac24c..c01e5410 100644
--- a/packages/plugins/mermaid/src/index.ts
+++ b/packages/plugins/mermaid/src/index.ts
@@ -21,7 +21,7 @@ const __dirname = path.dirname(__filename);
 
 export const plugin: PluginDescriptor = {
   name: 'mermaid',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['markdown', 'assets']
 };
 
diff --git a/packages/plugins/okf/package.json b/packages/plugins/okf/package.json
index 48bcca85..64640ba9 100644
--- a/packages/plugins/okf/package.json
+++ b/packages/plugins/okf/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-okf",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Generate an Open Knowledge Format (OKF) bundle from your docmd site for AI agent consumption.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/okf/src/index.ts b/packages/plugins/okf/src/index.ts
index 76cb1cde..e9c6f9fa 100644
--- a/packages/plugins/okf/src/index.ts
+++ b/packages/plugins/okf/src/index.ts
@@ -45,7 +45,7 @@ import { GRAPH_CSS, GRAPH_JS, graphHtml } from './graph-assets.js';
 
 export const plugin: PluginDescriptor = {
   name: 'okf',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['post-build']
 };
 
@@ -223,7 +223,7 @@ export async function onPostBuild({ config, pages, outputDir, log }: any) {
   for (const c of concepts) byType[c.type] = (byType[c.type] || 0) + 1;
 
   const manifest = {
-    okf_version: '0.8.11',
+    okf_version: '0.8.12',
     bundle: {
       name: bundleName, title: config.title || bundleName, description: config.description || '',
       url: config.url || '', generated_by: '@docmd/plugin-okf', generated_at: new Date().toISOString(),
diff --git a/packages/plugins/openapi/package.json b/packages/plugins/openapi/package.json
index 784022a6..260c2f95 100644
--- a/packages/plugins/openapi/package.json
+++ b/packages/plugins/openapi/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-openapi",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "OpenAPI documentation generator plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/openapi/src/index.ts b/packages/plugins/openapi/src/index.ts
index 4aaab8ce..ec4be3f1 100644
--- a/packages/plugins/openapi/src/index.ts
+++ b/packages/plugins/openapi/src/index.ts
@@ -24,7 +24,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export const plugin: PluginDescriptor = {
   name: 'openapi',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['markdown', 'assets']
 };
 
diff --git a/packages/plugins/pwa/package.json b/packages/plugins/pwa/package.json
index fd3f084a..e8fb16a0 100644
--- a/packages/plugins/pwa/package.json
+++ b/packages/plugins/pwa/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-pwa",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Progressive Web App (PWA) plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/pwa/src/index.ts b/packages/plugins/pwa/src/index.ts
index a016e678..a684614a 100644
--- a/packages/plugins/pwa/src/index.ts
+++ b/packages/plugins/pwa/src/index.ts
@@ -19,7 +19,7 @@ import { attrEsc } from '@docmd/utils';
 
 export const plugin: PluginDescriptor = {
   name: 'pwa',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['post-build', 'head', 'body']
 };
 
diff --git a/packages/plugins/search/package.json b/packages/plugins/search/package.json
index 8a0dc3c1..30f22780 100644
--- a/packages/plugins/search/package.json
+++ b/packages/plugins/search/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-search",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Offline full-text search for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/search/src/index.ts b/packages/plugins/search/src/index.ts
index 4a5c1e6a..03db95c1 100644
--- a/packages/plugins/search/src/index.ts
+++ b/packages/plugins/search/src/index.ts
@@ -28,7 +28,7 @@ const require = createRequire(import.meta.url);
 
 export const plugin: PluginDescriptor = {
   name: 'search',
-  version: '0.8.11',
+  version: '0.8.12',
   // `init` lets onConfigResolved run at config-parse time — that's where we
   // compute the single `searchConfig` object. The build pipeline reads
   // it from `config._searchConfig` everywhere else, so there's exactly
diff --git a/packages/plugins/seo/package.json b/packages/plugins/seo/package.json
index 9d87ed7e..748d142f 100644
--- a/packages/plugins/seo/package.json
+++ b/packages/plugins/seo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-seo",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "SEO meta tag generator for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/seo/src/index.ts b/packages/plugins/seo/src/index.ts
index 1d43c081..72f46a94 100644
--- a/packages/plugins/seo/src/index.ts
+++ b/packages/plugins/seo/src/index.ts
@@ -21,7 +21,7 @@ import { attrEsc } from '@docmd/utils';
 
 export const plugin: PluginDescriptor = {
   name: 'seo',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['head', 'post-build']
 };
 
diff --git a/packages/plugins/sitemap/package.json b/packages/plugins/sitemap/package.json
index aeb1e431..d0253580 100644
--- a/packages/plugins/sitemap/package.json
+++ b/packages/plugins/sitemap/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-sitemap",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Sitemap generator plugin for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/plugins/sitemap/src/index.ts b/packages/plugins/sitemap/src/index.ts
index e1444ebe..49b0f370 100644
--- a/packages/plugins/sitemap/src/index.ts
+++ b/packages/plugins/sitemap/src/index.ts
@@ -19,7 +19,7 @@ import { outputPathToPathname, sanitizeUrl } from '@docmd/api';
 
 export const plugin: PluginDescriptor = {
   name: 'sitemap',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['post-build']
 };
 
diff --git a/packages/plugins/threads/package.json b/packages/plugins/threads/package.json
index 690a3425..687fc45e 100644
--- a/packages/plugins/threads/package.json
+++ b/packages/plugins/threads/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/plugin-threads",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "type": "module",
   "description": "Inline discussion threads for docmd.",
   "main": "dist/index.js",
diff --git a/packages/plugins/threads/src/index.ts b/packages/plugins/threads/src/index.ts
index 1bd87aff..5bc1cbc0 100644
--- a/packages/plugins/threads/src/index.ts
+++ b/packages/plugins/threads/src/index.ts
@@ -9,7 +9,7 @@ import type { PluginDescriptor } from '@docmd/api';
 
 export const plugin: PluginDescriptor = {
   name: 'threads',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['markdown', 'body', 'assets', 'actions', 'translations']
 };
 
diff --git a/packages/templates/summer/package.json b/packages/templates/summer/package.json
index aa00c3c1..980e281d 100644
--- a/packages/templates/summer/package.json
+++ b/packages/templates/summer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/template-summer",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Summer template for docmd. A bright, hopeful, summer-feel layout with a top search bar and halo accents.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/templates/summer/src/index.ts b/packages/templates/summer/src/index.ts
index 6b5a7bd0..af92ab28 100644
--- a/packages/templates/summer/src/index.ts
+++ b/packages/templates/summer/src/index.ts
@@ -42,7 +42,7 @@ const pathOf = (relPath: string): string => fileURLToPath(urlOf(relPath));
 
 export const plugin: PluginDescriptor = {
   name: 'template-summer',
-  version: '0.8.11',
+  version: '0.8.12',
   capabilities: ['template'],
 };
 
diff --git a/packages/themes/package.json b/packages/themes/package.json
index 3e50fdf0..98669b49 100644
--- a/packages/themes/package.json
+++ b/packages/themes/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/themes",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Official themes for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/tui/package.json b/packages/tui/package.json
index 22bde932..872c031c 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/tui",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Terminal User Interface (TUI) design system for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 3f5db5bb..73153103 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/ui",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Base UI templates and assets for docmd.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 5eccef74..52adb563 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@docmd/utils",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "description": "Zero-dependency shared utilities for docmd core.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b0558157..8df8ce8d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -19,7 +19,7 @@ importers:
         version: 4.1.2
       docmd-search:
         specifier: ^0.1.0
-        version: 0.1.0(@docmd/engine-js@0.8.10)(@docmd/engine-rust@0.8.10)(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
+        version: 0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
       esbuild:
         specifier: ^0.28.1
         version: 0.28.1
@@ -112,9 +112,6 @@ importers:
       '@docmd/plugin-openapi':
         specifier: workspace:*
         version: link:../plugins/openapi
-      '@docmd/plugin-pwa':
-        specifier: workspace:*
-        version: link:../plugins/pwa
       '@docmd/plugin-search':
         specifier: workspace:*
         version: link:../plugins/search
@@ -376,7 +373,7 @@ importers:
     dependencies:
       docmd-search:
         specifier: '>=0.1.0'
-        version: 0.1.0(@docmd/engine-js@0.8.10)(@docmd/engine-rust@0.8.10)(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
+        version: 0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
       markdown-it:
         specifier: ^14.3.0
         version: 14.3.0
@@ -510,14 +507,6 @@ packages:
     resolution: {integrity: sha512-WyOx8cJQ+FQus4Mm4uPIZA64gbk3Wxh0so5Lcii0aJifqwoVOlfFtorjLE0Hen4OYyHZMXDWqMmaQemBhgxFRQ==}
     engines: {node: '>=14'}
 
-  '@docmd/engine-js@0.8.10':
-    resolution: {integrity: sha512-h440qMbZCPdZZlV8REFeJLKwx170t66h5uVh8jpoxAHQ5xRAwhuifgUpj8szBq+WnzHIGT1ZHqzefaqucdV+sg==}
-    engines: {node: '>=18'}
-
-  '@docmd/engine-rust@0.8.10':
-    resolution: {integrity: sha512-OpwzQ9roiAxAQH2slomez4KS2NeeIa8ldPp6eDfSOx3ZOLmxa191KfMOIlEkXbgcXUiB70I3OqcY4jdMzzEgKQ==}
-    engines: {node: '>=18'}
-
   '@emnapi/runtime@1.11.2':
     resolution: {integrity: sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==}
 
@@ -1740,12 +1729,6 @@ snapshots:
 
   '@ctrl/tinycolor@4.1.0': {}
 
-  '@docmd/engine-js@0.8.10':
-    optional: true
-
-  '@docmd/engine-rust@0.8.10':
-    optional: true
-
   '@emnapi/runtime@1.11.2':
     dependencies:
       tslib: 2.8.1
@@ -2272,10 +2255,8 @@ snapshots:
 
   detect-node@2.1.0: {}
 
-  docmd-search@0.1.0(@docmd/engine-js@0.8.10)(@docmd/engine-rust@0.8.10)(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0):
+  docmd-search@0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0):
     optionalDependencies:
-      '@docmd/engine-js': 0.8.10
-      '@docmd/engine-rust': 0.8.10
       '@huggingface/transformers': 4.2.0
       onnxruntime-node: 1.27.0
 
diff --git a/tests/cli-contracts/runtime-deps.test.js b/tests/cli-contracts/runtime-deps.test.js
new file mode 100644
index 00000000..104ae8d0
--- /dev/null
+++ b/tests/cli-contracts/runtime-deps.test.js
@@ -0,0 +1,236 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Runtime-deps regression tests — covers the shared auto-install pipeline
+ * used by hooks.ts (plugin / template loader) and engine.ts (engine
+ * loader). The 0.9.0 refactor extracted this logic from hooks.ts into
+ * `packages/api/src/runtime-deps.ts` to:
+ *
+ *   - Replace `execSync(\`pnpm add ${pkg}\`)` (CWE-78 surface) with a
+ *     strict regex + `spawn(... { shell: false })` arg-array install.
+ *   - Apply a registry re-check as defence-in-depth so the auto-install
+ *     path can never silently turn into a generic npm loader.
+ *   - Single-source the TUI status reporter so dev-server rebuilds
+ *     can't spam "[ WAIT ] / [ DONE ]" line pairs for packages that are
+ *     already on disk.
+ *
+ * Tests touch the public surface only — everything goes through the
+ * @docmd/api index, so plugins and the core package agree on the same
+ * behaviour.
+ *
+ * Run: `node tests/runner.js --only=runtime-deps`
+ * --------------------------------------------------------------------
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { runTestFile } from '../shared.js';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    ❌ ${message}`);
+  } else {
+    passed++;
+    console.log(`    ✅ ${message}`);
+  }
+}
+
+const API_DIST = path.resolve(
+  import.meta.dirname,
+  '..',
+  '..',
+  'packages',
+  'api',
+  'dist',
+  'index.js',
+);
+
+export const test = runTestFile({
+  name: 'Runtime-deps (shared auto-install pipeline)',
+  emoji: '🧰',
+  run: async () => {
+    // -----------------------------------------------------------------
+    // 1. Public surface — symbols we export from @docmd/api must exist
+    // -----------------------------------------------------------------
+    {
+      const source = fs.readFileSync(API_DIST, 'utf8');
+      assert(
+        /loadRuntimeRegistry/.test(source),
+        'RD-1: @docmd/api re-exports loadRuntimeRegistry'
+      );
+      assert(
+        /isValidRuntimeDepName/.test(source),
+        'RD-2: @docmd/api re-exports isValidRuntimeDepName'
+      );
+      assert(
+        /installRuntimeDep/.test(source),
+        'RD-3: @docmd/api re-exports installRuntimeDep'
+      );
+      assert(
+        /tryLoadAfterInstall/.test(source),
+        'RD-4: @docmd/api re-exports tryLoadAfterInstall'
+      );
+      assert(
+        /detectPackageManager/.test(source),
+        'RD-5: @docmd/api re-exports detectPackageManager'
+      );
+      assert(
+        /getDocmdVersion/.test(source),
+        'RD-6: @docmd/api re-exports getDocmdVersion'
+      );
+      assert(
+        /getBuildStatusReporter/.test(source),
+        'RD-7: @docmd/api re-exports getBuildStatusReporter'
+      );
+    }
+
+    // -----------------------------------------------------------------
+    // 2. Functional behaviour — the regex validator is the FIRST line
+    // of defence against shell-injection. Anything outside the canonical
+    // @docmd/<kind>-<short> shape must be rejected.
+    // -----------------------------------------------------------------
+    {
+      const api = await import(API_DIST);
+      const { isValidRuntimeDepName, shortRuntimeDepKey, getBuildStatusReporter } = api;
+
+      // Positive: official names.
+      assert(isValidRuntimeDepName('@docmd/plugin-search') === true, 'RD-POS-1: @docmd/plugin-search is valid');
+      assert(isValidRuntimeDepName('@docmd/template-summer') === true, 'RD-POS-2: @docmd/template-summer is valid');
+      assert(isValidRuntimeDepName('@docmd/engine-js') === true, 'RD-POS-3: @docmd/engine-js is valid');
+      assert(isValidRuntimeDepName('@docmd/engine-rust') === true, 'RD-POS-4: @docmd/engine-rust is valid');
+      assert(isValidRuntimeDepName('@docmd/plugin-math-katex') === true, 'RD-POS-5: hyphenated short names are valid');
+      assert(isValidRuntimeDepName('@docmd/plugin-foo-1.0') === true, 'RD-POS-6: dotted version suffix is valid');
+
+      // Negative: shell-injection / shape violations.
+      assert(isValidRuntimeDepName('@docmd/plugin-foo; rm -rf /') === false, 'RD-NEG-1: shell-metacharacters rejected');
+      assert(isValidRuntimeDepName('@docmd/plugin-foo && curl evil') === false, 'RD-NEG-2: command-chain rejected');
+      assert(isValidRuntimeDepName('@docmd/plugin-foo`whoami`') === false, 'RD-NEG-3: backticks rejected');
+      assert(isValidRuntimeDepName('@docmd/plugin-foo$(whoami)') === false, 'RD-NEG-4: $() expansion rejected');
+      assert(isValidRuntimeDepName('docmd/plugin-search') === false, 'RD-NEG-5: missing scope rejected');
+      assert(isValidRuntimeDepName('@docmd/plugin-') === false, 'RD-NEG-6: empty short name rejected');
+      assert(isValidRuntimeDepName('@docmd/random-search') === false, 'RD-NEG-7: unrecognised kind rejected');
+      assert(isValidRuntimeDepName('@docmd/PLUGIN-search') === false, 'RD-NEG-8: uppercase rejected');
+      assert(isValidRuntimeDepName('@evil/plugin-search') === false, 'RD-NEG-9: non-@docmd scope rejected');
+      assert(isValidRuntimeDepName('') === false, 'RD-NEG-10: empty string rejected');
+      assert(isValidRuntimeDepName(null) === false, 'RD-NEG-11: null rejected');
+      assert(isValidRuntimeDepName(undefined) === false, 'RD-NEG-12: undefined rejected');
+      assert(isValidRuntimeDepName(123) === false, 'RD-NEG-13: non-string rejected');
+
+      // shortRuntimeDepKey must agree on the same shape AND return null for
+      // unknown inputs (so call sites can defensively fall through).
+      assert(shortRuntimeDepKey('@docmd/plugin-search') === 'search', 'RD-SK-1: plugin-search short name');
+      assert(shortRuntimeDepKey('@docmd/template-summer') === 'summer', 'RD-SK-2: template-summer short name');
+      assert(shortRuntimeDepKey('@docmd/engine-rust') === 'rust', 'RD-SK-3: engine-rust short name');
+      assert(shortRuntimeDepKey('@docmd/plugin-math-katex') === 'math-katex', 'RD-SK-4: hyphenated short name');
+      assert(shortRuntimeDepKey('@docmd/plugin-foo; rm -rf /') === null, 'RD-SK-5: rejected name → null');
+      assert(shortRuntimeDepKey('@evil/plugin-search') === null, 'RD-SK-6: rejected scope → null');
+
+      // Idempotent TUI reporter: second `begin` on the same short name
+      // must be a no-op (the same reporter instance owns one build).
+      const reporter = getBuildStatusReporter();
+      reporter.begin('fake-test-plugin');
+      reporter.begin('fake-test-plugin');
+      reporter.finish('fake-test-plugin', 'DONE');
+      // No equality assertion possible from here (output went to TUI);
+      // we only need the function to not throw and to be callable
+      // multiple times. Mark a smoke pass.
+      assert(true, 'RD-IDEMPOTENT: getBuildStatusReporter() can be reused across begin/finish pairs');
+    }
+
+    // -----------------------------------------------------------------
+    // 3. Registry loader — first call must not throw, second call must
+    // return the cached object (idempotent).
+    // -----------------------------------------------------------------
+    {
+      const api = await import(API_DIST);
+      const { loadRuntimeRegistry } = api;
+      const r1 = loadRuntimeRegistry();
+      const r2 = loadRuntimeRegistry();
+      assert(r1 && typeof r1 === 'object', 'RD-REG-1: loadRuntimeRegistry returns an object');
+      assert(r1 === r2, 'RD-REG-2: loadRuntimeRegistry caches (identity check)');
+      // The generated registry at packages/api/registry/.../plugins.generated.json
+      // ships with at least these two plugins during this session. Use
+      // known-present entries so the test does not break when the
+      // catalog grows.
+      assert(r1['search'], 'RD-REG-3: @docmd/plugin-search present in registry');
+      assert(r1['summer'], 'RD-REG-4: @docmd/template-summer present in registry');
+      assert(r1['js'] && r1['js'].package === '@docmd/engine-js', 'RD-REG-5: js entry points at @docmd/engine-js');
+      assert(r1['rust'] && r1['rust'].package === '@docmd/engine-rust', 'RD-REG-6: rust entry points at @docmd/engine-rust');
+    }
+
+    // -----------------------------------------------------------------
+    // 4. installRuntimeDep must refuse non-runtime names AND names not
+    // in the registry. We can't actually run an install in CI without
+    // mutating the test-runner's working dir, so we assert the early
+    // rejections (which are the security-critical path) and ensure the
+    // happy-path call doesn't immediately throw synchronously.
+    // -----------------------------------------------------------------
+    {
+      const api = await import(API_DIST);
+      const { installRuntimeDep } = api;
+
+      // First defence: regex rejects. Function returns Promise<boolean>;
+      // resolves to false without spawning anything.
+      const evil = await installRuntimeDep('@docmd/plugin-foo; rm -rf /');
+      assert(evil === false, 'RD-INSTALL-1: installRuntimeDep refuses shell-injection name');
+
+      const badScope = await installRuntimeDep('@evil/plugin-search');
+      assert(badScope === false, 'RD-INSTALL-2: installRuntimeDep refuses non-@docmd scope');
+
+      const missing = await installRuntimeDep('@docmd/plugin-not-in-registry');
+      assert(missing === false, 'RD-INSTALL-3: installRuntimeDep refuses registry miss');
+
+      // Happy-path: returns a boolean — never throws synchronously for
+      // valid inputs (a runtime exception in spawn would be surfaced
+      // via the returned promise rather than killing the loader).
+      const promise = installRuntimeDep('@docmd/plugin-search');
+      assert(typeof promise?.then === 'function', 'RD-INSTALL-4: installRuntimeDep returns a Promise for valid name');
+      // Drain without asserting outcome — under CI there may be no
+      // network. We only care about the call surface.
+      promise.then((ok) => assert(typeof ok === 'boolean', 'RD-INSTALL-5: installRuntimeDep resolves to boolean')).catch(() => {});
+    }
+
+    // -----------------------------------------------------------------
+    // 5. hooks.ts + engine.ts no longer contain the old inline
+    // `execSync(`${pm} add ${pkg}`)` shell-string. This is a static
+    //    source check — proves the CWE-78 path is gone from BOTH files.
+    // -----------------------------------------------------------------
+    {
+      const hooksSrc = fs.readFileSync(
+        path.resolve(import.meta.dirname, '..', '..', 'packages', 'api', 'src', 'hooks.ts'),
+        'utf8',
+      );
+      const engineSrc = fs.readFileSync(
+        path.resolve(import.meta.dirname, '..', '..', 'packages', 'api', 'src', 'engine.ts'),
+        'utf8',
+      );
+      const runtimeSrc = fs.readFileSync(
+        path.resolve(import.meta.dirname, '..', '..', 'packages', 'api', 'src', 'runtime-deps.ts'),
+        'utf8',
+      );
+
+      assert(!/execSync\s*\(\s*[`'"][\s\S]*\$\{/.test(hooksSrc), 'RD-CWE-1: hooks.ts has no shell-string execSync');
+      assert(!/execSync\s*\(\s*[`'"][\s\S]*\$\{/.test(engineSrc), 'RD-CWE-2: engine.ts has no shell-string execSync');
+      assert(/import\s*\{[^}]*installRuntimeDep[^}]*\}\s*from\s*['"]\.\/runtime-deps\.js['"]/.test(hooksSrc), 'RD-IMPORT-1: hooks.ts imports installRuntimeDep from runtime-deps');
+      assert(/import\s*\{[^}]*installRuntimeDep[^}]*\}\s*from\s*['"]\.\/runtime-deps\.js['"]/.test(engineSrc), 'RD-IMPORT-2: engine.ts imports installRuntimeDep from runtime-deps');
+      assert(/spawn\(/.test(runtimeSrc), 'RD-SPAWN: runtime-deps.ts uses spawn, not shell');
+      assert(/process\.platform === ['"]win32['"]/.test(runtimeSrc), 'RD-SHELL: runtime-deps gates shell on Windows (npm is .cmd there)');
+      assert(/shell:\s*useShell/.test(runtimeSrc), 'RD-SHELL-VAR: shell is driven by useShell variable');
+      assert(!/execSync\s*\(\s*[`'"][\s\S]*\$\{/.test(hooksSrc), 'RD-CWE-1b: no template-string execSync remains in hooks.ts');
+    }
+  },
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return failures; },
+};
diff --git a/tests/runner.js b/tests/runner.js
index 0f8cef87..73c7a5c0 100644
--- a/tests/runner.js
+++ b/tests/runner.js
@@ -150,6 +150,11 @@ addInProcess(
   'Asset base-URL + engine-key (URL-1, URL-2 — <base> + KNOWN_KEYS)',
   await import('./cli-contracts/asset-base-url.test.js')
 );
+addInProcess(
+  'runtime-deps',
+  'Runtime-deps shared auto-install pipeline (RD-1..RD-CWE, CWE-78 fix)',
+  await import('./cli-contracts/runtime-deps.test.js')
+);
 
 // --- Section 2: Container parser (Phase 2 PR 1+2+3) ----------------------
 addExternal(