simt-dev 0.2.2 → 0.3.1

package/src/measure/context.mjs

@@ -21,14 +21,21 @@
 //   4. Write anything. `compare` is read-only for the same reason - a measurement
 //      that can change what it measures is not a measurement.
 
-import { readFile, readdir } from 'node:fs/promises';
+import { lstat, readFile, readdir } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 
 import { resolveSurfaces } from '../projection/surfaces.mjs';
 import { parse } from '../projection/markers.mjs';
-import { budgetFinding, DEFAULT_BUDGET_BYTES, readManifest } from '../projection/manifest.mjs';
+import {
+  budgetFinding,
+  declaredBudget,
+  DEFAULT_BUDGET_BYTES,
+  readManifest,
+} from '../projection/manifest.mjs';
 import { extractFrontmatter } from '../projection/targets.mjs';
 import { readLimitFindings } from '../projection/project.mjs';
+import { loader } from '../projection/loaders.mjs';
+import { expandClaudeImports, viewOf } from './loaderView.mjs';
 import { TOOLS } from '../mcp/tools.mjs';
 
 /**
@@ -98,7 +105,7 @@ async function readText(path) {
  * guess about nesting; it is the bound that keeps a stray `node_modules` inside a
  * tool-owned directory from turning a byte count into an unbounded walk.
  */
