@elevasis/sdk 1.37.0 → 1.39.0

package/reference/claude-config/skills/tutorial/technical.md

@@ -59,7 +59,7 @@ why the scaffold is described as an agent operating environment, not just an app
 **Estimated time:** 15 min
 
 **Files referenced:** `.claude/rules/agent-start-here.md`, `CLAUDE.md`,
-`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
 
 **Flow:**
 
@@ -101,7 +101,7 @@ across sessions). The scaffold is not just an app starter; the agent reads `.cla
 every session and uses it to route task classes, resolve boundaries, and choose the right tool.
 
 **SDK reference scaffold.** After `pnpm install`, the entry point
-`node_modules/@elevasis/sdk/reference/scaffold/index.mdx` gives access to canonical recipes, UI
+`operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` gives access to canonical recipes, UI
 patterns, the gating model, contracts, and a glossary. Whenever the user wants the authoritative
 answer on a scaffold surface (how to add a System or UI feature, extend an entity, wire a workflow), that
 index is the starting point.
@@ -431,7 +431,7 @@ and knows how to create a credential in Command Center.
 **Estimated time:** 20 min
 
 **Files referenced:** `.claude/skills/elevasis/SKILL.md` (creds section),
-`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -493,7 +493,7 @@ how data flows between steps.
 
 **Estimated time:** 25 min
 
-**Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
+**Files referenced:** `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
 `apps/docs/content/docs/sdk/sdk/concepts.mdx` (design decisions section)
 
 **Flow:**
@@ -828,7 +828,7 @@ full lifecycle through Command Queue.
 **Estimated time:** 25 min
 
 **Files referenced:** `.claude/rules/error-handling.md`,
-`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -878,7 +878,7 @@ uses the `scheduler` singleton inside a workflow, and knows the cron syntax the
 
 **Estimated time:** 20 min
 
-**Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+**Files referenced:** `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -922,7 +922,7 @@ adapter using a credential from the project's identity.
 **Estimated time:** 25 min
 
 **Files referenced:** `.claude/skills/elevasis/SKILL.md` (credentials section),
-`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -981,7 +981,7 @@ try/catch with retryable vs permanent error distinction.
 **Estimated time:** 20 min
 
 **Files referenced:** `.claude/rules/error-handling.md`,
-`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -1043,7 +1043,7 @@ result) and understands when to use an agent definition vs a workflow definition
 
 **Estimated time:** 25 min
 
-**Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
+**Files referenced:** `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
 `apps/docs/content/docs/sdk/sdk/concepts.mdx` (workflow vs agent section)
 
 **Flow:**
@@ -1107,7 +1107,7 @@ value. The type system confirms the result matches the schema without a cast.
 **Estimated time:** 20 min
 
 **Files referenced:** `operations/src/index.ts`,
-`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
 
 **Flow:**
 
@@ -1290,7 +1290,7 @@ following closing script:
 > - **Build real automations.** You now have the full surface: workflows, schemas, HITL, schedules,
 >   LLM integration, error handling, and composition. Start with the domain most relevant to your
 >   project and use `/project create` to track the work.
-> - **SDK reference scaffold.** `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` is the
+> - **SDK reference scaffold.** `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` is the
 >   canonical recipe index for anything you want to build: adding a System or UI feature, extending lead-gen,
 >   customizing CRM actions, authoring agents. Read it whenever you are starting something new.
 > - **Explore the codebase.** `/explore` is your tool for open-ended questions about how things

package/reference/claude-config/sync-notes/2026-06-25-shared-page-scroll-contract-guard.md

