@elevasis/sdk 1.39.0 → 1.41.0

package/reference/packages/core/src/business/README.md

@@ -1,52 +1,52 @@
-# Entities
-
-Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
-
-External projects extend these in `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
-
-## Published Exports
-
-The published entry point exposes six entity contracts:
-
-- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
-- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
-- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
-- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
-- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
-- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
-
-Import them from the published subpath:
-
-```ts
-import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
-```
-
-## Extension Pattern
-
-Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
-
-```ts
-import { z } from 'zod'
-import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
-
-const ProjectMetaSchema = z.object({
-  budget: z.number().int().nonnegative(),
-  clientPriority: z.enum(['low', 'medium', 'high'])
-})
-
-export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
-export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
-```
-
-Use the base shape as-is when no extension is needed:
-
-```ts
-export const DealSchema = BaseDealSchema
-export type Deal = BaseDeal
-```
-
-## Recipe
-
-The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
-
-The canonical template demo lives at `external/_template/core/types/entities.ts`.
+# Entities
+
+Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
+
+External projects extend these in `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+
+## Published Exports
+
+The published entry point exposes six entity contracts:
+
+- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
+- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
+- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
+- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
+- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
+- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
+
+Import them from the published subpath:
+
+```ts
+import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
+```
+
+## Extension Pattern
+
+Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
+
+```ts
+import { z } from 'zod'
+import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
+
+const ProjectMetaSchema = z.object({
+  budget: z.number().int().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
+```
+
+Use the base shape as-is when no extension is needed:
+
+```ts
+export const DealSchema = BaseDealSchema
+export type Deal = BaseDeal
+```
+
+## Recipe
+
+The full pattern is documented in the SDK scaffold bundle: `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
+
+The canonical template demo lives at `external/_template/core/types/entities.ts`.

package/reference/rules/frontend.md

@@ -12,7 +12,7 @@ paths:
 ## Safety Invariants
 
 - `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
-- `useApiClient()` from `@/lib/hooks/useApiClient` for authenticated API calls -- never raw `fetch` with auth headers
+- `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`
 - Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`

package/reference/rules/package-taxonomy.md

@@ -36,5 +36,5 @@ This project's own org-model and workflows live in `core/config/organization-mod
 
 ## References
 
-- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` — full SDK scaffold reference
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` — full SDK scaffold reference
 - Monorepo source rule: `.claude/rules/package-taxonomy.md` in the elevasis-monorepo (when working across both)

package/reference/rules/platform.md

@@ -39,7 +39,7 @@ paths:
 
 ## Detailed Reference
 
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- end-to-end resource authoring guide
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen UI, hooks, list/member state, artifacts, and workflow adapter extension guide
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- end-to-end resource authoring guide
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen UI, hooks, list/member state, artifacts, and workflow adapter extension guide
 - SDK reference docs: `operations/node_modules/@elevasis/sdk/reference/` (concepts, framework, platform-tools, runtime, CLI)

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

@@ -1,63 +1,63 @@
----
-title: Scaffold Maintenance
-description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
----
+---
+title: Scaffold Maintenance
+description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Scaffold Maintenance
-
-`🟢 Stable` -- Use this when adding or modifying scaffold documentation.
-
----
-
-## Content Placement Model
-
-Scaffold docs are co-located with their owning package and copied into the SDK reference at build time. This makes each package owner responsible for their docs and avoids a single monolithic directory.
-
-### Placement Rules
-
-- If a doc explains a single abstraction boundary, **co-locate it** with the owning package.
-- If a doc explains relationships between multiple abstractions, **centralize it** in `packages/sdk/docs/scaffold/`.
-- If a doc can be derived from code or manifests, **generate it**.
-- Hand-authored docs should point to generated maps rather than restating them.
-
-### Source-to-Destination Map
-
-| Content                     | Source                                                          | SDK Reference Destination                     |
-| --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
-| Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
-| Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
+
+# Scaffold Maintenance
+
+`🟢 Stable` -- Use this when adding or modifying scaffold documentation.
+
+---
+
+## Content Placement Model
+
+Scaffold docs are co-located with their owning package and copied into the SDK reference at build time. This makes each package owner responsible for their docs and avoids a single monolithic directory.
+
+### Placement Rules
+
+- If a doc explains a single abstraction boundary, **co-locate it** with the owning package.
+- If a doc explains relationships between multiple abstractions, **centralize it** in `packages/sdk/docs/scaffold/`.
+- If a doc can be derived from code or manifests, **generate it**.
+- Hand-authored docs should point to generated maps rather than restating them.
+
+### Source-to-Destination Map
+
+| Content                     | Source                                                          | SDK Reference Destination                     |
+| --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
+| Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
+| Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
 | Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
 | Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
 | System Interface Capabilities (auto-gen) | `packages/core/src/reference/_generated/system-interface-capabilities.md` | `scaffold/reference/system-interface-capabilities.md` |
 | UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
