@elevasis/core 0.24.0 → 0.25.0

package/src/reference/glossary.md

@@ -1,76 +1,78 @@
----
-title: Glossary
-description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
----
-
-# Glossary
-
-## Terms
-
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
-
-**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
-
-**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
-
-**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
-
-**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
-
+---
+title: Glossary
+description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
+---
+
+# Glossary
+
+## Terms
+
+**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+
+**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
+
+**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
+
+**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
+
+**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
+
 **SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional `sidebarWidth`. Graph bridge metadata is compatibility-only; new semantic bindings belong in the Organization Model System, ontology, navigation, and Resource descriptors.
-
-**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
-
-**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
-
-**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
-
-**Manifest** -- a runtime declaration for a feature or resource collection.
-
+
+**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
+
+**systemId (resource — deprecated)** -- the legacy `resource.systemId` field on Organization Model resource descriptors. Removed from the target contract; the canonical attachment is **`resource.systemPath`** (dot-separated path resolved against the system tree). Some external templates still ship a `systemId` compatibility mirror while published `@elevasis/core` releases catch up; treat that field as legacy adapter data only and author new resource relationships against `systemPath`. Query with `getResourcesForSystem(model, path)`.
+
+**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
+
+**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
+
+**Manifest** -- a runtime declaration for a feature or resource collection.
+
 **MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
-
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
-
+
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
+
 **OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
-
-**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
-
-**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
-
-**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, governance `status`, optional role ownership, optional `actionKey`, `codeRefs`, and nested `ontology` bindings for implemented actions, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
-
+
+**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
+
+**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
+
+**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, descriptor `title` / `description`, governance `status`, optional role ownership, `codeRefs`, and nested `ontology` bindings for `actions`, optional `primaryAction`, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
+
 **System** -- tenant-defined bounded context in `OrganizationModel.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, lifecycle, System-local ontology, and System-local config.
-
-**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
-
-**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
-
-**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
-
-**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
-
-**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
-
-**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
-
-## Package Boundary
-
-**`@elevasis/core`**
-
-- `OrganizationModel`, `OrganizationModelSystemEntry`
-- `SystemEntry`, `ResourceEntry`
-- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
-- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
-
-**`@elevasis/ui`**
-
-- `SystemModule`
-- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
-- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
-
-**External project source**
-
-- `canonicalOrganizationModel`
-- `organizationModel`
-- workflow I/O schemas
+
+**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
+
+**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
+
+**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
+
+**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
+
+**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
+
+**Topology** -- durable OM operational wiring declared in `OrganizationModel.topology.relationships`. Initial relationship kinds are `triggers`, `uses`, and `approval`; relationships use typed refs such as `{ kind: 'resource', id: 'lead-import' }`.
+
+## Package Boundary
+
+**`@elevasis/core`**
+
+- `OrganizationModel`, `OrganizationModelSystemEntry`
+- `SystemEntry`, `ResourceEntry`
+- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
+- `MembershipFeatureConfig`
+- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
+
+**`@elevasis/ui`**
+
+- `SystemModule`
+- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
+- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
+
+**External project source**
+
+- `canonicalOrganizationModel`
+- `organizationModel`
+- workflow I/O schemas