@elevasis/sdk 1.44.3 → 1.46.0

package/reference/sdk/deployment/execution-reference.mdx

@@ -290,227 +290,105 @@ The SDK CLI wraps all execution endpoints. Use these commands instead of calling
 
 ## UI Execution
 
-`@elevasis/ui` ships a set of components and hooks that let your custom React pages trigger workflow and agent executions without wiring up API calls manually. This section is for template users building interactive resource pages in `external/_template` who want to add Run buttons, input forms, and execution result displays.
+`@elevasis/ui` ships components and hooks that let your custom React pages trigger workflow and agent executions without wiring up API calls manually. This section is for template users building interactive resource pages who want to add Run buttons, input forms, and execution result displays.
 
-The API comes in three tiers: a convenience one-tag component that handles everything, a controlled form primitive for custom modal chrome, and low-level hooks for fully custom rendering. Most template pages need only the first tier.
+Two published pieces cover triggering: `useExecuteAsync` (the mutation) and `ExecuteWorkflowModal` (the modal chrome). You supply the input UI -- there is no built-in form renderer. `@elevasis/ui/features/operations` also publishes ready-made panels (`ExecutionPanel`, `WorkflowExecutionPanel`, `AgentExecutionPanel`) for when you want an execution history view rather than a trigger.
 
-### Quick Start -- `ResourceExecuteDialog`
+### `useExecuteAsync`
 
-`ResourceExecuteDialog` combines a modal shell, an input form, mutation state, and result display into a single component. Drop it next to a Button and you have a working Run dialog in about fifteen lines.
+`useExecuteAsync()` is a TanStack Query mutation that POSTs to the execution engine and resolves to `{ executionId, status, resourceId }`.
 
 ```tsx
-import { useState } from 'react'
-import { Button } from '@mantine/core'
-import { ResourceExecuteDialog } from '@elevasis/ui/features/operations'
-import { useNavigate } from '@tanstack/react-router'
-
-const resource = {
-  resourceId: 'qualify-lead-workflow',
-  resourceType: 'workflow' as const,
-  name: 'Qualify Lead',
-  formSchema: {
-    fields: [
-      { name: 'email', label: 'Lead email', type: 'text', required: true },
-      { name: 'company', label: 'Company', type: 'text', required: false },
-    ],
-  },
-}
-
-export function QualifyLeadPage() {
-  const [opened, setOpened] = useState(false)
-  const navigate = useNavigate()
+import { useExecuteAsync } from '@elevasis/ui/hooks'
 
-  return (
-    <>
-      <Button onClick={() => setOpened(true)}>Run</Button>
+const { mutateAsync, mutate, isPending, error, data, reset } = useExecuteAsync()
 
-      <ResourceExecuteDialog
-        opened={opened}
-        onClose={() => setOpened(false)}
-        resource={resource}
-        onViewExecution={(executionId) =>
-          navigate({ to: '/logs/$executionId', params: { executionId } })
-        }
-      />
-    </>
-  )
-}
+await mutateAsync({
+  resourceId: 'qualify-lead-workflow',
+  resourceType: 'workflow',
+  input: { email: 'lead@example.com' }
+})
 ```
 
-What the user sees when they click Run:
-
-- A modal opens titled "Run workflow" with the resource ID displayed.
-- The form renders one field per entry in `formSchema.fields`. Required fields show validation errors on submit.
-- On submit, a loading overlay appears while the POST is in flight.
-- On success, a teal confirmation card shows the execution ID. A "View execution" button calls `onViewExecution` with that ID.
-- On error, a red alert shows the error message with a "Try again" option.
+`ExecuteAsyncParams`:
 
-If `formSchema` is omitted or has no fields, the form skips to a single "Run" button with the message "This workflow takes no input."
+| Field          | Type           | Notes                                                    |
+| -------------- | -------------- | -------------------------------------------------------- |
+| `resourceId`   | `string`       | Deployed resource ID                                     |
+| `resourceType` | `ResourceType` | `'workflow'` or `'agent'`                                |
+| `input`        | `unknown`      | Passed through to the resource's input schema            |
+| `listId`       | `string`       | Optional; also attaches the execution to a lead-gen list |
 
-### The Three-Tier API
+On success it invalidates the executions list query keyed by organization plus `resourceId`, so any `useExecutions` query on the page refreshes automatically.
 
