openplanr 3.2.0 → 3.4.0

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/integration-files.mjs

@@ -1,18 +1,8 @@
 import { execFile as execFileCallback } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import {
-  linkSync,
-  lstatSync,
-  readFileSync,
-  readlinkSync,
-  renameSync,
-  symlinkSync,
-  unlinkSync,
-} from 'node:fs';
-import { chmod, lstat, mkdir, readFile, rename, rm, symlink, writeFile } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
-import { captureFileState, gitFileState, headFileState } from './custody.mjs';
+import { captureFileState, headFileState } from './custody.mjs';
 
 const execFile = promisify(execFileCallback);
 const gitOptions = { encoding: 'buffer', maxBuffer: 32 * 1024 * 1024 };
@@ -81,303 +71,6 @@ export async function safeDestination(root, path) {
   return full;
 }
 
-export async function putState(root, path, state, suffix, createdDirectories = []) {
-  const target = await safeDestination(root, path);
-  if (state.kind === 'absent') {
-    await rm(target, { force: true });
-    return;
-  }
-  const missing = [];
-  let directory = dirname(target);
-  while (directory !== resolve(root)) {
-    try {
-      await lstat(directory);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      missing.push(directory);
-      directory = dirname(directory);
-    }
-  }
-  for (const created of missing.reverse()) {
-    await mkdir(created);
-    createdDirectories.push(created);
-  }
-  const temporary = `${target}.planr-delegate-${suffix}`;
-  try {
-    if (state.kind === 'file') {
-      await writeFile(temporary, Buffer.from(state.contentBase64, 'base64'), {
-        mode: 0o600,
-        flag: 'wx',
-      });
-      await chmod(temporary, state.mode);
-    } else if (state.kind === 'symlink') {
-      if (
-        isAbsolute(state.target) ||
-        !resolve(dirname(target), state.target).startsWith(`${resolve(root)}${sep}`)
-      )
-        throw new IntegrationError('E_INTEGRATION_LINK', 'Delegate symlink target is unsafe.', {
-          path,
-        });
-      await symlink(state.target, temporary);
-    } else throw new IntegrationError('E_INTEGRATION_STATE', 'Unsupported file state.', { path });
-    await rename(temporary, target);
-  } finally {
-    await rm(temporary, { force: true });
-  }
-}
-
-export function retainedEntryState(file) {
-  try {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink())
-      return { kind: 'symlink', mode: info.mode & 0o777, target: readlinkSync(file) };
-    if (!info.isFile())
-      throw new IntegrationError('E_INTEGRATION_STATE', 'Destination is not a file.', {
-        path: file,
-      });
-    return {
-      kind: 'file',
-      mode: info.mode & 0o777,
-      contentBase64: readFileSync(file).toString('base64'),
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') return { kind: 'absent' };
-    throw error;
-  }
-}
-
-const LOCAL_CUSTODY = '.planr-delegate-write-custody';
-
-async function privateDirectory(path, create = true) {
-  if (create)
-    await mkdir(path, { mode: 0o700 }).catch((error) => {
-      if (error.code !== 'EEXIST') throw error;
-    });
-  const info = await lstat(path);
-  if (
-    !info.isDirectory() ||
-    info.isSymbolicLink() ||
-    (info.mode & 0o077) !== 0 ||
-    (process.getuid && info.uid !== process.getuid())
-  )
-    throw new IntegrationError(
-      'E_INTEGRATION_CUSTODY',
-      'Write custody is not a private directory.',
-    );
-}
-
-// Git metadata can be on another volume. Keep claims and staging beside the
-// destination in that case, and save the location before the first source write.
-async function writeCustody(root, target, suffix, create = true) {
-  if (basename(safePath(suffix)) !== suffix)
-    throw new IntegrationError('E_INTEGRATION_CUSTODY', 'Invalid write custody identifier.');
-  const gitDirectory = (await git(root, 'rev-parse', '--absolute-git-dir')).toString('utf8').trim();
-  const base = resolve(gitDirectory, 'planr-delegate-write-custody');
-  const metadata = resolve(base, suffix);
-  for (const directory of [base, metadata]) {
-    try {
-      await privateDirectory(directory, false);
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-    }
-  }
-  const reference = resolve(metadata, 'location.json');
-  let location;
-  try {
-    location = JSON.parse(await readFile(reference, 'utf8'));
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  if (location) {
-    const directory = await safeDestination(root, location.path);
-    const anchor = dirname(dirname(directory));
-    if (
-      basename(directory) !== suffix ||
-      basename(dirname(directory)) !== LOCAL_CUSTODY ||
-      !target.startsWith(`${anchor}${sep}`)
-    )
-      throw new IntegrationError('E_INTEGRATION_CUSTODY', 'Write custody location changed.');
-    await privateDirectory(dirname(directory), false);
-    await privateDirectory(directory, false);
-    return directory;
-  }
-  if (!create) return metadata;
-  await privateDirectory(base);
-  await privateDirectory(metadata);
-  let anchor = dirname(target);
-  let info;
-  for (;;) {
-    try {
-      info = await lstat(anchor);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      anchor = dirname(anchor);
-    }
-  }
-  if (info.dev === (await lstat(gitDirectory)).dev) return metadata;
-  const local = resolve(anchor, LOCAL_CUSTODY);
-  await privateDirectory(local);
-  const ignore = resolve(local, '.gitignore');
-  try {
-    await writeFile(ignore, '*\n', { flag: 'wx', mode: 0o600 });
-  } catch (error) {
-    if (error.code !== 'EEXIST' || (await readFile(ignore, 'utf8')) !== '*\n') throw error;
-  }
-  const directory = resolve(local, suffix);
-  await privateDirectory(directory);
-  await writeFile(reference, JSON.stringify({ path: relative(root, directory) }), {
-    flag: 'wx',
-    mode: 0o600,
-  });
-  return directory;
-}
-
-function parentEntries(root, target) {
-  const entries = [];
-  for (let path = dirname(target); ; path = dirname(path)) {
-    const info = lstatSync(path);
-    if (!info.isDirectory() || info.isSymbolicLink())
-      throw new IntegrationError(
-        'E_INTEGRATION_PATH',
-        'Destination parent is not a real directory.',
-      );
-    entries.push({ path, dev: info.dev, ino: info.ino });
-    if (path === resolve(root)) return entries;
-  }
-}
-
-function assertParentEntries(entries) {
-  for (const entry of entries) {
-    const info = lstatSync(entry.path);
-    if (
-      !info.isDirectory() ||
-      info.isSymbolicLink() ||
-      info.dev !== entry.dev ||
-      info.ino !== entry.ino
-    )
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'Destination parent changed during integration.',
-        { path: entry.path },
-      );
-  }
-}
-
-// Claim the current directory entry, inspect the claimed bytes, then publish with
-// exclusive link creation. A concurrent replacement is never overwritten. Claimed
-// entries remain private for crash recovery and for writers holding the old inode.
-export async function putStateGuarded(
-  root,
-  path,
-  state,
-  expected,
-  suffix,
-  createdDirectories = [],
-) {
-  const target = await safeDestination(root, path);
-  const custody = await writeCustody(root, target, suffix);
-  const key = createHash('sha256').update(path).digest('hex');
-  const claimed = resolve(custody, `${key}.before`);
-  const staged = `${key}.after-${randomUUID()}`;
-  await assertSafeChanges(root, [{ path, after: state }]);
-  if (state.kind === 'file') {
-    await writeFile(resolve(custody, staged), Buffer.from(state.contentBase64, 'base64'), {
-      flag: 'wx',
-      mode: 0o600,
-    });
-    await chmod(resolve(custody, staged), state.mode);
-  } else if (state.kind === 'symlink') await symlink(state.target, resolve(custody, staged));
-  const missing = [];
-  let directory = dirname(target);
-  while (directory !== resolve(root)) {
-    try {
-      await lstat(directory);
-      break;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-      missing.push(directory);
-      directory = dirname(directory);
-    }
-  }
-  for (const created of missing.reverse()) {
-    await mkdir(created);
-    createdDirectories.push(created);
-  }
-  const parents = parentEntries(root, target);
-  let moved = false;
-  let published = false;
-  try {
-    if (expected.kind !== 'absent') {
-      try {
-        if (retainedEntryState(claimed).kind === 'absent') renameSync(target, claimed);
-        moved = true;
-      } catch (error) {
-        if (error.code !== 'ENOENT') throw error;
-      }
-      if (!moved || !sameState(retainedEntryState(claimed), expected))
-        throw new IntegrationError(
-          'E_INTEGRATION_SOURCE_DRIFT',
-          'Destination changed before its write was claimed.',
-          { path, retainedPath: moved ? claimed : null },
-        );
-    }
-    assertParentEntries(parents);
-    // link is atomic and fails if an editor created a replacement during the claim.
-    if (state.kind !== 'absent') {
-      if (state.kind === 'symlink') symlinkSync(state.target, target);
-      else linkSync(resolve(custody, staged), target);
-      published = true;
-    } else if (retainedEntryState(target).kind !== 'absent')
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A concurrent replacement blocks deletion.',
-        { path, retainedPath: claimed },
-      );
-    assertParentEntries(parents);
-    if (moved && !sameState(retainedEntryState(claimed), expected))
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A writer changed the claimed original; retained for recovery.',
-        { path, retainedPath: claimed },
-      );
-    return moved ? claimed : null;
-  } catch (error) {
-    if (published)
-      error.details = { ...error.details, published: true, path, retainedPath: claimed };
-    if (moved) {
-      // Restore exclusively: an owner's replacement always takes precedence.
-      try {
-        assertParentEntries(parents);
-        const original = retainedEntryState(claimed);
-        if (original.kind === 'symlink') symlinkSync(original.target, target);
-        else linkSync(claimed, target);
-      } catch (restoreError) {
-        if (restoreError.code !== 'EEXIST')
-          error.details = { ...error.details, restoreCode: restoreError.code };
-      }
-    }
-    if (error.code === 'EEXIST')
-      throw new IntegrationError(
-        'E_INTEGRATION_SOURCE_DRIFT',
-        'A concurrent destination was preserved.',
-        { path, retainedPath: moved ? claimed : null },
-      );
-    throw error;
-  } finally {
-    if (state.kind !== 'absent') {
-      try {
-        unlinkSync(resolve(custody, staged));
-      } catch (error) {
-        // Staging is private and recoverable; cleanup failure must not replace a write conflict.
-        if (error.code !== 'ENOENT')
-          process.emitWarning(`Private write staging cleanup failed: ${error.code}`);
-      }
-    }
-  }
-}
-
 export async function workingPaths(root) {
   const [tracked, untracked] = await Promise.all([
     git(root, 'diff', '--name-only', '-z', 'HEAD'),
@@ -426,75 +119,3 @@ export async function assertSafeChanges(root, changes) {
       });
   }
 }
