@elevasis/sdk 1.45.0 → 1.46.0

package/reference/packages/core/src/organization-model/README.md

@@ -1,149 +1,148 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
-
-Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `createFoundationOrganizationModel`
-- node ID and System helper types
-- `OrganizationModel` and supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version`
-- `domainMetadata`
-- `branding`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `capabilities`
-- `policies`
-- `statuses`
-- `knowledge`
-
-The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
-
-Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## System Set
-
-System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
-
-```ts
-systems: {
-  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
-  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
-  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
-  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
-}
-```
-
-Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
-
-## Sidebar Navigation
-
-Shell navigation is authored as a recursive sidebar tree:
-
-```ts
-navigation: {
-  sidebar: {
-    primary: {
-      dashboard: {
-        type: 'surface',
-        order: 10,
-        label: 'Dashboard',
-        path: '/',
-        surfaceType: 'dashboard',
-        targets: { systems: ['dashboard'] }
-      },
-      business: {
-        type: 'group',
-        order: 20,
-        label: 'Business',
-        children: {
-          clients: {
-            type: 'surface',
-            order: 20,
-            label: 'Clients',
-            path: '/clients',
-            surfaceType: 'list',
-            targets: { systems: ['clients'] }
-          }
-        }
-      }
-    },
-    bottom: {}
-  }
-}
-```
-
-Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
-
-## Graph IDs
-
-Cross-collection links use kind-prefixed IDs:
-
-- `system:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `action:operations.queue.review`
-
-## Resource Descriptors
-
-The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
-- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
-- Plain objects merge recursively.
-- Id-keyed domain maps merge additively by key.
-- Arrays replace the default value.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- System IDs must be unique.
-- Child System IDs require valid ancestors or `parentSystemId` links.
-- Systems with UI provide `ui.path`.
-- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model.
-- Use `defineOrganizationModel()` when authoring static overrides.
-- Keep System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
-- Put resource identity and governance in `resources`; attach executable behavior in operations.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and System helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `resources`
+- `capabilities`
+- `statuses`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
+
+Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Set
+
+System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
+
+## Sidebar Navigation
+
+Shell navigation is authored as a recursive sidebar tree:
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+## Resource Descriptors
+
+The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- System IDs must be unique.
+- Child System IDs require valid ancestors or `parentSystemId` links.
+- Systems with UI provide `ui.path`.
+- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model.
+- Use `defineOrganizationModel()` when authoring static overrides.
+- Keep System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put resource identity and governance in `resources`; attach executable behavior in operations.

package/reference/packages/core/src/organization-model/readiness/README.md

@@ -0,0 +1,42 @@
+# System Interface Readiness
+
+The readiness engine answers one question: is a given System's declared interface actually usable, or is something in the tenant's organization model missing or malformed? `computeInterfaceReadiness` produces a structured result rather than a boolean, so a caller can report which family of issue blocked the interface instead of failing opaquely.
+
+Use this module when gating an API surface on a System's adoption state, or when registering a readiness profile that carries real structural validation logic.
+
+## Two registration functions, and only one of them validates
+
+This is the distinction that most often gets it wrong, so it is worth stating plainly:
+
+- **`registerBuiltInReadinessProfile`** (this module) registers a profile **with a validator**. It is the extension point that makes `isBuiltInReadinessProfile` return true.
+- **`registerReadinessProfile`** (in `../domains/systems`) only acknowledges a custom profile id. It registers no validator, writes `kind: 'custom'`, and can **never** make a profile resolve as built-in.
+
+Calling the second one and expecting the first one's effect is a silent no-op — declaring a readiness contract on the System remains mandatory. Only `registerBuiltInReadinessProfile` changes what validation runs.
+
+## Published Exports
+
+```ts
+import {
+  computeInterfaceReadiness,
+  registerBuiltInReadinessProfile,
+  getBuiltInReadinessProfile,
+  registerReadinessInterfaceMarker,
+  resolveReadinessInterfaceMarker,
+  SystemInterfaceReadinessError,
+  type SystemInterfaceReadinessIssue,
+  type SystemInterfaceReadinessIssueFamily,
+  type SystemInterfaceReadinessRequest,
+  type SystemInterfaceReadinessResult,
+  type ReadinessProfileRegistration,
+  type ReadinessProfileValidator,
+  type ReadinessOntologyIndex,
+  type ReadinessInterfaceMarkerResolver,
+  type SystemInterfaceMarker
+} from '@elevasis/core/organization-model/readiness'
+```
+
+This subpath exists so the extension point can be reached without pulling in the rest of `@elevasis/core`. It points at the same module workspace consumers import, deliberately — the two surfaces cannot drift apart.
+
+## Layering constraint
+
+Nothing under `readiness/` may import from `business/**`. The engine is generic; the lead-gen and CRM profile validators are registered **into** it by `business/acquisition` at module load, never the other way around. Adding a `business/` import here inverts the dependency the extraction exists to enforce.

