dotmd-cli 0.1.0 → 0.3.0

package/README.md

@@ -7,16 +7,28 @@ Index, query, validate, and lifecycle-manage any collection of `.md` files — p
 ## Install
 
 ```bash
-npm install -g dotmd-cli
+npm install -g dotmd-cli    # global — use `dotmd` anywhere
+npm install -D dotmd-cli    # project devDep — use via npm scripts
 ```
 
 ## Quick Start
 
 ```bash
-dotmd init              # creates dotmd.config.mjs + docs/ + docs/README.md
-dotmd list              # index all docs grouped by status
-dotmd check             # validate frontmatter and references
-dotmd context           # compact briefing (great for LLM context)
+dotmd init                  # creates dotmd.config.mjs, docs/, docs/docs.md
+dotmd new my-feature        # scaffold a new doc with frontmatter
+dotmd list                  # index all docs grouped by status
+dotmd check                 # validate frontmatter and references
+dotmd context               # compact briefing (great for LLM context)
+```
+
+### Shell Completion
+
+```bash
+# bash
+eval "$(dotmd completions bash)"    # add to ~/.bashrc
+
+# zsh
+eval "$(dotmd completions zsh)"     # add to ~/.zshrc
 ```
 
 ## What It Does
@@ -27,8 +39,10 @@ dotmd scans a directory of markdown files, parses their YAML frontmatter, and gi
 - **Query** — filter by status, keyword, module, surface, owner, staleness
 - **Validate** — check for missing fields, broken references, stale dates
 - **Lifecycle** — transition statuses, auto-archive with `git mv`, bump dates
-- **README generation** — auto-generate an index block in your README
+- **Scaffold** — create new docs with frontmatter from the command line
+- **Index generation** — auto-generate a `docs.md` index block
 - **Context briefing** — compact summary designed for AI/LLM consumption
+- **Dry-run** — preview any mutation with `--dry-run` before committing
 
 ## Document Format
 
@@ -58,7 +72,7 @@ The only required field is `status`. Everything else is optional but unlocks mor
 ## Commands
 
 ```
-dotmd list [--verbose]       List docs grouped by status
+dotmd list [--verbose]       List docs grouped by status (default)
 dotmd json                   Full index as JSON
 dotmd check                  Validate frontmatter and references
 dotmd coverage [--json]      Metadata coverage report
@@ -69,7 +83,21 @@ dotmd index [--write]        Generate/update docs.md index block
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + index regen)
 dotmd touch <file>           Bump updated date
+dotmd watch [command]        Re-run a command on file changes
+dotmd diff [file]            Show changes since last updated date
+dotmd new <name>             Create a new document with frontmatter
 dotmd init                   Create starter config + docs directory
+dotmd completions <shell>    Output shell completion script (bash, zsh)
+```
+
+### Global Flags
+
+```
+--config <path>        Explicit config file path
+--dry-run, -n          Preview changes without writing anything
+--verbose              Show resolved config details
+--help, -h             Show help (per-command with: dotmd <cmd> --help)
+--version, -v          Show version
 ```
 
 ### Query Filters
@@ -83,6 +111,15 @@ dotmd query --surface backend --checklist-open
 
 Flags: `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`.
 
+### Scaffold a Document
+
+```bash
+dotmd new my-feature                          # creates docs/my-feature.md (status: active)
+dotmd new "API Redesign" --status planned     # custom status
+dotmd new auth-refresh --title "Auth Refresh" # custom title
+dotmd new something --dry-run                 # preview without creating
+```
+
 ### Preset Aliases
 
 Define custom query presets in your config:
