@elevasis/sdk 1.8.2 → 1.9.0

package/reference/scaffold/recipes/add-a-feature.md

@@ -1,158 +1,158 @@
----
-title: Add a Feature
-description: End-to-end walkthrough for adding a new shell feature (e.g., analytics) from org-model key through manifest, routes, and gating.
----
-
-# Add a Feature
-
-End-to-end: add a new shell feature such as `analytics`. Steps are sequential.
-
-See [glossary.md](../reference/glossary.md) for term disambiguation throughout this recipe (Feature has three distinct contexts). See [contracts.md](../reference/contracts.md) for authoritative TypeScript shapes.
-
----
-
-## 1. Decide the feature shape
-
-A shell feature requires a `feature.id` in the org model's `features[]` array to gate it. You have two options:
-
-- **Reuse an existing feature** (e.g., `operations`, `monitoring`). The new shell module shares the on/off toggle with the existing feature entry. Fine for sub-modules within the same product area.
-- **Add a new feature object** -- add an entry to the `features[]` array in `foundations/config/organization-model.ts`. This is always a template-local change; no core package change is required.
-
-For a genuinely new capability (e.g., `analytics`), you add a feature object to the defaults array and author a matching manifest.
-
-See [glossary.md](../reference/glossary.md) under **Feature** (three contexts).
-
----
-
-## 2. Update the organization model
-
-File: `foundations/config/organization-model.ts`
-
-Add a new feature object to the `features[]` array passed to `defineOrganizationModel`.
-
-```ts
-import { defineOrganizationModel } from '@elevasis/core/organization-model'
-```
-
-Use typed constants for the 7 platform features (`SALES_FEATURE_ID`, `PROSPECTING_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`); use string literals for project-specific features you invent.
-
-```ts
-const foundationOrganizationModelOverride = defineOrganizationModel({
-  features: [
-    // ... existing features
-    {
-      id: 'analytics',
-      label: 'Analytics',
-      enabled: false,          // start disabled
-      entityIds: [],
-      surfaceIds: [],
-      resourceIds: [],
-      capabilityIds: []
-    }
-  ],
-  // ... rest of model
-})
-```
-
-Each field of the feature object:
-
-- `id` -- unique stable identifier; this is the value `FeatureModule.featureId` must match
-- `label` -- display name; used by nav label resolution when no manifest override is provided
-- `enabled` -- org-wide default; `MembershipFeatureConfig.features` can override per member
-- `entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds` -- semantic references (leave empty to start)
-
-No domain entry or separate key resolver is needed. The `features[]` array is the sole source of truth.
-
-**Two-step pattern:** in a template-derived project, the `defineOrganizationModel` output is passed to `createFoundationOrganizationModel(override)` in `foundations/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/foundations/config/organization-model.ts` for the canonical two-step example.
-
----
-
-## 3. Author the FeatureModule
-
-Create `ui/src/features/analytics/manifest.ts`. Full `FeatureModule` shape is in [contracts.md](../reference/contracts.md#featuremodule) (`@elevasis/ui/provider`).
-
-```ts
-import type { FeatureModule } from '@elevasis/ui/provider'
-import { IconChartBar } from '@tabler/icons-react'
-import { AnalyticsSidebar } from './sidebar'
-
-export const analyticsManifest: FeatureModule = {
-  key: 'analytics',
-  featureId: 'analytics',     // must match a feature.id in the org model's features[] array
-  navEntry: {
-    label: 'Analytics',
-    icon: IconChartBar,
-    link: '/analytics'
-  },
-  sidebar: AnalyticsSidebar,
-  subshellRoutes: ['/analytics', '/analytics/reports']
-}
-```
-
-Key fields:
-
-- `featureId` -- the org-model feature ID that gates the entire feature. The provider throws at startup if this ID is not found in the org model's `features[]` array. See [glossary.md](../reference/glossary.md) under **featureId**.
-- `sidebar` -- a component that renders the subshell sidebar. Compose from published primitives. See [customization.md](../ui/customization.md).
-- `subshellRoutes` -- every path that should activate this feature's sidebar.
-
-Register the manifest in `ui/src/routes/__root.tsx` by adding it to the `FEATURE_MANIFESTS` array passed to `ElevasisFeaturesProvider`.
-
----
-
-## 4. Add routes under the subshell
-
-Create the TanStack Router layout and child routes.
-
-Layout file (`ui/src/routes/analytics.tsx`) owns the subshell guard and renders `<Outlet />`:
-
-```tsx
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-import { ProtectedRoute } from '@/features/auth'
-import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
-
-export const Route = createFileRoute('/analytics')({
-  component: AnalyticsLayout
-})
-
-function AnalyticsLayout() {
-  return (
-    <ProtectedRoute>
-      <FeatureGuard featureKey="analytics">
-        <Outlet />
-      </FeatureGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-Child pages go under `ui/src/routes/analytics/`. See [UI Recipes](../ui/recipes.md) recipe 2 for the nested page pattern.
-
----
-
-## 5. Gate the route
-
-Two independent mechanisms -- use both:
-
-- `FeatureGuard` (feature-level): blocks access when the org model has the feature key disabled or when the member's `MembershipFeatureConfig` disables it. Always nest inside `ProtectedRoute`.
-- `AdminGuard` (admin-level): blocks access for non-admin members. Add this if the feature should only be accessible to admins.
-
-Full decision table and import paths are in [gate-by-feature-or-admin.md](gate-by-feature-or-admin.md).
-
----
-
-## 6. (Optional) Add operations resources that back the feature
-
-If the feature drives automation (e.g., an analytics pipeline workflow), create the resources in `operations/src/` and optionally map them into the org model via `resourceMappings`. See [add-a-resource.md](add-a-resource.md).
-
----
-
-## 7. Verify
-
-```bash
-pnpm -C ui dev
-```
-
-- Feature appears in the nav sidebar.
-- Route is accessible and the subshell sidebar renders.
-- Toggle `features.enabled.analytics` to `false` in `foundations/config/organization-model.ts` and confirm the nav item disappears and the route redirects.
-- Check `FeatureGuard` by navigating directly to `/analytics` with the feature disabled.
+---
+title: Add a Feature
+description: End-to-end walkthrough for adding a new shell feature (e.g., analytics) from org-model key through manifest, routes, and gating.
+---
+
+# Add a Feature
+
+End-to-end: add a new shell feature such as `analytics`. Steps are sequential.
+
+See [glossary.md](../reference/glossary.md) for term disambiguation throughout this recipe (Feature has three distinct contexts). See [contracts.md](../reference/contracts.md) for authoritative TypeScript shapes.
+
+---
+
+## 1. Decide the feature shape
+
+A shell feature requires a `feature.id` in the org model's `features[]` array to gate it. You have two options:
+
+- **Reuse an existing feature** (e.g., `operations`, `monitoring`). The new shell module shares the on/off toggle with the existing feature entry. Fine for sub-modules within the same product area.
+- **Add a new feature object** -- add an entry to the `features[]` array in `foundations/config/organization-model.ts`. This is always a template-local change; no core package change is required.
+
+For a genuinely new capability (e.g., `analytics`), you add a feature object to the defaults array and author a matching manifest.
+
+See [glossary.md](../reference/glossary.md) under **Feature** (three contexts).
+
+---
+
+## 2. Update the organization model
+
+File: `foundations/config/organization-model.ts`
+
+Add a new feature object to the `features[]` array passed to `defineOrganizationModel`.
+
+```ts
+import { defineOrganizationModel } from '@elevasis/core/organization-model'
+```
+
+Use typed constants for the 7 platform features (`SALES_FEATURE_ID`, `PROSPECTING_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`); use string literals for project-specific features you invent.
+
+```ts
+const foundationOrganizationModelOverride = defineOrganizationModel({
+  features: [
+    // ... existing features
+    {
+      id: 'analytics',
+      label: 'Analytics',
+      enabled: false,          // start disabled
+      entityIds: [],
+      surfaceIds: [],
+      resourceIds: [],
+      capabilityIds: []
+    }
+  ],
+  // ... rest of model
+})
+```
+
+Each field of the feature object:
+
+- `id` -- unique stable identifier; this is the value `FeatureModule.featureId` must match
+- `label` -- display name; used by nav label resolution when no manifest override is provided
+- `enabled` -- org-wide default; `MembershipFeatureConfig.features` can override per member
+- `entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds` -- semantic references (leave empty to start)
+
+No domain entry or separate key resolver is needed. The `features[]` array is the sole source of truth.
+
+**Two-step pattern:** in a template-derived project, the `defineOrganizationModel` output is passed to `createFoundationOrganizationModel(override)` in `foundations/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/foundations/config/organization-model.ts` for the canonical two-step example.
+
+---
+
+## 3. Author the FeatureModule
+
+Create `ui/src/features/analytics/manifest.ts`. Full `FeatureModule` shape is in [contracts.md](../reference/contracts.md#featuremodule) (`@elevasis/ui/provider`).
+
+```ts
+import type { FeatureModule } from '@elevasis/ui/provider'
+import { IconChartBar } from '@tabler/icons-react'
+import { AnalyticsSidebar } from './sidebar'
+
+export const analyticsManifest: FeatureModule = {
+  key: 'analytics',
+  featureId: 'analytics',     // must match a feature.id in the org model's features[] array
+  navEntry: {
+    label: 'Analytics',
+    icon: IconChartBar,
+    link: '/analytics'
+  },
+  sidebar: AnalyticsSidebar,
+  subshellRoutes: ['/analytics', '/analytics/reports']
+}
+```
+
+Key fields:
+
+- `featureId` -- the org-model feature ID that gates the entire feature. The provider throws at startup if this ID is not found in the org model's `features[]` array. See [glossary.md](../reference/glossary.md) under **featureId**.
+- `sidebar` -- a component that renders the subshell sidebar. Compose from published primitives. See [customization.md](../ui/customization.md).
+- `subshellRoutes` -- every path that should activate this feature's sidebar.
+
+Register the manifest in `ui/src/routes/__root.tsx` by adding it to the `FEATURE_MANIFESTS` array passed to `ElevasisFeaturesProvider`.
+
+---
+
+## 4. Add routes under the subshell
+
+Create the TanStack Router layout and child routes.
+
+Layout file (`ui/src/routes/analytics.tsx`) owns the subshell guard and renders `<Outlet />`:
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+
+export const Route = createFileRoute('/analytics')({
+  component: AnalyticsLayout
+})
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Child pages go under `ui/src/routes/analytics/`. See [UI Recipes](../ui/recipes.md) recipe 2 for the nested page pattern.
+
+---
+
+## 5. Gate the route
+
+Two independent mechanisms -- use both:
+
+- `FeatureGuard` (feature-level): blocks access when the org model has the feature key disabled or when the member's `MembershipFeatureConfig` disables it. Always nest inside `ProtectedRoute`.
+- `AdminGuard` (admin-level): blocks access for non-admin members. Add this if the feature should only be accessible to admins.
+
+Full decision table and import paths are in [gate-by-feature-or-admin.md](gate-by-feature-or-admin.md).
+
+---
+
+## 6. (Optional) Add operations resources that back the feature
+
+If the feature drives automation (e.g., an analytics pipeline workflow), create the resources in `operations/src/` and optionally map them into the org model via `resourceMappings`. See [add-a-resource.md](add-a-resource.md).
+
+---
+
+## 7. Verify
+
+```bash
+pnpm -C ui dev
+```
+
+- Feature appears in the nav sidebar.
+- Route is accessible and the subshell sidebar renders.
+- Toggle `features.enabled.analytics` to `false` in `foundations/config/organization-model.ts` and confirm the nav item disappears and the route redirects.
+- Check `FeatureGuard` by navigating directly to `/analytics` with the feature disabled.

package/reference/scaffold/recipes/add-a-resource.md

@@ -1,158 +1,158 @@
----
-title: Add a Resource
-description: End-to-end walkthrough for adding a new workflow or agent to the deployment spec, declaring relationships, and verifying in the resource inventory.
----
-
-# Add a Resource
-
-End-to-end: add a new workflow or agent to `operations/` and verify it in the platform inventory. Steps are sequential.
-
-See [glossary.md](../reference/glossary.md) under **Resource**, **DeploymentSpec**, and **Topology**. See [contracts.md](../reference/contracts.md) for `OrganizationModel` and `OrganizationModelResourceMapping` shapes.
-
----
-
-## 1. Author the resource
-
-Create `operations/src/<name>/index.ts`. Follow the anatomy from [workflow-recipes.md](../operations/workflow-recipes.md) recipe 1 for the full `WorkflowDefinition` shape.
-
-```ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { StepType } from '@elevasis/sdk'
-import { myInputSchema, myOutputSchema } from '@foundation/types'
-
-export const myWorkflow: WorkflowDefinition = {
-  config: {
-    resourceId: 'my-workflow',
-    name: 'My Workflow',
-    type: 'workflow',
-    version: '1.0.0',
-    status: 'dev'
-  },
-  contract: {
-    inputSchema: myInputSchema,
-    outputSchema: myOutputSchema
-  },
-  steps: {
-    run: {
-      id: 'run',
-      name: 'Run',
-      handler: async (rawInput, context) => {
-        context.logger.info('[run] starting')
-        // ...
-        return { result: 'done' }
-      },
-      inputSchema: myInputSchema,
-      outputSchema: myOutputSchema,
-      next: null
-    }
-  },
-  entryPoint: 'run'
-}
-```
-
-Define input/output schemas in `foundations/types/index.ts`, not inline. Both runtimes import from `@foundation/types`. See [workflow-recipes.md](../operations/workflow-recipes.md) for Zod schema conventions and adapter usage (`llm`, `storage`, `scheduler`, `notifications` from `@elevasis/sdk/worker`).
-
-**Entity-backed workflows:** if your workflow operates on a domain entity (Project, Deal, Company, etc.), define or reference the entity shape in `foundations/types/entities.ts` rather than declaring an ad-hoc shape here. The entity types extend base contracts from `@elevasis/core/entities` (`BaseProject`, `BaseDeal`, etc.) with project-specific metadata. See [./extend-a-base-entity.md](./extend-a-base-entity.md) for the pattern.
-
----
-
-## 2. Register in the DeploymentSpec
-
-Create an exports barrel at `operations/src/<name>/exports.ts`:
-
-```ts
-import { myWorkflow } from './index.js'
-import type { WorkflowDefinition } from '@elevasis/sdk'
-
-export const workflows: WorkflowDefinition[] = [myWorkflow]
-export const agents: never[] = []
-```
-
-Then spread into the top-level spec at `operations/src/index.ts`:
-
-```ts
-import * as myFeature from './my-feature/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
-  workflows: [...existing.workflows, ...myFeature.workflows],
-  agents:    [...existing.agents,    ...myFeature.agents]
-}
-```
-
-Use `.js` extensions in imports even though source is TypeScript -- required for ESM interoperability.
-
----
-
-## 3. (Optional) Declare relationships
-
-If the resource triggers another resource, uses a human checkpoint, or depends on an integration, declare those relationships on the `DeploymentSpec`. See [glossary.md](../reference/glossary.md) under **Topology** for the three edge types (`triggers`, `uses`, `approval`).
-
-```ts
-const org: DeploymentSpec = {
-  // ...
-  relationships: {
-    'my-workflow': {
-      triggers: { workflows: ['email-notification'] }
-    }
-  },
-  humanCheckpoints: [
-    {
-      resourceId: 'approval-gate',
-      name: 'Approve before sending',
-      type: 'human',
-      version: '1.0.0',
-      status: 'prod',
-      routesTo: { workflows: ['my-workflow'] }
-    }
-  ]
-}
-```
-
-Full relationship and checkpoint types are defined in `@elevasis/sdk` (`DeploymentSpec`). Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly.
-
----
-
-## 4. (Optional) Map to a domain
-
-To make the resource referenceable from the org model (so the Operations graph and Command View can link to it), add an entry to `resourceMappings` in `foundations/config/organization-model.ts`:
-
-```ts
-resourceMappings: [
-  {
-    id: 'my-workflow',
-    resourceId: 'my-workflow',
-    resourceType: 'workflow',
-    domainIds: ['operations'],
-    label: 'My Workflow'
-  }
-]
-```
-
-See `OrganizationModelResourceMapping` in [contracts.md](../reference/contracts.md) for the full shape.
-
----
-
-## 5. Verify resource inventory
-
-Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly. Confirm the new resource appears with the correct `resourceId`, `version`, and `status`.
-
----
-
-## 6. Verify
-
-Validate and deploy:
-
-```bash
-pnpm -C operations run check   # validate resource definitions
-pnpm -C operations run deploy  # deploy to dev
-```
-
-Execute via the platform CLI from the project root:
-
-```bash
-pnpm exec elevasis describe Elevasis/my-workflow
-pnpm exec elevasis exec Elevasis/my-workflow --input '{"field": "value"}'
-```
-
-Use `--async` for long-running resources. Use `pnpm exec elevasis --prod exec ...` (flag before `exec`) for production. See [workflow-recipes.md](../operations/workflow-recipes.md) recipe 3 for the low-level frontend trigger pattern (`useApiClient` + `useMutation`). For the higher-level UI pattern using `RunResourceButton`, `useExecuteResource`, and `ZodFormRenderer`, see [../ui/recipes.md](../ui/recipes.md) recipe 6.
+---
+title: Add a Resource
+description: End-to-end walkthrough for adding a new workflow or agent to the deployment spec, declaring relationships, and verifying in the resource inventory.
+---
+
+# Add a Resource
+
+End-to-end: add a new workflow or agent to `operations/` and verify it in the platform inventory. Steps are sequential.
+
+See [glossary.md](../reference/glossary.md) under **Resource**, **DeploymentSpec**, and **Topology**. See [contracts.md](../reference/contracts.md) for `OrganizationModel` and `OrganizationModelResourceMapping` shapes.
+
+---
+
+## 1. Author the resource
+
+Create `operations/src/<name>/index.ts`. Follow the anatomy from [workflow-recipes.md](../operations/workflow-recipes.md) recipe 1 for the full `WorkflowDefinition` shape.
+
+```ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { StepType } from '@elevasis/sdk'
+import { myInputSchema, myOutputSchema } from '@foundation/types'
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'my-workflow',
+    name: 'My Workflow',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev'
+  },
+  contract: {
+    inputSchema: myInputSchema,
+    outputSchema: myOutputSchema
+  },
+  steps: {
+    run: {
+      id: 'run',
+      name: 'Run',
+      handler: async (rawInput, context) => {
+        context.logger.info('[run] starting')
+        // ...
+        return { result: 'done' }
+      },
+      inputSchema: myInputSchema,
+      outputSchema: myOutputSchema,
+      next: null
+    }
+  },
+  entryPoint: 'run'
+}
+```
+
+Define input/output schemas in `foundations/types/index.ts`, not inline. Both runtimes import from `@foundation/types`. See [workflow-recipes.md](../operations/workflow-recipes.md) for Zod schema conventions and adapter usage (`llm`, `storage`, `scheduler`, `notifications` from `@elevasis/sdk/worker`).
+
+**Entity-backed workflows:** if your workflow operates on a domain entity (Project, Deal, Company, etc.), define or reference the entity shape in `foundations/types/entities.ts` rather than declaring an ad-hoc shape here. The entity types extend base contracts from `@elevasis/core/entities` (`BaseProject`, `BaseDeal`, etc.) with project-specific metadata. See [./extend-a-base-entity.md](./extend-a-base-entity.md) for the pattern.
+
+---
+
+## 2. Register in the DeploymentSpec
+
+Create an exports barrel at `operations/src/<name>/exports.ts`:
+
+```ts
+import { myWorkflow } from './index.js'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+
+export const workflows: WorkflowDefinition[] = [myWorkflow]
+export const agents: never[] = []
+```
+
+Then spread into the top-level spec at `operations/src/index.ts`:
+
+```ts
+import * as myFeature from './my-feature/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  workflows: [...existing.workflows, ...myFeature.workflows],
+  agents:    [...existing.agents,    ...myFeature.agents]
+}
+```
+
+Use `.js` extensions in imports even though source is TypeScript -- required for ESM interoperability.
+
+---
+
+## 3. (Optional) Declare relationships
+
+If the resource triggers another resource, uses a human checkpoint, or depends on an integration, declare those relationships on the `DeploymentSpec`. See [glossary.md](../reference/glossary.md) under **Topology** for the three edge types (`triggers`, `uses`, `approval`).
+
+```ts
+const org: DeploymentSpec = {
+  // ...
+  relationships: {
+    'my-workflow': {
+      triggers: { workflows: ['email-notification'] }
+    }
+  },
+  humanCheckpoints: [
+    {
+      resourceId: 'approval-gate',
+      name: 'Approve before sending',
+      type: 'human',
+      version: '1.0.0',
+      status: 'prod',
+      routesTo: { workflows: ['my-workflow'] }
+    }
+  ]
+}
+```
+
+Full relationship and checkpoint types are defined in `@elevasis/sdk` (`DeploymentSpec`). Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly.
+
+---
+
+## 4. (Optional) Map to a domain
+
+To make the resource referenceable from the org model (so the Operations graph and Command View can link to it), add an entry to `resourceMappings` in `foundations/config/organization-model.ts`:
+
+```ts
+resourceMappings: [
+  {
+    id: 'my-workflow',
+    resourceId: 'my-workflow',
+    resourceType: 'workflow',
+    featureIds: ['operations'],
+    label: 'My Workflow'
+  }
+]
+```
+
+See `OrganizationModelResourceMapping` in [contracts.md](../reference/contracts.md) for the full shape.
+
+---
+
+## 5. Verify resource inventory
+
+Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly. Confirm the new resource appears with the correct `resourceId`, `version`, and `status`.
+
+---
+
+## 6. Verify
+
+Validate and deploy:
+
+```bash
+pnpm -C operations run check   # validate resource definitions
+pnpm -C operations run deploy  # deploy to dev
+```
+
+Execute via the platform CLI from the project root:
+
+```bash
+pnpm exec elevasis describe Elevasis/my-workflow
+pnpm exec elevasis exec Elevasis/my-workflow --input '{"field": "value"}'
+```
+
+Use `--async` for long-running resources. Use `pnpm exec elevasis --prod exec ...` (flag before `exec`) for production. See [workflow-recipes.md](../operations/workflow-recipes.md) recipe 3 for the low-level frontend trigger pattern (`useApiClient` + `useMutation`). For the higher-level UI pattern using `RunResourceButton`, `useExecuteResource`, and `ZodFormRenderer`, see [../ui/recipes.md](../ui/recipes.md) recipe 6.