@elevasis/sdk 1.55.0 → 1.56.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elevasis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @elevasis/sdk
+
+SDK for building Elevasis organization resources — agents, workflows, and the CLI that deploys them.
+
+## Install
+
+```sh
+pnpm add @elevasis/sdk
+```
+
+## Published surface
+
+| Subpath                      | Contains                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| `@elevasis/sdk`              | Resource definitions, the registry, and its validators                    |
+| `@elevasis/sdk/worker`       | The worker-thread authoring surface: `Agent`, `Workflow`, collectors      |
+| `@elevasis/sdk/node`         | Node-only helpers                                                         |
+| `@elevasis/sdk/test-utils`   | Test helpers for resource authors                                         |
+
+The package also installs an `elevasis-sdk` binary. Run `elevasis-sdk --help` for the command set;
+every authenticated command accepts `--prod` to target production rather than a local API.
+
+## Relationship to `@elevasis/core`
+
+The SDK inlines the `@repo/core` types it re-exports, so no `@elevasis/core` specifier survives in
+the shipped declarations. That makes the SDK a second sanctioned route onto capabilities core does
+not publish directly — import them from here rather than reaching for a core subpath that does not
+resolve.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli.cjs

@@ -49577,7 +49577,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@elevasis/sdk",
-      version: "1.55.0",
+      version: "1.56.0",
       description: "SDK for building Elevasis organization resources",
       type: "module",
       bin: {

package/dist/node/index.d.ts

@@ -44,15 +44,8 @@ interface KnowledgeNodeInput {
     summary: string;
     body: string;
 }
-interface KnowledgeSearchEntry {
-    id: string;
-    title: string;
-    summary: string;
-    bodyText: string;
-}
 interface CodegenResult {
     bodiesTsx: string;
-    searchIndex: KnowledgeSearchEntry[];
 }
 /**
  * Compiles knowledge nodes into generated file contents.
@@ -71,4 +64,4 @@ interface ResolvedKnowledgeLayout {
 declare function runKnowledgeCodegen(layout: ResolvedKnowledgeLayout): Promise<void>;
 
 export { generateKnowledgeBodies, generateKnowledgeNodes, generateKnowledgeNodesTs, readKnowledgeNodeMdx, runKnowledgeCodegen };
-export type { CodegenResult, GenerateKnowledgeNodesOptions, GenerateKnowledgeNodesResult, KnowledgeCodegenNode, KnowledgeKind, KnowledgeNodeInput, KnowledgeSearchEntry, ResolvedKnowledgeLayout };
+export type { CodegenResult, GenerateKnowledgeNodesOptions, GenerateKnowledgeNodesResult, KnowledgeCodegenNode, KnowledgeKind, KnowledgeNodeInput, ResolvedKnowledgeLayout };

package/dist/node/index.js

@@ -393,9 +393,6 @@ To add a component:
     );
   }
 }
-function stripToPlainText(body) {
-  return body.replace(/^(import|export)\s+.+$/gm, "").replace(/<[A-Z][^>]*>/g, "").replace(/<\/[A-Z][^>]*>/g, "").replace(/^#{1,6}\s+/gm, "").replace(/[*_`~]/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\n{3,}/g, "\n\n").trim();
-}
 var BODIES_HEADER = [
   "// @generated by generate-knowledge-bodies -- DO NOT EDIT",
   "// Regenerate: pnpm scaffold:sync",
@@ -457,11 +454,10 @@ async function generateKnowledgeBodies(nodes) {
       "> = {}",
       ""
     ].join("\n");
-    return { bodiesTsx: bodiesTsx2, searchIndex: [] };
+    return { bodiesTsx: bodiesTsx2 };
   }
   const nodeComments = [];
   const mapEntries = [];
-  const searchIndex = [];
   for (const node of nodes) {
     if (/^(import|export)\s+/m.test(node.body)) {
       throw new Error(
@@ -475,15 +471,13 @@ async function generateKnowledgeBodies(nodes) {
     });
     const fnBodyCode = String(compiled);
     validateComponents(node.id, fnBodyCode);
-    const bodyText = stripToPlainText(node.body);
-    searchIndex.push({ id: node.id, title: node.title, summary: node.summary, bodyText });
     nodeComments.push(`// Node: ${node.id} (${node.kind})`);
     mapEntries.push(`  '${node.id}': makeKnowledgeComponent(${JSON.stringify(fnBodyCode)})`);
   }
   const mapBlock = `export const KNOWLEDGE_BODIES: Record<string, ComponentType<KnowledgeBodyProps>> = {
 ` + mapEntries.join(",\n") + "\n}\n";
   const bodiesTsx = BODIES_HEADER + FACTORY_BLOCK + MAP_HEADER + (nodeComments.length > 0 ? nodeComments.join("\n") + "\n\n" : "") + mapBlock;
-  return { bodiesTsx, searchIndex };
+  return { bodiesTsx };
 }
 async function runKnowledgeCodegen(layout) {
   let nodes;
@@ -504,14 +498,9 @@ async function runKnowledgeCodegen(layout) {
     });
     nodes = result.nodes;
   }
-  const { bodiesTsx, searchIndex } = await generateKnowledgeBodies(nodes);
+  const { bodiesTsx } = await generateKnowledgeBodies(nodes);
   mkdirSync(layout.generatedDir, { recursive: true });
   writeFileSync(resolve(layout.generatedDir, "knowledge-bodies.tsx"), bodiesTsx, "utf8");
-  writeFileSync(
-    resolve(layout.generatedDir, "knowledge-search-index.json"),
-    JSON.stringify(searchIndex, null, 2) + "\n",
-    "utf8"
-  );
 }
 
 export { generateKnowledgeBodies, generateKnowledgeNodes, generateKnowledgeNodesTs, readKnowledgeNodeMdx, runKnowledgeCodegen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
     "zod": "^4.1.0",
-    "@repo/core": "0.71.0",
+    "@repo/core": "0.72.0",
     "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },

package/reference/_navigation.md

@@ -162,7 +162,7 @@ Package entries indexed: 63.
 | Theme | `packages/ui/src/theme/README.md` | Published theme entry for downstream applications. | (not specified) |
 | Graph | `packages/ui/src/graph/README.md` | Published graph helper and visualization entry. | (not specified) |
 | Theme Presets | `packages/ui/src/theme/presets/README.md` | Published THEME_PRESETS tuple, ThemePresetName union, and ThemePresetEnum Zod enum, defined locally and kept manually aligned with the canonical list in packages/core/src/auth/multi-tenancy/theme-presets.ts. | (not specified) |
-| Knowledge | `packages/ui/src/knowledge/README.md` | Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the generated KNOWLEDGE_BODIES map. | (not specified) |
+| Knowledge | `packages/ui/src/knowledge/README.md` | 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. | (not specified) |
 
 ---
 
@@ -226,9 +226,9 @@ Agent rules indexed: 19.
 | Platform | `rules/platform.md` | Platform conventions -- SDK workflows, agents, deployment, resource registry | Authoring a workflow or agent definition, or registering a resource in the registry. |
 | Deployment | `rules/deployment.md` | Deployment workflow -- check-first, dev vs prod, version bumping, common errors | Before any deploy -- a plain `run deploy` targets production by default. |
 | Content | `rules/content.md` | Building the content System behind the shipped pipeline, item, and distribution routes -- which recipe to read, and the catalog vocabulary that is model-owned rather than coded | Editing anything under `ui/src/routes/content/` -- items, pipelines, distributions, or a review gate. |
-| Execution Model | `rules/execution.md` | Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints | Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime. |
+| Execution Model | `rules/execution.md` | Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation | Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime. |
 | Agent Runtime | `rules/agent-runtime.md` | Agent runtime behavior -- iteration response shape, session memory and replay, prose normalization, and why a redeploy is what makes a platform fix live | Debugging an agent turn -- a missing reply, a corrupted one, a session that forgot, or an unenforced schema. |
-| Error Handling | `rules/error-handling.md` | Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry | Writing or debugging a step handler that throws, catches, or retries. |
+| Error Handling | `rules/error-handling.md` | Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry, /api/external error envelope | Writing or debugging a step handler that throws, catches, or retries. |
 | Observability | `rules/observability.md` | Observability -- context.logger API, execution inspection, step-level context | Adding logging to a step handler, or inspecting a past execution. |
 
 ### Orientation

package/reference/_reference-manifest.json

@@ -875,7 +875,7 @@
       "subpath": "./knowledge",
       "kind": "subpath",
       "title": "Knowledge",
-      "description": "Published knowledge browser primitives: Browser, Tree, NodeList, NodeView, SearchBar, MDX provider, and the generated KNOWLEDGE_BODIES map.",
+      "description": "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.",
       "group": "Visual",
       "order": 3,
       "sourcePath": "packages/ui/src/knowledge/index.ts",
@@ -948,7 +948,7 @@
     {
       "packageName": "@elevasis/sdk",
       "title": "Execution Model",
-      "description": "Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints",
+      "description": "Execution model -- per-step and agent timeouts, spend ceilings, memory, concurrency, org isolation",
       "group": "Operations",
       "order": 4,
       "loadWhen": "Hitting a timeout, memory ceiling, concurrency limit, or org-isolation question at runtime.",
@@ -968,7 +968,7 @@
     {
       "packageName": "@elevasis/sdk",
       "title": "Error Handling",
-      "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",
       "group": "Operations",
       "order": 6,
       "loadWhen": "Writing or debugging a step handler that throws, catches, or retries.",

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/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/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

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. |