-
-export async function rollbackWritten(root, changes, suffix) {
-  const errors = [];
-  for (const change of [...changes].reverse()) {
-    try {
-      const current = await captureFileState(root, change.path);
-      if (sameState(current, change.sourceBefore)) continue;
-      let claimed;
-      if (change.writeId) {
-        const target = await safeDestination(root, change.path);
-        const directory = await writeCustody(root, target, change.writeId, false);
-        const file = `${createHash('sha256').update(change.path).digest('hex')}.before`;
-        claimed = retainedEntryState(resolve(directory, file));
-        if (claimed.kind !== 'absent' && !sameState(claimed, change.sourceBefore)) {
-          errors.push({
-            path: change.path,
-            retainedPath: resolve(directory, file),
-            code: 'E_INTEGRATION_ROLLBACK_CONFLICT',
-          });
-          continue;
-        }
-      }
-      if (
-        current.kind === 'absent' &&
-        claimed?.kind !== 'absent' &&
-        claimed &&
-        sameState(claimed, change.sourceBefore)
-      ) {
-        await putStateGuarded(
-          root,
-          change.path,
-          change.sourceBefore,
-          current,
-          `${suffix}-interrupted`,
-        );
-        continue;
-      }
-      if (!sameState(current, change.after)) {
-        errors.push({ path: change.path, code: 'E_INTEGRATION_ROLLBACK_CONFLICT' });
-        continue;
-      }
-      await putStateGuarded(
-        root,
-        change.path,
-        change.sourceBefore,
-        change.after,
-        change.writeId ? `${change.writeId}-rollback` : `${suffix}-rollback`,
-      );
-    } catch (error) {
-      errors.push({ path: change.path, code: error.code ?? 'E_INTEGRATION_ROLLBACK' });
-    }
-  }
-  return errors;
-}
-
-export async function treeIdentity(root, overrides = new Map()) {
-  const paths = new Set(
-    (await git(root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'))
-      .toString('utf8')
-      .split('\0')
-      .filter(Boolean),
-  );
-  for (const path of overrides.keys()) paths.add(path);
-  const hash = createHash('sha256');
-  for (const path of [...paths].sort()) {
-    const state = overrides.get(path) ?? (await captureFileState(root, safePath(path)));
-    const logical = await gitFileState(root, path, state);
-    if (logical.kind !== 'absent')
-      hash.update(path).update('\0').update(JSON.stringify(logical)).update('\0');
-  }
-  return hash.digest('hex');
-}

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/presentation.mjs

@@ -94,6 +94,16 @@ export function handoffPresentation(outcome) {
   };
 }
 
+function warningText({ refs, omitted }) {
+  return `Refs changed outside this run (not blocking): ${refs.join(', ')}${omitted ? ` and ${omitted} more` : ''}`;
+}
+
+function violationText({ code, path, ref, change, omitted }) {
+  if (omitted) return `${code}: ${omitted} more path(s)`;
+  if (!path) return ref ? `${code}: ${ref}` : code;
+  return change ? `${code}: ${path} (${change})` : `${code}: ${path}`;
+}
+
 export function reviewPresentation(review) {
   return {
     phase: 'review',
@@ -102,7 +112,8 @@ export function reviewPresentation(review) {
       ? `${review.changedPaths.length} observed file change(s) ready for human review; nothing has been integrated.`
       : 'Observed changes require attention before integration.',
     changed: visiblePaths(review.changedPaths),
-    violations: review.violations.map(({ code, path }) => (path ? `${code}: ${path}` : code)),
+    violations: review.violations.map(violationText),
+    warnings: (review.warnings ?? []).map(warningText),
     nextAction: review.ready
       ? 'Inspect the retained worktree patch and then call apply with the same scope.'
       : 'Resolve the violations in the retained worktree or source before retrying.',
@@ -121,7 +132,8 @@ export function implementationReport(result, selector) {
     ...(result.cleanup?.status === 'failed'
       ? ['Owned worktree cleanup failed; integration remains accepted']
       : []),
-    ...(result.violations ?? []).map(({ code, path }) => (path ? `${code}: ${path}` : code)),
+    ...(result.violations ?? []).map(violationText),
+    ...(result.warnings ?? []).map(warningText),
     ...(result.code ? [result.code] : []),
     ...failed.map(({ command, status, exitCode, timeoutMs, classification }) =>
       status === 'timed-out'
@@ -136,6 +148,10 @@ export function implementationReport(result, selector) {
         ]
       : []),
   ];
+  const unselected = result.unselectedDirtyPaths ?? [];
+  const unselectedNote = unselected.length
+    ? ` Checks did not include ${result.unselectedDirtyCount ?? unselected.length} unselected local change(s): ${visiblePaths(unselected)}.`
+    : '';
   return {
     Outcome: accepted
       ? paths.length
@@ -146,16 +162,17 @@ export function implementationReport(result, selector) {
     Changed: paths.length
       ? `${paths.length} observed file(s) ${accepted ? 'integrated' : 'not accepted'}: ${visiblePaths(paths)}`
       : 'No observed file changes.',
-    Checks: checks.length
-      ? `${checks.filter(({ status }) => status === 'passed').length}/${checks.length} independent check(s) passed: ${checks
-          .map(
-            ({ command, status, durationMs }) =>
-              `${command} (${status}${
-                durationMs === undefined ? '' : `, ${(durationMs / 1000).toFixed(1)}s`
-              })`,
-          )
-          .join(', ')}`
-      : 'No independent checks ran; verification remains unconfirmed.',
+    Checks:
+      (checks.length
+        ? `${checks.filter(({ status }) => status === 'passed').length}/${checks.length} independent check(s) passed: ${checks
+            .map(
+              ({ command, status, durationMs }) =>
+                `${command} (${status}${
+                  durationMs === undefined ? '' : `, ${(durationMs / 1000).toFixed(1)}s`
+                })`,
+            )
+            .join(', ')}${unselectedNote ? '.' : ''}`
+        : 'No independent checks ran; verification remains unconfirmed.') + unselectedNote,
     Issues: issues.length
       ? `${issues.join('; ')}.${accepted ? '' : ` ${result.nextAction ?? ''}`}`.trim()
       : 'None found in this review.',

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-contract.mjs

@@ -55,6 +55,17 @@ export function integrationPaths(paths) {
             'E_DELEGATE_SCOPE',
             'Integration paths must be safe repository-relative paths.',
           );
+        // Scope entries are literal prefixes; a glob would only fail later at review.
+        const parts = path.split('/');
+        const glob = parts.findIndex((part) => /[*?]/u.test(part));
+        if (glob !== -1) {
+          throw new DelegateRunError(
+            'E_DELEGATE_SCOPE',
+            glob > 0
+              ? `Integration paths are literal path prefixes, not globs; use "${parts.slice(0, glob).join('/')}" instead of "${path}".`
+              : `Integration paths are literal path prefixes, not globs; list the files or directories "${path}" should cover.`,
+          );
+        }
         return path;
       }),
     ),

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-execution.mjs

@@ -42,7 +42,7 @@ const SAFE_ADAPTER_DIAGNOSTICS = Object.freeze({
   E_ADAPTER_PROCESS_IDENTITY:
     'Process identity inspection is unavailable. Restore normal host process inspection before retrying; native permissions were not changed.',
   E_ADAPTER_PERMISSION:
-    'Native permission needs attention. Resolve it in the native configuration, then continue this exact session; permissions are never weakened automatically.',
+    'Native permission needs attention. Resolve it in the native configuration, then continue this exact session; permissions are never bypassed automatically.',
   E_ADAPTER_RESULT:
     'Native execution ended without terminal evidence; inspect the exact session and retained worktree.',
   E_ADAPTER_MODEL_TEMPLATE:

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-lifecycle.mjs

@@ -5,7 +5,7 @@ import { basename, dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { terminateProcessGroup } from './adapters/generic.mjs';
 import { captureFileState, cleanupWorktreeCustody, validateWorktreeCustody } from './custody.mjs';
-import { git, treeIdentity } from './integration-files.mjs';
+import { git } from './integration-files.mjs';
 import {
   implementationReport,
   liveExecutionTiming,
@@ -118,8 +118,13 @@ async function initialAbandonmentInventory(record, custody) {
     (record.initialIndex && record.initialIndex !== custody.initialIndex)
   )
     throw abandonError(record, 'The initial worktree HEAD, index or protected contents changed.');
+  if (
+    custody.base &&
+    (await git(target, 'rev-parse', 'HEAD')).toString('utf8').trim() !== custody.base
+  )
+    throw abandonError(record, 'The run branch advanced past its base commit.');
   const entries = new Map(
-    (await git(target, 'ls-tree', '-r', '-z', custody.initialHead))
+    (await git(target, 'ls-tree', '-r', '-z', custody.base ?? custody.initialHead))
       .toString('utf8')
       .split('\0')
       .filter(Boolean)
@@ -338,6 +343,12 @@ export async function recoverDelegateRun({ runId, runDirectory = defaultRunDirec
   });
 }
 
+async function worktreeAtTip(target, tip) {
+  const head = (await git(target, 'rev-parse', 'HEAD')).toString('utf8').trim();
+  const status = await git(target, 'status', '--porcelain=v1', '-z', '--untracked-files=all');
+  return head === tip && status.length === 0;
+}
+
 export async function cleanupAcceptedWorktree(record, runDirectory) {
   if (record.cleanup?.status === 'removed') return record.cleanup;
   const disposition = record.disposition === 'integrated' ? 'accepted' : 'abandoned';
@@ -357,11 +368,7 @@ export async function cleanupAcceptedWorktree(record, runDirectory) {
     beforeRemove: async (target) => {
       if (unstarted)
         await assertUnchangedAbandonment(record, await custodyAt(record, runDirectory));
-      if (
-        record.nativeSelection &&
-        record.integration?.worktreeIdentity &&
-        (await treeIdentity(target)) !== record.integration.worktreeIdentity
-      )
+      if (record.integration?.tip && !(await worktreeAtTip(target, record.integration.tip)))
         throw new DelegateRunError(
           'E_DELEGATE_CLEANUP_DRIFT',
           'Owned worktree changed after acceptance; retain it for inspection.',
@@ -450,9 +457,6 @@ export async function delegateRunStatus({ runId, runDirectory = defaultRunDirect
       ? {
           status: record.integration.status,
           phase: record.integration.phase,
-          journalPath: record.integration.journalPath,
-          cursor: record.integration.cursor,
-          pendingPath: record.integration.pendingPath,
           nextAction: `Run node ${record.helper?.integrationPath ?? 'integrate.mjs'} recover with this run ID and resolution rollback (default) or accept after verifying every written path.`,
         }
       : null,

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-preparation.mjs

@@ -273,6 +273,8 @@ export async function prepareDelegateRun({
       worktreeParent: custodyParent,
       runId,
       native: prepared.profile.kind !== 'generic',
+      branch: true,
+      runDirectory: privateDirectory,
     });
     const custodyPath = join(runPath, 'custody.json');
     await updateRunRecord(
@@ -282,6 +284,8 @@ export async function prepareDelegateRun({
         worktreePath: custody.worktreePath,
         initialHead: custody.initialHead,
         initialIndex: custody.initialIndex,
+        branch: custody.branch,
+        base: custody.base,
       },
       { directory: privateDirectory },
     );

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/run-record.mjs

@@ -17,7 +17,7 @@ import { promisify } from 'node:util';
 import { CREDENTIAL_FORMAT } from './credentials.mjs';
 import { captureFileState } from './custody.mjs';
 
-export const RUN_RECORD_SCHEMA_VERSION = '2.0.0';
+export const RUN_RECORD_SCHEMA_VERSION = '3.0.0';
 export const MAX_RUN_RECORD_BYTES = 64 * 1024;
 export const CLOSED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
@@ -64,7 +64,7 @@ function encoded(record) {
   if (
     !record ||
     record.kind !== 'openplanr-delegation-run' ||
-    !['1.0.0', RUN_RECORD_SCHEMA_VERSION].includes(record.schemaVersion) ||
+    !['1.0.0', '2.0.0', RUN_RECORD_SCHEMA_VERSION].includes(record.schemaVersion) ||
     !RUN_ID.test(record.runId ?? '')
   ) {
     throw new RunRecordError('E_RUN_FORMAT', 'Invalid delegated run record.');

package/lib/host-packages/claude/openplanr/skills/design/references/design-system.md

@@ -54,8 +54,23 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshotting needs network access while authoring. When it is unavailable, or a
-license is unclear, use the role's system stack and name that fallback in the return:
+Snapshot with the bundled helper, run from the skill directory (see
+[utilities.md](utilities.md)):
+
+```sh
+node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+```
+
+It is the one command to ask approval for. A host that allowlists network access by
+domain needs `raw.githubusercontent.com`, `fonts.googleapis.com` and
+`fonts.gstatic.com`. It enforces the rules above, verifies each
+license from the Google Fonts catalog, writes `fonts.css`, and prints the files and
+total bytes. Start the design stylesheet with `@import "assets/fonts/fonts.css";`
+(relative to that stylesheet), then use the families by name. Nothing is fetched when
+a design opens.
+
+When the host denies network access, the command fails, or it refuses a license, use
+the role's system stack and name that fallback in the return:
 
 | Role | System stack |
 | --- | --- |