-| System Flags & Gating       | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
-| Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
-| System Shell                | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
-| Composition & Extensibility | `packages/ui/src/scaffold/composition-extensibility.mdx`        | `scaffold/ui/composition-extensibility.mdx`   |
-| System Registry (auto-gen)  | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
-| Scaffold Index              | `packages/sdk/docs/scaffold/index.mdx`                          | `scaffold/index.mdx`                          |
-| Pathway Recipes             | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
-| Workflow Recipes            | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`     | `scaffold/operations/workflow-recipes.md`     |
-| Propagation Pipeline        | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md` | `scaffold/operations/propagation-pipeline.md` |
-| This doc                    | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md` | `scaffold/operations/scaffold-maintenance.md` |
-
----
-
-## Auto-Generation Pipeline
-
-Two types of docs are auto-generated from source:
-
-### Contracts (`contracts.md`)
-
-Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript source types:
-
-- `packages/core/src/organization-model/types.ts` -- Organization Model, System Model
-- `packages/ui/src/features/registry/types.ts` -- System Registry
-- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
-
+| System Flags & Gating       | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
+| Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
+| System Shell                | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
+| Composition & Extensibility | `packages/ui/src/scaffold/composition-extensibility.mdx`        | `scaffold/ui/composition-extensibility.mdx`   |
+| System Registry (auto-gen)  | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
+| Scaffold Index              | `packages/sdk/docs/scaffold/index.mdx`                          | `scaffold/index.mdx`                          |
+| Pathway Recipes             | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
+| Workflow Recipes            | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`     | `scaffold/operations/workflow-recipes.md`     |
+| Propagation Pipeline        | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md` | `scaffold/operations/propagation-pipeline.md` |
+| This doc                    | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md` | `scaffold/operations/scaffold-maintenance.md` |
+
+---
+
+## Auto-Generation Pipeline
+
+Two types of docs are auto-generated from source:
+
+### Contracts (`contracts.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript source types:
+
+- `packages/core/src/organization-model/types.ts` -- Organization Model, System Model
+- `packages/ui/src/features/registry/types.ts` -- System Registry
+- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
+
 Output: `packages/core/src/reference/_generated/contracts.md`
 
 ### System Interface Capabilities (`system-interface-capabilities.md`)
@@ -68,37 +68,37 @@ Generated by `scripts/monorepo/generate-scaffold-contracts.js` from:
 - `packages/core/src/business/acquisition/ontology-validation.ts` -- derived-readiness validation constants and checks
 
 Output: `packages/core/src/reference/_generated/system-interface-capabilities.md`
