@elevasis/sdk 1.20.2 → 1.22.0

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

@@ -1,109 +1,109 @@
-# Customers domain
-
-The `customers` domain describes who the organization serves — distinct buyer archetypes modeled
-after the Value Proposition Canvas (BMC / VPC). Each segment captures jobs-to-be-done, pains,
-gains, firmographics, and a value proposition. Agents use these segments for targeting, outreach
-context, and personalization.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/customers.ts`
-
-```typescript
-CustomersDomainSchema = z.object({
-  segments: z.array(CustomerSegmentSchema).default([])
-})
-
-CustomerSegmentSchema = z.object({
-  id:           z.string().trim().min(1).max(100),             // stable ID, e.g. "segment-smb-agencies"
-  name:         z.string().trim().max(200).default(''),        // display name
-  description:  z.string().trim().max(2000).default(''),       // who this segment is
-  jobsToBeDone: z.string().trim().max(2000).default(''),       // the goal they hire you to accomplish
-  pains:        z.array(z.string().trim().max(500)).default([]),
-  gains:        z.array(z.string().trim().max(500)).default([]),
-  firmographics: FirmographicsSchema.default({}),              // industry, companySize, region
-  valueProp:    z.string().trim().max(2000).default('')        // why your offering fits this segment
-})
-
-FirmographicsSchema = z.object({
-  industry:    z.string().trim().max(200).optional(),  // e.g. "Marketing Agency"
-  companySize: z.string().trim().max(100).optional(),  // e.g. "11–50"
-  region:      z.string().trim().max(200).optional()   // e.g. "North America"
-})
-```
-
-## Field reference
-
-| Field           | Type     | Max  | Notes                                                        |
-| --------------- | -------- | ---- | ------------------------------------------------------------ |
-| `id`            | string   | 100  | Stable key, min 1 char; e.g. `"segment-smb-agencies"`        |
-| `name`          | string   | 200  | Display name                                                 |
-| `description`   | string   | 2000 | Who this segment is in one or two sentences                  |
-| `jobsToBeDone`  | string   | 2000 | The goal they hire you to accomplish, in their terms         |
-| `pains`         | string[] | 500  | Each item: a frustration or obstacle                         |
-| `gains`         | string[] | 500  | Each item: an outcome or benefit they hope for               |
-| `firmographics` | object   | --   | Optional industry, companySize, region filters for targeting |
-| `valueProp`     | string   | 2000 | Why your offering uniquely addresses this segment's needs    |
-
-## Validation rules
-
-- `id` is the stable key used by `offerings.products[].targetSegmentIds` references; once set,
-  changing the `id` of a segment breaks any offering that references it
-- `firmographics` is optional; all three sub-fields (`industry`, `companySize`, `region`) are
-  individually optional
-- `pains` and `gains` default to empty arrays; agents should treat an empty array as unconfigured
-- There is no uniqueness constraint enforced by the schema on `id`, but agents must treat it as
-  unique and surface duplicates if found
-- Cross-reference: if a segment is removed, any `offerings.products[].targetSegmentIds` that
-  reference its `id` become dangling references; surface a warning before removing
-
-## Examples
-
-```typescript
-customers: {
-  segments: [
-    {
-      id:           "segment-smb-agencies",
-      name:         "SMB Marketing Agencies",
-      description:  "Owner-operated agencies with 1–15 employees running campaign delivery for SMB clients.",
-      jobsToBeDone: "Deliver consistent client results without adding headcount.",
-      pains: [
-        "Manual campaign QA eats time",
-        "Client reporting takes hours each week",
-        "Hard to scale without hiring"
-      ],
-      gains: [
-        "More client capacity without more staff",
-        "Predictable delivery timelines"
-      ],
-      firmographics: {
-        industry:    "Marketing Agency",
-        companySize: "1–15",
-        region:      "North America"
-      },
-      valueProp: "Automates the repetitive delivery and reporting work so agencies can take on more clients."
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `customers` key of
-`defineOrganizationModel({...})`.
-
-To read current segments: open the adapter file and inspect the `customers.segments` array, or
-use `pnpm exec elevasis-sdk knowledge:cat customers` (external project).
-
-## Write path
-
-To add, edit, or remove a segment, the `/knowledge` skill runs the codify ceremony
-(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
-rollback on failure. Only the `segments` array is written; no other keys in the adapter are
-touched. When adding, append to the array. When editing, replace the matching entry by `id`.
-When removing, filter it out — and surface any dangling `targetSegmentIds` references first.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "who are our customer segments?" or
-"what pains does the agency segment have?" route to this domain via the skill's intent classifier.
+# Customers domain
+
+The `customers` domain describes who the organization serves — distinct buyer archetypes modeled
+after the Value Proposition Canvas (BMC / VPC). Each segment captures jobs-to-be-done, pains,
+gains, firmographics, and a value proposition. Agents use these segments for targeting, outreach
+context, and personalization.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/customers.ts`
+
+```typescript
+CustomersDomainSchema = z.object({
+  segments: z.array(CustomerSegmentSchema).default([])
+})
+
+CustomerSegmentSchema = z.object({
+  id:           z.string().trim().min(1).max(100),             // stable ID, e.g. "segment-smb-agencies"
+  name:         z.string().trim().max(200).default(''),        // display name
+  description:  z.string().trim().max(2000).default(''),       // who this segment is
+  jobsToBeDone: z.string().trim().max(2000).default(''),       // the goal they hire you to accomplish
+  pains:        z.array(z.string().trim().max(500)).default([]),
+  gains:        z.array(z.string().trim().max(500)).default([]),
+  firmographics: FirmographicsSchema.default({}),              // industry, companySize, region
+  valueProp:    z.string().trim().max(2000).default('')        // why your offering fits this segment
+})
+
+FirmographicsSchema = z.object({
+  industry:    z.string().trim().max(200).optional(),  // e.g. "Marketing Agency"
+  companySize: z.string().trim().max(100).optional(),  // e.g. "11–50"
+  region:      z.string().trim().max(200).optional()   // e.g. "North America"
+})
+```
+
+## Field reference
+
+| Field           | Type     | Max  | Notes                                                        |
+| --------------- | -------- | ---- | ------------------------------------------------------------ |
+| `id`            | string   | 100  | Stable key, min 1 char; e.g. `"segment-smb-agencies"`        |
+| `name`          | string   | 200  | Display name                                                 |
+| `description`   | string   | 2000 | Who this segment is in one or two sentences                  |
+| `jobsToBeDone`  | string   | 2000 | The goal they hire you to accomplish, in their terms         |
+| `pains`         | string[] | 500  | Each item: a frustration or obstacle                         |
+| `gains`         | string[] | 500  | Each item: an outcome or benefit they hope for               |
+| `firmographics` | object   | --   | Optional industry, companySize, region filters for targeting |
+| `valueProp`     | string   | 2000 | Why your offering uniquely addresses this segment's needs    |
+
+## Validation rules
+
+- `id` is the stable key used by `offerings.products[].targetSegmentIds` references; once set,
+  changing the `id` of a segment breaks any offering that references it
+- `firmographics` is optional; all three sub-fields (`industry`, `companySize`, `region`) are
+  individually optional
+- `pains` and `gains` default to empty arrays; agents should treat an empty array as unconfigured
+- There is no uniqueness constraint enforced by the schema on `id`, but agents must treat it as
+  unique and surface duplicates if found
+- Cross-reference: if a segment is removed, any `offerings.products[].targetSegmentIds` that
+  reference its `id` become dangling references; surface a warning before removing
+
+## Examples
+
+```typescript
+customers: {
+  segments: [
+    {
+      id:           "segment-smb-agencies",
+      name:         "SMB Marketing Agencies",
+      description:  "Owner-operated agencies with 1–15 employees running campaign delivery for SMB clients.",
+      jobsToBeDone: "Deliver consistent client results without adding headcount.",
+      pains: [
+        "Manual campaign QA eats time",
+        "Client reporting takes hours each week",
+        "Hard to scale without hiring"
+      ],
+      gains: [
+        "More client capacity without more staff",
+        "Predictable delivery timelines"
+      ],
+      firmographics: {
+        industry:    "Marketing Agency",
+        companySize: "1–15",
+        region:      "North America"
+      },
+      valueProp: "Automates the repetitive delivery and reporting work so agencies can take on more clients."
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `customers` key of
+`defineOrganizationModel({...})`.
+
+To read current segments: open the adapter file and inspect the `customers.segments` array, or
+use `pnpm exec elevasis-sdk knowledge:cat customers` (external project).
+
+## Write path
+
+To add, edit, or remove a segment, the `/knowledge` skill runs the codify ceremony
+(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
+rollback on failure. Only the `segments` array is written; no other keys in the adapter are
+touched. When adding, append to the array. When editing, replace the matching entry by `id`.
+When removing, filter it out — and surface any dangling `targetSegmentIds` references first.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "who are our customer segments?" or
+"what pains does the agency segment have?" route to this domain via the skill's intent classifier.

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,
-})
-```
-
-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.
-
-## Platform default feature IDs
-
-`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`
-
-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.
-
-## Levels
-
-Two levels of feature change, both gated by the codify ceremony:
-
-- **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`.
-
-- **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`.
-
-## Validation rules
-
-- `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.
-
-## Realistic examples
-
-Toggle a default feature off:
-
-```typescript
-defineOrganizationModel({
-  features: [
-    // ... redeclare every default feature you want to keep ...
-    { id: SEO_FEATURE_ID, label: 'SEO', enabled: false, /* ... */ },
-  ],
-})
-```
-
-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,
-  ],
-})
-```
-
-## Validation gate
-
-Every change must pass before codify completes:
-
-1. `pnpm -C operations check-types` -- TypeScript compilation succeeds.
-2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result.
-
-On failure, the codify ceremony rolls back. See `operations/codify-level-a.md` and
-`operations/codify-level-b.md` for the rollback procedure.
-
----
-
-> **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.
+# Features Compatibility Notes
+
+`features` is legacy organization-model wording. Current Organization OS vocabulary is
+System/Action oriented:
+
+- **Systems** describe availability, routing, ownership, navigation grouping, and knowledge
+  mounts.
+- **Actions** describe invokable operations such as workflows, agents, commands, and UI-triggered
+  tasks.
+
+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.
+
+## Compatibility Mapping
+
+| 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`                                       |
+
+`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.
+
+## What To Do With Toggle Requests
+
+For natural-language requests like "turn on lead gen", "disable SEO", or "enable CRM":
+
+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`.
+
+Do not create new extension files for a simple on/off change.
+
+## When Level B Applies
+
+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.
+
+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`.
+
+## 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`.
+
+## Read Examples
+
+Use current system paths:
+
+```bash
+pnpm exec elevasis-sdk knowledge:ls /by-system/<id> --ids-only
+pnpm exec elevasis-sdk knowledge:cat <node-id>
+```
+
+Legacy browser output:
+
+```text
+/knowledge read-folder feature:<id>
+```
+
+Resolve as:
+
+```bash
+pnpm exec elevasis-sdk knowledge:ls /by-system/<id> --ids-only
+```

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

@@ -1,118 +1,118 @@
-# Goals domain
-
-The `goals` domain captures what the organization is working toward — time-bounded goals with
-measurable outcomes. The schema shape is OKR-inspired (objectives + key results) but all
-user-facing language must say "goals" and "measurable outcomes". Never say "OKR", "objective",
-or "key result" to the user.
-
-Agents use this domain for quarterly planning, priority routing, and understanding which outcomes
-matter most right now.
-
-## Schema
-
-Source: `packages/core/src/organization-model/domains/goals.ts`
-
-```typescript
-GoalsDomainSchema = z.object({
-  objectives: z.array(ObjectiveSchema).default([])
-})
-
-ObjectiveSchema = z.object({
-  id:          z.string().trim().min(1).max(100),   // stable ID, e.g. "goal-grow-arr-q1-2026"
-  description: z.string().trim().min(1).max(1000),  // plain-language goal statement
-  periodStart: z.string().regex(ISO_DATE),          // YYYY-MM-DD — must be before periodEnd
-  periodEnd:   z.string().regex(ISO_DATE),          // YYYY-MM-DD — enforced in superRefine
-  keyResults:  z.array(KeyResultSchema).default([]) // measurable outcomes under this goal
-})
-
-KeyResultSchema = z.object({
-  id:           z.string().trim().min(1).max(100),  // e.g. "kr-revenue-q1"
-  description:  z.string().trim().min(1).max(500),  // e.g. "Increase trial-to-paid conversion"
-  targetMetric: z.string().trim().min(1).max(200),  // what is being measured, e.g. "monthly revenue"
-  currentValue: z.number().default(0),              // current tracked value
-  targetValue:  z.number().optional()               // target to hit (omit if directional)
-})
-```
-
-## Field reference
-
-| Field         | Type          | Notes                                                      |
-| ------------- | ------------- | ---------------------------------------------------------- |
-| `id`          | string (100)  | Stable key; e.g. `"goal-grow-arr-q1-2026"`                 |
-| `description` | string (1000) | Plain-language goal statement; min 1 char required         |
-| `periodStart` | string        | ISO date `YYYY-MM-DD`; must be strictly before `periodEnd` |
-| `periodEnd`   | string        | ISO date `YYYY-MM-DD`; enforced by `superRefine`           |
-| `keyResults`  | array         | Measurable outcomes under this goal; defaults to `[]`      |
-
-Key result fields:
-
-| Field          | Type         | Notes                                               |
-| -------------- | ------------ | --------------------------------------------------- |
-| `id`           | string (100) | Stable key; e.g. `"kr-revenue-q1"`                  |
-| `description`  | string (500) | What is being tracked; min 1 char required          |
-| `targetMetric` | string (200) | The metric name; e.g. `"monthly recurring revenue"` |
-| `currentValue` | number       | Current value; defaults to `0`                      |
-| `targetValue`  | number       | Optional target; omit if the outcome is directional |
-
-## Validation rules
-
-- `periodEnd` must be strictly after `periodStart`; enforced at parse time by
-  `OrganizationModelSchema.superRefine()`; setting equal dates is also invalid
-- Both `periodStart` and `periodEnd` must match `YYYY-MM-DD` ISO date format exactly
-- The internal field name for the goals array is `objectives` (not `goals`) — this is a
-  schema-level name, not user-facing vocabulary; always say "goals" to users
-- The internal field name for measurable outcomes is `keyResults` (not `outcomes`) — same
-  convention applies; say "measurable outcomes" to users
-- `targetValue` is optional for directional goals where there is no specific number target
-
-## Examples
-
-```typescript
-goals: {
-  objectives: [
-    {
-      id:          "goal-arr-q1-2026",
-      description: "Reach $50K MRR by end of Q1 2026",
-      periodStart: "2026-01-01",
-      periodEnd:   "2026-03-31",
-      keyResults: [
-        {
-          id:           "kr-mrr-q1",
-          description:  "Grow monthly recurring revenue",
-          targetMetric: "monthly recurring revenue (MRR)",
-          currentValue: 32000,
-          targetValue:  50000
-        },
-        {
-          id:           "kr-churn-q1",
-          description:  "Reduce monthly churn rate",
-          targetMetric: "monthly churn rate (%)",
-          currentValue: 4.2,
-          targetValue:  2.5
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Where it lives in the adapter
-
-`core/config/organization-model.ts` under the `goals` key of
-`defineOrganizationModel({...})`.
-
-To read current goals: open the adapter file and inspect the `goals.objectives` array, or use
-`pnpm exec elevasis-sdk knowledge:cat goals` (external project).
-
-## Write path
-
-To add, edit, remove, or update progress on a goal, the `/knowledge` skill runs the codify
-ceremony (`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck →
-Zod parse → rollback on failure. Only the `objectives` array is written; no other keys in the
-adapter are touched. For progress-only updates (changing `currentValue` on an existing outcome),
-a targeted edit is preferred over rewriting the entire goals block.
-
----
-
-**Read via `/knowledge`** — natural-language queries like "what are our goals this quarter?" or
-"what's the current MRR against target?" route to this domain via the skill's intent classifier.
+# Goals domain
+
+The `goals` domain captures what the organization is working toward — time-bounded goals with
+measurable outcomes. The schema shape is OKR-inspired (objectives + key results) but all
+user-facing language must say "goals" and "measurable outcomes". Never say "OKR", "objective",
+or "key result" to the user.
+
+Agents use this domain for quarterly planning, priority routing, and understanding which outcomes
+matter most right now.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/goals.ts`
+
+```typescript
+GoalsDomainSchema = z.object({
+  objectives: z.array(ObjectiveSchema).default([])
+})
+
+ObjectiveSchema = z.object({
+  id:          z.string().trim().min(1).max(100),   // stable ID, e.g. "goal-grow-arr-q1-2026"
+  description: z.string().trim().min(1).max(1000),  // plain-language goal statement
+  periodStart: z.string().regex(ISO_DATE),          // YYYY-MM-DD — must be before periodEnd
+  periodEnd:   z.string().regex(ISO_DATE),          // YYYY-MM-DD — enforced in superRefine
+  keyResults:  z.array(KeyResultSchema).default([]) // measurable outcomes under this goal
+})
+
+KeyResultSchema = z.object({
+  id:           z.string().trim().min(1).max(100),  // e.g. "kr-revenue-q1"
+  description:  z.string().trim().min(1).max(500),  // e.g. "Increase trial-to-paid conversion"
+  targetMetric: z.string().trim().min(1).max(200),  // what is being measured, e.g. "monthly revenue"
+  currentValue: z.number().default(0),              // current tracked value
+  targetValue:  z.number().optional()               // target to hit (omit if directional)
+})
+```
+
+## Field reference
+
+| Field         | Type          | Notes                                                      |
+| ------------- | ------------- | ---------------------------------------------------------- |
+| `id`          | string (100)  | Stable key; e.g. `"goal-grow-arr-q1-2026"`                 |
+| `description` | string (1000) | Plain-language goal statement; min 1 char required         |
+| `periodStart` | string        | ISO date `YYYY-MM-DD`; must be strictly before `periodEnd` |
+| `periodEnd`   | string        | ISO date `YYYY-MM-DD`; enforced by `superRefine`           |
+| `keyResults`  | array         | Measurable outcomes under this goal; defaults to `[]`      |
+
+Key result fields:
+
+| Field          | Type         | Notes                                               |
+| -------------- | ------------ | --------------------------------------------------- |
+| `id`           | string (100) | Stable key; e.g. `"kr-revenue-q1"`                  |
+| `description`  | string (500) | What is being tracked; min 1 char required          |
+| `targetMetric` | string (200) | The metric name; e.g. `"monthly recurring revenue"` |
+| `currentValue` | number       | Current value; defaults to `0`                      |
+| `targetValue`  | number       | Optional target; omit if the outcome is directional |
+
+## Validation rules
+
+- `periodEnd` must be strictly after `periodStart`; enforced at parse time by
+  `OrganizationModelSchema.superRefine()`; setting equal dates is also invalid
+- Both `periodStart` and `periodEnd` must match `YYYY-MM-DD` ISO date format exactly
+- The internal field name for the goals array is `objectives` (not `goals`) — this is a
+  schema-level name, not user-facing vocabulary; always say "goals" to users
+- The internal field name for measurable outcomes is `keyResults` (not `outcomes`) — same
+  convention applies; say "measurable outcomes" to users
+- `targetValue` is optional for directional goals where there is no specific number target
+
+## Examples
+
+```typescript
+goals: {
+  objectives: [
+    {
+      id:          "goal-arr-q1-2026",
+      description: "Reach $50K MRR by end of Q1 2026",
+      periodStart: "2026-01-01",
+      periodEnd:   "2026-03-31",
+      keyResults: [
+        {
+          id:           "kr-mrr-q1",
+          description:  "Grow monthly recurring revenue",
+          targetMetric: "monthly recurring revenue (MRR)",
+          currentValue: 32000,
+          targetValue:  50000
+        },
+        {
+          id:           "kr-churn-q1",
+          description:  "Reduce monthly churn rate",
+          targetMetric: "monthly churn rate (%)",
+          currentValue: 4.2,
+          targetValue:  2.5
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`core/config/organization-model.ts` under the `goals` key of
+`defineOrganizationModel({...})`.
+
+To read current goals: open the adapter file and inspect the `goals.objectives` array, or use
+`pnpm exec elevasis-sdk knowledge:cat goals` (external project).
+
+## Write path
+
+To add, edit, remove, or update progress on a goal, the `/knowledge` skill runs the codify
+ceremony (`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck →
+Zod parse → rollback on failure. Only the `objectives` array is written; no other keys in the
+adapter are touched. For progress-only updates (changing `currentValue` on an existing outcome),
+a targeted edit is preferred over rewriting the entire goals block.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "what are our goals this quarter?" or
+"what's the current MRR against target?" route to this domain via the skill's intent classifier.