@elevasis/sdk 1.40.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.56.0",
+    "@repo/core": "0.57.0",
     "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },

package/reference/claude-config/sync-notes/2026-07-27-agent-strict-output-and-turn-drift.md

@@ -0,0 +1,73 @@
+# Agent iteration output is now actually enforced, and long turns stop being lost
+
+## Why this note exists
+
+Two changes land together. Both are platform-side and need no agent definition changes, but **both
+require a redeploy** to take effect, and one of them silently did nothing until now.
+
+**1. Structured output was not being enforced for your agents, and nothing said so.**
+
+The platform asks the model for agent iterations through a forced tool call. `strict: true` is what
+actually enforces the response shape — without it the schema is guidance, required fields are
+best-effort, and the model is free to return an object missing one. Measured across long sessions,
+about 20% of iteration calls came back with `reasoning` and no `nextActions`.
+
+Strict mode compiles the schema into a sampling grammar, and that grammar accepts only a subset of
+JSON Schema. The agent iteration schema asked for memory writes as a free-form map
+(`additionalProperties: true` with nothing declared), which has no strict equivalent — so the
+platform refused to send `strict` and fell back to the old unenforced behavior. Correct and safe,
+but **completely silent**: there was no way to tell an enforced call from an unenforced one.
+
+The schema now asks for memory writes as a list of `{ key, value }` pairs, which is inside the
+grammar, so the call goes out enforced. The shape lives in your deployed bundle, which is why a
+redeploy is required and why a platform deploy alone could not fix it.
+
+**2. Long agent turns were occasionally lost outright.**
+
+On long turns the model would begin a second tool invocation while still writing the first one's
+`reasoning` string. The grammar traps that markup inside the string, and the turn ends with either
+response markup embedded in `reasoning` or no user-facing message at all. Measured at roughly 10%
+of calls on a long turn.
+
+The iteration schema now emits `nextActions` before `reasoning`. Under grammar-constrained sampling
+the model fills keys in declaration order, so the reply is already committed by the time the drift
+can start. Measured over 70 calls per arm, this took the failure rate from 10% to 2.9%, and the one
+remaining case still delivered its message. Answer quality was measured, not assumed: replies got
+slightly longer and read the same or better.
+
+## Applies to
+
+- **Every agent**, and especially every `sessionCapable: true` agent, since the failures scale with
+  accumulated context and show up on long conversations rather than in a smoke test.
+- Agents on **Anthropic models**. OpenAI-model agents stay on the unenforced path for now; that is
+  a separate, deliberately deferred item.
+- Anything that reads a stored `reasoning` field — see the caveat below.
+
+## Required actions
+
+1. **Take the `@elevasis/core` and `@elevasis/sdk` baseline bumps** this train propagates, then
+   reinstall in `operations/` so the new worker bundle is present.
+2. **Redeploy your operations bundle.** Both changes live in the schema your deployed bundle emits.
+   An existing deployment keeps sending the old unenforced schema until it is redeployed:
+   `pnpm -C operations exec elevasis-sdk deploy --prod` (or your project's deploy command).
+3. **If you parse or display stored `reasoning`, re-check it.** Nothing about the field's type or
+   presence changed, but it is now generated after the reply rather than before, so its content
+   reads more like a summary of the answer than a lead-up to it.
+
+## Verification
+
+- Run a session long enough to accumulate real context — the failures do not reproduce on short
+  ones. Confirm no turn fails with `LLM output does not match responseSchema: missing required
+field 'reasoning'; missing required field 'nextActions'`. That error on a redeployed agent means the
+  bundle is stale.
+- Check the observability rows for an execution: a call that had to fall back to the unenforced path
+  now records `strictRefusalReasons` on its `ai_calls` entry. **Absence of that field is the healthy
+  state** — a redeployed agent should show none. If you see `["freeFormObject"]`, that agent is
+  still running a pre-update bundle.
+
+## Not handled by /git-sync
+
+- **The redeploy.** `/git-sync` commits and pushes the propagated dependency baseline. It does not
+  redeploy your operations bundle, and neither change is live until you do (action 2 above).
+- **Reading the new observability field.** Nothing is written retroactively; only executions that
+  run after the redeploy carry it.

package/reference/index.mdx

@@ -63,4 +63,4 @@ See [@elevasis/ui](ui/index.mdx) for the provider model, feature modules, peer d
 
 ## Authoring Note
 
-These pages have a dual surface. At SDK build time, `packages/sdk/scripts/copy-reference-docs.mjs` copies every `apps/docs/content/docs/sdk/**.mdx` into `packages/sdk/reference/`, which ships inside the npm package (`files: ["reference/"]`). The `external/_template/CLAUDE.md` points tenant-project agents at `node_modules/@elevasis/sdk/reference/` as their primary reference bundle. Drift in these docs does not just affect the public site -- it actively misleads every agent building a tenant project.
+These pages have a dual surface. At SDK build time, `packages/sdk/scripts/copy-reference-docs.mjs` copies every `apps/docs/content/docs/sdk/**.mdx` into `packages/sdk/reference/`, which ships inside the npm package (`files: ["reference/"]`). The `external/_template/CLAUDE.md` points tenant-project agents at `operations/node_modules/@elevasis/sdk/reference/` as their primary reference bundle. Drift in these docs does not just affect the public site -- it actively misleads every agent building a tenant project.

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.