-| Tier            | Component / Hook                           | Use case                                                                                        |
-| --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| Convenience     | `ResourceExecuteDialog`                    | One-tag Run button + modal + form. Parent only manages `opened` state.                          |
-| Controlled form | `ResourceExecuteForm`                      | Custom modal chrome; parent owns the mutation and decides where to show results.                |
-| Low-level       | `ExecuteWorkflowModal` + `useExecuteAsync` | Fully custom rendering, non-standard modal behavior, or composing execution into a larger flow. |
+### `ExecuteWorkflowModal`
 
-Start with `ResourceExecuteDialog`. Move down the tiers only when you need something the convenience component cannot do.
-
-### Controlled Usage with `ResourceExecuteForm`
-
-Use `ResourceExecuteForm` when you want to own the modal or display the result somewhere outside the dialog -- for example, rendering the execution ID inline on the page after submission.
-
-`ResourceExecuteForm` accepts `onSubmit` and `isPending` from the parent. The parent calls `useExecuteAsync()` directly and passes `mutateAsync` as the submit handler.
+`ExecuteWorkflowModal` is a Mantine Modal pre-wired with a loading overlay, a success card (execution ID plus a "View execution" button), and an error alert. Pass your input UI as `children`.
 
 ```tsx
 import { useState } from 'react'
-import { Modal, Button, Text } from '@mantine/core'
-import { ResourceExecuteForm } from '@elevasis/ui/features/operations'
+import { Button, TextInput } from '@mantine/core'
+import { ExecuteWorkflowModal } from '@elevasis/ui/features/operations'
 import { useExecuteAsync } from '@elevasis/ui/hooks'
+import { useNavigate } from '@tanstack/react-router'
 
-const formSchema = {
-  fields: [
-    { name: 'topic', label: 'Topic', type: 'text', required: true },
-  ],
-}
-
-export function CustomRunPanel() {
+export function QualifyLeadPage() {
   const [opened, setOpened] = useState(false)
-  const mutation = useExecuteAsync()
-
-  const handleSubmit = async (input: Record<string, unknown>) => {
-    await mutation.mutateAsync({
-      resourceId: 'research-agent',
-      resourceType: 'agent',
-      input,
-    })
-  }
+  const [email, setEmail] = useState('')
+  const navigate = useNavigate()
+  const { mutateAsync, isPending, error, data, reset } = useExecuteAsync()
 
   return (
     <>
-      <Button onClick={() => setOpened(true)}>Run agent</Button>
-
-      {mutation.data && (
-        <Text size="sm">Started: {mutation.data.executionId}</Text>
-      )}
-
-      <Modal opened={opened} onClose={() => setOpened(false)} title="Run research agent">
-        <ResourceExecuteForm
-          formSchema={formSchema}
-          onSubmit={handleSubmit}
-          isPending={mutation.isPending}
-          disabled={mutation.isPending}
-          submitLabel="Start research"
-        />
-      </Modal>
+      <Button onClick={() => setOpened(true)}>Run</Button>
+
+      <ExecuteWorkflowModal
+        opened={opened}
+        onClose={() => setOpened(false)}
+        resource={{ resourceId: 'qualify-lead-workflow', resourceType: 'workflow', name: 'Qualify Lead' }}
+        isPending={isPending}
+        error={error}
+        result={data ?? null}
+        onReset={reset}
+        onViewExecution={(executionId) => navigate({ to: '/logs/$executionId', params: { executionId } })}
+      >
+        <TextInput label="Lead email" value={email} onChange={(e) => setEmail(e.currentTarget.value)} />
+        <Button
+          mt="md"
+          loading={isPending}
+          onClick={() => mutateAsync({ resourceId: 'qualify-lead-workflow', resourceType: 'workflow', input: { email } })}
+        >
+          Run
+        </Button>
+      </ExecuteWorkflowModal>
     </>
   )
 }
 ```
 
