@gregiteen/ssss-cli 0.7.0

package/scripts/autolink.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * ssss autolink — OKF wiki-autolinker for an SSSS vault.
+ *
+ * Two layers, by design (mirrors the SSSS thesis: semantics enriches at
+ * authoring time; the deterministic contract is never touched):
+ *
+ *   1. Deterministic core (default, no network): links exact surface forms —
+ *      every primitive's `title`, `aliases`, `name`, and `slug` — using
+ *      absolute bundle-relative paths (spec §4.3). Code spans/blocks, existing
+ *      links, headings, and URLs are protected. First occurrence per target
+ *      only. Idempotent: re-running adds nothing.
+ *
+ *   2. Semantic layer (--semantic, uses the Anthropic API): links by MEANING —
+ *      a body that talks about "writing files atomically" links to the
+ *      `prefer-atomic-writes` memory even with no exact title match. This is the
+ *      core SSSS promise (meaning over surface tokens) applied to linking.
+ *
+ * SAFE BY DEFAULT: prints a plan and writes nothing unless --write is given.
+ *
+ * Usage:
+ *   ssss autolink [dir] [--write] [--semantic] [--model <id>]
+ *                 [--max-per-target N] [--min-len N] [--index]
+ *                 [--include-headings] [--concurrency N]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ─── args ────────────────────────────────────────────────────────────────────
+function parseArgs() {
+  let a = process.argv.slice(2);
+  if (a[0] === 'autolink') a = a.slice(1); // reached via the `ssss` dispatcher
+  const o = {
+    dir: process.cwd(), write: false, semantic: false,
+    model: 'claude-haiku-4-5', maxPerTarget: 1, minLen: 3,
+    index: false, includeHeadings: false, concurrency: 4
+  };
+  const pos = [];
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    if (x === '--write') o.write = true;
+    else if (x === '--semantic') o.semantic = true;
+    else if (x === '--index') o.index = true;
+    else if (x === '--include-headings') o.includeHeadings = true;
+    else if (x === '--model') o.model = a[++i];
+    else if (x === '--max-per-target') o.maxPerTarget = parseInt(a[++i], 10);
+    else if (x === '--min-len') o.minLen = parseInt(a[++i], 10);
+    else if (x === '--concurrency') o.concurrency = parseInt(a[++i], 10);
+    else if (!x.startsWith('--')) pos.push(x);
+  }
+  if (pos[0]) o.dir = path.resolve(pos[0]);
+  return o;
+}
+
+// Common words we never auto-link even if they appear as a single-word title.
+const STOPWORDS = new Set([
+  'type', 'name', 'status', 'task', 'run', 'model', 'rule', 'page', 'event',
+  'memory', 'skill', 'note', 'data', 'index', 'title', 'tags', 'the', 'and'
+]);
+
+// ─── vault walk + glossary ───────────────────────────────────────────────────
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (name === 'node_modules' || name === '.git' || name.startsWith('.')) continue;
+    const p = path.join(dir, name);
+    const st = fs.lstatSync(p);
+    if (st.isSymbolicLink()) continue;
+    if (st.isDirectory()) walk(p, out);
+    else if (p.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+function splitFrontmatter(content) {
+  if (!content.startsWith('---')) return { fm: '', body: content, hasFm: false };
+  const end = content.indexOf('\n---', 3);
+  if (end < 0) return { fm: '', body: content, hasFm: false };
+  const fmEnd = content.indexOf('\n', end + 1);
+  return {
+    fm: content.slice(0, fmEnd + 1),
+    body: content.slice(fmEnd + 1),
+    hasFm: true
+  };
+}
+
+/** Pull title / name / slug / aliases[] out of a YAML frontmatter block (no dep). */
+function readMeta(fm) {
+  const scalar = (k) => {
+    const m = fm.match(new RegExp(`^${k}:\\s*(.+)$`, 'm'));
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
+  };
+  const meta = { title: scalar('title'), name: scalar('name'), slug: scalar('slug'), aliases: [] };
+  // aliases: inline [a, b] or YAML block list
+  const inline = fm.match(/^aliases:\s*\[(.*)\]\s*$/m);
+  if (inline) meta.aliases = inline[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  else {
+    const block = fm.match(/^aliases:\s*\n((?:\s*-\s*.+\n?)+)/m);
+    if (block) meta.aliases = block[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+  return meta;
+}
+
+function buildGlossary(files, root) {
+  const entries = [];
+  for (const file of files) {
+    const { fm } = splitFrontmatter(fs.readFileSync(file, 'utf8'));
+    if (!fm) continue;
+    const meta = readMeta(fm);
+    const target = '/' + path.relative(root, file).split(path.sep).join('/');
+    const surfaces = new Set();
+    for (const s of [meta.title, meta.name, ...meta.aliases]) {
+      if (s && s.length >= 1) surfaces.add(s);
+    }
+    if (surfaces.size === 0) continue;
+    entries.push({ file, target, surfaces: [...surfaces] });
+  }
+  return entries;
+}
+
+// ─── deterministic linking ───────────────────────────────────────────────────
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Replace term matches in a single plain-text chunk (no code/links inside). */
+function linkChunk(chunk, regex, byForm, selfTarget, used, opts, stats) {
+  return chunk.replace(regex, (m) => {
+    const entry = byForm.get(m.toLowerCase());
+    if (!entry || entry.target === selfTarget) return m;
+    const count = used.get(entry.target) || 0;
+    if (count >= opts.maxPerTarget) return m;
+    used.set(entry.target, count + 1);
+    stats.links++;
+    return `[${m}](${entry.target})`;
+  });
+}
+
+/** Link a line of body text, protecting inline code and existing links. */
+function linkLine(line, regex, byForm, selfTarget, used, opts, stats) {
+  // Split out protected spans: `inline code`, [text](url), [[wikilink]], <url>
+  const protect = /(`[^`]*`|\[[^\]]*\]\([^)]*\)|\[\[[^\]]*\]\]|<[^>]+>|https?:\/\/\S+)/g;
+  let out = '', last = 0, m;
+  while ((m = protect.exec(line)) !== null) {
+    out += linkChunk(line.slice(last, m.index), regex, byForm, selfTarget, used, opts, stats);
+    out += m[0]; // protected span, untouched
+    last = m.index + m[0].length;
+  }
+  out += linkChunk(line.slice(last), regex, byForm, selfTarget, used, opts, stats);
+  return out;
+}
+
+function linkBody(body, glossary, selfTarget, opts, stats) {
+  // Build a longest-first surface→entry map and one combined regex.
+  const byForm = new Map();
+  const forms = [];
+  for (const e of glossary) {
+    for (const s of e.surfaces) {
+      const key = s.toLowerCase();
+      const single = !/\s/.test(s);
+      if (single && (s.length < opts.minLen || STOPWORDS.has(key))) continue;
+      if (!byForm.has(key)) { byForm.set(key, e); forms.push(s); }
+    }
+  }
+  if (forms.length === 0) return body;
+  forms.sort((a, b) => b.length - a.length);
+  const regex = new RegExp(`\\b(${forms.map(esc).join('|')})\\b`, 'gi');
+
+  // Seed the per-target budget from links already present so re-runs are
+  // idempotent: a target that already has maxPerTarget links gets no more.
+  const used = new Map();
+  for (const m of body.matchAll(/\]\((\/[^)]+)\)/g)) {
+    used.set(m[1], (used.get(m[1]) || 0) + 1);
+  }
+
+  const lines = body.split('\n');
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trimStart();
+    if (t.startsWith('```') || t.startsWith('~~~')) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (!opts.includeHeadings && /^#{1,6}\s/.test(t)) continue;
+    lines[i] = linkLine(lines[i], regex, byForm, selfTarget, used, opts, stats);
+  }
+  return lines.join('\n');
+}
+
+// ─── semantic linking (Anthropic API, optional) ──────────────────────────────
+async function semanticLinks(body, glossary, selfTarget, opts) {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) return [];
+  const items = glossary.filter(e => e.target !== selfTarget)
+    .map(e => ({ path: e.target, names: e.surfaces.slice(0, 4) }));
+  const sys = 'You insert wiki links into Markdown. You are given a glossary of concepts (each with a path and names) and a document body. Find places where the body references a glossary concept BY MEANING — including paraphrases and synonyms, not just exact name matches. Return ONLY a JSON array of {"path","anchor"} where "anchor" is an EXACT substring of the body to turn into a link to "path". Rules: never link inside code; never link the document to its own path; pick natural noun-phrase anchors; max one anchor per concept; prefer precision over recall. Return [] if nothing fits.';
+  const user = `GLOSSARY:\n${JSON.stringify(items)}\n\nDOCUMENT BODY:\n${body.slice(0, 8000)}`;
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify({ model: opts.model, max_tokens: 1024, system: sys, messages: [{ role: 'user', content: user }] })
+    });
+    if (!res.ok) { console.error(`   ⚠ semantic API ${res.status}: ${(await res.text()).slice(0, 120)}`); return []; }
+    const data = await res.json();
+    const text = (data.content || []).map(c => c.text || '').join('');
+    const json = text.slice(text.indexOf('['), text.lastIndexOf(']') + 1);
+    const out = JSON.parse(json);
+    return Array.isArray(out) ? out.filter(x => x && x.path && x.anchor) : [];
+  } catch (err) {
+    console.error(`   ⚠ semantic link failed: ${err.message}`);
+    return [];
+  }
+}
+
+/** Apply semantic anchors as links to the first plain-text occurrence of each. */
+function applySemantic(body, links, selfTarget, stats) {
+  let inFence = false;
+  const lines = body.split('\n');
+  // Seed from existing links so a path already linked is not linked again (idempotent).
+  const done = new Set();
+  for (const m of body.matchAll(/\]\((\/[^)]+)\)/g)) done.add(m[1]);
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trimStart();
+    if (t.startsWith('```') || t.startsWith('~~~')) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    for (const l of links) {
+      if (done.has(l.path) || l.path === selfTarget) continue;
+      const idx = lines[i].indexOf(l.anchor);
+      if (idx < 0) continue;
+      // Don't relink inside an existing link/code span on this line.
+      const before = lines[i].slice(0, idx);
+      if ((before.match(/`/g) || []).length % 2 === 1) continue;
+      if (/\]\([^)]*$/.test(before) || /\[[^\]]*$/.test(before)) continue;
+      lines[i] = before + `[${l.anchor}](${l.path})` + lines[i].slice(idx + l.anchor.length);
+      done.add(l.path); stats.semantic++;
+    }
+  }
+  return lines.join('\n');
+}
+
+// ─── index.md generation (spec §4.3) ─────────────────────────────────────────
+/**
+ * Generate one index.md per directory for progressive disclosure.
+ *
+ * Covers every ANCESTOR directory of every tracked file (not just directories
+ * that directly contain a .md file) — a nested primitive like
+ * `roles/admin/ROLE.md` needs `roles/admin/index.md` (listing ROLE.md) AND
+ * `roles/index.md` (listing the `admin/` subdirectory) for the chain to be
+ * navigable end to end. Subdirectories that themselves get an index are
+ * listed as `[name/](./name/index.md)` entries alongside sibling files.
+ */
+export function generateIndexes(files, root, opts, summary) {
+  const dirs = new Set();
+  for (const f of files) {
+    if (path.basename(f) === 'index.md') continue;
+    // Stop before `root` itself: a bundle-relative path of bare "index.md"
+    // (no leading directory) doesn't match the engine's `*/index.md` special
+    // case and would fail normal frontmatter validation. Vault-root indexing
+    // is intentionally out of scope here, matching prior behavior.
+    let d = path.dirname(f);
+    while (d !== root) {
+      dirs.add(d);
+      const parent = path.dirname(d);
+      if (parent === d) break;
+      d = parent;
+    }
+  }
+
+  for (const dir of dirs) {
+    const lines = [`# Index — ${path.relative(root, dir) || '.'}`, ''];
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => !e.name.startsWith('.') && e.name !== 'node_modules')
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (dirs.has(path.join(dir, e.name))) lines.push(`- [${e.name}/](./${e.name}/index.md)`);
+      } else if (e.name.endsWith('.md') && e.name !== 'index.md') {
+        const { fm } = splitFrontmatter(fs.readFileSync(path.join(dir, e.name), 'utf8'));
+        const meta = readMeta(fm);
+        const label = meta.title || meta.name || path.basename(e.name, '.md');
+        lines.push(`- [${label}](./${e.name})`);
+      }
+    }
+    const target = path.join(dir, 'index.md');
+    summary.indexes.push(path.relative(root, target));
+    if (opts.write) fs.writeFileSync(target, lines.join('\n') + '\n', 'utf8');
+  }
+}
+
+// ─── main ────────────────────────────────────────────────────────────────────
+export async function main() {
+  const opts = parseArgs();
+  console.log(`\n=== ssss autolink ===`);
+  console.log(`  dir:      ${opts.dir}`);
+  console.log(`  mode:     ${opts.write ? 'WRITE' : 'dry-run (use --write to apply)'}${opts.semantic ? ' + semantic AI' : ''}\n`);
+
+  const files = walk(opts.dir);
+  if (files.length === 0) { console.log('No .md files found.'); return; }
+  const glossary = buildGlossary(files, opts.dir);
+  console.log(`  ${files.length} files scanned · ${glossary.length} linkable concepts in glossary`);
+  if (opts.semantic && !process.env.ANTHROPIC_API_KEY) {
+    console.log('  ⚠ --semantic given but ANTHROPIC_API_KEY is not set; running deterministic only.\n');
+  }
+
+  const summary = { changed: 0, links: 0, semantic: 0, indexes: [] };
+  // Limit concurrency for the semantic API calls.
+  const queue = [...files];
+  async function worker() {
+    while (queue.length) {
+      const file = queue.shift();
+      const original = fs.readFileSync(file, 'utf8');
+      const { fm, body } = splitFrontmatter(original);
+      const selfTarget = '/' + path.relative(opts.dir, file).split(path.sep).join('/');
+      const stats = { links: 0, semantic: 0 };
+      let newBody = linkBody(body, glossary, selfTarget, opts, stats);
+      if (opts.semantic && process.env.ANTHROPIC_API_KEY) {
+        const links = await semanticLinks(newBody, glossary, selfTarget, opts);
+        if (links.length) newBody = applySemantic(newBody, links, selfTarget, stats);
+      }
+      if (stats.links + stats.semantic > 0) {
+        summary.changed++; summary.links += stats.links; summary.semantic += stats.semantic;
+        const rel = path.relative(opts.dir, file);
+        console.log(`  ~ ${rel}  (+${stats.links} exact${stats.semantic ? `, +${stats.semantic} semantic` : ''})`);
+        if (opts.write) fs.writeFileSync(file, fm + newBody, 'utf8');
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, opts.semantic ? opts.concurrency : 1) }, worker));
+
+  if (opts.index) generateIndexes(files, opts.dir, opts, summary);
+
+  console.log(`\n  ${summary.changed} files ${opts.write ? 'updated' : 'would change'} · ${summary.links} exact + ${summary.semantic} semantic links` +
+    (opts.index ? ` · ${summary.indexes.length} index.md` : ''));
+  if (!opts.write && summary.changed > 0) console.log(`  Re-run with --write to apply.`);
+}
+
+// Only self-execute when run directly (`node scripts/autolink.mjs ...` or the
+// `ssss.mjs` dispatcher explicitly calling `main()`), never as a side effect
+// of another module importing `generateIndexes` for reuse.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/scripts/build-reference-bundle.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Build the canonical reference `.ucw` bundle (spec §16, Track G — "Festival in a
+ * Box"). Writes conformance/reference-bundle.ucw.json deterministically so the
+ * content hash is stable and the bundle is a fixed conformance artifact.
+ *
+ * The reference vault deliberately contains all three portability classes so the
+ * exported `sale` bundle proves the keystone (§5.5):
+ *   - structural     → INCLUDED  (the sellable festival model)
+ *   - resource_bound → INCLUDED as a requirement declaration (buyer binds a domain)
+ *   - tenant_private → DROPPED   (the operator's ticket records never ship)
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exportBundle, validateBundle } from '../src/bundle.mjs';
+import { generateIndexes } from './autolink.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const OUT = path.resolve(__dirname, '..', 'conformance', 'reference-bundle.ucw.json');
+
+// ─── The reference vault ────────────────────────────────────────────────────
+const VAULT = {
+  // structural — the festival's reusable model
+  'workflows/box-office.md':
+`---
+type: workflow
+title: Box Office
+description: Ticket-sales workflow for a music festival.
+timestamp: 2026-07-02T00:00:00Z
+name: Box Office
+slug: box-office
+---
+Sell tickets, then hand the buyer to [[concierge]] for questions.`,
+  'assistants/concierge.md':
+`---
+type: assistant
+title: Festival Concierge
+description: Assistant that answers attendee questions about the lineup and venue.
+timestamp: 2026-07-02T00:00:00Z
+name: Festival Concierge
+slug: concierge
+---
+Answer attendee questions about the lineup and venue.`,
+  'pages/lineup.md':
+`---
+type: page
+title: Lineup
+description: Public-facing festival lineup page.
+timestamp: 2026-07-02T00:00:00Z
+slug: lineup
+name: Lineup
+sandbox_entry: lineup/index.html
+---
+The festival lineup page.`,
+  'rules/refund-policy.md':
+`---
+type: rule
+title: Refund Policy
+description: Refund eligibility rule for festival attendees.
+timestamp: 2026-07-02T00:00:00Z
+name: Refund Policy
+slug: refund-policy
+---
+Refunds are available up to 14 days before the event.`,
+  'roles/admin/ROLE.md':
+`---
+type: security_role
+title: Administrator Role
+description: Security role with full festival operations write access.
+timestamp: 2026-07-02T00:00:00Z
+name: Administrator
+permissions:
+  - "write:assistant"
+  - "write:workflow"
+  - "write:rule"
+  - "write:domain"
+  - "write:page"
+  - "write:security_role"
+  - "write:task"
+---
+Full access to all festival operations.`,
+  // resource_bound — declares "this business needs a domain"; the SELLER's domain never ships
+  'domains/festival.md':
+`---
+type: domain
+title: Festival Domain Requirement
+description: Domain resource requirement that the buyer binds during provisioning.
+timestamp: 2026-07-02T00:00:00Z
+domain_name: REQUIREMENT
+registrar: REQUIREMENT
+status: required
+payment_status: unbound
+x_portability: resource_bound
+---
+This festival needs a domain. The buyer binds their own at provision (owns_domain).`,
+  // tenant_private — operator's ticket record; MUST be dropped from a sale bundle
+  'tasks/ticket-4821.md':
+`---
+type: task
+title: Ticket 4821 Seat Change
+description: Private support task for an attendee seat-change request.
+timestamp: 2026-07-02T00:00:00Z
+priority: high
+category: support
+status: open
+---
+Attendee jane@example.com requested a seat change.`,
+};
+
+function buildVault() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-refvault-'));
+  const files = [];
+
+  for (const [rel, content] of Object.entries(VAULT)) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    files.push(abs);
+  }
+
+  // Generate index.md for progressive disclosure (§4.3) — reuses the same
+  // generator `ssss autolink --index` uses, so there is one implementation.
+  generateIndexes(files, root, { write: true }, { indexes: [] });
+
+  return root;
+}
+
+const vault = buildVault();
+try {
+  const bundle = exportBundle(vault, {
+    profile: 'sale',
+    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',
+    requiredExtensions: ['festech'],
+    parameters: [
+      { key: 'business_name', label: 'Festival name', type: 'string', scope: 'workspace', source: 'user', required: true },
+      { key: 'domain', label: 'Domain to bind', type: 'string', scope: 'workspace', source: 'user', required: true, description: 'Satisfies the resource_bound domain requirement (owns_domain).' },
+      { key: 'support_mailbox', label: 'Support mailbox', type: 'string', scope: 'workspace', source: 'user', required: false },
+    ],
+    provisioning: [
+      { id: 'ws', label: 'Create the workspace', system: 'workspace', mode: 'generate', required: true },
+      { id: 'dom', label: 'Bind the festival domain', system: 'domains', mode: 'provision', required: true, notes: 'owns_domain — buyer supplies their own domain.' },
+      { id: 'mail', label: 'Provision a support mailbox', system: 'email', mode: 'provision', required: false },
+    ],
+  });
+
+  // Drop the internal export trace before persisting the artifact.
+  const dropped = bundle._dropped;
+  delete bundle._dropped;
+
+  const { valid, errors } = validateBundle(bundle);
+  if (!valid) {
+    console.error('❌ Reference bundle failed validation:');
+    for (const e of errors) console.error('   • ' + e);
+    process.exit(1);
+  }
+
+  fs.writeFileSync(OUT, JSON.stringify(bundle, null, 2) + '\n');
+  console.log(`✅ Wrote ${path.relative(path.resolve(__dirname, '..'), OUT)}`);
+  console.log(`   profile=sale  files=${bundle.files.length}  hash=${bundle.manifest.provenance.content_hash.slice(0, 23)}…`);
+  console.log(`   inventory: ${JSON.stringify(bundle.manifest.primitive_inventory)}`);
+  console.log(`   dropped (tenant_private, not sold): ${dropped.map((d) => `${d.path}[${d.portability}]`).join(', ') || '(none)'}`);
+} finally {
+  fs.rmSync(vault, { recursive: true, force: true });
+}