package/reference/packages/ui/src/features/README.md

@@ -1,28 +1,28 @@
-# Features
-
-Feature subpaths package complete shell-level UI flows for downstream apps.
-
-## Published Feature Surfaces
-
-- `./features/auth`
-- `./features/crm`
-- `./features/dashboard`
-- `./features/delivery`
-- `./features/lead-gen`
-- `./features/operations`
-- `./features/monitoring`
-- `./features/seo`
-- `./features/settings`
-
-## What They Contain
-
-- Route shells and page-level components
-- Sidebars and feature-specific navigation
-- Feature manifests for registry consumers
-- Feature-specific hooks and shared constants
-
-## Notes
-
-- These surfaces are meant for app composition, not for low-level design-system primitives.
-- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.
-
+# Features
+
+Feature subpaths package complete shell-level UI flows for downstream apps.
+
+## Published Feature Surfaces
+
+- `./features/auth`
+- `./features/content`
+- `./features/crm`
+- `./features/dashboard`
+- `./features/delivery`
+- `./features/lead-gen`
+- `./features/operations`
+- `./features/monitoring`
+- `./features/seo`
+- `./features/settings`
+
+## What They Contain
+
+- Route shells and page-level components
+- Sidebars and feature-specific navigation
+- Feature manifests for registry consumers
+- Feature-specific hooks and shared constants
+
+## Notes
+
+- These surfaces are meant for app composition, not for low-level design-system primitives.
+- Some feature exports are also re-exported through `./components` for convenience in legacy or mixed consumers.

package/reference/rules/shared-types.md

@@ -27,6 +27,27 @@ Keep this as a standalone rule because it autoloads only for `core/types/**` edi
 - Browser APIs or Node-specific APIs
 - Implementation logic -- types and constants only
 
+## Organization Model Vocabulary Is Not a Shared Constant
+
+"Shared constants" above means values with no home in the Organization Model. It does **not** mean model vocabulary. Stage keys, step ids, action keys, catalog entries, pipeline states, and enumerations like employee-size ranges are **model-owned**, and copying them into `core/types/` is architecturally excluded — not merely discouraged.
+
+The reason is ownership: every project owns its own Organization Model, so a TypeScript constant can only ever encode one project's vocabulary. It cannot be shared substrate, and it silently diverges the moment the model changes, with no gate comparing the two. The platform ruled this out for itself as well and deleted its own copy of this mirror; do not reintroduce the pattern here.
+
+Read the vocabulary from the resolved model instead — the catalog helpers and config hooks exist for exactly this.
+
+### The four-place contract
+
+One build-step id has to be spelled identically in four places, and **nothing compares them**:
+
+| Place                          | What it holds                                  |
+| ------------------------------ | ---------------------------------------------- |
+| the workflow contract          | the step id the handler dispatches on          |
+| the OM `template-step` catalog | the same id as a catalog entry                 |
+| the resource ontology bindings | the actions and catalogs the resource declares |
+| the UI action keys             | the key the surface invokes                    |
+
+A mismatch is not a type error. It surfaces at runtime as a step that never matches or an action that never fires, which is why the id is worth checking against all four before authoring downstream of it.
+
 ## Schema Convention
 
 Define Zod schemas first, then infer the type:

package/reference/scaffold/core/organization-graph.mdx

@@ -35,7 +35,6 @@ Node kinds:
 - `event`
 - `resource`
 - `knowledge`
-- `policy`
 - `stage`
 - `customer-segment`
 - `offering`
@@ -72,7 +71,7 @@ Edge kinds:
 
 System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
 
