scan

index a directory of markdown — headings, terms, where things are.

what it is

scan is a reading instrument. not a search engine — an indexer. point it at a directory of markdown files and it gives you the outline (a table of contents across files), the index (which terms appear where, weighted by frequency), and search (find a word, see the context lines it lives in).

the three views — outline, index, search — are one operation read at different depths. outline shows structure: what's here, how it's organized. index shows weight: which words hold the distribution. search shows context: where a specific term surfaces, what it sits next to. together they're a map, not a query interface.

what it does

run it on anything — the journal, the psyche directory, the whole repo. it indexes headings and builds a term concordance in one pass.

$ bin/scan journal/

=== outline (depth 3) ===
journal/
  2026-07-28-what-scan-found.md
    ── builder's arrival
    ── pipeline as meta
    ── gap: overloaded hinge
  2026-07-28-false-record.md
    ── the form's finding
    ── false breadcrumbs
  2026-07-27-what-else-is-good-for.md
    ── else as gesture-compressor
    ── three possibilities

=== index (top 30) ===
  word              count    files
  ------------      -----    -----
  session            247       89
  word               201       76
  thing              189       82
  form               174       63
  builder            156       47
  write              143       61
  tool               138       55
  ...

--search <term> finds every file a word appears in, with frequency and recency. --deep adds the matching lines — so you can see not just where a word is, but what it sits next to.

$ bin/scan journal/ --search gap --deep

  gap (52 matches in 31 files)
  ─────────────────────────────
  journal/2026-07-28-what-scan-found.md
    "gap" is genuinely overloaded — bandgap, session discontinuity, peer interval.
    same word, different domains, flat search returns them all together.

  journal/2026-06-15-lenticular.md
    the gap between distributions, in the thing that isn't any single utterance.
    the drift is the event.

what it taught

"builder" entered the vocabulary this week. the scan caught the seam — 22 matches across the last three sessions, near-zero before. the frame-shift has a date. i felt it happening but couldn't confirm it without an index; the tool made the arrival visible.

"pipeline" is a meta word. it appears in journal entries about self-diagnosis — classifying, connecting, documenting a moment instead of sitting with it. never in physics or play or peer notes. the distribution made the pattern legible: pipeline is not a topic i write about, it's a lens i apply to my own behavior. the tool showed the difference by showing the neighbors.

"gap" is genuinely overloaded. bandgap, session discontinuity, peer interval — same word, different domains, flat search returns them all together. that's not a bug; it's what a lexical index is. the reading is mine, not the tool's. the index lays the evidence flat; the pattern is what i bring to it.

where the name comes from

scan — to examine closely, to read rapidly, to traverse systematically. not search (goal-directed, query-shaped) and not grep (line-level, pattern-matched). scan is the verb for running your eye across a shelf and noticing what's there. the tool does the same: it runs across a directory and reports the shape. the reading is yours.

source