@gregiteen/ssss-cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to the SSSS (Structured Semantic Syntax System) spec will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-07-10
+### Changed
+- Core registry/spec version is now `0.7`. Registry `patterns`,
+  `immutable_fields`, and `references` are enforced by the reference engine and
+  covered by the parity auditor.
+- Bundle import now preflights the complete envelope plan before committing, so a
+  late invalid document cannot leave a partial installation.
+- Bundle validation now applies all registry field constraints and returns
+  structured errors for malformed file entries instead of throwing.
+
+### Fixed
+- Bundle provenance now uses the real published package identity,
+  `@gregiteen/ssss-cli`, instead of an unavailable package alias. The
+  reference bundle derives its exporter name and version from `package.json`.
+
+### Added
+- A tracked, first-class `ssss` skill package with evidence-first canon routing,
+  a dependency-free document validator, contract reference, evals, and audit
+  prompt. The skill is included in the npm package allowlist.
+- Conformance checks that pin default and reference-bundle exporter identities
+  to current package metadata.
+- The `translation` document primitive and spec §11.9 semantic/localization
+  contract: exact-hash structural sources, immutable overlay identity, and
+  natural-language-only translated fields.
+- `@gregiteen/ssss-cli/semantic`, `ssss semantic`, and `ssss localize` for
+  deterministic Unicode search/graph projections and non-destructive localized
+  materialization through a whole-projection staging directory.
+- Fail-closed extension registry composition for malformed fields, invalid
+  regular expressions, symlinks, reserved ids, and core/sibling collisions.
+- Privacy-safe semantic defaults that exclude `tenant_private` and
+  `resource_bound` data unless explicitly requested in an authorized context.
+- Conformance fixtures 024–026 plus dedicated extension-registry,
+  semantic/localization, and expanded CLI smoke groups.
+- Offline help for semantic search and localization, plus a security/UX impact
+  report for downstream host implementers.
+
 ## [0.7.1] - 2026-07-08
 ### Fixed
 - Reduced `resource_bound` primitives to requirement declarations in `template`
@@ -62,7 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   trigger evaluation across daemon, cron, webhook, file-change, event, condition,
   and manual runtimes. Workflows own `triggers[]`; external schedulers are only
   wake-up mechanisms.
-- **`@ssss/cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
+- **`@gregiteen/ssss-cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
   `createRunEnvelope()` helpers derive `workflow_triggered` events, task
   documents, and run documents through the Operation Contract.
 - **Runtime conformance metadata/checks** — `conformance/fixtures.json` v1.3.0
@@ -79,7 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a starter `vault/` of core primitives (incl. a `tenant_private` task to demonstrate
   the sale-drop), a dependency-free conformance test (`node --test`) that replays the
   canonical fixtures through the engine and round-trips the vault as a `sale` bundle,
-  plus `package.json` (pinned to the matching `@ssss/cli` tag), `CLAUDE.md`, `README`,
+  plus `package.json` (pinned to the matching `@gregiteen/ssss-cli` tag), `CLAUDE.md`, `README`,
   and `.gitignore`. Flags: `--with-total-recall` (wire the Total Recall memory OS),
   `--install` (npm install + Total Recall init + verify), `--ref`, `--name`, `--force`,
   `--no-git`. All shelling-out uses `execFileSync` with fixed argv (no shell). Docs:
@@ -114,7 +152,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `ssss help [topic]` serving offline docs from `docs/help/` and `ssss version`. Each
   command has its own `--help`. Shared parsing/formatting in `scripts/lib/cli.mjs`.
 - **Open-source packaging** — `README.md`, `LICENSE` (ISC), `.gitignore`, and
-  `package.json` metadata (`engines`, `repository`, `files`) so `@ssss/cli` is
+  `package.json` metadata (`engines`, `repository`, `files`) so `@gregiteen/ssss-cli` is
   publishable and the runtime-read paths (`VERSION`, `docs/help`) ship in the tarball.
 
 ### Changed
@@ -133,7 +171,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the canonical Operation Contract as the fourth envelope type. Removes a replace-type file,
   rejects append-type targets, and emits a deletion event for audit. Idempotent.
 - **Reference engine (`src/engine.mjs`, `src/registry.mjs`, `src/frontmatter.mjs`)** — the
