catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/mcp_v2/knowledge-base.json

@@ -474,9 +474,9 @@
     {
         "section": "config_structure",
         "title": "Full config/config.json Schema",
-        "content": "config/config.json contains all runtime config. Required keys (enforced by validator.js at startup \u2014 missing any = server crash): NODE_SERVER_HOSTNAME (string), NODE_SERVER_PORT (number), WEBPACK_DEV_SERVER_HOSTNAME (string), WEBPACK_DEV_SERVER_PORT (number), BUILD_OUTPUT_PATH (string, e.g. 'build'), PUBLIC_STATIC_ASSET_PATH (string, e.g. '/assets/'), PUBLIC_STATIC_ASSET_URL (string, CDN base URL), CLIENT_ENV_VARIABLES (array of env var names to expose to client bundle), ANALYZE_BUNDLE (boolean). Optional top-level keys: API_URL (string, app convention not enforced), WEBVIEW_CONFIG (object, required for native builds \u2014 contains splashScreen, appInfo, android, ios, etc.). Common mistake: CLIENT_ENV_KEYS is WRONG \u2014 the actual key is CLIENT_ENV_VARIABLES. Common mistake: splashScreen is NOT a top-level key \u2014 it lives inside WEBVIEW_CONFIG. Example: { NODE_SERVER_HOSTNAME: 'localhost', NODE_SERVER_PORT: 3000, WEBPACK_DEV_SERVER_HOSTNAME: 'localhost', WEBPACK_DEV_SERVER_PORT: 3001, BUILD_OUTPUT_PATH: 'build', PUBLIC_STATIC_ASSET_PATH: '/assets/', PUBLIC_STATIC_ASSET_URL: 'https://cdn.example.com', CLIENT_ENV_VARIABLES: ['API_URL'], ANALYZE_BUNDLE: false }",
+        "content": "config/config.json contains all runtime config. Required keys (enforced by validator.js at startup \u2014 missing any = server crash): NODE_SERVER_HOSTNAME (string), NODE_SERVER_PORT (number), BUILD_OUTPUT_PATH (string, e.g. 'build'), PUBLIC_STATIC_ASSET_PATH (string, e.g. '/assets/'), PUBLIC_STATIC_ASSET_URL (string, CDN base URL), CLIENT_ENV_VARIABLES (array of env var names to expose to client bundle). WEBPACK_DEV_SERVER_HOSTNAME, WEBPACK_DEV_SERVER_PORT, and ANALYZE_BUNDLE are no longer required or read \u2014 they are ignored if present. Optional top-level keys: API_URL (string, app convention not enforced), WEBVIEW_CONFIG (object, required for native builds \u2014 contains splashScreen, appInfo, android, ios, etc.). Common mistake: CLIENT_ENV_KEYS is WRONG \u2014 the actual key is CLIENT_ENV_VARIABLES. Common mistake: splashScreen is NOT a top-level key \u2014 it lives inside WEBVIEW_CONFIG. Example: { NODE_SERVER_HOSTNAME: 'localhost', NODE_SERVER_PORT: 3000, BUILD_OUTPUT_PATH: 'build', PUBLIC_STATIC_ASSET_PATH: '/assets/', PUBLIC_STATIC_ASSET_URL: 'https://cdn.example.com', CLIENT_ENV_VARIABLES: ['API_URL'] }",
         "layer": "Config",
-        "source": "extracted:src/scripts/validator.js",
+        "source": "extracted:src/server/utils/validator.ts",
         "tags": ["config", "schema", "required-fields"]
     },
     {
@@ -570,10 +570,10 @@
     {
         "section": "server_structure",
         "title": "Required Server Files",
-        "content": "Catalyst requires 3 specific files in server/: server/index.js (lifecycle hooks), server/server.js (Express middleware), server/document.js (HTML template). These are NOT optional. Missing any one = server startup fails. Any repo using custom Express, Next.js, CRA, or Vite must rebuild all 3 from scratch.",
+        "content": "Catalyst requires 3 specific files in server/: server/index.js (lifecycle hooks), server/server.js (Express middleware), server/document.js (HTML template). These are NOT optional. Missing any one = server startup fails. Any repo using custom Express, Next.js, CRA, or Vite must rebuild all 3 from scratch. From 1.0.0, a file that exists but lacks a required export is reported once at startup, naming the file and the export; the server still boots (log-and-continue) and the affected feature fails instead.",
         "layer": "Build",
         "source": "static",
-        "tags": ["server", "required-files", "structure"]
+        "tags": ["server", "required-files", "structure", "1.0.0"]
     },
     {
         "section": "server_structure",
@@ -610,7 +610,7 @@
     {
         "section": "native_hooks",
         "title": "Native Hooks \u2014 Overview & Common Interface",
-        "content": "All catalyst-core hooks share a standardized base interface: { data, loading, progress, error, isWeb, isNative, execute, clear, clearError }. isNative is true when running inside the native shell (Android/iOS WebView). isWeb is true on browser. All return SSR-safe stubs when window is undefined. Import from catalyst-core/hooks.\n\nWEB FALLBACK SYSTEM: Hooks that implement browser fallbacks additionally expose: { webFallbackActive: boolean, webFallbackDisabled: boolean, setWebFallback: (enabled: boolean) => void }. webFallbackActive=true means the hook is currently running its browser fallback (not native bridge). setWebFallback(false) disables the built-in fallback at runtime \u2014 React re-runs effects and cleans up side effects automatically (e.g. stops MediaStream, removes event listeners). webFallbackDisabled=true means the hook returned an inert no-op shape (all actions are no-ops, data/error/loading are null/false) \u2014 consumer must render its own UI.\n\nDYNAMIC PROP SYNC: The webFallback prop syncs dynamically after mount in all hooks (both useBaseHook consumers and thin-state hooks) via useEffect. Passing a new webFallback prop value re-evaluates webFallbackActive without remounting the component.\n\nRULES OF HOOKS: All hooks (useState, useRef, useCallback, useEffect) are always called unconditionally at top level, regardless of webFallbackActive/webFallbackDisabled. Branching only happens in return statements.\n\nHooks with web fallbacks: useCamera, useFilePicker, useHapticFeedback, useVideoStream, useDataProtection, useCameraPermission, useNetworkStatus, useSafeArea, useDeviceInfo.",
+        "content": "catalyst-core hooks fall into TWO CATEGORIES.\n\nSINGLE-ACTION HOOKS wrap exactly one native operation and share a standardized base interface: { data, loading, progress, error, isWeb, isNative, execute, clear, clearError }. execute takes the operation's own arguments — it NEVER takes an operation-name string. Each also exposes a domain alias for execute: useCamera->takePhoto, useFilePicker->pickFile, useIntent->openFile, useGoogleSignIn->signIn, useHapticFeedback->trigger/triggerHaptic, useCameraPermission->request.\n\nMULTI-ACTION HOOKS wrap several distinct operations, so their NAMED FUNCTIONS ARE THE API and they have NO execute: useNotification (scheduleLocal, cancelLocal, registerForPush, updateBadge, subscribeToTopic, unsubscribeFromTopic, getSubscribedTopics, requestPermission), useVideoStream (start, stop, sendCommand, flip), useDataProtection (setScreenSecure, clearWebData), useNativeTransition (navigate, cancelTransition). EXCEPTION: useNotification carries execute as a frozen-but-discouraged alias of scheduleLocal — do NOT copy that pattern for other multi-action hooks.\n\nREAD-ONLY HOOKS report ambient state with no action functions: useNetworkStatus, useDeviceInfo, useSafeArea.\n\nisNative is true when running inside the native shell (Android/iOS WebView). isWeb is true on browser. All return SSR-safe stubs when window is undefined. Import from catalyst-core/hooks.\n\nWEB FALLBACK SYSTEM: Hooks that implement browser fallbacks additionally expose: { webFallbackActive: boolean, webFallbackDisabled: boolean, setWebFallback: (enabled: boolean) => void }. webFallbackActive=true means the hook is currently running its browser fallback (not native bridge). setWebFallback(false) disables the built-in fallback at runtime \u2014 React re-runs effects and cleans up side effects automatically (e.g. stops MediaStream, removes event listeners). webFallbackDisabled=true means the hook returned an inert no-op shape (all actions are no-ops, data/error/loading are null/false) \u2014 consumer must render its own UI.\n\nDYNAMIC PROP SYNC: The webFallback prop syncs dynamically after mount in all hooks (both useBaseHook consumers and thin-state hooks) via useEffect. Passing a new webFallback prop value re-evaluates webFallbackActive without remounting the component.\n\nRULES OF HOOKS: All hooks (useState, useRef, useCallback, useEffect) are always called unconditionally at top level, regardless of webFallbackActive/webFallbackDisabled. Branching only happens in return statements.\n\nHooks with web fallbacks: useCamera, useFilePicker, useHapticFeedback, useVideoStream, useDataProtection, useCameraPermission, useNetworkStatus, useSafeArea, useDeviceInfo.",
         "layer": "Runtime",
         "source": "static",
         "tags": [
@@ -673,7 +673,7 @@
     {
         "section": "native_hooks",
         "title": "useNotification \u2014 return shape",
-        "content": "useNotification() returns: { data, loading, progress, error, execute (=scheduleLocal), clear, clearError, isNative, isWeb, permissionStatus, pushToken, badges, lastNotification, subscribedTopics, scheduleLocal(config), schedule (alias for scheduleLocal), cancelLocal(id), registerForPush(), updateBadge(count), subscribeToTopic(topic), unsubscribeFromTopic(topic), getSubscribedTopics(), requestPermission() }. requestPermission() triggers native permission prompt (wraps requestNotificationPermission(), errors routed through base.handleNativeError). schedule is an alias for scheduleLocal. Requires WEBVIEW_CONFIG.notifications.enabled=true + Firebase files.",
+        "content": "useNotification() is a MULTI-ACTION hook — its named functions are the API. Returns: { data, loading, progress, error, clear, clearError, isNative, isWeb, permissionStatus, pushToken, badges, lastNotification, subscribedTopics, scheduleLocal(config), cancelLocal(id), registerForPush(), updateBadge(count), subscribeToTopic(topic), unsubscribeFromTopic(topic), getSubscribedTopics(), requestPermission() }. requestPermission() triggers native permission prompt (wraps requestNotificationPermission(), errors routed through base.handleNativeError).\n\nFROZEN-BUT-DISCOURAGED ALIASES: execute and schedule both alias scheduleLocal, kept for backward compatibility only. They are the sole exception among multi-action hooks and must NOT be treated as the pattern to copy — other multi-action hooks have no execute. Both aliases are removed at 2.0; write new code against scheduleLocal. Requires WEBVIEW_CONFIG.notifications.enabled=true + Firebase files.",
         "layer": "Runtime",
         "source": "static",
         "tags": ["native-hooks", "useNotification", "return-shape"]
@@ -729,7 +729,7 @@
         "title": "moduleAliases \u2014 Required Path Aliases in package.json",
         "content": "package.json must have a _moduleAliases key (used by module-alias package) with these 6 required entries (enforced by validator.js \u2014 missing any = server crash): @api -> api/ (WARNING: common bug \u2014 @api accidentally set to src/static/css in legacy repos, causes all API imports to break silently), @containers -> src/js/containers, @server -> server, @config -> config, @css -> src/static/css, @routes -> src/js/routes/. Additional aliases (@store, @utils, @components, etc.) are optional but recommended. Dollar-prefix aliases (, , , , ) are server-side only \u2014 do not import in client code. Restriction: alias names containing catalyst are reserved. Migration check: always verify @api points to the actual API module, not a static asset path.",
         "layer": "Config",
-        "source": "extracted:src/scripts/validator.js",
+        "source": "extracted:src/server/utils/validator.ts",
         "tags": ["module-aliases", "package-json", "required", "config"]
     },
     {
@@ -1072,7 +1072,7 @@
     {
         "section": "native_hooks",
         "title": "Native Hooks \u2014 Full List and Standard Interface",
-        "content": "All hooks live in src/native/bridge/hooks/ (one file per domain). hooks.js is a 2-line re-export shim for backwards compat.\n\nSTANDARD BASE INTERFACE (useBaseHook consumers):\n{ data, loading, progress, error, isWeb, isNative, execute, clear, clearError,\n  webFallbackActive, webFallbackDisabled, setWebFallback }\n\nprogress shape: { state, percentage, message, phase, transport, bytesLoaded, bytesTotal }\n\nENVIRONMENT DETECTION (useBaseHook):\nisNative = window.WebBridge && (window.NativeBridge || window.webkit?.messageHandlers?.NativeBridge)\nisWeb = !isNative\n\nWEB FALLBACK SYSTEM:\n- Hooks that support a browser fallback declare hasWebFallback: true in useBaseHook options.\n- webFallbackActive defaults to true on web when a fallback exists (unless webFallback prop === false).\n- webFallback prop syncs dynamically after mount \u2014 all hooks (useBaseHook consumers and thin-state hooks) update webFallbackActive via a useEffect that watches the prop.\n- setWebFallback(false) disables fallback at runtime \u2014 React re-runs effects + cleanups (e.g. stops MediaStream, removes event listeners).\n- When disabled: webFallbackDisabled=true, all action methods are no-ops, data/error/loading are null/false.\n- Thin-state hooks (useNetworkStatus, useSafeArea, useDeviceInfo, useCameraPermission) manage webFallback locally and expose isNative, isWeb, webFallbackActive, webFallbackDisabled, setWebFallback \u2014 same surface as useBaseHook consumers.\n- Rules of Hooks: all hooks are always called unconditionally at top level \u2014 early returns and conditional branches only in return statements, never around hook calls.\n\nFULL HOOK LIST:\nWith web fallback:\n- useCamera \u2014 capture photo. Web: <input type=file capture=environment>.\n- useFilePicker \u2014 pick file. Web: <input type=file>.\n- useHapticFeedback \u2014 haptic/vibration. Web: navigator.vibrate.\n- useVideoStream \u2014 live camera stream + sendCommand (zoom/torch/fps). Web: getUserMedia (requires secure context) with track.applyConstraints. Stream auto-stopped on mode change or unmount.\n- useDataProtection \u2014 setScreenSecure + clearWebData. Web: overlay div on visibilitychange + localStorage/sessionStorage/cookie/IndexedDB clear.\n- useCameraPermission \u2014 camera permission state + request(). Web: navigator.permissions API (query) + getUserMedia side-effect for request().\n- useNetworkStatus \u2014 online/type. Web: navigator.onLine (defaults true if not boolean) + online/offline events (live updates).\n- useSafeArea \u2014 inset pixels. Web: CSS env() vars.\n- useDeviceInfo \u2014 device metadata. Web: navigator/screen APIs.\n\nNo web fallback (native-only or scoped out):\n- useNotification \u2014 push notifications. Web: scoped out (Service Worker required, unreliable in WebView).\n- useNotificationPermission \u2014 notification permission.\n- useGoogleSignIn \u2014 Google sign-in via native.\n- useIntent \u2014 open file with external app.",
+        "content": "All hooks live in src/native/bridge/hooks/ (one file per domain). hooks.js is a 2-line re-export shim for backwards compat.\n\nTWO CATEGORIES:\n- SINGLE-ACTION hooks wrap one operation and expose it as execute (plus a domain alias). execute takes the operation's arguments, never an operation-name string. These are: useCamera (takePhoto), useFilePicker (pickFile), useIntent (openFile), useGoogleSignIn (signIn), useHapticFeedback (trigger/triggerHaptic), useCameraPermission (request).\n- MULTI-ACTION hooks wrap several operations, so the named functions ARE the API and there is NO execute: useNotification, useVideoStream, useDataProtection, useNativeTransition. useNotification is the sole exception carrying execute as a frozen-but-discouraged alias of scheduleLocal — never copy that pattern.\n- READ-ONLY hooks have no action functions: useNetworkStatus, useDeviceInfo, useSafeArea.\n\nSTANDARD BASE INTERFACE (single-action useBaseHook consumers):\n{ data, loading, progress, error, isWeb, isNative, execute, clear, clearError,\n  webFallbackActive, webFallbackDisabled, setWebFallback }\n\nMulti-action hooks share the same state keys (data, loading, error, isWeb, isNative, clear, clearError) but replace execute with their named functions.\n\nERROR SHAPE: error is a standard error object everywhere EXCEPT useDeviceInfo and useNetworkStatus, where it remains a plain string until 2.0. useNativeTransition and useSafeArea are error-exempt — they have no error key at all (transition failures self-heal into a plain navigate; safe-area insets always resolve to numeric defaults). useAI's shape is owned by the catalyst-ai package and is outside this contract.\n\nprogress shape: { state, percentage, message, phase, transport, bytesLoaded, bytesTotal }\n\nENVIRONMENT DETECTION (useBaseHook):\nisNative = window.WebBridge && (window.NativeBridge || window.webkit?.messageHandlers?.NativeBridge)\nisWeb = !isNative\n\nWEB FALLBACK SYSTEM:\n- Hooks that support a browser fallback declare hasWebFallback: true in useBaseHook options.\n- webFallbackActive defaults to true on web when a fallback exists (unless webFallback prop === false).\n- webFallback prop syncs dynamically after mount \u2014 all hooks (useBaseHook consumers and thin-state hooks) update webFallbackActive via a useEffect that watches the prop.\n- setWebFallback(false) disables fallback at runtime \u2014 React re-runs effects + cleanups (e.g. stops MediaStream, removes event listeners).\n- When disabled: webFallbackDisabled=true, all action methods are no-ops, data/error/loading are null/false.\n- Thin-state hooks (useNetworkStatus, useSafeArea, useDeviceInfo, useCameraPermission) manage webFallback locally and expose isNative, isWeb, webFallbackActive, webFallbackDisabled, setWebFallback \u2014 same surface as useBaseHook consumers.\n- Rules of Hooks: all hooks are always called unconditionally at top level \u2014 early returns and conditional branches only in return statements, never around hook calls.\n\nFULL HOOK LIST:\nWith web fallback:\n- useCamera \u2014 capture photo. Web: <input type=file capture=environment>.\n- useFilePicker \u2014 pick file. Web: <input type=file>.\n- useHapticFeedback \u2014 haptic/vibration. Web: navigator.vibrate.\n- useVideoStream \u2014 live camera stream + sendCommand (zoom/torch/fps). Web: getUserMedia (requires secure context) with track.applyConstraints. Stream auto-stopped on mode change or unmount.\n- useDataProtection \u2014 setScreenSecure + clearWebData. Web: overlay div on visibilitychange + localStorage/sessionStorage/cookie/IndexedDB clear.\n- useCameraPermission \u2014 camera permission state + request(). Web: navigator.permissions API (query) + getUserMedia side-effect for request().\n- useNetworkStatus \u2014 online/type. Web: navigator.onLine (defaults true if not boolean) + online/offline events (live updates).\n- useSafeArea \u2014 inset pixels. Web: CSS env() vars.\n- useDeviceInfo \u2014 device metadata. Web: navigator/screen APIs.\n\nNo web fallback (native-only or scoped out):\n- useNotification \u2014 push notifications. Web: scoped out (Service Worker required, unreliable in WebView).\n- useNotificationPermission \u2014 notification permission.\n- useGoogleSignIn \u2014 Google sign-in via native.\n- useIntent \u2014 open file with external app.\n- useNativeTransition \u2014 navigate with native slide/fade transitions. Web: CSS overlay on document.body driven by the same state machine (not a webFallback-prop hook).",
         "layer": "Bridge",
         "source": "static",
         "tags": [
@@ -1108,7 +1108,7 @@
     {
         "section": "native_hooks",
         "title": "useVideoStream \u2014 return shape",
-        "content": "useVideoStream(options?) returns: { isStreaming: boolean, streamState: { zoom, minZoom, maxZoom, torchOn, fpsMin, fpsMax }, error, isNative, webFallbackActive, webFallbackDisabled, setWebFallback, mediaStream: MediaStream|null (web only), viewfinderRef, start, stop, sendCommand, flip, clearError }.\n\nstart(options?) / stop() / flip() \u2014 stream lifecycle. sendCommand(type, value) controls live stream: 'zoom' (number \u2265 1.0), 'torch' (boolean), 'fps' ({ min, max }).\n\nOn native: sendCommand routes to WebBridge native commands. streamState updates only on native confirmation events (ON_TORCH_CHANGED, ON_ZOOM_CHANGED). On web fallback: sendCommand maps to track.applyConstraints().\n\nWEB FALLBACK (getUserMedia):\n- Requires secure context (HTTPS or localhost) \u2014 hook returns error if window.isSecureContext is false.\n- Requires navigator.mediaDevices.getUserMedia \u2014 hook returns error if unavailable.\n- mediaStream is returned directly (attach to <video> srcObject).\n- All tracks stopped automatically when setWebFallback(false) is called or component unmounts.\n- start()/stop()/flip() are async on web.\n- Rules of Hooks: all hooks (useState, useRef, useCallback, useEffect) declared unconditionally at top level \u2014 branching only in return statements.",
+        "content": "useVideoStream(options?) is a MULTI-ACTION hook — start/stop/sendCommand/flip are the API and there is NO execute key. Returns: { isStreaming: boolean, streamState: { zoom, minZoom, maxZoom, torchOn, fpsMin, fpsMax }, loading, error, isNative, isWeb, webFallbackActive, webFallbackDisabled, setWebFallback, mediaStream: MediaStream|null (web only), viewfinderRef, start, stop, sendCommand, flip, clearError }.\n\nstart(options?) / stop() / flip() \u2014 stream lifecycle. sendCommand(type, value) controls live stream: 'zoom' (number \u2265 1.0), 'torch' (boolean), 'fps' ({ min, max }).\n\nOn native: sendCommand routes to WebBridge native commands. streamState updates only on native confirmation events (ON_TORCH_CHANGED, ON_ZOOM_CHANGED). On web fallback: sendCommand maps to track.applyConstraints().\n\nWEB FALLBACK (getUserMedia):\n- Requires secure context (HTTPS or localhost) \u2014 hook returns error if window.isSecureContext is false.\n- Requires navigator.mediaDevices.getUserMedia \u2014 hook returns error if unavailable.\n- mediaStream is returned directly (attach to <video> srcObject).\n- All tracks stopped automatically when setWebFallback(false) is called or component unmounts.\n- start()/stop()/flip() are async on web.\n- Rules of Hooks: all hooks (useState, useRef, useCallback, useEffect) declared unconditionally at top level \u2014 branching only in return statements.",
         "layer": "Runtime",
         "source": "static",
         "tags": [
@@ -1126,7 +1126,7 @@
     {
         "section": "native_hooks",
         "title": "useDeviceInfo \u2014 return shape",
-        "content": "useDeviceInfo() returns: { data: { model, manufacturer, platform, osVersion, screenWidth, screenHeight, screenDensity, appVersion, appInfo }, loading, error, isWeb, isNative, webFallbackActive, webFallbackDisabled, setWebFallback }.\n\nThis is a NEW React hook (did not exist before \u2014 only WebBridge.getDeviceInfo() imperative method existed). Use useDeviceInfo() in React components instead of calling WebBridge.getDeviceInfo() imperatively.\n\nOn native: wraps WebBridge.getDeviceInfo() promise, resolves on ON_DEVICE_INFO_SUCCESS callback.\n\nWEB FALLBACK: Populates device info from browser APIs:\n- platform: navigator.platform or 'web'\n- model/manufacturer: derived from navigator.userAgent (best-effort)\n- screenWidth/Height: screen.width/height\n- screenDensity: window.devicePixelRatio\n- appVersion/appInfo: null on web (no native app context)\n\nManages webFallback state locally (thin-state hook, not via useBaseHook).",
+        "content": "useDeviceInfo() is a READ-ONLY hook (no action functions, no execute). Returns: { data: { model, manufacturer, platform, screenWidth, screenHeight, screenDensity, appInfo }, deviceInfo (=data, deprecated alias removed at 2.0), loading, error, isWeb, isNative, webFallbackActive, webFallbackDisabled, setWebFallback }. NOTE: error is a plain STRING here, not a standard error object — this stays a string until 2.0.\n\nThis is a NEW React hook (did not exist before \u2014 only WebBridge.getDeviceInfo() imperative method existed). Use useDeviceInfo() in React components instead of calling WebBridge.getDeviceInfo() imperatively.\n\nOn native: wraps WebBridge.getDeviceInfo() promise, resolves on ON_DEVICE_INFO_SUCCESS callback.\n\nWEB FALLBACK: Populates device info from browser APIs:\n- platform: navigator.platform or 'web'\n- model/manufacturer: derived from navigator.userAgent (best-effort)\n- screenWidth/Height: screen.width/height\n- screenDensity: window.devicePixelRatio\n- appVersion/appInfo: null on web (no native app context)\n\nManages webFallback state locally (thin-state hook, not via useBaseHook).",
         "layer": "Runtime",
         "source": "static",
         "tags": [
@@ -1142,7 +1142,7 @@
     {
         "section": "native_hooks",
         "title": "useDataProtection \u2014 return shape",
-        "content": "useDataProtection() returns: { data, loading, error, isWeb, isNative, execute, clear, clearError, setScreenSecure: (enabled: boolean) => void, clearWebData: () => void, isScreenSecure: boolean, webFallbackActive, webFallbackDisabled, setWebFallback }.\n\nsetScreenSecure(true/false) \u2014 enables/disables screen security (prevents screenshots/recents).\nclearWebData() \u2014 clears all web storage.\n\nOn native (Android): setScreenSecure sets FLAG_SECURE on WebView. clearWebData clears cookies, localStorage, WebView cache.\nOn native (iOS): setScreenSecure applies blur overlay. clearWebData uses WKWebsiteDataStore.\n\nWEB FALLBACK:\n- setScreenSecure(true): injects a fixed black overlay div (position:fixed, z-index:9999, 100vw/100vh) that shows/hides on document.visibilitychange \u2014 best-effort screenshot prevention (cannot block OS-level screenshots on web).\n- setScreenSecure(false): removes the overlay div and visibilitychange listener.\n- clearWebData(): clears localStorage, sessionStorage, all cookies (document.cookie), and all IndexedDB databases (indexedDB.databases() + deleteDatabase()).\n- setWebFallback(false): removes overlay + listener, returns inert no-op shape.",
+        "content": "useDataProtection() is a MULTI-ACTION hook — its named functions are the API and there is NO execute key. Returns: { data, loading, progress, error, isWeb, isNative, clear, clearError, screenSecure: boolean, setScreenSecure: (enabled: boolean) => void, clearWebData: () => void, webFallbackActive, webFallbackDisabled, setWebFallback }. Note the state key is screenSecure, not isScreenSecure.\n\nsetScreenSecure(true/false) \u2014 enables/disables screen security (prevents screenshots/recents).\nclearWebData() \u2014 clears all web storage.\n\nOn native (Android): setScreenSecure sets FLAG_SECURE on WebView. clearWebData clears cookies, localStorage, WebView cache.\nOn native (iOS): setScreenSecure applies blur overlay. clearWebData uses WKWebsiteDataStore.\n\nWEB FALLBACK:\n- setScreenSecure(true): injects a fixed black overlay div (position:fixed, z-index:9999, 100vw/100vh) that shows/hides on document.visibilitychange \u2014 best-effort screenshot prevention (cannot block OS-level screenshots on web).\n- setScreenSecure(false): removes the overlay div and visibilitychange listener.\n- clearWebData(): clears localStorage, sessionStorage, all cookies (document.cookie), and all IndexedDB databases (indexedDB.databases() + deleteDatabase()).\n- setWebFallback(false): removes overlay + listener, returns inert no-op shape.",
         "layer": "Runtime",
         "source": "static",
         "tags": [
@@ -1157,6 +1157,41 @@
             "IndexedDB"
         ]
     },
+    {
+        "section": "native_hooks",
+        "title": "useNativeTransition \u2014 return shape",
+        "content": "useNativeTransition(defaults?) is a MULTI-ACTION hook \u2014 navigate/cancelTransition are the API and there is NO execute key. Returns: { navigate: (to, options?) => void, cancelTransition: () => void, transitioning: boolean, loading (=transitioning, deprecated alias direction is reversed here \u2014 loading is canonical, transitioning is the alias removed at 2.0), isNative, isWeb }.\n\nERROR-EXEMPT: there is NO error key. Transition failures self-heal \u2014 if native startTransition or commitTransition throws, the hook logs, clears transitioning, and falls through to a plain router navigate, so the user always lands on the destination route.\n\nnavigate(to, options) accepts standard react-router NavigateOptions plus: type ('slide'|'fade', default 'slide'), direction ('left'|'right'|'up'|'down', default 'left'), duration (ms, default 300), timeout (ms safety timer, default max(duration*3, 800)). The same options can be passed once to the hook as per-call defaults.\n\nNative path: startTransition (native snapshots screen) \u2192 router.navigate(to) \u2192 double-rAF \u2192 commitTransition (native animates overlay out). Native-side safety timer force-fades the overlay if commit never arrives (ON_TRANSITION_TIMEOUT).\n\nWeb path: CSS overlay div on document.body (position:fixed, z-index:9999, opacity transition) driven by the same state machine, with its own setTimeout safety net. Not a webFallback-prop hook \u2014 it has no webFallbackActive/webFallbackDisabled/setWebFallback keys.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": [
+            "native-hooks",
+            "useNativeTransition",
+            "return-shape",
+            "navigation",
+            "transition",
+            "react-router",
+            "multi-action",
+            "error-exempt"
+        ]
+    },
+    {
+        "section": "native_hooks",
+        "title": "Native hooks \u2014 aliases and deprecations (removed at 2.0)",
+        "content": "Alias keys kept from earlier releases. Both names work and return the same value. ALL ALIASES ARE REMOVED AT 2.0 \u2014 write new code against the canonical key.\n\nALIAS -> CANONICAL:\n- isLoading -> loading (useCamera, useFilePicker, useIntent, useCameraPermission, useNotificationPermission)\n- transitioning -> loading (useNativeTransition)\n- deviceInfo -> data (useDeviceInfo)\n- permission -> data (useCameraPermission, useNotificationPermission)\n- request -> execute (useCameraPermission)\n- photo -> data (useCamera)\n- clearPhoto -> clear (useCamera)\n- clearFile -> clear (useFilePicker)\n- reset -> clear (useIntent)\n\nuseNotification.execute and useNotification.schedule both alias scheduleLocal. They are frozen for backward compatibility but DISCOURAGED, and they are explicitly NOT the pattern to copy for multi-action hooks \u2014 every other multi-action hook (useVideoStream, useDataProtection, useNativeTransition) has no execute key at all. With useNotification.execute and schedule, the list above is the complete set of 16 aliases as of 1.0.0; every one carries an @deprecated marker in the shipped type declarations.\n\nERROR SHAPE EXCEPTIONS: error is a standard error object everywhere EXCEPT useDeviceInfo and useNetworkStatus, where it stays a plain string until 2.0. useNativeTransition and useSafeArea are error-exempt \u2014 no error key at all. useAI's shape is owned by the catalyst-ai package and sits outside this contract.\n\nDUAL SURFACES: requestHapticFeedback and requestCameraPermission exist BOTH as catalyst-core/hooks exports and as WebBridge methods, with different defaults and return types. requestHapticFeedback: hooks export defaults to 'light' and resolves the raw status string; WebBridge.requestHapticFeedback defaults to 'VIRTUAL_KEY' and resolves the parsed result object. requestCameraPermission: hooks export takes no arguments and REJECTS on denial; WebBridge.requestCameraPermission takes a config object ({ includeDetails }) and RESOLVES with the denied status. The hooks exports are SSR-safe (return Promise<null> when window is undefined). The two surfaces are unified at 2.0.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": [
+            "native-hooks",
+            "aliases",
+            "deprecations",
+            "2.0",
+            "api-freeze",
+            "error-shape",
+            "WebBridge",
+            "requestHapticFeedback",
+            "requestCameraPermission"
+        ]
+    },
     {
         "section": "seo_metadata",
         "title": "Legacy 0.2.x Server-Side Meta Tags \u2014 setMetaData()",
@@ -1222,11 +1257,11 @@
     {
         "section": "framework_identity",
         "title": "Catalyst Runtime Generations",
-        "content": "Always determine the installed catalyst-core version before giving web runtime guidance. Catalyst 0.2.x is the legacy webpack generation and uses @tata1mg/router plus @loadable/component. Catalyst 0.3.x, beginning with 0.3.0-beta.1, is the Vite/ESM generation: router APIs are exported by catalyst-core and split()/hydrationReady() replace loadable APIs. Do not combine instructions from the two generations. If no version can be detected, ask which version the project targets.",
+        "content": "Always determine the installed catalyst-core version before giving web runtime guidance. Catalyst 0.2.x is the legacy webpack generation and uses @tata1mg/router plus @loadable/component. Catalyst 0.3.x, beginning with 0.3.0-beta.1, is the Vite/ESM generation: router APIs are exported by catalyst-core and split()/hydrationReady() replace loadable APIs. Catalyst 1.0.0 is the API freeze (there is no 0.4.0 release); see 'Upgrading catalyst-core 0.3.x to 1.0.0'. Do not combine instructions from different generations. If no version can be detected, ask which version the project targets.",
         "layer": "Framework",
         "source": "static",
-        "tags": ["versions", "0.2.x", "0.3.x", "migration", "webpack", "vite"],
-        "github_files": ["packages/catalyst-core/package.json", "packages/catalyst-core/src/index.jsx"]
+        "tags": ["versions", "0.2.x", "0.3.x", "1.0.0", "migration", "webpack", "vite"],
+        "github_files": ["packages/catalyst-core/package.json", "packages/catalyst-core/src/index.tsx"]
     },
     {
         "section": "build_system",
@@ -1268,12 +1303,21 @@
     {
         "section": "routing",
         "title": "Catalyst 0.3.x Integrated Router",
-        "content": "Catalyst 0.3.x removes the @tata1mg/router package dependency. catalyst-core exports React Router APIs plus RouterDataProvider, MetaTag, routing data hooks, metadata utilities, split, and hydrationReady. Existing route arrays and preparedRoutes structure remain, but imports must move from @tata1mg/router to catalyst-core. Keeping both router packages can create duplicate runtime contracts and invalid React element errors.",
+        "content": "Catalyst 0.3.x removes the @tata1mg/router package dependency. As of 1.0.0 (the API freeze), catalyst-core does NOT re-export React Router. Its root entry exports exactly eight names: RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. There is no default export (split was previously also the default). React Router is a peerDependency (^7.18.2): install react-router in the application and import RouterProvider, Outlet, Link, useParams, useNavigate, useLocation, Navigate and every other router name from 'react-router' directly. Metadata utilities (getMetaData, mergeHeadElements, deleteHeadTagsByDataAttribute), RouterContext, serverDataFetcher and useNavigateWithTransition are no longer public. Existing route arrays and preparedRoutes structure remain unchanged. Keeping both router packages can create duplicate runtime contracts and invalid React element errors.",
         "layer": "Runtime",
         "source": "static",
-        "tags": ["0.3.x", "router", "react-router", "RouterDataProvider", "migration"],
+        "tags": [
+            "0.3.x",
+            "1.0.0",
+            "router",
+            "react-router",
+            "peer-dependency",
+            "RouterDataProvider",
+            "migration",
+            "api-freeze"
+        ],
         "github_files": [
-            "packages/catalyst-core/src/index.jsx",
+            "packages/catalyst-core/src/index.tsx",
             "packages/catalyst-core/src/web-router/components/RouterDataProvider.jsx"
         ]
     },
@@ -1329,5 +1373,59 @@
         "layer": "Runtime",
         "source": "static",
         "tags": ["known-error", "0.3.x", "offline", "start", "build", "serve"]
+    },
+    {
+        "section": "version_migration",
+        "title": "Upgrading catalyst-core 0.3.x to 1.0.0",
+        "content": "Upgrade path for an application on catalyst-core 0.3.0-beta.5. Older applications first move to 0.3.x (see 'Legacy 0.2.x Migration Phase 0' and 'Catalyst 0.3.x React Runtime Contract'). 1.0.0 is the API freeze; there is no 0.4.0 release. Do the steps in order.\n\n1. DEPENDENCIES: set catalyst-core to 1.0.0. Add react-router ^7.18.2 as an application dependency: it is now a peer dependency and the server throws at startup if it is missing or outside that range. Keep react and react-dom pinned to 19.0.0. TypeScript applications also need @types/react ^19.0.0.\n\n2. NODE: run node -v. catalyst-core 1.0.0 requires >=22.12; on Node 20, importing catalyst-core/hooks or catalyst-core/WebBridge fails with ERR_REQUIRE_ESM. If the runtime is older, stop and tell the user; do not change the project's Node pin yourself.\n\n3. IMPORTS: the root entry exports exactly RouterDataProvider, useCurrentRouteData, useRouterData, MetaTag, split, hydrationReady, Head, Body. Move every React Router name (Link, Outlet, RouterProvider, useParams, useNavigate, useLocation, Navigate, ...) from 'catalyst-core' to 'react-router'. Replace `import split from 'catalyst-core'` with `import { split } from 'catalyst-core'`; there is no default export. Replace imports from 'catalyst-core/document' with Head and Body from 'catalyst-core'. 'catalyst-core/caching' is removed with no replacement. RouterContext, serverDataFetcher, mergeHeadElements, deleteHeadTagsByDataAttribute, getMetaData, useNavigateWithTransition and sanitizeFilePickerOptions (catalyst-core/hooks) are internal with no replacement: if the application uses one, stop and tell the user instead of inventing a substitute.\n\n4. BUILD AND START: run the build, then start the server once. The build catches removed imports (they fail instead of resolving to undefined); startup catches the react-router range and the Node version.\n\n5. HOOK ERROR FIELDS (not caught by the build): hook errors are now CatalystError instances. Rename reads of error.action to error.suggestedAction and error.nativeError to error.cause; error.recoverable and error.timestamp no longer exist. error.code values are registry codes (RUNTIME-NATIVE-xxx) instead of names like PERMISSION_DENIED, so replace string-literal comparisons with ERROR_CODES from catalyst-core/errors (for example ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED). See 'CatalystError shape (1.0.0)'.\n\n6. OPTIONAL, NON-BREAKING: rename deprecated hook alias keys to the canonical ones (see 'Native hooks \u2014 aliases and deprecations'); aliases keep working until 2.0.\n\nUnchanged: route arrays, preparedRoutes, server hooks, config/config.json keys and module aliases. Full guide: docs/content/12-Migration/02-Version-Upgrades.md.",
+        "layer": "Framework",
+        "source": "static",
+        "tags": [
+            "migration",
+            "migrate",
+            "upgrade",
+            "update",
+            "bump",
+            "1.0.0",
+            "0.3.x",
+            "breaking-changes",
+            "api-freeze",
+            "react-router",
+            "peer-dependency",
+            "peerDependency",
+            "node"
+        ],
+        "github_files": ["docs/content/12-Migration/02-Version-Upgrades.md"]
+    },
+    {
+        "section": "known_errors",
+        "title": "ERR_REQUIRE_ESM importing catalyst-core/hooks on Node 20",
+        "content": "Symptom: importing catalyst-core/hooks or catalyst-core/WebBridge throws ERR_REQUIRE_ESM on Node 20. Cause: the CommonJS native bridge require()s the ESM error registry, which older Node runtimes refuse without a flag; the package's engines field sets the supported minimum. Fix: run Node 22.12 or newer (catalyst-core 1.0.0 declares engines node >=22.12). Do not change the project's Node pin without telling the user.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": ["1.0.0", "node", "22.12", "ERR_REQUIRE_ESM", "error", "hooks", "WebBridge"]
+    },
+    {
+        "section": "native_hooks",
+        "title": "CatalystError shape (1.0.0)",
+        "content": "From 1.0.0, hook failures are CatalystError instances (class exported from catalyst-core/errors) with fields code, message, category, suggestedAction, docUrl, details and cause (the originating platform error). code is a registry code such as RUNTIME-NATIVE-001; compare against ERROR_CODES from catalyst-core/errors (ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED and so on), never against string literals.\n\nCHANGED FROM 0.3.x: the error used to be a plain object { code, category, message, details, recoverable, action, nativeError, timestamp } with code values like PERMISSION_DENIED. action is now suggestedAction, nativeError is now cause, recoverable and timestamp are gone, and code values changed. These renames are not caught by a build.\n\nCatalystError extends Error, so message is non-enumerable: JSON.stringify(error) omits it. Log error.message explicitly or use code and docUrl. Render error.message in JSX, never the error object. Exceptions to the object shape (string errors, error-exempt hooks) are listed under 'Native hooks \u2014 aliases and deprecations'.",
+        "layer": "Runtime",
+        "source": "static",
+        "tags": [
+            "1.0.0",
+            "CatalystError",
+            "error",
+            "error-shape",
+            "suggestedAction",
+            "cause",
+            "ERROR_CODES",
+            "RUNTIME-NATIVE",
+            "JSON.stringify",
+            "native-hooks"
+        ],
+        "github_files": [
+            "packages/catalyst-core/src/errors/index.js",
+            "packages/catalyst-core/src/native/bridge/errors.ts"
+        ]
     }
 ]

package/mcp_v2/mcp.js

@@ -26,6 +26,7 @@ const tasks = require("./tools/tasks")
 const sync = require("./tools/sync")
 const knowledge = require("./tools/knowledge")
 const github = require("./tools/github")
+const errors = require("./tools/errors")
 
 const MCP_DIR = __dirname
 const DB_PATH = path.join(MCP_DIR, "context.db")
@@ -121,6 +122,7 @@ tasks.init(db)
 sync.init(db)
 knowledge.init(db)
 github.init(projectInfo)
+errors.init()
 
 // ── Intent classification (internal, not exposed as tool) ─────────────────────
 
@@ -131,9 +133,9 @@ const INTENT_PATTERNS = {
     guidance:
         /\b(what\s+is|what\s+are|how\s+does|how\s+do|explain|show\s+me|tell\s+me|hook|api|usage|example)\b/i,
     status: /status|done|complet|finish|check.*config|config.*check|what.*(left|remain|todo|next|pending)|how far|progress/i,
-    // feedback = wants to raise an issue or discussion on GitHub
+    // feedback = wants to raise an issue, PR, or discussion on GitHub
     feedback:
-        /\b(issue|bug\s+report|report\s+(a\s+)?bug|open\s+(an?\s+)?issue|create\s+(an?\s+)?issue|raise\s+(an?\s+)?issue|discussion|discuss|feature\s+request|proposal|suggest)\b/i,
+        /\b(issue|bug\s+report|report\s+(a\s+)?bug|open\s+(an?\s+)?issue|create\s+(an?\s+)?issue|raise\s+(an?\s+)?issue|pull\s*request|open\s+(a\s+)?pr|raise\s+(a\s+)?pr|create\s+(a\s+)?pr|discussion|discuss|feature\s+request|proposal|suggest)\b/i,
     debug: /error|fail|broken|not work|crash|issue|bug|why|wrong/i,
     build: /build|compile|webpack|vite|bundle|android|ios|platform/i,
     sync: /sync|update.*doc|fetch.*doc|latest.*doc/i,
@@ -148,7 +150,7 @@ const INTENT_NEXT_ACTION = {
     build: "answer_only — explain build flow. Do NOT call create_task_plan.",
     sync: "answer_only — sync complete. Do NOT call create_task_plan.",
     feedback:
-        "answer_only — run the GitHub issue workflow and show the created issue URL or markdown fallback. Do NOT call create_task_plan.",
+        "answer_only — run the GitHub issue or PR workflow and show the created URL or markdown fallback. Do NOT call create_task_plan.",
     unknown: "answer_only — unclear intent. Return what you found. Do NOT call create_task_plan.",
 }
 
@@ -234,6 +236,21 @@ const TOOLS = [
             required: ["symptom"],
         },
     },
+    {
+        name: "explain_error",
+        description:
+            "Use when the developer has a specific catalyst-core error code (e.g. 'PREFLIGHT-001', 'BUNDLE-000') and wants to know what it means and how to fix it. Looks it up against the generated errors/ registry. If the code isn't catalyst-owned (e.g. a raw Vite/Rollup/Gradle/Xcode code), says so rather than guessing — those are not reinterpreted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                code: {
+                    type: "string",
+                    description: "The error code to explain, e.g. 'PREFLIGHT-001'.",
+                },
+            },
+            required: ["code"],
+        },
+    },
     {
         name: "check_config",
         description:
@@ -419,6 +436,7 @@ const TOOLS = [
                         "seo_metadata",
                         "transport_architecture",
                         "webview_config",
+                        "version_migration",
                     ],
                     description:
                         "Optional: only pass when you are certain of the section. Omit if unsure — wrong section returns zero results.",
@@ -589,6 +607,124 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "create_github_pr",
+        description:
+            "Use when the developer wants to open, raise, create, or publish a GitHub pull request for catalyst-core. Resolves the head branch from the current git checkout (or the head arg), renders the PR body in the shape of the matching .github/PULL_REQUEST_TEMPLATE (fix / feature / chore) from the structured fields, appends the shared checklist, and previews with dry_run:true. Publishes via the GitHub API only when dry_run:false is explicitly passed, and only if the head branch is already pushed to origin (it does not push for you). Default to dry_run:true first. Intent: feedback.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                dry_run: {
+                    type: "boolean",
+                    description:
+                        "Defaults to true. When true, returns the rendered PR preview (title, head → base, change type, body, commits ahead of base) without publishing. Pass false only after explicit developer approval.",
+                },
+                change_type: {
+                    type: "string",
+                    enum: ["fix", "feature", "chore"],
+                    description:
+                        "Which PR template to render. Omit to infer from the title/summary. fix = bug fix, feature = new capability, chore = no behaviour change (deps, CI, refactor, docs).",
+                },
+                title: {
+                    type: "string",
+                    description:
+                        "PR title. Use a conventional-commit prefix (fix: / feat: / chore:) to match the repo's commitlint config.",
+                },
+                body: {
+                    type: "string",
+                    description:
+                        "Full PR description. Already-structured markdown (with ## headings) is preserved as-is; plain text and the structured fields below are laid out in the template's section order.",
+                },
+                summary: {
+                    type: "string",
+                    description:
+                        "One or two sentences on what the PR changes. Used when body is not composed.",
+                },
+                head: {
+                    type: "string",
+                    description:
+                        "Head branch. Defaults to the current branch (git rev-parse --abbrev-ref HEAD).",
+                },
+                base: {
+                    type: "string",
+                    description:
+                        "Base branch to merge into. Defaults to 'main'. Pass the epic/story branch when the PR rides a stack (e.g. epic/329).",
+                },
+                draft: {
+                    type: "boolean",
+                    description: "Open as a draft PR. Defaults to true.",
+                },
+                closes_issue: {
+                    type: ["string", "number"],
+                    description:
+                        "Issue number this PR closes. Renders a 'Closes #<n>' line at the top of the body.",
+                },
+                root_cause: {
+                    type: "string",
+                    description:
+                        "fix: what was actually wrong, at the level of the offending line or contract.",
+                },
+                repro: {
+                    type: "string",
+                    description:
+                        "fix: minimal steps or the failing input that triggered the bug before this change.",
+                },
+                fix: {
+                    type: "string",
+                    description: "fix: what this PR changes and why that closes the root cause.",
+                },
+                regression_test: {
+                    type: "string",
+                    description:
+                        "fix: the test added that fails without the fix and passes with it, or why none was added.",
+                },
+                affected_error_codes: {
+                    type: "string",
+                    description:
+                        "fix: CatalystError codes whose behaviour or wording this touches, or 'none'.",
+                },
+                what: {
+                    type: "string",
+                    description: "feature: the capability being added, in one or two sentences.",
+                },
+                why: {
+                    type: "string",
+                    description: "feature: the problem it solves or the use case it unblocks.",
+                },
+                new_error_codes: {
+                    type: "string",
+                    description:
+                        "feature: new CatalystError code(s) introduced + confirmation errors/ docs were regenerated (node packages/catalyst-core/src/errors/generateDocs.js), or 'No new error codes'.",
+                },
+                coverage_delta: {
+                    type: "string",
+                    description: "feature: what is now covered that was not, and the delta if known.",
+                },
+                change_trigger: {
+                    type: "string",
+                    description:
+                        "chore: what triggered this — dependency bump, CI tweak, flaky job, refactor, doc drift.",
+                },
+                change: {
+                    type: "string",
+                    description: "chore: what this PR does.",
+                },
+                no_behaviour_change: {
+                    type: ["boolean", "string"],
+                    description:
+                        "chore: pass true to check the 'no runtime behaviour change' confirmation box in the rendered body.",
+                },
+                project_path: {
+                    type: "string",
+                    description: "Path to the catalyst repo root. Defaults to detected project root.",
+                },
+                _query: {
+                    type: "string",
+                    description: "Original user query for intent classification.",
+                },
+            },
+        },
+    },
 ]
 
 // ── Tool handler dispatch ─────────────────────────────────────────────────────
@@ -607,6 +743,8 @@ const TOOL_HANDLERS = {
     sync_knowledge_base: sync.handle_sync_knowledge_base,
     query_knowledge: knowledge.handle_query_knowledge,
     create_github_issue: github.handle_create_github_issue,
+    create_github_pr: github.handle_create_github_pr,
+    explain_error: errors.handle_explain_error,
 }
 
 // ── MCP JSON-RPC over stdio ───────────────────────────────────────────────────