@@ -0,0 +1,52 @@
+# Shared Full-Height Page Scroll Contract + Canonical headerActions Pattern
+
+## Why this note exists
+
+`@elevasis/ui` (>= 2.61.2) hardens the shared full-height page scroll contract and
+the template now demonstrates the safe customization pattern for it.
+
+- `SubshellContentContainer` (the root of the lead-gen list-detail, CRM/delivery/
+  clients detail pages, etc.) is a `flex:1 / overflowY:auto / minHeight:0` scroll
+  container that only bounds correctly as a **direct flex child** of the shell's
+  height-bounded region. Wrapping a shared page in a layout element (e.g. a Mantine
+  `<Stack>`, which is `flex:0 1 auto` with no `min-height:0`) breaks the height
+  chain: the page balloons to content height and its internal scroll never engages.
+- The package now ships a **dev-only runtime guard** that logs a console warning when
+  it detects an unbounded `SubshellContentContainer`, so this mistake is caught while
+  authoring a route instead of shipping a silently broken page. No-op in production.
+- The template `lead-gen/lists.$listId.tsx` now injects a `ListExportButton` through
+  the page's **`headerActions` slot** (not a wrapper) as the canonical reference for
+  customizing a shared full-height page.
+
+## Applies to
+
+- All template-derived projects that render shared full-height pages
+  (`LeadGenListDetailPage`, CRM/delivery/clients detail pages).
+- Any project that wrapped a shared page in a `<Stack>` (or similar) to bolt on
+  extra UI -> that page's scroll is broken; switch to the page's slot props.
+
+## Required actions
+
+- Bump `@elevasis/ui` to `^2.61.2` (or later) and install. (The ship train's
+  `external-sync` stage does this automatically via the package-cascade baseline;
+  manual `pnpm update` is not required.)
+- If any route wraps a shared full-height page, remove the wrapper and pass the
+  extra UI through the page's slot props (`headerActions` / `tabs` / `footer`). The
+  template `lead-gen/lists.$listId.tsx` is the canonical reference.
+- Heed the new dev console warning if it appears; do not silence it.
+
+## Verification
+
+- `pnpm -C ui check-types` passes against `@elevasis/ui@^2.61.2`.
+- Open a shared detail page (e.g. `/lead-gen/lists/:listId`): the page scrolls
+  internally, the bottom is reachable, and no scroll-contract console warning fires.
+- Wrapping the page in a `<Stack>` produces the dev warning (negative check).
+
+## Not handled by /git-sync
+
+- `/git-sync` surfaces this note and pulls the template `lists.$listId.tsx` +
+  `ListExportButton` baseline, but a diverged tenant copy is preserved
+  (merge-managed) -- you must manually remove any page wrapper and adopt the slot
+  pattern.
+- The dev guard ships inside `@elevasis/ui`; no tenant source change is required to
+  receive it beyond the dependency-baseline bump.

package/reference/claude-config/sync-notes/2026-06-26-leadgen-overview-om-telemetry.md

@@ -0,0 +1,47 @@
+# Lead Gen Overview — OM-derived telemetry (NaN fix)
+
+## Why this note exists
+
+The published `@elevasis/ui` Lead Gen **Overview** page previously hardcoded the
+pre-migration canonical pipeline stage keys (`populated, extracted, qualified,
+discovered, verified, personalized, uploaded`) in its telemetry reducer. Any tenant
+whose Organization Model declares a different stage set got `undefined` stage reads
+and rendered `NaN` in the header and the **Ready Contacts** stat card.
+
+`@elevasis/ui@2.62.0` (paired with `@elevasis/core@0.54.0`) makes the Overview render
+generically over the OM-declared stage catalog. Telemetry now derives entirely from
+`getLeadGenStageCatalog()` + `ListTelemetry.stageCounts`; an absent stage contributes
+`0`, never `NaN`. The "ready / next focus" backlog moved from hardcoded
+`personalized − uploaded` to a declared OM descriptor.
+
+## Applies to
+
+- Every template-derived project that consumes `@elevasis/ui` for the Lead Gen
+  Overview surface and whose pipeline diverges from the old canonical stage set.
+- This is a **package-cascade-only** change: no template SOURCE edits are required.
+  The fix is bundled in the published packages; tenants only need the new baselines.
+
+## Required actions
+
+- Take the dependency baseline bump propagated by this train:
+  - `@elevasis/core` → `0.54.0`
+  - `@elevasis/ui` → `2.62.0`
+- Reinstall so the new bundles are live (`pnpm install` in the project's `ui/`
+  workspace) and clear any stale Vite optimize cache
+  (`node_modules/.vite`) before restarting a running dev server.
+
+## Verification
+
+- After the baseline bump + install, open the Lead Gen Overview for a list on a
+  divergent pipeline: the header summary and the three stat cards render finite
+  numbers, with no `NaN` and no reference to retired stages.
+- `pnpm sync:verify -- <project>` confirms the project is on the new baselines.
+
+## Not handled by /git-sync
+
+- **Optional OM authoring (tenant-owned, NOT shipped here):** a tenant MAY declare
+  `readinessTarget: true` on one stage in its `core/config/organization-model.ts`
+  stage catalog to restore a semantic "Ready: \<stage\>" stat. Until declared, the UI
+  correctly falls back to a generic last-incomplete-stage backlog. This is an
+  enhancement done via a separate `/om` cycle, never auto-propagated.
+- The visual confirmation that `NaN` is gone on a running tenant page (a human check).

