From 77ef4cf2d7eb7e5924ed5d16f9442d14f539c861 Mon Sep 17 00:00:00 2001 From: Danilo Alonso Date: Sun, 25 Oct 2026 21:32:22 -0400 Subject: [PATCH 1/2] feat(init): state sql/ and changes/ roles in db/AGENTS.md --- .changeset/agents-sql-changes-hint.md | 6 ++++++ docs/cli/init.md | 2 +- src/core/project-init.ts | 2 ++ tests/core/project-init.test.ts | 1 + 4 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 .changeset/agents-sql-changes-hint.md diff --git a/.changeset/agents-sql-changes-hint.md b/.changeset/agents-sql-changes-hint.md new file mode 100644 index 00000000..0aaf9d27 --- /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. diff --git a/docs/cli/init.md b/docs/cli/init.md index 361a1b56..01d61aa4 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 current state and `changes/` brings existing databases up to 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/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(''); From ed05b3be659f4cbdbb87a64591654f5ae620af44 Mon Sep 17 00:00:00 2001 From: Danilo Alonso Date: Sun, 25 Oct 2026 21:37:41 -0400 Subject: [PATCH 2/2] docs: split AGENTS.md sentence, prod examples use change ff --- .changeset/agents-sql-changes-hint.md | 2 +- docs/cli/init.md | 2 +- docs/getting-started/concepts.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.changeset/agents-sql-changes-hint.md b/.changeset/agents-sql-changes-hint.md index 0aaf9d27..1de86c2a 100644 --- a/.changeset/agents-sql-changes-hint.md +++ b/.changeset/agents-sql-changes-hint.md @@ -3,4 +3,4 @@ '@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. +`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 01d61aa4..d632f2ca 100644 --- a/docs/cli/init.md +++ b/docs/cli/init.md @@ -39,7 +39,7 @@ noorm init --yes └── sql/ ``` -`db/AGENTS.md` also states that `sql/` is the current state and `changes/` brings existing databases up to 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. +`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 ` | | 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