@elevasis/sdk 1.8.2 → 1.8.3

package/reference/scaffold/index.mdx

@@ -1,64 +1,64 @@
----
-title: Scaffold Reference
-description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
----
-
-## Overview
-
-This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
-
-- **recipes/** -- Cross-package pathway recipes (add a feature, add a resource, gating patterns)
-- **ui/** -- UI patterns, feature shell architecture, composition, and customization
-- **core/** -- Organization model architecture, graph layer, and semantic contracts
-- **operations/** -- Workflow authoring patterns and adapter usage
-- **reference/** -- Glossary, auto-generated contracts, and feature registry
-
-## Quick Navigation
-
-### Pathway Recipes
-
-- [Add a Feature](./recipes/add-a-feature.md) -- end-to-end from org model key through manifest, routes, gating
-- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
-- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
-- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
-
-### UI Patterns
-
-- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
-- [Feature Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for feature access
-- [Customizing Features](./ui/customization.md) -- sidebar composition via manifest overrides
-- [Feature Shell & Provider](./ui/feature-shell.mdx) -- FeatureModule manifest contract, provider runtime
-- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
-
-### Core Architecture
-
-- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
-- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
-
-### Operations
-
-- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
-- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
-- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
-
-### Reference
-
-- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
-- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
-- [Feature Registry](./reference/feature-registry.md) -- auto-generated feature manifest catalog
-
-## Source Locations
-
-Content is co-located with its owning package and copied here during SDK build:
-
-| Bundle Path                                   | Source Location                                           | Owner           |
-| --------------------------------------------- | --------------------------------------------------------- | --------------- |
-| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
-| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
-| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
-| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
-| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
-| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |
+---
+title: Scaffold Reference
+description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
+---
+
+## Overview
+
+This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
+
+- **recipes/** -- Cross-package pathway recipes (add a feature, add a resource, gating patterns)
+- **ui/** -- UI patterns, feature shell architecture, composition, and customization
+- **core/** -- Organization model architecture, graph layer, and semantic contracts
+- **operations/** -- Workflow authoring patterns and adapter usage
+- **reference/** -- Glossary, auto-generated contracts, and feature registry
+
+## Quick Navigation
+
+### Pathway Recipes
+
+- [Add a Feature](./recipes/add-a-feature.md) -- end-to-end from org model key through manifest, routes, gating
+- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
+- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
+- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
+
+### UI Patterns
+
+- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
+- [Feature Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for feature access
+- [Customizing Features](./ui/customization.md) -- sidebar composition via manifest overrides
+- [Feature Shell & Provider](./ui/feature-shell.mdx) -- FeatureModule manifest contract, provider runtime
+- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
+
+### Core Architecture
+
+- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
+- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
+
+### Operations
+
+- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
+- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
+- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
+
+### Reference
+
+- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
+- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
+- [Feature Registry](./reference/feature-registry.md) -- auto-generated feature manifest catalog
+
+## Source Locations
+
+Content is co-located with its owning package and copied here during SDK build:
+
+| Bundle Path                                   | Source Location                                           | Owner           |
+| --------------------------------------------- | --------------------------------------------------------- | --------------- |
+| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
+| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
+| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
+| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
+| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
+| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |

package/reference/scaffold/operations/propagation-pipeline.md

@@ -1,132 +1,153 @@
----
-title: Propagation Pipeline
-description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, template sync, and verification.
----
-
-# Propagation Pipeline
-
-`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
-
----
-
-## Architecture
-
+---
+title: Propagation Pipeline
+description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
+---
+
+# Propagation Pipeline
+
+`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
+
+---
+
+## Architecture
+
 The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
 
 ```
 Layer 1: Source Generation (pnpm scaffold:sync)
    Regenerates derived docs from TypeScript types and manifests
         ↓
-Layer 2: Template Sync (/external sync)
-   Propagates template to downstream external projects
+Layer 2: Registry-Driven Sync Planning + Apply (/external sync)
+   Plans registry-backed writes/deletes, then applies the approved scope
         ↓
 Layer 3: Sync Verification (pnpm sync:verify)
-   Asserts correctness across all template-derived projects
+   Asserts correctness across all template-derived projects after apply
 ```
+
+---
+
+## Layer 1: Source Generation
+
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
+
+| Script                                  | Input                                                                                                                                         | Output                                                              |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
+| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/*/manifest.ts`, `packages/core/src/organization-model/domains/features.ts`                                          | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
+| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
+
+After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
+
+### Trigger Points
+
+- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
+- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
+- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
+- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
+
+### Design: Regenerate-on-Propagation
+
+Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
+
+---
+
+## Layer 2: Registry-Driven Sync Planning + Apply
+
+`/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
+The canonical ownership vocabulary is:
+
+| Category        | Strategy examples                               | Meaning                                                                 |
+| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `replace`       | `replace-all`                                   | Template-managed surface; copy from template baseline                   |
+| `merge`         | `merge-baseline`, `merge-regions`               | Merge-aware surface; preserve project customizations where required     |
+| `never-touch`   | `verify-only`                                   | Project-owned surface; planner may report drift but never writes        |
+| `generated`     | `generated-freshness`                           | Generated surface; verify/regen instead of copying                      |
+
+Current command helpers:
 
