total-recall-brain 3.10.0 → 3.11.0

package/bin/antigravity.mjs

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
+// Antigravity CLI Agent Wrapper — routes through the running Antigravity IDE
+// via agentapi, using the user's logged-in Google account.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { spawnSync } from 'node:child_process';
 
 const args = process.argv.slice(2);
 let prompt = '';
 let outputJson = false;
-let requestedModel = process.env.TR_CLI_MODEL || 'default';
+let requestedModel = process.env.TR_CLI_MODEL || 'flash';
 
 if (args.includes('-h') || args.includes('--help')) {
   console.log(`
-Antigravity CLI Agent Wrapper — Headless Zero-Dependency Cognitive Agent
+Antigravity CLI Agent Wrapper — Headless via agentapi (logged-in account)
 
 Usage:
   antigravity [options] [prompt]
@@ -19,39 +22,30 @@ Usage:
 
 Options:
   -p, --prompt    The text prompt to generate content for
-  -m, --model     Gemini API model identifier or alias (default: default / gemini-3.5-flash)
-                  Supported aliases:
-                    - default / gemini / flash / gemini-flash -> dynamically resolves best Flash model
-                    - pro / gemini-pro / 3.1-pro             -> dynamically resolves best Pro model
-  -o, --json      Output dynamic JSON response payload (choices: stream/json/default)
-  --json          Output dynamic JSON response payload
+  -m, --model     Model: flash_lite, flash, pro (default: flash)
+  -o json         Output JSON response payload
+  --json          Output JSON response payload
   -h, --help      Show this help information
-
-Examples:
-  antigravity "Say hello"
-  antigravity -p "Write an essay about AI" -m pro
-  antigravity -p "Get system stats" --json
 `);
   process.exit(0);
 }
 
