@elevasis/sdk 1.23.0 → 1.25.0

package/reference/claude-config/sync-notes/2026-05-04-knowledge-bundle.md

@@ -1,83 +1,83 @@
-# Knowledge Bundle Ship-Train
-
-## Why this note exists
-
-The Knowledge Map (Browser, CLI, skill, icons, external parity) is being shipped as a coordinated bundle. The Organization Model now treats `knowledge` as a first-class graph domain with `kind`-discriminated nodes (`playbook` / `strategy` / `reference`) connected to features and capabilities through `governs` edges. A new `/knowledge` skill absorbs the prior `/configure` skill as a unified intent-inferring surface (read + describe + codify + toggle); `/configure` is tombstoned via `sync-delete-manifest.json`. A new `knowledge:*` CLI subcommand suite ships on both `elevasis` and `elevasis-sdk` over a shared `@repo/core/knowledge/queries` data layer. The Knowledge Browser is wired into `@elevasis/ui` with reusable primitives (`KnowledgeBrowser`, `KnowledgeTree`, `DescribeNodeView`, `KindChip`, `NodeHeader`, `NodeDescribeShell`, etc.) and a build-time MDX codegen pipeline at `@elevasis/sdk/node`. A unified semantic icon-token catalog lives at `@elevasis/core/organization-model` and is shared across core, SDK, UI, Command Center, and external projects. External-parity work makes the bundle zero-config for tenant projects: a dual-mode Vite plugin walks up to `.elevasis`, runs the two-codegen pipeline in-process, and writes artifacts the published Browser already imports -- no flags, no paths, no recipe steps.
-
-## Applies to
-
-All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
-
-- `nirvana-marketing`
-- `ZentaraHQ`
-- Any future external SDK consumer derived from the `_template` baseline
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so the refreshed knowledge wiring (template OM defaults, starter `welcome.mdx`, vite plugin pre-wiring, `/knowledge` skill, `/configure` tombstone, scaffold recipe) reaches the project.
-
-2. **`/configure` is gone.** The skill was absorbed into `/knowledge`. `/git-sync` removes `external/_template/.claude/skills/configure/` (and its 10 operations files) via `sync-delete-manifest.json` (wave: `knowledge-skill`). Update any tenant-side automation, prompts, or docs that still reference `/configure` -- replace with `/knowledge`. The skill is intent-inferring: classify by natural language (read / describe / codify / toggle), not by verb namespace.
-
-3. **`/knowledge` ceremony is unchanged.** The codify ceremony (snapshot -> propose -> confirm -> write -> validate -> rollback) and the two-level model (Level A config-only edits vs. Level B new Zod extension files) are preserved bit-for-bit. The skill body lives at `.claude/skills/knowledge/SKILL.md` (~245 lines) with 10 operations files: `codify-level-a.md`, `codify-level-b.md`, plus 8 domain references (`identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, `labels`).
-
-4. **Vite plugin is pre-wired.** `external/_template/ui/vite.config.ts` imports and spreads `elevasisVite()` from `@elevasis/ui/vite`. After `/git-sync`, the plugin auto-discovers the project via `.elevasis` walk-up, runs both knowledge codegens in-process, and writes:
-   - `core/config/knowledge/_generated/nodes.ts`
-   - `core/config/knowledge/_generated/knowledge-bodies.tsx`
-   - `core/config/knowledge/_generated/knowledge-search-index.json`
-
-   Same behavior in `vite dev` and `vite build`. No flags, no manual codegen step required for the bundle to work.
-
-5. **Starter knowledge node lands.** `core/config/knowledge/nodes/welcome.mdx` ships in the template so a fresh clone has a non-empty Browser on first `pnpm -C ui dev`. Replace with tenant-authored MDX nodes as the project codifies real organizational knowledge. Tenant nodes go under `core/config/knowledge/nodes/**/*.mdx` with frontmatter declaring `id`, `kind`, `title`, optional `icon` (semantic token), and an MDX body. Default fallback icons by `kind` apply when `icon` is omitted.
-
-6. **Knowledge baseline propagates to the OM.** `core/config/organization-model.ts` now includes baseline knowledge defaults imported from `@elevasis/core/organization-model`. The merge-aware Tier 2 sync preserves tenant overrides while picking up the baseline. After `/git-sync`, verify `resolveOrganizationModel()` still parses (Zod) and `pnpm -C ui exec tsc --noEmit` passes.
-
-7. **`knowledge:*` CLI subcommands are available.** From inside the project (any subdirectory):
-
-   ```bash
-   pnpm exec elevasis-sdk knowledge:ls /by-feature/sales/crm
-   pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
-   pnpm exec elevasis-sdk knowledge:cat <node-id>
-   pnpm exec elevasis-sdk knowledge:graph <node-id>
-   ```
-
-   These walk up to `.elevasis`, load the project's OM (with tenant nodes), and print results. Output flags: default text, `--json` envelope, `--ids-only` for piping. The Knowledge Browser sidebar copy buttons emit matching skill-resolvable commands (`/knowledge read <node-id>`, `/knowledge read-folder feature:<id>`, `/knowledge read-folder kind:<kind>`).
-
-8. **Semantic icon tokens replace ad-hoc strings.** When authoring or editing nodes (OM or MDX frontmatter), use semantic tokens from the catalog: `nav.*`, `knowledge.*`, `feature.*`, `resource.*`, `integration.*`, plus `custom.*` namespace for tenant extensions. `IconNameSchema` validates them. The UI renders via Tabler mappings in `@elevasis/ui/icons`; library names (`IconBook`, etc.) stay out of the OM/MDX surface.
-
-9. **Rebuild and type-check:**
-
-   ```bash
-   pnpm install
-   pnpm -C ui build
-   pnpm -C ui exec tsc --noEmit
-   pnpm -C operations exec tsc --noEmit
-   ```
-
-   The first `vite dev` or `vite build` after sync triggers the in-process codegen automatically. To regenerate codegen artifacts manually (one-shot, not normally required):
-
-   ```bash
-   pnpm exec elevasis-sdk knowledge:generate
-   ```
-
-## Verification
-
-After applying all actions above:
-
-- `/configure` skill directory is absent: `external/<project>/.claude/skills/configure/` does not exist after sync.
-- `/knowledge` skill is present at `.claude/skills/knowledge/SKILL.md` with the 10 operations files under `.claude/skills/knowledge/operations/`.
-- `core/config/knowledge/nodes/welcome.mdx` exists; `core/config/knowledge/_generated/` has been populated by the vite plugin (3 files).
-- `pnpm -C ui dev` boots; navigating to `/knowledge` renders the Browser with the welcome node visible in the tree.
-- The 5 mount axes resolve: `/knowledge`, `/knowledge/by-feature/$path`, `/knowledge/by-kind/$kind`, `/knowledge/by-owner/$id`, `/knowledge/graph/$nodeId/governs|governed-by`.
-- `pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook` returns text output without error.
-- `pnpm install` completes cleanly with no unresolved peer warnings.
-- `pnpm -C ui exec tsc --noEmit` passes; `pnpm -C operations exec tsc --noEmit` passes.
-
-## Not handled by /git-sync
-
-`/git-sync` propagates template-authored files (package baselines, `welcome.mdx` starter node, generated `_generated/` files, `/knowledge` skill, `/configure` tombstones, vite.config.ts wiring, scaffold recipe doc) but does NOT:
-
-- Author tenant-specific knowledge MDX nodes. The starter `welcome.mdx` is illustrative; real organizational playbooks, strategies, and reference docs need to be hand-authored under `core/config/knowledge/nodes/**/*.mdx`. Use `/knowledge` for ceremony when codifying.
-- Regenerate `_generated/` artifacts on its own. The vite plugin runs the codegens automatically on next `vite dev` / `vite build`. To regenerate manually before booting, run `pnpm exec elevasis-sdk knowledge:generate`.
-- Migrate references in tenant code from `/configure` to `/knowledge`. Search the project for `/configure` mentions in `.claude/`, `docs/`, `README.md`, prompts, and CI scripts; rewrite to `/knowledge`. The tombstone deletes the skill files but does not edit downstream references.
-- Replace tenant-authored icon strings with semantic tokens. Existing nodes that carried library-specific icon names (`IconBook`, etc.) will continue to render via fallback, but the canonical surface is semantic tokens. Migrate at-touched nodes to `knowledge.*` / `feature.*` / `nav.*` / `custom.*` over time.
-- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the bundle, clear this directory manually and restart the dev server before verifying the Browser renders -- stale cache can mask a successful generation.
+# Knowledge Bundle Ship-Train
+
+## Why this note exists
+
+The Knowledge Map (Browser, CLI, skill, icons, external parity) is being shipped as a coordinated bundle. The Organization Model now treats `knowledge` as a first-class graph domain with `kind`-discriminated nodes (`playbook` / `strategy` / `reference`) connected to features and capabilities through `governs` edges. A new `/knowledge` skill absorbs the prior `/configure` skill as a unified intent-inferring surface (read + describe + codify + toggle); `/configure` is tombstoned via `sync-delete-manifest.json`. A new `knowledge:*` CLI subcommand suite ships on both `elevasis` and `elevasis-sdk` over a shared `@repo/core/knowledge/queries` data layer. The Knowledge Browser is wired into `@elevasis/ui` with reusable primitives (`KnowledgeBrowser`, `KnowledgeTree`, `DescribeNodeView`, `KindChip`, `NodeHeader`, `NodeDescribeShell`, etc.) and a build-time MDX codegen pipeline at `@elevasis/sdk/node`. A unified semantic icon-token catalog lives at `@elevasis/core/organization-model` and is shared across core, SDK, UI, Command Center, and external projects. External-parity work makes the bundle zero-config for tenant projects: a dual-mode Vite plugin walks up to `.elevasis`, runs the two-codegen pipeline in-process, and writes artifacts the published Browser already imports -- no flags, no paths, no recipe steps.
+
+## Applies to
+
+All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
+
+- `nirvana-marketing`
+- `ZentaraHQ`
+- Any future external SDK consumer derived from the `_template` baseline
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the refreshed knowledge wiring (template OM defaults, starter `welcome.mdx`, vite plugin pre-wiring, `/knowledge` skill, `/configure` tombstone, scaffold recipe) reaches the project.
+
+2. **`/configure` is gone.** The skill was absorbed into `/knowledge`. `/git-sync` removes `external/_template/.claude/skills/configure/` (and its 10 operations files) via `sync-delete-manifest.json` (wave: `knowledge-skill`). Update any tenant-side automation, prompts, or docs that still reference `/configure` -- replace with `/knowledge`. The skill is intent-inferring: classify by natural language (read / describe / codify / toggle), not by verb namespace.
+
+3. **`/knowledge` ceremony is unchanged.** The codify ceremony (snapshot -> propose -> confirm -> write -> validate -> rollback) and the two-level model (Level A config-only edits vs. Level B new Zod extension files) are preserved bit-for-bit. The current skill body lives at `.claude/skills/om/SKILL.md` with operations under `.claude/skills/om/operations/` (renamed from the former knowledge skill path), including `codify-level-a.md`, `codify-level-b.md`, plus 8 domain references (`identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, `labels`).
+
+4. **Vite plugin is pre-wired.** `external/_template/ui/vite.config.ts` imports and spreads `elevasisVite()` from `@elevasis/ui/vite`. After `/git-sync`, the plugin auto-discovers the project via `.elevasis` walk-up, runs both knowledge codegens in-process, and writes:
+   - `core/config/knowledge/_generated/nodes.ts`
+   - `core/config/knowledge/_generated/knowledge-bodies.tsx`
+   - `core/config/knowledge/_generated/knowledge-search-index.json`
+
+   Same behavior in `vite dev` and `vite build`. No flags, no manual codegen step required for the bundle to work.
+
+5. **Starter knowledge node lands.** `core/config/knowledge/nodes/welcome.mdx` ships in the template so a fresh clone has a non-empty Browser on first `pnpm -C ui dev`. Replace with tenant-authored MDX nodes as the project codifies real organizational knowledge. Tenant nodes go under `core/config/knowledge/nodes/**/*.mdx` with frontmatter declaring `id`, `kind`, `title`, optional `icon` (semantic token), and an MDX body. Default fallback icons by `kind` apply when `icon` is omitted.
+
+6. **Knowledge baseline propagates to the OM.** `core/config/organization-model.ts` now includes baseline knowledge defaults imported from `@elevasis/core/organization-model`. The merge-aware Tier 2 sync preserves tenant overrides while picking up the baseline. After `/git-sync`, verify `resolveOrganizationModel()` still parses (Zod) and `pnpm -C ui exec tsc --noEmit` passes.
+
+7. **`knowledge:*` CLI subcommands are available.** From inside the project (any subdirectory):
+
+   ```bash
+   pnpm exec elevasis-sdk knowledge:ls /by-feature/sales/crm
+   pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
+   pnpm exec elevasis-sdk knowledge:cat <node-id>
+   pnpm exec elevasis-sdk knowledge:graph <node-id>
+   ```
+
+   These walk up to `.elevasis`, load the project's OM (with tenant nodes), and print results. Output flags: default text, `--json` envelope, `--ids-only` for piping. The Knowledge Browser sidebar copy buttons emit matching skill-resolvable commands (`/knowledge read <node-id>`, `/knowledge read-folder feature:<id>`, `/knowledge read-folder kind:<kind>`).
+
+8. **Semantic icon tokens replace ad-hoc strings.** When authoring or editing nodes (OM or MDX frontmatter), use semantic tokens from the catalog: `nav.*`, `knowledge.*`, `feature.*`, `resource.*`, `integration.*`, plus `custom.*` namespace for tenant extensions. `IconNameSchema` validates them. The UI renders via Tabler mappings in `@elevasis/ui/icons`; library names (`IconBook`, etc.) stay out of the OM/MDX surface.
+
+9. **Rebuild and type-check:**
+
+   ```bash
+   pnpm install
+   pnpm -C ui build
+   pnpm -C ui exec tsc --noEmit
+   pnpm -C operations exec tsc --noEmit
+   ```
+
+   The first `vite dev` or `vite build` after sync triggers the in-process codegen automatically. To regenerate codegen artifacts manually (one-shot, not normally required):
+
+   ```bash
+   pnpm exec elevasis-sdk knowledge:generate
+   ```
+
+## Verification
+
+After applying all actions above:
+
+- `/configure` skill directory is absent: `external/<project>/.claude/skills/configure/` does not exist after sync.
+- `/om` skill is present at `.claude/skills/om/SKILL.md` with the operation files under `.claude/skills/om/operations/`.
+- `core/config/knowledge/nodes/welcome.mdx` exists; `core/config/knowledge/_generated/` has been populated by the vite plugin (3 files).
+- `pnpm -C ui dev` boots; navigating to `/knowledge` renders the Browser with the welcome node visible in the tree.
+- The 5 mount axes resolve: `/knowledge`, `/knowledge/by-feature/$path`, `/knowledge/by-kind/$kind`, `/knowledge/by-owner/$id`, `/knowledge/graph/$nodeId/governs|governed-by`.
+- `pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook` returns text output without error.
+- `pnpm install` completes cleanly with no unresolved peer warnings.
+- `pnpm -C ui exec tsc --noEmit` passes; `pnpm -C operations exec tsc --noEmit` passes.
+
+## Not handled by /git-sync
+
+`/git-sync` propagates template-authored files (package baselines, `welcome.mdx` starter node, generated `_generated/` files, `/knowledge` skill, `/configure` tombstones, vite.config.ts wiring, scaffold recipe doc) but does NOT:
+
+- Author tenant-specific knowledge MDX nodes. The starter `welcome.mdx` is illustrative; real organizational playbooks, strategies, and reference docs need to be hand-authored under `core/config/knowledge/nodes/**/*.mdx`. Use `/knowledge` for ceremony when codifying.
+- Regenerate `_generated/` artifacts on its own. The vite plugin runs the codegens automatically on next `vite dev` / `vite build`. To regenerate manually before booting, run `pnpm exec elevasis-sdk knowledge:generate`.
+- Migrate references in tenant code from `/configure` to `/knowledge`. Search the project for `/configure` mentions in `.claude/`, `docs/`, `README.md`, prompts, and CI scripts; rewrite to `/knowledge`. The tombstone deletes the skill files but does not edit downstream references.
+- Replace tenant-authored icon strings with semantic tokens. Existing nodes that carried library-specific icon names (`IconBook`, etc.) will continue to render via fallback, but the canonical surface is semantic tokens. Migrate at-touched nodes to `knowledge.*` / `feature.*` / `nav.*` / `custom.*` over time.
+- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the bundle, clear this directory manually and restart the dev server before verifying the Browser renders -- stale cache can mask a successful generation.