@@ -96,6 +133,29 @@ export const presets = {
 
 Then run `dotmd stale` or `dotmd mine` as shorthand.
 
+### Watch Mode
+
+```bash
+dotmd watch              # re-run list on every .md change
+dotmd watch check        # live validation
+dotmd watch context      # live briefing
+```
+
+### Diff & Summarize
+
+Show git changes since each document's `updated` frontmatter date:
+
+```bash
+dotmd diff                           # all drifted docs
+dotmd diff docs/plans/auth.md        # single file
+dotmd diff --stat                    # summary stats only
+dotmd diff --since 2026-01-01        # override date
+dotmd diff --summarize               # AI summary via local MLX model
+dotmd diff --summarize --model mlx-community/Mistral-7B-Instruct-v0.3-4bit
+```
+
+The `--summarize` flag requires `uv` and a local MLX-compatible model. No JS dependencies are added.
+
 ## Configuration
 
 Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
@@ -115,8 +175,8 @@ export const lifecycle = {
   skipWarningsFor: ['archived'],
 };
 
-export const readme = {
-  path: 'docs/plans/README.md',
+export const index = {
+  path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
   endMarker: '<!-- GENERATED:dotmd:end -->',
 };
@@ -178,9 +238,11 @@ Available: `onArchive`, `onStatusChange`, `onTouch`.
 - **Zero dependencies** — pure Node.js builtins (`fs`, `path`, `child_process`)
 - **No build step** — ships as plain ESM, runs directly
 - **Git-aware** — detects frontmatter date drift vs git history, uses `git mv` for archives
+- **Dry-run everything** — preview any mutation with `--dry-run` / `-n`
 - **Configurable everything** — statuses, taxonomy, lifecycle, validation rules, display
 - **Hook system** — extend with JS functions, no plugin framework to learn
 - **LLM-friendly** — `dotmd context` generates compact briefings for AI assistants
+- **Shell completion** — bash and zsh via `dotmd completions`
 
 ## License
 

package/bin/dotmd.mjs

@@ -10,7 +10,11 @@ import { renderIndexFile, writeIndex } from '../src/index-file.mjs';
 import { runFocus, runQuery } from '../src/query.mjs';
 import { runStatus, runArchive, runTouch } from '../src/lifecycle.mjs';
 import { runInit } from '../src/init.mjs';
-import { die } from '../src/util.mjs';
+import { runNew } from '../src/new.mjs';
+import { runCompletions } from '../src/completions.mjs';
+import { runWatch } from '../src/watch.mjs';
+import { runDiff } from '../src/diff.mjs';
+import { die, warn } from '../src/util.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -31,11 +35,16 @@ Commands:
   status <file> <status> Transition document status
   archive <file>         Archive (status + move + index regen)
   touch <file>           Bump updated date
+  watch [command]       Re-run a command on file changes
+  diff [file]           Show changes since last updated date
+  new <name>             Create a new document with frontmatter
   init                   Create starter config + docs directory
+  completions <shell>    Output shell completion script (bash, zsh)
 
 Options:
   --config <path>        Explicit config file path
   --dry-run, -n          Preview changes without writing anything
+  --verbose              Show config details and doc count
   --help, -h             Show help
   --version, -v          Show version`,
 
@@ -81,6 +90,38 @@ With --write, updates the configured index file in place.
 
 Use --dry-run (-n) with --write to preview without writing.`,
 
+  new: `dotmd new <name> — create a new document
+
+Creates a new markdown document with frontmatter in the docs root.
+
+Options:
+  --status <s>         Set initial status (default: active)
+  --title <t>          Override the document title
+
+The filename is derived from <name> by slugifying it.
+Use --dry-run (-n) to preview without creating the file.`,
+
+  watch: `dotmd watch [command] — re-run a command on file changes
+
+Watches the docs root for .md file changes and re-runs the specified
+command. Defaults to 'list' if no command given.
+
+Examples:
+  dotmd watch              # re-run list on changes
+  dotmd watch check        # re-run check on changes
+  dotmd watch context      # live briefing`,
+
+  diff: `dotmd diff [file] — show changes since last updated date
+
+Shows git diffs for docs that changed after their frontmatter updated date.
+Without a file argument, shows all drifted docs.
+
+Options:
+  --stat                 Summary only (files changed, insertions/deletions)
+  --since <date>         Override: diff since this date instead of frontmatter
+  --summarize            Generate AI summary using local MLX model
+  --model <name>         MLX model to use (default: mlx-community/Llama-3.2-3B-Instruct-4bit)`,
+
   init: `dotmd init — create starter config and docs directory
 
 Creates dotmd.config.mjs, docs/, and docs/docs.md in the current
@@ -108,12 +149,17 @@ async function main() {
     return;
   }
 
-  // Init doesn't need config
+  // Init and completions don't need config
   if (command === 'init') {
     runInit(process.cwd());
     return;
   }
 
+  if (command === 'completions') {
+    runCompletions(args.slice(1));
+    return;
+  }
+
   // Extract --config flag
   let explicitConfig = null;
   for (let i = 0; i < args.length; i++) {
@@ -124,10 +170,21 @@ async function main() {
   }
 
   const dryRun = args.includes('--dry-run') || args.includes('-n');
+  const verbose = args.includes('--verbose');
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
   const restArgs = args.slice(1);
 
+  if (!config.configFound && command !== 'init') {
+    warn('No dotmd config found — using defaults. Run `dotmd init` to create one.');
+  }
+
+  if (verbose) {
+    process.stderr.write(`Config: ${config.configPath ?? 'none'}\n`);
+    process.stderr.write(`Docs root: ${config.docsRoot}\n`);
+    process.stderr.write(`Repo root: ${config.repoRoot}\n`);
+  }
+
   // Preset aliases
   if (config.presets[command]) {
     const index = buildIndex(config);
@@ -135,13 +192,22 @@ async function main() {
     return;
   }
 
+  // Watch and diff (handle their own index building)
+  if (command === 'watch') { runWatch(restArgs, config); return; }
+  if (command === 'diff') { runDiff(restArgs, config); return; }
+
   // Lifecycle commands
   if (command === 'status') { runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
+  if (command === 'new') { runNew(restArgs, config, { dryRun }); return; }
 
   const index = buildIndex(config);
 
+  if (verbose) {
+    process.stderr.write(`Docs found: ${index.docs.length}\n`);
+  }
+
   if (command === 'json') {
     process.stdout.write(`${JSON.stringify(index, null, 2)}\n`);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Zero-dependency CLI for managing markdown documents with YAML frontmatter — index, query, validate, lifecycle.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,9 @@
     "url": "git+https://github.com/beyond-dev/platform.git",
     "directory": "packages/dotmd"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "engines": {
     "node": ">=18"
   }

package/src/completions.mjs

@@ -0,0 +1,98 @@
+import { die } from './util.mjs';
+
+const COMMANDS = [
+  'list', 'json', 'check', 'coverage', 'context', 'focus', 'query',
+  'index', 'status', 'archive', 'touch', 'watch', 'diff', 'init', 'new', 'completions',
+];
+
+const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--help', '--version'];
+
+const COMMAND_FLAGS = {
+  query: ['--status', '--keyword', '--module', '--surface', '--domain', '--owner',
+          '--updated-since', '--stale', '--has-next-step', '--has-blockers',
+          '--checklist-open', '--sort', '--limit', '--all', '--git', '--json'],
+  index: ['--write'],
+  list: ['--verbose'],
+  coverage: ['--json'],
+  new: ['--status', '--title'],
+  diff: ['--stat', '--since', '--summarize', '--model'],
+};
+
+function bashCompletion() {
+  return `# dotmd bash completion
+# Add to ~/.bashrc: eval "$(dotmd completions bash)"
+_dotmd() {
+  local cur prev cmd
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Find the subcommand
+  cmd=""
+  for ((i=1; i < COMP_CWORD; i++)); do
+    case "\${COMP_WORDS[i]}" in
+      -*) ;;
+      *) cmd="\${COMP_WORDS[i]}"; break ;;
+    esac
+  done
+
+  # Complete commands if no subcommand yet
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${COMMANDS.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  # Per-command flag completion
+  case "$cmd" in
+${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
+    `    ${cmd}) COMPREPLY=( $(compgen -W "${flags.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;`
+  ).join('\n')}
+    *) COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
+  esac
+}
+complete -F _dotmd dotmd`;
+}
+
+function zshCompletion() {
+  return `# dotmd zsh completion
+# Add to ~/.zshrc: eval "$(dotmd completions zsh)"
+_dotmd() {
+  local -a commands global_flags
+  commands=(
+${COMMANDS.map(c => `    '${c}'`).join('\n')}
+  )
+  global_flags=(
+${GLOBAL_FLAGS.map(f => `    '${f}'`).join('\n')}
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    _describe 'flag' global_flags
+    return
+  fi
+
+  local cmd=\${words[2]}
+  case "$cmd" in
+${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
+    `    ${cmd}) _values 'flags' ${flags.map(f => `'${f}'`).join(' ')} ;;`
+  ).join('\n')}
+  esac
+
+  _describe 'flag' global_flags
+}
+compdef _dotmd dotmd`;
+}
+
+export function runCompletions(argv) {
+  const shell = argv[0];
+  if (!shell) {
+    die('Usage: dotmd completions <bash|zsh>');
+    return;
+  }
+  if (shell === 'bash') {
+    process.stdout.write(bashCompletion() + '\n');
+  } else if (shell === 'zsh') {
+    process.stdout.write(zshCompletion() + '\n');
+  } else {
+    die(`Unsupported shell: ${shell}\nSupported: bash, zsh`);
+  }
+}

package/src/config.mjs

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { die, warn } from './util.mjs';
 
 const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config.js'];
 
@@ -99,7 +100,27 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   if (configPath && existsSync(configPath)) {
     const configUrl = pathToFileURL(configPath).href;
-    const mod = await import(configUrl);
+    let mod;
+    try {
+      mod = await import(configUrl);
+    } catch (err) {
+      die('Failed to load config: ' + configPath + '\n' + err.message + '\nRun `dotmd init` to create a starter config.');
+      // Return defaults so caller can still function
+      const defaults = deepMerge(DEFAULTS, {});
+      const defaultStatusOrder = defaults.statuses.order;
+      return {
+        raw: defaults, docsRoot: cwd, repoRoot: cwd, configDir: cwd,
+        configPath: configPath ?? null, configFound: Boolean(configPath),
+        archiveDir: defaults.archiveDir, excludeDirs: new Set(defaults.excludeDirs),
+        docsRootPrefix: '', statusOrder: defaultStatusOrder,
+        validStatuses: new Set(defaultStatusOrder), staleDaysByStatus: {},
+        lifecycle: { archiveStatuses: new Set(defaults.lifecycle.archiveStatuses), skipStaleFor: new Set(defaults.lifecycle.skipStaleFor), skipWarningsFor: new Set(defaults.lifecycle.skipWarningsFor) },
+        validSurfaces: null, moduleRequiredStatuses: new Set(),
+        indexPath: null, indexStartMarker: '<!-- GENERATED:dotmd:start -->', indexEndMarker: '<!-- GENERATED:dotmd:end -->', archivedHighlightLimit: 8,
+        context: defaults.context, display: defaults.display,
+        referenceFields: defaults.referenceFields, presets: defaults.presets, hooks: {},
+      };
+    }
 
     configDir = path.dirname(configPath);
 
@@ -123,6 +144,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   const docsRoot = path.resolve(configDir, config.root);
 
+  if (!existsSync(docsRoot)) {
+    warn('Docs root does not exist: ' + docsRoot);
+  }
+
   // Find repo root by walking up looking for .git
   let repoRoot = configDir;
   {
@@ -170,6 +195,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     repoRoot,
     configDir,
     configPath: configPath ?? null,
+    configFound: Boolean(configPath),
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
     docsRootPrefix,

package/src/diff.mjs

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, resolveDocPath, die, warn } from './util.mjs';
+import { gitDiffSince } from './git.mjs';
+import { buildIndex } from './index.mjs';
+import { bold, dim, green } from './color.mjs';
+
+export function runDiff(argv, config) {
+  // Parse flags
+  let file = null;
+  let stat = false;
+  let sinceOverride = null;
+  let summarize = false;
+  let model = 'mlx-community/Llama-3.2-3B-Instruct-4bit';
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--stat') { stat = true; continue; }
+    if (argv[i] === '--summarize') { summarize = true; continue; }
+    if (argv[i] === '--since' && argv[i + 1]) { sinceOverride = argv[++i]; continue; }
+    if (argv[i] === '--model' && argv[i + 1]) { model = argv[++i]; continue; }
+    if (!argv[i].startsWith('-')) { file = argv[i]; }
+  }
+
+  if (file) {
+    // Single file mode
+    const filePath = resolveDocPath(file, config);
+    if (!filePath) {
+      die(`File not found: ${file}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
+      return;
+    }
+
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const since = sinceOverride ?? asString(parsed.updated);
+
+    if (!since) {
+      die(`No updated date found in ${file} and no --since provided.`);
+      return;
+    }
+
+    const relPath = toRepoPath(filePath, config.repoRoot);
+    const diffOutput = gitDiffSince(relPath, since, config.repoRoot, { stat });
+
+    if (!diffOutput) {
+      process.stdout.write(`No changes since ${since} for ${relPath}\n`);
+      return;
+    }
+
+    printFileDiff(relPath, since, diffOutput, { summarize, model, config });
+  } else {
+    // All drifted docs mode
+    const index = buildIndex(config);
+    const drifted = [];
+
+    for (const doc of index.docs) {
+      if (!doc.updated) continue;
+      const relPath = doc.path;
+      const since = sinceOverride ?? doc.updated;
+      const diffOutput = gitDiffSince(relPath, since, config.repoRoot, { stat });
+      if (diffOutput && diffOutput.trim()) {
+        drifted.push({ relPath, since, diffOutput });
+      }
+    }
+
+    if (drifted.length === 0) {
+      process.stdout.write('No drifted docs.\n');
+      return;
+    }
+
+    process.stdout.write(bold(`${drifted.length} doc(s) with changes since their updated date:\n\n`));
+    for (const { relPath, since, diffOutput } of drifted) {
+      printFileDiff(relPath, since, diffOutput, { summarize, model, config });
+    }
+  }
+}
+
+function printFileDiff(relPath, since, diffOutput, opts) {
+  process.stdout.write(bold(relPath) + dim(` (updated: ${since})`) + '\n');
+
+  if (opts.summarize) {
+    const summary = summarizeWithMLX(diffOutput, relPath, opts.model);
+    if (summary) {
+      process.stdout.write(dim(`  Summary: ${summary}`) + '\n');
+    } else {
+      warn('  Summary unavailable (model call failed)');
+    }
+  }
+
+  process.stdout.write(diffOutput);
+  process.stdout.write('\n');
+}
+
+function summarizeWithMLX(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)}`;
+
+  const result = spawnSync('uv', [
+    'run', '--with', 'mlx-lm',
+    'python3', '-m', 'mlx_lm', 'generate',
+    '--model', model,
+    '--prompt', prompt,
+    '--max-tokens', '150',
+    '--verbose', 'false',
+  ], { encoding: 'utf8', timeout: 120000 });
+
+  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('=========='));
+  return lines.join(' ').trim() || null;
+}

package/src/git.mjs

@@ -16,3 +16,20 @@ export function gitMv(source, target, repoRoot) {
   });
   return { status: result.status, stderr: result.stderr };
 }
+
+export function gitDiffSince(relPath, sinceDate, repoRoot, opts = {}) {
+  // Find the last commit at or before sinceDate
+  const baseline = spawnSync('git', [
+    'log', '-1', '--before=' + sinceDate + 'T23:59:59', '--format=%H', '--', relPath
+  ], { cwd: repoRoot, encoding: 'utf8' });
+
+  const baseRef = baseline.stdout.trim();
+  if (!baseRef) return null;
+
+  const diffArgs = ['diff', baseRef, 'HEAD'];
+  if (opts.stat) diffArgs.push('--stat');
+  diffArgs.push('--', relPath);
+
+  const result = spawnSync('git', diffArgs, { cwd: repoRoot, encoding: 'utf8' });
+  return result.stdout || null;
+}

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die } from './util.mjs';
+import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
 import { gitMv } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -16,7 +16,7 @@ export function runStatus(argv, config, opts = {}) {
   if (!config.validStatuses.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...config.validStatuses].join(', ')}`); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);
