@elevasis/sdk 1.10.0 → 1.11.0

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

@@ -1,158 +1,102 @@
----
-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 `core/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: `core/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 `core/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/core/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 `core/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: Add a shell feature using the flat Organization Model feature list, manifest registration, routes, and guards.
+---
+
+# Add a Feature
+
+Shell navigation is derived from `OrganizationModel.features`. Feature manifests attach implementation details to those feature IDs; they do not declare sidebar nav structure.
+
+## 1. Add the feature node
+
+Edit `core/config/organization-model.ts` and add a feature to the `features` override.
+
+```ts
+const organizationOverride = defineOrganizationModel({
+  features: [
+    {
+      id: 'analytics',
+      label: 'Analytics',
+      enabled: true,
+      path: '/analytics',
+      icon: 'chart',
+      uiPosition: 'sidebar-primary'
+    }
+  ]
+})
+```
+
+Use dotted IDs for hierarchy:
+
+```ts
+{ id: 'analytics', label: 'Analytics', enabled: true, uiPosition: 'sidebar-primary' },
+{ id: 'analytics.reports', label: 'Reports', enabled: true, path: '/analytics/reports' }
+```
+
+Containers omit `path`; leaves provide `path`.
+
+## 2. Add the manifest
+
+Create `ui/src/features/analytics/manifest.ts`.
+
+```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',
+  icon: IconChartBar,
+  sidebar: AnalyticsSidebar
+}
+```
+
+Register it in the `FEATURE_MANIFESTS` array in `ui/src/routes/__root.tsx`.
+
+## 3. Add routes
+
+Create TanStack routes whose paths match the feature nodes.
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { ProtectedRoute, FeatureGuard } from '@elevasis/ui/features/auth'
+
+export const Route = createFileRoute('/analytics')({
+  component: AnalyticsLayout
+})
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+## 4. Add backing resources
+
+For workflows or agents that power the feature, declare graph links on the resource metadata:
+
+```ts
+config: {
+  resourceId: 'analytics-refresh',
+  name: 'Analytics Refresh',
+  type: 'workflow',
+  version: '1.0.0',
+  status: 'prod',
+  links: [{ nodeId: 'feature:analytics', kind: 'operates-on' }],
+  category: 'production'
+}
+```
+
+## 5. Verify
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui test
+pnpm -C operations check
+```

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

@@ -1,158 +1,85 @@
----
-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 `core/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.
+---
+title: Add a Resource
+description: Add a workflow or agent with resource metadata, graph links, and deployment verification.
+---
+
+# Add a Resource
+
+Resources are workflows, agents, triggers, integrations, external systems, or human checkpoints collected in a `DeploymentSpec`. They link into the Organization Model graph through resource metadata, not through `OrganizationModel` mapping tables.
+
+## 1. Author the resource
+
+```ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resourceId: 'my-workflow',
+    name: 'My Workflow',
+    type: 'workflow',
+    version: '1.0.0',
+    status: 'dev',
+    links: [{ nodeId: 'feature:operations', kind: 'operates-on' }],
+    category: 'production'
+  },
+  contract: {
+    inputSchema,
+    outputSchema
+  },
+  steps: {
+    run: {
+      id: 'run',
+      name: 'Run',
+      handler: async (_input, context) => {
+        context.logger.info('[my-workflow] starting')
+        return { ok: true }
+      },
+      inputSchema,
+      outputSchema,
+      next: null
+    }
+  },
+  entryPoint: 'run'
+}
+```
+
+`links[].nodeId` uses the kind-prefixed graph grammar, such as `feature:sales.crm`, `integration:instantly`, or `capability:operations.queue.review`.
+
+`category` is one of `production`, `diagnostic`, `internal`, or `testing`.
+
+## 2. Register in the deployment spec
+
+```ts
+import { myWorkflow } from './my-workflow/index.js'
+
+export const org = {
+  version: '0.1.0',
+  workflows: [myWorkflow],
+  agents: []
+}
+```
+
+Use `.js` extensions in TypeScript source imports for ESM compatibility.
+
+## 3. Declare runtime relationships
+
+Use `DeploymentSpec.relationships` for execution topology:
+
+```ts
+relationships: {
+  'my-workflow': {
+    triggers: { workflows: ['email-notification'] },
+    uses: { integrations: ['hubspot'] }
+  }
+}
+```
+
+Use `config.links` for semantic graph binding and `relationships` for runtime execution relationships.
+
+## 4. Verify
+
+```bash
+pnpm -C operations check
+pnpm -C operations deploy
+pnpm exec elevasis describe Elevasis/my-workflow
+```