-`ResourceExecuteForm` props:
-
-| Prop          | Type                                 | Default  | Notes                                |
-| ------------- | ------------------------------------ | -------- | ------------------------------------ |
-| `formSchema`  | `SerializedExecutionFormSchema`      | required | Drives field rendering               |
-| `onSubmit`    | `(input) => void | Promise<void>` | required | Called with mapped field values      |
-| `isPending`   | `boolean`                            | `false`  | Shows loading state on submit button |
-| `disabled`    | `boolean`                            | `false`  | Disables all fields and button       |
-| `submitLabel` | `string`                             | `'Run'`  | Button label when not pending        |
-
-### Low-Level: Hooks and `ExecuteWorkflowModal`
-
-For complete rendering control, use `useExecuteAsync` and `ExecuteWorkflowModal` independently. `ExecuteWorkflowModal` is a Mantine Modal pre-wired with a loading overlay, a success card (execution ID + "View execution" button), and an error alert. You pass `children` for the input area.
-
-```tsx
-import { ExecuteWorkflowModal } from '@elevasis/ui/features/operations'
-import { useExecuteAsync } from '@elevasis/ui/hooks'
+`ExecuteWorkflowModalProps`:
 
-const { mutateAsync, isPending, error, data, reset } = useExecuteAsync()
-
-<ExecuteWorkflowModal
-  opened={opened}
-  onClose={() => setOpened(false)}
-  resource={{ resourceId: 'my-workflow', resourceType: 'workflow', name: 'My Workflow' }}
-  isPending={isPending}
-  error={error}
-  result={data ?? null}
-  onViewExecution={handleViewExecution}
-  onReset={reset}
->
-  {/* your custom form or content here */}
-</ExecuteWorkflowModal>
-```
+| Prop              | Type                            | Default  | Notes                                                |
+| ----------------- | ------------------------------- | -------- | ---------------------------------------------------- |
+| `opened`          | `boolean`                       | required | Modal visibility                                     |
+| `onClose`         | `() => void`                    | required | Ignored while `isPending`                            |
+| `resource`        | `ExecuteWorkflowModalResource`  | required | `{ resourceId, resourceType, name? }`                |
+| `isPending`       | `boolean`                       | `false`  | Shows the loading overlay and locks dismissal        |
+| `error`           | `Error | null`                 | --       | Renders the error alert                              |
+| `result`          | `ExecuteAsyncResult | null`    | --       | Renders the success card                             |
+| `onViewExecution` | `(executionId: string) => void` | --       | Adds the "View execution" button to the success card |
+| `onReset`         | `() => void`                    | --       | Backs the "Try again" action                         |
+| `children`        | `ReactNode`                     | --       | Your input UI                                        |
 
 The modal locks close interactions (click-outside, Escape, close button) while `isPending` is true, preventing accidental dismissal mid-execution.
 
-Source: `packages/ui/src/features/operations/executions/ExecuteWorkflowModal.tsx`, `packages/ui/src/hooks/executions/useExecuteAsync.ts`
-
-### Zod-Validated Execution with `useExecuteWorkflow`
-
-`useExecuteWorkflow` wraps `useExecuteAsync` with a Zod parse step before the POST. Use it when you are constructing input programmatically (not from a form) and want to catch schema mismatches before they reach the API.
-
-```tsx
-import { z } from 'zod'
-import { useExecuteWorkflow } from '@elevasis/ui/hooks'
-
-const inputSchema = z.object({
-  email: z.string().email(),
-  score: z.number().min(0).max(100),
-})
-
-function useScoredExecution() {
-  return useExecuteWorkflow({ schema: inputSchema })
-}
-
-// In a component:
-const { execute, isPending, data, error } = useScoredExecution()
-
-await execute({
-  resourceId: 'score-lead-workflow',
-  resourceType: 'workflow',
-  input: { email: 'lead@example.com', score: 72 },
-})
-```
-
-If `input` fails the Zod parse, `execute` throws synchronously with the message `"Invalid workflow input: ..."` before making any network request. The `mutation` object on the return value is the underlying `useExecuteAsync` mutation, giving you full TanStack Query state if needed.
-
-Prefer `useExecuteWorkflow` over raw `useExecuteAsync` when:
-
-- Input is assembled from multiple sources (not a single form submit).
-- You want TypeScript inference on the input shape via `z.infer`.
-- You want a clear validation error message rather than a 400 from the API.
-
-Source: `packages/ui/src/hooks/executions/useExecuteWorkflow.ts`
-
-### Input Forms
-
-`ResourceExecuteDialog` and `ResourceExecuteForm` auto-render form fields from `formSchema.fields`. Each field is a `SerializedFormField` with at minimum `name`, `label`, and `type`.
-
-Supported field types:
-
-- `text` -- single-line text input
-- `textarea` -- multi-line text input
-- `number` -- numeric input
-- `select` -- dropdown with `options` array
-- `checkbox` -- boolean toggle; defaults to `false`
-- `radio` -- radio group with `options` array
-- `richtext` -- rich text editor
-
-Required fields (`required: true`) are validated on submit. Custom field-to-input-key remapping is supported via `formSchema.fieldMappings` -- a `Record<string, string>` that renames field values before they are passed to `onSubmit`.
-
-If `formSchema` is undefined, an empty object, or has `fields: []`, the form skips rendering fields entirely and shows "This workflow takes no input." with a single Run button.
-
 ### Error and Result Handling
 
