damusix · Oct 23, 2026 · Oct 21, 2026 · Oct 8, 2026 · Oct 19, 2026 · Oct 20, 2026
diff --git a/.changeset/change-multi-statement.md b/.changeset/change-multi-statement.md
@@ -0,0 +1,6 @@
+---
+'@noormdev/cli': patch
+'@noormdev/sdk': patch
+---
+
+A change file with more than one statement now runs every statement on SQLite, and `GO` batch separators in change files are honored on SQL Server, as they already were for `sql/` files. Before, SQLite ran only the first statement of a change file and reported success.
diff --git a/.changeset/change-parse-failures.md b/.changeset/change-parse-failures.md
@@ -0,0 +1,6 @@
+---
+'@noormdev/cli': patch
+'@noormdev/sdk': patch
+---
+
+`noorm change ff` and `change next` now fail at the position of a change folder that cannot be parsed when they would run it (never run, `reverted`, or `stale`), for example a `.txt` manifest that names a file no longer in `sql/`. Before, the folder was skipped, later changes ran without it, and the command exited 0. `change list` shows such a change as `failed` with the parse error, the TUI change screens and home count include it, `changes.pending()` returns it, and `change run <name>` reports the parse error instead of "Change not found". An applied change keeps its status, and the batch adds a warning instead of failing. A folder with neither `change/` nor `revert/` is not a change and is ignored.
diff --git a/.changeset/init-db-layout-agent-files.md b/.changeset/init-db-layout-agent-files.md
@@ -0,0 +1,8 @@
+---
+'@noormdev/cli': minor
+'@noormdev/sdk': minor
+---
+
+`noorm init` now creates `db/sql/` and `db/changes/` instead of `sql/` and `changes/`, and writes `db/AGENTS.md` and `db/CLAUDE.md`. `AGENTS.md` points coding agents at the `/noorm` skill and points data modeling at ignatius and its `/ignatius-modeling` skill. It also leaves a marker for your own steering. `CLAUDE.md` imports `AGENTS.md`. Neither file is overwritten on re-init. Overwriting a settings file (`noorm init --force`, `noorm settings init --force`) keeps the `paths` already in it. The `noorm` skill now states what `sql/` and `changes/` are for, which edits belong in each, how to reference `sql/` files from a change with a `.txt` manifest, and when to use a `.sql.tmpl`.
+
+The built-in default for `paths.sql` and `paths.changes` is now `./db/sql` and `./db/changes`, matching what `noorm init` creates. `noorm init` writes `paths` into `settings.yml`, so an initialized project keeps its layout. A project laid out at `./sql` and `./changes` whose `settings.yml` is missing, empty, or has no `paths` key now resolves to `./db/sql` and `./db/changes`. Add `paths: { sql: ./sql, changes: ./changes }` to `settings.yml`, or set `NOORM_PATHS_SQL` and `NOORM_PATHS_CHANGES`.
diff --git a/.changeset/prefetch-run-gate.md b/.changeset/prefetch-run-gate.md
diff --git a/.changeset/update-skill-prompt.md b/.changeset/update-skill-prompt.md
@@ -0,0 +1,8 @@
+---
+'@noormdev/cli': minor
+'@noormdev/sdk': minor
+---
+
+After a successful update, `noorm update` offers the noorm agent skill. It runs `npx skills add noormdev/noorm/skills` when `npx` is on `PATH`, else `gh skill install noormdev/noorm skills/noorm` (GitHub CLI 2.90 or newer). With neither, or when the command fails, it prints both commands and where to get Node.js and the GitHub CLI. On a terminal it asks first; piped output prints the command instead, and `--json` skips the offer. A declined or failed skill install does not change the exit code.
+
+On a terminal, `noorm update` now rewrites its status line in place: `Checking for updates...` is replaced by the result, and the download counter ends on `Downloaded X MB (100%)`. `noorm update --json` now writes only the JSON document to stdout; before, status lines preceded it.
diff --git a/.claude/rules/documentation.md b/.claude/rules/documentation.md
@@ -19,15 +19,13 @@ Every claim has to be one you can point at.
 
 Do not invent a position to argue against. No "some people say", no "you may have been told", no opponent who does not hold the view. State the finding and let it stand without a foil.
 
