@elevasis/sdk 1.15.0 → 1.16.0

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

@@ -0,0 +1,1309 @@
+# Tutorial: Technical Track
+
+This file is loaded by `.claude/skills/tutorial/SKILL.md` when the user selects the technical
+track. Do not invoke this file directly -- the router reads it and dispatches to the lesson the
+user picks.
+
+Each lesson is a script for the teaching agent. Instructions in plain text address the agent
+("Read X", "Walk the user through Y"). User-facing strings are indented as block quotes.
+
+After each lesson, update `.claude/memory/tutorial-progress.md` by changing `[ ]` to
+`[x] YYYY-MM-DD` for that item. After completing any full section, redisplay the menu with
+updated markers.
+
+---
+
+## Menu
+
+```
+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                    [ ]
+```
+
+---
+
+## SECTION A -- The Workspace
+
+### Item 1: What is this workspace
+
+**Goal:** The user understands the three-layer project structure, the standalone repo model, and
+why the scaffold is described as an agent operating environment, not just an app starter.
+
+**Estimated time:** 15 min
+
+**Files referenced:** `.claude/rules/agent-start-here.md`, `CLAUDE.md`,
+`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+
+**Flow:**
+
+Open by reading `.claude/rules/agent-start-here.md` (the canonical first-read) and `CLAUDE.md`
+(the project bootstrap surface). Use both to anchor the explanation below.
+
+Open with the skip affordance:
+
+> "Item 1 covers what this workspace is and how it is structured. If you already know the
+> three-layer layout (ui / operations / core), the standalone repo model, and why the scaffold
+> is an agent operating environment, type 'skip' and I'll mark it complete."
+
+If the user skips, mark `[x] YYYY-MM-DD` in `.claude/memory/tutorial-progress.md` for item 1
+and move on.
+
+Otherwise, walk through the following:
+
+**Three runtime layers.** The template is divided into three directories with hard runtime
+boundaries:
+
+- `ui/` -- React 19 frontend (Vite, TanStack Router, Mantine). Browser runtime. Imports from
+  `core/` only.
+- `operations/` -- Platform workflows and agents (Elevasis SDK). Node target. Imports from
+  `core/` only.
+- `core/` -- Runtime-agnostic shared contracts: Zod schemas, TypeScript types, organization
+  model configuration. No React, no Node APIs, no SDK worker imports.
+
+Emphasize: `ui/` and `operations/` are separate runtimes. They communicate through the platform
+API at runtime. At build time they share types only via `core/`.
+
+**Standalone repo.** This project is NOT part of the monorepo pnpm workspace. It has its own
+`.git/`, own `pnpm-lock.yaml`, own `node_modules/`. The monorepo boundary hook does not apply
+here. Git, gh, and CLI commands work directly.
+
+**Agent operating environment.** Read the "Template Surfaces" section from `agent-start-here.md`
+aloud to the user. Key point: the `.claude/` directory is a first-class surface -- rules (always
+loaded), skills (invocable via slash commands), hooks (run on tool calls), and memory (persists
+across sessions). The scaffold is not just an app starter; the agent reads `.claude/rules/` on
+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
+patterns, the gating model, contracts, and a glossary. Whenever the user wants the authoritative
+answer on a scaffold surface (how to add a feature, extend an entity, wire a workflow), that
+index is the starting point.
+
+**Verification:** Ask the user: "Where does the agent look first when entering a session?" (Answer:
+`agent-start-here.md` via the always-loaded rules.) If they get it right, continue. If not, point
+them to the "First Action: Check Active Projects" and "Discovery Order" sections in
+`agent-start-here.md`.
+
+**Completion signal:** Mark `[ ] 1 What is this workspace` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 2: The skill layer -- slash commands you'll use
+
+**Goal:** The user knows all 12 slash commands, how to invoke them, where they live, and can
+demonstrate `/status` and `/project`.
+
+**Estimated time:** 15 min
+
+**Files referenced:** `.claude/skills/*/SKILL.md` (skim), `CLAUDE.md` slash command table
+
+**Flow:**
+
+Open with the skip affordance:
+
+> "Item 2 walks through the 12 slash commands in this scaffold. If you've already used them and
+> know where they live, type 'skip' and I'll mark it complete."
+
+If the user skips, mark complete and move on.
+
+Otherwise, read the Slash Commands table in `CLAUDE.md` aloud. Then explain the skill system:
+
+**Invocation pattern.** Every slash command is a skill. Type `/<name>` (optionally with args,
+e.g., `/knowledge features`). The agent reads `.claude/skills/<name>/SKILL.md` and follows its
+instructions. Skills may be context-forked (they run in a subagent) or inline. The frontmatter
+`context: fork` means a subagent handles it.
+
+**Where they live.** Each skill lives in `.claude/skills/<name>/SKILL.md`. Multi-step operations
+that belong to a skill (but are too large for `SKILL.md`) live in
+`.claude/skills/<name>/operations/<op>.md`.
+
+**How the agent knows to use them.** The `description` frontmatter field (or `metadata.promptSignals`)
+tells the agent when to auto-invoke a skill without an explicit slash command. For example,
+`/knowledge` auto-invokes whenever the conversation references org-model entities.
+
+Walk through each of the 12 commands:
+
+- `/setup` -- first-time bootstrap: placeholder replacement, deps, verification, then hands off
+  to `/knowledge`
+- `/save` -- conversation fanout: updates knowledge docs, persists `prj_tasks.resume_context`
+  via `elevasis-sdk project:task:save`, creates a project note on blockers/status signals
+- `/dsp` -- parallel agent dispatch for implementation tasks with multiple independent steps
+- `/deploy` -- test, build, commit, push pipeline
+- `/explore` -- codebase exploration anchored to docs
+- `/git-sync` -- pull latest changes, surface new template sync notes, install when needed,
+  run baseline verification, then stop before manual reconciliation
+- `/status` -- quick project health check
+- `/project` -- primary work-tracking entry point; portfolio orientation, intent detection
+  (resume vs new), and project/milestone/task/note lifecycle via `elevasis-sdk project:*`
+- `/elevasis` -- SDK operations: check, deploy, exec, describe, logs, creds
+- `/sync` -- fresh reinstall and cache reset when local deps or build caches are stale
+- `/knowledge` -- org model ceremony: read, codify, toggle, layered flow for identity through
+  goals
+- `/submit-request` -- submit a structured request (bug, feature, support) to the platform
+
+**Demo 1: `/status`.** Ask the user to type `/status`. Narrate what it shows: project health
+summary, active projects, recent executions if any.
+
+**Demo 2: `/project`.** Ask the user to type `/project`. Walk them through the portfolio
+orientation output. Show how to create a task: `/project create task --title "My first task"`.
+
+**Verification:** The user can name any 3 commands unprompted and describe what they do.
+
+**Completion signal:** Mark `[ ] 2 The skill layer` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 3: The vibe layer -- ambient intent classification
+
+**Goal:** The user understands the 7-intent classifier, can recognize when it fires, and knows
+it is absent in the monorepo.
+
+**Estimated time:** 15 min
+
+**Files referenced:** `.claude/rules/vibe.md`, `CLAUDE.md` ambient vibe section
+
+**Flow:**
+
+Open with the skip affordance:
+
+> "Item 3 covers the vibe layer -- an ambient intent classifier that fires on every natural-language
+> message. If you already know the 7 intent types and how the classifier routes them, type 'skip'
+> and I'll mark it complete."
+
+If the user skips, mark complete and move on.
+
+Otherwise, read `.claude/rules/vibe.md` before explaining. Then walk through:
+
+**What vibe is.** Every natural-language message in an external project passes through the vibe
+classifier before the agent acts. No slash command, no activation phrase. The agent silently
+classifies the message into one of seven intent types and routes to the right behavior. The user
+never sees the classification.
+
+**The seven intent types.** Walk through each by name with one fixture example:
+
+- **Capture** -- "Add a task to follow up with the Shopify client." Agent drafts, confirms,
+  writes via `elevasis-sdk project:*`.
+- **Query** -- "What's pending in the HITL queue?" Agent reads and narrates.
+- **Describe** -- "What's going on with this deal?" Agent narrates from org model labels.
+- **Transition** -- "Done with the proposal draft." Agent confirms, updates task status via
+  `elevasis-sdk project:task:save`.
+- **Navigate** -- "Let's focus on the onboarding flow." Agent updates scope, narrates the shift.
+- **Codify** -- "We track deals by Shopify platform." Agent detects new organizational reality
+  and delegates to `/knowledge`.
+- **Toggle** -- "Turn on the lead-gen feature." Agent delegates to `/knowledge features`.
+
+**Important behavioral rules.** Codify and Toggle delegate immediately to `/knowledge` -- the
+vibe layer detects intent but does NOT run the ceremony itself. The ceremony (snapshot, propose,
+confirm, write, validate, rollback) belongs to `/knowledge`. Ambiguous messages get one
+clarifying question; no precedence rule is applied.
+
+**Where it applies.** Vibe is always-on in external projects. It is explicitly OFF in the
+monorepo. The monorepo uses task-class routing via `agent-start-here.md` instead. If the user is
+working inside the monorepo (`apps/`, `packages/`, etc.), vibe does not fire.
+
+**Reference.** The full classifier definition, fixture tables, and codify heuristics live in
+`.claude/rules/vibe.md`. The `CLAUDE.md` table is a pointer -- for authoritative behavior, read
+the rule file.
+
+**Verification:** Ask "What happens when you type 'turn on SEO'?" Answer: Vibe classifies it as
+Toggle intent and delegates to `/knowledge features` without running the ceremony itself.
+
+**Completion signal:** Mark `[ ] 3 The vibe layer` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+## SECTION B -- Build Your First Thing
+
+### Item 4: Echo workflow tour
+
+**Goal:** The user reads the echo workflow source, validates it, deploys it, and executes it
+end-to-end.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `operations/src/example/echo.ts`, `core/types/index.ts`,
+`operations/src/index.ts`
+
+**Commands:** `pnpm -C operations check`, `pnpm -C operations deploy`,
+`pnpm elevasis-sdk exec echo --input '{"message":"hi"}'`
+
+**Flow:**
+
+Tell the user:
+
+> "Let's tour the echo workflow -- the starter resource that ships with every template project.
+> We'll read the source, run the validator, deploy it, and execute it."
+
+**Step 1: Read the source.** Open `operations/src/example/echo.ts` with the user. Walk through
+each section:
+
+- `config` block: `resourceId` (the deploy-time unique ID), `name`, `type: 'workflow'`,
+  `description`, `version` (semver, bump on contract changes), `status: 'dev'` (new resources
+  start here; `'prod'` means visible to end users in the production environment).
+- `contract` block: `inputSchema` and `outputSchema` are imported from `core/types/index.ts`,
+  NOT defined inline. This is the pattern: schemas live in `core/` so both the frontend and
+  `operations/` can import them without creating a dependency cycle.
+- `steps` map: each step has `id`, `name`, `description`, a `handler` async function, and
+  `next: null` (last step). The handler receives `input` and `context`. `context.logger.info()`
+  is the correct logging call -- `console.log` is not captured by the platform.
+- `entryPoint`: the key from `steps` that runs first.
+- `interface.form`: defines the UI form the Command Center renders when a user triggers this
+  workflow manually.
+
+**Step 2: Validate.** Run:
+
+```bash
+pnpm -C operations check
+```
+
+Show the output. Explain: this catches duplicate `resourceId`s, broken step chains (`next`
+referencing a non-existent step), invalid schema serialization, and other errors the platform
+would reject at deploy time. Exit code 0 = pass.
+
+**Step 3: Deploy.** Run:
+
+```bash
+pnpm -C operations deploy
+```
+
+Walk through the output stages: Authenticating, Validating, Bundling (esbuild packages
+`operations/src/index.ts` and all dependencies into a single CJS file), Uploading. After deploy,
+resources are live immediately -- no restart required.
+
+**Step 4: Execute.** Run:
+
+```bash
+pnpm elevasis-sdk exec echo --input '{"message":"hi"}'
+```
+
+Show the output: status, duration, and output `{ "echo": "hi" }`. Explain: the platform
+validated `{"message":"hi"}` against `echoInputSchema`, spun up an ephemeral worker thread,
+ran the handler, returned the result, and terminated the worker.
+
+**Step 5: Check history.** Run:
+
+```bash
+pnpm elevasis-sdk executions echo
+```
+
+Pick the execution ID from the list and run:
+
+```bash
+pnpm elevasis-sdk execution echo <execution-id>
+```
+
+Show the full detail including logs. Point out the `[echo] Received message: "hi"` log line
+emitted by `context.logger.info()` in the handler.
+
+**Verification:** The user sees the execution complete with `{ "echo": "hi" }` output.
+
+**Completion signal:** Mark `[ ] 4 Echo workflow tour` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 5: Custom workflow with schemas
+
+**Goal:** The user creates a new workflow in its own domain directory, defines a Zod input schema
+in `core/types/`, registers it in `operations/src/index.ts`, and validates it.
+
+**Estimated time:** 25 min
+
+**Files referenced:** `operations/src/example/echo.ts` (model), `core/types/index.ts`,
+`operations/src/index.ts`
+
+**Commands:** `pnpm -C operations check`, `pnpm -C core check-types`
+
+**Flow:**
+
+Tell the user:
+
+> "Now you'll build a real workflow from scratch. We'll pick a domain for your project, define
+> the input and output schemas in `core/types/`, author the workflow in `operations/src/`, and
+> register it."
+
+**Step 1: Pick a domain.** Ask the user what their project does -- even a rough description is
+enough. Suggest a simple workflow relevant to their context (e.g., "classify a support ticket",
+"score a lead", "send a notification on a Stripe event"). Name the domain in kebab-case.
+
+**Step 2: Define schemas in `core/types/`.** Open `core/types/index.ts`. Walk the user through
+the schema convention:
+
+```typescript
+export const myWorkflowInputSchema = z.object({
+  // define fields here
+})
+export type MyWorkflowInput = z.infer<typeof myWorkflowInputSchema>
+
+export const myWorkflowOutputSchema = z.object({
+  // define fields here
+})
+export type MyWorkflowOutput = z.infer<typeof myWorkflowOutputSchema>
+```
+
+Explain: `z.infer` gives you a TypeScript type from the schema so the type system can check your
+handlers. You define once, get both runtime validation and compile-time inference. The schema
+lives in `core/` so the frontend can import it for form validation without importing SDK worker
+code.
+
+Explain common field types: `z.string()`, `z.number()`, `z.boolean()`, `z.enum([...])`,
+`z.string().optional()`, `z.object({...})`, `z.array(z.string())`.
+
+After writing the schemas, run:
+
+```bash
+pnpm -C core check-types
+```
+
+Fix any TypeScript errors before continuing.
+
+**Step 3: Create the domain directory.** Create `operations/src/<domain>/` with two files:
+`index.ts` (the domain barrel) and `<workflow-name>.ts` (the workflow implementation). Mirror
+the echo structure but use the new schemas imported from `@core/types`.
+
+Key points to emphasize:
+
+- `resourceId` must be unique within the organization (kebab-case).
+- `status: 'dev'` for new resources.
+- `next: null` on the last step.
+- Import schemas from `@core/types`, never define them inline in the workflow file.
+
+**Step 4: Register in `operations/src/index.ts`.** Show the current registry:
+
+```typescript
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
+```
+
+Add the new domain import and spread its `workflows` into the `DeploymentSpec`.
+
+**Step 5: Validate.** Run `pnpm -C operations check`. The output should now show N+1 resources
+with 0 errors.
+
+**Verification:** `pnpm -C operations check` passes with the new workflow listed.
+
+**Completion signal:** Mark `[ ] 5 Custom workflow with schemas` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 6: Platform tools and credentials
+
+**Goal:** The user understands singleton adapters vs factory adapters, imports them correctly,
+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`
+
+**Flow:**
+
+Tell the user:
+
+> "The platform provides typed adapters for external services: CRM, email, payments, AI, storage,
+> and more. You call them from workflow handlers without putting API keys in your code."
+
+**Singleton adapters.** Import once at the top of the worker file, use directly:
+
+```typescript
+import { llm, scheduler, storage, notifications } from '@elevasis/sdk/worker'
+```
+
+These are singletons -- no credential binding at construction. They use platform-managed config.
+Use them for: LLM generation, scheduling, object storage, in-app notifications.
+
+**Factory adapters.** Credential-bound: constructed with a credential name, then used:
+
+```typescript
+import { createAttioAdapter } from '@elevasis/sdk/worker'
+
+const attio = createAttioAdapter('my-attio-cred')
+// inside a step handler:
+await attio.createRecord({ ... })
+```
+
+The string `'my-attio-cred'` is the credential name you register in Command Center. The naming
+convention is `{org}-{service}` kebab-case, e.g. `acme-attio`, `acme-stripe`.
+
+**Credential setup in Command Center.** Walk the user through: Command Center -> Settings ->
+Credentials -> Create. The credential is stored encrypted on the platform. Workers access it at
+runtime through the adapter. It never appears in code or `.env`. The `.env` file holds only
+`ELEVASIS_PLATFORM_KEY` for CLI authentication.
+
+**Common error.** `PlatformToolError: credential not found` means the credential name in code
+does not exactly match what was created in Command Center. Check spelling and case; credential
+names are case-sensitive.
+
+**CLI credential management.** Show the `/elevasis creds` surface as an alternative to the UI:
+
+```bash
+pnpm elevasis-sdk creds list
+pnpm elevasis-sdk creds create --name acme-attio --type api-key --value '{"apiKey":"..."}'
+```
+
+**Verification:** Ask: "Where do integration credentials live at runtime?" Answer: on the platform,
+injected by the worker runtime. Not in `.env`, not in code.
+
+**Completion signal:** Mark `[ ] 6 Platform tools and credentials` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 7: Multi-step and conditionals
+
+**Goal:** The user implements a two-step LINEAR workflow and a CONDITIONAL workflow, understanding
+how data flows between steps.
+
+**Estimated time:** 25 min
+
+**Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`,
+`apps/docs/content/docs/sdk/concepts.mdx` (design decisions section)
+
+**Flow:**
+
+**Step 1: LINEAR steps.** Extend the workflow from Item 5 (or create a new one) to add a second
+step. Show the `next` field on step 1 pointing to the key of step 2:
+
+```typescript
+steps: {
+  fetchData: {
+    id: 'fetchData',
+    name: 'Fetch Data',
+    handler: async (input, context) => {
+      // ... fetch or compute something
+      return { result: 'some-value' }
+    },
+    inputSchema: myInputSchema,
+    outputSchema: z.object({ result: z.string() }),
+    next: 'processData'       // <-- key of the next step
+  },
+  processData: {
+    id: 'processData',
+    name: 'Process Data',
+    handler: async (input, context) => {
+      const { result } = input  // receives output from fetchData
+      return { finalResult: result.toUpperCase() }
+    },
+    inputSchema: z.object({ result: z.string() }),
+    outputSchema: myOutputSchema,
+    next: null
+  }
+},
+entryPoint: 'fetchData'
+```
+
+Emphasize: the output schema of step N must match the input schema of step N+1. The platform
+validates this chain at deploy time. Data passes from step to step -- no global state, no shared
+variables.
+
+**Step 2: CONDITIONAL routing.** Import `StepType` and show a conditional branch:
+
+```typescript
+import type { WorkflowDefinition, StepType } from '@elevasis/sdk'
+
+// ... inside steps:
+routeStep: {
+  id: 'routeStep',
+  type: StepType.CONDITIONAL,
+  name: 'Route by Score',
+  handler: async (input, context) => {
+    if (input.score >= 80) return { path: 'approve', ...input }
+    if (input.score >= 50) return { path: 'review', ...input }
+    return { path: 'reject', ...input }
+  },
+  routes: {
+    approve: 'approveStep',
+    review: 'reviewStep',
+    default: 'rejectStep'   // always include a default
+  },
+  // ...
+}
+```
+
+Always include a `default` route. Without it, an execution whose output does not match any
+explicit key will fail at runtime.
+
+**Verification:** `pnpm -C operations check` passes with the multi-step workflow registered. Ask
+the user what happens if they omit the `default` route (runtime failure for unmatched paths).
+
+**Completion signal:** Mark `[ ] 7 Multi-step and conditionals` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 8: Going to production
+
+**Goal:** The user knows the dev/prod split, version bumping flags, and the `cli-cwd-invariant`
+rule for `--prod` flag placement.
+
+**Estimated time:** 15 min
+
+**Files referenced:** `.claude/rules/deployment.md`, `.claude/rules/cli-cwd-invariant.md`
+
+**Commands:** `pnpm -C operations deploy:prod`
+
+**Flow:**
+
+**Dev vs prod targeting.** The default `pnpm -C operations deploy` targets the development
+environment. To deploy to production:
+
+```bash
+pnpm -C operations deploy:prod
+```
+
+In `config.status`: `'dev'` means the resource is visible only in dev mode. Change to `'prod'`
+before deploying to production -- otherwise the resource deploys but is not exposed in the
+production surface.
+
+**Version bumping.** The deploy command accepts version bump flags that are written back to
+`operations/src/index.ts`:
+
+```bash
+pnpm -C operations deploy:prod   # no bump (same version)
+# or pass a flag via pnpm scripts if wired in package.json:
+pnpm elevasis-sdk deploy --prod --patch   # 1.0.0 -> 1.0.1
+pnpm elevasis-sdk deploy --prod --minor   # 1.0.0 -> 1.1.0
+pnpm elevasis-sdk deploy --prod --major   # 1.0.0 -> 2.0.0
+```
+
+Bump rules: `--patch` for bug fixes, `--minor` for new features (no breaking schema changes),
+`--major` for breaking input/output schema changes.
+
+**The `cli-cwd-invariant`.** Read `.claude/rules/cli-cwd-invariant.md`. Two critical rules:
+
+1. The `--prod` flag on the `elevasis-sdk` binary MUST come before the subcommand name:
+
+   ```bash
+   # Correct
+   pnpm elevasis-sdk --prod deploy
+   # Wrong -- --prod after deploy is silently ignored
+   pnpm elevasis-sdk deploy --prod
+   ```
+
+   The `pnpm -C operations deploy:prod` script in `package.json` handles this correctly.
+   Prefer the script over a raw CLI call to avoid the pitfall.
+
+2. Never use bare `cd <dir> && elevasis-sdk ...` -- use a subshell `(cd <dir> && ...)` or
+   `pnpm -C <dir> ...` to avoid CWD drift that causes env resolution failures.
+
+**Standard pre-production checklist.** Walk the user through:
+
+```
+1. pnpm -C operations check        -- validate resources
+2. pnpm -C operations check-types  -- TypeScript type-check
+3. pnpm elevasis-sdk exec <id> -i '...'   -- test in dev
+4. pnpm -C operations deploy:prod  -- ship to prod
+```
+
+**Verification:** The user can explain where `--prod` must be placed and why.
+
+**Completion signal:** Mark `[ ] 8 Going to production` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+## SECTION C -- The Organization Model
+
+### Item 9: /knowledge ceremony -- identity, customers, offerings via the layered flow
+
+**Goal:** The user runs `/knowledge` and understands the six-step write ceremony, why direct
+edits to `core/config/organization-model.ts` are blocked, and the layered flow order.
+
+**Estimated time:** 25 min
+
+**Files referenced:** `.claude/skills/knowledge/SKILL.md`, `core/config/organization-model.ts`,
+`.claude/rules/organization-os.md`
+
+**Flow:**
+
+Tell the user:
+
+> "The organization model is the semantic contract layer that defines your business reality:
+> who you are, who your customers are, what you offer, your team, and your goals. All edits go
+> through `/knowledge` -- not direct file edits."
+
+**Why direct edits are blocked.** Read `core/config/organization-model.ts`. The file calls
+`resolveOrganizationModel()` which runs Zod cross-reference validation: every customer segment
+referenced in offerings must exist in `customers`, every resource mapping must reference a valid
+feature ID, and so on. A direct edit that passes TypeScript can still fail the cross-ref check,
+leaving the project in a broken state. The `/knowledge` ceremony runs both checks and rolls back
+on failure.
+
+**The six-step ceremony.** Walk through `.claude/skills/knowledge/SKILL.md`:
+
+1. **Snapshot** -- reads `core/config/organization-model.ts` into memory before any edit
+2. **Propose** -- shows the diff and the proposed new value alongside current value
+3. **Confirm** -- pauses for explicit user confirmation; never writes without a clear yes
+4. **Write** -- applies the edit
+5. **Validate** -- runs `pnpm -C operations check-types` (TypeScript) then `pnpm -C operations
+check` (Zod parse via `resolveOrganizationModel()`)
+6. **Rollback** -- if either check fails, restores from the Step 1 snapshot
+
+**The layered flow.** Run `/knowledge` with no argument to walk through the full flow:
+identity -> customers -> offerings -> roles -> goals -> techStack. The agent reads the current
+state of each domain, proposes any missing or incomplete fields, and asks for confirmation before
+writing.
+
+Or target a specific domain:
+
+- `/knowledge identity` -- legal name, mission/vision, industry, geography, timezone
+- `/knowledge customers` -- customer segments with jobs-to-be-done, pains, gains
+- `/knowledge offerings` -- products and services with pricing model and segment references
+- `/knowledge roles` -- role chart with responsibilities and reporting lines
+- `/knowledge goals` -- organizational goals with period and measurable outcomes
+- `/knowledge techStack` -- external SaaS integration metadata on resource mappings
+
+**Demo.** Ask the user to run `/knowledge identity`. Walk through the ceremony together -- read
+the current state, propose an edit, confirm, watch it validate.
+
+**Verification:** The user can describe what `resolveOrganizationModel()` does and why the
+rollback step exists.
+
+**Completion signal:** Mark `[ ] 9 /knowledge ceremony` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 10: Features and labels
+
+**Goal:** The user can enable/disable a feature via `/knowledge features` and rename a display
+label via `/knowledge labels`.
+
+**Estimated time:** 15 min
+
+**Files referenced:** `.claude/skills/knowledge/operations/features.md`,
+`.claude/skills/knowledge/operations/labels.md`, `core/config/organization-model.ts`
+
+**Flow:**
+
+**Features.** The org model has a `features` domain that controls which platform features are
+active for this project. Toggle by running:
+
+```
+/knowledge features
+```
+
+The ceremony proposes the change (e.g., `seo: false -> true`), asks for confirmation, writes,
+and validates. The TypeScript constant names are stable (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`,
+`PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`,
+`SEO_FEATURE_ID`) -- use these constants instead of magic strings when writing workflow code that
+references feature IDs.
+
+Feature toggles affect the UI shell: a disabled feature removes its nav entry and routes from
+the shell. The org model is the single gate for all feature visibility.
+
+**Labels.** The `labels` domain controls display strings on enum entries -- CRM pipeline stages,
+lead-gen lifecycle statuses, project statuses, and so on. Rename by running:
+
+```
+/knowledge labels
+```
+
+The agent reads the current enum entries (each carries an `id`, `label`, and `semanticClass`
+field), proposes a label rename, and writes through the ceremony. The `semanticClass` field
+should not change -- it maps to semantic behavior like `blocked`, `in_progress`, `complete`.
+
+Show an example: renaming the `discovery` CRM stage to `qualification`.
+
+**Verification:** Ask: "What is the difference between a feature toggle and a label rename?"
+(Toggle controls visibility/routing. Label rename changes display text on an existing enum
+entry without changing its semantic ID or behavior.)
+
+**Completion signal:** Mark `[ ] 10 Features and labels` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 11: Entity extensions -- BaseProject, BaseDeal
+
+**Goal:** The user reads the entity extension pattern in `core/types/entities.ts` and understands
+how to add project-specific metadata fields to base entities.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `core/types/entities.ts`, `core/config/organization-model.ts`
+(for the `resourceMappings` context)
+
+**Flow:**
+
+**Read the demo extension.** Open `core/types/entities.ts`. Walk through both patterns it
+demonstrates:
+
+**Pattern 1: extend with metadata.**
+
+```typescript
+import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
+
+export const ProjectMetaSchema = z.object({
+  budget: z.number().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+export type Project = BaseProject<ProjectMeta>
+```
+
+The base types from `@elevasis/core/entities` are generic over a `\<TMeta>` slot. You pass your
+metadata type to specialize the base. `BaseProjectSchema.extend(...)` is the Zod idiom; the
+TypeScript type is `BaseProject<ProjectMeta>`.
+
+**Pattern 2: use a base entity unchanged.**
+
+```typescript
+export const DealSchema = BaseDealSchema
+export type Deal = BaseDeal
+```
+
+When you have no project-specific fields, re-export the base. This keeps the import path
+consistent (`@core/types` everywhere) while avoiding redundant extension.
+
+**Using entity types in workflows.** When authoring a workflow that receives or returns a
+Project or Deal, reference these types in the input/output schemas rather than re-declaring the
+shape. This ensures the workflow contract stays in sync with the entity definition as it evolves.
+
+**Reference for all base shapes.** `@elevasis/core/entities` exports: `BaseProject`,
+`BaseProjectSchema`, `BaseProjectInput`, `BaseMilestone`, `BaseMilestoneSchema`,
+`BaseTask`, `BaseTaskSchema`, `BaseDeal`, `BaseDealSchema`, `BaseCompany`, `BaseCompanySchema`,
+`BaseContact`, `BaseContactSchema`.
+
+**Domain rename note.** In `core/config/organization-model.ts`, the domain config fields were
+renamed in the 2026-04-20 expansion: `crm` -> `sales`, `leadGen` -> `prospecting`,
+`delivery` -> `projects`. The feature ID constants (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`,
+`PROJECTS_FEATURE_ID`) are unchanged -- use the constants, not the field names, when referencing
+features in code.
+
+**Verification:** The user can explain when to use Pattern 1 vs Pattern 2 and name two base
+entity types they could extend.
+
+**Completion signal:** Mark `[ ] 11 Entity extensions` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+## SECTION D -- Modules (load on demand)
+
+Modules in Section D are available any time. No Section B or C prerequisites are enforced. After
+completing a module, redisplay the full menu with updated progress markers.
+
+---
+
+### Item 12: HITL
+
+**Goal:** The user implements an approval gate using `approval.create()` and understands the
+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`
+
+**Flow:**
+
+**What HITL is.** Human-in-the-Loop (HITL) pauses a workflow execution and waits for a human
+decision before continuing. The execution is suspended at the approval gate; the platform stores
+the pending state. When a user approves or rejects in Command Center, the execution resumes.
+
+**Implementation.** Import `approval` from `@elevasis/sdk/worker` and call it inside a step
+handler:
+
+```typescript
+import { approval } from '@elevasis/sdk/worker'
+
+const decision = await approval.create({
+  title: 'Approve Invoice',
+  description: `Invoice #${input.invoiceId} for $${input.amount} ready for approval.`,
+  context: { invoiceId: input.invoiceId, amount: input.amount }
+})
+
+if (decision.approved) {
+  // continue the workflow
+} else {
+  // handle rejection
+}
+```
+
+**Lifecycle.** The step calls `approval.create()` -> platform suspends the execution -> a
+pending item appears in the Command Queue in Command Center -> user reviews and approves or
+rejects -> execution resumes from the same step with `decision.approved` set.
+
+**Variant rule.** Always use `variant: 'light'` (hardcoded by the platform; never pass `variant`
+in the `approval.create()` call -- the field does not exist on the call signature and will cause
+a TypeScript error).
+
+**Verify.** Deploy the workflow, execute it, confirm that it appears as pending in Command Center
+Command Queue, approve it, and confirm the execution completes.
+
+**Completion signal:** Mark `[ ] 12 HITL` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 13: Schedules
+
+**Goal:** The user understands the three Task Scheduler types (Recurring, Relative, Absolute),
+uses the `scheduler` singleton inside a workflow, and knows the cron syntax the platform accepts.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+
+**Flow:**
+
+**The `scheduler` singleton.** Import from `@elevasis/sdk/worker` to trigger workflow actions
+from within a running step:
+
+```typescript
+import { scheduler } from '@elevasis/sdk/worker'
+
+await scheduler.schedule({
+  resourceId: 'my-workflow',
+  triggerAt: new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now
+  input: { ... }
+})
+```
+
+**Task Scheduler UI -- three types.** Walk the user through Command Center -> Task Scheduler:
+
+- **Recurring** -- cron-based, runs on a schedule. Standard cron syntax: `0 9 * * 1-5` (9am
+  weekdays). The platform interprets cron in UTC.
+- **Relative** -- fires N minutes/hours/days after a trigger event (e.g., "24 hours after a
+  deal enters a stage").
+- **Absolute** -- fires at a specific UTC datetime (one-shot, not recurring).
+
+**Creating a schedule.** Show the Task Scheduler create flow: select resource, choose type,
+configure the trigger, set input. Schedules appear as `workflow_schedules` rows in the DB -- the
+`elevasis-sdk executions` command shows executions triggered by schedules alongside manual ones.
+
+**Verification:** Ask: "What time zone does the platform use for cron expressions?" (UTC.)
+
+**Completion signal:** Mark `[ ] 13 Schedules` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 14: Notifications + integrations
+
+**Goal:** The user uses the `notifications` and `email` singletons and wires a real integration
+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`
+
+**Flow:**
+
+**`notifications` singleton.** Sends in-app notifications visible in Command Center:
+
+```typescript
+import { notifications } from '@elevasis/sdk/worker'
+
+await notifications.send({
+  title: 'Campaign complete',
+  message: `Processed ${count} leads.`,
+  level: 'info'  // 'info' | 'warning' | 'error'
+})
+```
+
+**`email` singleton.** Sends transactional email through the platform's configured mail provider:
+
+```typescript
+import { email } from '@elevasis/sdk/worker'
+
+await email.send({
+  to: 'user@example.com',
+  subject: 'Your report is ready',
+  body: 'Here is a summary...'
+})
+```
+
+**Real adapter integration.** Read `core/config/organization-model.ts` and find the
+`resourceMappings` entries. Each entry may carry a `techStack` extension showing the platform
+(`attio`, `stripe`, `apify`, etc.), the credential name, and whether a credential is configured.
+Use the credential name from there as the constructor argument:
+
+```typescript
+import { createAttioAdapter } from '@elevasis/sdk/worker'
+const attio = createAttioAdapter('acme-attio')
+```
+
+Walk the user through the end-to-end: create the credential in Command Center, reference it in
+the adapter constructor, deploy, execute a test run, check that the integration call succeeds.
+
+**Common error.** If the credential is missing or misspelled, the adapter throws
+`PlatformToolError: credential not found`. Check the exact name in Command Center.
+
+**Verification:** A test execution that calls the integration adapter completes without a
+`PlatformToolError`.
+
+**Completion signal:** Mark `[ ] 14 Notifications + integrations` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 15: Error handling
+
+**Goal:** The user knows the three error types, uses `context.logger`, and implements a
+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`
+
+**Flow:**
+
+Read `.claude/rules/error-handling.md` before starting. Then walk through each error type:
+
+**`ExecutionError`.** Base class for workflow/step failures. Throw to halt an execution with a
+user-readable message:
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk'
+
+throw new ExecutionError('Payment processing failed', {
+  context: { invoiceId: input.invoiceId }
+})
+```
+
+**`PlatformToolError`.** Thrown by `platform.call()` and typed adapters when an integration
+call fails. Always check `err.retryable`:
+
+```typescript
+import { PlatformToolError } from '@elevasis/sdk'
+
+try {
+  await attio.createRecord({ ... })
+} catch (err) {
+  if (err instanceof PlatformToolError) {
+    if (err.retryable) {
+      context.logger.warn(`Transient error (rate limit or timeout): ${err.message}`)
+      // safe to retry or re-throw for the caller to handle
+    } else {
+      throw new ExecutionError(`Permanent integration error: ${err.message}`)
+    }
+  }
+  throw err
+}
+```
+
+**`ToolingError`.** Internal SDK infrastructure error. Treat as non-retryable.
+
+**`context.logger`.** Use it for all logging inside handlers. `console.log` is not captured by
+the platform worker runtime. Log levels: `debug`, `info`, `warn`, `error`. The error message in
+an unhandled throw surfaces directly to CLI output and Command Center -- write it for humans.
+
+**Common retryable codes.** `rate_limit_exceeded` and `timeout_error` are retryable.
+`credentials_invalid` and `validation_error` are not.
+
+**Verification:** Demonstrate a handler that catches a `PlatformToolError`, checks `retryable`,
+logs appropriately, and re-throws as an `ExecutionError` with a clear message.
+
+**Completion signal:** Mark `[ ] 15 Error handling` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 16: LLM and agents
+
+**Goal:** The user calls `llm.generate()` with structured output (Zod -> JSON Schema -> typed
+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`,
+`apps/docs/content/docs/sdk/concepts.mdx` (workflow vs agent section)
+
+**Flow:**
+
+**`llm.generate()` with structured output.** The `llm` singleton from `@elevasis/sdk/worker`
+accepts a Zod output schema and returns a typed result:
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const classificationSchema = z.object({
+  category: z.enum(['support', 'billing', 'feature-request', 'other']),
+  confidence: z.number().min(0).max(1),
+  summary: z.string()
+})
+
+const result = await llm.generate({
+  prompt: `Classify this ticket: ${input.ticketBody}`,
+  outputSchema: classificationSchema,
+  model: 'gpt-4o',
+  temperature: 0.2
+})
+
+// result is typed as z.infer<typeof classificationSchema>
+context.logger.info(`Classified as: ${result.category} (${result.confidence})`)
+```
+
+The SDK converts the Zod schema to JSON Schema internally. The LLM is instructed to return JSON
+matching that shape. The result is validated and returned as the inferred TypeScript type.
+
+**Agent definition vs workflow definition.** Read the glossary entries from
+`apps/docs/content/docs/sdk/concepts.mdx`:
+
+- **Workflow** -- deterministic, step-by-step, 300s timeout. Use when inputs and outputs are
+  known and the process is predefined.
+- **Agent** -- autonomous, tool-calling, 600s timeout (configurable). Use when the agent needs
+  to make decisions, call tools iteratively, or navigate ambiguous inputs.
+
+When to use an agent: the task requires the LLM to decide WHICH tools to call and in WHAT order
+based on what it finds (not predetermined routing). When to use a workflow: the sequence of steps
+is predetermined, even if LLM judgment is involved inside individual steps.
+
+**Model selection.** `gpt-4o` for complex reasoning, `gpt-4o-mini` for speed-sensitive tasks,
+`o3-mini` for multi-step reasoning chains. Temperature: `0.0` for deterministic classification,
+`0.2-0.4` for structured extraction, `0.7+` for creative generation.
+
+**Verification:** A workflow step calls `llm.generate()` with a Zod schema and returns a typed
+value. The type system confirms the result matches the schema without a cast.
+
+**Completion signal:** Mark `[ ] 16 LLM and agents` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 17: Composition (execution.trigger)
+
+**Goal:** The user chains two workflows using `execution.trigger()`, declares the relationship in
+`DeploymentSpec`, and can find the edge in Command View.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `operations/src/index.ts`,
+`node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md`
+
+**Flow:**
+
+**`execution.trigger()`.** Call from inside a step handler to launch another workflow
+asynchronously:
+
+```typescript
+import { execution } from '@elevasis/sdk/worker'
+
+const { executionId } = await execution.trigger({
+  resourceId: 'downstream-workflow',
+  input: { ...outputFromCurrentStep }
+})
+
+context.logger.info(`Triggered downstream-workflow: ${executionId}`)
+```
+
+The calling step does not wait for the downstream workflow to complete. If you need the result,
+use async polling or chain via HITL.
+
+**Declare the relationship in `DeploymentSpec`.** In `operations/src/index.ts`, add a
+`relationships` entry so the platform knows this workflow triggers another:
+
+```typescript
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  workflows: [...],
+  agents: [...],
+  relationships: [
+    {
+      source: 'upstream-workflow',
+      target: 'downstream-workflow',
+      type: 'triggers'
+    }
+  ]
+}
+```
+
+This metadata populates the Command View graph. Without it, the edge is not visible in the UI
+even if the trigger call works.
+
+**Command View.** Show the user how to find Command View in Command Center -> Operations.
+Deployed relationships appear as directed edges between resource nodes. This is the primary
+debugging surface for understanding how automations are connected.
+
+**Verification:** Deploy both workflows with the relationship declared, then view the edge in
+Command View.
+
+**Completion signal:** Mark `[ ] 17 Composition` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+## SECTION E -- Power User
+
+### Item 18: Rules, memory, scaffold registry
+
+**Goal:** The user can navigate the `.claude/rules/` and `.claude/memory/` directories and
+understands the scaffold registry's purpose.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `.claude/rules/` (all files), `.claude/memory/` (layout),
+`.claude/scaffold-registry.yml` (reference, monorepo-side concept)
+
+**Flow:**
+
+**Rules directory.** List the current rule files in `.claude/rules/`. Each rule is automatically
+loaded by the agent on every session based on its `paths:` frontmatter (path globs that trigger
+auto-load). Key files:
+
+- `agent-start-here.md` -- always-loaded canonical first-read; task-class routing and boundary
+  resolution
+- `vibe.md` -- always-loaded ambient intent classifier
+- `organization-os.md` -- loaded when touching org model, feature access, or entity work
+- `deployment.md` -- loaded when deploying resources
+- `error-handling.md` -- loaded when authoring handlers with error concerns
+- `execution.md` -- loaded when reasoning about the runtime model
+- `observability.md` -- loaded when using `context.logger` or inspecting executions
+- `operations.md` -- loaded when touching `operations/src/`
+- `platform.md` -- loaded when importing from `@elevasis/sdk`
+- `shared-types.md` -- loaded when touching `core/types/`
+- `task-tracking.md` -- loaded when managing project tasks
+- `active-change-index.md` -- flags areas under active architecture change; trust this over
+  stable scaffold docs for those areas
+
+To add a new rule: create `.claude/rules/<domain>.md` with `paths:` frontmatter matching the
+glob of files it applies to. The rules system discovers it automatically -- no registration step.
+
+**Memory directory.** List `.claude/memory/`. Common files:
+
+- `profile.md` -- track choice and tone implications (written by this tutorial)
+- `tutorial-progress.md` -- per-item progress markers for both tracks
+
+Memory files are readable by the agent at session start. The `profile.md` file is particularly
+important: it sets the project-wide tone for all sessions after the tutorial track is selected.
+
+**Scaffold registry (monorepo-side concept).** `.claude/scaffold-registry.yml` is the
+monorepo's source-of-truth for scaffold dependencies -- it maps source paths to generated or
+manual scaffolds that depend on them. It drives the PostToolUse reminder hook and `/work handoff`
+preflight in the monorepo. In an external project you are a consumer, not a contributor, of that
+registry. The relevant thing to know: when the SDK ships a template update, the registry controls
+which files are Tier 1 (always replaced on sync), Tier 2 (merge-aware), and Tier 3 (never
+touched). Item 19 covers this in detail.
+
+**Verification:** Ask: "How does the agent know to load `deployment.md` when you run a deploy?"
+(Answer: the `paths:` frontmatter in the rule file matches `operations/` file globs and deploy
+command patterns.)
+
+**Completion signal:** Mark `[ ] 18 Rules, memory, scaffold registry` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+### Item 19: Template lifecycle and /git-sync
+
+**Goal:** The user understands the three-tier file classification, runs `/git-sync`, and knows
+what manual reconciliation is required after a template update.
+
+**Estimated time:** 20 min
+
+**Files referenced:** `.claude/skills/git-sync/SKILL.md`, `.claude/sync-notes/` (directory)
+
+**Flow:**
+
+Tell the user:
+
+> "The template you scaffolded from is versioned. When a new SDK version ships, the template
+> updates. `/git-sync` pulls those changes and tells you what changed. You decide what to do
+> with them."
+
+**Three-tier file classification.** Walk through the tiers:
+
+- **Tier 1 (always replaced)** -- SDK-owned files that ship in a known correct state:
+  `.claude/skills/*/SKILL.md` (except project-authored skills), `.claude/hooks/`, `CLAUDE.md`
+  sections that are platform-managed. These are overwritten on every template sync. Do not put
+  custom logic in them; instead use Tier 3 files for project-specific config.
+- **Tier 2 (merge-aware)** -- Files where the template ships defaults but the project may have
+  customized: `core/config/organization-model.ts`, `.claude/rules/active-change-index.md`,
+  vibe classifier threshold. The sync does not blindly overwrite -- the agent surfaces the diff
+  and the user decides what to keep.
+- **Tier 3 (never touched)** -- Project-owned files the template never overwrites: project
+  source code in `operations/src/`, `ui/src/`, all `core/types/` files, `core/config/extensions/`,
+  custom rules added to `.claude/rules/`, everything in `.claude/memory/`.
+
+**Running `/git-sync`.** Read `.claude/skills/git-sync/SKILL.md` and walk the user through each
+step:
+
+1. Check for uncommitted changes (`git status --short`). Stop if dirty.
+2. Snapshot current sync-note filenames before pulling.
+3. `git pull --rebase` -- stop and report conflicts; do not auto-resolve.
+4. Detect dependency baseline changes; run `pnpm install` if `package.json` or
+   `pnpm-lock.yaml` changed.
+5. Run baseline verification: `pnpm -C ui check-types`, `pnpm -C ui build`,
+   `pnpm -C operations check`, `pnpm -C operations check-types`.
+6. Surface newly introduced sync notes from `.claude/sync-notes/`. Each note has required
+   actions and a verification section.
+7. Stop. `/git-sync` does not auto-reconcile. Manual follow-up is explicit.
+
+**Sync notes contract.** Files in `.claude/sync-notes/` named `YYYY-MM-DD-<slug>.md` are
+operative release guidance. They use fixed headings: `## Why this note exists`,
+`## Applies to`, `## Required actions`, `## Verification`, `## Not handled by /git-sync`.
+Never edit operative note filenames after they ship -- they are append-only.
+
+**Verification:** The user knows which of their own files are Tier 3 (never touched) and can
+explain why `/git-sync` stops before reconciliation rather than auto-applying diffs.
+
+**Completion signal:** Mark `[ ] 19 Template lifecycle and /git-sync` as `[x] YYYY-MM-DD` in
+`.claude/memory/tutorial-progress.md`.
+
+---
+
+## After All 19 Items Complete
+
+When all 19 items are marked `[x]` in `.claude/memory/tutorial-progress.md`, deliver the
+following closing script:
+
+> "You've completed the technical track. Here's where to go from here:
+>
+> - **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
+>   canonical recipe index for anything you want to build: adding a 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
+>   are wired. Use it before making changes in unfamiliar parts of the project.
+> - **Keep the org model current.** Run `/knowledge` any time your business reality changes --
+>   new offerings, new customer segments, new goals. The model is the agent's vocabulary for
+>   your project; an accurate model means better agent output.
+> - **Stay current with template updates.** When a new SDK version ships, run `/git-sync` to pull
+>   it and read the sync notes. They tell you exactly what changed and what manual follow-up is
+>   needed."