diff --git a/.changeset/agents-sql-changes-hint.md b/.changeset/agents-sql-changes-hint.md
new file mode 100644
index 00000000..1de86c2a
--- /dev/null
+++ b/.changeset/agents-sql-changes-hint.md
@@ -0,0 +1,6 @@
+---
+'@noormdev/cli': patch
+'@noormdev/sdk': patch
+---
+
+`db/AGENTS.md` written by `noorm init` now states that `sql/` is the current state of the schema and `changes/` brings existing databases, production included, up to that state. An existing `db/AGENTS.md` is left as is.
diff --git a/docs/cli/init.md b/docs/cli/init.md
index 361a1b56..d632f2ca 100644
--- a/docs/cli/init.md
+++ b/docs/cli/init.md
@@ -39,7 +39,7 @@ noorm init --yes
     └── sql/
 ```
 
-`db/AGENTS.md` also points data modeling at [ignatius](/modeling/) and its [`/ignatius-modeling` skill](/modeling/modeling-skill), and holds a marker comment for your own steering. `db/CLAUDE.md` is one line, `@AGENTS.md`. Without `--yes`, `init` prompts for a name and email when no identity exists yet.
+`db/AGENTS.md` also states that `sql/` is the schema's current state and `changes/` brings existing databases up to it. It points data modeling at [ignatius](/modeling/) and its [`/ignatius-modeling` skill](/modeling/modeling-skill), and holds a marker comment for your own steering. `db/CLAUDE.md` is one line, `@AGENTS.md`. Without `--yes`, `init` prompts for a name and email when no identity exists yet.
 
 
 ## Flags
diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md
index ce687ebb..f6049c45 100644
--- a/docs/getting-started/concepts.md
+++ b/docs/getting-started/concepts.md
@@ -102,7 +102,7 @@ A **config** is a saved connection: `dev`, `staging`, `prod`. Commands use the a
 
 ```bash
 noorm config use staging
-noorm run build --config prod
+noorm change ff --config prod
 ```
 
 A **stage** in `.noorm/settings.yml` applies to the config with the same name. Its `defaults` seed that config when the TUI first creates it, `protected: true` caps its access, and `secrets` lists what it needs:
@@ -171,7 +171,7 @@ State is encrypted with your own key, so a copy is useless on another machine. E
 | Edit a table in `db/sql/` with no change | new databases get the edit, existing ones never do | add a change: `noorm change add <slug>` |
 | A change that is not safe to run twice | a database built from `db/sql/` has no change records, so `change ff` runs the change against a table that already has it | guard it: `ADD COLUMN IF NOT EXISTS`, `WHERE status IS NULL` |
 | Folders without number prefixes | alphabetical order runs `functions/` before `tables/` | `01_tables/`, `02_views/` |
-| `noorm -c prod run build` fails: `--cwd path is not a directory` | before the subcommand, `-c` is `--cwd`, so noorm looks for a project folder named `prod` | `noorm run build --config prod` |
+| `noorm -c prod change ff` fails: `--cwd path is not a directory` | before the subcommand, `-c` is `--cwd`, so noorm looks for a project folder named `prod` | `noorm change ff --config prod` |
 
 
 ## Next
diff --git a/src/core/project-init.ts b/src/core/project-init.ts
index d64245bf..fdce32ae 100644
--- a/src/core/project-init.ts
+++ b/src/core/project-init.ts
@@ -52,6 +52,8 @@ const NOORM_GITIGNORE_BLOCK = `\n# noorm\n${NOORM_IGNORE_ENTRY}\n`;
 const AGENTS_TEMPLATE = [
     'Use the `/noorm` skill for managing files here.',
     '',
+    '`sql/` is the current state of the schema; `changes/` brings existing databases, production included, up to that state.',
+    '',
     'For data modeling, use ignatius (https://noorm.dev/modeling/) and its `/ignatius-modeling` skill '
         + '(https://noorm.dev/modeling/modeling-skill).',
     '',
diff --git a/tests/core/project-init.test.ts b/tests/core/project-init.test.ts
index bb537972..1776caa4 100644
--- a/tests/core/project-init.test.ts
+++ b/tests/core/project-init.test.ts
@@ -238,6 +238,7 @@ describe('core: scaffoldDbLayout', () => {
         const claude = readFileSync(join(tmpDir, 'db', 'CLAUDE.md'), 'utf-8');
 
         expect(agents).toContain('Use the `/noorm` skill for managing files here.');
+        expect(agents).toContain('`sql/` is the current state of the schema; `changes/` brings existing databases');
         expect(agents).toContain('`/ignatius-modeling` skill');
         expect(agents).toContain('https://noorm.dev/modeling/');
         expect(agents).toContain('<!-- add user specific LLM steering here -->');