@elevasis/sdk 1.15.1 → 1.17.0

package/reference/claude-config/skills/{configure → knowledge}/operations/codify-level-b.md

@@ -1,158 +1,158 @@
-# Codify Pipeline: Level B (New Extension TypeScript Files)
-
-Level B is the codify pipeline for changes that require creating a new TypeScript file under
-`foundations/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
-field override in `foundations/config/organization-model.ts`.
-
-Level B is **only offered when the user explicitly asks** for something that requires a new file.
-Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
-
----
-
-## 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 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
-and for confirming the intent with the user before invoking this pipeline.
-
----
-
-## Pipeline
-
-### Step 1: Snapshot all files that will be touched
-
-Before any write, read and snapshot:
-
-1. `foundations/config/organization-model.ts` (always touched for wiring)
-2. The target extension file path (if it already exists -- confirm overwrite with user)
-
-```
-Read("foundations/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
-Read("foundations/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
-```
-
-The target extension file path follows the naming convention:
-`foundations/config/extensions/{kebab-case-feature-id}.ts`
-
-### Step 2: Scaffold the extension file
-
-Create `foundations/config/extensions/{id}.ts` using the Write tool.
-
-The file shape depends on the extension type:
-
-**Custom feature (most common Level B case):**
-
-```typescript
-/**
- * {Feature label} feature extension.
- * Registered in foundations/config/organization-model.ts.
- */
-import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
-
-export const {FEATURE_CONST}: OrganizationModelFeature = {
-  id: '{feature-id}',
-  label: '{Feature Label}',
-  description: '{optional description}',
-  enabled: true,
-  entityIds: [],
-  surfaceIds: [],
-  resourceIds: [],
-  capabilityIds: [],
-}
-```
-
-Replace `{FEATURE_CONST}` with the SCREAMING_SNAKE_CASE version of the feature ID
-(e.g. `CLIENT_PORTAL_FEATURE`).
-
-The caller provides the exact field values based on what the user confirmed.
-
-### Step 3: Wire the extension into the adapter
-
-Edit `foundations/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.
-
-Example import addition:
-
-```typescript
-import { CLIENT_PORTAL_FEATURE } from './extensions/client-portal'
-```
-
-Example features array addition:
-
-```typescript
-features: [
-  ...existingFeatures,
-  CLIENT_PORTAL_FEATURE,
-],
-```
-
-### Step 4: TypeScript type-check
-
-```bash
-pnpm -C operations check-types
-```
-
-Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
-
-### Step 5: Runtime schema validation
-
-```bash
-pnpm -C operations check
-```
-
-If either check fails, proceed to Step 6 (rollback).
-
-### Step 6: Rollback (on failure only)
-
-If Step 4 or Step 5 failed:
-
-1. Restore `foundations/config/organization-model.ts` from ROLLBACK_ADAPTER.
-2. If the extension file did not previously exist, delete it. If it previously existed, restore
-   from ROLLBACK_EXTENSION.
-3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
-   itself fails type-check, report both the original error and the restore state to the user --
-   do not silently leave the project in a broken state.
-4. Return the error message to the caller.
-
-### Step 7: Success signal
-
-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)
-- `Type-check: PASS`
-- `Schema validation: PASS`
-
-The caller formats and presents the final report to the user.
-
----
-
-## Caller Contract
-
-Callers must provide before invoking this pipeline:
-
-- **Extension file path:** `foundations/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
-- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
-  a new extension file
-
-This pipeline does not ask the user any questions. All confirmation and escalation decisions
-happen in the domain operation before this pipeline is invoked.
-
----
-
-## Constraint: Extension files are Tier 3 (never synced)
-
-Files under `foundations/config/extensions/` are Tier 3 -- project-specific, never overwritten
-by `/external sync`. This means custom features and entity extensions survive template upgrades
-automatically. Do not put platform-default overrides in extension files; those belong directly in
-`foundations/config/organization-model.ts` (Tier 2, merge-aware).
+# Codify Pipeline: Level B (New Extension TypeScript Files)
+
+Level B is the codify pipeline for changes that require creating a new TypeScript file under
+`foundations/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
+field override in `foundations/config/organization-model.ts`.
+
+Level B is **only offered when the user explicitly asks** for something that requires a new file.
+Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
+
+---
+
+## 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 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
+and for confirming the intent with the user before invoking this pipeline.
+
+---
+
+## Pipeline
+
+### Step 1: Snapshot all files that will be touched
+
+Before any write, read and snapshot:
+
+1. `foundations/config/organization-model.ts` (always touched for wiring)
+2. The target extension file path (if it already exists -- confirm overwrite with user)
+
+```
+Read("foundations/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
+Read("foundations/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
+```
+
+The target extension file path follows the naming convention:
+`foundations/config/extensions/{kebab-case-feature-id}.ts`
+
+### Step 2: Scaffold the extension file
+
+Create `foundations/config/extensions/{id}.ts` using the Write tool.
+
+The file shape depends on the extension type:
+
+**Custom feature (most common Level B case):**
+
+```typescript
+/**
+ * {Feature label} feature extension.
+ * Registered in foundations/config/organization-model.ts.
+ */
+import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
+
+export const {FEATURE_CONST}: OrganizationModelFeature = {
+  id: '{feature-id}',
+  label: '{Feature Label}',
+  description: '{optional description}',
+  enabled: true,
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: [],
+}
+```
+
+Replace `{FEATURE_CONST}` with the SCREAMING_SNAKE_CASE version of the feature ID
+(e.g. `CLIENT_PORTAL_FEATURE`).
+
+The caller provides the exact field values based on what the user confirmed.
+
+### Step 3: Wire the extension into the adapter
+
+Edit `foundations/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.
+
+Example import addition:
+
+```typescript
+import { CLIENT_PORTAL_FEATURE } from './extensions/client-portal'
+```
+
+Example features array addition:
+
+```typescript
+features: [
+  ...existingFeatures,
+  CLIENT_PORTAL_FEATURE,
+],
+```
+
+### Step 4: TypeScript type-check
+
+```bash
+pnpm -C operations check-types
+```
+
+Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
+
+### Step 5: Runtime schema validation
+
+```bash
+pnpm -C operations check
+```
+
+If either check fails, proceed to Step 6 (rollback).
+
+### Step 6: Rollback (on failure only)
+
+If Step 4 or Step 5 failed:
+
+1. Restore `foundations/config/organization-model.ts` from ROLLBACK_ADAPTER.
+2. If the extension file did not previously exist, delete it. If it previously existed, restore
+   from ROLLBACK_EXTENSION.
+3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
+   itself fails type-check, report both the original error and the restore state to the user --
+   do not silently leave the project in a broken state.
+4. Return the error message to the caller.
+
+### Step 7: Success signal
+
+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)
+- `Type-check: PASS`
+- `Schema validation: PASS`
+
+The caller formats and presents the final report to the user.
+
+---
+
+## Caller Contract
+
+Callers must provide before invoking this pipeline:
+
+- **Extension file path:** `foundations/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
+- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
+  a new extension file
+
+This pipeline does not ask the user any questions. All confirmation and escalation decisions
+happen in the domain operation before this pipeline is invoked.
+
+---
+
+## Constraint: Extension files are Tier 3 (never synced)
+
+Files under `foundations/config/extensions/` are Tier 3 -- project-specific, never overwritten
+by `/external sync`. This means custom features and entity extensions survive template upgrades
+automatically. Do not put platform-default overrides in extension files; those belong directly in
+`foundations/config/organization-model.ts` (Tier 2, merge-aware).

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

@@ -0,0 +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
+
+`foundations/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

@@ -0,0 +1,113 @@
+# 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.

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

@@ -0,0 +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
+
+`foundations/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.