@elevasis/sdk 1.22.1 → 1.23.0

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

@@ -0,0 +1,52 @@
+# OM Skill Rename + Write Family Release Train
+
+## Why this note exists
+
+This release train renames the tenant `/knowledge` skill to `/om` and broadens it, ports `om:search` / `om:describe` to the `elevasis-sdk` CLI, and bumps the `@elevasis/core` and `@elevasis/sdk` dependency baselines. The template `.claude` skill surface changed shape (a directory was renamed and slash-command references were rewritten across CLAUDE.md, rules, and adjacent skills), and `@elevasis/core` / `@elevasis/sdk` published new exports and CLI commands. Ordinary git merge does not reconcile a managed `.claude` skill rename or pull republished package baselines, so template-derived projects need an operative note.
+
+This note covers the `om-skill` workstream (the `/knowledge` -> `/om` rename + SDK CLI port) and the package-baseline cascades from the same train (`@elevasis/core` minor from `om-skill` + `om-create-skill`; `@elevasis/sdk` minor from `om-skill`). It does NOT cover the unrelated Shared-UI-Migration changes under `external/_template/ui/**`, which are a separate workstream and not part of this train.
+
+## Applies to
+
+- `external/_template/.claude/skills/om/SKILL.md` (renamed from `external/_template/.claude/skills/knowledge/SKILL.md`; canonical 5-bucket decision tree with the tenant Codify/Toggle ceremony preserved)
+- `external/_template/.claude/skills/om/operations/*.md` (10 files moved from `knowledge/operations/`; `elevasis-sdk knowledge:*` references rewritten to `elevasis-sdk om:*`, `/knowledge` footers rewritten to `/om`)
+- `external/_template/.claude/skills/knowledge/` (DELETED — directory removed; tombstone, do not re-create on sync)
+- `external/_template/CLAUDE.md` (Slash Commands table — `/knowledge` -> `/om`)
+- `external/_template/.claude/rules/{organization-model,organization-os,vibe}.md` (slash-command references)
+- `external/_template/.claude/skills/{setup,project,tutorial}/*.md` (slash-command references)
+- `external/_template/core/package.json` (`@elevasis/core` baseline -> 0.25.0)
+- `external/_template/operations/package.json` (`@elevasis/core` -> 0.25.0 and `@elevasis/sdk` -> 1.23.0 baselines)
+
+Package baselines become concrete only after the `core` and `sdk` publish stages of `/sdk ship` complete; the `.claude` skill rename is template-authored and already present in `external/_template`.
+
+## 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.
+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.
+5. The `/om` write sub-skill family (`verify` / `create` / `rename` / `deprecate`) is intentionally NOT ported to the tenant template in this train (deferred to a dedicated task). Do not scaffold those tenant operations from this sync.
+
+## Verification
+
+Run the template verification lane after applying this sync:
+
+```bash
+pnpm sync:verify --pre
+pnpm external:verify
+pnpm -C external/_template/operations check-types
+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.
+- `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.
+
+## Not handled by /git-sync
+
+- Publishing `@elevasis/core` (0.25.0) or `@elevasis/sdk` (1.23.0) — owned by `/sdk ship` publish stages.
+- Redeploying the SDK resources bundle (`elevasis-operations`) after the `@elevasis/sdk` publish.
+- Tenant-specific conflict resolution in dirty external project worktrees, including reconciling any project-authored edits to the former `knowledge/SKILL.md`.
+- The unrelated Shared-UI-Migration changes under `external/_template/ui/**` (separate workstream; not in this train's scope).

package/reference/scaffold/recipes/query-the-knowledge-graph.md

@@ -1,71 +1,71 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
----
+---
 title: Query the Knowledge Graph
 description: Use the `knowledge:*` CLI subcommands on `elevasis-sdk` (external projects) and `elevasis` (monorepo) to browse, inspect, and traverse the OrganizationModel knowledge graph via six mount axes.
----
-
-# Query the Knowledge Graph
-
-The `knowledge:*` subcommands expose the OrganizationModel as a virtual filesystem. Paths are query strings -- `/by-system/sales/crm/` dispatches to a graph query, not a directory on disk. Three verbs cover all access patterns: `ls` (list), `cat` (read a node body), and `graph` (traverse edges).
-
-Both CLIs share the same query layer (`@repo/core/knowledge/queries`). The only difference is which OrganizationModel they load:
-
-- `elevasis-sdk` -- runs from inside `external/<project>/`, walks up to `.elevasis`, loads the project's `core/config/organization-model.ts`.
-- `elevasis` -- runs from the monorepo root, loads `canonicalOrganizationModel` from `@repo/elevasis-core`.
-
-## Before you start
-
-The `knowledge:*` commands require `elevasis-sdk >= 1.4.0`. Check with:
-
-```bash
-pnpm exec elevasis-sdk --version
-```
-
-If you are running on Windows, **use PowerShell** for all `knowledge:*` commands. MSYS Bash rewrites the leading `/by-system/...` path argument to a Windows filesystem path, mangling the query. PowerShell passes the argument through verbatim.
-
-## Three Verbs
-
-| Verb                   | Behavior                                                                                                                    |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `knowledge:ls <path>`  | List nodes or edges for the mount. Default: id + summary table. `--json` for the wrapped envelope. `--ids-only` for piping. |
-| `knowledge:cat <id>`   | Print a node's raw MDX `body` to stdout.                                                                                    |
-| `knowledge:graph <id>` | Show outgoing and incoming edges for a node, grouped by edge kind.                                                          |
-
-All three accept `--json` for machine-readable output. `knowledge:ls` additionally accepts `--ids-only` to print one node ID per line.
-
+---
+
+# Query the Knowledge Graph
+
+The `knowledge:*` subcommands expose the OrganizationModel as a virtual filesystem. Paths are query strings -- `/by-system/sales/crm/` dispatches to a graph query, not a directory on disk. Three verbs cover all access patterns: `ls` (list), `cat` (read a node body), and `graph` (traverse edges).
+
+Both CLIs share the same query layer (`@repo/core/knowledge/queries`). The only difference is which OrganizationModel they load:
+
+- `elevasis-sdk` -- runs from inside `external/<project>/`, walks up to `.elevasis`, loads the project's `core/config/organization-model.ts`.
+- `elevasis` -- runs from the monorepo root, loads `canonicalOrganizationModel` from `@repo/elevasis-core`.
+
+## Before you start
+
+The `knowledge:*` commands require `elevasis-sdk >= 1.4.0`. Check with:
+
+```bash
+pnpm exec elevasis-sdk --version
+```
+
+If you are running on Windows, **use PowerShell** for all `knowledge:*` commands. MSYS Bash rewrites the leading `/by-system/...` path argument to a Windows filesystem path, mangling the query. PowerShell passes the argument through verbatim.
+
+## Three Verbs
+
+| Verb                   | Behavior                                                                                                                    |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `knowledge:ls <path>`  | List nodes or edges for the mount. Default: id + summary table. `--json` for the wrapped envelope. `--ids-only` for piping. |
+| `knowledge:cat <id>`   | Print a node's raw MDX `body` to stdout.                                                                                    |
+| `knowledge:graph <id>` | Show outgoing and incoming edges for a node, grouped by edge kind.                                                          |
+
+All three accept `--json` for machine-readable output. `knowledge:ls` additionally accepts `--ids-only` to print one node ID per line.
+
 ## Six Mount Axes
 
 The path argument to `knowledge:ls` determines the query. Six axes are available:
 
-| Path prefix                    | Query                         | Returns                                             |
-| ------------------------------ | ----------------------------- | --------------------------------------------------- |
-| `/by-system/<dotted-id>/`     | `bySystem(graph, systemId)` | nodes with incoming `governs` edges to this system |
-| `/by-ontology/<ontology-id>/` | `byOntology(graph, ontologyId)` | nodes with incoming `governs` edges to this ontology record |
-| `/by-kind/<kind>/`             | `byKind(graph, kind)`         | nodes where `node.kind === kind`                    |
-| `/by-owner/<id>/`              | `byOwner(graph, ownerId)`     | nodes where `node.ownerIds.includes(id)`            |
-| `/graph/<nodeId>/governs/`     | `governs(graph, nodeId)`      | outgoing `governs` edges from `nodeId`              |
-| `/graph/<nodeId>/governed-by/` | `governedBy(graph, nodeId)`   | incoming `governs` edges to `nodeId`                |
-
-## Examples
-
-Each example is shown for both CLIs.
-
-### 1. List by system (`/by-system/<dotted-id>/`)
-
-List all knowledge nodes that govern the `sales.crm` system:
-
-```bash
-# External project (from inside external/<project>/)
-pnpm exec elevasis-sdk knowledge:ls /by-system/sales.crm/
-
-# Monorepo (from monorepo root)
-pnpm exec elevasis knowledge:ls /by-system/sales.crm/
-```
-
-Nested system ids use dots, not slashes: `sales.crm`, `sales.lead-gen`, `projects`.
-
+| Path prefix                    | Query                           | Returns                                                     |
+| ------------------------------ | ------------------------------- | ----------------------------------------------------------- |
+| `/by-system/<dotted-id>/`      | `bySystem(graph, systemId)`     | nodes with incoming `governs` edges to this system          |
+| `/by-ontology/<ontology-id>/`  | `byOntology(graph, ontologyId)` | nodes with incoming `governs` edges to this ontology record |
+| `/by-kind/<kind>/`             | `byKind(graph, kind)`           | nodes where `node.kind === kind`                            |
+| `/by-owner/<id>/`              | `byOwner(graph, ownerId)`       | nodes where `node.ownerIds.includes(id)`                    |
+| `/graph/<nodeId>/governs/`     | `governs(graph, nodeId)`        | outgoing `governs` edges from `nodeId`                      |
+| `/graph/<nodeId>/governed-by/` | `governedBy(graph, nodeId)`     | incoming `governs` edges to `nodeId`                        |
+
+## Examples
+
+Each example is shown for both CLIs.
+
+### 1. List by system (`/by-system/<dotted-id>/`)
+
+List all knowledge nodes that govern the `sales.crm` system:
+
+```bash
+# External project (from inside external/<project>/)
+pnpm exec elevasis-sdk knowledge:ls /by-system/sales.crm/
+
+# Monorepo (from monorepo root)
+pnpm exec elevasis knowledge:ls /by-system/sales.crm/
+```
+
+Nested system ids use dots, not slashes: `sales.crm`, `sales.lead-gen`, `projects`.
+
 ### 2. List by ontology (`/by-ontology/<ontology-id>/`)
 
 List all knowledge nodes that govern the CRM deal ontology record:
@@ -81,112 +81,117 @@ pnpm exec elevasis knowledge:ls /by-ontology/sales.crm:object/deal
 Ontology IDs use `system.path:kind/local-id` or `global:kind/local-id`. Slash-containing ontology IDs are part of the query path; use PowerShell on Windows so the leading `/by-ontology/...` path is not rewritten by MSYS Bash.
 
 ### 3. List by kind (`/by-kind/<kind>/`)
-
-List all nodes of kind `playbook`:
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
-
-# Monorepo
-pnpm exec elevasis knowledge:ls /by-kind/playbook
-```
-
-Common kinds: `playbook`, `strategy`, and `reference`. The available kinds are defined on `OrgKnowledgeNode.kind` in `@elevasis/core/knowledge`.
-
-Machine-readable output for piping:
-
-```bash
-pnpm exec elevasis knowledge:ls /by-kind/playbook --ids-only
-```
-
+
+List all nodes of kind `playbook`:
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
+
+# Monorepo
+pnpm exec elevasis knowledge:ls /by-kind/playbook
+```
+
+Common kinds: `playbook`, `strategy`, and `reference`. The available kinds are defined on `OrgKnowledgeNode.kind` in `@elevasis/core/knowledge`.
+
+Machine-readable output for piping:
+
+```bash
+pnpm exec elevasis knowledge:ls /by-kind/playbook --ids-only
+```
+
 ### 4. List by owner (`/by-owner/<id>/`)
-
-List all knowledge nodes owned by a specific member or team:
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:ls /by-owner/operations-team
-
-# Monorepo
-pnpm exec elevasis knowledge:ls /by-owner/operations-team
-```
-
-The `<id>` matches against `node.ownerIds`. Owner IDs are declared on each knowledge node in the OrganizationModel.
-
+
+List all knowledge nodes owned by a specific member or team:
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:ls /by-owner/operations-team
+
+# Monorepo
+pnpm exec elevasis knowledge:ls /by-owner/operations-team
+```
+
+The `<id>` matches against `node.ownerIds`. Owner IDs are declared on each knowledge node in the OrganizationModel.
+
 ### 5. Traverse outgoing edges (`/graph/<nodeId>/governs/`)
-
-List what a specific node governs (outgoing `governs` edges):
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
-
-# Monorepo
-pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
-```
-
-Knowledge node IDs use the `knowledge.<slug>` source id. Graph node IDs may be kind-prefixed,
-such as `knowledge:knowledge.new-vertical-launch-playbook` or `system:sales.crm`, when traversing
-graph edges.
-
+
+List what a specific node governs (outgoing `governs` edges):
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
+
+# Monorepo
+pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
+```
+
+Knowledge node IDs use the `knowledge.<slug>` source id. Graph node IDs may be kind-prefixed,
+such as `knowledge:knowledge.new-vertical-launch-playbook` or `system:sales.crm`, when traversing
+graph edges.
+
+> **Note:** Graph node IDs like `system:sales.crm` are addresses in the knowledge graph API and
+> are distinct from the Organization Model `resource.systemPath` field. A resource attaches to a
+> System with `systemPath: 'sales.crm'` (no prefix); the same System appears in the graph as the
+> node `system:sales.crm`. Do not author `system:`-prefixed values into `resource.systemPath`.
+
 ### 6. Traverse incoming edges (`/graph/<nodeId>/governed-by/`)
-
-List what governs a specific node (incoming `governs` edges):
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
-
-# Monorepo
-pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
-```
-
-## Read a Node Body
-
-`knowledge:cat` prints the raw MDX `body` string for a node. The body is not rendered -- it is the source MDX as stored in the OrganizationModel.
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook
-
-# Monorepo
-pnpm exec elevasis knowledge:cat knowledge.new-vertical-launch-playbook
-```
-
-Pipe to a pager for long bodies:
-
-```bash
-pnpm exec elevasis knowledge:cat knowledge.platform-composition-patterns | less
-```
-
-## Inspect a Node's Edges
-
-`knowledge:graph` shows all edges for a node grouped by kind:
-
-```bash
-# External project
-pnpm exec elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook
-
-# Monorepo
-pnpm exec elevasis knowledge:graph knowledge.new-vertical-launch-playbook
-```
-
-This combines the `governs` and `governed-by` views in one output, useful for understanding a node's full graph position.
-
-## JSON Output
-
+
+List what governs a specific node (incoming `governs` edges):
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
+
+# Monorepo
+pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
+```
+
+## Read a Node Body
+
+`knowledge:cat` prints the raw MDX `body` string for a node. The body is not rendered -- it is the source MDX as stored in the OrganizationModel.
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook
+
+# Monorepo
+pnpm exec elevasis knowledge:cat knowledge.new-vertical-launch-playbook
+```
+
+Pipe to a pager for long bodies:
+
+```bash
+pnpm exec elevasis knowledge:cat knowledge.platform-composition-patterns | less
+```
+
+## Inspect a Node's Edges
+
+`knowledge:graph` shows all edges for a node grouped by kind:
+
+```bash
+# External project
+pnpm exec elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook
+
+# Monorepo
+pnpm exec elevasis knowledge:graph knowledge.new-vertical-launch-playbook
+```
+
+This combines the `governs` and `governed-by` views in one output, useful for understanding a node's full graph position.
+
+## JSON Output
+
 All three verbs accept `--json`. `knowledge:ls --json` uses the wrapped envelope format:
-
-```json
-{
-  "path": "/by-system/sales.crm",
-  "mount": "by-system",
-  "args": ["sales.crm"],
-  "results": [...]
-}
-```
-
+
+```json
+{
+  "path": "/by-system/sales.crm",
+  "mount": "by-system",
+  "args": ["sales.crm"],
+  "results": [...]
+}
+```
+
 This is the format consumed by the `/knowledge` agent skill. Use it when scripting or building tooling that reads knowledge graph data programmatically.
 
 `knowledge:cat --json` returns the full knowledge node object, including the MDX `body`, links, owners, timestamps, and generated `sourceFilePath` when present.
@@ -200,28 +205,27 @@ This is the format consumed by the `/knowledge` agent skill. Use it when scripti
   "incoming": []
 }
 ```
-
-```bash
-pnpm exec elevasis knowledge:ls /by-kind/playbook --json | jq '.results[].id'
-```
-
-## Windows Note
-
-On Windows, MSYS Bash rewrites path arguments starting with `/` to Windows filesystem paths before the CLI sees them. Use PowerShell:
-
-```powershell
-# Correct on Windows -- PowerShell leaves the path arg intact
-pnpm exec elevasis knowledge:ls /by-kind/playbook
-
-# Wrong on Windows -- MSYS Bash mangles to C:\by-kind\playbook or similar
-bash -c "pnpm exec elevasis knowledge:ls /by-kind/playbook"
-```
-
-All other `elevasis` and `elevasis-sdk` commands are unaffected; this gotcha is specific to path arguments that start with `/`.
-
-## See Also
-
+
+```bash
+pnpm exec elevasis knowledge:ls /by-kind/playbook --json | jq '.results[].id'
+```
+
+## Windows Note
+
+On Windows, MSYS Bash rewrites path arguments starting with `/` to Windows filesystem paths before the CLI sees them. Use PowerShell:
+
+```powershell
+# Correct on Windows -- PowerShell leaves the path arg intact
+pnpm exec elevasis knowledge:ls /by-kind/playbook
+
+# Wrong on Windows -- MSYS Bash mangles to C:\by-kind\playbook or similar
+bash -c "pnpm exec elevasis knowledge:ls /by-kind/playbook"
+```
+
+All other `elevasis` and `elevasis-sdk` commands are unaffected; this gotcha is specific to path arguments that start with `/`.
+
+## See Also
+
 - [Query functions API](../reference/contracts.md) -- `bySystem`, `byOntology`, `byKind`, `byOwner`, `governs`, `governedBy` TypeScript signatures
-- [Glossary](../reference/glossary.md) -- `systemId`, `nodeId`, `kind`, `ownerIds`
-- [Knowledge Browser](../../../../apps/docs/content/docs/in-progress/active-development/sdk-changes/knowledge/index.mdx) -- task doc for the full Knowledge Map bundle
-
+- [Glossary](../reference/glossary.md) -- `systemId`, `nodeId`, `kind`, `ownerIds`
+- [Knowledge Browser](../../../../apps/docs/content/docs/in-progress/active-development/sdk-changes/knowledge/index.mdx) -- task doc for the full Knowledge Map bundle