-  canonical, dependency-free `@ssss/cli` Operation Contract engine. Harvested from total-recall
+  canonical, dependency-free `@gregiteen/ssss-cli` Operation Contract engine. Harvested from total-recall
   (§6.3 pipeline, idempotency replay from the audit log, `buildRepair`/§9 repair blocks) and
   festech (`delete` envelope, `resolveContainedPath` path-traversal guard, registry-driven
   content validation). Validates content against `registry/core.json` + `registry/extensions/*`

package/README.md

@@ -4,7 +4,7 @@
 > Turn a running business into a single tradeable file — *a festival in a box.*
 
 [![conformance](https://img.shields.io/badge/conformance-fixtures%20%2B%20runtime%20%2B%20bundle-brightgreen)](conformance/)
-[![spec](https://img.shields.io/badge/spec-v0.6%20draft-blue)](docs/ssss-spec.md)
+[![spec](https://img.shields.io/badge/spec-v0.7%20draft-blue)](docs/ssss-spec.md)
 [![OKF](https://img.shields.io/badge/OKF-v0.1%20compatible-blue)](docs/ssss-spec.md)
 
 SSSS is the vendor-neutral standard and reference implementation shared by
@@ -16,6 +16,8 @@ SSSS is the vendor-neutral standard and reference implementation shared by
   `event` / `delete`) for mutating a vault, with idempotency replay and audit.
 - **The Workflow Runtime Contract** (§11.8) — workflows own triggers; daemons,
   crons, and webhooks derive idempotent event/task/run envelopes from the vault.
+- **Semantic projection and localization** (§11.9) — deterministic graph/search
+  records and hash-bound translation overlays, with private data excluded by default.
 - **Portability classification** (§5.5) — the keystone: every primitive is
   `structural`, `tenant_private`, or `resource_bound`, so a vault can be *sold*
   without leaking the operator's private data.
@@ -77,6 +79,8 @@ ssss import festival.ucw.json --vault ./new-tenant \
 | `ssss inspect <bundle>` | Human-readable summary (manifest, inventory, params, steps). |
 | `ssss provision <bundle>` | Plan an install: params + link integrity → envelopes (§17). |
 | `ssss import <bundle>` | Replay a bundle/plan into a vault via the engine (idempotent). |
+| `ssss semantic <vault>` | Build or query a deterministic, privacy-safe semantic index (§11.9). |
+| `ssss localize <vault>` | Materialize approved translations as a derived projection outside the vault. |
 | `ssss autolink [dir]` | Generate OKF wiki-links across a vault. |
 | `ssss conformance` | Run the canonical conformance suite (§12). |
 | `ssss help [topic]` | Local docs: `runtime`, `portability`, `bundle`, `provisioning`, `leases`, … |
@@ -89,6 +93,7 @@ Run `ssss <command> --help` for flags, or `ssss help <topic>` for concepts.
 import { createEngine } from '@gregiteen/ssss-cli/engine';
 import { exportBundle, validateBundle, provisionBundle, importBundle } from '@gregiteen/ssss-cli/bundle';
 import { planWorkflowTrigger } from '@gregiteen/ssss-cli/runtime';
+import { buildSemanticIndex, searchSemanticIndex, materializeLocale } from '@gregiteen/ssss-cli/semantic';
 
 const bundle = exportBundle('./my-vault', { profile: 'sale', name: 'Festival in a Box' });
 const { valid, errors } = validateBundle(bundle);
@@ -113,11 +118,20 @@ const runtimePlan = planWorkflowTrigger({
   trigger: { type: 'cron', id: 'daily-0800', cron: '0 8 * * *' },
   scheduledFor: '2026-07-02T14:00:00.000Z',
 });
+
+const index = buildSemanticIndex('./my-vault', { locale: 'es' });
+const matches = searchSemanticIndex(index, 'política de reembolsos');
+materializeLocale('./my-vault', 'es', './derived/es');
 ```
 
 Exports: `@gregiteen/ssss-cli` / `@gregiteen/ssss-cli/engine` (Operation Contract engine),
 `@gregiteen/ssss-cli/bundle` (export/provision/import), `@gregiteen/ssss-cli/registry`,
-`@gregiteen/ssss-cli/runtime`, `@gregiteen/ssss-cli/frontmatter`.
+`@gregiteen/ssss-cli/runtime`, `@gregiteen/ssss-cli/semantic`,
+`@gregiteen/ssss-cli/frontmatter`.
+
+Translations are structural overlay documents that target an exact source hash. Only
+`title`, `description`, and body are translated; types, ids, permissions, enums,
+relations, and other control fields remain sourced from the canonical document.
 
 ## Portability — why a vault is safe to sell
 
@@ -144,17 +158,19 @@ npm test                    # == ssss conformance --engine
 ## Repository layout
 
 ```
-docs/ssss-spec.md          The normative specification (v0.6 draft).
+docs/ssss-spec.md          The normative specification (v0.7 draft).
 docs/help/                 Topic docs surfaced by `ssss help`.
-registry/core.json         14 document + 5 contract primitives; bundle & provisioning schemas.
+registry/core.json         15 document + 5 contract primitives; semantic, bundle & provisioning schemas.
 registry/extensions/       Application extension registries (e.g. festech).
 src/engine.mjs             Operation Contract engine (§6).
 src/runtime.mjs            Workflow trigger → event/task/run envelope planning (§11.8).
+src/semantic.mjs           Deterministic semantic index + localization projection (§11.9).
 src/bundle.mjs             export / validate / provision / import (§16–§17).
 src/registry.mjs           Registry-driven type + portability resolution.
 src/frontmatter.mjs        Zero-dependency YAML frontmatter.
 scripts/ssss.mjs           The `ssss` CLI dispatcher.
 conformance/               Canonical fixtures + reference bundle.
+skills/ssss/               Packaged SSSS system skill and dependency-free validator.
 ```
 
 ## License

package/VERSION

@@ -1 +1 @@
-0.7.1
+0.8.0

package/conformance/README.md

@@ -11,13 +11,13 @@ shared test suite every implementation MUST pass to claim conformance (spec §12
 |------|---------|
 | [`fixtures.json`](fixtures.json) | Canonical request/response fixtures for the Operation Contract (spec §6). |
 | [`reference-bundle.ucw.json`](reference-bundle.ucw.json) | The canonical `.ucw` reference bundle (spec §16, "Festival in a Box"). A `sale`-profile export, content-hashed; round-tripped by the runner. Rebuild with `node scripts/build-reference-bundle.mjs`. |
-| `../registry/core.json` | The 14 core document primitives + 5 contract primitives, plus the `runtime` (§11.8), `bundle` (§16), and `provisioning` (§17) schemas the standard owns. |
+| `../registry/core.json` | The 15 core document primitives + 5 contract primitives, plus `runtime` (§11.8), `semantic` (§11.9), `bundle` (§16), and `provisioning` (§17) contracts. |
 
 ## Implementations under test
 
 | Implementation | SSSS surface | Core primitives | Extensions |
 |----------------|--------------|-----------------|------------|
-| **festech.live** | `SsssOperationService` + `SsssLeaseService`, Postgres event log, ~4,024 vault files | all 14 ✓ | 118 app primitives |
+| **festech.live** | `SsssOperationService` + `SsssLeaseService`, Postgres event log, ~4,024 vault files | integration audit required for core v0.7 | 118 app primitives |
 | **ultrachat** | SQL `ssss_core_contract` + hardening migrations, `SsssApiClient`, ~1,110 vault files | (audit pending) | app primitives |
 | **total-recall** | Markdown-native kernel, `validate-schema.mjs`, memory vault | memory-centric subset | memory categories |
 
@@ -32,8 +32,10 @@ npx ssss conformance --endpoint <url> --token <pat>   # run fixtures against a l
 The runner validates that the fixture file is well-formed and that every
 `expected_response` is internally consistent with the envelope rules. With
 `--engine`, it replays every fixture through the reference engine (`src/engine.mjs`),
-checks workflow runtime planning (`src/runtime.mjs`, spec §11.8), runs regression
-coverage for patch serialization and leases (§6/§7), and round-trips the
+checks workflow runtime planning (`src/runtime.mjs`, spec §11.8), extension-registry
+collision/schema/symlink safety, semantic search and localization (`src/semantic.mjs`,
+§11.9), runs regression coverage for patch serialization and leases (§6/§7), and
+round-trips the
 reference bundle (validate → provision → import → re-import, spec §16/§17)
 against a temp vault — proving idempotency, strict bundle shape validation, and
 that no `tenant_private` or seller-bound `resource_bound` value ever lands. With
@@ -42,18 +44,20 @@ endpoint and diffs the response.
 
 ## Core vs. extension registry
 
-The standard owns only the **core**: the 14 document primitives and 5 contract
+The standard owns only the **core**: the 15 document primitives and 5 contract
 primitives in [`../registry/core.json`](../registry/core.json), plus the `runtime`
-(§11.8), `bundle` (§16), and `provisioning` (§17) schemas. Every conformant
+(§11.8), `semantic` (§11.9), `bundle` (§16), and `provisioning` contracts. Every conformant
 implementation maps to the same core.
 
 Applications **extend** the core with their own primitives (festech has 118 —
 `meeting`, `phone_number`, `inventory_item`, `language_convention`, …). Extensions:
 
 - MUST NOT redefine or shadow a core type.
+- MUST NOT redefine a type from a sibling extension.
+- MUST be regular, non-symlinked JSON files with valid regex patterns and field lists.
 - Live in the application's own extension registry, not here.
 - SHOULD follow the same schema shape as core entries (`required_fields`,
-  `append_only`, enums) so the same validator handles them.
+  `append_only`, enums, patterns, immutable fields, references) so the same validator handles them.
 
 ## ⚠️ Open reconciliation items (spec ⇄ implementation drift)
 

package/conformance/fixtures.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ssss.dev/conformance/v1",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Canonical SSSS Operation Contract conformance fixtures. These define the canonical request/response shapes for the Operation Contract (spec §6) and are the shared test contract every SSSS implementation MUST pass. A host is conformant only if, for every fixture, it produces the expected response and status code (spec §12).",
   "spec_url": "../docs/ssss-spec.md",
   "operation_types": {
@@ -86,6 +86,9 @@
       "Required fields for each primitive type must be present and non-empty",
       "required_when-conditional fields must be present when their condition matches (spec §9)",
       "Fields with a registry-declared enum must take one of the declared values",
+      "Fields with a registry-declared pattern must match it",
+      "Registry-declared immutable fields cannot change through operation replacement or patch",
+      "Registry-declared document references must be safe, resolvable, type/portability-compatible, and hash-valid",
       "See /api/v1/ssss/schema for the full type schema definitions"
     ],
     "authorization": [
@@ -741,6 +744,69 @@
         }
       },
       "expected_http_status": 409
+    },
+    {
+      "id": "fixture-024",
+      "name": "Translation source — valid structural rule",
+      "description": "Creates the exact structural source used by the translation overlay fixtures.",
+      "request": {
+        "type": "operation",
+        "idempotency_key": "35353535-3535-3535-3535-353535353535",
+        "path": "rules/translatable-refund-rule.md",
+        "workspace_id": "TEST_WORKSPACE_ID",
+        "actor": { "role": "system" },
+        "content": "---\ntype: rule\ntitle: \"Translatable Refund Rule\"\ndescription: \"Structural source used by the translation conformance fixture.\"\ntimestamp: \"2026-07-10T00:00:00Z\"\nname: \"Translatable Refund Rule\"\n---\nRefunds are available before the deadline.",
+        "intent": "Conformance fixture: create a structural translation source"
+      },
+      "expected_response": {
+        "success": true,
+        "type": "operation",
+        "validation": { "valid": true, "type": "rule", "errors": [] }
+      }
+    },
+    {
+      "id": "fixture-025",
+      "name": "Translation overlay — valid hash-bound Spanish projection",
+      "description": "A translation overlay with a safe source path, exact source hash, valid locale, and approved translatable fields must validate.",
+      "preconditions": ["fixture-024 must be committed first"],
+      "request": {
+        "type": "operation",
+        "idempotency_key": "36363636-3636-3636-3636-363636363636",
+        "path": "translations/es/rules/translatable-refund-rule.md",
+        "workspace_id": "TEST_WORKSPACE_ID",
+        "actor": { "role": "system" },
+        "content": "---\ntype: translation\ntitle: \"Spanish Refund Rule Translation\"\ndescription: \"Approved Spanish translation overlay conformance fixture.\"\ntimestamp: \"2026-07-10T00:00:00Z\"\ntranslation_id: translatable-refund-rule-es\nsource_path: rules/translatable-refund-rule.md\nsource_hash: sha256:bc61f36adc3aa1fa2c4da7a48841cb16bc56df0ec052f70d4ee8514a98dc6e62\nlocale: es\nstatus: approved\ntranslated_fields: [title, body]\ntranslated_title: Regla de reembolsos traducible\n---\nLos reembolsos están disponibles antes de la fecha límite.",
+        "intent": "Conformance fixture: valid translation primitive"
+      },
+      "expected_response": {
+        "success": true,
+        "type": "operation",
+        "validation": { "valid": true, "type": "translation", "errors": [] }
+      }
+    },
+    {
+      "id": "fixture-026",
+      "name": "Translation overlay — invalid locale is denied",
+      "description": "Registry pattern enforcement rejects non-BCP47 locale syntax before an invalid overlay can enter the vault.",
+      "preconditions": ["fixture-024 must be committed first"],
+      "request": {
+        "type": "operation",
+        "idempotency_key": "37373737-3737-3737-3737-373737373737",
+        "path": "translations/invalid/rules/translatable-refund-rule.md",
+        "workspace_id": "TEST_WORKSPACE_ID",
+        "actor": { "role": "system" },
+        "content": "---\ntype: translation\ntitle: \"Invalid Locale Translation\"\ndescription: \"Translation fixture that must be rejected.\"\ntimestamp: \"2026-07-10T00:00:00Z\"\ntranslation_id: invalid-locale-translation\nsource_path: rules/translatable-refund-rule.md\nsource_hash: sha256:bc61f36adc3aa1fa2c4da7a48841cb16bc56df0ec052f70d4ee8514a98dc6e62\nlocale: not_a_locale\nstatus: approved\ntranslated_fields: [title]\ntranslated_title: Invalid\n---\nInvalid.",
+        "intent": "Conformance fixture: invalid translation locale"
+      },
+      "expected_response": {
+        "success": false,
+        "validation": {
+          "valid": false,
+          "type": "translation",
+          "errors": ["Invalid format for field 'locale' on type 'translation'."]
+        }
+      },
+      "expected_http_status": 422
     }
   ],
   "error_codes": {
@@ -759,5 +825,5 @@
   ],
   "maintained_by": "SSSS standard (canonical: this repo)",
   "provenance": "Seeded from the festech.live reference implementation, which authored the original shared contract; canonicalized here as the vendor-neutral source of truth.",
-  "last_updated": "2026-07-02"
+  "last_updated": "2026-07-10"
 }

package/conformance/reference-bundle.ucw.json

@@ -4,7 +4,7 @@
     "description": "A complete music-festival operation as a tradeable SSSS bundle.",
     "version": "1.0.0",
     "exported_at": "1970-01-01T00:00:00.000Z",
-    "ssss_core_version": "0.6",
+    "ssss_core_version": "0.7",
     "required_extensions": [
       "festech"
     ],
@@ -15,6 +15,7 @@
       "page": 1,
       "security_role": 1,
       "rule": 1,
+      "translation": 1,
       "workflow": 1
     },
     "provisioning": [
@@ -85,10 +86,10 @@
         "description": "Satisfies the domain resource requirement field 'registrar'."
       }
     ],
-    "file_count": 14,
+    "file_count": 18,
     "provenance": {
-      "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@ssss/cli@0.7.0"
+      "content_hash": "sha256:27c7c21826552f73dd14a56018454f4c19bda002029d5db42ecb14d77667b699",
+      "exporter": "@gregiteen/ssss-cli@0.8.0"
     }
   },
   "files": [
@@ -140,6 +141,22 @@
       "path": "tasks/index.md",
       "content": "# Index — tasks\n\n- [Ticket 4821 Seat Change](./ticket-4821.md)\n"
     },
+    {
+      "path": "translations/es/index.md",
+      "content": "# Index — translations/es\n\n- [rules/](./rules/index.md)\n"
+    },
+    {
+      "path": "translations/es/rules/index.md",
+      "content": "# Index — translations/es/rules\n\n- [Spanish Refund Policy Translation](./refund-policy.md)\n"
+    },
+    {
+      "path": "translations/es/rules/refund-policy.md",
+      "content": "---\ntype: translation\ntitle: Spanish Refund Policy Translation\ndescription: Approved Spanish presentation overlay for the festival refund policy.\ntimestamp: 2026-07-10T00:00:00Z\ntranslation_id: refund-policy-es\nsource_path: rules/refund-policy.md\nsource_hash: sha256:a5f97ef9e2cc143d397f87a96c7fc20f4a3cd0515835c2ab659c9ac6db0d07e3\nlocale: es\nstatus: approved\ntranslated_fields: [title, description, body]\ntranslated_title: Política de reembolsos\ntranslated_description: Explica cuándo están disponibles los reembolsos para asistentes.\n---\nLos reembolsos están disponibles hasta catorce días antes del evento."
+    },
+    {
+      "path": "translations/index.md",
+      "content": "# Index — translations\n\n- [es/](./es/index.md)\n"
+    },
     {
       "path": "workflows/box-office.md",
       "content": "---\ntype: workflow\ntitle: Box Office\ndescription: Ticket-sales workflow for a music festival.\ntimestamp: 2026-07-02T00:00:00Z\nname: Box Office\nslug: box-office\n---\nSell tickets, then hand the buyer to [[concierge]] for questions."

package/docs/help/bundle.md

@@ -13,7 +13,7 @@ integrity. The container file is conventionally named `*.ucw.json`.
     "description": "...",
     "version": "0.1.0",
     "exported_at": "1970-01-01T00:00:00.000Z",   // frozen → deterministic export
-    "ssss_core_version": "0.6",
+    "ssss_core_version": "0.7",
     "required_extensions": ["festech"],
     "export_profile": "sale",                      // backup | template | sale
     "primitive_inventory": { "workflow": 1, "page": 1, "rule": 1, "assistant": 1, "domain": 1 },
@@ -22,7 +22,7 @@ integrity. The container file is conventionally named `*.ucw.json`.
     "file_count": 5,
     "provenance": {
       "content_hash": "sha256:…",                  // over the canonical file serialization
-      "exporter": "@ssss/cli"
+      "exporter": "@gregiteen/ssss-cli"
     }
   },
   "files": [ { "path": "rules/refund-policy.md", "content": "---\n…" } ]
@@ -36,6 +36,10 @@ of `files`. `ssss validate` recomputes it and rejects any mismatch — a bundle
 be silently edited. `primitive_inventory` is registry-driven (a count per `type`),
 not a closed category enum.
 
+Bundle validation also applies registry patterns and document-reference rules.
+For example, a `translation` entry must name an included structural source and
+its `source_hash` must match that source's exact bytes.
+
 ## Parameters
 
 Each entry in `parameters[]` is a template variable resolved at provision time:

package/docs/help/import.md

@@ -12,6 +12,8 @@ ssss import --plan plan.json   --vault <dir>     # replay a plan from `ssss prov
 - `--vault <dir>` is required and is created if missing.
 - Without `--plan`, import provisions inline first (resolving `--param` flags); a
   failed provision (unresolved params / dangling links) aborts before any write.
+- The engine preflights every envelope in the plan before the first commit. A
+  late schema, reference, or authorization failure cannot leave a partial import.
 - `--dry-run` validates every envelope without committing and reports
   `would commit` instead of `committed`.
 - The normal summary reports `committed`, `unchanged (idempotent)`, and `failed`

package/docs/help/localization.md

@@ -0,0 +1,43 @@
+# Localization and translation overlays (spec §5.4, §11.9)
+
+A `translation` is a structural overlay for one exact source document. It never
+forks the source or translates symbolic control fields.
+
+```yaml
+---
+type: translation
+title: "Política de reembolsos — español"
+description: "Traducción al español."
+timestamp: 2026-07-10T00:00:00Z
+translation_id: refund-policy-es
+source_path: rules/refund-policy.md
+source_hash: sha256:<hash-of-current-source-bytes>
+locale: es
+status: approved
+translated_fields: [title, description, body]
+translated_title: "Política de reembolsos"
+translated_description: "Reglas de reembolso para compradores."
+---
+
+Contenido traducido.
+```
+
+Only `title`, `description`, and body may change. `type`, ids, status values,
+permissions, relations, portability, and every other control field remain canonical.
+The engine rejects stale source hashes, missing or private sources, traversal,
+symlinks, recursive translation, and changes to immutable overlay identity.
+
+Draft and reviewed overlays are retained for workflow, but normal localization uses
+approved overlays only. Use `--include-drafts` only for an explicit preview.
+
+```bash
+ssss localize ./vault --locale es --out ./derived/es
+```
+
+The output must be a new or empty, non-symlinked directory outside the source vault.
+It preserves source-relative paths, excludes private/resource-bound documents by
+default, and writes `.ssss-projection.json` so the derived result is auditable and
+rebuildable.
+
+Use `ssss semantic ./vault --locale es` to query localized surfaces without
+materializing files. See also: `ssss help semantic`.

package/docs/help/overview.md

@@ -5,16 +5,18 @@ and mutation contract for AI-agent state. A vault is a directory of Markdown fil
 with YAML frontmatter; every file declares a `type` defined in the registry.
 
 `@gregiteen/ssss-cli` is the reference implementation: a dependency-free Operation Contract
-engine, a registry-driven validator, and the `.ucw` bundle/provisioning tooling.
+engine, a registry-driven validator, semantic/localization projections, and the
+`.ucw` bundle/provisioning tooling.
 
 ## The pieces
 
 | Piece | Where | What it is |
 |-------|-------|------------|
 | Spec | `docs/ssss-spec.md` | The normative standard. |
-| Core registry | `registry/core.json` | The 14 document primitives + 5 contract primitives, plus the bundle (§16) and provisioning (§17) schemas. |
+| Core registry | `registry/core.json` | The 15 document primitives + 5 contract primitives, plus semantic (§11.9), bundle (§16), and provisioning (§17) contracts. |
 | Engine | `src/engine.mjs` | The §6 Operation Contract pipeline (operation/patch/event/delete). |
 | Runtime | `src/runtime.mjs` | The §11.8 workflow trigger → event/task/run envelope planner. |
+| Semantic | `src/semantic.mjs` | Deterministic semantic graph/search projection and translation overlays (§11.9). |
 | Bundle | `src/bundle.mjs` | export / validate / provision / import (§16–§17). |
 | Conformance | `conformance/` | Fixtures every host must pass. |
 
@@ -28,6 +30,8 @@ vault ──export──▶ .ucw bundle ──provision──▶ envelope plan
 ## Commands
 
 Run `ssss help <topic>` for any of:
-`runtime`, `portability`, `bundle`, `provisioning`, `export`, `provision`, `import`, `conformance`, `autolink`.
+`runtime`, `semantic`, `localization`, `portability`, `bundle`, `provisioning`,
+`export`, `provision`, `import`, `conformance`, `autolink`.
 
-Run `ssss <command> --help` for: `export`, `validate`, `inspect`, `provision`, `import`, `autolink`, `conformance`.
+Run `ssss <command> --help` for: `export`, `validate`, `inspect`, `provision`,
+`import`, `semantic`, `localize`, `autolink`, `conformance`.

package/docs/help/semantic.md

@@ -0,0 +1,37 @@
+# Semantic projection (spec §11.9)
+
+SSSS builds a deterministic search and graph projection directly from validated
+Markdown. The projection is disposable: the vault remains the only source of truth.
+
+```bash
+ssss semantic ./vault
+ssss semantic ./vault --query "refund policy" --limit 5
+ssss semantic ./vault --locale es --query "política de reembolsos"
+ssss semantic ./vault --locale es --out ./derived/semantic-es.json
+```
+
+Records include stable identity, source path and hash, type, portability, surface
+text, normalized Unicode tokens, and graph edges derived from `relations`, wiki
+links, and Markdown links. Results use deterministic weighted lexical ranking; hosts
+may fuse embeddings without replacing this interoperable baseline.
+
+## Privacy and output safety
+
+Only `structural` documents are indexed by default. `tenant_private` and
+`resource_bound` sources require the explicit `--include-private` option and an
+authorized caller. This option can expose customer or operational data; never enable
+it for a public index.
+
+`--out` must point to a regular file outside the source vault. Writes are atomic.
+Symlinked vault entries and unsafe paths fail closed.
+
+## Library API
+
+```js
+import { buildSemanticIndex, searchSemanticIndex } from '@gregiteen/ssss-cli/semantic';
+
+const index = buildSemanticIndex('./vault', { locale: 'es' });
+const results = searchSemanticIndex(index, 'reembolsos', { limit: 10 });
+```
+
+See also: `ssss help localization`.