@elevasis/sdk 1.8.2 → 1.9.0

package/reference/claude-config/sync-notes/2026-04-22-lead-gen-deliverability-removal.md

@@ -0,0 +1,30 @@
+# Lead Gen Deliverability Page Removal
+
+## Why this note exists
+
+`LeadGenDeliverabilityPage` has been removed from the published `@elevasis/ui` package. The deliverability route and sidebar nav item were removed from the shared lead-gen surface. Template-derived projects that still import or route to this page will fail to compile after pulling this train.
+
+## Applies to
+
+All template-derived projects that use the lead-gen feature and have a `ui/src/routes/lead-gen/deliverability.tsx` route file or a deliverability entry in their lead-gen sidebar.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+1. Delete `ui/src/routes/lead-gen/deliverability.tsx` — this file is completely removed (no redirect replacement).
+2. Remove the deliverability nav item from any project-local lead-gen sidebar overrides that reference it by ID or label.
+3. Remove any import of `LeadGenDeliverabilityPage` from route trees, lazy-loaded chunks, or custom page wrappers.
+4. Regenerate the TanStack Router route tree (`pnpm -C ui exec tsr generate` or equivalent) after removing the route file so the generated routeTree no longer references the deleted route.
+5. Run `pnpm -C ui build` to confirm the build is clean.
+
+## Verification
+
+- `pnpm -C ui build` passes with no import or route errors.
+- Navigating to `/lead-gen` works; navigating to `/lead-gen/deliverability` either 404s or redirects as expected by the project's router config.
+
+## Not handled by /git-sync
+
+- `/git-sync` pulls the template source change (removal of `deliverability.tsx` from `_template/ui/src/routes/lead-gen/`), but it does not automatically delete project-owned route files that still import `LeadGenDeliverabilityPage`.
+- Any project-local sidebar override that hard-references the deliverability nav entry must be manually cleaned up.
+- The route tree regeneration step must be run manually after route file removal.

package/reference/claude-config/sync-notes/2026-04-24-ui-consolidation-and-sdk-cli-train.md