-`docs/guide/changes/overview.md:15` currently breaks this ("Some argue that you *are* moving data..."). Fix it when you next touch that file, and do not copy the shape.
-
 Measurements carry their conditions: the tool, the scale, the run. Never combine numbers from different runs or builds into one comparison. If the conditions differ, re-measure or say which figure came from where.
 
 Mark inference as inference. An extrapolation from a mechanism reads as a measured result unless the text says otherwise.
 
 
 ## Structure
 
-Lead with the problem the reader wants to solve, then the mechanism. Code follows the explanation that motivates it.
+Lead with the problem the reader wants to solve, in one sentence. The example comes next, the file or command with its real output, and the explanation follows it. A reader should see the thing working before the first `##` heading.
 
 Prefer a table, tree, or diagram wherever the content has a shape. Reserve prose for reasoning and motivation, which is the one thing a table cannot carry.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -125,18 +125,20 @@ For setup wizards where the target database may not exist yet, use `testConnecti
 | Path | Covers | Voice |
 |------|--------|-------|
 | `README.md` | project overview, install, quick start | atomic-writing |
-| `docs/index.md` | docs landing, why noorm, quick start | atomic-writing |
+| `docs/index.md` | landing: problems noorm and ignatius remove, how it works, FAQ | atomic-writing |
+| `docs/download.md` | install noorm and ignatius, agent skills, SDK, install options | atomic-writing |
 | `docs/why-noorm.md` | rationale, prior tools, history | atomic-writing |
 | `docs/tui.md` | TUI screens, navigation, keyboard shortcuts | terse-technical |
 | `docs/headless.md` | CLI reference, global flags, command discovery | terse-technical |
-| `docs/getting-started/installation.md` | requirements, CLI install, SDK install | atomic-writing |
-| `docs/getting-started/concepts.md` | SQL files as source of truth, execution order, changes | atomic-writing |
+| `docs/getting-started/installation.md` | CLI install, SDK install, agent skill, update, download verification | atomic-writing |
+| `docs/getting-started/concepts.md` | db/sql vs db/changes, execution order, templates, configs and roles, secrets, what lives where | atomic-writing |
 | `docs/getting-started/first-build.md` | init, first build walkthrough | atomic-writing |
-| `docs/getting-started/building-your-sdk.md` | monorepo setup, database package, SDK wiring | atomic-writing |
+| `docs/getting-started/building-your-sdk.md` | database package layout, schema types, domain classes, client, tests | atomic-writing |
 | `docs/guide/automation/ci.md` | test CI, prod CI shapes | atomic-writing |
 | `docs/guide/automation/mcp.md` | MCP server, AI agent integration, tools | atomic-writing |
 | `docs/guide/automation/non-interactive.md` | --yes semantics, CI bootstrap | atomic-writing |
-| `docs/guide/changes/overview.md` | changes vs migrations, directory structure | atomic-writing |
+| `docs/guide/changes/overview.md` | change folder anatomy, file types, .txt manifests, ordering | atomic-writing |
+| `docs/guide/changes/add-a-column.md` | adding a column: db/sql/ declaration, change with backfill, revert | atomic-writing |
 | `docs/guide/changes/forward-revert.md` | apply and revert lifecycle | atomic-writing |
 | `docs/guide/changes/history.md` | execution history, TUI history views | atomic-writing |
 | `docs/guide/database/create.md` | db create, configs-first workflow | atomic-writing |
@@ -189,10 +191,13 @@ For setup wizards where the target database may not exist yet, use `testConnecti
 | `docs/dev/version.md` | version layers, migration | atomic-writing |
 | `docs/dev/ink-cheatsheet.md` | Ink API cheatsheet | terse-technical |
 | `docs/dev/ink-testing-library-cheatsheet.md` | ink-testing-library cheatsheet | terse-technical |
-| `docs/modeling/index.md` | ignatius overview, IDEF1X modeling | atomic-writing |
-| `docs/modeling/installation.md` | ignatius install | atomic-writing |
+| `docs/modeling/index.md` | ignatius landing: data flows, live model, two-minute try-it, links into the section | atomic-writing |
+| `docs/modeling/why.md` | case for modeling first, why a separate tool, the two notations, the name | atomic-writing |
+| `docs/parts/` | fragments shared by the two landings through `<!--@include: -->`; not pages | atomic-writing |
+| `docs/modeling/installation.md` | ignatius commands: install, serve, validate, export, index, approve, update | atomic-writing |
 | `docs/modeling/entities.md` | entity format, key inheritance | atomic-writing |
 | `docs/modeling/data-flows.md` | SSADM data flow diagrams | atomic-writing |
