@elevasis/sdk 1.15.1 → 1.17.0

package/reference/claude-config/sync-notes/2026-05-04-elevasis-workspace.md

@@ -0,0 +1,71 @@
+# Elevasis Workspace Ship-Train
+
+## Why this note exists
+
+The Elevasis runtime (`external/elevasis/`) was promoted into the pnpm workspace as `packages/elevasis-{core,operations}/`. That migration exposed two latent SDK pipeline failures -- a rollup `.dts` resolver bug affecting transitive type-only peers (`openai`, `@supabase/*`, `@workos-inc/node`, etc.) and a deploy-validator crash on ESM-only `exports` maps -- both of which are now fixed in `@elevasis/sdk`. The same migration forced a formal subpath boundary contract for `@elevasis/sdk`: the default barrel is now browser-safe only, with `@elevasis/sdk/worker`, `@elevasis/sdk/node`, and `@elevasis/sdk/test-utils` as explicit runtime-gated subpaths, enforced by `no-restricted-imports` lint rules and a build-time bundle-leak test suite. Separately, workflow input/output schemas are now codified as the canonical SSOT through a three-layer pattern (operations contract owns schemas; CC imports from the workflow contract; `apps/api` stays envelope-only). The result is minor bumps to `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk`, a `_template` dependency-baseline update, and new boundary rules that external SDK consumers must follow.
+
+## Applies to
+
+All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
+
+- `nirvana-marketing`
+- `ZentaraHQ`
+- Any future external SDK consumer derived from the `_template` baseline
+
+`@elevasis/sdk` is now boundary-enforced. Any external project that previously imported Node-only modules from the default `@elevasis/sdk` barrel -- including `knowledge-codegen`, anything touching `node:fs`, or `worker_threads` -- must migrate those imports to `@elevasis/sdk/node`. Workflow handler code that uses `platform.call`, `acqDb`, or adapter factories should already be on `@elevasis/sdk/worker`; verify this is the case.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the refreshed package baselines (`core/package.json`, `ui/package.json`, `operations/package.json`) reach the project.
+
+2. After the baseline lands, update package versions in the project:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
+```
+
+Version baselines are written into the `_template` package files by the release train. Match the versions from `_template` after sync or run `--latest` to pull the published minors.
+
+3. Run `pnpm install` from the project root after the dep bump to ensure the lockfile is updated.
+
+4. **Audit `@elevasis/sdk` import subpaths.** In `operations/src/`, search for any import from `@elevasis/sdk` that touches `knowledge-codegen`, `node:fs`, `worker_threads`, or any other Node-only module. These must move to `@elevasis/sdk/node`. Workflow handler files that use `platform`, `acqDb`, or adapter factories belong on `@elevasis/sdk/worker` -- verify the subpath is explicit.
+
+   ```ts
+   // Before (incorrect for Node-only tooling)
+   import { knowledgeCodegen } from '@elevasis/sdk'
+
+   // After
+   import { knowledgeCodegen } from '@elevasis/sdk/node'
+   ```
+
+5. **Audit for `@repo/elevasis-core` or `@repo/elevasis-operations` imports.** These package names are workspace-internal to the platform monorepo and are not published. External consumers must use the published packages (`@elevasis/sdk`, `@elevasis/core`, `@elevasis/ui`) exclusively. If a tenant project forked or copied an import path using the `@repo/elevasis-*` namespace, replace it with the appropriate published subpath.
+
+6. **Audit workflow input/output schema usage in `ui/src/`.** Per the schema SSOT pattern, CC code should import schemas from the workflow's `contract.inputSchema` or `contract.outputSchema`, not from hand-duplicated local type declarations. If the project has hand-written copies of workflow input or output schemas in `ui/src/`, flag them for migration to direct imports from the workflow contract. If a workflow's main file imports Node-only code, use the browser-safe sibling-schema pattern (a separate `<workflow-name>-schema.ts` file, importing `node:*`-free schema definitions only) so CC can consume the schema without triggering Vite's `"fs" has been externalized` error.
+
+7. **Rebuild and type-check:**
+
+```bash
+pnpm -C ui build
+pnpm -C ui exec tsc --noEmit
+pnpm -C operations exec tsc --noEmit
+```
+
+## Verification
+
+After applying all actions above:
+
+- `pnpm install` completes cleanly with no unresolved peer warnings.
+- `pnpm check-types` passes across all project packages (`ui`, `operations`, `core`).
+- `pnpm test` passes where test suites exist.
+- `pnpm -C ui dev` starts the CC dev server. Navigating to any workflow detail route (e.g., a lead-gen list action form) produces no `Module "fs" has been externalized for browser compatibility` console errors. If those errors appeared before this upgrade, they should be gone.
+- A workflow execution round-trips end-to-end in dev: trigger a workflow from the CC UI, confirm the execution record appears in the monitoring view.
+
+## Not handled by /git-sync
+
+`/git-sync` propagates template-authored files (package baselines, scaffold doc copies, sync-managed surfaces) but does NOT:
+
+- Run `pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest` -- dep bumps are manual after the baseline lands.
+- Infer or apply subpath migrations for `@elevasis/sdk`. If any workflow in `operations/src/` was importing Node-only modules from the default `@elevasis/sdk` barrel, `/git-sync` will not rewrite those import paths to `@elevasis/sdk/node`. That migration is manual per project.
+- Replace hand-duplicated workflow schemas in `ui/src/` with imports from workflow contracts. Tenant-side schema copies need manual migration to use `contract.inputSchema` / `contract.outputSchema`.
+- Remove or update any `no-restricted-imports` lint rule overrides that the project may have added to disable `@elevasis/sdk` subpath enforcement. If the project disabled the rule, re-enable it after sync and resolve any violations it surfaces.
+- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the SDK, clear this directory manually and restart the dev server before verifying that browser-safety errors are gone -- stale cache can make fixed boundary violations appear to persist.

package/reference/claude-config/sync-notes/2026-05-04-knowledge-bundle.md

@@ -0,0 +1,83 @@
+# Knowledge Bundle Ship-Train
+
+## Why this note exists
+
+The Knowledge Map (Browser, CLI, skill, icons, external parity) is being shipped as a coordinated bundle. The Organization Model now treats `knowledge` as a first-class graph domain with `kind`-discriminated nodes (`playbook` / `strategy` / `reference`) connected to features and capabilities through `governs` edges. A new `/knowledge` skill absorbs the prior `/configure` skill as a unified intent-inferring surface (read + describe + codify + toggle); `/configure` is tombstoned via `sync-delete-manifest.json`. A new `knowledge:*` CLI subcommand suite ships on both `elevasis` and `elevasis-sdk` over a shared `@repo/core/knowledge/queries` data layer. The Knowledge Browser is wired into `@elevasis/ui` with reusable primitives (`KnowledgeBrowser`, `KnowledgeTree`, `DescribeNodeView`, `KindChip`, `NodeHeader`, `NodeDescribeShell`, etc.) and a build-time MDX codegen pipeline at `@elevasis/sdk/node`. A unified semantic icon-token catalog lives at `@elevasis/core/organization-model` and is shared across core, SDK, UI, Command Center, and external projects. External-parity work makes the bundle zero-config for tenant projects: a dual-mode Vite plugin walks up to `.elevasis`, runs the two-codegen pipeline in-process, and writes artifacts the published Browser already imports -- no flags, no paths, no recipe steps.
+
+## Applies to
+
+All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
+
+- `nirvana-marketing`
+- `ZentaraHQ`
+- Any future external SDK consumer derived from the `_template` baseline
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the refreshed knowledge wiring (template OM defaults, starter `welcome.mdx`, vite plugin pre-wiring, `/knowledge` skill, `/configure` tombstone, scaffold recipe) reaches the project.
+
+2. **`/configure` is gone.** The skill was absorbed into `/knowledge`. `/git-sync` removes `external/_template/.claude/skills/configure/` (and its 10 operations files) via `sync-delete-manifest.json` (wave: `knowledge-skill`). Update any tenant-side automation, prompts, or docs that still reference `/configure` -- replace with `/knowledge`. The skill is intent-inferring: classify by natural language (read / describe / codify / toggle), not by verb namespace.
+
+3. **`/knowledge` ceremony is unchanged.** The codify ceremony (snapshot -> propose -> confirm -> write -> validate -> rollback) and the two-level model (Level A config-only edits vs. Level B new Zod extension files) are preserved bit-for-bit. The skill body lives at `.claude/skills/knowledge/SKILL.md` (~245 lines) with 10 operations files: `codify-level-a.md`, `codify-level-b.md`, plus 8 domain references (`identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, `labels`).
+
+4. **Vite plugin is pre-wired.** `external/_template/ui/vite.config.ts` imports and spreads `elevasisVite()` from `@elevasis/ui/vite`. After `/git-sync`, the plugin auto-discovers the project via `.elevasis` walk-up, runs both knowledge codegens in-process, and writes:
+   - `core/config/knowledge/_generated/nodes.ts`
+   - `core/config/knowledge/_generated/knowledge-bodies.tsx`
+   - `core/config/knowledge/_generated/knowledge-search-index.json`
+
+   Same behavior in `vite dev` and `vite build`. No flags, no manual codegen step required for the bundle to work.
+
+5. **Starter knowledge node lands.** `core/config/knowledge/nodes/welcome.mdx` ships in the template so a fresh clone has a non-empty Browser on first `pnpm -C ui dev`. Replace with tenant-authored MDX nodes as the project codifies real organizational knowledge. Tenant nodes go under `core/config/knowledge/nodes/**/*.mdx` with frontmatter declaring `id`, `kind`, `title`, optional `icon` (semantic token), and an MDX body. Default fallback icons by `kind` apply when `icon` is omitted.
+
+6. **Knowledge baseline propagates to the OM.** `core/config/organization-model.ts` now includes baseline knowledge defaults imported from `@elevasis/core/organization-model`. The merge-aware Tier 2 sync preserves tenant overrides while picking up the baseline. After `/git-sync`, verify `resolveOrganizationModel()` still parses (Zod) and `pnpm -C ui exec tsc --noEmit` passes.
+
+7. **`knowledge:*` CLI subcommands are available.** From inside the project (any subdirectory):
+
+   ```bash
+   pnpm exec elevasis-sdk knowledge:ls /by-feature/sales/crm
+   pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
+   pnpm exec elevasis-sdk knowledge:cat <node-id>
+   pnpm exec elevasis-sdk knowledge:graph <node-id>
+   ```
+
+   These walk up to `.elevasis`, load the project's OM (with tenant nodes), and print results. Output flags: default text, `--json` envelope, `--ids-only` for piping. The Knowledge Browser sidebar copy buttons emit matching skill-resolvable commands (`/knowledge read <node-id>`, `/knowledge read-folder feature:<id>`, `/knowledge read-folder kind:<kind>`).
+
+8. **Semantic icon tokens replace ad-hoc strings.** When authoring or editing nodes (OM or MDX frontmatter), use semantic tokens from the catalog: `nav.*`, `knowledge.*`, `feature.*`, `resource.*`, `integration.*`, plus `custom.*` namespace for tenant extensions. `IconNameSchema` validates them. The UI renders via Tabler mappings in `@elevasis/ui/icons`; library names (`IconBook`, etc.) stay out of the OM/MDX surface.
+
+9. **Rebuild and type-check:**
+
+   ```bash
+   pnpm install
+   pnpm -C ui build
+   pnpm -C ui exec tsc --noEmit
+   pnpm -C operations exec tsc --noEmit
+   ```
+
+   The first `vite dev` or `vite build` after sync triggers the in-process codegen automatically. To regenerate codegen artifacts manually (one-shot, not normally required):
+
+   ```bash
+   pnpm exec elevasis-sdk knowledge:generate
+   ```
+
+## Verification
+
+After applying all actions above:
+
+- `/configure` skill directory is absent: `external/<project>/.claude/skills/configure/` does not exist after sync.
+- `/knowledge` skill is present at `.claude/skills/knowledge/SKILL.md` with the 10 operations files under `.claude/skills/knowledge/operations/`.
+- `core/config/knowledge/nodes/welcome.mdx` exists; `core/config/knowledge/_generated/` has been populated by the vite plugin (3 files).
+- `pnpm -C ui dev` boots; navigating to `/knowledge` renders the Browser with the welcome node visible in the tree.
+- The 5 mount axes resolve: `/knowledge`, `/knowledge/by-feature/$path`, `/knowledge/by-kind/$kind`, `/knowledge/by-owner/$id`, `/knowledge/graph/$nodeId/governs|governed-by`.
+- `pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook` returns text output without error.
+- `pnpm install` completes cleanly with no unresolved peer warnings.
+- `pnpm -C ui exec tsc --noEmit` passes; `pnpm -C operations exec tsc --noEmit` passes.
+
+## Not handled by /git-sync
+
+`/git-sync` propagates template-authored files (package baselines, `welcome.mdx` starter node, generated `_generated/` files, `/knowledge` skill, `/configure` tombstones, vite.config.ts wiring, scaffold recipe doc) but does NOT:
+
+- Author tenant-specific knowledge MDX nodes. The starter `welcome.mdx` is illustrative; real organizational playbooks, strategies, and reference docs need to be hand-authored under `core/config/knowledge/nodes/**/*.mdx`. Use `/knowledge` for ceremony when codifying.
+- Regenerate `_generated/` artifacts on its own. The vite plugin runs the codegens automatically on next `vite dev` / `vite build`. To regenerate manually before booting, run `pnpm exec elevasis-sdk knowledge:generate`.
+- Migrate references in tenant code from `/configure` to `/knowledge`. Search the project for `/configure` mentions in `.claude/`, `docs/`, `README.md`, prompts, and CI scripts; rewrite to `/knowledge`. The tombstone deletes the skill files but does not edit downstream references.
+- Replace tenant-authored icon strings with semantic tokens. Existing nodes that carried library-specific icon names (`IconBook`, etc.) will continue to render via fallback, but the canonical surface is semantic tokens. Migrate at-touched nodes to `knowledge.*` / `feature.*` / `nav.*` / `custom.*` over time.
+- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the bundle, clear this directory manually and restart the dev server before verifying the Browser renders -- stale cache can mask a successful generation.

