@elevasis/sdk 1.54.0 → 1.56.0

package/reference/packages/ui/src/knowledge/README.md

@@ -1,33 +1,33 @@
-# @elevasis/ui/knowledge
-
-Read-only browser primitives for the Organization Model knowledge graph.
-
-## Surface
-
-| Export                                                                 | Purpose                                                                             |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
-| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
-| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
-| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
-| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
+# @elevasis/ui/knowledge
+
+Read-only browser primitives for the Organization Model knowledge graph.
+
+## Surface
+
+| Export                                                                 | Purpose                                                                                                        |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.                                        |
+| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication.                           |
+| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                                            |
+| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups.                           |
+| `KnowledgeSearchBar`                                                   | Client-side search built in-memory from the live `knowledgeNodes` prop.                                        |
 | `KnowledgeNodeDetailRouteView`                                         | Shared `/knowledge/$nodeId` content route view; apps keep TanStack route adapters and navigation wiring local. |
-| `KnowledgeRouteIds` helpers                                            | Decode route ids, resolve Knowledge route targets, and derive route labels for app-local breadcrumbs. |
-| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
-| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
-| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
-| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
-
-## Customization tiers
-
-1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
-2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
-3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
-
-## Codegen
-
-`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
-
-The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
-
-Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.
+| `KnowledgeRouteIds` helpers                                            | Decode route ids, resolve Knowledge route targets, and derive route labels for app-local breadcrumbs.          |
+| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`.             |
+| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                                               |
+| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`).                            |
+| `KnowledgeBodiesMap`                                                   | Type for the compiled MDX-component-by-node-id map. `@elevasis/ui` ships this type only, not a corpus.         |
+
+## Customization tiers
+
+1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
+2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
+3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
+
+## Codegen
+
+This package ships the machinery only, not a compiled corpus. Each consumer generates its own `knowledge-bodies.tsx` (matching `KnowledgeBodiesMap`) beside its own Organization Model and hands it to `ElevasisSystemsProvider` as the required `knowledgeBodies` prop. In the monorepo that lives at `packages/elevasis/core/config/knowledge/_generated/`, sourced from `canonicalOrganizationModel.knowledge.nodes`; in an external project it lives at `<project-root>/core/config/knowledge/_generated/`. Regenerate with `pnpm scaffold:sync` (or `pnpm knowledge:generate` for only the knowledge step).
+
+The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
+
+Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.

package/reference/rules/error-handling.md

@@ -1,5 +1,5 @@
 ---
-description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry
+description: Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry, /api/external error envelope
 paths:
   - operations/**
 ---
@@ -41,6 +41,17 @@ try {
 }
 ```
 
+## What Your Handler May Throw
+
+`ExecutionError` is the class to throw from workflow and agent code. It carries a `context` record
+and an `isRetryable()` the engine reads, which is why it is preferable to a bare `Error` -- a plain
+throw arrives at the platform with no classification and no structured context.
+
+Handler code runs in a worker thread, not in an API request. A throw there becomes an **execution
+failure** recorded against the execution -- it never becomes an HTTP response body, so there is no
+status code to pick and no envelope to shape. The envelope below is what you _receive_ when you call
+the platform's own API, not what your handler produces.
+
 ## No Auto-Retry
 
 The platform does NOT automatically retry failed steps. Your handler is responsible for retry logic. Check `PlatformToolError.retryable` to decide whether retrying is safe.
@@ -60,6 +71,44 @@ The platform does NOT automatically retry failed steps. Your handler is responsi
 | `credentials_invalid` | No        | Credential not found or expired   |
 | `validation_error`    | No        | Invalid parameters passed to tool |
 
+## Error Bodies From `/api/external/*`
+
+Every `/api/external/*` route returns the same error envelope. Tenants are the only consumers of
+these routes, so this is the shape your API-key client parses:
+
+```json
+{
+  "error": "human-readable message",
+  "code": "VALIDATION_ERROR",
+  "requestId": "correlates with server logs",
+  "fields": { "newResourceId": ["must differ from oldResourceId"] }
+}
+```
+
+`error` and `code` are always present. `requestId` is present on every error response -- quote it
+when reporting a problem. `fields` appears only when the request body itself failed schema
+validation. `retryAfter` (seconds) accompanies `RATE_LIMIT_EXCEEDED`, and `details` carries a
+structured payload on some conflicts.
+
+**`POST /api/external/resources/rename` changed shape -- read `code`, not just `error`.** It used to
+build `{ error, code }` by hand, and then briefly returned `code: "VALIDATION_ERROR"` with a 400 for
+_every_ failure, including ones that were not your fault. It now states the real cause:
+
+| Failure                                       | Status | `code`                             |
+| --------------------------------------------- | ------ | ---------------------------------- |
+| Body fails schema validation                  | 400    | `VALIDATION_ERROR` (with `fields`) |
+| `newResourceId` already has execution history | 409    | `CONFLICT`                         |
+| A database query or update failed             | 500    | `INTERNAL_SERVER_ERROR`            |
+
+A client that branched on "400 means my input was wrong" now needs to distinguish 409 (rename to a
+different id) from 500 (retry or report). A client reading only `error` as its diagnostic silently
+loses that distinction -- the message text is not a stable contract, and `code` is.
+
+**On any 5xx, `error` is generic by design.** The platform suppresses server-fault messages, so a 500
+reads `"Internal server error"` rather than what actually broke -- that sentence was written for
+whoever fixes the server, and it stays in the server's logs. `requestId` is what joins your failure
+to that log line, so quote it when you report a 5xx rather than the message.
+
 ## CLI Transport Failures
 
 These are errors in the CLI you type commands into, not in your handler code. They are worth knowing because the natural reaction to one of them is the wrong reaction.

package/reference/rules/execution.md

@@ -1,5 +1,5 @@
 ---
