---
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
- `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` -- `SALES_FEATURE_ID`, `PROSPECTING_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `SALES_PIPELINE_SURFACE_ID`, `PROSPECTING_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_COMMAND_VIEW_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.

## Capability Surface

When a user asks what skills or commands are available, do NOT answer from recollection.

- **Skill inventory:** Read `.claude/Overview.md` — it is the authoritative list of skills available in this project.
- **Live CLI capability:** Run `pnpm elevasis-sdk cli` — it outputs every command and domain currently registered in the SDK, grouped by domain.

## 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.
