@gregiteen/ssss-cli 0.7.1 → 0.8.0

package/docs/ssss-spec.md

@@ -1,6 +1,6 @@
 # SSSS — Structured Semantic Syntax System
 
-**Specification v0.6 — Draft**
+**Specification v0.7 — Draft**
 
 > This is the canonical, vendor-neutral specification for SSSS. It is the ground
 > truth on which all SSSS implementations are built. It is intended to be vendored
@@ -31,6 +31,10 @@ SSSS additionally defines the **Operation Contract**: a single, validated, idemp
 envelope through which all agent-generated mutations must flow. This makes
 AI-generated state changes deterministic, replayable, conflict-safe, and auditable.
 
+Its semantic projection contract turns the same canonical files into a deterministic
+searchable graph, while translation overlays localize natural-language surfaces
+without mutating symbolic control fields or private operational data.
+
 Any tool, IDE, agent framework, daemon, or CLI that can read Markdown can
 interoperate with an SSSS vault. The only thing that distinguishes a memory engine,
 a chat runtime, and a workflow orchestrator is *which primitive types they read and
@@ -124,6 +128,17 @@ For OKF-compatible discovery, SSSS document primitives SHOULD also include:
 | `tags` | array | Array of string tags for categorization and routing. |
 | `aliases` | array | Array of alternative names for this concept, used for wiki autolinking. |
 
+For stable semantic identity and graph projection, documents SHOULD also include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `semantic_id` | string | Stable concept identity that survives file moves and localized presentation. |
+| `relations` | array | Explicit semantic edges to other vault-relative document paths or semantic ids. |
+| `locale` | string | BCP-47-style locale of the authored natural-language surface, when known. |
+
+`resource`, `tags`, and `aliases` serve both OKF discovery and the semantic layer.
+These fields are recommendations, not new universal requirements.
+
 Every primitive type defines its own additional REQUIRED and OPTIONAL fields
 (§5.4). To maintain forward compatibility and allow agents scratchpad space, hosts MUST NOT reject documents containing unknown frontmatter keys. Unknown fields MUST be preserved.
 
@@ -180,6 +195,7 @@ primitive — it implements the subset its product requires — but any primitiv
 | `page` | capability | structural | A VFS-native sandboxed custom workspace page. |
 | `migration` | meta | structural | An SSSS schema migration state record. |
 | `release` | meta | structural | An SSSS system schema version release record. |
+| `translation` | localization | structural | A hash-bound, non-destructive localization overlay for a structural source document. |
 
 The **Portability** column is the primitive's default portability class (§5.5); a host
 resolves it from `registry/core.json`. Extension registries assign their own primitives a
@@ -201,7 +217,7 @@ Document primitives are either:
 
 - **Replace-type** — the whole file represents current state; a write replaces it
   entirely (`memory`, `skill`, `assistant`, `workflow`, `model`, `task`,
-  `conflict`).
+  `conflict`, `translation`).
 - **Append-type** — the file is an ordered, append-only log; writes add records to
   the body and MUST NOT rewrite prior records (`conversation`, `run`).
 
