NOTES.md

What is a NOTES.md?

A NOTES.md is a plain Markdown file that lives in the directory it describes. That's the whole idea. It holds developer-facing context that doesn't belong in user documentation: gotchas, architectural decisions, deployment quirks, half-finished thoughts, reminders for future-you.

The key property is locality. The file sits next to the code, so it's there when you need it — visible in diffs, version-controlled, searchable, and zero infrastructure required.

my-project/├── src/├── docker-compose.yml└── NOTES.md        ← "port 5432 is hardcoded in legacy.py, fix before prod"

Think of it as the sticky note on the manila folder — except it travels with the folder, survives a git clone, and shows up in grep.

The convention

This page follows the informal standard described at github.com/goude/NOTES.md . That repository is the canonical reference: a single-page spec, a worked example, and its own NOTES.md in the same repo.

The spec is deliberately minimal. A NOTES.md is not a wiki, not a changelog, not a runbook. It is whatever helps the next person — or the next version of you — understand the thing they're looking at right now.

This directory's NOTES.md

What follows is the actual NOTES.md for this part of the site, rendered in place.

todo:- move the ai slop into its own subdir `aislop/`