@elevasis/sdk 1.15.1 → 1.16.0

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

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

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

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

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

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

@@ -0,0 +1,99 @@
+# Roles domain
+
+The `roles` domain describes who does what inside the organization — a role chart inspired by the
+EOS Accountability Chart but using plain-language field names throughout. Agents use this domain
+for HITL routing, escalation logic, and approval-rights reasoning.
+
+Field names are developer-facing; when narrating to users, say "role", "responsibilities",
+"reports to", and "held by". Do not say "seat", "accountability", or "EOS".
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/roles.ts`
+
+```typescript
+RolesDomainSchema = z.object({
+  roles: z.array(RoleSchema).default([])
+})
+
+RoleSchema = z.object({
+  id:               z.string().trim().min(1).max(100),              // stable ID, e.g. "role-ceo"
+  title:            z.string().trim().min(1).max(200),              // display title, e.g. "CEO"
+  responsibilities: z.array(z.string().trim().max(500)).default([]),// what this role owns
+  reportsToId:      z.string().trim().min(1).max(100).optional(),   // must ref another roles[].id
+  heldBy:           z.string().trim().max(200).optional()           // name or email, free-form
+})
+```
+
+## Field reference
+
+| Field              | Type     | Max | Notes                                                           |
+| ------------------ | -------- | --- | --------------------------------------------------------------- |
+| `id`               | string   | 100 | Stable key, min 1 char; e.g. `"role-ceo"`                       |
+| `title`            | string   | 200 | Display title; min 1 char required                              |
+| `responsibilities` | string[] | 500 | Each item: one thing this role is accountable for               |
+| `reportsToId`      | string   | 100 | Optional; must reference another `roles[].id` in the collection |
+| `heldBy`           | string   | 200 | Optional; name or email of the person holding this role         |
+
+## Validation rules
+
+- `reportsToId` (when present) must resolve to another `roles[].id` in the same collection;
+  enforced at parse time by `OrganizationModelSchema.superRefine()`
+- Absence of `reportsToId` indicates a top-level role (no reporting line)
+- Cycle detection is not enforced by the schema (known limitation); agents should surface
+  obvious cycles (e.g. role A reports to role B which reports to role A)
+- `heldBy` is free-form; no validation beyond max length
+- An empty roles array means no HITL routing or escalation rules are available
+
+## Examples
+
+```typescript
+roles: {
+  roles: [
+    {
+      id:               "role-ceo",
+      title:            "CEO",
+      responsibilities: [
+        "Set company direction",
+        "Final approval on deals >$10K",
+        "Manage investor relations"
+      ],
+      reportsToId: undefined,
+      heldBy:      "Alice Johnson"
+    },
+    {
+      id:               "role-head-of-client-success",
+      title:            "Head of Client Success",
+      responsibilities: [
+        "Own client health scores",
+        "Lead quarterly business reviews",
+        "Handle escalations"
+      ],
+      reportsToId: "role-ceo",
+      heldBy:      undefined
+    }
+  ]
+}
+```
+
+## Where it lives in the adapter
+
+`foundations/config/organization-model.ts` under the `roles` key of
+`defineOrganizationModel({...})`.
+
+To read the current role chart: open the adapter file and inspect the `roles.roles` array, or
+use `pnpm exec elevasis-sdk knowledge:cat roles` (external project).
+
+## Write path
+
+To add, edit, or remove a role, the `/knowledge` skill runs the codify ceremony
+(`operations/codify-level-a.md`): snapshot → propose → confirm → write → typecheck → Zod parse →
+rollback on failure. Only the `roles` array is written; no other keys in the adapter are touched.
+Before writing, the skill verifies all `reportsToId` references resolve to IDs that will exist
+after the write. When removing a role, the skill surfaces any other roles that `reportsToId` to it
+and asks whether to clear those reporting lines before proceeding.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "who is responsible for client
+escalations?" or "list my roles" route to this domain via the skill's intent classifier.

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

@@ -0,0 +1,102 @@
+# TechStack domain
+
+Tech stack information is not a standalone top-level domain — it lives as an optional `techStack`
+extension field on individual `ResourceMapping` entries in the organization model. This keeps all
+integration metadata co-located with the resource mapping that represents it, while adding fields
+that agents need for cross-integration automation and system-of-record resolution.
+
+## Schema
+
+Source: `packages/core/src/organization-model/domains/shared.ts`
+
+```typescript
+TechStackEntrySchema = z.object({
+  platform:         z.string().trim().min(1).max(200),
+  purpose:          z.string().trim().min(1).max(500),
+  credentialStatus: z.enum(['configured', 'pending', 'expired', 'missing']),
+  isSystemOfRecord: z.boolean().default(false)
+})
+```
+
+`TechStackEntrySchema` is an optional field on `ResourceMappingSchema`. It applies to resource
+mapping entries whose `resourceType` is `'integration'` or `'external'`.
+
+## Field reference
+
+| Field              | Type    | Notes                                                                  |
+| ------------------ | ------- | ---------------------------------------------------------------------- |
+| `platform`         | string  | Name of the external platform; e.g. `"HubSpot"`, `"Stripe"`, `"Apify"` |
+| `purpose`          | string  | Free-form description of what this integration is used for             |
+| `credentialStatus` | enum    | `configured`, `pending`, `expired`, or `missing`                       |
+| `isSystemOfRecord` | boolean | `true` if this integration is the authoritative source for its domain  |
+
+## Validation rules
+
+- `platform` and `purpose` are required (min 1 char)
+- `credentialStatus` must be one of the four enum values; no free-form strings
+- `isSystemOfRecord` defaults to `false`; only one integration per domain should be `true`,
+  though the schema does not enforce uniqueness — agents should surface conflicts
+- `techStack` applies only to resource mappings with `resourceType: 'integration'` or
+  `'external'`; adding it to other resource types is valid at schema level but semantically
+  incorrect
+
+`credentialStatus` semantics:
+
+- `configured` -- credential present and active
+- `pending` -- integration planned but not yet set up
+- `expired` -- credential previously configured but has lapsed
+- `missing` -- expected to be configured but not present
+
+## Examples
+
+```typescript
+// Inside resourceMappings array in defineOrganizationModel({...})
+resourceMappings: [
+  {
+    id:           "rm-hubspot",
+    label:        "HubSpot CRM Integration",
+    resourceType: "integration",
+    techStack: {
+      platform:         "HubSpot",
+      purpose:          "CRM for contacts, companies, and deal pipeline",
+      credentialStatus: "configured",
+      isSystemOfRecord: true
+    }
+  },
+  {
+    id:           "rm-apify",
+    label:        "Apify Web Scraping",
+    resourceType: "integration",
+    techStack: {
+      platform:         "Apify",
+      purpose:          "Web scraping and data extraction for lead enrichment",
+      credentialStatus: "pending",
+      isSystemOfRecord: false
+    }
+  }
+]
+```
+
+## Where it lives in the adapter
+
+`foundations/config/organization-model.ts` inside the `resourceMappings` array of
+`defineOrganizationModel({...})`. The `techStack` field is set on the matching `ResourceMapping`
+object by `id`.
+
+To read current tech stack entries: open the adapter file and inspect the `resourceMappings`
+array, filtering to entries with a `techStack` field, or use
+`pnpm exec elevasis-sdk knowledge:cat techStack` (external project).
+
+## Write path
+
+To add or update `techStack` metadata on a resource mapping, the `/knowledge` skill runs the
+codify ceremony (`operations/codify-level-a.md`): snapshot → propose → confirm → write →
+typecheck → Zod parse → rollback on failure. Only the targeted `resourceMappings` entry (matched
+by `id`) is modified; all other entries are left unchanged. If the user only wants to update
+`credentialStatus`, a targeted edit to that single field is preferred.
+
+---
+
+**Read via `/knowledge`** — natural-language queries like "what integrations are configured?" or
+"is HubSpot our system of record for contacts?" route to this domain via the skill's intent
+classifier.

package/reference/claude-config/skills/run-ui/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: run-ui
+description: Start the project's Vite UI dev server on port 4300 in the background, surfacing the URL once it's ready. Detects port conflicts and asks before killing the holder.
+---
+
+# Run UI
+
+Start `ui/` dev server (`pnpm -C ui dev`) in the background on port 4300 and surface the URL when Vite reports ready.
+
+**Usage:** `/run-ui`
+
+The Vite config in `ui/vite.config.ts` pins port 4300 with `strictPort: true`, so a conflict is a hard fail — the skill resolves the conflict before launching.
+
+## Process
+
+### Step 1: Probe port 4300
+
+Run via PowerShell tool (Windows-native, cleanest):
+
+```powershell
+$conn = Get-NetTCPConnection -LocalPort 4300 -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
+if ($conn) {
+  $proc = Get-Process -Id $conn.OwningProcess -ErrorAction SilentlyContinue
+  $cmd = (Get-CimInstance Win32_Process -Filter "ProcessId = $($conn.OwningProcess)" -ErrorAction SilentlyContinue).CommandLine
+  "PID=$($conn.OwningProcess) NAME=$($proc.ProcessName) CMD=$cmd"
+} else {
+  "FREE"
+}
+```
+
+### Step 2: Branch on probe result
+
+- **`FREE`** → go to Step 3.
+- **Holder is our Vite** (CMD contains `vite` or `node` running from this project's `ui/`) → port is already serving the app. Skip launch and surface `http://localhost:4300/` directly. Done.
+- **Holder is something else** → ask the user:
+
+  > "Port 4300 is held by `<NAME>` (PID `<PID>`). Kill it and start the dev server? (y/n)"
+
+  On `n`, abort with no further action. On `y`, run `Stop-Process -Id <PID> -Force` then continue to Step 3.
+
+### Step 3: Launch dev server in background
+
+Use Bash tool with `run_in_background: true`:
+
+```bash
+pnpm -C ui dev
+```
+
+Capture the returned shell ID.
+
+### Step 4: Wait for ready signal
+
+Poll the background shell output (read every ~2s) for Vite's ready line — typically:
+
+```
+  ➜  Local:   http://localhost:4300/
+```
+
+or `ready in <N>ms`.
+
+Stop polling on the first match. Hard cap: ~15 seconds (≈7 reads). If no ready signal arrives, surface the last 20 lines of background output so the user can debug, and leave the background process running.
+
+### Step 5: Report
+
+On success:
+
+```
+UI dev server running
+  Local:  http://localhost:4300/
+  Shell:  <bg-shell-id>
+```
+
+On timeout, prepend a one-line note ("Vite did not report ready within 15s — last output:") before the captured tail.