@@ -545,6 +561,49 @@ released_at: 2026-05-16T12:00:00Z
 ---
 ```
 
+#### `translation`
+
+A non-destructive localization overlay for one structural source document. A
+translation is itself `structural`, but it does not replace or fork the source. The
+source remains authoritative for identity, behavior, permissions, enums, links, and
+all other symbolic control fields.
+
+REQUIRED: `type`, `translation_id`, `source_path`, `source_hash`, `locale`, `status`
+(`draft|reviewed|approved`), and `translated_fields` (a subset of
+`title|description|body`). OPTIONAL: `translated_title`, `translated_description`,
+`translator`, `reviewed_at`. The Markdown body is the translated body when
+`translated_fields` includes `body`.
+
+`translation_id`, `source_path`, and `locale` are immutable after creation.
+`source_path` MUST be a safe, vault-relative path to an existing `structural`
+document whose type is not `translation`. `source_hash` MUST equal the source's
+current SHA-256 content hash, written as `sha256:<64 lowercase hex characters>`.
+A stale, missing, private, resource-bound, recursive, traversing, or symlinked source
+MUST be rejected.
+
+```markdown
+---
+type: translation
+title: "Política de reembolsos — español"
+description: "Traducción al español de la política de reembolsos."
+timestamp: 2026-07-10T00:00:00Z
+translation_id: refund-policy-es
+source_path: rules/refund-policy.md
+source_hash: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+locale: es
+status: approved
+translated_fields: [title, description, body]
+translated_title: "Política de reembolsos"
+translated_description: "Reglas de reembolso para compradores."
+---
+
+Los reembolsos están disponibles dentro de los treinta días.
+```
+
+Draft and reviewed translations MAY be stored and previewed, but only approved,
+hash-current overlays are applied by default to canonical localized projections
+(§11.9).
+
 ### 5.5 Portability Classification
 
 A workspace is not one undifferentiated blob. Some of it is the **reusable business
@@ -1042,11 +1101,50 @@ run, plus an event explaining the terminal failure.
 
 #### Runtime Helpers
 
-The reference package exposes `@ssss/cli/runtime`, including deterministic helpers
+The reference package exposes `@gregiteen/ssss-cli/runtime`, including deterministic helpers
 for planning a workflow trigger into a `workflow_triggered` event envelope and a
 task `operation` envelope. Hosts MAY implement their own daemon, but SHOULD pass the
 runtime conformance checks to prove the same source-of-truth and idempotency rules.
 
+### 11.9 Semantic Projection & Localization Contract
+
+The semantic layer is a **derived projection** over validated vault documents. It
+MUST be deterministic for the same vault bytes, registry set, locale, and projection
+options. It MUST NOT become a second source of truth.
+
+Each projected record SHOULD expose a stable identity, source path and content hash,
+primitive type, portability class, surface text, normalized search tokens, and graph
+edges. Identity is resolved from `semantic_id`, then `resource`, then the source path.
+Edges are derived from explicit `relations`, wiki links, and Markdown links. Hosts MAY
+add embeddings or richer ranking, but the exact lexical/graph projection MUST remain
+available as a dependency-free interoperability baseline.
+
+The safe default projection contains only `structural` documents. It MUST exclude
+`tenant_private` and `resource_bound` documents unless the caller explicitly enables
+private indexing in an authorized context. A localized export MUST use the same safe
+default, so requesting a locale can never implicitly disclose conversations, runs,
+tasks, credentials, customer data, or bound resource values.
+
+When a locale is requested, the host MAY apply one eligible `translation` (§5.4) per
+source. Eligibility requires all of the following:
+
+1. The overlay locale normalizes to the requested locale.
+2. Its status is `approved`, unless a caller explicitly opts into draft preview.
+3. The source is an existing, non-symlinked `structural` document.
+4. `source_hash` exactly matches the current source bytes.
+5. There is no second eligible overlay for the same source and locale.
+
+An overlay may replace only `title`, `description`, and body. It MUST preserve `type`,
+paths, ids, enums, status, permissions, portability, relations, and every other
+symbolic field from the source. Stale hashes, duplicate overlays, traversal, symlink
+targets, recursive translations, and translations of non-structural sources MUST
+fail closed.
+
+A materialized locale is a disposable projection, not a translated vault. It MUST be
+written outside the source vault to a new or empty non-symlinked directory, preserve
+source-relative paths, and include enough projection metadata to identify its locale
+and source hashes. It may be deleted and rebuilt at any time.
+
 ---
 
 ## 12. Conformance
@@ -1061,6 +1159,11 @@ Fixtures are distributed as a JSON document carrying:
 - `idempotency` — TTL and replay behavior.
 - `validation_rules` — envelope and content rules.
 - `runtime_contract` — trigger vocabulary and daemon idempotency rules (§11.8).
+- registry-extension checks — schema shape, regex validity, symlink rejection, and
+  core/sibling collision rejection.
+- semantic/localization checks — deterministic indexing, privacy defaults, graph
+  edges, exact source hashes, immutable overlay identity, and safe materialization
+  (§11.9).
 - `fixtures[]` — each with a `request`, an `expected_response`, and an
   OPTIONAL `expected_http_status`.
 - `error_codes` — the canonical code table.
@@ -1068,7 +1171,8 @@ Fixtures are distributed as a JSON document carrying:
 The conformance fixture set is the shared test contract between all SSSS
 implementations. A host MUST NOT claim SSSS conformance without passing the current
 fixture set. Hosts implementing workflow daemons SHOULD also run the reference
-runtime checks exposed by `@ssss/cli/runtime`.
+  runtime checks exposed by `@gregiteen/ssss-cli/runtime`. Hosts exposing semantic
+  search or localized projections MUST also pass the §11.9 checks.
 
 ---
 
@@ -1096,7 +1200,7 @@ opaque ID as the slug and keep the human-readable label in `title` / `name`.
 This document is versioned independently of any host and of the conformance
 fixture set.
 
-- The spec version is stated in the document header (currently **v0.6 — Draft**).
+- The spec version is stated in the document header (currently **v0.7 — Draft**).
 - Breaking changes to the file format, the type registry, or the Operation
   Contract increment the spec version.
 - Until **v1.0**, any version MAY introduce breaking changes.
@@ -1208,7 +1312,7 @@ them without a spec change.
   serialization of `files` (path-sorted, §16.1). An importer MUST recompute it and reject
   a bundle whose files do not match. This is what makes a bundle tamper-evident and what a
   marketplace lists against.
-- `exporter` — an identifier for the tool/host that produced the bundle (`"@ssss/cli@0.3.0"`).
+- `exporter` — an identifier for the tool/host that produced the bundle (`"@gregiteen/ssss-cli@0.8.0"`).
 - `signature` — OPTIONAL detached signature over `content_hash` for a sold bundle, so a
   buyer can verify authorship. Unsigned bundles are valid; signing is a marketplace concern.
 
@@ -1313,7 +1417,8 @@ cannot resolve a link MUST fail the provision rather than emit a dangling refere
 
 The following frontmatter keys are reserved by this spec across all primitives and
 MUST NOT be repurposed by hosts: `type`, `slug`, `schema_version`, `status`,
-`feedback`, `confidence`.
+`feedback`, `confidence`, `semantic_id`, `relations`, `locale`, `translation_id`,
+`source_path`, `source_hash`, and `translated_fields`.
 
 Hosts adding their own frontmatter fields SHOULD prefix them `x_` to remain
 forward-compatible with future spec revisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {
@@ -10,13 +10,14 @@
     "./registry": "./src/registry.mjs",
     "./frontmatter": "./src/frontmatter.mjs",
     "./bundle": "./src/bundle.mjs",
+    "./semantic": "./src/semantic.mjs",
     "./conformance/fixtures.json": "./conformance/fixtures.json",
     "./conformance/reference-bundle.ucw.json": "./conformance/reference-bundle.ucw.json",
     "./registry/core.json": "./registry/core.json",
     "./package.json": "./package.json"
   },
   "bin": {
-    "ssss": "./scripts/ssss.mjs"
+    "ssss": "scripts/ssss.mjs"
   },
   "type": "module",
   "engines": {
@@ -29,6 +30,7 @@
     "conformance",
     "docs/ssss-spec.md",
     "docs/help",
+    "skills/ssss",
     "VERSION",
     "README.md",
     "CHANGELOG.md",
@@ -46,7 +48,10 @@
     "vault",
     "operation-contract",
     "ucw",
-    "provisioning"
+    "provisioning",
+    "semantic-search",
+    "localization",
+    "translation"
   ],
   "author": "Greg Iteen",
   "license": "ISC",

package/registry/core.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://ssss.dev/registry/v1",
   "registry": "core",
-  "spec_version": "0.6",
-  "description": "The canonical SSSS core primitive registry. These 14 document primitives and 5 contract primitives are defined by the SSSS specification (docs/ssss-spec.md §5) and are owned by this standard. Every document primitive declares a portability class (§5.5); the registry also defines the workflow runtime contract (§11.8), the `.ucw` bundle format (§16), and the provisioning contract (§17). A conformant host MUST implement any core primitive it uses according to this registry. Applications extend the core with their own primitives via an extension registry (see registry/README.md); extensions MUST NOT redefine a core type.",
+  "spec_version": "0.7",
+  "description": "The canonical SSSS core primitive registry. These 15 document primitives and 5 contract primitives are defined by the SSSS specification (docs/ssss-spec.md §5) and are owned by this standard. Every document primitive declares a portability class (§5.5); the registry also defines the workflow runtime contract (§11.8), semantic/localization contract (§11.9), `.ucw` bundle format (§16), and provisioning contract (§17). A conformant host MUST implement any core primitive it uses according to this registry. Applications extend the core with their own primitives via an extension registry; extensions MUST NOT redefine a core or sibling-extension type.",
   "conformance": "A host is core-conformant for a primitive if a file of that type validates exactly when all required_fields are present and non-empty, and (for append_only types) writes only append.",
 
   "document_primitives": {
@@ -136,6 +136,34 @@
       "portability": "structural",
       "required_fields": ["type", "release_id", "version", "schema_version", "summary", "released_at"],
       "spec_ref": "§5.4 release"
+    },
+    "translation": {
+      "family": "localization",
+      "canonical_path": "translations/<locale>/<source-path>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "translation_id", "source_path", "source_hash", "locale", "status", "translated_fields"],
+      "optional_fields": ["translated_title", "translated_description", "translator", "reviewed_at"],
+      "immutable_fields": ["translation_id", "source_path", "locale"],
+      "enums": {
+        "status": ["draft", "reviewed", "approved"],
+        "translated_fields": ["title", "description", "body"]
+      },
+      "patterns": {
+        "translation_id": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$",
+        "locale": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
+        "source_hash": "^sha256:[a-f0-9]{64}$"
+      },
+      "references": {
+        "source_path": {
+          "must_exist": true,
+          "disallowed_types": ["translation"],
+          "allowed_portability": ["structural"],
+          "hash_field": "source_hash"
+        }
+      },
+      "notes": "A non-destructive presentation overlay. Only title, description, and body may be translated; symbolic control fields remain byte-for-byte sourced from the referenced structural document.",
+      "spec_ref": "§5.4 translation"
     }
   },
 
@@ -150,6 +178,7 @@
   "universal_frontmatter": {
     "required": ["type", "title", "description", "timestamp"],
     "recommended_okf": ["resource", "tags", "aliases"],
+    "recommended_semantic": ["semantic_id", "resource", "tags", "aliases", "relations", "locale"],
     "spec_ref": "§4.2"
   },
 
@@ -219,7 +248,18 @@
     "spec_ref": "§11.8"
   },
 
-  "reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence"],
+  "semantic": {
+    "version": 1,
+    "identity_fields": ["semantic_id", "resource", "type", "path"],
+    "surface_fields": ["title", "description", "name", "slug", "aliases", "tags"],
+    "relation_fields": ["relations", "wiki_links", "markdown_links"],
+    "translatable_fields": ["title", "description", "body"],
+    "locale_pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
+    "safe_default": "Semantic indexes exclude tenant_private and resource_bound documents unless include_private is explicitly enabled. Translation overlays may reference structural sources only.",
+    "spec_ref": "§11.9"
+  },
+
+  "reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence", "semantic_id", "locale", "translation_of", "translation_source_hash"],
   "host_field_prefix": "x_",
   "spec_ref_reserved": "Appendix A"
 }

package/scripts/audit-registry-field-usage.mjs

@@ -37,7 +37,15 @@ const ENGINE_FILES = [
 // spec §6.3 + §9). If a primitive declares one, the engine source MUST
 // reference it — otherwise the registry is making a promise the engine
 // doesn't keep.
-const ENGINE_ENFORCED_KEYS = ['required_fields', 'required_when', 'enums', 'append_only'];
+const ENGINE_ENFORCED_KEYS = [
+  'required_fields',
+  'required_when',
+  'enums',
+  'patterns',
+  'immutable_fields',
+  'references',
+  'append_only',
+];
 
 // Keys that are real and load-bearing but are intentionally consumed
 // elsewhere (export/bundle time, documentation, or the registry loader
@@ -75,6 +83,7 @@ function engineReferencesKey(engineSources, key) {
   const patterns = [
     new RegExp(`\\bdef\\.${key}\\b`),
     new RegExp(`\\btypeDef\\.${key}\\b`),
+    new RegExp(`(?:\\.|\\?\\.)${key}\\b`),
     new RegExp(`\\['${key}'\\]`),
     new RegExp(`\\["${key}"\\]`),
   ];

package/scripts/build-reference-bundle.mjs

@@ -15,10 +15,14 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { exportBundle, validateBundle } from '../src/bundle.mjs';
+import { documentHash } from '../src/registry.mjs';
 import { generateIndexes } from './autolink.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const OUT = path.resolve(__dirname, '..', 'conformance', 'reference-bundle.ucw.json');
+const PACKAGE = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')
+);
 
 // ─── The reference vault ────────────────────────────────────────────────────
 const VAULT = {
@@ -109,6 +113,25 @@ status: pending
 Attendee jane@example.com requested a seat change.`,
 };
 