@@ -92,7 +92,7 @@ export function runArchive(argv, config, opts = {}) {
   if (!input) { die('Usage: dotmd archive <file>'); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
   if (filePath.includes(`/${config.archiveDir}/`)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); return; }
 
   const raw = readFileSync(filePath, 'utf8');
@@ -173,7 +173,7 @@ export function runTouch(argv, config, opts = {}) {
   if (!input) { die('Usage: dotmd touch <file>'); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
 
   const today = new Date().toISOString().slice(0, 10);
 
@@ -188,19 +188,6 @@ export function runTouch(argv, config, opts = {}) {
   config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today });
 }
 
-function resolveDocPath(input, config) {
-  if (!input) return null;
-  if (path.isAbsolute(input)) return existsSync(input) ? input : null;
-
-  let candidate = path.resolve(config.repoRoot, input);
-  if (existsSync(candidate)) return candidate;
-
-  candidate = path.resolve(config.docsRoot, input);
-  if (existsSync(candidate)) return candidate;
-
-  return null;
-}
-
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
   if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);

package/src/new.mjs

@@ -0,0 +1,54 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { toRepoPath, die } from './util.mjs';
+import { green, dim } from './color.mjs';
+
+export function runNew(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  // Parse args
+  const positional = [];
+  let status = 'active';
+  let title = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
+    if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
+    if (!argv[i].startsWith('-')) positional.push(argv[i]);
+  }
+
+  const name = positional[0];
+  if (!name) { die('Usage: dotmd new <name> [--status <s>] [--title <t>]'); return; }
+
+  // Validate status
+  if (!config.validStatuses.has(status)) {
+    die(`Invalid status: ${status}\nValid: ${[...config.validStatuses].join(', ')}`);
+    return;
+  }
+
+  // Slugify
+  const slug = name.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (!slug) { die('Name resolves to empty slug: ' + name); return; }
+
+  // Title
+  const docTitle = title ?? name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+  // Path
+  const filePath = path.join(config.docsRoot, slug + '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (existsSync(filePath)) {
+    die(`File already exists: ${repoPath}`);
+    return;
+  }
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    return;
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const content = `---\nstatus: ${status}\nupdated: ${today}\n---\n\n# ${docTitle}\n`;
+
+  writeFileSync(filePath, content, 'utf8');
+  process.stdout.write(`${green('Created')}: ${repoPath}\n`);
+}