-description: Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints
+description: Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation
 paths:
   - operations/**
 ---
@@ -15,15 +15,71 @@ Each execution runs in an isolated Node.js worker thread spawned from the deploy
 
 ## Constraints
 
-| Constraint | Workflows                       | Agents                                                |
-| ---------- | ------------------------------- | ----------------------------------------------------- |
-| Timeout    | 300s (5 min)                    | 600s (10 min, configurable via `constraints.timeout`) |
-| Memory     | 256MB hard limit                | 256MB hard limit                                      |
-| Disk       | None (no persistent filesystem) | None                                                  |
+| Constraint | Workflows                       | Agents                                         |
+| ---------- | ------------------------------- | ---------------------------------------------- |
+| Timeout    | 2h execution ceiling            | 2h ceiling, lower it via `constraints.timeout` |
+| Memory     | 256MB hard limit                | 256MB hard limit                               |
+| Disk       | None (no persistent filesystem) | None                                           |
 
 - Platform enforces timeouts -- no handler code needed, worker terminates automatically.
 - Memory overflow crashes the worker. Other tenants are unaffected.
-- For long-running tasks, break work into multiple steps or use agents with extended timeout.
+- The ceiling is a safety net against a runaway loop, not a duration budget. Bound the work you
+  actually want bounded with a per-step `timeout` (below) or `constraints.timeout`, rather than
+  relying on the ceiling to stop it.
+
+## Per-Step Timeouts
+
+A workflow step may declare its own millisecond ceiling:
+
+| Field                  | Applies to    | Omitted                                               |
+| ---------------------- | ------------- | ----------------------------------------------------- |
+| `WorkflowStep.timeout` | one step      | the step is bounded only by the 2h execution ceiling  |
+| `constraints.timeout`  | a whole agent | the agent is bounded only by the 2h execution ceiling |
+
+`WorkflowConfig` has no `constraints` field on purpose. A per-workflow override would only restate
+the execution ceiling; "this HTTP call should never take more than 5 seconds" is a property of the
+step and has nowhere else to live.
+
+**The two timeout failures are not the same failure, and the difference is whether a retry can
+work.** A step that breaches its own `timeout` while the workflow still has budget left fails
+**retryably** -- a slow third-party call is exactly what a retry exists for. A workflow that reaches
+the 2h execution ceiling fails **non-retryably**: there is no budget left to retry inside. Neither
+error class is exported from `@elevasis/sdk`, so branch on your own step's outcome rather than on
+`instanceof`; the retryability distinction is what determines whether re-running is worth anything.
+
+Declare a `timeout` on any step that calls something you do not control. Without one, a hung
+integration call holds the whole workflow open for two hours.
+
+## Agent Spend Guards
+
+`maxIterations` and `timeout` bound how MANY model calls an agent makes and how LONG it runs.
+Neither bounds how much those calls cost. An agent on a large context or an expensive model can
+spend without limit inside a budget it is technically respecting. Three `AgentConstraints` fields
+close that:
+
+| Constraint               | Bounds                                           | Default             |
+| ------------------------ | ------------------------------------------------ | ------------------- |
+| `maxCostUsd`             | total USD across every AI call in the turn       | unset -- no ceiling |
+| `maxTotalTokens`         | total input + output tokens across every AI call | unset -- no ceiling |
+| `maxIdenticalIterations` | consecutive byte-identical plans before stopping | 3                   |
+
+Set at least one of the first two on any agent you are not watching. Unset is genuinely unbounded,
+not "bounded by something sensible".
+
+**Reaching a spend ceiling fails the execution.** The stop reason is `spend_exhausted`, and the
+worker reports `status: 'failed'` with `AgentSpendExhaustedError` -- deliberately, because an agent
+that stopped at its ceiling did not finish its work, and reporting that as success is what makes the
+failure mode invisible. Whatever the agent synthesized still travels on the failed result, so a
+partial answer is not lost.
+
+`spend_exhausted` is kept distinct from `budget_exhausted` (the `maxIterations` stop) because the
+right response differs: an agent out of iterations may just need a larger `maxIterations`, while one
+out of spend is the ceiling doing its job. Read the stop reason before raising either limit.
+
+Ceilings are enforced only where the platform injects a usage collector, which is every
+coordinator-run execution. Note that a **synchronous nested execution shares its parent's
+collector**, so a parent's ceiling covers the agent and everything it invokes synchronously -- and
+can therefore be reached by a child's spend.
 
 ## Concurrency
 

package/reference/scaffold/core/organization-model.mdx

@@ -51,7 +51,7 @@ Resource identity is authored inside `OrganizationModel.resources`. Runtime work
 
 ## System Shape
 
-`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `systems`; dotted paths such as `sales.crm` are derived from position in that tree. `subsystems` is a deprecated compatibility alias — it is still accepted and kept in sync with `systems` during parse, but new authoring should use `systems`. `parentSystemId` and `id` remain accepted compatibility fields during the migration.
+`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `systems`; dotted paths such as `sales.crm` are derived from position in that tree. `subsystems` is a deprecated compatibility alias — it is still accepted on input, but new authoring should use `systems`. Parsing does **not** copy `systems` into it: children come back under whichever key the author wrote, so read `system.systems ?? system.subsystems` rather than assuming either key is populated. `parentSystemId` and `id` remain accepted compatibility fields during the migration.
 
 {/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
 

package/reference/scaffold/recipes/customize-organization-model.md

@@ -103,7 +103,9 @@ System field reference:
 - `actions` -- references to the cross-cutting actions domain.
 - `ontology` -- System-owned object, link, action, catalog, event, surface, interface, value-type, property, or group records.
 - `config` -- JSON-serializable settings local to this System.
-- `systems` -- nested child Systems. Use this for new recursive authoring; `subsystems` is a compatibility alias only.
+- `systems` -- nested child Systems. Use this for new recursive authoring; `subsystems` is a retired spelling, accepted on input only.
+
+**A parsed model no longer carries children under both keys.** Parsing used to mirror `systems` into `subsystems`, so either spelling could be read off any parsed System. That mirror is gone: children now live under whichever key the author wrote. Anything walking the tree must read `system.systems ?? system.subsystems` -- reading `subsystems` alone looked correct only because the mirror was filling it in.
 
 ## Ontology
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -51,6 +51,7 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 | `useLeadGenConfig`, `LeadGenBuildConfig`, build-state helpers                                                                                                | `@elevasis/ui/features/lead-gen`            | Provider-backed derivation of stage catalog, build templates, default build steps, default template id, and export workflow id          |
 | `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenActionKey`                                                    | `@elevasis/ui/features/lead-gen`            | List Builder workflow registry, slot-based field contracts, and project-owned action wiring                                             |
 | `LeadGenRouteShell`                                                                                                                                          | `@elevasis/ui/features/lead-gen`            | Route shell helper (contact/company detail surfaces are now `ContactDetailPage` / `CompanyDetailPage` from `@elevasis/ui/features/crm`) |
+| `EMPLOYEE_RANGES`, `EmployeeRange`                                                                                                                           | `@elevasis/ui/features/lead-gen`            | Apollo's own employee-count brackets for an Apollo import form. Wire values are Apollo's; relabel by mapping, never by redeclaring      |
 | `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`                        | Headless list and telemetry data access                                                                                                 |
 | `useWorkflowExecution`, `useExecutionSSE`, `useAddCompaniesToList`, `useRemoveCompaniesFromList`, `useAddContactsToList`                                     | `@elevasis/ui/hooks`                        | List Builder workflow triggering, live execution tailing, and list membership mutations                                                 |
 | `useCompanies`, `useCompany`, `useContacts`, `useContact`                                                                                                    | `@elevasis/ui/hooks`                        | Acquisition company/contact data access                                                                                                 |
@@ -208,7 +209,7 @@ function RootLayoutComponent() {
 
 Data sourcing mode is list-wide. Read `list.pipelineConfig.dataMode` or the workflow-side `list.getConfig()` result when a workflow must choose mock versus live sourcing. Do not add per-action `mock` / `live` controls for Apollo, crawl, enrichment, or scoring steps. Export mode is separate: `preview` versus `export` controls whether a destination write happens.
 
-Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer. Omit the `advanced:` section when a step has none.
+Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer. Omit the `advanced:` section when a step has none.
 
 Available field component variants: `textinput`, `textarea`, `numberinput`, `switch`, `segmented`, `select`, `multiselect`, `tags`, `json`. Field hints support `label`, `description`, `placeholder`, `min`/`max`/`step` (numbers), `options` (selects), and `when: (values) => boolean` for conditional visibility.
 

package/reference/scaffold/reference/contracts.md

@@ -941,6 +941,13 @@ export interface ElevasisSystemsProviderProps {
   /** Registered topbar action modules. OM node presence controls visibility; module supplies behavior. */
   topbarActions?: TopbarActionModule[]
   organizationModel?: ElevasisOrganizationModel