+// Ignored flags for compatibility with tr-cli-agents dispatch
+const IGNORED = new Set(['--sandbox=false', '--yolo']);
+
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '-p' || args[i] === '--prompt') {
-    prompt = args[i + 1] || '';
-    i++;
-  } else if (args[i] === '-o' && args[i + 1] === 'json') {
-    outputJson = true;
-    i++;
-  } else if (args[i] === '--json') {
-    outputJson = true;
-  } else if (args[i] === '-m' || args[i] === '--model') {
-    requestedModel = args[i + 1] || requestedModel;
-    i++;
-  }
+  if (IGNORED.has(args[i])) continue;
+  if (args[i] === '-p' || args[i] === '--prompt') { prompt = args[i + 1] || ''; i++; }
+  else if (args[i] === '-o' && args[i + 1] === 'json') { outputJson = true; i++; }
+  else if (args[i] === '--json') { outputJson = true; }
+  else if (args[i] === '-m' || args[i] === '--model') { requestedModel = args[i + 1] || requestedModel; i++; }
 }
 
 if (!prompt && args.length > 0) {
-  prompt = args[args.length - 1];
+  // Last non-flag arg is the prompt
+  for (let i = args.length - 1; i >= 0; i--) {
+    if (!args[i].startsWith('-') && !IGNORED.has(args[i])) { prompt = args[i]; break; }
+  }
 }
 
 if (!prompt) {
@@ -59,165 +53,50 @@ if (!prompt) {
   process.exit(1);
 }
 
-// Robust fallback to load GOOGLE_API_KEY from .env files when executed standalone
-if (!process.env.GOOGLE_API_KEY) {
-  try {
-    let dir = process.cwd();
-    while (dir !== path.dirname(dir)) {
-      const envPath = path.join(dir, '.env');
-      if (fs.existsSync(envPath)) {
-        const content = fs.readFileSync(envPath, 'utf8');
-        for (const line of content.split('\n')) {
-          const match = line.match(/^\s*GOOGLE_API_KEY\s*=\s*(["']?)(.*?)\1\s*$/);
-          if (match) {
-            process.env.GOOGLE_API_KEY = match[2];
-            break;
-          }
-        }
-      }
-      if (process.env.GOOGLE_API_KEY) break;
-      dir = path.dirname(dir);
-    }
-  } catch {
-    // Silent ignore
-  }
+// Map model aliases
+const modelMap = {
+  default: 'flash', gemini: 'flash', 'gemini-flash': 'flash',
+  'gemini-3.5-flash': 'flash', '3.5-flash': 'flash',
+  pro: 'pro', 'gemini-pro': 'pro', '3.1-pro': 'pro',
+  lite: 'flash_lite', 'flash-lite': 'flash_lite',
+};
+const model = modelMap[requestedModel] || requestedModel;
+
+// Spawn agentapi new-conversation and capture the response
+const result = spawnSync('agentapi', [
+  'new-conversation',
+  `--model=${model}`,
+  '--title=antigravity-cli',
+  prompt,
+], {
+  encoding: 'utf8',
+  timeout: 300_000,
+  maxBuffer: 10 * 1024 * 1024,
+  env: process.env,
+});
+
+if (result.status !== 0) {
+  const err = result.stderr || result.stdout || 'agentapi failed';
+  console.error('Error:', err);
+  process.exit(1);
 }
 
-const apiKey = process.env.GOOGLE_API_KEY || '';
-if (!apiKey) {
-  console.warn('Warning: GOOGLE_API_KEY environment variable is not configured. Attempting connection via GCP Application Default Credentials or ambient environment...');
+const raw = result.stdout?.trim() || '';
+
+// Parse agentapi response
+let text = raw;
+try {
+  const parsed = JSON.parse(raw);
+  // agentapi returns { response: { conversationId, content } }
+  if (parsed.response?.content) text = parsed.response.content;
+  else if (parsed.content) text = parsed.content;
+  else if (parsed.response) text = typeof parsed.response === 'string' ? parsed.response : JSON.stringify(parsed.response);
+} catch {
+  // Not JSON, use raw output
 }
 
-// Resolve the model dynamically from the API registry based on the category/alias selected
-async function resolveGenerativeModel(selectedModel) {
-  const aliases = {
-    gemini: 'flash',
-    default: 'flash',
-    flash: 'flash',
-    'gemini-flash': 'flash',
-    '3.5-flash': 'flash',
-    pro: 'pro',
-    'gemini-pro': 'pro',
-    '3.1-pro': 'pro'
-  };
-
-  const category = aliases[selectedModel];
-  if (!category) {
-    // If it's a full model string, use it directly
-    return selectedModel;
-  }
-
-  try {
-    const keyParam = apiKey ? `key=${apiKey}` : '';
-    const headers = {};
-    if (!apiKey && process.env.GCLOUD_TOKEN) {
-      headers['Authorization'] = `Bearer ${process.env.GCLOUD_TOKEN}`;
-    }
-    const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models?${keyParam}`, {
-      headers,
-      signal: AbortSignal.timeout(5000)
-    });
-    if (res.ok) {
-      const data = await res.json();
-      const models = data.models || [];
-      
-      if (category === 'pro') {
-        const proPreferences = [
-          'gemini-3.1-pro-preview',
-          'gemini-2.5-pro',
-          'gemini-1.5-pro',
-          'gemini-pro-latest'
-        ];
-        for (const p of proPreferences) {
-          if (models.some(m => m.name === `models/${p}`)) {
-            return p;
-          }
-        }
-      } else {
-        const flashPreferences = [
-          'gemini-3.5-flash',
-          'gemini-3.1-flash-lite',
-          'gemini-2.5-flash',
-          'gemini-2.0-flash-lite',
-          'gemini-flash-latest'
-        ];
-        for (const p of flashPreferences) {
-          if (models.some(m => m.name === `models/${p}`)) {
-            return p;
-          }
-        }
-      }
-    }
-  } catch {
-    // Silent failover to hardcoded default targets
-  }
-
-  // Ultimate fallback
-  return category === 'pro' ? 'gemini-3.1-pro-preview' : 'gemini-3.5-flash';
+if (outputJson) {
+  console.log(JSON.stringify({ response: text }));
+} else {
+  console.log(text);
 }
-
-async function main() {
-  try {
-    const resolvedModel = await resolveGenerativeModel(requestedModel);
-    const keyParam = apiKey ? `?key=${apiKey}` : '';
-    const url = `https://generativelanguage.googleapis.com/v1beta/models/${resolvedModel}:generateContent${keyParam}`;
-
-    const headers = {
-      'Content-Type': 'application/json',
-    };
-    if (!apiKey && process.env.GCLOUD_TOKEN) {
-      headers['Authorization'] = `Bearer ${process.env.GCLOUD_TOKEN}`;
-    }
-
-    const res = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({
-        contents: [{
-          parts: [{ text: prompt }]
-        }]
-      })
-    });
-
-    if (!res.ok) {
-      const errText = await res.text();
-      throw new Error(`Gemini API returned status ${res.status}: ${errText}`);
-    }
-
-    const data = await res.json();
-    const text = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
-
-    // Save usage data for token monitoring/budget safety
-    try {
-      const promptTokens = data.usageMetadata?.promptTokenCount || 0;
-      const candidatesTokens = data.usageMetadata?.candidatesTokenCount || 0;
-      if (promptTokens > 0 || candidatesTokens > 0) {
-        const tmpDir = path.join(os.homedir(), '.gemini', 'tmp', 'antigravity', 'chats');
-        if (!fs.existsSync(tmpDir)) {
-          fs.mkdirSync(tmpDir, { recursive: true });
-        }
-        const usageLine = JSON.stringify({
-          timestamp: new Date().toISOString(),
-          tokens: {
-            input: promptTokens,
-            output: candidatesTokens
-          }
-        });
-        fs.appendFileSync(path.join(tmpDir, 'usage.jsonl'), usageLine + '\n', 'utf8');
-      }
-    } catch {
-      // Silent ignore
-    }
-
-    if (outputJson) {
-      console.log(JSON.stringify({ response: text }));
-    } else {
-      console.log(text);
-    }
-  } catch (err) {
-    console.error('Error calling Gemini API:', err.message);
-    process.exit(1);
-  }
-}
-
-main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
   "type": "module",
   "bin": {
@@ -56,7 +56,7 @@
   },
   "homepage": "https://github.com/gregiteen/total-recall#readme",
   "dependencies": {
-    "@ssss/cli": "github:gregiteen/ssss#v0.4.0",
+    "@ssss/cli": "github:gregiteen/ssss#v0.7.0",
     "bcrypt": "^6.0.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",

package/scaffold/.agent/skills/total-recall/skills/tr-ssss/SKILL.md

@@ -14,15 +14,17 @@ schema/reference files.
 ## Ground Truth
 
 The vendor-neutral contract is now a published package, **`@ssss/cli`** (pinned to
-**`v0.4.0`**; source <https://github.com/gregiteen/ssss>), declared in
+**`v0.7.0`**, spec v0.6 draft; source <https://github.com/gregiteen/ssss>), declared in
 `package.json`. `references/ssss-spec.md` is the local mirror. The canon owns the
-spec (§5.5 portability, §6 Operation Contract incl. `delete`, §16 the `.ucw` bundle
-format, §17 provisioning), the core registry (`@ssss/cli/registry/core.json`: 13
-document + 5 contract primitives), the reference engine, and the conformance
-fixtures. Total Recall's kernel was the engine the canon's reference implementation
-was harvested from; keep them aligned. If this skill conflicts with the canon,
-correct this skill unless the implementation has intentionally advanced beyond it
-and the difference is documented here.
+spec (§4.2 universal OKF-compatible frontmatter, §5.5 portability, §6 Operation
+Contract incl. `event` and `delete`, §11.8 workflow runtime daemon contract, §16
+the `.ucw` bundle format, §17 provisioning), the core
+registry (`@ssss/cli/registry/core.json`: 14 document + 5 contract primitives),
+the reference engine, runtime helpers, and the v1.4.0 conformance fixtures. Total
+Recall's kernel was the engine the canon's reference implementation was harvested
+from; keep them aligned. If this skill conflicts with the canon, correct this
+skill unless the implementation has intentionally advanced beyond it and the
+difference is documented here.
 
 Current local implementation entry points:
 
@@ -41,7 +43,8 @@ Current local implementation entry points:
 It operates on a **vault directory** of Markdown files and `.ucw` bundles, using
 the canon's own reference engine — separate from this kernel's `processOperation`.
 Use it for bundle/tenant tooling and conformance; for in-kernel memory writes keep
-using `writeNodeValidated()` / `processOperation()`.
+using `writeNodeValidated()` / `processOperation()`. Use `@ssss/cli/runtime` when
+building daemon, cron, webhook, event, file-change, or agent-host wake-up loops.
 
 ```bash
 npx ssss help                  # list doc topics; e.g. `ssss help portability|bundle|provisioning`
@@ -68,7 +71,7 @@ All agent-generated mutations must flow through the SSSS operation pipeline:
 ```text
 processOperation(envelope, vaultRoot, options)
   -> envelope validation
-  -> idempotency check
+  -> idempotency replay/conflict check
   -> authorization
   -> lease validation
   -> deterministic schema validation
@@ -93,6 +96,52 @@ Total Recall implements all four canonical envelope types in
 Use `dry_run: true` for preflight validation when constructing writes from model
 output.
 
+## Universal Frontmatter / OKF
+
+SSSS v0.7.0 / spec v0.6 is an OKF-compatible Markdown contract. Every SSSS
+document primitive, including skills, memory, workflows, assistants, pages,
+models, migrations, and releases, MUST carry non-empty universal frontmatter:
+
+- `type`
+- `title`
+- `description`
+- `timestamp`
+
+Recommended OKF-compatible fields are:
+
+- `resource`
+- `tags`
+- `aliases`
+
+Primitive-specific required fields still apply on top of the universal fields.
+For example, a `workflow` still needs its workflow identity fields, and
+`schema_version: 2` memory nodes still need the knowledge-graph fields below.
+Do not "fix" OKF compatibility by weakening primitive validation; add the
+universal metadata and keep the primitive registry strict.
+
+## Security Contract
+
+The reference engine now treats path and replay safety as part of the standard:
+
+- `workspace_id`, `idempotency_key`, and `actor.role` must be safe identifiers:
+  ASCII alphanumeric start, then ASCII letters, digits, `.`, `_`, or `-`, max
+  128 characters.
+- Operation paths must be relative vault paths. Reject empty/root paths, `.`,
+  `..`, absolute paths, backslashes, null bytes, empty segments, and directory
+  targets.
+- `type` is immutable after creation. An operation or patch must not rewrite an
+  existing file from one primitive type to another.
+- Append-only primitives may only preserve existing content exactly or append
+  after the existing body plus a newline. Prefix tricks are not enough.
+- Idempotency is scoped by `workspace_id + idempotency_key + request_hash`.
+  Replaying the same effective request returns the original result; reusing the
+  same key/workspace with a different effective request is an idempotency
+  conflict and must fail.
+- Leases fail closed. Corrupt or unreadable lease state does not authorize a
+  write, and lease storage must not expose the VFS path directly.
+- Bundle import/export must reject unsafe or duplicate file paths, and exporters
+  must not follow symlinked vault entries into files outside the vault.
+
 ## Canonical State
 
 The vault is source-of-truth. Derived files, embeddings, search indexes,
@@ -158,9 +207,6 @@ SSSS schema v2. Required schema v2 knowledge-graph fields are:
 
 Invariants additionally use `priority: absolute` and `immutable: true`.
 
-### OKF Compatibility Note
-SSSS v0.2 is a strict superset of the Open Knowledge Format (OKF v0.1 Draft). SSSS memory nodes are fully OKF-compatible, as they are Markdown files containing a YAML frontmatter block with a `type` field (which maps to SSSS `category` via the OKF adapter). To bridge the format seamlessly, SSSS v0.2 extends `MemoryNodeSchema` with two optional OKF-standard fields: `description` and `resource` (supporting non-HTTP URIs such as `gs://` or `s3://`).
-
 Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
 frontmatter checks. No memory path may be committed with zero validation.
 
@@ -174,6 +220,13 @@ frontmatter checks. No memory path may be committed with zero validation.
   body records but must not rewrite prior records.
 - Events are immutable. Do not update or delete event records.
 - Leases must be time-bound, actor-owned, operation-linked, and recoverable.
+- Workflow daemons, crons, webhook workers, and agent hosts must treat workflow
+  frontmatter triggers as canonical and use deterministic runtime planning
+  (`@ssss/cli/runtime`) to derive event/task/run envelopes.
+- Bundle exporters/importers must use the canon's path, content hash,
+  portability, and provisioning validation. `template` and `sale` profiles must
+  drop every `tenant_private` primitive and reduce `resource_bound` values to
+  requirement declarations.
 
 ## Projections And Indexes
 
@@ -208,9 +261,9 @@ npx vitest run \
 The **conformance bridge** (`src/core/ssss-conformance.bridge.spec.mjs`) runs the
 canonical fixtures from `@ssss/cli` through this kernel's `processOperation` and
 asserts every canonical core primitive is present in `SSSS_SCHEMAS`. It proves the
-kernel implements the *same* standard as the festech and UltraChat hosts. If you
-change the operation contract or the registry, keep this green; to adopt a newer
-standard, bump the `@ssss/cli` pin and re-run it.
+kernel implements the *same* standard as the SSSS reference engine and host apps.
+If you change the operation contract or the registry, keep this green; to adopt a
+newer standard, bump the `@ssss/cli` pin and re-run it.
 
 ## Do Not
 
@@ -223,13 +276,18 @@ standard, bump the `@ssss/cli` pin and re-run it.
 - Do not delete append-type documents (`conversation`, `run`); they are immutable.
 - Do not add host-specific required fields to the vendor-neutral spec unless they
   are being standardized.
+- Do not claim OKF compliance unless `type`, `title`, `description`, and
+  `timestamp` are present and non-empty.
+- Do not replay idempotency keys without comparing `request_hash`.
+- Do not export symlinked vault entries or accept unsafe bundle paths.
 
 ## References
 
 | For | Read |
 | --- | --- |
-| Upstream canon (package) | `@ssss/cli` (`v0.4.0`, github:gregiteen/ssss) |
+| Upstream canon (package) | `@ssss/cli` (`v0.7.0`, spec v0.6 draft, github:gregiteen/ssss) |
 | Canonical core registry | `@ssss/cli/registry/core.json` |
+| Runtime helpers | `@ssss/cli/runtime` |
 | Conformance bridge | `src/core/ssss-conformance.bridge.spec.mjs` |
 | SSSS standard (local mirror) | `references/ssss-spec.md` |
 | Implemented schemas | `src/core/schema.mjs` |

package/scaffold/.agent/skills/total-recall/skills/tr-ssss/references/CHANGELOG.md

@@ -1,9 +1,124 @@
-# SSSS Changelog
+# Changelog
 
-## [v0.2.0] - 2026-06
-- **Changed**: Stripped product-specific primitives (`meeting`, `event`, `crm`, etc.) from the core specification to enforce vendor-neutrality. Product primitives must now live strictly in host-level registries.
-- **Added**: Upgraded Total Recall, UltraChat, and MUSE to v0.2.0 alignment.
+All notable changes to the SSSS (Structured Semantic Syntax System) spec will be documented in this file.
 
-## [v0.1.0] - 2026-05
-- Initial Draft Specification.
-- Defined VFS primitives, Operation Contract, and Append-Only Event Graph.
+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).
+
+## [0.7.0] - 2026-07-02
+### Changed
+- **BREAKING: universal frontmatter enforcement** — every SSSS document primitive
+  now requires `type`, `title`, `description`, and `timestamp`. Primitive-specific
+  required fields still apply after these universal fields.
+- Registry `spec_version` -> `0.6`; spec header -> v0.6 draft. Reference bundle
+  metadata now targets SSSS core `0.6`.
+- The reference engine, bundle validator, skill validator, runtime helpers,
+  scaffold output, conformance fixtures, shipped skills, and reference bundle now
+  share the universal metadata requirement.
+
+### Added
+- OKF compatibility guidance documenting `resource`, `tags`, and `aliases` as
+  recommended discovery enrichment fields while keeping the mandatory universal
+  metadata minimal and deterministic.
+- Security hardening for the reference engine and CLI:
+  - VFS paths now reject absolute, root, dot-segment, empty-segment, backslash,
+    and directory targets.
+  - `workspace_id`, `idempotency_key`, and role names are constrained to safe
+    filesystem identifiers.
+  - Idempotency replay is bound to a request hash; same-key/different-payload
+    requests now fail as conflicts.
+  - Leases fail closed when unreadable and no longer derive filenames directly
+    from raw VFS paths.
+  - Bundle validation rejects unsafe and duplicate file paths, and export refuses
+    symlinked vault entries.
+  - Autolink skips symlinked Markdown targets before `--write`.
+  - Repo-local skill utility scripts avoid shell-string execution and validate
+    write-target names.
+
+## [0.6.0] - 2026-07-02
+### Added
+- **Workflow Runtime & Daemon Contract (spec §11.8)** — standardizes workflow
+  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
+  `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
+  declares trigger/misfire/concurrency vocabularies and proves duplicate daemon
+  ticks replay idempotently.
+
+### Changed
+- Registry `spec_version` -> `0.5`; spec header -> v0.5 draft. Reference bundle
+  metadata now targets SSSS core `0.5`.
+
+## [0.5.0] - 2026-06-25
+### Added
+- **`ssss new <dir>` scaffolder** — bootstrap a fresh SSSS-native repo in one command:
+  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`,
+  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:
+  `ssss help scaffold`.
+
+## [0.4.0] - 2026-06-24
+### Added
+- **The `.ucw` bundle format (spec §16, registry `bundle`)** — the canonical transportable
+  package of a vault: a manifest plus path-sorted files, content-hashed for integrity. The
+  manifest declares `ssss_core_version`, `required_extensions`, `export_profile`,
+  `primitive_inventory` (registry-driven, replacing ultrachat's closed `categories` enum),
+  `provisioning[]`, `parameters[]`, and `provenance{content_hash, exporter, signature?}`.
+  Harvested from ultrachat's `WorkspaceVfsPackageService` and generalized to be portability-
+  and registry-driven.
+- **The provisioning contract (spec §17, registry `provisioning`)** — three deterministic,
+  idempotent verbs: `export` (pure, profile-filtered), `provision` (params + link-integrity
+  + id-remap → replayable envelope plan), `import` (engine replay, idempotent via
+  idempotency_key). Adopts ultrachat's `WorkspaceProvisioningStep.mode`/`system` and
+  `WorkspaceGraphEdge.relation` as the canonical binding/dependency vocabularies, plus
+  `installMode` composition and structural-only `migration`+`patch` upgrades.
+- **Reference engine for bundles (`src/bundle.mjs`)** — dependency-free `exportBundle`,
+  `validateBundle`, `provisionBundle`, `importBundle` over the registry bundle schema.
+- **Reference bundle (`conformance/reference-bundle.ucw.json`, "Festival in a Box")** — a
+  real `sale`-profile bundle, built deterministically by `scripts/build-reference-bundle.mjs`.
+  Proves the §5.5 keystone: structural + resource_bound files ship, the `tenant_private`
+  ticket record is dropped. Round-tripped (validate → provision → import → re-import) by
+  `ssss conformance --engine`; 6/6 bundle/provisioning checks pass alongside the 9 fixtures.
+- **`language_convention` documented (spec §11.7)** — the festech-shipped, `structural`
+  presentation-overlay primitive, formally placed in the semantic layer.
+- **CLI command surface for the full lifecycle** — `ssss export`, `validate`, `inspect`,
+  `provision`, and `import` wire the bundle/provisioning verbs to the command line, plus
+  `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
+  publishable and the runtime-read paths (`VERSION`, `docs/help`) ship in the tarball.
+
+### Changed
+- Registry `spec_version` → `0.4`; spec header + §14 → v0.4. Engine exports add `./bundle`.
+
+## [0.3.0] - 2026-06-24
+### Added
+- **Portability classification (spec §5.5, registry `portability`)** — every document
+  primitive now declares a portability class: `structural` (the sellable business model),
+  `tenant_private` (the operator's private data, never sold), or `resource_bound` (needs a
+  real resource bound at provision). Export profiles `backup | template | sale` are filters
+  over these classes; `template`/`sale` exports MUST drop all `tenant_private` primitives.
+  Files MAY override their type default with `x_portability`. Lifted and generalized from
+  ultrachat's ad-hoc export filter in `WorkspaceVfsPackageService`.
+- **`delete` envelope (spec §6.2)** — promoted from festech's `SsssOperationService` into
+  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
+  (§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/*`
+  with no per-type code and no Zod/YAML dependency. Runs all 9 conformance fixtures in-process
+  via `ssss conformance --engine` (now wired into `npm test`).
+
+### Changed
+- Registry now defines **5 contract primitives** (added `delete`); `spec_version` → `0.3`.
+- §5.1 Document Primitives table gains a **Portability** column.