package/reference/claude-config/sync-notes/2026-05-15-om-skill-rename-and-write-family.md

@@ -21,7 +21,7 @@ Package baselines become concrete only after the `core` and `sdk` publish stages
 
 ## Required actions
 
-1. Apply the managed `.claude` skill rename atomically: create `.claude/skills/om/` (SKILL.md + `operations/`) and delete `.claude/skills/knowledge/` in the same sync. Never leave both directories present — two skills advertising the same scope is the exact confusion the rename removes.
+1. Apply the managed `.claude` skill rename atomically: create `.claude/skills/om/` (SKILL.md + `operations/`) and delete the former knowledge skill directory in the same sync. Never leave both directories present — two skills advertising the same scope is the exact confusion the rename removes.
 2. Preserve any tenant-owned Codify/Toggle ceremony content in the project's `om/SKILL.md` Write-Power section; do not overwrite project-authored knowledge node content under `core/config/knowledge/**` (the content directory is separate from the slash-command name).
 3. Rewrite `/knowledge` -> `/om` and `elevasis-sdk knowledge:*` -> `elevasis-sdk om:*` references in managed surfaces only; `knowledge:*` CLI aliases remain valid, so do not hard-fail on legacy invocations in project-owned files.
 4. After the `/sdk ship` publish stages land, bump the `@elevasis/core` (0.25.0) and `@elevasis/sdk` (1.23.0) baselines in `core/package.json` and `operations/package.json`, then reinstall.
