@elevasis/sdk 1.15.1 → 1.17.0

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

@@ -0,0 +1,32 @@
+# @elevasis/core/knowledge
+
+Pure query layer over the organization graph. Browser-safe (no Node APIs); shared by the SDK CLI, platform CLI, and the `@elevasis/ui/knowledge` browser.
+
+## Surface
+
+| Export                                        | Purpose                                                                                                                             |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `byFeature(graph, featureId, knowledgeNodes)` | Knowledge nodes that govern the given feature.                                                                                      |
+| `byKind(graph, kind, knowledgeNodes)`         | Filter knowledge nodes by `OrgKnowledgeKind`.                                                                                       |
+| `byOwner(graph, ownerId, knowledgeNodes)`     | Knowledge nodes whose `ownerIds` includes the given owner.                                                                          |
+| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-feature ids) from a knowledge node.                                                            |
+| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a feature.                                                           |
+| `parsePath(pathString)`                       | Parse `/by-feature/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
+| `formatText`, `formatJson`, `formatIdsOnly`   | Output formatters used by the `knowledge:*` CLI subcommands.                                                                        |
+
+## Path syntax
+
+```
+/by-feature/<featureId>
+/by-kind/<playbook|strategy|reference>
+/by-owner/<ownerId>
+/graph/<nodeId>/governs
+/graph/<nodeId>/governed-by
+/<nodeId>
+```
+
+## JSON envelope
+
+`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
+
+`governs` and `governedBy` accept either bare or graph-namespaced ids (`knowledge.foo` or `knowledge:knowledge.foo`).

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

@@ -0,0 +1,31 @@
+# @elevasis/ui/knowledge
+
+Read-only browser primitives for the Organization Model knowledge graph.
+
+## Surface
+
+| Export                                                                 | Purpose                                                                             |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
+| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
+| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
+| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
+| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
+| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
+| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
+| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
+| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
+
+## Customization tiers
+
+1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
+2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
+3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
+
+## Codegen
+
+`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
+
+The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
+
+Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.

package/reference/packages/ui/src/theme/presets/README.md

@@ -0,0 +1,19 @@
+# Theme Presets
+
+Re-exports the canonical theme-preset SSOT from `@repo/core`. This subpath exists so that consumers can import preset metadata without pulling in the full theme runtime surface.
+
+## Exports
+
+- `THEME_PRESETS` — `as const` tuple of preset names; the single source of truth.
+- `ThemePresetName` — union type derived from `THEME_PRESETS`.
+- `ThemePresetEnum` — Zod enum derived from `THEME_PRESETS`.
+
+## Use When
+
+- You need a Zod-validated preset name (form schemas, API request/response validation).
+- You need the union type for component props or Zustand state.
+- You're adding a new preset and want to ensure it propagates everywhere via the canonical tuple.
+
+## Source Of Truth
+
+`packages/core/src/auth/multi-tenancy/theme-presets.ts`. This subpath is a thin re-export. The `ui → core` dependency stays one-directional; the runtime preset catalog (`presets`, `getPreset`) lives at `@repo/ui/theme` and consumes the names declared in core.

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

@@ -72,7 +72,7 @@ Authored fields:
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
 Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
 
-Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `operations.command-view` is intentionally development-only while its graph visualization modes continue to mature.
+Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
 ## Graph IDs and Resource Links
 

package/reference/scaffold/recipes/add-a-feature.md

@@ -22,7 +22,7 @@ const organizationOverride = defineOrganizationModel({
       label: 'Analytics',
       enabled: true,
       path: '/analytics',
-      icon: 'chart',
+      icon: 'custom.analytics',
       uiPosition: 'sidebar-primary'
     }
   ]