package/reference/claude-config/sync-notes/2026-07-21-agent-scaffold-hardening.md

@@ -0,0 +1,75 @@
+# Agent Scaffold Hardening — deploy default, rule paths, ownership split
+
+## Why this note exists
+
+Three corrections in this train change guidance agents were previously following
+incorrectly. The first is safety-relevant and is the reason this note exists.
+
+**1. Plain `deploy` targets PRODUCTION, not dev.** `resolveApiUrl` in the SDK CLI
+falls through to `https://api.elevasis.io` unless `NODE_ENV === 'development'` is
+set. The template `CLAUDE.md` Commands table and the bundled `deployment.md` both
+stated that plain `deploy` targeted dev. Both were wrong, and every derived project
+inherited the wrong statement. The full resolution order is now documented:
+`--api-url` > `--prod` > `ELEVASIS_API_URL` > `NODE_ENV === 'development'` >
+production fallthrough. `resolveApiKey` follows a separate rule and is documented
+alongside it.
+
+If your project has no `NODE_ENV=development` in its environment, it has **no
+working dev target** — `deploy` and `deploy:prod` resolve to the same production
+API. Verify before your next deploy rather than assuming.
+
+**2. Bundled rule paths were wrong fleet-wide.** Every drill-down pointer said
+`node_modules/@elevasis/sdk/reference/...`. The SDK actually installs at
+`operations/node_modules/@elevasis/sdk/reference/...`; the project root has no
+`@elevasis` packages at all.
+
+**3. `ui.md` documented three import surfaces that do not exist.**
+
+| Was documented                                               | Actual                                                    |
+| ------------------------------------------------------------ | --------------------------------------------------------- |
+| `useApiClient` from `@/lib/hooks/useApiClient`               | `@elevasis/ui/api`, and it takes `API_URL` as an argument |
+| `ProtectedRoute` from `ui/src/features/auth/`                | `@elevasis/ui/auth` — that directory does not exist       |
+| `sseConnectionManager` from `@/lib/sse/SSEConnectionManager` | `@/lib/sse` (`ui/src/lib/sse.ts`)                         |
+
+## Applies to
+
+- Every template-derived project. All three corrections ship inside the
+  `@elevasis/sdk` reference bundle, so they arrive with the dependency baseline —
+  no source edits required to receive them.
+- `CLAUDE.md` also changed shape this train. Template-structural guidance (project
+  structure, stack, commands, slash-command surface) moved into
+  `.claude/Overview.md`, which is replace-managed and propagates by sync.
+  `CLAUDE.md` is now project-owned identity only and remains never-touch.
+
+## Required actions
+
+- Take the `@elevasis/sdk` dependency baseline bump propagated by this train, then
+  reinstall in `operations/` so `reference/rules/` carries the corrected canon.
+- Read the new `OPERATIONS.md` at your project root. It is tenant-owned, never
+  synced, and is the sanctioned home for operational facts that contradict generic
+  guidance — starting with your real deploy target.
+- Once this train's `.claude/Overview.md` has landed, remove template-structural
+  prose from your project's `CLAUDE.md`. Keep your identity sections verbatim.
+
+## Verification
+
+- `grep -n "elevasis/ui/api" operations/node_modules/@elevasis/sdk/reference/rules/ui.md`
+  returns a match, and `@/lib/hooks/useApiClient` returns none.
+- The bundled `deployment.md` leads with a Dev vs Prod section stating the
+  production default.
+- `.claude/Overview.md` contains Project Structure, Stack, and Commands sections.
+- `pnpm sync:verify -- <project>` confirms the project is on the new baseline.
+
+## Not handled by /git-sync
+
+- **The `CLAUDE.md` migration is manual and tenant-specific.** The file is
+  never-touch by design, so nothing overwrites it. Lifting stale template prose out
+  while preserving your identity sections is a per-project edit.
+- **Literal `{CLIENT_CONTEXT}` / `{USER_PREFERENCES}` placeholders must stay
+  literal** if setup has not run for your project. Setup only fills them while they
+  are still literal; replacing them with stub prose permanently marks an
+  unconfigured project as configured.
+- **One-time EOL renormalization.** This train adds `.gitattributes` (LF in-repo).
+  After it lands, run `git add --renormalize .` once in your project repo. Until
+  then the CRLF/LF false-drift persists in existing checkouts — it accounted for
+  roughly 95% of apparent `.claude/` drift before this change.