-async function filesUnder(root, dir, suffix, depth = 0) {
+async function filesUnder(root, dir, suffix, depth = 0, maxDepth = 6) {
   let entries;
   try {
     entries = await readdir(join(root, dir), { withFileTypes: true });
@@ -112,8 +119,8 @@ async function filesUnder(root, dir, suffix, depth = 0) {
     const entry = entries.find((e) => e.name === name);
     const path = `${dir}/${name}`;
     if (entry.isDirectory()) {
-      if (depth >= 6) continue;
-      out.push(...(await filesUnder(root, `${path}`, suffix, depth + 1)));
+      if (depth >= maxDepth) continue;
+      out.push(...(await filesUnder(root, `${path}`, suffix, depth + 1, maxDepth)));
     } else if (entry.isFile() && (!suffix || name.endsWith(suffix))) {
       out.push(path);
     }
@@ -121,6 +128,46 @@ async function filesUnder(root, dir, suffix, depth = 0) {
   return out;
 }
 
+/** True when `rel` under `root` is a regular file and not a symlink. */
+async function isRegularFile(root, rel) {
+  try {
+    const st = await lstat(join(root, rel));
+    return st.isFile() && !st.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Generated span bytes of a document (0 when the file carries no valid region). */
+function generatedSpanBytes(text) {
+  const state = parse(text);
+  if (state.status !== 'ok') return 0;
+  const open = state.before.length === 0 ? 0 : state.before.length + 1;
+  const close = state.after.length === 0 ? text.length : text.length - state.after.length - 1;
+  return bytes(text.slice(open, close));
+}
+
+/**
+ * Whether a rule file loads unconditionally at session start according to the
+ * reader's loader row (R14).
+ *
+ * A file with no frontmatter block at all is treated as unconditional (e.g. a
+ * `.claude/rules/*.md` file or a bare `.mdc`); a file that declares frontmatter is
+ * filtered against the loader row's `frontmatter` requirement so scoped rules
+ * (`alwaysApply: false`, `trigger: glob`, `trigger: model_decision`, path-specific
+ * `applyTo`, or Claude `paths:`) are not billed to session start.
+ */
+function isAlwaysOnRule(surfaceId, ruleEntry, text) {
+  const block = extractFrontmatter(text);
+  if (!block) return true;
+  const meta = frontmatter(text);
+  if (surfaceId === 'claude' && meta.paths) return false;
+  if (ruleEntry?.frontmatter) {
+    return Object.entries(ruleEntry.frontmatter).every(([k, v]) => meta[k] === v);
+  }
+  return true;
+}
+
 /** Frontmatter keys, as an object. One block, no nesting - which is all a SKILL.md has. */
 function frontmatter(text) {
   const block = extractFrontmatter(text);
@@ -176,13 +223,68 @@ async function documentsFor(root, surface) {
     }
   }
 
+  if (surface.id === 'claude') {
+    const claudeLoader = loader('claude');
+    const seenImports = new Set();
+    for (const candidate of ['CLAUDE.md', 'CLAUDE.local.md']) {
+      if (!(await isRegularFile(root, candidate))) continue;
+      const text = await readText(join(root, candidate));
+      if (text === null) continue;
+      seenImports.add(candidate);
+      out.push({
+        channel: 'rules',
+        file: candidate,
+        text,
+        generatedBytes: generatedSpanBytes(text),
+        readerBytes: bytes(text),
+      });
+      const depth = claudeLoader?.imports?.depth ?? 4;
+      for (const imp of await expandClaudeImports(root, candidate, text, depth, seenImports)) {
+        out.push({
+          channel: 'imports',
+          file: imp.file,
+          text: imp.text,
+          generatedBytes: generatedSpanBytes(imp.text),
+          readerBytes: bytes(imp.text),
+        });
+      }
+    }
+  }
+
+  if (surface.id === 'copilot' && (await isRegularFile(root, '.github/copilot-instructions.md'))) {
+    const rel = '.github/copilot-instructions.md';
+    const text = await readText(join(root, rel));
+    if (text !== null) {
+      out.push({
+        channel: 'rules',
+        file: rel,
+        text,
+        generatedBytes: generatedSpanBytes(text),
+        readerBytes: bytes(text),
+      });
+    }
+  }
+
   if (surface.rule) {
     const dir = surface.rule.slice(0, surface.rule.lastIndexOf('/'));
     const suffix = surface.rule.slice(surface.rule.lastIndexOf('.') + 1);
-    for (const file of await filesUnder(root, dir, `.${suffix}`)) {
+    const row = loader(surface.id);
+    const ruleEntry = row?.start.find((e) => e.dir === dir && e.atStart) ?? null;
+    // Antigravity scans `.agents/rules/` flat (`tree: 'flat'`) and ignores nested
+    // directories; Cursor, Claude and Copilot walk subdirectories (`tree: 'nested'`).
+    const maxDepth = ruleEntry?.tree === 'flat' ? 0 : 6;
+    for (const file of await filesUnder(root, dir, `.${suffix}`, 0, maxDepth)) {
       const text = await readText(join(root, file));
       if (text === null) continue;
-      out.push({ channel: 'rules', file, text, generatedBytes: bytes(text), readerBytes: bytes(text) });
+      if (!isAlwaysOnRule(surface.id, ruleEntry, text)) continue;
+      const isGenerated = parse(text).status === 'ok';
+      out.push({
+        channel: 'rules',
+        file,
+        text,
+        generatedBytes: isGenerated ? bytes(text) : 0,
+        readerBytes: bytes(text),
+      });
     }
   }
 
@@ -231,10 +333,7 @@ export async function measureRoot(root) {
 
   const generatedBytes = documents.reduce((sum, d) => sum + d.generatedBytes, 0);
   const readerBytes = documents.reduce((sum, d) => sum + d.readerBytes, 0);
-  const budgetBytes =
-    manifest?.budget?.bytes !== undefined && Number.isFinite(manifest.budget.bytes)
-      ? manifest.budget.bytes
-      : ALWAYS_ON_BUDGET_BYTES;
+  const budgetBytes = declaredBudget(manifest);
 
   const byChannel = new Map();
   for (const doc of documents) {
@@ -268,6 +367,52 @@ export async function measureRoot(root) {
     }
   }
 
+  // R14 chain and per-file caps: Codex's 32 KiB applies to the merged root-to-cwd
+  // chain, so a repository where every individual AGENTS.md sits under 32 KiB can still
+  // drop its deepest file once merged; Antigravity's 24,000 B cap applies per rule file.
+  const codexLoader = loader('codex');
+  if (codexLoader?.cap?.scope === 'chain') {
+    for (const dir of await instructionDirs(root)) {
+      const view = await viewOf(root, codexLoader, { cwd: join(root, dir) });
+      if (!view.cap?.over) continue;
+      // If a single root AGENTS.md already tripped `readLimitFindings` above, do not
+      // report the same 1-file root overflow twice.
+      if (view.files.length === 1 && readLimits.some((r) => r.file === view.files[0].file && r.reader === 'Codex')) {
+        continue;
+      }
+      const chainLabel = view.files.map((f) => f.file).join(' -> ');
+      const overBy = view.cap.totalBytes - view.cap.bytes;
+      readLimits.push({
+        file: chainLabel,
+        reader: 'Codex',
+        limit: view.cap.bytes,
+        endByte: view.cap.totalBytes,
+        overBy,
+      });
+      findings.push(
+        `${chainLabel}: BEYOND-READ-LIMIT — merged chain is ${view.cap.totalBytes} B, ${overBy} B past Codex's ${view.cap.bytes} B (${view.cap.config}) chain limit`,
+      );
+    }
+  }
+
+  const antigravityCap = loader('antigravity')?.cap;
+  if (antigravityCap?.scope === 'file') {
+    for (const doc of documents) {
+      if (!doc.file.startsWith('.agents/rules/') || doc.readerBytes <= antigravityCap.bytes) continue;
+      const overBy = doc.readerBytes - antigravityCap.bytes;
+      readLimits.push({
+        file: doc.file,
+        reader: 'Antigravity',
+        limit: antigravityCap.bytes,
+        endByte: doc.readerBytes,
+        overBy,
+      });
+      findings.push(
+        `${doc.file}: BEYOND-READ-LIMIT — rule file is ${doc.readerBytes} B, ${overBy} B past Antigravity's ${antigravityCap.bytes} B per-file limit`,
+      );
+    }
+  }
+
   const name = root.split('/').filter(Boolean).pop() ?? root;
   return {
     name,
@@ -368,4 +513,32 @@ export function totals(rows) {
     repeatBytes,
     overBudget: rows.filter((r) => r.budget.over).map((r) => r.name),
   };
+}
+
+/**
+ * Directories under `root` that carry an `AGENTS.md` or `AGENTS.override.md` beyond
+ * a lone root `AGENTS.md`, sorted for determinism.
+ */
+async function instructionDirs(root, rel = '', depth = 0, out = []) {
+  let entries;
+  try {
+    entries = await readdir(join(root, rel), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  const names = entries.map((e) => e.name).sort();
+  const hasOverride = names.includes('AGENTS.override.md');
+  const hasAgents = names.includes('AGENTS.md');
+  if ((rel !== '' && (hasAgents || hasOverride)) || (rel === '' && hasOverride)) {
+    out.push(rel);
+  }
+  if (depth >= 4) return out;
+  for (const name of names) {
+    if (name.startsWith('.') || name === 'node_modules' || name === 'dist' || name === 'build') continue;
+    const entry = entries.find((e) => e.name === name);
+    if (entry?.isDirectory()) {
+      await instructionDirs(root, rel === '' ? name : `${rel}/${name}`, depth + 1, out);
+    }
+  }
+  return out;
 }

package/src/measure/loaderView.mjs

@@ -0,0 +1,435 @@
+// One reader's view of one repository: which files it loads before the first message,
+// in what order, and what the cap leaves out.
+//
+// This is the consumer R14 was built for. Before the loader table, `simt tokens` counted
+// the files a surface WRITES — which is why it recursed six levels into `.agents/rules/`
+// and reported bytes Antigravity never reads, and why it could not see a repository that
+// is inside 32 KiB in every file and past it once Codex merges the chain.
+//
+// What it deliberately does not do:
+//
+//   1. Walk the user's home. A reader's global instructions are the reader's, not the
+//      repository's, and a per-repository report that carried them would change because
+//      somebody installed something. `scopes` reports that a user scope exists; the bytes
+//      are the repository's.
+//   2. Decide whether a file matches. `frontmatter` in the table is an equality filter
+//      on parsed frontmatter, which is all any of these vendors document. Cursor's
+//      `alwaysApply: true` and Antigravity's `trigger: always_on` are exactly that.
+//   3. Expand imports. Claude's `@path` and Antigravity's `@[label](path)` are recorded
+//      with their depth, and `imports` reports what the reader would pull in — a
+//      measurement of the syntax, not a recursive parse of the file that would need a
+//      frontmatter-aware Markdown parser this package does not have (ADR-012).
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { LOADERS, caps } from '../projection/loaders.mjs';
+import { extractFrontmatter } from '../projection/targets.mjs';
+import { BYTES_PER_TOKEN } from './context.mjs';
+
+/**
+ * The longest directory walk any of these readers documents.
+ *
+ * A bound, not a guess about nesting: a stray `node_modules` inside a tool-owned
+ * directory must not turn a byte count into an unbounded walk.
+ */
+const MAX_DEPTH = 8;
+
+/** UTF-8 byte length. `String.length` counts UTF-16 units and undercounts every
+ *  non-ASCII character, and a rule file with an em dash in it is ordinary. */
+function bytes(text) {
+  return Buffer.byteLength(text);
+}
+
+/** Frontmatter as a flat object. One block, no nesting — all a rule file carries. */
+function frontmatter(text) {
+  const block = extractFrontmatter(text);
+  const out = {};
+  if (!block) return out;
+  for (const line of block.split('\n').slice(1)) {
+    if (line.trim() === '---') break;
+    const at = line.indexOf(':');
+    if (at < 1) continue;
+    out[line.slice(0, at).trim()] = line
+      .slice(at + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/**
+ * Files under a directory in a stable order.
+ *
+ * `depth` bounds the recursion. Nothing here filters dotfiles: a reader that documented
+ * ignoring them is not one whose docs were read, and a `.md` inside `.agents/rules/` is
+ * a rule.
+ */
+async function filesUnder(dir, depth = 0, prefix = '') {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+    const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (depth >= MAX_DEPTH) continue;
+      out.push(...(await filesUnder(join(dir, entry.name), depth + 1, rel)));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+async function readText(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    // Absence is the expected answer for a reader configured in a repository that has
+    // not written the file yet, and a permission error is not a byte count either.
+    return null;
+  }
+}
+
+async function exists(root, rel) {
+  try {
+    return (await stat(join(root, rel))).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve one `start` entry into the repository files it loads.
+ *
+ * `chain` is the case that needs care and gets it: Codex takes at most one file per
+ * directory in precedence order, and the entries are the precedence list. Each entry is
+ * resolved separately and the first one present wins per directory, which is the rule as
+ * documented rather than as inferred — but the entries carry the same root, so the merge
+ * is over the same directory set and the winner is the entry order in the table.
+ *
+ * Returns `[]` for an entry whose documented precondition fails: `absent` names paths
+ * that must not exist, so `CLAUDE.md` beside `AGENTS.md` is exactly what makes Claude
+ * Code skip the latter.
+ */
+async function resolveEntry(root, entry) {
+  if (entry.scope !== 'project' || !entry.atStart) return [];
+  if (entry.absent && (await Promise.all(entry.absent.map((p) => exists(root, p)))).some(Boolean)) {
+    return [];
+  }
+
+  const hit = async (rel, note) => {
+    const text = await readText(join(root, rel));
+    if (text === null) return [];
+    if (entry.frontmatter) {
+      const meta = frontmatter(text);
+      const matches = Object.entries(entry.frontmatter).every(([k, v]) => meta[k] === v);
+      if (!matches) return [];
+    }
+    return [{ file: rel, text, note: note ?? null }];
+  };
+
+  switch (entry.tree) {
+    case 'single':
+      return hit(entry.path);
+    case 'chain': {
+      // The repository root is the only directory measured: these readers walk between
+      // the project root and the working directory, and a repository's own files are
+      // what it controls. A nested AGENTS.md is picked up by the nested reads below.
+      return hit(entry.path);
+    }
+    case 'flat': {
+      const out = [];
+      for (const rel of await filesUnder(join(root, entry.dir))) {
+        if (rel.includes('/')) continue;
+        if (entry.suffix && !rel.endsWith(entry.suffix)) continue;
+        out.push(...(await hit(`${entry.dir}/${rel}`)));
+      }
+      return out;
+    }
+    case 'nested': {
+      const out = [];
+      for (const rel of await filesUnder(join(root, entry.dir))) {
+        if (entry.suffix && !rel.endsWith(entry.suffix)) continue;
+        out.push(...(await hit(`${entry.dir}/${rel}`)));
+      }
+      return out;
+    }
+    default:
+      return [];
+  }
+}
+
+/** One measured file: what it weighs, what it costs a turn, and what the caps did to it. */
+function rowFor(found, entry, channel) {
+  return {
+    file: found.file,
+    scope: entry.scope,
+    channel,
+    bytes: bytes(found.text),
+    // A skill's frontmatter is what costs a turn; its body is opened later. Charging the
+    // body here is the error the `metadata` flag exists to prevent.
+    countedBytes: entry.metadata ? bytes(skillHead(found.text)) : bytes(found.text),
+    overCap: false,
+    beyondCap: false,
+    why: entry.why,
+  };
+}
+
+/**
+ * What one reader loads from one repository, at session start.
+ *
+ * `chainBytes` is the sum in load order, and `cap` is what that reader does to it: a
+ * chain-scoped cap truncates the chain, a file-scoped cap truncates each file. Both
+ * report `droppedBytes`, because "over the limit" without "by how much and which file"
+ * is the number that started this slice.
+ *
+ * `overCap` on a row means THIS FILE is truncated; `beyondCap` means the chain stopped
+ * before reaching it. They are different failures with the same visible symptom, and the
+ * one that costs a repository its deepest instructions is the second.
+ */
+export async function viewOf(root, row, options = {}) {
+  const cwd = options.cwd ? relative(root, options.cwd).split(sep).join('/') : '';
+  const files = [];
+
+  // The chain is walked directory by directory — project root down to the working
+  // directory, which is the order Codex and Antigravity document and the reverse of what
+  // a reader that walks *up* from the working directory sees. Inside one directory the
+  // entries are the precedence list and the first one present wins: two AGENTS.md files
+  // in the same directory are one of them not loaded, not both concatenated.
+  //
+  // With no `cwd` this is the root alone, which is the honest default: a repository's
+  // own root document is what the tool can measure without knowing where the agent is
+  // standing, and `--at` is how a reader asks about a subdirectory.
+  const chainEntries = row.start.filter((e) => e.tree === 'chain');
+  const parts = cwd === '' || cwd.startsWith('..') ? [] : cwd.split('/').filter(Boolean);
+  const dirs = ['', ...parts.map((_, i) => parts.slice(0, i + 1).join('/'))];
+  for (const dir of dirs) {
+    // `first` is Codex and Claude: one file per directory, precedence order.
+    // `all` is DeepSeek: every candidate loads, and a later file whose trimmed
+    // text matches an earlier one in the SAME directory is the duplicate the
+    // vendor collapses. The set resets per directory because a nested file that
+    // happens to match the root is a different scope, not a duplicate.
+    const mergeAll = row.chainMerge === 'all';
+    const trimmed = new Set();
+    let taken = false;
+    for (const entry of chainEntries) {
+      if (taken && !mergeAll) break;
+      const scoped = {
+        ...entry,
+        path: dir === '' ? entry.path : `${dir}/${entry.path}`,
+        absent: entry.absent?.map((p) => join(dir, p)),
+      };
+      const found = await resolveEntry(root, scoped);
+      if (found.length === 0) continue;
+      if (row.dedupe === 'trim') {
+        const key = found[0].text.trim();
+        if (trimmed.has(key)) continue;
+        trimmed.add(key);
+      }
+      if (!mergeAll) taken = true;
+      files.push(rowFor(found[0], entry, 'documents'));
+      if (row.imports?.syntax === '@path' && row.imports.depth > 0) {
+        for (const imp of await expandClaudeImports(root, found[0].file, found[0].text, row.imports.depth)) {
+          files.push(rowFor(imp, { scope: 'project', why: row.imports.why }, 'imports'));
+        }
+      }
+    }
+  }
+
+  for (const entry of row.start) {
+    if (entry.tree === 'chain') continue;
+    for (const found of await resolveEntry(root, entry)) {
+      // Claude Code treats `paths:` in `.claude/rules/*.md` frontmatter as path-scoped,
+      // not session-start.
+      if (row.id === 'claude' && entry.dir === '.claude/rules' && frontmatter(found.text).paths) continue;
+      files.push(
+        rowFor(found, entry, entry.metadata ? 'skills' : entry.tree === 'single' ? 'documents' : 'rules'),
+      );
+    }
+  }
+
+  // One skill id is one cost. OpenCode v2 registers .claude, then .agents, then
+  // .opencode, and the later source supplies the skill. Counting every copy would
+  // bill a turn for a body the reader replaced.
+  const skillsById = new Map();
+  const measured = [];
+  for (const file of files) {
+    if (file.channel !== 'skills') {
+      measured.push(file);
+      continue;
+    }
+    const id = file.file.split('/').at(-2) ?? file.file;
+    skillsById.set(id, file);
+  }
+  measured.push(...skillsById.values());
+  files.length = 0;
+  files.push(...measured);
+
+  const limits = caps(row);
+  const chainCap = limits.find((c) => c.scope === 'chain') ?? null;
+  // A token budget is a budget, but it is not a byte count: 20,000 tokens is 80,000
+  // bytes at the four-bytes-per-token approximation, and comparing raw bytes to it
+  // would trip on a repository that has not come close. So the token figure is
+  // converted here and reported in the unit it was documented in.
+  const tokenCap = limits.find((c) => c.scope === 'tokens') ?? null;
+  const tokenCapBytes = tokenCap ? tokenCap.bytes * BYTES_PER_TOKEN : null;
+  const fileCap = limits.find((c) => c.scope === 'file') ?? null;
+
+  // Both caps are checked, not either-or: Antigravity has a per-file byte cap and an
+  // aggregate token budget, and a rule can trip the first without tripping the second.
+  // Which one fired is reported separately, because the remedy differs.
+  let running = 0;
+  for (const file of files) {
+    running += file.countedBytes;
+    if (fileCap && file.countedBytes > fileCap.bytes) file.overCap = true;
+  }
+  if (chainCap?.drop === 'broader') {
+    // DeepSeek keeps the most specific files. Broader files are omitted whole;
+    // only the most specific file may be cut, and the rendered total stays inside
+    // the cap. A source already over the per-file cap is ignored before this.
+    const eligible = files.filter((f) => f.channel === 'documents' && !f.overCap);
+    let sum = eligible.reduce((n, f) => n + f.countedBytes, 0);
+    for (let i = 0; i < eligible.length && sum > chainCap.bytes; i += 1) {
+      const file = eligible[i];
+      const last = i === eligible.length - 1;
+      if (!last) {
+        file.beyondCap = true;
+        sum -= file.countedBytes;
+        continue;
+      }
+      file.truncated = true;
+      file.keptBytes = chainCap.bytes - (sum - file.countedBytes);
+    }
+  } else if (chainCap) {
+    let chainRunning = 0;
+    for (const file of files) {
+      if (file.overCap) continue;
+      chainRunning += file.countedBytes;
+      if (chainRunning > chainCap.bytes) file.beyondCap = true;
+    }
+  }
+  const contributed = (file) => {
+    if (file.beyondCap) return 0;
+    if (file.truncated) return file.keptBytes ?? 0;
+    if (file.overCap) return file.keptBytes ?? 0;
+    return file.countedBytes;
+  };
+  const totalBytes = files.reduce((n, file) => n + contributed(file), 0);
+
+  return {
+    reader: row.id,
+    label: row.label,
+    root,
+    order: row.order,
+    nested: row.nested,
+    imports: row.imports,
+    files,
+    totalBytes,
+    droppedBytes: files.reduce((n, f) => {
+      if (!f.beyondCap && !f.overCap && !f.truncated) return n;
+      return n + f.countedBytes - (f.truncated || f.overCap ? (f.keptBytes ?? 0) : 0);
+    }, 0),
+    // Reported, not measured: the user's global instructions are the reader's bytes.
+    // A per-repository total that included them would change when the reader installed
+    // something, which is the reason `--user` is a flag on `harness detect` and not a
+    // default anywhere in this tool.
+    userScope: row.start.filter((e) => e.scope === 'user').map((e) => e.path),
+    cap: chainCap
+      ? {
+          bytes: chainCap.bytes,
+          scope: chainCap.scope,
+          appliesTo: chainCap.appliesTo,
+          config: chainCap.config,
+          why: chainCap.why,
+          totalBytes: running,
+          over: running > chainCap.bytes,
+        }
+      : null,
+    budget: tokenCap
+      ? {
+          tokens: tokenCap.bytes,
+          bytes: tokenCapBytes,
+          appliesTo: tokenCap.appliesTo,
+          config: tokenCap.config ?? null,
+          why: tokenCap.why,
+          over: running > tokenCapBytes,
+        }
+      : null,
+    perFileCap: fileCap
+      ? {
+          bytes: fileCap.bytes,
+          appliesTo: fileCap.appliesTo,
+          config: fileCap.config,
+          why: fileCap.why,
+          over: files.some((f) => f.overCap),
+        }
+      : null,
+    skills: row.skills,
+    hooks: row.hooks,
+    mcp: row.mcp,
+    verified: row.verified,
+    note: row.note ?? null,
+  };
+}
+
+/** Name and description, which is what a reader loads before it opens a skill body. */
+function skillHead(text) {
+  const meta = frontmatter(text);
+  const name = meta.name ?? '';
+  const description = meta.description ?? '';
+  if (description) return `${name}\n${description}`;
+  return name;
+}
+
+/**
+ * Expand Claude Code `@path/to/import` directives up to `maxDepth` hops.
+ *
+ * Follows the documented parser rules on `claude.imports`:
+ *   - skips fenced code blocks and inline code spans;
+ *   - skips quoted `@path` tokens and `@[label](path)` links;
+ *   - resolves relative to the importing file's directory;
+ *   - refuses paths outside the repository root (Claude Code prompts for approval
+ *     before reading outside the working directory, so those bytes are not automatic).
+ */
+export async function expandClaudeImports(
+  root,
+  fromRel,
+  text,
+  maxDepth = 4,
+  seen = new Set([fromRel]),
+  depth = 0,
+) {
+  if (depth >= maxDepth) return [];
+  const absRoot = resolve(root);
+  const stripped = text
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/~~~[\s\S]*?~~~/g, '')
+    .replace(/`[^`\n]*`/g, '');
+
+  const out = [];
+  const baseDir = dirname(join(absRoot, fromRel));
+  for (const match of stripped.matchAll(/(?:^|(?<=[\s(]))@([A-Za-z0-9_./-]+\.[A-Za-z0-9]+)(?=$|[\s),.;:!?\])])/gm)) {
+    const rawTarget = match[1];
+    const absTarget = resolve(baseDir, rawTarget);
+    const rel = relative(absRoot, absTarget).split(sep).join('/');
+    if (rel === '' || rel.startsWith('..') || seen.has(rel)) continue;
+    const body = await readText(absTarget);
+    if (body === null) continue;
+    seen.add(rel);
+    out.push({ file: rel, text: body });
+    out.push(...(await expandClaudeImports(absRoot, rel, body, maxDepth, seen, depth + 1)));
+  }
+  return out;
+}
+
+/** Every reader's view of one repository, in table order. */
+export async function viewAll(root, rows = LOADERS, options = {}) {
+  const out = [];
+  for (const row of rows) out.push(await viewOf(root, row, options));
+  return out;
+}