@elevasis/ui 2.30.0 → 2.32.0

package/dist/{chunk-CLUP5H3C.js → knowledge-search-index-5KYPO746.js}

@@ -1,775 +1,4 @@
-import { SemanticIcon } from './chunk-JCGD4GM6.js';
-import { Stack, Group, Title, Text, Box, Divider, useTree, Tree, UnstyledButton, TextInput } from '@mantine/core';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { useMemo, useState, useRef, useEffect } from 'react';
-import { useClipboard } from '@mantine/hooks';
-import { IconChevronDown, IconChevronRight, IconX, IconSearch, IconCheck, IconCopy } from '@tabler/icons-react';
-
-// src/knowledge/iconTokens.ts
-var KNOWLEDGE_ICON_TOKEN_BY_KIND = {
-  playbook: "knowledge.playbook",
-  strategy: "knowledge.strategy",
-  reference: "knowledge.reference"
-};
-function getKnowledgeIconToken(node) {
-  return node.icon ?? KNOWLEDGE_ICON_TOKEN_BY_KIND[node.kind];
-}
-
-// ../core/src/knowledge/queries.ts
-function buildKnowledgeSourceIdMap(graph) {
-  const map = /* @__PURE__ */ new Map();
-  for (const node of graph.nodes) {
-    if (node.kind === "knowledge" && node.sourceId) {
-      map.set(node.id, node.sourceId);
-    }
-  }
-  return map;
-}
-function byFeature(graph, featureId, knowledgeNodes) {
-  const targetGraphNodeId = `feature:${featureId}`;
-  const governingKnowledgeNodeIds = /* @__PURE__ */ new Set();
-  for (const edge of graph.edges) {
-    if (edge.kind === "governs" && edge.targetId === targetGraphNodeId && edge.sourceId.startsWith("knowledge:")) {
-      governingKnowledgeNodeIds.add(edge.sourceId);
-    }
-  }
-  const sourceIdMap = buildKnowledgeSourceIdMap(graph);
-  const matchingOmIds = /* @__PURE__ */ new Set();
-  for (const graphNodeId of governingKnowledgeNodeIds) {
-    const omId = sourceIdMap.get(graphNodeId);
-    if (omId) matchingOmIds.add(omId);
-  }
-  return knowledgeNodes.filter((n) => matchingOmIds.has(n.id));
-}
-function byKind(_graph, kind, knowledgeNodes) {
-  return knowledgeNodes.filter((n) => n.kind === kind);
-}
-var KIND_CHIP_TONE_STYLES = {
-  subtle: {
-    backgroundColor: "var(--color-surface-hover)",
-    borderColor: "var(--color-border)",
-    color: "var(--color-text-dimmed)"
-  },
-  primary: {
-    backgroundColor: "var(--surface-primary-subtle)",
-    borderColor: "color-mix(in srgb, var(--color-primary) 28%, var(--color-border))",
-    color: "var(--color-primary)"
-  },
-  muted: {
-    backgroundColor: "var(--color-surface)",
-    borderColor: "var(--color-border)",
-    color: "var(--color-text-subtle)"
-  }
-};
-function KindChip({ kind, tone = "subtle", style, ...spanProps }) {
-  return /* @__PURE__ */ jsx(
-    "span",
-    {
-      ...spanProps,
-      "data-kind-chip": true,
-      "data-tone": tone,
-      style: {
-        display: "inline-flex",
-        alignItems: "center",
-        width: "fit-content",
-        maxWidth: "100%",
-        padding: "2px 8px",
-        border: "1px solid",
-        borderRadius: "var(--mantine-radius-sm)",
-        fontFamily: "var(--mantine-font-family)",
-        fontSize: "var(--mantine-font-size-xs)",
-        fontWeight: 600,
-        lineHeight: 1.2,
-        letterSpacing: 0,
-        whiteSpace: "nowrap",
-        transition: "background-color var(--duration-fast) var(--easing), border-color var(--duration-fast) var(--easing)",
-        ...KIND_CHIP_TONE_STYLES[tone],
-        ...style
-      },
-      children: kind
-    }
-  );
-}
-function NodeHeader({
-  title,
-  kind,
-  tone = "primary",
-  iconToken,
-  description,
-  updatedAt,
-  rightSection
-}) {
-  return /* @__PURE__ */ jsxs(Stack, { gap: "xs", children: [
-    /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "flex-start", wrap: "nowrap", children: [
-      iconToken && /* @__PURE__ */ jsx(
-        SemanticIcon,
-        {
-          token: iconToken,
-          fallbackKind: "knowledge",
-          size: 22,
-          style: { color: "var(--color-primary)", marginTop: 5 }
-        }
-      ),
-      /* @__PURE__ */ jsx(Title, { order: 3, style: { flex: 1, minWidth: 0, color: "var(--color-text)" }, children: title }),
-      /* @__PURE__ */ jsx(KindChip, { kind, tone, style: { flexShrink: 0, marginTop: 4 } }),
-      rightSection
-    ] }),
-    description && /* @__PURE__ */ jsx(Text, { size: "sm", c: "dimmed", style: { lineHeight: 1.5 }, children: description }),
-    updatedAt && /* @__PURE__ */ jsxs(Text, { size: "xs", c: "dimmed", style: { opacity: 0.7 }, children: [
-      "Updated ",
-      updatedAt
-    ] })
-  ] });
-}
-function EdgeChip({ id, onClick }) {
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      role: onClick ? "button" : void 0,
-      tabIndex: onClick ? 0 : void 0,
-      onClick,
-      onKeyDown: onClick ? (e) => (e.key === "Enter" || e.key === " ") && onClick() : void 0,
-      style: {
-        display: "inline-flex",
-        alignItems: "center",
-        padding: "2px 8px",
-        borderRadius: "var(--mantine-radius-sm)",
-        backgroundColor: "var(--color-surface)",
-        border: "1px solid var(--color-border)",
-        fontSize: "var(--mantine-font-size-xs)",
-        color: onClick ? "var(--color-primary)" : "var(--color-text-subtle)",
-        cursor: onClick ? "pointer" : "default",
-        fontFamily: "var(--mantine-font-family-monospace)",
-        width: "fit-content",
-        background: "none"
-      },
-      children: id
-    }
-  );
-}
-function EdgeGroup({ label, ids, onNavigateToNode }) {
-  return /* @__PURE__ */ jsxs(Stack, { gap: 4, children: [
-    /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", fw: 500, children: label }),
-    ids.map((id) => /* @__PURE__ */ jsx(EdgeChip, { id, onClick: onNavigateToNode ? () => onNavigateToNode(id) : void 0 }, id))
-  ] });
-}
-function knowledgeNodeIdFromGraphNode(graphNode, graphNodeId) {
-  if (graphNode?.sourceId) return graphNode.sourceId;
-  return graphNodeId.startsWith("knowledge:") ? graphNodeId.slice("knowledge:".length) : graphNodeId;
-}
-function RelatedKnowledgeSection({
-  nodeId,
-  graph,
-  knowledgeNodes,
-  onNavigateToNode
-}) {
-  const knowledgeById = new Map(knowledgeNodes.map((node) => [node.id, node]));
-  const cards = graph.edges.filter((edge) => edge.kind === "governs" && edge.targetId === nodeId).map((edge) => {
-    const graphNode = graph.nodes.find((node) => node.id === edge.sourceId && node.kind === "knowledge");
-    const knowledgeNode = knowledgeById.get(knowledgeNodeIdFromGraphNode(graphNode, edge.sourceId));
-    return knowledgeNode ? { graphNodeId: edge.sourceId, node: knowledgeNode } : null;
-  }).filter((card) => card !== null);
-  if (cards.length === 0) return null;
-  return /* @__PURE__ */ jsxs(Stack, { gap: "xs", "data-related-knowledge-section": true, children: [
-    /* @__PURE__ */ jsx(Text, { size: "xs", fw: 600, tt: "uppercase", c: "dimmed", style: { letterSpacing: "0.05em" }, children: "Governing Knowledge" }),
-    /* @__PURE__ */ jsx(Stack, { gap: "xs", children: cards.map(({ graphNodeId, node }) => /* @__PURE__ */ jsx(
-      Box,
-      {
-        component: onNavigateToNode ? "button" : "article",
-        type: onNavigateToNode ? "button" : void 0,
-        onClick: onNavigateToNode ? () => onNavigateToNode(graphNodeId) : void 0,
-        style: {
-          display: "block",
-          width: "100%",
-          padding: "var(--mantine-spacing-sm)",
-          border: "1px solid var(--color-border)",
-          borderRadius: "var(--mantine-radius-sm)",
-          background: "var(--color-surface)",
-          color: "var(--color-text)",
-          textAlign: "left",
-          cursor: onNavigateToNode ? "pointer" : "default",
-          font: "inherit"
-        },
-        children: /* @__PURE__ */ jsxs(Stack, { gap: 4, children: [
-          /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "flex-start", wrap: "nowrap", children: [
-            /* @__PURE__ */ jsx(
-              SemanticIcon,
-              {
-                token: getKnowledgeIconToken(node),
-                fallbackKind: node.kind,
-                size: 16,
-                style: { color: "var(--color-text-subtle)", marginTop: 1 }
-              }
-            ),
-            /* @__PURE__ */ jsx(Text, { size: "sm", fw: 600, style: { flex: 1, minWidth: 0, lineHeight: 1.35 }, children: node.title }),
-            /* @__PURE__ */ jsx(KindChip, { kind: node.kind, tone: "muted", style: { flexShrink: 0 } })
-          ] }),
-          /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { lineHeight: 1.45 }, children: node.summary })
-        ] })
-      },
-      node.id
-    )) })
-  ] });
-}
-function relatedIds(graph, nodeId, edgeKind, direction, targetKind) {
-  return graph.edges.filter(
-    (edge) => direction === "outgoing" ? edge.kind === edgeKind && edge.sourceId === nodeId : edge.kind === edgeKind && edge.targetId === nodeId
-  ).map((edge) => direction === "outgoing" ? edge.targetId : edge.sourceId).filter((id) => {
-    if (!targetKind) return true;
-    return graph.nodes.find((node) => node.id === id)?.kind === targetKind;
-  });
-}
-function EdgeRelationshipGroup({ nodeId, graph, knowledgeNodes, onNavigateToNode }) {
-  const subFeatures = relatedIds(graph, nodeId, "contains", "outgoing", "feature");
-  const resourcesUsed = relatedIds(graph, nodeId, "uses", "outgoing", "resource");
-  const entities = relatedIds(graph, nodeId, "operates-on", "outgoing", "entity");
-  const governedTargets = relatedIds(graph, nodeId, "governs", "outgoing");
-  const governingKnowledge = relatedIds(graph, nodeId, "governs", "incoming", "knowledge");
-  const hasRelationships = subFeatures.length > 0 || resourcesUsed.length > 0 || entities.length > 0 || governedTargets.length > 0 || governingKnowledge.length > 0;
-  if (!hasRelationships) return null;
-  return /* @__PURE__ */ jsxs(Stack, { gap: "xs", "data-edge-relationship-group": true, children: [
-    /* @__PURE__ */ jsx(Divider, {}),
-    /* @__PURE__ */ jsx(Text, { size: "xs", fw: 600, tt: "uppercase", c: "dimmed", style: { letterSpacing: "0.05em" }, children: "Relationships" }),
-    subFeatures.length > 0 && /* @__PURE__ */ jsx(
-      EdgeGroup,
-      {
-        label: `Sub-features (${subFeatures.length})`,
-        ids: subFeatures,
-        onNavigateToNode
-      }
-    ),
-    resourcesUsed.length > 0 && /* @__PURE__ */ jsx(
-      EdgeGroup,
-      {
-        label: `Resources used (${resourcesUsed.length})`,
-        ids: resourcesUsed,
-        onNavigateToNode
-      }
-    ),
-    entities.length > 0 && /* @__PURE__ */ jsx(EdgeGroup, { label: `Entities (${entities.length})`, ids: entities, onNavigateToNode }),
-    governedTargets.length > 0 && /* @__PURE__ */ jsx(
-      EdgeGroup,
-      {
-        label: `Governs (${governedTargets.length})`,
-        ids: governedTargets,
-        onNavigateToNode
-      }
-    ),
-    governingKnowledge.length > 0 && (knowledgeNodes ? /* @__PURE__ */ jsx(
-      RelatedKnowledgeSection,
-      {
-        nodeId,
-        graph,
-        knowledgeNodes,
-        onNavigateToNode
-      }
-    ) : /* @__PURE__ */ jsx(
-      EdgeGroup,
-      {
-        label: `Governing knowledge (${governingKnowledge.length})`,
-        ids: governingKnowledge,
-        onNavigateToNode
-      }
-    ))
-  ] });
-}
-var PRESENTATION_METADATA_KEYS = /* @__PURE__ */ new Set(["label", "description"]);
-function formatMetadataLabel(key) {
-  return key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (char) => char.toUpperCase());
-}
-function NodeMetadataFooter({ node, title = "Technical metadata" }) {
-  const entries = Object.entries(node).filter(
-    ([key, value]) => !PRESENTATION_METADATA_KEYS.has(key) && value !== void 0 && value !== null && typeof value !== "object"
-  );
-  if (entries.length === 0) return null;
-  return /* @__PURE__ */ jsxs(
-    Box,
-    {
-      component: "details",
-      style: {
-        borderTop: "1px solid var(--color-border)",
-        paddingTop: "var(--mantine-spacing-sm)"
-      },
-      children: [
-        /* @__PURE__ */ jsx(
-          Box,
-          {
-            component: "summary",
-            style: {
-              cursor: "pointer",
-              color: "var(--color-text-dimmed)",
-              fontSize: "var(--mantine-font-size-xs)",
-              fontWeight: 600,
-              letterSpacing: "0.05em",
-              textTransform: "uppercase"
-            },
-            children: title
-          }
-        ),
-        /* @__PURE__ */ jsx(Stack, { gap: 4, style: { paddingTop: "var(--mantine-spacing-xs)" }, children: entries.map(([key, value]) => /* @__PURE__ */ jsx(KeyField, { label: formatMetadataLabel(key), value: String(value) }, key)) })
-      ]
-    }
-  );
-}
-function NodeDescribeShell({ header, content, relationships, footer }) {
-  return /* @__PURE__ */ jsxs(Stack, { gap: "md", style: { padding: "var(--mantine-spacing-md)", width: "100%" }, children: [
-    header,
-    content && /* @__PURE__ */ jsxs(Fragment, { children: [
-      header && /* @__PURE__ */ jsx(Divider, {}),
-      content
-    ] }),
-    relationships,
-    footer
-  ] });
-}
-function KeyField({ label, value }) {
-  return /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "baseline", children: [
-    /* @__PURE__ */ jsx(Text, { size: "xs", fw: 500, c: "dimmed", style: { minWidth: 96 }, children: label }),
-    /* @__PURE__ */ jsx(Text, { size: "sm", style: { fontFamily: "var(--mantine-font-family-monospace)" }, children: value })
-  ] });
-}
-var FEATURE_PREFIX = "feat:";
-var LEAF_PREFIX = "leaf:";
-var FOLDER_PREFIX = "folder:";
-var GROUP_THRESHOLD = 8;
-var SIDEBAR_TREE_ACCENT_COLOR = "var(--color-primary)";
-var FOLDER_ORDER = [
-  "campaigns",
-  "pipeline",
-  "targeting",
-  "channels",
-  "proof",
-  "references",
-  "playbooks",
-  "strategies"
-];
-var FOLDER_LABELS = {
-  campaigns: "Campaigns",
-  pipeline: "Pipeline",
-  targeting: "Targeting and Strategy",
-  channels: "Channels",
-  proof: "Proof",
-  references: "References",
-  playbooks: "Playbooks",
-  strategies: "Strategies"
-};
-function toBareFeatureId(graphNodeId) {
-  return graphNodeId.startsWith("feature:") ? graphNodeId.slice("feature:".length) : graphNodeId;
-}
-function topLevelFeatureIds(allBareIds) {
-  return allBareIds.filter((id) => !id.includes("."));
-}
-function childFeatureIds(allBareIds, parentId) {
-  const prefix = `${parentId}.`;
-  return allBareIds.filter((id) => id.startsWith(prefix) && !id.slice(prefix.length).includes("."));
-}
-function featureHasKnowledgeDescendant(bareId, allBareIds, graph, knowledgeNodes) {
-  if (byFeature(graph, bareId, knowledgeNodes).length > 0) return true;
-  return childFeatureIds(allBareIds, bareId).some(
-    (childId) => featureHasKnowledgeDescendant(childId, allBareIds, graph, knowledgeNodes)
-  );
-}
-function buildFeatureMetaMap(graph) {
-  const map = {};
-  for (const node of graph.nodes) {
-    if (node.kind === "feature") {
-      map[toBareFeatureId(node.id)] = { label: node.label, icon: node.icon, node };
-    }
-  }
-  return map;
-}
-function getKnowledgeReadCommand(nodeId) {
-  return `/knowledge read ${nodeId}`;
-}
-function getKnowledgeReadCommands(nodeIds) {
-  return [...new Set(nodeIds)].map(getKnowledgeReadCommand).join("\n");
-}
-function getKnowledgeReadFeatureFolderCommand(bareFeatureId) {
-  return `/knowledge read-folder feature:${bareFeatureId}`;
-}
-function getKnowledgeFolderKey(node) {
-  const key = `${node.id} ${node.title}`.toLowerCase();
-  if (/\b(stage|booking|discovery|pipeline|communications?)\b/.test(key)) return "pipeline";
-  if (/\b(upwork scanning|youtube|obs|recording|reddit|social)\b/.test(key)) return "channels";
-  if (/\b(testimonials?|case stud|proof)\b/.test(key)) return "proof";
-  if (/\b(target|personalization|vertical|calibration|query|research|strategy)\b/.test(key)) return "targeting";
-  if (/\b(outreach|campaign|copy|handoff|bounce|reply|lead-gen playbook)\b/.test(key)) return "campaigns";
-  if (node.kind === "reference") return "references";
-  if (node.kind === "strategy") return "strategies";
-  return "playbooks";
-}
-function sortFolderKeys(left, right) {
-  const leftIndex = FOLDER_ORDER.indexOf(left);
-  const rightIndex = FOLDER_ORDER.indexOf(right);
-  if (leftIndex === -1 && rightIndex === -1) return left.localeCompare(right);
-  if (leftIndex === -1) return 1;
-  if (rightIndex === -1) return -1;
-  return leftIndex - rightIndex;
-}
-function createKnowledgeLeaf(bareId, node) {
-  return {
-    value: `${LEAF_PREFIX}${bareId}::${node.id}`,
-    label: node.title,
-    nodeType: "leaf",
-    knowledgeNodeId: node.id,
-    knowledgeNodeIds: [node.id]
-  };
-}
-function createKnowledgeLeaves(bareId, nodes) {
-  if (nodes.length < GROUP_THRESHOLD) {
-    return nodes.map((node) => createKnowledgeLeaf(bareId, node));
-  }
-  const grouped = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    const folderKey = getKnowledgeFolderKey(node);
-    const folderNodes = grouped.get(folderKey) ?? [];
-    folderNodes.push(node);
-    grouped.set(folderKey, folderNodes);
-  }
-  return [...grouped.entries()].sort(([left], [right]) => sortFolderKeys(left, right)).map(([folderKey, folderNodes]) => ({
-    value: `${FOLDER_PREFIX}${bareId}::${folderKey}`,
-    label: FOLDER_LABELS[folderKey] ?? folderKey,
-    nodeType: "folder",
-    icon: "knowledge.playbook",
-    knowledgeNodeIds: folderNodes.map((node) => node.id),
-    children: folderNodes.map((node) => createKnowledgeLeaf(bareId, node))
-  }));
-}
-function collectKnowledgeNodeIds(node) {
-  if (node.knowledgeNodeIds) return node.knowledgeNodeIds;
-  return (node.children ?? []).flatMap(collectKnowledgeNodeIds);
-}
-function buildFeatureTreeNode(bareId, allBareIds, featureMetaMap, graph, knowledgeNodes) {
-  const governing = byFeature(graph, bareId, knowledgeNodes);
-  const childIds = childFeatureIds(allBareIds, bareId);
-  const childFeatureNodes = childIds.filter((childId) => featureHasKnowledgeDescendant(childId, allBareIds, graph, knowledgeNodes)).map((childId) => buildFeatureTreeNode(childId, allBareIds, featureMetaMap, graph, knowledgeNodes));
-  const knowledgeLeaves = createKnowledgeLeaves(bareId, governing);
-  const children = [...childFeatureNodes, ...knowledgeLeaves];
-  const meta = featureMetaMap[bareId];
-  return {
-    value: `${FEATURE_PREFIX}${bareId}`,
-    label: meta?.label ?? bareId,
-    nodeType: "feature",
-    icon: meta?.icon,
-    knowledgeNodeIds: children.flatMap(collectKnowledgeNodeIds),
-    children: children.length > 0 ? children : void 0
-  };
-}
-function collectExpandableValues(nodes, acc = {}) {
-  for (const node of nodes) {
-    if (typeof node.value === "string" && (node.value.startsWith(FEATURE_PREFIX) || node.value.startsWith(FOLDER_PREFIX))) {
-      acc[node.value] = true;
-    }
-    if (node.children) {
-      collectExpandableValues(node.children, acc);
-    }
-  }
-  return acc;
-}
-function KnowledgeTree({
-  graph,
-  knowledgeNodes,
-  onSelectNode,
-  onSelectGraphNode,
-  selectedNodeId
-}) {
-  const treeData = useMemo(() => {
-    const featureMetaMap = buildFeatureMetaMap(graph);
-    const allBareIds = Object.keys(featureMetaMap);
-    const topIds = topLevelFeatureIds(allBareIds);
-    return topIds.filter((bareId) => featureHasKnowledgeDescendant(bareId, allBareIds, graph, knowledgeNodes)).map((bareId) => buildFeatureTreeNode(bareId, allBareIds, featureMetaMap, graph, knowledgeNodes));
-  }, [graph, knowledgeNodes]);
-  const initialExpandedState = useMemo(() => collectExpandableValues(treeData), [treeData]);
-  const treeController = useTree({ initialExpandedState });
-  const leafNodeMap = useMemo(() => {
-    const map = /* @__PURE__ */ new Map();
-    for (const node of knowledgeNodes) {
-      for (const graphNode of graph.nodes) {
-        if (graphNode.kind === "feature") {
-          const bareId = toBareFeatureId(graphNode.id);
-          map.set(`${LEAF_PREFIX}${bareId}::${node.id}`, node);
-        }
-      }
-    }
-    return map;
-  }, [graph, knowledgeNodes]);
-  const featureKnowledgeCountMap = useMemo(() => {
-    const counts = /* @__PURE__ */ new Map();
-    for (const graphNode of graph.nodes) {
-      if (graphNode.kind === "feature") {
-        const bareId = toBareFeatureId(graphNode.id);
-        counts.set(bareId, byFeature(graph, bareId, knowledgeNodes).length);
-      }
-    }
-    return counts;
-  }, [graph, knowledgeNodes]);
-  const featureGraphNodeMap = useMemo(() => {
-    const map = /* @__PURE__ */ new Map();
-    for (const graphNode of graph.nodes) {
-      if (graphNode.kind === "feature") {
-        map.set(toBareFeatureId(graphNode.id), graphNode);
-      }
-    }
-    return map;
-  }, [graph]);
-  if (treeData.length === 0) {
-    return /* @__PURE__ */ jsx(Text, { size: "sm", c: "dimmed", style: { padding: "var(--mantine-spacing-md)" }, children: "No features in graph." });
-  }
-  return /* @__PURE__ */ jsx(
-    Tree,
-    {
-      data: treeData,
-      tree: treeController,
-      style: { padding: "var(--mantine-spacing-xs)" },
-      renderNode: ({ node, expanded, hasChildren, elementProps }) => {
-        const value = node.value;
-        const typedNode = node;
-        if (typeof value === "string" && value.startsWith(LEAF_PREFIX)) {
-          const knowledgeNode = leafNodeMap.get(value);
-          if (!knowledgeNode) return null;
-          return /* @__PURE__ */ jsx(
-            KnowledgeLeafRow,
-            {
-              elementProps,
-              knowledgeNode,
-              isActive: knowledgeNode.id === selectedNodeId,
-              onSelectNode
-            }
-          );
-        }
-        if (typeof value === "string" && value.startsWith(FOLDER_PREFIX)) {
-          return /* @__PURE__ */ jsx(
-            DirectoryRow,
-            {
-              elementProps,
-              expanded,
-              hasChildren,
-              label: String(node.label),
-              iconToken: typedNode.icon,
-              count: typedNode.knowledgeNodeIds?.length ?? 0,
-              command: getKnowledgeReadCommands(typedNode.knowledgeNodeIds ?? []),
-              isActive: false
-            }
-          );
-        }
-        const bareId = typeof value === "string" && value.startsWith(FEATURE_PREFIX) ? value.slice(FEATURE_PREFIX.length) : String(value);
-        const count = featureKnowledgeCountMap.get(bareId) ?? 0;
-        const graphNode = featureGraphNodeMap.get(bareId);
-        const isActive = graphNode !== void 0 && (selectedNodeId === graphNode.id || selectedNodeId === graphNode.sourceId || selectedNodeId === bareId);
-        return /* @__PURE__ */ jsx(
-          DirectoryRow,
-          {
-            elementProps,
-            expanded,
-            hasChildren,
-            label: String(node.label),
-            iconToken: typedNode.icon,
-            count,
-            command: getKnowledgeReadFeatureFolderCommand(bareId),
-            isActive,
-            uppercase: true,
-            onSelectGraphNode: graphNode ? () => onSelectGraphNode?.(graphNode) : void 0
-          }
-        );
-      }
-    }
-  );
-}
-function CopyCommandControl({ command, label, visible }) {
-  const clipboard = useClipboard({ timeout: 1500 });
-  if (!command) return null;
-  return /* @__PURE__ */ jsx(
-    "span",
-    {
-      role: "button",
-      tabIndex: 0,
-      "aria-label": label,
-      onClick: (event) => {
-        event.preventDefault();
-        event.stopPropagation();
-        clipboard.copy(command);
-      },
-      onKeyDown: (event) => {
-        if (event.key !== "Enter" && event.key !== " ") return;
-        event.preventDefault();
-        event.stopPropagation();
-        clipboard.copy(command);
-      },
-      style: {
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        width: 22,
-        height: 22,
-        flexShrink: 0,
-        opacity: visible ? 1 : 0,
-        pointerEvents: visible ? "auto" : "none",
-        color: clipboard.copied ? "var(--color-primary)" : "var(--color-text-subtle)",
-        transition: "opacity 120ms ease, color 120ms ease"
-      },
-      children: clipboard.copied ? /* @__PURE__ */ jsx(IconCheck, { size: 14 }) : /* @__PURE__ */ jsx(IconCopy, { size: 14 })
-    }
-  );
-}
-function KnowledgeLeafRow({ elementProps, knowledgeNode, isActive, onSelectNode }) {
-  const [hovered, setHovered] = useState(false);
-  return /* @__PURE__ */ jsx(
-    UnstyledButton,
-    {
-      ...elementProps,
-      onMouseEnter: (event) => {
-        elementProps.onMouseEnter?.(event);
-        setHovered(true);
-      },
-      onMouseLeave: (event) => {
-        elementProps.onMouseLeave?.(event);
-        setHovered(false);
-      },
-      onClick: () => onSelectNode(knowledgeNode),
-      style: {
-        ...elementProps.style ?? {},
-        padding: "5px 8px 5px 24px",
-        borderRadius: "var(--mantine-radius-sm)",
-        backgroundColor: isActive ? "color-mix(in srgb, var(--color-primary) 10%, transparent)" : hovered ? "var(--color-surface-hover)" : "transparent",
-        width: "100%",
-        textAlign: "left",
-        display: "block"
-      },
-      children: /* @__PURE__ */ jsxs(Group, { gap: "xs", wrap: "nowrap", children: [
-        /* @__PURE__ */ jsx(
-          SemanticIcon,
-          {
-            token: getKnowledgeIconToken(knowledgeNode),
-            fallbackKind: knowledgeNode.kind,
-            size: 15,
-            style: { color: SIDEBAR_TREE_ACCENT_COLOR }
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          Text,
-          {
-            size: "sm",
-            c: isActive ? "var(--color-primary)" : hovered ? "var(--color-text)" : void 0,
-            fw: isActive ? 600 : 400,
-            style: { flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
-            children: knowledgeNode.title
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          CopyCommandControl,
-          {
-            command: getKnowledgeReadCommand(knowledgeNode.id),
-            label: "Copy knowledge command",
-            visible: hovered
-          }
-        )
-      ] })
-    }
-  );
-}
-function DirectoryRow({
-  elementProps,
-  expanded,
-  hasChildren,
-  label,
-  iconToken,
-  count,
-  command,
-  isActive,
-  uppercase = false,
-  onSelectGraphNode
-}) {
-  const [hovered, setHovered] = useState(false);
-  return /* @__PURE__ */ jsxs(
-    Group,
-    {
-      ...elementProps,
-      gap: "xs",
-      onMouseEnter: (event) => {
-        elementProps.onMouseEnter?.(event);
-        setHovered(true);
-      },
-      onMouseLeave: (event) => {
-        elementProps.onMouseLeave?.(event);
-        setHovered(false);
-      },
-      onClick: (event) => {
-        elementProps.onClick?.(event);
-        onSelectGraphNode?.();
-      },
-      style: {
-        ...elementProps.style ?? {},
-        padding: "4px 8px",
-        borderRadius: "var(--mantine-radius-sm)",
-        backgroundColor: isActive ? "color-mix(in srgb, var(--color-primary) 10%, transparent)" : hovered ? "var(--color-surface-hover)" : "transparent",
-        cursor: onSelectGraphNode || hasChildren ? "pointer" : "default",
-        userSelect: "none"
-      },
-      children: [
-        hasChildren ? /* @__PURE__ */ jsx(
-          "span",
-          {
-            "aria-hidden": "true",
-            style: {
-              display: "inline-flex",
-              alignItems: "center",
-              justifyContent: "center",
-              width: 12,
-              height: 12,
-              color: SIDEBAR_TREE_ACCENT_COLOR,
-              flexShrink: 0
-            },
-            children: expanded ? /* @__PURE__ */ jsx(IconChevronDown, { size: 12, stroke: 2 }) : /* @__PURE__ */ jsx(IconChevronRight, { size: 12, stroke: 2 })
-          }
-        ) : /* @__PURE__ */ jsx(Text, { size: "xs", style: { width: 12, flexShrink: 0 } }),
-        /* @__PURE__ */ jsx(
-          SemanticIcon,
-          {
-            token: iconToken,
-            fallbackKind: "feature",
-            size: 14,
-            style: { color: SIDEBAR_TREE_ACCENT_COLOR }
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          Text,
-          {
-            size: "xs",
-            fw: isActive ? 700 : 600,
-            tt: uppercase ? "uppercase" : void 0,
-            c: isActive ? "var(--color-primary)" : hovered ? "var(--color-text)" : void 0,
-            style: {
-              letterSpacing: uppercase ? "0.05em" : 0,
-              flex: 1,
-              minWidth: 0,
-              overflow: "hidden",
-              textOverflow: "ellipsis",
-              whiteSpace: "nowrap"
-            },
-            children: label
-          }
-        ),
-        /* @__PURE__ */ jsx(TrailingCopySlot, { count, command, label: "Copy folder knowledge commands", showCopy: hovered })
-      ]
-    }
-  );
-}
-function TrailingCopySlot({ count, command, label, showCopy }) {
-  return /* @__PURE__ */ jsx(
-    "span",
-    {
-      style: {
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        width: 32,
-        height: 22,
-        flexShrink: 0
-      },
-      children: showCopy && command ? /* @__PURE__ */ jsx(CopyCommandControl, { command, label, visible: true }) : count > 0 ? /* @__PURE__ */ jsx(KindChip, { kind: String(count), tone: "primary" }) : null
-    }
-  );
-}
+import './chunk-I2KLQ2HA.js';
 
 // src/knowledge/_generated/knowledge-search-index.json
 var knowledge_search_index_default = [
@@ -788,8 +17,8 @@ var knowledge_search_index_default = [
   {
     id: "knowledge.org-model-reference",
     title: "Organization Model Schema Reference",
-    summary: "Technical reference for the OrganizationModel Zod schema: all domains, field contracts, and versioning rules.",
-    bodyText: "Schema\n\nThe OrganizationModel schema is defined in packages/core/src/organization-model/schema.ts. It is versioned at version: 1 and composed from domain sub-schemas.\n\nDomains\n\n- features \u2014 flat array of FeatureSchema nodes (nav tree)\n- knowledge \u2014 flat array of KnowledgeNodeSchema nodes\n- sales, prospecting, projects \u2014 sales and GTM domains\n- operations, statuses \u2014 runtime entity domains\n- customers, offerings, roles, goals \u2014 business context domains"
+    summary: "Technical reference for the OrganizationModel Zod schema: all top-level domains, the graph contract orientation, authored primitives versus projected graph nodes, and versioning rules.",
+    bodyText: "Schema\n\nThe OrganizationModel schema is defined in packages/core/src/organization-model/schema.ts. It is versioned at version: 1 and composed from domain sub-schemas. The OM is the authoritative contract for the organization: downstream surfaces including Command View, the Knowledge Browser, and the navigation shell are all derived projections from this schema.\n\nTop-Level Domains\n\nThese are the current top-level fields on OrganizationModel. There is no live features or capabilities top-level field -- those terms are legacy wording and should not appear as authored OM primitives.\n\n- version -- schema version, currently locked at 1\n- domainMetadata -- per-domain version and lastModified tracking\n- branding -- organization name, logo, color identity\n- navigation -- surfaces, groups, and defaultSurfaceId for shell routing\n- sales -- sales domain including pipeline entity references\n- prospecting -- lead generation stages, entity references, and pipeline config\n- projects -- project, milestone, and task entity references\n- identity -- organization identity fields\n- customers -- customer segment definitions\n- offerings -- product and service definitions linked to customer segments\n- roles -- role definitions with reportsToId hierarchy and agentId holder support\n- goals -- OKR-style objectives with period ranges and system links\n- systems -- the backbone: hierarchical bounded contexts with dotted IDs and parentSystemId\n- resources -- governance descriptors for workflows, agents, integrations, triggers, and scripts; resource identity lives here, not in a separate deployment manifest\n- actions -- the invokable semantic layer; actions map to resources, affect entities, bind to knowledge, and expose invocation types (slash command, MCP tool, API endpoint, script execution)\n- entities -- business objects owned by systems, with table metadata, state catalogs, and typed entity links\n- policies -- governance rules applied to systems, actions, resources, and roles\n- statuses -- runtime semantic status registry\n- knowledge -- first-class OM content backed by inline nodes and MDX source nodes\n\nGraph Contract\n\nThe OM is projected into a typed graph by buildOrganizationGraph() in packages/core/src/organization-model/graph/build.ts.\n\nNode kinds: organization, system, role, action, entity, event, policy, stage, resource, knowledge\n\nEdge kinds: contains, references, mapsto, uses, governs, links, affects, emits, originatesfrom, triggers, appliesto, effects\n\nThe resourceType overlay on resource nodes is a separate enum: workflow, agent, trigger, integration, external, humancheckpoint, script.\n\nAuthored Primitives vs Projected Graph Nodes\n\nAuthored primitives are what you write directly in the OM: systems, roles, resources, actions, entities, policies, knowledge. The graph builder reads these and emits a richer set of typed nodes and edges. Events, for example, are not authored directly -- they are projected from resource emits declarations. Stages are projected from prospecting stage catalogs.\n\nCommand View\n\nCommand View is a derived operational projection of the OM graph. It visualizes systems, resources, actions, entities, and relationships using the same node and edge taxonomy as buildOrganizationGraph(). It does not have a separate deployment manifest model -- the OM resources domain is the single source of resource identity."
   },
   {
     id: "knowledge.seo-lead-gen-playbook",
@@ -1367,6 +596,131 @@ Graduated Exposure Protocol
 3. Face bubble intro (15-30s) + screen recording \u2014 ongoing
 
 Each stage desensitizes one fear at a time. Never skip ahead. The goal is consistency, not perfection.`
+  },
+  {
+    id: "knowledge.what-is-elevasis",
+    title: "What is Elevasis",
+    summary: "Company overview, positioning, value proposition, and pricing for the AI orchestration platform",
+    bodyText: 'Executive Summary\n\nCompany: Bootstrapped AI orchestration platform for done-for-you business automation\n\nFounder: Solo (Alex, 34), bootstrapped\n\nMarket: Service-based SMBs that need practical AI automation without building internal AI teams\n\nGTM: Content-led marketing, proof assets, consultative sales, and land-and-expand pricing\n\nCompany Overview\n\nCurrent Status\n\nThe platform core is production-ready enough to support client-facing demonstrations and implementation work. Current business focus is client acquisition, proof-building, and turning the platform into a repeatable service delivery system.\n\nFounder Profile\n\nAlex, 34 \u2014 Solo founder with software engineering background (BSCS degree). Previous: Ecommerce platforms, Streaming technology. No formal AI background \u2014 practitioner, not academic.\n\nWhat We Are\n\nOperating layer for AI automation. We help SMBs operate with closed-loop feedback, decision capture, and continuous learning \u2014 at SMB pricing with done-for-you implementation (NOT self-service).\n\nTarget Market\n\nICP: Service-based SMBs (2-50 employees, USA, $200K-$5M revenue)\n\nCore Pain: Capacity crisis, pipeline problems, operational chaos, growth blockers \u2014 too busy serving clients to grow their own business.\n\nPricing (Land-and-Expand)\n\n- Tier 1 \u2014 Foundation (1-2 workflows): $500-2k/mo\n- Tier 2 \u2014 Scaled Operations (3-5 workflows): $2k-5k/mo\n- Tier 3 \u2014 AI-Powered Systems (6+ workflows): $5k-15k+/mo\n\nAdditional workflows cost less due to shared infrastructure.\n\nValue Proposition\n\n"We find one bottleneck in your business, build an AI solution to fix it, and you only pay if it actually saves you time or makes you money."'
+  },
+  {
+    id: "knowledge.platform-systems-overview",
+    title: "Platform Systems Overview",
+    summary: "Authoritative overview of the Elevasis AI Orchestration Platform systems -- what's built, what each system does, and how the pieces fit together",
+    bodyText: "Overview\n\nElevasis is a production AI orchestration platform that coordinates workflows, autonomous agents, and human approvals into a unified operating layer for SMBs. Everything described below is implemented and running in production.\n\nCore Architecture:\n\n| Layer | What It Does | Key Components |\n| --- | --- | --- |\n| Execution | Runs workflows and agents with schema validation | Workflow Engine, Agent Framework, Execution Runner |\n| Control | Human oversight, approvals, and decision capture | Command Queue (HITL), Dynamic Forms, Action System |\n| Intelligence | Autonomous reasoning, tool use, and memory management | ReAct Agents, Knowledge Map, Session Memory |\n| Observability | Real-time visibility into cost, performance, and health | Cost Tracking, Metrics, Activity Log, SSE Streaming |\n| Platform | Multi-tenancy, security, scheduling, integrations | Registry, RLS, Scheduler, Credential Vault, SDK |\n\nExecution Engine\n\nAI Workflows\n\nGraph-based workflow execution with schema-validated steps and conditional routing. Steps define explicit routing: linear, conditional (rule-based branching), or terminal. Context flows through the entire workflow.\n\nAutonomous Agents\n\nProduction-grade ReAct-style agents with tool use, memory management, and security hardening.\n\nLLM Provider Support: OpenAI (GPT-5), Google (Gemini 3 Flash), Anthropic (Claude Sonnet 4.5), OpenRouter (GLM-5)\n\nHuman-in-the-Loop (HITL)\n\nThe Command Queue surfaces pending approvals as structured tasks. Admin reviews, approves or edits, and the workflow continues. Every critical decision \u2014 sending emails to prospects, updating customer records, publishing content \u2014 requires human approval.\n\nKnowledge Map\n\nOrganizational knowledge loaded lazily into agent context. 80-95% token savings vs. always-loading full context. Nodes link to features, teams, and other nodes.\n\nIntegrations (13 active)\n\nAttio CRM, Cal.com, Instantly (cold email), Resend, Apify, Google Maps, Tomba, Mails.so, Supabase, Stripe, OpenAI, Google Gemini, Anthropic Claude.\n\nSDK\n\nTypeScript-based resource development with local testing, validation, and deployment pipeline. External consumers define workflows and agents in their own repos and deploy via elevasis-sdk deploy."
+  },
+  {
+    id: "knowledge.client-testimonials",
+    title: "Testimonials",
+    summary: "Customer testimonials and case study permissions from previous client work",
+    bodyText: `Status: 4 testimonials from 2 clients | Source: Upwork client work (2024)
+
+Testimonials
+
+Xero Automation \u2014 The Invoice Chase That Disappeared
+
+Client: Word of Mouth Agency
+
+Result: 10+ hours/week saved. Zero manual follow-up emails.
+
+> "Working with Alex at Elevasis to automate our Xero follow-ups has been a game-changer. We're set to save over 5 hours a week, but more importantly, it has completely removed the stress of chasing invoices. The process was smooth and professional."
+
+Permission: Case study approved with company name.
+
+Influencer Discovery \u2014 From Spreadsheet Hell to Strategic Decisions
+
+Client: Word of Mouth Agency (Perth, Australia)
+
+Result: 10+ hours/week saved. Research scope: 50 to 200+ influencers. Team focus shifted from data to strategy.
+
+> "Working with Alex at Elevasis to automate our Influencer Discovery has been a game-changer. We're set to save over 5 hours a week..."
+
+Permission: Case study approved with company name.
+
+EMRG Media \u2014 4 Automations for NYC's Premier Events Firm
+
+Client: EMRG Media (NYC, est. 2001). Clients include Google, YouTube, Sony Music, Fiverr, Equinox.
+
+What We Built:
+1. Case Study Generator \u2014 7-10 hours \u2192 2 hours. Publication rate: 1/quarter \u2192 2/month.
+2. EMRG Follow-Up Generator \u2014 Automated post-event follow-ups with signature management.
+3. Event Sponsor Tracker \u2014 Automated sponsor pipeline tracking and communications.
+4. Lead Scraper \u2014 Automated discovery of event planning prospects.
+
+Fame Stats:
+- 3,500+ attendees at The Event Planner Expo
+- 25+ year track record
+- Fortune 500 client roster
+
+Permission: Case study approved with company name.`
+  },
+  {
+    id: "knowledge.understanding-elevasis",
+    title: "Understanding Elevasis Overview",
+    summary: "Company overview, product positioning, and platform systems context for Elevasis AI orchestration platform",
+    bodyText: "Lean documentation explaining what Elevasis is and what the platform can do. This section provides the foundational context for business conversations and technical evaluation.\n\nElevasis is a done-for-you AI automation service backed by a production-grade platform. The company targets service-based SMBs (2-50 employees, $200K-$5M revenue) who are too busy serving clients to grow their own business.\n\nKey Facts\n\n- Stage: Pre-revenue, platform 100% complete, client acquisition active\n- Offer: Done-for-you AI automation -- we build and maintain the workflows, no coding required\n- ICP: Service-based SMBs (2-50 employees, $200K-$5M revenue, USA)\n- Pricing: $500-$2k/mo (Foundation) \u2192 $2k-$5k/mo (Scaled) \u2192 $5k-$15k+/mo (AI-Powered)\n- Market: Early Adopters stage, $23.77B TAM growing to $87.7B by 2032\n- Competitive position: No dominant done-for-you SMB AI provider exists; blue ocean\n\nWhen to Use Each Document\n\n| Situation | Document |\n| --- | --- |\n| First conversation with any audience | What is Elevasis |\n| Technical evaluation or demo prep | Platform Systems Overview |\n\nDocumentation\n\n- What is Elevasis \u2014 AI orchestration platform overview, company stage, value proposition, and pricing tiers\n- Platform Systems Overview \u2014 Authoritative overview of what is built, what each system does, and how the pieces fit together"
+  },
+  {
+    id: "knowledge.marketing-overview",
+    title: "Marketing Overview",
+    summary: "Marketing documentation for Elevasis - strategy, website infrastructure, and content systems",
+    bodyText: "Welcome to the Elevasis marketing documentation. This section covers marketing strategy, website implementation, and content systems.\n\nDocumentation\n\nStrategy\n\n- Overview \u2014 Channel strategy, inbound content system, and proof-led demand generation\n\nWebsite\n\nThe marketing website's technical infrastructure, setup, and SEO docs now live under Architecture \u2192 Website."
+  },
+  {
+    id: "knowledge.ai-orchestration-principles",
+    title: "AI Orchestration Principles",
+    summary: "The 4 principles that separate production AI from toy automation",
+    bodyText: `Most AI automation fails. Not because the technology is bad, but because it's implemented without the principles that make AI systems work in production.
+
+These four principles separate toy automation from AI systems that actually run businesses.
+
+The 4 Principles
+
+1. Integrated: Works With Your Existing Systems
+
+Principle: AI must work with your existing tools, not replace them.
+
+AI that doesn't connect to your CRM, your email, your calendar, your existing workflows is a toy. Real AI automation works WITH what you already have \u2014 not instead of it.
+
+- Your 50 Zapier workflows keep running
+- Your CRM stays your CRM
+- AI adds intelligence on top, not a rip-and-replace
+
+The anti-pattern: "Use our AI instead of everything else." Creates vendor lock-in and throws away your existing investment.
+
+2. Improving: Gets Smarter Over Time
+
+Principle: AI must learn from every decision and improve continuously.
+
+Static automation is just fancy if-then logic. Real AI captures every approval, rejection, and edit \u2014 then uses that data to get smarter.
+
+The anti-pattern: "Set it and forget it." Systems that don't learn stay dumb forever.
+
+3. Observable: You See What AI Is Doing
+
+Principle: You must be able to see what AI systems are doing in real-time.
+
+Black-box automation is unacceptable for business operations. You need to see every action, every decision, every cost \u2014 as it happens.
+
+- Real-time activity feeds showing what's executing
+- Cost tracking per workflow, per execution
+- Token usage visibility
+- Execution logs for debugging
+
+The anti-pattern: "It just works, trust us." Systems without observability create anxiety and prevent adoption.
+
+4. Governed: Humans Control What Matters
+
+Principle: Humans must approve important actions before execution.
+
+AI should handle the grunt work. But critical decisions \u2014 sending emails to prospects, updating customer records, publishing content \u2014 require human approval.
+
+- AI researches 50 prospects and drafts personalized emails
+- Before anything sends, it lands in your approval queue
+- You spend 10 minutes reviewing, approve or tweak
+- Only then does it execute
+
+The anti-pattern: "Fully autonomous AI." Systems without governance create risk and erode trust.`
   },
   {
     id: "knowledge.new-vertical-launch-playbook",
@@ -1528,6 +882,240 @@ Launch Checklist
     summary: "Stable scanning, scoring, freshness, and query-health workflow for the Upwork acquisition channel.",
     bodyText: 'Overview\n\nUse this playbook to run the Upwork acquisition scanning loop. The goal is to find fresh, low-competition jobs where Elevasis can deliver a real business system, score them consistently, and turn the best opportunities into proposals through the Upwork proposal playbook.\n\nThe scanning loop has six phases:\n\n1. Confirm browser and login readiness.\n2. Run saved search queries with the right filters.\n3. Extract fresh job cards.\n4. Deduplicate, score, and enrich strong candidates.\n5. Write the scan output.\n6. Review query health before the next scan.\n\nProposal copy and response handling are intentionally separate. Use knowledge.upwork-proposal-playbook for proposal strategy and knowledge.upwork-response-templates for client replies.\n\nPreconditions\n\nBefore scanning, verify the browser automation surface is available and Upwork is logged in.\n\n- Chrome tooling must be available through the active browser automation tools.\n- The Upwork search page must load at https://www.upwork.com/nx/search/jobs/.\n- The page must show the job search interface, not a login prompt.\n- If login is required, stop and log in manually before scanning again.\n\nDo not try to work around a missing browser session by inventing scan results. The scan depends on live Upwork search pages, current saved-search filters, and the visible result cards.\n\nScan Surface\n\nRun scans from the Upwork search page:\n\ntext\nhttps://www.upwork.com/nx/search/jobs/\n\nEach saved query is run individually. Apply the filters every time, because Upwork search state is session-dependent and not always persisted across queries.\n\n| Filter    | Value       | Reason                                                                 |\n| --------- | ----------- | ---------------------------------------------------------------------- |\n| U.S. only | Checked     | Higher-quality clients, stronger timezone fit, more verified payments. |\n| Sort by   | Most Recent | Freshness is the strongest conversion lever.                           |\n| Proposals | \\<5, 5-10 | Low competition is required before spending connects.                  |\n\nUse saved queries as the primary scan source. The strategy targets operational system-build terms, not generic "AI automation" searches that attract high competition.\n\nFreshness Rule\n\nOnly collect posts from the last 12 hours. Results should be sorted by Most Recent, so stop extracting for a query once the visible posts are older than 12 hours. Do not do catch-up windows.\n\nFreshness priority:\n\n| Post age   | Action                                                           |\n| ---------- | ---------------------------------------------------------------- |\n| 0-1 hour   | Highest priority. Client is most likely active and shortlisting. |\n| 1-12 hours | Valid scan window. Still worth scoring if competition is low.    |\n| 12+ hours  | Skip. The client has usually already formed the shortlist.       |\n\nRecord the scan timestamp as lastscanned in the daily scan doc frontmatter. This timestamp helps avoid reprocessing posts from prior scans, but the hard 12-hour cap still applies.\n\nRun Each Query\n\nFor each active saved query:\n\n1. Clear the search box.\n2. Enter the query string and submit.\n3. Apply U.S. only, Most Recent, and proposal-count filters.\n4. Wait for results to render.\n5. Extract visible job cards from the search page.\n6. Stop once a post exceeds the freshness cutoff.\n7. Tag each job with the source query.\n\nThe first page of most-recent, low-proposal results is the high-value slice. Do not paginate unless a specific investigation requires it.\n\nWhile scanning the API integration query, flag custom dashboard opportunities where a custom build is likely better than Power BI, Looker, Tableau, or a spreadsheet. Strong signs include 3+ data sources, live dashboard requirements, AI-generated summaries, anomaly detection, or workflow triggers.\n\nExtract Job Card Data\n\nThe search-card extraction should capture the fields needed for initial triage:\n\n- Title.\n- Upwork job URL path.\n- Posted age.\n- Proposal count.\n- Budget or hourly range.\n- Payment verification.\n- Client rating.\n- Total client spend.\n- Description snippet.\n- Source query.\n\nDeduplicate by Upwork job URL path after all queries finish. If a job appears under multiple queries, keep one row and note the overlap.\n\nScore and Enrich\n\nScoring has two stages.\n\nStage 1: Relevance\n\nScore relevance from 0 to 100 by asking whether the client needs a system, workflow, integration, automation, or operational build that Elevasis can deliver.\n\n| Range  | Label        | Criteria                                                                  |\n| ------ | ------------ | ------------------------------------------------------------------------- |\n| 75-100 | Strong fit   | Clear build intent, specific business workflow, named tools or outputs.   |\n| 50-74  | Possible fit | Some build signals, but scope or buyer intent is ambiguous.               |\n| 25-49  | Weak fit     | Marginally related, mostly noise, low business-system signal.             |\n| 0-24   | Irrelevant   | Hiring, marketing, design, manual VA work, personal projects, or errands. |\n\nDisqualify posts that are clearly hiring a role, outsourcing manual work, asking for generic marketing/design help, or describing a personal/non-business project.\n\nStage 2: Application Priority\n\nApply tactical modifiers after relevance scoring. The final score determines whether to draft a proposal.\n\n| Signal         | Positive indicators                                  | Negative indicators                         |\n| -------------- | ---------------------------------------------------- | ------------------------------------------- |\n| Freshness      | \\<1h or same-session post.                         | 8-12h old, or outside the scan window.      |\n| Competition    | \\<5 proposals, or 5-10 with strong fit.            | 10+ proposals, especially 20+.              |\n| Client quality | Payment verified, spend history, good rating, hires. | Unverified, no history, 0% hire rate.       |\n| Budget         | Fixed \\>$5K or hourly \\>$75/hr.                  | Fixed \\<$1K or hourly \\<$40/hr.         |\n| Fit            | Workflow, integration, dashboard, CRM, operations.   | Copywriting, funnels, ads, hiring, support. |\n\nOnly enrich posts with a strong enough relevance score to matter, usually 65+. For those posts, open the job detail view and capture:\n\n- Hire rate.\n- Jobs posted.\n- Member since.\n- Company size.\n- Last viewed by client.\n- Interviewing count.\n\nUse this data to avoid over-ranking stale or low-quality clients that have a good-sounding job description but weak application ROI.\n\nWrite the Scan Output\n\nWrite scan docs under:\n\ntext\napps/docs/content/docs/operations/client-acquisition/upwork/scans/{YYYY-MM-DD}.mdx\n\nIf a scan doc already exists for the day, append the new scan as a later section instead of creating a second daily file.\n\nEach scan output should include:\n\n- Date and timestamp.\n- Freshness cutoff.\n- Queries scanned.\n- Total posts collected.\n- Deduplicated count.\n- Top opportunities only.\n- Comparison table.\n- Query health table.\n- Draft proposals section, when proposals are generated.\n\nKeep scan docs as decision tools, not archives. Include the top 10 ranked opportunities rather than every collected post.\n\nQuery Health\n\nAfter scoring, compute a query-health score so weak searches can be removed over time.\n\n| Metric          | Measurement                                                       | Weight |\n| --------------- | ----------------------------------------------------------------- | ------ |\n| Fresh posts     | Count within cutoff, normalized against 5 posts.                  | 25%    |\n| Low competition | Percent with fewer than 10 proposals.                             | 25%    |\n| Relevance       | Percent actionable after deduplication and disqualification.      | 30%    |\n| Client quality  | Percent with verified payment and useful spend or rating signals. | 20%    |\n\nQueries that score 0 across 3+ consecutive scans are drop candidates. Compare the latest query-health table with the previous scan before changing the active query set.\n\nActive Query Principles\n\nStrong Upwork queries describe the system the buyer needs, not the freelancer category they think they are hiring.\n\nUse:\n\n- Specific operational system nouns such as booking system, intake form, scheduling system, ticketing system, tracking system, reservation system, billing system, and payment system.\n- Action verbs such as build, automate, custom, develop, setup, integration, and workflow.\n- Platform-specific searches where system-build intent overlaps with implementation work, such as GoHighLevel, Pipedrive, CRM, API integration, or inventory sync.\n\nAvoid:\n\n- Broad solution-first terms such as AI automation, AI agent, workflow automation, portal, dashboard, tool, or custom without a specific system noun.\n- Vertical keywords such as clinic, contractor, salon, or real estate unless paired with concrete system intent.\n- Pain-signal phrases that usually mean the client is hiring a human to perform manual work.\n- Revenue-proximity service terms such as cold email, appointment setting, outbound specialist, or funnel work.\n\nBefore testing a new query, read knowledge.upwork-query-strategy and check the Upwork query registry in the operations docs so old failure modes are not repeated. Use knowledge.upwork-calibration-strategy when promoting, dropping, or re-evaluating saved searches.\n\nProposal Handoff\n\nAfter the scan, draft proposals only for opportunities that remain strong after relevance, tactical modifiers, and client-quality checks.\n\nFor proposal drafting:\n\n1. Load knowledge.upwork-proposal-playbook.\n2. Read the top opportunities from the latest scan doc.\n3. Select the right proposal template by scope, budget, and relevance.\n4. Tailor the opening, proof point, plan, and two discovery questions.\n5. Append draft proposals to the scan doc under ## Draft Proposals.\n\nUse knowledge.upwork-response-templates after a client replies or sends an offer.\n\nScan Checklist\n\n- Browser tooling available.\n- Upwork logged in.\n- Search page loaded.\n- U.S. only filter applied.\n- Sort set to Most Recent.\n- Proposal-count filters applied.\n- All active saved queries scanned.\n- Posts older than 12 hours skipped.\n- Jobs deduplicated by URL path.\n- Relevance scores assigned.\n- Strong candidates enriched from detail view.\n- Final scores sorted descending.\n- Daily scan doc created or appended.\n- Query health table written.\n- Top proposal candidates handed to knowledge.upwork-proposal-playbook.'
   },
+  {
+    id: "knowledge.client-cli-overview",
+    title: "Client CLI Overview",
+    summary: "Reference for the seven client:* SDK CLI commands -- list, get, status, resolve, create, update, and delete -- with drill-down recipes for navigating client lineage, org-wide rollups, and write operations.",
+    bodyText: `Overview
+
+The client: commands expose the clients hub through the SDK CLI. Use them to paginate clients, inspect individual client lineage, check org-wide status rollups, resolve a fuzzy name to a client ID, and mutate clients with create, update, and delete operations.
+
+All examples below use the canonical monorepo invocation pattern. Tenant projects inside their own operations/ directory drop the -C packages/elevasis-operations prefix and run pnpm exec elevasis-sdk <cmd> directly.
+
+client:list
+
+Lists clients for the authenticated organization with optional filtering and pagination.
+
+Purpose: Paginate all clients or narrow by status or search term to find the right client ID before drilling in with client:get.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:list
+
+Tenant invocation (from inside operations/):
+
+bash
+pnpm exec elevasis-sdk client:list
+
+Key flags:
+
+- --status <value> -- filter by client status (e.g. active, inactive, prospect)
+- --search <term> -- full-text search against client name
+- --limit <n> -- maximum rows to return (default varies by server)
+- --offset <n> -- pagination offset
+- --pretty -- pretty-print JSON output
+
+Drill-down recipe:
+
+1. Run client:list --pretty to scan names and IDs.
+2. Use --search to narrow when the list is long.
+3. Copy the id from a row and pass it to client:get <id> for the full lineage payload (linked deal, primary company, primary contact, projects).
+
+client:get
+
+Fetches a single client record with its full lineage payload.
+
+Purpose: Inspect one client in detail -- its associated deal, primary company, primary contact, and linked projects. Use this to confirm linkage after wiring a project to a client via project:update --client.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:get <clientId>
+
+Tenant invocation:
+
+bash
+pnpm exec elevasis-sdk client:get <clientId>
+
+Key flags:
+
+- --pretty -- pretty-print JSON output
+
+Drill-down recipe:
+
+1. Obtain <clientId> from client:list or client:resolve.
+2. Run client:get <clientId> --pretty.
+3. Check projects array to confirm which projects are linked.
+4. If projects is empty and a linkage was expected, run project:update <projectId> --client <clientId> to attach it.
+5. Re-run client:get to verify the lineage updated.
+
+client:status
+
+Returns an org-wide rollup of client counts grouped by status.
+
+Purpose: High-level health check -- how many clients are active, how many are in each pipeline stage -- without enumerating every record.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:status
+
+Tenant invocation:
+
+bash
+pnpm exec elevasis-sdk client:status
+
+Key flags:
+
+- --pretty -- pretty-print JSON output
+
+Drill-down recipe:
+
+1. Run client:status --pretty to see counts per status bucket.
+2. If a bucket looks unexpectedly large or small, run client:list --status <value> to enumerate the records in that bucket.
+3. Use client:get <id> on specific records to investigate lineage gaps.
+
+client:resolve
+
+Fuzzy-resolves a client name to a client ID.
+
+Purpose: Convert a partial or approximate name to the canonical UUID before passing --client to project commands. Mirrors project:resolve in shape.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:resolve "<query>"
+
+Tenant invocation:
+
+bash
+pnpm exec elevasis-sdk client:resolve "<query>"
+
+Key flags:
+
+None beyond the positional <query> argument. Output is the resolved client ID (or a ranked list if multiple matches exist).
+
+Drill-down recipe:
+
+1. Run client:resolve "partial name" -- the command returns the best-match client ID.
+2. Pass the returned ID to project:create --client <id>, project:update --client <id>, or project:list --client <id>.
+3. If multiple matches are returned, refine the query or use client:list --search "<term>" to inspect candidates before committing.
+
+client:create
+
+Creates a new client record for the authenticated organization.
+
+Purpose: Provision a client directly from the CLI -- useful for scripted onboarding or bulk imports where no source deal exists yet. The only required field is --name; all relationship IDs are optional and can be set later via client:update.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:create --name "Acme Corp"
+
+Tenant invocation (from inside operations/):
+
+bash
+pnpm exec elevasis-sdk client:create --name "Acme Corp"
+
+Key flags:
+
+- --name <name> -- (required) client display name
+- --status <value> -- initial status: active | onboarding | paused | completed | churned
+- --source-deal-id <uuid> -- UUID of the originating deal
+- --primary-company-id <uuid> -- UUID of the primary company record
+- --primary-contact-id <uuid> -- UUID of the primary contact record
+- --metadata <json> -- arbitrary metadata as a JSON string (e.g. '{"tier":"enterprise"}')
+- --pretty -- render a human-readable summary instead of raw JSON
+
+Drill-down recipe:
+
+1. Run client:create --name "Acme Corp" --status onboarding --pretty to create and confirm the new record.
+2. Copy the ID from the pretty output (or id from raw JSON) for subsequent commands.
+3. Run client:get <id> --pretty to verify the full lineage payload was initialized correctly.
+4. If a source deal exists, pass --source-deal-id <uuid> at create time or backfill with client:update <id> --source-deal-id <uuid>.
+
+client:update
+
+Updates one or more fields on an existing client. Accepts a UUID or fuzzy name as the \\<id\\> argument.
+
+Purpose: Rename a client, change its status, swap or clear relationship IDs, or patch arbitrary metadata -- without leaving the CLI. The command enforces a client-side "at-least-one-field" guard and rejects mutually exclusive flag pairs before making any API call.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:update <id> --status active
+
+Tenant invocation:
+
+bash
+pnpm exec elevasis-sdk client:update <id> --status active
+
+Key flags:
+
+- --name <name> -- new client display name
+- --status <value> -- new status: active | onboarding | paused | completed | churned
+- --source-deal-id <uuid> -- set or replace the source deal link
+- --clear-source-deal -- remove the source deal link (sets sourceDealId to null; mutually exclusive with --source-deal-id)
+- --primary-company-id <uuid> -- set or replace the primary company
+- --clear-primary-company -- remove the primary company link (mutually exclusive with --primary-company-id)
+- --primary-contact-id <uuid> -- set or replace the primary contact
+- --clear-primary-contact -- remove the primary contact link (mutually exclusive with --primary-contact-id)
+- --metadata <json> -- replace metadata with the provided JSON string
+- --pretty -- render a human-readable summary instead of raw JSON
+
+Drill-down recipe:
+
+1. Obtain \\<id\\> from client:list, client:resolve, or the output of client:create.
+2. Pass only the fields to change -- the command patches rather than replaces the record.
+3. To unlink a relationship (e.g. remove the source deal), use --clear-source-deal rather than omitting the flag; omitting leaves the existing value unchanged.
+4. After update, run client:get <id> --pretty to confirm all fields reflect the expected state.
+5. If the command exits with CONFLICTINGFLAGS on stderr, you passed both a set flag and its --clear- counterpart -- remove one and retry.
+
+client:delete
+
+Deletes a client record. Accepts a UUID or fuzzy name as the \\<id\\> argument.
+
+Purpose: Remove a client that was created in error or is no longer relevant. The API enforces a 409 Conflict when the client has linked rows (deals, projects, companies, contacts). The CLI surfaces the API error message verbatim so you know which links to resolve first.
+
+Monorepo invocation:
+
+bash
+pnpm -C packages/elevasis-operations exec elevasis-sdk client:delete <id>
+
+Tenant invocation:
+
+bash
+pnpm exec elevasis-sdk client:delete <id>
+
+Key flags:
+
+- --pretty -- render a human-readable confirmation instead of raw JSON
+- --api-url <url> -- override the API base URL (advanced; rarely needed)
+
+Drill-down recipe:
+
+1. Run client:get <id> --pretty to confirm which projects and deal links are attached before attempting deletion.
+2. Run client:delete <id> --pretty.
+3. If the API returns a 409, the error message lists the linked record counts (deals, projects, companies, contacts). Unlink or reassign those records first:
+   - Projects: project:update <projectId> --clear-client (or reassign with --client <otherId>)
+   - Deals: handled via the acquisition domain; no dedicated CLI command today
+4. Retry client:delete <id> --pretty once all links are resolved.
+5. Confirm deletion with client:list --search "<name>" -- the record should no longer appear.
+
+Typical Workflow
+
+A common session combining read and write commands:
+
+1. client:status --pretty -- check org-wide distribution.
+2. client:resolve "Acme" -- get the Acme client ID.
+3. client:get <id> --pretty -- confirm lineage (deal, company, contact, projects).
+4. project:update <projectId> --client <id> -- link a project if missing.
+5. client:get <id> --pretty -- verify the linkage appears in the projects array.
+6. client:create --name "New Corp" --status onboarding --pretty -- provision a new client.
+7. client:update <id> --status active --pretty -- transition a client to active.
+8. client:delete <id> --pretty -- remove a client (API rejects with 409 if linked rows exist).`
+  },
   {
     id: "knowledge.youtube-obs-recording-setup",
     title: "YouTube OBS Recording Setup",
@@ -1786,216 +1374,106 @@ Pre-Recording Checklist
     bodyText: "Overview\n\nElevasis finance operations run through Xero, with Stripe handling payment collection. Xero is the single source of truth for financial records: business checking bank feeds, Stripe payouts, contractor payments, expenses, invoices, receivables, and year-end exports.\n\nThe finance loop has three connected parts:\n\n1. Invoicing captures client revenue through monthly retainers and Stripe Checkout.\n2. Accounting records and reconciles bank transactions, Stripe payouts, contractor payments, and operating expenses.\n3. Taxes use accurate Xero records for quarterly estimates, deductions, 1099s, and annual filing.\n\nAccounting and Reconciliation\n\nReconcile bank transactions in Xero weekly. Match each bank feed entry to its real-world source before month end.\n\n- Stripe payouts should match against Stripe bank feed activity.\n- Contractor payments should match checking account transfers.\n- Software subscriptions such as Railway, Vercel, Supabase, WorkOS, and OpenAI should be categorized as operating expenses.\n- Unmatched or ambiguous transactions should be flagged for manual review before monthly close.\n\nMaintain the core chart of accounts around revenue, cost of sales, operating expenses, and owner draws. Revenue includes client retainers and one-time project fees. Cost of sales covers contractor labor directly tied to client work. Operating expenses cover SaaS tools, hosting, banking fees, and professional services. Owner draws track business distributions.\n\nConfigure Xero with the connected business checking account, the default tax rate for the business jurisdiction, and the correct financial year end in organization settings.\n\nInvoicing and Accounts Receivable\n\nClient billing runs on a monthly retainer model. Create invoices in Xero at the start of each billing period, send them by Xero email or Stripe Checkout link, record payment after Stripe confirms checkout completion, and reconcile the Stripe payout in Xero.\n\nUse Xero repeating invoices for monthly retainers:\n\n- Frequency: monthly.\n- Start date: billing cycle start date.\n- Approval: automatic approval where the billing terms are stable.\n\nConfigure invoice reminders around the due date: a courtesy reminder 3 days before due date, an overdue notice 1 day after due date, and an escalation notice 7 days after due date.\n\nFor invoices more than 14 days overdue, contact the client directly through the active communication channel, pause active work pending payment confirmation, and resolve the balance before the next billing cycle.\n\nTaxes\n\nTax work depends on accurate Xero records throughout the year. As a pass-through entity, Elevasis business income flows to the owner personal return, so quarterly estimates reduce underpayment risk and year-end exports should be clean enough for a CPA or tax preparer.\n\nQuarterly estimated payment targets:\n\n- Q1: April 15.\n- Q2: June 15.\n- Q3: September 15.\n- Q4: January 15 of the following year.\n\nEstimate payments as roughly 25-30% of net profit for the quarter and pay via IRS Direct Pay or EFTPS.\n\nTrack deductible expenses in Xero during the year: SaaS subscriptions, contractor payments, home office expenses where applicable, professional development, courses, and business banking fees. Keep digital receipts organized by year in the business records folder.\n\nIssue 1099-NEC forms to US-based contractors paid more than $600 in a calendar year. Collect a W-9 before first payment, track annual contractor totals in Xero, file 1099-NEC forms by January 31 of the following year, and file the 1096 summary with the IRS when required.\n\nAt year end, export the Xero profit and loss statement and balance sheet. Provide them to the CPA or tax preparer with issued 1099s, bank statements for the business year, mileage logs if applicable, and home office documentation if applicable."
   },
   {
-    id: "knowledge.platform-command-view",
-    title: "Platform Command View",
-    summary: "Reference for Command View, the read-only graph surface for organization automation resources, relationships, manifest validation, graph modes, filters, and troubleshooting.",
-    bodyText: "Overview\n\nCommand View visualizes an organization's automation landscape: agents, workflows, triggers, integrations, external resources, and human checkpoints, plus the relationships between them.\n\nIt answers operational questions such as:\n\n- What does this agent talk to?\n- If a provider goes down, what breaks?\n- What is connected to the CRM?\n- Which resources are hidden, diagnostic-only, or currently relevant to this trace?\n\nAccess Command View through the Knowledge area at /knowledge/command-view.\n\nHow Command View Works\n\nCommand View is a visualization layer over the organization deployment manifest.\n\ntypescript\nconst yourOrgRegistry: DeploymentSpec = {\n  agents: [],\n  workflows: [],\n  triggers: [],\n  integrations: [],\n  humanCheckpoints: [],\n  relationships: {},\n  externalResources: []\n}\n\nArchitecture:\n\n1. Manifest declares resources and relationships.\n2. SDK deploy and API registration validate declared references.\n3. Pre-serialization computes graph data once.\n4. Frontend visualizes cached graph data.\n\nCommand View does not create routing. It displays declarations and runtime topology data.\n\nNode Types\n\n| Type | Purpose | Badge info |\n| --- | --- | --- |\n| Triggers | Entry points such as webhook, schedule, manual, or event triggers | Trigger type |\n| Agents | Autonomous AI resources | Tool count, Knowledge Map, memory |\n| Workflows | Multi-step orchestrations | Step count |\n| Integrations | External service connections | Connection status |\n| External resources | Third-party platforms such as n8n, Make, or Zapier | Platform name |\n| Human checkpoints | Human decision points | Approval required |\n\nNode badges:\n\n- Agents show tool count, Knowledge Map, and memory.\n- Workflows show step count.\n- Integrations show connection status.\n- Triggers show webhook, schedule, manual, or event type.\n- External resources show platform.\n\nEdge Types\n\n| Type | Meaning |\n| --- | --- |\n| Triggers | A trigger initiates a resource |\n| Invokes | A resource calls another resource |\n| Uses | A resource uses an integration |\n| Approval | A resource requests human approval |\n\nDeclaring Relationships\n\nInternal Resources\n\nUse relationships to declare what agents and workflows invoke or use.\n\ntypescript\nconst relationships: ResourceRelationships = {\n  'executive-agent': {\n    triggers: {\n      workflows: ['report-workflow'],\n      agents: ['research-agent']\n    },\n    uses: {\n      integrations: ['integration-gmail', 'integration-attio']\n    }\n  }\n}\n\nTriggers\n\nTriggers declare their own metadata, while routing is declared through relationships.\n\ntypescript\nconst triggers: TriggerDefinition[] = [\n  {\n    resourceId: 'webhook-customer-created',\n    type: 'trigger',\n    triggerType: 'webhook',\n    name: 'Customer Created Webhook',\n    description: 'Triggers when a customer is created in Shopify',\n    status: 'prod',\n    webhookPath: '/webhooks/customer-created'\n  }\n]\n\nTrigger routing is not configured on the trigger object itself.\n\nExternal Resources\n\nExternal resources can declare what they trigger and which integrations they use.\n\ntypescript\nconst externalResources: ExternalResourceDefinition[] = [\n  {\n    resourceId: 'external-n8n-sync',\n    type: 'external',\n    platform: 'n8n',\n    name: 'N8N Product Sync',\n    description: 'Syncs product data from Shopify to internal database',\n    status: 'prod',\n    triggers: { workflows: ['internal-sync-workflow'] },\n    uses: { integrations: ['integration-shopify'] }\n  }\n]\n\nThese declarations document the relationship. They do not programmatically connect the external platform.\n\nHuman Checkpoints\n\nHuman checkpoints declare which resources request approval and where approval can route.\n\ntypescript\nconst humanCheckpoints: HumanCheckpointDefinition[] = [\n  {\n    resourceId: 'approval-sales',\n    name: 'Sales Approval Queue',\n    description: 'Human approval for sales proposals',\n    status: 'prod',\n    requestedBy: { agents: ['sales-agent'] },\n    routesTo: { workflows: ['send-proposal-workflow'] }\n  }\n]\n\nActual human approval decisions are runtime choices, not automatic routing from the declaration alone.\n\nValidation\n\nCommand View shows relationships validated during deploy and API registration.\n\nValidation checks:\n\n- Referenced resource IDs exist.\n- Agent and workflow IDs are unique.\n- External resource references are valid.\n- Human checkpoint routes exist.\n- Model configs have valid providers, models, and API key references.\n\nThese checks cover declared relationships and registry consistency. They do not infer every runtime execution.trigger(...) target, especially when the target is computed dynamically.\n\nWhen validation errors occur, API startup fails with a descriptive error such as:\n\ntext\nRegistryValidationError: [YourOrg] Resource 'my-agent' uses non-existent integration: integration-attio\n\nFix validation errors by updating the manifest to reference the correct IDs or by adding the missing resource definition.\n\nUsing Command View\n\nVisualization Features\n\nCommand View uses Cytoscape graph modes:\n\n- Map: keeps organization structure visible and honors hidden-resource visibility.\n- Trace: resolves directed paths and reveals resources for the active trace.\n- Impact: pivots around the selected node and reveals related resources for impact review.\n\nFilter panel capabilities:\n\n- Search across nodes, relationships, and IDs.\n- Filter by node kind, resource type, environment, topology presence, integrations, and resource facets.\n- Toggle resource visibility and diagnostic/testing resource visibility.\n- Show visible and hidden resource counts in the same control surface.\n\nHidden resource behavior:\n\n- Resource nodes are hidden by default so the organization structure remains readable.\n- Structural nodes remain visible as the navigation skeleton.\n- Selecting a visible node can reveal directly connected hidden resources.\n- Diagnostic and testing resources are hidden by default and can be revealed from the filter panel.\n\nExpand Around behavior:\n\n- Select a node, open Details, and use Expand Around to preview nearby graph context before revealing it.\n- Semantic presets cover coverage, operational dependencies, organization context, and impact paths.\n- Feature, surface, entity, and capability nodes default to Coverage.\n- Resource nodes default to Operational Dependencies.\n- Preview counts show hidden resources before Apply reveals the graph patch.\n\nRead-only constraints:\n\n- No drag and drop.\n- No connection editing.\n- No graph mutation from the visualization layer.\n\nManifest Debugging\n\nUse Command View to verify:\n\n1. Resources appear as nodes.\n2. Relationships show as edges.\n3. Integration connections exist.\n4. Trigger invocations are declared correctly.\n5. Orphaned resources are intentional.\n\nCommon issues:\n\n- Typo in a resource ID reference.\n- Missing relationship declaration.\n- Incorrect integration credential name.\n- External resource missing a bidirectional declaration.\n\nSystem Understanding\n\nUseful exploration questions:\n\n- What triggers this workflow?\n- What integrations does this agent use?\n- What happens after this approval?\n- If this integration fails, what breaks?\n\nVisual patterns:\n\n- Hub nodes with many connections indicate critical resources.\n- Linear chains show sequential workflows.\n- Branching shows conditional logic.\n- Isolated nodes may indicate unused resources.\n\nTroubleshooting\n\nEmpty Graph\n\nLikely causes:\n\n- Organization has no resources defined.\n- Search, environment, node kind, topology, or resource facet filters hide all graph elements.\n- Command View resources are hidden and no structural nodes match current filters.\n- Validation errors prevented serialization.\n\nCheck:\n\n1. API logs for validation errors.\n2. Network tab for the /api/command-view response.\n3. Manifest resources arrays.\n4. Filter panel visibility and filter state.\n\nFix:\n\n- Add resources to the manifest.\n- Fix validation errors.\n- Reveal resources or reset graph filters.\n\nMissing Edges\n\nLikely causes:\n\n- Relationship is not declared in the manifest.\n- Resource ID reference has a typo.\n- Validation passed but the relationship declaration is incomplete.\n\nCheck:\n\n1. Manifest relationships field.\n2. Resource ID spelling and case.\n3. API response includes both nodes.\n\nFix the relationship declaration in the manifest.\n\nNode Not Appearing\n\nLikely causes:\n\n- Resource is not in the correct manifest array.\n- Resource is hidden by visibility controls.\n- Status, resource type, topology, or facet filters exclude the node.\n- Duplicate ID caused validation failure.\n\nCheck:\n\n1. Manifest includes the resource in the correct array.\n2. Filter panel visibility and filter state.\n3. Resource status field.\n4. API logs for duplicate ID errors.\n\nFix by adding the resource, revealing resources, or resetting filters.\n\nValidation Errors on Startup\n\nCommon error shape:\n\ntext\nRegistryValidationError: [OrgName] Resource 'resource-id' uses non-existent integration: integration-name\n\nCommon causes:\n\n- Typo in integration credential name.\n- Resource referenced before definition.\n- Missing import.\n\nFix:\n\n- Verify credential names match integration definitions.\n- Ensure all resources exist in manifest arrays.\n- Check module dependency statements in the manifest module.\n\nBest Practices\n\nKeep relationships current when resources change:\n\n1. Add new tools, then update uses.integrations.\n2. Add workflow invocation, then update triggers.workflows.\n3. Add agent delegation, then update triggers.agents.\n4. Add approval gate, then update the human checkpoint requestedBy.\n\nUse descriptive IDs:\n\n- integration-shopify-store-alpha instead of integration-1.\n- trigger-customer-created-webhook instead of trigger-webhook.\n- approval-sales-proposals instead of approval-1.\n\nValidate early and often:\n\nbash\npnpm dev:api\n\nAPI startup runs registry validation. Fix validation errors immediately because they prevent graph visualization.\n\nReview Command View regularly to onboard team members, plan new features, trace execution paths, and audit integration dependencies.\n\nRelationship Enforcement\n\nRelationships are declarations, not routing.\n\n| Layer | What it does | Enforcement |\n| --- | --- | --- |\n| DeploymentSpec.relationships | Declares relationships such as workflow A triggers workflow B | Validated at startup so IDs must exist |\n| buildEdges() in serialization.ts | Serializes declarations into CommandViewEdge[] | Pure transformation, no runtime check |\n| Runtime workflow and agent code | Calls resources through execution.trigger(...) or equivalent wiring | Independent of declarations |\n\nThe Resource Registry validates that declared targets reference real resource IDs during deploy and registration. However, there is no guarantee that declared graph relationships match runtime reality. Code can call a resource that is not declared in relationships, and that runtime call will not fail solely because the declaration is missing.\n\nEnforcement status:\n\n| Category | Validated at startup | Matches runtime | Status |\n| --- | --- | --- | --- |\n| Resource IDs unique | Yes | Yes, because lookup works | Enforced |\n| Input schema matches execution interface | Yes | Yes, because validation uses it | Enforced |\n| Relationship targets exist | Yes | No, invocations can be dynamic strings | Partially enforced |\n| Trigger routing | No | No, webhook handlers can hardcode routes | Decorative |\n| Tool availability per agent | No | No, tools are built dynamically by factories | Decorative |\n| Model config | Yes | No, runtime selects from environment variables | Decorative |\n| Integration usage | Partially, IDs checked | No, credentials resolve at runtime | Decorative |\n\nNon-Executable Node Types\n\nTriggers, integrations, external resources, and human checkpoints are non-executable node types. They exist for Command View.\n\n- TriggerDefinition does not set up actual routing. Webhook routing is independent.\n- IntegrationDefinition is a credentials reference with provider and credentialName; it does not connect to a provider by itself.\n- ExternalResourceDefinition documents a third-party automation but has no programmatic link to that platform.\n- HumanCheckpointDefinition documents approval queues and routes. Actual routing is determined by human choice and workflow code.\n\nRuntime Relationship Guard\n\nThere is no general runtime guard that discovers every nested execution target at call time. Deployed SDK workers can invoke nested resources through execution.trigger(...) and the API dispatcher, so dynamic targets can drift from DeploymentSpec.relationships even when deploy-time validation passes.\n\nDeploy-Time Validation\n\nResources are deployed through elevasis-sdk deploy. The SDK includes relationships in DeployMetadata, validates the resulting DeploymentSpec locally, and the API validates the merged deployment before registerOrganization().\n\nKey files:\n\n- packages/sdk/src/cli/commands/deploy.ts\n- apps/api/src/deployments/service.ts\n- packages/core/src/platform/registry/validation.ts\n\nAccepted Decorative Gaps\n\nThese gaps are inherent to the architecture and cannot be fully validated at deploy time:\n\n- Runtime invocation drift, especially with computed target IDs.\n- Tool declarations, because agents build tools dynamically by factory.\n- Model config, because runtime LLM calls use environment variables.\n- External resource triggers, because routing lives in external platforms.\n\nRelated References\n\n- /knowledge read knowledge.platform-composition-patterns\n- /knowledge read knowledge.platform-integration-patterns\n- /knowledge read knowledge.platform-capabilities"
-  },
-  {
-    id: "knowledge.platform-composition-patterns",
-    title: "Platform Composition Patterns",
-    summary: "Reference for composing agents, workflows, integrations, tools, observability, scaling, error handling, and security into complete Elevasis automation systems.",
-    bodyText: "Overview\n\nUse this reference to choose how Elevasis resources compose into complete systems. The core decision is whether reasoning, deterministic orchestration, or a hybrid of both should own the business flow.\n\nThree primary patterns exist:\n\n- Agent-centric: an agent is the primary orchestrator, and workflows or integrations are tools.\n- Workflow-centric: a workflow is the deterministic pipeline, and agents appear only as processing steps.\n- Hybrid: agents decide what should happen, and workflows execute reliable sequences.\n\nSystem Architecture Patterns\n\nAgent-Centric Systems\n\nPattern: Agent is the primary orchestrator; workflows and integrations are tools.\n\ntext\nTrigger to Agent\n           |- Tool: Integration A\n           |- Tool: Integration B\n           |- Tool: Workflow 1 via resource invocation\n           - Tool: Workflow 2 via resource invocation\n\nUse this pattern for ambiguous goals, dynamic decision-making, multi-turn conversations, and business logic that requires judgment.\n\nStrengths:\n\n- Flexible and adaptive.\n- Handles ambiguity well.\n- Can delegate to specialist resources.\n- Supports natural language interaction.\n\nWeaknesses:\n\n- Token cost per execution.\n- Non-deterministic LLM variance.\n- Requires strong observability for debugging.\n- Usually slower than deterministic workflows.\n\nWorkflow-Centric Systems\n\nPattern: Workflow is the pipeline; agents are processing steps.\n\ntext\nTrigger to Workflow\n           |- Step 1: Integration A reads data\n           |- Step 2: Agent processes or reasons\n           |- Step 3: Integration B writes result\n           - Step 4: Conditional routing\n\nUse this pattern for predictable sequences, data transformation pipelines, integration orchestration, and fixed business logic.\n\nStrengths:\n\n- Deterministic and reliable.\n- Fast execution.\n- Easy to debug step-by-step.\n- No token cost unless an agent step is included.\n\nWeaknesses:\n\n- Rigid, because steps are predefined.\n- Does not handle ambiguity well.\n- Requires code changes for logic updates.\n\nHybrid Systems\n\nPattern: Agents decide, workflows execute. This is the recommended default for complex automation.\n\ntext\nTrigger to Agent decides what to do\n           |- Invokes: Workflow A\n           |- Invokes: Workflow B\n           - Uses: Integration C directly\n\nWorkflow A:\n  |- Integration D reads\n  |- Agent processes a specific subtask\n  - Integration E writes\n\nUse this pattern when the system needs variable paths, reasoning, reliability, and a mix of predictable and unpredictable steps.\n\nStrengths:\n\n- Flexible where needed and reliable where possible.\n- Cost-efficient because workflows do not use tokens by default.\n- Good observability across agent reasoning and workflow steps.\n\nResource Composition Patterns\n\nAgent + Tools\n\nUse direct integration access for simple or frequent operations.\n\nTool categories:\n\n- Base tools: always available, high-frequency operations such as read queries or cached data access. Example: attiogetrecord.\n- Knowledge Map tools: lazy-loaded, low-frequency operations such as write operations or domain-specific capabilities. Examples: attiocreatecontact, dropboxuploadfile.\n- Resource invocation tools: delegate to workflows for deterministic sequences or call specialist agents.\n\nTool creation example:\n\ntypescript\nconst tool = createAttioCreateRecordTool('elevasis-attio')\n\nCredential names resolve to organization-scoped storage. RLS policies enforce organization isolation, credentials are encrypted at rest, and OAuth tokens can refresh automatically.\n\nAgent + Workflow\n\nUse an agent for reasoning and a workflow for deterministic execution.\n\ntext\nTrigger to Agent reasoning\n          |- Direct tool: read integration\n          |- Invoke tool: Workflow A\n          - Invoke tool: Workflow B\n\nExecution flow:\n\n1. Agent analyzes the request.\n2. Agent invokes a workflow through a tool call.\n3. Workflow executes deterministic steps without token cost.\n4. Agent explains the result to the user.\n\nUse this pattern when the system needs both reasoning and reliability, has multiple execution paths, or should minimize token use by moving predictable work into workflows.\n\nWorkflow + Integration\n\nUse a workflow to orchestrate deterministic integration sequences.\n\ntext\nTrigger to Workflow\n          |- Step 1: Integration A reads\n          |- Step 2: Transform pure function\n          |- Step 3: Integration B writes\n          - Step 4: Notify\n\nUse this pattern for predictable step sequences, data transformation pipelines, integration orchestration, and cost-sensitive work that does not need LLM reasoning.\n\nPattern Selection Guide\n\n| Requirement | Pattern | Example |\n| --- | --- | --- |\n| Ambiguous goals | Agent-centric | Business orchestration with variable outcomes |\n| Predictable sequence | Workflow-centric | Shopify to CRM sync |\n| Hybrid needs | Agent + workflow | Support router where agent decides and workflow executes |\n| \\>10 tools | Knowledge Map | Agent with many domain capabilities |\n| High-frequency reads | Base tools | Attio read operations |\n| Low-frequency writes | Lazy-loaded tools | CRM updates or page creation |\n| External services | Integration tools | Attio, Gmail, Google Sheets |\n| Deterministic pipelines | Workflow + integration | Data transformation |\n\nComplexity guidelines:\n\n- Simple, 1-2 resources: agent with base tools, or workflow with 1-2 integrations.\n- Medium, 3-5 resources: agent plus Knowledge Map with 2-3 nodes, or workflow plus an agent step.\n- Complex, 6+ resources: agent plus Knowledge Map plus memory preload, or multi-integration workflows.\n\nCross-Cutting Concerns\n\nObservability\n\nTrack these surfaces:\n\n- Agent iterations, including reasoning and actions.\n- Workflow steps, including inputs and outputs.\n- Tool calls, including integration requests and responses.\n- Errors and retries.\n- Token usage and cost.\n\nPrimary tools:\n\n- Execution Logs for SSE-based debugging.\n- Activity Log for the real-time stream.\n- Execution Health for cost tracking and ROI review.\n- Command View for system architecture and dependency review.\n\nCost Tracking\n\nAgent cost comes from per-iteration token usage, model pricing, and tool execution cost. Workflow cost is usually zero token cost plus any external integration API fees.\n\nOptimization rules:\n\n- Use workflows for predictable tasks.\n- Lazy-load tools for 80-95% token savings.\n- Cache frequently accessed stable data.\n- Choose the appropriate model per task.\n\nScaling Strategies\n\nHorizontal scaling:\n\n- Keep agent execution stateless.\n- Store sessions in the database.\n- Let a load balancer distribute requests.\n\nVertical optimization:\n\n- Preload memory to reduce iteration count.\n- Lazy-load tools to reduce token usage.\n- Batch tool operations where possible.\n- Use parallel integration calls when the steps are independent.\n\nError Handling\n\nAgent error handling:\n\n- Tool errors are returned to the agent so it can reason about recovery.\n- Iteration limits prevent infinite loops.\n- Timeout protection constrains long-running tools and executions.\n- Graceful degradation explains what failed.\n\nWorkflow error handling:\n\n- Step retry logic uses exponential backoff, commonly 1, 4, and 9 minutes.\n- Conditional routing can send failures to an alternative step.\n- Manual intervention can route work to a human checkpoint.\n- Idempotent steps should be safe to retry.\n\nExample:\n\ntypescript\n{\n  id: 'sync-to-crm',\n  handler: async ({ input, context }) => {\n    try {\n      return await crmClient.createContact(input)\n    } catch (error) {\n      if (error.code === 'DUPLICATE') {\n        return crmClient.updateContact(input)\n      }\n\n      throw error\n    }\n  },\n  next: { type: 'linear', target: 'send-notification' }\n}\n\nSecurity\n\nCredential management:\n\n- Store credentials in the credentials table.\n- Encrypt values at rest.\n- Scope records by organization with RLS policies.\n- Refresh OAuth tokens automatically where supported.\n- Never store API keys in code.\n\nMulti-tenancy isolation layers:\n\n1. Database RLS on tenant-scoped tables.\n2. API middleware that requires organization context.\n3. Resource registry lookups scoped to the organization.\n4. Command View filtered by organization.\n\nBest Practices\n\n1. Start with a single agent or workflow, then add complexity only when needed.\n2. Build the working version before optimizing for caching or lazy loading.\n3. Put domain logic in agents and execution flow in workflows.\n4. Lazy-load large or low-frequency tool groups.\n5. Cache stable data, not fast-changing operational state.\n\nCommon mistakes:\n\n- Creating a Knowledge Map for fewer than five tools.\n- Using a workflow for one integration call when an agent tool would be simpler.\n- Loading more than ten tools as base tools.\n- Putting domain logic into workflows where it becomes hard to test and adapt.\n- Mixing unrelated concerns in one knowledge node.\n\nRelated References\n\n- /knowledge read knowledge.platform-integration-patterns\n- /knowledge read knowledge.platform-command-view"
-  },
-  {
-    id: "knowledge.platform-integration-patterns",
-    title: "Platform Integration Patterns",
-    summary: "Reference for connecting Elevasis agents and workflows to external services through adapters, OAuth, API keys, tenant-isolated credentials, retries, and tests.",
-    bodyText: "Overview\n\nIntegration patterns define how Elevasis agents and workflows connect to external services such as Gmail, Attio, Google Sheets, and custom APIs. The platform uses a standardized adapter pattern with OAuth 2.0 and API key authentication backed by tenant-isolated credentials.\n\nCore patterns:\n\n- Direct integration, where a resource uses integration tools directly.\n- Integration workflow, where a workflow coordinates multiple integrations.\n- Shared integration, where multiple resources use the same credential set.\n- Multi-account integration, where the same provider has separate credentials for different contexts.\n\nDirect Integration Pattern\n\nPattern: Resource uses an integration tool.\n\nUse direct integration tools when an agent or workflow performs frequent operations against a provider.\n\nCharacteristics:\n\n- Tools are always available to the resource.\n- There is no additional navigation overhead.\n- The pattern is optimized for frequent read-heavy operations.\n\nTool factory location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-tools.ts\n\nTool factories use createIntegrationTool() with a credentialName parameter. Example: createAttioCreateRecordTool(credentialName).\n\nIntegration Workflow Pattern\n\nPattern: Agent invokes a workflow, and the workflow uses integrations.\n\nUse an integration workflow for complex multi-step operations that need deterministic orchestration.\n\nExample lead capture flow:\n\n1. Webhook trigger receives the event.\n2. Workflow creates an Attio contact.\n3. Workflow sends a Gmail notification.\n4. Workflow returns confirmation.\n\nCharacteristics:\n\n- Deterministic execution order.\n- Step-level error handling and retry.\n- Multiple integrations coordinated in one place.\n- Built-in audit trail through workflow execution.\n\nShared Integration Pattern\n\nPattern: Multiple resources share the same integration.\n\nUse shared integrations for organization-wide providers that should use one credential set.\n\nExample:\n\ntext\npackages/elevasis-operations/src/index.ts\n\nCharacteristics:\n\n- One credential per integration.\n- Centralized credential management.\n- Shared across agents and workflows.\n\nMulti-Account Pattern\n\nPattern: Same provider, different credentials.\n\nUse this pattern for department-specific provider instances or separate dev/prod environments.\n\nExample:\n\ntypescript\nconst salesTool = createAttioCreateRecordTool('attio-sales')\nconst supportTool = createAttioCreateRecordTool('attio-support')\n\nDisambiguate multi-account tools with explicit tool names:\n\ntypescript\nconst tool = createAttioToolNamed(\n  'attiosalescreaterecord',\n  'attio-sales',\n  'createRecord'\n)\n\nAuthentication Patterns\n\nOAuth 2.0 vs API Key\n\n| Aspect | OAuth 2.0 | API key |\n| --- | --- | --- |\n| Auth flow | Browser redirect plus token exchange | Direct API key |\n| Setup complexity | High: client ID, secret, redirect URL | Low: single API key |\n| Token refresh | Automatic refresh token rotation | Manual key rotation |\n| Scope control | Granular permission scopes | Full access or none |\n| User context | Per-user authorization | Service-level access |\n| Revocation | User can revoke anytime | Manual key deletion |\n\nOAuth 2.0 Pattern\n\nProviders include Gmail and Google Sheets.\n\nCredential format:\n\ntypescript\ninterface OAuthToken {\n  provider: string\n  accessToken: string\n  refreshToken: string\n  expiresAt: string\n  tokenType: 'Bearer'\n  scope?: string\n}\n\nexpiresAt is an ISO 8601 timestamp. The platform handles token refresh when supported by the provider and credential implementation.\n\nAPI Key Pattern\n\nProviders include Attio and custom APIs.\n\nCredential format:\n\ntypescript\ninterface APIKeyCredentials {\n  apiKey: string\n}\n\nProvider-specific validation belongs in the adapter. For Attio, see:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/attio/attio-adapter.ts\n\nCredential Management\n\nCredentials are stored in the credentials table.\n\nKey columns:\n\n- organizationid for tenant isolation.\n- name, such as elevasis-attio.\n- provider, such as gmail or attio.\n- encryptedvalue containing encrypted JSON.\n\nSecurity rules:\n\n- RLS policies enforce tenant isolation.\n- Values are encrypted at rest.\n- Credentials do not cross organization boundaries.\n\nBest practices:\n\n- Store credentials encrypted in the database.\n- Use tenant-isolated credential names.\n- Validate credentials before API calls.\n- Rotate API keys regularly.\n- Use least-privilege OAuth scopes.\n\nDo not:\n\n- Hardcode credentials in code.\n- Share credentials across organizations.\n- Log credential values.\n- Store provider API keys in environment variables for tenant integrations.\n- Reuse the same credential name for dev and prod.\n\nCredential resolution flow:\n\n1. Tool requests a credential by name.\n2. Platform queries credentials with the current organizationid.\n3. Platform decrypts the credential.\n4. Adapter validates the credential against the provider schema.\n5. Tool passes the credential to the provider adapter.\n6. Usage is logged without credential values.\n\nImplementation reference:\n\ntext\npackages/core/src/execution/engine/tools/integration/tool.ts\n\nError Handling Patterns\n\nAdapters should convert provider errors into platform tooling errors.\n\nCommon error categories:\n\n- credentialsinvalid for invalid or missing credentials.\n- apierror for provider API errors.\n- networkerror for network or timeout failures.\n- validationerror for invalid parameters.\n- methodnotfound for unknown adapter methods.\n\nRetry strategy:\n\n- Network errors: retry with exponential backoff, commonly 1, 2, and 4 seconds.\n- Auth errors: fail immediately because the credential needs attention.\n- Validation errors: fail immediately because the input needs correction.\n- Rate limits: retry after reset when the provider exposes a reset time.\n- Workflow-level retries: commonly 3 attempts with 1, 4, and 9 minute delays.\n\nAdapter Development\n\nAdapter class location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-adapter.ts\n\nAdapter classes implement BaseIntegrationAdapter and contain call() and validateCredentials() methods.\n\nTool factory location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-tools.ts\n\nTool factories export create{Provider}{Operation}Tool(credentialName) functions.\n\nTests belong under:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/tests/\n\nRegistration happens in:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/index.ts\n\nTesting Strategies\n\nUnit testing:\n\n- Mock external APIs.\n- Cover credential validation.\n- Cover API call construction.\n- Cover response parsing.\n- Cover error handling.\n\nIntegration testing:\n\n- Use real API calls only with test accounts or test workspaces.\n- Clean up test data after tests.\n- Run in CI only when secret credentials are available.\n- Keep provider behavior mocked in unit tests.\n\nAgent testing:\n\n- Test agents using integration tools at the resource boundary.\n- Tenant project agent tests normally live under external/{org}/src/agents/{agent}/tests/.\n\nRelated References\n\n- /knowledge read knowledge.platform-composition-patterns\n- /knowledge read knowledge.platform-command-view\n- /knowledge read knowledge.platform-capabilities"
-  },
-  {
-    id: "knowledge.what-is-elevasis",
-    title: "What is Elevasis",
-    summary: "Company overview, positioning, value proposition, and pricing for the AI orchestration platform",
-    bodyText: 'Executive Summary\n\nCompany: Bootstrapped AI orchestration platform for done-for-you business automation\n\nFounder: Solo (Alex, 34), bootstrapped\n\nMarket: Service-based SMBs that need practical AI automation without building internal AI teams\n\nGTM: Content-led marketing, proof assets, consultative sales, and land-and-expand pricing\n\nCompany Overview\n\nCurrent Status\n\nThe platform core is production-ready enough to support client-facing demonstrations and implementation work. Current business focus is client acquisition, proof-building, and turning the platform into a repeatable service delivery system.\n\nFounder Profile\n\nAlex, 34 \u2014 Solo founder with software engineering background (BSCS degree). Previous: Ecommerce platforms, Streaming technology. No formal AI background \u2014 practitioner, not academic.\n\nWhat We Are\n\nOperating layer for AI automation. We help SMBs operate with closed-loop feedback, decision capture, and continuous learning \u2014 at SMB pricing with done-for-you implementation (NOT self-service).\n\nTarget Market\n\nICP: Service-based SMBs (2-50 employees, USA, $200K-$5M revenue)\n\nCore Pain: Capacity crisis, pipeline problems, operational chaos, growth blockers \u2014 too busy serving clients to grow their own business.\n\nPricing (Land-and-Expand)\n\n- Tier 1 \u2014 Foundation (1-2 workflows): $500-2k/mo\n- Tier 2 \u2014 Scaled Operations (3-5 workflows): $2k-5k/mo\n- Tier 3 \u2014 AI-Powered Systems (6+ workflows): $5k-15k+/mo\n\nAdditional workflows cost less due to shared infrastructure.\n\nValue Proposition\n\n"We find one bottleneck in your business, build an AI solution to fix it, and you only pay if it actually saves you time or makes you money."'
-  },
-  {
-    id: "knowledge.platform-capabilities",
-    title: "Platform Capabilities",
-    summary: "Authoritative overview of the Elevasis AI Orchestration Platform \u2014 what's built, what it does, and how the pieces fit together",
-    bodyText: "Overview\n\nElevasis is a production AI orchestration platform that coordinates workflows, autonomous agents, and human approvals into a unified operating layer for SMBs. Everything described below is implemented and running in production.\n\nCore Architecture:\n\n| Layer | What It Does | Key Components |\n| --- | --- | --- |\n| Execution | Runs workflows and agents with schema validation | Workflow Engine, Agent Framework, Execution Runner |\n| Control | Human oversight, approvals, and decision capture | Command Queue (HITL), Dynamic Forms, Action System |\n| Intelligence | Autonomous reasoning, tool use, and memory management | ReAct Agents, Knowledge Map, Session Memory |\n| Observability | Real-time visibility into cost, performance, and health | Cost Tracking, Metrics, Activity Log, SSE Streaming |\n| Platform | Multi-tenancy, security, scheduling, integrations | Registry, RLS, Scheduler, Credential Vault, SDK |\n\nExecution Engine\n\nAI Workflows\n\nGraph-based workflow execution with schema-validated steps and conditional routing. Steps define explicit routing: linear, conditional (rule-based branching), or terminal. Context flows through the entire workflow.\n\nAutonomous Agents\n\nProduction-grade ReAct-style agents with tool use, memory management, and security hardening.\n\nLLM Provider Support: OpenAI (GPT-5), Google (Gemini 3 Flash), Anthropic (Claude Sonnet 4.5), OpenRouter (GLM-5)\n\nHuman-in-the-Loop (HITL)\n\nThe Command Queue surfaces pending approvals as structured tasks. Admin reviews, approves or edits, and the workflow continues. Every critical decision \u2014 sending emails to prospects, updating customer records, publishing content \u2014 requires human approval.\n\nKnowledge Map\n\nOrganizational knowledge loaded lazily into agent context. 80-95% token savings vs. always-loading full context. Nodes link to features, teams, and other nodes.\n\nIntegrations (13 active)\n\nAttio CRM, Cal.com, Instantly (cold email), Resend, Apify, Google Maps, Tomba, Mails.so, Supabase, Stripe, OpenAI, Google Gemini, Anthropic Claude.\n\nSDK\n\nTypeScript-based resource development with local testing, validation, and deployment pipeline. External consumers define workflows and agents in their own repos and deploy via elevasis-sdk deploy."
-  },
-  {
-    id: "knowledge.client-testimonials",
-    title: "Testimonials",
-    summary: "Customer testimonials and case study permissions from previous client work",
-    bodyText: `Status: 4 testimonials from 2 clients | Source: Upwork client work (2024)
-
-Testimonials
-
-Xero Automation \u2014 The Invoice Chase That Disappeared
-
-Client: Word of Mouth Agency
-
-Result: 10+ hours/week saved. Zero manual follow-up emails.
-
-> "Working with Alex at Elevasis to automate our Xero follow-ups has been a game-changer. We're set to save over 5 hours a week, but more importantly, it has completely removed the stress of chasing invoices. The process was smooth and professional."
-
-Permission: Case study approved with company name.
-
-Influencer Discovery \u2014 From Spreadsheet Hell to Strategic Decisions
-
-Client: Word of Mouth Agency (Perth, Australia)
-
-Result: 10+ hours/week saved. Research scope: 50 to 200+ influencers. Team focus shifted from data to strategy.
+    id: "knowledge.org-model-actions",
+    title: "Organization Model Actions",
+    summary: "Actions are the invokable semantic layer of the Organization Model -- they map to resources, affect entities, bind to knowledge, and expose four invocation types.",
+    bodyText: `Overview
 
-> "Working with Alex at Elevasis to automate our Influencer Discovery has been a game-changer. We're set to save over 5 hours a week..."
+Actions are the invokable semantic layer of the Organization Model. They declare what an organization can do: what resources implement them, which entities they affect, and how they can be called.
 
-Permission: Case study approved with company name.
+Actions are authored in the OM.actions domain map and projected as action graph nodes by buildOrganizationGraph(). Each action emits a contains edge from the organization root and optional mapsto, affects, and triggers edges based on its declared fields.
 
-EMRG Media \u2014 4 Automations for NYC's Premier Events Firm
+Source schema: packages/core/src/organization-model/domains/actions.ts
 
-Client: EMRG Media (NYC, est. 2001). Clients include Google, YouTube, Sony Music, Fiverr, Equinox.
+What Actions Are
 
-What We Built:
-1. Case Study Generator \u2014 7-10 hours \u2192 2 hours. Publication rate: 1/quarter \u2192 2/month.
-2. EMRG Follow-Up Generator \u2014 Automated post-event follow-ups with signature management.
-3. Event Sponsor Tracker \u2014 Automated sponsor pipeline tracking and communications.
-4. Lead Scraper \u2014 Automated discovery of event planning prospects.
+An action is a named, typed, invokable operation. It is not executable code -- it is a semantic declaration that says "this operation exists, it can be called this way, it affects these business objects, and it is implemented by this resource."
 
-Fame Stats:
-- 3,500+ attendees at The Event Planner Expo
-- 25+ year track record
-- Fortune 500 client roster
+Actions answer questions like:
 
-Permission: Case study approved with company name.`
-  },
-  {
-    id: "knowledge.understanding-elevasis",
-    title: "Understanding Elevasis Overview",
-    summary: "Company overview, product positioning, and platform capability context for Elevasis AI orchestration platform",
-    bodyText: "Lean documentation explaining what Elevasis is and what the platform can do. This section provides the foundational context for business conversations and technical evaluation.\n\nElevasis is a done-for-you AI automation service backed by a production-grade platform. The company targets service-based SMBs (2-50 employees, $200K-$5M revenue) who are too busy serving clients to grow their own business.\n\nKey Facts\n\n- Stage: Pre-revenue, platform 100% complete, client acquisition active\n- Offer: Done-for-you AI automation -- we build and maintain the workflows, no coding required\n- ICP: Service-based SMBs (2-50 employees, $200K-$5M revenue, USA)\n- Pricing: $500-$2k/mo (Foundation) \u2192 $2k-$5k/mo (Scaled) \u2192 $5k-$15k+/mo (AI-Powered)\n- Market: Early Adopters stage, $23.77B TAM growing to $87.7B by 2032\n- Competitive position: No dominant done-for-you SMB AI provider exists; blue ocean\n\nWhen to Use Each Document\n\n| Situation | Document |\n| --- | --- |\n| First conversation with any audience | What is Elevasis |\n| Technical evaluation or demo prep | Platform Capabilities |\n\nDocumentation\n\n- What is Elevasis \u2014 AI orchestration platform overview, company stage, value proposition, and pricing tiers\n- Platform Capabilities \u2014 Authoritative overview of what is built, what it does, and how the pieces fit together"
-  },
-  {
-    id: "knowledge.marketing-overview",
-    title: "Marketing Overview",
-    summary: "Marketing documentation for Elevasis - strategy, website infrastructure, and content systems",
-    bodyText: "Welcome to the Elevasis marketing documentation. This section covers marketing strategy, website implementation, and content systems.\n\nDocumentation\n\nStrategy\n\n- Overview \u2014 Channel strategy, inbound content system, and proof-led demand generation\n\nWebsite\n\nThe marketing website's technical infrastructure, setup, and SEO docs now live under Architecture \u2192 Website."
-  },
-  {
-    id: "knowledge.ai-orchestration-principles",
-    title: "AI Orchestration Principles",
-    summary: "The 4 principles that separate production AI from toy automation",
-    bodyText: `Most AI automation fails. Not because the technology is bad, but because it's implemented without the principles that make AI systems work in production.
+- What operations does the sales.lead-gen system expose?
+- Which workflow implements the lead-gen.company.qualify operation?
+- What entities does this action modify?
+- How can this action be invoked from the CLI, an API, or an MCP client?
 
-These four principles separate toy automation from AI systems that actually run businesses.
+ActionInvocation Kinds
 
-The 4 Principles
+Each action can declare one or more invocations. An invocation describes how the action is called.
 
-1. Integrated: Works With Your Existing Systems
+| Kind               | Fields                                                     | Description                               |
+| ------------------ | ---------------------------------------------------------- | ----------------------------------------- |
+| slash-command    | command (must start with /), optional toolFactory    | Called from the CLI or agent tool surface |
+| mcp-tool         | server, name                                           | Exposed as an MCP tool on a named server  |
+| api-endpoint     | method (GET/POST/PATCH/DELETE), path, optional schemas | Called via HTTP API endpoint              |
+| script-execution | resourceId                                               | Executed by running a script resource     |
 
-Principle: AI must work with your existing tools, not replace them.
+Multiple invocations on one action mean the same semantic operation is reachable through multiple surfaces.
 
-AI that doesn't connect to your CRM, your email, your calendar, your existing workflows is a toy. Real AI automation works WITH what you already have \u2014 not instead of it.
+Scope
 
-- Your 50 Zapier workflows keep running
-- Your CRM stays your CRM
-- AI adds intelligence on top, not a rip-and-replace
+Actions are either global or domain-scoped.
 
-The anti-pattern: "Use our AI instead of everything else." Creates vendor lock-in and throws away your existing investment.
+- Global (scope: 'global'): available across all systems.
+- Domain-scoped (scope: { domain: '<modelId>' }): associated with a specific OM domain such as sales.
 
-2. Improving: Gets Smarter Over Time
+Systems reference actions through ActionRef entries on system.actions[], with an intent of exposes (the system owns the action) or consumes (the system calls the action). This relationship emits a uses edge from the system to the action in the graph.
 
-Principle: AI must learn from every decision and improve continuously.
+Affects and Knowledge Bindings
 
-Static automation is just fancy if-then logic. Real AI captures every approval, rejection, and edit \u2014 then uses that data to get smarter.
+Actions can declare which entities they modify via the affects field (array of entity IDs). Each entry emits an affects edge from the action to the entity node.
 
-The anti-pattern: "Set it and forget it." Systems that don't learn stay dumb forever.
+Actions can also declare knowledge bindings (array of knowledge node IDs) that reference relevant reference material. These bindings are not graph edges; they associate documentation with the action for surfacing in the Knowledge Base.
 
-3. Observable: You See What AI Is Doing
+Resource Mapping
 
-Principle: You must be able to see what AI systems are doing in real-time.
-
-Black-box automation is unacceptable for business operations. You need to see every action, every decision, every cost \u2014 as it happens.
-
-- Real-time activity feeds showing what's executing
-- Cost tracking per workflow, per execution
-- Token usage visibility
-- Execution logs for debugging
-
-The anti-pattern: "It just works, trust us." Systems without observability create anxiety and prevent adoption.
+The optional resourceId field links an action to its implementation resource. Setting resourceId emits a mapsto edge from the action node to the resource node. If the resource does not yet exist in OM.resources, the graph builder creates a stub resource node from the ID.
 
-4. Governed: Humans Control What Matters
+Lifecycle States
 
-Principle: Humans must approve important actions before execution.
-
-AI should handle the grunt work. But critical decisions \u2014 sending emails to prospects, updating customer records, publishing content \u2014 require human approval.
-
-- AI researches 50 prospects and drafts personalized emails
-- Before anything sends, it lands in your approval queue
-- You spend 10 minutes reviewing, approve or tweak
-- Only then does it execute
-
-The anti-pattern: "Fully autonomous AI." Systems without governance create risk and erode trust.`
+Actions follow a five-stage lifecycle: draft, beta, active, deprecated, archived. The default is active. Lifecycle state is authored on the action entry and is reflected in the graph node.`
+  },
+  {
+    id: "knowledge.org-model-entities",
+    title: "Organization Model Entities",
+    summary: "Entities model business objects owned by systems -- with table metadata, state catalogs, and typed entity links.",
+    bodyText: "Overview\n\nEntities are the business objects of the Organization Model. Each entity is a named, typed object owned by a system -- it corresponds to a database table, optionally participates in a state catalog, and can declare typed relationships to other entities.\n\nEntities are authored in the OM.entities domain map and projected as entity graph nodes by buildOrganizationGraph(). Each entity emits a contains edge from its owning system node and optional links edges to related entities.\n\nSource schema: packages/core/src/organization-model/domains/entities.ts\n\nWhat Entities Are\n\nAn entity declaration answers questions like:\n\n- What business objects does the sales.crm system own?\n- Which database table backs the crm.deal entity?\n- What states can a leadgen.company pass through?\n- How are crm.deal and crm.contact related?\n\nEntities are not executable. They are semantic declarations that describe the shape of business data: who owns it, where it lives, what states it can be in, and how it connects to other objects.\n\nownedBySystemId\n\nEvery entity must declare ownedBySystemId -- the ID of the system responsible for it. The graph builder emits a contains edge from system:<ownedBySystemId> to the entity node. An entity can only be owned by one system.\n\nTable and Row Schema\n\nThe optional table field names the backing database table (e.g. crmdeals). The optional rowSchema field references a schema identifier that describes the row shape. These fields are informational references; they are not validated against the database at OM parse time.\n\nstateCatalogId\n\nThe optional stateCatalogId field links the entity to a state catalog. The graph builder uses this to project event nodes for each state transition:\n\n- For general status catalogs, the builder walks OM.statuses entries whose semanticClass matches the catalog ID.\n- For crm.pipeline, the builder also walks pipeline stages from OM.sales.\n- For delivery.task, the builder walks task statuses from OM.projects.\n- For lead-gen.company and lead-gen.contact, the builder walks the lead-gen stage catalog.\n\nEach matching status or stage generates an event node with an originatesfrom edge pointing back to the entity.\n\nTyped Entity Links\n\nThe links field declares typed relationships to other entities. Each link has:\n\n- toEntity -- the target entity ID.\n- kind -- one of belongs-to, has-many, has-one, or many-to-many.\n- via -- optional join key or junction table name.\n- label -- optional display label for the relationship.\n\nEach link emits a links edge from the entity node to the target entity node in the graph.\n\nExample Entity Shape\n\nA crm.deal entity owned by sales.crm, backed by the crmdeals table, in the crm.pipeline state catalog, with a has-many link to crm.contact via the dealcontacts junction:\n\n- id: crm.deal\n- ownedBySystemId: sales.crm\n- table: crmdeals\n- stateCatalogId: crm.pipeline\n- links: [{ toEntity: 'crm.contact', kind: 'has-many', via: 'dealcontacts' }]"
+  },
+  {
+    id: "knowledge.org-model-events",
+    title: "Organization Model Events",
+    summary: "Events are projected signals -- the OM has no authored event domain. They emit from resources and originate from entity state catalogs.",
+    bodyText: "Overview\n\nEvents are projected graph nodes. The Organization Model has no OM.events domain map that authors edit directly. Instead, events are derived by buildOrganizationGraph() from two sources: EventEmissionDescriptor entries on workflow and agent resources, and state catalog entries on entities.\n\nEvery event node carries a unique ID formed as \\<ownerId\\>:\\<eventKey\\>, a human-readable label, and an edge that connects it back to the node that produced it.\n\nProjection logic: packages/core/src/organization-model/graph/build.ts\n\nAuthored vs. Projected\n\nThe distinction matters because it determines where you change event data.\n\nEvents are never edited in a standalone events file. To change an event you must change its source:\n\n- To change a resource-emitted event, update the emits array on the workflow or agent entry in OM.resources.\n- To change an entity state-transition event, update the entity's stateCatalogId or the underlying status/stage entry in the relevant catalog domain.\n\nThe graph builder projects these into event graph nodes automatically on the next call to buildOrganizationGraph().\n\nEventEmissionDescriptor on Resources\n\nWorkflow and agent resource entries can declare an emits array. Each element is an EventEmissionDescriptor:\n\n| Field           | Type            | Description                                                   |\n| --------------- | --------------- | ------------------------------------------------------------- |\n| eventKey      | ModelIdSchema | Short key scoped to the owner resource (e.g. enrolled)      |\n| label         | string          | Human-readable label for the event                            |\n| payloadSchema | ModelIdSchema | Optional reference to a schema that describes the payload     |\n| lifecycle     | lifecycle enum  | Optional: draft, beta, active, deprecated, archived |\n\nThe graph builder constructs the full EventDescriptor by combining ownerId (the resource ID), ownerKind: 'resource', and the emission descriptor fields. The resulting event ID is \\<resourceId\\>:\\<eventKey\\>.\n\nAn emits edge is then projected from the resource node to the event node.\n\nOnly workflow and agent resource kinds support emits. integration and script resources do not.\n\noriginatesfrom Edges from Entity State Catalogs\n\nWhen an entity declares a stateCatalogId, the graph builder projects one event node per state transition available to that entity. These events use ownerKind: 'entity' and the resulting event ID is \\<entityId\\>:\\<eventKey\\>.\n\nA reversed originatesfrom edge is projected from the event node pointing back to the entity node. This edge direction is the opposite of emits: it signals that the event represents a state change that originates from the entity, not that the entity actively fires the event.\n\nThe builder resolves state catalogs as follows:\n\n- General status catalogs: walks OM.statuses entries whose semanticClass matches the entity's stateCatalogId.\n- crm.pipeline: also walks pipeline stages from OM.sales that reference the entity.\n- delivery.task: also walks task statuses from OM.projects.\n- lead-gen.company and lead-gen.contact: walks the LEADGENSTAGECATALOG constant, filtering by entity type.\n\ntriggers Edges to Policies\n\nWhen a policy declares trigger.kind: 'event', the graph builder looks up the projected event node by event ID and emits a triggers edge from the event node to the policy node. This edge is only emitted if the event node was already projected by the time the policy loop runs.\n\nPolicy triggers are the primary way events connect to downstream behavior. No triggers edge is emitted for events that no policy references.\n\nEventDescriptor Full Shape\n\nEventDescriptor is the resolved type used internally by the graph builder. It extends EventEmissionDescriptor with identity fields:\n\n| Field           | Type                       | Description                                           |\n| --------------- | -------------------------- | ----------------------------------------------------- |\n| id            | EventIdSchema            | Composite: \\<ownerId\\>:\\<eventKey\\>                 |\n| ownerId       | resource ID or model ID    | ID of the resource or entity that is the event source |\n| ownerKind     | 'resource' or 'entity' | Discriminates between the two projection paths        |\n| eventKey      | ModelIdSchema            | Short key, unique within the owner                    |\n| label         | string                     | Human-readable label                                  |\n| payloadSchema | ModelIdSchema (opt)      | Schema reference for payload shape                    |\n| lifecycle     | lifecycle enum (opt)       | Lifecycle state from the emission descriptor          |\n\nEventDescriptor is not stored in the graph node itself -- it is used transiently during graph construction to build the node and emit edges. The graph node stores id, kind: 'event', label, and sourceId.\n\nGraph Summary\n\n| Edge kind         | Direction                   | When emitted                                 |\n| ----------------- | --------------------------- | -------------------------------------------- |\n| emits           | resource node -> event node | Resource emits[] array is non-empty        |\n| originatesfrom | event node -> entity node   | Entity has a stateCatalogId                |\n| triggers        | event node -> policy node   | Policy trigger.kind === 'event' matches ID |"
+  },
+  {
+    id: "knowledge.org-model-graph-contract",
+    title: "Organization Model Graph Contract",
+    summary: "The canonical graph node and edge contract -- 10 node kinds, 12 edge kinds, and the resource-type overlay derived from the Organization Model.",
+    bodyText: "Overview\n\nThe Organization Model graph contract defines the typed node and edge taxonomy emitted by buildOrganizationGraph(). Every surface that reads or visualizes the OM -- including Command View -- works against this contract.\n\nThe graph has two categories of nodes: authored nodes derived directly from OM domain maps, and projected nodes derived by the graph builder from authored content. Events and stages are projected; all other node kinds are authored.\n\nSource schema: packages/core/src/organization-model/graph/schema.ts\nProjection logic: packages/core/src/organization-model/graph/build.ts\n\nNode Kinds\n\nTen node kinds are valid in the graph.\n\n| Kind           | Authored / Projected | Source                                                  |\n| -------------- | -------------------- | ------------------------------------------------------- |\n| organization | Projected            | Root node; always present; id is organization-model   |\n| system       | Authored             | OM.systems domain map                                 |\n| role         | Authored             | OM.roles domain map                                   |\n| action       | Authored             | OM.actions domain map                                 |\n| entity       | Authored             | OM.entities domain map                                |\n| event        | Projected            | Derived from resource emits and entity state catalogs |\n| policy       | Authored             | OM.policies domain map                                |\n| stage        | Projected            | Derived from OM.prospecting stage catalogs            |\n| resource     | Authored             | OM.resources domain map                               |\n| knowledge    | Authored             | OM.knowledge.nodes array                              |\n\nEdge Kinds\n\nTwelve edge kinds are valid in the graph.\n\n| Kind              | Direction                             | Meaning                                                       |\n| ----------------- | ------------------------------------- | ------------------------------------------------------------- |\n| contains        | parent -> child                       | Containment: organization to system, system to resource, etc. |\n| references      | source -> target                      | Cross-reference: role reports-to, agent invokes action        |\n| mapsto         | action -> resource                    | Action is implemented by a resource                           |\n| uses            | system -> action, stage -> action     | System or stage uses an action                                |\n| governs         | knowledge -> target, role -> system   | Knowledge node or role governs a target                       |\n| links           | entity -> entity                      | Typed entity relationship (belongs-to, has-many, etc.)        |\n| affects         | action -> entity                      | Action modifies or reads an entity                            |\n| emits           | resource -> event                     | Resource produces an observable event                         |\n| originatesfrom | event -> entity                       | Event originates from an entity state transition              |\n| triggers        | event -> policy, action -> policy     | Event or action invocation triggers a policy evaluation       |\n| appliesto      | policy -> system/action/resource/role | Policy governs the target                                     |\n| effects         | policy -> action/role                 | Policy effect invokes an action or notifies a role            |\n\nResource Type Overlay\n\nResource nodes carry an optional resourceType field that is a separate enum from kind. It is set by the graph builder from the OM resource kind field or from Command View data.\n\n| Value              | Description                       |\n| ------------------ | --------------------------------- |\n| workflow         | Deterministic automation pipeline |\n| agent            | LLM-driven reasoning resource     |\n| trigger          | Event-driven entry point          |\n| integration      | External service connector        |\n| external         | Third-party system reference      |\n| humancheckpoint | Human-in-the-loop review gate     |\n| script           | One-shot executable script        |\n\nAuthored vs. Projected Fields\n\nAuthored nodes\n\nSystem, role, action, entity, policy, resource, and knowledge nodes are authored in the OM domain maps. Their id, label, description, and domain-specific fields are set from OM source data.\n\nProjected nodes\n\n- Organization node: always present; id is always organization-model.\n- Event nodes: derived from two sources. Resource events come from resource.emits declarations on workflow and agent resources. Entity events come from the entity's stateCatalogId -- the builder walks the matching statuses and pipeline/project stage catalogs to generate one event node per transition.\n- Stage nodes: derived from OM.prospecting.companyStages and OM.prospecting.contactStages.\n\nProjected nodes are never authored directly. To add an event, declare emits on a resource or assign stateCatalogId to an entity.\n\nGraph Node Shape\n\nEach node has: id (graph-unique string), kind (one of the 10 kinds), label (display name), optional sourceId (OM domain ID), optional description, optional icon, optional enabled flag, and optional resourceType (resource nodes only).\n\nEach edge has: id (graph-unique string), kind (one of the 12 kinds), sourceId, targetId, optional label, and optional relationshipType (triggers, uses, or approval)."
+  },
+  {
+    id: "knowledge.org-model-policies",
+    title: "Organization Model Policies",
+    summary: "Policies govern systems, actions, resources, and roles -- with discriminated triggers, predicates, and effects.",
+    bodyText: "Overview\n\nPolicies are cross-cutting governance rules in the Organization Model. They declare what should happen when a trigger fires, under what conditions, and with what effect. Policies are authored in the OM.policies domain map and projected as policy graph nodes by buildOrganizationGraph().\n\nEvery policy emits a contains edge from the organization root and appliesto edges to each system, action, resource, or role it governs. When the trigger is event-based or action-based, an additional triggers edge connects the source node to the policy.\n\nSource schema: packages/core/src/organization-model/domains/policies.ts\n\nPolicyTrigger\n\nThe trigger is a discriminated union on kind that defines what activates the policy.\n\n| Kind                | Required fields | Description                                               |\n| ------------------- | --------------- | --------------------------------------------------------- |\n| event             | eventId       | Fires when the referenced event is projected in the graph |\n| action-invocation | actionId      | Fires when the referenced action is invoked               |\n| schedule          | cron          | Fires on a cron schedule (max 120 chars)                  |\n| manual            | none            | Fires only when explicitly triggered by a user or process |\n\nFor event triggers, the graph builder looks up the projected event node by eventId and emits a triggers edge from that event node to the policy node. For action-invocation triggers, a triggers edge is emitted from the action node to the policy node. Schedule and manual triggers produce no additional graph edges.\n\nPolicyPredicate\n\nThe predicate is a discriminated union on kind that defines the condition under which the policy effect is applied.\n\n| Kind         | Required fields                 | Description                                                |\n| ------------ | ------------------------------- | ---------------------------------------------------------- |\n| always     | none                            | Condition is unconditionally true; effect always fires     |\n| expression | expression (string, max 2000) | Arbitrary expression evaluated at runtime                  |\n| threshold  | metric, operator, value   | Numeric threshold check: lt, lte, eq, gte, or gt |\n\nThe default predicate if not specified is { kind: 'always' }.\n\nPolicyEffect\n\nThe actions field holds an ordered array of effects (PolicyEffect[]). At least one effect is required. Effects are a discriminated union on kind.\n\n| Kind               | Required fields     | Description                                                 |\n| ------------------ | ------------------- | ----------------------------------------------------------- |\n| require-approval | roleId (optional) | Blocks execution until a human approves; routes to the role |\n| invoke-action    | actionId          | Invokes the referenced action as a consequence              |\n| notify-role      | roleId            | Sends a notification to the specified role                  |\n| block            | none                | Stops execution entirely; no approval path                  |\n\nFor invoke-action effects, the graph builder emits an effects edge from the policy node to the referenced action node. For notify-role and require-approval effects that include a roleId, an effects edge is emitted from the policy node to the role node.\n\nappliesTo\n\nThe appliesTo field declares which OM entities the policy governs. It contains four ID arrays, all defaulting to empty:\n\n| Field         | Target kind | Graph edge emitted                        |\n| ------------- | ----------- | ----------------------------------------- |\n| systemIds   | system    | appliesto from policy to system node   |\n| actionIds   | action    | appliesto from policy to action node   |\n| resourceIds | resource  | appliesto from policy to resource node |\n| roleIds     | role      | appliesto from policy to role node     |\n\nA policy can apply to any combination of these targets simultaneously. A policy with all four arrays empty is valid but produces no appliesto edges.\n\nLifecycle\n\nPolicies follow the same five-stage lifecycle as systems and actions: draft, beta, active, deprecated, archived. The default is active. Lifecycle is authored on the policy entry and is reflected in the graph node.\n\nThe order field controls domain-map iteration order. The convention is multiples of 10 (10, 20, 30, ...) to allow easy insertion between existing entries.\n\nGraph Summary\n\n| Edge kind    | Direction                                  | When emitted                                                                       |\n| ------------ | ------------------------------------------ | ---------------------------------------------------------------------------------- |\n| contains   | organization root -> policy node           | Always; every policy is contained by the organization root                         |\n| appliesto | policy node -> system/action/resource/role | For each non-empty appliesTo.Ids entry                                          |\n| triggers   | event or action node -> policy node        | When trigger.kind is event or action-invocation                              |\n| effects    | policy node -> action or role node         | For invoke-action, notify-role, and require-approval effects with a roleId |"
+  },
+  {
+    id: "knowledge.platform-command-view",
+    title: "Platform Command View",
+    summary: "Reference for Command View, the visual Organization Model graph surface that projects systems, resources, actions, entities, events, and policies into an explorable operational view.",
+    bodyText: "Overview\n\nCommand View is the visual surface for the Organization Model graph. It projects the OM -- systems, resources, actions, entities, events, and policies -- into an explorable graph using the same node and edge taxonomy emitted by buildOrganizationGraph().\n\nIt answers operational questions such as:\n\n- What systems own which resources?\n- What does this agent map to in the OM?\n- Which actions affect which entities?\n- If a resource goes offline, what policies or actions reference it?\n- What events originate from this entity or resource?\n\nAccess Command View through the Knowledge area at /knowledge/command-view.\n\nHow Command View Works\n\nCommand View is a projection of the Organization Model graph, not a separate deployment manifest.\n\nThe OM resources domain is the single source of resource identity. The actions domain is the invokable semantic layer. The systems domain is the backbone. Command View merges the graph emitted by buildOrganizationGraph() with optional live Command View data (deployed resource metadata) to render a unified operational picture.\n\nGraph projection pipeline:\n\n1. Organization Model is authored in packages/elevasis-core/src/organization-model/.\n2. buildOrganizationGraph() projects the OM into typed nodes and edges.\n3. Command View data (deployed resource metadata) is optionally merged as an overlay.\n4. The merged graph is serialized and cached.\n5. The frontend visualizes the cached graph.\n\nCommand View does not own resource identity. It reads what the OM declares.\n\nNode Kinds\n\nCommand View renders the same node kinds as the OM graph:\n\n| Kind           | Source         | Description                                                                |\n| -------------- | -------------- | -------------------------------------------------------------------------- |\n| organization | Root           | The organization-model root node                                           |\n| system       | OM.systems   | Bounded contexts with dotted IDs and parentSystemId hierarchy              |\n| role         | OM.roles     | Named roles with hierarchy and holder assignments                          |\n| action       | OM.actions   | Invokable operations with invocation type metadata                         |\n| entity       | OM.entities  | Business objects owned by systems                                          |\n| event        | Projected      | Derived from resource emits declarations and entity state catalogs       |\n| policy       | OM.policies  | Governance rules applied to systems, actions, resources, and roles         |\n| stage        | Projected      | Derived from prospecting stage catalogs                                    |\n| resource     | OM.resources | Workflows, agents, integrations, triggers, scripts, and external resources |\n| knowledge    | OM.knowledge | Knowledge nodes governed by systems                                        |\n\nThe resourceType overlay on resource nodes is a separate enum: workflow, agent, trigger, integration, external, humancheckpoint, script.\n\nEdge Kinds\n\n| Kind              | Meaning                                                                        |\n| ----------------- | ------------------------------------------------------------------------------ |\n| contains        | Parent-to-child containment (organization to system, system to resource, etc.) |\n| references      | Cross-reference between nodes (role reports-to, agent invokes action)          |\n| mapsto         | Action mapped to a resource implementation                                     |\n| uses            | System or stage uses an action                                                 |\n| governs         | Knowledge node or role governs a system or target                              |\n| links           | Entity links to another entity                                                 |\n| affects         | Action affects an entity                                                       |\n| emits           | Resource or entity emits an event                                              |\n| originatesfrom | Event originates from an entity                                                |\n| triggers        | Event or action triggers a policy                                              |\n| appliesto      | Policy applies to a system, action, resource, or role                          |\n| effects         | Policy effect invokes an action or notifies a role                             |\n\nVisualization Modes\n\nCommand View uses Cytoscape graph modes:\n\n- Map: preserves organization structure and honors hidden-resource visibility.\n- Trace: resolves directed paths and reveals resources for the active trace.\n- Impact: pivots around the selected node and reveals related resources for impact review.\n\nFilter panel:\n\n- Search across nodes, relationships, and IDs.\n- Filter by node kind, resource type, environment, topology presence, integrations, and resource facets.\n- Toggle resource visibility and diagnostic/testing resource visibility.\n- Show visible and hidden resource counts in the same control surface.\n\nHidden resource behavior:\n\n- Resource nodes are hidden by default so the organization structure remains readable.\n- Structural nodes remain visible as the navigation skeleton.\n- Selecting a visible node can reveal directly connected hidden resources.\n- Diagnostic and testing resources are hidden by default and can be revealed from the filter panel.\n\nExpand Around behavior:\n\n- Select a node, open Details, and use Expand Around to preview nearby graph context before revealing it.\n- Semantic presets cover coverage, operational dependencies, organization context, and impact paths.\n- System and entity nodes default to Coverage.\n- Resource nodes default to Operational Dependencies.\n- Preview counts show hidden resources before Apply reveals the graph patch.\n\nRead-only constraints:\n\n- No drag and drop.\n- No connection editing.\n- No graph mutation from the visualization layer.\n\nOrganization Model as the Source of Truth\n\nResource identity lives in OM.resources, not in a separate manifest. To add a resource to Command View:\n\n1. Add the resource to OM.resources in the organization model.\n2. Link it to a system via systemPath.\n3. Optionally link actions to the resource via action.resourceId.\n4. Deploy the organization model. Command View reflects the new resource automatically.\n\nThere is no separate DeploymentSpec.relationships declaration required for OM-declared resources. The graph builder derives containment and relationship edges directly from the OM contract.\n\nLive resource metadata (deployed name, description, runtime status) can be overlaid from Command View data when available, but the OM contract is primary.\n\nUsing Command View\n\nSystem Understanding\n\nUseful exploration questions:\n\n- What systems own which resources and entities?\n- What actions does this system expose, and what do they map to?\n- Which knowledge nodes govern this system?\n- What policies apply to this system?\n- What events originate from this entity?\n- What roles are responsible for this system?\n\nVisual patterns:\n\n- Hub nodes with many edges indicate central resources or pivotal systems.\n- Linear chains show sequential workflow pipelines.\n- Branching shows conditional routing or multiple action paths.\n- Isolated nodes may indicate unused or draft resources.\n\nManifest Debugging\n\nUse Command View to verify:\n\n1. Resources appear as nodes under the correct system.\n2. Actions map to the expected resources.\n3. Entities link to the correct systems and each other.\n4. Policies apply to the correct systems, actions, or resources.\n5. Events appear for resources with emits declarations.\n6. Orphaned resources are intentional.\n\nCommon issues:\n\n- Resource declared in OM but assigned to the wrong systemPath.\n- Action resourceId points to a resource ID that does not exist.\n- Entity ownedBySystemId references an unknown system.\n- Policy appliesTo references a system, action, or resource that was removed.\n\nTroubleshooting\n\nEmpty Graph\n\nLikely causes:\n\n- Organization has no systems or resources defined.\n- Search, node kind, or resource type filters hide all graph elements.\n- Command View resources are hidden and no structural nodes match current filters.\n\nCheck:\n\n1. OM systems and resources domains have entries.\n2. Filter panel visibility and filter state.\n3. API response for the /api/command-view endpoint.\n\nFix:\n\n- Add systems and resources to the organization model.\n- Reveal resources or reset graph filters.\n\nMissing Nodes\n\nLikely causes:\n\n- Resource, action, or entity is defined in OM but omitted from the relevant domain map.\n- Node is hidden by visibility controls.\n- Status, resource type, or topology filters exclude the node.\n\nCheck:\n\n1. OM domain map includes the ID as a key and as id in the entry.\n2. Filter panel visibility and filter state.\n3. Node lifecycle or enabled field.\n\nFix by adding the entry to the correct domain map or revealing hidden nodes.\n\nMissing Edges\n\nLikely causes:\n\n- Action resourceId does not match any OM resource ID.\n- Entity ownedBySystemId references an unknown system.\n- Policy appliesTo references IDs that do not exist.\n- Knowledge node link uses a nodeId that has no matching OM node.\n\nCheck:\n\n1. Cross-reference IDs across OM domains.\n2. Run pnpm --filter @repo/core check-types to surface Zod validation errors.\n\nFix the OM entry to reference the correct ID.\n\nBest Practices\n\nKeep the OM up to date as systems and resources evolve:\n\n1. Add new resources to OM.resources with the correct systemPath.\n2. Map actions to resources via action.resourceId when the action calls a specific resource.\n3. Update entity.ownedBySystemId when entities move between systems.\n4. Update policy.appliesTo when systems, actions, or resources are renamed or removed.\n5. Declare resource.emits for workflows and agents that produce observable events.\n\nUse the OM graph as the authoritative reference for Command View structure. The graph builder derives the visualization from the OM contract -- do not expect Command View to show connections that are not declared in the OM.\n\nRelated References\n\n- /knowledge read knowledge.org-model-reference\n- /knowledge read knowledge.platform-composition-patterns\n- /knowledge read knowledge.platform-integration-patterns"
+  },
+  {
+    id: "knowledge.platform-composition-patterns",
+    title: "Platform Composition Patterns",
+    summary: "Reference for composing agents, workflows, integrations, tools, observability, scaling, error handling, and security into complete Elevasis automation systems.",
+    bodyText: "Overview\n\nUse this reference to choose how Elevasis resources compose into complete systems. The core decision is whether reasoning, deterministic orchestration, or a hybrid of both should own the business flow.\n\nThree primary patterns exist:\n\n- Agent-centric: an agent is the primary orchestrator, and workflows or integrations are tools.\n- Workflow-centric: a workflow is the deterministic pipeline, and agents appear only as processing steps.\n- Hybrid: agents decide what should happen, and workflows execute reliable sequences.\n\nSystem Architecture Patterns\n\nAgent-Centric Systems\n\nPattern: Agent is the primary orchestrator; workflows and integrations are tools.\n\ntext\nTrigger to Agent\n           |- Tool: Integration A\n           |- Tool: Integration B\n           |- Tool: Workflow 1 via resource invocation\n           - Tool: Workflow 2 via resource invocation\n\nUse this pattern for ambiguous goals, dynamic decision-making, multi-turn conversations, and business logic that requires judgment.\n\nStrengths:\n\n- Flexible and adaptive.\n- Handles ambiguity well.\n- Can delegate to specialist resources.\n- Supports natural language interaction.\n\nWeaknesses:\n\n- Token cost per execution.\n- Non-deterministic LLM variance.\n- Requires strong observability for debugging.\n- Usually slower than deterministic workflows.\n\nWorkflow-Centric Systems\n\nPattern: Workflow is the pipeline; agents are processing steps.\n\ntext\nTrigger to Workflow\n           |- Step 1: Integration A reads data\n           |- Step 2: Agent processes or reasons\n           |- Step 3: Integration B writes result\n           - Step 4: Conditional routing\n\nUse this pattern for predictable sequences, data transformation pipelines, integration orchestration, and fixed business logic.\n\nStrengths:\n\n- Deterministic and reliable.\n- Fast execution.\n- Easy to debug step-by-step.\n- No token cost unless an agent step is included.\n\nWeaknesses:\n\n- Rigid, because steps are predefined.\n- Does not handle ambiguity well.\n- Requires code changes for logic updates.\n\nHybrid Systems\n\nPattern: Agents decide, workflows execute. This is the recommended default for complex automation.\n\ntext\nTrigger to Agent decides what to do\n           |- Invokes: Workflow A\n           |- Invokes: Workflow B\n           - Uses: Integration C directly\n\nWorkflow A:\n  |- Integration D reads\n  |- Agent processes a specific subtask\n  - Integration E writes\n\nUse this pattern when the system needs variable paths, reasoning, reliability, and a mix of predictable and unpredictable steps.\n\nStrengths:\n\n- Flexible where needed and reliable where possible.\n- Cost-efficient because workflows do not use tokens by default.\n- Good observability across agent reasoning and workflow steps.\n\nResource Composition Patterns\n\nAgent + Tools\n\nUse direct integration access for simple or frequent operations.\n\nTool categories:\n\n- Base tools: always available, high-frequency operations such as read queries or cached data access. Example: attiogetrecord.\n- Knowledge Map tools: lazy-loaded, low-frequency operations such as write operations or domain-specific capabilities. Examples: attiocreatecontact, dropboxuploadfile.\n- Resource invocation tools: delegate to workflows for deterministic sequences or call specialist agents.\n\nTool creation example:\n\ntypescript\nconst tool = createAttioCreateRecordTool('elevasis-attio')\n\nCredential names resolve to organization-scoped storage. RLS policies enforce organization isolation, credentials are encrypted at rest, and OAuth tokens can refresh automatically.\n\nAgent + Workflow\n\nUse an agent for reasoning and a workflow for deterministic execution.\n\ntext\nTrigger to Agent reasoning\n          |- Direct tool: read integration\n          |- Invoke tool: Workflow A\n          - Invoke tool: Workflow B\n\nExecution flow:\n\n1. Agent analyzes the request.\n2. Agent invokes a workflow through a tool call.\n3. Workflow executes deterministic steps without token cost.\n4. Agent explains the result to the user.\n\nUse this pattern when the system needs both reasoning and reliability, has multiple execution paths, or should minimize token use by moving predictable work into workflows.\n\nWorkflow + Integration\n\nUse a workflow to orchestrate deterministic integration sequences.\n\ntext\nTrigger to Workflow\n          |- Step 1: Integration A reads\n          |- Step 2: Transform pure function\n          |- Step 3: Integration B writes\n          - Step 4: Notify\n\nUse this pattern for predictable step sequences, data transformation pipelines, integration orchestration, and cost-sensitive work that does not need LLM reasoning.\n\nPattern Selection Guide\n\n| Requirement | Pattern | Example |\n| --- | --- | --- |\n| Ambiguous goals | Agent-centric | Business orchestration with variable outcomes |\n| Predictable sequence | Workflow-centric | Shopify to CRM sync |\n| Hybrid needs | Agent + workflow | Support router where agent decides and workflow executes |\n| \\>10 tools | Knowledge Map | Agent with many domain capabilities |\n| High-frequency reads | Base tools | Attio read operations |\n| Low-frequency writes | Lazy-loaded tools | CRM updates or page creation |\n| External services | Integration tools | Attio, Gmail, Google Sheets |\n| Deterministic pipelines | Workflow + integration | Data transformation |\n\nComplexity guidelines:\n\n- Simple, 1-2 resources: agent with base tools, or workflow with 1-2 integrations.\n- Medium, 3-5 resources: agent plus Knowledge Map with 2-3 nodes, or workflow plus an agent step.\n- Complex, 6+ resources: agent plus Knowledge Map plus memory preload, or multi-integration workflows.\n\nCross-Cutting Concerns\n\nObservability\n\nTrack these surfaces:\n\n- Agent iterations, including reasoning and actions.\n- Workflow steps, including inputs and outputs.\n- Tool calls, including integration requests and responses.\n- Errors and retries.\n- Token usage and cost.\n\nPrimary tools:\n\n- Execution Logs for SSE-based debugging.\n- Activity Log for the real-time stream.\n- Execution Health for cost tracking and ROI review.\n- Command View for system architecture and dependency review.\n\nCost Tracking\n\nAgent cost comes from per-iteration token usage, model pricing, and tool execution cost. Workflow cost is usually zero token cost plus any external integration API fees.\n\nOptimization rules:\n\n- Use workflows for predictable tasks.\n- Lazy-load tools for 80-95% token savings.\n- Cache frequently accessed stable data.\n- Choose the appropriate model per task.\n\nScaling Strategies\n\nHorizontal scaling:\n\n- Keep agent execution stateless.\n- Store sessions in the database.\n- Let a load balancer distribute requests.\n\nVertical optimization:\n\n- Preload memory to reduce iteration count.\n- Lazy-load tools to reduce token usage.\n- Batch tool operations where possible.\n- Use parallel integration calls when the steps are independent.\n\nError Handling\n\nAgent error handling:\n\n- Tool errors are returned to the agent so it can reason about recovery.\n- Iteration limits prevent infinite loops.\n- Timeout protection constrains long-running tools and executions.\n- Graceful degradation explains what failed.\n\nWorkflow error handling:\n\n- Step retry logic uses exponential backoff, commonly 1, 4, and 9 minutes.\n- Conditional routing can send failures to an alternative step.\n- Manual intervention can route work to a human checkpoint.\n- Idempotent steps should be safe to retry.\n\nExample:\n\ntypescript\n{\n  id: 'sync-to-crm',\n  handler: async ({ input, context }) => {\n    try {\n      return await crmClient.createContact(input)\n    } catch (error) {\n      if (error.code === 'DUPLICATE') {\n        return crmClient.updateContact(input)\n      }\n\n      throw error\n    }\n  },\n  next: { type: 'linear', target: 'send-notification' }\n}\n\nSecurity\n\nCredential management:\n\n- Store credentials in the credentials table.\n- Encrypt values at rest.\n- Scope records by organization with RLS policies.\n- Refresh OAuth tokens automatically where supported.\n- Never store API keys in code.\n\nMulti-tenancy isolation layers:\n\n1. Database RLS on tenant-scoped tables.\n2. API middleware that requires organization context.\n3. Resource registry lookups scoped to the organization.\n4. Command View filtered by organization.\n\nBest Practices\n\n1. Start with a single agent or workflow, then add complexity only when needed.\n2. Build the working version before optimizing for caching or lazy loading.\n3. Put domain logic in agents and execution flow in workflows.\n4. Lazy-load large or low-frequency tool groups.\n5. Cache stable data, not fast-changing operational state.\n\nCommon mistakes:\n\n- Creating a Knowledge Map for fewer than five tools.\n- Using a workflow for one integration call when an agent tool would be simpler.\n- Loading more than ten tools as base tools.\n- Putting domain logic into workflows where it becomes hard to test and adapt.\n- Mixing unrelated concerns in one knowledge node.\n\nRelated References\n\n- /knowledge read knowledge.platform-integration-patterns\n- /knowledge read knowledge.platform-command-view"
+  },
+  {
+    id: "knowledge.platform-integration-patterns",
+    title: "Platform Integration Patterns",
+    summary: "Reference for connecting Elevasis agents and workflows to external services through adapters, OAuth, API keys, tenant-isolated credentials, retries, and tests.",
+    bodyText: "Overview\n\nIntegration patterns define how Elevasis agents and workflows connect to external services such as Gmail, Attio, Google Sheets, and custom APIs. The platform uses a standardized adapter pattern with OAuth 2.0 and API key authentication backed by tenant-isolated credentials.\n\nCore patterns:\n\n- Direct integration, where a resource uses integration tools directly.\n- Integration workflow, where a workflow coordinates multiple integrations.\n- Shared integration, where multiple resources use the same credential set.\n- Multi-account integration, where the same provider has separate credentials for different contexts.\n\nDirect Integration Pattern\n\nPattern: Resource uses an integration tool.\n\nUse direct integration tools when an agent or workflow performs frequent operations against a provider.\n\nCharacteristics:\n\n- Tools are always available to the resource.\n- There is no additional navigation overhead.\n- The pattern is optimized for frequent read-heavy operations.\n\nTool factory location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-tools.ts\n\nTool factories use createIntegrationTool() with a credentialName parameter. Example: createAttioCreateRecordTool(credentialName).\n\nIntegration Workflow Pattern\n\nPattern: Agent invokes a workflow, and the workflow uses integrations.\n\nUse an integration workflow for complex multi-step operations that need deterministic orchestration.\n\nExample lead capture flow:\n\n1. Webhook trigger receives the event.\n2. Workflow creates an Attio contact.\n3. Workflow sends a Gmail notification.\n4. Workflow returns confirmation.\n\nCharacteristics:\n\n- Deterministic execution order.\n- Step-level error handling and retry.\n- Multiple integrations coordinated in one place.\n- Built-in audit trail through workflow execution.\n\nShared Integration Pattern\n\nPattern: Multiple resources share the same integration.\n\nUse shared integrations for organization-wide providers that should use one credential set.\n\nExample:\n\ntext\npackages/elevasis-operations/src/index.ts\n\nCharacteristics:\n\n- One credential per integration.\n- Centralized credential management.\n- Shared across agents and workflows.\n\nMulti-Account Pattern\n\nPattern: Same provider, different credentials.\n\nUse this pattern for department-specific provider instances or separate dev/prod environments.\n\nExample:\n\ntypescript\nconst salesTool = createAttioCreateRecordTool('attio-sales')\nconst supportTool = createAttioCreateRecordTool('attio-support')\n\nDisambiguate multi-account tools with explicit tool names:\n\ntypescript\nconst tool = createAttioToolNamed(\n  'attiosalescreaterecord',\n  'attio-sales',\n  'createRecord'\n)\n\nAuthentication Patterns\n\nOAuth 2.0 vs API Key\n\n| Aspect | OAuth 2.0 | API key |\n| --- | --- | --- |\n| Auth flow | Browser redirect plus token exchange | Direct API key |\n| Setup complexity | High: client ID, secret, redirect URL | Low: single API key |\n| Token refresh | Automatic refresh token rotation | Manual key rotation |\n| Scope control | Granular permission scopes | Full access or none |\n| User context | Per-user authorization | Service-level access |\n| Revocation | User can revoke anytime | Manual key deletion |\n\nOAuth 2.0 Pattern\n\nProviders include Gmail and Google Sheets.\n\nCredential format:\n\ntypescript\ninterface OAuthToken {\n  provider: string\n  accessToken: string\n  refreshToken: string\n  expiresAt: string\n  tokenType: 'Bearer'\n  scope?: string\n}\n\nexpiresAt is an ISO 8601 timestamp. The platform handles token refresh when supported by the provider and credential implementation.\n\nAPI Key Pattern\n\nProviders include Attio and custom APIs.\n\nCredential format:\n\ntypescript\ninterface APIKeyCredentials {\n  apiKey: string\n}\n\nProvider-specific validation belongs in the adapter. For Attio, see:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/attio/attio-adapter.ts\n\nCredential Management\n\nCredentials are stored in the credentials table.\n\nKey columns:\n\n- organizationid for tenant isolation.\n- name, such as elevasis-attio.\n- provider, such as gmail or attio.\n- encryptedvalue containing encrypted JSON.\n\nSecurity rules:\n\n- RLS policies enforce tenant isolation.\n- Values are encrypted at rest.\n- Credentials do not cross organization boundaries.\n\nBest practices:\n\n- Store credentials encrypted in the database.\n- Use tenant-isolated credential names.\n- Validate credentials before API calls.\n- Rotate API keys regularly.\n- Use least-privilege OAuth scopes.\n\nDo not:\n\n- Hardcode credentials in code.\n- Share credentials across organizations.\n- Log credential values.\n- Store provider API keys in environment variables for tenant integrations.\n- Reuse the same credential name for dev and prod.\n\nCredential resolution flow:\n\n1. Tool requests a credential by name.\n2. Platform queries credentials with the current organizationid.\n3. Platform decrypts the credential.\n4. Adapter validates the credential against the provider schema.\n5. Tool passes the credential to the provider adapter.\n6. Usage is logged without credential values.\n\nImplementation reference:\n\ntext\npackages/core/src/execution/engine/tools/integration/tool.ts\n\nError Handling Patterns\n\nAdapters should convert provider errors into platform tooling errors.\n\nCommon error categories:\n\n- credentialsinvalid for invalid or missing credentials.\n- apierror for provider API errors.\n- networkerror for network or timeout failures.\n- validationerror for invalid parameters.\n- methodnotfound for unknown adapter methods.\n\nRetry strategy:\n\n- Network errors: retry with exponential backoff, commonly 1, 2, and 4 seconds.\n- Auth errors: fail immediately because the credential needs attention.\n- Validation errors: fail immediately because the input needs correction.\n- Rate limits: retry after reset when the provider exposes a reset time.\n- Workflow-level retries: commonly 3 attempts with 1, 4, and 9 minute delays.\n\nAdapter Development\n\nAdapter class location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-adapter.ts\n\nAdapter classes implement BaseIntegrationAdapter and contain call() and validateCredentials() methods.\n\nTool factory location:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/{provider}-tools.ts\n\nTool factories export create{Provider}{Operation}Tool(credentialName) functions.\n\nTests belong under:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/adapters/{provider}/tests/\n\nRegistration happens in:\n\ntext\npackages/core/src/execution/engine/tools/integration/server/index.ts\n\nTesting Strategies\n\nUnit testing:\n\n- Mock external APIs.\n- Cover credential validation.\n- Cover API call construction.\n- Cover response parsing.\n- Cover error handling.\n\nIntegration testing:\n\n- Use real API calls only with test accounts or test workspaces.\n- Clean up test data after tests.\n- Run in CI only when secret credentials are available.\n- Keep provider behavior mocked in unit tests.\n\nAgent testing:\n\n- Test agents using integration tools at the resource boundary.\n- Tenant project agent tests normally live under external/{org}/src/agents/{agent}/tests/.\n\nRelated References\n\n- /knowledge read knowledge.platform-composition-patterns\n- /knowledge read knowledge.platform-command-view\n- /knowledge read knowledge.platform-systems-overview"
   }
 ];
-function buildSearchIndex(entries) {
-  return {
-    search(query) {
-      if (!query.trim()) return [];
-      const q = query.trim().toLowerCase();
-      const scored = [];
-      for (const entry of entries) {
-        let score = 0;
-        if (entry.title.toLowerCase().includes(q)) score += 3;
-        if (entry.summary.toLowerCase().includes(q)) score += 2;
-        if (entry.bodyText.toLowerCase().includes(q)) score += 1;
-        if (score > 0) scored.push({ id: entry.id, score });
-      }
-      return scored.sort((a, b) => b.score - a.score).map((s) => s.id);
-    }
-  };
-}
-function KnowledgeSearchBar({
-  knowledgeNodes,
-  onResults,
-  placeholder = "Search knowledge\u2026"
-}) {
-  const [query, setQuery] = useState("");
-  const indexRef = useRef(null);
-  useEffect(() => {
-    indexRef.current = buildSearchIndex(knowledge_search_index_default);
-  }, []);
-  const nodeMapRef = useRef(/* @__PURE__ */ new Map());
-  useEffect(() => {
-    const map = /* @__PURE__ */ new Map();
-    for (const node of knowledgeNodes) map.set(node.id, node);
-    nodeMapRef.current = map;
-  }, [knowledgeNodes]);
-  const handleChange = (value) => {
-    setQuery(value);
-    if (!value.trim()) {
-      onResults(null);
-      return;
-    }
-    const ids = indexRef.current?.search(value) ?? [];
-    const hits = ids.flatMap((id) => {
-      const node = nodeMapRef.current.get(id);
-      return node ? [node] : [];
-    });
-    onResults(hits);
-  };
-  const handleClear = () => {
-    setQuery("");
-    onResults(null);
-  };
-  return /* @__PURE__ */ jsx(
-    TextInput,
-    {
-      value: query,
-      onChange: (e) => handleChange(e.currentTarget.value),
-      placeholder,
-      leftSection: /* @__PURE__ */ jsx(IconSearch, { size: 16 }),
-      rightSection: query ? /* @__PURE__ */ jsx(IconX, { size: 14, style: { cursor: "pointer", color: "var(--color-text-subtle)" }, onClick: handleClear }) : null,
-      styles: {
-        input: {
-          backgroundColor: "var(--color-surface)",
-          borderColor: "var(--color-border)",
-          color: "var(--color-text)"
-        }
-      }
-    }
-  );
-}
-
-export { EdgeChip, EdgeGroup, EdgeRelationshipGroup, KNOWLEDGE_ICON_TOKEN_BY_KIND, KeyField, KindChip, KnowledgeSearchBar, KnowledgeTree, NodeDescribeShell, NodeHeader, NodeMetadataFooter, RelatedKnowledgeSection, byKind, getKnowledgeIconToken };
+
+export { knowledge_search_index_default as default };