@elevasis/sdk 1.15.0 → 1.16.0

package/reference/framework/tutorial-system.mdx

@@ -1,222 +1,135 @@
 ---
 title: Tutorial System
-description: Reference for the SDK tutorial system -- 21-item menu across 4 sections, skill-level adaptation rules, progress tracking format, and per-lesson module contents
+description: The /tutorial skill in the external project scaffold -- two-track onboarding (vibe-coder and technical), gate question, track persistence, and escape hatch
 ---
 
-The tutorial system is available via the `/tutorial` slash command in Claude Code. It is included in the external template project scaffold.
+The `/tutorial` skill is included in every scaffolded external project. Run it from Claude Code inside a project to start interactive onboarding. It forks into two tracks on first invocation and adapts agent tone project-wide based on your choice.
 
 ---
 
-## Menu System
+## Getting Started
 
-`/tutorial` always shows the full 21-item menu table on invocation. All items are visible at once with progress indicators. No track gating -- any item is available at any time.
+Open a scaffolded external project in Claude Code and run:
 
 ```
-Elevasis Tutorial
-==================
-
-INTRODUCTION                                       0/4
-  1  Welcome & Orientation                         [ ]
-  2  How This Workspace Works                      [ ]
-  3  The /meta Command                             [ ]
-  4  /work and /docs                               [ ]
-
-CORE CONCEPTS                                      0/6
-  5  Your First Custom Workflow                    [ ]
-  6  Understanding Data (Schemas)                  [ ]
-  7  Using Platform Tools                          [ ]
-  8  Multi-Step Workflows                          [ ]
-  9  Decision Points                               [ ]
- 10  Going to Production                           [ ]
-
-ADVANCED MODULES                                   0/9
- 11  Human-in-the-Loop                             [ ]
- 12  Task Scheduling                               [ ]
- 13  Notification System                           [ ]
- 14  Real-World Integrations                       [ ]
- 15  Error Handling Mastery                        [ ]
- 16  Advanced Workflows                            [ ]
- 17  Resource Composition                          [ ]
- 18  LLM Integration                               [ ]
- 19  AI Agents                                     [ ]
-
-ADVANCED WORKSPACE                                 0/2
- 20  Rules, Memory, and Customization              [ ]
- 21  Template Lifecycle                            [ ]
-
-Pick a number to start.
+/tutorial
 ```
 
-**Progress indicators:** `[ ]` not started, `[>]` in progress, `[x] YYYY-MM-DD` complete.
-
-User picks a number to start or resume any item. `"status"` shows the same table.
+On first invocation in a fresh project, the skill asks one gate question:
 
----
+> "Are you here to **build automations by describing what you want** (and I handle the technical side), or are you a **developer** who'll edit code directly?"
 
-## 4 Sections
+Your answer selects a track. The choice is saved to `.claude/memory/profile.md` and shapes agent vocabulary, tool-call visibility, and verbosity for every conversation in the project -- not just `/tutorial` sessions.
 
-- **INTRODUCTION (1-4):** Welcome + workspace orientation (workspace framework, /meta, /work and /docs) -- taught before building
-- **CORE CONCEPTS (5-10):** Orchestration lessons (workflows, schemas, tools, multi-step, conditions, production)
-- **ADVANCED MODULES (11-19):** Hands-on feature modules (hitl, schedules, notifications, integrations, error-handling, workflows, composition, llm, agents)
-- **ADVANCED WORKSPACE (20-21):** Power-user customization (rules/memory, template lifecycle)
+Subsequent `/tutorial` invocations skip the gate question and resume your progress.
 
 ---
 
-## Skill-Level Adaptation
-
-Assessed during `/meta init`. Two independent dimensions.
-
-### automation dimension
+## Tracks at a Glance
 
-| Level      | Context Loading                                                                                            | Delivery                                                            | Verification                                                      |
-| ---------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `none`     | Glossary, Workflow overview, Platform Tools Overview only. Skip Zod, Execution Model, Design Decisions.    | Agent writes all code. No code shown to user. Analogies throughout. | CLI primary. Agent runs `elevasis-sdk exec` and narrates results. |
-| `low-code` | All concept sections. Zapier/Make mapping. `adapters-integration.mdx` / `adapters-platform.mdx` on-demand. | Map to Zapier/Make equivalents. Show code with explanations.        | CLI primary.                                                      |
-| `custom`   | All docs listed per-lesson and per-module.                                                                 | Full technical content, code-first.                                 | CLI primary.                                                      |
-
-### platformNavigation dimension
-
-| Level         | Behavior                                                                                                               |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `none`        | Walk through pages step by step with exact navigation paths. Explain each page before asking user to interact with it. |
-| `oriented`    | Reference pages by name; briefly remind purpose on first mention.                                                      |
-| `comfortable` | Reference by name only; focus on advanced filtering and schedule types.                                                |
-
-**General rules (all levels):** Fast users: acknowledge, offer to skip ahead. Level change observed: note in `skills.md` Growth Log. After lesson/module: update progress file.
-
----
+### Vibe-Coder Track (8 lessons)
 
