dotmd-cli 0.87.0 → 0.87.1

package/README.md

@@ -259,6 +259,12 @@ The register block is the fenced block whose first line carries `statusLine`.
 The row is the question plus `--answers` (what each answer leaves in place),
 which is required when a register is configured.
 
+`runlist decisions --json` gives each open or held decision its `question`,
+its document's `docTitle`, and `blocks`: what its record says it blocks or
+gates, then every unticked checklist item and frontmatter blocker that names
+its id, alone or inside a written range (`A2 to A12`). In another document the
+id has to sit beside a link to the decision's document.
+
 ## Flags
 
 A flag is something someone found that the person should know about when they
@@ -282,6 +288,59 @@ merged. The log is append-only, `.runlist/flags.jsonl` by default
 beside the flag, never over it. Every session start shows a count and the top
 open flags.
 
+## Local model
+
+Summaries (`--summarize`, `runlist summary`, `runlist diff --summarize`) and
+lint's status inference use one local model server, Ollama by default or any
+OpenAI-compatible server. runlist never starts it or pulls a model on its own:
+
+```bash
+runlist model                 # server, model, cap, free memory, what is loaded
+runlist model start           # ollama serve, one model and one request at a time
+runlist model measure         # record each pulled candidate's peak memory and speed here
+runlist model use qwen3.5:9b  # name a model; `auto` picks the first measured one under the cap
+runlist model cap 8           # most memory a model may take; `auto` is a quarter of the machine
+runlist model stop            # unload it now
+```
+
+The model unloads after 5 idle minutes. Before it loads, the memory free right
+now must hold it plus 1.5 GB with memory pressure normal, or the command goes
+on without it. On an 8 GB machine the cap is 2 GB and model features stay off;
+point `RUNLIST_MODEL_ENDPOINT` at a server on a bigger machine instead. Settings
+are per machine in `~/.runlist/model.json`.
+
+`runlist model status --json` leads with a one-line reading for dashboards,
+`running`, `name` (the model loaded now, else the one runlist would load) and
+`memoryMb` (what it holds, null when nothing is loaded), followed by the full
+detail.
+
+## One document's card
+
+```bash
+runlist show docs/plans/shelf.md          # title, status, next step, blockers, checklist, related, links
+runlist show shelf bins --json            # [{ path, title, status, nextStep, blockers, checklist,
+                                          #    related: [{ field, path, title, status }], links: [...] }]
+```
+
+Read-only: nothing is claimed. `related` is what the frontmatter names
+(`related_plans`, `related_docs`, `supports_plans`, `parent_plan`, `runlist` and
+the configured reference fields), each with its title and status; `links` is
+every other document the body links to.
+
+## Failed commands
+
+Every runlist command that fails, by an error or a non-zero exit, appends one
+line to `~/.claude/logs/runlist-errors.log` (`RUNLIST_ERROR_LOG_DIR` moves it)
+with the time, the command with secrets redacted, and the error's one-line
+message. It rolls over once, to `runlist-errors.log.1`, at 5 MB or a new
+runlist version. Dry runs and the session-start `hud` are never logged.
+
+```bash
+runlist errors                # the newest 20 failures, newest first
+runlist errors --limit 50     # the newest N
+runlist errors --json         # [{ at, command, message, repo, exit }]
+```
+
 ## Safety Model
 
 - Mutation commands support `--dry-run` / `-n`.

package/bin/dotmd.mjs