-Resource, action, entity, policy, navigation, and ontology catalog edges are derived from canonical OM maps:
+Resource, action, entity, navigation, and ontology catalog edges are derived from canonical OM maps:
 
 ```ts
 // ResourceEntry.systemPath => system -> resource contains
@@ -101,7 +100,7 @@ interface BuildOrganizationGraphInput {
 
 1. Reads Organization Model Systems and derives `system:*` nodes.
 2. Reads OM resources, including workflow, agent, integration, and script resources, as `resource` nodes.
-3. Emits derived graph links from System, Resource, Action, Entity, Policy, Agent invocation, Knowledge, navigation, and ontology catalog contracts.
+3. Emits derived graph links from System, Resource, Action, Entity, Agent invocation, Knowledge, navigation, and ontology catalog contracts.
 4. Bridges Command View runtime topology into resource nodes and relationship edges.
 5. Returns a renderer-agnostic DTO.
 

package/reference/scaffold/core/organization-model.mdx

@@ -43,10 +43,9 @@ Top-level fields on `OrganizationModel`:
 - `topology`
 - `actions`
 - `entities`
-- `policies`
 - `knowledge`
 
-The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `clients`, `customers`, `offerings`, `resources`, `actions`, `entities`, `policies`, and `knowledge`. `ontology` is an `OntologyScope` object (not an id-keyed map at the top level) and `topology` is a relationships record. The map key must match the entry `id` for id-keyed domains. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters. `sales`, `prospecting`, `projects`, and `statuses` were removed from the top-level contract; do not author against them.
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `clients`, `customers`, `offerings`, `resources`, `actions`, `entities`, and `knowledge`. `ontology` is an `OntologyScope` object (not an id-keyed map at the top level) and `topology` is a relationships record. The map key must match the entry `id` for id-keyed domains. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters. `sales`, `prospecting`, `projects`, `statuses`, and `policies` were removed from the top-level contract; do not author against them.
 
 Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
 
@@ -74,11 +73,9 @@ Authored fields:
 - `parentSystemId`
 - `ui`
 - `lifecycle`
-- `requiresAdmin`
 - `responsibleRoleId`
 - `governedByKnowledge`
 - `actions`
-- `policies`
 - `drivesGoals`
 - `apiInterface`
 - `config`
@@ -169,7 +166,7 @@ export const resourceDescriptors = defineResources({
     },
     codeRefs: [
       {
-        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
+        path: 'packages/elevasis/operations/src/sales/prospecting/scrape/apollo-import.ts',
         role: 'entrypoint',
         symbol: 'lgnApolloImportWorkflow'
       }
@@ -195,7 +192,6 @@ The model keeps business semantics in named domains:
 - `actions` -- stable business verbs exposed or consumed by systems
 - `entities` -- durable business nouns and their semantic links
 - `resources` -- governance-only workflow, agent, integration, and script descriptors
-- `policies` -- operational governance rules over systems, actions, resources, and roles
 - `knowledge` -- playbooks, strategies, references, and graph-governing links
 
 System-local operational catalogs live under `System.ontology.catalogTypes`, including pipeline, stage, template, template-step, status-flow, and status records. System-local settings live in `System.config`. The legacy compound and status domains should not be used for new authoring.

package/reference/scaffold/operations/propagation-pipeline.md

@@ -31,19 +31,18 @@ Layer 3: Sync Verification (pnpm sync:verify)
 
 ## Layer 1: Source Generation
 
-`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains seven sub-scripts:
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains six sub-scripts:
 