-## Progress Logic
+For users who want to describe what they want and have the agent handle the implementation. The agent never uses technical vocabulary -- no TypeScript, no pnpm, no CLI commands shown, no schemas explained. Everything is narrated in plain language.
 
 ```
-1. Read .claude/memory/tutorial-progress.md
-2. Show the full menu table with progress indicators filled in
-3. User picks a number -> start or resume that item directly
-4. After completion: mark done in progress file, show updated menu table
-5. All 21 items complete -> congratulate, suggest docs/ or /work
+Your Tutorial
+==============
+1  Welcome -- what this place does for you             [ ]
+2  How to talk to me                                   [ ]
+3  Your business profile                               [ ]
+4  Your first automation                               [ ]
+5  Your dashboard -- where everything lives            [ ]
+6  Your approval queue -- signing off on things        [ ]
+7  Changing things later                               [ ]
+8  When things go wrong                                [ ]
+
+Pick a number to start.
 ```
 
----
+**What each lesson covers:**
 
-## Introduction: Items 1-4
+- **1. Welcome** -- Plain analogy for the platform. Shows a real automation already running before any building.
+- **2. How to talk to me** -- Conversation patterns for making requests, asking questions, and describing changes. No technical vocabulary introduced.
+- **3. Your business profile** -- Conversational walk through org identity. Agent handles all edits silently; user answers questions.
+- **4. Your first automation** -- User describes what they want. Agent builds, runs, and narrates. User never sees code.
+- **5. Your dashboard** -- Tour of Command Center. Where automations live and how to read the visual map.
+- **6. Your approval queue** -- Show a pending approval, approve it, see the automation continue.
+- **7. Changing things later** -- Plain-language change requests. Agent handles implementation.
+- **8. When things go wrong** -- "Tell me what looks wrong. I'll figure it out and tell you what I did." No error traces shown.
 
-Items 1-4 orient the user to the platform and workspace before any building.
+**Vocabulary rules in this track:** The agent never says workflow, schema, deploy, credential, TypeScript, or pnpm. "Automation" replaces all SDK resource terms. "Make it live" replaces "deploy." "Account connection" replaces "credential." "Your approval queue" replaces HITL.
 
-**Item 1 -- Welcome & Orientation:** Platform tour, deploy echo workflow, Command Center orientation.
+### Technical Track (19 lessons, 5 sections)
 
-**Item 2 -- How This Workspace Works:** CLAUDE.md as instruction sheet, four commands, creds skill, memory system overview.
+For developers who will read and edit code directly. Lessons are code-first. All SDK concepts, CLI commands, and file structures are covered.
 
-**Item 3 -- The /meta Command:** Project dashboard, /meta fix, /meta deploy, /meta health.
+```
+SECTION A -- The workspace                              (3 items)
+  1  What is this workspace                              [ ]
+  2  The skill layer -- slash commands you'll use        [ ]
+  3  The vibe layer -- ambient intent classification     [ ]
+
+SECTION B -- Build your first thing                     (5 items)
+  4  Echo workflow tour                                  [ ]
+  5  Custom workflow with schemas                        [ ]
+  6  Platform tools and credentials                      [ ]
+  7  Multi-step and conditionals                         [ ]
+  8  Going to production                                 [ ]
+
+SECTION C -- The Organization Model                     (3 items)
+  9  /knowledge ceremony -- identity, customers,         [ ]
+     offerings via the layered flow
+ 10  Features and labels                                 [ ]
+ 11  Entity extensions -- BaseProject, BaseDeal          [ ]
+
+SECTION D -- Modules (load on demand)                   (~6 items)
+ 12  HITL                                                [ ]
+ 13  Schedules                                           [ ]
+ 14  Notifications + integrations                        [ ]
+ 15  Error handling                                      [ ]
+ 16  LLM and agents                                      [ ]
+ 17  Composition (execution.trigger)                     [ ]
+
+SECTION E -- Power user                                 (2 items)
+ 18  Rules, memory, scaffold registry                    [ ]
+ 19  Template lifecycle and /git-sync                    [ ]
+```
 