package/reference/claude-config/sync-notes/2026-07-23-agent-session-memory.md

@@ -0,0 +1,49 @@
+# Session-capable agents now remember earlier turns
+
+## Why this note exists
+
+Any agent with `sessionCapable: true` was silently forgetting everything from earlier in the same
+conversation. Two things were broken:
+
+- **Its saved memory was never loaded back in.** The agent wrote memory at the end of a turn; the
+  next turn started from an empty memory instead of restoring it.
+- **The earlier messages were never given to the model.** The conversation was stored for display
+  but the execution path never read it, so turn N could not see turns 1..N-1.
+
+Both are now fixed, and both are **on by default** for session-capable agents. Turn N is handed the
+agent's restored memory plus the earlier user/assistant messages (token-budgeted), so it can actually
+continue the conversation. The fix is entirely platform-side — no agent definition changes are
+required to get it.
+
+## Applies to
+
+- **Every agent with `sessionCapable: true`.** The behavior arrives with the `@elevasis/sdk` and
+  `@elevasis/core` dependency baselines this train propagates.
+- **Especially agents whose memory strategy was written around the old broken behavior.** For
+  example, a voice/interview agent told _"never store the full transcript in memory — the transcript
+  is the source of truth"_ only worked if the transcript was actually replayed to the model. It
+  wasn't, so those agents deliberately declined to remember the one thing they needed. That guidance
+  is now correct: the earlier messages are given to the model.
+
+## Required actions
+
+1. **Take the `@elevasis/core` and `@elevasis/sdk` baseline bumps** this train propagates, then
+   reinstall in `operations/` so the new worker bundle is present.
+2. **Redeploy your operations bundle.** The worker is baked into the deployed bundle at build time,
+   so an existing deployment stays amnesiac until it is redeployed. `pnpm -C operations exec
+elevasis-sdk deploy --prod` (or your project's deploy command).
+3. **Revisit any `memoryPreferences` you wrote around the old behavior.** If you told an agent not to
+   store something because "the conversation is the source of truth," confirm that still matches what
+   you want now that the conversation is actually available to the model.
+
+## Verification
+
+- Hard recall probe: plant an unguessable token in turn 1, then in turn 2 ask for it back verbatim
+  **without restating it**. A fixed agent returns it; a broken one says the session is empty.
+- `turnInputTokens` grows turn over turn as the conversation accumulates, instead of staying flat at
+  system-prompt-plus-current-message size.
+
+## Not handled by /git-sync
+
+- **The redeploy.** `/git-sync` commits and pushes the propagated dependency baseline, but it does
+  not redeploy your operations bundle. The fix does not go live until you redeploy (action 2 above).

package/reference/claude-config/sync-notes/2026-07-23-workos-org-marker.md

@@ -0,0 +1,50 @@
+# WorkOS single-org binding moves to the `.elevasis` marker
+
+## Why this note exists
+
+**This is a correctness fix for a live data-exposure class of bug. Read it before your next deploy.**
+
+Single-org apps used to bind to their WorkOS organization through `VITE_WORKOS_ORG_ID`, a build-time env var. That variable lived only in a gitignored `ui/.env`, so it was absent from any clean build — CI, a fresh clone, a new hosting project. When it was absent the org guard in `__root.tsx` silently **no-opped**, and the app inherited whatever organization the WorkOS session happened to be using. It failed **open**.
+
+That is not hypothetical. `app.contemplativerecords.com` served a different tenant's data because its production build had no `VITE_WORKOS_ORG_ID` set.
+
+The binding now lives in the project's committed `.elevasis` marker:
+
+```yaml
+projectSlug: your-project
+templateVersion: "1.0"
+appMode: client-centric
+workosOrgId: org_01ABCDEFGHIJKLMNOPQRSTUVWX
+```
+
+The shared `elevasisVite()` plugin (from `@elevasis/ui/vite`, already wired into your `ui/vite.config.ts`) walks up from `ui/`, reads the marker, and injects the value as the build-time constant `__ELEVASIS_WORKOS_ORG_ID__`. The org guard, the `login.tsx` `signIn()` calls, and the dev-centric topbar switcher gate all read that constant.
+
+**A WorkOS `org_` id is a public identifier, not a secret** — it appears in URLs. Committing it is correct. Treating it as a secret is what put it in a gitignored file and caused the failure.
+
+`VITE_WORKOS_ORG_ID` is removed with **no fallback**. There is no transition period and no back-compat read. If you leave the env var set and do not seed the marker, your org guard stops binding.
+
+## Applies to
+
+- **Every template-derived project.** The plugin change arrives with the `@elevasis/ui` dependency baseline this train propagates.
+- **`client-centric` projects — action required.** `/external verify` now fails closed: a `client-centric` project whose `.elevasis` lacks a non-empty `org_`-prefixed `workosOrgId` fails the gate. This is deliberate. A loud failure is the point; the old silent no-op is what shipped the bug.
+- **`dev-centric` projects — optional.** The field may be absent or empty. If present and non-empty it must still be `org_`-prefixed.
+
+## Required actions
+
+1. **Add `workosOrgId` to your `.elevasis`.** Sync will not do this for you — see "Not handled by /git-sync" below. Find your org id in Command Center, or in the `organizations` table as `workos_org_id`.
+2. **Take the `@elevasis/ui` baseline bump** this train propagates, then reinstall in `ui/` so the plugin that injects the constant is actually present.
+3. **Remove `VITE_WORKOS_ORG_ID` from every environment you set it in** — `ui/.env`, `ui/.env.local`, and your hosting provider's env settings (for Vercel: Project → Settings → Environment Variables). Leaving it set does nothing, but it will mislead the next person who reads it.
+4. **Redeploy.** The constant is injected at build time, so an existing deployment keeps its old behavior until it is rebuilt.
+
+## Verification
+
+- `pnpm external:verify` passes, and your project's `marker` category reports `.elevasis workosOrgId is set for client-centric project`.
+- `grep -rn "VITE_WORKOS_ORG_ID" ui/ .env* 2>/dev/null` returns nothing.
+- In a built bundle, your org id is present: `grep -o "org_[A-Za-z0-9]*" ui/dist/assets/*.js | head`. If this returns nothing for a `client-centric` project, the marker was not read — check that `.elevasis` sits at your project root, one level above `ui/`.
+- After deploying, log in and confirm the app lands in the correct organization.
+
+## Not handled by /git-sync
+
+- **Your `.elevasis` marker is project-owned and `never-touch`.** The sync engine will never write it, which means it will never seed `workosOrgId` for you and never overwrite the value once you set it. Step 1 above is a manual, per-project edit. A `client-centric` project that skips it will fail `/external verify` until it is done.
+- **A diverged `__root.tsx` will not auto-merge.** `__root.tsx` is merge-managed with `critical-manual-merge` severity. If your shell has diverged from the template, sync preserves your copy and the `useOrgGuard` swap from `import.meta.env.VITE_WORKOS_ORG_ID` to `__ELEVASIS_WORKOS_ORG_ID__` is a manual edit. When you make it, do **not** remove the structural contract substrings `ElevasisAuthenticatedShell`, `from '@elevasis/ui/app'`, or `SYSTEM_MANIFESTS` — dropping them makes `sync-apply` mis-escalate your project to `catch-up-required`.
+- **A diverged `ui/vite.config.ts` needs reconciliation, not overwrite.** It is `replace-all` managed, so a blind sync would clobber local divergence. Confirm `...elevasisVite()` survives in your plugins array — without it the constant is never defined and the guard reads `undefined`.

package/reference/rules/active-change-index.md

@@ -9,7 +9,7 @@ description: Bridge between stable scaffold docs and higher-volatility in-progre
 
 Use this rule to decide whether stable scaffold docs are enough, or whether you also need to load in-progress platform architecture docs from the monorepo.
 
-> **Note:** Paths prefixed with `apps/` or `packages/` are monorepo-internal and unavailable in standalone projects. For those areas, use the stable scaffold docs under `node_modules/@elevasis/sdk/reference/scaffold/` as the primary reference. The monorepo paths are retained for contributors working within the monorepo.
+> **Note:** Paths prefixed with `apps/` or `packages/` are monorepo-internal and unavailable in standalone projects. For those areas, use the stable scaffold docs under `operations/node_modules/@elevasis/sdk/reference/scaffold/` as the primary reference. The monorepo paths are retained for contributors working within the monorepo.
 
 ## Current Watch Areas
 
@@ -32,10 +32,10 @@ Load:
 
 Stable scaffold docs affected:
 
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 - `.claude/rules/ui.md`
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
 
 ### Package Surface / Reference System
 
@@ -54,7 +54,7 @@ Load:
 
 Stable scaffold docs affected:
 
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
 ### Resource / Topology Mapping
 

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

@@ -55,7 +55,9 @@ Do not write resume state into markdown frontmatter. Task-doc frontmatter is lim
 
 ### Session-Start Dashboard
 
-The session-start dashboard directive lives in `CLAUDE.md`. If you see it there, follow it on the first response of a session. This file (`agent-start-here` rule) is the drill-down reference layer; `CLAUDE.md` owns session bootstrap.
+**This rule owns session bootstrap.** Run the "First Action" flow above on the first response of a session. `CLAUDE.md` only points here — it is project-owned and never overwritten by sync, so it deliberately carries no procedure that might need correcting later.
+
+Older projects may still have a copy of the dashboard directive inline in their `CLAUDE.md`. If the two ever disagree, this file wins: it ships with the SDK version the project actually runs.
 
 ## Template Surfaces
 
@@ -65,28 +67,29 @@ Once project continuity is resolved (or confirmed irrelevant), the template is n
 - `operations/` -- Elevasis SDK resources deployed to the platform
 - `core/` -- runtime-agnostic shared contracts and organization model adaptation
 - `.claude/` -- local agent rules, skills, and hooks
-- `node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
 
 ## Discovery Order
 
 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 (`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
+2. Read `CLAUDE.md` for this project's identity, client context, and user preferences. It is deliberately short — for structure, stack, commands, and the slash-command surface, read `.claude/Overview.md`, which sync keeps current.
+3. Read `OPERATIONS.md` at the project root, if present -- it is tenant-owned, never overwritten by sync, and records operational quirks true for this tenant only (non-obvious deploy targets, environment gotchas). Read it early: it can override generic guidance elsewhere in this file for this specific tenant.
+4. Read this rule and classify the task using the Task Classes below.
+5. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`) for organization context and naming.
+6. Read the relevant structural map:
+   - Glob `operations/node_modules/@elevasis/sdk/reference/` for published package surfaces
    - Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
-6. For feature integration, resource authoring, or UI customization tasks, read `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
-7. Drill into the co-located local explainer for the abstraction boundary you are changing.
-8. Check the `.claude/rules/active-change-index.md` rule before trusting stable assumptions in areas that are under active architecture work.
+7. For feature integration, resource authoring, or UI customization tasks, read `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
+8. Drill into the co-located local explainer for the abstraction boundary you are changing.
+9. Check the `.claude/rules/active-change-index.md` rule before trusting stable assumptions in areas that are under active architecture work.
 
 ## SDK Reference Scaffold
 
 Universal scaffold documentation (recipes, patterns, architecture, reference) has been centralized in the SDK reference. After `pnpm install`, the entry point is:
 
-`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+`operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
 
 This index links to all scaffold docs including pathway recipes, UI patterns, core architecture, and auto-generated contracts/feature registry.
 
@@ -102,14 +105,14 @@ Examples: add a page, change sidebar behavior, adjust feature visibility, update
 
 Load first:
 
-- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
 - `.claude/rules/ui.md`
 - `ui/src/routes/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
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- when building or extending CRM pages, sidebars, hooks, workflows, or deal data surfaces
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- when building or extending lead-gen pages, sidebars, hooks, workflows, list/member state, or artifacts
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- when changing CRM deal action buttons or adding a workflow-backed deal action
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- when building or extending CRM pages, sidebars, hooks, workflows, or deal data surfaces
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- when building or extending lead-gen pages, sidebars, hooks, workflows, list/member state, or artifacts
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- when changing CRM deal action buttons or adding a workflow-backed deal action
 
 Then inspect:
 
@@ -130,7 +133,7 @@ Examples: add a workflow, update an agent, change resource registration, underst
 
 Load first:
 
-- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- workflow recipes, resource authoring)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- workflow recipes, resource authoring)
 - `.claude/rules/operations.md`
 - `operations/src/README.md`
 
