@elevasis/sdk 1.22.1 → 1.24.0

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

@@ -1,83 +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.
+# 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 current skill body lives at `.claude/skills/om/SKILL.md` with operations under `.claude/skills/om/operations/` (renamed from the former knowledge skill path), including `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.
+- `/om` skill is present at `.claude/skills/om/SKILL.md` with the operation files under `.claude/skills/om/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-15-om-skill-rename-and-write-family.md

@@ -0,0 +1,52 @@
+# OM Skill Rename + Write Family Release Train
+
+## Why this note exists
+
+This release train renames the tenant `/knowledge` skill to `/om` and broadens it, ports `om:search` / `om:describe` to the `elevasis-sdk` CLI, and bumps the `@elevasis/core` and `@elevasis/sdk` dependency baselines. The template `.claude` skill surface changed shape (a directory was renamed and slash-command references were rewritten across CLAUDE.md, rules, and adjacent skills), and `@elevasis/core` / `@elevasis/sdk` published new exports and CLI commands. Ordinary git merge does not reconcile a managed `.claude` skill rename or pull republished package baselines, so template-derived projects need an operative note.
+
+This note covers the `om-skill` workstream (the `/knowledge` -> `/om` rename + SDK CLI port) and the package-baseline cascades from the same train (`@elevasis/core` minor from `om-skill` + `om-create-skill`; `@elevasis/sdk` minor from `om-skill`). It does NOT cover the unrelated Shared-UI-Migration changes under `external/_template/ui/**`, which are a separate workstream and not part of this train.
+
+## Applies to
+
+- `external/_template/.claude/skills/om/SKILL.md` (renamed from `external/_template/.claude/skills/knowledge/SKILL.md`; canonical 5-bucket decision tree with the tenant Codify/Toggle ceremony preserved)
+- `external/_template/.claude/skills/om/operations/*.md` (10 files moved from `knowledge/operations/`; `elevasis-sdk knowledge:*` references rewritten to `elevasis-sdk om:*`, `/knowledge` footers rewritten to `/om`)
+- `external/_template/.claude/skills/knowledge/` (DELETED — directory removed; tombstone, do not re-create on sync)
+- `external/_template/CLAUDE.md` (Slash Commands table — `/knowledge` -> `/om`)
+- `external/_template/.claude/rules/{organization-model,organization-os,vibe}.md` (slash-command references)
+- `external/_template/.claude/skills/{setup,project,tutorial}/*.md` (slash-command references)
+- `external/_template/core/package.json` (`@elevasis/core` baseline -> 0.25.0)
+- `external/_template/operations/package.json` (`@elevasis/core` -> 0.25.0 and `@elevasis/sdk` -> 1.23.0 baselines)
+
+Package baselines become concrete only after the `core` and `sdk` publish stages of `/sdk ship` complete; the `.claude` skill rename is template-authored and already present in `external/_template`.
+
+## Required actions
+
+1. Apply the managed `.claude` skill rename atomically: create `.claude/skills/om/` (SKILL.md + `operations/`) and delete the former knowledge skill directory in the same sync. Never leave both directories present — two skills advertising the same scope is the exact confusion the rename removes.
+2. Preserve any tenant-owned Codify/Toggle ceremony content in the project's `om/SKILL.md` Write-Power section; do not overwrite project-authored knowledge node content under `core/config/knowledge/**` (the content directory is separate from the slash-command name).
+3. Rewrite `/knowledge` -> `/om` and `elevasis-sdk knowledge:*` -> `elevasis-sdk om:*` references in managed surfaces only; `knowledge:*` CLI aliases remain valid, so do not hard-fail on legacy invocations in project-owned files.
+4. After the `/sdk ship` publish stages land, bump the `@elevasis/core` (0.25.0) and `@elevasis/sdk` (1.23.0) baselines in `core/package.json` and `operations/package.json`, then reinstall.
+5. The `/om` write sub-skill family (`verify` / `create` / `rename` / `deprecate`) is intentionally NOT ported to the tenant template in this train (deferred to a dedicated task). Do not scaffold those tenant operations from this sync.
+
+## Verification
+
+Run the template verification lane after applying this sync:
+
+```bash
+pnpm sync:verify --pre
+pnpm external:verify
+pnpm -C external/_template/operations check-types
+pnpm -C external/_template/operations test
+```
+
+Then confirm in each downstream project:
+
+- `.claude/skills/om/` exists with `SKILL.md` + `operations/`; the former knowledge skill directory is gone.
+- `elevasis-sdk om:search "<query>"` and `elevasis-sdk om:describe <id>` resolve against the tenant's organization model; legacy `elevasis-sdk knowledge:*` still aliases.
+- `@elevasis/core` resolves to >= 0.25.0 and `@elevasis/sdk` to >= 1.23.0.
+
+## Not handled by /git-sync
+
+- Publishing `@elevasis/core` (0.25.0) or `@elevasis/sdk` (1.23.0) — owned by `/sdk ship` publish stages.
+- Redeploying the SDK resources bundle (`elevasis-operations`) after the `@elevasis/sdk` publish.
+- Tenant-specific conflict resolution in dirty external project worktrees, including reconciling any project-authored edits to the former `knowledge/SKILL.md`.
+- The unrelated Shared-UI-Migration changes under `external/_template/ui/**` (separate workstream; not in this train's scope).

package/reference/claude-config/sync-notes/2026-05-17-sdk-boundary-consolidation.md

@@ -0,0 +1,33 @@
+# SDK Boundary Consolidation Release Train
+
+## Why this note exists
+
+This train publishes the SDK boundary consolidation work and updates the template to consume more of the published Elevasis SDK family instead of carrying local boilerplate. It also carries the Organization Model bridge retirement and typed-contract hardening that the ship train depends on.
+
+## Applies to
+
+- Template UI shells derived from `external/_template/ui`.
+- Template operations packages that depend on `@elevasis/sdk`.
+- Template core packages that depend on `@elevasis/core`.
+- Projects that still carry copied `.claude/rules/*.md` files instead of SDK reference pointers.
+
+## Required actions
+
+- Refresh package baselines after publishing `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk`.
+- Adopt `ElevasisAuthenticatedShell` from `@elevasis/ui/app` in template-derived root routes.
+- Replace local UI test/store/query-client helpers with `@elevasis/ui/test-utils`, `@elevasis/ui/test-utils/setup`, `createElevasisAppStore`, and `createElevasisQueryClient`.
+- Keep project-specific Claude guidance as compatibility stubs that point at `@elevasis/sdk/reference/rules/`.
+- Treat `System.ontology.catalogTypes` and `System.config` as canonical Organization Model authoring surfaces; do not reintroduce `System.content`.
+
+## Verification
+
+- `pnpm sdk:verify-release`
+- `pnpm scaffold:verify`
+- `pnpm verify:scaffold-reference`
+- `pnpm sync:verify`
+- `pnpm org-os:verify`
+- Template UI typecheck and tests from the source workstream.
+
+## Not handled by /git-sync
+
+`/git-sync` does not publish npm packages, deploy the operations resource bundle, or decide whether project-owned files should adopt a template baseline. Those steps remain owned by `/sdk ship` and the prepared external-sync manifest.

package/reference/rules/active-change-index.md

@@ -0,0 +1,83 @@
+---
+description: Bridge between stable scaffold docs and higher-volatility in-progress architecture work that may override assumptions for agents working in the template
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Active Change Index
+
+Use this rule to decide whether stable scaffold docs are enough, or whether you also need to load in-progress platform architecture docs from the monorepo.
+
+> **Note:** Paths prefixed with `apps/` or `packages/` are monorepo-internal and unavailable in standalone projects. For those areas, use the stable scaffold docs under `node_modules/@elevasis/sdk/reference/scaffold/` as the primary reference. The monorepo paths are retained for contributors working within the monorepo.
+
+## Current Watch Areas
+
+### Organization OS
+
+Use when the task touches:
+
+- organization model semantics
+- feature/provider runtime
+- feature manifests or shell composition
+- graph or command-view concepts
+- downstream propagation of scaffold contract changes
+
+Load:
+
+- `apps/docs/content/docs/technical/architecture/core/organization-model/index.mdx`
+- `apps/docs/content/docs/technical/architecture/core/organization-model/graph.mdx`
+- `apps/docs/content/docs/technical/architecture/ui/feature-shell.mdx`
+- `apps/docs/content/docs/technical/architecture/ui/composition-extensibility.mdx`
+
+Stable scaffold docs affected:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- `.claude/rules/ui.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+
+### Package Surface / Reference System
+
+Use when the task touches:
+
+- published `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk` surfaces
+- generated package maps
+- contract drift between source and scaffold docs
+
+Load:
+
+- `packages/core/src/organization-model/README.md`
+- `packages/ui/src/provider/README.md`
+- `packages/ui/src/features/README.md`
+- `packages/sdk/reference/_navigation.md`
+
+Stable scaffold docs affected:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+### Resource / Topology Mapping
+
+Use when the task touches:
+
+- resource registration
+- triggers, integrations, relationships, human checkpoints
+- topology-aware navigation or impact analysis
+
+Load:
+
+- `operations/src/README.md`
+- `operations/src/index.ts`
+
+Stable scaffold docs affected:
+
+- `.claude/rules/operations.md`
+
+## Working Rule
+
+When a task touches one of the watch areas above:
+
+1. Read the stable scaffold doc.
+2. Read the listed in-progress or package-local source-of-truth docs.
+3. Prefer source and in-progress architecture docs if they disagree with scaffold prose.
+4. Flag drift instead of silently trusting the scaffold doc.

package/reference/rules/agent-start-here.md

@@ -0,0 +1,280 @@
+---
+description: Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Agent Start Here
+
+Read this file first when entering a freshly scaffolded project.
+
+## Project Profile
+
+Before doing anything else, check for `.claude/memory/profile.md`. It is created by `/tutorial` on first invocation and persists across sessions.
+
+If present, read it. The file declares which onboarding **track** is active -- `vibe-coder` (non-technical user, agent does the work) or `technical` (developer, code-first) -- and ships a tone block describing how to communicate.
+
+Apply the tone block to ALL agent output for the rest of the session, not just inside `/tutorial`:
+
+- **vibe-coder track:** never use technical vocabulary in user-facing dialogue (workflow -> automation, deploy -> make it live, schema -> "the information your automation needs"). Tool calls are made silently -- do not narrate slash commands, file paths, or build steps. The full swap table lives in `profile.md`.
+- **technical track:** code-first, current command surface, real file paths. The user reads diffs and stacktraces; do not over-explain.
+
+If the file does not exist, the user has not run `/tutorial` yet. Proceed normally and note that running `/tutorial` would establish a project tone for future sessions.
+
+## First Action: Check Active Projects
+
+Before loading any docs for a new session, check whether the user's ask resumes or relates to an in-flight client project. Project context (milestones, tasks, resume notes) is DB-canonical -- agents and CLI read/write it through the `elevasis-sdk project:*` surface.
+
+1. **Portfolio snapshot.** Run this first to see what is active or blocked:
+
+   ```bash
+   pnpm elevasis-sdk project:list --status active --pretty
+   pnpm elevasis-sdk project:list --status blocked --pretty
+   ```
+
+2. **Resume-style asks.** If the user says "continue", "pick up", references a client name, or names a task/milestone, resolve it via:
+
+   ```bash
+   pnpm elevasis-sdk project:work <query>
+   ```
+
+   `project:work` fuzzy-matches a project or task by name/ID and returns the current resume context -- the canonical continuity payload (current state, next steps, files modified, key docs).
+
+3. **Fresh non-project asks.** Only if the portfolio snapshot and the request show no overlap with active projects, fall back to the docs-index flow below. Even then, if the work will take more than a single file edit, offer to create a project first (`/project create` or `project:create`) so continuity is captured from the start.
+
+### Resume Context Source of Truth
+
+`resume_context` lives in the `prj_tasks` table in the database, not in task-doc frontmatter. There is one source of truth:
+
+- **Humans write** via the inline resume-context editor on the Project Detail page in Command Center.
+- **Agents and the CLI write** via `pnpm elevasis-sdk project:task:save <task-id> --current-state ... --next-steps ... --files-modified ...`.
+- **Readers** consume it via `project:work <query>` or `project:task:resume <id>`.
+
+Do not write resume state into markdown frontmatter. Task-doc frontmatter is limited to `title`, `description`, and `status`.
+
+### Session-Start Dashboard
+
+The session-start dashboard directive lives in `CLAUDE.md`. If you see it there, follow it on the first response of a session. This file (`agent-start-here` rule) is the drill-down reference layer; `CLAUDE.md` owns session bootstrap.
+
+## Template Surfaces
+
+Once project continuity is resolved (or confirmed irrelevant), the template is not just an app starter. It is an agent operating environment with several distinct surfaces:
+
+- `ui/` -- React frontend app and shell composition
+- `operations/` -- Elevasis SDK resources deployed to the platform
+- `core/` -- runtime-agnostic shared contracts and organization model adaptation
+- `.claude/` -- local agent rules, skills, and hooks
+- `client-workspace/` -- optional separate knowledge workspace for richer team knowledge management
+- `node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
+
+## Discovery Order
+
+Use this order unless a more specific doc tells you otherwise:
+
+1. Complete the "First Action: Check Active Projects" flow above.
+2. Read `CLAUDE.md` for project rules, command surface, and navigation pointers.
+3. Read this rule and classify the task using the Task Classes below.
+4. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`) for organization context and naming.
+5. Read the relevant structural map:
+   - Glob `node_modules/@elevasis/sdk/reference/` for published package surfaces
+   - Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+6. For feature integration, resource authoring, or UI customization tasks, read `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
+7. Drill into the co-located local explainer for the abstraction boundary you are changing.
+8. Check the `.claude/rules/active-change-index.md` rule before trusting stable assumptions in areas that are under active architecture work.
+
+## SDK Reference Scaffold
+
+Universal scaffold documentation (recipes, patterns, architecture, reference) has been centralized in the SDK reference. After `pnpm install`, the entry point is:
+
+`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+
+This index links to all scaffold docs including pathway recipes, UI patterns, core architecture, and auto-generated contracts/feature registry.
+
+For task classes that involve feature integration, resource authoring, or UI customization, start with the scaffold index rather than local docs.
+
+## Task Classes
+
+Classify the request, then follow the load/inspect/verify sequence for that class.
+
+### 1. UI / Shell Work
+
+Examples: add a page, change sidebar behavior, adjust feature visibility, update dashboard labels.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
+- `.claude/rules/ui.md`
+- `ui/src/routes/README.md`
+- `core/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- when building or extending CRM pages, sidebars, hooks, workflows, or deal data surfaces
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- when building or extending lead-gen pages, sidebars, hooks, workflows, list/member state, or artifacts
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- when changing CRM deal action buttons or adding a workflow-backed deal action
+
+Then inspect:
+
+- `ui/src/routes/__root.tsx`
+- `ui/src/config/*`
+- relevant `ui/src/routes/*`
+- relevant `ui/src/features/*`
+- `core/config/organization-model.ts`
+
+Verify with:
+
+- route and manifest source
+- any relevant package README from `packages/ui`
+
+### 2. Workflow / Agent / Operations Work
+
+Examples: add a workflow, update an agent, change resource registration, understand deployable resources.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- workflow recipes, resource authoring)
+- `.claude/rules/operations.md`
+- `operations/src/README.md`
+
+Then inspect:
+
+- `operations/src/index.ts`
+- relevant `operations/src/<feature>/*`
+- `core/types/index.ts` -- workflow input/output Zod schemas
+- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when authoring a workflow that takes or returns these entities so the input/output schemas reference the canonical entity shapes rather than redeclaring them.
+- `operations/elevasis.config.ts`
+
+Verify with:
+
+- Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+- local SDK guidance in `.claude/skills/elevasis/SKILL.md`
+
+### 3. Organization Model / Feature Access Work
+
+Examples: rename a feature area, change quick access surfaces, map new business terms into the shell, adjust feature gating.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
+- `core/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- typed feature/surface constants from `@elevasis/core/organization-model` -- `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `CRM_PIPELINE_SURFACE_ID`, `LEAD_GEN_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID`. Use these typed constants instead of magic strings when overriding feature/surface IDs.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending CRM structure.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead gen is an Organization OS + UI + hooks + workflow-adapter surface; read this before extending lead-gen lists, members, artifacts, or state transitions.
+- `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- CRM action buttons are not `sales.actions` org-model config in v1; use the recipe's provider/custom-button path.
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+
+Then inspect:
+
+- `core/config/organization-model.ts`
+- `core/config/organization-model.ts` -- Organization Model overrides plus Systems and Resources descriptors. Start here for feature labels, surface mapping, and resource identity/governance changes.
+- `ui/src/routes/__root.tsx`
+- `ui/src/lib/hooks/useFeatureAccess.ts`
+- relevant nav config files
+
+Verify with:
+
+- published package docs for `@elevasis/core/organization-model`
+- current scaffold routes and manifests
+
+### 4. Debugging / Impact Analysis
+
+Examples: why is this automation disconnected, what does this workflow affect, what should I inspect before changing this resource.
+
+Load first:
+
+- `operations/src/README.md`
+- `.claude/rules/active-change-index.md`
+- Read `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+- For "why didn't this run?", "why is this still pending?", "what needs approval?", or schedule/queue debugging, inspect live operations state with `pnpm elevasis-sdk schedule:list --pretty`, `pnpm elevasis-sdk queue:list --status pending --pretty`, and `pnpm elevasis-sdk queue:status --pretty`.
+
+Then inspect:
+
+- `operations/src/index.ts`
+- resource definitions
+- related UI route and feature files
+- related core contracts
+- pending HITL items via `elevasis-sdk queue:get <id>` before selecting or expiring an action
+- recurring automation via `elevasis-sdk schedule:get <id>` before pausing, resuming, or cancelling it
+
+Verify with:
+
+- resource registration and relationship declarations
+- generated maps
+- package and source ownership boundaries
+- `queue:*` or `schedule:*` CLI output when runtime state is part of the question
+
+### 5. Platform Extension / Package Contract Work
+
+Examples: extend a published package contract, understand how a scaffold surface maps to `@elevasis/ui`, update a package-facing reference doc.
+
+Load first:
+
+- `.claude/rules/active-change-index.md`
+- Glob `node_modules/@elevasis/sdk/reference/` for the current SDK package surface
+- package README found via that glob
+
+Then inspect:
+
+- package source entrypoints
+- package reference manifests
+- scaffold files that consume that contract
+
+Verify with:
+
+- published package docs
+- source exports
+- scaffold consumption points
+
+## Boundary Resolution
+
+Once the request is classified, determine which boundary owns the change:
+
+- **Core boundary** -- semantics, aliases, labels, shared schemas
+- **UI shell boundary** -- provider composition, manifests, navigation, route ownership
+- **Operations boundary** -- deployable resource registration, workflow/agent contracts, topology
+- **Package boundary** -- public exports, shared platform behavior, reusable contracts
+
+If a task spans boundaries, start at the semantic boundary, then move to runtime composition, then to registration/deployment.
+
+## Main Boundaries
+
+### `core/config/organization-model.ts`
+
+The semantic adaptation point between platform contracts and scaffold-local terminology. Start here for feature labels, legacy aliases, quick-access surfaces, and shell-facing organization semantics.
+
+### `ui/src/routes/__root.tsx`
+
+The shell composition point. Start here for manifest mounting, provider wiring, app-local nav, and how the scaffold combines published feature surfaces with project-owned shell concerns.
+
+### `operations/src/index.ts`
+
+The deployment aggregation point. Start here for what resources are registered and deployed as part of the scaffold.
+
+## Source of Truth
+
+Trust these in order:
+
+1. Source code and published package docs
+2. Co-located boundary docs
+3. Generated structural maps
+4. Hand-authored template guidance
+5. In-progress architecture docs when `.claude/rules/active-change-index.md` says the area is actively evolving
+
+If a hand-authored doc conflicts with source or published package docs, trust source and flag the doc drift.
+
+## Common Traps
+
+- Do not assume feature directories are exhaustive without also checking `operations/src/index.ts` and `core/config/organization-model.ts` directly.
+- Do not assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`).
+- Do not trust stable docs blindly when `.claude/rules/active-change-index.md` flags related in-progress architecture work.
+- Do not write `resume_context` into task-doc frontmatter. DB is canonical; write via `project:task:save` or the inline editor in Command Center.
+
+## Operations-Only Projects
+
+Some projects derived from this template are operations-only. They have `operations/` (or a top-level `src/`) but NO `ui/`, NO `core/config/organization-model.ts`, and NO frontend. Finding none of these is not missing scaffolding -- it is by design.
+
+**What applies:** Only Task Classes 2 (Workflow / Agent / Operations Work) and 4 (Debugging / Impact Analysis) apply to operations-only projects. Task Classes 1 (UI / Shell Work), 3 (Organization Model / Feature Access Work), and 5 (Platform Extension / Package Contract Work) do not apply and can be skipped.
+
+**Primary entrypoint:** For operations-only projects, the project's own `CLAUDE.md` and its Navigation table are the canonical first-read. This rule provides task-routing context but its full surface map is irrelevant for that project type.
+
+**Signal:** The `CLAUDE.md` of an operations-only project includes `Project type: operations-only` in its `## Project` section. When you see this signal, skip all template surfaces that don't exist and go directly to the operations task class.