@gregiteen/ssss-cli 0.14.2 → 0.14.3

package/scripts/cmd-new.mjs

@@ -28,6 +28,7 @@ const HELP = usage({
   usage: 'ssss new <dir> [options]',
   options: [
     ['--name <s>', 'Package name (default: the target directory name).'],
+    ['--extension <s>', 'Scaffold a custom app extension registry under registry/extensions/<name>.json.'],
     ['--with-total-recall', 'Also wire the Total Recall memory OS (total-recall-brain).'],
     ['--install', 'Run `npm install` after scaffolding (and Total Recall init if requested).'],
     ['--no-git', 'Do not run `git init`.'],
@@ -36,6 +37,7 @@ const HELP = usage({
   ],
   examples: [
     'ssss new my-app',
+    'ssss new my-app --extension myapp',
     'ssss new my-app --with-total-recall --install',
   ],
   seeAlso: ['ssss help scaffold', 'ssss export', 'ssss conformance'],
@@ -65,6 +67,15 @@ export async function run(argv) {
   const name = flags.name || path.basename(root);
   const ref = flags.ref || `v${VERSION}`;
   const withTR = !!flags['with-total-recall'];
+  const extensionName = flags.extension === undefined ? null : String(flags.extension);
+  if (extensionName !== null) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(extensionName)) {
+      die(`--extension '${extensionName}' is not a valid registry name (lowercase letter first, then a-z, 0-9, _ or -; max 64).`);
+    }
+    if (extensionName === 'core' || extensionName === 'ssss') {
+      die(`--extension '${extensionName}' is reserved for the SSSS core registry.`);
+    }
+  }
 
   if (fs.existsSync(root) && fs.readdirSync(root).length && !flags.force) {
     die(`${root} is not empty. Use --force to scaffold anyway.`);
@@ -79,7 +90,9 @@ export async function run(argv) {
       ssss: 'ssss',
       test: 'node --test',
       export: 'ssss export vault --profile sale --out dist/bundle.ucw.json',
-      validate: 'ssss conformance --engine',
+      validate: extensionName
+        ? `ssss schema validate registry/extensions/${extensionName}.json && ssss conformance --engine`
+        : 'ssss conformance --engine',
     },
     dependencies: { '@gregiteen/ssss-cli': `github:gregiteen/ssss#${ref}` },
     ...(withTR ? { devDependencies: { 'total-recall-brain': 'latest' } } : {}),
@@ -96,14 +109,42 @@ export async function run(argv) {
   W(root, 'vault/tasks/first-task.md',
     '---\ntype: task\ntitle: First Task\ndescription: Starter private setup task that demonstrates tenant_private filtering.\ntimestamp: 2026-07-02T00:00:00Z\npriority: normal\ncategory: setup\nstatus: pending\n---\n\n# First task\n\nThis is `tenant_private` (§5.5) — it is **dropped** from `template`/`sale` exports.\n');
 
+  // ── optional app extension registry ─────────────────────────────────────
+  if (extensionName) {
+    const extRegistry = {
+      $schema: 'https://ssss.dev/schemas/core-registry.schema.json',
+      registry: extensionName,
+      extends: 'core',
+      version: '0.1.0',
+      description: `Custom SSSS primitive extensions for ${name}.`,
+      document_primitives: {
+        [`${extensionName}_item`]: {
+          family: 'content',
+          canonical_filename: null,
+          append_only: false,
+          portability: 'structural',
+          required_fields: ['type', 'name', 'title'],
+          optional_fields: ['description', 'status'],
+          enums: {
+            status: ['active', 'archived', 'draft'],
+          },
+          notes: `Custom primitive for ${name} application.`,
+        },
+      },
+    };
+    W(root, `registry/extensions/${extensionName}.json`, JSON.stringify(extRegistry, null, 2) + '\n');
+    W(root, `vault/${extensionName}_items/first-${extensionName}-item.md`,
+      `---\ntype: ${extensionName}_item\ntitle: Starter Item\ndescription: Starter ${extensionName} item.\ntimestamp: 2026-07-02T00:00:00Z\nname: Starter Item\nstatus: active\n---\n\n# Starter Item\n\nCustom primitive defined in \`registry/extensions/${extensionName}.json\`.\n`);
+  }
+
   // ── conformance test (zero-dependency: node --test) ─────────────────────
-  W(root, 'test/ssss-conformance.test.mjs', CONFORMANCE_TEST);
+  W(root, 'test/ssss-conformance.test.mjs', conformanceTest(extensionName));
 
   // ── repo meta ───────────────────────────────────────────────────────────
   W(root, '.gitignore', 'node_modules/\ndist/\n*.ucw.json\n.DS_Store\n');
-  W(root, 'README.md', readme(name, withTR));
-  W(root, 'CLAUDE.md', claudeMd(name, withTR));
-  W(root, 'docs/design.md', designMd(name));
+  W(root, 'README.md', readme(name, withTR, extensionName));
+  W(root, 'CLAUDE.md', claudeMd(name, withTR, extensionName));
+  W(root, 'docs/design.md', designMd(name, extensionName));
 
   // ── git + install (best-effort, flag-gated, no shell) ───────────────────
   const log = (m) => console.error(m);
@@ -145,7 +186,8 @@ export async function run(argv) {
   console.log('  npx ssss help                  # explore the standard');
 }
 
-const CONFORMANCE_TEST = `/**
+function conformanceTest(extensionName) {
+  return `/**
  * SSSS conformance — proves this repo's toolchain matches the published standard.
  * Zero test dependencies: run with \`node --test\` (Node 18+).
  */
@@ -161,7 +203,18 @@ import { exportBundle, validateBundle, provisionBundle, importBundle } from '@gr
 
 const require = createRequire(import.meta.url);
 const { fixtures } = require('@gregiteen/ssss-cli/conformance/fixtures.json');
-const VAULT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'vault');
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VAULT = path.join(ROOT, 'vault');
+${extensionName
+    ? `// App-specific primitives live in this repo's registry/extensions/; the core comes from the package.
+const REGISTRY = path.join(ROOT, 'registry');
+const EXTENSIONS = [${JSON.stringify(extensionName)}];
+const EXPORT_OPTIONS = { registryDir: REGISTRY, requiredExtensions: EXTENSIONS };
+const REGISTRY_OPTIONS = { registryDir: REGISTRY };
+const ENGINE_OPTIONS = { registryDir: REGISTRY, registryNames: EXTENSIONS };`
+    : `const EXPORT_OPTIONS = {};
+const REGISTRY_OPTIONS = {};
+const ENGINE_OPTIONS = {};`}
 
 test('engine implements the canonical Operation Contract (spec §6)', async () => {
   const vault = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-conf-'));
@@ -179,17 +232,17 @@ test('engine implements the canonical Operation Contract (spec §6)', async () =
 });
 
 test('this vault exports, validates, and round-trips as a sale bundle (spec §16/§17)', async () => {
-  const bundle = exportBundle(VAULT, { profile: 'sale', name: 'starter' });
-  const { valid, errors } = validateBundle(bundle);
+  const bundle = exportBundle(VAULT, { profile: 'sale', name: 'starter', ...EXPORT_OPTIONS });
+  const { valid, errors } = validateBundle(bundle, REGISTRY_OPTIONS);
   assert.ok(valid, 'bundle invalid: ' + errors.join('; '));
   assert.ok(!bundle.files.some((f) => f.path.startsWith('tasks/')), 'tenant_private leaked into sale export');
 
-  const plan = provisionBundle(bundle, { workspaceId: 'ws-test' });
-  assert.ok(plan.ok, 'provision failed: ' + JSON.stringify(plan.unresolved) + ' ' + JSON.stringify(plan.danglingLinks));
+  const plan = provisionBundle(bundle, { workspaceId: 'ws-test', ...REGISTRY_OPTIONS });
+  assert.ok(plan.ok, 'provision failed: ' + JSON.stringify(plan.errors) + ' ' + JSON.stringify(plan.unresolved) + ' ' + JSON.stringify(plan.danglingLinks));
 
   const target = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-import-'));
   try {
-    const engine = createEngine();
+    const engine = createEngine(ENGINE_OPTIONS);
     const r1 = await importBundle(plan.plan, target, engine);
     assert.ok(r1.ok && r1.committed === bundle.files.length, 'import did not commit every file');
     const r2 = await importBundle(plan.plan, target, engine);
@@ -197,8 +250,9 @@ test('this vault exports, validates, and round-trips as a sale bundle (spec §16
   } finally { fs.rmSync(target, { recursive: true, force: true }); }
 });
 `;
+}
 
-function readme(name, withTR) {
+function readme(name, withTR, extensionName) {
   return `# ${name}
 
 An [SSSS](https://github.com/gregiteen/ssss)-native project: a Markdown **vault** is
@@ -208,7 +262,7 @@ the source of truth, validated and packaged by the dependency-free \`@gregiteen/
 
 \`\`\`
 vault/         Your SSSS documents (structural + tenant_private primitives).
-test/          Conformance test — replays the canonical fixtures + round-trips the vault.
+${extensionName ? `registry/      Custom primitive extension schema (registry/extensions/${extensionName}.json).\n` : ''}test/          Conformance test — replays the canonical fixtures + round-trips the vault.
 \`\`\`
 
 ## Use
@@ -236,18 +290,23 @@ npx total-recall recall "..."                    # semantic recall
 ` : ''}`;
 }
 
-function claudeMd(name, withTR) {
+function claudeMd(name, withTR, extensionName) {
   return `# ${name} — agent guide
 
 This repo uses **SSSS** (Structured Semantic Syntax System) as its state contract.
 
 ## Source of truth
 - \`vault/\` is the only source of truth — typed Markdown documents with YAML
-  frontmatter. Every file declares a \`type\` defined in the \`@gregiteen/ssss-cli\` core registry.
+  frontmatter. Every file declares a \`type\` defined in the \`@gregiteen/ssss-cli\` core registry${extensionName ? ` or local \`registry/extensions/${extensionName}.json\`` : ''}.
 - Mutate the vault through the standard, not by hand-writing files in bulk:
   \`npx ssss\` for bundle/tenant tooling, or the \`@gregiteen/ssss-cli/engine\` Operation Contract
   in code.
 
+## Extension & Registry Isolation Invariant
+- App-specific primitives belong exclusively in \`registry/extensions/\` inside this application repository.
+- Never modify or fork \`@gregiteen/ssss-cli\` to add app-specific schemas.
+- Validate local extension schemas with: \`npx ssss schema validate registry/extensions/<name>.json\`.
+
 ## Portability (§5.5) — the rule that matters
 - \`structural\` documents (rules, workflows, pages, assistants) are the sellable model.
 - \`tenant_private\` documents (tasks, customer data) are **never** shipped in a
@@ -264,7 +323,7 @@ ${withTR ? `
 ` : ''}`;
 }
 
-function designMd(name) {
+function designMd(name, extensionName) {
   return `# ${name} — System Architecture & Design
 
 > Technical design and architecture specification for ${name}.
@@ -278,7 +337,7 @@ function designMd(name) {
 - **Vault Structure**: Typed Markdown documents under \`vault/\` serving as the source of truth.
 - **Workflows & Execution**: Automated procedures defined in \`vault/workflows/\` triggered by operational events.
 - **Capabilities & Resources**: Tools and external service integrations required for execution.
-
+${extensionName ? `- **Extension Registry**: Custom primitive definitions located in \`registry/extensions/${extensionName}.json\` extending core SSSS.\n` : ''}
 ## Data & Schema Contracts
 
 <Core entities, external dependencies, and integration interfaces.>
@@ -287,5 +346,7 @@ function designMd(name) {
 
 - SSSS VFS is the single source of truth for application state.
 - Structural business logic is strictly decoupled from private tenant operational data.
+- App-specific primitives reside in \`registry/extensions/\` within this repository and extend \`core\`.
+- Core SSSS library (\`@gregiteen/ssss-cli\`) remains vendor-neutral and dependency-free.
 `;
 }

package/scripts/cmd-schema.mjs

@@ -1,22 +1,41 @@
 /**
- * Schema export and inspection commands for SSSS.
+ * `ssss schema` — inspect, export, and validate against the canonical Draft 2020-12
+ * JSON Schemas for SSSS registries (`schemas/core-registry.schema.json`) and
+ * `.ucw` transport bundles (`schemas/bundle.schema.json`).
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
+import {
+  getCoreRegistrySchema,
+  getBundleSchema,
+  validateJsonSchema,
+} from '../src/schema-validator.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(HERE, '..');
 const SCHEMAS_DIR = path.resolve(ROOT, 'schemas');
 
-const HELP = `Usage: ssss schema core|bundle|export [options]
-
-Commands:
-  core [--out <file>]      Output the Core Registry JSON Schema.
-  bundle [--out <file>]    Output the .ucw Bundle JSON Schema.
-  export [--out <dir>]     Export all canonical schemas to a directory (default: ./schemas).
-`;
+const HELP = usage({
+  summary: 'Output, export, or validate against the canonical SSSS Draft 2020-12 JSON Schemas.',
+  usage: 'ssss schema <core|bundle|export|validate> [target] [options]',
+  options: [
+    ['--out <path>', 'Destination file (core/bundle) or directory (export; default: ./schemas).'],
+    ['--type <core|bundle>', 'Target schema kind for `validate` (auto-detected when omitted).'],
+    ['--schema <file>', 'Custom JSON Schema file path for `validate`.'],
+    ['--json', 'Emit machine-readable JSON output for `export` or `validate`.'],
+    ['--quiet', 'Suppress human-readable output on valid `validate` check.'],
+  ],
+  examples: [
+    'ssss schema core',
+    'ssss schema bundle --out ./bundle.schema.json',
+    'ssss schema export --out ./schemas',
+    'ssss schema validate registry/core.json',
+    'ssss schema validate conformance/reference-bundle.ucw.json --type bundle',
+  ],
+  seeAlso: ['ssss registry', 'ssss validate', 'ssss help schema'],
+});
 
 function emit(value, output) {
   const text = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
@@ -28,10 +47,30 @@ function emit(value, output) {
   }
 }
 
+function detectSchemaType(data, explicitType) {
+  if (explicitType === 'core' || explicitType === 'registry') return 'core';
+  if (explicitType === 'bundle') return 'bundle';
+  if (explicitType) {
+    die(`Unknown --type '${explicitType}'. Use 'core' or 'bundle'.`);
+  }
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    if (typeof data.$schema === 'string') {
+      if (data.$schema.includes('bundle.schema.json')) return 'bundle';
+      if (data.$schema.includes('core-registry.schema.json') || data.$schema.includes('registry')) return 'core';
+    }
+    if ('manifest' in data || 'files' in data) return 'bundle';
+    if ('registry' in data || 'document_primitives' in data) return 'core';
+  }
+  return 'core';
+}
+
 export async function run(argv) {
   if (wantsHelp(argv)) { console.log(HELP); return; }
   const verb = argv[0];
-  const { flags } = parseArgs(argv.slice(1));
+  const { positionals, flags } = parseArgs(argv.slice(1), {
+    booleans: ['json', 'quiet'],
+    alias: { j: 'json', q: 'quiet' },
+  });
 
   try {
     const coreSchemaPath = path.join(SCHEMAS_DIR, 'core-registry.schema.json');
@@ -50,12 +89,63 @@ export async function run(argv) {
     if (verb === 'export') {
       const targetDir = path.resolve(flags.out || './schemas');
       fs.mkdirSync(targetDir, { recursive: true });
-      fs.copyFileSync(coreSchemaPath, path.join(targetDir, 'core-registry.schema.json'));
-      fs.copyFileSync(bundleSchemaPath, path.join(targetDir, 'bundle.schema.json'));
-      console.log(`Exported canonical schemas to ${targetDir}`);
+      const written = [
+        path.join(targetDir, 'core-registry.schema.json'),
+        path.join(targetDir, 'bundle.schema.json'),
+      ];
+      fs.copyFileSync(coreSchemaPath, written[0]);
+      fs.copyFileSync(bundleSchemaPath, written[1]);
+      if (flags.json) {
+        console.log(JSON.stringify({ exported: written, directory: targetDir }, null, 2));
+      } else {
+        console.log(`Exported canonical schemas to ${targetDir}`);
+      }
       return;
     }
-    die(`Unknown schema verb '${verb || ''}'.\n${HELP}`);
+    if (verb === 'validate') {
+      const file = positionals[0];
+      if (!file) die(`validate requires a target JSON file.\n\n${HELP}`);
+      const resolvedFile = path.resolve(file);
+      if (!fs.existsSync(resolvedFile)) die(`no such file: ${file}`);
+      let data;
+      try {
+        data = JSON.parse(fs.readFileSync(resolvedFile, 'utf8'));
+      } catch (err) {
+        die(`not valid JSON (${file}): ${err.message}`);
+      }
+
+      let schema;
+      let schemaLabel;
+      if (flags.schema) {
+        const customSchemaPath = path.resolve(flags.schema);
+        if (!fs.existsSync(customSchemaPath)) die(`no such schema file: ${flags.schema}`);
+        schema = JSON.parse(fs.readFileSync(customSchemaPath, 'utf8'));
+        schemaLabel = flags.schema;
+      } else {
+        const kind = detectSchemaType(data, flags.type);
+        schema = kind === 'bundle' ? getBundleSchema() : getCoreRegistrySchema();
+        schemaLabel = kind;
+      }
+
+      const { valid, errors } = validateJsonSchema(data, schema);
+      if (flags.json) {
+        console.log(JSON.stringify({ valid, schema: schemaLabel, file, errors }, null, 2));
+        if (!valid) process.exit(1);
+        return;
+      }
+      if (valid) {
+        if (!flags.quiet) {
+          console.log(`✓ valid — ${file} (${schemaLabel} schema)`);
+        }
+        return;
+      }
+      console.error(`✗ invalid — ${errors.length} error(s) in ${file}:`);
+      for (const e of errors) {
+        console.error(`  - ${e.path ? `${e.path}: ` : ''}${e.message}`);
+      }
+      process.exit(1);
+    }
+    die(`Unknown schema verb '${verb || ''}'.\n\n${HELP}`);
   } catch (error) {
     die(error.message);
   }

package/scripts/conformance-09.mjs

@@ -463,6 +463,19 @@ function checkJsonSchemas(check) {
   const badBundle = { files: [] };
   const badBundleResult = validateJsonSchema(badBundle, bundleSchema);
   check('schema: bundle schema rejects missing manifest', !badBundleResult.valid && badBundleResult.errors.some((e) => e.path.includes('manifest')));
+
+  // Extension registries need no spec_version/description (those are core-only, A-009).
+  const extDef = definePrimitive({ namespace: 'acme', name: 'Widget', fields: [{ id: 'title', name: 'Title', kind: 'string', required: true }] });
+  const extResult = validateJsonSchema(definitionsToExtensionRegistry('acme', [extDef]), coreSchema);
+  check('schema: definitionsToExtensionRegistry() output validates against the registry schema', extResult.valid, extResult.errors?.[0] && `${extResult.errors[0].path}: ${extResult.errors[0].message}`);
+
+  const strayKey = validateJsonSchema({ ...coreRegistry, unexpected_root_key: true }, coreSchema);
+  check('schema: registry schema rejects unknown root keys (fail-closed)', !strayKey.valid && strayKey.errors.some((e) => e.path === 'unexpected_root_key'));
+
+  const dupFields = JSON.parse(JSON.stringify(coreRegistry));
+  dupFields.document_primitives.rule.required_fields = ['type', 'type'];
+  const dupResult = validateJsonSchema(dupFields, coreSchema);
+  check('schema: registry schema rejects duplicate required_fields (uniqueItems)', !dupResult.valid && dupResult.errors.some((e) => e.message.includes('uniqueItems')));
 }
 
 // Resource hooks (spec §6.3): every prepare ends in exactly one finalize or

package/scripts/conformance.mjs

@@ -430,13 +430,13 @@ async function runBundleConformance() {
     // D4: Resource bindings emitted in result
     check('provisionBundle emits resource bindings with relations and modes (D4)',
       provAlpha.bindings.length > 0 &&
-      provAlpha.bindings.some((b) => b.type === 'domain' && b.value === 'alpha.example' && b.relation === 'owns_domain'));
+      provAlpha.bindings.some((b) => (b.type === 'resource' || b.type === 'domain') && b.value === 'alpha.example'));
 
     // D4: Unbound required resource fails when not dryRun
     const unboundBundle = JSON.parse(JSON.stringify(bundle));
     const provUnbound = provisionBundle(unboundBundle, {
       workspaceId: 'ws-unbound',
-      parameters: { business_name: 'Unbound Fest' }, // domain omitted!
+      parameters: { business_name: 'Unbound Fest' }, // domain / resource binding omitted!
       dryRun: false,
     });
     check('unbound required resource fails provisioning when dryRun is false (D4)',
@@ -1135,6 +1135,44 @@ async function runCliSmokeConformance() {
     }
     check('ssss new starter vault files validate against the registry', files.length > 0 && failures.length === 0, JSON.stringify(failures));
 
+    // A-008: an app-local extension scaffold must pass its own generated test.
+    const extApp = path.join(tmp, 'ext-app');
+    execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'new', extApp, '--extension', 'acme', '--no-git'], { stdio: 'ignore' });
+    fs.mkdirSync(path.join(extApp, 'node_modules', '@gregiteen'), { recursive: true });
+    fs.symlinkSync(path.resolve(__dirname, '..'), path.join(extApp, 'node_modules', '@gregiteen', 'ssss-cli'), 'dir');
+    let extTestOk = true;
+    let extTestDetail = '';
+    try { execFileSync('node', ['--test'], { cwd: extApp, stdio: 'pipe' }); }
+    catch (err) { extTestOk = false; extTestDetail = String(err.stdout || err.message).slice(-600); }
+    check('ssss new --extension scaffolds an app whose own node --test passes', extTestOk, extTestDetail);
+
+    const badExt = (() => {
+      try { execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'new', path.join(tmp, 'bad-ext'), '--extension', 'core', '--no-git'], { stdio: 'pipe' }); return false; }
+      catch { return !fs.existsSync(path.join(tmp, 'bad-ext')); }
+    })();
+    check('ssss new --extension rejects reserved registry names before writing', badExt);
+
+    // ssss schema validate: core, scaffolded extension, bundle, and a failing input.
+    const schemaValidate = (target, extra = []) => {
+      try {
+        return { code: 0, out: JSON.parse(execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'schema', 'validate', target, '--json', ...extra], { encoding: 'utf8' })) };
+      } catch (err) {
+        return { code: err.status, out: JSON.parse(err.stdout || '{}') };
+      }
+    };
+    const coreValid = schemaValidate(path.join(REGISTRY_DIR, 'core.json'));
+    const extValid = schemaValidate(path.join(extApp, 'registry', 'extensions', 'acme.json'));
+    const bundleValid = schemaValidate(path.resolve(__dirname, '..', 'conformance', 'reference-bundle.ucw.json'));
+    check('ssss schema validate accepts core, extension, and bundle documents',
+      coreValid.code === 0 && coreValid.out.valid && extValid.code === 0 && extValid.out.valid &&
+      bundleValid.code === 0 && bundleValid.out.valid && bundleValid.out.schema === 'bundle',
+      JSON.stringify({ coreValid, extValid, bundleValid }).slice(0, 600));
+    const badRegistryPath = path.join(tmp, 'bad-registry.json');
+    fs.writeFileSync(badRegistryPath, JSON.stringify({ registry: 'acme', document_primitives: {}, typo_key: 1 }));
+    const badValid = schemaValidate(badRegistryPath, ['--type', 'core']);
+    check('ssss schema validate exits 1 with structured errors on an invalid registry',
+      badValid.code === 1 && badValid.out.valid === false && badValid.out.errors.some((e) => e.path === 'typo_key'));
+
     const semanticOutput = JSON.parse(execFileSync('node', [
       path.join(__dirname, 'ssss.mjs'),
       'semantic',

package/scripts/sync-docs.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Automatically synchronize and verify documentation after OpenWiki updates:
+ * 1. Updates overview.md command lists, topics, and primitive counts.
+ * 2. Ingests updated docs into OpenWiki knowledge graph.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPTS_DIR = path.join(ROOT, 'scripts');
+const HELP_DIR = path.join(ROOT, 'docs', 'help');
+const OVERVIEW_FILE = path.join(HELP_DIR, 'overview.md');
+const CORE_REGISTRY = path.join(ROOT, 'registry', 'core.json');
+
+const commands = fs.readdirSync(SCRIPTS_DIR)
+  .filter((f) => f.startsWith('cmd-') && f.endsWith('.mjs'))
+  .map((f) => f.replace(/^cmd-/, '').replace(/\.mjs$/, ''))
+  .sort();
+
+const helpTopics = fs.existsSync(HELP_DIR)
+  ? fs.readdirSync(HELP_DIR)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.replace(/\.md$/, ''))
+      .sort()
+  : [];
+
+let corePrimitivesCount = 20;
+let contractPrimitivesCount = 5;
+if (fs.existsSync(CORE_REGISTRY)) {
+  const core = JSON.parse(fs.readFileSync(CORE_REGISTRY, 'utf8'));
+  corePrimitivesCount = Object.keys(core.document_primitives || {}).length;
+  contractPrimitivesCount = Object.keys(core.contract_primitives || {}).length;
+}
+
+if (fs.existsSync(OVERVIEW_FILE)) {
+  let content = fs.readFileSync(OVERVIEW_FILE, 'utf8');
+
+  // Update primitive counts
+  const regPattern = /\|\s*Core registry\s*\|\s*`registry\/core\.json`\s*\|\s*[^|]+\|/;
+  const regReplacement = `| Core registry | \`registry/core.json\` | ${corePrimitivesCount} document primitives + ${contractPrimitivesCount} contract primitives; semantic (§11.9), bundle (§16), and provisioning (§17) rules. |`;
+  content = content.replace(regPattern, regReplacement);
+
+  // Update help topic list
+  const helpSection = `Run \`ssss help <topic>\` for any of:\n\`${helpTopics.join('`, `')}\`.`;
+  content = content.replace(/Run `ssss help <topic>` for any of:\n[\s\S]*?(?=\n\nRun `ssss <command>)/, helpSection);
+
+  // Update command list
+  const cmdSection = `Run \`ssss <command> --help\` for: \`${commands.join('`, `')}\`.`;
+  content = content.replace(/Run `ssss <command> --help` for:[\s\S]*?(?=\n*$)/, cmdSection);
+
+  fs.writeFileSync(OVERVIEW_FILE, content.trim() + '\n', 'utf8');
+}
+
+console.log(`✓ Synchronized docs/help/overview.md: ${commands.length} commands, ${helpTopics.length} help topics, ${corePrimitivesCount} primitives.`);

package/skills/ssss/core/references/core-registry.json

@@ -269,7 +269,7 @@
     "classes": {
       "structural": "The reusable business model — sellable and templatable. Carries no operator- or customer-specific data. Examples: workflow, assistant, page, skill, model, rule, memory, migration, release.",
       "tenant_private": "The operator's private operational data — customers, transcripts, runtime work. NEVER leaves the workspace in a template or sale bundle; included only in an encrypted backup. Examples: conversation, run, task, conflict, and (via extension) profile / CRM contact / deal.",
-      "resource_bound": "Requires a real external resource bound at provision time (a domain, phone number, mailbox, API connection). NEVER ships the seller's resource value; ships only a requirement declaration the buyer satisfies. Defined by extension registries (e.g. festech domain / phone_number / integration_connection)."
+      "resource_bound": "Requires a real external resource bound at provision time (a domain, phone number, mailbox, API connection). NEVER ships the seller's resource value; ships only a requirement declaration the buyer satisfies. Defined by extension registries (e.g. a domain, phone_number, or integration_connection primitive)."
     },
     "export_profiles": {
       "backup": { "includes": ["structural", "tenant_private", "resource_bound"], "note": "Complete fidelity copy. tenant_private MUST be encrypted at rest." },

package/src/bundle.mjs

@@ -63,6 +63,7 @@ function requirementParameterKey(type, field) {
 function resourceFieldParameterAliases(type, field) {
   const aliases = [requirementParameterKey(type, field), field];
   if (type === 'domain' && field === 'domain_name') aliases.push('domain');
+  if (type === 'resource' && (field === 'binds' || field === 'name')) aliases.push('domain', 'resource_domain');
   if (type === 'phone_number' && field === 'phone_number') aliases.push('phone');
   return aliases;
 }

package/src/registry.mjs

@@ -408,12 +408,19 @@ function loadExtensionDefaults(registryDir) {
  * `extensions/defaults.json` is loaded; failing that, every extension is loaded
  * and any duplicate name remains a hard error rather than a silent preference.
  *
- * @param {string} [registryDir] - directory containing core.json + extensions/
+ * @param {string} [registryDir] - directory containing core.json + extensions/, or an
+ *   application `registry/` holding only extensions/ (the package core is used)
  * @param {{ only?: string[]|Set<string> }} [options]
  * @returns {{ types: Map<string, object>, contractTypes: Set<string>, portabilityClasses: string[], core: object, extensions: Set<string> }}
  */
 export function loadRegistries(registryDir = DEFAULT_REGISTRY_DIR, options = {}) {
-  const corePath = path.join(registryDir, 'core.json');
+  // Application repositories hold only `registry/extensions/`; the core always
+  // comes from this package (hosts never copy core.json). Fall back to the
+  // package core when the given directory has extensions but no core.json.
+  const ownCore = path.join(registryDir, 'core.json');
+  const corePath = fs.existsSync(ownCore) || !fs.existsSync(path.join(registryDir, 'extensions'))
+    ? ownCore
+    : path.join(DEFAULT_REGISTRY_DIR, 'core.json');
   const core = JSON.parse(fs.readFileSync(corePath, 'utf8'));
   const requested = options.only ? new Set(options.only) : null;
   const defaults = requested ? null : loadExtensionDefaults(registryDir);