-Mutation state flows automatically into the modal chrome when using `ResourceExecuteDialog` or `ExecuteWorkflowModal`:
+Mutation state flows into the modal chrome automatically:
 
 - **Success** -- a teal alert card displays the execution ID from `result.executionId`. If `onViewExecution` is provided, a "View execution" button calls it with the ID. This is the recommended way to deep-link to the Execution Logs page.
-- **Error** -- a red alert displays `error.message`. A "Try again" button calls `onReset`, which clears the mutation state and re-shows the form.
-- **Pending** -- a blur overlay covers the form area while the POST is in flight. The modal cannot be dismissed during this state.
-
-`useExecuteAsync` also invalidates the executions list query on success (keyed by `organizationId` + `resourceId`), so any `useExecutions` query on the page refreshes automatically.
+- **Error** -- a red alert displays `error.message`. A "Try again" button calls `onReset`, which clears the mutation state and re-shows the children.
+- **Pending** -- a blur overlay covers the content area while the POST is in flight. The modal cannot be dismissed during this state.
 
 ---
 

package/reference/sdk/deployment/index.mdx

@@ -248,6 +248,8 @@ Host apps still own TanStack route registration, topbar behavior, branding, auth
 
 Manifest `systemId` values must match Organization Model System IDs. Sidebar placement is authored in the Organization Model navigation domain:
 
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
 ```ts
 systems: {
   dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },

package/reference/sdk/exports.mdx

@@ -8,7 +8,7 @@ description: "Auto-generated catalog of all published @elevasis/sdk subpath expo
 
 | Import | Title | Group | Description |
 | --- | --- | --- | --- |
-| `@elevasis/sdk` | SDK | Getting Started | Root SDK types, config, runtime errors, and registry surface. |
-| `@elevasis/sdk/worker` | Worker Runtime | Runtime | Worker runtime entrypoint, adapters, and platform execution surface. |
-| `@elevasis/sdk/test-utils` | Test Utils | Testing | Workflow runner, registry assertion, and typed adapter mocks for SDK consumers. |
-| `@elevasis/sdk/node` | Node Build Tooling | Tooling | Node-only build helpers: knowledge codegen and other fs/path/process utilities. Not browser-safe. |
+| `@elevasis/sdk` | SDK | Getting Started |  |
+| `@elevasis/sdk/worker` | Worker Runtime | Runtime |  |
+| `@elevasis/sdk/test-utils` | Test Utils | Testing |  |
+| `@elevasis/sdk/node` | Node Build Tooling | Tooling |  |

package/reference/sdk/framework/agent.mdx

@@ -1,156 +1,92 @@
 ---
 title: Agent System
-description: CLAUDE.md drives all agent behavior -- project instructions, slash commands, memory-based developer profile, and three-tier adaptive guidance
+description: The template's skill layer, the always-on ambient vibe classifier, the rules layer, and how project continuity is tracked through the elevasis-sdk project CLI, not files
 loadWhen: "Configuring agent behavior or capabilities"
 ---
 
-The agent system is the set of files that shape how Claude Code behaves in your SDK project. It consists of four parts: `CLAUDE.md` (the instruction file), slash commands (structured task entry points), the developer profile stored in `memory/profile/`, and the adaptive guidance rules that translate profile data into concrete agent behavior.
+The agent system is the set of files that shape how Claude Code behaves in your SDK project. It consists of three parts: the skill layer (`.claude/skills/`, slash-command entry points), the rules layer (path-scoped operating context, mostly bundled with the installed `@elevasis/sdk` package), and the ambient vibe layer (an always-on natural-language intent classifier). `CLAUDE.md` carries only project identity and preferences -- session bootstrap belongs to the rules layer, not to `CLAUDE.md`.
 
 Nothing here requires configuration. The agent reads these files at session start and adapts automatically.
 
-## CLAUDE.md
+## CLAUDE.md and Overview.md
 
-`CLAUDE.md` is the project instruction file for Claude Code. It is read at the start of every session and governs all agent behavior. In an Elevasis SDK project, it lives at the project root.
+`CLAUDE.md` is project-owned and never overwritten by sync. It routes the agent to `agent-start-here.md` for session bootstrap, points to `.claude/Overview.md` for the full skill/rule/command surface, and carries two project-specific sections: **Client Context** and **User Preferences**. These are populated by `/setup` during first-time bootstrap and are not re-written on subsequent runs.
 
-The file is instruction-driven by design. Non-technical developers should never need to edit it. When the agent learns a new rule worth preserving -- such as an error pattern that recurs three times -- it promotes that rule into `CLAUDE.md` automatically.
+`.claude/Overview.md` is template-owned and replaced on every `/git-sync`. It is the authoritative routing map: skill inventory, rule inventory, project structure, stack table, and command reference. When a user asks what skills or commands are available, the agent reads this file (or runs `elevasis-sdk cli` for live capability) rather than answering from memory.
 
-### Sections
+`OPERATIONS.md` and `CONNECTIONS.md` are also project-owned and never overwritten. `OPERATIONS.md` records tenant-specific operational quirks that override generic guidance -- for example, whether this tenant even has a working dev deploy target. `CONNECTIONS.md` records production wiring values (URLs, IDs, non-secret connection facts).
 
-The generated `CLAUDE.md` contains these sections:
+### Session Bootstrap
 
-- **Session Initialization** -- Checks the `<!-- initialized: false -->` auto-init flag; if false, runs `/meta init` automatically. Otherwise reads `memory/profile/skills.md` for adaptive behavior, reads `memory/index.md` for project context, checks if the template version is current, and suggests `/tutorial` for users with no Platform Navigation experience.
-- **Identity** -- Project orientation: what an Elevasis SDK project is, the developer's role, and how to adapt to non-technical users.
-- **Navigation** -- A table mapping concepts to file paths with load conditions (when to load each file). Includes SDK reference docs, credential model, error history, `docs/project-map.mdx`, and `docs/priorities.mdx`.
-- **Rules** -- Points to auto-loaded rule files in `.claude/rules/`. SDK patterns load automatically; project-specific patterns live in `workspace-patterns.md`. Includes error handling protocol.
-- **Interaction Guidance** -- Per-dimension behavior rules derived from `memory/profile/skills.md`. Covers vocabulary, code completeness, explanation depth, and growth logging.
-- **Commands** -- Table of the 4 slash commands (`/meta`, `/docs`, `/work`, `/tutorial`) with one-line purpose descriptions.
-- **Skills** -- Auto-trigger conditions for the `creds` skill.
-- **Maintaining Memory** -- Hierarchical structure, pruning rules, and what belongs in memory vs. `docs/` vs. `.claude/rules/`.
+`.claude/rules/agent-start-here.md` is a thin pointer to the canonical rule body bundled with the installed SDK: `operations/node_modules/@elevasis/sdk/reference/rules/agent-start-here.md`. It is always-loaded and owns session bootstrap. The invariants it establishes:
 
-### Session Initialization
+- **Project context is DB-canonical.** Milestones, tasks, and resume notes are read and written only through `elevasis-sdk project:*` -- never through files. A session opens with `project:list --status active --pretty`, then `--status blocked`, and resolves "continue" or "pick up" requests with `project:work <query>`.
+- **`OPERATIONS.md` outranks generic guidance.** Trust order: tenant `OPERATIONS.md`, then source and published package docs, then co-located boundary docs, then generated maps, then hand-authored template guidance.
+- **Never answer "what can you do" from memory.** Skill inventory is `.claude/Overview.md`; live CLI capability is `elevasis-sdk cli`.
+- **A missing `ui/` or `core/config/organization-model.ts` is not broken scaffolding.** Operations-only projects legitimately have neither.
 
-At the start of every session the agent runs these steps silently before responding:
+There is no `<!-- initialized: false -->` flag and no `/meta init` flow in the current template. First-time bootstrap is the `/setup` skill (see below), which hands off to `/om` for organization-model configuration.
 
-0. Check the `<!-- initialized: ... -->` flag at the top of `CLAUDE.md`. If `false`, run the `/meta init` flow automatically. If `true`, proceed with steps below.
-1. Read `.claude/memory/profile/skills.md` -- adapt all responses to the user's assessed skill levels (see Interaction Guidance below).
-2. Read `.claude/memory/index.md` if it exists -- drill into relevant topic files as needed, balancing context relevance against token usage.
-3. Check the installed `@elevasis/sdk` template version against `templateVersion` in `elevasis.config.ts`. If the SDK has a newer version, notify the user and suggest running `/meta fix`.
-4. If `.claude/memory/` does not exist, suggest running `/meta init` to set up the project.
-5. If the user's Platform Navigation level is none (from skills.md) and `.claude/memory/tutorial-progress.md` does not exist, suggest `/tutorial`.
-
-## Slash Commands
+## The Skill Layer
 
 Skills are Markdown instruction files in `.claude/skills/`. When you type `/skill-name` in a Claude Code session, the agent reads the corresponding `SKILL.md` and follows its instructions.
 
-The following skills ship with every Elevasis SDK project and are committed to version control so collaborators get the same experience:
-
-| Skill       | File                       | Purpose                                                  |
-| ----------- | -------------------------- | -------------------------------------------------------- |
-| `/work`     | `skills/work/SKILL.md`     | Task tracking -- list, create, save, resume, complete    |
-| `/elevasis` | `skills/elevasis/SKILL.md` | SDK operations -- check, deploy, exec                    |
-| `/deploy`   | `skills/deploy/skill.md`   | Full deploy pipeline (test, build, commit, push)         |
-| `/setup`    | `skills/setup/SKILL.md`    | First-time project setup (placeholder replacement, deps) |
-| `/status`   | `skills/status/SKILL.md`   | Quick project health check                               |
-| `/continue` | `skills/continue/SKILL.md` | Resume in-progress work from docs                        |
-| `/project`  | `skills/project/SKILL.md`  | Route project management to `elevasis-sdk project:*`     |
-| `/sync`     | `skills/sync/SKILL.md`     | Pull latest, wipe caches, fresh reinstall                |
-| `/explore`  | `skills/explore/SKILL.md`  | Codebase exploration anchored to docs                    |
-| `/save`     | `skills/save/SKILL.md`     | Auto-manage docs from conversation context               |
-| `/dsp`      | `skills/dsp/SKILL.md`      | Parallel agent dispatch for implementation tasks         |
+The template ships these skills, all committed to version control:
+
+| Skill             | Purpose                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `/client`         | Client portfolio management -- list, resolve, inspect, and maintain client records               |
+| `/deploy`         | Test, build, fix issues, then commit and push                                                    |
+| `/dsp`            | Dispatch subagents in parallel for implementation tasks                                          |
+| `/elevasis`       | SDK operations -- check, deploy, execute, inspect, and debug resources                           |
+| `/explore`        | Codebase exploration anchored to project documentation                                           |
+| `/git-sync`       | Pull latest changes, install when the dependency baseline moved, run baseline verification       |
+| `/om`             | Organization Model ceremony -- read, codify, toggle, layered flow                                |
+| `/project`        | Portfolio- and project-level work management via `elevasis-sdk project:*`                        |
+| `/run-ui`         | Start the Vite UI dev server on port 4300 in the background                                      |
+| `/save`           | Auto-manage project documentation and persist task resume context from conversation              |
+| `/setup`          | First-time project setup -- placeholder replacement, deps, build verification, hand off to `/om` |
+| `/status`         | Quick project health check                                                                       |
+| `/submit-request` | Submit a structured request (bug, feature, support) to the platform                              |
+| `/sync`           | Fresh reinstall and cache reset after local dependency or cache drift                            |
+| `/tutorial`       | Persona-aware onboarding -- vibe-coder or technical track                                        |
+
+There is no `/meta`, `/docs`, or `/work` skill. The template's own boundary guidance splits overlapping responsibilities this way: `/project` updates or inspects shared project records, `/save` captures implementation progress and conversation-derived docs, and `/elevasis` (or the monorepo-side `/adev`) handles resource execution and debugging.
 
 ### Key Skills
 
-**`/setup`** -- First-time project setup. Replaces template placeholders, installs dependencies, configures `.env`, verifies the project, and optionally runs a first deploy.
-
-**`/deploy`** -- Full deploy pipeline: type-check, validate resources, commit, deploy (auto-regenerates `docs/index.md` and `docs/resources.md`), verify platform, and optionally push.
-
-**`/elevasis`** -- SDK operations entry point: `check` validates resource definitions, `deploy` bundles and uploads, `exec` runs a resource with input.
-
-**`/work`** -- File-based task lifecycle. Creates, resumes, saves, and completes task docs in `docs/in-progress/`. It tracks in-progress work state, not project records.
-
-**`/status`** -- Quick project health check: shows SDK version, deployed resources, last deploy date, and environment status.
-
-**`/save`** -- Auto-manages docs from conversation context: writes or updates docs based on what was discussed in the session.
-
-**`/explore`** -- Codebase exploration anchored to `docs/`. Reads the doc map first, then drills into source as needed.
-
-**`/continue`** -- Resumes in-progress work by reading `docs/in-progress/` and picking up where the last session left off.
-
-**`/project`** -- Project-management routing for milestones, tasks, notes, and status. It should call the canonical `elevasis-sdk project:*` CLI surface rather than inventing a parallel workflow.
-
-That routing is interface-first, not a separate semantic model. `/project` should treat the SDK CLI as the operational entrypoint for the Organization OS delivery/projects contract: `deliveryManifest` in the shared UI, `PROJECTS_SYSTEM_ID` (`platform.projects`) in the organization model, and `organizationModel.delivery` for project/milestone/task status semantics.
-
-When these command families overlap conceptually, use this boundary:
-
-- `/project` -- update or inspect project data in the shared Projects system
-- `/work` -- capture implementation progress and resume context in docs
-- `/adev` -- build, debug, test, or execute resources
-
-**`/dsp`** -- Dispatches subagents in parallel for implementation tasks that can run concurrently.
-
-**`/sync`** -- Pulls latest changes, wipes all `node_modules` and caches, and runs a fresh reinstall.
-
-## Developer Profile
-
-The developer profile is stored in `.claude/memory/profile/` as a set of markdown files. It is gitignored -- personal to each developer, not shared with collaborators. Profile data lives in the memory system alongside error patterns, deployment state, and decisions.
-
-### Onboarding Flow
-
-Profile data is created during `/meta init`. The command runs a 6-question assessment and writes the responses to `memory/profile/`:
-
-- **Identity & Goals (3 questions):** What the business does, what to automate, which tools are already in use.
-- **Competency (2 questions):** Command Center familiarity (maps to `platformNavigation`), automation tool familiarity (maps to `automation`). Two additional dimensions (`apiIntegration`, `domainExpertise`) are inferred from these answers.
-- **Communication (1 question):** Step-by-step explanations vs. concise answers.
-
-### Profile Structure
-
-```
-.claude/memory/profile/
-├── index.md          # Profile summary with links to sub-files
-├── identity.md       # Organization, industry, goals, integrations
-├── skills.md         # Skill dimensions (platformNavigation, apiIntegration, automation, domainExpertise)
-└── preferences.md    # Verbosity, guidance style, interaction patterns
-```
+**`/setup`** -- First-time project bootstrap. Detects whether the project still has template placeholders (`__PROJECT_NAME__`, `__PROJECT_SLUG__`, and similar), collects project and client identity conversationally, replaces placeholders (everything under `.claude/` is explicitly excluded from replacement), fills the `CLAUDE.md` **Client Context** and **User Preferences** sections, writes `identity.clientBrief` in the organization model, installs dependencies, verifies the build, then hands off to `/om` for full organization-model configuration. All of its writes are idempotent -- re-running `/setup` on an already-bootstrapped project skips replacement and offers to re-verify only.
 
-`identity.md` records the organization name, industry, size, project goals, and known tool integrations. `skills.md` stores four skill dimensions as structured values (`platformNavigation`, `apiIntegration`, `automation`, `domainExpertise`) along with a Growth Log table. See [Interaction Guidance](interaction-guidance.mdx) for the full set of per-dimension adaptation rules. `preferences.md` stores verbosity (`detailed / concise`) and proactive guidance preference.
+**`/om`** -- The only path to edits in `core/config/organization-model.ts`. Runs a snapshot-propose-confirm-write-validate-rollback ceremony rather than a direct file edit, because a change that passes TypeScript can still fail the model's Zod cross-reference validation (`resolveOrganizationModel()`).
 
-### Auto-Update Triggers
+**`/deploy`** -- Test, build, commit, push pipeline.
 
-The agent updates `memory/profile/` files when it observes:
+**`/elevasis`** -- SDK operations entry point: `check` validates resource definitions, `deploy` bundles and uploads, `exec` runs a resource with input, plus `describe`, `logs`, and `creds`.
 
-- The user successfully completes an advanced task (level upgrade candidate in `skills.md`)
-- The user mentions new tools or integrations not in `identity.md`
-- The user explicitly asks to change preferences
+**`/project`** -- Primary work-tracking entry point: portfolio orientation, intent detection (resume vs. new), and project/milestone/task/note lifecycle, all routed through the `elevasis-sdk project:*` CLI rather than files.
 
-The agent does not prompt for confirmation on minor updates. Major changes (level upgrades) are surfaced to the user before writing.
+**`/git-sync`** -- Pulls the latest template changes, checks the installed `@elevasis/sdk` version against the declared range, reinstalls if the dependency baseline changed, and runs baseline verification (`ui check-types`, `ui build`, `operations check`, `operations check-types`). It stops after verifying -- it never auto-reconciles template drift or overwrites project-owned files. Release guidance is not delivered here; it ships inside the `@elevasis/sdk` reference bundle, which is always current for your installed version.
 
-## Rules System
+On a green verification it also **bumps your app version**. The literal lives in `ui/src/config/app-version.ts` (exported as `APP_VERSION`, consumed by `ui/src/config/app-config.ts` and rendered in the topbar), and the agent picks the segment by judging the whole run: **minor** for new capability or a changed `@elevasis/*` dependency baseline, **patch** for everything else. **Major is never automatic** -- if a run genuinely looks major the report says so and leaves the version alone.
 
-Ten rule files are scaffolded in `.claude/rules/`. Rule files are auto-injected by Claude Code when their path patterns match the current file being edited -- no manual loading needed.
+The gate is **outgoing commits**, checked with `git rev-list --count @{u}..HEAD` before the bump commit is written. Nothing deploys off a run with nothing to push, so a pull-only run reports `Version: unchanged (nothing to push)` while a run with local commits and an empty pull does bump. The bump lands as its own `chore(ui): bump app version to x.y.z` commit and is not pushed. It is skipped when there is no upstream, when the pull or verification failed, when the project has no `ui/src/config/app-version.ts`, and inside the template itself.
 
-Rules injected for operations source files (`operations/src/`):
+`app-version.ts` is a separate file from `app-config.ts` deliberately. It is registered `never-touch` / `verify-only`, so the sync engine protects your value; folding it back into `app-config.ts` -- a critical manual-merge surface -- would flag every project as behind the template on every sync for a difference that is working as intended.
 
-- **`platform.md`** -- SDK adapter patterns, typed adapters, platform tool usage.
-- **`error-handling.md`** -- Error types (`ExecutionError`, `PlatformToolError`), retry behavior.
-- **`execution.md`** -- Worker thread model, timeouts, concurrency, org isolation.
-- **`observability.md`** -- Logging with `context.logger`, step-level auto-logging, debugging.
-- **`deployment.md`** -- Deploy commands, dev vs prod, version bumping, common errors.
+**`/tutorial`** -- Persona-aware onboarding; see [Tutorial System](tutorial-system.mdx) for the full lesson breakdown.
 
-Rules injected for docs files (`docs/`):
+## The Ambient Vibe Layer
 
-- **`docs.md`** -- Documentation structure, frontmatter conventions, auto-generated files.
-- **`task-tracking.md`** -- Task doc conventions, injected for in-progress files.
+External projects run an always-on natural-language intent classifier -- there is no `/vibe` command and no activation phrase. Every message is silently classified into one of seven intents (Capture, Query, Describe, Transition, Navigate, Codify, Toggle) before the agent responds. Codify and Toggle detect intent and delegate immediately to `/om`; the classifier never runs the organization-model ceremony itself. The full classifier definition and fixture tables ship with the SDK at `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md`. Vibe is explicitly off inside the monorepo, which uses the task-class routing in `agent-start-here.md` instead.
 
-Additional contextual rules:
+## The Rules Layer
 
-- **`frontend.md`** -- React/Mantine patterns, injected for UI source files.
-- **`shared-types.md`** -- Cross-runtime type conventions, injected for foundations files.
-- **`organization-os.md`** -- Organization model and feature shell conventions.
+`.claude/rules/` in the git-tracked template holds short pointer files with `paths:` frontmatter that Claude Code auto-loads for matching files. The authoritative rule bodies ship with the installed `@elevasis/sdk` package at `operations/node_modules/@elevasis/sdk/reference/rules/` and update whenever the SDK dependency is bumped. Rules include `agent-start-here.md` (always-loaded), `vibe.md` (always-loaded), `organization-os.md`, `deployment.md`, `error-handling.md`, `execution.md`, `frontend.md`, `observability.md`, `operations.md`, `organization-model.md`, `platform.md`, `shared-types.md`, `task-tracking.md`, `ui.md`, and `active-change-index.md` (which flags areas under active platform change).
 
-## Interaction Guidance
+## Template Version Tracking
 
-The `CLAUDE.md` Interaction Guidance section translates skill dimensions from `memory/profile/skills.md` into concrete behavior rules -- adapting vocabulary, code completeness, explanation depth, and growth logging per dimension. For the full set of per-dimension adaptation rules, see [Interaction Guidance](interaction-guidance.mdx).
+The scaffold's version marker is `templateVersion` in the project-root `.elevasis` file (a flat YAML-like marker file, not `elevasis.config.ts`). `elevasis.config.ts` (`operations/elevasis.config.ts`) only accepts `defaultStatus` and `dev.port` -- it has no version field. To pull a template update, run `/git-sync`, not `/meta fix` (which does not exist in this template).
 
 ---
 
-**Last Updated:** 2026-04-17
+**Last Updated:** 2026-08-06