runlist 0.0.0 → 0.94.1

package/src/output-identity.mjs

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export const HTML_FALLBACK_DIR = '__runlist';
+// Exports written by dotmd-cli 0.78.0 and earlier put fallbacks under this
+// directory, and an old export tree may still hold it. It stays reserved so a
+// document's own path can never land inside a stale fallback directory.
+export const LEGACY_HTML_FALLBACK_DIR = '__dotmd';
+const RESERVED_FALLBACK_DIRS = [HTML_FALLBACK_DIR, LEGACY_HTML_FALLBACK_DIR];
+
+function normalizeRelative(value, kind) {
+  if (typeof value !== 'string' || value.includes('\0')) {
+    throw new Error(`${kind} must be a string without NUL bytes`);
+  }
+  const normalized = path.posix.normalize(value || '.');
+  if (path.posix.isAbsolute(normalized)) throw new Error(`${kind} must be relative: ${value}`);
+  return normalized;
+}
+
+function isTraversal(value) {
+  return value === '..' || value.startsWith('../');
+}
+
+function pathsConflict(a, b) {
+  const left = a.toLowerCase();
+  const right = b.toLowerCase();
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function validateHtmlPath(value) {
+  const normalized = normalizeRelative(value, 'HTML output path');
+  if (normalized === '.' || isTraversal(normalized) || normalized !== value) {
+    throw new Error(`Unsafe HTML output path: ${value}`);
+  }
+  return normalized;
+}
+
+export function outputPathToUrl(value) {
+  return validateHtmlPath(value).split('/').map(encodeURIComponent).join('/');
+}
+
+export function allocateOutputIdentities(docs) {
+  const entries = [];
+  const logicalIds = new Set();
+
+  for (const doc of docs) {
+    const logicalId = normalizeRelative(doc.path, 'Document path');
+    if (logicalIds.has(logicalId)) throw new Error(`Duplicate document path: ${logicalId}`);
+    logicalIds.add(logicalId);
+
+    const root = normalizeRelative(doc.root || '.', 'Document root');
+    const relativeSource = path.posix.relative(root, logicalId);
+    if (!relativeSource || isTraversal(relativeSource) || path.posix.isAbsolute(relativeSource)) {
+      throw new Error(`Document path is not owned by its root: ${logicalId} (root: ${root})`);
+    }
+    if (!relativeSource.toLowerCase().endsWith('.md')) {
+      throw new Error(`Document path must end in .md: ${logicalId}`);
+    }
+
+    const preferred = validateHtmlPath(relativeSource.slice(0, -3) + '.html');
+    entries.push({
+      logicalId,
+      label: path.posix.basename(logicalId, path.posix.extname(logicalId)),
+      preferred,
+      conflict: preferred.toLowerCase() === 'index.html'
+        || preferred.toLowerCase().startsWith('index.html/')
+        || RESERVED_FALLBACK_DIRS.some(dir => preferred.toLowerCase().startsWith(`${dir.toLowerCase()}/`)),
+    });
+  }
+
+  entries.sort((a, b) => a.logicalId.localeCompare(b.logicalId));
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      if (!pathsConflict(entries[i].preferred, entries[j].preferred)) continue;
+      entries[i].conflict = true;
+      entries[j].conflict = true;
+    }
+  }
+
+  const digestOwners = new Map();
+  for (const entry of entries) {
+    if (!entry.conflict) {
+      entry.htmlPath = entry.preferred;
+      continue;
+    }
+    const digest = createHash('sha256').update(entry.logicalId).digest('hex');
+    const owner = digestOwners.get(digest);
+    if (owner && owner !== entry.logicalId) {
+      throw new Error(`Output identity hash collision: ${owner} and ${entry.logicalId}`);
+    }
+    digestOwners.set(digest, entry.logicalId);
+    entry.htmlPath = `${HTML_FALLBACK_DIR}/${digest}.html`;
+  }
+
+  const finalEntries = [...entries].sort((a, b) => a.htmlPath.localeCompare(b.htmlPath));
+  for (let i = 0; i < finalEntries.length; i++) {
+    validateHtmlPath(finalEntries[i].htmlPath);
+    for (let j = i + 1; j < finalEntries.length; j++) {
+      if (pathsConflict(finalEntries[i].htmlPath, finalEntries[j].htmlPath)) {
+        throw new Error(`Conflicting HTML output paths: ${finalEntries[i].htmlPath} and ${finalEntries[j].htmlPath}`);
+      }
+    }
+  }
+
+  return new Map(entries.map(entry => [entry.logicalId, {
+    logicalId: entry.logicalId,
+    label: entry.label,
+    htmlPath: entry.htmlPath,
+    htmlUrl: outputPathToUrl(entry.htmlPath),
+  }]));
+}