+  /**
+   * Compiled knowledge-node body components for this consumer's own corpus.
+   * Required, not defaulted: a missing corpus must fail to compile at the
+   * provider mount rather than render a blank panel at runtime. See
+   * `knowledge-corpus-injection.mdx`.
+   */
+  knowledgeBodies: KnowledgeBodiesMap
   timeRange?: TimeRange
   operationsApiUrl?: string
   operationsSSEManager?: SSEConnectionManagerLike
@@ -964,6 +971,8 @@ export interface ElevasisSystemsContextValue {
   resolvedSystems: ResolvedSystemModule[]
   organizationGraph: OrganizationGraphContextValue
   organizationModel?: OrganizationModel
+  /** Compiled knowledge-node body components for this consumer's own corpus. See `ElevasisSystemsProviderProps.knowledgeBodies`. */
+  knowledgeBodies: KnowledgeBodiesMap
   timeRange?: TimeRange
   operationsApiUrl?: string
   operationsSSEManager?: SSEConnectionManagerLike
@@ -3142,45 +3151,45 @@ export const AcqSubstrateSchemas = {
 ### `Stateful`
 
 ```typescript
-/**
- * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
- * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
- * acq_lists / acq_list_members / acq_list_companies via Track B.
- */
-export interface Stateful {
-  pipeline_key: string
-  stage_key: string
-  state_key: string
-  activity_log: ActivityEvent[]
+/**
+ * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
+ * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
+ * acq_lists / acq_list_members / acq_list_companies via Track B.
+ */
+export interface Stateful {
+  pipeline_key: string
+  stage_key: string
+  state_key: string
+  activity_log: ActivityEvent[]
 }
 ```
 
 ### `TransitionItem`
 
 ```typescript
-/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
-export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
-  item: T,
-  transition: { stage_key?: string; state_key?: string; event: TEvent }
+/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
+export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
+  item: T,
+  transition: { stage_key?: string; state_key?: string; event: TEvent }
 ) => T
 ```
 
 ### `DeriveActions`
 
 ```typescript
-/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
+/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
 export type DeriveActions<T extends Stateful, TAction> = (item: T) => TAction[]
 ```
 
 ### `StatefulSchema`
 
 ```typescript
-export const StatefulSchema = z.object({
-  pipeline_key: z.string(),
-  stage_key: z.string(),
-  state_key: z.string(),
-  activity_log: z.array(ActivityEventSchema)
-})
+export const StatefulSchema = z.object({
+  pipeline_key: z.string(),
+  stage_key: z.string(),
+  state_key: z.string(),
+  activity_log: z.array(ActivityEventSchema)
+}) satisfies z.ZodType<Stateful>
 ```
 
 ### `StatefulStateDefinition`

package/reference/sdk/framework/project-structure.mdx

@@ -92,8 +92,6 @@ operations/
 │   ├── metadata.ts                    # Trigger/integration/human-checkpoint metadata (starts empty)
 │   ├── resource-registry.test.ts
 │   ├── README.md
-│   ├── __tests__/
-│   │   └── sdk-test-utils.compat.ts   # Shared test helpers -- assertResourceRegistry, runWorkflow
 │   ├── example/
 │   │   ├── echo.ts                    # Starter workflow
 │   │   ├── echo.test.ts
@@ -122,7 +120,7 @@ Convention seed for deployment mechanics that are not resource identity: trigger
 
 ### `operations/src/example/echo.ts`
 
-The starter workflow: one workflow per file with its own `config`, Zod `contract`, `steps` map, and `entryPoint`. Replace this domain with your own when ready. `operations/src/example/example-agent.ts` is the equivalent starter for an agent resource -- a minimal single-shot (non-session) `AgentDefinition` with no tools and no memory. Each has a matching `*.test.ts` file exercising it through the shared test helpers in `operations/src/__tests__/sdk-test-utils.compat.ts`.
+The starter workflow: one workflow per file with its own `config`, Zod `contract`, `steps` map, and `entryPoint`. Replace this domain with your own when ready. `operations/src/example/example-agent.ts` is the equivalent starter for an agent resource -- a minimal single-shot (non-session) `AgentDefinition` with no tools and no memory. Each has a matching `*.test.ts` file exercising it through the published test helpers -- `runLinearWorkflow` (imported as `runWorkflow`) and `assertResourceRegistry`, both from `@elevasis/sdk/test-utils`.
 
 ### `operations/src/email-notification/index.ts`
 

package/reference/ui/exports.mdx

@@ -33,7 +33,7 @@ description: "Auto-generated catalog of all published @elevasis/ui subpath expor
 | `@elevasis/ui/features/knowledge` | Features Knowledge | Features | Published knowledge feature manifest for downstream shells. |
 | `@elevasis/ui/features/notes` | Features Notes | Features | Published Notes panel view and supporting note components for shared right-panel integrations. |
 | `@elevasis/ui/features/right-panel-host` | Features Right Panel Host | Features | Published right-panel host provider, layer, trigger, keyboard shortcut, store, and view contract. |
-| `@elevasis/ui/knowledge` | Knowledge | Visual | Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the generated KNOWLEDGE_BODIES map. |
+| `@elevasis/ui/knowledge` | Knowledge | Visual | Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the KnowledgeBodiesMap type. Machinery only -- each consumer supplies its own compiled corpus via the required knowledgeBodies prop. |
 | `@elevasis/ui/vite` | Vite | Build | Composite Vite plugin factory (elevasisVite) that bundles all @elevasis/ui Vite plugins into a single array for consumer vite.config.ts files. |
 | `@elevasis/ui/vite-plugin-knowledge` | Vite Plugin Knowledge | Build | Vite plugin that regenerates the build-time knowledge MDX bodies and search index, with HMR support. |
 | `@elevasis/ui/features/settings` | Features Settings | Features | Published settings feature surface for downstream shells. |