package/reference/claude-config/sync-notes/2026-05-04-template-skills-run-ui-and-tutorial.md

@@ -0,0 +1,59 @@
+# Template Skills: `/run-ui` and `/tutorial`
+
+## Why this note exists
+
+This sync introduces two new template skills and a project-wide tone-block in the always-loaded `agent-start-here` rule:
+
+- **`/run-ui`** -- new skill at `.claude/skills/run-ui/SKILL.md`. One-command path to start the project's Vite dev server on port `4300` in the background. Probes the port, branches on free/own-vite/other-holder, asks before killing a non-vite holder, polls Vite stdout for `Local:` / `ready in`, then surfaces the URL and the background shell ID. Resolves the `strictPort: true` failure mode introduced by the `2026-05-02` WorkOS hardcode train -- before this skill, port collisions were a hard manual debug.
+- **`/tutorial`** -- new skill at `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md`. Persona-aware onboarding that forks at first invocation into a `vibe-coder` track (zero technical vocabulary, agent does all the work) or a `technical` track (full SDK depth, code-first). The choice persists to `.claude/memory/profile.md` and ships a tone block applied project-wide for the rest of every session.
+- **`agent-start-here.md` Project Profile section** -- the always-loaded entrypoint rule now reads `profile.md` at session start and applies the per-track tone block to ALL agent output, not just inside `/tutorial`. This is the load-bearing change that lets `/tutorial` actually flip agent behavior across the whole project.
+
+The project-owned `CLAUDE.md` Slash Commands table has a new `/tutorial` row in the template, but `CLAUDE.md` is verify-only on `/git-sync` -- derived projects own that file and need to add the row themselves if they want it documented.
+
+This sync moves three pieces into derived projects:
+
+- `.claude/skills/run-ui/SKILL.md` -- new file, replace-all surface, lands automatically
+- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` -- new files, replace-all surface, lands automatically
+- `.claude/rules/agent-start-here.md` -- replace-all surface, the Project Profile section lands automatically
+
+## Applies to
+
+All template-derived projects. There are no surface preconditions -- the new skills do not depend on a particular org-model shape, feature set, or workspace topology. Operations-only projects with no `ui/` will receive `/run-ui` but it will not be useful in that context (no Vite dev server to launch); leaving it installed is harmless.
+
+`agent-start-here.md` is replace-all: any project that hand-edited that file will lose those local edits on this sync. Run `git diff .claude/rules/agent-start-here.md` after `/git-sync` and re-apply local customizations if needed -- the template version assumes no project-local changes.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the new skills and the `agent-start-here.md` Project Profile section reach the project.
+
+2. Optionally run `/tutorial` to set the project's persona track. The first run asks one gate question (`vibe-coder` vs `technical`) and writes the choice to `.claude/memory/profile.md`. Subsequent runs go straight to the menu. If you skip this, the agent behaves normally and prompts you to consider running `/tutorial` only when relevant.
+
+3. If you want the `/tutorial` row visible in the project's own Slash Commands table, manually add a row to `CLAUDE.md` (project-owned, not overwritten by `/git-sync`):
+
+   ```
+   | `/tutorial` | Guided onboarding -- picks one of two tracks (vibe-coder for non-technical users, technical for developers) and walks through the menu interactively |
+   ```
+
+4. If the project hand-edited `.claude/rules/agent-start-here.md` for project-local agent behavior, diff against the new template version and re-apply those edits on top of the new Project Profile section. The replace-all behavior of this file is unchanged from prior trains.
+
+5. Optionally run `/run-ui` at the start of UI work. It is an explicit ask to start the dev server, not an ambient hook -- there is no behavior change unless you invoke it.
+
+## Verification
+
+After upgrading:
+
+- `.claude/skills/run-ui/SKILL.md` exists and is non-empty.
+- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` all exist and are non-empty.
+- `.claude/rules/agent-start-here.md` includes a `## Project Profile` section near the top that references `.claude/memory/profile.md` and the `vibe-coder` / `technical` tracks.
+- Running `/run-ui` from a UI-bearing project either starts Vite on `4300` and reports the URL, or detects a port holder and asks before proceeding.
+- Running `/tutorial` for the first time asks the gate question and writes `.claude/memory/profile.md`. Running it a second time skips the question and shows the menu.
+- For a project that ran `/tutorial`: the agent's tone in subsequent (non-`/tutorial`) responses reflects the chosen track per the tone block in `profile.md`. Vibe-coder track: no technical vocabulary, no slash-command surfacing. Technical track: real paths, code-first, no over-explanation.
+
+## Not handled by /git-sync
+
+`/git-sync` does not:
+
+- create or update `.claude/memory/profile.md`. The file is created on first `/tutorial` invocation. If a project never runs `/tutorial`, the agent operates as if no profile exists -- normal default behavior.
+- write the new `/tutorial` row into the project's own `CLAUDE.md` Slash Commands table. `CLAUDE.md` is project-owned (verify-only); the row is a manual edit if the project wants it documented.
+- preserve project-local edits to `.claude/rules/agent-start-here.md`. That file is replace-all. Re-apply local customizations after the sync if any exist.
+- run smoke tests for either skill. The `/tutorial` task doc explicitly defers smoke testing to a fresh-scaffold pass; `/run-ui` is exercised on first user invocation, not via sync verification.