-**Item 4 -- /work and /docs:** Cross-session task tracking, documentation lifecycle, /work vs /docs boundary.
+Section D modules are available any time -- no section order prerequisite. Sections A-C are designed to be completed in order on a first pass, though any item can be picked directly.
 
 ---
 
-## Core Path: Lessons 5-10
-
-Each lesson: (1) announce title and goal, (2) explain concept per skill level, (3) build or modify something, (4) verify it works, (5) record observations, ask "ready for next?"
-
-**Lesson 5 -- Your First Custom Workflow**
-
-- `automation: none` -- "A recipe." Agent writes all code. Agent runs `elevasis-sdk exec` and narrates result.
-- `automation: low-code or custom` -- Modify echo workflow. Walk through `config`, `contract`, `steps`, `entryPoint`. Deploy with `elevasis-sdk check` then `elevasis-sdk deploy`.
-
-**Lesson 6 -- Understanding Data (Schemas)**
-
-- `automation: none` -- "What information does your automation need?" No Zod, no code shown. Agent reads identity.md goals and writes the schema.
-- `automation: low-code` -- "Field mapping like Zapier, but with validation." Show Zod types briefly.
-- `automation: custom` -- Full Zod explanation. `z.infer`. Show how schema fields define CLI input structure.
-
-**Lesson 7 -- Using Platform Tools**
+## Track Persistence
 
-- `automation: none` -- Agent makes all code edits. Credential creation guided via Command Center UI.
-- `automation: low-code or custom` -- Explain adapter pattern: `createAttioAdapter('cred')`. Show singleton pattern: `import { scheduler, llm } from '@elevasis/sdk/worker'`.
+The track choice is saved to `.claude/memory/profile.md` on selection. The agent reads this file at session start alongside `agent-start-here.md`. This means:
 
-**Lesson 8 -- Multi-Step Workflows**
-
-- `automation: none` -- "Step 1 passes its result to Step 2, like a relay race." Command View is PRIMARY teaching tool.
-- `automation: low-code or custom` -- Chain steps with `StepType.LINEAR`. Show relationship edges in Command View.
-
-**Lesson 9 -- Decision Points**
-
-- `automation: none` -- "If the customer is VIP, do this -- otherwise, do that." Agent runs both paths. Open Execution Logs.
-- `automation: low-code or custom` -- Conditional routing with `StepType.CONDITIONAL`. Show step trace in Execution Logs.
-
-**Lesson 10 -- Going to Production**
-
-- `automation: none` -- "Draft vs live." Create Recurring schedule in Task Scheduler.
-- `automation: low-code or custom` -- Change `status: dev` -> `prod`. Cover `try/catch`, `ExecutionError`, `PlatformToolError`. CLI monitoring: `elevasis-sdk executions`.
+- Agent vocabulary and tone adjust for every conversation in the project, not just `/tutorial`
+- The vibe-coder track suppresses all technical surface globally until switched
+- Progress is tracked separately in `.claude/memory/tutorial-progress.md`
 
 ---
 
-## Module System: Items 11-19
-
-Modules are available any time -- no core path prerequisite. After completing a module the full menu table is shown again.
+## Switching Tracks
 