+| `docs/modeling/model-to-sql.md` | entity file fields mapped to DDL, constraint naming | atomic-writing |
 | `docs/modeling/best-practices.md` | modeling best practices | atomic-writing |
 | `docs/modeling/branding.md` | model branding | atomic-writing |
 | `docs/modeling/modeling-skill.md` | /ignatius-modeling skill | atomic-writing |

diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ The install script is [fully transparent and open source](https://github.com/noo
 ## Quick start
 
 ```bash
-# Bootstrap a project — creates your identity and the sql/ and changes/ layout
+# Bootstrap a project — creates your identity and the db/sql/ and db/changes/ layout
 noorm init
 
 # Add a database config

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -1,5 +1,6 @@
 import { defineConfig } from 'vitepress';
 import { withMermaid } from 'vitepress-plugin-mermaid';
+import { mermaid } from './mermaid';
 
 // https://vitepress.dev/reference/site-config
 const SITE_URL = 'https://noorm.dev';
@@ -11,6 +12,7 @@ export default withMermaid(
         title: 'noorm',
         description: DESCRIPTION,
         base: process.env.VITEPRESS_BASE || '/',
+        mermaid,
 
         // `docs/wiki/` is generated repo-analysis output for tooling and
         // contributors, not published documentation. VitePress compiles every
@@ -24,8 +26,9 @@ export default withMermaid(
         // `models/**` joins the list for the same reason as `tapes/**`: it is
         // source for a generated artifact, not pages. Left in, VitePress
         // compiles every entity file into a route like
-        // /models/todo-list/data/core/users.html.
-        srcExclude: ['wiki/**', 'spec/**', 'design/**', 'superpowers/**', 'tmp/**', 'tapes/**', 'models/**'],
+        // /models/todo-list/data/core/users.html. `parts/**` holds fragments
+        // that pages pull in with `<!--@include: -->`; they are not pages either.
+        srcExclude: ['wiki/**', 'spec/**', 'design/**', 'superpowers/**', 'tmp/**', 'tapes/**', 'models/**', 'parts/**'],
 
         markdown: {
             // The terminal recordings are the heaviest assets on the site
@@ -41,7 +44,7 @@ export default withMermaid(
         // The `title`/`description` config fields cover <title> and <meta name>;
         // everything social has to be spelled out here.
         head: [
-            ['link', { rel: 'icon', href: '/image/logo.svg', type: 'image/svg+xml' }],
+            ['link', { rel: 'icon', href: '/image/favicon.svg', type: 'image/svg+xml' }],
             ['link', { rel: 'apple-touch-icon', href: '/image/logo.png' }],
             ['link', { rel: 'canonical', href: `${SITE_URL}/` }],
             ['meta', { name: 'theme-color', content: '#E05742' }],
@@ -83,17 +86,15 @@ gtag('config', 'G-Y69K95866J');`],
         },
         themeConfig: {
             // https://vitepress.dev/reference/default-theme-config
-            logo: '/image/logo.svg',
+            logo: { light: '/image/logo.svg', dark: '/image/logo-dark.svg' },
             siteTitle: 'noorm',
-            // No Home entry: the logo already links to `/`. Dev docs are not a
-            // top-bar concern either — they live in the Reference group of the
-            // main sidebar as "Contributor Documentation".
+            // No Home entry: the logo already links to `/`. Contributor docs are
+            // not a reader's concern, so they sit in the footer, not the nav.
             nav: [
-                { text: 'Getting Started', link: '/getting-started/installation' },
-                { text: 'Guide', link: '/guide/sql-files/organization' },
-                { text: 'CLI', link: '/headless' },
-                { text: 'TUI', link: '/tui' },
+                { text: 'Docs', link: '/getting-started/installation' },
                 { text: 'Modeling', link: '/modeling/' },
+                { text: 'Reference', link: '/headless' },
+                { text: 'Download', link: '/download' },
             ],
 
             sidebar: {
@@ -149,7 +150,6 @@ gtag('config', 'G-Y69K95866J');`],
                     {
                         text: 'Getting Started',
                         items: [
-                            { text: 'Why noorm', link: '/why-noorm' },
                             { text: 'Installation', link: '/getting-started/installation' },
                             { text: 'First Build', link: '/getting-started/first-build' },
                             { text: 'Building Your SDK', link: '/getting-started/building-your-sdk' },
@@ -160,15 +160,6 @@ gtag('config', 'G-Y69K95866J');`],
                     // is what pins them open with no toggle. Every other group
                     // is collapsible and starts closed, so the sidebar opens as
                     // a short list of topics rather than a wall of links.
-                    {
-                        text: 'Features',
-                        collapsed: true,
-                        items: [
-                            { text: 'CLI Reference', link: '/headless' },
-                            { text: 'Terminal UI', link: '/tui' },
-                            { text: 'Relational Design', link: '/guide/relational-design' },
-                        ],
-                    },
                     {
                         // ignatius is a separate binary with its own release
                         // cadence, so these pages carry the narrative and link
@@ -178,13 +169,15 @@ gtag('config', 'G-Y69K95866J');`],
                         collapsed: true,
                         items: [
                             { text: 'Overview', link: '/modeling/' },
-                            { text: 'Installation', link: '/modeling/installation' },
+                            { text: 'Commands', link: '/modeling/installation' },
                             { text: 'Entities & Key Inheritance', link: '/modeling/entities' },
                             { text: 'Data Flows', link: '/modeling/data-flows' },
+                            { text: 'From Model to SQL', link: '/modeling/model-to-sql' },
                             { text: 'Modeling Skill', link: '/modeling/modeling-skill' },
                             { text: 'Reverse-Engineering', link: '/modeling/reverse-engineering' },
                             { text: 'Branding', link: '/modeling/branding' },
                             { text: 'Best Practices', link: '/modeling/best-practices' },
+                            { text: 'Why ignatius', link: '/modeling/why' },
                         ],
                     },
                     {
@@ -215,6 +208,7 @@ gtag('config', 'G-Y69K95866J');`],
                         collapsed: true,
                         items: [
                             { text: 'Overview', link: '/guide/changes/overview' },
+                            { text: 'Add a Column', link: '/guide/changes/add-a-column' },
                             { text: 'Forward & Revert', link: '/guide/changes/forward-revert' },
                             { text: 'History', link: '/guide/changes/history' },
                         ],
@@ -241,8 +235,17 @@ gtag('config', 'G-Y69K95866J');`],
                     {
                         text: 'Reference',
                         items: [
+                            { text: 'CLI', link: '/headless' },
                             { text: 'SDK', link: '/reference/sdk' },
-                            { text: 'Contributor Documentation', link: '/dev/' },
+                            { text: 'Terminal UI', link: '/tui' },
+                        ],
+                    },
+                    {
+                        text: 'Background',
+                        collapsed: true,
+                        items: [
+                            { text: 'Why noorm', link: '/why-noorm' },
+                            { text: 'Relational Design', link: '/guide/relational-design' },
                         ],
                     },
                 ],
@@ -268,15 +271,16 @@ gtag('config', 'G-Y69K95866J');`],
                 },
             },
 
+            // Depth 4 because the CLI reference puts each command at ####.
             outline: {
-                level: [2, 3],
+                level: [2, 4],
             },
 
             footer: {
                 message: 'Database Schema & Change Manager',
                 // Apache-2.0 to match LICENSE and every package.json in the repo. This
                 // read "ISC" until 2026-08 and matched nothing that ships.
-                copyright: `© ${new Date().getFullYear()} <a href="https://github.com/noormdev">noorm</a> · <a href="https://github.com/noormdev/noorm">GitHub</a> · <a href="https://www.npmjs.com/org/noormdev">npm</a> · <a href="https://github.com/noormdev/noorm/blob/master/LICENSE">Apache 2.0</a>`,
+                copyright: `© ${new Date().getFullYear()} <a href="https://github.com/noormdev">noorm</a> · <a href="https://github.com/noormdev/noorm">GitHub</a> · <a href="https://www.npmjs.com/org/noormdev">npm</a> · <a href="https://github.com/noormdev/noorm/blob/master/LICENSE">Apache 2.0</a> · <a href="/dev/">Contributor docs</a>`,
             },
         },
     }),