----
-
-## Layer 1: Source Generation
-
-`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
-
-| Script                                  | Input                                                                                                                                         | Output                                                              |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
-| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/*/manifest.ts`, `packages/core/src/organization-model/domains/features.ts`                                          | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
-| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
-
-After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
-
-### Trigger Points
-
-- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
-- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
-- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
-- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
-
-### Design: Regenerate-on-Propagation
-
-Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
-
----
-
-## Layer 2: Template Sync
-
-`/external sync` propagates the `external/_template` to downstream projects. It uses a three-tier model:
-
-| Tier                           | Policy                                    | Examples                                                              |
-| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------- |
-| **Tier 1 (Infrastructure)**    | Always replaced from template             | Configs, shared runtime surfaces, `lib/`, `test-utils/`, entry points |
-| **Tier 2 (Standard Features)** | Synced unless project has customized them | Standard UI features, common patterns                                 |
-| **Tier 3 (Project-Specific)**  | Never touched                             | `nav-items.ts`, `operations/src/`, `docs/`, `CLAUDE.md`               |
+```bash
+pnpm sync:plan -- --all                  # registry-backed dry-run plan
+pnpm sync:apply -- --all                 # registry-backed apply pass
+pnpm sync:verify                         # post-apply verification
+```
 
-The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier model and phase sequence.
+Per-project or scoped runs pass the project name and optional `--path` / `--source` filters through to the planner/apply script.
 
----
+Delete behavior is explicit:
 
-## Layer 3: Sync Verification
+- managed deletes apply only to `replace` surfaces
+- deletion is allowed only when the path appears in the manifest-backed tombstone list
+- absence from the template alone is not enough to delete a downstream file
 
-`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
+Generated surfaces are also explicit:
 
-### Per-Project Checks (auto-discovered)
+- they are planned as `generated`
+- apply does not copy them as normal source files
+- the relevant regen command must run, then `pnpm sync:verify` checks freshness
 
+The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow authority, but it should be read as planner/apply/verify orchestration over the registry model above.
+
+---
+
+## Layer 3: Sync Verification
+
+`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
+
+### Per-Project Checks (auto-discovered)
+
 | Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
-| `tier1`        | 9 config files match template (with placeholder resolution for project slug/name)                                                                                                                                                                                                                                                                           |
+| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
 | `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `defineOrganizationModel` + `resolveOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `ElevasisUIProvider`, all 3 CSS subpath imports present |
 | `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
 | `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
 | `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |
-| `tier3`        | `nav-items.ts` has project-specific customization (not overwritten by template)                                                                                                                                                                                                                                                                             |
+| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                  |
 | `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
 | `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
 | `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
-
-### Monorepo-Level Checks
-
-| Category    | What It Checks                                  |
-| ----------- | ----------------------------------------------- |
-| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
-| `artifacts` | 5 generated artifacts exist and have content    |
-
-### Usage
-
-```bash
-pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
-pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
-pnpm sync:verify -- ZentaraHQ  # Single project
-```
-
+
+### Monorepo-Level Checks
+
+| Category    | What It Checks                                  |
+| ----------- | ----------------------------------------------- |
+| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
+| `artifacts` | 5 generated artifacts exist and have content    |
+
+### Usage
+
+```bash
+pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
+pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
+pnpm sync:verify -- ZentaraHQ  # Single project
+```
+
 ### Integration Points
 
-- **`/external sync` Phase 0:** Runs `pnpm sync:verify --pre` to show drift before writes
-- **`/external sync` Phase 5/7:** Runs `pnpm sync:verify` to assert correctness after sync
-- **Vitest suite:** Tests at `scripts/external/__tests__/verify-sync.test.js` (project: `scripts-external`)
-
-### Known Acceptable Drifts
-
-Some failures are expected and intentional:
-
-- **`style.css` in nirvana-marketing:** Project-specific sidebar logo rounding customization
-- **`.gitignore` in ZentaraHQ:** Minor project-specific additions
-- **SDK patch versions:** Template may bump to a patch ahead of downstream projects between syncs
-
-These do not indicate sync failures.
-
-### Tier Ownership Note
-
-Local `.claude/` guidance remains valuable inside the template, but it is project-owned documentation and agent configuration rather than a Tier 1 sync contract. Template propagation should treat the generated docs, published package surfaces, and runtime entrypoints as the authoritative shared scaffold surface.
-
----
-
-## Remaining Gaps (Future Work)
-
-| Gap                                                                       | Priority |
-| ------------------------------------------------------------------------- | -------- |
-| Feature manifest validation (all manifests imported in `__root.tsx`)      | Medium   |
-| TypeScript verification (`check-types` per project)                       | Medium   |
-| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
-| Environment variable template validation (`.env.example` completeness)    | Low      |
-| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |
+- **`/external sync` preflight:** Runs `pnpm sync:verify --pre` before planning so current drift is visible before any writes
+- **`/external sync` planner/apply:** `pnpm sync:plan` previews registry-backed writes/deletes, then `pnpm sync:apply` executes the approved plan
+- **`/external sync` post-apply:** Runs `pnpm sync:verify` to assert correctness after the planner/apply pass
+- **Automated coverage:** tests live under `scripts/external/__tests__/` including planner/apply coverage
+
+### Planner Interpretation Note
+
+`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
+
+- `.claude/commands/**`, `hooks/**`, `rules/**`, `scripts/**`, `skills/**`, and `.claude/settings.json` are managed `replace` surfaces
+- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
+- generated surfaces are verified for freshness, not copied
+
+Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
+
+---
+
+## Remaining Gaps (Future Work)
+
+| Gap                                                                       | Priority |
+| ------------------------------------------------------------------------- | -------- |
+| Feature manifest validation (all manifests imported in `__root.tsx`)      | Medium   |
+| TypeScript verification (`check-types` per project)                       | Medium   |
+| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
+| Environment variable template validation (`.env.example` completeness)    | Low      |
+| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |