@elevasis/sdk 1.8.2 → 1.9.0

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

@@ -1,150 +1,150 @@
-# Configure: customers
-
-Guides the user through reviewing and updating the `customers` domain of the organization model.
-
-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 reference
-
-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"
-})
-```
-
-Where this lands in the adapter: `foundations/config/organization-model.ts` under the `customers`
-key of `defineOrganizationModel({...})`.
-
----
-
-## Process
-
-### Step 1: Read current state
-
-Read `foundations/config/organization-model.ts` and extract the current `customers.segments` array.
-Present it as a summary table:
-
-```
-Current customer segments (N):
-  1. {name} ({id}) — {description truncated to 80 chars}
-  2. ...
-  (none defined yet)
-```
-
-### Step 2: Establish intent
-
-Ask whether the user wants to:
-
-- **Add** a new segment
-- **Edit** an existing segment (by name or number)
-- **Remove** a segment
-- **Review all** segments in detail
-
-Handle one segment at a time unless the user explicitly asks to work on multiple at once.
-
-### Step 3: Gather segment details
-
-For each segment being added or edited, work through the fields conversationally:
-
-**Core identity:**
-
-- "What's a good name for this segment? (e.g. 'SMB Marketing Agencies', 'Enterprise SaaS Companies')"
-- "Give it a stable ID I'll use as a key — lowercase with hyphens, like `segment-smb-agencies`."
-- "How would you describe who this segment is in one or two sentences?"
-
-**Jobs-to-be-done:**
-
-- "What is the main job this segment is trying to get done? The goal they hire you to accomplish —
-  describe it in their terms, not yours."
-
-**Pains and gains:**
-
-- "What are two or three frustrations or obstacles this segment runs into when trying to get that
-  job done?"
-- "What outcomes or benefits are they hoping for — beyond just fixing the pain?"
-
-**Firmographics (optional):**
-
-- "Do you want to capture firmographic filters for targeting? Things like industry vertical,
-  typical company size, and geographic region."
-
-**Value proposition:**
-
-- "How does your organization's offering uniquely address this segment's needs? One or two sentences."
-
-If a field already has a value, show it and ask "Keep this or update it?"
-
-### Step 4: Confirm before writing
-
-Present a diff for the affected segment(s):
-
-```
-Proposed customers change:
-
-ADD segment "SMB Marketing Agencies" (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", "Client reporting takes hours", "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."
-
-Apply? (yes/no)
-```
-
-For edits to existing segments, show only the fields that changed.
-
-### Step 5: Codify
-
-Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `customers`
-block. Only the `segments` array is written — no other keys in the adapter are touched.
-
-When adding a segment, append to the array. When editing, replace the matching entry by `id`.
-When removing, filter it out.
-
-Cross-reference note: if `offerings.products[].targetSegmentIds` references a segment being
-removed, surface a warning and ask the user whether to clean up those references before writing.
-
-### Step 6: Report
-
-After successful validation:
-
-```
-Customers updated.
-  Segments: {total count} ({N added / N edited / N removed})
-  foundations/config/organization-model.ts — customers.segments updated
-  Type-check: PASS
-  Schema validation: PASS
-```
-
-If validation failed and rollback occurred:
-
-```
-Customers update rolled back.
-  Reason: {error message}
-  foundations/config/organization-model.ts — restored to previous state
-  No changes persisted.
-```
+# Configure: customers
+
+Guides the user through reviewing and updating the `customers` domain of the organization model.
+
+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 reference
+
+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"
+})
+```
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `customers`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `customers.segments` array.
+Present it as a summary table:
+
+```
+Current customer segments (N):
+  1. {name} ({id}) — {description truncated to 80 chars}
+  2. ...
+  (none defined yet)
+```
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add** a new segment
+- **Edit** an existing segment (by name or number)
+- **Remove** a segment
+- **Review all** segments in detail
+
+Handle one segment at a time unless the user explicitly asks to work on multiple at once.
+
+### Step 3: Gather segment details
+
+For each segment being added or edited, work through the fields conversationally:
+
+**Core identity:**
+
+- "What's a good name for this segment? (e.g. 'SMB Marketing Agencies', 'Enterprise SaaS Companies')"
+- "Give it a stable ID I'll use as a key — lowercase with hyphens, like `segment-smb-agencies`."
+- "How would you describe who this segment is in one or two sentences?"
+
+**Jobs-to-be-done:**
+
+- "What is the main job this segment is trying to get done? The goal they hire you to accomplish —
+  describe it in their terms, not yours."
+
+**Pains and gains:**
+
+- "What are two or three frustrations or obstacles this segment runs into when trying to get that
+  job done?"
+- "What outcomes or benefits are they hoping for — beyond just fixing the pain?"
+
+**Firmographics (optional):**
+
+- "Do you want to capture firmographic filters for targeting? Things like industry vertical,
+  typical company size, and geographic region."
+
+**Value proposition:**
+
+- "How does your organization's offering uniquely address this segment's needs? One or two sentences."
+
+If a field already has a value, show it and ask "Keep this or update it?"
+
+### Step 4: Confirm before writing
+
+Present a diff for the affected segment(s):
+
+```
+Proposed customers change:
+
+ADD segment "SMB Marketing Agencies" (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", "Client reporting takes hours", "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."
+
+Apply? (yes/no)
+```
+
+For edits to existing segments, show only the fields that changed.
+
+### Step 5: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `customers`
+block. Only the `segments` array is written — no other keys in the adapter are touched.
+
+When adding a segment, append to the array. When editing, replace the matching entry by `id`.
+When removing, filter it out.
+
+Cross-reference note: if `offerings.products[].targetSegmentIds` references a segment being
+removed, surface a warning and ask the user whether to clean up those references before writing.
+
+### Step 6: Report
+
+After successful validation:
+
+```
+Customers updated.
+  Segments: {total count} ({N added / N edited / N removed})
+  foundations/config/organization-model.ts — customers.segments updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Customers update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts — restored to previous state
+  No changes persisted.
+```

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

@@ -1,162 +1,162 @@
-# Configure: features
-
-Guides the user through enabling, disabling, or adding features in the organization model.
-
-Features are the top-level capability switches in the platform. Enabling a feature makes its nav
-items and routes visible; disabling hides them without removing the feature from the model. Adding
-a new feature may require only a config edit (Level A) or a new extension TypeScript file
-(Level B), depending on whether the feature already exists in the platform defaults.
-
-This operation handles both toggling existing features and introducing custom features.
-
-## Background: Level A vs Level B
-
-- **Level A (config-only edit):** The feature exists in the platform defaults (see
-  `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for the default feature
-  set). The adapter in `foundations/config/organization-model.ts` overrides its `enabled` flag or
-  adjusts metadata. No new TypeScript files needed.
-
-- **Level B (new extension file):** The feature does not exist in platform defaults. A new
-  feature ID and manifest need to be declared. This requires a new TypeScript file under
-  `foundations/config/extensions/` plus wiring it into the adapter. Level B is only offered when
-  the user explicitly asks to create a custom feature.
-
-## Schema reference
-
-Source: `node_modules/@elevasis/core/organization-model` (published types) or
-`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` (auto-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
-})
-```
-
-Platform default feature IDs (from `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`):
-`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`
-
-Where this lands in the adapter: `foundations/config/organization-model.ts` under the `features`
-array of `defineOrganizationModel({...})`. The `features` array replaces entirely (no element
-merge), so the adapter must redeclare all features it wants to override.
-
----
-
-## Process
-
-### Step 1: Read current state
-
-Read `foundations/config/organization-model.ts` and extract the current `features` array from the
-adapter. Also read `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` to see
-what the platform defaults look like.
-
-Present a combined view:
-
-```
-Platform features (current state):
-  crm          [enabled]  -- CRM (adapter override or platform default)
-  lead-gen     [enabled]  -- Lead Generation
-  projects     [enabled]  -- Projects
-  operations   [enabled]  -- Operations
-  monitoring   [enabled]  -- Monitoring
-  settings     [enabled]  -- Settings
-  seo          [disabled] -- SEO (disabled in platform default)
-
-Custom features (adapter-only):
-  (none)
-```
-
-### Step 2: Establish intent
-
-Ask what the user wants to do:
-
-- **Enable** a disabled feature
-- **Disable** an enabled feature
-- **Add a custom feature** (Level B -- will ask for explicit confirmation)
-- **Edit metadata** on an existing feature (label, color, icon)
-
-For enable/disable: this is Level A. For custom add: escalate to Level B branch.
-
-### Step 3a: Level A -- Enable or disable
-
-For an enable or disable request:
-
-- Identify the target feature by name or ID.
-- Read the current `enabled` value.
-- Confirm the proposed change:
-
-```
-Proposed feature change:
-
-DISABLE feature "SEO" (seo):
-  enabled: true -> false
-
-This will hide the SEO nav item and gate its routes.
-Apply? (yes/no)
-```
-
-After confirmation, execute `.claude/skills/configure/operations/codify-level-a.md`.
-
-The write either adds or updates the matching entry in the `features` array of the adapter.
-Because the array replaces entirely, verify that the adapter redeclares all features that should
-remain in their current state.
-
-### Step 3b: Level B -- Add a custom feature
-
-Only proceed here when the user explicitly asks to add a new custom feature that does not exist in
-the platform defaults.
-
-State clearly: "Adding a custom feature creates a new TypeScript extension file in
-`foundations/config/extensions/`. This is a bigger change than a config toggle. Want to proceed?"
-
-If yes, gather:
-
-- "What should the feature ID be? Lowercase, hyphens only (e.g. `client-portal`)."
-- "What's the display label? (e.g. 'Client Portal')"
-- "Optional: a short description of what this feature represents."
-- "Which surfaces, entities, or resources does this feature relate to? (IDs -- leave blank to add
-  later)"
-
-Then execute `.claude/skills/configure/operations/codify-level-b.md` to scaffold the extension
-file and wire it into the adapter.
-
-### Step 4: Validation
-
-All changes -- Level A and Level B -- must pass:
-
-1. `pnpm -C operations check-types`
-2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result
-
-On failure, roll back and report. See `codify-level-a.md` and `codify-level-b.md` for the
-rollback procedure.
-
-### Step 5: Report
-
-After successful validation:
-
-```
-Features updated.
-  {feature label} ({id}): {old enabled} -> {new enabled}   (Level A)
-  Custom feature "{label}" ({id}): added                   (Level B, if applicable)
-  foundations/config/organization-model.ts -- features array updated
-  foundations/config/extensions/{id}.ts -- created          (Level B only)
-  Type-check: PASS
-  Schema validation: PASS
-```
-
-If validation failed and rollback occurred:
-
-```
-Features update rolled back.
-  Reason: {error message}
-  All files restored to previous state.
-  No changes persisted.
-```
+# Configure: features
+
+Guides the user through enabling, disabling, or adding features in the organization model.
+
+Features are the top-level capability switches in the platform. Enabling a feature makes its nav
+items and routes visible; disabling hides them without removing the feature from the model. Adding
+a new feature may require only a config edit (Level A) or a new extension TypeScript file
+(Level B), depending on whether the feature already exists in the platform defaults.
+
+This operation handles both toggling existing features and introducing custom features.
+
+## Background: Level A vs Level B
+
+- **Level A (config-only edit):** The feature exists in the platform defaults (see
+  `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for the default feature
+  set). The adapter in `foundations/config/organization-model.ts` overrides its `enabled` flag or
+  adjusts metadata. No new TypeScript files needed.
+
+- **Level B (new extension file):** The feature does not exist in platform defaults. A new
+  feature ID and manifest need to be declared. This requires a new TypeScript file under
+  `foundations/config/extensions/` plus wiring it into the adapter. Level B is only offered when
+  the user explicitly asks to create a custom feature.
+
+## Schema reference
+
+Source: `node_modules/@elevasis/core/organization-model` (published types) or
+`node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` (auto-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
+})
+```
+
+Platform default feature IDs (from `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`):
+`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `features`
+array of `defineOrganizationModel({...})`. The `features` array replaces entirely (no element
+merge), so the adapter must redeclare all features it wants to override.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `features` array from the
+adapter. Also read `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` to see
+what the platform defaults look like.
+
+Present a combined view:
+
+```
+Platform features (current state):
+  crm          [enabled]  -- CRM (adapter override or platform default)
+  lead-gen     [enabled]  -- Lead Generation
+  projects     [enabled]  -- Projects
+  operations   [enabled]  -- Operations
+  monitoring   [enabled]  -- Monitoring
+  settings     [enabled]  -- Settings
+  seo          [disabled] -- SEO (disabled in platform default)
+
+Custom features (adapter-only):
+  (none)
+```
+
+### Step 2: Establish intent
+
+Ask what the user wants to do:
+
+- **Enable** a disabled feature
+- **Disable** an enabled feature
+- **Add a custom feature** (Level B -- will ask for explicit confirmation)
+- **Edit metadata** on an existing feature (label, color, icon)
+
+For enable/disable: this is Level A. For custom add: escalate to Level B branch.
+
+### Step 3a: Level A -- Enable or disable
+
+For an enable or disable request:
+
+- Identify the target feature by name or ID.
+- Read the current `enabled` value.
+- Confirm the proposed change:
+
+```
+Proposed feature change:
+
+DISABLE feature "SEO" (seo):
+  enabled: true -> false
+
+This will hide the SEO nav item and gate its routes.
+Apply? (yes/no)
+```
+
+After confirmation, execute `.claude/skills/configure/operations/codify-level-a.md`.
+
+The write either adds or updates the matching entry in the `features` array of the adapter.
+Because the array replaces entirely, verify that the adapter redeclares all features that should
+remain in their current state.
+
+### Step 3b: Level B -- Add a custom feature
+
+Only proceed here when the user explicitly asks to add a new custom feature that does not exist in
+the platform defaults.
+
+State clearly: "Adding a custom feature creates a new TypeScript extension file in
+`foundations/config/extensions/`. This is a bigger change than a config toggle. Want to proceed?"
+
+If yes, gather:
+
+- "What should the feature ID be? Lowercase, hyphens only (e.g. `client-portal`)."
+- "What's the display label? (e.g. 'Client Portal')"
+- "Optional: a short description of what this feature represents."
+- "Which surfaces, entities, or resources does this feature relate to? (IDs -- leave blank to add
+  later)"
+
+Then execute `.claude/skills/configure/operations/codify-level-b.md` to scaffold the extension
+file and wire it into the adapter.
+
+### Step 4: Validation
+
+All changes -- Level A and Level B -- must pass:
+
+1. `pnpm -C operations check-types`
+2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result
+
+On failure, roll back and report. See `codify-level-a.md` and `codify-level-b.md` for the
+rollback procedure.
+
+### Step 5: Report
+
+After successful validation:
+
+```
+Features updated.
+  {feature label} ({id}): {old enabled} -> {new enabled}   (Level A)
+  Custom feature "{label}" ({id}): added                   (Level B, if applicable)
+  foundations/config/organization-model.ts -- features array updated
+  foundations/config/extensions/{id}.ts -- created          (Level B only)
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Features update rolled back.
+  Reason: {error message}
+  All files restored to previous state.
+  No changes persisted.
+```