@makinbakin/sdk 0.0.0-bootstrap.0 → 0.0.1-rc.10

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@bakin/sdk` — plugin author SDK.
+ * `@makinbakin/sdk` — plugin author SDK.
  *
  * The main entry re-exports types + the single-call `registerPlugin` helper
  * so plugin authors can write `import { registerPlugin } from '@makinbakin/sdk'`
@@ -8,20 +8,53 @@
  * `/slots`) to keep the top-level namespace from exploding.
  *
  * Sub-paths:
- *   - `@bakin/sdk/ui`         — shadcn UI primitives (Button, Card, Dialog, ...)
- *   - `@bakin/sdk/hooks`      — React hooks (useAgent, useSSE, useSearch, ...)
- *   - `@bakin/sdk/components` — shared components (PluginHeader, FacetFilter, ...)
- *   - `@bakin/sdk/slots`      — Slot + registerSlot primitive
- *   - `@bakin/sdk/types`      — full type re-exports
- *   - `@bakin/sdk/metadata`   — docs-aware contract helpers
+ *   - `@makinbakin/sdk/ui`         — shadcn UI primitives (Button, Card, Dialog, ...)
+ *   - `@makinbakin/sdk/hooks`      — React hooks (useAgent, useSSE, useSearch, ...)
+ *   - `@makinbakin/sdk/components` — shared components (PluginHeader, FacetFilter, ...)
+ *   - `@makinbakin/sdk/slots`      — Slot + registerSlot primitive
+ *   - `@makinbakin/sdk/types`      — full type re-exports
+ *   - `@makinbakin/sdk/metadata`   — docs-aware contract helpers
  *
- * Plugin authors: at build time, mark `@bakin/sdk`, `@bakin/sdk/*`, and
+ * Plugin authors: at build time, mark `@makinbakin/sdk`, `@makinbakin/sdk/*`, and
  * `react`/`react-dom` as externals. At runtime the browser's import map
  * (emitted by Bakin) resolves those to the host's bundled copies so there
  * is a single React instance and a single SDK.
  */
+/** Re-exports every plugin contract type. See `@makinbakin/sdk/types` for the full list. */
 export * from './types/index';
-export { registerPlugin, unregisterPlugin, registerPluginCleanup, getRegistryVersion, subscribeRegistry, getAllNavItems, getNavItemsSnapshot, getPluginNavItems, getPluginRoute, getPluginRoutes, } from './register';
+/** Register a plugin (single-call entry from a plugin's `client.tsx`). */
+export { registerPlugin } from './register';
+/** Tear down all registrations owned by a plugin (used during hot-swap). */
+export { unregisterPlugin } from './register';
+/** Register a cleanup callback fired when the plugin is unregistered. */
+export { registerPluginCleanup } from './register';
+/** Current registry version — bumps on every mutation (for useSyncExternalStore). */
+export { getRegistryVersion } from './register';
+/** Subscribe to registry-version changes. */
+export { subscribeRegistry } from './register';
+/** Get every registered nav item across all plugins. */
+export { getAllNavItems } from './register';
+/** Get a snapshot of the current nav items (non-subscribing). */
+export { getNavItemsSnapshot } from './register';
+/** Get nav items contributed by a specific plugin. */
+export { getPluginNavItems } from './register';
+/** Set or clear a runtime badge on a plugin-owned nav item. */
+export { setNavBadge } from './register';
+/** Read the current badge for a nav item, or undefined if none. */
+export { getNavBadge } from './register';
+/** Stable snapshot of every active nav badge keyed by navItemId. */
+export { getNavBadgesSnapshot } from './register';
+/** Subscribe to nav-badge mutations (separate channel from `subscribeRegistry`). */
+export { subscribeNavBadges } from './register';
+/** Look up a specific client route by plugin id + path. */
+export { getPluginRoute } from './register';
+/** Get all registered client routes (across all plugins). */
+export { getPluginRoutes } from './register';
 export type { ClientRouteEntry, MatchedPluginRoute, NavItem, PluginRegistration } from './register';
-export { defineRoute, defineCoreRoute, definePlugin } from './routing/index';
+/** Define a plugin HTTP route with typed input/output schemas. */
+export { defineRoute } from './routing/index';
+/** Define a core (non-plugin) HTTP route. */
+export { defineCoreRoute } from './routing/index';
+/** Compose a plugin's routes into a single definition for the server. */
+export { definePlugin } from './routing/index';
 export type { APIRoute, HttpStatus, RouteContext, PluginContextLite, CoreContext, BodySpec, ResponseSpec, ParsedInput, } from './routing/index';

