`change add` scaffolds only changelog.md; the SQL file layout is undocumented

[damusix]

Problem

noorm change add <name> creates the changeset directory and a changelog.md, but not the SQL files. The layout it expects —

db/changes/<name>/change/001_<name>.sql
db/changes/<name>/revert/001_<name>.sql

— appears in none of the CLI reference, the skill guide, or the templates reference. change add --help does not describe it either.

Two people hit this independently on the same project and both had to reverse-engineer it: once from the SDK reference's addFile(change, 'change', {...}) signature plus trial and error, once by inspecting a directory after the fact.

The failure mode is quiet. change add reports success, and the changeset is only revealed as inert later, when change run has nothing to apply.

Proposal

Either scaffold the files, or document the convention — ideally both:

• Have change add create change/001_<name>.sql and revert/001_<name>.sql as empty stubs with a comment naming what belongs in each. The directory shape then teaches itself, and an empty stub that runs as a no-op is far easier to diagnose than a missing file.
• Document the layout in the CLI reference under change add, alongside the numbering convention (NNN_ prefix) and how multiple files within one changeset are ordered.

Why now

The changeset loop is the main reason to adopt noorm over a hand-rolled deploy script. It is the first thing an evaluator tries, and it currently requires reading the SDK reference to get past step one.

Out of scope

• Changing the directory convention itself. change/ + revert/ is fine; it just needs to be discoverable.

Environment

• noorm CLI 0.0.0, core 1.0.0-alpha.39
• OS: macOS (darwin 25.5.0), Node v24.13.0, mssql dialect