package/scripts/cmd-export.mjs

@@ -0,0 +1,72 @@
+/**
+ * `ssss export` — package a vault directory into a `.ucw` bundle (spec §16).
+ *
+ * Pure and deterministic: the same vault + profile always yields a byte-identical
+ * bundle (frozen `exported_at`, content-hashed). Profile filtering enforces the
+ * §5.5 portability rules — `template`/`sale` drop every `tenant_private` file.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { exportBundle } from '../src/bundle.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = usage({
+  summary: 'Package an SSSS vault directory into a transportable .ucw bundle (spec §16).',
+  usage: 'ssss export <vault-dir> [options]',
+  options: [
+    ['--profile <p>', 'Export profile: backup | template | sale (default: backup).'],
+    ['--out <file>', 'Write the bundle here (default: stdout).'],
+    ['--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).'],
+    ['--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).'],
+    ['--show-dropped', 'Print the files excluded by the profile to stderr.'],
+  ],
+  examples: [
+    'ssss export ./my-vault --profile sale --out festival.ucw.json',
+    'ssss export ./my-vault --profile backup --name "Nightly" --out backup.ucw.json',
+  ],
+  seeAlso: ['ssss validate', 'ssss inspect', 'ssss help portability'],
+});
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const { positionals, flags } = parseArgs(argv, {
+    booleans: ['show-dropped'],
+    multi: ['ext'],
+  });
+  const vault = positionals[0];
+  if (!vault) die('export needs a vault directory.\n\n' + HELP);
+  if (!fs.existsSync(vault) || !fs.statSync(vault).isDirectory()) die(`not a directory: ${vault}`);
+
+  let bundle;
+  try {
+    bundle = exportBundle(path.resolve(vault), {
+      profile: flags.profile || 'backup',
+      registryDir: flags.registry,
+      name: flags.name || path.basename(path.resolve(vault)),
+      description: flags.description || '',
+      version: flags['bundle-version'] || '0.1.0',
+      exporter: flags.exporter || '@ssss/cli',
+      requiredExtensions: flags.ext || [],
+      ...(flags['exported-at'] ? { exportedAt: flags['exported-at'] } : {}),
+    });
+  } catch (err) { die(err.message); }
+
+  if (flags['show-dropped'] && bundle._dropped.length) {
+    console.error(`Dropped ${bundle._dropped.length} file(s) excluded by profile '${bundle.manifest.export_profile}':`);
+    for (const d of bundle._dropped) console.error(`  - ${d.path} (${d.type || 'untyped'} · ${d.portability})`);
+  }
+
+  const out = { manifest: bundle.manifest, files: bundle.files };
+  const json = JSON.stringify(out, null, 2);
+  if (flags.out) {
+    fs.writeFileSync(flags.out, json + '\n');
+    console.error(`Wrote ${out.files.length} file(s) → ${flags.out} (${bundle.manifest.provenance.content_hash}).`);
+  } else {
+    process.stdout.write(json + '\n');
+  }
+}

package/scripts/cmd-help.mjs

@@ -0,0 +1,60 @@
+/**
+ * `ssss help [topic]` — query the local documentation shipped with the package.
+ *
+ * Topics are Markdown files under `docs/help/`. With no argument it lists them;
+ * with a topic it prints that file. No network, no dependencies — the docs travel
+ * with the CLI so they work offline and match the installed version.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './lib/cli.mjs';
+
+const HELP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'docs', 'help');
+
+function topics() {
+  if (!fs.existsSync(HELP_DIR)) return [];
+  return fs.readdirSync(HELP_DIR).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')).sort();
+}
+
+function firstLineSummary(topic) {
+  const lines = fs.readFileSync(path.join(HELP_DIR, `${topic}.md`), 'utf8').split('\n');
+  for (const l of lines) {
+    const t = l.trim();
+    if (t && !t.startsWith('#')) return t.replace(/[*`]/g, '');
+  }
+  return '';
+}
+
+export async function run(argv) {
+  const { positionals, flags } = parseArgs(argv, { booleans: ['json'], alias: { j: 'json' } });
+  const all = topics();
+  const topic = positionals[0];
+
+  if (flags.json) {
+    if (topic) {
+      const file = path.join(HELP_DIR, `${topic}.md`);
+      if (!fs.existsSync(file)) { console.error(JSON.stringify({ error: `unknown topic '${topic}'`, topics: all })); process.exit(1); }
+      console.log(JSON.stringify({ topic, content: fs.readFileSync(file, 'utf8') }));
+    } else {
+      console.log(JSON.stringify({ topics: all.map((t) => ({ topic: t, summary: firstLineSummary(t) })) }));
+    }
+    return;
+  }
+
+  if (!topic) {
+    console.log('SSSS help topics — run `ssss help <topic>`:\n');
+    const w = Math.max(...all.map((t) => t.length));
+    for (const t of all) console.log(`  ${t.padEnd(w)}   ${firstLineSummary(t)}`);
+    console.log('\nPer-command flags: `ssss <command> --help`.');
+    return;
+  }
+
+  const file = path.join(HELP_DIR, `${topic}.md`);
+  if (!fs.existsSync(file)) {
+    console.error(`No help topic '${topic}'. Available: ${all.join(', ')}`);
+    process.exit(1);
+  }
+  process.stdout.write(fs.readFileSync(file, 'utf8'));
+  if (!fs.readFileSync(file, 'utf8').endsWith('\n')) process.stdout.write('\n');
+}