# 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.