@@ -0,0 +1,86 @@
+# UI Consolidation And SDK CLI Train
+
+## Why this note exists
+
+This release train combines three changes that affect derived projects after `pnpm up`:
+
+1. `@elevasis/ui` 2.18.x consolidates previously-duplicated template surface (hooks, components, constants, utilities, test-utils, org-model examples) into the published package. Files that lived in `_template/ui/src/lib/**`, `_template/ui/src/test-utils/**`, and `_template/scripts/use-*-ui.mjs` are deleted from the template and re-exported from `@elevasis/ui`. A `useDeleteRequest` hook and a rollup dts fix also land in this `@elevasis/ui` version.
+2. `@elevasis/sdk` hardens project-root and CWD resolution in the `elevasis-sdk` CLI. Unsupported invocation directories now fail fast with a clear error instead of silently using `process.cwd()`.
+3. `@elevasis/sdk` + `@elevasis/core` + `@elevasis/ui` close three `project:*` / `request:submit` CLI gaps: `--description` on `project:milestone:update`, `agent_learning` note-type enum alignment between `/project` skill docs and the server, and enum values surfaced in `request:submit --help`.
+
+## Applies to
+
+All template-derived projects that:
+
+- import from `@elevasis/ui` (nearly all of them),
+- run the `elevasis-sdk` CLI from any project directory (all of them),
+- invoke `project:milestone:update`, `project:note:create --type agent_learning`, or `request:submit`.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+### Step 1 -- Pull the train via `/git-sync`
+
+`/git-sync` surfaces this note and applies template-source changes (deletions of `ui/src/lib/**`, `ui/src/test-utils/**`, `scripts/use-*-ui.mjs`).
+
+### Step 2 -- Update package dependencies
+
+Run from project root:
+
+```
+pnpm up @elevasis/ui @elevasis/core @elevasis/sdk --latest
+```
+
+Dep bumps are already written into `_template/ui/package.json` and `_template/operations/package.json` by the release train.
+
+### Step 3 -- Replace inlined type defs with package imports
+
+Projects that copied the Phase-1 workaround carry six inlined symbols in `ui/src/lib/platform-utils.ts` that should now come from `@elevasis/ui`:
+
+- `CredentialSchema`, `CredentialField`, `OAuthProviderConfig`, `OAuthToken`, `OAuthState` -> `@elevasis/ui/types`
+- `DOMAIN_MAP` -> `@elevasis/ui/utils`
+
+Delete the inlined copies and replace with named imports from the appropriate subpaths. After the edit, `ui/src/lib/platform-utils.ts` should only contain Elevasis-specific symbols and the new imports.
+
+### Step 4 -- Re-verify `elevasis-sdk` invocations
+
+From any dir you routinely invoke the SDK CLI, run:
+
+```
+pnpm exec elevasis-sdk doctor
+```
+
+If the command fails with a "no `.elevasis` marker reachable" error, re-run from a supported directory (project root, `operations/`, or any nested path under a valid project). Previously-silent misfires now surface as hard errors; this is intentional.
+
+### Step 5 -- Audit `project:note:create --type agent_learning` call sites
+
+If any project scripts or agent prompts call `project:note:create --type agent_learning`, verify they match the server enum decision (the train either adds `agent_learning` to the enum or strips it from `/project` skill docs -- check the landed behavior in `pnpm exec elevasis-sdk project:note:create --help` and in the project's synced `/project` SKILL).
+
+### Step 6 -- Rebuild and type-check
+
+Run from project root:
+
+```
+pnpm -C ui build
+pnpm -C ui exec tsc --noEmit
+pnpm -C operations exec tsc --noEmit
+```
+
+All three must pass before the update is complete.
+
+## Verification
+
+- `pnpm up` completes cleanly.
+- `ui/src/lib/platform-utils.ts` contains no inlined `CredentialSchema | CredentialField | OAuthProviderConfig | OAuthToken | OAuthState | DOMAIN_MAP` definitions -- only imports from `@elevasis/ui`.
+- `pnpm -C ui exec tsc --noEmit` passes with no missing-module errors for `@elevasis/ui/hooks`, `@elevasis/ui/components`, `@elevasis/ui/constants`, `@elevasis/ui/utils`, `@elevasis/ui/test-utils`.
+- `pnpm exec elevasis-sdk doctor` reports project root correctly from the directories you use.
+- `pnpm exec elevasis-sdk project:milestone:update --help` lists `--description`.
+- `pnpm exec elevasis-sdk request:submit --help` shows enum values for `--type`, `--category`, `--severity`.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not run `pnpm up` -- Step 2 is manual.
+- `/git-sync` does not rewrite project-owned `ui/src/lib/platform-utils.ts` -- the inlined-to-imports swap in Step 3 is manual per project.
+- `/git-sync` does not validate SDK CLI behavior from project terminals -- Step 4 verification is manual.
+- Any project-local override that hard-references the deleted `_template/ui/src/lib/**` paths must be cleaned up manually.

package/reference/claude-config/sync-notes/README.md

@@ -0,0 +1,43 @@
+# Sync Notes
+
+Template-owned downstream migration guidance lives in this directory.
+
+## File Contract
+
+- Operative note files must be named `YYYY-MM-DD-<slug>.md`
+- `README.md` explains the contract and is ignored by `/git-sync`
+- Notes are append-only. Add a new dated file for each downstream-affecting release train instead of rewriting an older note
+
+## When A Note Is Mandatory
+
+Add a new operative note whenever a train affects derived projects beyond a normal pull, install, and baseline verify. Common triggers:
+
+- template dependency-baseline changes
+- scaffold or sync-contract changes
+- rename or migration work
+- verifier or behavior changes that downstream maintainers need to understand
+- any release train that will ask maintainers to do manual follow-up after pulling
+
+## Required Sections
+
+Every operative note must include these exact headings:
+
+## Why this note exists
+
+Explain what changed and why downstream maintainers are seeing this note.
+
+## Applies to
+
+State which projects, app modes, or versions need the follow-up.
+
+## Required actions
+
+List the manual work maintainers need to do after `/git-sync`.
+
+## Verification
+
+List the commands or flows that confirm the migration landed correctly.
+
+## Not handled by /git-sync
+
+Call out what remains manual so maintainers do not assume the pull/install/verify flow reconciled everything.

package/reference/deployment/index.mdx

@@ -12,16 +12,50 @@ Deploying your resources makes them live on the Elevasis platform and immediatel
 
 When you run `elevasis-sdk deploy`, the CLI performs these steps in order:
 
-1. **Authenticate** -- calls the API with your `ELEVASIS_PLATFORM_KEY` to verify credentials and resolve your organization name
-2. **Validate** -- runs your `src/index.ts` through `ResourceRegistry`, catching the same errors as the platform
-3. **Bundle** -- uses esbuild to produce a single self-contained `dist/bundle.js` file (~50-200 KB) containing your code and all dependencies
-4. **Upload** -- sends the bundle and resource metadata to the platform via `POST /api/external/deploy`
-5. **Go live** -- the platform registers your resources; they are immediately available for execution
+1. **Preflight** -- verifies a `.elevasis` marker is reachable from the current directory, that `.env` exists at the project root, and that `ELEVASIS_PLATFORM_KEY` is set. Fails before any side effect if any check fails.
+2. **Authenticate** -- calls the API with your `ELEVASIS_PLATFORM_KEY` to verify credentials and resolve your organization name
+3. **Validate** -- runs your `src/index.ts` through `ResourceRegistry`, catching the same errors as the platform
+4. **Bundle** -- uses esbuild to produce a single self-contained `dist/bundle.js` file (~50-200 KB) containing your code and all dependencies
+5. **Upload** -- sends the bundle and resource metadata to the platform via `POST /api/external/deploy`
+6. **Go live** -- the platform registers your resources; they are immediately available for execution
 
 There is no local dev server and no separate staging environment. Deployed resources run directly on the platform. Local testing uses `tsc --noEmit` and Vitest with direct handler calls.
 
 ---
 
+## Invocation CWD
+
+`elevasis-sdk` is valid from **any subdirectory inside a valid project**. Two separate anchors govern path resolution:
+
+- **Preflight / auth / env** -- anchors on the `.elevasis` project root, found by walking up from the invocation directory. If no `.elevasis` marker is reachable, the CLI exits non-zero before running the command.
+- **Build commands** (`deploy`, `check`) -- anchor on the **nearest `package.json`** (the package root). Bundle outputs land in that package's `dist/`, not the project root. The default entry point (`./src/index.ts`) also resolves from the package root.
+
+**Single-package project** (e.g. `external/acme/`): both anchors resolve to the same directory. Invoke from anywhere inside the project tree.
+
+**Multi-package workspace** (e.g. `external/elevasis/` with `operations/` as a sub-package):
+
+```bash
+# Invoke from operations/ or any subdir inside it
+pnpm -C external/elevasis/operations exec elevasis-sdk deploy
+
+# Both CWDs work identically:
+#   .elevasis root  -> external/elevasis/            (auth / .env)
+#   package root    -> external/elevasis/operations/  (bundle, dist/)
+#   bundle output   -> external/elevasis/operations/dist/bundle.js
+```
+
+Each package in a workspace produces its own `dist/bundle.js` when deployed. Run `elevasis-sdk deploy` from within each package separately.
+
+**Running outside a valid project** produces a hard failure before any network call:
+
+```
+Not inside an Elevasis project. Run from a directory under one containing `.elevasis`.
+```
+
+The only commands that bypass preflight are `--help` / `-h` / `--version` / `-V`.
+
+---
+
 ## Running a Deploy
 
 ```bash
@@ -108,7 +142,7 @@ The CLI also accepts a `--api-url` flag on every command, which takes priority o
 ELEVASIS_PLATFORM_KEY=sk_***
 ```
 
-Place `.env` in your project root. The CLI walks up directories to find it, so running from subdirectories like `operations/` works automatically. Never commit this file.
+Place `.env` in your project root (the directory containing `.elevasis`). The CLI walks up directories to find both the `.elevasis` marker and the `.env` file, so running from subdirectories like `operations/` works automatically. Never commit this file.
 
 ---
 
@@ -154,7 +188,8 @@ The bundle is stored on the platform for durability and restart recovery. If the
 - [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
 - [Provided Features](provided-features.mdx) - Shared Lead Gen, CRM, Projects, and feature-shell surfaces for downstream apps and agents
 - [Execution API](api.mdx) - REST endpoints for executing resources and managing deployments
+- [UI Execution](ui-execution.mdx) - Custom React run dialogs, forms, and hooks for triggering resource executions
 
 ---
 
-**Last Updated:** 2026-04-15
+**Last Updated:** 2026-04-23