package/src/parent-plan.mjs

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { MutationConflictError } from './atomic-mutation.mjs';
+import { escapeRegex, normalizeStringList, nowIso, resolveRefPath, toRepoPath } from './util.mjs';
+
+// Replace a top-level frontmatter field (its `key:` line + any indented
+// continuation block) with `serialized`, or append it when absent. Shared by
+// runlist mutations and the membership back-reference fixer so both paths
+// serialize `parent_plan:` identically.
+export function upsertFrontmatterField(fm, key, serialized) {
+  const re = new RegExp(`^${escapeRegex(key)}:.*(\\n[ \\t]+.*)*`, 'm');
+  if (re.test(fm)) return fm.replace(re, serialized);
+  return fm.replace(/\s*$/, '') + '\n' + serialized;
+}
+
+// Plan an atomic child-side `parent_plan:` update. The caller owns the evidence
+// that authorizes the relationship (a runlist entry or body-order row); this
+// helper owns the byte-level invariant: never clobber another parent, write a
+// child-relative forward-slash ref, bump `updated:`, and compare-and-swap the
+// exact child snapshot used to make the decision.
+export function planChildParentUpdate(childAbs, hubAbs, config) {
+  const raw = readFileSync(childAbs, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  if (fmRaw == null) return { wrote: false, reason: 'missing-frontmatter', raw };
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const childDir = path.dirname(childAbs);
+  const existingRefs = normalizeStringList(fm.parent_plan);
+  if (existingRefs.length > 0) {
+    const resolved = existingRefs.map(ref => resolveRefPath(ref, childDir, config.repoRoot));
+    if (existingRefs.length === 1 && resolved[0] === hubAbs) {
+      return { wrote: false, reason: 'already-set', raw };
+    }
+    return { wrote: false, reason: 'different-parent', existing: existingRefs.join(', '), raw };
+  }
+  const ref = path.relative(childDir, hubAbs).split(path.sep).join('/');
+  return {
+    wrote: true,
+    ref,
+    raw,
+    update: {
+      path: childAbs,
+      expectedContent: raw,
+      render: current => {
+        const { frontmatter: currentFm } = extractFrontmatter(current);
+        const currentParsed = parseSimpleFrontmatter(currentFm);
+        const currentParents = normalizeStringList(currentParsed.parent_plan);
+        if (currentParents.length > 0
+          && !(currentParents.length === 1 && resolveRefPath(currentParents[0], childDir, config.repoRoot) === hubAbs)) {
+          throw new MutationConflictError(`Child parent_plan changed while the membership mutation was being prepared: ${toRepoPath(childAbs, config.repoRoot)}`);
+        }
+        let updatedFm = upsertFrontmatterField(currentFm, 'parent_plan', `parent_plan: ${ref}`);
+        updatedFm = upsertFrontmatterField(updatedFm, 'updated', `updated: ${nowIso()}`);
+        return replaceFrontmatter(current, updatedFm);
+      },
+    },
+  };
+}

package/src/parse-cache.mjs

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commitRename } from './durable-rename.mjs';
+import { readEnv, stateDir } from './naming.mjs';
+
+// What every build of the index used to redo from scratch: read each document
+// and pull its frontmatter, links, checklist and summary out of the body. None
+// of that depends on the config or the clock, so it is kept per file under the
+// state directory and reused while the file's size, times and inode are
+// unchanged. Everything that does depend on them (terminal statuses, staleness,
+// reference fields, validation) is still computed on every run.
+//
+// One line per document, `path \t stamp \t json`, so a hit parses only its own
+// line and hands back fresh objects: nothing a caller does to a document can
+// leak into what is saved. The cache is an optimisation and never an input:
+// a missing, unreadable or foreign-version file is treated as empty, a failed
+// write is dropped, and `RUNLIST_NO_PARSE_CACHE=1` turns it off.
+
+const SCHEMA = 1;
+const FILE_NAME = 'parse-cache';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version; }
+  catch { return 'unknown'; }
+})();
+const HEADER = JSON.stringify({ schema: SCHEMA, version: VERSION });
+
+export function fileStamp(filePath) {
+  try {
+    const s = statSync(filePath, { bigint: true });
+    return `${s.size}:${s.mtimeNs}:${s.ctimeNs}:${s.ino}`;
+  } catch {
+    return null;
+  }
+}
+
+export function stampSize(stamp) {
+  return Number(stamp.slice(0, stamp.indexOf(':')));
+}
+
+export function openParseCache(config) {
+  if (readEnv('NO_PARSE_CACHE') === '1') return null;
+  const dir = stateDir(config.repoRoot);
+  // The state directory is created, and ignored by git, by `init` and the
+  // commands that own it; a repo without one gets no cache rather than a new
+  // untracked folder from a read-only command.
+  if (!existsSync(dir)) return null;
+  const cachePath = path.join(dir, FILE_NAME);
+  const lines = new Map();
+  try {
+    const text = readFileSync(cachePath, 'utf8');
+    const rows = text.split('\n');
+    if (rows[0] === HEADER) {
+      for (let i = 1; i < rows.length; i++) {
+        const row = rows[i];
+        const a = row.indexOf('\t');
+        const b = row.indexOf('\t', a + 1);
+        if (a < 0 || b < 0) continue;
+        lines.set(row.slice(0, a), { stamp: row.slice(a + 1, b), row });
+      }
+    }
+  } catch { /* no cache yet */ }
+
+  const seen = new Set();
+  let dirty = false;
+
+  return {
+    get(key, stamp) {
+      seen.add(key);
+      const entry = lines.get(key);
+      if (!entry || entry.stamp !== stamp) return null;
+      try { return JSON.parse(entry.row.slice(entry.row.indexOf('\t', entry.row.indexOf('\t') + 1) + 1)); }
+      catch { return null; }
+    },
+    set(key, stamp, value) {
+      seen.add(key);
+      if (/[\t\n]/.test(key)) return;
+      lines.set(key, { stamp, row: `${key}\t${stamp}\t${JSON.stringify(value)}` });
+      dirty = true;
+    },
+    save({ complete = true } = {}) {
+      if (complete) {
+        for (const key of lines.keys()) {
+          if (!seen.has(key)) { lines.delete(key); dirty = true; }
+        }
+      }
+      if (!dirty) return;
+      const temp = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
+      try {
+        writeFileSync(temp, [HEADER, ...[...lines.values()].map(entry => entry.row)].join('\n'), 'utf8');
+        commitRename(temp, cachePath);
+        dirty = false;
+      } catch {
+        try { unlinkSync(temp); } catch { /* already gone */ }
+      }
+    },
+  };
+}