package/src/util.mjs

@@ -1,4 +1,6 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { dim } from './color.mjs';
 
 export function escapeTable(value) {
   return String(value).replace(/\|/g, '\\|');
@@ -49,7 +51,24 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+export function warn(message) {
+  process.stderr.write(`${dim(message)}\n`);
+}
+
 export function die(message) {
   process.stderr.write(`${message}\n`);
   process.exitCode = 1;
 }
+
+export function resolveDocPath(input, config) {
+  if (!input) return null;
+  if (path.isAbsolute(input)) return existsSync(input) ? input : null;
+
+  let candidate = path.resolve(config.repoRoot, input);
+  if (existsSync(candidate)) return candidate;
+
+  candidate = path.resolve(config.docsRoot, input);
+  if (existsSync(candidate)) return candidate;
+
+  return null;
+}

package/src/watch.mjs

@@ -0,0 +1,48 @@
+import { watch } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { dim } from './color.mjs';
+
+export function runWatch(argv, config) {
+  const subCommand = argv.length > 0 ? argv : ['list'];
+  const cliPath = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'bin', 'dotmd.mjs');
+
+  let lastRun = 0;
+  const DEBOUNCE = 300;
+
+  function run() {
+    const now = Date.now();
+    if (now - lastRun < DEBOUNCE) return;
+    lastRun = now;
+
+    // Clear terminal
+    process.stdout.write('\x1b[2J\x1b[H');
+    process.stderr.write(dim(`[${new Date().toLocaleTimeString()}] dotmd ${subCommand.join(' ')}`) + '\n\n');
+
+    spawnSync(process.execPath, [cliPath, ...subCommand], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+  }
+
+  // Run once immediately
+  run();
+
+  process.stderr.write(dim(`\nWatching ${config.docsRoot} for changes... (Ctrl+C to stop)`) + '\n');
+
+  // Watch for changes
+  const watcher = watch(config.docsRoot, { recursive: true }, (eventType, filename) => {
+    if (filename && filename.endsWith('.md')) {
+      run();
+    }
+  });
+
+  // Clean exit
+  process.on('SIGINT', () => {
+    watcher.close();
+    process.exit(0);
+  });
+
+  // Keep alive
+  setInterval(() => {}, 1 << 30);
+}