@elevasis/sdk 1.36.5 → 1.38.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-15-session-chat-zero-wiring.md

@@ -0,0 +1,46 @@
+# Session Chat Zero-Wiring Default Slot
+
+## Why this note exists
+
+`@elevasis/ui` (>= 2.56.0) makes `SessionChatPage`'s `renderConversationView` slot
+optional and self-defaulting: when omitted, the page renders the shared
+`SessionConversationView` itself, resolving `apiUrl` from the service context
+(now exposed on `ElevasisServiceContextValue`). The template `SessionChatPage`
+now mounts the shared page with NO slot, and the orphan null-stub
+`ui/src/features/assistant/components/ConversationView.tsx` is deleted. Projects
+that omit the slot get a working session chat out of the box; customization stays
+opt-in via the same prop. Backward-compatible: hosts that still pass the slot are
+unaffected.
+
+## Applies to
+
+- All template-derived projects with the agent-sessions page
+  (`ui/src/features/operations/sessions/SessionChatPage.tsx`).
+- Any project still wiring a local `ConversationView` stub
+  (`ui/src/features/assistant/components/ConversationView.tsx`) -> these render
+  a blank chat with a stuck `DISCONNECTED` badge until reconciled.
+
+## Required actions
+
+- Bump `@elevasis/ui` to `^2.56.0` (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.)
+- Drop the explicit `renderConversationView={...}` slot from your
+  `SessionChatPage.tsx` and remove the local stub import, relying on the new
+  default. (To keep a custom body, keep passing the slot.)
+- Delete the now-unused local null-stub
+  `ui/src/features/assistant/components/ConversationView.tsx`.
+
+## Verification
+
+- `pnpm -C ui check-types` passes against `@elevasis/ui@^2.56.0`.
+- The session-detail chat page (`/operations/sessions/$sessionId`) renders
+  history + live messages and the `DISCONNECTED` badge clears, with NO slot wired.
+
+## Not handled by /git-sync
+
+- `/git-sync` surfaces this note and pulls the template `SessionChatPage`
+  baseline, but the diverged tenant copy is preserved (merge-managed) -- you must
+  manually drop the explicit slot.
+- `/git-sync` does NOT delete the local `ConversationView` stub
+  (`delete_policy: none`); remove it manually.

package/reference/claude-config/sync-notes/2026-06-17-agent-session-ux-features.md

@@ -0,0 +1,34 @@
+# Agent session UX features (End Conversation, intake form, session naming)
+
+## Why this note exists
+
+This train bumps `@elevasis/core` and `@elevasis/ui` with three tenant-facing agent-session features that ship entirely inside the published packages (no template source edit, package-cascade-only):
+
+- **End Conversation** (`@elevasis/ui`) — both the internal Agent Sessions surface (`features/operations/sessions/SessionDetailsPanel`) and the public agent-chat surface (`features/public-agent-chat/PublicAgentChat`) now render an "End conversation" control. Ending preserves history and blocks new turns (distinct from Delete, which removes). The public composer locks out after end with a "This conversation has ended" placeholder.
+- **Welcome intake form** (`@elevasis/ui` + `@elevasis/core`) — the public chat intro screen renders an optional intake form driven by the grant's `capture_fields` column (now typed as `CaptureField[]` in `@elevasis/core`'s public-agent-chat schema). Collected values flow into `session.metadata`. All fields are optional.
+- **Session naming from intake** (`@elevasis/ui` + platform API) — sessions are titled from the collected `name` (server-side, with a first-user-message fallback), and the Agent Sessions list now renders `session.title` as the row label.
+
+The session `session:end` / `session:ended` WebSocket messages, the internal `POST /sessions/:id/end` route, and server-side title derivation live in the Elevasis-deployed platform API — tenants receive that behavior automatically; the package bump only delivers the frontend.
+
+## Applies to
+
+- All template-derived projects that expose the Agent Sessions page (`ui/src/features/operations/sessions/`) or the public agent-chat surface (`ui/src/features/public-agent-chat/`).
+- Projects that configure public agent grants and want to collect intake fields (Name plus arbitrary configurable fields) on the public intro screen.
+
+## Required actions
+
+- Bump `@elevasis/core` to `^0.52.0` and `@elevasis/ui` to `^2.59.0` (or later) and install. The ship train's `external-sync` stage does this automatically via the package-cascade baselines — manual `pnpm update` is not required.
+- No source changes are required to receive End Conversation, the intake form, or title-in-list — they ship inside `@elevasis/ui` / `@elevasis/core`.
+- To enable an intake form on a public agent, populate the grant's `capture_fields` (array of `{ key, label, type?, required? }`). There is no Command Center editor for `capture_fields` yet — configure it via a grant write. Leaving `capture_fields` empty renders the intro exactly as before (no form).
+
+## Verification
+
+- `pnpm -C ui check-types` passes against `@elevasis/ui@^2.59.0`.
+- Open the public agent chat for a grant with `capture_fields` set → the intro renders the configured fields; entering a name and starting the session titles the session by that name in the Agent Sessions list.
+- With no `capture_fields` → the intro renders unchanged; the session is titled from the first user message.
+- Click "End conversation" on either the public header or the internal session detail panel → the session ends, history is preserved, and a new turn is rejected ("Session has ended").
+
+## Not handled by /git-sync
+
+- `/git-sync` surfaces this note and pulls the propagated package baselines, but it does not run the `@elevasis/core` / `@elevasis/ui` install for you when reconciling manually outside the ship train.
+- The intake/title and End features depend on the Elevasis-deployed platform API (`session:end` handling, `/sessions/:id/end`, server-side title derivation). They are not part of a tenant's own backend and require no tenant action — but they only work once the platform API carrying them is deployed.

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/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

package/reference/rules/organization-model.md

@@ -51,7 +51,7 @@ governance metadata belong in the id-keyed `resources` map; operations code deri
 Author system-local semantics by boundary:
 
 - `System.ontology` owns durable object types, action types, catalog types, link types, event types, and surfaces.
-- `System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Use only cataloged profiles from `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, on their convention-locked System paths, and satisfy readiness through ontology/resources/catalogs/topology. Custom Systems do not declare `apiInterface`; route custom behavior through workflows/operations and the OM layers tenants own.
+- `System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Use only cataloged profiles from `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, on their convention-locked System paths, and satisfy readiness through ontology/resources/catalogs/topology. Custom Systems do not declare `apiInterface`; route custom behavior through workflows/operations and the OM layers tenants own.
 - `System.config` owns system-local JSON settings and defaults.
 - `resources` own executable workflow/agent descriptors, `systemPath`, owners, governance status, code references, and runtime implementation links.
 - `resource.ontology.actions` describes the ontology actions a Resource performs; `resource.ontology.primaryAction` names the default/selectable action when a Resource has one.