@elevasis/sdk 1.32.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -58,13 +58,13 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.41.0",
+    "@repo/core": "0.42.0",
     "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --banner:js=\"#!/usr/bin/env node\" && node scripts/copy-reference-docs.mjs && node ../../scripts/monorepo/generate-reference-artifacts.js",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.core-dts.json && tsc -p tsconfig.build.json && tsup && rollup -c rollup.dts.config.mjs && esbuild src/cli/index.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --external:esbuild --banner:js=\"#!/usr/bin/env node\" && node scripts/verify-skill-coverage.mjs && node scripts/copy-reference-docs.mjs && node ../../scripts/monorepo/generate-reference-artifacts.js",
     "type-check": "tsc --noEmit",
     "check-types": "pnpm type-check",
     "test": "pnpm build && node ../../scripts/monorepo/validate-reference-artifacts.js && vitest run --config vitest.bundle.config.ts",

package/reference/claude-config/Overview.md

@@ -0,0 +1,123 @@
+# Claude Code Configuration Overview
+
+Start here when working with the Claude agent scaffold for this project.
+This file is a routing map for the skill and rule inventories. For live CLI capability, run `elevasis-sdk cli`.
+
+---
+
+## What Lives Here
+
+| Surface | Purpose                       | Source of truth                                |
+| ------- | ----------------------------- | ---------------------------------------------- |
+| Skills  | Slash-command entry points    | `.claude/skills/*/SKILL.md`                    |
+| Rules   | Path-scoped operating context | `node_modules/@elevasis/sdk/reference/rules/`  |
+| Hooks   | Claude lifecycle automation   | `.claude/hooks/*.mjs`, `.claude/settings.json` |
+| CLI     | Live command + domain surface | `elevasis-sdk cli` (authoritative, run it)     |
+
+For CLI capability, run `elevasis-sdk cli` — it is the authoritative surface for what commands
+and domains are available. For architecture context, read `CLAUDE.md` first.
+
+---
+
+## Operating Model
+
+This project is skill-first with an always-on ambient vibe layer:
+
+1. Load `CLAUDE.md` for project rules, stack, and the Ambient Vibe Layer contract.
+2. Every natural-language message is silently classified into an intent (Capture, Query, Describe,
+   Transition, Navigate, Codify, Toggle, Operate) before the agent responds — no slash command needed.
+3. For explicit work, match intent to a skill in `.claude/skills/{name}/SKILL.md`.
+4. Load the relevant bundled rule from `node_modules/@elevasis/sdk/reference/rules/` for the area
+   being changed (the local `.claude/rules/*.md` files are thin pointers to these).
+5. Use `elevasis-sdk cli` for the live command/domain surface — do not answer "what can I do" from memory.
+
+---
+
+## Skills
+
+**Location:** `.claude/skills/`
+
+Skills are the slash-command surface. Each skill is `.claude/skills/{name}/SKILL.md`:
+
+<!-- @generated:start:sync-overview-skills -->
+- **client** -- Client portfolio management -- list, resolve, inspect, and maintain client records and their lineage to companies, contacts, and source deals -- via the elevasis-sdk client:* CLI.
+- **deploy** -- Test, build, fix issues, then commit and push
+- **dsp** -- Dispatch subagents in parallel for implementation tasks
+- **elevasis** -- Elevasis platform operations -- check, deploy, execute, inspect, and debug SDK resources
+- **explore** -- Codebase exploration anchored to project documentation
+- **git-sync** -- Pull latest changes, surface new sync notes, install when needed, and run baseline verification without auto-reconciling template drift
+- **om** -- TRIGGER this skill when any of the following apply: - The user references organization-model entities by name or concept: identity, customers, offerings, roles, goals, techStack, systems, actions, labels, knowledge nodes, governance edges, mounts, playbook, outreach cadence, or any domain in the org model. - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit, update, toggle, enable, or disable any organization-model domain or knowledge node. - The user asks "what governs X?", "what does X control?", "system governs", "what is our identity set to?", "what's our timezone?", "show me all reference docs", "list my roles", "where does outreach-cadence apply?", or similar. - An agent is editing files matching: core/config/organization-model.ts, core/config/organization-model/**, or core/config/knowledge/**. SKIP this skill when the task is purely UI layout, workflow authoring, or infrastructure work with no reference to org-model or knowledge-graph entities.
+- **project** -- Portfolio- and project-level work management -- orientation, intent routing, active projects, milestones, tasks, notes, and resume context -- via the elevasis-sdk project:* CLI.
+- **run-ui** -- 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.
+- **save** -- Auto-manage project documentation and persist task resume context from conversation
+- **setup** -- First-time project setup — detect and replace template placeholders, install dependencies, verify build, then hand off to /om for org-model configuration
+- **status** -- Quick project health check
+- **submit-request** -- Submit a structured request report to the Elevasis platform via CLI — enforces pre-analysis before posting
+- **sync** -- Fresh reinstall and cache reset after local dependency or cache drift
+- **tutorial** -- Persona-aware onboarding tutorial that forks into a vibe-coder track (zero technical vocabulary, agent does all the work) or a technical track (full SDK depth, code-first). On first invocation, asks one gate question to determine the user's track and persists the choice to .claude/memory/profile.md. Subsequent invocations skip the question and display the track menu with current progress markers. Supports /tutorial switch (flip track) and /tutorial status (display-only).
+<!-- @generated:end:sync-overview-skills -->
+
+---
+
+## Rules
+
+**Location:** `node_modules/@elevasis/sdk/reference/rules/` (bundled with `@elevasis/sdk`)
+
+Path-scoped operating context loaded for substantial work in their areas. The project's local
+`.claude/rules/*.md` files are thin compatibility pointers; the authoritative content ships with
+the SDK and is listed here:
+
+<!-- @generated:start:sync-overview-rules -->
+- `node_modules/@elevasis/sdk/reference/rules/active-change-index.md` -- Bridge between stable scaffold docs and higher-volatility in-progress architecture work that may override assumptions for agents working in the template
+- `node_modules/@elevasis/sdk/reference/rules/agent-start-here.md` -- Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
+- `node_modules/@elevasis/sdk/reference/rules/deployment.md` -- Deployment workflow -- check-first, dev vs prod, version bumping, common errors
+- `node_modules/@elevasis/sdk/reference/rules/error-handling.md` -- Error handling -- ExecutionError vs PlatformToolError, retry logic, no auto-retry
+- `node_modules/@elevasis/sdk/reference/rules/execution.md` -- Execution model -- timeouts, memory, concurrency, org isolation, runtime constraints
+- `node_modules/@elevasis/sdk/reference/rules/frontend.md` -- Frontend conventions -- React, routing, state, styling, testing, pages
+- `node_modules/@elevasis/sdk/reference/rules/observability.md` -- Observability -- context.logger API, execution inspection, step-level context
+- `node_modules/@elevasis/sdk/reference/rules/operations.md` -- Platform workflows, agents, resource definitions, and deployment for the operations/ surface
+- `node_modules/@elevasis/sdk/reference/rules/organization-model.md` -- Edits to the canonical organization model go through /om
+- `node_modules/@elevasis/sdk/reference/rules/organization-os.md` -- Organization OS orientation -- the semantic contract layer relating Systems, Actions, ontology, resources, policies, roles, goals, and knowledge; consumed via published @elevasis/core / @elevasis/sdk
+- `node_modules/@elevasis/sdk/reference/rules/package-taxonomy.md` -- Package taxonomy (consumer view) -- external projects consume the published @elevasis/* surface only; workspace-internal @repo/elevasis-* packages are not installable here
+- `node_modules/@elevasis/sdk/reference/rules/platform.md` -- Platform conventions -- SDK workflows, agents, deployment, resource registry
+- `node_modules/@elevasis/sdk/reference/rules/shared-types.md` -- Core type boundary -- what belongs in core/types, import rules, schema conventions
+- `node_modules/@elevasis/sdk/reference/rules/task-tracking.md` -- In-progress task conventions -- doc format, status values, auto-save behavior
+- `node_modules/@elevasis/sdk/reference/rules/ui.md` -- UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
+- `node_modules/@elevasis/sdk/reference/rules/vibe.md` -- Ambient intent classifier -- routes natural-language input to intent buckets without a slash command; Codify and Toggle delegate to /om, Operate delegates to /elevasis
+<!-- @generated:end:sync-overview-rules -->
+
+---
+
+## Skill Boundaries
+
+Use the owning skill instead of guessing from the name alone:
+
+| Need                                                     | Route             |
+| -------------------------------------------------------- | ----------------- |
+| SDK operations (check, deploy, exec, inspect, debug)     | `/elevasis`       |
+| Project and task lifecycle                               | `/project`        |
+| Client portfolio (list, resolve, inspect, maintain)      | `/client`         |
+| Organization Model read, codify, or governance           | `/om`             |
+| First-time project setup (placeholder replacement, deps) | `/setup`          |
+| Guided onboarding walkthrough                            | `/tutorial`       |
+| Conversation fanout (notes, task save, blockers)         | `/save`           |
+| Parallel agent dispatch                                  | `/dsp`            |
+| Test, build, commit, push                                | `/deploy`         |
+| Codebase exploration                                     | `/explore`        |
+| Pull latest, surface sync notes, baseline verify         | `/git-sync`       |
+| Project health check                                     | `/status`         |
+| Submit a request to the Elevasis team                    | `/submit-request` |
+| Fresh reinstall / cache reset                            | `/sync`           |
+| Start the Vite dev server on port 4300                   | `/run-ui`         |
+
+---
+
+## Scaffold Maintenance
+
+| Action                                 | Command or file                             |
+| -------------------------------------- | ------------------------------------------- |
+| Refresh the Skills + Rules lists above | `pnpm gen:overview` (run from the monorepo) |
+
+The Skills section is generated from `external/_template/.claude/skills/*/SKILL.md` frontmatter, and
+the Rules section from the bundled rule source `packages/sdk/docs/agent-rules/*.md`, both by
+`.claude/_gen/sync-overview.ts`. Do not hand-edit the generated blocks.

package/reference/claude-config/registries/skill-coverage.json

@@ -0,0 +1,19 @@
+{
+  "skills": {
+    "project": { "domains": ["project"] },
+    "elevasis": { "domains": ["platform"] },
+    "om": { "domains": ["knowledge", "om"] },
+    "submit-request": { "domains": ["request"] },
+    "client": { "domains": ["client"] }
+  },
+  "waived": {
+    "acquisition": "read-only, surfaced via lead-gen UI",
+    "agent": "operator-facing deployed-agent introspection",
+    "session": "operator-facing session introspection",
+    "queue": "HITL approval queue — surfaced in the UI",
+    "schedule": "operator-facing scheduler control",
+    "note": "CLI-only in tenant context; /notes is monorepo-internal, not propagated",
+    "ui": "infra-only dev toggle (ui:use-local / ui:use-published)",
+    "skill": "SDK meta-tooling (skill:scaffold, skill:check-coverage) — developer-facing build utilities, not agent-facing workflow commands"
+  }
+}

package/reference/claude-config/skills/client/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: client
+description: "Client portfolio management -- list, resolve, inspect, and maintain client records and their lineage to companies, contacts, and source deals -- via the elevasis-sdk client:* CLI."
+argument-hint: "[list | status | get | resolve | create | update | delete] [args]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Client Management
+
+`/client` is the entrypoint for all client-portfolio work in the template. It covers:
+
+- **Portfolio status** -- bare `/client` or `/client status` gives a portfolio-level overview of all clients.
+- **Lookup and resolution** -- `/client <query>` or `/client resolve <query>` resolves a name or search term to a canonical client ID.
+- **Detail and lineage** -- `/client get <id>` returns full client detail including linked companies, contacts, and source deals.
+- **CRUD surface** -- create, update, and delete client records via `elevasis-sdk client:*`.
+
+**Usage:**
+
+- `/client` / `/client status` -- Portfolio overview (see "Status Mode" below). Wraps `client:status`.
+- `/client list [--search q] [--status s] [--limit n] [--offset n]` -- Paginated client list. Wraps `client:list`.
+- `/client <query>` / `/client resolve <query>` -- Fuzzy-resolve a client by name, UUID, or search string. Wraps `client:resolve`.
+- `/client get <id>` -- Full client detail: name, status, source, linked company, contact, deals. Wraps `client:get`.
+- `/client create --name "..." [options]` -- Create a new client (confirm ceremony). Wraps `client:create`.
+- `/client update <id> [options]` -- Update client fields (confirm ceremony). Wraps `client:update`.
+- `/client delete <id>` -- Delete a client (destructive -- explicit confirmation required). Wraps `client:delete`.
+
+---
+
+## Ambient Vibe Integration
+
+`/client` is the landing point for client-scoped vibe intents. Agents arriving from the ambient layer behave identically to a direct invocation.
+
+| Vibe intent    | What vibe detected                                          | What to do here                                                                                       |
+| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Describe**   | "tell me about Acme", "what's the status of this client"    | Resolve the client name via `client:resolve`, then run `client:get <id>` and narrate detail + lineage |
+| **Query**      | "which clients are active", "list clients", "client status" | Run `client:list [--status s] [--search q]` or `client:status` and present the results                |
+| **Navigate**   | "focus on Acme", "switch to Acme", "back to Acme"           | Resolve via `client:resolve <query>`, update scope to that client, narrate the new context            |
+| **Capture**    | "add a new client", "create a client for Beta LLC"          | Draft fields from the user's message, confirm with user (Capture ceremony), then `client:create`      |
+| **Transition** | "update Acme's status", "mark Acme as active"               | Confirm the change with user (Transition ceremony), then `client:update <id> --status <new>`          |
+
+`client:create`, `client:update`, and `client:delete` MUST route through the standard Capture/Transition confirm step before executing. The destructive `client:delete` requires explicit user confirmation (show what will be deleted and ask "Are you sure?" before proceeding).
+
+---
+
+## Prerequisites
+
+**Run from the project root** (the directory containing `.elevasis`). Before issuing any other commands, run:
+
+```bash
+pnpm elevasis-sdk doctor
+```
+
+If `doctor` fails, stop immediately and surface the error -- do not retry other commands. Fix the reported issue first (missing `.env`, bad API key, wrong directory), then re-run `doctor` before proceeding.
+
+---
+
+## Invocation Contract
+
+All `elevasis-sdk` commands in this skill use the wrapper script form:
+
+```bash
+pnpm elevasis-sdk <subcommand> [flags]
+```
+
+Available from the **project root** -- the directory that contains the `.elevasis` marker file. The long form `pnpm -C operations exec elevasis-sdk <subcommand>` is equivalent.
+
+---
+
+## Status Mode (bare `/client` or `/client status`)
+
+When invoked without a subcommand or with `status`, enter **client portfolio mode**: present a high-level overview and offer next actions.
+
+```bash
+pnpm elevasis-sdk client:status --pretty
+```
+
+Present the result as a compact summary: total clients, breakdown by status, and a suggestion of what to do next (e.g. "3 active clients. Inspect one with `/client get <id>` or list all with `/client list`").
+
+---
+
+## Operations
+
+### `list [options]` -- Client List
+
+```bash
+pnpm elevasis-sdk client:list --pretty
+
+# Filter by status
+pnpm elevasis-sdk client:list --status active --pretty
+
+# Search by name
+pnpm elevasis-sdk client:list --search "Acme" --pretty
+
+# Paginate
+pnpm elevasis-sdk client:list --limit 20 --offset 0 --pretty
+```
+
+**Options:** `--status <status>`, `--search <query>`, `--limit <n>`, `--offset <n>`, `--api-url <url>`, `--pretty`
+
+Present as a compact table: name, status, source.
+
+### `resolve <query>` -- Name-to-ID Resolution
+
+Resolves a name, UUID, or search string to a canonical client record. This is the primary tool for name-to-ID translation before any `get`, `update`, or `delete` call.
+
+```bash
+pnpm elevasis-sdk client:resolve "Acme" --pretty
+```
+
+If multiple candidates match, the CLI returns candidates -- pick the right one and confirm with the user before proceeding. If zero match, surface the error and suggest `client:list --search "<query>"` to browse.
+
+### `get <id>` -- Client Detail and Lineage
+
+```bash
+pnpm elevasis-sdk client:get <id> --pretty
+```
+
+Returns full client detail: name, status, source, source deal, linked primary company, primary contact, and metadata. Narrate the lineage in plain language (e.g. "Acme Corp -- active client, sourced from deal john@acme.com, linked to Acme Corp (acq_companies)").
+
+### `create` -- Create Client (Confirm Ceremony)
+
+**Always confirm before creating.** Collect required and optional fields, draft a summary, and ask the user to confirm before executing.
+
+**Required:** `--name <name>`
+
+**Optional:** `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--primary-company-id <uuid>`, `--primary-contact-id <uuid>`, `--metadata <json>`
+
+```bash
+pnpm elevasis-sdk client:create \
+  --name "Acme Corp" \
+  --status active \
+  --source deal \
+  --source-deal-id <deal-uuid> \
+  --pretty
+```
+
+After creation, show the new client ID and suggest `/client get <id>` to verify.
+
+### `update <id>` -- Update Client (Confirm Ceremony)
+
+**Always confirm before updating.** Show the current state via `client:get <id>`, draft the proposed changes, and ask the user to confirm before executing.
+
+**Options:** `--name <name>`, `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--clear-source-deal`, `--primary-company-id <uuid>`, `--clear-primary-company`, `--primary-contact-id <uuid>`, `--clear-primary-contact`, `--metadata <json>`
+
+```bash
+pnpm elevasis-sdk client:update <id> --status active --pretty
+```
+
+To clear a linked field, use the corresponding `--clear-*` flag (e.g. `--clear-source-deal`, `--clear-primary-company`, `--clear-primary-contact`). Do NOT pass an empty string -- it is rejected. Use the clear flag instead.
+
+### `delete <id>` -- Delete Client (Destructive -- Explicit Confirmation Required)
+
+**ALWAYS confirm before deleting.** Show the client record first (via `client:get <id>`), then ask the user explicitly: "Delete client `<name>` (`<id>`)? This cannot be undone." Only proceed after an affirmative confirmation.
+
+```bash
+pnpm elevasis-sdk client:delete <id> --pretty
+```
+
+---
+
+## Client Inference
+
+When the user refers to a client by name rather than ID, resolve using these steps (in priority order):
+
+1. **Exact UUID** -- if the argument looks like a UUID, use it directly with `client:get`
+2. **`client:resolve`** -- run `client:resolve "<name>"` to fuzzy-match by name; use the returned ID
+3. **`client:list --search`** -- if `resolve` returns no match, search with `client:list --search "<name>"` and present candidates
+4. **Context from conversation** -- if a specific client was resolved earlier in this session, prefer it
+5. **Ambiguous** -- if multiple match or none match, show candidates and ask
+
+---
+
+## Natural Language Mode
+
+When args do not match any command pattern, infer intent from natural language:
+
+| User says                                         | Inferred operation                                          |
+| ------------------------------------------------- | ----------------------------------------------------------- |
+| "show me Acme"                                    | `resolve "Acme"` then `get <id>`                            |
+| "who are our active clients"                      | `list --status active --pretty`                             |
+| "client overview" / "how many clients do we have" | `status --pretty`                                           |
+| "add a new client: Beta LLC"                      | `create --name "Beta LLC"` (confirm ceremony)               |
+| "update Acme to active"                           | `resolve "Acme"` then `update <id> --status active`         |
+| "delete the Gamma client"                         | `resolve "Gamma"` then `delete <id>` (explicit confirm)     |
+| "link Acme to deal <uuid>"                        | `resolve "Acme"` then `update <id> --source-deal-id <uuid>` |
+| "remove Acme's source deal"                       | `resolve "Acme"` then `update <id> --clear-source-deal`     |
+
+---
+
+## Safety Rules
+
+1. **Always confirm create/update/delete** -- show proposed changes and ask the user before executing any write operation
+2. **Explicit confirmation for delete** -- `client:delete` is irreversible; require an affirmative "yes" before running
+3. **Organization scoping** -- all API calls are automatically org-scoped via `ELEVASIS_PLATFORM_KEY`; no `--org` flag is required
+4. **Read before write** -- when updating, show current state via `client:get` before applying changes
+5. **Use `--clear-*` flags to unlink** -- never pass empty strings to clear linked fields; use `--clear-source-deal`, `--clear-primary-company`, or `--clear-primary-contact`
+6. **Template project assumption** -- the template is a single-organization project; all `/client` operations are scoped by `ELEVASIS_PLATFORM_KEY`; there is no cross-org capability
+
+---
+
+**Last Updated:** 2026-06-03