package/reference/deployment/index.mdx

@@ -32,16 +32,16 @@ There is no local dev server and no separate staging environment. Deployed resou
 
 **Single-package project** (e.g. `external/acme/`): both anchors resolve to the same directory. Invoke from anywhere inside the project tree.
 
-**Multi-package workspace** (e.g. `external/elevasis/` with `operations/` as a sub-package):
+**Multi-package workspace** (e.g. `external/_template/` with `operations/` as a sub-package):
 
 ```bash
 # Invoke from operations/ or any subdir inside it
-pnpm -C external/elevasis/operations exec elevasis-sdk deploy
+pnpm -C external/_template/operations exec elevasis-sdk deploy
 
 # Both CWDs work identically:
-#   .elevasis root  -> external/elevasis/            (auth / .env)
-#   package root    -> external/elevasis/operations/  (bundle, dist/)
-#   bundle output   -> external/elevasis/operations/dist/bundle.js
+#   .elevasis root  -> external/_template/            (auth / .env)
+#   package root    -> external/_template/operations/  (bundle, dist/)
+#   bundle output   -> external/_template/operations/dist/bundle.js
 ```
 
 Each package in a workspace produces its own `dist/bundle.js` when deployed. Run `elevasis-sdk deploy` from within each package separately.

package/reference/examples/organization-model.ts

