@elevasis/sdk 1.44.2 → 1.45.0

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

@@ -11,93 +11,52 @@ 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.
+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: it declares the active onboarding **track** and ships a tone block.
 
-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 that tone block to ALL agent output for the rest of the session, not just inside `/tutorial`:
 
-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.
+- **vibe-coder track** (non-technical user, agent does the work) -- never use technical vocabulary in user-facing dialogue (workflow -> automation, deploy -> make it live, schema -> "the information your automation needs"). Make tool calls silently: do not narrate slash commands, file paths, or build steps. The full swap table lives in `profile.md`.
+- **technical track** (developer, 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`.
+**This rule owns session bootstrap.** Run this flow on the first response of a session, before loading any docs. Project context (milestones, tasks, resume notes) is DB-canonical -- agents and CLI read and write it through the `elevasis-sdk project:*` surface only.
 
-### Session-Start Dashboard
+1. **Portfolio snapshot.** Run first: `pnpm elevasis-sdk project:list --status active --pretty`, then the same with `--status blocked`.
+2. **Resume-style asks** ("continue", "pick up", a client name, a task or milestone name): resolve with `pnpm elevasis-sdk project:work <query>`. It fuzzy-matches a project or task by name/ID and returns the current resume context -- current state, next steps, files modified, key docs.
+3. **Fresh non-project asks.** Only when the snapshot and the request show no overlap, fall back to the Discovery Order below. Even then, if the work is more than a single file edit, offer to create a project first (`/project create` or `project:create`) so continuity is captured from the start.
 
-**This rule owns session bootstrap.** Run the "First Action" flow above on the first response of a session. `CLAUDE.md` only points here — it is project-owned and never overwritten by sync, so it deliberately carries no procedure that might need correcting later.
-
-Older projects may still have a copy of the dashboard directive inline in their `CLAUDE.md`. If the two ever disagree, this file wins: it ships with the SDK version the project actually runs.
+`CLAUDE.md` only points here -- it is project-owned and never overwritten by sync, so it deliberately carries no procedure that might need correcting later. Older projects may still have an inline copy of the session-start directive in their `CLAUDE.md`; if the two disagree, this file wins, because it ships with the SDK version the project actually runs.
 
 ## 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:
+Once project continuity is resolved (or confirmed irrelevant): the template is an agent operating environment, not just an app starter.
 
 - `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
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- SDK reference scaffold, available after `pnpm install`: pathway recipes, UI patterns, gating model, core architecture, contracts, feature registry, glossary. For feature integration, resource authoring, or UI customization, start here rather than at local docs.
 
 ## 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 this project's identity, client context, and user preferences. It is deliberately short — for structure, stack, commands, and the slash-command surface, read `.claude/Overview.md`, which sync keeps current.
-3. Read `OPERATIONS.md` at the project root, if present -- it is tenant-owned, never overwritten by sync, and records operational quirks true for this tenant only (non-obvious deploy targets, environment gotchas). Read it early: it can override generic guidance elsewhere in this file for this specific tenant.
-4. Read this rule and classify the task using the Task Classes below.
-5. Read `identity.clientBrief` from the OrganizationModel (`core/config/organization-model.ts`) for organization context and naming.
-6. Read the relevant structural map:
-   - Glob `operations/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
-7. For feature integration, resource authoring, or UI customization tasks, read `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
-8. Drill into the co-located local explainer for the abstraction boundary you are changing.
-9. 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:
-
-`operations/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.
+2. `CLAUDE.md` -- this project's identity, client context, and user preferences. It is deliberately short; for structure, stack, commands, and the slash-command surface read `.claude/Overview.md`, which sync keeps current.
+3. `OPERATIONS.md` at the project root, if present -- tenant-owned, never overwritten by sync, and records operational quirks true for this tenant only (non-obvious deploy targets, environment gotchas). Read it early: it can override generic guidance elsewhere in this file.
+4. This rule -- classify the task using the Task Classes below.
+5. `identity.clientBrief` in `core/config/organization-model.ts` -- organization context and naming.
+6. Structural state: `operations/src/index.ts` for deployment assembly, `core/config/organization-model.ts` for resource descriptors, `pnpm elevasis-sdk project:list --pretty` for live DB state.
+7. The scaffold index (see Template Surfaces) for the canonical recipe covering the task.
+8. The co-located local explainer for the abstraction boundary you are changing.
+9. `.claude/rules/active-change-index.md` before trusting stable assumptions in an area under active architecture work.
 
 ## Task Classes
 
-Classify the request, then follow the load/inspect/verify sequence for that class.
+Classify the request, then follow the load/inspect/verify sequence for that class. Every class starts at the scaffold index; the extra loads below are what that class adds.
 
 ### 1. UI / Shell Work
 
@@ -105,27 +64,16 @@ Examples: add a page, change sidebar behavior, adjust feature visibility, update
 
 Load first:
 
-- `operations/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`
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- when building or extending CRM pages, sidebars, hooks, workflows, or deal data surfaces
-- `operations/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
-- `operations/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/README.md`, `core/config/README.md`
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- recipe 6 when building a "run this resource" surface
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM pages, sidebars, hooks, workflows, deal data surfaces
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen pages, sidebars, hooks, workflows, list/member state, artifacts
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- deal action buttons and workflow-backed deal actions
 
-- `ui/src/routes/__root.tsx`
-- `ui/src/config/*`
-- relevant `ui/src/routes/*`
-- relevant `ui/src/features/*`
-- `core/config/organization-model.ts`
+Then inspect: `ui/src/routes/__root.tsx`, `ui/src/config/*`, the relevant `ui/src/routes/*` and `ui/src/features/*`, `core/config/organization-model.ts`.
 
-Verify with:
-
-- route and manifest source
-- any relevant package README from `packages/ui`
+Verify with: route and manifest source, plus the mirrored `@elevasis/ui` source in the bundle (see References) when a prop or hook signature is in question.
 
 ### 2. Workflow / Agent / Operations Work
 
@@ -133,22 +81,17 @@ Examples: add a workflow, update an agent, change resource registration, underst
 
 Load first:
 
-- `operations/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>/*`
+- `operations/src/index.ts` and the 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.
+- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when a workflow takes or returns these entities so its schemas reference the canonical shapes instead of 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`
+Verify with: the structural state sources in Discovery Order step 6, and `.claude/skills/elevasis/SKILL.md`.
 
 ### 3. Organization Model / Feature Access Work
 
@@ -156,27 +99,19 @@ Examples: rename a feature area, change quick access surfaces, map new business
 
 Load first:
 
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
 - `core/config/README.md`
 - `operations/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.
-- `operations/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.
-- `operations/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.
-- `operations/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.
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+- Typed feature and surface ID constants exported from `@elevasis/core/organization-model` (`SALES_FEATURE_ID`, `PROSPECTING_LISTS_SURFACE_ID`, and the rest). Always use these constants instead of magic strings when overriding feature/surface IDs; the full list is enumerated in `.claude/rules/organization-os.md`.
+- The `extend-crm.md`, `extend-lead-gen.md`, and `customize-crm-actions.md` recipes listed under Class 1 -- CRM and lead gen are Organization OS + UI + hooks + workflow-adapter surfaces, and CRM action buttons are not `sales.actions` org-model config in v1 (use the recipe's provider/custom-button path).
 
 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`
-- feature-access gating call sites built from `createFeatureAccessHook` (`@elevasis/ui/hooks`) -- the template no longer ships a local `useFeatureAccess.ts`; the hook factory is the published equivalent
-- relevant nav config files
+- `ui/src/routes/__root.tsx` and the relevant nav config files
+- Access-gating call sites: `useAccess(accessKey)` from `@elevasis/ui/hooks` and `<AccessGuard accessKey={...}>` from `@elevasis/ui/auth`. The template ships no local `useFeatureAccess.ts` and there is no hook factory -- these two published entry points are the whole gating surface.
 
-Verify with:
-
-- published package docs for `@elevasis/core/organization-model`
-- current scaffold routes and manifests
+Verify with: published docs for `@elevasis/core/organization-model`, plus current scaffold routes and manifests.
 
 ### 4. Debugging / Impact Analysis
 
@@ -184,79 +119,38 @@ Examples: why is this automation disconnected, what does this workflow affect, w
 
 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
+- `operations/src/README.md`, `.claude/rules/active-change-index.md`
+- The structural state sources in Discovery Order step 6
+- For "why didn't this run?", "why is this still pending?", "what needs approval?", or schedule/queue questions: `pnpm elevasis-sdk schedule:list --pretty`, `queue:list --status pending --pretty`, `queue:status --pretty`
 
-Verify with:
+Then inspect: `operations/src/index.ts`, resource definitions, related UI route/feature files, related core contracts. Always check a pending HITL item with `elevasis-sdk queue:get <id>` before selecting or expiring it, and a recurring automation with `elevasis-sdk schedule:get <id>` before pausing, resuming, or cancelling it.
 
-- 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
+Verify with: resource registration and relationship declarations, generated maps, package/source ownership boundaries, and `queue:*` or `schedule:*` 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:
+Load first: `.claude/rules/active-change-index.md`, then glob `operations/node_modules/@elevasis/sdk/reference/` for the current SDK package surface and read the package reference found there.
 
-- `.claude/rules/active-change-index.md`
-- Glob `operations/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, and the scaffold files that consume the contract.
 
-Then inspect:
-
-- package source entrypoints
-- package reference manifests
-- scaffold files that consume that contract
-
-Verify with:
-
-- published package docs
-- source exports
-- scaffold consumption points
+Verify with: published package docs, source exports, and 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
+Once the request is classified, determine which boundary owns the change. If a task spans boundaries, start at the semantic boundary, then runtime composition, then registration/deployment.
 
-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.
+- **Core boundary** -- semantics, aliases, labels, shared schemas. Entry: `core/config/organization-model.ts`, the adaptation point between platform contracts and scaffold-local terminology (feature labels, legacy aliases, quick-access surfaces, shell-facing organization semantics).
+- **UI shell boundary** -- provider composition, manifests, navigation, route ownership. Entry: `ui/src/routes/__root.tsx`, where the scaffold combines published feature surfaces with project-owned shell concerns.
+- **Operations boundary** -- deployable resource registration, workflow/agent contracts, topology. Entry: `operations/src/index.ts`, the deployment aggregation point.
+- **Package boundary** -- public exports, shared platform behavior, reusable contracts. Entry: the SDK reference bundle.
 
 ## Source of Truth
 
 Trust these in order:
 
-1. Tenant-owned `OPERATIONS.md` at the project root, when present, for facts specific to this tenant's own environment and operational quirks -- it is never overwritten by sync and can override any generic guidance below for this tenant specifically
+1. Tenant-owned `OPERATIONS.md`, when present, for this tenant's own environment and operational quirks -- never overwritten by sync, and it overrides any generic guidance below
 2. Source code and published package docs
 3. Co-located boundary docs
 4. Generated structural maps
@@ -268,23 +162,37 @@ If a hand-authored doc conflicts with source or published package docs, trust so
 ## 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 assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from `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.
+- Never write `resume_context` into task-doc frontmatter -- the DB is canonical. Write it via `pnpm elevasis-sdk project:task:save` or the inline editor on the Project Detail page in Command Center; full rule in `operations/node_modules/@elevasis/sdk/reference/rules/task-tracking.md`.
 
 ## 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.
+- **Skill inventory:** read `.claude/Overview.md` -- the authoritative list of skills in this project.
+- **Live CLI capability:** run `pnpm elevasis-sdk cli` -- 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.
+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.
+
+**Signal:** the project's `CLAUDE.md` includes `Project type: operations-only` in its `## Project` section.
+
+**What applies:** only Task Classes 2 and 4. Classes 1, 3, and 5 do not apply and can be skipped. The project's own `CLAUDE.md` and its Navigation table are the canonical first-read; this rule still supplies task routing, but its surface map does not.
+
+## Related Rules
 
-**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.
+- `operations/node_modules/@elevasis/sdk/reference/rules/task-tracking.md` -- task doc format, status values, auto-save behavior, and the canonical `resume_context` rule
+- `operations/node_modules/@elevasis/sdk/reference/rules/ui.md` -- shell composition, gating call sites, and route ownership detail for Task Class 1
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- resource authoring and deployment detail for Task Class 2
+- `operations/node_modules/@elevasis/sdk/reference/rules/organization-os.md` -- Organization Model field/constant surface and published subpaths for Task Class 3
+- `operations/node_modules/@elevasis/sdk/reference/rules/active-change-index.md` -- which areas are under active architecture work
 
-**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.
+## References
 
-**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.
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold entry point; links every recipe, UI pattern, contract, and generated registry
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `AccessGuard` and `useAccess` usage, structured action keys, and how System lifecycle maps to an access answer
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- `NavItem`, `SystemModule`, and the other published TypeScript shapes
+- `operations/node_modules/@elevasis/sdk/reference/packages/ui/src/` -- mirrored `@elevasis/ui` source when an exact hook or prop signature is needed
+- `.claude/Overview.md` -- project-local skill and command inventory, kept current by sync

package/reference/rules/deployment.md

@@ -9,19 +9,26 @@ paths:
 
 # Deployment
 
+This rule is the single owner of the check-before-deploy command table. `platform.md` and `operations.md` point here instead of restating it -- do not copy the table back into them.
+
 ## Always Check Before Deploy
 
-```bash
-pnpm -C operations run check        # Validate resource definitions
-pnpm -C operations run check-types  # TypeScript type-check
-pnpm -C operations run deploy       # Deploy (target depends on environment -- see below)
-```
+| Command                              | Purpose                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------- |
+| `pnpm -C operations run check`       | Validate resource definitions                                                |
+| `pnpm -C operations run check-types` | TypeScript type-check                                                        |
+| `pnpm -C operations run deploy`      | Deploy -- **targets production by default**; see the next section before use |
+| `pnpm -C operations run deploy:prod` | Deploy to production explicitly (`elevasis-sdk deploy --prod`)               |
+
+**Always use the explicit `run` form.** `pnpm -C operations deploy` (no `run`) is parsed as pnpm's builtin `deploy` command, which prunes and copies a package into a target directory rather than running the project's `deploy` script. That is a real trap, not a style preference -- `run` is the form that cannot misfire. These four names are the actual scripts declared in `operations/package.json`.
 
 `check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.
 
 ## Dev vs Prod (SAFETY-CRITICAL: plain `deploy` targets PRODUCTION by default)
 
-Plain `pnpm -C operations run deploy` runs `elevasis-sdk deploy` with no flags. There is no dev-safe default baked into the command name. The API URL resolution (`packages/sdk/src/cli/config.ts`, `resolveApiUrl`) checks, in order:
+**Plain `pnpm -C operations run deploy` targets production (`https://api.elevasis.io`) unless `NODE_ENV=development` is exported in your shell. There is no dev-safe default.**
+
+It runs `elevasis-sdk deploy` with no flags, and no dev-safe default is baked into the command name. The API URL resolution checks, in order:
 
 1. `--api-url <url>` CLI flag -- explicit override, always wins
 2. `--prod` CLI flag -- forces `https://api.elevasis.io`
@@ -36,17 +43,17 @@ Plain `pnpm -C operations run deploy` runs `elevasis-sdk deploy` with no flags.
 
 Do not assume plain `deploy` is a dev-safe command. Most tenant shells do not export `NODE_ENV=development`, so plain `deploy` hits production. Before running it, confirm the target: check `echo $NODE_ENV` / `$env:NODE_ENV`, or pass `--api-url` explicitly if you need to target a specific environment. If this tenant project has a checked-in `OPERATIONS.md` at the project root, check it first -- it records tenant-specific deploy-target facts that override this generic guidance.
 
-The API key follows a related but distinct rule (`resolveApiKey`): with `--prod`, or whenever `NODE_ENV !== 'development'`, only `ELEVASIS_PLATFORM_KEY` is used. Only when `NODE_ENV === 'development'` (and `--prod` is not passed) does the CLI prefer `ELEVASIS_PLATFORM_KEY_DEV`, falling back to `ELEVASIS_PLATFORM_KEY` if the dev key is unset.
+The API key follows a related but distinct rule: with `--prod`, or whenever `NODE_ENV !== 'development'`, only `ELEVASIS_PLATFORM_KEY` is used. Only when `NODE_ENV === 'development'` (and `--prod` is not passed) does the CLI prefer `ELEVASIS_PLATFORM_KEY_DEV`, falling back to `ELEVASIS_PLATFORM_KEY` if the dev key is unset.
 
 Always verify the actual deploy target before treating a deploy as safe-to-repeat, verify with `elevasis-sdk exec`, then deploy to prod deliberately (`deploy:prod` or `--prod`).
 
 ## Version Bumping
 
-Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `src/index.ts`. Bump on contract changes (input/output schema modifications).
+Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `operations/src/index.ts`. Bump on contract changes (input/output schema modifications).
 
 ## What Gets Deployed
 
-1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
+1. **Bundle:** esbuild compiles `operations/src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
 2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.
 
 ## Environment
@@ -65,9 +72,25 @@ Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment vers
 | `Missing OM Resource descriptor`         | Add the descriptor to `core/config/organization-model.ts` under the id-keyed `resources` map        |
 | `Step references non-existent next step` | Fix the `next:` field in the step chain                                                             |
 | `Schema serialization failed`            | Simplify the Zod schema (warning, still deploys)                                                    |
-| `No default export found`                | `src/index.ts` must `export default` a `DeploymentSpec`                                             |
+| `No default export found`                | `operations/src/index.ts` must `export default` a `DeploymentSpec`                                  |
 | `Documentation file exceeds 100KB`       | Split the `.md` file                                                                                |
 
 ## Deployment Replaces Previous
 
 Only one deployment can be `active` at a time. Deploying again automatically marks the previous deployment as `stopped`. Resources become executable immediately after deploy succeeds.
+
+## Related Rules
+
+Sibling rule bodies live at `operations/node_modules/@elevasis/sdk/reference/rules/`.
+
+- **platform.md** -- SDK authoring invariants every deployable resource must satisfy before `check` will pass
+- **operations.md** -- the `operations/` surface: adding a workflow, the resource registry, rule upkeep
+- **organization-model.md** -- OM Resource descriptors that deploy validation requires
+- **execution.md** -- running and verifying a resource after it deploys
+
+## References
+
+- `operations/package.json` -- the actual `check`, `check-types`, `deploy`, and `deploy:prod` scripts this table wraps
+- `operations/node_modules/@elevasis/sdk/reference/sdk/deployment/index.mdx` -- full deploy pipeline: validation stages, bundling, API URL and key resolution, deployment lifecycle
+- `operations/node_modules/@elevasis/sdk/reference/sdk/cli.mdx` -- every `elevasis-sdk` command and flag
+- `operations/node_modules/@elevasis/sdk/reference/sdk/troubleshooting.mdx` -- diagnosing deploy and execution failures

package/reference/rules/error-handling.md

@@ -25,6 +25,8 @@ throw new ExecutionError('Payment processing failed', {
 
 **`PlatformToolError`** -- thrown by `platform.call()` and typed adapters.
 
+<!-- doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file -->
+
 ```typescript
 import { PlatformToolError } from '@elevasis/sdk'
 
@@ -57,3 +59,27 @@ The platform does NOT automatically retry failed steps. Your handler is responsi
 | `timeout_error`       | Yes       | Integration call timed out        |
 | `credentials_invalid` | No        | Credential not found or expired   |
 | `validation_error`    | No        | Invalid parameters passed to tool |
+
+## CLI Transport Failures
+
+These are errors in the CLI you type commands into, not in your handler code. They are worth knowing because the natural reaction to one of them is the wrong reaction.
+
+**A 502, 503, or 504 does not come from the platform API.** It comes from a hop in front of it that ended your connection while the API was still working, so **the request you sent may have completed in full.** This is measured, not theoretical: a session turn returned 502 to the CLI after 300 seconds and completed successfully server-side at 319.8 seconds, with a model reply written and no error of any kind. The only thing that failed was the connection carrying the answer back.
+
+**Look for the result before re-running the command.** Use `elevasis-sdk executions <resourceId>` to check whether the work landed. Re-running blind on a gateway failure executes it a second time.
+
+**Every CLI request is bounded by a timeout, defaulting to 2 hours.** The limit is deliberately high because it matches the server's own socket budget on long routes -- the goal is to bound an indefinite hang, not to police how long your work may take. Anything shorter would make the CLI give up on executions the API is still legitimately serving. Override with `ELEVASIS_CLI_TIMEOUT_MS`.
+
+"Timed out", "never reached the API", and "the API rejected this" are three distinct messages. If automation branches on CLI stderr, match on the current text rather than on `API request failed`.
+
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/observability.md` -- logging errors so they surface in execution output
+- `operations/node_modules/@elevasis/sdk/reference/rules/execution.md` -- timeouts and cancellation, which fail steps without throwing
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- workflow and step authoring conventions
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/platform-tools/adapters-integration.mdx` -- which adapter calls raise `PlatformToolError`
+- `operations/node_modules/@elevasis/sdk/reference/sdk/troubleshooting.mdx` -- diagnosing failed executions
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- handler patterns including retry loops

package/reference/rules/execution.md

@@ -41,3 +41,16 @@ No developer action needed for multi-tenancy -- the platform handles it.
 ## Cancellation
 
 The platform can cancel in-flight executions. The worker terminates immediately with no cleanup handler.
+
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/error-handling.md` -- error classes and retry decisions
+- `operations/node_modules/@elevasis/sdk/reference/rules/observability.md` -- logging and inspecting a running execution
+- `operations/node_modules/@elevasis/sdk/reference/rules/deployment.md` -- how the bundle workers run from gets built and shipped
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- workflow and agent authoring conventions
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/runtime.mdx` -- worker runtime model in full
+- `operations/node_modules/@elevasis/sdk/reference/sdk/deployment/execution-reference.mdx` -- execution lifecycle and states
+- `operations/node_modules/@elevasis/sdk/reference/sdk/resources/patterns.mdx` -- splitting long work across steps

package/reference/rules/frontend.md

@@ -14,7 +14,7 @@ paths:
 - `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
 - `useApiClient()` from `@elevasis/ui/api` for authenticated API calls, passing `API_URL` from `@/lib/constants/api` -- never raw `fetch` with auth headers. There is no `ui/src/lib/hooks/` directory; see `ui.md` "API and Streaming"
 - `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
-- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Admin pages nest `AdminGuard` inside `ProtectedRoute`
+- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Gate further with `AccessGuard accessKey={...}` nested inside `ProtectedRoute` -- a System path for system gating, or an `AccessKeys` constant (e.g. `AccessKeys.platformAdmin`) for permission-backed gating. `FeatureGuard`, `SystemGuard`, `SurfaceGuard`, and `AdminGuard` are retired -- do not reintroduce them
 - Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
 
 ## Silent-Break Gotchas
@@ -36,10 +36,17 @@ paths:
 
 When building pages that display external data, use published `@elevasis/ui` components before building custom UI. Use Mantine components and CSS variables exclusively -- no inline hex colors, no custom design tokens. Match existing page density and spacing.
 
-## Detailed Reference
+## Related Rules
+
+- **ui.md** -- shell composition, route structure, auth flow, API access, and template customization points
+- **shared-types.md** -- what belongs in `core/types` and the import boundary `ui/src` must respect
+- **organization-model.md** -- System paths and lifecycle values that `AccessGuard accessKey` resolves against
+- **organization-os.md** -- Systems, navigation surfaces, and the `SystemModule` manifest contract
+
+## References
 
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `systemKey` / `SystemGuard` / `AdminGuard` model
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- System lifecycle gating, `AccessGuard` / `useAccess` / `AccessKeys`, and the structured `{ systemPath, action }` key shape
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `NavItem`, `OrganizationModel`)
 - `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions

package/reference/rules/observability.md

@@ -29,6 +29,14 @@ pnpm elevasis-sdk execution <resourceId> <executionId>
 pnpm elevasis-sdk executions <resourceId>
 ```
 
-## Detailed Reference
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/error-handling.md` -- error classes, retry decisions, error visibility
+- `operations/node_modules/@elevasis/sdk/reference/rules/execution.md` -- worker lifecycle, timeouts, cancellation
+- `operations/node_modules/@elevasis/sdk/reference/rules/task-tracking.md` -- recording what an execution produced against a task
+
+## References
 
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- full logging patterns and handler examples
+- `operations/node_modules/@elevasis/sdk/reference/sdk/deployment/execution-reference.mdx` -- execution and step record shapes
+- `operations/node_modules/@elevasis/sdk/reference/sdk/cli.mdx` -- `execution` / `executions` command reference