@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,277 +1,277 @@
----
-description: Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
----
-
-# 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.
+---
+description: Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
+---
+
+# 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.