@@ -153,21 +156,21 @@ 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)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
 - `core/config/README.md`
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 - typed feature/surface constants from `@elevasis/core/organization-model` -- `SALES_FEATURE_ID`, `PROSPECTING_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `SALES_PIPELINE_SURFACE_ID`, `PROSPECTING_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_COMMAND_VIEW_SURFACE_ID`. Use these typed constants instead of magic strings when overriding feature/surface IDs.
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending CRM structure.
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead gen is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending lead-gen lists, members, artifacts, or state transitions.
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- CRM action buttons are not `sales.actions` org-model config in v1; use the recipe's provider/custom-button path.
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending CRM structure.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead gen is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending lead-gen lists, members, artifacts, or state transitions.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- CRM action buttons are not `sales.actions` org-model config in v1; use the recipe's provider/custom-button path.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
 
 Then inspect:
 
 - `core/config/organization-model.ts`
 - `core/config/organization-model.ts` -- Organization Model overrides plus Systems and Resources descriptors. Start here for feature labels, surface mapping, and resource identity/governance changes.
 - `ui/src/routes/__root.tsx`
-- `ui/src/lib/hooks/useFeatureAccess.ts`
+- feature-access gating call sites built from `createFeatureAccessHook` (`@elevasis/ui/hooks`) -- the template no longer ships a local `useFeatureAccess.ts`; the hook factory is the published equivalent
 - relevant nav config files
 
 Verify with:
@@ -209,7 +212,7 @@ Examples: extend a published package contract, understand how a scaffold surface
 Load first:
 
 - `.claude/rules/active-change-index.md`
-- Glob `node_modules/@elevasis/sdk/reference/` for the current SDK package surface
+- Glob `operations/node_modules/@elevasis/sdk/reference/` for the current SDK package surface
 - package README found via that glob
 
 Then inspect:
@@ -253,11 +256,12 @@ The deployment aggregation point. Start here for what resources are registered a
 
 Trust these in order:
 
-1. Source code and published package docs
-2. Co-located boundary docs
-3. Generated structural maps
-4. Hand-authored template guidance
-5. In-progress architecture docs when `.claude/rules/active-change-index.md` says the area is actively evolving
+1. Tenant-owned `OPERATIONS.md` at the project root, when present, for facts specific to this tenant's own environment and operational quirks -- it is never overwritten by sync and can override any generic guidance below for this tenant specifically
+2. Source code and published package docs
+3. Co-located boundary docs
+4. Generated structural maps
+5. Hand-authored template guidance
+6. In-progress architecture docs when `.claude/rules/active-change-index.md` says the area is actively evolving
 
 If a hand-authored doc conflicts with source or published package docs, trust source and flag the doc drift.
 

package/reference/rules/deployment.md

@@ -14,19 +14,31 @@ paths:
 ```bash
 pnpm -C operations run check        # Validate resource definitions
 pnpm -C operations run check-types  # TypeScript type-check
