@elevasis/sdk 1.7.0 → 1.8.1

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

@@ -30,11 +30,11 @@ Layer 3: Sync Verification (pnpm sync:verify)
 
 `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`, `external/_template/docs/platform-navigation-map.md` |
+| 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.
 
@@ -55,11 +55,11 @@ Drift is healed at the moment it would otherwise leak downstream. This is cheape
 
 `/external sync` propagates the `external/_template` to downstream projects. It uses a three-tier model:
 
-| Tier                           | Policy                                    | Examples                                                            |
-| ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
+| 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`             |
+| **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`               |
 
 The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier model and phase sequence.
 
@@ -78,8 +78,7 @@ The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier mo
 | `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                                                                                                                                                                                                                                                                                              |
-| `generated-docs` | `docs/index.md` and `docs/resources.md` are current with `pnpm exec elevasis-sdk generate-docs` and `pnpm exec elevasis-sdk generate-resources`; `pnpm exec elevasis-sdk validate-docs` passes                                                                                                                                                                                                            |
-| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                      |
+| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |
 | `tier3`        | `nav-items.ts` has project-specific customization (not overwritten by template)                                                                                                                                                                                                                                                                             |
 | `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
 | `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |

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

@@ -71,7 +71,6 @@ 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
-- `external/_template/docs/platform-navigation-map.md` -- cross-package reference map for external projects
 
 ### Running Generators
 
@@ -120,6 +119,4 @@ The output lands in `packages/sdk/reference/` which is included in the npm packa
 
 ## Freshness Validation
 
-External projects validate generated docs with `pnpm check:autogenerated-docs`, which now calls `pnpm exec elevasis-sdk validate-docs`. The legacy `scripts/validate-autogenerated-docs.mjs` file may still exist as a temporary compatibility shim in the template, but the SDK CLI is the canonical path.
-
-At the monorepo level, `pnpm scaffold:sync` followed by `pnpm sync:verify` confirms that all artifacts are current and all downstream projects are consistent.
+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.

package/reference/scaffold/recipes/add-a-resource.md

@@ -109,7 +109,7 @@ const org: DeploymentSpec = {
 }
 ```
 
-Full relationship and checkpoint types are defined in `@elevasis/sdk` (`DeploymentSpec`). The generated `docs/resources.md` topology map will reflect these in the Topology Relationships, Triggers, and Human Checkpoints sections after regeneration.
+Full relationship and checkpoint types are defined in `@elevasis/sdk` (`DeploymentSpec`). Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly.
 
 ---
 
@@ -133,18 +133,9 @@ See `OrganizationModelResourceMapping` in [contracts.md](../reference/contracts.
 
 ---
 
-## 5. Regenerate the topology map
+## 5. Verify resource inventory
 
-```bash
-pnpm exec elevasis-sdk generate-resources
-```
-
-Open `docs/resources.md` and confirm:
-
-- Section 1 (Workflows table) lists the new resource with correct `resourceId`, `version`, and `status`.
-- Section 2 (Topology Relationships) shows any declared `relationships` edges.
-- Sections 3-6 (Triggers, Integrations, Human Checkpoints, External Resources) show any relevant declarations.
-- Section 7 (Schema Signatures) includes the new resource's input/output field list.
+Resources are discovered live via `pnpm elevasis-sdk project:list` or by globbing `operations/resources/**` directly. Confirm the new resource appears with the correct `resourceId`, `version`, and `status`.
 
 ---
 

package/reference/scaffold/reference/contracts.md

@@ -1,4 +1,4 @@
-<!-- Auto-generated on 2026-04-20T23:27:16.482Z by scripts/monorepo/generate-scaffold-contracts.js -->
+<!-- Auto-generated on 2026-04-21T08:23:05.375Z by scripts/monorepo/generate-scaffold-contracts.js -->
 ---
 title: Reference Contracts
 description: Auto-generated TypeScript contracts for SDK consumers. Do not edit manually.

package/reference/claude-config/hooks/__tests__/pre-edit-vibe-gate.test.mjs

@@ -1,169 +0,0 @@
-#!/usr/bin/env node
-// pre-edit-vibe-gate.test.mjs
-// Tests for the pre-edit-vibe-gate hook.
-// Run with: node --test .claude/hooks/__tests__/pre-edit-vibe-gate.test.mjs
-//
-// Tests the exported `isProtectedPath` helper directly (pure logic, no stdin/stdout
-// mocking needed). Integration cases simulate the full hook by spawning it as a
-// child process.
-
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { spawnSync } from 'node:child_process'
-import { resolve, dirname } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const HOOK_PATH = resolve(__dirname, '..', 'pre-edit-vibe-gate.mjs')
-
-// Import the exported helper for unit-level tests.
-// Using a dynamic import so the module's top-level await (stdin read) doesn't
-// execute — the hook guards that behind the stdin loop which only runs when
-// there is actual input; unit tests call the exported function directly.
-// On Windows, absolute paths must be converted to file:// URLs for ESM imports.
-const { isProtectedPath } = await import(pathToFileURL(HOOK_PATH).href)
-
-// Template root = 3 levels up from __tests__/
-const TEMPLATE_ROOT = resolve(__dirname, '..', '..', '..')
-
-// ---------------------------------------------------------------------------
-// Helper: run the hook as a subprocess with a synthetic PreToolUse event.
-// filePath may be relative (to template root) or already absolute.
-// ---------------------------------------------------------------------------
-function runHook(toolName, filePath, env = {}) {
-  // Claude always sends absolute paths to hooks. Resolve relative paths
-  // against the template root so toRelative() inside the hook works correctly.
-  const absFilePath =
-    filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath) ? filePath : resolve(TEMPLATE_ROOT, filePath)
-
-  const event = JSON.stringify({
-    tool_name: toolName,
-    tool_input: { file_path: absFilePath }
-  })
-
-  return spawnSync(process.execPath, [HOOK_PATH], {
-    input: event,
-    encoding: 'utf-8',
-    env: {
-      ...process.env,
-      // Override AFTER spreading so this always wins over any ambient value
-      CLAUDE_PROJECT_DIR: TEMPLATE_ROOT,
-      ...env
-    },
-    timeout: 5000
-  })
-}
-
-// ---------------------------------------------------------------------------
-// Unit tests — isProtectedPath (pure function, no process spawning)
-// ---------------------------------------------------------------------------
-
-describe('isProtectedPath — exact protected files', () => {
-  it('blocks organization-model.ts', () => {
-    assert.equal(isProtectedPath('foundations/config/organization-model.ts'), true)
-  })
-
-  it('blocks organization-model.examples.ts', () => {
-    assert.equal(isProtectedPath('foundations/config/organization-model.examples.ts'), true)
-  })
-
-  it('blocks organization-model.override.ts', () => {
-    assert.equal(isProtectedPath('foundations/config/organization-model.override.ts'), true)
-  })
-})
-
-describe('isProtectedPath — extensions glob', () => {
-  it('blocks a .ts file directly under extensions/', () => {
-    assert.equal(isProtectedPath('foundations/config/extensions/deal-ecom.ts'), true)
-  })
-
-  it('blocks a .ts file in a subdirectory under extensions/', () => {
-    assert.equal(isProtectedPath('foundations/config/extensions/crm/deal-ecom.ts'), true)
-  })
-
-  it('blocks the discriminated-union index.ts under extensions/', () => {
-    assert.equal(isProtectedPath('foundations/config/extensions/index.ts'), true)
-  })
-
-  it('does NOT block a non-.ts file under extensions/', () => {
-    assert.equal(isProtectedPath('foundations/config/extensions/README.md'), false)
-  })
-})
-
-describe('isProtectedPath — unrelated paths always pass', () => {
-  it('allows ui/ files', () => {
-    assert.equal(isProtectedPath('ui/src/routes/__root.tsx'), false)
-  })
-
-  it('allows operations/ files', () => {
-    assert.equal(isProtectedPath('operations/src/index.ts'), false)
-  })
-
-  it('allows foundations/types (not config)', () => {
-    assert.equal(isProtectedPath('foundations/types/entities.ts'), false)
-  })
-
-  it('does NOT block a partial-match path that is not under foundations/config', () => {
-    // "organization-model.ts" without the full prefix should not be blocked
-    assert.equal(isProtectedPath('src/organization-model.ts'), false)
-  })
-})
-
-describe('isProtectedPath — partial path / edge cases', () => {
-  it('does not block foundations/config/ itself (no .ts suffix)', () => {
-    // The directory path should not be blocked
-    assert.equal(isProtectedPath('foundations/config/'), false)
-  })
-
-  it('strips leading ./ before matching', () => {
-    assert.equal(isProtectedPath('./foundations/config/organization-model.ts'), true)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Integration tests — spawn the hook with synthetic events
-// ---------------------------------------------------------------------------
-
-describe('hook subprocess — blocked without VIBE_APPROVED', () => {
-  it('exits 2 for Write to organization-model.ts', () => {
-    const result = runHook('Write', 'foundations/config/organization-model.ts')
-    assert.equal(result.status, 2, `expected exit 2, got ${result.status}`)
-    assert.ok(result.stderr.includes('BLOCKED'), 'expected BLOCKED in stderr')
-  })
-
-  it('exits 2 for Edit to extensions/deal-ecom.ts', () => {
-    const result = runHook('Edit', 'foundations/config/extensions/deal-ecom.ts')
-    assert.equal(result.status, 2)
-    assert.ok(result.stderr.includes('BLOCKED'))
-  })
-
-  it('exits 2 for MultiEdit to organization-model.override.ts', () => {
-    const result = runHook('MultiEdit', 'foundations/config/organization-model.override.ts')
-    assert.equal(result.status, 2)
-    assert.ok(result.stderr.includes('BLOCKED'))
-  })
-})
-
-describe('hook subprocess — passes with VIBE_APPROVED=1', () => {
-  it('exits 0 for Write to organization-model.ts when VIBE_APPROVED=1', () => {
-    const result = runHook('Write', 'foundations/config/organization-model.ts', { VIBE_APPROVED: '1' })
-    assert.equal(result.status, 0, `expected exit 0, got ${result.status}`)
-  })
-
-  it('exits 0 for Edit to extensions/deal-ecom.ts when VIBE_APPROVED=1', () => {
-    const result = runHook('Edit', 'foundations/config/extensions/deal-ecom.ts', { VIBE_APPROVED: '1' })
-    assert.equal(result.status, 0)
-  })
-})
-
-describe('hook subprocess — unrelated path always passes', () => {
-  it('exits 0 for Write to ui/src/routes/__root.tsx without VIBE_APPROVED', () => {
-    const result = runHook('Write', 'ui/src/routes/__root.tsx')
-    assert.equal(result.status, 0)
-  })
-
-  it('exits 0 for Edit to operations/src/index.ts without VIBE_APPROVED', () => {
-    const result = runHook('Edit', 'operations/src/index.ts')
-    assert.equal(result.status, 0)
-  })
-})

package/reference/claude-config/hooks/pre-edit-vibe-gate.mjs

@@ -1,128 +0,0 @@
-#!/usr/bin/env node
-// pre-edit-vibe-gate.mjs
-// PreToolUse backstop — blocks raw writes to protected foundations/config paths
-// unless the VIBE_APPROVED=1 trust marker is present.
-//
-// Protected paths (relative to project root):
-//   foundations/config/organization-model.ts
-//   foundations/config/organization-model.examples.ts
-//   foundations/config/organization-model.override.ts
-//   foundations/config/extensions/**/*.ts
-//
-// To allow a write: set VIBE_APPROVED=1 in the environment before invoking the
-// agent, or run /configure which sets the marker automatically after user
-// confirmation.
-
-import { appendFileSync, mkdirSync } from 'node:fs'
-import { normalize, resolve, relative, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const ROOT = normalize(process.env.CLAUDE_PROJECT_DIR ?? process.cwd())
-const LOG_DIR = ROOT + sep + '.claude' + sep + 'logs'
-const LOG_FILE = LOG_DIR + sep + 'pre-edit-vibe-gate.log'
-
-function log(msg) {
-  try {
-    mkdirSync(LOG_DIR, { recursive: true })
-    appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`)
-  } catch {
-    // Never crash on log failure
-  }
-}
-
-/**
- * Normalise an incoming file path (may be absolute or project-relative) to a
- * forward-slash relative path from ROOT for consistent matching.
- */
-function toRelative(filePath) {
-  const abs = normalize(resolve(filePath))
-  // relative() returns OS-separator paths — normalise to forward slashes
-  return relative(ROOT, abs).replace(/\\/g, '/')
-}
-
-/**
- * Returns true if `rel` (forward-slash relative path from root) matches one of
- * the protected path patterns. No external deps — uses simple string checks.
- *
- * Protected patterns:
- *   foundations/config/organization-model.ts                (exact)
- *   foundations/config/organization-model.examples.ts       (exact)
- *   foundations/config/organization-model.override.ts       (exact)
- *   foundations/config/extensions/**\/*.ts                  (glob — any .ts under extensions/)
- */
-export function isProtectedPath(rel) {
-  // Normalise away any leading ./
-  const r = rel.replace(/^\.\//, '')
-
-  // Exact protected files
-  const EXACT = [
-    'foundations/config/organization-model.ts',
-    'foundations/config/organization-model.examples.ts',
-    'foundations/config/organization-model.override.ts'
-  ]
-  if (EXACT.includes(r)) return true
-
-  // Glob: foundations/config/extensions/**/*.ts
-  // Must start with the prefix, end with .ts, and have at least one path segment
-  // after the extensions/ directory.
-  const EXT_PREFIX = 'foundations/config/extensions/'
-  if (r.startsWith(EXT_PREFIX) && r.endsWith('.ts')) {
-    // Ensure there is at least one filename after the prefix (not just the dir itself)
-    const remainder = r.slice(EXT_PREFIX.length)
-    if (remainder.length > 3) return true // at least "x.ts"
-  }
-
-  return false
-}
-
-const BLOCK_MESSAGE =
-  'BLOCKED: This file is protected by the vibe gate.\n' +
-  'WHY: Direct edits to foundations/config/organization-model.ts and\n' +
-  '     foundations/config/extensions/*.ts bypass the ambient vibe ceremony\n' +
-  '     (confirm + /configure write + pnpm check-types).\n' +
-  'FIX: Run /configure to codify changes with proper ceremony (sets VIBE_APPROVED=1\n' +
-  '     automatically), or set VIBE_APPROVED=1 explicitly if you are a power user\n' +
-  '     who has already completed the ceremony manually.'
-
-// Only run the stdin-reading main loop when this file is the entry point,
-// not when it is imported as a module (e.g., by tests).
-const isMain =
-  process.argv[1] != null && normalize(fileURLToPath(import.meta.url)) === normalize(resolve(process.argv[1]))
-
-if (isMain) {
-  try {
-    const chunks = []
-    for await (const chunk of process.stdin) chunks.push(chunk)
-    const input = JSON.parse(Buffer.concat(chunks).toString())
-
-    const toolName = input.tool_name ?? ''
-    const filePath = input.tool_input?.file_path ?? ''
-
-    // Only gate Write, Edit, MultiEdit
-    if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-      log(`SKIP tool=${toolName} (not a write tool)`)
-      process.exit(0)
-    }
-
-    if (!filePath) {
-      log(`SKIP tool=${toolName} no file_path in input`)
-      process.exit(0)
-    }
-
-    const rel = toRelative(filePath)
-    const protected_ = isProtectedPath(rel)
-    const approved = process.env.VIBE_APPROVED === '1'
-    const decision = protected_ && !approved ? 'BLOCK' : 'ALLOW'
-
-    log(`tool=${toolName} path=${rel} protected=${protected_} VIBE_APPROVED=${approved} decision=${decision}`)
-
-    if (decision === 'BLOCK') {
-      process.stderr.write(BLOCK_MESSAGE)
-      process.exit(2)
-    }
-  } catch (err) {
-    log(`ERROR: ${err?.message ?? String(err)}`)
-  }
-
-  process.exit(0)
-}

package/reference/claude-config/rules/docs.md

@@ -1,26 +0,0 @@
----
-description: Documentation conventions -- structure, frontmatter, /save integration, auto-generated files
-paths:
-  - docs/**
----
-
-# Documentation
-
-## Safety Invariants
-
-- `docs/index.md` and `docs/resources.md` are auto-generated by the SDK CLI -- never edit manually
-- Regenerate: `pnpm exec elevasis-sdk generate-docs` / `pnpm exec elevasis-sdk generate-resources`
-- Validate: `pnpm exec elevasis-sdk validate-docs` (or `pnpm check:autogenerated-docs`)
-- Every `.md` file in `docs/` MUST have `title` and `description` frontmatter -- docs without it are skipped by the index generator
-- In-progress docs additionally require `status: planned | in-progress | complete`
-
-## Structure
-
-- All docs are Markdown (`.md`), not MDX -- external projects don't use Fumadocs
-- UI features → `docs/ui/`, platform features → `docs/operations/`, knowledge → `docs/knowledge/`
-- New subdirectories under `docs/` are automatically discovered by the index generator
-
-## Detailed Reference
-
-- `docs/index.md` -- auto-generated navigation hub (full doc map)
-- `docs/agent-start-here.md` -- canonical agent entrypoint and task-routing guidance