@elevasis/sdk 1.20.2 → 1.22.0

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

@@ -1,93 +1,93 @@
-# Identity domain
-
-The `identity` domain captures the organization's legal identity, purpose, and operational anchors.
-It is distinct from `branding` (display identity: logos, product names) — editing identity fields
-here does not touch any visual or branding configuration.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/identity.ts`
-
-```typescript
-IdentityDomainSchema = z.object({
-  mission:          z.string().trim().max(1000).default(''),
-  vision:           z.string().trim().max(1000).default(''),
-  legalName:        z.string().trim().max(200).default(''),
-  entityType:       z.string().trim().max(100).default(''),    // e.g. "LLC", "Corporation"
-  jurisdiction:     z.string().trim().max(200).default(''),    // e.g. "United States – Delaware"
-  industryCategory: z.string().trim().max(200).default(''),    // e.g. "Marketing Agency"
-  geographicFocus:  z.string().trim().max(200).default(''),    // e.g. "North America"
-  timeZone:         z.string().trim().max(100).default('UTC'), // IANA identifier
-  businessHours:    BusinessHoursSchema                        // per-day { open, close } in HH:MM
-})
-```
-
-`BusinessHoursSchema` is an object with optional keys `monday` through `sunday`, each holding
-`{ open: "HH:MM", close: "HH:MM" }`. An empty object `{}` means not configured.
-
-## Field reference
-
-| Field              | Type   | Max  | Notes                                                    |
-| ------------------ | ------ | ---- | -------------------------------------------------------- |
-| `mission`          | string | 1000 | Why the organization exists                              |
-| `vision`           | string | 1000 | Where the organization is headed long-term               |
-| `legalName`        | string | 200  | Registered legal name                                    |
-| `entityType`       | string | 100  | e.g. "LLC", "Corporation", "Sole Proprietor"             |
-| `jurisdiction`     | string | 200  | e.g. "United States – Delaware", "Canada – Ontario"      |
-| `industryCategory` | string | 200  | e.g. "Marketing Agency", "SaaS", "Professional Services" |
-| `geographicFocus`  | string | 200  | e.g. "North America", "Global", "Southeast Asia"         |
-| `timeZone`         | string | 100  | IANA identifier, e.g. `America/Los_Angeles`              |
-| `businessHours`    | object | --   | Per-day `{ open: "HH:MM", close: "HH:MM" }`              |
-
-## Validation rules
-
-- All string fields default to empty string `''`; none are required to be non-empty at schema level
-- `timeZone` defaults to `"UTC"` when not set; agents should treat a value of `"UTC"` as
-  potentially unconfigured and surface it for review
-- `businessHours` defaults to `{}` (not configured); an empty object is valid
-- Per-day entries must follow `"HH:MM"` 24-hour format; the schema does not enforce range bounds
-  but convention is `00:00`–`23:59`
-- `jurisdiction` should use the format `"Country – Region"` (em dash, not hyphen) for
-  consistency across agents that parse it
-
-## Examples
-
-```typescript
-identity: {
-  mission:          "We help SMBs automate complex operations using AI.",
-  vision:           "A world where every business operates at the efficiency of a Fortune 500.",
-  legalName:        "Acme Operations LLC",
-  entityType:       "LLC",
-  jurisdiction:     "United States – Delaware",
-  industryCategory: "AI Automation / Professional Services",
-  geographicFocus:  "North America",
-  timeZone:         "America/Chicago",
-  businessHours: {
-    monday:    { open: "09:00", close: "17:00" },
-    tuesday:   { open: "09:00", close: "17:00" },
-    wednesday: { open: "09:00", close: "17:00" },
-    thursday:  { open: "09:00", close: "17:00" },
-    friday:    { open: "09:00", close: "17:00" }
-  }
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `identity` key of
-`defineOrganizationModel({...})`.
-
-To read the current values: open the adapter file and inspect the `identity` block directly, or
-use `pnpm exec elevasis-sdk knowledge:cat identity` (external project).
-
-## Write path
-
-To edit any field, the `/knowledge` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Only the confirmed fields are written; no other top-level keys in the adapter
-are touched.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "what's our identity set to?" or
-"what timezone are we in?" route to this domain via the skill's intent classifier.
+# Identity domain
+
+The `identity` domain captures the organization's legal identity, purpose, and operational anchors.
+It is distinct from `branding` (display identity: logos, product names) — editing identity fields
+here does not touch any visual or branding configuration.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/identity.ts`
+
+```typescript
+IdentityDomainSchema = z.object({
+  mission:          z.string().trim().max(1000).default(''),
+  vision:           z.string().trim().max(1000).default(''),
+  legalName:        z.string().trim().max(200).default(''),
+  entityType:       z.string().trim().max(100).default(''),    // e.g. "LLC", "Corporation"
+  jurisdiction:     z.string().trim().max(200).default(''),    // e.g. "United States – Delaware"
+  industryCategory: z.string().trim().max(200).default(''),    // e.g. "Marketing Agency"
+  geographicFocus:  z.string().trim().max(200).default(''),    // e.g. "North America"
+  timeZone:         z.string().trim().max(100).default('UTC'), // IANA identifier
+  businessHours:    BusinessHoursSchema                        // per-day { open, close } in HH:MM
+})
+```
+
+`BusinessHoursSchema` is an object with optional keys `monday` through `sunday`, each holding
+`{ open: "HH:MM", close: "HH:MM" }`. An empty object `{}` means not configured.
+
+## Field reference
+
+| Field              | Type   | Max  | Notes                                                    |
+| ------------------ | ------ | ---- | -------------------------------------------------------- |
+| `mission`          | string | 1000 | Why the organization exists                              |
+| `vision`           | string | 1000 | Where the organization is headed long-term               |
+| `legalName`        | string | 200  | Registered legal name                                    |
+| `entityType`       | string | 100  | e.g. "LLC", "Corporation", "Sole Proprietor"             |
+| `jurisdiction`     | string | 200  | e.g. "United States – Delaware", "Canada – Ontario"      |
+| `industryCategory` | string | 200  | e.g. "Marketing Agency", "SaaS", "Professional Services" |
+| `geographicFocus`  | string | 200  | e.g. "North America", "Global", "Southeast Asia"         |
+| `timeZone`         | string | 100  | IANA identifier, e.g. `America/Los_Angeles`              |
+| `businessHours`    | object | --   | Per-day `{ open: "HH:MM", close: "HH:MM" }`              |
+
+## Validation rules
+
+- All string fields default to empty string `''`; none are required to be non-empty at schema level
+- `timeZone` defaults to `"UTC"` when not set; agents should treat a value of `"UTC"` as
+  potentially unconfigured and surface it for review
+- `businessHours` defaults to `{}` (not configured); an empty object is valid
+- Per-day entries must follow `"HH:MM"` 24-hour format; the schema does not enforce range bounds
+  but convention is `00:00`–`23:59`
+- `jurisdiction` should use the format `"Country – Region"` (em dash, not hyphen) for
+  consistency across agents that parse it
+
+## Examples
+
+```typescript
+identity: {
+  mission:          "We help SMBs automate complex operations using AI.",
+  vision:           "A world where every business operates at the efficiency of a Fortune 500.",
+  legalName:        "Acme Operations LLC",
+  entityType:       "LLC",
+  jurisdiction:     "United States – Delaware",
+  industryCategory: "AI Automation / Professional Services",
+  geographicFocus:  "North America",
+  timeZone:         "America/Chicago",
+  businessHours: {
+    monday:    { open: "09:00", close: "17:00" },
+    tuesday:   { open: "09:00", close: "17:00" },
+    wednesday: { open: "09:00", close: "17:00" },
+    thursday:  { open: "09:00", close: "17:00" },
+    friday:    { open: "09:00", close: "17:00" }
+  }
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `identity` key of
+`defineOrganizationModel({...})`.
+
+To read the current values: open the adapter file and inspect the `identity` block directly, or
+use `pnpm exec elevasis-sdk knowledge:cat identity` (external project).
+
+## Write path
+
+To edit any field, the `/knowledge` skill runs the codify ceremony
+(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
+rollback on failure. Only the confirmed fields are written; no other top-level keys in the adapter
+are touched.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "what's our identity set to?" or
+"what timezone are we in?" route to this domain via the skill's intent classifier.

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

@@ -1,89 +1,94 @@
-# 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
-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`).
-
-## What carries labels
-
-The following model elements have editable inline `label` fields:
-
-**Status / stage entries.** Each domain that carries an enum-like array exposes per-entry labels:
-
-- `sales.statuses` -- deal pipeline stages.
-- `prospecting.statuses` -- lead lifecycle stages.
-- `projects.statuses` -- project and task stages.
-
-Source of platform defaults: `packages/core/src/organization-model/domains/{sales,prospecting,projects}.ts`.
-
-Each status entry shape:
-
-```typescript
-{ 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.
-
-**Navigation surfaces.** Surface entries in the `navigation.surfaces` array each carry a `label`.
-Editing changes breadcrumb text and nav item display.
-
-## What is NOT in scope
-
-`id` and `semanticClass` of any entry must never change in a label edit -- they are structural
-anchors used by code, hooks, and workflow adapters. Only `label` (and optionally `color` or
-`icon`) are in scope. To rename an `id`, escalate to a separate Level B refactor with explicit
-confirmation, because every consumer that references the old `id` must be updated in the same
-change.
-
-## Validation rules
-
-- `label` is non-empty, max 120 characters.
-- `id` and `semanticClass` are unchanged from the previous state.
-- Entries not being edited remain byte-identical in the output -- partial array rewrites are
-  preferred over wholesale array replacement to minimize diff surface.
-
-## Realistic examples
-
-Rename two sales statuses:
-
-```
-Domain: sales (deal pipeline)
-  new:           "New Lead"        -> "Inbound Lead"
-  proposal:      "Proposal Sent"   -> "Proposal Out"
-  negotiation:   (unchanged)
-```
-
-Rename a feature label without changing its ID:
-
-```
-features:
-  crm:           label "CRM"            -> "Sales Pipeline"
-  (id stays 'crm'; CRM_FEATURE_ID constant unchanged)
-```
-
-Rename a navigation surface:
-
-```
-navigation.surfaces:
-  crm-pipeline:  label "Pipeline"       -> "Deal Pipeline"
-```
-
-## Validation gate
-
-Every label change must pass before codify completes:
-
-1. `pnpm -C operations check-types`.
-2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
-
-On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` for the rollback
-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
-> classifier. To rename one or more labels, the `/knowledge` skill triggers the codify ceremony
-> when intent classifies as Codify.
+# Labels domain
+
+`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`).
+
+## What carries labels
+
+The following model elements have editable inline `label` fields:
+
+**Status / stage entries.** Each domain that carries an enum-like array exposes per-entry labels:
+
+- `sales.statuses` -- deal pipeline stages.
+- `prospecting.statuses` -- lead lifecycle stages.
+- `projects.statuses` -- project and task stages.
+
+Source of platform defaults: `packages/core/src/organization-model/domains/{sales,prospecting,projects}.ts`.
+
+Each status entry shape:
+
+```typescript
+{ id: 'new', label: 'New Lead', semanticClass: 'active', color: 'blue' }
+```
+
+**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.
+
+**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
+
+`id` and `semanticClass` of any entry must never change in a label edit -- they are structural
+anchors used by code, hooks, and workflow adapters. Only `label` (and optionally `color` or
+`icon`) are in scope. To rename an `id`, escalate to a separate Level B refactor with explicit
+confirmation, because every consumer that references the old `id` must be updated in the same
+change.
+
+## Validation rules
+
+- `label` is non-empty, max 120 characters.
+- `id` and `semanticClass` are unchanged from the previous state.
+- Entries not being edited remain byte-identical in the output -- partial array rewrites are
+  preferred over wholesale array replacement to minimize diff surface.
+
+## Realistic examples
+
+Rename two sales statuses:
+
+```
+Domain: sales (deal pipeline)
+  new:           "New Lead"        -> "Inbound Lead"
+  proposal:      "Proposal Sent"   -> "Proposal Out"
+  negotiation:   (unchanged)
+```
+
+Rename a System label without changing its ID:
+
+```
+systems:
+  sales.crm:     label "CRM"            -> "Sales Pipeline"
+  (id stays 'sales.crm'; graph node remains 'system:sales.crm')
+```
+
+Rename a sidebar surface:
+
+```
+navigation.sidebar.primary:
+  sales.crm:     label "Pipeline"       -> "Deal Pipeline"
+```
+
+## Validation gate
+
+Every label change must pass before codify completes:
+
+1. `pnpm -C operations check-types`.
+2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
+
+On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` for the rollback
+procedure.
+
+---
+
+> **Read via `/knowledge`** -- natural-language queries like "what's the label for the proposal
+> 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

@@ -1,109 +1,109 @@
-# Offerings domain
-
-The `offerings` domain describes what the organization sells or delivers — a catalog of products
-and services modeled after the Business Model Canvas "Value Propositions". Agents use offerings
-for quoting, proposal generation, and scope-of-work reasoning.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/offerings.ts`
-
-```typescript
-OfferingsDomainSchema = z.object({
-  products: z.array(ProductSchema).default([])
-})
-
-ProductSchema = z.object({
-  id:                z.string().trim().min(1).max(100),       // stable ID, e.g. "product-starter-plan"
-  name:              z.string().trim().max(200).default(''),  // display name
-  description:       z.string().trim().max(2000).default(''), // what it delivers
-  pricingModel:      PricingModelSchema.default('custom'),    // 'one-time' | 'subscription' | 'usage-based' | 'custom'
-  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
-})
-```
-
-`pricingModel` values:
-
-- `one-time` -- single purchase (setup fee, project fee)
-- `subscription` -- recurring (monthly/annual SaaS, retainer)
-- `usage-based` -- metered by consumption (API calls, seats)
-- `custom` -- negotiated or bespoke pricing
-
-## Field reference
-
-| Field               | Type     | Max  | Notes                                                    |
-| ------------------- | -------- | ---- | -------------------------------------------------------- |
-| `id`                | string   | 100  | Stable key, min 1 char; e.g. `"product-starter-plan"`    |
-| `name`              | string   | 200  | Display name                                             |
-| `description`       | string   | 2000 | What this product or service delivers                    |
-| `pricingModel`      | enum     | --   | `one-time`, `subscription`, `usage-based`, or `custom`   |
-| `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`                  |
-
-## Validation rules
-
-- `id` is the stable key; changing it after creation is a breaking change for any downstream
-  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
-- `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
-  that reference the removed ID
-
-## Examples
-
-```typescript
-offerings: {
-  products: [
-    {
-      id:               "product-full-service-retainer",
-      name:             "Full-Service Retainer",
-      description:      "End-to-end campaign delivery, reporting, and optimization for SMB clients.",
-      pricingModel:     "subscription",
-      price:            2500,
-      currency:         "USD",
-      targetSegmentIds: ["segment-smb-agencies"],
-      deliveryFeatureId: undefined
-    },
-    {
-      id:               "product-one-time-audit",
-      name:             "One-Time Operations Audit",
-      description:      "Single-engagement review of current workflows with a remediation roadmap.",
-      pricingModel:     "one-time",
-      price:            1500,
-      currency:         "USD",
-      targetSegmentIds: ["segment-smb-agencies"],
-      deliveryFeatureId: undefined
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `offerings` key of
-`defineOrganizationModel({...})`.
-
-To read current products: open the adapter file and inspect the `offerings.products` array, or
-use `pnpm exec elevasis-sdk knowledge:cat offerings` (external project).
-
-## Write path
-
-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`
-references resolve. When adding, append to the array. When editing, replace by `id`. When
-removing, filter out — and surface any dangling references first.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "what do we sell?" or "what's the
-pricing on the retainer?" route to this domain via the skill's intent classifier.
+# Offerings domain
+
+The `offerings` domain describes what the organization sells or delivers — a catalog of products
+and services modeled after the Business Model Canvas "Value Propositions". Agents use offerings
+for quoting, proposal generation, and scope-of-work reasoning.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/offerings.ts`
+
+```typescript
+OfferingsDomainSchema = z.object({
+  products: z.array(ProductSchema).default([])
+})
+
+ProductSchema = z.object({
+  id:                z.string().trim().min(1).max(100),       // stable ID, e.g. "product-starter-plan"
+  name:              z.string().trim().max(200).default(''),  // display name
+  description:       z.string().trim().max(2000).default(''), // what it delivers
+  pricingModel:      PricingModelSchema.default('custom'),    // 'one-time' | 'subscription' | 'usage-based' | 'custom'
+  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
+  deliverySystemId: z.string().optional()                     // optional ref to systems[].id
+})
+```
+
+`pricingModel` values:
+
+- `one-time` -- single purchase (setup fee, project fee)
+- `subscription` -- recurring (monthly/annual SaaS, retainer)
+- `usage-based` -- metered by consumption (API calls, seats)
+- `custom` -- negotiated or bespoke pricing
+
+## Field reference
+
+| Field               | Type     | Max  | Notes                                                    |
+| ------------------- | -------- | ---- | -------------------------------------------------------- |
+| `id`                | string   | 100  | Stable key, min 1 char; e.g. `"product-starter-plan"`    |
+| `name`              | string   | 200  | Display name                                             |
+| `description`       | string   | 2000 | What this product or service delivers                    |
+| `pricingModel`      | enum     | --   | `one-time`, `subscription`, `usage-based`, or `custom`   |
+| `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`    |
+| `deliverySystemId`  | string   | --   | Optional reference to a `systems[].id`                   |
+
+## Validation rules
+
+- `id` is the stable key; changing it after creation is a breaking change for any downstream
+  references
+- `targetSegmentIds` entries must exist in `customers.segments[].id`; the schema enforces this
+  at parse time — missing references cause `resolveOrganizationModel()` to fail
+- `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
+  that reference the removed ID
+
+## Examples
+
+```typescript
+offerings: {
+  products: [
+    {
+      id:               "product-full-service-retainer",
+      name:             "Full-Service Retainer",
+      description:      "End-to-end campaign delivery, reporting, and optimization for SMB clients.",
+      pricingModel:     "subscription",
+      price:            2500,
+      currency:         "USD",
+      targetSegmentIds: ["segment-smb-agencies"],
+      deliverySystemId: undefined
+    },
+    {
+      id:               "product-one-time-audit",
+      name:             "One-Time Operations Audit",
+      description:      "Single-engagement review of current workflows with a remediation roadmap.",
+      pricingModel:     "one-time",
+      price:            1500,
+      currency:         "USD",
+      targetSegmentIds: ["segment-smb-agencies"],
+      deliverySystemId: undefined
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `offerings` key of
+`defineOrganizationModel({...})`.
+
+To read current products: open the adapter file and inspect the `offerings.products` array, or
+use `pnpm exec elevasis-sdk knowledge:cat offerings` (external project).
+
+## Write path
+
+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 `deliverySystemId`
+references resolve. When adding, append to the array. When editing, replace by `id`. When
+removing, filter out — and surface any dangling references first.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "what do we sell?" or "what's the
+pricing on the retainer?" route to this domain via the skill's intent classifier.