@elevasis/sdk 1.20.1 → 1.21.0

package/reference/claude-config/skills/knowledge/SKILL.md

@@ -3,15 +3,15 @@ name: knowledge
 description: |
   TRIGGER this skill when any of the following apply:
   - The user references organization-model entities by name or concept: identity, customers,
-    offerings, roles, goals, techStack, features, labels, knowledge nodes, governance edges,
+    offerings, roles, goals, techStack, systems, actions, labels, knowledge nodes, governance edges,
     mounts, playbook, outreach cadence, or any domain in the org model.
   - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
     update, toggle, enable, or disable any organization-model domain or knowledge node.
-  - The user asks "what governs X?", "what does X control?", "feature governs", "what is our
+  - The user asks "what governs X?", "what does X control?", "system governs", "what is our
     identity set to?", "what's our timezone?", "show me all reference docs", "list my roles",
     "where does outreach-cadence apply?", or similar.
   - An agent is editing files matching: core/config/organization-model.ts,
-    core/config/organization-model.ts, packages/elevasis-core/src/organization-model.ts,
+    core/config/organization-model.ts, packages/elevasis-core/src/organization-model/index.ts,
     or packages/core/src/knowledge/**.
   SKIP this skill when the task is purely UI layout, workflow authoring, or infrastructure
   work with no reference to org-model or knowledge-graph entities.
@@ -19,19 +19,19 @@ metadata:
   pathPatterns:
     - "core/config/organization-model.ts"
     - "core/config/organization-model.ts"
-    - "packages/elevasis-core/src/organization-model.ts"
+    - "packages/elevasis-core/src/organization-model/**"
     - "packages/core/src/knowledge/**"
   promptSignals:
     phrases:
       - playbook
       - knowledge node
-      - feature governs
+      - system governs
       - outreach cadence
       - identity
       - customer segment
       - codify
-      - enable feature
-      - toggle feature
+      - enable system
+      - toggle system
       - what governs
       - org model
       - organization model
@@ -68,11 +68,11 @@ context and routes to the appropriate flow internally.
 This skill auto-invokes whenever:
 
 - Conversation references org-model entities (identity, customers, offerings, roles, goals,
-  techStack, features, labels, knowledge nodes, governance edges, mounts)
+  techStack, systems, actions, labels, knowledge nodes, governance edges, mounts)
 - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
   update, toggle, enable, or disable any of those
 - An agent is editing files matching `core/config/organization-model.ts`,
-  `core/config/organization-model.ts`, `packages/elevasis-core/src/organization-model.ts`,
+  `core/config/organization-model.ts`, `packages/elevasis-core/src/organization-model/index.ts`,
   or `packages/core/src/knowledge/**`
 
 Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`, and
@@ -90,10 +90,10 @@ cannot bypass the write gate.
 | Flow     | Triggers (examples)                                                                | Mechanics                                                                                                     |
 | -------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | Read     | "what playbooks govern sales.crm?", "show me all reference docs", "list my roles"  | Run CLI read commands (monorepo or external); format result                                                   |
-| Navigate | "what governs this feature?", "where does outreach-cadence apply?"                 | Same CLI; pick mount axis from intent; default to `by-feature` for orientation queries                        |
+| Navigate | "what governs this system?", "where does outreach-cadence apply?"                  | Same CLI; pick mount axis from intent; default to `by-system` for orientation queries                         |
 | Describe | "what is our identity set to?", "what's our timezone?"                             | Read current values from OM source; narrate                                                                   |
 | Codify   | "we're an e-commerce company", "add a customer segment", "our outreach goal is..." | Run codify ceremony with shared-layer impact preview: snapshot -> propose -> confirm -> write -> typecheck -> Zod parse -> rollback on failure |
-| Toggle   | "enable the lead-gen feature", "turn off SEO"                                      | Codify ceremony scoped to `features` domain; flip the boolean; same validation/rollback                       |
+| Toggle   | "enable the lead-gen system", "turn off SEO"                                       | Codify ceremony scoped to the `systems` domain; flip availability/routing state; same validation/rollback     |
 
 ---
 
@@ -124,6 +124,29 @@ through `/knowledge`; do not point them at monorepo-only commands.
 
 ---
 
+## Organization Model Navigation Guide
+
+Use this map whenever the task asks what something is, where it lives, what governs it, or
+what adjacent context may matter:
+
+| Question | Start here | Then inspect |
+| --- | --- | --- |
+| What Systems exist? | `core/config/organization-model.ts` | System IDs, parentage, lifecycle, UI metadata, and content |
+| What governs a System? | `/by-system/<id>` knowledge read | system entry, governed knowledge, roles, policies, graph `governs` edges |
+| What resources belong to a System? | `organizationModel.resources.entries` and `getResourcesForSystem(model, systemPath)` | use `{ includeDescendants: true }` only for parent-scope rollups |
+| What can a System do? | system action refs and the actions domain | `action.resourceId`, invocation metadata, affected entities, policies |
+| What data does it own? | entities domain | owning System refs, state catalogs, entity links, emitted/projected events |
+| What operational content exists? | system `content` | content helpers and scaffold migration helpers when available |
+| What UI surface exposes it? | `navigation.sidebar` plus `SystemModule` manifests | route files, surface targets, route-prefix modules, guards |
+| What knowledge applies? | knowledge domain plus graph edges | `knowledge:cat`, `knowledge:graph`, `/graph/<id>/governed-by` |
+
+Do not treat any one read as a complete system snapshot. The OM is a set of related
+domain maps; follow the relationship that matches the work. Prefer structured helpers
+from `@elevasis/core/organization-model` over ad hoc string scanning when code access is
+available.
+
+---
+
 ## Read Patterns
 
 ### Monorepo (platform defaults)
@@ -131,7 +154,7 @@ through `/knowledge`; do not point them at monorepo-only commands.
 ```bash
 pnpm exec elevasis knowledge:ls
 pnpm exec elevasis knowledge:cat <node-id>
-pnpm exec elevasis knowledge:ls /by-feature/<feature-id>
+pnpm exec elevasis knowledge:ls /by-system/<system-id>
 pnpm exec elevasis knowledge:ls /by-owner/<owner-id>
 pnpm exec elevasis knowledge:graph <node-id>
 ```
@@ -141,31 +164,52 @@ pnpm exec elevasis knowledge:graph <node-id>
 ```bash
 pnpm exec elevasis-sdk knowledge:ls
 pnpm exec elevasis-sdk knowledge:cat <node-id>
-pnpm exec elevasis-sdk knowledge:ls /by-feature/<feature-id>
+pnpm exec elevasis-sdk knowledge:ls /by-system/<system-id>
 pnpm exec elevasis-sdk knowledge:ls /by-owner/<owner-id>
 pnpm exec elevasis-sdk knowledge:graph <node-id>
 ```
 
 Use `knowledge:ls` to enumerate all knowledge nodes. Use `knowledge:cat` to read a specific
-node's content. Use `knowledge:ls /by-feature/<feature-id>` or
-`knowledge:ls /by-owner/<owner-id>` to navigate feature and owner groupings. Use
+node's content. Use `knowledge:ls /by-system/<system-id>` or
+`knowledge:ls /by-owner/<owner-id>` to navigate system and owner groupings. Use
 `knowledge:graph <node-id>` to inspect incoming and outgoing graph edges for a specific node.
 
 ### `/knowledge read-folder` (chat shorthand from the Knowledge Browser)
 
-The Knowledge Browser's copy button on a top-level feature or kind group emits a single
+The Knowledge Browser's copy button on a top-level system or kind group emits a single
 `/knowledge read-folder <axis>:<id>` line instead of N per-node `read` lines. Resolve it by
 listing the folder via `knowledge:ls` and reading each child:
 
-| Copy form                             | Resolution (external)                                                                        |
-| ------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `/knowledge read-folder feature:<id>` | `pnpm exec elevasis-sdk knowledge:ls /by-feature/<id> --ids-only`, then `knowledge:cat` each |
-| `/knowledge read-folder kind:<kind>`  | `pnpm exec elevasis-sdk knowledge:ls /by-kind/<kind> --ids-only`, then `knowledge:cat` each  |
-
-Dotted feature ids may use either dots or slashes (`sales.crm` and `sales/crm` both work
-with `knowledge:ls`). Per-node leaves still copy as `/knowledge read <node-id>`; virtual
-sub-folders inside a feature (regex-grouped UI buckets like Campaigns/Pipeline) keep the
-N-line list since they have no stable folder id.
+| Copy form                            | Resolution (external)                                                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `/knowledge read-folder system:<id>` | `pnpm exec elevasis-sdk knowledge:ls /by-system/<id> --ids-only`, then `knowledge:cat` each   |
+| `/knowledge read-folder kind:<kind>` | `pnpm exec elevasis-sdk knowledge:ls /by-kind/<kind> --ids-only`, then `knowledge:cat` each    |
+| `/knowledge read-folder owner:<id>`  | `pnpm exec elevasis-sdk knowledge:ls /by-owner/<id> --ids-only`, then `knowledge:cat` each     |
+| `/knowledge read-folder graph:<id>`  | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids      |
+
+Dotted system ids may use either dots or slashes (`sales.crm` and `sales/crm` both work
+with `knowledge:ls`). Legacy `feature:<id>` copy lines may still appear in older browser
+builds; treat them as compatibility aliases for `system:<id>` and resolve through `/by-system/`.
+Per-node leaves still copy as `/knowledge read <node-id>`. Browser group/domain/item folders
+usually copy explicit N-line read lists when they contain knowledge nodes; if they fall back to
+`group:`, `domain:`, `item:`, or `folder:` route ids, treat those as UI route breadcrumbs, not
+CLI mounts. Resolve them from visible child knowledge ids or the corresponding OM/graph context.
+
+`read-folder system:<id>` is the baseline knowledge read, not a mandatory full-system
+snapshot. Start by loading governing knowledge nodes. Broaden into adjacent Organization
+Model context only when the current task makes it relevant:
+
+- Runtime or implementation work: inspect `organizationModel.resources.entries` with
+  `getResourcesForSystem(model, id)` or `getResourcesForSystem(model, id, { includeDescendants: true })`.
+- Operational configuration: inspect the system entry, `system.content`, `getContent()`,
+  `resolveSystemContent()`, and scaffold migration helpers when applicable.
+- Governance or access work: inspect roles, policies, actions, entities, and graph edges
+  through the Organization Graph or direct `core/config/organization-model.ts` domain reads.
+- Deployment/code work: follow resource ids into `operations/src/**` only when the task
+  needs executable implementation details.
+
+There is no first-class CLI mount for "all resources/actions/entities/policies/roles by
+system" yet. Use the helpers above or scan the org model plus the relevant domain maps.
 
 ---
 
@@ -236,7 +280,7 @@ classification names a specific domain.
 - `.claude/skills/knowledge/operations/roles.md` -- role chart
 - `.claude/skills/knowledge/operations/goals.md` -- organizational goals
 - `.claude/skills/knowledge/operations/techStack.md` -- external integration registry
-- `.claude/skills/knowledge/operations/features.md` -- feature toggles and Level B extension gate
+- `.claude/skills/knowledge/operations/features.md` -- legacy compatibility notes for feature wording; current availability/routing work uses Systems and Actions language
 - `.claude/skills/knowledge/operations/labels.md` -- inline display labels on enum entries
 
 These files are populated by Wave B2 and own the domain-specific schema reference content. The
@@ -249,7 +293,7 @@ and routing.
 
 ### External projects (canonical scope -- full power)
 
-In external projects (`external/nirvana-marketing`, `external/ZentaraHQ`, etc.) this skill has
+In external projects (`external/_template`, `external/ZentaraHQ`, etc.) this skill has
 full power: read + write + codify + toggle. The org-model file is
 `core/config/organization-model.ts` (or `core/config/organization-model.ts` for
 `external/_template`-derived projects). Extension files live in `core/config/extensions/`.
@@ -259,11 +303,11 @@ This is the environment where Codify and Toggle intents write. All six ceremony
 ### Monorepo (read-only pointer for tenants; direct PR for platform)
 
 The monorepo-side skill at `.claude/skills/knowledge/SKILL.md` is a read-only pointer. For
-tenant agents reading the platform OM, it reads `packages/elevasis-core/src/organization-model.ts`
+tenant agents reading the platform OM, it reads `packages/elevasis-core/src/organization-model/index.ts`
 (the workspace-resident platform OM, importable as `@repo/elevasis-core/organization-model`).
 It documents read patterns and explicitly declines write operations for tenant contexts.
 
-To modify the Elevasis runtime/platform OM, edit `packages/elevasis-core/src/organization-model.ts`
+To modify the Elevasis runtime/platform OM, edit files under `packages/elevasis-core/src/organization-model/`
 via a standard PR in the monorepo -- this is source-controlled workspace code, not an external
 project. To modify your own tenant org-model state, work in `external/<your-project>/` where
 `/knowledge` has full write power via the codify ceremony.

package/reference/claude-config/skills/knowledge/operations/codify-level-a.md

@@ -6,7 +6,7 @@ ceremony is: snapshot current file, propose the edit, write the edit, validate,
 failure.
 
 This pipeline is called by domain operations (identity, customers, offerings, roles, goals,
-techStack, features, labels) after the user has confirmed the proposed change. The caller provides
+techStack, systems, actions, labels, and legacy feature compatibility) after the user has confirmed the proposed change. The caller provides
 the specific field/block being changed and the proposed new value.
 
 ---

package/reference/claude-config/skills/knowledge/operations/codify-level-b.md

@@ -1,8 +1,8 @@
 # Codify Pipeline: Level B (New Extension TypeScript Files)
 
 Level B is the codify pipeline for changes that require creating a new TypeScript file under
-`core/config/extensions/`. This pipeline is used when the user wants to add a custom
-feature, a custom entity type, or any structural addition that cannot be expressed as a simple
+`core/config/extensions/`. This pipeline is used when the user wants to add or extend a System,
+add an Action, add a custom entity type, or make any structural addition that cannot be expressed as a simple
 field override in `core/config/organization-model.ts`.
 
 Level B is **only offered when the user explicitly asks** for something that requires a new file.
@@ -12,13 +12,14 @@ Never silently escalate from Level A to Level B. If Level A is sufficient, use i
 
 ## When Level B applies
 
-- Adding a custom feature that does not exist in the platform defaults (new `FeatureSchema` entry
-  with a custom ID, manifest wiring, and route references)
+- Adding or extending a System that does not exist in the platform defaults, including routing,
+  manifest wiring, and route references
+- Adding an Action that is invokable by a workflow, agent, command, or UI trigger
 - Adding a custom entity extension (new Zod schema extending a base entity type)
 - Any structural addition the caller's domain operation has determined cannot be expressed as a
   field value in the existing adapter
 
-The calling operation (e.g. `features.md`) is responsible for deciding when Level B is needed
+The calling operation (or the legacy compatibility notes in `features.md`) is responsible for deciding when Level B is needed
 and for confirming the intent with the user before invoking this pipeline.
 
 ---
@@ -38,7 +39,7 @@ Read("core/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if e
 ```
 
 The target extension file path follows the naming convention:
-`core/config/extensions/{kebab-case-feature-id}.ts`
+`core/config/extensions/{kebab-case-system-or-action-id}.ts`
 
 ### Step 2: Scaffold the extension file
 
@@ -46,29 +47,29 @@ Create `core/config/extensions/{id}.ts` using the Write tool.
 
 The file shape depends on the extension type:
 
-**Custom feature (most common Level B case):**
+**Custom system/action extension (common Level B case):**
 
 ```typescript
 /**
- * {Feature label} feature extension.
+ * {System or action label} extension.
  * Registered in core/config/organization-model.ts.
  */
-import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
+import type { OrganizationModelSystem } from '@elevasis/core/organization-model'
 
-export const {FEATURE_CONST}: OrganizationModelFeature = {
-  id: '{feature-id}',
-  label: '{Feature Label}',
+export const {SYSTEM_CONST}: OrganizationModelSystem = {
+  id: '{system-or-action-id}',
+  label: '{System or Action Label}',
   description: '{optional description}',
   enabled: true,
   entityIds: [],
   surfaceIds: [],
   resourceIds: [],
-  capabilityIds: [],
+  actionIds: [],
 }
 ```
 
-Replace `{FEATURE_CONST}` with the SCREAMING_SNAKE_CASE version of the feature ID
-(e.g. `CLIENT_PORTAL_FEATURE`).
+Replace `{SYSTEM_CONST}` with the SCREAMING_SNAKE_CASE version of the system or action ID
+(e.g. `CLIENT_PORTAL_SYSTEM`).
 
 The caller provides the exact field values based on what the user confirmed.
 
@@ -77,20 +78,20 @@ The caller provides the exact field values based on what the user confirmed.
 Edit `core/config/organization-model.ts` to:
 
 1. Import the new constant from the extension file.
-2. Add it to the `features` array in the `defineOrganizationModel({...})` call.
+2. Add it to the appropriate `systems` or `actions` collection in the `defineOrganizationModel({...})` call.
 
 Example import addition:
 
 ```typescript
-import { CLIENT_PORTAL_FEATURE } from './extensions/client-portal'
+import { CLIENT_PORTAL_SYSTEM } from './extensions/client-portal'
 ```
 
-Example features array addition:
+Example system collection addition:
 
 ```typescript
-features: [
-  ...existingFeatures,
-  CLIENT_PORTAL_FEATURE,
+systems: [
+  ...existingSystems,
+  CLIENT_PORTAL_SYSTEM,
 ],
 ```
 
@@ -127,7 +128,7 @@ If Step 4 or Step 5 failed:
 If Steps 4 and 5 both passed, return a success signal to the caller with:
 
 - Extension file path created
-- Adapter wiring changes (import + features array entry)
+- Adapter wiring changes (import + systems/actions collection entry)
 - `Type-check: PASS`
 - `Schema validation: PASS`
 
@@ -141,7 +142,7 @@ Callers must provide before invoking this pipeline:
 
 - **Extension file path:** `core/config/extensions/{id}.ts`
 - **Extension file content:** the full TypeScript content for the new file
-- **Adapter changes:** the exact import line and features-array addition to write into the adapter
+- **Adapter changes:** the exact import line and systems/actions collection addition to write into the adapter
 - **Confirmed:** the user has already said yes to the proposed change and explicitly requested
   a new extension file
 
@@ -153,6 +154,6 @@ happen in the domain operation before this pipeline is invoked.
 ## Constraint: Extension files are Tier 3 (never synced)
 
 Files under `core/config/extensions/` are Tier 3 -- project-specific, never overwritten
-by `/external sync`. This means custom features and entity extensions survive template upgrades
+by `/external sync`. This means custom systems, actions, and entity extensions survive template upgrades
 automatically. Do not put platform-default overrides in extension files; those belong directly in
 `core/config/organization-model.ts` (Tier 2, merge-aware).

package/reference/claude-config/skills/knowledge/operations/features.md

@@ -1,113 +1,76 @@
-# Features domain
-
-The `features` domain controls top-level capability switches in the platform. Each entry in the
-`features` array of the OrganizationModel governs whether a feature's nav items, routes, and
-surfaces render. Disabling a feature hides it without removing it from the model; enabling makes
-it visible. Custom features extend the platform's defaults via a TypeScript extension file.
-
-## Schema
-
-Source: `@elevasis/core/organization-model` (published types) or
-`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` (generated shapes).
-
-```typescript
-FeatureSchema = z.object({
-  id:            ModelIdSchema,                // lowercase, e.g. "crm", "lead-gen", "seo"
-  label:         LabelSchema,                  // display label
-  description:   DescriptionSchema.optional(),
-  enabled:       z.boolean().default(true),
-  color:         ColorTokenSchema.optional(),
-  icon:          IconNameSchema.optional(),
-  entityIds:     ReferenceIdsSchema,
-  surfaceIds:    ReferenceIdsSchema,
-  resourceIds:   ReferenceIdsSchema,
-  capabilityIds: ReferenceIdsSchema,
-})
-```
+# Features Compatibility Notes
 
-Lives at: `core/config/organization-model.ts` under the `features` array of
-`defineOrganizationModel({...})`. The `features` array replaces entirely (no per-element merge), so
-the adapter must redeclare every feature it wants to override.
+`features` is legacy organization-model wording. Current Organization OS vocabulary is
+System/Action oriented:
 
-## Platform default feature IDs
+- **Systems** describe availability, routing, ownership, navigation grouping, and knowledge
+  mounts.
+- **Actions** describe invokable operations such as workflows, agents, commands, and UI-triggered
+  tasks.
 
-`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`
+Use this file only when older prompts, browser copy text, SDK references, or scaffold recipes still
+say "feature". For current tenant organization-model work, route the user to Systems and Actions
+wording and use `/by-system/<id>` knowledge paths.
 
-Source of truth: `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`. Use the
-typed feature constants from `@elevasis/core/organization-model` (`CRM_FEATURE_ID`,
-`LEAD_GEN_FEATURE_ID`, etc.) instead of magic strings when overriding.
+## Compatibility Mapping
 
-## Levels
+| Legacy wording                     | Current wording                                      |
+| ---------------------------------- | ---------------------------------------------------- |
+| Feature toggle                     | System availability or routing toggle                |
+| Feature ID                         | System ID when discussing Organization OS            |
+| Add a custom feature               | Add or extend a System, then define any Actions      |
+| Feature governs X                  | System governs X                                     |
+| `/knowledge read-folder feature:x` | `/knowledge read-folder system:x`                    |
+| `/by-feature/x`                    | `/by-system/x`                                       |
 
-Two levels of feature change, both gated by the codify ceremony:
+`by-feature` may still exist as a legacy compatibility axis in older tools. Do not introduce new
+guidance that depends on it; prefer `by-system` everywhere.
 
-- **Level A (config-only edit)** -- toggle `enabled`, adjust label/color/icon, or override
-  metadata on a feature that already exists in the platform defaults. No new TypeScript files. See
-  `operations/codify-level-a.md`.
+## What To Do With Toggle Requests
 
-- **Level B (new extension file)** -- introduce a custom feature ID that does not exist in the
-  platform defaults. Requires a new file under `core/config/extensions/` plus wiring it into the
-  adapter. Level B is reserved for explicit user requests. See `operations/codify-level-b.md`.
+For natural-language requests like "turn on lead gen", "disable SEO", or "enable CRM":
 
-## Validation rules
+1. Treat the request as a System availability/routing change.
+2. Read `core/config/organization-model.ts` and find the matching System entry or platform
+   default constant exposed by `@elevasis/core/organization-model`.
+3. Propose the exact availability/routing change in plain language.
+4. After confirmation, run the Level A codify ceremony in `operations/codify-level-a.md`.
 
-- `id` is lowercase, hyphens only (e.g. `client-portal`); enforces `ModelIdSchema`.
-- `label` is non-empty, max 120 characters.
-- The `features` array replaces entirely on override -- entries omitted from the adapter are
-  dropped, even if they appear in the platform defaults.
-- A new custom feature ID must not collide with any platform default ID.
+Do not create new extension files for a simple on/off change.
 
-## Realistic examples
+## When Level B Applies
 
-Toggle a default feature off:
+Level B applies only when the user explicitly asks for a new structural concept that cannot be
+represented as an existing System or Action configuration. In current vocabulary this usually
+means adding a project-owned extension under `core/config/extensions/` and wiring it into the
+organization model.
 
-```typescript
-defineOrganizationModel({
-  features: [
-    // ... redeclare every default feature you want to keep ...
-    { id: SEO_FEATURE_ID, label: 'SEO', enabled: false, /* ... */ },
-  ],
-})
-```
+Older references may call this "adding a custom feature"; translate it to "add or extend a
+System and define any Actions it owns" before invoking `operations/codify-level-b.md`.
 
-Add a custom feature (Level B):
-
-```typescript
-// core/config/extensions/client-portal.ts
-export const clientPortalFeature = {
-  id: 'client-portal',
-  label: 'Client Portal',
-  description: 'Self-serve project status for clients',
-  enabled: true,
-  entityIds: ['project', 'deliverable'],
-  surfaceIds: ['client-portal-dashboard'],
-  resourceIds: [],
-  capabilityIds: [],
-}
-
-// core/config/organization-model.ts
-import { clientPortalFeature } from './extensions/client-portal'
-defineOrganizationModel({
-  features: [
-    /* ... defaults you want to keep ... */
-    clientPortalFeature,
-  ],
-})
-```
+## UI Package Exception
+
+Keep the word `features` only for legacy frontend source paths that still use that directory
+name, such as `ui/src/features/`. Current published shell APIs are System-oriented:
+`SystemShell`, `SystemModule`, and `ElevasisSystemsProvider`.
 
-## Validation gate
+## Read Examples
 
-Every change must pass before codify completes:
+Use current system paths:
 
-1. `pnpm -C operations check-types` -- TypeScript compilation succeeds.
-2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
+```bash
+pnpm exec elevasis-sdk knowledge:ls /by-system/<id> --ids-only
+pnpm exec elevasis-sdk knowledge:cat <node-id>
+```
+
+Legacy browser output:
 
-On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` and
-`operations/codify-level-b.md` for the rollback procedure.
+```text
+/knowledge read-folder feature:<id>
+```
 
----
+Resolve as:
 
-> **Read via `/knowledge`** -- natural-language queries like "what features are enabled?" or
-> "is the SEO feature on?" route to this domain via the skill's intent classifier. To enable,
-> disable, or add a custom feature, the `/knowledge` skill triggers the codify ceremony when
-> intent classifies as Toggle or Codify.
+```bash
+pnpm exec elevasis-sdk knowledge:ls /by-system/<id> --ids-only
+```

package/reference/claude-config/skills/knowledge/operations/labels.md

@@ -1,7 +1,7 @@
 # Labels domain
 
-`label` is an inline display field carried by status entries, stage entries, feature entries, and
-navigation surfaces in the OrganizationModel. Labels control what users see in the UI and what
+`label` is an inline display field carried by status entries, stage entries, System entries,
+knowledge nodes, registry entries, and sidebar surfaces in the OrganizationModel. Labels control what users see in the UI and what
 agents say when narrating state. Editing a label does not change the entry's `id` or
 `semanticClass` -- only the human-readable display string. This is Level A only (config-only
 edits to `core/config/organization-model.ts`).
@@ -24,11 +24,16 @@ Each status entry shape:
 { id: 'new', label: 'New Lead', semanticClass: 'active', color: 'blue' }
 ```
 
-**Features.** The `label` field on a feature entry. Editing it changes sidebar nav text and any
-agent narration that references the feature by label.
+**Systems.** The `label` field on a System entry. Editing it changes agent narration and any
+System-derived shell text, but it does not change the System `id`, route path, or graph node id.
 
-**Navigation surfaces.** Surface entries in the `navigation.surfaces` array each carry a `label`.
-Editing changes breadcrumb text and nav item display.
+**Sidebar surfaces.** Routeable leaves under `navigation.sidebar.primary` and
+`navigation.sidebar.bottom` carry labels. Editing changes nav item and breadcrumb display without
+changing the route path or target System refs.
+
+**Knowledge/domain entries.** Knowledge nodes, customers, offerings, goals, roles, resources,
+actions, entities, and policies may carry labels or titles depending on the domain. Edit only the
+display field that already exists on the entry.
 
 ## What is NOT in scope
 
@@ -56,19 +61,19 @@ Domain: sales (deal pipeline)
   negotiation:   (unchanged)
 ```
 
-Rename a feature label without changing its ID:
+Rename a System label without changing its ID:
 
 ```
-features:
-  crm:           label "CRM"            -> "Sales Pipeline"
-  (id stays 'crm'; CRM_FEATURE_ID constant unchanged)
+systems:
+  sales.crm:     label "CRM"            -> "Sales Pipeline"
+  (id stays 'sales.crm'; graph node remains 'system:sales.crm')
 ```
 
-Rename a navigation surface:
+Rename a sidebar surface:
 
 ```
-navigation.surfaces:
-  crm-pipeline:  label "Pipeline"       -> "Deal Pipeline"
+navigation.sidebar.primary:
+  sales.crm:     label "Pipeline"       -> "Deal Pipeline"
 ```
 
 ## Validation gate
@@ -84,6 +89,6 @@ procedure.
 ---
 
 > **Read via `/knowledge`** -- natural-language queries like "what's the label for the proposal
-> stage?" or "what do we call the SEO feature?" route to this domain via the skill's intent
+> stage?" or "what do we call the SEO System?" route to this domain via the skill's intent
 > classifier. To rename one or more labels, the `/knowledge` skill triggers the codify ceremony
 > when intent classifies as Codify.

package/reference/claude-config/skills/knowledge/operations/offerings.md

@@ -21,7 +21,7 @@ ProductSchema = z.object({
   price:             z.number().min(0).default(0),            // base price amount (>= 0)
   currency:          z.string().trim().max(10).default('USD'),// ISO 4217, e.g. "USD", "EUR"
   targetSegmentIds:  z.array(z.string()).default([]),         // must ref customers.segments[].id
-  deliveryFeatureId: z.string().optional()                    // optional ref to features[].id
+  deliverySystemId: z.string().optional()                     // optional ref to systems[].id
 })
 ```
 
@@ -43,7 +43,7 @@ ProductSchema = z.object({
 | `price`             | number   | --   | Base price amount, min 0; use 0 for fully custom pricing |
 | `currency`          | string   | 10   | ISO 4217 code; defaults to `"USD"`                       |
 | `targetSegmentIds`  | string[] | --   | Each entry must reference a `customers.segments[].id`    |
-| `deliveryFeatureId` | string   | --   | Optional reference to a `features[].id`                  |
+| `deliverySystemId`  | string   | --   | Optional reference to a `systems[].id`                   |
 
 ## Validation rules
 
@@ -51,7 +51,7 @@ ProductSchema = z.object({
   references
 - `targetSegmentIds` entries must exist in `customers.segments[].id`; the schema enforces this
   at parse time — missing references cause `resolveOrganizationModel()` to fail
-- `deliveryFeatureId` (when present) must exist in `features[].id`; same parse-time enforcement
+- `deliverySystemId` (when present) must exist in `systems[].id`; same parse-time enforcement
 - `price` must be >= 0; use 0 when pricing is fully custom or not yet set
 - `currency` must be a valid ISO 4217 code by convention (the schema only validates length)
 - Cross-reference: if a product is removed, surface any `targetSegmentIds` in other products
@@ -70,7 +70,7 @@ offerings: {
       price:            2500,
       currency:         "USD",
       targetSegmentIds: ["segment-smb-agencies"],
-      deliveryFeatureId: undefined
+      deliverySystemId: undefined
     },
     {
       id:               "product-one-time-audit",
@@ -80,7 +80,7 @@ offerings: {
       price:            1500,
       currency:         "USD",
       targetSegmentIds: ["segment-smb-agencies"],
-      deliveryFeatureId: undefined
+      deliverySystemId: undefined
     }
   ]
 }
@@ -99,7 +99,7 @@ use `pnpm exec elevasis-sdk knowledge:cat offerings` (external project).
 To add, edit, or remove a product, the `/knowledge` skill runs the codify ceremony
 (`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
 rollback on failure. Only the `products` array is written; no other keys in the adapter are
-touched. Before writing, the skill verifies all `targetSegmentIds` and `deliveryFeatureId`
+touched. Before writing, the skill verifies all `targetSegmentIds` and `deliverySystemId`
 references resolve. When adding, append to the array. When editing, replace by `id`. When
 removing, filter out — and surface any dangling references first.