-pnpm -C operations run deploy       # Deploy to dev (only after both pass)
+pnpm -C operations run deploy       # Deploy (target depends on environment -- see below)
 ```
 
 `check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.
 
-## Dev vs Prod
+## Dev vs Prod (SAFETY-CRITICAL: plain `deploy` targets PRODUCTION by default)
 
-| Command                              | Target            | When                    |
-| ------------------------------------ | ----------------- | ----------------------- |
-| `pnpm -C operations run deploy`      | Local dev API     | Development and testing |
-| `pnpm -C operations run deploy:prod` | `api.elevasis.io` | Production release      |
+Plain `pnpm -C operations run deploy` runs `elevasis-sdk deploy` with no flags. There is no dev-safe default baked into the command name. The API URL resolution (`packages/sdk/src/cli/config.ts`, `resolveApiUrl`) checks, in order:
 
-Always test in dev first, verify with `elevasis-sdk exec`, then deploy to prod.
+1. `--api-url <url>` CLI flag -- explicit override, always wins
+2. `--prod` CLI flag -- forces `https://api.elevasis.io`
+3. `ELEVASIS_API_URL` env var -- explicit override
+4. `NODE_ENV === 'development'` -- ONLY this exact condition returns `http://localhost:5170`
+5. Otherwise (no flag, no env var, `NODE_ENV` unset or anything other than `'development'`) -- falls through to `https://api.elevasis.io` (**production**)
+
+| Command                              | Target                                                                              | When                                                                                        |
+| ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `pnpm -C operations run deploy`      | **Production (`api.elevasis.io`) unless your shell has `NODE_ENV=development` set** | Only safe as a "dev" command in a shell where `NODE_ENV=development` is explicitly exported |
+| `pnpm -C operations run deploy:prod` | `api.elevasis.io`, via explicit `--prod`                                            | Production release                                                                          |
+
+Do not assume plain `deploy` is a dev-safe command. Most tenant shells do not export `NODE_ENV=development`, so plain `deploy` hits production. Before running it, confirm the target: check `echo $NODE_ENV` / `$env:NODE_ENV`, or pass `--api-url` explicitly if you need to target a specific environment. If this tenant project has a checked-in `OPERATIONS.md` at the project root, check it first -- it records tenant-specific deploy-target facts that override this generic guidance.
+
+The API key follows a related but distinct rule (`resolveApiKey`): with `--prod`, or whenever `NODE_ENV !== 'development'`, only `ELEVASIS_PLATFORM_KEY` is used. Only when `NODE_ENV === 'development'` (and `--prod` is not passed) does the CLI prefer `ELEVASIS_PLATFORM_KEY_DEV`, falling back to `ELEVASIS_PLATFORM_KEY` if the dev key is unset.
+
+Always verify the actual deploy target before treating a deploy as safe-to-repeat, verify with `elevasis-sdk exec`, then deploy to prod deliberately (`deploy:prod` or `--prod`).
 
 ## Version Bumping
 
@@ -39,7 +51,8 @@ Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment vers
 
 ## Environment
 
-- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth
+- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth (used for every deploy unless `NODE_ENV=development` with no `--prod`)
+- `ELEVASIS_PLATFORM_KEY_DEV` is optional -- only consulted when `NODE_ENV=development` and `--prod` is not passed; falls back to `ELEVASIS_PLATFORM_KEY` if unset
 - `.env` is never included in the bundle -- it stays local
 - Integration credentials live in Command Center, not `.env`
 

package/reference/rules/frontend.md

@@ -38,9 +38,9 @@ When building pages that display external data, use published `@elevasis/ui` com
 
 ## Detailed Reference
 
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `systemKey` / `SystemGuard` / `AdminGuard` model
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `NavItem`, `OrganizationModel`)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `systemKey` / `SystemGuard` / `AdminGuard` model
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `NavItem`, `OrganizationModel`)
 - `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
 - `ui/src/config/nav-items.ts` -- sidebar navigation entries

package/reference/rules/observability.md

@@ -31,4 +31,4 @@ pnpm elevasis-sdk executions <resourceId>
 
 ## Detailed Reference
 
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples