@elevasis/sdk 1.11.0 → 1.12.0

package/dist/types/worker/adapters/llm.d.ts

@@ -4,7 +4,7 @@
  * Typed wrapper over platform.call() for LLM generation.
  * Singleton export -- no credential needed (platform tool).
  *
- * Types are shared with the server-side LLM engine via @repo/core/execution.
+ * Types are shared with the server-side LLM engine and inlined for SDK consumers.
  */
 import type { LLMGenerateRequest, LLMGenerateResponse, LLMModel } from '../../types/index.js';
 type LLMProvider = 'openai' | 'anthropic' | 'openrouter' | 'google';

package/dist/worker/index.js

@@ -1,4 +1,4 @@
-import { parentPort } from 'worker_threads';
+import { workerData, parentPort } from 'worker_threads';
 import { z, ZodError } from 'zod';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
@@ -4986,14 +4986,14 @@ var acqDb = createAdapter("acqDb", [
   "getDealById",
   "getContactById",
   "getCompanyById",
-  // Deal-sync operations
+  // Deal transitions
   "updateDiscoveryData",
   "updateProposalData",
   "markProposalSent",
   "markProposalReviewed",
   "updateCloseLostReason",
   "updateFees",
-  "syncDealStage",
+  "transitionItem",
   "setContactNurture",
   "cancelSchedulesAndHitlByEmail",
   "cancelHitlByDealId",
@@ -5043,7 +5043,6 @@ var crm = createAdapter("crm", [
   "listDeals",
   "getDeal",
   "getDealByEmail",
-  "updateDealStage",
   "createDealNote",
   "listDealNotes",
   "createDealTask",
@@ -5436,5 +5435,12 @@ function startWorker(org) {
     }
   });
 }
+if (workerData != null && workerData.kind === "static") {
+  const { modulePath } = workerData;
+  void (async () => {
+    const mod = await import(modulePath);
+    startWorker(mod.default);
+  })();
+}
 
 export { PlatformToolError, acqDb, approval, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, list, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -50,7 +50,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.11.0",
+    "@repo/core": "0.13.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/claude-config/rules/agent-start-here.md

@@ -47,7 +47,7 @@ Once project continuity is resolved (or confirmed irrelevant), the template is n
 
 - `ui/` -- React frontend app and shell composition
 - `operations/` -- Elevasis SDK resources deployed to the platform
-- `foundations/` -- runtime-agnostic shared contracts and organization model adaptation
+- `core/` -- runtime-agnostic shared contracts and organization model adaptation
 - `.claude/` -- local agent rules, skills, and hooks
 - `client-workspace/` -- optional separate knowledge workspace for richer team knowledge management
 - `node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
@@ -59,7 +59,7 @@ Use this order unless a more specific doc tells you otherwise:
 1. Complete the "First Action: Check Active Projects" flow above.
 2. Read `CLAUDE.md` for project rules, command surface, and navigation pointers.
 3. Read this rule and classify the task using the Task Classes below.
-4. Read `identity.clientBrief` from the OrganizationModel (`operations/foundations/config/organization-model.ts`) for organization context and naming.
+4. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`) for organization context and naming.
 5. Read the relevant structural map:
    - Glob `node_modules/@elevasis/sdk/reference/` for published package surfaces
    - Glob `operations/resources/**` for source, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
@@ -90,7 +90,7 @@ Load first:
 - `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
 - `.claude/rules/ui.md`
 - `ui/src/routes/README.md`
-- `foundations/config/README.md`
+- `core/config/README.md`
 - `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
 
 Then inspect:
@@ -99,7 +99,7 @@ Then inspect:
 - `ui/src/config/*`
 - relevant `ui/src/routes/*`
 - relevant `ui/src/features/*`
-- `foundations/config/organization-model.ts`
+- `core/config/organization-model.ts`
 
 Verify with:
 
@@ -120,8 +120,8 @@ Then inspect:
 
 - `operations/src/index.ts`
 - relevant `operations/src/<feature>/*`
-- `foundations/types/index.ts` -- workflow input/output Zod schemas
-- `foundations/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when authoring a workflow that takes or returns these entities so the input/output schemas reference the canonical entity shapes rather than redeclaring them.
+- `core/types/index.ts` -- workflow input/output Zod schemas
+- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when authoring a workflow that takes or returns these entities so the input/output schemas reference the canonical entity shapes rather than redeclaring them.
 - `operations/elevasis.config.ts`
 
 Verify with:
@@ -136,15 +136,15 @@ Examples: rename a feature area, change quick access surfaces, map new business
 Load first:
 
 - `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
-- `foundations/config/README.md`
+- `core/config/README.md`
 - `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 - typed feature/surface constants from `@elevasis/core/organization-model` -- `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `CRM_PIPELINE_SURFACE_ID`, `LEAD_GEN_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID`. Use these typed constants instead of magic strings when overriding feature/surface IDs.
 - `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
 
 Then inspect:
 
-- `foundations/config/organization-model.ts`
-- `foundations/config/organization-model.examples.ts` -- 5 reference patterns: branding override, CRM pipeline stage customization, lead-gen lifecycle customization, resource mapping registration, custom feature declaration. Not imported anywhere -- pure reference. Start here for the override pattern when extending the org model.
+- `core/config/organization-model.ts`
+- `core/config/organization-model.examples.ts` -- 5 reference patterns: branding override, CRM pipeline stage customization, lead-gen lifecycle customization, resource mapping registration, custom feature declaration. Not imported anywhere -- pure reference. Start here for the override pattern when extending the org model.
 - `ui/src/routes/__root.tsx`
 - `ui/src/lib/hooks/useFeatureAccess.ts`
 - relevant nav config files
@@ -169,7 +169,7 @@ Then inspect:
 - `operations/src/index.ts`
 - resource definitions
 - related UI route and feature files
-- related foundations contracts
+- related core contracts
 
 Verify with:
 
@@ -203,7 +203,7 @@ Verify with:
 
 Once the request is classified, determine which boundary owns the change:
 
-- **Foundations boundary** -- semantics, aliases, labels, shared schemas
+- **Core boundary** -- semantics, aliases, labels, shared schemas
 - **UI shell boundary** -- provider composition, manifests, navigation, route ownership
 - **Operations boundary** -- deployable resource registration, workflow/agent contracts, topology
 - **Package boundary** -- public exports, shared platform behavior, reusable contracts
@@ -212,7 +212,7 @@ If a task spans boundaries, start at the semantic boundary, then move to runtime
 
 ## Main Boundaries
 
-### `foundations/config/organization-model.ts`
+### `core/config/organization-model.ts`
 
 The semantic adaptation point between platform contracts and scaffold-local terminology. Start here for feature labels, legacy aliases, quick-access surfaces, and shell-facing organization semantics.
 
@@ -239,13 +239,13 @@ If a hand-authored doc conflicts with source or published package docs, trust so
 ## Common Traps
 
 - Do not assume `operations/resources/**` is exhaustive without also checking `operations/src/index.ts` directly.
-- Do not assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from the OrganizationModel (`operations/foundations/config/organization-model.ts`).
+- Do not assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`).
 - Do not trust stable docs blindly when `.claude/rules/active-change-index.md` flags related in-progress architecture work.
 - Do not write `resume_context` into task-doc frontmatter. DB is canonical; write via `project:task:save` or the inline editor in Command Center.
 
 ## Operations-Only Projects
 
-Some projects derived from this template are operations-only. They have `operations/` (or a top-level `src/`) but NO `ui/`, NO `foundations/config/organization-model.ts`, and NO frontend. Finding none of these is not missing scaffolding -- it is by design.
+Some projects derived from this template are operations-only. They have `operations/` (or a top-level `src/`) but NO `ui/`, NO `core/config/organization-model.ts`, and NO frontend. Finding none of these is not missing scaffolding -- it is by design.
 
 **What applies:** Only Task Classes 2 (Workflow / Agent / Operations Work) and 4 (Debugging / Impact Analysis) apply to operations-only projects. Task Classes 1 (UI / Shell Work), 3 (Organization Model / Feature Access Work), and 5 (Platform Extension / Package Contract Work) do not apply and can be skipped.
 

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

@@ -1,6 +1,6 @@
 ---
 name: configure
-description: "Recurring organization model editor — layered QA flow across identity, customers, offerings, roles, goals, and techStack. Idempotent, confirm-before-overwrite. Codifies changes to foundations/config/organization-model.ts with runtime validation gate."
+description: "Recurring organization model editor — layered QA flow across identity, customers, offerings, roles, goals, and techStack. Idempotent, confirm-before-overwrite. Codifies changes to core/config/organization-model.ts with runtime validation gate."
 argument-hint: "[identity|customers|offerings|roles|goals|techStack|features|labels]"
 context: fork
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
@@ -28,7 +28,7 @@ Recurring, safe-to-re-run org model editor for external projects. Reads the orga
 
 ## Goal
 
-Keep `foundations/config/organization-model.ts` accurate and validated. Every edit proposed by this skill ends with `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` confirming the merged result is valid — and a full TypeScript type-check via `pnpm -C operations check-types` to catch static errors. If validation fails, the change is rolled back.
+Keep `core/config/organization-model.ts` accurate and validated. Every edit proposed by this skill ends with `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` confirming the merged result is valid — and a full TypeScript type-check via `pnpm -C operations check-types` to catch static errors. If validation fails, the change is rolled back.
 
 ---
 
@@ -37,7 +37,7 @@ Keep `foundations/config/organization-model.ts` accurate and validated. Every ed
 Before any domain flow, read the current organization model adapter:
 
 ```
-Read("foundations/config/organization-model.ts")
+Read("core/config/organization-model.ts")
 ```
 
 This is the single source of truth. All proposals must start from what is currently in this file, not from stale context.

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

@@ -23,7 +23,7 @@ Before collecting any information or running any steps, determine which state th
 
 **State A — Virgin (placeholders present):** One or more of the above placeholder strings is found. Run the full bootstrap flow (Steps 1–7 below), then hand off to `/configure`.
 
-**State B — Already bootstrapped, org-model at defaults:** No placeholders found, but `foundations/config/organization-model.ts` contains only the default branding override (just `branding.organizationName`, `branding.productName`, `branding.shortName` — no identity, customers, offerings, roles, goals, or techStack overrides). Print:
+**State B — Already bootstrapped, org-model at defaults:** No placeholders found, but `core/config/organization-model.ts` contains only the default branding override (just `branding.organizationName`, `branding.productName`, `branding.shortName` — no identity, customers, offerings, roles, goals, or techStack overrides). Print:
 
 ```
 This project is already set up. The organization model has not been configured yet.
@@ -32,7 +32,7 @@ Running /configure to set up your organization profile...
 
 Then execute `/configure` (the full layered flow) and stop.
 
-**State C — Fully configured:** No placeholders found AND `foundations/config/organization-model.ts` has at least one non-branding domain populated (identity, customers, offerings, roles, goals, or techStack present). Print:
+**State C — Fully configured:** No placeholders found AND `core/config/organization-model.ts` has at least one non-branding domain populated (identity, customers, offerings, roles, goals, or techStack present). Print:
 
 ```
 This project is already configured. To update your organization profile, run /configure.
@@ -145,7 +145,7 @@ If the user skipped any knowledge questions, fill in what was provided and omit
 
 ### Step 5: Write Client Brief to Org Model
 
-**Idempotency check:** Read `foundations/config/organization-model.ts` and inspect `identity.clientBrief`. If the field is already a non-empty string, skip this step entirely — do not overwrite.
+**Idempotency check:** Read `core/config/organization-model.ts` and inspect `identity.clientBrief`. If the field is already a non-empty string, skip this step entirely — do not overwrite.
 
 If the field is empty or absent, compose the client brief from the information gathered in Step 2:
 
@@ -171,12 +171,12 @@ Here's the client brief I'll write into identity.clientBrief:
 Write this? (yes/no)
 ```
 
-On confirmation, use the Edit tool to replace the `clientBrief: ''` value in `foundations/config/organization-model.ts` with a template literal containing the composed markdown. Use a regular string (backtick or single-quoted multi-line) — ensure the closing quote and trailing comma are correct TypeScript.
+On confirmation, use the Edit tool to replace the `clientBrief: ''` value in `core/config/organization-model.ts` with a template literal containing the composed markdown. Use a regular string (backtick or single-quoted multi-line) — ensure the closing quote and trailing comma are correct TypeScript.
 
 After the edit, run:
 
 ```bash
-pnpm -C foundations check-types
+pnpm -C core test
 ```
 
 If type-check fails, report the error and do not proceed to Step 6 until it is resolved.
@@ -258,7 +258,7 @@ Running `/setup` more than once is safe:
 - **Placeholder replacement** only runs when placeholders are detected (State A). It is skipped entirely in States B and C.
 - **CLAUDE.md knowledge sections** (`{CLIENT_CONTEXT}`, `{USER_PREFERENCES}`) are checked before writing. If already replaced, the write is skipped.
 - **`identity.clientBrief`** is only written when the field is empty. A non-empty field is never overwritten by `/setup`. The write uses a read → propose → confirm ceremony before touching the file.
-- **All other org-model fields** (`foundations/config/organization-model.ts`) are never written by `/setup`. All other org-model edits go through `/configure`, which has its own diff-preview and confirm ceremony.
+- **All other org-model fields** (`core/config/organization-model.ts`) are never written by `/setup`. All other org-model edits go through `/configure`, which has its own diff-preview and confirm ceremony.
 
 ---
 

package/reference/claude-config/sync-notes/2026-04-25-auth-role-system-and-settings-roles.md

@@ -0,0 +1,55 @@
+# Auth Role System And Settings Roles
+
+## Why this note exists
+
+The Org OS default surface now includes `settings.roles` at `/settings/roles`. Template-derived projects that update to the matching `@elevasis/core` release will receive the Settings navigation entry, so the template now ships a self-view route for members to see their current role and effective permission groups.
+
+This route depends on the published `@elevasis/ui` provider/layout/auth exports that the template already uses, plus the backend role and permission endpoints introduced by the same release train. The release train also publishes reusable role hooks and primitives for custom app code that wants the richer role-management surfaces.
+
+## Applies to
+
+All template-derived projects that sync from `external/_template` and update to the auth role system release train.
+
+This is especially relevant for projects that expose the default Settings navigation from `@elevasis/core` organization-model surfaces or run a project-local organization model derived from those defaults.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` so `ui/src/routes/settings/roles.tsx` is available.
+2. Update project packages after the release train is published:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui --latest
+```
+
+3. Confirm the project API target is deployed to a backend version that includes the auth role endpoints used by the published UI hooks:
+
+- `GET /permissions/catalog`
+- `GET /memberships/my-permissions/:orgId`
+- role-management endpoints under `/organizations/:orgId/roles`
+- membership role and effective-permission endpoints under `/memberships/:membershipId`
+
+4. Rebuild any project-local route tree artifacts if your project does not regenerate TanStack Router routes during normal dev/build startup.
+
+## Verification
+
+Run from the project root after package updates and backend deployment:
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+```
+
+Then sign in to the UI, open `/settings/roles`, and verify:
+
+- the page is protected for authenticated organization members,
+- the current membership role badge is visible,
+- grouped effective permissions render,
+- permission descriptions load from the catalog endpoint,
+- no Settings navigation item points to a missing route.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not publish or upgrade `@elevasis/core` or `@elevasis/ui`.
+- `/git-sync` does not deploy the API/backend version that serves the role and permission endpoints.
+- `/git-sync` does not reconcile project-owned organization-model overrides that intentionally remove or rename Settings surfaces.
+- `/git-sync` does not validate downstream auth state, role assignments, or production API connectivity.

package/reference/claude-config/sync-notes/2026-04-27-crm-hitl-action-layer-cutover.md

@@ -0,0 +1,101 @@
+# CRM HITL Action Layer Cutover
+
+## Why this note exists
+
+The Elevasis platform completed an atomic cutover of `acq_deals` from the legacy `cached_stage` + `proposal_status` model to the canonical `pipeline_key` / `stage_key` / `state_key` runtime fields. The release train that ships this cutover bumps `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` together, and rewires server-side lifecycle to flow through a single `transitionItem()` boundary in the API.
+
+Concretely, this train introduces:
+
+- a flat `ActivityEventSchema` discriminated union on `@elevasis/core/business/acquisition` (replaces the older `DealActivityEntry` shape; activity rows now use fields like `stageBefore`, `stageAfter`, `stateBefore`, `stateAfter`, `taskId`, `timestamp`)
+- a pure `deriveActions(deal)` helper on `@elevasis/core/business/acquisition` (UI/API action derivation from current deal state)
+- new typed CRM hooks on `@elevasis/ui` (`useTransitionItem`, refreshed `useSyncDealStage`, kanban + deal-drawer wiring)
+- canonical `transitionItem(dealId, organizationId, pipelineKey, stageKey, stateKey?, reason?, expectedUpdatedAt?)` as the single lifecycle mutation; server-side it appends activity, supersedes open command-queue rows, and closes incompatible tasks atomically
+- a `command_queue`-backed HITL transport supersession lifecycle resolved by `resolveDealCommandQueue` (called inside `transitionItem`)
+
+Derived projects that read or write `acq_deals` directly, render the CRM kanban from `@elevasis/ui`, or import acquisition types from `@elevasis/core` will pick up these contract changes when they upgrade through this train.
+
+## Applies to
+
+All template-derived projects that:
+
+- consume `@elevasis/core/business/acquisition` types (`Deal`, `ActivityEvent`, action types) or import `deriveActions`
+- render the CRM kanban / deal drawer surfaces from `@elevasis/ui`
+- have a project-local `acq_deals` table that mirrors the platform schema
+- author workflows under `operations/src/sales/crm/**` that call `acqDb.transitionItem(...)` (or formerly called `syncDealStage` / direct stage writes)
+- read `activity_log` rows on deals and pattern-match on event shape
+
+Operations-only projects with no CRM surface and no `acq_deals` table can ignore this train.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` so the refreshed CRM hook + drawer/kanban consumers are available.
+
+2. After the release train is published, update package versions in the project:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
+```
+
+3. If your project has a project-local `acq_deals` table, run the matching atomic cutover migration. The reference SQL lives in the monorepo at `apps/docs/content/docs/in-progress/active-development/sdk-changes/org-model/_sql/`:
+   - `00_preflight_org_model_cutover.sql`
+   - `01_cleanup_known_cutover_outliers.sql`
+   - `02_acq_deals_atomic_cutover.sql`
+   - `03_postflight_org_model_cutover.sql`
+
+   The cutover is single-shot, not dual-write. Backfill `pipeline_key` / `stage_key` from `cached_stage` and drop the legacy columns in the same transaction. There is no mid-flight rollback path; fix-forward only. Confirm prod deal volume is small enough to accept that tradeoff before applying.
+
+4. Replace any direct stage writes with `acqDb.transitionItem(...)`:
+   - workflow code that previously called `syncDealStage`, `updateDeal({ cached_stage: ... })`, or wrote `proposal_status` directly must now route through `transitionItem`
+   - the API server injects `organizationId` from execution context — never pass `organizationId` from worker payload
+   - the platform-side method appends `ActivityEventSchema`-shaped events; do NOT also write activity rows from the workflow side
+
+5. If you read `activity_log` and pattern-match by `type`, update consumers to the flat schema:
+
+```ts
+// Stage change
+{ type: 'stage_change', timestamp, stageBefore, stageAfter, reason? }
+
+// State change
+{ type: 'state_change', timestamp, stateBefore, stateAfter, reason? }
+
+// Task created
+{ type: 'task_created', timestamp, taskId }
+
+// Approval resolved (written by resolveDealCommandQueue)
+{ type: 'approval_resolved', timestamp, ... }
+```
+
+The legacy `{ type, title, payload, occurredAt }` envelope is gone.
+
+6. If your project deploys SDK resources, redeploy `operations` after the package upgrades so workers pick up the new typed adapter surface and ToolMap entries:
+
+```bash
+pnpm -C operations exec elevasis-sdk deploy --prod
+```
+
+## Verification
+
+Run from the project root after package updates and any DB migration:
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+pnpm -C operations check-types
+pnpm -C operations exec elevasis-sdk check
+```
+
+Then exercise the CRM surface:
+
+- open the deal kanban — drag a deal between stages; confirm the activity log shows a flat `stage_change` event with `stageBefore` / `stageAfter`
+- open a deal drawer — confirm available actions render from `deriveActions(deal)` and not from a stored `available_actions` array
+- if you have a HITL approval surface, confirm that completing or superseding an approval lands an `approval_resolved` activity event before any subsequent state change
+
+If a workflow that historically wrote stage updates throws Zod errors against `ActivityEventSchema`, it is still on the legacy envelope — fix-forward by routing it through `acqDb.transitionItem(...)`.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not publish or upgrade `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
+- `/git-sync` does not run the project-local `acq_deals` cutover migration. The DB cutover is atomic and irreversible — only the project owner can authorize it.
+- `/git-sync` does not redeploy the project's `operations` bundle to dev or prod.
+- `/git-sync` does not rewrite project-owned workflow code that bypasses `transitionItem` to write stage / state directly.
+- `/git-sync` does not reconcile project-owned `activity_log` consumers that still pattern-match on the legacy `DealActivityEntry` envelope.

package/reference/cli.mdx

@@ -537,9 +537,12 @@ elevasis-sdk project:delete <id>
 elevasis-sdk project:milestone:list --project <id>
 elevasis-sdk project:milestone:create --project <id> --name "Phase 1"
 elevasis-sdk project:milestone:update <id> --status completed
+elevasis-sdk project:milestone:update <id> --description "Updated scope description"
 elevasis-sdk project:milestone:delete <id>
 ```
 
+`project:milestone:update` accepts `--description` to set or clear the milestone description. Passing an empty string clears the field, matching `project:task:update --description` semantics.
+
 ### Tasks
 
 ```bash
@@ -566,10 +569,42 @@ elevasis-sdk project:task:save <id> --current-state "Implemented the route layer
 ```bash
 elevasis-sdk project:note:list --project <id>
 elevasis-sdk project:note:create --project <id> --content "Client approved scope"
+elevasis-sdk project:note:create --project <id> --type agent_learning --content "Learned X"
 elevasis-sdk project:note:update <id> --content "Updated status"
 elevasis-sdk project:note:delete <id>
 ```
 
+The `--type` flag accepts: `call_note`, `status_update`, `issue`, `blocker`, `agent_learning`. The `agent_learning` type is the canonical way for agents to record durable skill observations. Accepted values are derived from `NoteTypeSchema` in `packages/core/src/projects/api-schemas.ts` -- that schema is the source of truth; the CLI help text is generated from it to prevent drift.
+
+### Requests
+
+```bash
+elevasis-sdk request:submit --input-file ./tmp/request-report.json
+elevasis-sdk request:submit --input '{"type":"bug","category":"sdk","severity":"high","title":"..."}'
+```
+
+Submits a structured request report to `POST /api/external/requests`. The payload is validated against `CreateRequestInputSchema` before the network call.
+
+**Payload enum values** (inline in `--help` output; sourced from `packages/core/src/requests/api-schemas.ts`):
+
+| Field      | Accepted values                                                                       |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `type`     | Values from `RequestTypeEnum` -- see `request:submit --help` for the current list     |
+| `category` | Values from `RequestCategoryEnum` -- see `request:submit --help` for the current list |
+| `severity` | Values from `RequestSeverityEnum` -- see `request:submit --help` for the current list |
+
+**Flags:**
+
+| Flag                        | Description                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `-i, --input <json>`      | Request body as JSON string                                                   |
+| `-f, --input-file <path>` | Read body from a JSON file; relative paths resolve against the project root   |
+| `--pretty`                  | Human-readable output instead of raw JSON                                     |
+| `--cleanup-input`           | Delete the input file after success (only files under `<projectRoot>/tmp/`) |
+| `--api-url <url>`         | Override the API base URL                                                     |
+
+---
+
 ### Shared Flags
 
 Most `project:*` commands support:
@@ -590,6 +625,28 @@ For exact required flags and accepted enum values, see the command source under
 
 ---
 
+## elevasis-sdk ui:use-local / ui:use-published
+
+Switch the `@elevasis/ui` dependency in an external project between a local tarball build and the published npm package.
+
+**Synopsis:**
+
+```bash
+elevasis-sdk ui:use-local
+elevasis-sdk ui:use-published
+```
+
+**Behavior:**
+
+- `ui:use-local` -- builds a tarball from the local `packages/ui/` source and rewrites the project's `package.json` to point at the tarball path. Use this during active `@elevasis/ui` development to test changes without publishing.
+- `ui:use-published` -- reverts `package.json` to the published `@elevasis/ui` version string and removes any local tarball reference.
+
+Both commands install after rewriting `package.json`. The `external/_template` root scripts `ui:use-local` and `ui:use-published` are compatibility wrappers that delegate to these CLI commands.
+
+**Implementation:** `packages/sdk/src/cli/commands/ui/ui-switcher.ts`
+
+---
+
 ## Global Flags
 
 These flags are accepted by all commands:

package/reference/examples/organization-model.ts

@@ -1,3 +1,6 @@
+// @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT
+// Regenerate: pnpm scaffold:sync
+
 // Pure reference file -- NOT imported anywhere.
 // Copy individual examples into core/config/organization-model.ts or resource definitions as needed.
 

package/reference/packages/core/src/organization-model/README.md

@@ -66,6 +66,7 @@ features: [
 ```
 
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+Development-only features remain in the contract with `enabled: true` and `devOnly: true`; shell consumers hide them and guard their paths outside development mode.
 
 ## Graph IDs
 

package/reference/scaffold/core/organization-graph.mdx

@@ -2,6 +2,9 @@
 title: Organization Graph
 description: Organization OS graph layer documentation for the organization graph derived from flat Organization Model features and resource metadata links.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 ## Overview
 
@@ -25,10 +28,10 @@ Node kinds:
 
 - `organization`
 - `feature`
+- `surface`
 - `entity`
 - `capability`
 - `resource`
-- `integration`
 
 Edge kinds:
 
@@ -62,7 +65,7 @@ interface BuildOrganizationGraphInput {
 `buildOrganizationGraph`:
 
 1. Reads flat Organization Model features and derives `feature:*` nodes.
-2. Reads entities, capabilities, integrations, and resources.
+2. Reads Command View resources, including integration resources, as `resource` nodes with `resourceType` metadata.
 3. Emits authored graph links from resource/entity/capability metadata.
 4. Bridges Command View runtime topology into resource nodes and relationship edges.
 5. Returns a renderer-agnostic DTO.

package/reference/scaffold/core/organization-model.mdx

@@ -2,6 +2,9 @@
 title: Organization Model
 description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource graph links, and curated @elevasis/core public API.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 ## Overview
 
@@ -67,6 +70,9 @@ Authored fields:
 - `devOnly`
 
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
+
+Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `operations.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
 ## Graph IDs and Resource Links
 

package/reference/scaffold/index.mdx

@@ -2,6 +2,9 @@
 title: Scaffold Reference
 description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 ## Overview
 

package/reference/scaffold/operations/propagation-pipeline.md

@@ -2,6 +2,9 @@
 title: Propagation Pipeline
 description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Propagation Pipeline
 
@@ -99,7 +102,7 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
 | `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
-| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `defineOrganizationModel` + `resolveOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `ElevasisUIProvider`, all 3 CSS subpath imports present |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `createFoundationOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
 | `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
 | `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
 | `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -2,6 +2,9 @@
 title: Scaffold Maintenance
 description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Scaffold Maintenance