@elevasis/sdk 1.33.1 → 1.34.0

package/reference/claude-config/sync-notes/2026-06-05-ontology-endpoint-rename-and-knowledge-browser-ui.md

@@ -0,0 +1,86 @@
+# Ontology `surface` → `endpoint` rename + Knowledge Browser UI upgrades
+
+## Why this note exists
+
+This release bumps **both** `@elevasis/core` and `@elevasis/ui`. Two distinct changes ride it:
+
+1. **Breaking OM contract rename (`@elevasis/core`).** The ontology kind `surface` was renamed to
+   `endpoint` to stop colliding with **navigation surfaces** (shell sidebar routes). The published
+   contract changed: the `OntologyKind` enum member `'surface'` is now `'endpoint'`, the ontology ID
+   namespace `…:surface/…` is now `…:endpoint/…`, `ontology.surfaces` is now `ontology.endpoints`,
+   and the exported `OntologySurfaceType` / `OntologySurfaceTypeSchema` are now
+   `OntologyEndpointType` / `OntologyEndpointTypeSchema`. **There is no back-compat alias** (hard
+   rename — the kind was near-dormant). Any tenant OM that still declares a `:surface/` **ontology**
+   ID will fail validation once it installs the new `@elevasis/core`.
+
+2. **Knowledge Browser UI upgrades (`@elevasis/ui`).** Three additive, platform-substrate
+   enhancements that tenants get purely on the `@elevasis/ui` bump — no authoring change required:
+   full `ClientProfile` detail rendering in the Clients panel, clickable group child cards
+   (Profile → Identity/Branding navigate like the tree), and explanatory hover tooltips on
+   platform-vocabulary badges/edge labels. The ontology tree row + its tooltip now read
+   **"Endpoints"** instead of "Surfaces", consistent with change #1.
+
+## Applies to
+
+- **Change #1 (ontology rename):** every tenant whose `core/config/organization-model/` declares any
+  ontology ID with a `:surface/` segment (i.e. an entry under a System's `ontology.surfaces`).
+  **Confirmed in this train: ZERO live tenants carry any `:surface/` ontology ID** (verified by a
+  repo-wide grep across all of `external/` — only `_template` carried one, migrated in this train).
+  The 3 live derived projects (ZentaraHQ, nirvana-marketing, contemplative-records) inherit
+  `endpoint/` cleanly. Run the verification below anyway before installing the new `@elevasis/core`.
+- **Change #2 (UI upgrades):** every template-derived project — they render on the `@elevasis/ui`
+  bump with no further action.
+
+## Required actions
+
+`/git-sync` / `/external sync` delivers the new `@elevasis/core` + `@elevasis/ui` dependency
+baselines and this note. The dependency bumps install automatically; the ontology-ID rewrite (only if
+your project authored any) is project-owned OM content and is **not** auto-applied.
+
+1. **Install the baselines together.** Bump `@elevasis/core` and `@elevasis/ui` in the same change
+   (the baseline write from sync covers `core/package.json`, `operations/package.json`, and
+   `ui/package.json`). Do not install the new `@elevasis/core` while your OM still has any `:surface/`
+   **ontology** ID.
+2. **Rename any ontology `surface/` IDs (only if present).** In `core/config/organization-model/`,
+   change every ontology ID `…:surface/<name>` to `…:endpoint/<name>`, and the containing
+   `ontology: { surfaces: { … } }` key to `ontology: { endpoints: { … } }`. Update every
+   cross-reference (`ownerSystemId`, `route`, links, etc.). Most tenants have nothing to change here.
+3. **Do NOT touch navigation surfaces.** This is the critical disambiguation. The rename is
+   ontology-only. Leave `system.surfaces`, `ui.surfaces`, sidebar `SidebarSurfaceNode`s, the
+   `surfaceType` route field, the graph node kind `surface`, and `SurfaceDescribeView` **unchanged** —
+   those legitimately own the word "surface" for shell routing and are orthogonal to the ontology kind.
+4. **Update tests.** If your `core/config/organization-model.test.ts` or contract tests assert
+   `compiled.ontology.surfaces` or a `:surface/` ontology ID, rename them to `.endpoints` /
+   `:endpoint/`. Leave any `ui.surfaces` / navigation-surface assertions alone.
+5. **Verify, then boot.** Run the verification block, then `pnpm -C core test` and
+   `pnpm -C ui check-types` before booting the app.
+
+## Verification
+
+```bash
+# 1. Find any remaining ontology surface/ IDs (navigation surfaces are fine — see discriminator)
+grep -rn ":surface/\|ontology.surfaces\|OntologySurfaceType" core/config/organization-model
+
+# Discriminator while reading hits:
+#   ontology (RENAME)  -> a ":surface/" ID segment, "ontology: { surfaces: ... }", OntologySurface*
+#   navigation (KEEP)  -> bare system.surfaces / ui.surfaces, SidebarSurface*, surfaceType
+
+# 2. Template-family coherence
+pnpm -C core test
+pnpm -C ui check-types
+pnpm -C ui test:contracts
+
+# 3. Boot must not throw OM validation (no unknown OntologyKind)
+```
+
+`OntologyKindSchema` must accept `endpoint` and reject `surface`; no `:surface/` ontology ID may
+remain. Navigation surfaces must still resolve and render in the sidebar.
+
+## Not handled by /git-sync
+
+- `/git-sync` and `/external sync` deliver the `@elevasis/core` + `@elevasis/ui` dependency baselines
+  and this note, but they do **not** edit your `core/config/organization-model/` — tenant OM content
+  is project-owned (`sync-preservation`). The `surface/` → `endpoint/` ontology-ID rewrite in steps
+  2–4 is manual per tenant (a no-op for every current live tenant, which carries none).
+- The Knowledge Browser UI upgrades (change #2) require **no** action — they are entirely inside
+  `@elevasis/ui` and appear on the bump.

package/reference/claude-config/sync-notes/2026-06-06-om-item-copy-references.md

@@ -0,0 +1,50 @@
+# Knowledge Browser item copy-references now resolve via `om:describe item:<domain>:<id>`
+
+## Why this note exists
+
+The Knowledge Browser used to copy an unresolvable `graph:<kind>:<uuid>` shorthand for
+domain items (clients, roles, policies, customers, offerings, goals). Pasting that to an
+agent led to dead ends — the OM resolver had no mount for it and `om:describe` rejected the
+id. This train (published `@elevasis/core`, `@elevasis/sdk`, `@elevasis/ui` + the bundled
+`om` skill) standardizes domain-item copy references on `item:<domain>:<id>`, which resolves
+to the rich profile plus its location and governing knowledge. The `om` skill's read-folder
+table and CLI invocation guidance changed, so derived projects must pick up the new skill
+text and package baselines.
+
+## Applies to
+
+- All template-derived projects that ship the `om` skill (`.claude/skills/om/SKILL.md`).
+- Any project whose Knowledge Browser surfaces domain items (clients, roles, policies,
+  customers, offerings, goals).
+- Agents that consume copied Knowledge Browser references.
+
+## Required actions
+
+1. Pull template changes and bump the published package baselines to the versions shipped by
+   this train: `@elevasis/core`, `@elevasis/sdk`, `@elevasis/ui` (run `pnpm install` after the
+   baseline bump so the new SDK CLI and UI copy behavior are present).
+2. Adopt the refreshed `.claude/skills/om/SKILL.md` read-folder table. It now documents
+   `item:<domain>:<id>` (resolves via `om:describe item:<domain>:<id>`), the `/by-domain/<domain>`
+   and `/by-item/<domain>/<id>` `om:ls` mounts, `group:` / `domain:` / `folder:` as
+   browser-overview references, and a legacy `graph:client:<uuid>` bridge note pointing to
+   `om:describe item:clients:<uuid>`.
+3. Use the corrected SDK CLI invocation at a project root: `pnpm elevasis-sdk om:describe …`
+   (root script alias) or `pnpm -C operations exec elevasis-sdk om:describe …`. The old
+   `pnpm exec elevasis-sdk …` at the project root fails in a multi-package tenant — replace it.
+
+## Verification
+
+- `pnpm elevasis-sdk om:describe item:clients:<id>` returns the client profile, its location
+  (domain + graph id + `contains` parentage), and any governing knowledge — no dead ends.
+- A bare/legacy `om:describe client:<uuid>` still resolves (back-compat for already-copied
+  references).
+- `pnpm sync:verify -- <project>` shows the `.claude/skills/om/SKILL.md` write applied and no
+  remaining `om`-skill drift.
+
+## Not handled by /git-sync
+
+- The published-package baseline bumps (`@elevasis/core` / `@elevasis/sdk` / `@elevasis/ui`)
+  and the subsequent `pnpm install` are manual — `/git-sync` does not bump dependencies.
+- Any project-local documentation that hand-copied the old `pnpm exec elevasis-sdk` root
+  invocation or the old `graph:<kind>:<uuid>` copy vocabulary must be corrected by the
+  maintainer; `/git-sync` stops before touching project-owned surfaces.

package/reference/sdk/cli-management.mdx

@@ -1,12 +1,28 @@
 ---
 title: CLI Management Commands
-description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, and ui subcommand families
+description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, ui, and skill subcommand families
 ---
 
 This page covers the domain management commands for `elevasis-sdk`. For core SDK commands (check, deploy, exec, resources, executions, describe, creds, rename), see [CLI Reference](cli.mdx).
 
 ---
 
+## JSON-valued options
+
+Any option that expects JSON can take inline JSON or a file reference:
+
+```bash
+elevasis-sdk queue:select <id> --action-id approve --payload @json:tmp/queue-payload.json
+elevasis-sdk schedule:create --name "Weekly report" --target-resource-type workflow --target-resource-id weekly-report --schedule-config @json:tmp/schedule-config.json
+elevasis-sdk project:task:save <id> --current-state "Updated" --files-modified @json:tmp/files-modified.json
+```
+
+`@json:<path>` is expanded before command parsing, so existing command handlers receive the same JSON string they would receive from an inline argument. Relative paths resolve against the Elevasis project root when the current directory is inside a project; otherwise they resolve against the current working directory. The referenced file must contain valid JSON.
+
+Use `@json:<path>` for generated payloads, nested objects, arrays, or Windows shells. Inline JSON remains supported for small values.
+
+---
+
 ## elevasis-sdk project:\*
 
 `elevasis-sdk project:*` is the canonical project-management surface. Use it for project, milestone, task, and note operations whether the caller is a human, a scripted workflow, or a slash-command router like `/project`.
@@ -42,18 +58,23 @@ elevasis-sdk project:milestone:list --project <id>
 elevasis-sdk project:milestone:create --project <id> --name "Phase 1"
 elevasis-sdk project:milestone:update <id> --status completed
 elevasis-sdk project:milestone:update <id> --description "Updated scope description"
+elevasis-sdk project:milestone:update <id> --checklist @json:tmp/milestone-checklist.json
 elevasis-sdk project:milestone:delete <id>
 ```
 
 `project:milestone:update` accepts `--description` to set or clear the milestone description. Passing an empty string clears the field, matching `project:task:update --description` semantics.
 
+Checklist updates are full replacements. Use `--checklist <json>` for small inline arrays, or `--checklist @json:<path>` for generated JSON. `--checklist-file <path>` is also supported for checklist-specific file input.
+
 ### Tasks
 
 ```bash
 elevasis-sdk project:task:list --project <id>
 elevasis-sdk project:task:get <id>
 elevasis-sdk project:task:create --project <id> --title "Implement API"
+elevasis-sdk project:task:create --project <id> --title "Implement API" --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:update <id> --status in_progress
+elevasis-sdk project:task:update <id> --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:delete <id>
 ```
 
@@ -68,6 +89,8 @@ elevasis-sdk project:task:save <id> --current-state <text> [--files-modified <js
 - `project:task:save <id>` -- merges fields into `resume_context`; `--current-state` is required; all other flags are optional JSON arrays or plain text
 - these commands are the CLI counterpart to `/work resume` and `/work save` style flows
 
+Task checklist flags are also full replacements. `project:task:create`, `project:task:update`, and `project:milestone:update` support `--checklist <json>`, `--checklist @json:<path>`, and `--checklist-file <path>`. Prefer `@json:<path>` for non-trivial JSON and Windows shells because it works across JSON-valued options, not only checklist commands.
+
 **`project:task:save` flags:**
 
 | Flag                        | Description                               |
@@ -373,7 +396,7 @@ JWT-gated routes at the original unprefixed paths remain for the Command Center.
 
 Full CRUD management for client records. The `client:*` family covers create, read, update, and delete operations at `/api/external/clients`.
 
-For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/clients).
+For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/operations/clients).
 
 **Quick reference:**
 
@@ -650,6 +673,24 @@ Both commands install after rewriting `package.json`. The `external/_template` r
 
 ---
 
+## elevasis-sdk skill:\*
+
+Developer-facing skill tooling keeps the template `.claude/skills/` surface aligned with the live CLI catalog.
+
+```bash
+elevasis-sdk skill:scaffold <domain>
+elevasis-sdk skill:check-coverage
+```
+
+- `skill:scaffold <domain>` prints a `SKILL.md` stub built from `elevasis-sdk cli --format json` for that domain. Author the curated skill at `external/_template/.claude/skills/<domain>/SKILL.md`; do not edit generated SDK reference copies directly.
+- `skill:check-coverage` compares live CLI domains against `.claude/registries/skill-coverage.json`. Domains must be owned by a skill or explicitly waived.
+
+The same coverage gate runs inside `elevasis-sdk check` when the coverage registry exists in the project root.
+
+**Implementation:** `packages/sdk/src/cli/commands/skill/`
+
+---
+
 ## Appendix: Domain Status
 
 Current status of all SDK CLI domains. Domains marked `deferred` have no CLI commands yet.
@@ -669,6 +710,7 @@ Current status of all SDK CLI domains. Domains marked `deferred` have no CLI com
 | session     | `session:list`, `session:get`, `session:end`                              | `/api/external/sessions*`                                  | implemented management scope |
 | queue       | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*`                             | implemented                  |
 | schedule    | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`     | `/api/external/task-scheduler/schedules*`                  | implemented                  |
+| skill       | `skill:scaffold`, `skill:check-coverage`                                  | local CLI catalog and `.claude/registries/skill-coverage.json` | implemented developer tooling |
 | content     | none                                                                      | not scoped here                                            | deferred                     |
 | seo         | none                                                                      | not scoped here                                            | deferred                     |
 | monitoring  | none                                                                      | not scoped here                                            | deferred                     |

package/reference/sdk/cli.mdx

@@ -13,7 +13,7 @@ pnpm add @elevasis/sdk
 
 After installation, the `elevasis-sdk` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_PLATFORM_KEY` to be set in your environment or a `.env` file.
 
-For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*), see [CLI Management](cli-management.mdx).
+For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*, skill:\*), see [CLI Management](cli-management.mdx).
 
 ---
 
@@ -30,6 +30,7 @@ elevasis-sdk check
 **Behavior:**
 
 - Imports your `src/index.ts` and runs it through `ResourceRegistry` validation
+- Runs the skill coverage gate when `.claude/registries/skill-coverage.json` is present, ensuring every live CLI domain is covered by a template skill or explicitly waived
 - Catches the same errors that the platform catches at deploy time:
   - Duplicate `resourceId` within the organization
   - Invalid model configuration (temperature and token bounds)