@elevasis/sdk 1.4.0 → 1.5.1

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

@@ -0,0 +1,163 @@
+---
+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`).
+
+---
+
+## 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: [
+    {
+      source: 'my-workflow',
+      target: 'email-notification',
+      type: 'triggers'
+    }
+  ],
+  humanCheckpoints: [
+    {
+      id: 'approval-gate',
+      label: 'Approve before sending',
+      routesTo: { resourceType: 'workflow', resourceId: 'my-workflow' }
+    }
+  ]
+}
+```
+
+Full relationship and checkpoint types are defined in `@elevasis/sdk` (`DeploymentSpec`). The generated `docs/resources.md` topology map will reflect these in the Topology Relationships, Triggers, and Human Checkpoints sections after regeneration.
+
+---
+
+## 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: [
+  {
+    resourceId: 'my-workflow',
+    resourceType: 'workflow',
+    domainId: 'operations',
+    label: 'My Workflow'
+  }
+]
+```
+
+See `OrganizationModelResourceMapping` in [contracts.md](../reference/contracts.md) for the full shape.
+
+---
+
+## 5. Regenerate the topology map
+
+```bash
+pnpm generate-resources
+```
+
+Open `docs/resources.md` and confirm:
+
+- Section 1 (Workflows table) lists the new resource with correct `resourceId`, `version`, and `status`.
+- Section 2 (Topology Relationships) shows any declared `relationships` edges.
+- Sections 3-6 (Triggers, Integrations, Human Checkpoints, External Resources) show any relevant declarations.
+- Section 7 (Schema Signatures) includes the new resource's input/output field list.
+
+---
+
+## 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 frontend trigger pattern.

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -0,0 +1,152 @@
+---
+title: Gate by Feature or Admin
+description: Decision table and step-by-step recipes for gating routes, nav items, and UI elements by feature flag or admin role.
+---
+
+# Gate by Feature or Admin
+
+End-to-end: gate a route, nav item, or UI element. Steps are sequential.
+
+See [glossary.md](../reference/glossary.md) under **FeatureGuard**, **AdminGuard**, **accessFeatureKey**, **featureKey**, **Settings asymmetry**, and **MembershipFeatureConfig**. See [contracts.md](../reference/contracts.md) for `MembershipFeatureConfig` shape and the settings-asymmetry callout.
+
+For the three-concept model in full detail, see [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md).
+
+---
+
+## 1. Decide: feature-level or admin-level?
+
+| Scenario                                                                         | Gate to use                                                            |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Surface should be off by default for all members, toggled org-wide or per member | `FeatureGuard` + `featureKey` on nav entry                             |
+| Surface is always visible to authenticated members but restricted to admins only | `AdminGuard` + `requiresAdmin` on nav entry                            |
+| Surface is both feature-gated and admin-only                                     | Both: `FeatureGuard` wrapping `AdminGuard`, plus both nav-entry fields |
+
+Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminGuard` reads admin role. They are independent.
+
+---
+
+## 2. Feature gate -- org level
+
+Ensure the key exists in the org model. File: `foundations/config/organization-model.ts`.
+
+```ts
+// In defineOrganizationModel call:
+features: { enabled: { ..., analytics: false } }
+
+// In featuresEnabled resolver:
+analytics: resolvedOrganizationModel.features.enabled.analytics ?? false
+```
+
+If the key is template-local (not a platform `OrganizationModelFeatureKey`), add it to `FoundationLegacyFeatureKey` first. See [add-a-feature.md](add-a-feature.md) step 2.
+
+Toggle `analytics: true` to enable for all members by default.
+
+---
+
+## 3. Feature gate -- route level
+
+Wrap the route layout with `FeatureGuard` inside `ProtectedRoute`. The template-local `FeatureGuard` resolves key aliases automatically.
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`FeatureGuard` redirects to `/` with a Mantine notification when the feature is off. All child routes under this layout are automatically protected -- no need to repeat the guard in children.
+
+Import path: `@/features/auth/guards/FeatureGuard` (template-local). Do not import `FeatureGuard` from `@elevasis/ui/features` -- that version does not close over the local key aliases. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
+
+---
+
+## 4. Admin gate -- route level
+
+Wrap with `AdminGuard` inside `ProtectedRoute`. `AdminGuard` redirects non-admins to `redirectTo` (default `/`).
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { AdminGuard } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({ component: AdminLayout })
+
+function AdminLayout() {
+  return (
+    <ProtectedRoute>
+      <AdminGuard>
+        <Outlet />
+      </AdminGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Import path: `@elevasis/ui/auth` (published). Always nest inside `ProtectedRoute` -- the guard depends on the user profile being loaded.
+
+---
+
+## 5. Nav-item visibility
+
+Declare `featureKey` on the nav entry to have the shell auto-hide it when the feature is off. Declare `requiresAdmin: true` to hide it for non-admin members.
+
+```ts
+// In FeatureModule.navEntry (manifest-backed features):
+navEntry: {
+  label: 'Analytics',
+  icon: IconChartBar,
+  link: '/analytics',
+  featureKey: 'analytics'   // optional -- accessFeatureKey already gates the whole module
+}
+
+// In nav-items.ts (app-local nav):
+{ label: 'Analytics', icon: IconChartBar, link: '/analytics', featureKey: 'analytics' }
+{ label: 'Admin',     icon: IconShield,   link: '/admin',     requiresAdmin: true }
+```
+
+`featureKey` on a nav entry is a display hint only -- it does not protect the route. Always pair with a route-level `FeatureGuard`. See [glossary.md](../reference/glossary.md) under **accessFeatureKey vs featureKey** for the distinction.
+
+---
+
+## 6. Per-member override
+
+`MembershipFeatureConfig.features` (stored in `org_memberships.config`) overrides org-level defaults per member. Full shape is in [contracts.md](../reference/contracts.md#membershipfeatureconfig).
+
+```ts
+// Disable analytics for a specific member (stored in their membership record):
+{
+  features: { acquisition: false }
+}
+```
+
+**Settings asymmetry -- read this before writing membership config.** `OrganizationModelFeatureKey` has 7 keys; `MembershipFeatureConfig.features` has only 6. The `settings` key is intentionally absent from membership config: settings access is controlled by `requiresAdmin` and `AdminGuard`, not per-member feature flags. Writing a `settings` key to `org_memberships.config` has no effect. See [contracts.md](../reference/contracts.md#membershipfeatureconfig) for the full callout, and [glossary.md](../reference/glossary.md) under **Settings asymmetry**.
+
+Membership config is read/written directly via the Supabase client (`org_memberships.config` column). There is no dedicated API route for bulk updates.
+
+---
+
+## 7. Verify
+
+State matrix -- confirm each combination:
+
+| Org feature enabled | Member override | Admin     | Expected result                               |
+| ------------------- | --------------- | --------- | --------------------------------------------- |
+| true                | (absent)        | any       | Route accessible, nav visible                 |
+| true                | false           | any       | Route redirects, nav hidden                   |
+| false               | (absent)        | any       | Route redirects, nav hidden                   |
+| false               | true            | any       | Route redirects (org gate wins)               |
+| true                | (absent)        | non-admin | Admin-gated route redirects, admin nav hidden |
+| true                | (absent)        | admin     | Admin-gated route accessible, nav visible     |
+
+Check each gate independently: feature toggle in `foundations/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.

package/reference/scaffold/recipes/index.md

@@ -0,0 +1,32 @@
+---
+title: Pathway Recipes
+description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a feature, adding a resource, and gating access.
+---
+
+# Pathway Recipes
+
+Three sequential walkthroughs for common authoring tasks. Each recipe links into the reference docs rather than duplicating them.
+
+Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (Feature, Resource, accessFeatureKey, Settings asymmetry, Topology).
+
+---
+
+## Recipes
+
+**[Add a Feature](add-a-feature.md)**
+You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar, routes, and org-model gate. Covers org-model key declaration, `FeatureModule` manifest authoring, route creation, and gating.
+
+**[Add a Resource](add-a-resource.md)**
+You want a new workflow or agent deployed to the platform. Covers `WorkflowDefinition` authoring, `DeploymentSpec` registration, relationship declarations, domain mapping, and CLI verification.
+
+**[Gate by Feature or Admin](gate-by-feature-or-admin.md)**
+You want to restrict a route, nav item, or UI element by feature flag or admin role. Covers the decision table, `FeatureGuard`, `AdminGuard`, nav-entry visibility fields, per-member `MembershipFeatureConfig` overrides, and the settings-asymmetry gotcha.
+
+---
+
+## Reference docs these recipes link into
+
+- [glossary.md](../reference/glossary.md) -- term disambiguation for Feature, Resource, accessFeatureKey, Topology, Settings asymmetry
+- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `FeatureModule`, `FeatureNavEntry`, `OrganizationModel`, `MembershipFeatureConfig`
+- [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
+- [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns