@elevasis/sdk 1.20.2 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.20.2",
+  "version": "1.22.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -57,9 +57,9 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.22.0",
+    "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/core": "0.24.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/_navigation.md

@@ -1,3 +1,5 @@
+<!-- @generated by scripts/monorepo/generate-reference-artifacts.js -- DO NOT EDIT -->
+
 # SDK Reference Navigation
 
 Auto-generated from the package reference manifests.
@@ -20,7 +22,7 @@ Package entries indexed: 55.
 
 | Resource | Location | Description | When to Load |
 | --- | --- | --- | --- |
-| Knowledge | `packages/core/src/knowledge/README.md` | Published knowledge query layer: byFeature/byKind/byOwner/governs/governedBy queries, parsePath, and output formatters. | (not specified) |
+| Knowledge | `packages/core/src/knowledge/README.md` | Published knowledge query layer: bySystem/byKind/byOwner/governs/governedBy queries, parsePath, and output formatters. | (not specified) |
 
 ## @elevasis/core / Organization Model
 
@@ -153,17 +155,17 @@ Universal scaffold documentation for all SDK projects. Source locations are co-l
 | Document | Bundle Path | Description |
 | --- | --- | --- |
 | Scaffold Index | `scaffold/index.mdx` | Discovery entry point and navigation map |
-| Add a Feature | `scaffold/recipes/add-a-feature.md` | End-to-end feature addition recipe |
+| Add a System | `scaffold/recipes/add-a-feature.md` | End-to-end system addition recipe |
 | Add a Resource | `scaffold/recipes/add-a-resource.md` | Workflow/agent authoring recipe |
-| Gate by Feature/Admin | `scaffold/recipes/gate-by-feature-or-admin.md` | Access control patterns |
+| Gate by System/Admin | `scaffold/recipes/gate-by-feature-or-admin.md` | Access control patterns |
 | UI Recipes | `scaffold/ui/recipes.md` | Copy-paste UI recipes |
-| Feature Flags & Gating | `scaffold/ui/feature-flags-and-gating.md` | Three-concept gating model |
-| Customizing Features | `scaffold/ui/customization.md` | Sidebar composition patterns |
-| Feature Shell | `scaffold/ui/feature-shell.mdx` | FeatureModule manifest and provider |
+| System Flags & Gating | `scaffold/ui/feature-flags-and-gating.md` | Three-concept gating model |
+| Customizing Systems | `scaffold/ui/customization.md` | Sidebar composition patterns |
+| System Shell | `scaffold/ui/feature-shell.mdx` | SystemModule manifest and provider |
 | Composition & Extensibility | `scaffold/ui/composition-extensibility.mdx` | Layout primitives and overrides |
 | Organization Model | `scaffold/core/organization-model.mdx` | Semantic contract and schema |
 | Organization Graph | `scaffold/core/organization-graph.mdx` | Graph derivation and Cytoscape |
 | Workflow Recipes | `scaffold/operations/workflow-recipes.md` | Workflow anatomy and adapters |
 | Glossary | `scaffold/reference/glossary.md` | Term definitions |
 | Contracts | `scaffold/reference/contracts.md` | Auto-generated type contracts |
-| Feature Registry | `scaffold/reference/feature-registry.md` | Auto-generated feature catalog |
+| System Registry | `scaffold/reference/feature-registry.md` | Auto-generated system catalog |

package/reference/_reference-manifest.json

@@ -35,7 +35,7 @@
       "subpath": "./knowledge",
       "kind": "subpath",
       "title": "Knowledge",
-      "description": "Published knowledge query layer: byFeature/byKind/byOwner/governs/governedBy queries, parsePath, and output formatters.",
+      "description": "Published knowledge query layer: bySystem/byKind/byOwner/governs/governedBy queries, parsePath, and output formatters.",
       "group": "Knowledge",
       "order": 1,
       "sourcePath": "packages/core/src/knowledge/index.ts",

package/reference/claude-config/hooks/post-edit-validate.mjs

@@ -1,98 +1,98 @@
-#!/usr/bin/env node
-// post-edit-validate.mjs
-// PostToolUse hook — auto-formats with prettier, type-checks .ts/.tsx files.
-// Fires after Edit|Write|MultiEdit succeeds.
-
-import { existsSync, readFileSync } from 'node:fs'
-import { resolve, normalize, extname, join, dirname, relative } from 'node:path'
-import { execSync } from 'node:child_process'
-
-const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-
-// Extensions prettier should format
-const PRETTIER_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.css', '.md'])
-
-// Extensions that trigger type-checking
-const TS_EXTENSIONS = new Set(['.ts', '.tsx'])
-
-function findNearestTsconfig(startDir) {
-  let dir = startDir
-  const root = normalize(ROOT)
-  while (dir.length >= root.length) {
-    const candidate = join(dir, 'tsconfig.json')
-    if (existsSync(candidate)) return candidate
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  return null
-}
-
-try {
-  const chunks = []
-  for await (const chunk of process.stdin) chunks.push(chunk)
-  const input = JSON.parse(Buffer.concat(chunks).toString())
-
-  const filePath = input.tool_input?.file_path
-  if (!filePath) process.exit(0)
-
-  const ext = extname(filePath).toLowerCase()
-  const absPath = normalize(resolve(filePath))
-  if (!existsSync(absPath)) process.exit(0)
-
-  const results = []
-
-  // 1. Prettier (skip silently if not installed yet, e.g. before first pnpm install)
-  if (PRETTIER_EXTENSIONS.has(ext)) {
-    try {
-      execSync('pnpm exec prettier --version', { cwd: ROOT, stdio: 'pipe', timeout: 5_000 })
-      try {
-        execSync('pnpm exec prettier --write "' + absPath + '"', {
-          cwd: ROOT,
-          stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 10_000
-        })
-      } catch (err) {
-        const stderr = err.stderr?.toString().trim() || ''
-        if (stderr && !/ignored/i.test(stderr)) {
-          results.push('Prettier error: ' + stderr.slice(0, 300))
-        }
-      }
-    } catch {
-      // prettier not installed yet -- skip silently
-    }
-  }
-
-  // 2. Type-check for .ts/.tsx
-  if (TS_EXTENSIONS.has(ext)) {
-    const tsconfig = findNearestTsconfig(dirname(absPath))
-    if (tsconfig) {
-      try {
-        execSync('pnpm exec tsc --noEmit -p "' + tsconfig + '"', {
-          cwd: ROOT,
-          stdio: ['pipe', 'pipe', 'pipe'],
-          timeout: 30_000,
-          env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=4096' }
-        })
-      } catch (err) {
-        if (err.killed) process.exit(0) // Don't block on timeout
-        const stdout = err.stdout?.toString() || ''
-        if (stdout.includes('error TS')) {
-          const errorLines = stdout
-            .split('\n')
-            .filter((l) => l.includes('error TS'))
-            .slice(0, 10)
-          results.push('Type errors after editing ' + filePath + ':\n' + errorLines.join('\n'))
-        }
-      }
-    }
-  }
-
-  // Output errors to Claude's context (silence = success)
-  if (results.length > 0) {
-    process.stderr.write(results.join('\n\n'))
-    process.exit(2) // Exit 2 = send stderr as feedback to Claude
-  }
-} catch {}
-
-process.exit(0)
+#!/usr/bin/env node
+// post-edit-validate.mjs
+// PostToolUse hook — auto-formats with prettier, type-checks .ts/.tsx files.
+// Fires after Edit|Write|MultiEdit succeeds.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, normalize, extname, join, dirname, relative } from 'node:path'
+import { execSync } from 'node:child_process'
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+
+// Extensions prettier should format
+const PRETTIER_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', '.css', '.md'])
+
+// Extensions that trigger type-checking
+const TS_EXTENSIONS = new Set(['.ts', '.tsx'])
+
+function findNearestTsconfig(startDir) {
+  let dir = startDir
+  const root = normalize(ROOT)
+  while (dir.length >= root.length) {
+    const candidate = join(dir, 'tsconfig.json')
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+try {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const input = JSON.parse(Buffer.concat(chunks).toString())
+
+  const filePath = input.tool_input?.file_path
+  if (!filePath) process.exit(0)
+
+  const ext = extname(filePath).toLowerCase()
+  const absPath = normalize(resolve(filePath))
+  if (!existsSync(absPath)) process.exit(0)
+
+  const results = []
+
+  // 1. Prettier (skip silently if not installed yet, e.g. before first pnpm install)
+  if (PRETTIER_EXTENSIONS.has(ext)) {
+    try {
+      execSync('pnpm exec prettier --version', { cwd: ROOT, stdio: 'pipe', timeout: 5_000 })
+      try {
+        execSync('pnpm exec prettier --write "' + absPath + '"', {
+          cwd: ROOT,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 10_000
+        })
+      } catch (err) {
+        const stderr = err.stderr?.toString().trim() || ''
+        if (stderr && !/ignored/i.test(stderr)) {
+          results.push('Prettier error: ' + stderr.slice(0, 300))
+        }
+      }
+    } catch {
+      // prettier not installed yet -- skip silently
+    }
+  }
+
+  // 2. Type-check for .ts/.tsx
+  if (TS_EXTENSIONS.has(ext)) {
+    const tsconfig = findNearestTsconfig(dirname(absPath))
+    if (tsconfig) {
+      try {
+        execSync('pnpm exec tsc --noEmit -p "' + tsconfig + '"', {
+          cwd: ROOT,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 30_000,
+          env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=4096' }
+        })
+      } catch (err) {
+        if (err.killed) process.exit(0) // Don't block on timeout
+        const stdout = err.stdout?.toString() || ''
+        if (stdout.includes('error TS')) {
+          const errorLines = stdout
+            .split('\n')
+            .filter((l) => l.includes('error TS'))
+            .slice(0, 10)
+          results.push('Type errors after editing ' + filePath + ':\n' + errorLines.join('\n'))
+        }
+      }
+    }
+  }
+
+  // Output errors to Claude's context (silence = success)
+  if (results.length > 0) {
+    process.stderr.write(results.join('\n\n'))
+    process.exit(2) // Exit 2 = send stderr as feedback to Claude
+  }
+} catch {}
+
+process.exit(0)

package/reference/claude-config/hooks/scaffold-registry-reminder.mjs

@@ -1,188 +1,188 @@
-#!/usr/bin/env node
-// scaffold-registry-reminder.mjs
-// PostToolUse hook — reads the compiled scaffold registry and emits advisory
-// reminders when an edited file matches a registry source pattern.
-//
-// Template twin of the monorepo hook. Gracefully no-ops when the compiled
-// registry is absent (e.g. before SDK delivers scaffold-registry.compiled.json
-// to external projects — Step 7/SDK milestone).
-//
-// Exit 0 always (advisory hook — never blocks).
-
-import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs'
-import { join, normalize, relative } from 'node:path'
-
-const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-const LOG_DIR = join(ROOT, '.claude', 'logs')
-const LOG_FILE = join(LOG_DIR, 'scaffold-registry-reminder.log')
-const STATE_FILE = join(LOG_DIR, 'scaffold-registry-reminder.state.json')
-const REGISTRY_FILE = join(ROOT, '.claude', 'scaffold-registry.compiled.json')
-
-const DEFAULT_COOLDOWN_MS = 300_000 // 5 minutes
-
-const GENERATED_DIR_SEGMENTS = ['_generated', '_gen']
-const GENERATED_CONTENT_MARKER = '@generated'
-
-function log(msg) {
-  try {
-    mkdirSync(LOG_DIR, { recursive: true })
-    appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`)
-  } catch {}
-}
-
-function pathMatchesPattern(filePath, pattern) {
-  const normalizedFile = filePath.replace(/\\/g, '/')
-  const normalizedPattern = pattern.replace(/\\/g, '/')
-
-  if (normalizedFile === normalizedPattern) return true
-
-  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
-    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
-    return normalizedFile.startsWith(prefix + '/')
-  }
-
-  if (normalizedPattern.includes('*')) {
-    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
-    return new RegExp(`^${escaped}$`).test(normalizedFile)
-  }
-
-  return normalizedFile.startsWith(normalizedPattern + '/')
-}
-
-function loadState() {
-  try {
-    return JSON.parse(readFileSync(STATE_FILE, 'utf-8'))
-  } catch {
-    return {}
-  }
-}
-
-function saveState(state) {
-  try {
-    mkdirSync(LOG_DIR, { recursive: true })
-    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + '\n', 'utf-8')
-  } catch {}
-}
-
-function throttleKey(entryId, filePath) {
-  return `${entryId}:${filePath}`
-}
-
-function isCoolingDown(state, key, cooldownMs) {
-  const last = state[key]
-  if (!last) return false
-  return Date.now() - last < cooldownMs
-}
-
-function formatDependentLine(dep) {
-  const regen = dep.regen === 'manual' ? 'manual check' : dep.regen
-  const hint = dep.hint ? ` [${dep.hint}]` : ''
-  return `    - ${dep.path} -> ${regen}${hint}`
-}
-
-function emitReminder(entry, relFilePath) {
-  const lines = [
-    `\uD83D\uDD14 Scaffold reminder -- ${entry.id} (${relFilePath})`,
-    `  Downstream scaffolds that may need updating:`
-  ]
-  for (const dep of entry.dependents) {
-    lines.push(formatDependentLine(dep))
-  }
-  lines.push(
-    `  If this is a scaffold-sensitive pattern not in the registry, also add an entry to .claude/scaffold-registry.yml.`
-  )
-  return lines.join('\n')
-}
-
-function emitMissingEntryHint(relFilePath) {
-  return [
-    `\uD83D\uDD14 Scaffold reminder -- unregistered generated path (${relFilePath})`,
-    `  This path looks scaffold-generated but has no registry entry.`,
-    `  If it is scaffold-sensitive, add a new entry to .claude/scaffold-registry.yml`,
-    `  so the reminder hook and /work handoff can track it.`
-  ].join('\n')
-}
-
-function looksLikeGeneratedPath(filePath) {
-  const normalizedFile = filePath.replace(/\\/g, '/')
-  const segments = normalizedFile.split('/')
-  return segments.some((seg) => GENERATED_DIR_SEGMENTS.includes(seg))
-}
-
-function looksLikeGeneratedContent(absFilePath) {
-  try {
-    const content = readFileSync(absFilePath, 'utf-8').slice(0, 500)
-    return content.includes(GENERATED_CONTENT_MARKER)
-  } catch {
-    return false
-  }
-}
-
-try {
-  const chunks = []
-  for await (const chunk of process.stdin) chunks.push(chunk)
-  const input = JSON.parse(Buffer.concat(chunks).toString())
-
-  const rawFilePath = input.tool_input?.file_path
-  if (!rawFilePath) process.exit(0)
-
-  const absFilePath = normalize(rawFilePath)
-  const relFilePath = relative(ROOT, absFilePath).replace(/\\/g, '/')
-
-  // Graceful no-op when registry is absent (pre-SDK-delivery state)
-  let registry
-  try {
-    const raw = readFileSync(REGISTRY_FILE, 'utf-8')
-    registry = JSON.parse(raw)
-  } catch {
-    log(`SKIP — registry not found (pre-SDK-delivery)`)
-    process.exit(0)
-  }
-
-  const entries = registry?.entries ?? []
-
-  const matched = entries.filter((entry) =>
-    (entry.sources ?? []).some((pattern) => pathMatchesPattern(relFilePath, pattern))
-  )
-
-  const state = loadState()
-  const now = Date.now()
-  const messages = []
-
-  if (matched.length > 0) {
-    for (const entry of matched) {
-      const key = throttleKey(entry.id, relFilePath)
-      const cooldown = entry.cooldown_ms ?? DEFAULT_COOLDOWN_MS
-      if (isCoolingDown(state, key, cooldown)) {
-        log(`THROTTLED — ${entry.id} for ${relFilePath}`)
-        continue
-      }
-      messages.push(emitReminder(entry, relFilePath))
-      state[key] = now
-      log(`EMITTED — ${entry.id} for ${relFilePath}`)
-    }
-  } else {
-    const isGenerated = looksLikeGeneratedPath(relFilePath) || looksLikeGeneratedContent(absFilePath)
-
-    if (isGenerated) {
-      const key = throttleKey('__missing__', relFilePath)
-      if (!isCoolingDown(state, key, DEFAULT_COOLDOWN_MS)) {
-        messages.push(emitMissingEntryHint(relFilePath))
-        state[key] = now
-        log(`EMITTED missing-entry hint for ${relFilePath}`)
-      } else {
-        log(`THROTTLED missing-entry hint for ${relFilePath}`)
-      }
-    }
-  }
-
-  if (messages.length > 0) {
-    saveState(state)
-    process.stderr.write(messages.join('\n\n') + '\n')
-    process.exit(2)
-  }
-} catch (err) {
-  log(`ERROR: ${err.message}`)
-}
-
-process.exit(0)
+#!/usr/bin/env node
+// scaffold-registry-reminder.mjs
+// PostToolUse hook — reads the compiled scaffold registry and emits advisory
+// reminders when an edited file matches a registry source pattern.
+//
+// Template twin of the monorepo hook. Gracefully no-ops when the compiled
+// registry is absent (e.g. before SDK delivers scaffold-registry.compiled.json
+// to external projects — Step 7/SDK milestone).
+//
+// Exit 0 always (advisory hook — never blocks).
+
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs'
+import { join, normalize, relative } from 'node:path'
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+const LOG_DIR = join(ROOT, '.claude', 'logs')
+const LOG_FILE = join(LOG_DIR, 'scaffold-registry-reminder.log')
+const STATE_FILE = join(LOG_DIR, 'scaffold-registry-reminder.state.json')
+const REGISTRY_FILE = join(ROOT, '.claude', 'scaffold-registry.compiled.json')
+
+const DEFAULT_COOLDOWN_MS = 300_000 // 5 minutes
+
+const GENERATED_DIR_SEGMENTS = ['_generated', '_gen']
+const GENERATED_CONTENT_MARKER = '@generated'
+
+function log(msg) {
+  try {
+    mkdirSync(LOG_DIR, { recursive: true })
+    appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`)
+  } catch {}
+}
+
+function pathMatchesPattern(filePath, pattern) {
+  const normalizedFile = filePath.replace(/\\/g, '/')
+  const normalizedPattern = pattern.replace(/\\/g, '/')
+
+  if (normalizedFile === normalizedPattern) return true
+
+  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
+    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
+    return normalizedFile.startsWith(prefix + '/')
+  }
+
+  if (normalizedPattern.includes('*')) {
+    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
+    return new RegExp(`^${escaped}$`).test(normalizedFile)
+  }
+
+  return normalizedFile.startsWith(normalizedPattern + '/')
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function saveState(state) {
+  try {
+    mkdirSync(LOG_DIR, { recursive: true })
+    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + '\n', 'utf-8')
+  } catch {}
+}
+
+function throttleKey(entryId, filePath) {
+  return `${entryId}:${filePath}`
+}
+
+function isCoolingDown(state, key, cooldownMs) {
+  const last = state[key]
+  if (!last) return false
+  return Date.now() - last < cooldownMs
+}
+
+function formatDependentLine(dep) {
+  const regen = dep.regen === 'manual' ? 'manual check' : dep.regen
+  const hint = dep.hint ? ` [${dep.hint}]` : ''
+  return `    - ${dep.path} -> ${regen}${hint}`
+}
+
+function emitReminder(entry, relFilePath) {
+  const lines = [
+    `\uD83D\uDD14 Scaffold reminder -- ${entry.id} (${relFilePath})`,
+    `  Downstream scaffolds that may need updating:`
+  ]
+  for (const dep of entry.dependents) {
+    lines.push(formatDependentLine(dep))
+  }
+  lines.push(
+    `  If this is a scaffold-sensitive pattern not in the registry, also add an entry to .claude/scaffold-registry.yml.`
+  )
+  return lines.join('\n')
+}
+
+function emitMissingEntryHint(relFilePath) {
+  return [
+    `\uD83D\uDD14 Scaffold reminder -- unregistered generated path (${relFilePath})`,
+    `  This path looks scaffold-generated but has no registry entry.`,
+    `  If it is scaffold-sensitive, add a new entry to .claude/scaffold-registry.yml`,
+    `  so the reminder hook and /work handoff can track it.`
+  ].join('\n')
+}
+
+function looksLikeGeneratedPath(filePath) {
+  const normalizedFile = filePath.replace(/\\/g, '/')
+  const segments = normalizedFile.split('/')
+  return segments.some((seg) => GENERATED_DIR_SEGMENTS.includes(seg))
+}
+
+function looksLikeGeneratedContent(absFilePath) {
+  try {
+    const content = readFileSync(absFilePath, 'utf-8').slice(0, 500)
+    return content.includes(GENERATED_CONTENT_MARKER)
+  } catch {
+    return false
+  }
+}
+
+try {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  const input = JSON.parse(Buffer.concat(chunks).toString())
+
+  const rawFilePath = input.tool_input?.file_path
+  if (!rawFilePath) process.exit(0)
+
+  const absFilePath = normalize(rawFilePath)
+  const relFilePath = relative(ROOT, absFilePath).replace(/\\/g, '/')
+
+  // Graceful no-op when registry is absent (pre-SDK-delivery state)
+  let registry
+  try {
+    const raw = readFileSync(REGISTRY_FILE, 'utf-8')
+    registry = JSON.parse(raw)
+  } catch {
+    log(`SKIP — registry not found (pre-SDK-delivery)`)
+    process.exit(0)
+  }
+
+  const entries = registry?.entries ?? []
+
+  const matched = entries.filter((entry) =>
+    (entry.sources ?? []).some((pattern) => pathMatchesPattern(relFilePath, pattern))
+  )
+
+  const state = loadState()
+  const now = Date.now()
+  const messages = []
+
+  if (matched.length > 0) {
+    for (const entry of matched) {
+      const key = throttleKey(entry.id, relFilePath)
+      const cooldown = entry.cooldown_ms ?? DEFAULT_COOLDOWN_MS
+      if (isCoolingDown(state, key, cooldown)) {
+        log(`THROTTLED — ${entry.id} for ${relFilePath}`)
+        continue
+      }
+      messages.push(emitReminder(entry, relFilePath))
+      state[key] = now
+      log(`EMITTED — ${entry.id} for ${relFilePath}`)
+    }
+  } else {
+    const isGenerated = looksLikeGeneratedPath(relFilePath) || looksLikeGeneratedContent(absFilePath)
+
+    if (isGenerated) {
+      const key = throttleKey('__missing__', relFilePath)
+      if (!isCoolingDown(state, key, DEFAULT_COOLDOWN_MS)) {
+        messages.push(emitMissingEntryHint(relFilePath))
+        state[key] = now
+        log(`EMITTED missing-entry hint for ${relFilePath}`)
+      } else {
+        log(`THROTTLED missing-entry hint for ${relFilePath}`)
+      }
+    }
+  }
+
+  if (messages.length > 0) {
+    saveState(state)
+    process.stderr.write(messages.join('\n\n') + '\n')
+    process.exit(2)
+  }
+} catch (err) {
+  log(`ERROR: ${err.message}`)
+}
+
+process.exit(0)