-
-### System Registry (`feature-registry.md`)
-
-Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from system manifests:
-
-- `packages/ui/src/features/*/manifest.ts` -- individual system manifests
-- `packages/ui/src/features/registry/manifests.ts` -- `SYSTEM_MANIFESTS`
-
-Output: `packages/ui/src/scaffold/_generated/feature-registry.md`
-
-### Reference Artifacts
-
-Generated by `scripts/monorepo/generate-reference-artifacts.js`:
-
-- `packages/sdk/reference/_reference-manifest.json` -- machine-readable catalog of all reference entries
-- `packages/sdk/reference/_navigation.md` -- navigation table
-
-### Running Generators
-
-```bash
-pnpm scaffold:generate    # Run both generators
-pnpm scaffold:sync        # Generate + validate (the full loop)
-pnpm sdk-ref:generate     # Reference artifacts only
-```
-
-Generated files should never be edited manually. If the output is wrong, fix the source types or the generator script.
-
----
-
-## SDK Build Pipeline (Reference Copy)
-
+
+### System Registry (`feature-registry.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from system manifests:
+
+- `packages/ui/src/features/*/manifest.ts` -- individual system manifests
+- `packages/ui/src/features/registry/manifests.ts` -- `SYSTEM_MANIFESTS`
+
+Output: `packages/ui/src/scaffold/_generated/feature-registry.md`
+
+### Reference Artifacts
+
+Generated by `scripts/monorepo/generate-reference-artifacts.js`:
+
+- `packages/sdk/reference/_reference-manifest.json` -- machine-readable catalog of all reference entries
+- `packages/sdk/reference/_navigation.md` -- navigation table
+
+### Running Generators
+
+```bash
+pnpm scaffold:generate    # Run both generators
+pnpm scaffold:sync        # Generate + validate (the full loop)
+pnpm sdk-ref:generate     # Reference artifacts only
+```
+
+Generated files should never be edited manually. If the output is wrong, fix the source types or the generator script.
+
+---
+
+## SDK Build Pipeline (Reference Copy)
+
 `packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has four phases:
 
 1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
@@ -106,31 +106,31 @@ Generated files should never be edited manually. If the output is wrong, fix the
 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
 
-The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `node_modules/@elevasis/sdk/reference/`.
-
----
-
-## Adding New Scaffold Docs
-
-1. **Create the source doc** in the appropriate package:
-   - Core concepts: `packages/core/src/...`
-   - UI patterns: `packages/ui/src/scaffold/...`
-   - Cross-package or SDK-owned: `packages/sdk/docs/scaffold/...`
-
-2. **Add to `SCAFFOLD_COPIES`** in `packages/sdk/scripts/copy-reference-docs.mjs`:
-
-   ```javascript
-   { source: 'packages/sdk/docs/scaffold/operations/my-doc.md', target: 'scaffold/operations/my-doc.md' }
-   ```
-
-3. **Update the scaffold index** in `packages/sdk/docs/scaffold/index.mdx` with a link and description.
-
-4. **Rebuild the SDK** to verify: `pnpm --filter @elevasis/sdk build`
-
-5. **Update the permanent architecture docs** if the new doc covers a concept already referenced in `apps/docs/content/docs/technical/architecture/scaffold-reference.mdx`.
-
----
-
-## Freshness Validation
-
-At the monorepo level, `pnpm scaffold:sync` followed by `pnpm sync:verify` confirms that all artifacts are current and all downstream projects are consistent. The SDK no longer ships doc validation because external projects no longer carry a `docs/` tree.
+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/`.
+
+---
+
+## Adding New Scaffold Docs
+
+1. **Create the source doc** in the appropriate package:
+   - Core concepts: `packages/core/src/...`
+   - UI patterns: `packages/ui/src/scaffold/...`
+   - Cross-package or SDK-owned: `packages/sdk/docs/scaffold/...`
+
+2. **Add to `SCAFFOLD_COPIES`** in `packages/sdk/scripts/copy-reference-docs.mjs`:
+
+   ```javascript
+   { source: 'packages/sdk/docs/scaffold/operations/my-doc.md', target: 'scaffold/operations/my-doc.md' }
+   ```
+
+3. **Update the scaffold index** in `packages/sdk/docs/scaffold/index.mdx` with a link and description.
+
+4. **Rebuild the SDK** to verify: `pnpm --filter @elevasis/sdk build`
+
+5. **Update the permanent architecture docs** if the new doc covers a concept already referenced in `apps/docs/content/docs/technical/architecture/scaffold-reference.mdx`.
+
+---
+
+## Freshness Validation
+
+At the monorepo level, `pnpm scaffold:sync` followed by `pnpm sync:verify` confirms that all artifacts are current and all downstream projects are consistent. The SDK no longer ships doc validation because external projects no longer carry a `docs/` tree.