-| #   | Module           | Reference Docs                                                               | Build                                                                                                         | Key Concepts                                                       |
-| --- | ---------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| 11  | `hitl`           | `command-center.mdx` (Command Queue)                                         | Approval gate with `approval.create()`. Full lifecycle: trigger -> Command Queue -> approve/reject -> resume. | `approval` adapter, pending state, Command Queue UI                |
-| 12  | `schedules`      | `command-center.mdx` (Task Scheduler)                                        | All three schedule types: Recurring, Relative, Absolute. `scheduler` adapter for in-workflow.                 | Cron syntax, schedule types, Task Scheduler UI                     |
-| 13  | `notifications`  | `adapters-platform.mdx` (notifications, email)                               | Notification + email steps. Alerts on completion.                                                             | `notifications` singleton, `email` singleton                       |
-| 14  | `integrations`   | `platform-tools/index.mdx` (Credential Security), `adapters-integration.mdx` | Real adapter from `identity.md`. Full end-to-end with OAuth or API key credential.                            | Adapter pattern, credential scoping, external call error handling  |
-| 15  | `error-handling` | `patterns.mdx` (error handling), `troubleshooting.mdx`                       | Workflow demonstrating all three error types. `try/catch`, `context.logger`, recovery.                        | `ExecutionError`, `PlatformToolError`, `ToolingError`              |
-| 16  | `workflows`      | `patterns.mdx` (store, logging, organization)                                | Refactor with `context.store`, `context.logger`, domain directories. Advanced schema patterns.                | `context.store`, `context.logger`, schema depth                    |
-| 17  | `composition`    | `command-center.mdx` (Command View), `patterns.mdx`                          | Two workflows: first triggers second with `execution.trigger()`. Declare relationship.                        | `execution.trigger`, relationship declarations, Command View edges |
-| 18  | `llm`            | `adapters-platform.mdx` (llm singleton)                                      | `llm.generate()` with structured output. Model selection and temperature.                                     | `llm` singleton, structured output, temperature                    |
-| 19  | `agents`         | `framework/agent.mdx`                                                        | Agent definition with tools. LLM tool calling. Agent vs workflow comparison.                                  | Agent definition, tool registration, execution trace               |
+Run `/tutorial switch` at any time to flip tracks and restart the menu. Progress from the previous track is preserved in the progress file for reference but the active lesson resets.
 
 ---
 
-## Advanced Workspace: Items 20-21
+## Progress Indicators
 
-**Item 20 -- Rules, Memory, and Customization**
+The menu uses three states:
 
-- `none` -- "Sticky notes the agent reads automatically." Show `.claude/rules/workspace-patterns.md` without technical detail.
-- `low-code` -- Show `.claude/rules/` directory. Explain MANAGED (`sdk-patterns.md`) vs INIT_ONLY (`workspace-patterns.md`). Explain error promotion: 3+ recurrences -> add a rule.
-- `custom` -- Read both rules files. Walk through memory layout: `index.md`, `profile/`, `errors/`, `tutorial-progress.md`. Walk through adding a new rule.
+- `[ ]` -- not started
+- `[>]` -- in progress
+- `[x] YYYY-MM-DD` -- complete
 
-**Item 21 -- Template Lifecycle**
-
-- `none` -- "SDK releases automatically update your workspace." Explain `/meta fix` as the update command.
-- `low-code` -- Explain MANAGED vs INIT_ONLY file types. Show how `/meta fix` handles conflicts.
-- `custom` -- Full template lifecycle: the external template handles initial project creation. `/meta fix` performs drift repair and SDK upgrade. Conflict resolution merges current files against the template, preserving customizations in INIT_ONLY files.
+Run `/tutorial` with no argument at any time to see the current menu with progress filled in. Run `/tutorial status` for the same view.
 
 ---
 
-## Progress File Format
-
-Stored at `.claude/memory/tutorial-progress.md`.
-
-```markdown
-# Tutorial Progress
-
-Current: <free-form, e.g. "4: /work and /docs" or "M:integrations">
-Started: YYYY-MM-DD
-Last Session: YYYY-MM-DD
-
-## Completed Lessons
-
-| Item | Title | Completed | Duration |
-| --- | --- | --- | --- |
-| 1 | Welcome & Orientation | 2026-03-01 | 25 min |
-
-## Completed Modules
-
-| Module | Title | Completed | Duration |
-| --- | --- | --- | --- |
-| hitl | Human-in-the-Loop | 2026-03-03 | 40 min |
-
-## Capability Observations
-
-| Source | Observation |
-| --- | --- |
-| 1 | Navigated Command View without guidance |
-
-## Assessment Notes
-
-- Strong automation background, slow on TypeScript syntax
-```
-
----
+## Related Docs
 
-**Last Updated:** 2026-03-05
+- [SDK Concepts](../concepts.mdx) -- full technical reference for workflows, schemas, adapters, and the org model
+- [Getting Started](../getting-started.mdx) -- scaffold setup and first deploy
+- [CLI Reference](../cli.mdx) -- `elevasis-sdk` commands referenced in the technical track
+- [Framework Overview](index.mdx) -- skill layer, memory system, and interaction guidance

package/reference/packages/core/src/knowledge/README.md

@@ -0,0 +1,32 @@
+# @elevasis/core/knowledge
+
+Pure query layer over the organization graph. Browser-safe (no Node APIs); shared by the SDK CLI, platform CLI, and the `@elevasis/ui/knowledge` browser.
+
+## Surface
+
+| Export                                        | Purpose                                                                                                                             |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `byFeature(graph, featureId, knowledgeNodes)` | Knowledge nodes that govern the given feature.                                                                                      |
+| `byKind(graph, kind, knowledgeNodes)`         | Filter knowledge nodes by `OrgKnowledgeKind`.                                                                                       |
+| `byOwner(graph, ownerId, knowledgeNodes)`     | Knowledge nodes whose `ownerIds` includes the given owner.                                                                          |
+| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-feature ids) from a knowledge node.                                                            |
+| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a feature.                                                           |
+| `parsePath(pathString)`                       | Parse `/by-feature/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
+| `formatText`, `formatJson`, `formatIdsOnly`   | Output formatters used by the `knowledge:*` CLI subcommands.                                                                        |
+
+## Path syntax
+
+```
+/by-feature/<featureId>
+/by-kind/<playbook|strategy|reference>
+/by-owner/<ownerId>
+/graph/<nodeId>/governs
+/graph/<nodeId>/governed-by
+/<nodeId>
+```
+
+## JSON envelope
+
+`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
+
+`governs` and `governedBy` accept either bare or graph-namespaced ids (`knowledge.foo` or `knowledge:knowledge.foo`).

package/reference/packages/ui/src/knowledge/README.md

@@ -0,0 +1,31 @@
+# @elevasis/ui/knowledge
+
+Read-only browser primitives for the Organization Model knowledge graph.
+
+## Surface
+
+| Export                                                                 | Purpose                                                                             |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `KnowledgeBrowser`                                                     | Selected-node detail pane. Tree/search now live in the feature sidebar.             |
+| `KnowledgeTree`                                                        | By-feature primary tree with hierarchical features and multi-governance duplication. |
+| `KnowledgeNodeList`                                                    | Legacy flat list of node summary cards; exported for compatibility.                 |
+| `KnowledgeNodeView`                                                    | Single knowledge-node detail view using `NodeDescribeShell` and relationship groups. |
+| `KnowledgeSearchBar`                                                   | Client-side search over `_generated/knowledge-search-index.json`.                   |
+| `KnowledgeSidebarMiddle`                                               | Deprecated legacy sidebar middle section; active sidebar lives under `features/knowledge/sidebar`. |
+| `KNOWLEDGE_ITEMS`                                                      | Deprecated default sidebar nav items retained for compatibility.                    |
+| `KnowledgeMDXProvider`, `useKnowledgeAllowlist`, `KNOWLEDGE_ALLOWLIST` | MDX runtime allowlist (`Card`, `Cards`, `Step`, `Steps`, `Callout`, `Tab`, `Tabs`). |
+| `KNOWLEDGE_BODIES`                                                     | Build-time-compiled MDX components keyed by node id.                                |
+
+## Customization tiers
+
+1. **Default** — mount `knowledgeManifest` from `@elevasis/ui/features/knowledge`.
+2. **Extend** — pass `extraComponents` to `KnowledgeMDXProvider` or compose around the feature sidebar primitives.
+3. **Replace** — call `@elevasis/core/knowledge` queries directly from project-owned routes.
+
+## Codegen
+
+`KNOWLEDGE_BODIES` and the search index are regenerated by `pnpm scaffold:sync` (or `pnpm knowledge:generate` to run only the knowledge step). Source: `canonicalOrganizationModel.knowledge.nodes` from `@repo/elevasis-core`.
+
+The Vite plugin at `@elevasis/ui/vite-plugin-knowledge` re-runs codegen on `buildStart` and watches the OM source dir for HMR.
+
+Phase 1 is read-only. Phase 2 will move bodies into Supabase and ship via `mdx-bundler`.

package/reference/packages/ui/src/theme/presets/README.md

@@ -0,0 +1,19 @@
+# Theme Presets
+
+Re-exports the canonical theme-preset SSOT from `@repo/core`. This subpath exists so that consumers can import preset metadata without pulling in the full theme runtime surface.
+
+## Exports
+
+- `THEME_PRESETS` — `as const` tuple of preset names; the single source of truth.
+- `ThemePresetName` — union type derived from `THEME_PRESETS`.
+- `ThemePresetEnum` — Zod enum derived from `THEME_PRESETS`.
+
+## Use When
+
+- You need a Zod-validated preset name (form schemas, API request/response validation).
+- You need the union type for component props or Zustand state.
+- You're adding a new preset and want to ensure it propagates everywhere via the canonical tuple.
+
+## Source Of Truth
+
+`packages/core/src/auth/multi-tenancy/theme-presets.ts`. This subpath is a thin re-export. The `ui → core` dependency stays one-directional; the runtime preset catalog (`presets`, `getPreset`) lives at `@repo/ui/theme` and consumes the names declared in core.

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

