@elevasis/sdk 1.14.1 → 1.15.0

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

@@ -1,260 +1,260 @@
----
-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.
-
-## 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
+---
+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.
+
+## 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.
+- `.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
-   - Glob `operations/resources/**` for source, 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`
+5. Read the relevant structural map:
+   - Glob `node_modules/@elevasis/sdk/reference/` for published package surfaces
+   - Glob `operations/resources/**` for source, 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, artifacts, or touchpoint 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/*`
+
+- `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>/*`
+
+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:
-
-- Glob `operations/resources/**` for local source files, 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)
+- `operations/elevasis.config.ts`
+
+Verify with:
+
+- Glob `operations/resources/**` for local source files, 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, touchpoints, or state transitions.
+- `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:
-
+
+Then inspect:
+
 - `core/config/organization-model.ts`
 - `core/config/organization-model.examples.ts` -- 5 reference patterns: branding override, CRM pipeline stage customization, lead-gen lifecycle customization, resource mapping registration, custom feature declaration. Not imported anywhere -- pure reference. Start here for the override pattern when extending the org model.
-- `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`
-- Glob `operations/resources/**` for source, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
-
-Then inspect:
-
-- `operations/src/index.ts`
-- resource definitions
-- related UI route and feature files
+- `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`
+- Glob `operations/resources/**` for source, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+
+Then inspect:
+
+- `operations/src/index.ts`
+- resource definitions
+- related UI route and feature files
 - related core contracts
-
-Verify with:
-
-- resource registration and relationship declarations
-- generated maps
-- package and source ownership boundaries
-
-### 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:
-
+
+Verify with:
+
+- resource registration and relationship declarations
+- generated maps
+- package and source ownership boundaries
+
+### 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
-
+- **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 `operations/resources/**` is exhaustive without also checking `operations/src/index.ts` directly.
+
+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 `operations/resources/**` is exhaustive without also checking `operations/src/index.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
-
+- 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.
+
+**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.