runlist 0.96.1 → 0.98.0

package/README.md

@@ -71,8 +71,8 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.96.1**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.96.1).
+CLI and desktop release version: **0.98.0**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.98.0).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 
@@ -105,15 +105,16 @@ Host source, cache and registry copies are labelled separately; a cache entry
 alone does not prove which copy a running host has loaded. No package manager or
 host command runs to produce the `doctor --project` installation report.
 
-The local desktop snapshot passed packaged and installed checks, with
-its previous app retained for rollback. Open the installed app with `rl desktop`;
-native save/reset and status/archive journeys also passed a bounded review, with
-accessibility/confirmation findings recorded in
-[desktop validation](desktop/VALIDATION.md#native-workflow-review-2026-10-20).
-The installed review app includes the failed-status-preview confirmation fix.
-Native review verified disabled confirmation for a failed or missing review, then
-a successful pause at the original path. Dialog accessibility remains unresolved;
-see the [current investigation](desktop/VALIDATION.md#confirmation-fix-and-native-investigation-2026-10-20).
+**0.97.0 is published and installed locally.** It adds the `runlist show`
+brief (outline, open boxes and `--section` reads with line numbers), counts
+checklists outside code fences only, and trims session and subagent start-up
+context. The desktop app's own code is unchanged from 0.96.1; it bundles the
+0.97.0 engine. The Mac installer is signed, notarized and verified; installation
+retained the previous app for rollback. Open it with `rl desktop`. See the
+[release validation](desktop/VALIDATION.md#current-mac-release--2026-10-22)
+for checks and evidence. Full-app dialog accessibility remains an open finding;
+fresh/minimum-host and controlled whole-app performance qualification remain
+follow-up work.
 
 Verify an installed Mac app without opening it:
 
@@ -134,33 +135,22 @@ record completed results in durable plans before explicitly archiving the
 selected prompts. Historical nested-archive origin recovery stays deferred until
 a concrete case needs it.
 
-Deferred work awaiting selection:
-
-1. Expand local-commit qualification to process filters, broader clean-filter
-   command profiles, Windows, Linux x64/other Git versions and additional signing profiles.
-   Configured commit hooks and noninteractive SSH/OpenPGP signing are supported
-   in current source on the qualified macOS/Linux combinations. Push is deferred.
-2. Optional grepmax live retrieval/coverage qualification is parked: the owner
-   reports a watcher issue requiring a reboot. The last check saw gmax 0.26.65
-   ready, but its installed bridge/daemon lacked Runlist's required document-search
-   contract. Watcher recovery and compatibility must be verified before live
-   qualification resumes; preserve the existing safety hold. See the
-   current status and resume gates.
-   The compatibility plan
-   now has steps 1–4 passing against gmax 0.26.66 source and an extracted local
-   npm candidate, including the actual private helper. Deployment and live
-   checks remain separate gates.
-   Large-checkout inventory,
-   unavailable-state memory/latency and bridge cleanup have terminal evidence.
-   The Runlist GUI/backend adapter and guarded protocol fixtures are included
-   in GUI 0.94.0-rc.1. External provider deployment and successful live retrieval
-   remain unverified. Optional local model chat is deferred.
-3. Complete native plan lifecycle, legacy migration,
-   settings/diagnostics. GUI yardstick and Filing reports are delivered in
-   0.94.0-rc.1. Stage filters/groups and guarded Stage editing are also delivered.
-4. Finish platform qualification: a terminal-ready Windows host, Linux x64 and
-   older distributions, real-version upgrades, fresh/minimum-version and Intel
-   Macs, plus native rendering, focus, accessibility and whole-window memory.
+Remaining product work:
+
+1. Resolve full-app dialog accessibility and extend native offline, fresh/minimum-Mac
+   installation/upgrade/recovery and whole-app performance qualification.
+2. Finish the broader native-plan, identity/migration, history/verification,
+   scoped-relationship and advanced settings/diagnostics contracts. Reviewed
+   legacy plan status/archive operations already ship.
+3. Qualify additional local-commit filter, hook, signing and platform profiles.
+   Push remains deferred.
+4. Deploy and qualify an exact optional grepmax provider against an existing
+   index, after the separately recorded watcher/resource hold is resolved.
+   Compatibility fixtures pass; successful live retrieval remains unverified.
+   Local model chat remains deferred.
+5. Complete post-release agent-workflow measurement and assess the installed
+   OpenCode prompt-hook API. A Rust engine migration remains planned pending
+   performance evidence.
 
 The current Mac installer is linked in the release-version section above.
 CLI and desktop include the optional product yardstick.

package/bin/runlist.mjs

@@ -263,6 +263,7 @@ View & Query:
   plans                             Live plans (excludes archived; --include-archived for all)
   app [document] [--port 5173]      Local Markdown document library with reviewed saves and draft recovery
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
+                                    (a doc over 500 lines prints its brief; --full prints it whole)
   baton [<plan>|<slug>] @<draft>     Save a resume prompt; releases the plan + prints the commit when one is in-session
   prompts [list|show|archive|new] Prompt admin (list / peek / archive / save). Use \`runlist use\` to consume.
   stale                             Stale docs (preset)
@@ -285,7 +286,7 @@ Analyze:
   record <file> <action> --note <reason> Act on a native flag or decision
   decision <file> <id> --disposition <state> --note <reason> Record an outcome
   decisions [doc|id] [--all|--check] Open and held decisions, read from the corpus
-  show <file...> [--json]           One document's card: status, next step, related plans and docs, links
+  show <file...> [--section <h>]    One document's card, outline and open boxes with line numbers; one section
   xref <file...> | --check [--flag] Cross-references: what names it, its decisions, its cited code
 
 Validate & Fix:
@@ -1571,18 +1572,41 @@ remain owned by their CLI sessions; coordinate/release them before a human save.
 Metadata and lifecycle changes continue through the CLI. Ctrl+C stops the app.
 --dry-run previews startup without opening a server or writing editor state.
 `,
-  show: `runlist show <file...> — one document's card, read-only
-
-  runlist show <file>           title, status, next step, blockers, checklist,
-                                related plans and docs, documents linked from the body
-  runlist show <a> <b> --json   [{ path, type, title, status, summary, currentState,
-                                   nextStep, blockers, checklist, updated,
-                                   related: [{ field, ref, path, exists, title, status, type }],
-                                   links: [{ path, title, status, type }] }]
-
-A file is a path, filename or slug, as for \`use\`. Nothing is claimed or
-written. With --json a file that is not found is { path, error } rather than
-an exit.`,
+  show: `runlist show <file...> — a document in a few KB, read-only
+
+  runlist show <file>           card (title, status, next step, blockers, related
+                                plans and docs, body links), then the outline and
+                                open boxes with line numbers, then the other
+                                frontmatter fields by name
+  runlist show <file> --section "<heading>"
+                                that section, every line numbered, to the next
+                                heading at the same or a higher level
+      --from <line>             continue a section read that was cut
+      --all                     every open box, not the first 30
+      --card                    the card only
+      --frontmatter             the frontmatter as written, long values collapsed
+      --json                    the same as data; a section read is
+                                { path, query, heading, from, to, next, rows, others }
+
+Read a plan or long doc this way, then one section at a time, never whole. A
+heading matches case-insensitively: exact first, then as a prefix, then as a
+substring; other matches are named. A section read stops at 500 lines or
+60 KB and prints the command that continues it. Headings and boxes inside code
+fences are ignored. Several files at once get a shorter outline each.
+
+A phase heading shows its own boxes as [done/total], → marks the active phase
+(the one \`use\` would point at), and a marker its boxes contradict is named
+(marked shipped with boxes open, or todo with every box checked). Open boxes
+are grouped by phase, and the last line is the --section call for the active
+phase.
+
+\`runlist use <doc>\` prints this brief for a doc over 500 lines or 60 KB;
+\`use <doc> --full\` prints the whole body.
+
+A file is a path, filename or slug, as for \`use\`, and any Markdown file in
+the repo works. Nothing is claimed or written. With --json a file that is not
+found is { path, error } rather than an exit; a heading that matches nothing
+exits 1 and lists the headings.`,
 
   model: `runlist model — the local model behind summaries and lint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.96.1",
+  "version": "0.98.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.96.1",
+  "version": "0.98.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -12,6 +12,7 @@ Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`.
 **Optional filing policy:** with `export const filing = true` (or `{ categoryDepth: 3 }`), `check` warns on missing/multiple/uncategorized homes, while `coverage` lists direct/inherited homes and hub:line evidence. A home is a status-bearing table row whose first cell links the plan; mentions and order lists are references. A child without its own row can inherit a home through explicit `parent_plan:` ancestors. Categories come from headings or the containing hub's filing category. Scoping retains full evidence; incomplete scans suppress absence findings. Neither command assigns homes or repairs rows. Enable the policy or retire an older custom check only with repository authorization. Available in CLI 0.93.0.
 
 - Orient with `runlist plans`. Use `runlist agent-context` for structured state; `runlist briefing` is the comprehensive view and can be large.
+- Read a plan or long doc with `runlist show <file>` (card, outline and open boxes with line numbers, the active phase), then `runlist show <file> --section "<heading>"` one section at a time; never read a plan whole.
 - Start plan work with `runlist use <plan-file>`. It claims the plan, marks it `in-session`, and prints the card.
 - Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
 - Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.

package/src/baton.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso, shellQuote } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput, slugify } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
@@ -82,11 +82,6 @@ function archivedCopyPath(promptPath, config) {
   return authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
 }
 
-function shellQuote(value) {
-  const raw = String(value);
-  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
-}
-
 function commitCommand(config, message, paths) {
   const fallback = ['git', 'commit', '-m', message, '--', ...paths];
   let argv = fallback;

package/src/brief.mjs

@@ -0,0 +1,174 @@
+import { extractFrontmatter, normalizeEol } from './frontmatter.mjs';
+import { detectMarker, findActivePhase, isPhaseHeading, matchSections, phaseMarkerConflict, phaseTally, walkChecklist, walkSections } from './section.mjs';
+
+// A document in a few KB, for an agent to read in place of the whole file: a
+// heading outline and the open checklist boxes, both with file line numbers,
+// and one section on request. Pure: callers read the file and render.
+
+export const LIMITS = {
+  outline: 60, // headings shown; the deepest levels drop first
+  boxes: 30, // open boxes shown without --all
+  width: 140, // a heading, box or frontmatter line is cut to this
+  listItems: 8, // a frontmatter list longer than this is collapsed
+  textLines: 4, // and a multi-line frontmatter value cut to this many lines
+  sectionLines: 500, // lines of one section read
+  sectionBytes: 60 * 1024,
+};
+
+// Several files at once is a survey; each one gets less.
+export const SURVEY_LIMITS = { ...LIMITS, outline: 20, boxes: 10 };
+
+export const cut = (text, width = LIMITS.width) =>
+  text.length > width ? `${text.slice(0, width - 3)}...` : text;
+
+// The file split into lines, without the empty one a final newline leaves.
+function fileLines(text) {
+  const lines = text.split('\n');
+  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+// Headings with file coordinates: `line` is the heading, `end` the last line of
+// its section (the line before the next heading at the same or a higher level).
+// A phase heading also carries `phase`: its marker, its own checklist tally,
+// whether it is the active phase (the rule the `use` pickup card applies), and
+// a contradiction between marker and boxes when there is one.
+function headingsOf(body, bodyLineOffset, lastLine) {
+  const sections = walkSections(body);
+  const active = findActivePhase(sections);
+  return sections.map(s => {
+    const h = {
+      line: s.lineStart + bodyLineOffset,
+      end: Math.min(s.lineEnd + bodyLineOffset, lastLine),
+      level: s.level,
+      heading: s.heading,
+    };
+    if (isPhaseHeading(s)) {
+      const tally = phaseTally(s);
+      const conflict = phaseMarkerConflict(s);
+      h.phase = {
+        marker: detectMarker(s.heading),
+        done: tally.checked,
+        total: tally.total,
+        active: s === active,
+        conflict: conflict ? { declared: conflict.declared, implied: conflict.implied } : null,
+      };
+    }
+    return h;
+  });
+}
+
+// The phase heading a body line sits under, if any.
+function phaseAt(headings, line) {
+  let found = null;
+  for (const h of headings) if (h.phase && h.line <= line && line <= h.end) found = h;
+  return found;
+}
+
+// Drop the deepest heading levels until the outline fits, then cut the tail.
+function boundOutline(headings, cap) {
+  let shown = headings;
+  while (shown.length > cap) {
+    const deepest = Math.max(...shown.map(h => h.level));
+    if (deepest <= 1) break;
+    shown = shown.filter(h => h.level < deepest);
+  }
+  shown = shown.slice(0, cap);
+  return { shown, omitted: headings.length - shown.length };
+}
+
+// Frontmatter as written, with long values cut and long lists collapsed.
+export function collapseFrontmatter(frontmatter, limits = LIMITS) {
+  if (!frontmatter) return [];
+  const out = [];
+  let listRun = 0;
+  let textRun = 0;
+  const flush = () => {
+    if (listRun > limits.listItems) out.push(`  (+${listRun - limits.listItems} more)`);
+    if (textRun > limits.textLines) out.push(`  (+${textRun - limits.textLines} more lines)`);
+    listRun = 0;
+    textRun = 0;
+  };
+  for (const line of frontmatter.split('\n')) {
+    if (/^\s+-\s/.test(line)) {
+      if (++listRun <= limits.listItems) out.push(cut(line, limits.width));
+      continue;
+    }
+    if (/^\s+\S/.test(line)) {
+      if (++textRun <= limits.textLines) out.push(cut(line, limits.width));
+      continue;
+    }
+    flush();
+    out.push(cut(line, limits.width));
+  }
+  flush();
+  return out;
+}
+
+/**
+ * The brief of one document's raw text: its size, a bounded outline and the
+ * open boxes. `all` lists every open box. Counts are of what sits outside code
+ * fences, so a template's example checklist is not reported as work.
+ */
+export function buildBrief(raw, { all = false, limits = LIMITS } = {}) {
+  const text = normalizeEol(raw);
+  const { frontmatter, body, bodyLineOffset } = extractFrontmatter(text);
+  const lines = fileLines(text);
+  const headings = headingsOf(body, bodyLineOffset, lines.length);
+  const { shown, omitted } = boundOutline(headings, limits.outline);
+  const boxes = walkChecklist(body).map(b => ({ ...b, line: b.line + bodyLineOffset }));
+  const open = boxes.filter(b => b.open)
+    .map(({ line, text: t }) => ({ line, text: t, phase: phaseAt(headings, line)?.heading ?? null }));
+  const active = headings.find(h => h.phase?.active) ?? null;
+  const listed = all ? open : open.slice(0, limits.boxes);
+  return {
+    lines: lines.length,
+    bytes: Buffer.byteLength(text),
+    frontmatterLines: frontmatter ? bodyLineOffset : 0,
+    outline: shown,
+    outlineOmitted: omitted,
+    activePhase: active ? { line: active.line, heading: active.heading } : null,
+    boxes: { open: open.length, done: boxes.length - open.length },
+    open: listed,
+    openOmitted: open.length - listed.length,
+  };
+}
+
+/**
+ * One section of a document by heading: its lines from `from` (default the
+ * heading) to the section's end, cut at `limits.sectionLines` lines or
+ * `limits.sectionBytes`. `next` is the first line not printed when cut.
+ * Returns { found: false, headings } when nothing matches.
+ */
+export function readSection(raw, query, { from = null, limits = LIMITS } = {}) {
+  const text = normalizeEol(raw);
+  const { body, bodyLineOffset } = extractFrontmatter(text);
+  const lines = fileLines(text);
+  const headings = headingsOf(body, bodyLineOffset, lines.length);
+  const matches = matchSections(headings, query);
+  if (!matches.length) return { found: false, query, headings };
+
+  const [match, ...others] = matches;
+  const start = from == null ? match.line : Math.max(from, match.line);
+  if (start > match.end) {
+    return { found: true, past: true, query, heading: match, from: start, others };
+  }
+  const rows = [];
+  let bytes = 0;
+  for (let n = start; n <= match.end; n++) {
+    bytes += Buffer.byteLength(lines[n - 1]) + 1;
+    if (rows.length >= limits.sectionLines || (rows.length && bytes > limits.sectionBytes)) break;
+    rows.push({ line: n, text: lines[n - 1] });
+  }
+  const to = rows.length ? rows[rows.length - 1].line : start - 1;
+  return {
+    found: true,
+    query,
+    heading: match,
+    from: start,
+    to,
+    next: to < match.end ? to + 1 : null,
+    rows,
+    others,
+  };
+}

package/src/commands.mjs

@@ -109,7 +109,7 @@ const definitions = [
     form('use <name>', { subcommands: ['use'], args: positionals(1, 1) }),
     form('cap <gb>', { subcommands: ['cap'], args: positionals(1, 1) }),
   ]),
-  command('show', none, 'read', [form('<file...>', { args: positionals(1, Infinity), options: [flag('--json')] })]),
+  command('show', none, 'read', [form('<file...>', { args: positionals(1, Infinity), options: [flag('--json'), flag('--card'), flag('--all'), flag('--frontmatter'), value('--section', '-s'), value('--from')] })]),
   command('xref', mutates('the flags log under the state directory with --check --flag; otherwise read-only'), 'read', [
     form('<file...> | --check [--flag]', { args: positionals(0, Infinity), options: [flag('--json'), flag('--check'), flag('--flag')] }),
   ]),

package/src/extractors.mjs

@@ -1,4 +1,5 @@
 import { maskInlineCodeSpans } from './markdown-code-spans.mjs';
+import { walkChecklist } from './section.mjs';
 
 export function extractFirstHeading(body) {
   return body.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
@@ -80,22 +81,14 @@ export function extractBodyLinks(body) {
   return links;
 }
 
+// Boxes inside a code fence are examples, not work, so they are not counted;
+// `runlist show` lists the open ones by the same rule (walkChecklist).
 export function extractChecklistCounts(body) {
-  const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX~])\]\s+/gm)];
-  let completed = 0;
-  let open = 0;
-
-  for (const match of matches) {
-    if (match[1].toLowerCase() === 'x') {
-      completed += 1;
-    } else {
-      open += 1;
-    }
-  }
-
+  const boxes = walkChecklist(body);
+  const open = boxes.filter(b => b.open).length;
   return {
-    completed,
+    completed: boxes.length - open,
     open,
-    total: completed + open,
+    total: boxes.length,
   };
 }