@@ -72,7 +72,7 @@ Authored fields:
 Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
 Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
 
-Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `operations.command-view` is intentionally development-only while its graph visualization modes continue to mature.
+Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
 ## Graph IDs and Resource Links
 

package/reference/scaffold/recipes/add-a-feature.md

@@ -22,7 +22,7 @@ const organizationOverride = defineOrganizationModel({
       label: 'Analytics',
       enabled: true,
       path: '/analytics',
-      icon: 'chart',
+      icon: 'custom.analytics',
       uiPosition: 'sidebar-primary'
     }
   ]

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -78,7 +78,7 @@ These wrap existing `LeadService` logic -- they are extraction, not new business
 
 Deploy a workflow with the same `workflowId` as the default action you want to replace. The resource registry resolves your project-owned workflow first.
 
-The canonical transition workflow (see `external/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+The canonical transition workflow (see `packages/elevasis-operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
 
 ```ts
 // operations/src/sales/crm/actions/move-to-proposal.ts
@@ -203,7 +203,7 @@ This controls the shared `DealDetailPage` and `DealDrawer` action row.
 
 For a brand-new action key that calls a project-owned workflow, define the workflow first.
 
-If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the workflow handler to append an audit entry to the deal's `activity_log`. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `external/elevasis/operations/src/sales/crm/actions/`.
+If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the workflow handler to append an audit entry to the deal's `activity_log`. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `packages/elevasis-operations/src/sales/crm/actions/`.
 
 ### Define the Workflow Contract
 
@@ -408,7 +408,7 @@ const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested'
 
 Workflows that write `state_key` should import from this definition rather than hardcoding string literals. This keeps the vocabulary in one place and lets the API validate against the allowed set for a deal's current stage.
 
-**Current gap:** `@elevasis/core` v0.13.0 does not yet expose the `organization-model` subpath. Until a new release ships that export, hardcoded strings in `external/elevasis/operations/...` are tracked as follow-up. Document usages with a `// TODO: replace with CRM_PIPELINE_DEFINITION import once @elevasis/core exposes organization-model` comment so they are easy to find.
+**Current gap:** `@elevasis/core` v0.13.0 does not yet expose the `organization-model` subpath. Until a new release ships that export, hardcoded strings in `packages/elevasis-operations/...` are tracked as follow-up. Document usages with a `// TODO: replace with CRM_PIPELINE_DEFINITION import once @elevasis/core exposes organization-model` comment so they are easy to find.
 
 ## Activity Log Conventions
 

package/reference/scaffold/recipes/customize-organization-model.md

@@ -36,14 +36,14 @@ const override = defineOrganizationModel({
       label: 'Dashboard',
       enabled: true,
       path: '/',
-      icon: 'dashboard',
+      icon: 'feature.dashboard',
       uiPosition: 'sidebar-primary'
     },
     {
       id: 'sales',
       label: 'Sales',
       enabled: true,
-      icon: 'briefcase',
+      icon: 'feature.sales',
       uiPosition: 'sidebar-primary'
     },
     {
@@ -71,7 +71,7 @@ Feature field reference:
 - `description` -- optional settings/help text.
 - `enabled` -- organization default.
 - `path` -- route path for leaf nodes. Containers omit it.
-- `icon` and `color` -- optional display metadata.
+- `icon` and `color` -- optional display metadata. Use semantic icon tokens such as `feature.dashboard`, `feature.sales`, or project-owned `custom.*` tokens; UI icon libraries are implementation details.
 - `uiPosition` -- `sidebar-primary` or `sidebar-bottom`; descendants inherit it.
 - `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
 - `devOnly` -- hides the node outside development contexts; descendants inherit it.

package/reference/scaffold/recipes/extend-crm.md

@@ -58,7 +58,9 @@ Read the generated contracts before changing typed boundaries:
 
 `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
-Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+
+Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
 
 ## 1. Extend CRM Navigation or Sidebar
 
@@ -192,13 +194,15 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
       outputSchema,
       next: null,
       handler: async (input) => {
-        const deals = await crm.listDeals({ stage: input.stage })
-
-        for (const deal of deals) {
-          await crm.createDealTask({
-            dealId: deal.id,
-            title: 'Follow up',
-            kind: 'email'
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
+
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
           })
           await crm.recordActivity({
             dealId: deal.id,