-| Script                 | Input                                                                                                                 | Output                                                                                                     |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `scaffold:generate`    | Scaffold contract and feature-registry sources                                                                        | `packages/core/src/reference/_generated/**`, `packages/ui/src/scaffold/_generated/feature-registry.md`     |
-| `knowledge:generate`   | Elevasis core knowledge nodes and UI knowledge body sources                                                           | Generated knowledge nodes and UI knowledge bodies                                                          |
-| `gen:sdk-catalog`      | SDK catalog source definitions                                                                                         | SDK catalog artifacts                                                                                      |
-| `gen:sdk-adapters`     | SDK adapter definitions                                                                                                | SDK adapter artifacts                                                                                      |
-| `copy-docs`            | SDK docs, package-owned reference docs, scaffold docs, and `_template/.claude` config                                  | `packages/sdk/reference/**` copied docs and scaffold reference bundle                                       |
-| `sdk-ref:generate`     | SDK manifest and navigation sources                                                                                    | `packages/sdk/reference/_reference-manifest.json`, `packages/sdk/reference/_navigation.md`                  |
-| `sdk-ref:check`        | Generated SDK reference artifacts                                                                                      | Freshness validation for `packages/sdk/reference/_reference-manifest.json` and `_navigation.md`             |
+| Script               | Input                                                                                 | Output                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `scaffold:generate`  | Scaffold contract and feature-registry sources                                        | `packages/core/src/reference/_generated/**`, `packages/ui/src/scaffold/_generated/feature-registry.md` |
+| `knowledge:generate` | Elevasis core knowledge nodes and UI knowledge body sources                           | Generated knowledge nodes and UI knowledge bodies                                                      |
+| `gen:sdk-catalog`    | SDK catalog source definitions                                                        | SDK catalog artifacts                                                                                  |
+| `gen:sdk-adapters`   | SDK adapter definitions                                                               | SDK adapter artifacts                                                                                  |
+| `copy-docs`          | SDK docs, package-owned reference docs, scaffold docs, and `_template/.claude` config | `packages/sdk/reference/**` copied docs, `_reference-manifest.json`, and `_navigation.md`              |
+| `sdk-ref:check`      | Generated SDK reference artifacts                                                     | Freshness validation for `packages/sdk/reference/_reference-manifest.json` and `_navigation.md`        |
 
-The final `sdk-ref:check` step validates that the reference artifacts are consistent. Exit 1 if drifted.
+`copy-docs` (`packages/sdk/scripts/copy-reference-docs.mjs`) atomically regenerates `_reference-manifest.json` and `_navigation.md` itself as its own Phase 5, via the same `buildAllArtifacts()`/`writeArtifacts()` functions the standalone `sdk-ref:generate` script runs -- so there is no separate `sdk-ref:generate` step in this chain; running it again after `copy-docs` would just recompute an identical result. The final `sdk-ref:check` step validates that the reference artifacts are consistent. Exit 1 if drifted.
 
 ### Trigger Points
 
@@ -63,12 +62,12 @@ Drift is healed at the moment it would otherwise leak downstream. This is cheape
 `/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
 The canonical ownership vocabulary is:
 
-| Category      | Strategy examples                 | Meaning                                                             |
-| ------------- | --------------------------------- | ------------------------------------------------------------------- |
-| `replace`     | `replace-all`                     | Template-managed surface; copy from template baseline               |
+| Category      | Strategy examples                          | Meaning                                                             |
+| ------------- | ------------------------------------------ | ------------------------------------------------------------------- |
+| `replace`     | `replace-all`                              | Template-managed surface; copy from template baseline               |
 | `merge`       | `merge-baseline`, `preserve-on-divergence` | Merge-aware surface; preserve project customizations where required |
-| `never-touch` | `verify-only`                     | Project-owned surface; planner may report drift but never writes    |
-| `generated`   | `generated-freshness`             | Generated surface; verify/regen instead of copying                  |
+| `never-touch` | `verify-only`                              | Project-owned surface; planner may report drift but never writes    |
+| `generated`   | `generated-freshness`                      | Generated surface; verify/regen instead of copying                  |
 
 Current command helpers:
 

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -100,12 +100,13 @@ Generated files should never be edited manually. If the output is wrong, fix the
 
 ## SDK Build Pipeline (Reference Copy)
 
-`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has four phases:
+`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` (and as the `copy-docs` root script) and has five phases:
 
 1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
 2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
 3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map
-4. **Phase 4:** Copies `external/_template/.claude` into `packages/sdk/reference/claude-config` for tenant-facing agent configuration
+4. **Phase 4:** Generates a pointer doc (`claude-config.md`) to the tenant's own `.claude/` config instead of bundling it wholesale
+5. **Phase 5 (F14):** Atomically regenerates `_reference-manifest.json` and `_navigation.md` via the same `buildAllArtifacts()`/`writeArtifacts()` functions the standalone `sdk-ref:generate` script runs -- this happens after the wipe-and-recopy above because the orphan-reachability check inside `buildAllArtifacts()` walks the output directory. This closes the window where `packages/sdk/reference/` could sit without those two files between a `copy-docs` run and a separate `sdk-ref:generate` run, so a chain that already runs `copy-docs` never needs a following `sdk-ref:generate` step -- it would just recompute an identical result.
 
 The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `operations/node_modules/@elevasis/sdk/reference/`.
 