package/src/path-containment.mjs

@@ -0,0 +1,15 @@
+import path from 'node:path';
+
+// Lexical preflight only. Callers must also check canonical filesystem paths
+// when authorizing real files, so symlink/junction parents cannot escape.
+export function isPathInside(root, file, paths = path) {
+  if (!paths.isAbsolute(root) || !paths.isAbsolute(file)) return false;
+  const relative = paths.relative(root, file);
+  return relative === '' || (relative !== '..'
+    && !relative.startsWith(`..${paths.sep}`) && !paths.isAbsolute(relative));
+}
+
+export function containingRoot(file, roots, paths = path) {
+  return roots.filter(root => isPathInside(root, file, paths))
+    .sort((a, b) => paths.resolve(b).length - paths.resolve(a).length)[0] ?? null;
+}

package/src/pickup-card.mjs

@@ -0,0 +1,293 @@
+import { referenceValues } from './reference-values.mjs';
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
+import { compareYardstick, readYardstick, renderYardstick } from './yardstick.mjs';
+import { walkSections, findSection, findActivePhase, summarizePhases, isPhaseHeading, detectMarker } from './section.mjs';
+import { dim, green } from './color.mjs';
+
+const CAPS = {
+  blurb: 200,
+  currentState: 500,
+  nextStep: 300,
+  versionHistoryEntry: 200,
+};
+
+function countBullets(body) {
+  if (!body) return 0;
+  return body.split('\n').filter(l => /^[-*]\s+\S/.test(l)).length;
+}
+
+function truncate(s, cap) {
+  if (!s) return '';
+  if (s.length <= cap) return s;
+  return s.slice(0, cap - 3).trimEnd() + '...';
+}
+
+function statusSummary(counts) {
+  const order = ['shipped', 'skipped', 'in-progress', 'blocked', 'todo'];
+  const icons = { shipped: '✅', skipped: '⏭', 'in-progress': '🟡', blocked: '🚧', todo: '⬜' };
+  return order.filter(k => counts[k]).map(k => `${counts[k]}${icons[k]}`).join(' ');
+}
+
+// `docDir` is the directory of the doc whose frontmatter we're reading.
+// Pre-fix: this used `resolveDocPath` which only tries repo-root and docsRoots-
+// relative, NOT doc-relative — so a bare basename like `sibling-plan.md` written
+// in `docs/plans/foo.md`'s `related_plans:` always showed `(missing)`, even
+// though graph/validate resolve the same ref fine via `resolveRefPath`. Now
+// matches graph's resolver semantics: doc-relative first, then repo-relative;
+// docsRoots-relative is kept as a final fallback for legacy refs.
+function readRelatedSummary(rawList, config, docDir) {
+  const list = referenceValues(rawList).paths;
+  const out = [];
+  for (const ref of list) {
+    if (!ref) continue;
+    const refStr = String(ref).trim();
+    if (!refStr) continue;
+    let abs = null;
+    try {
+      abs = resolveRefPath(refStr, docDir, config.repoRoot)
+        ?? resolveDocPath(refStr, config);
+    } catch { abs = null; }
+    if (!abs || !existsSync(abs)) {
+      out.push({ ref: refStr, status: null, missing: true });
+      continue;
+    }
+    try {
+      const raw = readFileSync(abs, 'utf8');
+      const { frontmatter } = extractFrontmatter(raw);
+      const fm = parseSimpleFrontmatter(frontmatter);
+      out.push({
+        ref: toRepoPath(abs, config.repoRoot),
+        status: asString(fm.status) ?? null,
+        missing: false,
+      });
+    } catch {
+      out.push({ ref: refStr, status: null, missing: true });
+    }
+  }
+  return out;
+}
+
+// Build the structured card object. Pure: no IO beyond what's passed in.
+export function buildCard(filePath, raw, config) {
+  const { frontmatter: fmRaw, body, bodyLineOffset } = extractFrontmatter(raw);
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const sections = walkSections(body);
+
+  // Title + blurb
+  const titleSection = sections.find(s => s.level === 1) ?? null;
+  const title = titleSection ? titleSection.heading : path.basename(filePath, '.md');
+  // Blurb = first blockquote line(s) after the H1, or first paragraph
+  const lines = body.split('\n');
+  let blurb = '';
+  if (titleSection) {
+    for (let i = titleSection.bodyLineStart - 1; i < lines.length; i++) {
+      const ln = lines[i];
+      if (!ln.trim()) {
+        if (blurb) break;
+        else continue;
+      }
+      if (ln.startsWith('## ') || ln.startsWith('# ')) break;
+      blurb += (blurb ? '\n' : '') + ln;
+    }
+  }
+  blurb = truncate(blurb.replace(/^> ?/gm, '').trim(), CAPS.blurb);
+
+  // Frontmatter pointers. The simple parser doesn't handle YAML multiline blocks
+  // (`>`, `|`); when only the marker char survives, treat as empty.
+  const cleanInline = (v) => {
+    const s = asString(v);
+    if (!s) return '';
+    if (/^[>|][+-]?$/.test(s.trim())) return '';
+    return s;
+  };
+  const status = asString(fm.status) ?? null;
+  const updated = asString(fm.updated) ?? null;
+  const currentState = truncate(cleanInline(fm.current_state), CAPS.currentState);
+  const nextStep = truncate(cleanInline(fm.next_step), CAPS.nextStep);
+  const delivers = typeof fm.delivers === 'string' ? fm.delivers.trim() : null;
+  const goal = asString(fm.type) === 'plan' ? readYardstick(config) : { enabled: false };
+  const yardstick = goal.enabled ? compareYardstick(fm, config, goal,
+    isArchivedPath(toRepoPath(filePath, config.repoRoot), config) || config.lifecycle?.archiveStatuses?.has(status)) : null;
+
+  // Related plans (compressed: slug + status only — show all, don't cap count).
+  // docDir lets the resolver try same-dir basenames first — graph/validate do this
+  // already; pickup-card now matches.
+  const docDir = path.dirname(filePath);
+  const related = [
+    ...readRelatedSummary(fm.parent_plan, config, docDir).map(r => ({ ...r, kind: 'parent' })),
+    ...readRelatedSummary(fm.related_plans, config, docDir).map(r => ({ ...r, kind: 'related' })),
+  ];
+
+  // Phases summary + active phase (pointer only, no body)
+  const phaseSummary = summarizePhases(sections);
+  const toFileLine = line => line + bodyLineOffset;
+  const phaseSummaryForCard = {
+    ...phaseSummary,
+    phases: phaseSummary.phases.map(phase => ({
+      ...phase,
+      lineStart: toFileLine(phase.lineStart),
+      lineEnd: toFileLine(phase.lineEnd),
+      bodyLineStart: toFileLine(phase.bodyLineStart),
+    })),
+  };
+  const activePhase = findActivePhase(sections);
+  let activePhasePointer = null;
+  if (activePhase) {
+    activePhasePointer = {
+      heading: activePhase.heading,
+      lineStart: toFileLine(activePhase.lineStart),
+      lineEnd: toFileLine(activePhase.lineEnd),
+      marker: detectMarker(activePhase.heading),
+    };
+  }
+
+  // Old-plan fallback: no ## Phases section → point to last H2 as "active content"
+  let fallbackPointer = null;
+  if (!findSection(sections, 'Phases') && !activePhase) {
+    const h2s = sections.filter(s => s.level === 2);
+    const lastH2 = h2s[h2s.length - 1] ?? null;
+    if (lastH2) {
+      fallbackPointer = {
+        heading: lastH2.heading,
+        lineStart: toFileLine(lastH2.lineStart),
+        lineEnd: toFileLine(lastH2.lineEnd),
+      };
+    }
+  }
+
+  // Open Questions — count + pointer only, no body
+  const oqSection = findSection(sections, 'Open Questions') ?? findSection(sections, 'Open questions');
+  let openQuestions = null;
+  if (oqSection && oqSection.body.trim()) {
+    openQuestions = {
+      heading: oqSection.heading,
+      lineStart: toFileLine(oqSection.lineStart),
+      lineEnd: toFileLine(oqSection.lineEnd),
+      count: countBullets(oqSection.body),
+    };
+  }
+
+  // Last Version History entry (newest = first bullet under the heading)
+  const vhSection = findSection(sections, 'Version History');
+  let lastVersion = null;
+  if (vhSection && vhSection.body.trim()) {
+    const firstBullet = vhSection.body.split('\n').find(l => /^[-*]\s/.test(l));
+    if (firstBullet) lastVersion = truncate(firstBullet.replace(/^[-*]\s+/, ''), CAPS.versionHistoryEntry);
+  }
+
+  // Outline = all H2 headings with line ranges; phase summary inline if Phases present
+  const outline = sections.filter(s => s.level === 2).map(s => {
+    const isPhases = /^phases?$/i.test(s.heading.replace(/[^\w\s]+$/, '').trim());
+    const lineStart = toFileLine(s.lineStart);
+    const lineEnd = toFileLine(s.lineEnd);
+    let suffix = `lines ${lineStart}-${lineEnd}`;
+    if (isPhases && phaseSummary.total > 0) {
+      suffix = `(${phaseSummary.total}: ${statusSummary(phaseSummary.counts)})  ${suffix}`;
+    }
+    return { heading: s.heading, lineStart, lineEnd, suffix };
+  });
+
+  return {
+    path: toRepoPath(filePath, config.repoRoot),
+    title,
+    status,
+    updated,
+    blurb,
+    currentState,
+    nextStep,
+    delivers,
+    yardstick,
+    related,
+    phases: phaseSummaryForCard,
+    activePhase: activePhasePointer,
+    fallbackContent: fallbackPointer,
+    openQuestions,
+    lastVersion,
+    outline,
+    bodyBytes: body.length,
+    bodyLineOffset,
+    coordinateSpace: 'file',
+  };
+}
+
+// Render the card to human-format string.
+export function renderCard(card) {
+  const lines = [];
+  lines.push(`[runlist] in-session: ${card.path} — close with: runlist set <status> ${card.path}`);
+  lines.push('---');
+  lines.push(`# ${card.title}`);
+  const meta = [card.status, card.updated && `updated ${card.updated}`].filter(Boolean).join(' · ');
+  if (meta) lines.push(dim(meta));
+  if (card.blurb) {
+    lines.push('');
+    lines.push(`> ${card.blurb.replace(/\n/g, '\n> ')}`);
+  }
+
+  if (card.currentState || card.nextStep) {
+    lines.push('');
+    if (card.currentState) lines.push(`${green('Current:')} ${card.currentState}`);
+    if (card.nextStep) lines.push(`${green('Next:')}    ${card.nextStep}`);
+  }
+
+  if (card.yardstick) {
+    lines.push('');
+    lines.push(renderYardstick(card.yardstick, { compact: true }).trimEnd());
+  } else if (card.delivers) {
+    lines.push('');
+    lines.push(`This plan delivers: ${truncate(card.delivers, 400)}`);
+  }
+
+  if (card.related.length > 0) {
+    lines.push('');
+    lines.push(green('Related:'));
+    for (const r of card.related) {
+      const tag = r.kind === 'parent' ? '↑ parent' : '↔';
+      if (r.missing) {
+        lines.push(`  ${tag} ${r.ref} ${dim('(missing)')}`);
+      } else {
+        lines.push(`  ${tag} ${r.ref}${r.status ? ` ${dim(`(${r.status})`)}` : ''}`);
+      }
+    }
+  }
+
+  if (card.activePhase) {
+    lines.push('');
+    lines.push(`${green('Active phase:')} ${card.activePhase.heading}  ${dim(`(lines ${card.activePhase.lineStart}-${card.activePhase.lineEnd})`)}`);
+  } else if (card.fallbackContent) {
+    lines.push('');
+    lines.push(`${green('Active section:')} ${card.fallbackContent.heading}  ${dim(`(lines ${card.fallbackContent.lineStart}-${card.fallbackContent.lineEnd})`)}`);
+  } else if (card.phases.total > 0) {
+    lines.push('');
+    lines.push(dim(`All ${card.phases.total} phases shipped/skipped — ready for archive?`));
+  }
+
+  if (card.openQuestions) {
+    lines.push(`${green('Open Questions:')} ${card.openQuestions.count}  ${dim(`(lines ${card.openQuestions.lineStart}-${card.openQuestions.lineEnd})`)}`);
+  }
+
+  if (card.lastVersion) {
+    lines.push('');
+    lines.push(`${green('Last change:')} ${card.lastVersion}`);
+  }
+
+  if (card.outline.length > 0) {
+    lines.push('');
+    lines.push(green('Outline:'));
+    for (const o of card.outline) {
+      lines.push(`  ## ${o.heading}  ${dim(o.suffix)}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(dim(`Body: ${formatBytes(card.bodyBytes)}. \`runlist set in-session ${card.path} --full\` for everything, or Read the file with offset/limit to target a section by line number.`));
+  return lines.join('\n') + '\n';
+}
+
+function formatBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}