@@ -222,3 +222,43 @@ export const rolesAndGoalsExample = defineOrganizationModel({
     ]
   }
 })
+
+// ---------------------------------------------------------------------------
+// Knowledge nodes
+// ---------------------------------------------------------------------------
+export const knowledgeExample = defineOrganizationModel({
+  knowledge: {
+    nodes: [
+      {
+        id: 'knowledge.example-outreach-playbook',
+        kind: 'playbook',
+        title: 'Example Outreach Playbook',
+        summary: 'Step-by-step runbook for launching a cold outreach campaign.',
+        body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
+        links: [{ nodeId: 'feature:sales.crm' }, { nodeId: 'feature:sales.lead-gen' }],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      },
+      {
+        id: 'knowledge.example-icp-strategy',
+        kind: 'strategy',
+        title: 'Example ICP Strategy',
+        summary: 'Describes the ideal customer profile and qualification thresholds.',
+        body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
+        links: [{ nodeId: 'feature:sales' }],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      },
+      {
+        id: 'knowledge.example-org-model-reference',
+        kind: 'reference',
+        title: 'Example Organization Model Reference',
+        summary: 'Glossary of OM domains and how they relate to features and resources.',
+        body: '## Domains\n\nThe organization model splits configuration into typed domains: identity, customers, offerings, roles, goals, techStack, features, statuses, operations, knowledge.',
+        links: [],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      }
+    ]
+  }
+})

package/reference/framework/index.mdx

@@ -87,7 +87,7 @@ The agent adapts its communication based on four independent skill dimensions st
 
 Each dimension has its own adaptation rules in the [Interaction Guidance](interaction-guidance.mdx) reference. A user who has deep Zapier experience (automation: low-code) but has never called an API directly (apiIntegration: none) will get credential walkthroughs every time while having automation concepts treated as familiar ground.
 
-`/meta init` runs a 6-question assessment: 3 identity questions, 2 competency questions, and 1 communication preference. Platform Navigation and Automation are assessed directly. API & Integration is inferred from the automation level and tools the user already uses. Domain Expertise is inferred from how specifically the user describes their goals.
+`/tutorial` runs the assessment via a single gate question on first invocation: are you here to build automations by describing what you want, or are you a developer who edits code directly. The choice persists to `.claude/memory/profile.md` and shapes the agent's tone, vocabulary, and tool-call visibility for the entire project, not just inside `/tutorial`. Within the chosen track, lessons adapt further -- senior devs in the technical track can mark Section A items complete to skip them.
 
 See [Agent System](agent.mdx) for the full assessment question set, dimensional interaction rules, and communication principles.
 

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