---
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`        |
| 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

Output: `packages/core/src/reference/_generated/contracts.md`

### System Interface Capabilities (`system-interface-capabilities.md`)

Generated by `scripts/monorepo/generate-scaffold-contracts.js` from:

- `packages/core/src/organization-model/domains/systems.ts` -- `SYSTEM_INTERFACE_PROFILES`
- `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)

`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has three phases:

1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map

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.
