rewritable 0.6.0 → 0.8.0

package/src/agent-loop.mjs

@@ -128,12 +128,14 @@ export async function runAgentLoop({
   throw new AgentError('no_envelope_after_retries', { retries: RETRY_BUDGET });
 }
 
-async function callBackend({ baseUrl, model, apiKey }, body) {
+async function callBackend({ baseUrl, model, apiKey, maxTokens }, body) {
   const headers = { 'Content-Type': 'application/json' };
   if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
   const url = baseUrl.replace(/\/+$/, '') + '/chat/completions';
   // Seed parity (seeds/rewritable.html openAiCompatChat caller in modify()):
-  // every request carries max_tokens: 32000 and tool_choice: 'auto'. The
+  // every request carries the backend's max_tokens (32000 historically; 8192
+  // for atomic, whose server REJECTS prompt+generation past MAX_KV_SIZE rather
+  // than clamping — see backendMaxTokens) and tool_choice: 'auto'. The
   // tool_choice default forces the model to call one of the provided tools
   // rather than emitting plain text (which would trip our no_tool_call retry).
   const res = await fetch(url, {
@@ -141,7 +143,7 @@ async function callBackend({ baseUrl, model, apiKey }, body) {
     headers,
     body: JSON.stringify({
       model,
-      max_tokens: 32000,
+      max_tokens: maxTokens || 32000,
       tool_choice: 'auto',
       ...body,
     }),

package/src/backend.mjs

@@ -2,15 +2,15 @@
 // precedence is unit-testable (the bin entrypoint runs on import and can't be
 // imported cleanly).
 //
-// Only the openrouter backend needs a key — ollama and lmstudio run locally
-// without auth. The key resolves in order: an explicit --api-key flag, then the
+// Only the openrouter backend needs a key — ollama, lmstudio, and atomic run
+// locally without auth. The key resolves in order: an explicit --api-key flag, then the
 // project-specific RWA_OPENROUTER_KEY (env conventions match the docker-compose
 // deploy in service/), then the CONVENTIONAL OPENROUTER_API_KEY that agents and
 // users normally have exported. Empty strings count as absent.
 
 /**
  * Resolve the API key for a backend.
- * @param {string} backendName — 'openrouter' | 'ollama' | 'lmstudio'
+ * @param {string} backendName — 'openrouter' | 'ollama' | 'lmstudio' | 'atomic'
  * @param {string|undefined} flagValue — the --api-key flag value, if any
  * @param {Record<string,string|undefined>} [env] — environment (injectable for tests)
  * @returns {string|undefined} the key, or undefined when none applies
@@ -26,10 +26,10 @@ export function resolveApiKey(backendName, flagValue, env = process.env) {
 /**
  * Default OpenAI-compatible base URL for a backend — mirrors the inline
  * `envBaseUrl` in bin/rwa.mjs (and seeds/rewritable.html resolveBackendConfig).
- * ollama and lmstudio honor RWA_*_URL overrides (remote host / non-standard port);
- * openrouter is fixed (the URL has never drifted in the seed). Shared by `rwa edit`
+ * ollama, lmstudio, and atomic honor RWA_*_URL overrides (remote host / non-standard
+ * port); openrouter is fixed (the URL has never drifted in the seed). Shared by `rwa edit`
  * and `rwa create` so the default never diverges between the two.
- * @param {string} name — 'openrouter' | 'ollama' | 'lmstudio'
+ * @param {string} name — 'openrouter' | 'ollama' | 'lmstudio' | 'atomic'
  * @param {Record<string,string|undefined>} [env] — environment (injectable for tests)
  * @returns {string|undefined}
  */
@@ -38,6 +38,24 @@ export function envBaseUrl(name, env = process.env) {
     case 'openrouter': return 'https://openrouter.ai/api/v1';
     case 'ollama':     return env.RWA_OLLAMA_URL || 'http://localhost:11434/v1';
     case 'lmstudio':   return env.RWA_LMSTUDIO_URL || 'http://localhost:1234/v1';
+    case 'atomic':     return env.RWA_ATOMIC_URL || 'http://127.0.0.1:1337/v1';
     default:           return undefined;
   }
 }
+
+/**
+ * Per-backend max_tokens for the agent loop. The historical 32000 stands for
+ * hosted/clamping backends, but atomic.chat REJECTS (400) any request whose
+ * prompt + max generation exceeds its MAX_KV_SIZE (16384 by default) rather
+ * than clamping — so it gets 8192, leaving the other half of the window for
+ * the system prompt + document. RWA_MAX_TOKENS overrides for unusual servers.
+ * Mirrors the seed's resolveBackendConfig() maxTokens.
+ * @param {string} name — backend name
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {number}
+ */
+export function backendMaxTokens(name, env = process.env) {
+  const override = Number(env.RWA_MAX_TOKENS);
+  if (Number.isFinite(override) && override > 0) return override;
+  return name === 'atomic' ? 8192 : 32000;
+}

package/src/commands.mjs

@@ -85,7 +85,7 @@ async function readEnvKey(name) {
 // than throwing — pre-fill is best-effort; an unknown value just means the
 // user sees the default backend (openrouter) on first paint.
 function validBackend(v) {
-  return ['openrouter', 'ollama', 'lmstudio', 'bridge'].includes(v) ? v : null;
+  return ['openrouter', 'ollama', 'lmstudio', 'atomic', 'bridge'].includes(v) ? v : null;
 }
 
 // Collect URL-param pre-fills from env / ./.env. Returns an object whose keys

package/src/create.mjs

@@ -20,7 +20,7 @@ import { runAgentLoop } from './agent-loop.mjs';
 import { applyPlan, CliError } from './edit.mjs';
 import { assertSelfContained } from './self-contained.mjs';
 import { findFrozenZones } from './apply-edits.mjs';
-import { resolveApiKey, envBaseUrl } from './backend.mjs';
+import { resolveApiKey, envBaseUrl, backendMaxTokens } from './backend.mjs';
 import { atomicWrite } from './atomic-write.mjs';
 
 // Hard cap on --data baked into the snapshot. The dataset lands inside INLINE_DOC
@@ -219,6 +219,7 @@ export async function createCmd(parsed, { seedCandidates, cwd = process.cwd(), s
     baseUrl: parsed.backend.baseUrl || envBaseUrl(backendName),
     model:   parsed.backend.model   || process.env.RWA_MODEL || 'google/gemini-3.5-flash',
     apiKey:  resolveApiKey(backendName, parsed.backend.apiKey),
+    maxTokens: backendMaxTokens(backendName),
   };
 
   // Per-kind system prompt + the create-only self-containment directive; the brief

package/src/identity.mjs

@@ -35,6 +35,7 @@ export const KIND_PROVIDERS = {
   workflow: [],
   // skill-host: no first-party affordances; installed skills (provenance:'installed')
   // come from parseSkillZone (§8), not this table. Explicit [] mirrors the oracle.
+  workspace: [],
   'skill-host': [],
 };
 

package/src/seed.mjs

@@ -1316,6 +1316,82 @@ const KIND_PRESENTATION_BODY = `<article>
 <p>The view is a pure re-presentation at render time; the bytes on disk never change shape.</p>
 </article>`;
 
+// ── workspace (directory index / control center) ─────────────────────────────
+const KIND_WORKSPACE_LENS = 'Describe a change to this workspace index.';
+const KIND_WORKSPACE_PAL  = 'edit this workspace index...';
+
+const KIND_WORKSPACE_HEADER = `// === PRODUCT HEADER ===
+// Product: workspace (directory control center).
+//
+// A workspace index is a normal re-writeable file named rwa-index.html that
+// summarizes sibling rewritables in the same directory. The editable article is
+// a dashboard; the frozen #rwa-workspace JSON manifest is regenerated by the CLI
+// (\`rwa workspace create|sync\`) from the files on disk. The index coordinates a
+// folder; it does not merge documents, expand the skill-host runtime, or persist
+// runtime chrome into any child document.
+// === END PRODUCT HEADER ===`;
+
+const KIND_WORKSPACE_BODY = `<!-- rwa:frozen:begin workspace-style -->
+<style>
+.rwa-workspace{max-width:1040px;margin:0 auto;padding:32px 24px 72px;}
+.rwa-workspace header{display:flex;align-items:flex-end;justify-content:space-between;gap:16px;margin-bottom:24px;border-bottom:1px solid var(--gray-200,#e5e7eb);padding-bottom:18px;}
+.rwa-workspace h1{margin:0;font-size:2rem;line-height:1.1;}
+.rwa-workspace .rwa-ws-meta{margin:0;color:var(--gray-500,#6b7280);font-size:13px;}
+.rwa-ws-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px;}
+.rwa-ws-card{display:flex;flex-direction:column;gap:7px;padding:14px 16px;border:1px solid var(--gray-200,#e5e7eb);border-radius:8px;text-decoration:none;color:inherit;background:var(--gray-50,#f9fafb);}
+.rwa-ws-card:hover{border-color:var(--gray-400,#9ca3af);background:#fff;}
+.rwa-ws-card strong{font-size:16px;line-height:1.25;}
+.rwa-ws-card span{font-size:13px;color:var(--gray-600,#4b5563);overflow-wrap:anywhere;}
+.rwa-ws-card small{font-size:12px;color:var(--gray-500,#6b7280);}
+.rwa-ws-kind{align-self:flex-start;text-transform:uppercase;letter-spacing:.04em;font-size:10px!important;color:#fff!important;background:var(--gray-800,#1f2937);border-radius:4px;padding:2px 6px;}
+.rwa-ws-empty{color:var(--gray-500,#6b7280);line-height:1.5;}
+.rwa-ws-context{display:grid;grid-template-columns:minmax(0,1fr);gap:10px;margin:20px 0 28px;}
+.rwa-ws-context h2{margin:18px 0 0;font-size:1.1rem;}
+.rwa-ws-context h2:first-child{margin-top:0;}
+.rwa-ws-context p,.rwa-ws-context ul,.rwa-ws-context ol{margin:0;line-height:1.55;}
+.rwa-ws-live{margin-top:28px;padding-top:18px;border-top:1px solid var(--gray-200,#e5e7eb);}
+.rwa-ws-live h2{margin:0 0 12px;font-size:1rem;}
+.rwa-ws-live-card{background:#fff;border-color:var(--blue,#2563eb);}
+</style>
+<!-- rwa:frozen:end workspace-style -->
+<article class="rwa-workspace">
+<header>
+  <div>
+    <h1>Workspace</h1>
+    <p class="rwa-ws-meta">0 documents · run <code>rwa workspace sync</code> in this folder</p>
+  </div>
+</header>
+<section class="rwa-ws-context" data-rwa-workspace-context>
+<h2>Workspace memory</h2>
+<p>Use this space for durable notes that every document in this workspace should be able to rely on.</p>
+
+<h2>Guidelines</h2>
+<ul>
+  <li>Describe the shared tone, standards, constraints, and recurring decisions for this workspace.</li>
+  <li>For a writing workspace, add voice, structure, audience, and publishing rules here.</li>
+</ul>
+
+<h2>Examples</h2>
+<p>Add canonical examples that new documents can imitate, such as a representative blog post, proposal, report, or brief.</p>
+
+<h2>Open questions</h2>
+<ul>
+  <li>Track unresolved decisions that should shape future documents.</li>
+</ul>
+</section>
+<h2>Workspace documents</h2>
+<section class="rwa-ws-grid" aria-label="Workspace documents">
+<p class="rwa-ws-empty">No sibling rewritables yet. Add documents to this folder, then run <code>rwa workspace sync</code>.</p>
+</section>
+<section class="rwa-ws-live" data-rwa-workspace-live hidden>
+<h2>Open now</h2>
+<div class="rwa-ws-grid" data-rwa-workspace-live-grid></div>
+</section>
+</article>
+<!-- rwa:frozen:begin workspace-manifest -->
+<script type="application/rwa-workspace+json" id="rwa-workspace" data-rwa-frozen>{"version":"rwa-workspace/1","name":"Workspace","documents":[]}</script>
+<!-- rwa:frozen:end workspace-manifest -->`;
+
 // ── skill-host (v0.8 actions spec §2) ──────────────────────────────────────
 const KIND_SKILLHOST_LENS = 'Describe a change to this skill host.';
 const KIND_SKILLHOST_PAL  = 'edit this skill host...';
@@ -1368,6 +1444,13 @@ const KIND_TABLE = {
     // (spec §5.10); this kind only sets PRODUCT_KIND + starter/framing/lens.
     lensClickToAnchor: false,
   },
+  workspace: {
+    body: KIND_WORKSPACE_BODY,
+    lensPlaceholder: KIND_WORKSPACE_LENS,
+    palPlaceholder: KIND_WORKSPACE_PAL,
+    productHeader: KIND_WORKSPACE_HEADER,
+    lensClickToAnchor: false,
+  },
   'skill-host': {
     body: KIND_SKILLHOST_BODY,
     lensPlaceholder: KIND_SKILLHOST_LENS,
@@ -1377,7 +1460,7 @@ const KIND_TABLE = {
     // in the runtime-owned frozen zone, not authored by clicking a paragraph.
     lensClickToAnchor: false,
   },
-  // app, workspace: reserved — wire when the templates land. The CLI rejects
+  // app: reserved — wire when the template lands. The CLI rejects
   // unknown kinds explicitly rather than silently emitting a document.
 };
 

package/src/workspace.mjs

@@ -0,0 +1,262 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { loadSeed, applySeedSubs, replaceInlineDoc, extractInlineDoc, kindOverrides } from './seed.mjs';
+import { inspectDoc } from './doc.mjs';
+
+export const WORKSPACE_INDEX = 'rwa-index.html';
+const UUID_RE = /const DOC_UUID = '([0-9a-f-]{36})';/;
+
+function titleFromDir(dir) {
+  const base = path.basename(path.resolve(dir)) || 'Workspace';
+  return base
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(w => w[0].toUpperCase() + w.slice(1))
+    .join(' ') || 'Workspace';
+}
+
+function titleFromFile(file) {
+  return path.basename(file, path.extname(file))
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(w => w[0].toUpperCase() + w.slice(1))
+    .join(' ') || file;
+}
+
+function escapeHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function escapeAttr(s) {
+  return escapeHtml(s).replace(/'/g, '&#39;');
+}
+
+function safeScriptJson(obj) {
+  return JSON.stringify(obj, null, 2).replace(/<\/script/gi, '<\\/script');
+}
+
+function defaultWorkspaceContext(name) {
+  return `<section class="rwa-ws-context" data-rwa-workspace-context>
+<h2>Workspace memory</h2>
+<p>Use this space for durable notes that every document in this workspace should be able to rely on.</p>
+
+<h2>Guidelines</h2>
+<ul>
+  <li>Describe the shared tone, standards, constraints, and recurring decisions for this workspace.</li>
+  <li>For a writing workspace, add voice, structure, audience, and publishing rules here.</li>
+</ul>
+
+<h2>Examples</h2>
+<p>Add canonical examples that new documents can imitate, such as a representative blog post, proposal, report, or brief.</p>
+
+<h2>Open questions</h2>
+<ul>
+  <li>Track unresolved decisions that should shape future documents.</li>
+</ul>
+</section>`;
+}
+
+function extractWorkspaceContext(doc, name) {
+  const m = String(doc || '').match(/<section\b[^>]*\bdata-rwa-workspace-context\b[^>]*>[\s\S]*?<\/section>/i);
+  return m ? m[0] : defaultWorkspaceContext(name);
+}
+
+async function indexUuid(indexPath) {
+  try {
+    const text = await fs.readFile(indexPath, 'utf8');
+    return (text.match(UUID_RE) || [])[1] || crypto.randomUUID();
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return crypto.randomUUID();
+    throw e;
+  }
+}
+
+async function ensureCreateTarget(dir, indexPath, force) {
+  try {
+    const st = await fs.stat(dir);
+    if (!st.isDirectory()) {
+      const e = new Error(`workspace target is not a directory: ${dir}`);
+      e.exitCode = 2;
+      throw e;
+    }
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      await fs.mkdir(dir, { recursive: true });
+    } else {
+      throw e;
+    }
+  }
+
+  try {
+    await fs.stat(indexPath);
+    if (!force) {
+      const e = new Error(`workspace index exists: ${indexPath} (use --force to overwrite)`);
+      e.exitCode = 2;
+      throw e;
+    }
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return;
+    throw e;
+  }
+}
+
+async function ensureSyncTarget(dir) {
+  const st = await fs.stat(dir).catch(e => {
+    if (e && e.code === 'ENOENT') {
+      const err = new Error(`workspace directory not found: ${dir}`);
+      err.exitCode = 2;
+      throw err;
+    }
+    throw e;
+  });
+  if (!st.isDirectory()) {
+    const e = new Error(`workspace target is not a directory: ${dir}`);
+    e.exitCode = 2;
+    throw e;
+  }
+}
+
+export async function scanWorkspace(dir) {
+  const names = (await fs.readdir(dir))
+    .filter(n => /\.html?$/i.test(n))
+    .filter(n => n !== WORKSPACE_INDEX)
+    .sort((a, b) => a.localeCompare(b));
+  const docs = [];
+  for (const name of names) {
+    const filePath = path.join(dir, name);
+    try {
+      const info = await inspectDoc(filePath);
+      docs.push({
+        file: name,
+        title: info.self.title || titleFromFile(name),
+        kind: info.self.kind || info.kind || 'document',
+        uuid: info.uuid,
+        blocks: info.self.blocks || 0,
+        affordances: Array.isArray(info.self.affordances)
+          ? info.self.affordances.map(a => ({ kind: a.kind, name: a.name, label: a.label, provenance: a.provenance }))
+          : [],
+      });
+    } catch (e) {
+      if (e && e.subcode === 'not_a_rewritable') continue;
+      throw e;
+    }
+  }
+  return docs;
+}
+
+export function buildWorkspaceBody({ name, docs, generatedAt = new Date().toISOString(), contextHtml }) {
+  const manifest = {
+    version: 'rwa-workspace/1',
+    name,
+    generatedAt,
+    index: WORKSPACE_INDEX,
+    documents: docs,
+  };
+  const cards = docs.length
+    ? docs.map(doc => {
+        const kinds = doc.affordances && doc.affordances.length
+          ? doc.affordances.map(a => a.kind).join(', ')
+          : 'baseline';
+        const href = './' + encodeURI(doc.file).replace(/"/g, '%22');
+        return `<a class="rwa-ws-card" href="${escapeAttr(href)}">
+  <span class="rwa-ws-kind">${escapeHtml(doc.kind)}</span>
+  <strong>${escapeHtml(doc.title)}</strong>
+  <span>${escapeHtml(doc.file)}</span>
+  <small>${escapeHtml(String(doc.blocks))} blocks · ${escapeHtml(kinds)}</small>
+</a>`;
+      }).join('\n')
+    : '<p class="rwa-ws-empty">No sibling rewritables yet. Add documents to this folder, then run <code>rwa workspace sync</code>.</p>';
+
+  return `<!-- rwa:frozen:begin workspace-style -->
+<style>
+.rwa-workspace{max-width:1040px;margin:0 auto;padding:32px 24px 72px;}
+.rwa-workspace header{display:flex;align-items:flex-end;justify-content:space-between;gap:16px;margin-bottom:24px;border-bottom:1px solid var(--gray-200,#e5e7eb);padding-bottom:18px;}
+.rwa-workspace h1{margin:0;font-size:2rem;line-height:1.1;}
+.rwa-workspace .rwa-ws-meta{margin:0;color:var(--gray-500,#6b7280);font-size:13px;}
+.rwa-ws-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px;}
+.rwa-ws-card{display:flex;flex-direction:column;gap:7px;padding:14px 16px;border:1px solid var(--gray-200,#e5e7eb);border-radius:8px;text-decoration:none;color:inherit;background:var(--gray-50,#f9fafb);}
+.rwa-ws-card:hover{border-color:var(--gray-400,#9ca3af);background:#fff;}
+.rwa-ws-card strong{font-size:16px;line-height:1.25;}
+.rwa-ws-card span{font-size:13px;color:var(--gray-600,#4b5563);overflow-wrap:anywhere;}
+.rwa-ws-card small{font-size:12px;color:var(--gray-500,#6b7280);}
+.rwa-ws-kind{align-self:flex-start;text-transform:uppercase;letter-spacing:.04em;font-size:10px!important;color:#fff!important;background:var(--gray-800,#1f2937);border-radius:4px;padding:2px 6px;}
+.rwa-ws-empty{color:var(--gray-500,#6b7280);line-height:1.5;}
+.rwa-ws-context{display:grid;grid-template-columns:minmax(0,1fr);gap:10px;margin:20px 0 28px;}
+.rwa-ws-context h2{margin:18px 0 0;font-size:1.1rem;}
+.rwa-ws-context h2:first-child{margin-top:0;}
+.rwa-ws-context p,.rwa-ws-context ul,.rwa-ws-context ol{margin:0;line-height:1.55;}
+.rwa-ws-live{margin-top:28px;padding-top:18px;border-top:1px solid var(--gray-200,#e5e7eb);}
+.rwa-ws-live h2{margin:0 0 12px;font-size:1rem;}
+.rwa-ws-live-card{background:#fff;border-color:var(--blue,#2563eb);}
+</style>
+<!-- rwa:frozen:end workspace-style -->
+<article class="rwa-workspace">
+<header>
+  <div>
+    <h1>${escapeHtml(name)}</h1>
+    <p class="rwa-ws-meta">${docs.length} document${docs.length === 1 ? '' : 's'} · synced ${escapeHtml(generatedAt)}</p>
+  </div>
+</header>
+${contextHtml || defaultWorkspaceContext(name)}
+<h2>Workspace documents</h2>
+<section class="rwa-ws-grid" aria-label="Workspace documents">
+${cards}
+</section>
+<section class="rwa-ws-live" data-rwa-workspace-live hidden>
+<h2>Open now</h2>
+<div class="rwa-ws-grid" data-rwa-workspace-live-grid></div>
+</section>
+</article>
+<!-- rwa:frozen:begin workspace-manifest -->
+<script type="application/rwa-workspace+json" id="rwa-workspace" data-rwa-frozen>${safeScriptJson(manifest)}</script>
+<!-- rwa:frozen:end workspace-manifest -->`;
+}
+
+async function writeWorkspaceIndex(dir, { seedCandidates, uuid }) {
+  const indexPath = path.join(dir, WORKSPACE_INDEX);
+  const docs = await scanWorkspace(dir);
+  const name = titleFromDir(dir);
+  let contextHtml = defaultWorkspaceContext(name);
+  try {
+    const existing = await fs.readFile(indexPath, 'utf8');
+    contextHtml = extractWorkspaceContext(extractInlineDoc(existing), name);
+  } catch (e) {
+    if (!(e && e.code === 'ENOENT')) contextHtml = defaultWorkspaceContext(name);
+  }
+  const overrides = kindOverrides('workspace');
+  let html = applySeedSubs(await loadSeed(seedCandidates), {
+    uuid,
+    title: name,
+    fileMeta: WORKSPACE_INDEX,
+    lensPlaceholder: overrides.lensPlaceholder,
+    palPlaceholder: overrides.palPlaceholder,
+    productHeader: overrides.productHeader,
+    productKind: 'workspace',
+    lensClickToAnchor: overrides.lensClickToAnchor,
+  });
+  html = replaceInlineDoc(html, buildWorkspaceBody({ name, docs, contextHtml }));
+  await fs.writeFile(indexPath, html, 'utf8');
+  return { indexPath, docs };
+}
+
+export async function workspaceCreateCmd({ dirPath = '.', force = false, seedCandidates }) {
+  const dir = path.resolve(dirPath);
+  const indexPath = path.join(dir, WORKSPACE_INDEX);
+  await ensureCreateTarget(dir, indexPath, force);
+  return writeWorkspaceIndex(dir, { seedCandidates, uuid: await indexUuid(indexPath) });
+}
+
+export async function workspaceSyncCmd({ dirPath = '.', seedCandidates }) {
+  const dir = path.resolve(dirPath);
+  await ensureSyncTarget(dir);
+  const indexPath = path.join(dir, WORKSPACE_INDEX);
+  return writeWorkspaceIndex(dir, { seedCandidates, uuid: await indexUuid(indexPath) });
+}