package/src/flags.mjs

@@ -221,13 +221,15 @@ function placeLabel(flag, config) {
 const severityLabel = s => (s === 'problem' ? red(s) : s === 'warn' ? yellow(s) : dim(s));
 
 // One line for the session-start banner, or null when nothing is open.
-export function flagsHudLine(config, { top = 3 } = {}) {
+// A count for the session-start line; `runlist flags` lists them. Printing the
+// first few flags' text put problems unrelated to the session's task in front
+// of every session, cut mid-sentence.
+export function flagsHudLine(config) {
   let open;
   try { open = openFlags(config); } catch { return null; }
   if (open.length === 0) return null;
   const problems = open.filter(f => f.severity === 'problem').length;
-  const items = open.slice(0, top).map(f => `${f.id} ${f.line != null ? `${f.file}:${f.line}` : f.file} ${f.text.slice(0, 80)}`).join('; ');
-  return `[runlist] ${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: ${items}. List: \`runlist flags\`.`;
+  return `${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: \`runlist flags\` lists them.`;
 }
 
 export function runFlags(argv, config) {

package/src/hud.mjs

@@ -12,7 +12,7 @@ import { compareVersions } from './update.mjs';
 import { findOwnedPlan } from './baton.mjs';
 import { listOwnedPlans, surveyOwnershipClaims } from './pickup.mjs';
 import { handoffNotDoneLine, pendingHandoffsForSession } from './handoff-record.mjs';
-import { actionablePromptStatuses, comparePromptDocs, resolveStatusMetadata } from './status-metadata.mjs';
+import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
 
@@ -286,40 +286,18 @@ export function buildHud(config) {
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
-// with ZERO project context and no SessionStart history — it has never seen the
-// command sheet the top-level session got. Without this, subagents reflexively
-// grep/cat/commit managed docs instead of using runlist. Keep it to a few dense
-// lines: the verbs + the three wrong-moves the guard exists to stop, so the
-// subagent self-corrects before the guard ever has to fire.
+// with ZERO project context and no SessionStart history. Without this,
+// subagents reflexively grep/cat/commit managed docs instead of using runlist.
+// It fires on every SubagentStart and CwdChanged, so every byte here is paid
+// again and again: the read verbs, the three wrong-moves the guard exists to
+// stop, and a pointer for the rare child handoff. Statuses are not listed —
+// `runlist set` names the valid ones when given a wrong one.
 const SUBAGENT_PRIMER = [
-  'runlist manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter).',
-  'Verbs: plans|briefing | query <filters> | use [<file>] | set <status> <file> | new <type> <slug> | archive <file>.',
-  'Child handoff: `runlist baton --subagent <task-slug> @<draft-file>` saves subagent-<task-slug>. Add --parent resume-<name> when known to group it under its parent prompt. Use a task slug under a parent-owned plan; release only your own plan. Parent batons default to resume-<name>.',
-  'Child draft: `runlist baton --subagent --template --parent resume-<name>` prints the checkout’s child outline (built-in: Task, State, Next, Evidence and Boundaries). Carry parent_prompt in the draft or pass RUNLIST_PARENT_PROMPT into the child environment. Save full records at durable repo-relative paths. Repair old links with `runlist prompts link <child...> --parent resume-<name>`.',
-  'Claims: `runlist doctor --claims` lists which session holds each plan; `--apply` releases the ones whose session is gone.',
-  'Do NOT: cat/read a docs/prompts/*.md (use `runlist use <file>` — archive/claim commits before at-most-once output);',
-  'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `runlist set`).',
+  'runlist manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter). Read a plan or long doc with `runlist show <file>` (outline and open boxes with line numbers), then `runlist show <file> --section "<heading>"`, never whole. Orient: `runlist plans`.',
+  'Do NOT: cat/read a docs/prompts/*.md (use `runlist use <file>`); git add/commit a prompt (session-local); hand-edit a `status:` field (use `runlist set <status> <file>`).',
+  'Handing work back as a saved prompt: `runlist baton --subagent <task-slug> @<draft-file>` (`runlist help baton` for --parent and --template).',
 ].join('\n');
 
-export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
-  const statuses = (resolveStatusMetadata(config).byType.plan ?? []).map(item => item.name);
-  const fallback = 'run `runlist statuses list --type plan`';
-  if (statuses.length === 0) return `Plan statuses unavailable; ${fallback}.`;
-  const prefix = 'Plan statuses: ';
-  const full = `${prefix}${statuses.join(', ')}`;
-  if (full.length <= maxChars) return full;
-
-  const shown = [];
-  for (const status of statuses) {
-    const omitted = statuses.length - shown.length - 1;
-    const candidate = `${prefix}${[...shown, status].join(', ')}, ... (+${omitted}; ${fallback})`;
-    if (candidate.length > maxChars) break;
-    shown.push(status);
-  }
-  const omitted = statuses.length - shown.length;
-  return `${prefix}${shown.join(', ')}${shown.length ? ', ' : ''}... (+${omitted}; ${fallback})`;
-}
-
 // The plugin's SessionStart/SubagentStart hooks fire in EVERY repo (it's enabled
 // globally), but the primer only helps where runlist is actually used. Gate on a
 // discovered config: `runlist init` writes runlist.config.mjs, so "has a config" is
@@ -415,14 +393,11 @@ export async function runPromptSubmitHud(config, { readStdin } = {}) {
   process.stdout.write(buildHandoffContext(config) + '\n');
 }
 
-// Names, not paths, and at most PROMPT_NAMES_SHOWN of them, so the line stays
-// one line however long the queue grows.
-const PROMPT_NAMES_SHOWN = 12;
+// A count, not names: a queue of dozens printed a dozen names nobody asked
+// about, and `runlist prompts` lists them when the user names one.
 export function pendingPromptsLine(prompts) {
   const n = prompts.length;
-  const names = prompts.slice(0, PROMPT_NAMES_SHOWN).map(p => path.basename(p, '.md'));
-  const more = n > names.length ? ` (+${n - names.length} more: \`runlist prompts\`)` : '';
-  return `[runlist] ${n} pending prompt${n === 1 ? '' : 's'}: ${names.join(', ')}${more}. Resume one only when the user asks for it (\`runlist use <name>\`); never consume the oldest by default. Peek without consuming: \`runlist prompts show <name>\`.`;
+  return `${n} pending prompt${n === 1 ? '' : 's'}: resume one only when the user asks for it (\`runlist prompts\` lists them, \`runlist use <name>\` resumes one, \`runlist prompts show <name>\` peeks); never consume the oldest by default.`;
 }
 
 function isRunlistRepo(config) {
@@ -441,7 +416,6 @@ export function runHud(argv, config) {
   if (argv.includes('--subagent')) {
     if (!runlistRepo) return; // silent in repos that don't use runlist
     process.stdout.write(dim(SUBAGENT_PRIMER) + '\n');
-    process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
     if (drift) process.stdout.write(yellow(drift) + '\n');
     return;
   }
@@ -458,26 +432,29 @@ export function runHud(argv, config) {
 
   const hud = buildHudFast(config);
 
-  // SessionStart contract: the command primer, plus ONLY signals that carry a
-  // direct instruction for this session. Passive state (error counts,
-  // slash-command refresh notices, previous-self / fleet / recent-rejections)
-  // stays suppressed — those nudged agents into phantom follow-up work (e.g.
-  // "errors: 1" prompting a check run) and live in their proper commands and
-  // `runlist hud --json`. Two signals ARE instructions and must print, because
-  // the handoff loop dies without them (sessions were saving batons that no
-  // next session ever picked up):
-  //   - pending prompts: earlier sessions queued work. The line lists them
-  //     and says to resume one only when the user asks. It used to say
-  //     "consume the oldest" unless told otherwise, but a new session nearly
+  // SessionStart contract: ONLY signals that carry a direct instruction for
+  // this session, and nothing at all in a clean repo. No command sheet and no
+  // status list: the runlist skill carries the verbs, and `runlist set` names
+  // the valid statuses when given a wrong one. Passive state (error counts,
+  // previous-self / fleet / recent-rejections) stays suppressed — it nudged
+  // agents into phantom follow-up work and lives in its own commands and
+  // `runlist hud --json`. What prints:
+  //   - pending prompts, as a count: earlier sessions queued work, and the
+  //     line says to resume one only when the user asks. A new session nearly
   //     always has a task from the user, the hook cannot see it, and the
   //     oldest prompt is rarely the useful one.
+  //   - open flags, as a count: the person asked that every session start
+  //     knowing where things stand. Worded as awareness, not an instruction.
   //   - an in-session plan attributed to this sid via durable ownership: this
   //     session (pre-compaction) owns it and should continue or hand it off.
   //     Global in-session counts never provide a fallback.
-  // The misuse recap stays for the same reason: a repeat-offense rule means
-  // the primer alone isn't landing, so name the habit to break.
-  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<plan-or-slug>] @<draft-file> (save a resume prompt; releases the in-session plan if any)') + '\n');
-  process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
+  //   - an unfinished handoff, a repeat-offense misuse rule, and plans held by
+  //     sessions that are gone: each names the command that clears it.
+  const queue = [];
+  if (hud.prompts.length > 0) queue.push(pendingPromptsLine(hud.prompts));
+  const flagsLine = flagsHudLine(config);
+  if (flagsLine) queue.push(flagsLine);
+  if (queue.length) process.stdout.write(yellow(`[runlist] ${queue.join(' ')}`) + '\n');
   if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[runlist] in-session (yours): ${hud.owned.path} — continue it; hand off with \`runlist baton @/tmp/draft.md\` before stopping.`) + '\n');
   }
@@ -486,16 +463,7 @@ export function runHud(argv, config) {
   try {
     for (const record of pendingHandoffsForSession(config)) process.stdout.write(yellow(`[runlist] ${handoffNotDoneLine(record, `runlist baton --done ${record.plan}`)}`) + '\n');
   } catch { /* advisory */ }
-  if (hud.prompts.length > 0) {
-    const n = hud.prompts.length;
-    process.stdout.write(yellow(pendingPromptsLine(hud.prompts)) + '\n');
-  }
   if (hud.misuseRecap) process.stdout.write(yellow(`[runlist] ${hud.misuseRecap}`) + '\n');
   if (hud.deadClaimsLine) process.stdout.write(yellow(hud.deadClaimsLine) + '\n');
-  // Open flags are the one piece of passive state printed here: the person
-  // asked that every session start knowing where things stand. It is worded
-  // as awareness, not an instruction, so no session treats it as its task.
-  const flagsLine = flagsHudLine(config);
-  if (flagsLine) process.stdout.write(yellow(flagsLine) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\n');
 }

package/src/section.mjs

@@ -3,26 +3,32 @@
 // and body-relative line numbers (1-indexed). Callers with stripped frontmatter
 // add extractFrontmatter().bodyLineOffset before exposing file coordinates.
 
-export function walkSections(body) {
-  const lines = body.split('\n');
+// Calls visit(line, index) for every line outside a fenced code block. A fence
+// closes only on the character that opened it, so ``` inside ~~~ stays code.
+function eachUnfencedLine(lines, visit) {
   const fenceRe = /^(`{3,}|~{3,})/;
-  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
-  const sections = [];
   let fenceChar = null;
-  let h2Ancestor = null;
-
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const fence = line.match(fenceRe);
+    const fence = lines[i].match(fenceRe);
     if (fence) {
       const tok = fence[1][0]; // ` or ~
       if (fenceChar === null) fenceChar = tok;
       else if (fenceChar === tok) fenceChar = null;
       continue;
     }
-    if (fenceChar !== null) continue;
+    if (fenceChar === null) visit(lines[i], i);
+  }
+}
+
+export function walkSections(body) {
+  const lines = body.split('\n');
+  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
+  const sections = [];
+  let h2Ancestor = null;
+
+  eachUnfencedLine(lines, (line, i) => {
     const h = line.match(headingRe);
-    if (!h) continue;
+    if (!h) return;
     const level = h[1].length;
     const heading = h[2];
     if (level === 1) h2Ancestor = null;
@@ -35,7 +41,7 @@ export function walkSections(body) {
       bodyLineStart: i + 2,
     });
     if (level === 2) h2Ancestor = heading;
-  }
+  });
 
   for (let i = 0; i < sections.length; i++) {
     const next = sections.find((s, j) => j > i && s.level <= sections[i].level);
@@ -57,6 +63,35 @@ export function findSection(sections, name) {
   return sections.find(s => norm(s.heading) === target) ?? null;
 }
 
+// Every section whose heading matches `query`, best first: exact, then prefix,
+// then substring, document order within each. Case-insensitive; leading `#`s
+// and trailing markers are ignored on both sides, as in findSection.
+export function matchSections(sections, query) {
+  const norm = (s) => s.toLowerCase().replace(/^#+\s*/, '').replace(/[^\w\s]+$/, '').replace(/\s+/g, ' ').trim();
+  const q = norm(query);
+  if (!q) return [];
+  const tiers = [[], [], []];
+  for (const s of sections) {
+    const h = norm(s.heading);
+    if (h === q) tiers[0].push(s);
+    else if (h.startsWith(q)) tiers[1].push(s);
+    else if (h.includes(q)) tiers[2].push(s);
+  }
+  return tiers.flat();
+}
+
+// Checklist boxes outside code fences, with body-relative 1-indexed lines.
+// `[ ]` and `[~]` are open, as in phaseTally and the index's checklist counts.
+const BOX_RE = /^\s*[-*]\s+\[([ xX~])\](?:\s+(.*?))?\s*$/;
+export function walkChecklist(body) {
+  const boxes = [];
+  eachUnfencedLine(body.split('\n'), (line, i) => {
+    const m = line.match(BOX_RE);
+    if (m) boxes.push({ line: i + 1, open: m[1].toLowerCase() !== 'x', text: m[2] ?? '' });
+  });
+  return boxes;
+}
+
 // Status marker detection for phase headings. Returns one of:
 //   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
 // Glyphs are checked BEFORE prose, not interleaved with it. A glyph is a

package/src/show.mjs

@@ -1,13 +1,16 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFrontmatter, normalizeEol, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { buildBrief, collapseFrontmatter, cut, LIMITS, readSection, SURVEY_LIMITS } from './brief.mjs';
 import { parseDocFile, resolveDocArg } from './index.mjs';
 import { resolveBodyLinkTarget } from './body-link.mjs';
-import { die, normalizeStringList, resolveRefPath, toRepoPath } from './util.mjs';
+import { die, normalizeStringList, resolveRefPath, shellQuote, toRepoPath } from './util.mjs';
 
 // `runlist show <file...>` — one document's card as data: its title, status,
 // next step, blockers and checklist, the plans and docs its frontmatter names,
-// and the documents its body links to. Read-only; nothing is claimed.
+// and the documents its body links to, followed by its brief (outline and open
+// boxes with line numbers; src/brief.mjs). `--section` reads one section in
+// place of the whole file. Read-only; nothing is claimed.
 
 // Frontmatter lists that name other documents. The configured reference fields
 // are read too; `related_docs` is read whether or not a repo configures it.
@@ -76,26 +79,169 @@ export function showDoc(abs, config) {
   };
 }
 
+// Fields the text card prints. Everything else non-empty is named on one line
+// so a reader knows it is there without printing the frontmatter.
+const CARD_FIELDS = new Set(['title', 'status', 'next_step', 'blockers']);
+
+function otherFields(abs, config) {
+  const raw = readFileSync(abs, 'utf8');
+  const fm = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter ?? '', []);
+  const shown = new Set([...CARD_FIELDS, ...relatedFields(config)]);
+  return Object.keys(fm).filter(k => !shown.has(k) && normalizeStringList(fm[k]).some(v => String(v).trim()));
+}
+
+function parseShowArgs(args) {
+  const opts = { json: false, card: false, all: false, frontmatter: false, section: null, from: null, targets: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--card') opts.card = true;
+    else if (a === '--all') opts.all = true;
+    else if (a === '--frontmatter') opts.frontmatter = true;
+    else if (a === '--section' || a === '-s') opts.section = args[++i] ?? die('--section needs a heading');
+    else if (a === '--from') opts.from = args[++i];
+    else if (a.startsWith('-')) die(`Unknown option for show: ${a}`);
+    else opts.targets.push(a);
+  }
+  if (opts.from != null) {
+    if (opts.section == null) die('--from continues a --section read; name the section too');
+    const n = Number(opts.from);
+    if (!Number.isInteger(n) || n < 1) die(`--from takes a line number, got: ${opts.from}`);
+    opts.from = n;
+  }
+  return opts;
+}
+
+const pad = (n, width) => String(n).padStart(width);
+
+function runSection(target, opts, config) {
+  const abs = resolveDocArg(target, config);
+  const rel = toRepoPath(abs, config.repoRoot);
+  const r = readSection(readFileSync(abs, 'utf8'), opts.section, { from: opts.from });
+  const again = from => `runlist show ${shellQuote(rel)} --section ${shellQuote(opts.section)} --from ${from}`;
+  if (opts.json) {
+    const { headings, ...rest } = r;
+    const out = r.found
+      ? { path: rel, ...rest, ...(r.next ? { continue: again(r.next) } : {}) }
+      : { path: rel, error: 'no heading matches', query: r.query, headings: headings.map(({ line, level, heading }) => ({ line, level, heading })) };
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+    if (!r.found || r.past) process.exitCode = 1;
+    return;
+  }
+  if (!r.found) {
+    const list = r.headings.slice(0, 20).map(h => `  ${h.line}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}`);
+    if (r.headings.length > 20) list.push(`  (+${r.headings.length - 20} more)`);
+    process.stderr.write([`No heading in ${rel} matches "${opts.section}". Headings:`, ...list].join('\n') + '\n');
+    process.exitCode = 1;
+    return;
+  }
+  const h = r.heading;
+  if (r.past) {
+    process.stderr.write(`${rel}: "${h.heading}" runs ${h.line} to ${h.end}; --from ${r.from} is past its end.\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const width = String(r.to).length;
+  const span = r.from === h.line && !r.next ? `${h.line} to ${h.end}` : `${r.from} to ${r.to} of ${h.line} to ${h.end}`;
+  const out = [`${rel} lines ${span} (${'#'.repeat(h.level)} ${h.heading}):`];
+  for (const row of r.rows) out.push(`${pad(row.line, width)}\t${row.text}`);
+  if (r.next) out.push(`(cut at line ${r.to}; the section runs to ${h.end}. Next: ${again(r.next)})`);
+  if (r.others.length) out.push(`Also matching: ${r.others.map(o => `${o.line} ${cut(o.heading, 60)}`).join('; ')}`);
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+// `[3/7]` for a phase with boxes, and the contradiction between its marker and
+// its boxes when there is one.
+function phaseNote(phase) {
+  if (!phase) return '';
+  let note = phase.total ? `  [${phase.done}/${phase.total}]` : '';
+  if (phase.conflict) {
+    note += phase.conflict.declared === 'shipped'
+      ? `  (marked shipped; ${phase.total - phase.done} open)`
+      : '  (marked todo; every box checked)';
+  }
+  return note;
+}
+
+// A heading as a --section query: trailing markers dropped, which the matcher
+// ignores anyway, so the suggested command reads cleanly.
+const sectionQuery = heading => heading.replace(/[^\w\s]+$/u, '').trim() || heading;
+
+function renderBrief(card, brief) {
+  const out = [];
+  const width = String(brief.lines).length;
+  const kb = Math.max(1, Math.round(brief.bytes / 1024));
+  out.push('', `Outline: ${brief.lines.toLocaleString('en-US')} lines, ${kb} KB (line, heading)`);
+  if (!brief.outline.length) out.push('  (no headings)');
+  for (const h of brief.outline) {
+    const gutter = h.phase?.active ? '→ ' : '  ';
+    out.push(`${gutter}${pad(h.line, width)}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}${phaseNote(h.phase)}`);
+  }
+  if (brief.outlineOmitted) out.push(`  (+${brief.outlineOmitted} deeper headings not shown; a --section read shows them)`);
+  const total = brief.boxes.open + brief.boxes.done;
+  if (total) {
+    out.push(`Open boxes: ${brief.boxes.open} of ${total} (line, text)`);
+    // Grouped under the phase each box sits in, so the list reads as what is
+    // left, phase by phase.
+    let group;
+    for (const b of brief.open) {
+      if (b.phase !== group && (b.phase || group)) out.push(`  ${b.phase ? cut(b.phase) : '(not in a phase)'}`);
+      group = b.phase;
+      out.push(`${group ? '    ' : '  '}${pad(b.line, width)}  ${cut(b.text)}`);
+    }
+    if (brief.openOmitted) out.push(`  (+${brief.openOmitted} more: add --all)`);
+  }
+  if (brief.frontmatter) {
+    out.push(`Frontmatter (lines 1 to ${brief.frontmatterLines}):`, ...brief.frontmatter.map(l => `  ${l}`));
+  } else if (card.otherFields?.length) {
+    out.push(`Other fields: ${card.otherFields.join(', ')} (--frontmatter prints them)`);
+  }
+  return out;
+}
+
 export function runShow(args, config) {
-  const json = args.includes('--json');
-  const targets = args.filter(a => !a.startsWith('-'));
-  if (!targets.length) die('Usage: runlist show <file...> [--json]');
+  const opts = parseShowArgs(args);
+  if (!opts.targets.length) die('Usage: runlist show <file...> [--section "<heading>" [--from <line>]] [--all] [--card] [--frontmatter] [--json]');
+  if (opts.section != null) {
+    if (opts.targets.length > 1) die('--section reads one file; name one');
+    runSection(opts.targets[0], opts, config);
+    return;
+  }
+  const limits = opts.targets.length > 1 ? SURVEY_LIMITS : LIMITS;
   const cards = [];
-  for (const t of targets) {
-    const abs = resolveDocArg(t, config, { dieOnMiss: !json });
-    cards.push(abs ? showDoc(abs, config) : { path: t, error: 'not found' });
+  for (const t of opts.targets) {
+    const abs = resolveDocArg(t, config, { dieOnMiss: !opts.json });
+    if (!abs) { cards.push({ path: t, error: 'not found' }); continue; }
+    const card = showDoc(abs, config);
+    if (!opts.card) {
+      const raw = readFileSync(abs, 'utf8');
+      card.brief = buildBrief(raw, { all: opts.all, limits });
+      if (opts.frontmatter) card.brief.frontmatter = collapseFrontmatter(extractFrontmatter(normalizeEol(raw)).frontmatter, limits);
+      card.otherFields = otherFields(abs, config);
+    }
+    cards.push(card);
   }
-  if (json) {
+  if (opts.json) {
     process.stdout.write(`${JSON.stringify(cards, null, 2)}\n`);
     return;
   }
   cards.forEach((c, n) => {
     if (n) process.stdout.write('\n');
-    process.stdout.write(`${c.title}  (${c.status ?? 'no status'})\n${c.path}\n`);
-    if (c.nextStep) process.stdout.write(`Next: ${c.nextStep}\n`);
-    for (const b of c.blockers) process.stdout.write(`Blocker: ${b}\n`);
-    if (c.checklist?.total) process.stdout.write(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done\n`);
-    for (const r of c.related) process.stdout.write(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}\n`);
-    if (c.links.length) process.stdout.write(`Linked from the body: ${c.links.map(l => l.path).join(', ')}\n`);
+    const out = [`${c.title}  (${c.status ?? 'no status'})`, c.path];
+    if (c.nextStep) out.push(`Next: ${c.nextStep}`);
+    for (const b of c.blockers) out.push(`Blocker: ${b}`);
+    // The brief's open-box line carries the same count, read outside code fences.
+    if (c.checklist?.total && !c.brief) out.push(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done`);
+    for (const r of c.related) out.push(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}`);
+    if (c.links.length) out.push(`Linked from the body: ${c.links.map(l => l.path).join(', ')}`);
+    if (c.brief) out.push(...renderBrief(c, c.brief));
+    process.stdout.write(out.join('\n') + '\n');
   });
+  if (!opts.card) {
+    const active = cards.length === 1 ? cards[0].brief?.activePhase : null;
+    const file = cards.length === 1 ? shellQuote(cards[0].path) : '<file>';
+    process.stdout.write(active
+      ? `\nNext: runlist show ${file} --section ${shellQuote(sectionQuery(active.heading))}\n`
+      : `\nOne section: runlist show ${file} --section "<heading>"\n`);
+  }
 }

package/src/use.mjs

@@ -5,13 +5,15 @@ import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
 import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
 import { startPlan } from './lifecycle.mjs';
 import { resolveDocArg } from './index.mjs';
+import { LIMITS } from './brief.mjs';
+import { runShow } from './show.mjs';
 
 // Top-level `runlist use [file]` — the single "start engaging with this doc"
 // verb. Dispatches by the target doc's `type:` so agents don't have to know
 // the verb-per-type rule:
 //   - prompt → print body + archive (one-shot consume)
 //   - plan   → set status in-session + print the plan card
-//   - doc    → print body (read-only)
+//   - doc    → print body (read-only); a long doc prints its brief, --full the body
 // With no argument, consumes the oldest pending prompt.
 export async function runUse(argv, config, opts = {}) {
   const positional = argv.find(a => !a.startsWith('-'));
@@ -51,8 +53,17 @@ export async function runUse(argv, config, opts = {}) {
   }
   // Anything else (doc, untyped, custom): print the body. The frontmatter
   // already names everything an agent needs to know about lifecycle for that
-  // type, so the verb stays a no-op read for non-actionable types.
+  // type, so the verb stays a no-op read for non-actionable types. A doc past
+  // the section-read caps prints its brief instead: printing a 2,000-line spec
+  // whole is the read `runlist show` exists to replace.
+  const rel = toRepoPath(filePath, config.repoRoot);
+  const lines = raw.split('\n').length - (raw.endsWith('\n') ? 1 : 0);
+  if (!argv.includes('--full') && (lines > LIMITS.sectionLines || Buffer.byteLength(raw) > LIMITS.sectionBytes)) {
+    runShow([rel], config);
+    process.stderr.write(`${rel} (${type ?? 'untyped'}) is ${lines} lines, so this is its brief. \`runlist use ${rel} --full\` prints it whole.\n`);
+    return;
+  }
   process.stdout.write(raw);
   if (!raw.endsWith('\n')) process.stdout.write('\n');
-  process.stderr.write(`${toRepoPath(filePath, config.repoRoot)} (${type ?? 'untyped'})\n`);
+  process.stderr.write(`${rel} (${type ?? 'untyped'})\n`);
 }

package/src/util.mjs

@@ -306,6 +306,13 @@ export function suggestCandidates(query, candidates, max = 3) {
     .map(([cand]) => cand);
 }
 
+// One argument as it must be typed into a POSIX shell: bare when it is plainly
+// safe, otherwise double-quoted with `"`, `\`, `$` and backtick escaped.
+export function shellQuote(value) {
+  const raw = String(value);
+  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
+}
+
 export function resolveDocPath(input, config) {
   if (!input) return null;
   if (path.isAbsolute(input)) return existsSync(input) ? input : null;