package/index.js

@@ -60,15 +60,45 @@ function getRegistry2() {
       cleanupByPlugin: new Map,
       navItemsSnapshot: [],
       version: 0,
-      listeners: new Set
+      listeners: new Set,
+      badgesByPlugin: new Map,
+      badgesSnapshot: new Map,
+      badgeListeners: new Set
     };
   }
   const registry = g.__bakinClientRegistry;
   if (!Array.isArray(registry.navItemsSnapshot)) {
     registry.navItemsSnapshot = buildNavItemsSnapshot(registry);
   }
+  if (!registry.badgesByPlugin)
+    registry.badgesByPlugin = new Map;
+  if (!registry.badgesSnapshot)
+    registry.badgesSnapshot = buildBadgesSnapshot(registry);
+  if (!registry.badgeListeners)
+    registry.badgeListeners = new Set;
   return registry;
 }
+function buildBadgesSnapshot(registry) {
+  const snapshot = new Map;
+  for (const byNavItemId of registry.badgesByPlugin.values()) {
+    for (const [navItemId, badge] of byNavItemId) {
+      if (!snapshot.has(navItemId))
+        snapshot.set(navItemId, badge);
+    }
+  }
+  return snapshot;
+}
+function bumpBadges() {
+  const registry = getRegistry2();
+  registry.badgesSnapshot = buildBadgesSnapshot(registry);
+  for (const l of registry.badgeListeners) {
+    try {
+      l();
+    } catch (err) {
+      console.error("[bakin] badge listener threw:", err);
+    }
+  }
+}
 function bumpVersion() {
   const registry = getRegistry2();
   registry.navItemsSnapshot = buildNavItemsSnapshot(registry);
@@ -116,7 +146,10 @@ function unregisterPlugin(id) {
   registry.navByPlugin.delete(id);
   registry.routesByPlugin.delete(id);
   clearSlotsOwnedBy(id);
+  const hadBadges = registry.badgesByPlugin.delete(id);
   bumpVersion();
+  if (hadBadges)
+    bumpBadges();
 }
 function registerPluginCleanup(id, fn) {
   const registry = getRegistry2();
@@ -143,6 +176,41 @@ function getNavItemsSnapshot() {
 function getPluginNavItems(pluginId) {
   return getRegistry2().navByPlugin.get(pluginId) ?? [];
 }
+function setNavBadge(pluginId, navItemId, badge) {
+  const registry = getRegistry2();
+  let plugin = registry.badgesByPlugin.get(pluginId);
+  if (badge === null) {
+    if (!plugin?.has(navItemId))
+      return;
+    plugin.delete(navItemId);
+    if (plugin.size === 0)
+      registry.badgesByPlugin.delete(pluginId);
+    bumpBadges();
+    return;
+  }
+  const prev = plugin?.get(navItemId);
+  if (prev && prev.count === badge.count && prev.tone === badge.tone)
+    return;
+  if (!plugin) {
+    plugin = new Map;
+    registry.badgesByPlugin.set(pluginId, plugin);
+  }
+  plugin.set(navItemId, { count: badge.count, tone: badge.tone });
+  bumpBadges();
+}
+function getNavBadge(navItemId) {
+  return getRegistry2().badgesSnapshot.get(navItemId);
+}
+function getNavBadgesSnapshot() {
+  return getRegistry2().badgesSnapshot;
+}
+function subscribeNavBadges(listener) {
+  const registry = getRegistry2();
+  registry.badgeListeners.add(listener);
+  return () => {
+    registry.badgeListeners.delete(listener);
+  };
+}
 function normalizePattern(pattern) {
   return pattern.split("/").filter(Boolean);
 }
@@ -13882,6 +13950,333 @@ var errorEnvelope = exports_external.object({
   error: exports_external.string(),
   issues: exports_external.array(exports_external.unknown()).optional()
 });
+
+// packages/core/src/logger.ts
+import { createWriteStream, existsSync, mkdirSync, renameSync, statSync } from "fs";
+import { join as join2 } from "path";
+
+// packages/core/src/content-dir.ts
+import { join } from "path";
+import { homedir } from "os";
+// packages/core/src/constants.ts
+var APP_SLUG = "bakin";
+
+// packages/core/src/content-dir.ts
+function bakinHomeDefault() {
+  return join(homedir(), `.${APP_SLUG}`);
+}
+var resolvedContentDir = null;
+function isTestEnv() {
+  return process.env.VITEST === "true" || !!process.env.VITEST;
+}
+function realBakinHome() {
+  const realHome = process.env.HOME || process.env.USERPROFILE || "";
+  if (!realHome)
+    return "";
+  return join(realHome, `.${APP_SLUG}`);
+}
+function assertSafeForTest(path) {
+  if (!isTestEnv())
+    return;
+  const real = realBakinHome();
+  if (real && path === real) {
+    throw new Error(`[bakin] getContentDir() resolved to the real Bakin home (${real}) ` + `during a test run. This would write test data to your production instance. ` + `Fix: mock src/core/content-dir in this test, or set BAKIN_HOME to a temp ` + `directory before importing any Bakin module. See CLAUDE.md \xA7 Testing Rules.`);
+  }
+}
+function getContentDir() {
+  if (resolvedContentDir)
+    return resolvedContentDir;
+  const resolved = resolveContentDirInner();
+  assertSafeForTest(resolved);
+  resolvedContentDir = resolved;
+  return resolvedContentDir;
+}
+function resolveContentDirInner() {
+  if (process.env.BAKIN_HOME)
+    return process.env.BAKIN_HOME;
+  return bakinHomeDefault();
+}
+function getBakinPaths() {
+  const home = getContentDir();
+  const assets = join(home, "assets");
+  return {
+    home,
+    memoryLog: join(home, "MEMORY-LOG.md"),
+    audit: join(home, "audit.jsonl"),
+    assets,
+    "assets.store": join(assets, "store"),
+    "assets.inbox": join(assets, "inbox"),
+    "assets.trash": join(assets, ".trash"),
+    agents: join(home, "agents"),
+    personas: join(home, "team", "personas"),
+    team: join(home, "team"),
+    heartbeats: join(home, "heartbeats"),
+    inbox: join(home, "inbox"),
+    tasks: join(home, "tasks"),
+    workflows: join(home, "workflows"),
+    settings: join(home, "settings.json"),
+    logs: join(home, "logs")
+  };
+}
+
+// packages/core/src/logger.ts
+var MAX_LOG_BYTES = 10 * 1024 * 1024;
+var LEVEL_RANK = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+var COLOR_RESET = "\x1B[0m";
+var COLORS = {
+  dim: "\x1B[2m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m",
+  magenta: "\x1B[35m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m"
+};
+var fileStream = null;
+var fileTransportInitialized = false;
+var fileTransportDisabled = false;
+function fileTransportEnabled() {
+  if (fileTransportDisabled)
+    return false;
+  if (false)
+    ;
+  if (process.env.VITEST)
+    return false;
+  if (process.env.BAKIN_DISABLE_FILE_LOG === "1")
+    return false;
+  return true;
+}
+function ensureFileStream() {
+  if (fileTransportInitialized)
+    return fileStream;
+  fileTransportInitialized = true;
+  if (!fileTransportEnabled())
+    return null;
+  try {
+    const logsDir = getBakinPaths().logs;
+    if (!existsSync(logsDir))
+      mkdirSync(logsDir, { recursive: true });
+    const logPath = join2(logsDir, "server.log");
+    if (existsSync(logPath)) {
+      try {
+        const size = statSync(logPath).size;
+        if (size > MAX_LOG_BYTES) {
+          const rotated = join2(logsDir, "server.log.1");
+          renameSync(logPath, rotated);
+        }
+      } catch {}
+    }
+    fileStream = createWriteStream(logPath, { flags: "a" });
+    fileStream.on("error", () => {
+      fileTransportDisabled = true;
+      fileStream = null;
+    });
+  } catch {
+    fileTransportDisabled = true;
+    fileStream = null;
+  }
+  return fileStream;
+}
+function formatEntry(entry) {
+  const parts = [`[${entry.ts}] [${entry.level.toUpperCase()}] [${entry.module}] ${entry.message}`];
+  if (entry.error)
+    parts.push(`  error: ${entry.error}`);
+  if (entry.data)
+    parts.push(`  data: ${JSON.stringify(entry.data)}`);
+  return parts.join(`
+`);
+}
+function consoleFormat() {
+  const configured = process.env.BAKIN_CONSOLE_FORMAT;
+  if (configured === "pretty" || configured === "verbose" || configured === "plain" || configured === "silent") {
+    return configured;
+  }
+  return process.stdout.isTTY === true ? "pretty" : "plain";
+}
+function consoleMinLevel(format) {
+  const configured = process.env.BAKIN_LOG_LEVEL;
+  if (configured === "debug" || configured === "info" || configured === "warn" || configured === "error") {
+    return configured;
+  }
+  if (format === "verbose")
+    return "debug";
+  if (format === "silent")
+    return "error";
+  if (format === "pretty")
+    return "info";
+  return "debug";
+}
+function colorEnabled(format) {
+  if (format === "plain")
+    return false;
+  if (process.env.NO_COLOR || process.env.BAKIN_NO_COLOR === "1")
+    return false;
+  return process.stdout.isTTY === true;
+}
+function colorize(text, color, enabled) {
+  return enabled ? `${COLORS[color]}${text}${COLOR_RESET}` : text;
+}
+function sourceLabel(entry) {
+  const data = entry.data;
+  const explicitSource = typeof data?.source === "string" ? data.source : undefined;
+  const pluginId = typeof data?.pluginId === "string" ? data.pluginId : undefined;
+  if (explicitSource === "antfly")
+    return "antfly";
+  if (explicitSource === "dev")
+    return "dev";
+  if (explicitSource === "plugin" && pluginId)
+    return `plugin:${pluginId}`;
+  if (entry.module === "plugin-registry" && pluginId)
+    return `plugin:${pluginId}`;
+  if (entry.module.startsWith("api:"))
+    return "api";
+  return entry.module;
+}
+function sourceColor(source) {
+  if (source === "dev")
+    return "cyan";
+  if (source === "server")
+    return "blue";
+  if (source === "antfly")
+    return "magenta";
+  if (source.startsWith("plugin:"))
+    return "green";
+  if (source.includes("search"))
+    return "cyan";
+  if (source.includes("runtime"))
+    return "magenta";
+  return "dim";
+}
+function levelColor(level) {
+  if (level === "debug")
+    return "dim";
+  if (level === "warn")
+    return "yellow";
+  if (level === "error")
+    return "red";
+  return "blue";
+}
+function isImportantAntflyInfo(entry) {
+  return [
+    "Metadata API server is ready",
+    "Store HTTP server is ready",
+    "Swarm mode: all servers are ready",
+    "Termite's api server starting"
+  ].some((message) => entry.message.includes(message));
+}
+function suppressPrettyInfo(entry) {
+  if (entry.level !== "info")
+    return false;
+  if (entry.data?.source === "antfly")
+    return !isImportantAntflyInfo(entry);
+  if (entry.module === "plugin-registry") {
+    return entry.message === "plugin activated" || entry.message.startsWith("Auto-registered ") || entry.message.startsWith("Plugin activation order:");
+  }
+  return [
+    "search-registry",
+    "search-reconcile",
+    "search-cleanup",
+    "hot-reload-coordinator",
+    "mcporter",
+    "dispatch",
+    "watchdog",
+    "doctor",
+    "lifecycle"
+  ].includes(entry.module);
+}
+function shouldWriteConsole(entry, format) {
+  if (format === "silent")
+    return false;
+  const minLevel = consoleMinLevel(format);
+  if (LEVEL_RANK[entry.level] < LEVEL_RANK[minLevel])
+    return false;
+  if (format === "pretty" && suppressPrettyInfo(entry))
+    return false;
+  return true;
+}
+function formatPrettyEntry(entry, format) {
+  const colors = colorEnabled(format);
+  const time3 = new Date(entry.ts).toTimeString().slice(0, 8);
+  const level = entry.level.padEnd(5);
+  const source = sourceLabel(entry);
+  const label = source.padEnd(18);
+  const levelPart = colorize(level, levelColor(entry.level), colors);
+  const sourcePart = colorize(label, sourceColor(source), colors);
+  const messagePart = entry.level === "error" ? colorize(entry.message, "red", colors) : entry.message;
+  const parts = [`${colorize(time3, "dim", colors)}  ${levelPart}  ${sourcePart}  ${messagePart}`];
+  if (entry.error)
+    parts[0] += ` - ${entry.error}`;
+  if (format === "verbose" && entry.data) {
+    parts.push(`  data: ${JSON.stringify(entry.data)}`);
+  }
+  return parts.join(`
+`);
+}
+function formatConsoleEntry(entry) {
+  const format = consoleFormat();
+  if (format === "plain")
+    return formatEntry(entry);
+  if (format === "silent")
+    return "";
+  return formatPrettyEntry(entry, format);
+}
+function writeToFile(entry) {
+  const stream = ensureFileStream();
+  if (!stream)
+    return;
+  try {
+    stream.write(JSON.stringify(entry) + `
+`);
+  } catch {
+    fileTransportDisabled = true;
+    fileStream = null;
+  }
+}
+function createLogger(module) {
+  function log(level, message, errorOrData, data) {
+    const entry = {
+      ts: new Date().toISOString(),
+      level,
+      module,
+      message
+    };
+    if (errorOrData instanceof Error) {
+      entry.error = errorOrData.message;
+      entry.data = data ? { ...data, stack: errorOrData.stack } : { stack: errorOrData.stack };
+    } else if (typeof errorOrData === "string") {
+      entry.error = errorOrData;
+      entry.data = data;
+    } else if (errorOrData && typeof errorOrData === "object") {
+      entry.data = errorOrData;
+    }
+    const format = consoleFormat();
+    if (shouldWriteConsole(entry, format)) {
+      const formatted = formatConsoleEntry(entry);
+      if (level === "error") {
+        console.error(formatted);
+      } else if (level === "warn") {
+        console.warn(formatted);
+      } else {
+        console.log(formatted);
+      }
+    }
+    writeToFile(entry);
+  }
+  return {
+    debug: (message, data) => log("debug", message, data),
+    info: (message, data) => log("info", message, data),
+    warn: (message, errorOrData, data) => log("warn", message, errorOrData, data),
+    error: (message, errorOrData, data) => log("error", message, errorOrData, data)
+  };
+}
+
+// packages/core/src/routing/dispatcher.ts
+var log = createLogger("dispatcher");
 // packages/core/src/routing/search-route.ts
 var searchQuery = exports_external.object({
   q: exports_external.string().min(1),
@@ -13903,6 +14298,8 @@ var errorResponse = exports_external.object({ error: exports_external.string() }
 export {
   unregisterPlugin,
   subscribeRegistry,
+  subscribeNavBadges,
+  setNavBadge,
   registerPluginCleanup,
   registerPlugin,
   getRegistryVersion,
@@ -13910,6 +14307,8 @@ export {
   getPluginRoute,
   getPluginNavItems,
   getNavItemsSnapshot,
+  getNavBadgesSnapshot,
+  getNavBadge,
   getAllNavItems,
   defineRoute,
   definePlugin,

package/metadata/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@bakin/sdk/metadata` — docs-aware contract helpers.
+ * `@makinbakin/sdk/metadata` — docs-aware contract helpers.
  *
  * Re-exports the canonical `RouteContract`, `CliCommandContract`,
  * `HookContract`, `SlotContract`, `ExecToolContract`, and the corresponding
@@ -10,7 +10,20 @@
  *
  * `defineApiRoute` / `definePluginRoute` are kept as re-exports for backward
  * compatibility with existing call sites; new code should use `defineRoute`
- * from `@bakin/sdk/routing` (the typed declarative shape).
+ * from `@makinbakin/sdk/routing` (the typed declarative shape).
  */
 export type { ContractMetadata, ContractStability, ContractVisibility, CliCommandContract, DocsAwareAPIRoute, DocsExample, ExecToolContract, HookContract, HookKind, PublicContract, RouteContract, SchemaLike, SlotContract, SourceLocation, } from '../_internal/core/docs';
-export { defineApiRoute, defineCliCommandContract, defineExecToolContract, defineHookContract, definePluginRoute, defineRouteContract, defineSlotContract, } from '../_internal/core/docs';
+/** Legacy: declare an API route with docs metadata. Prefer `defineRoute` from `/routing`. */
+export { defineApiRoute } from '../_internal/core/docs';
+/** Define a CLI command contract for documentation. */
+export { defineCliCommandContract } from '../_internal/core/docs';
+/** Define an MCP exec tool contract for documentation. */
+export { defineExecToolContract } from '../_internal/core/docs';
+/** Define a cross-plugin hook contract for documentation. */
+export { defineHookContract } from '../_internal/core/docs';
+/** Legacy: declare a plugin route with docs metadata. Prefer `defineRoute` from `/routing`. */
+export { definePluginRoute } from '../_internal/core/docs';
+/** Define a generic route contract (shared shape for API + plugin routes). */
+export { defineRouteContract } from '../_internal/core/docs';
+/** Define a UI slot contract for documentation. */
+export { defineSlotContract } from '../_internal/core/docs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makinbakin/sdk",
-  "version": "0.0.0-bootstrap.0",
+  "version": "0.0.1-rc.10",
   "description": "SDK for building Bakin plugins — UI components, slot types, hooks, and the runtime registerPlugin helper.",
   "type": "module",
   "sideEffects": false,
@@ -73,7 +73,7 @@
     "url": "https://github.com/markhayden/bakin/issues"
   },
   "author": "markhayden",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "keywords": [
     "bakin",
     "plugin",

package/register.d.ts

@@ -17,15 +17,7 @@
  * nav + slot trees re-render when plugins come or go at runtime.
  */
 import type { ComponentType } from 'react';
-interface NavItem {
-    id: string;
-    label: string;
-    icon?: string;
-    href?: string;
-    order?: number;
-    alwaysExpanded?: boolean;
-    children?: NavItem[];
-}
+import type { NavBadge, NavItem } from './types/index';
 interface PluginRegistration {
     id: string;
     navItems?: NavItem[];
@@ -92,6 +84,25 @@ export declare function getNavItemsSnapshot(): readonly NavItem[];
  * Nav items for a specific plugin. Returned as a readonly copy.
  */
 export declare function getPluginNavItems(pluginId: string): ReadonlyArray<NavItem>;
+/**
+ * Set or clear the badge for a nav item owned by a plugin. Pass `null` to
+ * clear. Safe to call before the nav item itself is registered — the badge
+ * survives in the registry until the owning plugin is unregistered.
+ */
+export declare function setNavBadge(pluginId: string, navItemId: string, badge: NavBadge | null): void;
+/** Read the current badge for a nav item, or undefined if none. */
+export declare function getNavBadge(navItemId: string): NavBadge | undefined;
+/**
+ * Stable snapshot of every active badge keyed by navItemId. The identity
+ * of the returned Map only changes when a badge is set, cleared, or its
+ * owning plugin is unregistered — safe for React's `useSyncExternalStore`.
+ */
+export declare function getNavBadgesSnapshot(): ReadonlyMap<string, NavBadge>;
+/**
+ * Subscribe to badge mutations on a channel separate from `subscribeRegistry`
+ * so high-frequency badge ticks don't force the whole nav to re-render.
+ */
+export declare function subscribeNavBadges(listener: () => void): () => void;
 export interface MatchedPluginRoute {
     pluginId: string;
     path: string;

package/routing/index.d.ts

@@ -1,11 +1,16 @@
 /**
- * `@bakin/sdk/routing` — typed route contracts for plugin authors.
+ * `@makinbakin/sdk/routing` — typed route contracts for plugin authors.
  *
  * Re-exports from `@bakin/core/routing` for a single source of truth. The
- * SDK's general type module (`@bakin/sdk/types`) keeps duplicated primitives
+ * SDK's general type module (`@makinbakin/sdk/types`) keeps duplicated primitives
  * for self-containment, but the routing surface re-exports because keeping
  * two parallel `APIRoute<...>` definitions in sync is a debt we are
  * deliberately avoiding.
  */
-export { defineRoute, defineCoreRoute, definePlugin, } from '../_internal/core/routing';
+/** Define a plugin HTTP route with typed input/output and handler. */
+export { defineRoute } from '../_internal/core/routing';
+/** Define a core (non-plugin) HTTP route. */
+export { defineCoreRoute } from '../_internal/core/routing';
+/** Compose a plugin's routes into a single definition for the server. */
+export { definePlugin } from '../_internal/core/routing';
 export type { HttpMethod, HttpStatus, RouteContext, PluginContextLite, CoreContext, JsonBodySpec, MultipartBodySpec, RawBodySpec, NoBodySpec, BodySpec, JsonResponseSpec, NoContentResponseSpec, NonJsonResponseSpec, ResponseSpec, ParsedInput, APIRoute, PluginWithRoutes, DefinePluginInput, } from '../_internal/core/routing';