@@ -40,7 +40,7 @@ pnpm -C external/_template/operations test
 
 Then confirm in each downstream project:
 
-- `.claude/skills/om/` exists with `SKILL.md` + `operations/`; `.claude/skills/knowledge/` is gone.
+- `.claude/skills/om/` exists with `SKILL.md` + `operations/`; the former knowledge skill directory is gone.
 - `elevasis-sdk om:search "<query>"` and `elevasis-sdk om:describe <id>` resolve against the tenant's organization model; legacy `elevasis-sdk knowledge:*` still aliases.
 - `@elevasis/core` resolves to >= 0.25.0 and `@elevasis/sdk` to >= 1.23.0.
 

package/reference/claude-config/sync-notes/2026-05-17-sdk-boundary-consolidation.md

@@ -0,0 +1,33 @@
+# SDK Boundary Consolidation Release Train
+
+## Why this note exists
+
+This train publishes the SDK boundary consolidation work and updates the template to consume more of the published Elevasis SDK family instead of carrying local boilerplate. It also carries the Organization Model bridge retirement and typed-contract hardening that the ship train depends on.
+
+## Applies to
+
+- Template UI shells derived from `external/_template/ui`.
+- Template operations packages that depend on `@elevasis/sdk`.
+- Template core packages that depend on `@elevasis/core`.
+- Projects that still carry copied `.claude/rules/*.md` files instead of SDK reference pointers.
+
+## Required actions
+
+- Refresh package baselines after publishing `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk`.
+- Adopt `ElevasisAuthenticatedShell` from `@elevasis/ui/app` in template-derived root routes.
+- Replace local UI test/store/query-client helpers with `@elevasis/ui/test-utils`, `@elevasis/ui/test-utils/setup`, `createElevasisAppStore`, and `createElevasisQueryClient`.
+- Keep project-specific Claude guidance as compatibility stubs that point at `@elevasis/sdk/reference/rules/`.
+- Treat `System.ontology.catalogTypes` and `System.config` as canonical Organization Model authoring surfaces; do not reintroduce `System.content`.
+
+## Verification
+
+- `pnpm sdk:verify-release`
+- `pnpm scaffold:verify`
+- `pnpm verify:scaffold-reference`
+- `pnpm sync:verify`
+- `pnpm org-os:verify`
+- Template UI typecheck and tests from the source workstream.
+
+## Not handled by /git-sync
+
+`/git-sync` does not publish npm packages, deploy the operations resource bundle, or decide whether project-owned files should adopt a template baseline. Those steps remain owned by `/sdk ship` and the prepared external-sync manifest.