+// Structural translation overlay — hash-bound to the exact source document and
+// applied only by the semantic/localization projection (§11.9).
+VAULT['translations/es/rules/refund-policy.md'] =
+`---
+type: translation
+title: Spanish Refund Policy Translation
+description: Approved Spanish presentation overlay for the festival refund policy.
+timestamp: 2026-07-10T00:00:00Z
+translation_id: refund-policy-es
+source_path: rules/refund-policy.md
+source_hash: ${documentHash(VAULT['rules/refund-policy.md'])}
+locale: es
+status: approved
+translated_fields: [title, description, body]
+translated_title: Política de reembolsos
+translated_description: Explica cuándo están disponibles los reembolsos para asistentes.
+---
+Los reembolsos están disponibles hasta catorce días antes del evento.`;
+
 function buildVault() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-refvault-'));
   const files = [];
@@ -134,7 +157,7 @@ try {
     name: 'Festival in a Box',
     description: 'A complete music-festival operation as a tradeable SSSS bundle.',
     version: '1.0.0',
-    exporter: '@ssss/cli@0.7.0',
+    exporter: `${PACKAGE.name}@${PACKAGE.version}`,
     requiredExtensions: ['festech'],
     parameters: [
       { key: 'business_name', label: 'Festival name', type: 'string', scope: 'workspace', source: 'user', required: true },

package/scripts/cmd-export.mjs

@@ -7,7 +7,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { exportBundle } from '../src/bundle.mjs';
+import { DEFAULT_EXPORTER, exportBundle } from '../src/bundle.mjs';
 import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
 
 const HELP = usage({
@@ -19,7 +19,7 @@ const HELP = usage({
     ['--name <s>', 'Bundle display name.'],
     ['--description <s>', 'Bundle description.'],
     ['--bundle-version <s>', 'Bundle version string (default: 0.1.0).'],
-    ['--exporter <s>', 'Exporter id recorded in provenance (default: @ssss/cli).'],
+    ['--exporter <s>', `Exporter id recorded in provenance (default: ${DEFAULT_EXPORTER}).`],
     ['--ext <name>', 'Declare a required extension registry (repeatable).'],
     ['--exported-at <iso>', 'Override the export timestamp (default: epoch, for determinism).'],
     ['--registry <dir>', 'Registry directory (default: the package core registry).'],
@@ -50,7 +50,7 @@ export async function run(argv) {
       name: flags.name || path.basename(path.resolve(vault)),
       description: flags.description || '',
       version: flags['bundle-version'] || '0.1.0',
-      exporter: flags.exporter || '@ssss/cli',
+      exporter: flags.exporter || DEFAULT_EXPORTER,
       requiredExtensions: flags.ext || [],
       ...(flags['exported-at'] ? { exportedAt: flags['exported-at'] } : {}),
     });

package/scripts/cmd-localize.mjs

@@ -0,0 +1,44 @@
+/** `ssss localize` — materialize a non-destructive locale projection. */
+import path from 'node:path';
+import { materializeLocale } from '../src/semantic.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = usage({
+  summary: 'Materialize approved translation overlays as a derived vault projection (spec §11.9).',
+  usage: 'ssss localize <vault-dir> --locale <tag> --out <empty-dir> [options]',
+  options: [
+    ['--locale <tag>', 'Required BCP47-style target locale.'],
+    ['--out <dir>', 'Required empty directory outside the source vault.'],
+    ['--include-private', 'Explicitly include private/resource-bound source documents.'],
+    ['--include-drafts', 'Allow non-approved translation overlays.'],
+    ['--registry <dir>', 'Registry directory (default: package registry).'],
+  ],
+  examples: [
+    'ssss localize ./vault --locale es --out ./derived/es',
+  ],
+  seeAlso: ['ssss semantic', 'ssss help localization'],
+});
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const { positionals, flags } = parseArgs(argv, {
+    booleans: ['include-private', 'include-drafts'],
+  });
+  const vault = positionals[0];
+  if (!vault || !flags.locale || !flags.out) die('localize requires a vault, --locale, and --out.\n\n' + HELP);
+  try {
+    const manifest = materializeLocale(
+      path.resolve(vault),
+      flags.locale,
+      path.resolve(flags.out),
+      {
+        includePrivate: !!flags['include-private'],
+        includeDrafts: !!flags['include-drafts'],
+        registryDir: flags.registry,
+      }
+    );
+    process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+  } catch (error) {
+    die(error.message);
+  }
+}

package/scripts/cmd-semantic.mjs

@@ -0,0 +1,88 @@
+/** `ssss semantic` — build/query a deterministic, privacy-safe semantic projection. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { buildSemanticIndex, searchSemanticIndex } from '../src/semantic.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = usage({
+  summary: 'Build or query the deterministic SSSS semantic index (spec §11.9).',
+  usage: 'ssss semantic <vault-dir> [options]',
+  options: [
+    ['--query <text>', 'Return ranked matches instead of the entire index.'],
+    ['--locale <tag>', 'Apply approved translation overlays for this locale.'],
+    ['--type <name>', 'Restrict query results to a primitive type (repeatable).'],
+    ['--limit <n>', 'Maximum query results (default: 10).'],
+    ['--include-private', 'Explicitly include tenant_private/resource_bound documents.'],
+    ['--include-drafts', 'Allow non-approved translation overlays.'],
+    ['--registry <dir>', 'Registry directory (default: package registry).'],
+    ['--out <file>', 'Write JSON outside the vault instead of stdout.'],
+  ],
+  examples: [
+    'ssss semantic ./vault --query "refund policy"',
+    'ssss semantic ./vault --locale es --out ./derived/semantic-es.json',
+  ],
+  seeAlso: ['ssss localize', 'ssss help semantic', 'ssss help localization'],
+});
+
+function physicalTarget(value) {
+  const requested = path.resolve(value);
+  let cursor = requested;
+  const suffix = [];
+  while (!fs.existsSync(cursor)) {
+    suffix.unshift(path.basename(cursor));
+    cursor = path.dirname(cursor);
+  }
+  return path.join(fs.realpathSync(cursor), ...suffix);
+}
+
+function writeOutsideVault(vault, output, content) {
+  const source = fs.realpathSync(path.resolve(vault));
+  const target = physicalTarget(output);
+  if (target === source || target.startsWith(source + path.sep)) {
+    throw new Error('Semantic projections must be written outside the source vault.');
+  }
+  if (fs.existsSync(target) && (fs.lstatSync(target).isSymbolicLink() || fs.statSync(target).isDirectory())) {
+    throw new Error(`Output must be a regular file: ${target}`);
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${crypto.randomUUID()}.tmp`);
+  fs.writeFileSync(temporary, content);
+  fs.renameSync(temporary, target);
+  return target;
+}
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const { positionals, flags } = parseArgs(argv, {
+    booleans: ['include-private', 'include-drafts'],
+    multi: ['type'],
+  });
+  const vault = positionals[0];
+  if (!vault) die('semantic needs a vault directory.\n\n' + HELP);
+  const limit = flags.limit === undefined ? 10 : Number(flags.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) die('--limit must be an integer from 1 to 1000.');
+
+  try {
+    const index = buildSemanticIndex(path.resolve(vault), {
+      locale: flags.locale,
+      includePrivate: !!flags['include-private'],
+      includeDrafts: !!flags['include-drafts'],
+      registryDir: flags.registry,
+    });
+    const result = flags.query ? {
+      query: flags.query,
+      locale: index.locale,
+      include_private: index.include_private,
+      index_hash: index.index_hash,
+      results: searchSemanticIndex(index, flags.query, { types: flags.type, limit }),
+    } : index;
+    const json = JSON.stringify(result, null, 2) + '\n';
+    if (flags.out) {
+      const target = writeOutsideVault(vault, flags.out, json);
+      console.error(`Wrote semantic projection to ${target}`);
+    } else process.stdout.write(json);
+  } catch (error) {
+    die(error.message);
+  }
+}