package/reference/scaffold/operations/workflow-recipes.md

@@ -409,10 +409,10 @@ pnpm elevasis-sdk exec Elevasis/email-notification --async --input '{...}'
 pnpm elevasis-sdk execution Elevasis/email-notification <executionId>
 ```
 
-The `--prod` flag targets `https://api.elevasis.io` and goes **before** the command:
+The `--prod` flag targets `https://api.elevasis.io` and goes **after** the command name -- the SDK CLI parses it as a per-command Commander option, not a global flag (`.claude/rules/cli-cwd-invariant.md`):
 
 ```bash
-pnpm elevasis-sdk --prod exec Elevasis/email-notification --input '{...}'
+pnpm elevasis-sdk exec Elevasis/email-notification --prod --input '{...}'
 ```
 
 ---

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -84,7 +84,7 @@ These wrap existing `LeadService` logic -- they are extraction, not new business
 
 Deploy a workflow with the same `workflowId` as the default action you want to replace. The resource registry resolves your project-owned workflow first.
 
-The canonical transition workflow (see `packages/elevasis-operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
+The canonical transition workflow (see `packages/elevasis/operations/src/sales/crm/actions/move-to-proposal.ts` for the deployed reference):
 
 <!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `../shared/action-workflow-schemas.js` is a project-local sibling file -->
 
@@ -220,7 +220,7 @@ This controls the shared `DealDetailPage` and `DealDrawer` action row.
 
 For a brand-new action key that calls a project-owned workflow, define the workflow first.
 
-If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the workflow handler to append an audit entry to the deal's `activity_log`. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `packages/elevasis-operations/src/sales/crm/actions/`.
+If the action sends email, writes to another channel, or otherwise touches a customer, use `acqDb.recordDealActivity` inside the workflow handler to append an audit entry to the deal's `activity_log`. For an advanced Instantly-thread-aware variant that prefers in-thread replies and falls back to fresh outbound, see the canonical CRM action examples in `packages/elevasis/operations/src/sales/crm/actions/`.
 
 ### Define the Workflow Contract
 
@@ -420,12 +420,12 @@ export function CustomDealPage({ dealId }: { dealId: string }) {
 
 ## CRM State-Key Source of Truth
 
-CRM `stage_key` and `state_key` values are tenant/runtime data. In the Elevasis workspace, the canonical CRM pipeline definition lives in `@repo/elevasis-core/organization-model` and is authored into the `sales.crm:catalog/crm.pipeline` ontology catalog on the canonical organization model. Published `@elevasis/core` keeps only generic `StatefulPipelineDefinition` types/helpers and transport schemas.
+CRM `stage_key` and `state_key` values are tenant/runtime data. In the Elevasis workspace, the canonical CRM pipeline definition lives in `@repo/elevasis-core/sales` and is authored into the `sales.crm:catalog/crm.pipeline` ontology catalog on the canonical organization model. Published `@elevasis/core` keeps only generic `StatefulPipelineDefinition` types/helpers and transport schemas.
 
-Within the Elevasis monorepo, import the tenant pipeline data from `@repo/elevasis-core/organization-model` and the generic `getValidStatesForStage` helper from `@repo/core/organization-model`:
+Within the Elevasis monorepo, import the tenant pipeline data from `@repo/elevasis-core/sales` and the generic `getValidStatesForStage` helper from `@repo/core/organization-model`:
 
 ```ts
-import { CRM_PIPELINE_DEFINITION, CRM_DISCOVERY_REPLIED_STATE } from '@repo/elevasis-core/organization-model'
+import { CRM_PIPELINE_DEFINITION, CRM_DISCOVERY_REPLIED_STATE } from '@repo/elevasis-core/sales'
 import { getValidStatesForStage } from '@repo/core/organization-model'
 
 const validStates = getValidStatesForStage(CRM_PIPELINE_DEFINITION, 'interested')