@@ -203,6 +203,20 @@ stop the others: every step runs, the failures are listed together, and the
 exit code is 1. A plugin whose marketplace registration is gone gets the
 marketplace re-added before the update (see \`runlist install claude\`).`,
 
+  errors: `runlist errors — the newest failed runlist commands, newest first
+
+Every runlist command that fails (an error, or a non-zero exit such as
+\`check\` finding errors) appends one line to ~/.claude/logs/runlist-errors.log
+(RUNLIST_ERROR_LOG_DIR moves it): when, the command with secrets redacted, and
+the error's one-line message. It rolls over to runlist-errors.log.1 at 5 MB or
+a new runlist version; this reads both. Dry runs and the session-start hud are
+never logged.
+
+  runlist errors                 last 20
+  runlist errors --limit 50      last N (--tail is the same)
+  runlist errors --repo <name>   only failures in a matching repo
+  runlist errors --json          [{ at, command, message, repo, exit }]`,
+
   misuse: `runlist misuse — read the cross-repo guard log (~/.claude/logs/runlist-misuse.log,
 merged by time with the legacy dotmd-misuse.log that older CLIs wrote)
 
@@ -247,8 +261,10 @@ Analyze:
   unblocks <file> [--json]          Show what completes when this doc ships
   diff [file] [--summarize]         Show changes since last updated date
   summary <file> [--json]           AI summary of a document
+  model [start|stop|use|cap]        The local model: server, which model, memory cap
   glossary <term> [--list] [--json] Look up domain terms + related docs
   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
 
 Validate & Fix:
   doctor [--apply]                  Auto-fix everything: refs, membership, lint, long fields, dates, index (preview by default)
@@ -294,6 +310,7 @@ Setup:
   completions <shell>               Shell completion script (bash, zsh)
   journal [--tail N|--errors|--by-command|--session id|--since iso|--json]
                                     View opt-in JSONL command journal (enable: RUNLIST_JOURNAL=1 or journal: true)
+  errors [--limit N] [--json]       The newest failed runlist commands, from the cross-repo error log
 
 Global Options:
   --config <path>        Explicit config file path
@@ -1096,7 +1113,7 @@ Options:
 Generates an AI-powered summary using a local model.
 
 Options:
-  --model <name>         Model to use (default: mlx-community/Llama-3.2-3B-Instruct-4bit)
+  --model <name>         Model to use (default: the one \`runlist model\` shows)
   --max-tokens <n>       Max tokens for generation (default: 200)
   --json                 Output as JSON`,
 
@@ -1109,7 +1126,7 @@ Options:
   --stat                 Summary only (files changed, insertions/deletions)
   --since <date>         Override: diff since this date instead of frontmatter
   --summarize            Generate AI summary using local model
-  --model <name>         Model to use (default: mlx-community/Llama-3.2-3B-Instruct-4bit)`,
+  --model <name>         Model to use (default: the one \`runlist model\` shows)`,
 
   lint: `runlist lint [--fix] — check and auto-fix frontmatter issues
 
@@ -1336,7 +1353,8 @@ Options:
   runlist decisions <doc>       one document, by path, filename or slug
   runlist decisions <ID>        one record, whole, as it is written
   runlist decisions --all       every disposition, not only the pending ones
-  runlist decisions --json      the same rows as data
+  runlist decisions --json      the same rows as data, each with its question, its
+                                document's title and what it blocks
   runlist decisions --check     every item it could not read or that is incomplete; exit 1 if any
 
 A decision is an item in a decisions section (a heading naming the section word
@@ -1345,7 +1363,53 @@ token is an id. A register is a fenced block whose first line carries
 decisions.register.statusLine; its rows are \`ID  text\`. A disposition is read
 from a \`Disposition:\` line or a row's opening word, then from prose when
 decisions.prose is on, then from the block or bold lead above it. Configure it
-with \`export const decisions = { ... }\` (see src/decisions.mjs).`,
+with \`export const decisions = { ... }\` (see src/decisions.mjs).
+
+What a decision blocks, in --json as \`blocks: [{ doc, line, kind, section, text }]\`:
+what its record says it blocks or gates (kind "stated"), and every unticked
+checklist item (kind "item") or frontmatter blocker (kind "blocker") that
+names its id, alone or inside a written range such as \`A2 to A12\`. In
+another document the id has to sit beside a link to the decision's document.`,
+
+  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.`,
+
+  model: `runlist model — the local model behind summaries and lint
+
+One local server (Ollama by default) holds one model, serves one request at a
+time and unloads it after it sits idle. runlist never starts the server or
+pulls a model on its own.
+
+Subcommands:
+  status [--json]        Default. Server, model, cap, what is loaded and its memory
+  start [--force]        Start \`ollama serve\` (one model, one request at a time);
+                         refused where no model fits unless forced
+  stop [--all]           Unload runlist's model now; --all unloads every loaded model
+  measure [name...]      Load each pulled candidate (or the named ones) in turn,
+                         summarise the corpus's largest documents at lower
+                         priority, and record peak memory and speed for this
+                         machine; a model is picked only once measured here
+  use <name|auto>        Name the model; auto takes the first measured candidate
+                         under the cap
+  cap <gb|auto>          The most memory a model may take; auto (the default) is a
+                         quarter of this machine's memory, at most 12 GB
+
+Before a model loads here, the memory free now must hold it plus 1.5 GB and
+memory pressure must be normal; otherwise the command goes on without it.
+
+Settings live in ~/.runlist/model.json. RUNLIST_MODEL, RUNLIST_MODEL_CAP_GB and
+RUNLIST_MODEL_ENDPOINT override them; \`runtime: "openai"\` there points at any
+OpenAI-compatible server (mlx_lm.server, llama-server, LM Studio).`,
 
   glossary: `runlist glossary <term> — look up domain terms and related docs
 
@@ -1650,7 +1714,8 @@ async function main() {
       if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
       if (HELP[topic]) { process.stdout.write(`${HELP[topic]}\n`); return; }
       process.stderr.write(`Unknown help topic: ${topic}\n\nAvailable topics: all, statuses\nPer-command help: runlist <cmd> --help\n`);
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
     process.stdout.write(`${HELP._main}\n`);
     return;
@@ -1916,6 +1981,8 @@ async function main() {
   if (command === 'flags') { const { runFlags } = await import('../src/flags.mjs'); runFlags(restArgs, config); return; }
   if (command === 'flag') { const { runFlag } = await import('../src/flags.mjs'); runFlag(restArgs, config); return; }
   if (command === 'glossary') { const { runGlossary } = await import('../src/glossary.mjs'); runGlossary(restArgs, config); return; }
+  if (command === 'model') { const { runModel } = await import('../src/model.mjs'); await runModel(restArgs, config); return; }
+  if (command === 'show') { const { runShow } = await import('../src/show.mjs'); runShow(restArgs, config); return; }
   if (command === 'decisions') { const { runDecisions } = await import('../src/decisions.mjs'); runDecisions(restArgs, config); return; }
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
@@ -1930,6 +1997,7 @@ async function main() {
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config, { dryRun }); return; }
   if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config, { dryRun }); return; }
   if (command === 'install') { const { runInstall } = await import('../src/install.mjs'); runInstall(restArgs, config, { dryRun }); return; }
+  if (command === 'errors') { const { runErrors } = await import('../src/errors-read.mjs'); runErrors(restArgs); return; }
   if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {
@@ -2362,19 +2430,30 @@ function _journalExit(err) {
       version: pkg.version,
     });
   } catch { /* never break exit on journal failure */ }
-  if (err) {
+  // A command that reports its own failure through the exit code (check with
+  // errors, a failed update step) is a failure too.
+  const code = Number(process.exitCode ?? 0);
+  const failure = err ?? (code !== 0 ? { name: 'ExitStatus', message: `exited with status ${code}` } : null);
+  if (failure) {
     try {
       recordGlobalError({
         config: _resolvedConfig,
         startMs: _startMs,
         args: _invocationArgs,
-        err,
+        err: failure,
         version: pkg.version,
       });
     } catch { /* never break exit on error-log failure */ }
   }
 }
 
+// A reader that stops early (`runlist flags | head`) closes the pipe; the rest
+// of the output has nowhere to go, which is not a failure.
+process.stdout.on('error', err => {
+  if (err.code === 'EPIPE') process.exit(0);
+  throw err;
+});
+
 main()
   .then(() => { _journalExit(null); })
   .catch(err => {

package/package.json

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

package/runlist.config.example.mjs

@@ -329,6 +329,6 @@ export const presets = {
 // by age, and an expired lease retries only when its owner is demonstrably dead.
 // export function onPickup({ path, oldStatus, newStatus, operationId }) {}
 
-// AI hooks — override summarization (replaces local MLX model).
+// AI hooks — override summarization (replaces the local model server; see `runlist model`).
 // export function summarizeDoc(body, meta) { return 'Custom summary'; }
 // export function summarizeDiff(diffOutput, filePath) { return 'Custom diff summary'; }

package/src/ai.mjs

@@ -1,56 +1,30 @@
-import { spawnSync } from 'node:child_process';
-import { warn } from './util.mjs';
-import { dim } from './color.mjs';
+import { generate } from './model.mjs';
 
-let uvChecked = null;
+// Model-backed text for summaries and lint. The server applies each model's
+// own chat template, so prompts are plain system and user messages.
+// `runlist model` shows which model runs and where.
 
-export function checkUvAvailable() {
-  if (uvChecked !== null) return uvChecked;
-  const result = spawnSync('uv', ['--version'], { encoding: 'utf8' });
-  uvChecked = !result.error && result.status === 0;
-  if (!uvChecked) warn('uv is not installed. Install it to enable AI summaries: https://docs.astral.sh/uv/');
-  return uvChecked;
-}
-
-export const DEFAULT_MODEL = 'mlx-community/Llama-3.2-3B-Instruct-4bit';
-
-export function runMLX(prompt, opts = {}) {
-  const { model = DEFAULT_MODEL, maxTokens = 200, timeout = 120000 } = opts;
-  if (!checkUvAvailable()) return null;
-
-  process.stderr.write(dim('  generating...'));
-  const result = spawnSync('uv', [
-    'run', '--with', 'mlx-lm',
-    'python3', '-m', 'mlx_lm', 'generate',
-    '--model', model,
-    '--prompt', prompt,
-    '--max-tokens', String(maxTokens),
-    '--verbose', 'false',
-  ], { encoding: 'utf8', timeout });
-
-  process.stderr.write('\r\x1b[K');
-  if (result.status !== 0) return null;
-
-  const output = result.stdout.trim();
-  const lines = output.split('\n')
-    .filter(l => !l.includes('Fetching') && !l.includes('Warning:') && !l.includes('=========='));
-  const text = lines.join(' ').trim();
+export function runModel(prompt, opts = {}) {
+  const { system, ...rest } = opts;
+  const messages = system ? [{ role: 'system', content: system }, { role: 'user', content: prompt }] : [{ role: 'user', content: prompt }];
+  const text = generate(messages, rest);
   return text ? text.replace(/\*\*/g, '').replace(/^#+\s*/gm, '').trim() : null;
 }
 
 export function summarizeDocBody(bodyText, meta, opts = {}) {
   if (!bodyText?.trim()) return null;
-  const prompt = `<|begin_of_text|><|start_header_id|>system<|end_header_id|>
-You write brief, direct summaries. No preamble. No filler. Start with the subject immediately.<|eot_id|><|start_header_id|>user<|end_header_id|>
-Write a 2-3 sentence plain text summary of this document. State what it covers, its current state (${meta.status}), and what remains to be done. No markdown formatting. No bold, headers, or bullets. Do not start with "This document" or "Here is".
+  const prompt = `Write a 2-3 sentence plain text summary of this document. State what it covers, its current state (${meta.status}), and what remains to be done. No markdown formatting. No bold, headers, or bullets. Do not start with "This document" or "Here is".
 
 Title: ${meta.title}
-${bodyText.slice(0, 6000)}<|eot_id|><|start_header_id|>assistant<|end_header_id|>
-`;
-  return runMLX(prompt, { maxTokens: 200, ...opts });
+${bodyText.slice(0, 6000)}`;
+  return runModel(prompt, {
+    system: 'You write brief, direct summaries. No preamble. No filler. Start with the subject immediately.',
+    maxTokens: 200,
+    ...opts,
+  });
 }
 
 export function summarizeDiffText(diffText, filePath, model) {
   const prompt = `Summarize this git diff in 1-2 sentences. Focus on what changed semantically, not line counts.\n\nFile: ${filePath}\n\n${diffText.slice(0, 4000)}`;
-  return runMLX(prompt, { model, maxTokens: 150 });
+  return runModel(prompt, { model, maxTokens: 150 });
 }

package/src/body-link.mjs

@@ -9,12 +9,14 @@ function isWithin(root, candidate) {
 // Markdown body links are filesystem paths relative to the document that
 // contains them. They deliberately do not inherit frontmatter references'
 // repo-root fallback: that fallback can make a broken Markdown link look valid.
-export function resolveBodyLinkTarget(href, docDir, repoRoot) {
+export function resolveBodyLinkTarget(href, docDir, repoRoot, externalRoots = []) {
   if (!href) return { ok: false, reason: 'missing' };
 
   const root = path.resolve(repoRoot);
   const candidate = path.resolve(docDir, href);
-  if (!isWithin(root, candidate)) return { ok: false, reason: 'outside-repo' };
+  const allowedRoots = externalRoots.map(entry => path.resolve(root, entry));
+  const allowedLexically = isWithin(root, candidate) || allowedRoots.some(entry => isWithin(entry, candidate));
+  if (!allowedLexically) return { ok: false, reason: 'outside-repo' };
   if (!existsSync(candidate)) return { ok: false, reason: 'missing' };
 
   let canonicalRoot;
@@ -25,7 +27,13 @@ export function resolveBodyLinkTarget(href, docDir, repoRoot) {
   } catch {
     return { ok: false, reason: 'unreadable' };
   }
-  if (!isWithin(canonicalRoot, canonicalTarget)) return { ok: false, reason: 'outside-repo' };
+  const canonicalAllowedRoots = allowedRoots.flatMap(entry => {
+    try { return [realpathSync(entry)]; } catch { return []; }
+  });
+  if (!isWithin(canonicalRoot, canonicalTarget)
+    && !canonicalAllowedRoots.some(entry => isWithin(entry, canonicalTarget))) {
+    return { ok: false, reason: 'outside-repo' };
+  }
 
   try {
     const stat = statSync(canonicalTarget);

package/src/commands.mjs

@@ -88,11 +88,22 @@ const definitions = [
     form('sync <check-name> [findings]', { subcommands: ['sync'], args: positionals(1, 2), dashPositionalsAfter: 1 }),
   ]),
   command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })]),
+  command('model', mutates('~/.runlist/model.json and the local model server'), 'read', [
+    form('', { options: [flag('--json')] }),
+    form('status', { subcommands: ['status'], options: [flag('--json')] }),
+    form('start', { subcommands: ['start'], options: [flag('--force')] }),
+    form('stop', { subcommands: ['stop'], options: [flag('--all')] }),
+    form('measure [name...]', { subcommands: ['measure'], args: positionals(0, Infinity) }),
+    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('decisions', none, 'read', [form('[doc-or-id]', { args: positionals(0, 1), options: [flag('--all'), flag('--json'), flag('--check')] })]),
   command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })]),
   command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })]),
   command('surfaces', none, 'read', [form('', { options: [flag('--json')] })]),
   command('journal', none, 'read', [form('', { options: [value('--tail'), flag('--errors'), value('--session'), value('--since'), flag('--by-command'), flag('--json')] })]),
+  command('errors', none, 'read', [form('', { options: [flag('--json'), value('--limit'), value('--tail'), value('--repo')] })]),
   command('misuse', none, 'read', [form('', { options: [flag('--json'), value('--tail'), flag('--by-rule'), value('--repo')] })]),
 
   command('roadmap', mutates('managed source when `next`; otherwise read-only'), 'workflow', [

package/src/config.mjs

@@ -19,6 +19,7 @@ const DEFAULTS = {
   root: '.',
   archiveDir: 'archived',
   excludeDirs: [],
+  externalBodyLinkRoots: [],
   // Floor under the scan surface; null = off. See `applyScanFloor` in validate.mjs.
   minDocs: null,
 
@@ -640,6 +641,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     configFound: Boolean(configPath),
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
+    externalBodyLinkRoots: Array.isArray(config.externalBodyLinkRoots) ? config.externalBodyLinkRoots : [],
     docsRootPrefix,
     minDocs,