@elevasis/sdk 1.8.2 → 1.8.3

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

@@ -1,122 +1,122 @@
----
-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.
----
-
-# 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`             |
-| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
-| Feature 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`                |
-| Feature 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`   |
-| Feature 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 (4)         | `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, Feature System
-- `packages/ui/src/features/registry/types.ts` -- Feature Registry
-- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
-
-Output: `packages/core/src/reference/_generated/contracts.md`
-
-### Feature Registry (`feature-registry.md`)
-
-Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from feature manifests:
-
-- `packages/ui/src/features/*/manifest.ts` -- individual feature manifests
-- `packages/core/src/organization-model/domains/features.ts` -- feature key definitions
-
-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.
+---
+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.
+---
+
+# 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`             |
+| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
+| Feature 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`                |
+| Feature 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`   |
+| Feature 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 (4)         | `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, Feature System
+- `packages/ui/src/features/registry/types.ts` -- Feature Registry
+- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
+
+Output: `packages/core/src/reference/_generated/contracts.md`
+
+### Feature Registry (`feature-registry.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from feature manifests:
+
+- `packages/ui/src/features/*/manifest.ts` -- individual feature manifests
+- `packages/core/src/organization-model/domains/features.ts` -- feature key definitions
+
+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.